FAQ.txt
Optimist FAQ
-----------
Q: Why should I use Optimist?
A: Because it will take you fewer lines of code to parse commandline arguments
than anything else out there.
Like this:
opts = Optimist::options do
opt :monkey, "Use monkey mode"
opt :goat, "Use goat mode", :default => true
opt :num_limbs, "Set number of limbs", :default => 4
end
That's it. 'opts' will be a hash and you can do whatever you want with it.
You don't have to mix processing code with the declarations. You don't have
to make a class for every option (what is this, Java?). You don't have to
write more than 1 line of code per option.
Plus, you get a beautiful help screen that detects your terminal width and
wraps appropriately.
Q: What is the philosophy behind Optimist?
A: Optimist does the parsing and gives you a hash table of options. You then
write whatever fancy constraint logic you need as regular Ruby code operating
on that hash table.
(Optimist does support limited constraints (see #conflicts and #depends), but
any non-trivial program will probably need to get fancier.)
Then if you need to abort and tell the user to fix their command line at any
point, you can call #die and Optimist will do that for you in a pretty way.
Q: What happens to the other stuff on the commandline?
A: Anything Optimist doesn't recognize as an option or as an option parameter is
left in ARGV for you to process.
Q: Does Optimist support multiple-value arguments?
A: Yes. If you set the :type of an option to something plural, like ":ints",
":strings", ":doubles", ":floats", ":ios", it will accept multiple arguments
on the commandline, and the value will be an array of the parameters.
Q: Does Optimist support arguments that can be given multiple times?
A: Yes. If you set :multi to true, then the argument can appear multiple times
on the commandline, and the value will be an array of the parameters.
Q: Does Optimist support subcommands?
A: Yes: you can direct Optimist to stop processing when it encounters certain
tokens. Then you can re-call Optimist with the subcommand-specific
configuration to process the rest of the commandline.
See the third example on the webpage.
(And if you don't know the subcommands ahead of time, you can call
#stop_on_unknown, which will cause Optimist to stop when it encounters any
unknown token. This might be more trouble than its worth if you're also
passing filenames on the commandline.)
Q: Why does Optimist disallow numeric short argument names, like '-1' and '-9'?
A: Because it's ambiguous whether these are arguments or negative integer or
floating-point parameters to arguments. E.g., is "-f -3" a negative floating
point parameter to -f, or two separate arguments?
Q: What was the big change in version 2.0?
A: The big change was boolean parameter (aka flag) handling. In pre-2.0,
not specifying a flag on the commandline would result in the option being set
to its default value; specifying it on the commandline would result in the
option being set to the opposite of its default value. This was weird for
options with a default of true:
opt :magic, "Use magic", default: true
Using --magic with the above configuration would result in a :magic => false
value in the options hash.
In 2.0, we introduce the GNU-style notion of a --no-x parameter. Now,
specifying --x will always set the option :x to true, regardless of its
default value, and specifying --no-x will always set the option :x to false,
regardless of its default value. The default value only comes into play when
neither form is given on the commandline.
E.g.:
opt :magic, "Use magic", :default => true
Using --magic will result in :magic => true, and --no-magic will result in
:magic => false, and neither will result in :magic => true.
There is one exception: if the option itself starts with a "no_", then you'll
get the opposite behavior:
opt :no_magic, "Don't use magic", :default => true
Using --magic will result in :no_magic => false, and --no-magic will result in
:no_magic => true, and neither will result in :no_magic => true.