FAQ.txt

   1 Trollop FAQ
   2 -----------
   3
   4 Q: Why is it called "Trollop"?
   5 A: No reason.
   6
   7 Q: Why should I use Trollop?
   8 A: Because it will take you FEWER LINES OF CODE to do reasonable option parsing
   9    than any other option parser out there.
  10
  11    Look at this:
  12
  13      opts = Trollop::options do
  14        opt :monkey, "Use monkey mode"
  15        opt :goat, "Use goat mode", :default => true
  16        opt :num_limbs, "Set number of limbs", :default => 4
  17      end
  18
  19    That's it. And opts is a hash and you do whatever you want with it.
  20    Trivial. You don't have to mix option processing code blocks with the
  21    declarations. You don't have to make a class for every option (what is this,
  22    Java?). You don't have to write more than 1 line of code per option.
  23
  24    Plus, you get a beautiful help screen that detects your terminal width and
  25    wraps appropriately. C'mon, that's hot.
  26
  27 Q: What is the philosophy behind Trollop?
  28 A: Must a commandline option processor have a philosophy?
  29
  30 Q: Seriously now. What is it?
  31 A: Ok, it's this: Trollop *just* does the parsing and gives you a hash table
  32    of the result. So whatever fancy logic or constraints you need, you can
  33    implement by operating on that hash table. Options that disable other
  34    options, fancy constraints involving multiple sets of values across multiple
  35    sets of options, etc. are all left for you to do manually.
  36
  37    (Trollop does support limited constraint setting (see #conflicts and
  38    #depends), but any non-trivial program will need to get fancier.)
  39
  40    The result is that using Trollop is pretty simple, and whatever bizarre
  41    logic you want, you can write yourself. And don't forget, you can call
  42    Trollop::die to abort the program and give a fancy options-related error
  43    message.
  44
  45 Q: What happens to the other stuff on the commandline?
  46 A: Anything Trollop doesn't recognize as an option or as an option parameter is
  47    left in ARGV for you to process.
  48
  49 Q: Does Trollop support multiple-value arguments?
  50 A: Yes. If you set the :type of an option to something plural, like ":ints",
  51    ":strings", ":doubles", ":floats", ":ios", it will accept multiple arguments
  52    on the commandline and the value will be an array of these.
  53
  54 Q: Does Trollop support arguments that can be given multiple times?
  55 A: Yes. If you set :multi to true, then the argument can appear multiple times
  56    on the commandline, and the value will be an array of the parameters.
  57
  58 Q: Does Trollop support subcommands?
  59 A: Yes. You get subcommand support by adding a call #stop_on within the options
  60    block, and passing the names of the subcommands to it. (See the third
  61    example on the webpage.) When Trollop encounters one of these subcommands on
  62    the commandline, it stops processing and returns.
  63
  64    ARGV at that point will contain the subcommand followed by any subcommand
  65    options, since Trollop has contained the rest. So you can consume the
  66    subcommand and call Trollop.options again with the particular options set
  67    for that subcommand.
  68
  69    If you don't know the subcommands ahead of time, you can call
  70    #stop_on_unknown, which will cause Trollop to stop when it encounters any
  71    unknown token. This might be more trouble than its worth if you're also
  72    passing filenames on the commandline.
  73
  74    It's probably easier to see the example on the webpage than to read all
  75    that.
  76
  77 Q: Why does Trollop disallow numeric short argument names, like '-1' and '-9'?
  78 A: Because it's ambiguous whether these are arguments or negative integer or
  79    floating-point parameters to arguments. E.g., what about "-f -3".  Is that a
  80    negative three parameter to -f, or two separate parameters?
  81
  82    I could be very clever and detect when there are no arguments that require
  83    floating-point parameters, and allow such short option names in those cases,
  84    but opted for simplicity and consistency.