como 0.0.2 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. data/CHANGELOG.rdoc +12 -0
  2. data/README.rdoc +11 -5
  3. data/Rakefile +6 -1
  4. data/doc/Como/ArgsParseState.html +912 -0
  5. data/doc/Como/ComoCommon.html +305 -0
  6. data/doc/Como/MainOpt.html +636 -0
  7. data/doc/Como/MasterOpt.html +636 -0
  8. data/doc/Como/Opt/ErrorWithData.html +304 -0
  9. data/doc/Como/Opt/InvalidOption.html +158 -0
  10. data/doc/Como/Opt/MissingArgument.html +158 -0
  11. data/doc/Como/Opt.html +6098 -0
  12. data/doc/Como/RuleCheck.html +933 -0
  13. data/doc/Como/RuleDisplay.html +1193 -0
  14. data/doc/Como/Spec.html +1750 -0
  15. data/doc/Como.html +625 -0
  16. data/doc/_index.html +242 -0
  17. data/doc/class_list.html +53 -0
  18. data/doc/css/common.css +1 -0
  19. data/doc/css/full_list.css +57 -0
  20. data/doc/css/style.css +338 -0
  21. data/doc/file.CHANGELOG.html +90 -0
  22. data/doc/file.README.html +94 -0
  23. data/doc/file.como.html +1962 -0
  24. data/doc/file_list.html +58 -0
  25. data/doc/frames.html +28 -0
  26. data/doc/index.html +94 -0
  27. data/doc/js/app.js +214 -0
  28. data/doc/js/full_list.js +178 -0
  29. data/doc/js/jquery.js +4 -0
  30. data/doc/method_list.html +838 -0
  31. data/doc/top-level-namespace.html +112 -0
  32. data/lib/como.rb +1660 -661
  33. data/test/como_compatible +37 -0
  34. data/test/como_config +44 -0
  35. data/test/como_options +36 -0
  36. data/test/como_queries +44 -0
  37. data/test/como_rule_1 +28 -0
  38. data/test/como_rule_2 +28 -0
  39. data/test/como_subcmd +72 -0
  40. data/test/como_subcmd_config +88 -0
  41. data/test/golden/compatible.txt +438 -0
  42. data/test/golden/config.txt +319 -0
  43. data/test/golden/options.txt +438 -0
  44. data/test/golden/queries.txt +78 -0
  45. data/test/golden/rule_1.txt +454 -0
  46. data/test/golden/rule_2.txt +476 -0
  47. data/test/golden/subcmd.txt +360 -0
  48. data/test/golden/subcmd_config.txt +534 -0
  49. data/test/test_como.rb +22 -328
  50. data/test/test_compatible +28 -0
  51. data/test/test_config +12 -0
  52. data/test/test_options +28 -0
  53. data/test/test_queries +7 -0
  54. data/test/test_rule_1 +27 -0
  55. data/test/test_rule_2 +27 -0
  56. data/test/test_subcmd +30 -0
  57. data/test/test_subcmd_config +31 -0
  58. metadata +62 -6
