como 0.1.2 → 0.1.3

data/doc/Como.html

@@ -79,7 +79,9 @@
   
   
     <dt class="r1 last">Defined in:</dt>
-    <dd class="r1 last">lib/como.rb</dd>
+    <dd class="r1 last">lib/como.rb<span class="defines">,<br />
+  lib/version.rb</span>
+</dd>
   
 </dl>
 <div class="clear"></div>
@@ -87,9 +89,9 @@
 <h2>Overview</h2><div class="docstring">
   <div class="discussion">
     
-<h1>Como</h1>
+<p>Como</p>
 
-<h2>Introduction</h2>
+<h1>Introduction</h1>
 
 <p>Como provides low manifest command line option parsing and deployment. The
 command line options are described in compact table format and option
@@ -98,18 +100,18 @@ usage information based on the option table (+ generic program info) and
 displays it automatically if necessary. Como supports also subcommands and
 checking for option combinations using a simple DSL.</p>
 
-<h2>Usage Examples</h2>
+<h1>Usage Examples</h1>
 
 <p>Two simple examples are presented in this section. First one includes a
 straight forward command definition and the second is a bit more
 complicated with subcommand feature in use.</p>
 
-<h3>Simple example</h3>
+<h2>Simple example</h2>
 
 <p>Below is a small example program ("como_simple") that demonstrates typical
 usage.</p>
 
-<h4>Program listing</h4>
+<h3>Program listing</h3>
 
 <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>como</span><span class='tstring_end'>&quot;</span></span>
 <span class='id identifier rubyid_include'>include</span> <span class='const'>Como</span>
@@ -178,7 +180,7 @@ replaced with "nil", the long option format is only available.</p>
 ("-h") option is given. Help option is added to the command automatically
 as default behavior.</p>
 
-<h4>Simple example executions</h4>
+<h3>Simple example executions</h3>
 
 <p>Normal behavior would be achieved by executing:</p>
 
@@ -206,8 +208,7 @@ checked for existence and error is displayed if arguments are not given.</p>
 
 <pre class="code ruby"><code class="ruby">como_simple error: Option &quot;-f&quot; missing for &quot;como_simple&quot;...
 
-  Usage:
-    como_simple -f &lt;file&gt; [-d]
+  como_simple -f &lt;file&gt; [-d]
 
   -f          File argument.
   -d          Enable debugging.
@@ -224,19 +225,19 @@ string is taken from the option specification to "usage" display.</p>
 
 <p>would display the same "usage" screen except without the error line.</p>
 
-<h3>Subcommand example</h3>
+<h2>Subcommand example</h2>
 
 <p>Subcmd example includes a program which has subcommands. Subcommands can
 have their own command line switches and options.</p>
 
-<h4>Program listing</h4>
+<h3>Program listing</h3>
 
 <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>como</span><span class='tstring_end'>&quot;</span></span>
 <span class='id identifier rubyid_include'>include</span> <span class='const'>Como</span>
 
 <span class='const'>Spec</span><span class='period'>.</span><span class='id identifier rubyid_program'>program</span><span class='lparen'>(</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Programmer</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>2013</span><span class='tstring_end'>&quot;</span></span> <span class='rparen'>)</span> <span class='kw'>do</span>
 
-    <span class='id identifier rubyid_subcmd'>subcmd</span><span class='lparen'>(</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>como_subcmd</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='lbracket'>[</span>
+    <span class='id identifier rubyid_command'>command</span><span class='lparen'>(</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>como_subcmd</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='lbracket'>[</span>
        <span class='lbracket'>[</span> <span class='symbol'>:subcmd</span><span class='comma'>,</span>      <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>add</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>       <span class='kw'>nil</span><span class='comma'>,</span>  <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Add file.</span><span class='tstring_end'>&quot;</span></span> <span class='rbracket'>]</span><span class='comma'>,</span>
        <span class='lbracket'>[</span> <span class='symbol'>:subcmd</span><span class='comma'>,</span>      <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>rm</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>        <span class='kw'>nil</span><span class='comma'>,</span>  <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Remove file.</span><span class='tstring_end'>&quot;</span></span> <span class='rbracket'>]</span><span class='comma'>,</span>
       <span class='rbracket'>]</span><span class='comma'>,</span> <span class='rparen'>)</span>
@@ -248,7 +249,7 @@ have their own command line switches and options.</p>
        <span class='lbracket'>[</span> <span class='symbol'>:single</span><span class='comma'>,</span>      <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>file</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>      <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>-f</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>  <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>File.</span><span class='tstring_end'>&quot;</span></span> <span class='rbracket'>]</span><span class='comma'>,</span>
       <span class='rbracket'>]</span> <span class='rparen'>)</span>
 
