PageRenderTime 44ms CodeModel.GetById 2ms app.highlight 32ms RepoModel.GetById 1ms app.codeStats 1ms

/documentation/docs/optparse.html

http://github.com/jashkenas/coffee-script
HTML | 366 lines | 259 code | 107 blank | 0 comment | 0 complexity | 626acfb49f15017332731849dbd26900 MD5 | raw file
  1<!DOCTYPE html>
  2
  3<html>
  4<head>
  5  <title>optparse.coffee</title>
  6  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  7  <meta name="viewport" content="width=device-width, target-densitydpi=160dpi, initial-scale=1.0; maximum-scale=1.0; user-scalable=0;">
  8  <link rel="stylesheet" media="all" href="docco.css" />
  9</head>
 10<body>
 11  <div id="container">
 12    <div id="background"></div>
 13    
 14      <ul id="jump_to">
 15        <li>
 16          <a class="large" href="javascript:void(0);">Jump To &hellip;</a>
 17          <a class="small" href="javascript:void(0);">+</a>
 18          <div id="jump_wrapper">
 19          <div id="jump_page_wrapper">
 20            <div id="jump_page">
 21              
 22                
 23                <a class="source" href="browser.html">
 24                  browser.coffee
 25                </a>
 26              
 27                
 28                <a class="source" href="cake.html">
 29                  cake.coffee
 30                </a>
 31              
 32                
 33                <a class="source" href="coffee-script.html">
 34                  coffee-script.coffee
 35                </a>
 36              
 37                
 38                <a class="source" href="command.html">
 39                  command.coffee
 40                </a>
 41              
 42                
 43                <a class="source" href="grammar.html">
 44                  grammar.coffee
 45                </a>
 46              
 47                
 48                <a class="source" href="helpers.html">
 49                  helpers.coffee
 50                </a>
 51              
 52                
 53                <a class="source" href="index.html">
 54                  index.coffee
 55                </a>
 56              
 57                
 58                <a class="source" href="lexer.html">
 59                  lexer.coffee
 60                </a>
 61              
 62                
 63                <a class="source" href="nodes.html">
 64                  nodes.coffee
 65                </a>
 66              
 67                
 68                <a class="source" href="optparse.html">
 69                  optparse.coffee
 70                </a>
 71              
 72                
 73                <a class="source" href="register.html">
 74                  register.coffee
 75                </a>
 76              
 77                
 78                <a class="source" href="repl.html">
 79                  repl.coffee
 80                </a>
 81              
 82                
 83                <a class="source" href="rewriter.html">
 84                  rewriter.coffee
 85                </a>
 86              
 87                
 88                <a class="source" href="scope.html">
 89                  scope.litcoffee
 90                </a>
 91              
 92                
 93                <a class="source" href="sourcemap.html">
 94                  sourcemap.litcoffee
 95                </a>
 96              
 97            </div>
 98          </div>
 99        </li>
