lots of documentation improvements
[trollop:mainline.git] / 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.