bump to 1.9
[trollop:michaeljedgars-mainline.git] / www / index.html
1 <html>
2 <head>
3 <title>Trollop</title>
4 <style type="text/css">
5 .ruby { background: #111122; padding: 10px; color: #228822; }
6 .ruby .normal { color: #fff; }
7 .ruby .comment { color: #99f }
8 .ruby .keyword { color: #A44; font-weight: bold; }
9 .ruby .method { color: #44f; }
10 .ruby .class { color: #0c4; }
11 .ruby .module { color: #050; }
12 .ruby .punct { color: #FF0; font-weight: bold; }
13 .ruby .symbol { color: #ff0; }
14 .ruby .string { color: #4f4 }
15 .ruby .char { color: #F07; }
16 .ruby .ident { color: #fff; }
17 .ruby .constant { color: #0c4; }
18 .ruby .regex { color: #B66; background: #444; }
19 .ruby .number { color: #F99; }
20 .ruby .attribute { color: #fc4; }
21 .ruby .global { color: #7FB; }
22 .ruby .expr { color: #227; }
23 .ruby .escape { color: #277; }
24 </style>
25 </head>
26
27 <body>
28
29 <h1>Trollop</h1>
30
31 <p>Trollop is a commandline option parser for Ruby that just gets out of your
32 way. One line of code per option is all you need to write. For that, you get
33 a nice automatically-generated help page, robust option parsing, command
34 subcompletion, and sensible defaults for everything you don't specify.</p>
35
36 <p> Reasons to use Trollop:
37 <ol>
38 <li> It requires <i>fewer lines of code</i> than any other option out there. </li>
39 <li> It doesn't require you to subclass some shit just to use an damn option parser.</li>
40 </li>
41 <li> It's one file. You don't even need to make it a dependency. Just throw it in <code>lib/</code>.</li>
42 <li> This gradient-free webpage. Fight the candy! </li>
43 </ol>
44 </p>
45
46 <p> To install, get the raw blob data for <a href="http://gitorious.org/projects/trollop/repos/mainline/blobs/master/lib%2Ftrollop.rb">lib/trollop.rb</a>, or download the tarball from the <a href="http://rubyforge.org/projects/trollop/">Trollop Rubyforge page</a>, or command your computer to <code>gem install trollop</code>.</p>
47
48
49 <p> To hack,  see the <a href="http://gitorious.org/projects/trollop">Trollop Gitorious page</a>. </p>
50
51 <p>To understand, see the <a href="README.txt">README</a>, <a href="FAQ.txt">FAQ</a>, and <a href="trollop/">API docs</a>.
52
53 <h2>Synopses</h2>
54 <h3>Simple</h3>
55 <pre class="ruby">
56 <span class="ident">require</span> <span class="punct">'</span><span class="string">trollop</span><span class="punct">'</span>
57 <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>
58   <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>
59   <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>
60   <span class="ident">opt</span> <span class="symbol">:num_limbs</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">Set number of limbs</span><span class="punct">&quot;,</span> <span class="symbol">:default</span> <span class="punct">=&gt;</span> <span class="number">4</span>
61 <span class="keyword">end</span>
62
63 <span class="ident">p</span> <span class="ident">opts</span> <span class="comment"># { :monkey =&gt; false, :goat =&gt; true, :num_limbs =&gt; 4 }</span>
64 </pre>
65
66 <h3>Medium</h3>
67 <pre class="ruby">
68 <span class="ident">require</span> <span class="punct">'</span><span class="string">trollop</span><span class="punct">'</span>
69 <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>
70   <span class="ident">version</span> <span class="punct">&quot;</span><span class="string">test 1.2.3 (c) 2007 William Morgan</span><span class="punct">&quot;</span>
71   <span class="ident">banner</span> <span class="punct">&lt;&lt;-</span><span class="constant">EOS</span><span class="string">
72 Test is an awesome program that does something very, very important.
73
74 Usage:
75        test [options] &lt;filenames&gt;+
76 where [options] are:
77 </span><span class="constant">EOS</span>
78
79   <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>
80   <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> <span class="symbol">:type</span> <span class="punct">=&gt;</span> <span class="constant">String</span>
81   <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>
82   <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>
83 <span class="keyword">end</span>
84 <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>
85 <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>
86 </pre>
87
88 <h3>Sub-commands</h3>
89 <pre class="ruby">
90 <span class="ident">require</span> <span class="punct">'</span><span class="string">trollop</span><span class="punct">'</span>
91 <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>
92   <span class="ident">opt</span> <span class="symbol">:global_option</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">This is a global option</span><span class="punct">&quot;</span>
93   <span class="ident">stop_on</span> <span class="punct">%w(</span><span class="string">sub-command-1 sub-command-2</span><span class="punct">)</span>
94 <span class="keyword">end</span>
95
96 <span class="ident">cmd</span> <span class="punct">=</span> <span class="constant">ARGV</span><span class="punct">.</span><span class="ident">shift</span>
97 <span class="ident">cmd_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>
98   <span class="ident">opt</span> <span class="symbol">:cmd_option</span><span class="punct">,</span> <span class="punct">&quot;</span><span class="string">This is an option only for the subcommand</span><span class="punct">&quot;</span>
99 <span class="keyword">end</span>
100
101 <span class="ident">p</span> <span class="ident">global_opts</span>
102 <span class="ident">p</span> <span class="ident">cmd</span>
103 <span class="ident">p</span> <span class="ident">cmd_opts</span>
104 </pre>
105
106 <h2> Contributors </h2>
107
108 <p>Trollop is brought to you by William Morgan and by:
109 <ul>
110 <li>Tuomas Kareinen &lt;tkareine at the gmail dot coms&gt;</li>
111 <li>Ohad Lutzky &lt;ohad at the lutzky dot nets&gt;</li>
112 </ul>
113 </p>
114
115 </body>
116 </html>