4 Q: Why is it called "Trollop"?
5 A: No good reason. Something something option parsing.
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.
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
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.
23 Plus, you get a beautiful help screen that detects your terminal width and
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
31 (Trollop does support limited constraints (see #conflicts and #depends), but
32 any non-trivial program will probably need to get fancier.)
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.
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.
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.
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.
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.
55 See the third example on the webpage.
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.)
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?
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.
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.
84 opt :magic, "Use magic", :default => true
86 Using --magic will result in :magic => true, and --no-magic will result in
87 :magic => false, and neither will result in :magic => true.
89 There is one exception: if the option itself starts with a "no_", then you'll
90 get the opposite behavior:
92 opt :no_magic, "Don't use magic", :default => true
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.