100      </ul>
101    
102    <ul class="sections">
103        
104          <li id="title">
105              <div class="annotation">
106                  <h1>optparse.coffee</h1>
107              </div>
108          </li>
109        
110        
111        
112        <li id="section-1">
113            <div class="annotation">
114              
115              <div class="pilwrap ">
116                <a class="pilcrow" href="#section-1">&#182;</a>
117              </div>
118              
119            </div>
120            
121            <div class="content"><div class='highlight'><pre>{repeat} = <span class="hljs-built_in">require</span> <span class="hljs-string">'./helpers'</span></pre></div></div>
122            
123        </li>
124        
125        
126        <li id="section-2">
127            <div class="annotation">
128              
129              <div class="pilwrap ">
130                <a class="pilcrow" href="#section-2">&#182;</a>
131              </div>
132              <p>A simple <strong>OptionParser</strong> class to parse option flags from the command-line.
133Use it like so:</p>
134<pre><code>parser  = <span class="hljs-keyword">new</span> OptionParser switches, helpBanner
135options = parser.parse process.argv
136</code></pre><p>The first non-option is considered to be the start of the file (and file
137option) list, and all subsequent arguments are left unparsed.</p>
138
139            </div>
140            
141            <div class="content"><div class='highlight'><pre><span class="hljs-built_in">exports</span>.OptionParser = <span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">OptionParser</span></span></pre></div></div>
142            
143        </li>
144        
145        
146        <li id="section-3">
147            <div class="annotation">
148              
149              <div class="pilwrap ">
150                <a class="pilcrow" href="#section-3">&#182;</a>
151              </div>
152              <p>Initialize with a list of valid options, in the form:</p>
153<pre><code>[short-flag, long-flag, description]
154</code></pre><p>Along with an an optional banner for the usage help.</p>
155
156            </div>
157            
158            <div class="content"><div class='highlight'><pre>  <span class="hljs-attribute">constructor</span>: <span class="hljs-function"><span class="hljs-params">(rules, <span class="hljs-property">@banner</span>)</span> -&gt;</span>
159    <span class="hljs-property">@rules</span> = buildRules rules</pre></div></div>
160            
161        </li>
162        
163        
164        <li id="section-4">
165            <div class="annotation">
166              
167              <div class="pilwrap ">
168                <a class="pilcrow" href="#section-4">&#182;</a>
169              </div>
170              <p>Parse the list of arguments, populating an <code>options</code> object with all of the
171specified options, and return it. Options after the first non-option
172argument are treated as arguments. <code>options.arguments</code> will be an array
173containing the remaining arguments. This is a simpler API than many option
174parsers that allow you to attach callback actions for every flag. Instead,
175you’re responsible for interpreting the options object.</p>
176
177            </div>
178            
179            <div class="content"><div class='highlight'><pre>  <span class="hljs-attribute">parse</span>: <span class="hljs-function"><span class="hljs-params">(args)</span> -&gt;</span>
180    options = <span class="hljs-attribute">arguments</span>: []
181    skippingArgument = <span class="hljs-literal">no</span>
182    originalArgs = args
183    args = normalizeArguments args
184    <span class="hljs-keyword">for</span> arg, i <span class="hljs-keyword">in</span> args
185      <span class="hljs-keyword">if</span> skippingArgument
186        skippingArgument = <span class="hljs-literal">no</span>
187        <span class="hljs-keyword">continue</span>
188      <span class="hljs-keyword">if</span> arg <span class="hljs-keyword">is</span> <span class="hljs-string">'--'</span>
189        pos = originalArgs.indexOf <span class="hljs-string">'--'</span>
190        options.arguments = options.arguments.concat originalArgs[(pos + <span class="hljs-number">1</span>)..]
191        <span class="hljs-keyword">break</span>
192      isOption = !!(arg.match(LONG_FLAG) <span class="hljs-keyword">or</span> arg.match(SHORT_FLAG))</pre></div></div>
193            
194        </li>
195        
196        
197        <li id="section-5">
198            <div class="annotation">
199              
200              <div class="pilwrap ">
201                <a class="pilcrow" href="#section-5">&#182;</a>
202              </div>
203              <p>the CS option parser is a little odd; options after the first
204non-option argument are treated as non-option arguments themselves</p>
205
206            </div>
207            
208            <div class="content"><div class='highlight'><pre>      seenNonOptionArg = options.arguments.length &gt; <span class="hljs-number">0</span>
209      <span class="hljs-keyword">unless</span> seenNonOptionArg
210        matchedRule = <span class="hljs-literal">no</span>
211        <span class="hljs-keyword">for</span> rule <span class="hljs-keyword">in</span> <span class="hljs-property">@rules</span>
212          <span class="hljs-keyword">if</span> rule.shortFlag <span class="hljs-keyword">is</span> arg <span class="hljs-keyword">or</span> rule.longFlag <span class="hljs-keyword">is</span> arg
213            value = <span class="hljs-literal">true</span>
214            <span class="hljs-keyword">if</span> rule.hasArgument
215              skippingArgument = <span class="hljs-literal">yes</span>
216              value = args[i + <span class="hljs-number">1</span>]
217            options[rule.name] = <span class="hljs-keyword">if</span> rule.isList <span class="hljs-keyword">then</span> (options[rule.name] <span class="hljs-keyword">or</span> []).concat value <span class="hljs-keyword">else</span> value
218            matchedRule = <span class="hljs-literal">yes</span>
219            <span class="hljs-keyword">break</span>
220        <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> Error <span class="hljs-string">"unrecognized option: <span class="hljs-subst">#{arg}</span>"</span> <span class="hljs-keyword">if</span> isOption <span class="hljs-keyword">and</span> <span class="hljs-keyword">not</span> matchedRule
221      <span class="hljs-keyword">if</span> seenNonOptionArg <span class="hljs-keyword">or</span> <span class="hljs-keyword">not</span> isOption
222        options.arguments.push arg
223    options</pre></div></div>
224            
225        </li>
226        
227        
228        <li id="section-6">
229            <div class="annotation">
230              
231              <div class="pilwrap ">
232                <a class="pilcrow" href="#section-6">&#182;</a>
233              </div>
234              <p>Return the help text for this <strong>OptionParser</strong>, listing and describing all
235of the valid options, for <code>--help</code> and such.</p>
236
237            </div>
238            
239            <div class="content"><div class='highlight'><pre>  <span class="hljs-attribute">help</span>:<span class="hljs-function"> -&gt;</span>
240    lines = []
241    lines.unshift <span class="hljs-string">"<span class="hljs-subst">#{<span class="hljs-property">@banner</span>}</span>\n"</span> <span class="hljs-keyword">if</span> <span class="hljs-property">@banner</span>
242    <span class="hljs-keyword">for</span> rule <span class="hljs-keyword">in</span> <span class="hljs-property">@rules</span>
243      spaces  = <span class="hljs-number">15</span> - rule.longFlag.length
244      spaces  = <span class="hljs-keyword">if</span> spaces &gt; <span class="hljs-number">0</span> <span class="hljs-keyword">then</span> repeat <span class="hljs-string">' '</span>, spaces <span class="hljs-keyword">else</span> <span class="hljs-string">''</span>
245      letPart = <span class="hljs-keyword">if</span> rule.shortFlag <span class="hljs-keyword">then</span> rule.shortFlag + <span class="hljs-string">', '</span> <span class="hljs-keyword">else</span> <span class="hljs-string">'    '</span>
246      lines.push <span class="hljs-string">'  '</span> + letPart + rule.longFlag + spaces + rule.description
247    <span class="hljs-string">"\n<span class="hljs-subst">#{ lines.join(<span class="hljs-string">'\n'</span>) }</span>\n"</span></pre></div></div>
248            
249        </li>
250        
251        
252        <li id="section-7">
253            <div class="annotation">
254              
255              <div class="pilwrap ">
256                <a class="pilcrow" href="#section-7">&#182;</a>
257              </div>
258              <h2 id="helpers">Helpers</h2>
259
260            </div>
261            
262        </li>
263        
264        
265        <li id="section-8">
266            <div class="annotation">
267              
268              <div class="pilwrap ">
269                <a class="pilcrow" href="#section-8">&#182;</a>
270              </div>
271              
272            </div>
273            
274        </li>
275        
276        
277        <li id="section-9">
278            <div class="annotation">
279              
280              <div class="pilwrap ">
281                <a class="pilcrow" href="#section-9">&#182;</a>
282              </div>
283              <p>Regex matchers for option flags.</p>
284
285            </div>
286            
287            <div class="content"><div class='highlight'><pre>LONG_FLAG  = <span class="hljs-regexp">/^(--\w[\w\-]*)/</span>
288SHORT_FLAG = <span class="hljs-regexp">/^(-\w)$/</span>
289MULTI_FLAG = <span class="hljs-regexp">/^-(\w{2,})/</span>
290OPTIONAL   = <span class="hljs-regexp">/\[(\w+(\*?))\]/</span></pre></div></div>
291            
292        </li>
293        
294        
295        <li id="section-10">
296            <div class="annotation">
297              
298              <div class="pilwrap ">
299                <a class="pilcrow" href="#section-10">&#182;</a>
300              </div>
301              <p>Build and return the list of option rules. If the optional <em>short-flag</em> is
302unspecified, leave it out by padding with <code>null</code>.</p>
303
304            </div>
305            
306            <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">buildRules</span> = <span class="hljs-params">(rules)</span> -&gt;</span>
307  <span class="hljs-keyword">for</span> tuple <span class="hljs-keyword">in</span> rules
308    tuple.unshift <span class="hljs-literal">null</span> <span class="hljs-keyword">if</span> tuple.length &lt; <span class="hljs-number">3</span>
309    buildRule tuple...</pre></div></div>
310            
311        </li>
312        
313        
314        <li id="section-11">
315            <div class="annotation">
316              
317              <div class="pilwrap ">
318                <a class="pilcrow" href="#section-11">&#182;</a>
319              </div>
320              <p>Build a rule from a <code>-o</code> short flag, a <code>--output [DIR]</code> long flag, and the
321description of what the option does.</p>
322
323            </div>
324            
325            <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">buildRule</span> = <span class="hljs-params">(shortFlag, longFlag, description, options = {})</span> -&gt;</span>
326  match     = longFlag.match(OPTIONAL)
327  longFlag  = longFlag.match(LONG_FLAG)[<span class="hljs-number">1</span>]
328  {
329    <span class="hljs-attribute">name</span>:         longFlag.substr <span class="hljs-number">2</span>
330    <span class="hljs-attribute">shortFlag</span>:    shortFlag
331    <span class="hljs-attribute">longFlag</span>:     longFlag
332    <span class="hljs-attribute">description</span>:  description
333    <span class="hljs-attribute">hasArgument</span>:  !!(match <span class="hljs-keyword">and</span> match[<span class="hljs-number">1</span>])
334    <span class="hljs-attribute">isList</span>:       !!(match <span class="hljs-keyword">and</span> match[<span class="hljs-number">2</span>])
335  }</pre></div></div>
336            
337        </li>
338        
339        
340        <li id="section-12">
341            <div class="annotation">
342              
343              <div class="pilwrap ">
344                <a class="pilcrow" href="#section-12">&#182;</a>
345              </div>
346              <p>Normalize arguments by expanding merged flags into multiple flags. This allows
347you to have <code>-wl</code> be the same as <code>--watch --lint</code>.</p>
348
349            </div>
350            
351            <div class="content"><div class='highlight'><pre><span class="hljs-function"><span class="hljs-title">normalizeArguments</span> = <span class="hljs-params">(args)</span> -&gt;</span>
352  args = args[..]
353  result = []
354  <span class="hljs-keyword">for</span> arg <span class="hljs-keyword">in</span> args
355    <span class="hljs-keyword">if</span> match = arg.match MULTI_FLAG
356      result.push <span class="hljs-string">'-'</span> + l <span class="hljs-keyword">for</span> l <span class="hljs-keyword">in</span> match[<span class="hljs-number">1</span>].split <span class="hljs-string">''</span>
357    <span class="hljs-keyword">else</span>
358      result.push arg
359  result</pre></div></div>
360            
361        </li>
362        
363    </ul>
364  </div>
365</body>
366</html>