make documentation aggressive
[trollop:mainline.git] / FAQ.txt
1 Trollop FAQ
2 -----------
3
4 Q: Why should I use Trollop?
5 A: Because it will take you FEWER LINES OF CODE to do reasonable option
6    parsing than any other option parser in existence.
7
8    Look:
9
10      opts = Trollop::options do
11        opt :monkey, "Use monkey mode"
12        opt :goat, "Use goat mode", :default => true
13        opt :num_limbs, "Set number of limbs", :default => 4
14      end
15
16    That's it. And opts is a hash and you do whatever you want with it.
17    Trivial. You don't have to mix option processing code blocks with the
18    declarations. You don't have to make a class for every option (what is
19    this, Java?). You don't have to write more than 1 line of code per
20    option.
21
22 Q: Why is it called "Trollop"?
23 A: No reason.
24
25 Q: Why does Trollop disallow numeric short argument names, like '-1'
26    and '-9'?
27 A: Because it's ambiguous whether these are arguments or negative
28    integer or floating-point parameters to arguments. E.g., what
29    about "-f -3". Is that a negative three parameter to -f, or two
30    separate parameters? 
31
32    I could be very clever and detect when there are no arguments
33    that require floating-point parameters, and allow such short option
34    names in those cases, but opted for simplicity and consistency.
35
36 Q: Why does Trollop disallow options appearing multiple times, despite
37    the POSIX standard allowing it?
38 A: Because basically I think it's confusing, and more often than
39    not, a symptom of you making a mistake (e.g. getting lost in a long
40    command line and accidentally setting the same thing twice.) 
41    I also don't see that much advantage to "-vvvvv" over "-v 5", so
42    Trollop will produce an error if you try to use the same argument
43    multiple times.
44