data/doc/Como.html ADDED
@@ -0,0 +1,625 @@
1
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4
+ <head>
5
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6
+ <title>
7
+ Module: Como
8
+
9
+ &mdash; Documentation by YARD 0.8.6.1
10
+
11
+ </title>
12
+
13
+ <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
14
+
15
+ <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
16
+
17
+ <script type="text/javascript" charset="utf-8">
18
+ hasFrames = window.top.frames.main ? true : false;
19
+ relpath = '';
20
+ framesUrl = "frames.html#!" + escape(window.location.href);
21
+ </script>
22
+
23
+
24
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
25
+
26
+ <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
27
+
28
+
29
+ </head>
30
+ <body>
31
+ <div id="header">
32
+ <div id="menu">
33
+
34
+ <a href="_index.html">Index (C)</a> &raquo;
35
+
36
+
37
+ <span class="title">Como</span>
38
+
39
+
40
+ <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
41
+ </div>
42
+
43
+ <div id="search">
44
+
45
+ <a class="full_list_link" id="class_list_link"
46
+ href="class_list.html">
47
+ Class List
48
+ </a>
49
+
50
+ <a class="full_list_link" id="method_list_link"
51
+ href="method_list.html">
52
+ Method List
53
+ </a>
54
+
55
+ <a class="full_list_link" id="file_list_link"
56
+ href="file_list.html">
57
+ File List
58
+ </a>
59
+
60
+ </div>
61
+ <div class="clear"></div>
62
+ </div>
63
+
64
+ <iframe id="search_frame"></iframe>
65
+
66
+ <div id="content"><h1>Module: Como
67
+
68
+
69
+
70
+ </h1>
71
+
72
+ <dl class="box">
73
+
74
+
75
+
76
+
77
+
78
+
79
+
80
+
81
+ <dt class="r1 last">Defined in:</dt>
82
+ <dd class="r1 last">lib/como.rb</dd>
83
+
84
+ </dl>
85
+ <div class="clear"></div>
86
+
87
+ <h2>Overview</h2><div class="docstring">
88
+ <div class="discussion">
89
+
90
+ <h1>Como</h1>
91
+
92
+ <h2>Introduction</h2>
93
+
94
+ <p>Como provides low manifest command line option parsing and deployment. The
95
+ command line options are described in compact table format and option
96
+ values are stored to conveniently named properties. Como builds command
97
+ usage information based on the option table (+ generic program info) and
98
+ displays it automatically if necessary. Como supports also subcommands and
99
+ checking for option combinations using a simple DSL.</p>
100
+
101
+ <h2>Usage Examples</h2>
102
+
103
+ <p>Two simple examples are presented in this section. First one includes a
104
+ straight forward command definition and the second is a bit more
105
+ complicated with subcommand feature in use.</p>
106
+
107
+ <h3>Simple example</h3>
108
+
109
+ <p>Below is a small example program ("como_simple") that demonstrates typical
110
+ usage.</p>
111
+
112
+ <h4>Program listing</h4>
113
+
114
+ <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>
115
+ <span class='id identifier rubyid_include'>include</span> <span class='const'>Como</span>
116
+
117
+ <span class='comment'># Define command line arguments:
118
+ </span><span class='const'>Spec</span><span class='period'>.</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_simple</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'>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='comma'>,</span>
119
+ <span class='lbracket'>[</span>
120
+ <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 argument.</span><span class='tstring_end'>&quot;</span></span> <span class='rbracket'>]</span><span class='comma'>,</span>
121
+ <span class='lbracket'>[</span> <span class='symbol'>:switch</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>debug</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'>-d</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'>Enable debugging.</span><span class='tstring_end'>&quot;</span></span> <span class='rbracket'>]</span><span class='comma'>,</span>
122
+ <span class='rbracket'>]</span> <span class='rparen'>)</span>
123
+
124
+ <span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'> File option: </span><span class='embexpr_beg'>#{</span><span class='const'>Opt</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>file</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_value'>value</span><span class='rbrace'>}</span><span class='tstring_end'>&quot;</span></span>
125
+ <span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'> Debugging selected!</span><span class='tstring_end'>&quot;</span></span> <span class='kw'>if</span> <span class='const'>Opt</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>debug</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_given'>given</span></code></pre>
126
+
127
+ <p>First Como is required and Como module is included.</p>
128
+
129
+ <p>"Spec.command" method takes 4 arguments:</p>
130
+ <dl class="rdoc-list"><dt>progname</dt>
131
+ <dd>
132
+ <p>Name of the program (or command).</p>
133
+ </dd><dt>author</dt>
134
+ <dd>
135
+ <p>Author of the program.</p>
136
+ </dd><dt>year</dt>
137
+ <dd>
138
+ <p>Year (or any date) for the program.</p>
139
+ </dd><dt>option table</dt>
140
+ <dd>
141
+ <p>Description of the command options.</p>
142
+ </dd></dl>
143
+
144
+ <p>Each option table entry (row/sub-array) includes 4 fields and specifies one
145
+ option:</p>
146
+
147
+ <pre class="code ruby"><code class="ruby"><span class='lbracket'>[</span> <span class='id identifier rubyid_type'>type</span><span class='comma'>,</span> <span class='id identifier rubyid_name'>name</span><span class='comma'>,</span> <span class='id identifier rubyid_mnemonic'>mnemonic</span><span class='comma'>,</span> <span class='id identifier rubyid_doc'>doc</span> <span class='rbracket'>]</span></code></pre>
148
+
149
+ <p>Two different types are present in the example:</p>
150
+ <dl class="rdoc-list"><dt>:single</dt>
151
+ <dd>
152
+ <p>Single means that the option requires one argument (and only one).</p>
153
+ </dd><dt>:switch</dt>
154
+ <dd>
155
+ <p>Switch is an optional flag (default value is false).</p>
156
+ </dd></dl>
157
+
158
+ <p>Option name is used to reference the option value that user has given. The
159
+ command line option values are stored automatically. For example the file
160
+ option value is returned by:</p>
161
+
162
+ <pre class="code ruby"><code class="ruby"><span class='const'>Opt</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>file</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_value'>value</span></code></pre>
163
+
164
+ <p>The option name also doubles as long option format, i.e. one could use
165
+ "--file &lt;filename&gt;" on the command line.</p>
166
+
167
+ <p>Existence of optional options can be tested using the "given" method. For
168
+ example</p>
169
+
170
+ <pre class="code ruby"><code class="ruby"><span class='const'>Opt</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>debug</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_given'>given</span></code></pre>
171
+
172
+ <p>would return "true" if "-d" was given on the command line.</p>
173
+
174
+ <p>Mnemonic is the short form option specification e.g. "-f". If short form is
175
+ replaced with "nil", the long option format is only available.</p>
176
+
177
+ <p>Doc includes documentation for the option. It is displayed when "help"
178
+ ("-h") option is given. Help option is added to the command automatically
179
+ as default behavior.</p>
180
+
181
+ <h4>Simple example executions</h4>
182
+
183
+ <p>Normal behavior would be achieved by executing:</p>
184
+
185
+ <pre class="code ruby"><code class="ruby">shell&gt; como_simple -f example -d</code></pre>
186
+
187
+ <p>The program would execute with the following output:</p>
188
+
189
+ <pre class="code ruby"><code class="ruby"><span class='const'>File</span> <span class='label'>option:</span> <span class='id identifier rubyid_example'>example</span>
190
+ <span class='const'>Debugging</span> <span class='id identifier rubyid_selected!'>selected!</span></code></pre>
191
+
192
+ <p>Same output would be achieved with:</p>
193
+
194
+ <pre class="code ruby"><code class="ruby">shell&gt; como_simple --file example --debug</code></pre>
195
+
196
+ <p>Since option name doubles as long option.</p>
197
+
198
+ <p>Como includes certain "extra" behavior out-of-box. Required arguments are
199
+ checked for existence and error is displayed if arguments are not given.</p>
200
+
201
+ <p>For example given the command:</p>
202
+
203
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_shell'>shell</span><span class='op'>&gt;</span> <span class='id identifier rubyid_como_simple'>como_simple</span></code></pre>
204
+
205
+ <p>The following is displayed on the screen:</p>
206
+
207
+ <pre class="code ruby"><code class="ruby">como_simple error: Option &quot;-f&quot; missing for &quot;como_simple&quot;...
208
+
209
+ Usage:
210
+ como_simple -f &lt;file&gt; [-d]
211
+
212
+ -f File argument.
213
+ -d Enable debugging.
214
+
215
+ Copyright (c) 2013 by Programmer</code></pre>
216
+
217
+ <p>Missing option error is displayed since "file" is a mandatory option. The
218
+ error message is followed by "usage" display (Usage Help). Documentation
219
+ string is taken from the option specification to "usage" display.</p>
220
+
221
+ <p>Given the command:</p>
222
+
223
+ <pre class="code ruby"><code class="ruby">shell&gt; como_simple -h</code></pre>
224
+
225
+ <p>would display the same "usage" screen except without the error line.</p>
226
+
227
+ <h3>Subccommand example</h3>
228
+
229
+ <p>Subcmd example includes a program which has subcommands. Subcommands can
230
+ have their own command line switches and options.</p>
231
+
232
+ <h4>Program listing</h4>
233
+
234
+ <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>
235
+ <span class='id identifier rubyid_include'>include</span> <span class='const'>Como</span>
236
+
237
+ <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>
238
+
239
+ <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>
240
+ <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>
241
+ <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>
242
+ <span class='rbracket'>]</span><span class='comma'>,</span> <span class='rparen'>)</span>
243
+
244
+ <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'>add</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='lbracket'>[</span>
245
+ <span class='lbracket'>[</span> <span class='symbol'>:switch</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>force</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'>-fo</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'>Force operation.</span><span class='tstring_end'>&quot;</span></span> <span class='rbracket'>]</span><span class='comma'>,</span>
246
+ <span class='lbracket'>[</span> <span class='symbol'>:opt_single</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>password</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'>-p</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'>User password.</span><span class='tstring_end'>&quot;</span></span> <span class='rbracket'>]</span><span class='comma'>,</span>
247
+ <span class='lbracket'>[</span> <span class='symbol'>:opt_single</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>username</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'>-u</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'>Username.</span><span class='tstring_end'>&quot;</span></span> <span class='rbracket'>]</span><span class='comma'>,</span>
248
+ <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>
249
+ <span class='rbracket'>]</span> <span class='rparen'>)</span>
250
+
251
+ <span class='id identifier rubyid_checkRule'>checkRule</span> <span class='kw'>do</span>
252
+ <span class='id identifier rubyid_one'>one</span><span class='lparen'>(</span>
253
+ <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>-fo</span><span class='tstring_end'>'</span></span><span class='comma'>,</span>
254
+ <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>
255
+ <span class='rparen'>)</span>
256
+ <span class='kw'>end</span>
257
+
258
+ <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'>rm</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='lbracket'>[</span>
259
+ <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>
260
+ <span class='rbracket'>]</span> <span class='rparen'>)</span>
261
+
262
+ <span class='kw'>end</span>
263
+
264
+ <span class='id identifier rubyid_subcmd'>subcmd</span> <span class='op'>=</span> <span class='const'>Opt</span><span class='period'>.</span><span class='id identifier rubyid_main'>main</span><span class='period'>.</span><span class='id identifier rubyid_givenSubcmd'>givenSubcmd</span>
265
+
266
+ <span class='kw'>case</span> <span class='id identifier rubyid_subcmd'>subcmd</span><span class='period'>.</span><span class='id identifier rubyid_name'>name</span>
267
+ <span class='kw'>when</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>add</span><span class='tstring_end'>'</span></span><span class='semicolon'>;</span> <span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'> Adding file \&quot;</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_subcmd'>subcmd</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>file</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_value'>value</span><span class='rbrace'>}</span><span class='tstring_content'>\&quot;...</span><span class='tstring_end'>&quot;</span></span>
268
+ <span class='kw'>when</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>rm</span><span class='tstring_end'>'</span></span><span class='semicolon'>;</span> <span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'> Removing file \&quot;</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_subcmd'>subcmd</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>file</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_value'>value</span><span class='rbrace'>}</span><span class='tstring_content'>\&quot;...</span><span class='tstring_end'>&quot;</span></span>
269
+ <span class='kw'>end</span></code></pre>
270
+
271
+ <p>"Spec.program" method defines a program (command) with subcommands. The
272
+ author and date are provided as parameters, and the program and subcommand
273
+ options are defined in block.</p>
274
+
275
+ <p>The first "subcmd" method call defines the main command ("Opt.main") which
276
+ represents the program. It has two "subcmd" options.</p>
277
+
278
+ <p>The rest of the "subcmd" methods define subcommands for the parent command.
279
+ This example includes one subcommand level, but multiple levels are
280
+ allowed.</p>
281
+
282
+ <p>The "checkRule" method defines option combination (RuleCheck) for the
283
+ previous subcommand definition. In this case the definition allows "add" to
284
+ have either the "-fo" option defined or "password" and "username" in
285
+ combination.</p>
286
+
287
+ <p>Main (root) commands can be referenced through</p>
288
+
289
+ <pre class="code ruby"><code class="ruby"><span class='const'>Opt</span><span class='period'>.</span><span class='id identifier rubyid_main'>main</span></code></pre>
290
+
291
+ <p>or alternatively</p>
292
+
293
+ <pre class="code ruby"><code class="ruby"><span class='const'>Opt</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>como_subcmd</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span></code></pre>
294
+
295
+ <p>The subcommands can be referenced through "Opt.main" (etc.)</p>
296
+
297
+ <pre class="code ruby"><code class="ruby"><span class='const'>Opt</span><span class='period'>.</span><span class='id identifier rubyid_main'>main</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>add</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span>
298
+ <span class='const'>Opt</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>como_subcmd</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>add</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span></code></pre>
299
+
300
+ <p>or directly from "Opt" if subcommand names do not collide:</p>
301
+
302
+ <pre class="code ruby"><code class="ruby"><span class='const'>Opt</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>add</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span></code></pre>
303
+
304
+ <p>The given subcommand can be accessed with "givenSubcmd" method from each
305
+ parent command.</p>
306
+
307
+ <h4>Subcommand example executions</h4>
308
+
309
+ <p>Normal behavior would be achieved by executing:</p>
310
+
311
+ <pre class="code ruby"><code class="ruby">shell&gt; como_subcmd add -fo -f example</code></pre>
312
+
313
+ <p>The program would execute with the following output:</p>
314
+
315
+ <pre class="code ruby"><code class="ruby">Adding file &quot;example&quot;...</code></pre>
316
+
317
+ <p>The option combinations for "add" subcommand are automatically checked.
318
+ Thus executing:</p>
319
+
320
+ <pre class="code ruby"><code class="ruby">shell&gt; como_subcmd add -f example</code></pre>
321
+
322
+ <p>Would result to:</p>
323
+
324
+ <pre class="code ruby"><code class="ruby">como_subcmd error: Option combination mismatch!
325
+
326
+ Subcommand &quot;add&quot; usage:
327
+ como_subcmd add [-fo] [-p &lt;password&gt;] [-u &lt;username&gt;] -f &lt;file&gt;
328
+
329
+ -fo Force operation.
330
+ -p User password.
331
+ -u Username.
332
+ -f File.
333
+
334
+ Option Combinations:
335
+ |--# One of:
336
+ | |--&lt;-fo&gt;
337
+ | |--# All of:
338
+ | | |--&lt;password&gt;
339
+ | | |--&lt;username&gt;</code></pre>
340
+
341
+ <p>Since the combination rule requires either "-fo" or both "password" and
342
+ "username" in a pair.</p>
343
+
344
+ <p>Help is automatically provided on each command level, thus these are both
345
+ valid.</p>
346
+
347
+ <pre class="code ruby"><code class="ruby">shell&gt; como_subcmd -h</code></pre>
348
+
349
+ <p>and</p>
350
+
351
+ <pre class="code ruby"><code class="ruby">shell&gt; como_subcmd rm -h</code></pre>
352
+
353
+ <h2>Option specification</h2>
354
+
355
+ <h3>Overview</h3>
356
+
357
+ <p>Option specification includes the minimum set of information required for
358
+ command line parsing. It is used to:</p>
359
+ <ul><li>
360
+ <p>Parse the command line.</p>
361
+ </li><li>
362
+ <p>Check for wrong options and report.</p>
363
+ </li><li>
364
+ <p>Check for mandatory arguments and report.</p>
365
+ </li><li>
366
+ <p>Set the options given/non-given state.</p>
367
+ </li><li>
368
+ <p>Set the options value. Array/String for all except true/false for switches.</p>
369
+ </li><li>
370
+ <p>Generate Usage Help printout.</p>
371
+ </li></ul>
372
+
373
+ <h3>Option types</h3>
374
+
375
+ <p>The following types can be defined for the command line options:</p>
376
+ <dl class="rdoc-list"><dt>:subcmd</dt>
377
+ <dd>
378
+ <p>Subcmd option. Subcmd specific options are provided separately.</p>
379
+ </dd><dt>:switch</dt>
380
+ <dd>
381
+ <p>Single switch option (no arguments).</p>
382
+ </dd><dt>:single</dt>
383
+ <dd>
384
+ <p>Mandatory single argument option.</p>
385
+ </dd><dt>:multi</dt>
386
+ <dd>
387
+ <p>Mandatory multiple argument option (one or many). Option values in array.</p>
388
+ </dd><dt>:opt_single</dt>
389
+ <dd>
390
+ <p>Optional single argument option.</p>
391
+ </dd><dt>:opt_multi</dt>
392
+ <dd>
393
+ <p>Optional multiple argument option (one or many). Option values in array.</p>
394
+ </dd><dt>:opt_any</dt>
395
+ <dd>
396
+ <p>Optional multiple argument option (also none accepted). Option values in
397
+ array.</p>
398
+ </dd><dt>:default</dt>
399
+ <dd>
400
+ <p>Default option (no switch associated). Name and option String values can be
401
+ left out, since only the document string is used. Default option is
402
+ referred with ":default" or "nil".</p>
403
+ </dd><dt>:exclusive</dt>
404
+ <dd>
405
+ <p>Option that does not coexist with other options.</p>
406
+ </dd><dt>:silent</dt>
407
+ <dd>
408
+ <p>Option that does not coexist with other options and is not displayed as an
409
+ option in Usage Help display. In effect a sub-option of :exclusive.</p>
410
+ </dd></dl>
411
+
412
+ <p>Options use typically all the 4 option fields:</p>
413
+
414
+ <pre class="code ruby"><code class="ruby"><span class='lbracket'>[</span> <span class='id identifier rubyid_type'>type</span><span class='comma'>,</span> <span class='id identifier rubyid_name'>name</span><span class='comma'>,</span> <span class='id identifier rubyid_mnemonic'>mnemonic</span><span class='comma'>,</span> <span class='id identifier rubyid_doc'>doc</span> <span class='rbracket'>]</span></code></pre>
415
+
416
+ <p>"type" field is mandatory for all options.</p>
417
+
418
+ <p>"name" field is also mandatory for all options. "mnemonic" can be left out,
419
+ but then option accepts only long option format.</p>
420
+
421
+ <p>":default" uses only "doc" and ":subcmd" doesn't use the "mnemonic" field.</p>
422
+
423
+ <p>":multi", ":opt_multi", and ":opt_any" option arguments are terminated only
424
+ when an option specifier is found. This can be a problem if ":default"
425
+ option follows. The recommended solution is to use a ":silent" option that
426
+ can be used to terminate the argument list. For example:</p>
427
+
428
+ <pre class="code ruby"><code class="ruby">[ :silent, &quot;terminator&quot;, &quot;-&quot;, &quot;The terminator.&quot; ],</code></pre>
429
+
430
+ <h3>Option specification method configuration</h3>
431
+
432
+ <p>Option behavior can be controlled with several configuration options.</p>
433
+
434
+ <p>The configuration options are provided in a Hash. These are the passed as
435
+ the last regular parameter for both "Spec.command" and "Spec.program"
436
+ methods. Setting the configuration at "Spec.program" will propagate the
437
+ config options to all the subcommands as well. Configuration can be given
438
+ to each subcommand separately to override the inherited config values.
439
+ Subcommand settings are not inherited, but apply only in the subcommand.</p>
440
+
441
+ <p>The usable configuration Hash keys:</p>
442
+ <dl class="rdoc-list"><dt>:autohelp</dt>
443
+ <dd>
444
+ <p>Add help option automatically (default: true). Custom help option can be
445
+ provided and it can be made also visible to user.</p>
446
+ </dd><dt>:rulehelp</dt>
447
+ <dd>
448
+ <p>Include RuleCheck help to Usage Help (default: false).</p>
449
+ </dd><dt>:header</dt>
450
+ <dd>
451
+ <p>Header lines before standard usage printout.</p>
452
+ </dd><dt>:footer</dt>
453
+ <dd>
454
+ <p>Footer lines after standard usage printout.</p>
455
+ </dd><dt>:subcheck</dt>
456
+ <dd>
457
+ <p>Automatically check that a subcommand is provided (default: true).</p>
458
+ </dd><dt>:check_missing</dt>
459
+ <dd>
460
+ <p>Check for missing arguments (default: true).</p>
461
+ </dd><dt>:tab</dt>
462
+ <dd>
463
+ <p>Tab stop column for option documentation (default: 12).</p>
464
+ </dd><dt>:help_exit</dt>
465
+ <dd>
466
+ <p>Exit program if help displayed (default: true).</p>
467
+ </dd><dt>:error_exit</dt>
468
+ <dd>
469
+ <p>Exit program if error in options (default: true).</p>
470
+ </dd></dl>
471
+
472
+ <h2>Option referencing</h2>
473
+
474
+ <h3>Existence and values</h3>
475
+
476
+ <p>Opt class includes the parsed option values. All options can be tested
477
+ whether they are specified on the command line using:</p>
478
+
479
+ <pre class="code ruby"><code class="ruby"><span class='const'>Opt</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>name</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_given'>given</span></code></pre>
480
+
481
+ <p>The "given" method takes optionally a block argument. When block argument
482
+ is used, the block is supplied with option value and the block is executed
483
+ if the option has been set (See: Opt#given).</p>
484
+
485
+ <p>Provided value is returned by:</p>
486
+
487
+ <pre class="code ruby"><code class="ruby"><span class='const'>Opt</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>name</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_value'>value</span></code></pre>
488
+
489
+ <p>For ":switch" type it is true/false value and for the other types a String
490
+ or an Array of Strings.</p>
491
+
492
+ <p>If an option takes multiple arguments, the value for the option is an
493
+ Array. The values can be iterated simply by:</p>
494
+
495
+ <pre class="code ruby"><code class="ruby"><span class='const'>Opt</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>files</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_each'>each</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_val'>val</span><span class='op'>|</span>
496
+ <span class='id identifier rubyid_puts'>puts</span> <span class='id identifier rubyid_val'>val</span>
497
+ <span class='kw'>end</span></code></pre>
498
+
499
+ <p>Short syntax for value referencing is performed with unary operator "~".
500
+ Thus</p>
501
+
502
+ <pre class="code ruby"><code class="ruby"><span class='op'>~</span><span class='const'>Opt</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>files</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span></code></pre>
503
+
504
+ <p>is equal to</p>
505
+
506
+ <pre class="code ruby"><code class="ruby"><span class='const'>Opt</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>files</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_value'>value</span></code></pre>
507
+
508
+ <p>With ":opt_any" type, the user should first check if the option was given:</p>
509
+
510
+ <pre class="code ruby"><code class="ruby"><span class='const'>Opt</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>many_files_or_none</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_given'>given</span></code></pre>
511
+
512
+ <p>Then check how many arguments where given:</p>
513
+
514
+ <pre class="code ruby"><code class="ruby"><span class='const'>Opt</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>many_files_or_none</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_value'>value</span><span class='period'>.</span><span class='id identifier rubyid_length'>length</span></code></pre>
515
+
516
+ <p>And finally decide what to do.</p>
517
+
518
+ <h3>Options including parameters</h3>
519
+
520
+ <p>Sometimes it is convenient for the program to use an option to include
521
+ multiple parameter settings. These settings can be parsed and mapped to a
522
+ Hash. Como performs automatic conversion to numeric values if possible. For
523
+ example with option:</p>
524
+
525
+ <pre class="code ruby"><code class="ruby">--set rounds=10 length=5</code></pre>
526
+
527
+ <p>Como can be used extract the parameter values with the "params" method:</p>
528
+
529
+ <pre class="code ruby"><code class="ruby"><span class='const'>Opt</span><span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>set</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_params'>params</span></code></pre>
530
+
531
+ <p>And a Hash is returned:</p>
532
+
533
+ <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>
534
+
535
+ <h3>Subcommand options</h3>
536
+
537
+ <p>The given subcommand for the parent command is return by "givenSubcmd".
538
+ Commonly the program creator should just check directly which subcommand
539
+ has been selected and check for any subcommand options set. For example:</p>
540
+
541
+ <pre class="code ruby"><code class="ruby">if Opt['como_subcmd']['add'].given
542
+ ...</code></pre>
543
+
544
+ <h3>Program external options</h3>
545
+
546
+ <p>If the user gives the "--" option (double-dash), the arguments after that
547
+ option is returned as an Array with "Opt.external".</p>
548
+
549
+ <h2>Option combination checks</h2>
550
+
551
+ <p>Como provides a facility to create relations between options using
552
+ RuleCheck DSL. This is needed since sometimes options have to be used in
553
+ combination to make sense for the program. Also options might be mutually
554
+ exclusive.</p>
555
+
556
+ <p>The following rules can be used (in combination):</p>
557
+ <dl class="rdoc-list"><dt>all</dt>
558
+ <dd>
559
+ <p>All options in the list.</p>
560
+ </dd><dt>one</dt>
561
+ <dd>
562
+ <p>One and only one from the list.</p>
563
+ </dd><dt>any</dt>
564
+ <dd>
565
+ <p>At least one of the list is given.</p>
566
+ </dd><dt>none</dt>
567
+ <dd>
568
+ <p>No options are required.</p>
569
+ </dd><dt>inv</dt>
570
+ <dd>
571
+ <p>Logical negation for existence.</p>
572
+ </dd><dt>incr</dt>
573
+ <dd>
574
+ <p>Incremental options in order i.e. have to have previous to have later.</p>
575
+ </dd><dt>follow</dt>
576
+ <dd>
577
+ <p>Incremental options in order i.e. have to have all later if had first.</p>
578
+ </dd><dt>meh</dt>
579
+ <dd>
580
+ <p>Dont care, always succeeds.</p>
581
+ </dd></dl>
582
+
583
+ <p>Examples can be found above.</p>
584
+
585
+ <h2>Customization</h2>
586
+
587
+ <p>If the default behavior is not satisfactory, changes can be implemented
588
+ simply by overloading the existing functions. Some knowledge of the
589
+ internal workings of Como is required though.</p>
590
+
591
+
592
+ </div>
593
+ </div>
594
+ <div class="tags">
595
+
596
+
597
+ </div><h2>Defined Under Namespace</h2>
598
+ <p class="children">
599
+
600
+
601
+
602
+
603
+ <strong class="classes">Classes:</strong> <span class='object_link'><a href="Como/ArgsParseState.html" title="Como::ArgsParseState (class)">ArgsParseState</a></span>, <span class='object_link'><a href="Como/ComoCommon.html" title="Como::ComoCommon (class)">ComoCommon</a></span>, <span class='object_link'><a href="Como/MainOpt.html" title="Como::MainOpt (class)">MainOpt</a></span>, <span class='object_link'><a href="Como/Opt.html" title="Como::Opt (class)">Opt</a></span>, <span class='object_link'><a href="Como/RuleCheck.html" title="Como::RuleCheck (class)">RuleCheck</a></span>, <span class='object_link'><a href="Como/RuleDisplay.html" title="Como::RuleDisplay (class)">RuleDisplay</a></span>, <span class='object_link'><a href="Como/Spec.html" title="Como::Spec (class)">Spec</a></span>
604
+
605
+
606
+ </p>
607
+
608
+
609
+
610
+
611
+
612
+
613
+
614
+
615
+
616
+ </div>
617
+
618
+ <div id="footer">
619
+ Generated on Mon Dec 30 13:50:51 2013 by
620
+ <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
621
+ 0.8.6.1 (ruby-1.9.3).
622
+ </div>
623
+
624
+ </body>
625
+ </html>