RubyCLI¶ ↑

Author: Martin Velez
Copyright: Copyright © 2011 Martin Velez
License: Distributed under the same terms as Ruby

Description ¶ ↑

“RubyCLI” is a Ruby library which factors out the code needed to create Ruby programs with a command line interface (CLI) and that follow the Unix Philosophy design method outlined in www.faqs.org/docs/artu/ch01s06.html.

Currently, RubyCLI is short and simple. It uses Ruby’s core optparse library.

Design¶ ↑

What does a command line application library need to do?

Provide a user interface (UI)
- Process options (use Ruby’s Option Parser)
- Process arguments
Pass options and arguments as parameters to other functions defined in libraries or other executables.

What does a command line application library need not do?

Validate options or arguments.
- Libraries or other executables should do this.

This is the core algorithm of any Ruby CLI application

def run
  if parse_options? && arguments_Valid?
    process_options
    process_arguments
    output_options_and_arguments# def run
    command
  else
    output_help(1)
  end
end

Installation¶ ↑

Rubygems:¶ ↑

gem install ruby_cli

Not Rubygems:¶ ↑

Download ruby_cli
Unzip.
Only the lib folder contents are needed
Use the RubyCLI module as a mixin for your CLI application

Alternative Tools¶ ↑

There are other tools out there which can be used to write command line applications.

clamp - I don’t like to learn new DSLs
optparse - This library uses this to parse options.
Thor - It does not try to follow the Unix Philosophy.
Clip - OptionParser already exists.

Usage¶ ↑

New File
Require the ruby_cli gem.
Create a Ruby class.
Call it “App”, for example.
Include the RubyCLI module.
Define the command method.
- This is where your program does the actual work.
- At this point you have options and arguments available.
- Pass them as parameters to library functions or as options/arguments to other executables.
- Be smart! Have libraries and other executables do the heavy work.
- Be smart! Fewer lines of code (LOC) here is an indication that your code will be easy to maintain.
Define command options and defaults (optional)
- This is where you define a hash for your options and set the default values.
- Remember, options by definition are optional.
Define command arguments and defaults (optional)

Usage Example 1¶ ↑

This example demonstrates how to use RubyCLI to create a command line application.

#!/usr/bin/ruby

require 'ruby_cli'

class App
  include RubyCLI  

  def command
    puts "hello world"
  end

end

app = App.new(ARGV) 
app.run

Usage Example 2¶ ↑

This example demonstrates how command specific options can be defined easily using RubyCLI. It is taken from the ruby_ngrams gem executable, which I also authored.

#!/usr/bin/env ruby

require 'ruby_cli'
require 'ruby_ngrams'

class App
  include RubyCLI  

  def initialize_command_options() @options = {:regex => //, :n => 2}  end

  def define_command_option_parsing
    @opt_parser.on('-n', '--n NUM', Integer, 'set length n for n-grams') do |n|
      @options[:n] = n
    end
    @opt_parser.on('-r', '--regex "REGEX"', Regexp, 'set regex to split string into tokens') do |r|
      @options[:regex] = r
    end
  end

  def command
    text = ARGF.read
    text.ngrams(@options).each { |ngram| puts ngram.inspect }
  end
end

app = App.new(ARGV, __FILE__)
app.run

Dependencies¶ ↑

Ruby 1.8.7 or greater
None other

Alternative Tools¶ ↑

There are other tools out there which can be used to write command line applications.

clamp - I don’t like to learn new DSLs
optparse - This library uses this to parse options.
Thor - It does not try to follow the Unix Philosophy.
Clip - OptionParser already exists.

Acknowledgements¶ ↑

Todd Werth

I used his Ruby command line application skeleton code. I borrowed some ideas from there.

TODO¶ ↑

Add tests

Development¶ ↑

Source Repository¶ ↑

ruby_cli is hosted on Github at:

https://github.com/martinvelez/ruby_cli

Issues and Bug Reports¶ ↑

Provide feedback, get help, request features, and reports bugs here:

https://github.com/martinvelez/ruby_cli/issues