Controlling short options

Auto-generated short options are order dependent.

Example: short_opt1.rb:

opts = Optimist::options do
  opt :corn, "We have corn"
  opt :cheese, "Name of the cheese", :type => :string 
  opt :chickens, "Number of chickens", :default => 4 
end

For this case we have three options that all start with 'c'. Automated generation of the short-option character uses the next-available letter.

Where's my help?

$ ./short_opt1.rb -h
Error: option '-h' needs a parameter.
Try --help for help.

Uh-oh. -h is no longer able to retrieve the help message.

$ ./short_opt1.rb --help
Options:
  -c, --corn            We have corn
  -h, --cheese=<s>      Name of the cheese
  -i, --chickens=<i>    Number of chickens (default: 4)
  -e, --help            Show this message

In this case, option :corn was binded to short-option -c. Once -c was taken, then option :cheese was bound to short-option -h. This took the short-option typically reserved for the help message.

Changing the order

Example: short_opt2.rb:

opts = Optimist::options do
  opt :chickens, "Number of chickens", :default => 4 
  opt :cheese, "Name of the cheese", :type => :string 
  opt :corn, "We have corn"
end

Compared to short_opt2, this specifies the opt's in reverse order. Notice how all of the short-options for corn and chickens use different letters. However it still doesn't allow help to be displayed with -h.

$ ./short_opt2.rb --help
Options:
  -c, --chickens=<i>    Number of chickens (default: 4)
  -h, --cheese=<s>      Name of the cheese
  -o, --corn            We have corn
  -e, --help            Show this message

Forcing a short-option name

Example: short_opt3.rb:

opts = Optimist::options do
  opt :chickens, "Number of chickens", :default => 4 
  opt :cheese, "Name of the cheese", :type => :string 
  opt :corn, "We have corn"
  opt :help, "This is a custom help message", :short => :h
end

By using the :short argument, you can force help to use the short-option -h. While you're explicitly defining the :help option, you can specify a custom help message.

$ ./short_opt3.rb -h
Options:
  -c, --chickens=<i>    Number of chickens (default: 4)
  -e, --cheese=<s>      Name of the cheese
  -o, --corn            We have corn
  -h, --help            This help message

Suppressing short options

Example short_opt4.rb:

opts = Optimist::options do
  opt :chickens, "Number of chickens", :short => :none, :default => 4
  opt :cheese, "Name of the cheese", :short => :none, :type => :string 
  opt :corn, "We have corn", :short => :none
end

In many cases it is desirable to suppress creation of a short-option. This can be accomplished by adding :short => :none to opt

$ ./short_opt4.rb -h
Options:
  --chickens=<i>    Number of chickens (default: 4)
  --cheese=<s>      Name of the cheese
  --corn            We have corn
  -h, --help        Show this message

Short options are auto-merged on the command line

Like most other option parsers, a short-option is specified with a single-dash and a long-option is specified with a double-dash. Also, short-option flags can be chained together in a single string on the command-line. e.g: -a -b -c -d can be given as -abcd. This can be dangerous or may confuse users if one of the dashes is not given on the command line.

Example short_opt5.rb:

opts = Optimist::options do
  opt :corn, "We have corn"
  opt :orange, "The grain is orange"
  opt :rice, "We have rice"
  opt :nice, "The grain is nice"
end
p opts

If we set the command-line option --corn, we a single long-option flag is triggered.

./short_opt5.rb --corn
{:corn=>true, :orange=>false, :rice=>false, :nice=>false, :help=>false, :corn_given=>true}

However if we set the command line option -corn, four short-option flags are triggered

$ ./short_opt5.rb -corn
{:corn=>true, :orange=>true, :rice=>true, :nice=>true, :help=>false, :corn_given=>true, :orange_given=>true, :rice_given=>true, :nice_given=>true}

Which characters can i use for short-options?

It is possible to provide both upper and lowercase letters and other symbols as short-options. Numbers are not allowed. While it is possible to use non-letter characters (e.g. $, @, ?, *, etc.) , it is not recommended as it increases the risk that the shell may interpret them in an unexpected manner.

Example short_opt6.rb:

opts = Optimist::options do
  opt :dollars, "Amount of money we have", :default => 4, :short => '$'
  opt :questions, "Give a question", :type => String, :short => '?'
end