como 0.0.2 → 0.1.0

Sign up to get free protection for your applications and to get access to all the features.
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>