remove warnings during test time
[trollop:mainline.git] / www / index.html
1 <html>
2 <head>
3 <title>Trollop</title>
4 <style type="text/css">
5 body { width: 800px; margin-left: auto; margin-right: auto; }
6 code { font-size: 14px; }
7 .ruby { background: #111122; padding: 10px; color: #228822; width: 800px; }
8 .ruby .normal { color: #fff; }
9 .ruby .comment { color: #99f }
10 .ruby .keyword { color: #A44; font-weight: bold; }
11 .ruby .method { color: #44f; }
12 .ruby .class { color: #0c4; }
13 .ruby .module { color: #050; }
14 .ruby .punct { color: #FF0; font-weight: bold; }
15 .ruby .symbol { color: #ff0; }
16 .ruby .string { color: #4f4 }
17 .ruby .char { color: #F07; }
18 .ruby .ident { color: #fff; }
19 .ruby .constant { color: #0c4; }
20 .ruby .regex { color: #B66; background: #444; }
21 .ruby .number { color: #F99; }
22 .ruby .attribute { color: #fc4; }
23 .ruby .global { color: #7FB; }
24 .ruby .expr { color: #827; }
25 .ruby .escape { color: #277; }
26 </style>
27 </head>
28
29 <body>
30
31 <h1>Trollop</h1>
32
33 <p style="border: solid 1px black; background: #ccc; padding: 0.5em;">
34 Current project news: see the <a href="http://all-thing.net/label/trollop">blog</a>.
35 </p>
36
37 <p>Trollop is a commandline option parser for Ruby that <i>gets out of your
38 way</i>. One line of code per option is all you need to write. For that, you get
39 a nice automatically-generated help page (fit to your screen size!), robust
40 option parsing, command subcompletion, and sensible defaults for everything you
41 don't specify.</p>
42
43 <p> Reasons to use Trollop:
44 <ol>
45 <li> It requires <i>fewer lines of code</i> than any other option out there. </li>
46 <li> It doesn't require you to subclass some shit just to use a damn option parser.</li>
47 </li>
48 <li> It's a single file. You don't even need to make it a dependency. Just throw it in <code>lib/</code>.</li>
49 <li> This gradient-free webpage. Fight the candy! </li>
50 </ol>
51 </p>
52
53 <p> To install, you have three options:
54 <ul>
55 <li>Trollop is a single file with no dependencies. You can <a href="http://gitorious.org/trollop/mainline/blobs/raw/master/lib/trollop.rb">just download it</a> and throw it in your code directory.</li>
56 <li>You can use rubygems and command your computer to <code>gem install trollop</code>.</li>
57 <li>You can download the tarball from the <a href="http://rubyforge.org/projects/trollop/">Trollop Rubyforge page</a>.</p>
58 </ul>
59
60 <p> To hack, command your computer to <code>git clone git://gitorious.org/trollop/mainline.git</code>, or see the <a href="http://gitorious.org/projects/trollop">Trollop Gitorious page</a>.</p>
61
62 <p>To understand, read the examples below, the <a href="FAQ.txt">FAQ</a>, and the <a href="trollop/">API docs</a>.
63
64 <h2>Examples</h2>
65 <h3>Simple</h3>
66 <pre class="ruby"><code><span class="ident">require</span> <span class="punct">'</span><span class="string">trollop</span><span class="punct">'</span>
67 <span class="ident">opts</span> <span class="punct">=</span> <span class="constant">Trollop</span><span class="punct">::</span><span class="ident">options</span> <span class="keyword">do</span>
68   <span class="ident">opt</span> <span class="symbol">:monkey</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">Use monkey mode</span><span class="punct">&quot;</span>                     <span class="comment"># flag --monkey, default false</span>
69   <span class="ident">opt</span> <span class="symbol">:goat</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">Use goat mode</span><span class="punct">&quot;,</span> <span class="symbol">:default</span> <span class="punct">=&gt;</span> <span class="constant">true</span>       <span class="comment"># flag --goat, default true</span>
70   <span class="ident">opt</span> <span class="symbol">:num_limbs</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">Number of limbs</span><span class="punct">&quot;,</span> <span class="symbol">:default</span> <span class="punct">=&gt;</span> <span class="number">4</span>   <span class="comment"># integer --num-limbs &lt;i&gt;, default to 4</span>
71   <span class="ident">opt</span> <span class="symbol">:num_thumbs</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">Number of thumbs</span><span class="punct">&quot;,</span> <span class="symbol">:type</span> <span class="punct">=&gt;</span> <span class="symbol">:int</span> <span class="comment"># integer --num-thumbs &lt;i&gt;, default nil</span>
72 <span class="keyword">end</span>
73
74 <span class="ident">p</span> <span class="ident">opts</span> <span class="comment"># a hash: { :monkey =&gt; false, :goat =&gt; true, :num_limbs =&gt; 4, :num_thumbs =&gt; nil }</span>
75 </code></pre>
76
77 <p>
78 <ul>
79 <li><tt>Trollop::options</tt> returns a hash of values. That's all the output you get.</li>
80 <li>Underscores are converted to dashes. <tt>opt :hello_there</tt> corresponds to an option <tt>--hello-there</tt>.
81 <li>All options are taken to be boolean flags, defaulting to false, unless you specify a default or a type. The type will be inferred from the default if given, so no need to specify both.</li>
82 <li>Short (one-character) option names are created automatically. You can set them manually with <tt>:short</tt>.
83 </ul>
84 </p>
85
86 <h3>Medium</h3>
87 <pre class="ruby"><code><span class="ident">require</span> <span class="punct">'</span><span class="string">trollop</span><span class="punct">'</span>
88 <span class="ident">opts</span> <span class="punct">=</span> <span class="constant">Trollop</span><span class="punct">::</span><span class="ident">options</span> <span class="keyword">do</span>
89   <span class="ident">version</span> <span class="punct">&quot;</span><span class="string">test 1.2.3 (c) 2008 William Morgan</span><span class="punct">&quot;</span>
90   <span class="ident">banner</span> <span class="punct">&lt;&lt;-</span><span class="constant">EOS</span><span class="string">
91 Test is an awesome program that does something very, very important.
92
93 Usage:
94        test [options] &lt;filenames&gt;+
95 where [options] are:
96 </span><span class="constant">EOS</span>
97
98   <span class="ident">opt</span> <span class="symbol">:ignore</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">Ignore incorrect values</span><span class="punct">&quot;</span>
99   <span class="ident">opt</span> <span class="symbol">:file</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">Extra data filename to read in, with a very long option description like this one</span><span class="punct">&quot;,</span>
100         <span class="symbol">:type</span> <span class="punct">=&gt;</span> <span class="constant">String</span>
101   <span class="ident">opt</span> <span class="symbol">:volume</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">Volume level</span><span class="punct">&quot;,</span> <span class="symbol">:default</span> <span class="punct">=&gt;</span> <span class="number">3.0</span>
102   <span class="ident">opt</span> <span class="symbol">:iters</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">Number of iterations</span><span class="punct">&quot;,</span> <span class="symbol">:default</span> <span class="punct">=&gt;</span> <span class="number">5</span>
103 <span class="keyword">end</span>
104 <span class="constant">Trollop</span><span class="punct">::</span><span class="ident">die</span> <span class="symbol">:volume</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">must be non-negative</span><span class="punct">&quot;</span> <span class="keyword">if</span> <span class="ident">opts</span><span class="punct">[</span><span class="symbol">:volume</span><span class="punct">]</span> <span class="punct">&lt;</span> <span class="number">0</span>
105 <span class="constant">Trollop</span><span class="punct">::</span><span class="ident">die</span> <span class="symbol">:file</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">must exist</span><span class="punct">&quot;</span> <span class="keyword">unless</span> <span class="constant">File</span><span class="punct">.</span><span class="ident">exist?</span><span class="punct">(</span><span class="ident">opts</span><span class="punct">[</span><span class="symbol">:file</span><span class="punct">])</span> <span class="keyword">if</span> <span class="ident">opts</span><span class="punct">[</span><span class="symbol">:file</span><span class="punct">]</span>
106 </code></pre>
107
108 <p>
109 <ul>
110 <li>You can specify a version and some banner text for the help message. <tt>--help</tt> and <tt>--version</tt> are defined for you.</li>
111 <li>Any special error-checking is done by you, on the option hash. You can call <tt>Trollop::die</tt> to die with a nice message.</li>
112 </ul>
113 </p>
114
115 <h3>Sub-commands, a la SVN and Git</h3>
116 <pre class="ruby"><code><span class="ident">require</span> <span class="punct">'</span><span class="string">trollop</span><span class="punct">'</span>
117
118 <span class="comment">## Here's a program called &quot;magic&quot;. We want this behavior:</span>
119 <span class="comment">##</span>
120 <span class="comment">##   magic delete &lt;fn&gt; =&gt; deletes a file</span>
121 <span class="comment">##   magic copy &lt;fn&gt;   =&gt; copies a file</span>
122 <span class="comment">##</span>
123 <span class="comment">## So 'delete' and 'copy' are subcommands.</span>
124 <span class="comment">##</span>
125 <span class="comment">## There are some global options, which appear to the left of the subcommand.</span>
126 <span class="comment">## There are some subcommand options, which appear to the right.</span>
127 <span class="comment">##</span>
128 <span class="comment">## Subcommand options can be specific to the subcommand. 'delete' might take</span>
129 <span class="comment">## different options from 'copy'.</span>
130 <span class="comment">##</span>
131 <span class="comment">## We do this by calling Trollop twice; one for the global options and once for</span>
132 <span class="comment">## the subcommand options. We need to tell Trollop what the subcommands are, so</span>
133 <span class="comment">## that it stops processing the global options when it encounters one of them.</span>
134
135 <span class="constant">SUB_COMMANDS</span> <span class="punct">=</span> <span class="punct">%w(</span><span class="string">delete copy</span><span class="punct">)</span>
136 <span class="ident">global_opts</span> <span class="punct">=</span> <span class="constant">Trollop</span><span class="punct">::</span><span class="ident">options</span> <span class="keyword">do</span>
137   <span class="ident">banner</span> <span class="punct">&quot;</span><span class="string">magic file deleting and copying utility</span><span class="punct">&quot;</span>
138   <span class="ident">opt</span> <span class="symbol">:dry_run</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">Don't actually do anything</span><span class="punct">&quot;,</span> <span class="symbol">:short</span> <span class="punct">=&gt;</span> <span class="punct">&quot;</span><span class="string">-n</span><span class="punct">&quot;</span>
139   <span class="ident">stop_on</span> <span class="constant">SUB_COMMANDS</span>
140 <span class="keyword">end</span>
141
142 <span class="ident">cmd</span> <span class="punct">=</span> <span class="constant">ARGV</span><span class="punct">.</span><span class="ident">shift</span> <span class="comment"># get the subcommand</span>
143 <span class="ident">cmd_opts</span> <span class="punct">=</span> <span class="keyword">case</span> <span class="ident">cmd</span>
144   <span class="keyword">when</span> <span class="punct">&quot;</span><span class="string">delete</span><span class="punct">&quot;</span> <span class="comment"># parse delete options</span>
145     <span class="constant">Trollop</span><span class="punct">::</span><span class="ident">options</span> <span class="keyword">do</span>
146       <span class="ident">opt</span> <span class="symbol">:force</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">Force deletion</span><span class="punct">&quot;</span>
147     <span class="keyword">end</span>
148   <span class="keyword">when</span> <span class="punct">&quot;</span><span class="string">copy</span><span class="punct">&quot;</span>  <span class="comment"># parse copy options</span>
149     <span class="constant">Trollop</span><span class="punct">::</span><span class="ident">options</span> <span class="keyword">do</span>
150       <span class="ident">opt</span> <span class="symbol">:double</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">Copy twice for safety's sake</span><span class="punct">&quot;</span>
151     <span class="keyword">end</span>
152   <span class="keyword">else</span>
153     <span class="constant">Trollop</span><span class="punct">::</span><span class="ident">die</span> <span class="punct">&quot;</span><span class="string">unknown subcommand <span class="expr">#{cmd.inspect}</span></span><span class="punct">&quot;</span>
154   <span class="keyword">end</span>
155
156 <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">Global options: <span class="expr">#{global_opts.inspect}</span></span><span class="punct">&quot;</span>
157 <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">Subcommand: <span class="expr">#{cmd.inspect}</span></span><span class="punct">&quot;</span>
158 <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">Subcommand options: <span class="expr">#{cmd_opts.inspect}</span></span><span class="punct">&quot;</span>
159 <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">Remaining arguments: <span class="expr">#{ARGV.inspect}</span></span><span class="punct">&quot;</span></code></pre>
160
161 <h3>Specialized parsing behavior</h3>
162 <p>Sometimes calling <code>Trollop::options</code> does too much for us. In this example, we create the parser without using <code>Trollop::options</code>, and force it to display the help message (and exit) if the user doesn't supply any arguments. The <code>with_standard_exception_handling</code> method takes care of dealing with the <code>VersionNeeded</code>, <code>HelpNeeded</code> and <code>CommandlineError</code> exceptions that <code>Parser#parse</code> throws, but we could handle those manually as well.</p>
163
164 <pre class="ruby"><code><span class="ident">require</span> <span class="punct">'</span><span class="string">trollop</span><span class="punct">'</span>
165 <span class="ident">p</span> <span class="punct">=</span> <span class="constant">Trollop</span><span class="punct">::</span><span class="constant">Parser</span><span class="punct">.</span><span class="ident">new</span> <span class="keyword">do</span>
166   <span class="ident">opt</span> <span class="symbol">:monkey</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">Use monkey mode</span><span class="punct">&quot;</span>                     <span class="comment"># a flag --monkey, defaulting to false</span>
167   <span class="ident">opt</span> <span class="symbol">:goat</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">Use goat mode</span><span class="punct">&quot;,</span> <span class="symbol">:default</span> <span class="punct">=&gt;</span> <span class="constant">true</span>       <span class="comment"># a flag --goat, defaulting to true</span>
168 <span class="keyword">end</span>
169
170 <span class="ident">opts</span> <span class="punct">=</span> <span class="constant">Trollop</span><span class="punct">::</span><span class="ident">with_standard_exception_handling</span> <span class="ident">p</span> <span class="keyword">do</span>
171   <span class="ident">o</span> <span class="punct">=</span> <span class="ident">p</span><span class="punct">.</span><span class="ident">parse</span> <span class="constant">ARGV</span>
172   <span class="keyword">raise</span> <span class="constant">Trollop</span><span class="punct">::</span><span class="constant">HelpNeeded</span> <span class="keyword">if</span> <span class="constant">ARGV</span><span class="punct">.</span><span class="ident">empty?</span> <span class="comment"># show help screen</span>
173   <span class="ident">o</span>
174 <span class="keyword">end</span></code></pre>
175
176 <h2> Contributors </h2>
177
178 <p>Trollop is brought to you by <a href="http://cs.stanford.edu/~ruby/">William Morgan</a> and by:
179 <ul>
180 <li>Tuomas Kareinen &lt;tkareine at the gmail dot coms&gt;</li>
181 <li>Ohad Lutzky &lt;ohad at the lutzky dot nets&gt;</li>
182 <li>Erik Ostrom &lt;erik at the echographia dot coms&gt;</li>
183 <li>Will Fitzgerald &lt;will.fitzgerald at the pobox dot coms&gt;</li>
184 </ul>
185 </p>
186
187 </body>
188 </html>