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?

1. Provide a user interface (UI)

   • Process options (use Ruby’s Option Parser)

   • Process arguments

2. 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?

1. Validate options or arguments.

   • Libraries or other executables should do this.

This is the core algorithm of any Ruby CLI application

defrunifparse_options?&&arguments_Valid?process_optionsprocess_argumentsoutput_options_and_arguments# def runcommandelseoutput_help(1)
endend

Installation

Rubygems:

geminstallruby_cli

Not Rubygems:

1. Download ruby_cli

2. Only the lib folder contents are needed

3. 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.

1. clamp - I don’t like to learn new DSLs

2. optparse - This library uses this to parse options.

3. Thor - It does not try to follow the Unix Philosophy.

4. Clip - OptionParser already exists.

Usage

1. New File

2. Require the ruby_cli gem.

3. Create a Ruby class.

4. Call it “App”, for example.

5. Include the RubyCLI module.

6. 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.

7. 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.

8. Define command arguments and defaults (optional)

Usage Example 1

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

#!/usr/bin/rubyrequire'ruby_cli'classAppincludeRubyCLIdefcommandputs"hello world"endendapp = 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 rubyrequire'ruby_cli'require'ruby_ngrams'classAppincludeRubyCLIdefinitialize_command_options() @options = {:regex=>//, :n=>2} enddefdefine_command_option_parsing@opt_parser.on('-n', '--n NUM', Integer, 'set length n for n-grams') do|n|@options[:n] = nend@opt_parser.on('-r', '--regex "REGEX"', Regexp, 'set regex to split string into tokens') do|r|@options[:regex] = rendenddefcommandtext = ARGF.readtext.ngrams(@options).each { |ngram|putsngram.inspect }
endendapp = 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.

1. clamp - I don’t like to learn new DSLs

2. optparse - This library uses this to parse options.

3. Thor - It does not try to follow the Unix Philosophy.

4. 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