lots of documentation improvements
[trollop:mainline.git] / www / index.html
1 <html>
2 <head>
3 <title>Trollop</title>
4 </head>
5
6 <body>
7
8 <h1>Trollop</h1>
9
10 <p>Trollop is YAFCLAP --- yet another fine commandline argument
11 processing library for Ruby.</p>
12
13 <p>See the <a href="README.txt">README</a>,
14    <a href="FAQ.txt">FAQ</a>,
15    <a href="trollop/">API docs</a>, or 
16    <a href="http://rubyforge.org/projects/trollop/">Rubyforge page</a>.</p>
17
18 <h2>Synopsis</h2>
19 <pre>
20   ###### simple ######
21
22   require 'trollop'
23   opts = Trollop::options do
24     opt :monkey, "Use monkey mode"
25     opt :goat, "Use goat mode", :default => true
26     opt :num_limbs, "Set number of limbs", :default => 4
27   end
28
29   p opts
30
31   ###### medium ######
32
33   require 'trollop'
34   opts = Trollop::options do
35     version "test 1.2.3 (c) 2007 William Morgan"
36     banner &lt;&lt;-EOS
37   Test is an awesome program that does something very, very important.
38
39   Usage:
40          test [options] <filenames>+
41   where [options] are:
42   EOS
43
44     opt :ignore, "Ignore incorrect values"
45     opt :file, "Extra data filename to read in, with a very long option description like this one", :type => String
46     opt :volume, "Volume level", :default => 3.0
47     opt :iters, "Number of iterations", :default => 5
48   end
49   Trollop::die :volume, "must be non-negative" if opts[:volume] < 0
50   Trollop::die :file, "must exist" unless File.exist?(opts[:file]) if opts[:file]
51
52   ###### real-life ######
53
54   require 'trollop'
55   opts = Trollop::options do
56     version "sup-sync (sup #{Redwood::VERSION})"
57     banner &lt;&lt;EOS
58   Synchronizes the Sup index with one or more message sources by adding
59   messages, deleting messages, or changing message state in the index as
60   appropriate.
61
62   [...]
63   
64   Usage:
65     sup-sync [options] <source>*
66   
67   where <source>* is zero or more source URIs. If no sources are given,
68   sync from all usual sources. Supported source URI schemes can be seen
69   by running "sup-add --help".
70   
71   Options controlling WHICH messages sup-sync operates on:
72   EOS
73     opt :new, "Operate on new messages only. Don't scan over the entire source. (Default.)", :short => :none
74     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.)"
75     opt :restored, "Operate only on those messages included in a dump file as specified by --restore which have changed state."
76     opt :all, "Operate on all messages in the source, regardless of newness or changedness."
77     opt :start_at, "For --changed and --all, start at a particular offset.", :type => :int
78   
79   text &lt;&lt;EOS
80   
81   Options controlling HOW message state is altered:
82   EOS
83     opt :asis, "If the message is already in the index, preserve its state. Otherwise, use default source state. (Default.)", :short => :none
84     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
85     opt :discard, "Discard any message state in the index and use the default source state. Dangerous!", :short => :none
86     opt :archive, "When using the default source state, mark messages as archived.", :short => "-x"
87     opt :read, "When using the default source state, mark messages as read."
88     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
89   
90   text &lt;&lt;EOS
91   
92   Other options:
93   EOS
94     opt :verbose, "Print message ids as they're processed."
95     opt :optimize, "As the final operation, optimize the index."
96     opt :all_sources, "Scan over all sources.", :short => :none
97     opt :dry_run, "Don't actually modify the index. Probably only useful with --verbose.", :short => "-n"
98     opt :version, "Show version information", :short => :none
99   
100     conflicts :changed, :all, :new, :restored
101     conflicts :asis, :restore, :discard
102   end
103   Trollop::die :restored, "requires --restore" if opts[:restored] unless opts[:restore]
104   if opts[:start_at]
105     Trollop::die :start_at, "must be non-negative" if opts[:start_at] < 0
106     Trollop::die :start_at, "requires either --changed or --all" unless opts[:changed] || opts[:all]
107   end
108 </pre>
109
110 </body>
111 </html>