-    <span class='id identifier rubyid_checkRule'>checkRule</span> <span class='kw'>do</span>
+    <span class='id identifier rubyid_check'>check</span> <span class='kw'>do</span>
         <span class='id identifier rubyid_one'>one</span><span class='lparen'>(</span>
             <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>-fo</span><span class='tstring_end'>'</span></span><span class='comma'>,</span>
             <span class='id identifier rubyid_all'>all</span><span class='lparen'>(</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>password</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>username</span><span class='tstring_end'>'</span></span> <span class='rparen'>)</span>
@@ -272,17 +273,18 @@ have their own command line switches and options.</p>
 author and date are provided as parameters, and the program and subcommand
 options are defined in block.</p>
 
-<p>The first "subcmd" method call defines the main command ("Opt.main") which
-represents the program. It has two "subcmd" options.</p>
+<p>The first "command" (or "subcmd") method call defines the main command
+("Opt.main") which represents the program. It has two "subcmd" options
+("add" and "rm").</p>
 
 <p>The rest of the "subcmd" methods define subcommands for the parent command.
 This example includes one subcommand level, but multiple levels are
 allowed.</p>
 
-<p>The "checkRule" method defines option combination (RuleCheck) for the
-previous subcommand definition. In this case the definition allows "add" to
-have either the "-fo" option defined or "password" and "username" in
-combination.</p>
+<p>The "check" (or "checkRule") method defines option combination
+(<span class='object_link'><a href="Como/RuleCheck.html" title="Como::RuleCheck (class)">RuleCheck</a></span>) for the previous subcommand definition. In this case the
+definition allows "add" to have either the "-fo" option defined or
+"password" and "username" in combination.</p>
 
 <p>Main (root) commands can be referenced through</p>
 
@@ -304,7 +306,7 @@ combination.</p>
 <p>The given subcommand can be accessed with "givenSubcmd" method from each
 parent command.</p>
 
-<h4>Subcommand example executions</h4>
+<h3>Subcommand example executions</h3>
 
 <p>Normal behavior would be achieved by executing:</p>
 
@@ -338,8 +340,8 @@ Thus executing:</p>
     |     |     |--&lt;password&gt;
     |     |     |--&lt;username&gt;</code></pre>
 
-<p>Since the combination rule requires either "-fo" or both "password" and
-"username" in a pair.</p>
+<p>since the combination rule requires either "-fo", or both "password" and
+"username".</p>
 
 <p>Help is automatically provided on each command level, thus these are both
 valid.</p>
@@ -350,9 +352,9 @@ valid.</p>
 
 <pre class="code ruby"><code class="ruby">shell&gt; como_subcmd rm -h</code></pre>
 
-<h2>Option specification</h2>
+<h1>Option specification</h1>
 
-<h3>Overview</h3>
+<h2>Overview</h2>
 
 <p>Option specification includes the minimum set of information required for
 command line parsing. It is used to:</p>
@@ -370,7 +372,7 @@ command line parsing. It is used to:</p>
 <p>Generate Usage Help printout.</p>
 </li></ul>
 
-<h3>Option types</h3>
+<h2>Option types</h2>
 
 <p>The following types can be defined for the command line options:</p>
 <dl class="rdoc-list"><dt>:subcmd</dt>
@@ -428,7 +430,7 @@ can be used to terminate the argument list. For example:</p>
 
 <pre class="code ruby"><code class="ruby">[ :silent, &quot;terminator&quot;, &quot;-&quot;, &quot;The terminator.&quot; ],</code></pre>
 
-<h3>Option specification method configuration</h3>
+<h2>Option specification method configuration</h2>
 
 <p>Option behavior can be controlled with several configuration options.</p>
 
@@ -468,11 +470,14 @@ provided and it can be made also visible to user.</p>
 </dd><dt>:help_exit</dt>
 <dd>
 <p>Exit program if help displayed (default: true).</p>
+</dd><dt>:copyright</dt>
+<dd>
+<p>Display copyright/author in usage printout (default: true).</p>
 </dd></dl>
 
-<h2>Option referencing</h2>
+<h1>Option referencing</h1>
 
-<h3>Existence and values</h3>
+<h2>Existence and values</h2>
 
 <p>Opt class includes the parsed option values. All options can be tested
 whether they are specified on the command line using:</p>
@@ -516,7 +521,7 @@ Thus</p>
 
 <p>And finally decide what to do.</p>
 
-<h3>Options including parameters</h3>
+<h2>Options including parameters</h2>
 
 <p>Sometimes it is convenient for the program to use an option to include
 multiple parameter settings. These settings can be parsed and mapped to a
@@ -533,7 +538,7 @@ example with option:</p>
 
 <pre class="code ruby"><code class="ruby"><span class='lbrace'>{</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>rounds</span><span class='tstring_end'>'</span></span> <span class='op'>=&gt;</span> <span class='int'>10</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>length</span><span class='tstring_end'>'</span></span> <span class='op'>=&gt;</span> <span class='int'>5</span> <span class='rbrace'>}</span></code></pre>
 
-<h3>Subcommand options</h3>
+<h2>Subcommand options</h2>
 
 <p>The given subcommand for the parent command is return by "givenSubcmd".
 Commonly the program creator should just check directly which subcommand
@@ -542,12 +547,12 @@ has been selected and check for any subcommand options set. For example:</p>
 <pre class="code ruby"><code class="ruby">if Opt['como_subcmd']['add'].given
    ...</code></pre>
 
-<h3>Program external options</h3>
+<h2>Program external options</h2>
 
 <p>If the user gives the "--" option (double-dash), the arguments after that
-option is returned as an Array with "Opt.external".</p>
+option are returned as an Array with "Opt.external".</p>
 
-<h2>Option combination checks</h2>
+<h1>Option combination checks</h1>
 
 <p>Como provides a facility to create relations between options using
 RuleCheck DSL. This is needed since sometimes options have to be used in
@@ -583,11 +588,52 @@ exclusive.</p>
 
 <p>Examples can be found above.</p>
 
-<h2>Customization</h2>
+<h1>Customization</h1>
+
+<p>A user specific customization file can be referenced through the "COMO"
+environment variable. If environment variable "COMO" is defined, the
+referenced file is read in as Ruby file as a last phase when Como is loaded
+from the program (require). Proposed naming convention for the
+customization is:</p>
+
+<pre class="code ruby"><code class="ruby">$HOME/.como</code></pre>
+
+<p>User can define a pre and a post action hook in the file.</p>
+
+<p>The pre-hook can be used for example to change the Como config defaults. It
+is run before the body of "Spec.command" or "Spec.program" is executed. It
+is passed all the parameters that has been passed to "Spec.command" or
+"Spec.program", only collected into a Hash. The Hash keys are method
+parameter names as symbols.</p>
+
+<p>Example:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='comment'># Define pre parser hook for Como.
+</span><span class='const'>Como</span><span class='period'>.</span><span class='id identifier rubyid_preHook'>preHook</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_args'>args</span><span class='op'>|</span>
+
+    <span class='comment'># Get default config for options.
+</span>    <span class='id identifier rubyid_config'>config</span> <span class='op'>=</span> <span class='const'>Como</span><span class='op'>::</span><span class='const'>Opt</span><span class='period'>.</span><span class='id identifier rubyid_configGet'>configGet</span>
+
+    <span class='comment'># Disable 'copyright' lines from usage.
+</span>    <span class='id identifier rubyid_config'>config</span><span class='lbracket'>[</span> <span class='symbol'>:copyright</span> <span class='rbracket'>]</span> <span class='op'>=</span> <span class='kw'>false</span>
+
+    <span class='comment'># Test if &quot;Spec.command&quot; is the entry method (it has arg named &quot;prog&quot;).
+</span>    <span class='kw'>if</span> <span class='id identifier rubyid_args'>args</span><span class='lbracket'>[</span> <span class='symbol'>:prog</span> <span class='rbracket'>]</span>
+        <span class='comment'># Place a custom header for all programs.
+</span>        <span class='id identifier rubyid_config'>config</span><span class='lbracket'>[</span> <span class='symbol'>:header</span> <span class='rbracket'>]</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>\nProgram \&quot;</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_args'>args</span><span class='lbracket'>[</span> <span class='symbol'>:prog</span> <span class='rbracket'>]</span><span class='rbrace'>}</span><span class='tstring_content'>\&quot; is ...\n\n</span><span class='tstring_end'>&quot;</span></span>
+    <span class='kw'>end</span>
+<span class='kw'>end</span></code></pre>
+
+<p>There is no predefined use cases for post-hook. Post-hook is passed the
+Opt.main as parameter.</p>
+
+<p>If the provided customization facilities are not satisfactory, changes can
+be implemented simply by overloading the existing functions. Some knowledge
+of the internal workings of Como is required though.</p>
 
-<p>If the default behavior is not satisfactory, changes can be implemented
-simply by overloading the existing functions. Some knowledge of the
-internal workings of Como is required though.</p>
+<p>Como version is returned with:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='const'>Como</span><span class='period'>.</span><span class='id identifier rubyid_version'>version</span></code></pre>
 
 
   </div>
@@ -612,12 +658,211 @@ internal workings of Como is required though.</p>
 
 
 
+  
+    <h2>
+      Class Method Summary
+      <small>(<a href="#" class="summary_toggle">collapse</a>)</small>
+    </h2>
+
+    <ul class="summary">
+      
+        <li class="public ">
+  <span class="summary_signature">
+    
+      <a href="#postHook-class_method" title="postHook (class method)">+ (Object) <strong>postHook</strong>(&amp;code) </a>
+    
+
+    
+  </span>
+  
+  
+  
+  
+  
+  
+  
 
+  
+    <span class="summary_desc"><div class='inline'>
+<p>Set "postHook" routine.</p>
+</div></span>
+  
+</li>
+
+      
+        <li class="public ">
+  <span class="summary_signature">
+    
+      <a href="#preHook-class_method" title="preHook (class method)">+ (Object) <strong>preHook</strong>(&amp;code) </a>
+    
+
+    
+  </span>
+  
+  
+  
+  
+  
+  
+  
+
+  
+    <span class="summary_desc"><div class='inline'>
+<p>Set "preHook" routine.</p>
+</div></span>
+  
+</li>
+
+      
+        <li class="public ">
+  <span class="summary_signature">
+    
+      <a href="#version-class_method" title="version (class method)">+ (Object) <strong>version</strong> </a>
+    
+
+    
+  </span>
+  
+  
+  
+  
+  
+  
+  
+
+  
+    <span class="summary_desc"><div class='inline'></div></span>
+  
+</li>
+
+      
+    </ul>
+  
+
+
+
+  <div id="class_method_details" class="method_details_list">
+    <h2>Class Method Details</h2>
+
+    
+      <div class="method_details first">
+  <h3 class="signature first" id="postHook-class_method">
+  
+    + (<tt>Object</tt>) <strong>postHook</strong>(&amp;code) 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    
+<p>Set "postHook" routine.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+
+</div><table class="source_code">
+  <tr>
+    <td>
+      <pre class="lines">
+
+
+502
+503
+504</pre>
+    </td>
+    <td>
+      <pre class="code"><span class="info file"># File 'lib/como.rb', line 502</span>
+
+<span class='kw'>def</span> <span class='const'>Como</span><span class='period'>.</span><span class='id identifier rubyid_postHook'>postHook</span><span class='lparen'>(</span> <span class='op'>&amp;</span><span class='id identifier rubyid_code'>code</span> <span class='rparen'>)</span>
+    <span class='const'>ComoCommon</span><span class='period'>.</span><span class='id identifier rubyid_setHook'>setHook</span><span class='lparen'>(</span> <span class='symbol'>:postHook</span><span class='comma'>,</span> <span class='op'>&amp;</span><span class='id identifier rubyid_code'>code</span> <span class='rparen'>)</span>
+<span class='kw'>end</span></pre>
+    </td>
+  </tr>
+</table>
+</div>
+    
+      <div class="method_details ">
+  <h3 class="signature " id="preHook-class_method">
+  
+    + (<tt>Object</tt>) <strong>preHook</strong>(&amp;code) 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    
+<p>Set "preHook" routine.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+
+</div><table class="source_code">
+  <tr>
+    <td>
+      <pre class="lines">
+
+
+496
+497
+498</pre>
+    </td>
+    <td>
+      <pre class="code"><span class="info file"># File 'lib/como.rb', line 496</span>
+
+<span class='kw'>def</span> <span class='const'>Como</span><span class='period'>.</span><span class='id identifier rubyid_preHook'>preHook</span><span class='lparen'>(</span> <span class='op'>&amp;</span><span class='id identifier rubyid_code'>code</span> <span class='rparen'>)</span>
+    <span class='const'>ComoCommon</span><span class='period'>.</span><span class='id identifier rubyid_setHook'>setHook</span><span class='lparen'>(</span> <span class='symbol'>:preHook</span><span class='comma'>,</span> <span class='op'>&amp;</span><span class='id identifier rubyid_code'>code</span> <span class='rparen'>)</span>
+<span class='kw'>end</span></pre>
+    </td>
+  </tr>
+</table>
+</div>
+    
+      <div class="method_details ">
+  <h3 class="signature " id="version-class_method">
+  
+    + (<tt>Object</tt>) <strong>version</strong> 
+  
+
+  
+
+  
+</h3><table class="source_code">
+  <tr>
+    <td>
+      <pre class="lines">
+
+
+3
+4
+5</pre>
+    </td>
+    <td>
+      <pre class="code"><span class="info file"># File 'lib/version.rb', line 3</span>
+
+<span class='kw'>def</span> <span class='const'>Como</span><span class='period'>.</span><span class='id identifier rubyid_version'>version</span>
+    <span class='const'>ComoCommon</span><span class='op'>::</span><span class='const'>VERSION</span>
+<span class='kw'>end</span></pre>
+    </td>
+  </tr>
+</table>
+</div>
+    
+  </div>
 
 </div>
 
     <div id="footer">
-  Generated on Wed Apr 23 19:33:20 2014 by
+  Generated on Wed Jul  9 14:02:42 2014 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.8.6.1 (ruby-1.9.3).
 </div>

data/doc/_index.html

@@ -233,7 +233,7 @@
 </div>
 
     <div id="footer">
-  Generated on Wed Apr 23 19:33:20 2014 by
+  Generated on Wed Jul  9 14:02:42 2014 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.8.6.1 (ruby-1.9.3).
 </div>

data/doc/file.CHANGELOG.html

@@ -63,7 +63,13 @@
 
     <div id="content"><div id='filecontents'>
 <h1>Version history</h1>
-<dl class="rdoc-list"><dt>0.1.2</dt>
+<dl class="rdoc-list"><dt>0.1.3</dt>
+<dd>
+<p>Customization through COMO env variable and hooks. Version information
+returned programmatically with Como.version. "command" is aliased to
+"subcmd" to enable highlighting of the main command. Aliases for
+"Spec.checkRule" and "Spec#checkRule".</p>
+</dd><dt>0.1.2</dt>
 <dd>
 <p>":check_invalid" applied correctly. Header and footer configs has to
 include all newlines explicitly. ":error_exit" config removed (always exit
@@ -92,7 +98,7 @@ settings, i.e. the Opt#params method added.</p>
 </div></div>
 
     <div id="footer">
-  Generated on Wed Apr 23 19:33:20 2014 by
+  Generated on Wed Jul  9 14:02:42 2014 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.8.6.1 (ruby-1.9.3).
 </div>

data/doc/file.README.html

@@ -85,7 +85,7 @@ used.</p>
 </div></div>
 
     <div id="footer">
-  Generated on Wed Apr 23 19:33:20 2014 by
+  Generated on Wed Jul  9 14:02:42 2014 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.8.6.1 (ruby-1.9.3).
 </div>

data/doc/index.html

@@ -85,7 +85,7 @@ used.</p>
 </div></div>
 
     <div id="footer">
-  Generated on Wed Apr 23 19:33:20 2014 by
+  Generated on Wed Jul  9 14:02:42 2014 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.8.6.1 (ruby-1.9.3).
 </div>