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.