more documentation fixups
[trollop:mainline.git] / FAQ.txt
1 Trollop FAQ
2 -----------
3
4 Q: Why is it called "Trollop"?
5 A: No good reason. Something something option parsing.
6
7 Q: Why should I use Trollop?
8 A: Because it will take you fewer lines of code to parse commandline arguments
9    than anything else out there.
10
11    Like this:
12      opts = Trollop::options do
13        opt :monkey, "Use monkey mode"
14        opt :goat, "Use goat mode", :default => true
15        opt :num_limbs, "Set number of limbs", :default => 4
16      end
17
18    That's it. 'opts' will be a hash and you can do whatever you want with it.
19    You don't have to mix processing code with the declarations. You don't have
20    to make a class for every option (what is this, Java?). You don't have to
21    write more than 1 line of code per option.
22
23    Plus, you get a beautiful help screen that detects your terminal width and
24    wraps appropriately.
25
26 Q: What is the philosophy behind Trollop?
27 A: Trollop does the parsing and gives you a hash table of options. You then
28    write whatever fancy constraint logic you need as regular Ruby code operating
29    on that hash table.
30
31    (Trollop does support limited constraints (see #conflicts and #depends), but
32    any non-trivial program will probably need to get fancier.)
33
34    Then if you need to abort and tell the user to fix their command line at any
35    point, you can call #die and Trollop will do that for you in a pretty way.
36
37 Q: What happens to the other stuff on the commandline?
38 A: Anything Trollop doesn't recognize as an option or as an option parameter is
39    left in ARGV for you to process.
40
41 Q: Does Trollop support multiple-value arguments?
42 A: Yes. If you set the :type of an option to something plural, like ":ints",
43    ":strings", ":doubles", ":floats", ":ios", it will accept multiple arguments
44    on the commandline, and the value will be an array of the parameters.
45
46 Q: Does Trollop support arguments that can be given multiple times?
47 A: Yes. If you set :multi to true, then the argument can appear multiple times
48    on the commandline, and the value will be an array of the parameters.
49
50 Q: Does Trollop support subcommands?
51 A: Yes: you can direct Trollop to stop processing when it encounters certain
52    tokens. Then you can re-call Trollop with the subcommand-specific
53    configuration to process the rest of the commandline.
54
55    See the third example on the webpage.
56
57    (And if you don't know the subcommands ahead of time, you can call
58    #stop_on_unknown, which will cause Trollop to stop when it encounters any
59    unknown token. This might be more trouble than its worth if you're also
60    passing filenames on the commandline.)
61
62 Q: Why does Trollop disallow numeric short argument names, like '-1' and '-9'?
63 A: Because it's ambiguous whether these are arguments or negative integer or
64    floating-point parameters to arguments. E.g., is "-f -3" a negative floating
65    point parameter to -f, or two separate arguments?
66
67 Q: What was the big change in version 2.0?
68 A: The big change was boolean parameter (aka flag) handling. In pre-2.0,
69    not specifying a flag on the commandline would result in the option being set
70    to its default value; specifying it on the commandline would result in the
71    option being set to the opposite of its default value. This was weird for
72    options with a default of true:
73      opt :magic, "Use magic", default: true
74    Using --magic with the above configuration would result in a :magic => false
75    value in the options hash.
76
77    In 2.0, we introduce the GNU-style notion of a --no-x parameter. Now,
78    specifying --x will always set the option :x to true, regardless of its
79    default value, and specifying --no-x will always set the option :x to false,
80    regardless of its default value. The default value only comes into play when
81    neither form is given on the commandline.
82
83    E.g.:
84      opt :magic, "Use magic", :default => true
85
86    Using --magic will result in :magic => true, and --no-magic will result in
87    :magic => false, and neither will result in :magic => true.
88
89    There is one exception: if the option itself starts with a "no_", then you'll
90    get the opposite behavior:
91
92      opt :no_magic, "Don't use magic", :default => true
93
94    Using --magic will result in :no_magic => false, and --no-magic will result in
95    :no_magic => true, and neither will result in :no_magic => true.