Subcommand¶ ↑

A tiny wrapper over ruby’s awesome OptionParser (standard) which gives easy facility of subcommands. It has a similar interface to git and prints subcommands summary as well.

Options parsers are lazy-loaded thanks to a suggestion and sample code by Robert Klemme on ruby-forum.org. If your program already uses OptionParser, then one merely needs to add a line above each option declaration – no rewriting required since all OptionParser syntax is valid syntax for ‘subcommand`.

This wrapper adds the ‘description` attr to what OptionParser already provides.

Features¶ ↑

subcommands using all of OptionParser’s features
aliases for subcommands

e.g Assuming a program “prog” with subcommands “del” and “add”

prog help
prog --help

prog help del
prog del --help

prog del --force file.a
prog --verbose del --force file.a

Examples¶ ↑

if a program has subcommands foo and baz

    ruby subcommand.rb help
    ruby subcommand.rb --help
    ruby subcommand.rb help foo
    ruby subcommand.rb foo --help
    ruby subcommand.rb baz --quiet "some text"
    ruby subcommand.rb --verbose foo --force file.zzz

STEPS ¶ ↑

1. define global_options (optional)

 global_options do |opts|
   opts.banner = "Usage: subcommand.rb [options] [subcommand [options]]"
   opts.description = "Stupid program that does something"
   opts.separator ""
   opts.separator "Global options are:"
   opts.on("-v", "--[no-]verbose", "Run verbosely") do |v|
     options[:verbose] = v
   end
 end

2. define commands using command(). Send multiple names for aliases.

 command :foo do |opts|
   opts.banner = "Usage: foo [options]"
   opts.description = "desc for foo"
   opts.on("-f", "--[no-]force", "force action") do |v|
     options[:force] = v
   end
 end

 # aliases init and create
 command :init, :create do |opts| ...

 alias_command :zoo, 'foo' , '-f'
 alias_command :bar, 'baz' , 'ruby.txt'

3. call opt_parse()

selected_command_name = opt_parse()

Custom Completion¶ ↑

 The command list_actions can be called from your application, so that the user
 can have custom completion.

  opts.on("--list-actions", "list actions for autocompletion ") do |v|
    Subcommands::list_actions
    exit 0
  end

Now we can place something like this in a configuration file. Here's what i placed
in .zshrc for bugzyrb.

  _bugzyrb() {
          reply=(`bugzyrb --list-actions`)
      }
  compctl -K _bugzyrb bugzyrb

Now, on the command line when I type "bugzyrb <TAB>" the actions are prompted in a menu.

Sample Output¶ ↑

$ ruby subcommand.rb help

Usage: subcommand.rb [options] [subcommand [options]]
Stupid program that does something

Global options are:
    -v, --[no-]verbose               Run verbosely

Commands are:
   foo : desc for foo
   baz : desc for baz

Aliases: 
   goo - foo

See 'subcommand.rb help COMMAND' for more information on a specific command.

$ ruby subcommand.rb help foo

Usage: foo [options]
desc for foo
    -f, --[no-]force                 force action

Install¶ ↑

sudo gem install subcommand

Or, copy into your lib directory and require (see source for sample usage)

Testing¶ ↑

This comes with a bunch of test cases, that I think cover all cases including printing help for aliases.

make test

You should have no errors. The test cases are in the tests folder.

RDOC¶ ↑

subcommand.rubyforge.org/doc/

Note on Patches/Pull Requests¶ ↑

Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don’t break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
Send me a pull request. Bonus points for topic branches.

umjames / subcommand