/documentation/docs/optparse.html
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 …</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">¶</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">¶</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">¶</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> -></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">¶</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> -></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">¶</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 > <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">¶</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"> -></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 > <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">¶</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">¶</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">¶</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">¶</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> -></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 < <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">¶</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> -></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">¶</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> -></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>