valibuk.net

A place for opinions and notes of a valibuk.

Command Line Options Parsing in Ruby

Tagged with: — ondrej at 3:35 pm on Friday, April 2, 2010

One of the most common ways how to control a command line application is to use options, e.g. almost every command line application would understand -h or --help or /? (common in the MS-DOS world) as a request to show some instruction.

Ruby (but also other programming languages such as Java) has a basic support for accessing command line arguments, so there is a space for libraries that make reading options easier such as Trollop, Optiflag or Choice.
Update: Actually not so true for Ruby - there are two standard libraries (they are built-in, so it is not necessary to install them): OptionParser and GetoptLong. Check them out. (thnx to Max)

The Choice library is an interesting choice, not only because it works smoothly, but it is a nice example of a domain specific language (DSL or see my older post about DSL in Ruby).

I. ARGV

Firstly an example how to read command line arguments in Ruby. It is using the standard ARGV array that holds all arguments that were specified after the application name:

ARGV.each do |a|
  puts "Argument: #{a}"
end

Store it into a file, e.g. argv_example.rb.

Let’s try it with three arguments:

ruby argv_example.rb 1 abcd 3

and the output should be:

Argument: 1
Argument: abcd
Argument: 3

It works ok for position based options, that is enough for simple applications, but if we would like to support multiple options distinguished by labels (or switches, e.g. -h) that order and number may vary, it would be quite cumbersome to support it with the functionality provided by ARGV.

II. Choice

Choice is a gem, that is necessary to install:

sudo gem install choice

As already mentioned, options are defined in Choice in its own DSL that is really easy to understand way. It supports for each option short and long switches, description, default value, if it is required and a lot more.

Let’s create an application that has the title and footer options and supports common options like help and version:

require 'rubygems'
require 'choice'

Choice.options do
  header 'Application options:'

  separator 'Required:'

  option :title, :required => true do
	short '-t'
	long '--title=TITLE'
	desc 'The document title.'
  end

  separator 'Optional:'

  option :footer do
	short '-f'
	long '--footer=FOOTER'
	desc 'The document footer.'
	default 'Standard footer'
  end

  separator 'Common:'

  option :help do
	short '-h'
	long '--help'
	desc 'Show this message.'
  end

  option :version do
	short '-v'
	long '--version'
	desc 'Show version.'
	action do
	  puts 'ChoiceExample version 1.0'
	  exit
	end
  end
end

puts "Creating document with title '#{Choice.choices.title}' and footer '#{Choice.choices[:footer]}’”

and store it into a file, e.g. choice_example.rb.

All options and their values are accessible through Choice.choices.OPTION, Choice.choices[:OPTION] or Choice.choices['OPTION'] in an application.

Choice provides generating of the usage instructions for free :)

ruby choice_example.rb -h

shows

Usage: choice_example.rb [-tfhv]
Application options:
Required:
    -t, –title=TITLE                The document title.
Optional:
    -f, –footer=FOOTER              The document footer.
Common:
    -h, –help                       Show this message.
    -v, –version                    Show version.

Various ways of calling the application

ruby choice_example.rb -t "My document" -f "Page: 1/1"

or

ruby choice_example.rb -f "Page: 1/1" --title "My document"

means no complication for the application and generates the same result:

Creating document with title 'My document' and footer 'Page: 1/1'

Enjoy --smile

These icons link to social bookmarking sites where readers can share and discover new web pages.
  • del.icio.us
  • DZone
  • Digg
  • Reddit
  • Technorati
  • Furl
  • NewsVine
  • Slashdot
  • Ma.gnolia
  • StumbleUpon

4 Comments »

Comment by Max

April 3, 2010 @ 4:35 pm

Um…how do you have a post about command-line parsing without mentioning the built-in OptionParser library?

Comment by ďuri

April 20, 2010 @ 5:13 pm

Hi, thanks for sharing Ondrej. I will use choice for sure, when it comes to command line. I am happy to see your blog is active! ;)

Comment by ondrej

April 25, 2010 @ 12:14 pm

@max: phew, very simple - i did not notice it is a standard library :) actually, there are two standard libraries for the CLI parsing in ruby: OptionParser and GetoptLong.
thanks!

Comment by ondrej

April 25, 2010 @ 12:19 pm

@ďuri:
thank you.
i do not have so much time for blogging nowadays, but still trying.. ;)

RSS feed for comments on this post. TrackBack URI

Leave a comment

XHTML: You can use these tags: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Comment Preview


commercial break :)

Make an account on slicehost.com -- a really good hosting where you have your own virtual machine. I installed Gentoo there = I like it very much ;)