/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. 

  2. 

  3. <html>
    4. 

  4. <head>
    5. 

  5.   <title>optparse.coffee</title>
    6. 

  6.   <meta http-equiv="content-type" content="text/html; charset=UTF-8">
    7. 

  7.   <meta name="viewport" content="width=device-width, target-densitydpi=160dpi, initial-scale=1.0; maximum-scale=1.0; user-scalable=0;">
    8. 

  8.   <link rel="stylesheet" media="all" href="docco.css" />
    9. 

  9. </head>
    10. 

  10. <body>
    11. 

  11.   <div id="container">
    12. 

  12.     <div id="background"></div>
    13. 

  13.     
    14. 

  14.       <ul id="jump_to">
    15. 

  15.         <li>
    16. 

  16.           <a class="large" href="javascript:void(0);">Jump To &hellip;</a>
    17. 

  17.           <a class="small" href="javascript:void(0);">+</a>
    18. 

  18.           <div id="jump_wrapper">
    19. 

  19.           <div id="jump_page_wrapper">
    20. 

  20.             <div id="jump_page">
    21. 

  21.               
    22. 

  22.                 
    23. 

  23.                 <a class="source" href="browser.html">
    24. 

  24.                   browser.coffee
    25. 

  25.                 </a>
    26. 

  26.               
    27. 

  27.                 
    28. 

  28.                 <a class="source" href="cake.html">
    29. 

  29.                   cake.coffee
    30. 

  30.                 </a>
    31. 

  31.               
    32. 

  32.                 
    33. 

  33.                 <a class="source" href="coffee-script.html">
    34. 

  34.                   coffee-script.coffee
    35. 

  35.                 </a>
    36. 

  36.               
    37. 

  37.                 
    38. 

  38.                 <a class="source" href="command.html">
    39. 

  39.                   command.coffee
    40. 

  40.                 </a>
    41. 

  41.               
    42. 

  42.                 
    43. 

  43.                 <a class="source" href="grammar.html">
    44. 

  44.                   grammar.coffee
    45. 

  45.                 </a>
    46. 

  46.               
    47. 

  47.                 
    48. 

  48.                 <a class="source" href="helpers.html">
    49. 

  49.                   helpers.coffee
    50. 

  50.                 </a>
    51. 

  51.               
    52. 

  52.                 
    53. 

  53.                 <a class="source" href="index.html">
    54. 

  54.                   index.coffee
    55. 

  55.                 </a>
    56. 

  56.               
    57. 

  57.                 
    58. 

  58.                 <a class="source" href="lexer.html">
    59. 

  59.                   lexer.coffee
    60. 

  60.                 </a>
    61. 

  61.               
    62. 

  62.                 
    63. 

  63.                 <a class="source" href="nodes.html">
    64. 

  64.                   nodes.coffee
    65. 

  65.                 </a>
    66. 

  66.               
    67. 

  67.                 
    68. 

  68.                 <a class="source" href="optparse.html">
    69. 

  69.                   optparse.coffee
    70. 

  70.                 </a>
    71. 

  71.               
    72. 

  72.                 
    73. 

  73.                 <a class="source" href="register.html">
    74. 

  74.                   register.coffee
    75. 

  75.                 </a>
    76. 

  76.               
    77. 

  77.                 
    78. 

  78.                 <a class="source" href="repl.html">
    79. 

  79.                   repl.coffee
    80. 

  80.                 </a>
    81. 

  81.               
    82. 

  82.                 
    83. 

  83.                 <a class="source" href="rewriter.html">
    84. 

  84.                   rewriter.coffee
    85. 

  85.                 </a>
    86. 

  86.               
    87. 

  87.                 
    88. 

  88.                 <a class="source" href="scope.html">
    89. 

  89.                   scope.litcoffee
    90. 

  90.                 </a>
    91. 

  91.               
    92. 

  92.                 
    93. 

  93.                 <a class="source" href="sourcemap.html">
    94. 

  94.                   sourcemap.litcoffee
    95. 

  95.                 </a>
    96. 

  96.               
    97. 

  97.             </div>
    98. 

  98.           </div>
    99. 

  99.         </li>
    100. 

  100.       </ul>
    101. 

  101.     
    102. 

  102.     <ul class="sections">
    103. 

  103.         
    104. 

  104.           <li id="title">
    105. 

  105.               <div class="annotation">
    106. 

  106.                   <h1>optparse.coffee</h1>
    107. 

  107.               </div>
    108. 

  108.           </li>
    109. 

  109.         
    110. 

  110.         
    111. 

  111.         
    112. 

  112.         <li id="section-1">
    113. 

  113.             <div class="annotation">
    114. 

  114.               
    115. 

  115.               <div class="pilwrap ">
    116. 

  116.                 <a class="pilcrow" href="#section-1">&#182;</a>
    117. 

  117.               </div>
    118. 

  118.               
    119. 

  119.             </div>
    120. 

  120.             
    121. 

  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. 

  122.             
    123. 

  123.         </li>
    124. 

  124.         
    125. 

  125.         
    126. 

  126.         <li id="section-2">
    127. 

  127.             <div class="annotation">
    128. 

  128.               
    129. 

  129.               <div class="pilwrap ">
    130. 

  130.                 <a class="pilcrow" href="#section-2">&#182;</a>
    131. 

  131.               </div>
    132. 

  132.               <p>A simple <strong>OptionParser</strong> class to parse option flags from the command-line.
    133. 

  133. Use it like so:</p>
    134. 

  134. <pre><code>parser  = <span class="hljs-keyword">new</span> OptionParser switches, helpBanner
    135. 

  135. options = parser.parse process.argv
    136. 

  136. </code></pre><p>The first non-option is considered to be the start of the file (and file
    137. 

  137. option) list, and all subsequent arguments are left unparsed.</p>
    138. 

  138. 

  139.             </div>
    140. 

  140.             
    141. 

  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. 

  142.             
    143. 

  143.         </li>
    144. 

  144.         
    145. 

  145.         
    146. 

  146.         <li id="section-3">
    147. 

  147.             <div class="annotation">
    148. 

  148.               
    149. 

  149.               <div class="pilwrap ">
    150. 

  150.                 <a class="pilcrow" href="#section-3">&#182;</a>
    151. 

  151.               </div>
    152. 

  152.               <p>Initialize with a list of valid options, in the form:</p>
    153. 

  153. <pre><code>[short-flag, long-flag, description]
    154. 

  154. </code></pre><p>Along with an an optional banner for the usage help.</p>
    155. 

  155. 

  156.             </div>
    157. 

  157.             
    158. 

  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. 

  159.     <span class="hljs-property">@rules</span> = buildRules rules</pre></div></div>
    160. 

  160.             
    161. 

  161.         </li>
    162. 

  162.         
    163. 

  163.         
    164. 

  164.         <li id="section-4">
    165. 

  165.             <div class="annotation">
    166. 

  166.               
    167. 

  167.               <div class="pilwrap ">
    168. 

  168.                 <a class="pilcrow" href="#section-4">&#182;</a>
    169. 

  169.               </div>
    170. 

  170.               <p>Parse the list of arguments, populating an <code>options</code> object with all of the
    171. 

  171. specified options, and return it. Options after the first non-option
    172. 

  172. argument are treated as arguments. <code>options.arguments</code> will be an array
    173. 

  173. containing the remaining arguments. This is a simpler API than many option
    174. 

  174. parsers that allow you to attach callback actions for every flag. Instead,
    175. 

  175. you’re responsible for interpreting the options object.</p>
    176. 

  176. 

  177.             </div>
    178. 

  178.             
    179. 

  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. 

  180.     options = <span class="hljs-attribute">arguments</span>: []
    181. 

  181.     skippingArgument = <span class="hljs-literal">no</span>
    182. 

  182.     originalArgs = args
    183. 

  183.     args = normalizeArguments args
    184. 

  184.     <span class="hljs-keyword">for</span> arg, i <span class="hljs-keyword">in</span> args
    185. 

  185.       <span class="hljs-keyword">if</span> skippingArgument
    186. 

  186.         skippingArgument = <span class="hljs-literal">no</span>
    187. 

  187.         <span class="hljs-keyword">continue</span>
    188. 

  188.       <span class="hljs-keyword">if</span> arg <span class="hljs-keyword">is</span> <span class="hljs-string">'--'</span>
    189. 

  189.         pos = originalArgs.indexOf <span class="hljs-string">'--'</span>
    190. 

  190.         options.arguments = options.arguments.concat originalArgs[(pos + <span class="hljs-number">1</span>)..]
    191. 

  191.         <span class="hljs-keyword">break</span>
    192. 

  192.       isOption = !!(arg.match(LONG_FLAG) <span class="hljs-keyword">or</span> arg.match(SHORT_FLAG))</pre></div></div>
    193. 

  193.             
    194. 

  194.         </li>
    195. 

  195.         
    196. 

  196.         
    197. 

  197.         <li id="section-5">
    198. 

  198.             <div class="annotation">
    199. 

  199.               
    200. 

  200.               <div class="pilwrap ">
    201. 

  201.                 <a class="pilcrow" href="#section-5">&#182;</a>
    202. 

  202.               </div>
    203. 

  203.               <p>the CS option parser is a little odd; options after the first
    204. 

  204. non-option argument are treated as non-option arguments themselves</p>
    205. 

  205. 

  206.             </div>
    207. 

  207.             
    208. 

  208.             <div class="content"><div class='highlight'><pre>      seenNonOptionArg = options.arguments.length &gt; <span class="hljs-number">0</span>
    209. 

  209.       <span class="hljs-keyword">unless</span> seenNonOptionArg
    210. 

  210.         matchedRule = <span class="hljs-literal">no</span>
    211. 

  211.         <span class="hljs-keyword">for</span> rule <span class="hljs-keyword">in</span> <span class="hljs-property">@rules</span>
    212. 

  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. 

  213.             value = <span class="hljs-literal">true</span>
    214. 

  214.             <span class="hljs-keyword">if</span> rule.hasArgument
    215. 

  215.               skippingArgument = <span class="hljs-literal">yes</span>
    216. 

  216.               value = args[i + <span class="hljs-number">1</span>]
    217. 

  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. 

  218.             matchedRule = <span class="hljs-literal">yes</span>
    219. 

  219.             <span class="hljs-keyword">break</span>
    220. 

  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. 

  221.       <span class="hljs-keyword">if</span> seenNonOptionArg <span class="hljs-keyword">or</span> <span class="hljs-keyword">not</span> isOption
    222. 

  222.         options.arguments.push arg
    223. 

  223.     options</pre></div></div>
    224. 

  224.             
    225. 

  225.         </li>
    226. 

  226.         
    227. 

  227.         
    228. 

  228.         <li id="section-6">
    229. 

  229.             <div class="annotation">
    230. 

  230.               
    231. 

  231.               <div class="pilwrap ">
    232. 

  232.                 <a class="pilcrow" href="#section-6">&#182;</a>
    233. 

  233.               </div>
    234. 

  234.               <p>Return the help text for this <strong>OptionParser</strong>, listing and describing all
    235. 

  235. of the valid options, for <code>--help</code> and such.</p>
    236. 

  236. 

  237.             </div>
    238. 

  238.             
    239. 

  239.             <div class="content"><div class='highlight'><pre>  <span class="hljs-attribute">help</span>:<span class="hljs-function"> -&gt;</span>
    240. 

  240.     lines = []
    241. 

  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. 

  242.     <span class="hljs-keyword">for</span> rule <span class="hljs-keyword">in</span> <span class="hljs-property">@rules</span>
    243. 

  243.       spaces  = <span class="hljs-number">15</span> - rule.longFlag.length
    244. 

  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. 

  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. 

  246.       lines.push <span class="hljs-string">'  '</span> + letPart + rule.longFlag + spaces + rule.description
    247. 

  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. 

  248.             
    249. 

  249.         </li>
    250. 

  250.         
    251. 

  251.         
    252. 

  252.         <li id="section-7">
    253. 

  253.             <div class="annotation">
    254. 

  254.               
    255. 

  255.               <div class="pilwrap ">
    256. 

  256.                 <a class="pilcrow" href="#section-7">&#182;</a>
    257. 

  257.               </div>
    258. 

  258.               <h2 id="helpers">Helpers</h2>
    259. 

  259. 

  260.             </div>
    261. 

  261.             
    262. 

  262.         </li>
    263. 

  263.         
    264. 

  264.         
    265. 

  265.         <li id="section-8">
    266. 

  266.             <div class="annotation">
    267. 

  267.               
    268. 

  268.               <div class="pilwrap ">
    269. 

  269.                 <a class="pilcrow" href="#section-8">&#182;</a>
    270. 

  270.               </div>
    271. 

  271.               
    272. 

  272.             </div>
    273. 

  273.             
    274. 

  274.         </li>
    275. 

  275.         
    276. 

  276.         
    277. 

  277.         <li id="section-9">
    278. 

  278.             <div class="annotation">
    279. 

  279.               
    280. 

  280.               <div class="pilwrap ">
    281. 

  281.                 <a class="pilcrow" href="#section-9">&#182;</a>
    282. 

  282.               </div>
    283. 

  283.               <p>Regex matchers for option flags.</p>
    284. 

  284. 

  285.             </div>
    286. 

  286.             
    287. 

  287.             <div class="content"><div class='highlight'><pre>LONG_FLAG  = <span class="hljs-regexp">/^(--\w[\w\-]*)/</span>
    288. 

  288. SHORT_FLAG = <span class="hljs-regexp">/^(-\w)$/</span>
    289. 

  289. MULTI_FLAG = <span class="hljs-regexp">/^-(\w{2,})/</span>
    290. 

  290. OPTIONAL   = <span class="hljs-regexp">/\[(\w+(\*?))\]/</span></pre></div></div>
    291. 

  291.             
    292. 

  292.         </li>
    293. 

  293.         
    294. 

  294.         
    295. 

  295.         <li id="section-10">
    296. 

  296.             <div class="annotation">
    297. 

  297.               
    298. 

  298.               <div class="pilwrap ">
    299. 

  299.                 <a class="pilcrow" href="#section-10">&#182;</a>
    300. 

  300.               </div>
    301. 

  301.               <p>Build and return the list of option rules. If the optional <em>short-flag</em> is
    302. 

  302. unspecified, leave it out by padding with <code>null</code>.</p>
    303. 

  303. 

  304.             </div>
    305. 

  305.             
    306. 

  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. 

  307.   <span class="hljs-keyword">for</span> tuple <span class="hljs-keyword">in</span> rules
    308. 

  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. 

  309.     buildRule tuple...</pre></div></div>
    310. 

  310.             
    311. 

  311.         </li>
    312. 

  312.         
    313. 

  313.         
    314. 

  314.         <li id="section-11">
    315. 

  315.             <div class="annotation">
    316. 

  316.               
    317. 

  317.               <div class="pilwrap ">
    318. 

  318.                 <a class="pilcrow" href="#section-11">&#182;</a>
    319. 

  319.               </div>
    320. 

  320.               <p>Build a rule from a <code>-o</code> short flag, a <code>--output [DIR]</code> long flag, and the
    321. 

  321. description of what the option does.</p>
    322. 

  322. 

  323.             </div>
    324. 

  324.             
    325. 

  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. 

  326.   match     = longFlag.match(OPTIONAL)
    327. 

  327.   longFlag  = longFlag.match(LONG_FLAG)[<span class="hljs-number">1</span>]
    328. 

  328.   {
    329. 

  329.     <span class="hljs-attribute">name</span>:         longFlag.substr <span class="hljs-number">2</span>
    330. 

  330.     <span class="hljs-attribute">shortFlag</span>:    shortFlag
    331. 

  331.     <span class="hljs-attribute">longFlag</span>:     longFlag
    332. 

  332.     <span class="hljs-attribute">description</span>:  description
    333. 

  333.     <span class="hljs-attribute">hasArgument</span>:  !!(match <span class="hljs-keyword">and</span> match[<span class="hljs-number">1</span>])
    334. 

  334.     <span class="hljs-attribute">isList</span>:       !!(match <span class="hljs-keyword">and</span> match[<span class="hljs-number">2</span>])
    335. 

  335.   }</pre></div></div>
    336. 

  336.             
    337. 

  337.         </li>
    338. 

  338.         
    339. 

  339.         
    340. 

  340.         <li id="section-12">
    341. 

  341.             <div class="annotation">
    342. 

  342.               
    343. 

  343.               <div class="pilwrap ">
    344. 

  344.                 <a class="pilcrow" href="#section-12">&#182;</a>
    345. 

  345.               </div>
    346. 

  346.               <p>Normalize arguments by expanding merged flags into multiple flags. This allows
    347. 

  347. you to have <code>-wl</code> be the same as <code>--watch --lint</code>.</p>
    348. 

  348. 

  349.             </div>
    350. 

  350.             
    351. 

  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. 

  352.   args = args[..]
    353. 

  353.   result = []
    354. 

  354.   <span class="hljs-keyword">for</span> arg <span class="hljs-keyword">in</span> args
    355. 

  355.     <span class="hljs-keyword">if</span> match = arg.match MULTI_FLAG
    356. 

  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. 

  357.     <span class="hljs-keyword">else</span>
    358. 

  358.       result.push arg
    359. 

  359.   result</pre></div></div>
    360. 

  360.             
    361. 

  361.         </li>
    362. 

  362.         
    363. 

  363.     </ul>
    364. 

  364.   </div>
    365. 

  365. </body>
    366. 

  366. </html>
    367.