contents/glyph/book/extending/command.html
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 |
----- title: "Glyph - Defining Custom Commands" content-type: page ----- <nav class="navigation"><a href="/glyph/book/extending/output_format.html">← Custom Output Formats</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/troubleshooting/errors_generic.html">Generic Errors →</a></nav> <p>Glyph relies on <a href="http://davetron5000.github.com/gli/"><span class="caps">GLI</span></a> for defining commands. This useful library provides a high-level framework for creating command-line interface similar to <a href="http://git-scm.com/">Git</a>, its <span class="caps">DSL</span> takes care of pretty much everything, from managing command line arguments and options to providing an interactive help system.</p> <section class="section"> <header> <h1 id="h_108" class="toc">Creating a 'glyph generate' command</h1> </header> <p>Consider the custom task defined in <a href="/glyph/book/extending/task.html#custom_generate_task">Creating a ‘custom:generate’ task</a>. Creating a custom command to call it is fairly straightforward.</p> <p>First of all, create a <code>lib/commands</code> folder in your project directory. Then, create a <code>.rb</code> file within it, e.g. <code>commands.rake</code>.</p> <p>Finally, here’s the source of the command:</p> <div class="CodeRay"> <div class="code"> <pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span><span class="constant">GLI</span>.desc <span class="string"><span class="delimiter">'</span><span class="content">Generates a specific file required for Glyph releases</span><span class="delimiter">'</span></span> <span class="line-numbers"> <a href="#n2" name="n2">2</a></span>arg_name <span class="string"><span class="delimiter">"</span><span class="content">file_name</span><span class="delimiter">"</span></span> <span class="line-numbers"> <a href="#n3" name="n3">3</a></span>command <span class="symbol">:generate</span> <span class="keyword">do</span> |c| <span class="line-numbers"> <a href="#n4" name="n4">4</a></span> c.action <span class="keyword">do</span> |global_options,options,args| <span class="line-numbers"> <a href="#n5" name="n5">5</a></span> <span class="keyword">if</span> args.blank? <span class="keyword">then</span> <span class="line-numbers"> <a href="#n6" name="n6">6</a></span> raise <span class="constant">RuntimeError</span>, <span class="string"><span class="delimiter">"</span><span class="content">You must specify a file to generate</span><span class="delimiter">"</span></span> <span class="line-numbers"> <a href="#n7" name="n7">7</a></span> <span class="keyword">else</span> <span class="line-numbers"> <a href="#n8" name="n8">8</a></span> <span class="constant">Glyph</span>.run <span class="string"><span class="delimiter">'</span><span class="content">custom:generate</span><span class="delimiter">'</span></span>, args[<span class="integer">0</span>] <span class="line-numbers"> <a href="#n9" name="n9">9</a></span> <span class="keyword">end</span> <span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> <span class="keyword">end</span> <span class="line-numbers"><a href="#n11" name="n11">11</a></span><span class="keyword">end</span></pre> </div> </div> <p>That’s it. If you try to run <code>glyph help</code> within your project directory, notice that there’s a new entry for the generate command:</p> <div class="CodeRay"> <div class="code"> <pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>$ glyph help <span class="line-numbers"> <a href="#n2" name="n2">2</a></span>===================================== <span class="line-numbers"> <a href="#n3" name="n3">3</a></span>Glyph v/0.5.3.1 <span class="line-numbers"> <a href="#n4" name="n4">4</a></span>===================================== <span class="line-numbers"> <a href="#n5" name="n5">5</a></span>usage: glyph command [options] <span class="line-numbers"> <a href="#n6" name="n6">6</a></span> <span class="line-numbers"> <a href="#n7" name="n7">7</a></span>Options: <span class="line-numbers"> <a href="#n8" name="n8">8</a></span> -d, --debug - Enable debugging <span class="line-numbers"> <a href="#n9" name="n9">9</a></span> <span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span>Commands: <span class="line-numbers"><a href="#n11" name="n11">11</a></span> add - Add a new text file to the project <span class="line-numbers"><a href="#n12" name="n12">12</a></span> compile - Compile the project <span class="line-numbers"><a href="#n13" name="n13">13</a></span> config - Get/set configuration settings <span class="line-numbers"><a href="#n14" name="n14">14</a></span> generate - Generates a specific file required for Glyph releases <span class="line-numbers"><a href="#n15" name="n15">15</a></span> help - Shows list of commands or help for one command <span class="line-numbers"><a href="#n16" name="n16">16</a></span> init - Create a new Glyph project <span class="line-numbers"><a href="#n17" name="n17">17</a></span> outline - Display the document outline <span class="line-numbers"><a href="#n18" name="n18">18</a></span> stats - Display statistics <span class="line-numbers"><a href="#n19" name="n19">19</a></span> todo - Display all project TODO items</pre> </div> </div> <p>You can now run the Glyph command as expected:</p> <div class="CodeRay"> <div class="code"> <pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>$ glyph -d generate changelog <span class="line-numbers"><a href="#n2" name="n2">2</a></span>-- Generating CHANGELOG... <span class="line-numbers"><a href="#n3" name="n3">3</a></span>-- Done.</pre> </div> </div> </section> <nav class="navigation"><a href="/glyph/book/extending/output_format.html">← Custom Output Formats</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/troubleshooting/errors_generic.html">Generic Errors →</a></nav> |