Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

155 lines (107 sloc) 4.636 kb


Shebang is a nice wrapper around OptionParser that makes it easier to write commandline executables. I wrote it after getting fed up of having to re-invent the same wheel every time I wanted to write a commandline executable. For example, a relatively simple command using OptionParser directly may look like the following:

require 'optparse'

@options = {:force => false, :f => false, :name => nil, :n => nil}
parser   = do |opt|
  opt.banner = <<-TXT.strip
Runs an example command.

  $ foobar.rb [OPTIONS]

  opt.summary_indent = '  '

  opt.separator "\nOptions:\n"

  opt.on('-h', '--help', 'Shows this help message') do
    puts parser

  opt.on('-v', '--version', 'Shows the current version') do
    puts '0.1'

  opt.on('-f', '--force', 'Forces the command to run') do
    @options[:force] = @options[:f] = true

  opt.on('-n', '--name NAME', 'A person\'s name') do |name|
    @options[:name] = @options[:n] = name


puts "Your name is #{@options[:name]}"

Using Shebang this can be done as following:

require 'shebang'

class Greet < Shebang::Command
  command :default
  banner  'Runs an example command.'
  usage   '$ foobar.rb [OPTIONS]'

  o :h, :help   , 'Shows this help message'  , :method => :help
  o :v, :version, 'Shows the current version', :method => :version
  o :f, :force  , 'Forces the command to run'
  o :n, :name   , 'A person\'s name', :type => String

  def version
    puts '0.1'

  def index
    puts "Your name is #{option(:n)}"


As shown in the example above commands can be created by extending the class Shebang::Command and calling the class method command(). Each command required an instance method called index() to be defined, this method is called once OptionParser has been set up and the commandline arguments have been parsed:

require 'shebang'

class Greet < Shebang::Command
  command :default

  def index


Options can be retrieved using the method option() which takes either the short or long name of an option, in both cases it will result in the same value (given the option names belong to the same option):

option(:h) === option(:help) # => true

Options can be added using the class method option() or it's alias o(). Besides the features offered by OptionParser options can specify a method to execute in case that particular option has been specified. This can be done by passing the :method key to the option method:

option :f, :foobar, 'Calls a method', :method => :foobar

Now whenever the -f of --foobar option is set the method foobar() will be executed without stopping the rest of the command. This means that you'll have to manually call Kernel.exit() if you want to stop the execution process if a certain option is specified.

Shebang comes with support for defining sub commands. Sub commands are nothing more than different methods than the default one. Say you have a class Git::Submodule, to run the command itself you'd invoke the default method on this class (index by default):

cmd =


To show the status of a submodule you'd invoke git submodule status, this translates to the following code:

cmd =


Shebang takes care of this using The first commandline argument that does not start with - (and this isn't an option) is considered the command name. If there's another argument that's not a switch following that one will be used as the method name. This means that in order to invoke Git::Submodule#index you'd type the following into your terminal:

git.rb submodule

If you want to invoke a method other than the default one you'd do the following:

git.rb submodule status

In other words, the syntax of a Shebang command is the following:



Various options of Shebang can be configured by modifying the hash Shebang::Config. For example, if you want to change the format of all the headers in the help message you can do so as following:

Shebang::Config[:heading] = "\n== %s:\n"

You can also change the name of the default command:

Shebang::Config[:default_command] = :my_default_command
Jump to Line
Something went wrong with that request. Please try again.