README.txt

   1 == trollop
   2
   3 by William Morgan <wmorgan-trollop@masanjin.net>
   4
   5 http://trollop.rubyforge.org
   6
   7 Documentation quickstart: See Trollop::Parser.
   8
   9 == DESCRIPTION
  10
  11 Trollop is YAFCLAP --- yet another fine commandline argument processor
  12 for Ruby. Trollop is designed to provide the maximal amount of GNU-style
  13 argument processing in the minimum number of lines of code (for you, the
  14 programmer).
  15
  16 Trollop provides a nice automatically-generated help page, robust option
  17 parsing, and sensible defaults for everything you don't specify.
  18
  19 Trollop: getting you 90% of the way there with only 10% of the effort.
  20
  21 == FEATURES/PROBLEMS
  22
  23 - Simple usage.
  24 - Sensible defaults. No tweaking necessary, much tweaking possible.
  25 - Support for long options, short options, short option bundling,
  26   and automatic type validation and conversion.
  27 - Automatic help message generation, wrapped to current screen width.
  28 - Lots of unit tests.
  29
  30 == SYNOPSIS
  31
  32   ###### simple ######
  33
  34   require 'trollop'
  35   opts = Trollop::options do
  36     opt :monkey, "Use monkey mode"
  37     opt :goat, "Use goat mode", :default => true
  38     opt :num_limbs, "Set number of limbs", :default => 4
  39   end
  40
  41   p opts
  42
  43   ###### medium ######
  44
  45   require 'trollop'
  46   opts = Trollop::options do
  47     version "test 1.2.3 (c) 2007 William Morgan"
  48     banner <<-EOS
  49   Test is an awesome program that does something very, very important.
  50
  51   Usage:
  52          test [options] <filenames>+
  53   where [options] are:
  54   EOS
  55
  56     opt :ignore, "Ignore incorrect values"
  57     opt :file, "Extra data filename to read in, with a very long option description like this one", :type => String
  58     opt :volume, "Volume level", :default => 3.0
  59     opt :iters, "Number of iterations", :default => 5
  60   end
  61   Trollop::die :volume, "must be non-negative" if opts[:volume] < 0
  62   Trollop::die :file, "must exist" unless File.exist?(opts[:file]) if opts[:file]
  63
  64   ###### real-life ######
  65
  66   require 'trollop'
  67   opts = Trollop::options do
  68     version "sup-sync (sup #{Redwood::VERSION})"
  69     banner <<EOS
  70   Synchronizes the Sup index with one or more message sources by adding
  71   messages, deleting messages, or changing message state in the index as
  72   appropriate.
  73
  74   [...]
  75
  76   Usage:
  77     sup-sync [options] <source>*
  78
  79   where <source>* is zero or more source URIs. If no sources are given,
  80   sync from all usual sources. Supported source URI schemes can be seen
  81   by running "sup-add --help".
  82
  83   Options controlling WHICH messages sup-sync operates on:
  84   EOS
  85     opt :new, "Operate on new messages only. Don't scan over the entire source. (Default.)", :short => :none
  86     opt :changed, "Scan over the entire source for messages that have been deleted, altered, or moved from another source. (In the case of mbox sources, this includes all messages AFTER an altered message.)"
  87     opt :restored, "Operate only on those messages included in a dump file as specified by --restore which have changed state."
  88     opt :all, "Operate on all messages in the source, regardless of newness or changedness."
  89     opt :start_at, "For --changed and --all, start at a particular offset.", :type => :int
  90
  91   text <<EOS
  92
  93   Options controlling HOW message state is altered:
  94   EOS
  95     opt :asis, "If the message is already in the index, preserve its state. Otherwise, use default source state. (Default.)", :short => :none
  96     opt :restore, "Restore message state from a dump file created with sup-dump. If a message is not in this dumpfile, act as --asis.", :type => String, :short => :none
  97     opt :discard, "Discard any message state in the index and use the default source state. Dangerous!", :short => :none
  98     opt :archive, "When using the default source state, mark messages as archived.", :short => "-x"
  99     opt :read, "When using the default source state, mark messages as read."
 100     opt :extra_labels, "When using the default source state, also apply these user-defined labels. Should be a comma-separated list.", :type => String, :short => :none
 101
 102   text <<EOS
 103
 104   Other options:
 105   EOS
 106     opt :verbose, "Print message ids as they're processed."
 107     opt :optimize, "As the final operation, optimize the index."
 108     opt :all_sources, "Scan over all sources.", :short => :none
 109     opt :dry_run, "Don't actually modify the index. Probably only useful with --verbose.", :short => "-n"
 110     opt :version, "Show version information", :short => :none
 111
 112     conflicts :changed, :all, :new, :restored
 113     conflicts :asis, :restore, :discard
 114   end
 115   Trollop::die :restored, "requires --restore" if opts[:restored] unless opts[:restore]
 116   if opts[:start_at]
 117     Trollop::die :start_at, "must be non-negative" if opts[:start_at] < 0
 118     Trollop::die :start_at, "requires either --changed or --all" unless opts[:changed] || opts[:all]
 119   end
 120
 121 == REQUIREMENTS
 122
 123 * none!
 124
 125 == INSTALL
 126
 127 * gem install trollop
 128
 129 == LICENSE
 130
 131 Copyright (c) 2008 William Morgan.
 132
 133 Trollop is distributed under the same terms as Ruby.