fix rake test task
[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?