Ruby Sub-command Executable With Commander Gem

Commander is a Ruby Gem aimed towards simplifying the sub-command/master-command structure of many executables. This light-weight gem allows you to create minimalist, clean, concise sub-command programs using the syntax below.

Installation

$ sudo gem sources -a http://gems.github.com
$ sudo gem install visionmedia-commander

Features

  • Sub-commands
  • Auto-generated help documentation globally and per sub-command
  • Simple syntax and implementation
  • Extensible help generators for various output formats
  • Use the 'commander' command to initialize a commander driven program
  • Interaction library to 'ask' for input, 'confirm', 'ask for lists', and more.
  • Imports the highline gem for interacting with the terminal
  • Auto-populates struct with options ( no more { |v| options[:recursive] = v } )
  • Terminal progress bar

Example Syntax

Below is the absolute minimum for commander to run. Read the README or watch the screencast to learn more.

   require 'rubygems'
   require 'commander'

   program :name, 'Foo Bar'
   program :version, '1.0.0'
   program :description, 'Stupid command that prints foo or bar.'

   command :foo do |c|
     c.syntax = "foobar foo"
     c.description = "Display foo"
     c.when_called do |args, options|
       say 'foo'
     end
   end

   command :bar do |c|
     c.syntax = "foobar [options] bar"
     c.description = "Display bar with optional prefix"
     c.option "--prefix STRING"
     c.when_called do |args, options|
       say "#{options.prefix} bar"
     end
   end

Watch The Screencasts

First ruby commander executable

Bookmark/Search this post with:

Comments

Jan 24 2010 - 5:50pm - admin

Not explicitly through the commander DSL, but you can do stuff like this:

...
c.action do |args, options|
  path = args.shift or raise('path is required.')
end

Jan 22 2010 - 8:54pm - fan of commander

first off, commander is awesome.

is there a way to make an argument or option required?

Dec 9 2009 - 5:21pm - admin

You can use default_command :foo to assign a default command when no subcommand is specified

Dec 8 2009 - 12:04am - Anonymous

Can Commander process a command-line options without sub-commands ?

Example:
At the command-line I would like to type
=> foobar --echo Hello

I tried something like:

command nil do |c|
  c.syntax = 'foobar [options]'
  c.description = 'Echoes stuff'
  c.option '--echo STRING', String, 'Echoes the typed string'
  c.action do |args, options|
    if options.echo
      say "#{options.say}"
    end
  end
end

It works except that I am not able to access the help of that nil command.

Is there a way to get it ?

Regards

Aug 12 2009 - 11:55pm - admin

Most of it should work fine on windows. If not patches are certainly welcome, although I have no intention of supporting windows myself.

Aug 12 2009 - 2:34pm - Anonymous

Will this gem ever be available for windows?