ruby_cli

= RubyCLI

Author:: {Martin Velez}[http://www.martinvelez.com] Copyright:: Copyright (c) 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 http://www.faqs.org/docs/artu/ch01s06.html.

Currently, RubyCLI is short and simple. It uses Ruby's core optparse[http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/index.html] 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 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:

1. use only files in lib folder
2. 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[http://github.com/mdub/clamp] - I don't like to learn new DSLs
2. optparse[http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/index.html] - This library uses this to parse options.
3. Thor[http://github.com/wycats/thor] - It does not try to follow the Unix Philosophy.
4. Clip[http://clip.rubyforge.org/] - 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/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[https://github.com/martinvelez/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

== Acknowledgements

{Todd Werth}[http://blog.toddwerth.com/entries/5]

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

== TODO

• ?

== Development

=== Source Repository ruby_cli is hosted on Github at: https://github.com/martinvelez/ruby_cli

=== Issues and Bug Reports Get help, request features, and reports bugs here: https://github.com/martinvelez/ruby_cli/issues