benry-cmdapp 0.2.0 → 1.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.
- checksums.yaml +4 -4
- data/CHANGES.md +12 -0
- data/README.md +1736 -862
- data/benry-cmdapp.gemspec +3 -3
- data/doc/benry-cmdapp.html +1620 -916
- data/doc/css/style.css +2 -2
- data/lib/benry/cmdapp.rb +1894 -1060
- data/test/app_test.rb +882 -1078
- data/test/config_test.rb +71 -0
- data/test/context_test.rb +382 -0
- data/test/func_test.rb +302 -82
- data/test/help_test.rb +1054 -553
- data/test/metadata_test.rb +191 -0
- data/test/misc_test.rb +175 -0
- data/test/registry_test.rb +402 -0
- data/test/run_all.rb +4 -3
- data/test/scope_test.rb +1219 -0
- data/test/shared.rb +112 -49
- data/test/util_test.rb +154 -99
- metadata +17 -9
- data/test/action_test.rb +0 -1038
- data/test/index_test.rb +0 -185
data/doc/benry-cmdapp.html
CHANGED
@@ -21,23 +21,23 @@
|
|
21
21
|
<ul class="nav">
|
22
22
|
</ul>
|
23
23
|
</nav>
|
24
|
-
<p>($Release:
|
24
|
+
<p>($Release: 1.1.0 $)</p>
|
25
25
|
<section class="section" id="whats-this">
|
26
26
|
<h2>What's This?</h2>
|
27
27
|
<p>Benry-CmdApp is a framework to create command-line application.
|
28
28
|
If you want create command-line application which takes sub-commands
|
29
29
|
like <code>git</code>, <code>docker</code>, or <code>npm</code>, Benry-CmdApp is the solution.</p>
|
30
|
-
<p>
|
30
|
+
<p>Basic idea:</p>
|
31
31
|
<ul>
|
32
|
-
<li>
|
32
|
+
<li>Action (= sub-command) is defined as a method in Ruby.</li>
|
33
33
|
<li>Commnad-line arguments are passed to action method as positional arguments.</li>
|
34
34
|
<li>Command-line options are passed to action method as keyword arguments.</li>
|
35
35
|
</ul>
|
36
36
|
<p>For example:</p>
|
37
37
|
<ul>
|
38
|
-
<li><code><command>
|
39
|
-
<li><code><command>
|
40
|
-
<li><code><command>
|
38
|
+
<li><code><command> hello</code> in command-line invokes action method <code>hello()</code> in Ruby.</li>
|
39
|
+
<li><code><command> hello arg1 arg2</code> invokes <code>hello("arg1", "arg2")</code>.</li>
|
40
|
+
<li><code><command> hello arg --opt=val</code> invokes <code>hello("arg", opt: "val")</code>.</li>
|
41
41
|
</ul>
|
42
42
|
<p>Links:</p>
|
43
43
|
<ul>
|
@@ -52,7 +52,7 @@ like <code>git</code>, <code>docker</code>, or <code>npm</code>, Benry-CmdApp is
|
|
52
52
|
<ul>
|
53
53
|
<li><a href="#whats-this">What's This?</a></li>
|
54
54
|
<li><a href="#install">Install</a></li>
|
55
|
-
<li><a href="#usage">Usage</a>
|
55
|
+
<li><a href="#basic-usage">Basic Usage</a>
|
56
56
|
<ul>
|
57
57
|
<li><a href="#action">Action</a></li>
|
58
58
|
<li><a href="#method-name-and-action-name">Method Name and Action Name</a></li>
|
@@ -62,13 +62,25 @@ like <code>git</code>, <code>docker</code>, or <code>npm</code>, Benry-CmdApp is
|
|
62
62
|
<li><a href="#option-value-validation">Option Value Validation</a></li>
|
63
63
|
<li><a href="#callback-for-option-value">Callback for Option Value</a></li>
|
64
64
|
<li><a href="#boolean-onoff-option">Boolean (On/Off) Option</a></li>
|
65
|
-
<li><a href="#
|
65
|
+
<li><a href="#option-set">Option Set</a></li>
|
66
|
+
<li><a href="#copy-options">Copy Options</a></li>
|
67
|
+
<li><a href="#option-error-and-action-error">Option Error and Action Error</a></li>
|
68
|
+
</ul></li>
|
69
|
+
<li><a href="#advanced-feature">Advanced Feature</a>
|
70
|
+
<ul>
|
71
|
+
<li><a href="#category-of-action">Category of Action</a></li>
|
72
|
+
<li><a href="#nested-category">Nested Category</a></li>
|
73
|
+
<li><a href="#category-action-or-alias">Category Action or Alias</a></li>
|
66
74
|
<li><a href="#invoke-other-action">Invoke Other Action</a></li>
|
67
|
-
<li><a href="#
|
75
|
+
<li><a href="#cleaning-up-block">Cleaning Up Block</a></li>
|
76
|
+
<li><a href="#alias-for-action">Alias for Action</a></li>
|
77
|
+
<li><a href="#abbreviation-of-category">Abbreviation of Category</a></li>
|
68
78
|
<li><a href="#default-action">Default Action</a></li>
|
69
|
-
<li><a href="#
|
70
|
-
<li><a href="#
|
71
|
-
<li><a href="#
|
79
|
+
<li><a href="#action-list-and-category-list">Action List and Category List</a></li>
|
80
|
+
<li><a href="#hidden-action">Hidden Action</a></li>
|
81
|
+
<li><a href="#hidden-option">Hidden Option</a></li>
|
82
|
+
<li><a href="#important-actions-or-options">Important Actions or Options</a></li>
|
83
|
+
<li><a href="#multiple-option">Multiple Option</a></li>
|
72
84
|
</ul></li>
|
73
85
|
<li><a href="#configuratoin-and-customization">Configuratoin and Customization</a>
|
74
86
|
<ul>
|
@@ -76,24 +88,28 @@ like <code>git</code>, <code>docker</code>, or <code>npm</code>, Benry-CmdApp is
|
|
76
88
|
<li><a href="#customization-of-global-options">Customization of Global Options</a></li>
|
77
89
|
<li><a href="#customization-of-global-option-behaviour">Customization of Global Option Behaviour</a></li>
|
78
90
|
<li><a href="#custom-hook-of-application">Custom Hook of Application</a></li>
|
79
|
-
<li><a href="#customization-of-
|
91
|
+
<li><a href="#customization-of-application-help-message">Customization of Application Help Message</a></li>
|
80
92
|
<li><a href="#customization-of-action-help-message">Customization of Action Help Message</a></li>
|
93
|
+
<li><a href="#customization-of-section-title-in-help-message">Customization of Section Title in Help Message</a></li>
|
81
94
|
</ul></li>
|
82
95
|
<li><a href="#q--a">Q & A</a>
|
83
96
|
<ul>
|
84
|
-
<li><a href="#q-how-to-
|
85
|
-
<li><a href="#q-how-to-
|
86
|
-
<li><a href="#q-how-to-
|
87
|
-
<li><a href="#q-how-to-
|
88
|
-
<li><a href="#q-how-to-
|
89
|
-
<li><a href="#q-how-to-
|
90
|
-
<li><a href="#q-how-to-
|
91
|
-
<li><a href="#q-how-to-
|
92
|
-
<li><a href="#q-
|
93
|
-
<li><a href="#q-how-to-
|
94
|
-
<li><a href="#q-
|
95
|
-
<li><a href="#q-
|
96
|
-
<li><a href="#q-how-to-
|
97
|
+
<li><a href="#q-how-to-show-all-backtraces-of-exception">Q: How to show all backtraces of exception?</a></li>
|
98
|
+
<li><a href="#q-how-to-specify-description-to-arguments-of-actions">Q: How to specify description to arguments of actions?</a></li>
|
99
|
+
<li><a href="#q-how-to-append-some-tasks-to-an-existing-action">Q: How to append some tasks to an existing action?</a></li>
|
100
|
+
<li><a href="#q-how-to-delete-an-existing-actionalias">Q: How to delete an existing action/alias?</a></li>
|
101
|
+
<li><a href="#q-how-to-re-define-an-existing-action">Q: How to re-define an existing action?</a></li>
|
102
|
+
<li><a href="#q-how-to-show-entering-into-or-exitting-from-actions">Q: How to show entering into or exitting from actions?</a></li>
|
103
|
+
<li><a href="#q-how-to-enabledisable-color-mode">Q: How to enable/disable color mode?</a></li>
|
104
|
+
<li><a href="#q-how-to-define--vvv-style-option">Q: How to define <code>-vvv</code> style option?</a></li>
|
105
|
+
<li><a href="#q-how-to-show-global-option--l-topic-in-help-message">Q: How to show global option <code>-L <topic></code> in help message?</a></li>
|
106
|
+
<li><a href="#q-how-to-specify-detailed-description-of-options">Q: How to specify detailed description of options?</a></li>
|
107
|
+
<li><a href="#q-how-to-list-only-aliases-or-actions-excluding-actions-or-aliases-">Q: How to list only aliases (or actions) excluding actions (or aliases) ?</a></li>
|
108
|
+
<li><a href="#q-how-to-change-the-order-of-options-in-help-message">Q: How to change the order of options in help message?</a></li>
|
109
|
+
<li><a href="#q-how-to-add-metadata-to-actions-or-options">Q: How to add metadata to actions or options?</a></li>
|
110
|
+
<li><a href="#q-how-to-remove-common-help-option-from-all-actions">Q: How to remove common help option from all actions?</a></li>
|
111
|
+
<li><a href="#q-is-it-possible-to-show-details-of-actions-and-aliases">Q: Is it possible to show details of actions and aliases?</a></li>
|
112
|
+
<li><a href="#q-how-to-make-error-messages-i18ned">Q: How to make error messages I18Ned?</a></li>
|
97
113
|
</ul></li>
|
98
114
|
<li><a href="#license-and-copyright">License and Copyright</a></li>
|
99
115
|
</ul>
|
@@ -106,39 +122,47 @@ like <code>git</code>, <code>docker</code>, or <code>npm</code>, Benry-CmdApp is
|
|
106
122
|
$ gem install benry-cmdapp
|
107
123
|
</pre>
|
108
124
|
</section>
|
109
|
-
<section class="section" id="usage">
|
110
|
-
<h2>Usage</h2>
|
125
|
+
<section class="section" id="basic-usage">
|
126
|
+
<h2>Basic Usage</h2>
|
111
127
|
<section class="subsection" id="action">
|
112
128
|
<h3>Action</h3>
|
129
|
+
<p>How to define actions:</p>
|
130
|
+
<ul>
|
131
|
+
<li>(1) Inherit action class.</li>
|
132
|
+
<li>(2) Define action methods with <code>@action.()</code>.</li>
|
133
|
+
<li>(3) Create an application object and run it.</li>
|
134
|
+
</ul>
|
135
|
+
<p>Note:</p>
|
113
136
|
<ul>
|
114
|
-
<li>
|
137
|
+
<li>Use <code>@action.()</code>, not <code>@action()</code>.</li>
|
138
|
+
<li>Command-line arguments are passed to action method as positional arguments.</li>
|
115
139
|
<li>An action class can have several action methods.</li>
|
116
140
|
<li>It is ok to define multiple action classes.</li>
|
117
|
-
<li>Command-line arguments are passed to action method as positional arguments.</li>
|
118
141
|
</ul>
|
119
142
|
<p>File: ex01.rb</p>
|
120
143
|
<pre class="language-ruby">
|
121
|
-
|
144
|
+
# coding: utf-8
|
122
145
|
<strong>require 'benry/cmdapp'</strong>
|
123
146
|
|
124
|
-
## action
|
147
|
+
## (1) Inherit action class.
|
125
148
|
class MyAction < <strong>Benry::CmdApp::Action</strong> # !!!!
|
126
149
|
|
150
|
+
## (2) Define action methods with `@action.()`.
|
127
151
|
<strong>@action.("print greeting message")</strong> # !!!!
|
128
|
-
<strong>def hello(
|
129
|
-
puts "Hello, #{
|
152
|
+
<strong>def hello(name="world")</strong> # !!!!
|
153
|
+
puts "Hello, #{name}!"
|
130
154
|
end
|
131
155
|
|
132
156
|
end
|
133
157
|
|
134
|
-
##
|
135
|
-
|
136
|
-
config.default_help = true
|
137
|
-
|
138
|
-
## run application
|
139
|
-
app = <strong>Benry::CmdApp::Application.new(config)</strong>
|
140
|
-
status_code = app.main()
|
158
|
+
## (3) Create an application object and run it.
|
159
|
+
status_code = <strong>Benry::CmdApp.main("sample app", "1.0.0")</strong>
|
141
160
|
exit status_code
|
161
|
+
## or:
|
162
|
+
#config = <strong>Benry::CmdApp::Config.new("sample app", "1.0.0")</strong>
|
163
|
+
#app = <strong>Benry::CmdApp::Application.new(config)</strong>
|
164
|
+
#status_code = app.main()
|
165
|
+
#exit status_code
|
142
166
|
</pre>
|
143
167
|
<p>Output:</p>
|
144
168
|
<pre class="language-console">
|
@@ -151,29 +175,44 @@ Hello, <strong>Alice</strong>!
|
|
151
175
|
<p>Help message of command:</p>
|
152
176
|
<pre class="language-console">
|
153
177
|
[bash]$ ruby ex01.rb <strong>-h</strong> # or `<strong>--help</strong>`
|
154
|
-
ex01.rb (1.0.0)
|
178
|
+
ex01.rb (1.0.0) --- sample app
|
155
179
|
|
156
180
|
Usage:
|
157
|
-
$ ex01.rb [<options>]
|
181
|
+
$ ex01.rb [<options>] <action> [<arguments>...]
|
158
182
|
|
159
183
|
Options:
|
160
|
-
-h, --help : print help message (of action if
|
184
|
+
-h, --help : print help message (of action if specified)
|
161
185
|
-V, --version : print version
|
186
|
+
-l, --list : list actions and aliases
|
187
|
+
-a, --all : list hidden actions/options, too
|
162
188
|
|
163
189
|
Actions:
|
164
190
|
hello : print greeting message
|
191
|
+
help : print help message (of action if specified)
|
165
192
|
</pre>
|
166
193
|
<p>Help message of action:</p>
|
167
194
|
<pre class="language-console">
|
168
|
-
[bash]$ ruby ex01.rb <strong>-h hello</strong>
|
169
|
-
ex01.rb hello
|
195
|
+
[bash]$ ruby ex01.rb <strong>-h hello</strong> # or: ruby ex01.rb --help hello
|
196
|
+
ex01.rb hello --- print greeting message
|
197
|
+
|
198
|
+
Usage:
|
199
|
+
$ ex01.rb hello [<name>]
|
200
|
+
</pre>
|
201
|
+
<ul>
|
202
|
+
<li>Benry-CmdApp adds <code>-h</code> and <code>--help</code> options to each action automatically.
|
203
|
+
Output of <code>ruby ex01.rb hello -h</code> and <code>ruby ex01.rb -h hello</code> will be the same.</li>
|
204
|
+
</ul>
|
205
|
+
<pre class="language-console">
|
206
|
+
[bash]$ ruby ex01.rb <strong>hello -h</strong> # or: ruby ex01.rb helo --help
|
207
|
+
ex01.rb hello --- print greeting message
|
170
208
|
|
171
209
|
Usage:
|
172
|
-
$ ex01.rb hello [&
|
210
|
+
$ ex01.rb hello [<name>]
|
173
211
|
</pre>
|
174
212
|
</section>
|
175
213
|
<section class="subsection" id="method-name-and-action-name">
|
176
214
|
<h3>Method Name and Action Name</h3>
|
215
|
+
<p>Rules between method name and action name:</p>
|
177
216
|
<ul>
|
178
217
|
<li>Method name <code>print_</code> results in action name <code>print</code>.
|
179
218
|
This is useful to define actions which name is same as Ruby keyword or popular functions.</li>
|
@@ -182,7 +221,7 @@ Usage:
|
|
182
221
|
</ul>
|
183
222
|
<p>File: ex02.rb</p>
|
184
223
|
<pre class="language-ruby">
|
185
|
-
|
224
|
+
# coding: utf-8
|
186
225
|
require 'benry/cmdapp'
|
187
226
|
|
188
227
|
class SampleAction < Benry::CmdApp::Action
|
@@ -201,30 +240,37 @@ class SampleAction < Benry::CmdApp::Action
|
|
201
240
|
|
202
241
|
## 'foo__bar__baz' => 'foo:bar:baz'
|
203
242
|
@action.("sample #3")
|
204
|
-
def foo<strong>__</strong>
|
243
|
+
def foo<strong>__</strong>bar<strong>__</strong>baz() # !!!!
|
205
244
|
puts __method__
|
206
245
|
end
|
207
246
|
|
208
247
|
end
|
209
248
|
|
210
|
-
|
211
|
-
|
212
|
-
|
249
|
+
status_code = Benry::CmdApp.main("test app")
|
250
|
+
exit status_code
|
251
|
+
## or:
|
252
|
+
#config = Benry::CmdApp::Config.new("test app")
|
253
|
+
#app = Benry::CmdApp::Application.new(config)
|
254
|
+
#status_code = app.main()
|
255
|
+
#exit status_code
|
213
256
|
</pre>
|
214
257
|
<p>Help message:</p>
|
215
258
|
<pre class="language-console">
|
216
259
|
[bash]$ ruby ex02.rb --help
|
217
|
-
ex02.rb
|
260
|
+
ex02.rb --- test app
|
218
261
|
|
219
262
|
Usage:
|
220
|
-
$ ex02.rb [<options>]
|
263
|
+
$ ex02.rb [<options>] <action> [<arguments>...]
|
221
264
|
|
222
265
|
Options:
|
223
|
-
-h, --help : print help message (of action if
|
266
|
+
-h, --help : print help message (of action if specified)
|
267
|
+
-l, --list : list actions and aliases
|
268
|
+
-a, --all : list hidden actions/options, too
|
224
269
|
|
225
270
|
Actions:
|
226
271
|
<strong>foo-bar-baz</strong> : sample #2
|
227
272
|
<strong>foo:bar:baz</strong> : sample #3
|
273
|
+
help : print help message (of action if specified)
|
228
274
|
<strong>print</strong> : sample #1
|
229
275
|
</pre>
|
230
276
|
<p>Output:</p>
|
@@ -241,57 +287,80 @@ foo__bar__baz
|
|
241
287
|
</section>
|
242
288
|
<section class="subsection" id="parameter-name-in-help-message-of-action">
|
243
289
|
<h3>Parameter Name in Help Message of Action</h3>
|
244
|
-
<p>In help message of action, positional parameters of action methods are printed under the name conversion rule.</p>
|
290
|
+
<p>In help message of an action, positional parameters of action methods are printed under the name conversion rule.</p>
|
245
291
|
<ul>
|
246
292
|
<li>Parameter <code>foo</code> is printed as <code><foo></code>.</li>
|
247
293
|
<li>Parameter <code>foo_bar_baz</code> is printed as <code><foo-bar-baz></code>.</li>
|
248
294
|
<li>Parameter <code>foo_or_bar_or_baz</code> is printed as <code><foo|bar|baz></code>.</li>
|
295
|
+
<li>Parameter <code>foobar__xxx</code> is printed as <code><foobar.xxx></code>.</li>
|
249
296
|
</ul>
|
250
297
|
<p>In addition, positional parameters are printed in different way according to its kind.</p>
|
251
298
|
<ul>
|
252
299
|
<li>If parameter <code>foo</code> is required (= doesn't have default value), it will be printed as <code><foo></code>.</li>
|
253
300
|
<li>If parameter <code>foo</code> is optional (= has default value), it will be printed as <code>[<foo>]</code>.</li>
|
254
301
|
<li>If parameter <code>foo</code> is variable length (= <code>*foo</code> style), it will be printed as <code>[<foo>...]</code>.</li>
|
302
|
+
<li>If parameter <code>foo</code> is required or optional and <code>foo_</code> is variable length, it will be printed as <code><foo>...</code>.</li>
|
255
303
|
</ul>
|
256
304
|
<p>File: ex03.rb</p>
|
257
305
|
<pre class="language-ruby">
|
258
|
-
|
306
|
+
# coding: utf-8
|
259
307
|
require 'benry/cmdapp'
|
260
308
|
|
261
309
|
class SampleAction < Benry::CmdApp::Action
|
262
310
|
|
263
|
-
@action.("
|
264
|
-
def test1(<strong>
|
311
|
+
@action.("name conversion test")
|
312
|
+
def test1(<strong>file_name, file_or_dir, file__html</strong>) # !!!!
|
313
|
+
# ...
|
314
|
+
end
|
315
|
+
|
316
|
+
@action.("parameter kind test")
|
317
|
+
def test2(<strong>aaa, bbb, ccc=nil, ddd=nil, *eee</strong>) # !!!!
|
318
|
+
# ...
|
319
|
+
end
|
320
|
+
|
321
|
+
@action.("parameter combination test")
|
322
|
+
def test3(<strong>file, *file_</strong>) # !!!!
|
323
|
+
files = [file] + file_
|
265
324
|
# ...
|
266
325
|
end
|
267
326
|
|
268
327
|
end
|
269
328
|
|
270
|
-
|
271
|
-
|
272
|
-
exit app.main()
|
329
|
+
status_code = Benry::CmdApp.main("sample app", "1.0.0")
|
330
|
+
exit status_code
|
273
331
|
</pre>
|
274
332
|
<p>Help message:</p>
|
275
333
|
<pre class="language-console">
|
276
334
|
[bash]$ ruby ex03.rb -h test1
|
277
|
-
|
335
|
+
ex03.rb test1 --- name conversion test
|
336
|
+
|
337
|
+
Usage:
|
338
|
+
$ ex03.rb test1 <strong><file-name> <file|dir> <file.html></strong> # !!!!
|
339
|
+
|
340
|
+
[bash]$ ruby ex03.rb -h test2
|
341
|
+
ex03.rb test2 --- parameter kind test
|
342
|
+
|
343
|
+
Usage:
|
344
|
+
$ ex03.rb test2 <strong><aaa> <bbb> [<ccc> [<ddd> [<eee>...]]]</strong> # !!!!
|
345
|
+
|
346
|
+
[bash]$ ruby ex03.rb -h test3
|
347
|
+
ex03.rb test3 --- parameter combination test
|
278
348
|
|
279
349
|
Usage:
|
280
|
-
$ ex03.rb
|
350
|
+
$ ex03.rb test3 <strong><file>...</strong> # !!!!
|
281
351
|
</pre>
|
282
352
|
</section>
|
283
353
|
<section class="subsection" id="options">
|
284
354
|
<h3>Options</h3>
|
285
355
|
<ul>
|
286
356
|
<li>Action can take command-line options.</li>
|
287
|
-
<li>Option values specified in command-line are passed to
|
357
|
+
<li>Option values specified in command-line are passed to action method as keyword arguments.</li>
|
288
358
|
</ul>
|
289
359
|
<p>File: ex04.rb</p>
|
290
360
|
<pre class="language-ruby">
|
291
|
-
|
361
|
+
# coding: utf-8
|
292
362
|
require 'benry/cmdapp'
|
293
363
|
|
294
|
-
## action
|
295
364
|
class MyAction < Benry::CmdApp::Action
|
296
365
|
|
297
366
|
@action.("print greeting message")
|
@@ -302,20 +371,13 @@ class MyAction < Benry::CmdApp::Action
|
|
302
371
|
when "fr" ; puts "Bonjour, #{user}!"
|
303
372
|
when "it" ; puts "Ciao, #{user}!"
|
304
373
|
else
|
305
|
-
raise "#{lang}:
|
374
|
+
raise "#{lang}: Unknown language."
|
306
375
|
end
|
307
376
|
end
|
308
377
|
|
309
378
|
end
|
310
379
|
|
311
|
-
|
312
|
-
config = Benry::CmdApp::Config.new("sample app", "1.0.0")
|
313
|
-
config.default_help = true
|
314
|
-
|
315
|
-
## run application
|
316
|
-
app = Benry::CmdApp::Application.new(config)
|
317
|
-
status_code = app.main()
|
318
|
-
exit status_code
|
380
|
+
exit Benry::CmdApp.main("sample app", "1.0.0")
|
319
381
|
</pre>
|
320
382
|
<p>Output:</p>
|
321
383
|
<pre class="language-console">
|
@@ -334,10 +396,9 @@ exit status_code
|
|
334
396
|
</ul>
|
335
397
|
<p>File: ex05.rb</p>
|
336
398
|
<pre class="language-ruby">
|
337
|
-
|
399
|
+
# coding: utf-8
|
338
400
|
require 'benry/cmdapp'
|
339
401
|
|
340
|
-
## action
|
341
402
|
class MyAction < Benry::CmdApp::Action
|
342
403
|
|
343
404
|
@action.("print greeting message")
|
@@ -351,21 +412,14 @@ class MyAction < Benry::CmdApp::Action
|
|
351
412
|
when "fr" ; puts "Bonjour, #{user}!"
|
352
413
|
when "it" ; puts "Ciao, #{user}!"
|
353
414
|
else
|
354
|
-
raise "#{lang}:
|
415
|
+
raise "#{lang}: Unknown language."
|
355
416
|
end
|
356
417
|
end
|
357
418
|
end
|
358
419
|
|
359
420
|
end
|
360
421
|
|
361
|
-
|
362
|
-
config = Benry::CmdApp::Config.new("sample app", "1.0.0")
|
363
|
-
config.default_help = true
|
364
|
-
|
365
|
-
## run application
|
366
|
-
app = Benry::CmdApp::Application.new(config)
|
367
|
-
status_code = app.main()
|
368
|
-
exit status_code
|
422
|
+
exit Benry::CmdApp.main("sample app", "1.0.0")
|
369
423
|
</pre>
|
370
424
|
<p>Output:</p>
|
371
425
|
<pre class="language-console">
|
@@ -373,47 +427,75 @@ exit status_code
|
|
373
427
|
Bonjour, Alice!
|
374
428
|
Bonjour, Alice!
|
375
429
|
Bonjour, Alice!
|
376
|
-
|
377
|
-
|
378
|
-
|
379
|
-
|
380
|
-
```console
|
430
|
+
</pre>
|
431
|
+
<p>Help message:</p>
|
432
|
+
<pre class="language-console">
|
381
433
|
[bash]$ ruby ex05.rb -h hello
|
382
|
-
ex05.rb hello
|
434
|
+
ex05.rb hello --- print greeting message
|
383
435
|
|
384
436
|
Usage:
|
385
437
|
$ ex05.rb hello [<options>] [<user>]
|
386
438
|
|
387
439
|
Options:
|
388
|
-
-l, --lang=<en|fr|it> : language
|
440
|
+
-l, --lang=<en|fr|it> : language
|
389
441
|
<strong> --repeat=<N> : repeat <N> times</strong> # !!!!
|
390
442
|
</pre>
|
391
|
-
<
|
392
|
-
|
393
|
-
|
443
|
+
<ul>
|
444
|
+
<li>If an option defined but the corresponding keyword argument is missing, error will be raised.</li>
|
445
|
+
<li>If an action method accepts any keyword arguments (such as <code>**kwargs</code>), nothing will be raised.</li>
|
446
|
+
</ul>
|
447
|
+
<pre class="language-ruby">
|
448
|
+
### ERROR: option `:repeat` is defined but keyword arg `repeat:` is missing.
|
449
|
+
@action.("greeting message")
|
450
|
+
@option.(<strong>:lang</strong> , "-l <lang>", "language")
|
451
|
+
@option.(<strong>:repeat</strong>, "-n <N>" , "repeat N times")
|
452
|
+
def hello(user="world", <strong>lang:</strong> "en")
|
453
|
+
....
|
454
|
+
end
|
455
|
+
|
456
|
+
### NO ERROR: `**kwargs` accepts any keyword arguments.
|
457
|
+
@action.("greeting message")
|
458
|
+
@option.(:lang , "-l <lang>", "language")
|
459
|
+
@option.(:repeat, "-n <N>" , "repeat N times")
|
460
|
+
def hello(user="world", lang: "en", <strong>**kwargs</strong>)
|
461
|
+
....
|
462
|
+
end
|
463
|
+
</pre>
|
464
|
+
<p>For usability reason, Benry-CmdApp supports <code>--lang=<val></code> style of long option
|
465
|
+
but doesn't support <code>--lang <val></code> style.
|
466
|
+
Benry-CmdApp regards <code>--lang <val></code> as 'long option without argument'
|
394
467
|
and 'argument for command'.</p>
|
395
468
|
<pre class="language-console">
|
396
469
|
[bash]$ ruby ex05.rb hello <strong>--lang fr</strong> # ``--lang fr`` != ``--lang=fr``
|
397
|
-
<strong>[ERROR] --lang:
|
470
|
+
<strong>[ERROR] --lang: Argument required.</strong>
|
398
471
|
</pre>
|
399
472
|
</section>
|
400
473
|
<section class="subsection" id="option-definition-format">
|
401
474
|
<h3>Option Definition Format</h3>
|
402
|
-
<p>
|
475
|
+
<p>There are 9 option definition formats.</p>
|
476
|
+
<ul>
|
477
|
+
<li>When the option takes no value:
|
478
|
+
<ul>
|
479
|
+
<li><code>-q</code> --- Short style.</li>
|
480
|
+
<li><code>--quiet</code> --- Long style.</li>
|
481
|
+
<li><code>-q, --quiet</code> --- Short and long style.</li>
|
482
|
+
</ul></li>
|
483
|
+
<li>When the option takes a required value:
|
484
|
+
<ul>
|
485
|
+
<li><code>-f <path></code> --- Short style.</li>
|
486
|
+
<li><code>--file=<path></code> --- Long style.</li>
|
487
|
+
<li><code>-f, --file=<path></code> --- Short and long style.</li>
|
488
|
+
</ul></li>
|
489
|
+
<li>When the option takes an optional value:
|
403
490
|
<ul>
|
404
|
-
<li
|
405
|
-
<li
|
406
|
-
<li
|
407
|
-
|
408
|
-
<li>(long option) <code>--file=<file></code> : value required.</li>
|
409
|
-
<li>(long option) <code>--indent[=<width>]</code> : value is optional.</li>
|
410
|
-
<li>(short & long) <code>-q, --quiet</code> : no values.</li>
|
411
|
-
<li>(short & long) <code>-f, --file=<file></code> : value required.</li>
|
412
|
-
<li>(short & long) <code>-i, --indent[=<width>]</code> : value is optional.</li>
|
491
|
+
<li><code>-i[<N>]</code> --- Short style.</li>
|
492
|
+
<li><code>--indent[=<N>]</code> --- Long style.</li>
|
493
|
+
<li><code>-i, --indent[=<N>]</code> --- Short and long style.</li>
|
494
|
+
</ul></li>
|
413
495
|
</ul>
|
414
496
|
<p>File: ex06.rb</p>
|
415
497
|
<pre class="language-ruby">
|
416
|
-
|
498
|
+
# coding: utf-8
|
417
499
|
require 'benry/cmdapp'
|
418
500
|
|
419
501
|
class SampleAction < Benry::CmdApp::Action
|
@@ -447,9 +529,7 @@ class SampleAction < Benry::CmdApp::Action
|
|
447
529
|
|
448
530
|
end
|
449
531
|
|
450
|
-
|
451
|
-
app = Benry::CmdApp::Application.new(config)
|
452
|
-
exit app.main()
|
532
|
+
exit Benry::CmdApp.main("test app")
|
453
533
|
</pre>
|
454
534
|
<p>Output:</p>
|
455
535
|
<pre class="language-console">
|
@@ -479,7 +559,7 @@ quiet=false, file=nil, <strong>indent="4"</strong>
|
|
479
559
|
<p>Help message:</p>
|
480
560
|
<pre class="language-ruby">
|
481
561
|
[bash]$ ruby ex06.rb -h test1
|
482
|
-
ex06.rb test1
|
562
|
+
ex06.rb test1 --- short options
|
483
563
|
|
484
564
|
Usage:
|
485
565
|
$ ex06.rb test1 [<options>]
|
@@ -490,7 +570,7 @@ Options:
|
|
490
570
|
<strong>-i[<N>]</strong> : indent width
|
491
571
|
|
492
572
|
[bash]$ ruby ex06.rb -h test2
|
493
|
-
ex06.rb test2
|
573
|
+
ex06.rb test2 --- long options
|
494
574
|
|
495
575
|
Usage:
|
496
576
|
$ ex06.rb test2 [<options>]
|
@@ -501,7 +581,7 @@ Options:
|
|
501
581
|
<strong>--indent[=<N>]</strong> : indent width
|
502
582
|
|
503
583
|
[bash]$ ruby ex06.rb -h test3
|
504
|
-
ex06.rb test3
|
584
|
+
ex06.rb test3 --- short and long options
|
505
585
|
|
506
586
|
Usage:
|
507
587
|
$ ex06.rb test3 [<options>]
|
@@ -524,10 +604,9 @@ Options:
|
|
524
604
|
</ul>
|
525
605
|
<p>File: ex07.rb</p>
|
526
606
|
<pre class="language-ruby">
|
527
|
-
|
607
|
+
# coding: utf-8
|
528
608
|
require 'benry/cmdapp'
|
529
609
|
|
530
|
-
## action
|
531
610
|
class MyAction < Benry::CmdApp::Action
|
532
611
|
|
533
612
|
@action.("print greeting message")
|
@@ -544,32 +623,25 @@ class MyAction < Benry::CmdApp::Action
|
|
544
623
|
when "fr" ; puts "Bonjour, #{user}!"
|
545
624
|
when "it" ; puts "Ciao, #{user}!"
|
546
625
|
else
|
547
|
-
raise "#{lang}:
|
626
|
+
raise "#{lang}: Unknown language."
|
548
627
|
end
|
549
628
|
end
|
550
629
|
end
|
551
630
|
|
552
631
|
end
|
553
632
|
|
554
|
-
|
555
|
-
config = Benry::CmdApp::Config.new("sample app", "1.0.0")
|
556
|
-
config.default_help = true
|
557
|
-
|
558
|
-
## run application
|
559
|
-
app = Benry::CmdApp::Application.new(config)
|
560
|
-
status_code = app.main()
|
561
|
-
exit status_code
|
633
|
+
exit Benry::CmdApp.main("sample app", "1.0.0")
|
562
634
|
</pre>
|
563
635
|
<p>Output:</p>
|
564
636
|
<pre class="language-console">
|
565
637
|
[bash]$ ruby ex07.rb hello <strong>-l japan</strong>
|
566
|
-
<strong>[ERROR] -l japan:
|
638
|
+
<strong>[ERROR] -l japan: Pattern unmatched.</strong>
|
567
639
|
|
568
640
|
[bash]$ ruby ex07.rb hello <strong>-l ja</strong>
|
569
|
-
<strong>[ERROR] -l ja:
|
641
|
+
<strong>[ERROR] -l ja: Expected one of en/fr/it.</strong>
|
570
642
|
|
571
643
|
[bash]$ ruby ex07.rb hello <strong>--repeat=abc</strong>
|
572
|
-
<strong>[ERROR] --repeat=abc:
|
644
|
+
<strong>[ERROR] --repeat=abc: Integer expected.</strong>
|
573
645
|
|
574
646
|
[bash]$ ruby ex07.rb hello <strong>--repeat=100</strong>
|
575
647
|
<strong>[ERROR] --repeat=100: Too large (max: 10).</strong>
|
@@ -585,10 +657,9 @@ Callback can:</p>
|
|
585
657
|
</ul>
|
586
658
|
<p>File: ex08.rb</p>
|
587
659
|
<pre class="language-ruby">
|
588
|
-
|
660
|
+
# coding: utf-8
|
589
661
|
require 'benry/cmdapp'
|
590
662
|
|
591
|
-
## action
|
592
663
|
class MyAction < Benry::CmdApp::Action
|
593
664
|
|
594
665
|
@action.("print greeting message")
|
@@ -597,7 +668,7 @@ class MyAction < Benry::CmdApp::Action
|
|
597
668
|
rexp: /\A\w\w\z/) <strong>{|v| v.downcase }</strong> # !!!!
|
598
669
|
@option.(:repeat, " --repeat=<N>", "repeat <N> times",
|
599
670
|
type: Integer) <strong>{|v|</strong> # !!!!
|
600
|
-
<strong>v > 0 or raise "
|
671
|
+
<strong>v > 0 or raise "Not positive value."</strong> # !!!!
|
601
672
|
<strong>v</strong> # !!!!
|
602
673
|
<strong>}</strong> # !!!!
|
603
674
|
def hello(user="world", lang: "en", repeat: 1)
|
@@ -607,21 +678,14 @@ class MyAction < Benry::CmdApp::Action
|
|
607
678
|
when "fr" ; puts "Bonjour, #{user}!"
|
608
679
|
when "it" ; puts "Ciao, #{user}!"
|
609
680
|
else
|
610
|
-
raise "#{lang}:
|
681
|
+
raise "#{lang}: Unknown language."
|
611
682
|
end
|
612
683
|
end
|
613
684
|
end
|
614
685
|
|
615
686
|
end
|
616
687
|
|
617
|
-
|
618
|
-
config = Benry::CmdApp::Config.new("sample app", "1.0.0")
|
619
|
-
config.default_help = true
|
620
|
-
|
621
|
-
## run application
|
622
|
-
app = Benry::CmdApp::Application.new(config)
|
623
|
-
status_code = app.main()
|
624
|
-
exit status_code
|
688
|
+
exit Benry::CmdApp.main("sample app", "1.0.0")
|
625
689
|
</pre>
|
626
690
|
<p>Output:</p>
|
627
691
|
<pre class="language-console">
|
@@ -629,12 +693,12 @@ exit status_code
|
|
629
693
|
Bonjour, world!
|
630
694
|
|
631
695
|
[bash]$ ruby ex08.rb hello <strong>--repeat=0</strong>
|
632
|
-
<strong>[ERROR] --repeat=0:
|
696
|
+
<strong>[ERROR] --repeat=0: Not positive value.</strong>
|
633
697
|
</pre>
|
634
698
|
</section>
|
635
699
|
<section class="subsection" id="boolean-onoff-option">
|
636
700
|
<h3>Boolean (On/Off) Option</h3>
|
637
|
-
<p>Benry
|
701
|
+
<p>Benry-CmdApp doesn't support <code>--[no-]foobar</code> style option.
|
638
702
|
Instead, define boolean (on/off) option.</p>
|
639
703
|
<ul>
|
640
704
|
<li>Specify <code>type: TrueClass</code> to <code>@option.()</code>.</li>
|
@@ -643,7 +707,7 @@ Instead, define boolean (on/off) option.</p>
|
|
643
707
|
</ul>
|
644
708
|
<p>File: ex09.rb</p>
|
645
709
|
<pre class="language-ruby">
|
646
|
-
|
710
|
+
# coding: utf-8
|
647
711
|
require 'benry/cmdapp'
|
648
712
|
|
649
713
|
class SampleAction < Benry::CmdApp::Action
|
@@ -658,9 +722,7 @@ class SampleAction < Benry::CmdApp::Action
|
|
658
722
|
|
659
723
|
end
|
660
724
|
|
661
|
-
|
662
|
-
app = Benry::CmdApp::Application.new(config)
|
663
|
-
exit app.main()
|
725
|
+
exit Benry::CmdApp.main("sample app", "1.0.0")
|
664
726
|
</pre>
|
665
727
|
<p>Output:</p>
|
666
728
|
<pre class="language-console">
|
@@ -692,7 +754,7 @@ verbose=<strong>false</strong>
|
|
692
754
|
</ul>
|
693
755
|
<p>File: ex10.rb</p>
|
694
756
|
<pre class="language-ruby">
|
695
|
-
|
757
|
+
# coding: utf-8
|
696
758
|
require 'benry/cmdapp'
|
697
759
|
|
698
760
|
class SampleAction < Benry::CmdApp::Action
|
@@ -706,9 +768,7 @@ class SampleAction < Benry::CmdApp::Action
|
|
706
768
|
|
707
769
|
end
|
708
770
|
|
709
|
-
|
710
|
-
app = Benry::CmdApp::Application.new(config)
|
711
|
-
exit app.main()
|
771
|
+
exit Benry::CmdApp.main("git helper")
|
712
772
|
</pre>
|
713
773
|
<p>Output:</p>
|
714
774
|
<pre class="language-console">
|
@@ -719,7 +779,7 @@ verbose=<strong>true</strong>
|
|
719
779
|
verbose=<strong>false</strong>
|
720
780
|
|
721
781
|
[bash]$ ruby ex10.rb flagtest2 <strong>--quiet=on</strong> # error
|
722
|
-
<strong>[ERROR] --quiet=on:
|
782
|
+
<strong>[ERROR] --quiet=on: Unexpected argument.</strong>
|
723
783
|
</pre>
|
724
784
|
<p>In above example, <code>--quiet=on</code> will be error because option is defined as
|
725
785
|
<code>@option.(:verbose, "-q, --quiet", ...)</code> which means that this option takes no arguments.
|
@@ -728,8 +788,8 @@ If you want to allow <code>--quiet=on</code>, specify option argument and <code>
|
|
728
788
|
...(snip)...
|
729
789
|
|
730
790
|
@action.("flag test")
|
731
|
-
@option.(:verbose, "-q, --quiet<strong>[=<on|off]</strong>", "quiet mode", # !!!!
|
732
|
-
<strong>type: TrueClass</strong>, value: false)
|
791
|
+
@option.(:verbose, "-q, --quiet<strong>[=<on|off>]</strong>", "quiet mode", # !!!!
|
792
|
+
<strong>type: TrueClass</strong>, value: false) # !!!!
|
733
793
|
def flagtest2(verbose: true)
|
734
794
|
puts "verbose=#{verbose.inspect}"
|
735
795
|
end
|
@@ -737,351 +797,749 @@ If you want to allow <code>--quiet=on</code>, specify option argument and <code>
|
|
737
797
|
...(snip)...
|
738
798
|
</pre>
|
739
799
|
</section>
|
740
|
-
<section class="subsection" id="
|
741
|
-
<h3>
|
742
|
-
<
|
743
|
-
|
744
|
-
<li>Method name <code>def baz__test()</code> with <code>prefix: "foo:bar"</code> results in action name <code>foo:bar:baz:test</code>.</li>
|
745
|
-
</ul>
|
800
|
+
<section class="subsection" id="option-set">
|
801
|
+
<h3>Option Set</h3>
|
802
|
+
<p>Option set handles multiple options as a object.
|
803
|
+
Option set will help you to define same options into multiple actions.</p>
|
746
804
|
<p>File: ex11.rb</p>
|
747
805
|
<pre class="language-ruby">
|
748
|
-
|
806
|
+
# coding: utf-8
|
749
807
|
require 'benry/cmdapp'
|
750
808
|
|
751
809
|
class SampleAction < Benry::CmdApp::Action
|
752
|
-
<strong>prefix "foo:bar"</strong> # !!!!
|
753
810
|
|
754
|
-
|
755
|
-
|
756
|
-
|
811
|
+
optset1 = <strong>optionset()</strong> { # !!!!
|
812
|
+
@option.(:host , "-H, --host=<host>" , "host name")
|
813
|
+
@option.(:port , "-p, --port=<port>" , "port number", type: Integer)
|
814
|
+
}
|
815
|
+
optset2 = <strong>optionset()</strong> { # !!!!
|
816
|
+
@option.(:user , "-u, --user=<user>" , "user name")
|
817
|
+
}
|
818
|
+
|
819
|
+
@action.("connect to postgresql server")
|
820
|
+
<strong>@optionset.(optset1, optset2)</strong> # !!!!
|
821
|
+
def postgresql(host: nil, port: nil, user: nil)
|
822
|
+
puts "psql ...."
|
757
823
|
end
|
758
824
|
|
759
|
-
@action.("
|
760
|
-
|
761
|
-
|
825
|
+
@action.("connect to mysql server")
|
826
|
+
<strong>@optionset.(optset1, optset2)</strong> # !!!!
|
827
|
+
def mysql(host: nil, port: nil, user: nil)
|
828
|
+
puts "mysql ...."
|
762
829
|
end
|
763
830
|
|
764
831
|
end
|
765
832
|
|
766
|
-
|
767
|
-
app = Benry::CmdApp::Application.new(config)
|
768
|
-
exit app.main()
|
769
|
-
</pre>
|
770
|
-
<p>Output:</p>
|
771
|
-
<pre class="language-console">
|
772
|
-
[bash]$ ruby ex11.rb <strong>foo:bar:test1</strong>
|
773
|
-
test1
|
774
|
-
|
775
|
-
[bash]$ ruby ex11.rb <strong>foo:bar:baz:test2</strong>
|
776
|
-
baz__test2
|
833
|
+
exit Benry::CmdApp.main("Sample App")
|
777
834
|
</pre>
|
778
835
|
<p>Help message:</p>
|
779
836
|
<pre class="language-console">
|
780
|
-
[bash]$ ruby ex11.rb -h
|
781
|
-
ex11.rb
|
837
|
+
[bash]$ ruby ex11.rb -h <strong>postgresql</strong> # !!!!
|
838
|
+
ex11.rb postgresql --- connect to postgresql
|
782
839
|
|
783
840
|
Usage:
|
784
|
-
$ ex11.rb [<options>]
|
841
|
+
$ ex11.rb postgresql [<options>]
|
785
842
|
|
786
843
|
Options:
|
787
|
-
|
844
|
+
<strong>-H, --host=<host> : host name</strong> # !!!!
|
845
|
+
<strong>-p, --port=<port> : port number</strong> # !!!!
|
846
|
+
<strong>-u, --user=<user> : user name</strong> # !!!!
|
788
847
|
|
789
|
-
|
790
|
-
|
791
|
-
|
848
|
+
[bash]$ ruby ex11.rb -h <strong>mysql</strong> # !!!!
|
849
|
+
ex11.rb mysql --- connect to mysql
|
850
|
+
|
851
|
+
Usage:
|
852
|
+
$ ex11.rb mysql [<options>]
|
853
|
+
|
854
|
+
Options:
|
855
|
+
<strong>-H, --host=<host> : host name</strong> # !!!!
|
856
|
+
<strong>-p, --port=<port> : port number</strong> # !!!!
|
857
|
+
<strong>-u, --user=<user> : user name</strong> # !!!!
|
792
858
|
</pre>
|
859
|
+
<p>Option set object has the following methods.</p>
|
793
860
|
<ul>
|
794
|
-
<li><code>
|
861
|
+
<li><code>OptionSet#select(:key1, :key2, ...)</code> ---
|
862
|
+
Creates new OptionSet object with copying options which are filtered by the keys specified.</li>
|
863
|
+
<li><code>OptionSet#exclude(:key1, :key2, ...)</code> ---
|
864
|
+
Creates new OptionSet object with copying options which are filtered by dropping the options that key is included in specified keys.</li>
|
795
865
|
</ul>
|
866
|
+
<pre class="language-ruby">
|
867
|
+
@action.("connect to postgresql server")
|
868
|
+
@optionset.(<strong>optset1.select(:host, :port)</strong>) # !!!!
|
869
|
+
def postgresql(host: nil, port: nil)
|
870
|
+
....
|
871
|
+
end
|
872
|
+
|
873
|
+
@action.("connect to mysql server")
|
874
|
+
@optionset.(<strong>optset1.exclude(:port)</strong>) # !!!!
|
875
|
+
def mysql(host: nil)
|
876
|
+
....
|
877
|
+
end
|
878
|
+
</pre>
|
879
|
+
</section>
|
880
|
+
<section class="subsection" id="copy-options">
|
881
|
+
<h3>Copy Options</h3>
|
882
|
+
<p><code>@copy_options.()</code> copies options from other action.</p>
|
796
883
|
<p>File: ex12.rb</p>
|
797
884
|
<pre class="language-ruby">
|
798
|
-
|
885
|
+
# coding: utf-8
|
799
886
|
require 'benry/cmdapp'
|
800
887
|
|
801
888
|
class SampleAction < Benry::CmdApp::Action
|
802
|
-
prefix "foo:bar", <strong>action: :test3_</strong> # !!!!
|
803
|
-
## or:
|
804
|
-
#prefix "foo:bar", <strong>action: "test3"</strong> # !!!!
|
805
889
|
|
806
|
-
@action.("
|
807
|
-
|
808
|
-
|
890
|
+
@action.("connect to postgresql")
|
891
|
+
@option.(:host , "-H, --host=<host>" , "host name")
|
892
|
+
@option.(:port , "-p, --port=<port>" , "port number", type: Integer)
|
893
|
+
@option.(:user , "-u, --user=<user>" , "user name")
|
894
|
+
def postgresql(host: nil, port: nil, user: nil)
|
895
|
+
puts "psql ...."
|
809
896
|
end
|
810
897
|
|
811
|
-
@action.("
|
812
|
-
|
813
|
-
|
898
|
+
@action.("connect to mysql")
|
899
|
+
<strong>@copy_options.("postgresql")</strong> # !!!!!
|
900
|
+
def mysql(host: nil, port: nil, user: nil)
|
901
|
+
puts "mysql ...."
|
814
902
|
end
|
815
903
|
|
816
904
|
end
|
817
905
|
|
818
|
-
|
819
|
-
app = Benry::CmdApp::Application.new(config)
|
820
|
-
exit app.main()
|
821
|
-
</pre>
|
822
|
-
<p>Output:</p>
|
823
|
-
<pre class="language-console">
|
824
|
-
[bash]$ ruby ex12.rb foo:bar:test1
|
825
|
-
test1
|
826
|
-
|
827
|
-
[bash]$ ruby ex12.rb <strong>foo:bar:test3</strong>
|
828
|
-
[ERROR] foo:bar:test2: unknown action.
|
829
|
-
|
830
|
-
[bash]$ ruby ex12.rb <strong>foo:bar</strong>
|
831
|
-
test3_
|
906
|
+
exit Benry::CmdApp.main("Sample App")
|
832
907
|
</pre>
|
833
908
|
<p>Help message:</p>
|
834
909
|
<pre class="language-console">
|
835
|
-
[bash]$ ruby ex12.rb -h
|
836
|
-
ex12.rb
|
910
|
+
[bash]$ ruby ex12.rb -h <strong>mysql</strong> # !!!!
|
911
|
+
ex12.rb mysql --- connect to mysql
|
837
912
|
|
838
913
|
Usage:
|
839
|
-
$ ex12.rb [<options>]
|
914
|
+
$ ex12.rb mysql [<options>]
|
840
915
|
|
841
916
|
Options:
|
842
|
-
|
843
|
-
|
844
|
-
|
845
|
-
<strong>foo:bar</strong> : test action #3
|
846
|
-
foo:bar:test1 : test action #1
|
917
|
+
<strong>-H, --host=<host> : host name</strong>
|
918
|
+
<strong>-p, --port=<port> : port number</strong>
|
919
|
+
<strong>-u, --user=<user> : user name</strong>
|
847
920
|
</pre>
|
921
|
+
<p>If you want to exclude some options from copying, specify <code>exlude:</code> keyword argument.
|
922
|
+
For example, <code>@copy_options.("hello", exclude: [:help, :lang])</code> copies all options of <code>hello</code> action excluding <code>:help</code> and <code>:lang</code> options.</p>
|
848
923
|
</section>
|
849
|
-
<section class="subsection" id="
|
850
|
-
<h3>
|
924
|
+
<section class="subsection" id="option-error-and-action-error">
|
925
|
+
<h3>Option Error and Action Error</h3>
|
851
926
|
<ul>
|
852
|
-
<li><code>
|
853
|
-
<li><code>
|
854
|
-
|
927
|
+
<li><code>option_error()</code> returns (not raise) <code>Benry::CmdApp::OptionError</code> object.</li>
|
928
|
+
<li><code>action_error()</code> returns (not raise) <code>Benry::CmdApp::ActionError</code> object.</li>
|
929
|
+
<li>These are available in action method.</li>
|
855
930
|
</ul>
|
856
931
|
<p>File: ex13.rb</p>
|
857
932
|
<pre class="language-ruby">
|
858
|
-
|
933
|
+
# coding: utf-8
|
859
934
|
require 'benry/cmdapp'
|
860
935
|
|
861
936
|
class SampleAction < Benry::CmdApp::Action
|
862
937
|
|
863
|
-
@action.("
|
864
|
-
|
865
|
-
|
866
|
-
|
867
|
-
|
868
|
-
|
869
|
-
|
870
|
-
|
871
|
-
|
872
|
-
|
873
|
-
|
874
|
-
|
938
|
+
@action.("invoke openssl command")
|
939
|
+
@option.(:encrypt, "--encrypt", "encrypt a file")
|
940
|
+
@option.(:decrypt, "--decrypt", "decrypt a file")
|
941
|
+
def openssl(filename, encrypt: false, decrypt: false)
|
942
|
+
if encrypt == false && decrypt == false
|
943
|
+
<strong>raise option_error</strong>("Required '--encrypt' or '--decrypt' option.") # !!!!
|
944
|
+
end
|
945
|
+
opt = encrypt ? "enc" : "dec"
|
946
|
+
command = "openssl #{opt} ..."
|
947
|
+
result = system command
|
948
|
+
if result == false
|
949
|
+
<strong>raise action_error</strong>("Command failed: #{command}") # !!!!
|
950
|
+
end
|
875
951
|
end
|
876
952
|
|
877
953
|
end
|
878
954
|
|
879
|
-
|
880
|
-
app = Benry::CmdApp::Application.new(config)
|
881
|
-
exit app.main()
|
955
|
+
exit Benry::CmdApp.main("Sample App")
|
882
956
|
</pre>
|
883
957
|
<p>Output:</p>
|
884
958
|
<pre class="language-console">
|
885
|
-
[bash]$ ruby ex13.rb
|
886
|
-
<strong>
|
887
|
-
|
888
|
-
|
889
|
-
|
959
|
+
[bash]$ ruby ex13.rb openssl file.txt
|
960
|
+
<strong>[ERROR] Required '--encrypt' or '--decrypt' option.</strong> #<== option_error()
|
961
|
+
|
962
|
+
[bash]$ ruby ex13.rb openssl --encrypt file.txt
|
963
|
+
enc: Use -help for summary.
|
964
|
+
<strong>[ERROR] Command failed: openssl enc ...</strong> #<== action_error()
|
965
|
+
From ex13.rb:17:in `openssl'
|
966
|
+
raise action_error("Command failed: #{command}")
|
967
|
+
From ex13.rb:25:in `<main>'
|
968
|
+
exit app.main()
|
969
|
+
</pre>
|
970
|
+
<p>If you want to show all stacktrace, add <code>--debug</code> global option.</p>
|
971
|
+
<pre class="language-console">
|
972
|
+
[bash]$ ruby ex13.rb --debug openssl --encrypt file.txt
|
973
|
+
enc: Use -help for summary.
|
974
|
+
ex13.rb:17:in `openssl': Command failed: openssl enc ... (Benry::CmdApp::ActionError)
|
975
|
+
from /home/yourname/cmdapp.rb:988:in `_invoke_action'
|
976
|
+
from /home/yourname/cmdapp.rb:927:in `start_action'
|
977
|
+
from /home/yourname/cmdapp.rb:1794:in `start_action'
|
978
|
+
from /home/yourname/cmdapp.rb:1627:in `handle_action'
|
979
|
+
from /home/yourname/cmdapp.rb:1599:in `run'
|
980
|
+
from /home/yourname/cmdapp.rb:1571:in `main'
|
890
981
|
</pre>
|
982
|
+
</section>
|
983
|
+
</section>
|
984
|
+
<section class="section" id="advanced-feature">
|
985
|
+
<h2>Advanced Feature</h2>
|
986
|
+
<section class="subsection" id="category-of-action">
|
987
|
+
<h3>Category of Action</h3>
|
891
988
|
<ul>
|
892
|
-
<li>
|
989
|
+
<li><code>category "foo:bar:"</code> in action class adds prefix <code>foo:bar:</code> to each action name.</li>
|
990
|
+
<li>Category name should be specified as a prefix string ending with <code>:</code>. For example, <code>category "foo:"</code> is OK but <code>category "foo"</code> will be error.</li>
|
991
|
+
<li>Symbol is not allowed. For example, <code>category :foo</code> will be error.</li>
|
992
|
+
<li>Method name <code>def baz__test()</code> with <code>category "foo:bar:"</code> results in the action name <code>foo:bar:baz:test</code>.</li>
|
893
993
|
</ul>
|
894
|
-
<p>File:
|
994
|
+
<p>File: ex21.rb</p>
|
895
995
|
<pre class="language-ruby">
|
896
|
-
|
996
|
+
# coding: utf-8
|
897
997
|
require 'benry/cmdapp'
|
898
998
|
|
899
|
-
class
|
900
|
-
|
901
|
-
@action.("test #1")
|
902
|
-
def test1()
|
903
|
-
run_action_once("test2")
|
904
|
-
end
|
999
|
+
class SampleAction < Benry::CmdApp::Action
|
1000
|
+
<strong>category "foo:bar:"</strong> # !!!!
|
905
1001
|
|
906
|
-
@action.("test #
|
907
|
-
def
|
908
|
-
|
1002
|
+
@action.("test action #1")
|
1003
|
+
def <strong>test1</strong>() # action name: 'foo:bar:test1'
|
1004
|
+
puts __method__ #=> test1
|
1005
|
+
puts methods().grep(/test1/) #=> foo__bar__test1
|
909
1006
|
end
|
910
1007
|
|
911
|
-
@action.("test #
|
912
|
-
def
|
913
|
-
|
1008
|
+
@action.("test action #2")
|
1009
|
+
def <strong>baz__test2</strong>() # action name: 'foo:bar:baz:test2'
|
1010
|
+
puts __method__ #=> baz__test2
|
1011
|
+
puts methods().grep(/test2/) #=> foo__bar__baz__test2
|
914
1012
|
end
|
915
1013
|
|
916
1014
|
end
|
917
1015
|
|
918
|
-
|
919
|
-
app = Benry::CmdApp::Application.new(config)
|
920
|
-
exit app.main()
|
1016
|
+
exit Benry::CmdApp.main("sample app")
|
921
1017
|
</pre>
|
922
1018
|
<p>Output:</p>
|
923
1019
|
<pre class="language-console">
|
924
|
-
[bash]$ ruby
|
925
|
-
|
1020
|
+
[bash]$ ruby ex21.rb -l
|
1021
|
+
Actions:
|
1022
|
+
<strong>foo:bar:baz:test2</strong> : test action #2
|
1023
|
+
<strong>foo:bar:test1</strong> : test action #1
|
1024
|
+
help : print help message (of action if specified)
|
1025
|
+
|
1026
|
+
[bash]$ ruby ex21.rb <strong>foo:bar:test1</strong>
|
1027
|
+
test1 # <== puts __method__
|
1028
|
+
foo__bar__test1 # <== puts methods().grep(/test1/)
|
926
1029
|
|
927
|
-
[bash]$ ruby
|
928
|
-
|
1030
|
+
[bash]$ ruby ex21.rb <strong>foo:bar:baz:test2</strong>
|
1031
|
+
baz__test2 # <== puts __method__
|
1032
|
+
foo__bar__baz__test2 # <== puts methods().grep(/test1/)
|
929
1033
|
</pre>
|
930
|
-
|
931
|
-
|
932
|
-
<
|
1034
|
+
<p>(INTERNAL MECHANISM):
|
1035
|
+
As shown in the above output, Benry-CmdApp internally renames <code>test1()</code> and <code>baz__test2()</code> methods within category <code>foo:bar:</code> to <code>foo__bar__test1()</code> and <code>foo__bar__baz__test2()</code> respectively.
|
1036
|
+
<code>__method__</code> seems to keep original method name, but don't be fooled, methods are renamed indeed.
|
1037
|
+
Due to this mechanism, it is possible to define the same name methods in different categories with no confliction.</p>
|
933
1038
|
<ul>
|
934
|
-
<li>
|
1039
|
+
<li><code>category()</code> can take a description text of category.
|
1040
|
+
For example, <code>category "foo:", "Bla bla"</code> registers <code>"Bla bla</code> as a description of category <code>foo:</code>.
|
1041
|
+
Description of category is displayed in list of category list.
|
1042
|
+
See <a href="#action-list-and-prefix-list">Action List and Prefix List</a> section for details.</li>
|
935
1043
|
</ul>
|
936
|
-
|
1044
|
+
</section>
|
1045
|
+
<section class="subsection" id="nested-category">
|
1046
|
+
<h3>Nested Category</h3>
|
1047
|
+
<p><code>category()</code> can take a block which represents sub-category.</p>
|
1048
|
+
<p>File: ex22.rb</p>
|
937
1049
|
<pre class="language-ruby">
|
938
|
-
|
1050
|
+
# coding: utf-8
|
939
1051
|
require 'benry/cmdapp'
|
940
1052
|
|
941
|
-
class
|
942
|
-
<strong>
|
1053
|
+
class GitAction < Benry::CmdApp::Action
|
1054
|
+
<strong>category "git:"</strong> # top level category
|
943
1055
|
|
944
|
-
@action.("
|
945
|
-
def
|
946
|
-
puts
|
1056
|
+
@action.("show current status in compact format")
|
1057
|
+
def status(path=".")
|
1058
|
+
puts "git status -sb #{path}"
|
947
1059
|
end
|
948
1060
|
|
949
|
-
|
1061
|
+
<strong>category "commit:" do</strong> # sub level category
|
950
1062
|
|
951
|
-
|
1063
|
+
@action.("create a new commit")
|
1064
|
+
def create(message: nil)
|
1065
|
+
puts "git commit"
|
1066
|
+
end
|
952
1067
|
|
953
|
-
|
954
|
-
app = Benry::CmdApp::Application.new(config)
|
955
|
-
exit app.main()
|
956
|
-
</pre>
|
957
|
-
<p>Output:</p>
|
958
|
-
<pre class="language-console">
|
959
|
-
[bash]$ ruby ex15.rb <strong>test</strong> # alias name
|
960
|
-
test1
|
1068
|
+
end
|
961
1069
|
|
962
|
-
|
963
|
-
test1
|
964
|
-
</pre>
|
965
|
-
<p>Help message:</p>
|
966
|
-
<pre class="language-console">
|
967
|
-
[bash]$ ruby ex15.rb -h
|
968
|
-
ex15.rb -- sample app
|
1070
|
+
<strong>category "branch:" do</strong> # sub level category
|
969
1071
|
|
970
|
-
|
971
|
-
|
1072
|
+
@action.("create a new branch")
|
1073
|
+
def create(branch)
|
1074
|
+
puts "git checkout -b #{branch}"
|
1075
|
+
end
|
972
1076
|
|
973
|
-
|
974
|
-
|
1077
|
+
end
|
1078
|
+
|
1079
|
+
end
|
975
1080
|
|
1081
|
+
exit Benry::CmdApp.main("sample app")
|
1082
|
+
</pre>
|
1083
|
+
<p>Output:</p>
|
1084
|
+
<pre class="language-console">
|
1085
|
+
[bash]$ ruby ex22.rb -l
|
976
1086
|
Actions:
|
977
|
-
|
978
|
-
<strong>
|
1087
|
+
<strong>git:branch:</strong>create : create a new branch
|
1088
|
+
<strong>git:commit:</strong>create : create a new commit
|
1089
|
+
<strong>git:</strong>status : show current status in compact format
|
1090
|
+
help : print help message (of action if specified)
|
979
1091
|
</pre>
|
980
|
-
<
|
981
|
-
<
|
982
|
-
</ul>
|
983
|
-
<p>File: ex16.rb</p>
|
1092
|
+
<p>Block of <code>category()</code> is nestable.</p>
|
1093
|
+
<p>File: ex23.rb</p>
|
984
1094
|
<pre class="language-ruby">
|
985
|
-
|
1095
|
+
# coding: utf-8
|
986
1096
|
require 'benry/cmdapp'
|
987
1097
|
|
988
|
-
class
|
1098
|
+
class GitAction < Benry::CmdApp::Action
|
1099
|
+
|
1100
|
+
<strong>category "git:" do</strong> # top level category
|
1101
|
+
|
1102
|
+
@action.("show current status in compact format")
|
1103
|
+
def status(path=".")
|
1104
|
+
puts "git status -sb #{path}"
|
1105
|
+
end
|
1106
|
+
|
1107
|
+
<strong>category "commit:" do</strong> # sub level category
|
1108
|
+
|
1109
|
+
@action.("create a new commit")
|
1110
|
+
def create(message: nil)
|
1111
|
+
puts "git commit"
|
1112
|
+
end
|
1113
|
+
|
1114
|
+
end
|
1115
|
+
|
1116
|
+
<strong>category "branch:" do</strong> # sub level category
|
1117
|
+
|
1118
|
+
@action.("create a new branch")
|
1119
|
+
def create(branch)
|
1120
|
+
puts "git checkout -b #{branch}"
|
1121
|
+
end
|
989
1122
|
|
990
|
-
@action.("print greeting message")
|
991
|
-
@option.(:lang, "-l, --lang=<lang>", "language", enum: ["en", "fr", "it"])
|
992
|
-
def hello(user="world", lang: "en")
|
993
|
-
case lang
|
994
|
-
when "en" ; puts "Hello, #{user}!"
|
995
|
-
when "fr" ; puts "Bonjour, #{user}!"
|
996
|
-
when "it" ; puts "Ciao, #{user}!"
|
997
|
-
else
|
998
|
-
raise "#{lang}: unknown language."
|
999
1123
|
end
|
1124
|
+
|
1000
1125
|
end
|
1001
1126
|
|
1002
1127
|
end
|
1003
1128
|
|
1004
|
-
Benry::CmdApp.
|
1005
|
-
Benry::CmdApp.action_alias("ciao" , "hello", <strong>"Bob", "-l", "it"</strong>) # !!!!
|
1006
|
-
|
1007
|
-
config = Benry::CmdApp::Config.new("sample app")
|
1008
|
-
app = Benry::CmdApp::Application.new(config)
|
1009
|
-
exit app.main()
|
1129
|
+
exit Benry::CmdApp.main("sample app")
|
1010
1130
|
</pre>
|
1011
1131
|
<p>Output:</p>
|
1012
1132
|
<pre class="language-console">
|
1013
|
-
[bash]$ ruby
|
1014
|
-
|
1015
|
-
|
1016
|
-
|
1017
|
-
|
1018
|
-
|
1019
|
-
[bash]$ ruby ex16.rb <strong>bonjour Alice</strong> # !!!!
|
1020
|
-
Bonjour, Alice!
|
1021
|
-
|
1022
|
-
[bash]$ ruby ex16.rb <strong>ciao</strong> # !!!!
|
1023
|
-
Ciao, Bob!
|
1133
|
+
[bash]$ ruby ex23.rb -l
|
1134
|
+
Actions:
|
1135
|
+
git:branch:create : create a new branch
|
1136
|
+
git:commit:create : create a new commit
|
1137
|
+
git:status : show current status in compact format
|
1138
|
+
help : print help message (of action if specified)
|
1024
1139
|
</pre>
|
1025
1140
|
</section>
|
1026
|
-
<section class="subsection" id="
|
1027
|
-
<h3>
|
1141
|
+
<section class="subsection" id="category-action-or-alias">
|
1142
|
+
<h3>Category Action or Alias</h3>
|
1028
1143
|
<ul>
|
1029
|
-
<li><code>
|
1030
|
-
In this case, action <code>test1</code> will be invoked if action name not specified in command-line.</li>
|
1031
|
-
<li>Default action name is shown in help message.</li>
|
1144
|
+
<li><code>category "foo:bar:", action: "blabla"</code> defines <code>foo:bar</code> action (instead of <code>foo:bar:blabla</code>) with <code>blabla()</code> method.</li>
|
1032
1145
|
</ul>
|
1033
|
-
<p>File:
|
1146
|
+
<p>File: ex24.rb</p>
|
1034
1147
|
<pre class="language-ruby">
|
1035
|
-
|
1148
|
+
# coding: utf-8
|
1036
1149
|
require 'benry/cmdapp'
|
1037
1150
|
|
1038
1151
|
class SampleAction < Benry::CmdApp::Action
|
1152
|
+
category "foo:bar:", <strong>action: "test3"</strong> # !!!!
|
1039
1153
|
|
1040
1154
|
@action.("test action #1")
|
1041
|
-
def test1()
|
1155
|
+
def test1() # action name: 'foo:bar:test1'
|
1156
|
+
puts __method__
|
1157
|
+
end
|
1158
|
+
|
1159
|
+
@action.("test action #3")
|
1160
|
+
def <strong>test3</strong>() # action name: 'foo:bar'
|
1042
1161
|
puts __method__
|
1043
1162
|
end
|
1044
1163
|
|
1045
1164
|
end
|
1046
1165
|
|
1047
|
-
|
1048
|
-
<strong>config.default_action = "test1"</strong> # !!!!
|
1049
|
-
app = Benry::CmdApp::Application.new(config)
|
1050
|
-
exit app.main()
|
1166
|
+
exit Benry::CmdApp.main("sample app")
|
1051
1167
|
</pre>
|
1052
1168
|
<p>Output:</p>
|
1053
1169
|
<pre class="language-console">
|
1054
|
-
[bash]$ ruby
|
1055
|
-
|
1170
|
+
[bash]$ ruby ex24.rb -l
|
1171
|
+
Actions:
|
1172
|
+
<strong>foo:bar</strong> : test action #3 # !!!! not 'foo:bar:test3'
|
1173
|
+
foo:bar:test1 : test action #1
|
1174
|
+
help : print help message (of action if specified)
|
1056
1175
|
|
1057
|
-
[bash]$
|
1176
|
+
[bash]$ ruby ex24.rb foo:bar:test1
|
1058
1177
|
test1
|
1059
|
-
|
1060
|
-
<
|
1061
|
-
|
1062
|
-
|
1063
|
-
|
1178
|
+
|
1179
|
+
[bash]$ ruby ex24.rb <strong>foo:bar:test3</strong> # !!!! not available because renamed
|
1180
|
+
[ERROR] foo:bar:test3: Action not found.
|
1181
|
+
|
1182
|
+
[bash]$ ruby ex24.rb <strong>foo:bar</strong> # !!!! available because renamed
|
1183
|
+
test3
|
1184
|
+
</pre>
|
1185
|
+
<ul>
|
1186
|
+
<li>Action name (and also category name) should be specified as a string. Symbol is not allowed.</li>
|
1187
|
+
</ul>
|
1188
|
+
<pre class="language-ruby">
|
1189
|
+
## Symbol is not allowed
|
1190
|
+
category <strong>:foo</strong> #=> error
|
1191
|
+
category "foo:", action: <strong>:blabla</strong> #=> error
|
1192
|
+
</pre>
|
1193
|
+
</section>
|
1194
|
+
<section class="subsection" id="invoke-other-action">
|
1195
|
+
<h3>Invoke Other Action</h3>
|
1196
|
+
<ul>
|
1197
|
+
<li><code>run_action()</code> invokes other action.</li>
|
1198
|
+
<li><code>run_once()</code> invokes other action only once.
|
1199
|
+
This is equivarent to 'prerequisite task' feature in task runner application.</li>
|
1200
|
+
</ul>
|
1201
|
+
<p>File: ex25.rb</p>
|
1202
|
+
<pre class="language-ruby">
|
1203
|
+
# coding: utf-8
|
1204
|
+
require 'benry/cmdapp'
|
1205
|
+
|
1206
|
+
class SampleAction < Benry::CmdApp::Action
|
1207
|
+
|
1208
|
+
@action.("create build dir")
|
1209
|
+
def <strong>prepare</strong>()
|
1210
|
+
puts <strong>"rm -rf build"</strong>
|
1211
|
+
puts <strong>"mkdir build"</strong>
|
1212
|
+
end
|
1213
|
+
|
1214
|
+
@action.("build something")
|
1215
|
+
def build()
|
1216
|
+
<strong>run_once("prepare")</strong> # !!!!
|
1217
|
+
<strong>run_once("prepare")</strong> # skipped because already invoked
|
1218
|
+
puts "echo 'README' > build/README.txt"
|
1219
|
+
puts "zip -r build.zip build"
|
1220
|
+
end
|
1221
|
+
|
1222
|
+
end
|
1223
|
+
|
1224
|
+
exit Benry::CmdApp.main("sample app")
|
1225
|
+
</pre>
|
1226
|
+
<p>Output:</p>
|
1227
|
+
<pre class="language-console">
|
1228
|
+
[bash]$ ruby ex25.rb build
|
1229
|
+
<strong>rm -rf build</strong> # invoked only once!!!!
|
1230
|
+
<strong>mkdir build</strong> # invoked only once!!!!
|
1231
|
+
echo 'README' > build/README.txt
|
1232
|
+
zip -r build.zip build
|
1233
|
+
</pre>
|
1234
|
+
<ul>
|
1235
|
+
<li>Action name should be a string. Symbol is not allowed.</li>
|
1236
|
+
</ul>
|
1237
|
+
<pre class="language-ruby">
|
1238
|
+
## Error because action name is not a string.
|
1239
|
+
run_once(<strong>:prepare</strong>)
|
1240
|
+
</pre>
|
1241
|
+
<ul>
|
1242
|
+
<li>When looped action is detected, Benry-CmdApp aborts action.</li>
|
1243
|
+
</ul>
|
1244
|
+
<p>File: ex26.rb</p>
|
1245
|
+
<pre class="language-ruby">
|
1246
|
+
require 'benry/cmdapp'
|
1247
|
+
|
1248
|
+
class LoopedAction < Benry::CmdApp::Action
|
1249
|
+
|
1250
|
+
@action.("test #1")
|
1251
|
+
def test1()
|
1252
|
+
run_once("test2")
|
1253
|
+
end
|
1254
|
+
|
1255
|
+
@action.("test #2")
|
1256
|
+
def test2()
|
1257
|
+
run_once("test3")
|
1258
|
+
end
|
1259
|
+
|
1260
|
+
@action.("test #3")
|
1261
|
+
def test3()
|
1262
|
+
<strong>run_once("test1")</strong> # !!!!
|
1263
|
+
end
|
1264
|
+
|
1265
|
+
end
|
1266
|
+
|
1267
|
+
exit Benry::CmdApp.main("sample app")
|
1268
|
+
</pre>
|
1269
|
+
<p>Output:</p>
|
1270
|
+
<pre class="language-console">
|
1271
|
+
[bash]$ ruby ex26.rb test1
|
1272
|
+
<strong>[ERROR] test1: Looped action detected.</strong>
|
1273
|
+
|
1274
|
+
[bash]$ ruby ex26.rb test3
|
1275
|
+
<strong>[ERROR] test3: Looped action detected.</strong>
|
1276
|
+
</pre>
|
1277
|
+
</section>
|
1278
|
+
<section class="subsection" id="cleaning-up-block">
|
1279
|
+
<h3>Cleaning Up Block</h3>
|
1280
|
+
<ul>
|
1281
|
+
<li><code>at_end { ... }</code> registers a clean-up block that is invoked at end of process (not at end of action).</li>
|
1282
|
+
<li>This is very useful to register clean-up blocks in preparation action.</li>
|
1283
|
+
<li>Registered blocks are invoked in reverse order of registration.
|
1284
|
+
For example, <code>at_end { puts "A" }; at_end { puts "B" }; at_end { puts "C" }</code> prints "C", "B", and "A" at end of process.</li>
|
1285
|
+
</ul>
|
1286
|
+
<p>File: ex27.rb</p>
|
1287
|
+
<pre class="language-ruby">
|
1288
|
+
# coding: utf-8
|
1289
|
+
require 'benry/cmdapp'
|
1290
|
+
|
1291
|
+
class SampleAction < Benry::CmdApp::Action
|
1292
|
+
|
1293
|
+
@action.("create build dir")
|
1294
|
+
def prepare()
|
1295
|
+
puts "mkdir -p build"
|
1296
|
+
## register cleaning up block in preparation task
|
1297
|
+
<strong>at_end { puts "rm -rf build" }</strong> # !!!!
|
1298
|
+
end
|
1299
|
+
|
1300
|
+
@action.("build something")
|
1301
|
+
def build()
|
1302
|
+
run_once("prepare")
|
1303
|
+
puts "echo 'README' > build/README.txt"
|
1304
|
+
puts "zip -r build.zip build"
|
1305
|
+
end
|
1306
|
+
|
1307
|
+
end
|
1308
|
+
|
1309
|
+
exit Benry::CmdApp.main("sample app")
|
1310
|
+
</pre>
|
1311
|
+
<p>Output:</p>
|
1312
|
+
<pre class="language-console">
|
1313
|
+
[bash]$ ruby ex27.rb build
|
1314
|
+
mkdir -p build
|
1315
|
+
echo 'README' > build/README.txt
|
1316
|
+
zip -r build.zip build
|
1317
|
+
<strong>rm -rf build</strong> # !!!! clean-up block invoked at the end of process !!!!
|
1318
|
+
</pre>
|
1319
|
+
</section>
|
1320
|
+
<section class="subsection" id="alias-for-action">
|
1321
|
+
<h3>Alias for Action</h3>
|
1322
|
+
<p>Alias provides alternative short name of action.</p>
|
1323
|
+
<ul>
|
1324
|
+
<li><code>define_alias()</code> in action class defines an alias with taking action category into account.</li>
|
1325
|
+
<li><code>Benry::CmdApp.define_alias()</code> defines an alias, without taking category into account.</li>
|
1326
|
+
</ul>
|
1327
|
+
<p>File: ex28.rb</p>
|
1328
|
+
<pre class="language-ruby">
|
1329
|
+
# coding: utf-8
|
1330
|
+
require 'benry/cmdapp'
|
1331
|
+
|
1332
|
+
class GitAction < Benry::CmdApp::Action
|
1333
|
+
<strong>category "git:"</strong> # !!!!
|
1334
|
+
|
1335
|
+
@action.("show current status in compact mode")
|
1336
|
+
def status()
|
1337
|
+
puts "git status -sb"
|
1338
|
+
end
|
1339
|
+
|
1340
|
+
<strong>define_alias "st", "status"</strong> # !!!!
|
1341
|
+
## or:
|
1342
|
+
#<strong>Benry::CmdApp.define_alias "st", "git:status"</strong> # !!!!
|
1343
|
+
|
1344
|
+
<strong>category "staging:" do</strong> # !!!!
|
1345
|
+
|
1346
|
+
@action.("show changes in staging area")
|
1347
|
+
def show()
|
1348
|
+
puts "git diff --cached"
|
1349
|
+
end
|
1350
|
+
|
1351
|
+
<strong>define_alias "staged" , "show"</strong> # !!!!
|
1352
|
+
## or:
|
1353
|
+
#<strong>Benry::CmdApp.define_alias "staged", "git:staging:show"</strong> # !!!!
|
1354
|
+
|
1355
|
+
end
|
1356
|
+
|
1357
|
+
end
|
1358
|
+
|
1359
|
+
<strong>Benry::CmdApp.define_alias "git", "git:status"</strong> # !!!!
|
1360
|
+
|
1361
|
+
exit Benry::CmdApp.main("sample app")
|
1362
|
+
</pre>
|
1363
|
+
<p>Help message:</p>
|
1364
|
+
<pre class="language-console">
|
1365
|
+
[bash]$ ruby ex28.rb -h
|
1366
|
+
ex28.rb --- sample app
|
1064
1367
|
|
1065
1368
|
Usage:
|
1066
|
-
$
|
1369
|
+
$ ex28.rb [<options>] <action> [<arguments>...]
|
1067
1370
|
|
1068
1371
|
Options:
|
1069
|
-
-h, --help : print help message (of action if
|
1372
|
+
-h, --help : print help message (of action if specified)
|
1373
|
+
-l, --list : list actions and aliases
|
1374
|
+
-a, --all : list hidden actions/options, too
|
1070
1375
|
|
1071
|
-
Actions:
|
1072
|
-
|
1376
|
+
Actions:
|
1377
|
+
<strong>git : alias for 'git:status'</strong> # !!!!
|
1378
|
+
git:staging:show : show changes in staging area
|
1379
|
+
git:status : show current status in compact mode
|
1380
|
+
help : print help message (of action if specified)
|
1381
|
+
<strong>st : alias for 'git:status'</strong> # !!!!
|
1382
|
+
<strong>staged : alias for 'git:staging:show'</strong> # !!!!
|
1383
|
+
</pre>
|
1384
|
+
<p>Output:</p>
|
1385
|
+
<pre class="language-console">
|
1386
|
+
[bash]$ ruby ex28.rb <strong>st</strong> # alias name
|
1387
|
+
git status -sb
|
1388
|
+
|
1389
|
+
[bash]$ ruby ex28.rb <strong>git:status</strong> # original action name
|
1390
|
+
git status -sb
|
1391
|
+
|
1392
|
+
[bash]$ ruby ex28.rb <strong>staged</strong> # alias name
|
1393
|
+
git diff --cached
|
1394
|
+
|
1395
|
+
[bash]$ ruby ex28.rb <strong>git:staging:show</strong> # original action name
|
1396
|
+
git diff --cached
|
1397
|
+
|
1398
|
+
[bash]$ ruby ex28.rb <strong>git</strong> # alias name
|
1399
|
+
git status -sb
|
1400
|
+
</pre>
|
1401
|
+
<ul>
|
1402
|
+
<li>Aliases are printed in the help message of action (if defined).</li>
|
1403
|
+
</ul>
|
1404
|
+
<pre class="language-console">
|
1405
|
+
[bash]$ ruby ex28.rb git:status -h
|
1406
|
+
ex28.rb git:status --- show current status in compact mode
|
1407
|
+
|
1408
|
+
Usage:
|
1409
|
+
$ ex28.rb git:status
|
1410
|
+
|
1411
|
+
<strong>Aliases:</strong> # !!!!
|
1412
|
+
<strong>git : alias for 'git:status'</strong> # !!!!
|
1413
|
+
<strong>st : alias for 'git:status'</strong> # !!!!
|
1414
|
+
</pre>
|
1415
|
+
<ul>
|
1416
|
+
<li>Both alias and action names should be string. Symbol is not allowed.</li>
|
1417
|
+
</ul>
|
1418
|
+
<pre class="language-ruby">
|
1419
|
+
## Error because alias name is a Symbol.
|
1420
|
+
Benry::CmdApp.define_alias <strong>:test</strong>, "hello"
|
1421
|
+
|
1422
|
+
## Error because action name is a Symbol.
|
1423
|
+
Benry::CmdApp.define_alias "test", <strong>:hello</strong>
|
1424
|
+
</pre>
|
1425
|
+
<ul>
|
1426
|
+
<li>Target action (second argument of `define_alias()`) can be an array of string
|
1427
|
+
which contains action name and options.</li>
|
1428
|
+
</ul>
|
1429
|
+
<p>File: ex29.rb</p>
|
1430
|
+
<pre class="language-ruby">
|
1431
|
+
# coding: utf-8
|
1432
|
+
require 'benry/cmdapp'
|
1433
|
+
|
1434
|
+
class MyAction < Benry::CmdApp::Action
|
1435
|
+
|
1436
|
+
@action.("print greeting message")
|
1437
|
+
@option.(:lang, "-l, --lang=<lang>", "language", enum: ["en", "fr", "it"])
|
1438
|
+
def hello(user="world", lang: "en")
|
1439
|
+
case lang
|
1440
|
+
when "en" ; puts "Hello, #{user}!"
|
1441
|
+
when "fr" ; puts "Bonjour, #{user}!"
|
1442
|
+
when "it" ; puts "Ciao, #{user}!"
|
1443
|
+
else
|
1444
|
+
raise "#{lang}: Unknown language."
|
1445
|
+
end
|
1446
|
+
end
|
1447
|
+
|
1448
|
+
end
|
1449
|
+
|
1450
|
+
Benry::CmdApp.define_alias("bonjour", <strong>["hello", "--lang=fr"]</strong>) # !!!!
|
1451
|
+
Benry::CmdApp.define_alias("ciao" , <strong>["hello", "-l", "it", "Bob"]</strong>) # !!!!
|
1452
|
+
|
1453
|
+
exit Benry::CmdApp.main("sample app")
|
1454
|
+
</pre>
|
1455
|
+
<p>Output:</p>
|
1456
|
+
<pre class="language-console">
|
1457
|
+
[bash]$ ruby ex29.rb hello
|
1458
|
+
Hello, world!
|
1459
|
+
|
1460
|
+
[bash]$ ruby ex29.rb <strong>bonjour</strong> # !!!!
|
1461
|
+
Bonjour, world!
|
1462
|
+
|
1463
|
+
[bash]$ ruby ex29.rb <strong>bonjour Alice</strong> # !!!!
|
1464
|
+
Bonjour, Alice!
|
1465
|
+
|
1466
|
+
[bash]$ ruby ex29.rb <strong>ciao</strong> # !!!!
|
1467
|
+
Ciao, Bob!
|
1468
|
+
</pre>
|
1469
|
+
<ul>
|
1470
|
+
<li>It is not allowed to define an alias for other alias.</li>
|
1471
|
+
</ul>
|
1472
|
+
<pre>
|
1473
|
+
## define an alias
|
1474
|
+
Benry::CmdApp.define_alias(<strong>"hello-it"</strong> , ["hello", "-l", "it"])
|
1475
|
+
|
1476
|
+
## ERROR: define an alias for other alias
|
1477
|
+
Benry::CmdApp.define_alias("ciao" , <strong>"hello-it"</strong>) # !!!!
|
1478
|
+
</pre>
|
1479
|
+
<ul>
|
1480
|
+
<li>Global option <code>-L alias</code> lists all aliases.
|
1481
|
+
This option is hidden in default, therefore not shown in help message but available in default (for debug purpose).</li>
|
1482
|
+
</ul>
|
1483
|
+
<pre class="language-console">
|
1484
|
+
[bash]$ ruby ex30.rb -L alias
|
1485
|
+
Aliases:
|
1486
|
+
git : alias for 'git:status'
|
1073
1487
|
</pre>
|
1074
1488
|
</section>
|
1075
|
-
<section class="subsection" id="
|
1076
|
-
<h3>
|
1489
|
+
<section class="subsection" id="abbreviation-of-category">
|
1490
|
+
<h3>Abbreviation of Category</h3>
|
1491
|
+
<p>Abbreviation of category is a shortcut of category prefix.
|
1492
|
+
For example, when <code>b:</code> is an abbreviation of a category prefix <code>git:branch:</code>, you can invoke <code>git:branch:create</code> action by <code>b:create</code>.</p>
|
1493
|
+
<p>File: ex31.rb</p>
|
1494
|
+
<pre class="language-ruby">
|
1495
|
+
# coding: utf-8
|
1496
|
+
require 'benry/cmdapp'
|
1497
|
+
|
1498
|
+
class GitAction < Benry::CmdApp::Action
|
1499
|
+
|
1500
|
+
category "git:" do
|
1501
|
+
|
1502
|
+
category "branch:" do
|
1503
|
+
|
1504
|
+
@action.("create a new branch")
|
1505
|
+
def create(branch)
|
1506
|
+
puts "git checkout -b #{branch}"
|
1507
|
+
end
|
1508
|
+
|
1509
|
+
end
|
1510
|
+
|
1511
|
+
end
|
1512
|
+
|
1513
|
+
end
|
1514
|
+
|
1515
|
+
## define abbreviation 'b:' of category prefix 'git:branch:'
|
1516
|
+
Benry::CmdApp.<strong>define_abbrev("b:", "git:branch:")</strong> # !!!!
|
1517
|
+
|
1518
|
+
exit Benry::CmdApp.main("sample app")
|
1519
|
+
</pre>
|
1520
|
+
<p>Output:</p>
|
1521
|
+
<pre class="language-console">
|
1522
|
+
[bash]$ ruby ex31.rb <strong>b:create</strong> topic1 # invokes 'git:branch:create' !!!!
|
1523
|
+
git checkout -b topic1
|
1524
|
+
</pre>
|
1525
|
+
<p>Global option <code>-L abbrev</code> lists all abbreviations.
|
1526
|
+
This option is hidden in default, therefore not shown in help message but available in default (for debug purpose).</p>
|
1527
|
+
<pre class="language-console">
|
1528
|
+
[bash]$ ruby ex31.rb <strong>-L abbrev</strong>
|
1529
|
+
Abbreviations:
|
1530
|
+
<strong>b: => git:branch:</strong>
|
1531
|
+
</pre>
|
1532
|
+
</section>
|
1533
|
+
<section class="subsection" id="default-action">
|
1534
|
+
<h3>Default Action</h3>
|
1077
1535
|
<ul>
|
1078
|
-
<li><code>config.
|
1079
|
-
<
|
1080
|
-
<li
|
1536
|
+
<li><code>config.default_action = "test1"</code> defines default action.
|
1537
|
+
In this case, action <code>test1</code> will be invoked if action name not specified in command-line.</li>
|
1538
|
+
<li>Default action name is shown in help message.</li>
|
1081
1539
|
</ul>
|
1082
|
-
<p>File:
|
1540
|
+
<p>File: ex32.rb</p>
|
1083
1541
|
<pre class="language-ruby">
|
1084
|
-
|
1542
|
+
# coding: utf-8
|
1085
1543
|
require 'benry/cmdapp'
|
1086
1544
|
|
1087
1545
|
class SampleAction < Benry::CmdApp::Action
|
@@ -1093,37 +1551,234 @@ class SampleAction < Benry::CmdApp::Action
|
|
1093
1551
|
|
1094
1552
|
end
|
1095
1553
|
|
1096
|
-
|
1097
|
-
<strong>
|
1098
|
-
|
1099
|
-
|
1554
|
+
exit Benry::CmdApp.main("sample app", "1.0.0",
|
1555
|
+
<strong>default_action: "test1"</strong>) # !!!!
|
1556
|
+
## or:
|
1557
|
+
#config = Benry::CmdApp::Config.new("sample app", "1.0.0")
|
1558
|
+
#<strong>config.default_action = "test1"</strong> # !!!!
|
1559
|
+
#app = Benry::CmdApp::Application.new(config)
|
1560
|
+
#exit app.main()
|
1100
1561
|
</pre>
|
1101
1562
|
<p>Output:</p>
|
1102
1563
|
<pre class="language-console">
|
1103
|
-
[bash]$
|
1104
|
-
|
1564
|
+
[bash]$ ruby ex32.rb test1
|
1565
|
+
test1
|
1566
|
+
|
1567
|
+
[bash]$ <strong>ruby ex32.rb</strong> # no action name!!!!
|
1568
|
+
test1
|
1569
|
+
</pre>
|
1570
|
+
<p>Help message:</p>
|
1571
|
+
<pre class="language-console">
|
1572
|
+
[bash]$ ruby ex32.rb -h
|
1573
|
+
ex32.rb --- sample app
|
1105
1574
|
|
1106
1575
|
Usage:
|
1107
|
-
$
|
1576
|
+
$ ex32.rb [<options>] <action> [<arguments>...]
|
1108
1577
|
|
1109
1578
|
Options:
|
1110
|
-
-h, --help : print help message (of action if
|
1579
|
+
-h, --help : print help message (of action if specified)
|
1580
|
+
-l, --list : list actions and aliases
|
1581
|
+
-a, --all : list hidden actions/options, too
|
1111
1582
|
|
1112
|
-
Actions:
|
1583
|
+
Actions: <strong>(default: test1)</strong> # !!!!
|
1584
|
+
help : print help message (of action if specified)
|
1113
1585
|
test1 : test action #1
|
1114
1586
|
</pre>
|
1115
1587
|
</section>
|
1116
|
-
<section class="subsection" id="
|
1117
|
-
<h3>
|
1588
|
+
<section class="subsection" id="action-list-and-category-list">
|
1589
|
+
<h3>Action List and Category List</h3>
|
1590
|
+
<p>When <code>config.default_action</code> is not specified, Benry-CmdAction lists action names if action name is not specified in command-line.</p>
|
1591
|
+
<p>File: ex33.rb</p>
|
1592
|
+
<pre class="language-ruby">
|
1593
|
+
# coding: utf-8
|
1594
|
+
require 'benry/cmdapp'
|
1595
|
+
|
1596
|
+
class SampleAction < Benry::CmdApp::Action
|
1597
|
+
|
1598
|
+
@action.("test action #1")
|
1599
|
+
def <strong>test1</strong>()
|
1600
|
+
end
|
1601
|
+
|
1602
|
+
<strong>category "foo:"</strong> do
|
1603
|
+
|
1604
|
+
@action.("test action #2")
|
1605
|
+
def <strong>test2</strong>()
|
1606
|
+
end
|
1607
|
+
|
1608
|
+
end
|
1609
|
+
|
1610
|
+
<strong>category "bar:"</strong> do
|
1611
|
+
|
1612
|
+
@action.("test action #3")
|
1613
|
+
def <strong>test3</strong>()
|
1614
|
+
end
|
1615
|
+
|
1616
|
+
<strong>category "baz:"</strong> do
|
1617
|
+
|
1618
|
+
@action.("test action #4")
|
1619
|
+
def <strong>test4</strong>()
|
1620
|
+
end
|
1621
|
+
|
1622
|
+
end
|
1623
|
+
|
1624
|
+
end
|
1625
|
+
|
1626
|
+
end
|
1627
|
+
|
1628
|
+
exit Benry::CmdApp.main("sample app")
|
1629
|
+
</pre>
|
1630
|
+
<p>Output:</p>
|
1631
|
+
<pre class="language-console">
|
1632
|
+
[bash]$ ruby ex33.rb # no action name!!!!
|
1633
|
+
Actions:
|
1634
|
+
<strong>bar:baz:test4</strong> : test action #4
|
1635
|
+
<strong>bar:test3</strong> : test action #3
|
1636
|
+
<strong>foo:test2</strong> : test action #2
|
1637
|
+
<strong>help</strong> : print help message (of action if specified)
|
1638
|
+
<strong>test1</strong> : test action #1
|
1639
|
+
</pre>
|
1640
|
+
<p>Command-line option <code>-l, --list</code> also prints the same result of the above example.
|
1641
|
+
This is useful if you specify default action name wit <code>config.default_action</code>.</p>
|
1642
|
+
<p>Action name list contains alias names, too.
|
1643
|
+
If you want to list only action names (or alias names), specify <code>-L action</code> or <code>-L alias</code> option.
|
1644
|
+
See <a href="#q-how-to-list-only-aliases-or-actions-excluding-actions-or-aliases-">Q: How to list only aliases (or actions) excluding actions (or aliases) ?</a> for details.</p>
|
1645
|
+
<p>If category prefix (such as <code>xxx:</code>) is specified instead of action name,
|
1646
|
+
Benry-CmdApp lists action names which have that category prefix.</p>
|
1647
|
+
<p>Output:</p>
|
1648
|
+
<pre class="language-console">
|
1649
|
+
[bash]$ ruby ex33.rb <strong>foo:</strong> # !!!!
|
1650
|
+
Actions:
|
1651
|
+
<strong>foo:test2</strong> : test action #2
|
1652
|
+
|
1653
|
+
[bash]$ ruby ex33.rb <strong>bar:</strong> # !!!!
|
1654
|
+
Actions:
|
1655
|
+
<strong>bar:baz:test4</strong> : test action #4
|
1656
|
+
<strong>bar:test3</strong> : test action #3
|
1657
|
+
</pre>
|
1658
|
+
<p>If <code>:</code> is specified instead of action name, Benry-CmdApp lists top-level category prefixes of action names and number of actions under the each category prefix.</p>
|
1659
|
+
<p>Outuput:</p>
|
1660
|
+
<pre class="language-console">
|
1661
|
+
[bash]$ ruby ex33.rb <strong>:</strong> # !!!!
|
1662
|
+
Categories: (depth=1)
|
1663
|
+
<strong>bar: (2)</strong> # !!! two actions ('bar:test3' and 'bar:baz:test4')
|
1664
|
+
<strong>foo: (1)</strong> # !!! one action ('foo:text2')
|
1665
|
+
</pre>
|
1666
|
+
<p>In the above example, only top-level category prefixes are displayed.
|
1667
|
+
If you specified <code>::</code> instead of <code>:</code>, second-level category prefixes are displayed,
|
1668
|
+
for example <code>foo:xxx:</code> and <code>foo:yyy:</code>.
|
1669
|
+
Of course, <code>:::</code> displays more level category prefixes.</p>
|
1670
|
+
<p>File: ex34.rb</p>
|
1671
|
+
<pre class="language-ruby">
|
1672
|
+
# coding: utf-8
|
1673
|
+
require 'benry/cmdapp'
|
1674
|
+
|
1675
|
+
class GitAction < Benry::CmdApp::Action
|
1676
|
+
<strong>category "git:"</strong>
|
1677
|
+
|
1678
|
+
<strong>category "staging:"</strong> do
|
1679
|
+
@action.("..."); def add(); end
|
1680
|
+
@action.("..."); def show(); end
|
1681
|
+
@action.("..."); def delete(); end
|
1682
|
+
end
|
1683
|
+
|
1684
|
+
<strong>category "branch:"</strong> do
|
1685
|
+
@action.("..."); def list(); end
|
1686
|
+
@action.("..."); def switch(name); end
|
1687
|
+
end
|
1688
|
+
|
1689
|
+
<strong>category "repo:"</strong> do
|
1690
|
+
@action.("..."); def create(); end
|
1691
|
+
@action.("..."); def init(); end
|
1692
|
+
|
1693
|
+
<strong>category "config:"</strong> do
|
1694
|
+
@action.("..."); def add(); end
|
1695
|
+
@action.("..."); def delete(); end
|
1696
|
+
@action.("..."); def list(); end
|
1697
|
+
end
|
1698
|
+
|
1699
|
+
<strong>category "remote:"</strong> do
|
1700
|
+
@action.("..."); def list(); end
|
1701
|
+
@action.("..."); def set(); end
|
1702
|
+
end
|
1703
|
+
|
1704
|
+
end
|
1705
|
+
|
1706
|
+
end
|
1707
|
+
|
1708
|
+
exit Benry::CmdApp.main("sample app")
|
1709
|
+
</pre>
|
1710
|
+
<p>Output:</p>
|
1711
|
+
<pre class="language-console">
|
1712
|
+
[bash]$ ruby ex34.rb <strong>:</strong>
|
1713
|
+
Categories: (depth=<strong>1</strong>)
|
1714
|
+
git: (12)
|
1715
|
+
|
1716
|
+
[bash]$ ruby ex34.rb <strong>::</strong> # !!!!
|
1717
|
+
Categories: (depth=<strong>2</strong>)
|
1718
|
+
git: (0)
|
1719
|
+
<strong>git:branch:</strong> (2)
|
1720
|
+
<strong>git:repo:</strong> (7)
|
1721
|
+
<strong>git:staging:</strong> (3)
|
1722
|
+
|
1723
|
+
[bash]$ ruby ex34.rb <strong>:::</strong> # !!!!
|
1724
|
+
Categories: (depth=<strong>3</strong>)
|
1725
|
+
git: (0)
|
1726
|
+
git:branch: (2)
|
1727
|
+
git:repo: (2)
|
1728
|
+
<strong>git:repo:config:</strong> (3)
|
1729
|
+
<strong>git:repo:remote:</strong> (2)
|
1730
|
+
git:staging: (3)
|
1731
|
+
</pre>
|
1732
|
+
<p><code>category()</code> can take a description of category as second argument.
|
1733
|
+
Descriptions of category are displayed in the category prefix list.</p>
|
1734
|
+
<p>File: ex35.rb</p>
|
1735
|
+
<pre class="language-ruby">
|
1736
|
+
# coding: utf-8
|
1737
|
+
require 'benry/cmdapp'
|
1738
|
+
|
1739
|
+
class SampleAction < Benry::CmdApp::Action
|
1740
|
+
|
1741
|
+
category "foo:"<strong>, "description of Foo"</strong> do
|
1742
|
+
@action.("test action #2")
|
1743
|
+
def test2()
|
1744
|
+
end
|
1745
|
+
end
|
1746
|
+
|
1747
|
+
category "bar:"<strong>, "description of Bar"</strong> do
|
1748
|
+
@action.("test action #3")
|
1749
|
+
def <strong>test3</strong>()
|
1750
|
+
end
|
1751
|
+
|
1752
|
+
category "baz:"<strong>, "description fo Baz"</strong> do
|
1753
|
+
@action.("test action #4")
|
1754
|
+
def <strong>test4</strong>()
|
1755
|
+
end
|
1756
|
+
end
|
1757
|
+
end
|
1758
|
+
|
1759
|
+
end
|
1760
|
+
|
1761
|
+
exit Benry::CmdApp.main("sample app")
|
1762
|
+
</pre>
|
1763
|
+
<p>Output:</p>
|
1764
|
+
<pre class="language-console">
|
1765
|
+
[bash]$ ruby ex35.rb <strong>:</strong> # !!!!
|
1766
|
+
Categories: (depth=1)
|
1767
|
+
bar: (2) : <strong>description of Bar</strong> # !!!!
|
1768
|
+
foo: (1) : <strong>description of Foo</strong> # !!!!
|
1769
|
+
</pre>
|
1770
|
+
</section>
|
1771
|
+
<section class="subsection" id="hidden-action">
|
1772
|
+
<h3>Hidden Action</h3>
|
1118
1773
|
<ul>
|
1119
1774
|
<li>If <code>hidden: true</code> keyword argument passed to <code>@action.()</code>,
|
1120
|
-
or action method is private, then Benry
|
1121
|
-
<li>
|
1122
|
-
<li>
|
1775
|
+
or action method is private, then Benry-CmdApp regards that action as hidden.</li>
|
1776
|
+
<li>Hidden actions are not shown in help message nor action list by default.</li>
|
1777
|
+
<li>Hidden actions are shown when <code>-a</code> or <code>--all</code> option is specified in command-line.</li>
|
1123
1778
|
</ul>
|
1124
|
-
<p>File:
|
1779
|
+
<p>File: ex36.rb</p>
|
1125
1780
|
<pre class="language-ruby">
|
1126
|
-
|
1781
|
+
# coding: utf-8
|
1127
1782
|
require 'benry/cmdapp'
|
1128
1783
|
|
1129
1784
|
class SampleAction < Benry::CmdApp::Action
|
@@ -1147,54 +1802,35 @@ class SampleAction < Benry::CmdApp::Action
|
|
1147
1802
|
|
1148
1803
|
end
|
1149
1804
|
|
1150
|
-
|
1151
|
-
<strong>config.option_all = true</strong> # !!!! enable '-a, --all' option !!!!
|
1152
|
-
app = Benry::CmdApp::Application.new(config)
|
1153
|
-
exit app.main()
|
1805
|
+
exit Benry::CmdApp.main("sample app")
|
1154
1806
|
</pre>
|
1155
|
-
<p>
|
1807
|
+
<p>Action list (without <code>-a</code> nor <code>--all</code>):</p>
|
1156
1808
|
<pre class="language-console">
|
1157
|
-
[bash]$ ruby
|
1158
|
-
ex20.rb -- sample app
|
1159
|
-
|
1160
|
-
Usage:
|
1161
|
-
$ ex20.rb [<options>] [<action> [<arguments>...]]
|
1162
|
-
|
1163
|
-
Options:
|
1164
|
-
-h, --help : print help message (of action if action specified)
|
1165
|
-
-a, --all : list all actions/options including private (hidden) ones
|
1166
|
-
|
1809
|
+
[bash]$ ruby ex36.rb
|
1167
1810
|
Actions:
|
1811
|
+
help : print help message (of action if specified)
|
1168
1812
|
test1 : test action #1
|
1169
1813
|
</pre>
|
1170
|
-
<p>
|
1814
|
+
<p>Action list (with <code>-a</code> or <code>--all</code>):</p>
|
1171
1815
|
<pre class="language-console">
|
1172
|
-
[bash]$ ruby
|
1173
|
-
ex20.rb -- sample app
|
1174
|
-
|
1175
|
-
Usage:
|
1176
|
-
$ ex20.rb [<options>] [<action> [<arguments>...]]
|
1177
|
-
|
1178
|
-
Options:
|
1179
|
-
-h, --help : print help message (of action if action specified)
|
1180
|
-
-a, --all : list all actions/options including private (hidden) ones
|
1181
|
-
|
1816
|
+
[bash]$ ruby ex36.rb <strong>--all</strong> # !!!!
|
1182
1817
|
Actions:
|
1818
|
+
help : print help message (of action if specified)
|
1183
1819
|
test1 : test action #1
|
1184
1820
|
<strong>test2 : test action #2</strong> # !!!!
|
1185
1821
|
<strong>test3 : test action #3</strong> # !!!!
|
1186
1822
|
</pre>
|
1187
1823
|
</section>
|
1188
|
-
<section class="subsection" id="
|
1189
|
-
<h3>
|
1824
|
+
<section class="subsection" id="hidden-option">
|
1825
|
+
<h3>Hidden Option</h3>
|
1190
1826
|
<ul>
|
1191
|
-
<li>Options defined with <code>hidden: true</code> keyword argument are treated as
|
1192
|
-
<li>
|
1193
|
-
<li>
|
1827
|
+
<li>Options defined with <code>hidden: true</code> keyword argument are treated as hidden option.</li>
|
1828
|
+
<li>Hidden options are not shown in help message of action.</li>
|
1829
|
+
<li>Hidden options are shown when <code>-a</code> or <code>--all</code> option is specified in command-line.</li>
|
1194
1830
|
</ul>
|
1195
|
-
<p>File:
|
1831
|
+
<p>File: ex37.rb</p>
|
1196
1832
|
<pre class="language-ruby">
|
1197
|
-
|
1833
|
+
# coding: utf-8
|
1198
1834
|
require 'benry/cmdapp'
|
1199
1835
|
|
1200
1836
|
class SampleAction < Benry::CmdApp::Action
|
@@ -1203,38 +1839,117 @@ class SampleAction < Benry::CmdApp::Action
|
|
1203
1839
|
@option.(:verbose, "-v", "verbose mode")
|
1204
1840
|
@option.(:debug , "-D", "debug mode", <strong>hidden: true</strong>) # !!!!
|
1205
1841
|
def test1(verbose: false, debug: false)
|
1206
|
-
puts "verbose=#{verbose}, debug=#{
|
1842
|
+
puts "verbose=#{verbose}, debug=#{debug}"
|
1207
1843
|
end
|
1208
1844
|
|
1209
1845
|
end
|
1210
1846
|
|
1211
|
-
|
1212
|
-
<strong>config.option_all = true</strong> # !!!! enable '-a, --all' option !!!!
|
1213
|
-
app = Benry::CmdApp::Application.new(config)
|
1214
|
-
exit app.main()
|
1847
|
+
exit Benry::CmdApp.main("sample app")
|
1215
1848
|
</pre>
|
1216
1849
|
<p>Help message (without <code>-a</code> nor <code>--all</code>):</p>
|
1217
1850
|
<pre class="language-console">
|
1218
|
-
[bash]$ ruby
|
1219
|
-
|
1851
|
+
[bash]$ ruby ex37.rb -h test1
|
1852
|
+
ex37.rb test1 --- test action
|
1220
1853
|
|
1221
1854
|
Usage:
|
1222
|
-
$
|
1855
|
+
$ ex37.rb test1 [<options>]
|
1223
1856
|
|
1224
1857
|
Options:
|
1225
1858
|
-v : verbose mode
|
1226
1859
|
</pre>
|
1227
1860
|
<p>Help message (with <code>-a</code> or <code>--all</code>)</p>
|
1228
1861
|
<pre class="language-console">
|
1229
|
-
[bash]$ ruby
|
1230
|
-
|
1862
|
+
[bash]$ ruby ex37.rb -h <strong>--all</strong> test1 # !!!!
|
1863
|
+
ex37.rb test1 --- test action
|
1231
1864
|
|
1232
1865
|
Usage:
|
1233
|
-
$
|
1866
|
+
$ ex37.rb test1 [<options>]
|
1234
1867
|
|
1235
1868
|
Options:
|
1869
|
+
<strong>-h, --help : print help message</strong> # !!!!
|
1236
1870
|
-v : verbose mode
|
1237
|
-
|
1871
|
+
<strong>-D : debug mode</strong> # !!!!
|
1872
|
+
</pre>
|
1873
|
+
<p>In the above example, <code>-h, --help</code> option as well as <code>-D</code> option is shown.
|
1874
|
+
In fact, Benry-CmdApp automatically adds <code>-h, --help</code> option to each action in hidden mode.
|
1875
|
+
Therefore all actions accept <code>-h, --help</code> option.</p>
|
1876
|
+
<p>For this reason, you should NOT define <code>-h</code> or <code>--help</code> options for your actions.</p>
|
1877
|
+
</section>
|
1878
|
+
<section class="subsection" id="important-actions-or-options">
|
1879
|
+
<h3>Important Actions or Options</h3>
|
1880
|
+
<p>It is possible to mark actions or options as important or not.</p>
|
1881
|
+
<ul>
|
1882
|
+
<li>Actions or options marked as important are emphasized in help message.</li>
|
1883
|
+
<li>Actions or options marked as not important are weaken in help message.</li>
|
1884
|
+
</ul>
|
1885
|
+
<p>File: ex38.rb</p>
|
1886
|
+
<pre class="language-ruby">
|
1887
|
+
require 'benry/cmdapp'
|
1888
|
+
|
1889
|
+
class SampleAction < Benry::CmdApp::Action
|
1890
|
+
|
1891
|
+
@action.("important action", <strong>important: true</strong>) # !!!!
|
1892
|
+
def test1()
|
1893
|
+
end
|
1894
|
+
|
1895
|
+
@action.("not important action", <strong>important: false</strong>) # !!!!
|
1896
|
+
def test2()
|
1897
|
+
end
|
1898
|
+
|
1899
|
+
@action.("sample")
|
1900
|
+
@option.(:foo, "--foo", "important option", <strong>important: true</strong>)
|
1901
|
+
@option.(:bar, "--bar", "not important option", <strong>important: false</strong>)
|
1902
|
+
def test3(foo: nil, bar: nil)
|
1903
|
+
end
|
1904
|
+
|
1905
|
+
end
|
1906
|
+
|
1907
|
+
exit Benry::CmdApp.main("sample app")
|
1908
|
+
</pre>
|
1909
|
+
<p>Output:</p>
|
1910
|
+
<pre class="language-console">
|
1911
|
+
[bash]$ ruby ex38.rb -l
|
1912
|
+
Actions:
|
1913
|
+
help : print help message (of action if specified)
|
1914
|
+
<strong>test1 : important action</strong> # !!!! bold font !!!!
|
1915
|
+
<strong>test2 : not important action</strong> # !!!! gray color !!!!
|
1916
|
+
test3 : sample
|
1917
|
+
|
1918
|
+
[bash]$ ruby ex38.rb -h test3
|
1919
|
+
ex38.rb test3 --- sample
|
1920
|
+
|
1921
|
+
Usage:
|
1922
|
+
$ ex38.rb test3 [<options>]
|
1923
|
+
|
1924
|
+
Options:
|
1925
|
+
<strong>--foo : important option</strong> # !!!! bold font !!!!
|
1926
|
+
<strong>--bar : not important option</strong> # !!!! gray color !!!!
|
1927
|
+
</pre>
|
1928
|
+
</section>
|
1929
|
+
<section class="subsection" id="multiple-option">
|
1930
|
+
<h3>Multiple Option</h3>
|
1931
|
+
<p>If you need multiple options like <code>-I</code> option of Ruby,
|
1932
|
+
pass <code>multiple: true</code> to <code>@option.()</code>.</p>
|
1933
|
+
<p>File: ex39.rb</p>
|
1934
|
+
<pre class="language-ruby">
|
1935
|
+
require 'benry/cmdapp'
|
1936
|
+
|
1937
|
+
class TestAction < Benry::CmdApp::Action
|
1938
|
+
|
1939
|
+
@action.("multiple option test")
|
1940
|
+
@option.(:path, "-I <path>", "path", <strong>multiple: true</strong>)
|
1941
|
+
def test_(path: [])
|
1942
|
+
puts "path=#{path.inspect}" #=> path=["/tmp", "/var/tmp"]
|
1943
|
+
end
|
1944
|
+
|
1945
|
+
end
|
1946
|
+
|
1947
|
+
exit Benry::CmdApp.main("test app")
|
1948
|
+
</pre>
|
1949
|
+
<p>Output:</p>
|
1950
|
+
<pre class="language-console">
|
1951
|
+
[bash]$ ruby ex39.rb test <strong>-I /tmp -I /var/tmp</strong> # !!!!
|
1952
|
+
path=<strong>["/tmp", "/var/tmp"]</strong> # !!!!
|
1238
1953
|
</pre>
|
1239
1954
|
</section>
|
1240
1955
|
</section>
|
@@ -1247,77 +1962,112 @@ Options:
|
|
1247
1962
|
<li><code>config.app_desc = "..."</code> sets command description which is shown in help message. (required)</li>
|
1248
1963
|
<li><code>config.app_version = "1.0.0"</code> enables <code>-V</code> and <code>--version</code> option, and prints version number if <code>-V</code> or <code>--version</code> option specified. (default: <code>nil</code>)</li>
|
1249
1964
|
<li><code>config.app_command = "<command>"</code> sets command name which is shown in help message. (default: <code>File.basname($0)</code>)</li>
|
1965
|
+
<li><code>config.app_name = "<string>"</code> sets application name which is shown in help message. (default: same as <code>config.app_command</code>)</li>
|
1966
|
+
<li><code>config.app_usage = "<text>" (or </code>["<text1>", "<text2>", ...]<code>) sets usage string in help message. (default: </code>" <action> [<arguments>...]"``)</li>
|
1250
1967
|
<li><code>config.app_detail = "<text>"</code> sets detailed description of command which is showin in help message. (default: <code>nil</code>)</li>
|
1968
|
+
<li><code>config.backtrace_ignore_rexp = /.../</code> sets regular expression to ignore backtrace when error raised. (default: <code>nil</code>)</li>
|
1969
|
+
<li><code>config.help_description = "<text>"</code> sets text of 'Description:' section in help message. (default: <code>nil</code>)</li>
|
1970
|
+
<li><code>config.help_postamble = {"<Title>:" => "<text>"}</code> sets postamble of help message, such as 'Example:' or 'Tips:'. (default: <code>nil</code>)</li>
|
1251
1971
|
<li><code>config.default_action = "<action>"</code> sets default action name. (default: <code>nil</code>)</li>
|
1252
|
-
<li><code>config.default_help = true</code> prints help message if no action names specified in command-line. (default: <code>false</code>)</li>
|
1253
1972
|
<li><code>config.option_help = true</code> enables <code>-h</code> and <code>--help</code> options. (default: <code>true</code>)</li>
|
1254
|
-
<li><code>config.
|
1973
|
+
<li><code>config.option_version = true</code> enables <code>-V</code> and <code>--version</code> options. (default: <code>true</code> if <code>app_version</code> provided, <code>false</code> if else)</li>
|
1974
|
+
<li><code>config.option_list = true</code> enables <code>-l</code> and <code>--list</code> options. (default: <code>true</code>)</li>
|
1975
|
+
<li><code>config.option_topic = true</code> enables <code>-L <topic></code> option. (default: <code>:hidden</code>)</li>
|
1976
|
+
<li><code>config.option_all = true</code> enables <code>-a</code> and <code>--all</code> options which shows private (hidden) actions and options into help message. (default: <code>true</code>)</li>
|
1255
1977
|
<li><code>config.option_verbose = true</code> enables <code>-v</code> and <code>--verbose</code> options which sets <code>$QUIET_MODE = false</code>. (default: <code>false</code>)</li>
|
1256
1978
|
<li><code>config.option_quiet = true</code> enables <code>-q</code> and <code>--quiet</code> options which sets <code>$QUIET_MODE = true</code>. (default: <code>false</code>)</li>
|
1257
1979
|
<li><code>config.option_color = true</code> enables <code>--color[=<on|off>]</code> option which sets <code>$COLOR_MODE = true/false</code>. This affects to help message colorized or not. (default: <code>false</code>)</li>
|
1258
|
-
<li><code>config.option_debug = true</code> enables <code>-D</code> and <code>--debug</code> options which sets <code>$DEBUG_MODE = true</code>. (default: <code
|
1259
|
-
<li><code>config.option_trace = true</code> enables <code>-T</code> and <code>--trace</code> options
|
1260
|
-
<li><code>config.
|
1261
|
-
<li><code>config.
|
1262
|
-
<li><code>config.
|
1263
|
-
<li><code>config.
|
1264
|
-
<li><code>config.
|
1265
|
-
<li><code>config.format_usage = " $ %s
|
1266
|
-
<li><code>config.
|
1980
|
+
<li><code>config.option_debug = true</code> enables <code>-D</code> and <code>--debug</code> options which sets <code>$DEBUG_MODE = true</code>. (default: <code>:hidden</code>)</li>
|
1981
|
+
<li><code>config.option_trace = true</code> enables <code>-T</code> and <code>--trace</code> options. Entering into and exitting from action are reported when trace mode is on. (default: <code>false</code>)</li>
|
1982
|
+
<li><code>config.option_dryrun = true</code> enables <code>-X</code> and <code>--dryrun</code> options which sets <code>$DRYRUN_MODE = true</code>. (default: <code>false</code>)</li>
|
1983
|
+
<li><code>config.format_option = " %-18s : %s"</code> sets format of options in help message. (default: <code>" %-18s : %s"</code>)</li>
|
1984
|
+
<li><code>config.format_action = " %-18s : %s"</code> sets format of actions in help message. (default: <code>" %-18s : %s"</code>)</li>
|
1985
|
+
<li><code>config.format_usage = " $ %s"</code> sets format of usage in help message. (default: <code>" $ %s"</code>)</li>
|
1986
|
+
<li><code>config.format_avvrev = " %-10s => %s"</code> sets format of abbreviations in output of <code>-L abbrev</code> option. (default: <code>" %-10s => %s"</code>)</li>
|
1987
|
+
<li><code>config.format_usage = " $ %s"</code> sets format of usage in help message. (default: <code>" $ %s"</code>)</li>
|
1988
|
+
<li><code>config.format_category = " $-18s : %s""</code> sets format of category prefixes in output of <code>-L category</code> option. (default: <code>nil</code> which means to use value of <code>config.format_action</code>)</li>
|
1267
1989
|
</ul>
|
1268
|
-
<p>File:
|
1990
|
+
<p>File: ex41.rb</p>
|
1269
1991
|
<pre class="language-ruby">
|
1270
|
-
|
1992
|
+
# coding: utf-8
|
1271
1993
|
require 'benry/cmdapp'
|
1272
1994
|
|
1273
|
-
config = Benry::CmdApp::Config.new("sample app", "1.0.0")
|
1274
|
-
|
1275
|
-
|
1276
|
-
config.class.instance_methods(false).each do |name|
|
1277
|
-
next if name =~ /=$/
|
1278
|
-
next if ! config.class.method_defined?("#{name}=")
|
1279
|
-
val = config.__send__(name)
|
1280
|
-
puts "%-25s = %s" % ["config.#{name}", val.inspect]
|
1995
|
+
config = Benry::CmdApp::Config.new("sample app", "1.0.0", app_name: "Sample App")
|
1996
|
+
config.each(sort: false) do |name, val|
|
1997
|
+
puts "config.%-20s = %s" % [name, val.inspect]
|
1281
1998
|
end
|
1282
1999
|
</pre>
|
1283
2000
|
<p>Output:</p>
|
1284
2001
|
<pre class="language-console">
|
1285
|
-
[bash]$ ruby
|
1286
|
-
config
|
1287
|
-
config
|
1288
|
-
config
|
1289
|
-
config
|
1290
|
-
config
|
1291
|
-
config
|
1292
|
-
config
|
1293
|
-
config
|
1294
|
-
config
|
1295
|
-
config
|
1296
|
-
config
|
1297
|
-
config
|
1298
|
-
config
|
1299
|
-
config
|
1300
|
-
config
|
1301
|
-
config
|
1302
|
-
config
|
1303
|
-
config
|
1304
|
-
config
|
1305
|
-
config
|
1306
|
-
config
|
1307
|
-
config
|
2002
|
+
[bash]$ ruby ex41.rb
|
2003
|
+
config.<strong>app_desc</strong> = "sample app"
|
2004
|
+
config.<strong>app_version</strong> = "1.0.0"
|
2005
|
+
config.<strong>app_name</strong> = "Sample App"
|
2006
|
+
config.<strong>app_command</strong> = "ex41.rb" # == File.basename($0)
|
2007
|
+
config.<strong>app_usage</strong> = nil
|
2008
|
+
config.<strong>app_detail</strong> = nil
|
2009
|
+
config.<strong>default_action</strong> = nil
|
2010
|
+
config.<strong>help_description</strong> = nil
|
2011
|
+
config.<strong>help_postamble</strong> = nil
|
2012
|
+
config.<strong>format_option</strong> = " %-18s : %s"
|
2013
|
+
config.<strong>format_action</strong> = " %-18s : %s"
|
2014
|
+
config.<strong>format_usage</strong> = " $ %s"
|
2015
|
+
config.<strong>format_category</strong> = nil
|
2016
|
+
config.<strong>deco_command</strong> = "\e[1m%s\e[0m" # bold
|
2017
|
+
config.<strong>deco_header</strong> = "\e[1;34m%s\e[0m" # bold, blue
|
2018
|
+
config.<strong>deco_extra</strong> = "\e[2m%s\e[0m" # gray color
|
2019
|
+
config.<strong>deco_strong</strong> = "\e[1m%s\e[0m" # bold
|
2020
|
+
config.<strong>deco_weak</strong> = "\e[2m%s\e[0m" # gray color
|
2021
|
+
config.<strong>deco_hidden</strong> = "\e[2m%s\e[0m" # gray color
|
2022
|
+
config.<strong>deco_debug</strong> = "\e[2m%s\e[0m" # gray color
|
2023
|
+
config.<strong>deco_error</strong> = "\e[31m%s\e[0m" # red
|
2024
|
+
config.<strong>option_help</strong> = true
|
2025
|
+
config.<strong>option_version</strong> = true
|
2026
|
+
config.<strong>option_list</strong> = true
|
2027
|
+
config.<strong>option_topic</strong> = :hidden
|
2028
|
+
config.<strong>option_all</strong> = true
|
2029
|
+
config.<strong>option_verbose</strong> = false
|
2030
|
+
config.<strong>option_quiet</strong> = false
|
2031
|
+
config.<strong>option_color</strong> = false
|
2032
|
+
config.<strong>option_debug</strong> = :hidden
|
2033
|
+
config.<strong>option_trace</strong> = false
|
2034
|
+
config.<strong>option_dryrun</strong> = false
|
2035
|
+
config.<strong>backtrace_ignore_rexp</strong> = nil
|
2036
|
+
config.<strong>trace_mode</strong> = nil
|
2037
|
+
</pre>
|
2038
|
+
<p>You may notice that the value of <code>config.option_debug</code> is <code>:hidden</code>.
|
2039
|
+
If value of <code>config.option_xxxx</code> is <code>:hidden</code>, then corresponding global option is enabled as hidden option.
|
2040
|
+
Therefore you can see <code>--debug</code> option in help message if you add <code>-h</code> and <code>-a</code> (or <code>--all</code>) option.</p>
|
2041
|
+
<p>Help message:</p>
|
2042
|
+
<pre class="language-console">
|
2043
|
+
$ ruby ex37.rb -h <strong>-a</strong> # !!!!
|
2044
|
+
ex37.rb --- sample app
|
2045
|
+
|
2046
|
+
Usage:
|
2047
|
+
$ ex37.rb [<options>] <action> [<arguments>...]
|
2048
|
+
|
2049
|
+
Options:
|
2050
|
+
-h, --help : print help message (of action if specified)
|
2051
|
+
-l, --list : list actions and aliases
|
2052
|
+
-a, --all : list hidden actions/options, too
|
2053
|
+
<strong>--debug : debug mode</strong> # !!!!
|
2054
|
+
|
2055
|
+
Actions:
|
2056
|
+
help : print help message (of action if specified)
|
2057
|
+
test1 : test action
|
1308
2058
|
</pre>
|
1309
2059
|
</section>
|
1310
2060
|
<section class="subsection" id="customization-of-global-options">
|
1311
2061
|
<h3>Customization of Global Options</h3>
|
1312
2062
|
<p>To add custom global options:</p>
|
1313
2063
|
<ul>
|
1314
|
-
<li>(1) Create global option schema object.</li>
|
2064
|
+
<li>(1) Create a global option schema object.</li>
|
1315
2065
|
<li>(2) Add custom options to it.</li>
|
1316
2066
|
<li>(3) Pass it to <code>Application.new()</code>.</li>
|
1317
2067
|
</ul>
|
1318
|
-
<p>File:
|
2068
|
+
<p>File: ex42.rb</p>
|
1319
2069
|
<pre class="language-ruby">
|
1320
|
-
|
2070
|
+
# coding: utf-8
|
1321
2071
|
require 'benry/cmdapp'
|
1322
2072
|
|
1323
2073
|
class SampleAction < Benry::CmdApp::Action
|
@@ -1331,7 +2081,7 @@ end
|
|
1331
2081
|
|
1332
2082
|
## (1) create global option shema
|
1333
2083
|
config = Benry::CmdApp::Config.new("sample app")
|
1334
|
-
<strong>schema = Benry::CmdApp::
|
2084
|
+
<strong>schema = Benry::CmdApp::GlobalOptionSchema.new(config)</strong> # !!!!
|
1335
2085
|
|
1336
2086
|
## (2) add custom options to it
|
1337
2087
|
<strong>schema.add(:logging, "--logging", "enable logging")</strong> # !!!!
|
@@ -1343,78 +2093,100 @@ exit app.main()
|
|
1343
2093
|
</pre>
|
1344
2094
|
<p>Help message:</p>
|
1345
2095
|
<pre class="language-console">
|
1346
|
-
[bash]$ ruby
|
1347
|
-
|
2096
|
+
[bash]$ ruby ex42.rb -h
|
2097
|
+
ex42.rb --- sample app
|
1348
2098
|
|
1349
2099
|
Usage:
|
1350
|
-
$
|
2100
|
+
$ ex42.rb [<options>] <action> [<arguments>...]
|
1351
2101
|
|
1352
2102
|
Options:
|
1353
|
-
-h, --help : print help message (of action if
|
2103
|
+
-h, --help : print help message (of action if specified)
|
2104
|
+
-l, --list : list actions and aliases
|
2105
|
+
-a, --all : list hidden actions/options, too
|
1354
2106
|
<strong>--logging : enable logging</strong> # !!!!
|
1355
2107
|
|
1356
2108
|
Actions:
|
2109
|
+
help : print help message (of action if specified)
|
1357
2110
|
test1 : test action
|
1358
2111
|
</pre>
|
1359
2112
|
<p>To customize global options entirely:</p>
|
1360
2113
|
<ul>
|
1361
|
-
<li>(1) Create empty <code>
|
2114
|
+
<li>(1) Create empty <code>GlobalOptionSchema</code> object.</li>
|
1362
2115
|
<li>(2) Add global options as you want.</li>
|
1363
2116
|
<li>(3) Create and execute Application object with it.</li>
|
1364
2117
|
</ul>
|
1365
|
-
<p>File:
|
2118
|
+
<p>File: ex43.rb</p>
|
1366
2119
|
<pre class="language-ruby">
|
1367
|
-
|
2120
|
+
# coding: utf-8
|
1368
2121
|
require 'benry/cmdapp'
|
1369
2122
|
|
1370
|
-
## (1) Create empty ``
|
1371
|
-
<strong>schema = Benry::CmdApp::
|
2123
|
+
## (1) Create empty ``GlobalOptionSchema`` object.
|
2124
|
+
<strong>schema = Benry::CmdApp::GlobalOptionSchema.new(nil)</strong> # !!!!
|
1372
2125
|
|
1373
2126
|
## (2) Add global options as you want.
|
1374
2127
|
<strong>schema.add</strong>(:help , "-h, --help" , "print help message")
|
1375
2128
|
<strong>schema.add</strong>(:version, "-V, --version", "print version")
|
1376
|
-
<strong>schema.add</strong>(:
|
2129
|
+
<strong>schema.add</strong>(:list , "-l, --list" , "list actions and aliases")
|
2130
|
+
<strong>schema.add</strong>(:all , "-a, --all" , "list hidden actions/options, too")
|
1377
2131
|
<strong>schema.add</strong>(:verbose, "-v, --verbose", "verbose mode")
|
1378
2132
|
<strong>schema.add</strong>(:quiet , "-q, --quiet" , "quiet mode")
|
1379
|
-
<strong>schema.add</strong>(:color , "--color[=<on|off>]", "enable/disable color", type: TrueClass)
|
2133
|
+
<strong>schema.add</strong>(:color , "--color[=<on|off>]", "enable/disable color mode", type: TrueClass)
|
1380
2134
|
<strong>schema.add</strong>(:debug , "-D, --debug" , "set $DEBUG_MODE to true")
|
1381
2135
|
<strong>schema.add</strong>(:trace , "-T, --trace" , "report enter into and exit from action")
|
1382
2136
|
|
1383
2137
|
## (3) Create and execute Application object with it.
|
1384
|
-
config = Benry::CmdApp::Config.new("sample app")
|
2138
|
+
config = Benry::CmdApp::Config.new("sample app", "1.0.0")
|
1385
2139
|
app = Benry::CmdApp::Application.new(config, <strong>schema</strong>) # !!!!
|
1386
2140
|
exit app.main()
|
1387
2141
|
</pre>
|
2142
|
+
<p>Help message:</p>
|
2143
|
+
<pre class="language-console">
|
2144
|
+
[bash]$ ruby ex43.rb -h
|
2145
|
+
ex43.rb (1.0.0) --- sample app
|
2146
|
+
|
2147
|
+
Usage:
|
2148
|
+
$ ex43.rb [<options>] <action> [<arguments>...]
|
2149
|
+
|
2150
|
+
Options:
|
2151
|
+
<strong>-h, --help : print help message</strong>
|
2152
|
+
<strong>-V, --version : print version</strong>
|
2153
|
+
<strong>-l, --list : list actions and aliases</strong>
|
2154
|
+
<strong>-a, --all : list hidden actions/options, too</strong>
|
2155
|
+
<strong>-v, --verbose : verbose mode</strong>
|
2156
|
+
<strong>-q, --quiet : quiet mode</strong>
|
2157
|
+
<strong>--color[=<on|off>] : enable/disable color mode</strong>
|
2158
|
+
<strong>-D, --debug : set $DEBUG_MODE to true</strong>
|
2159
|
+
<strong>-T, --trace : report enter into and exit from action</strong>
|
2160
|
+
|
2161
|
+
Actions:
|
2162
|
+
help : print help message (of action if specified)
|
2163
|
+
</pre>
|
1388
2164
|
</section>
|
1389
2165
|
<section class="subsection" id="customization-of-global-option-behaviour">
|
1390
2166
|
<h3>Customization of Global Option Behaviour</h3>
|
1391
2167
|
<ul>
|
1392
2168
|
<li>(1) Define subclass of <code>Application</code> class.</li>
|
1393
|
-
<li>(2) Override <code>#
|
2169
|
+
<li>(2) Override <code>#toggle_global_options()</code> method.</li>
|
1394
2170
|
<li>(3) Create and execute subclass object of <code>Application</code>.</li>
|
1395
2171
|
</ul>
|
1396
|
-
<p>File:
|
2172
|
+
<p>File: ex44.rb</p>
|
1397
2173
|
<pre class="language-ruby">
|
1398
|
-
|
2174
|
+
# coding: utf-8
|
1399
2175
|
require 'benry/cmdapp'
|
1400
2176
|
|
1401
2177
|
## (1) Define subclass of ``Application`` class.
|
1402
2178
|
<strong>class MyApplication < Benry::CmdApp::Application</strong>
|
1403
2179
|
|
1404
|
-
## (2) Override ``#
|
1405
|
-
<strong>def
|
1406
|
-
<strong>super</strong>
|
1407
|
-
|
1408
|
-
|
1409
|
-
|
1410
|
-
|
1411
|
-
|
1412
|
-
|
1413
|
-
#
|
1414
|
-
# when :trace ; $TRACE_MODE = val
|
1415
|
-
# else ; # do nothing
|
1416
|
-
# end
|
1417
|
-
#end
|
2180
|
+
## (2) Override ``#toggle_global_options()`` method.
|
2181
|
+
<strong>def toggle_global_options(global_opts)</strong>
|
2182
|
+
<strong>status_code = super</strong>
|
2183
|
+
<strong>return status_code if status_code</strong> # `return 0` means "stop process successfully",
|
2184
|
+
# `return 1` means "stop process as failed".
|
2185
|
+
if global_opts[:logging]
|
2186
|
+
require 'logger'
|
2187
|
+
$logger = Logger.new(STDOUT)
|
2188
|
+
end
|
2189
|
+
<strong>return nil</strong> # `return nil` means "continue process".
|
1418
2190
|
end
|
1419
2191
|
|
1420
2192
|
end
|
@@ -1425,14 +2197,14 @@ app = <strong>MyApplication.new(config)</strong> # !!!!
|
|
1425
2197
|
exit app.main()
|
1426
2198
|
</pre>
|
1427
2199
|
<p>Of course, prepending custom module to Application class is also effective way.</p>
|
1428
|
-
<p>File:
|
2200
|
+
<p>File: ex45.rb</p>
|
1429
2201
|
<pre class="language-ruby">
|
1430
|
-
|
2202
|
+
# coding: utf-8
|
1431
2203
|
require 'benry/cmdapp'
|
1432
2204
|
|
1433
2205
|
<strong>module MyApplicationMod</strong>
|
1434
2206
|
|
1435
|
-
<strong>def
|
2207
|
+
<strong>def toggle_global_options(global_opts)</strong>
|
1436
2208
|
# ....
|
1437
2209
|
end
|
1438
2210
|
|
@@ -1449,12 +2221,12 @@ exit app.main()
|
|
1449
2221
|
<h3>Custom Hook of Application</h3>
|
1450
2222
|
<ul>
|
1451
2223
|
<li>(1) Define subclass of Application class.</li>
|
1452
|
-
<li>(2) Override
|
2224
|
+
<li>(2) Override <code>#handle_action()</code> method.</li>
|
1453
2225
|
<li>(3) Create and execute custom application object.</li>
|
1454
2226
|
</ul>
|
1455
|
-
<p>File:
|
2227
|
+
<p>File: ex46.rb</p>
|
1456
2228
|
<pre class="language-ruby">
|
1457
|
-
|
2229
|
+
# coding: utf-8
|
1458
2230
|
require 'benry/cmdapp'
|
1459
2231
|
|
1460
2232
|
class SampleAction < Benry::CmdApp::Action
|
@@ -1469,74 +2241,33 @@ end
|
|
1469
2241
|
## (1) Define subclass of Application class
|
1470
2242
|
<strong>class MyApplication < Benry::CmdApp::Application</strong> # !!!!
|
1471
2243
|
|
1472
|
-
## (2) Override
|
1473
|
-
<strong>def
|
2244
|
+
## (2) Override method
|
2245
|
+
<strong>def handle_action(action, args)</strong> # !!!!
|
1474
2246
|
#p @config
|
1475
|
-
|
1476
|
-
|
1477
|
-
require 'logger'
|
1478
|
-
$logger = Logger.new(STDOUT)
|
1479
|
-
end
|
1480
|
-
## if return :SKIP, action skipped (not invoked).
|
1481
|
-
#return :SKIP
|
2247
|
+
$logger.debug("action=#{action}, args=#{args.inspect}") if $logger
|
2248
|
+
<strong>super</strong> # !!!!
|
1482
2249
|
end
|
1483
2250
|
|
1484
|
-
## or:
|
1485
|
-
#def do_handle_global_options(args, global_opts)
|
1486
|
-
# if global_opts[:logging]
|
1487
|
-
# require 'logger'
|
1488
|
-
# $logger = Logger.new(STDOUT)
|
1489
|
-
# end
|
1490
|
-
# super
|
1491
|
-
#end
|
1492
|
-
|
1493
2251
|
end
|
1494
2252
|
|
1495
2253
|
## (3) create and execute custom application object
|
1496
2254
|
config = Benry::CmdApp::Config.new("sample app")
|
1497
|
-
schema = Benry::CmdApp::
|
2255
|
+
schema = Benry::CmdApp::GlobalOptionSchema.new(config)
|
1498
2256
|
schema.add(:logging, "--logging", "enable logging")
|
1499
2257
|
app = <strong>MyApplication</strong>.new(config, schema) # !!!!
|
1500
2258
|
exit app.main()
|
1501
2259
|
</pre>
|
1502
|
-
<ul>
|
1503
|
-
<li>[EXPERIMENTAL] Instead of defining subclass of Application, you can pass callback block to Application object.</li>
|
1504
|
-
</ul>
|
1505
|
-
<p>File: ex28.rb</p>
|
1506
|
-
<pre class="language-ruby">
|
1507
|
-
#!/usr/bin/env ruby
|
1508
|
-
require 'benry/cmdapp'
|
1509
|
-
|
1510
|
-
class SampleAction < Benry::CmdApp::Action
|
1511
|
-
|
1512
|
-
@action.("test action")
|
1513
|
-
def test1()
|
1514
|
-
$logger.info("logging message") if $logger
|
1515
|
-
end
|
1516
|
-
|
1517
|
-
end
|
1518
|
-
|
1519
|
-
config = Benry::CmdApp::Config.new("sample app")
|
1520
|
-
schema = Benry::CmdApp::AppOptionSchema.new(config)
|
1521
|
-
schema.add(:logging, "--logging", "enable logging")
|
1522
|
-
app = Benry::CmdApp::Application.new(config, schema) <strong>do</strong> # !!!!
|
1523
|
-
<strong>|args, global_opts, config|</strong> # !!!!
|
1524
|
-
if global_opts[:logging] # !!!!
|
1525
|
-
require 'logger' # !!!!
|
1526
|
-
$logger = Logger.new(STDOUT) # !!!!
|
1527
|
-
end # !!!!
|
1528
|
-
#:SKIP # !!!!
|
1529
|
-
end # !!!!
|
1530
|
-
exit app.main()
|
1531
|
-
</pre>
|
1532
2260
|
</section>
|
1533
|
-
<section class="subsection" id="customization-of-
|
1534
|
-
<h3>Customization of
|
1535
|
-
<p>If you want to just add more text into
|
1536
|
-
set
|
1537
|
-
<p>
|
2261
|
+
<section class="subsection" id="customization-of-application-help-message">
|
2262
|
+
<h3>Customization of Application Help Message</h3>
|
2263
|
+
<p>If you want to just add more text into application help message,
|
2264
|
+
set the followings:</p>
|
2265
|
+
<p>.* <code>config.app_detail = <text></code> --- print text before 'Usage:' section.
|
2266
|
+
.* <code>config.help_description = <text></code> --- print text after 'Usage:' section as 'Description:' section.
|
2267
|
+
.* <code>config.help_postamble = {<head> => <text>}</code> --- print at end of help message.</p>
|
2268
|
+
<p>File: ex47.rb</p>
|
1538
2269
|
<pre class="language-ruby">
|
1539
|
-
|
2270
|
+
# coding: utf-8
|
1540
2271
|
require 'benry/cmdapp'
|
1541
2272
|
|
1542
2273
|
class SampleAction < Benry::CmdApp::Action
|
@@ -1548,307 +2279,364 @@ class SampleAction < Benry::CmdApp::Action
|
|
1548
2279
|
|
1549
2280
|
end
|
1550
2281
|
|
1551
|
-
config = Benry::CmdApp::Config.new("sample app")
|
1552
|
-
<strong>config.app_detail
|
1553
|
-
config.
|
1554
|
-
|
1555
|
-
|
1556
|
-
<strong>
|
2282
|
+
config = Benry::CmdApp::Config.new("sample app", "1.0.0")
|
2283
|
+
<strong>config.app_detail = "See https://...."</strong> # !!!!
|
2284
|
+
<strong>config.help_description = " Bla bla bla"</strong> # !!!!
|
2285
|
+
<strong>config.help_postamble = [</strong> # !!!!
|
2286
|
+
<strong> {"Example:" => " $ <command> hello Alice\n"},</strong> # !!!!
|
2287
|
+
<strong> "(Tips: ....)",</strong> # !!!!
|
2288
|
+
<strong>]</strong> # !!!!
|
2289
|
+
|
1557
2290
|
app = Benry::CmdApp::Application.new(config)
|
1558
2291
|
exit app.main()
|
1559
2292
|
</pre>
|
1560
2293
|
<p>Help message:</p>
|
1561
2294
|
<pre class="language-console">
|
1562
|
-
[bash]$ ruby
|
1563
|
-
|
2295
|
+
[bash]$ ruby ex47.rb -h
|
2296
|
+
ex47.rb --- sample app
|
1564
2297
|
|
1565
|
-
<strong>
|
2298
|
+
<strong>See https://....</strong> # !!!!
|
1566
2299
|
|
1567
2300
|
Usage:
|
1568
|
-
$
|
2301
|
+
$ ex47.rb [<options>] <action> [<arguments>...]
|
2302
|
+
|
2303
|
+
<strong>Description:</strong> # !!!!
|
2304
|
+
<strong>Bla bla bla</strong> # !!!!
|
1569
2305
|
|
1570
2306
|
Options:
|
1571
|
-
-h, --help : print help message (of action if
|
2307
|
+
-h, --help : print help message (of action if specified)
|
2308
|
+
-l, --list : list actions and aliases
|
2309
|
+
-a, --all : list hidden actions/options, too
|
1572
2310
|
|
1573
2311
|
Actions:
|
1574
2312
|
hello : test action #1
|
1575
2313
|
|
1576
|
-
<strong>Example:</strong>
|
1577
|
-
<strong>$ <command> hello Alice</strong>
|
2314
|
+
<strong>Example:</strong> # !!!!
|
2315
|
+
<strong>$ <command> hello Alice</strong> # !!!!
|
1578
2316
|
|
1579
|
-
<strong>(Tips: ....)</strong>
|
2317
|
+
<strong>(Tips: ....)</strong> # !!!!
|
1580
2318
|
</pre>
|
1581
2319
|
<p>If you want to change behaviour of building command help message:</p>
|
1582
2320
|
<ul>
|
1583
|
-
<li>(1) Define subclass of <code>Benry::CmdApp::
|
2321
|
+
<li>(1) Define subclass of <code>Benry::CmdApp::ApplicationHelpBuilder</code> class.</li>
|
1584
2322
|
<li>(2) Override methods.</li>
|
1585
2323
|
<li>(3) Create an instance object of the class.</li>
|
1586
2324
|
<li>(4) Pass it to Application object.</li>
|
1587
2325
|
</ul>
|
1588
|
-
<p>File:
|
2326
|
+
<p>File: ex48.rb</p>
|
1589
2327
|
<pre class="language-ruby">
|
1590
|
-
|
2328
|
+
# coding: utf-8
|
1591
2329
|
require 'benry/cmdapp'
|
1592
2330
|
|
1593
2331
|
class SampleAction < Benry::CmdApp::Action
|
1594
2332
|
|
1595
|
-
@action.("greeting message")
|
2333
|
+
@action.("print greeting message")
|
1596
2334
|
def hello(user="world")
|
1597
2335
|
puts "Hello, #{user}!"
|
1598
2336
|
end
|
1599
2337
|
|
1600
2338
|
end
|
1601
2339
|
|
1602
|
-
## (1) Define subclass of ``Benry::CmdApp::
|
1603
|
-
<strong>class MyAppHelpBuilder < Benry::CmdApp::
|
2340
|
+
## (1) Define subclass of ``Benry::CmdApp::ApplicationHelpBuilder`` class.
|
2341
|
+
<strong>class MyAppHelpBuilder < Benry::CmdApp::ApplicationHelpBuilder</strong>
|
1604
2342
|
|
1605
2343
|
## (2) Override methods.
|
1606
|
-
def <strong>build_help_message</strong>(all
|
1607
|
-
super
|
1608
|
-
end
|
1609
|
-
def <strong>build_preamble</strong>(all=false)
|
2344
|
+
def <strong>build_help_message</strong>(gschema, all: false)
|
1610
2345
|
super
|
1611
2346
|
end
|
1612
|
-
def <strong>
|
2347
|
+
def <strong>section_preamble</strong>()
|
1613
2348
|
super
|
1614
2349
|
end
|
1615
|
-
def <strong>
|
2350
|
+
def <strong>section_usage</strong>()
|
1616
2351
|
super
|
1617
2352
|
end
|
1618
|
-
def <strong>
|
2353
|
+
def <strong>section_options</strong>(global_opts_schema, all: false)
|
1619
2354
|
super
|
1620
2355
|
end
|
1621
|
-
def <strong>
|
2356
|
+
def <strong>section_actions</strong>(include_aliases=true, all: false)
|
1622
2357
|
super
|
1623
2358
|
end
|
1624
|
-
def <strong>
|
2359
|
+
def <strong>section_postamble</strong>()
|
1625
2360
|
super
|
1626
2361
|
end
|
2362
|
+
### optional (for `-L <topic>` option)
|
2363
|
+
#def section_candidates(prefix, all: false); super; end
|
2364
|
+
#def section_aliases(all: false); super; end
|
2365
|
+
#def section_abbrevs(all: false); super; end
|
2366
|
+
#def section_categories(depth=0, all: false); super; end
|
1627
2367
|
end
|
1628
2368
|
|
1629
2369
|
## (3) Create an instance object of the class.
|
1630
2370
|
config = Benry::CmdApp::Config.new("sample app")
|
1631
|
-
schema = Benry::CmdApp::
|
2371
|
+
schema = Benry::CmdApp::GlobalOptionSchema.new(config)
|
1632
2372
|
schema.add(:logging, "--logging", "enable logging")
|
1633
|
-
|
2373
|
+
<strong>app_help_builder = MyAppHelpBuilder.new(config)</strong> # !!!!
|
1634
2374
|
|
1635
2375
|
## (4) Pass it to Application object.
|
1636
|
-
app = Benry::CmdApp::Application.new(config, schema, <strong>
|
2376
|
+
app = Benry::CmdApp::Application.new(config, schema, <strong>app_help_builder</strong>) # !!!!
|
1637
2377
|
exit app.main()
|
1638
2378
|
</pre>
|
1639
2379
|
<p>More simple way:</p>
|
1640
2380
|
<ul>
|
1641
|
-
<li>(1) Create a module and override methods of <code>Benry::CmdApp::
|
1642
|
-
<li>(2) Prepend it to <code>Benry::CmdApp::
|
2381
|
+
<li>(1) Create a module and override methods of <code>Benry::CmdApp::ApplicationHelpBuilder</code> class.</li>
|
2382
|
+
<li>(2) Prepend it to <code>Benry::CmdApp::ApplicationHelpBuilder</code> class.</li>
|
1643
2383
|
<li>(3) Create and execute Application object.</li>
|
1644
2384
|
</ul>
|
1645
|
-
<p>File:
|
2385
|
+
<p>File: ex49.rb</p>
|
1646
2386
|
<pre class="language-ruby">
|
1647
|
-
|
2387
|
+
# coding: utf-8
|
1648
2388
|
require 'benry/cmdapp'
|
1649
2389
|
|
1650
2390
|
class SampleAction < Benry::CmdApp::Action
|
1651
2391
|
|
1652
|
-
@action.("greeting message")
|
2392
|
+
@action.("print greeting message")
|
1653
2393
|
def hello(user="world")
|
1654
2394
|
puts "Hello, #{user}!"
|
1655
2395
|
end
|
1656
2396
|
|
1657
2397
|
end
|
1658
2398
|
|
1659
|
-
## (1) Create a module and override methods of ``
|
2399
|
+
## (1) Create a module and override methods of ``ApplicationHelpBuilder`` class.
|
1660
2400
|
<strong>module MyHelpBuilderMod</strong>
|
1661
|
-
def build_help_message(all
|
2401
|
+
def build_help_message(gschema, all: false)
|
1662
2402
|
super
|
1663
2403
|
end
|
1664
|
-
def
|
2404
|
+
def section_preamble()
|
1665
2405
|
super
|
1666
2406
|
end
|
1667
|
-
def
|
2407
|
+
def section_usage()
|
1668
2408
|
super
|
1669
2409
|
end
|
1670
|
-
def
|
2410
|
+
def section_options(global_opts_schema, all: false)
|
1671
2411
|
super
|
1672
2412
|
end
|
1673
|
-
def
|
2413
|
+
def section_actions(include_aliases=true, all: false)
|
1674
2414
|
super
|
1675
2415
|
end
|
1676
|
-
def
|
1677
|
-
super
|
1678
|
-
end
|
1679
|
-
def heading(str)
|
2416
|
+
def section_postamble()
|
1680
2417
|
super
|
1681
2418
|
end
|
2419
|
+
### optional (for `-L <topic>` option)
|
2420
|
+
#def section_candidates(prefix, all: false); super; end
|
2421
|
+
#def section_aliases(all: false); super; end
|
2422
|
+
#def section_abbrevs(all: false); super; end
|
2423
|
+
#def section_categories(depth=0, all: false); super; end
|
1682
2424
|
end
|
1683
2425
|
|
1684
|
-
## (2) Prepend it to ``Benry::CmdApp::
|
1685
|
-
<strong>Benry::CmdApp::
|
2426
|
+
## (2) Prepend it to ``Benry::CmdApp::ApplicationHelpBuilder`` class.
|
2427
|
+
<strong>Benry::CmdApp::ApplicationHelpBuilder.prepend(MyHelpBuilderMod)</strong>
|
1686
2428
|
|
1687
|
-
## (3)
|
1688
|
-
|
1689
|
-
app = Benry::CmdApp::Application.new(config)
|
1690
|
-
exit app.main()
|
2429
|
+
## (3) Run application.
|
2430
|
+
exit Benry::CmdApp.main("sample app")
|
1691
2431
|
</pre>
|
1692
2432
|
</section>
|
1693
2433
|
<section class="subsection" id="customization-of-action-help-message">
|
1694
2434
|
<h3>Customization of Action Help Message</h3>
|
1695
2435
|
<p>If you want to just add more text into action help message,
|
1696
|
-
pass
|
1697
|
-
<
|
2436
|
+
pass the following keyword arguments to <code>@action.()</code>.</p>
|
2437
|
+
<ul>
|
2438
|
+
<li><code>detail: <text></code> --- printed before 'Usage:' section.</li>
|
2439
|
+
<li><code>description: <text></code> --- printed after 'Usage:' section as 'Description:' section, like <code>man</code> command in UNIX.</li>
|
2440
|
+
<li><code>postamble: {<header> => <text>}</code> --- printed at end of help message as a dedicated section.</li>
|
2441
|
+
</ul>
|
2442
|
+
<p>File: ex50.rb</p>
|
1698
2443
|
<pre class="language-ruby">
|
1699
|
-
|
2444
|
+
# coding: utf-8
|
1700
2445
|
require 'benry/cmdapp'
|
1701
2446
|
|
1702
2447
|
class SampleAction < Benry::CmdApp::Action
|
1703
2448
|
|
1704
2449
|
@action.("test action #1",
|
1705
|
-
<strong>detail
|
1706
|
-
<strong>
|
2450
|
+
<strong>detail: "See https://...."</strong>, # !!!!
|
2451
|
+
<strong>description: " Bla bla bla"</strong>, # !!!!
|
2452
|
+
<strong>postamble: {"Example:" => " ...."}</strong>) # !!!!
|
1707
2453
|
def hello(user="world")
|
1708
2454
|
puts "Hello, #{user}!"
|
1709
2455
|
end
|
1710
2456
|
|
1711
2457
|
end
|
1712
2458
|
|
1713
|
-
|
1714
|
-
app = Benry::CmdApp::Application.new(config)
|
1715
|
-
exit app.main()
|
2459
|
+
exit Benry::CmdApp.main("sample app")
|
1716
2460
|
</pre>
|
1717
2461
|
<p>Help message:</p>
|
1718
2462
|
<pre class="language-console">
|
1719
|
-
[bash]$ ruby
|
1720
|
-
|
2463
|
+
[bash]$ ruby ex50.rb -h hello
|
2464
|
+
ex50.rb hello --- test action #1
|
1721
2465
|
|
1722
|
-
<strong>
|
2466
|
+
<strong>See https://....</strong> # !!!!
|
1723
2467
|
|
1724
2468
|
Usage:
|
1725
|
-
$
|
2469
|
+
$ ex50.rb hello [<user>]
|
1726
2470
|
|
1727
|
-
<strong>
|
2471
|
+
<strong>Description:</strong> # !!!!
|
2472
|
+
<strong>Bla bla bla</strong> # !!!!
|
2473
|
+
|
2474
|
+
<strong>Example:</strong>
|
2475
|
+
<strong>....</strong> # !!!!
|
1728
2476
|
</pre>
|
1729
2477
|
<p>If you want to change behaviour of building action help message:</p>
|
1730
2478
|
<ul>
|
1731
|
-
<li>(1)
|
1732
|
-
<li>(2)
|
1733
|
-
<li>(3) Create
|
2479
|
+
<li>(1) Define subclass of <code>ActionHelpBuilder</code> class.</li>
|
2480
|
+
<li>(2) Override methods.</li>
|
2481
|
+
<li>(3) Create an instance object of the class.</li>
|
2482
|
+
<li>(4) Pass it to Application object.</li>
|
1734
2483
|
</ul>
|
1735
|
-
<p>File:
|
2484
|
+
<p>File: ex51.rb</p>
|
1736
2485
|
<pre class="language-ruby">
|
1737
|
-
#!/usr/bin/env ruby
|
1738
2486
|
require 'benry/cmdapp'
|
1739
2487
|
|
1740
2488
|
class SampleAction < Benry::CmdApp::Action
|
1741
2489
|
|
1742
|
-
@action.("greeting message")
|
2490
|
+
@action.("print greeting message")
|
1743
2491
|
def hello(user="world")
|
1744
2492
|
puts "Hello, #{user}!"
|
1745
2493
|
end
|
1746
2494
|
|
1747
2495
|
end
|
1748
2496
|
|
1749
|
-
## (1)
|
1750
|
-
<strong>
|
1751
|
-
|
2497
|
+
## (1) Define subclass of ``ActionHelpBuilder`` class.
|
2498
|
+
<strong>class MyActionHelpBuilder < Benry::CmdApp::ActionHelpBuilder</strong>
|
2499
|
+
## (2) Override methods.
|
2500
|
+
def <strong>build_help_message</strong>(metadata, all: false)
|
1752
2501
|
super
|
1753
2502
|
end
|
1754
|
-
def <strong>
|
2503
|
+
def <strong>section_preamble</strong>(metadata)
|
1755
2504
|
super
|
1756
2505
|
end
|
1757
|
-
def <strong>
|
2506
|
+
def <strong>section_usage</strong>(metadata, all: false)
|
1758
2507
|
super
|
1759
2508
|
end
|
1760
|
-
def <strong>
|
2509
|
+
def <strong>section_description</strong>(metadata)
|
1761
2510
|
super
|
1762
2511
|
end
|
1763
|
-
def <strong>
|
2512
|
+
def <strong>section_options</strong>(metadata, all: false)
|
1764
2513
|
super
|
1765
2514
|
end
|
1766
|
-
def <strong>
|
2515
|
+
def <strong>section_postamble</strong>(metadata)
|
1767
2516
|
super
|
1768
2517
|
end
|
1769
2518
|
end
|
1770
2519
|
|
1771
|
-
## (
|
1772
|
-
Benry::CmdApp::ActionHelpBuilder<strong>.prepend(MyActionHelpBuilderMod)</strong> # !!!!
|
1773
|
-
|
1774
|
-
## (3) Create and execute Application object.
|
2520
|
+
## (3) Create an instance object of the class.
|
1775
2521
|
config = Benry::CmdApp::Config.new("sample app")
|
1776
|
-
|
2522
|
+
<strong>action_help_builder = MyActionHelpBuilder.new(config)</strong>
|
2523
|
+
|
2524
|
+
## (4) Pass it to Application object.
|
2525
|
+
schema = Benry::CmdApp::GlobalOptionSchema.new(config)
|
2526
|
+
app = Benry::CmdApp::Application.new(config, schema, nil, <strong>action_help_builder</strong>)
|
1777
2527
|
exit app.main()
|
1778
2528
|
</pre>
|
1779
2529
|
<p>Another way:</p>
|
1780
2530
|
<ul>
|
1781
|
-
<li>(1)
|
1782
|
-
<li>(2)
|
1783
|
-
<li>(3)
|
2531
|
+
<li>(1) Create a module and override methods of <code>Benry::CmdApp::ActionHelpBuilder</code> class.</li>
|
2532
|
+
<li>(2) Prepend it to <code>Benry::CmdApp::ActionHelpBuilder</code> class.</li>
|
2533
|
+
<li>(3) Run application.</li>
|
1784
2534
|
</ul>
|
1785
|
-
<p>File:
|
2535
|
+
<p>File: ex52.rb</p>
|
1786
2536
|
<pre class="language-ruby">
|
1787
|
-
|
2537
|
+
# coding: utf-8
|
1788
2538
|
require 'benry/cmdapp'
|
1789
2539
|
|
1790
2540
|
class SampleAction < Benry::CmdApp::Action
|
1791
2541
|
|
1792
|
-
@action.("greeting message")
|
2542
|
+
@action.("print greeting message")
|
1793
2543
|
def hello(user="world")
|
1794
2544
|
puts "Hello, #{user}!"
|
1795
2545
|
end
|
1796
2546
|
|
1797
2547
|
end
|
1798
2548
|
|
1799
|
-
## (1)
|
1800
|
-
<strong>
|
1801
|
-
def build_help_message(
|
2549
|
+
## (1) Create a module and override methods of ``ActionHelpBuilder`` class.
|
2550
|
+
<strong>module MyActionHelpBuilderMod</strong>
|
2551
|
+
def <strong>build_help_message</strong>(metadata, all: false)
|
1802
2552
|
super
|
1803
2553
|
end
|
1804
|
-
def
|
2554
|
+
def <strong>section_preamble</strong>(metadata)
|
1805
2555
|
super
|
1806
2556
|
end
|
1807
|
-
def
|
2557
|
+
def <strong>section_usage</strong>(metadata, all: false)
|
1808
2558
|
super
|
1809
2559
|
end
|
1810
|
-
def
|
2560
|
+
def <strong>section_description</strong>(metadata)
|
1811
2561
|
super
|
1812
2562
|
end
|
1813
|
-
def
|
2563
|
+
def <strong>section_options</strong>(metadata, all: false)
|
1814
2564
|
super
|
1815
2565
|
end
|
1816
|
-
def
|
2566
|
+
def <strong>section_postamble</strong>(metadata)
|
1817
2567
|
super
|
1818
2568
|
end
|
1819
2569
|
end
|
1820
2570
|
|
1821
|
-
## (2)
|
1822
|
-
Benry::CmdApp
|
1823
|
-
<strong>remove_const :ACTION_HELP_BUILDER_CLASS</strong>
|
1824
|
-
<strong>const_set :ACTION_HELP_BUILDER_CLASS, MyActionHelpBuilder</strong>
|
1825
|
-
end
|
2571
|
+
## (2) Prepend it to ``Benry::CmdApp::ActionHelpBuilder`` class.
|
2572
|
+
Benry::CmdApp::ActionHelpBuilder<strong>.prepend(MyActionHelpBuilderMod)</strong> # !!!!
|
1826
2573
|
|
1827
|
-
## (3)
|
1828
|
-
|
1829
|
-
|
1830
|
-
|
2574
|
+
## (3) Run application.
|
2575
|
+
exit Benry::CmdApp::main("sample app")
|
2576
|
+
</pre>
|
2577
|
+
</section>
|
2578
|
+
<section class="subsection" id="customization-of-section-title-in-help-message">
|
2579
|
+
<h3>Customization of Section Title in Help Message</h3>
|
2580
|
+
<p>If you want to change section titles such as 'Options:' or 'Actions:'
|
2581
|
+
in the help message, override the constants representing section titles.</p>
|
2582
|
+
<p>The following constants are defined in <code>BaseHelperBuilder</code> class.</p>
|
2583
|
+
<pre class="language-ruby">
|
2584
|
+
module Benry::CmdApp
|
2585
|
+
class BaseHelpBuilder
|
2586
|
+
HEADER_USAGE = "Usage:"
|
2587
|
+
HEADER_DESCRIPTION = "Description:"
|
2588
|
+
HEADER_OPTIONS = "Options:"
|
2589
|
+
HEADER_ACTIONS = "Actions:"
|
2590
|
+
HEADER_ALIASES = "Aliases:"
|
2591
|
+
HEADER_ABBREVS = "Abbreviations:"
|
2592
|
+
HEADER_CATEGORIES = "Categories:"
|
2593
|
+
</pre>
|
2594
|
+
<p>You can override them in <code>ApplicationHelpBuilder</code> or <code>ActionHelpBuilder</code>
|
2595
|
+
classes which are subclass of <code>BaseHandlerBuilder</code> class.</p>
|
2596
|
+
<pre class="language-ruby">
|
2597
|
+
## for example
|
2598
|
+
Benry::CmdApp::ApplicationHelpBuilder::<strong>HEADER_ACTIONS</strong> = "ACTIONS:"
|
2599
|
+
Benry::CmdApp::ActionHelpBuilder::<strong>HEADER_OPTIONS</strong> = "OPTIONS:"
|
2600
|
+
</pre>
|
2601
|
+
<p>If you want to change just decoration of section titles,
|
2602
|
+
set <code>config.deco_header</code>.</p>
|
2603
|
+
<pre class="language-ruby">
|
2604
|
+
config = Benry::CmdApp::Config.new("Test App", "1.0.0")
|
2605
|
+
<strong>config.deco_header = "\e[1;34m%s\e[0m"</strong> # bold, blue
|
2606
|
+
<strong>#config.deco_header = "\e[1;4m%s\e[0m"</strong> # bold, underline
|
1831
2607
|
</pre>
|
1832
2608
|
</section>
|
1833
2609
|
</section>
|
1834
2610
|
<section class="section" id="q--a">
|
1835
2611
|
<h2>Q & A</h2>
|
1836
|
-
<section class="subsection" id="q-how-to-
|
1837
|
-
<h3>Q: How to
|
2612
|
+
<section class="subsection" id="q-how-to-show-all-backtraces-of-exception">
|
2613
|
+
<h3>Q: How to show all backtraces of exception?</h3>
|
2614
|
+
<p>A: Add <code>--deubg</code> option.
|
2615
|
+
Benry-CmdApp catches exceptions and handles their backtrace
|
2616
|
+
automatically in default, but doesn't catch them when <code>--debug</code>
|
2617
|
+
option is specified.</p>
|
2618
|
+
</section>
|
2619
|
+
<section class="subsection" id="q-how-to-specify-description-to-arguments-of-actions">
|
2620
|
+
<h3>Q: How to specify description to arguments of actions?</h3>
|
2621
|
+
<p>A: Can't. It is possible to specify description to actions or options,
|
2622
|
+
but not possible to arguments of actions.</p>
|
2623
|
+
</section>
|
2624
|
+
<section class="subsection" id="q-how-to-append-some-tasks-to-an-existing-action">
|
2625
|
+
<h3>Q: How to append some tasks to an existing action?</h3>
|
1838
2626
|
<p>A: (a) Use method alias, or (b) use prepend.</p>
|
1839
|
-
<p>File:
|
2627
|
+
<p>File: ex61.rb</p>
|
1840
2628
|
<pre class="language-ruby">
|
1841
2629
|
require 'benry/cmdapp'
|
1842
2630
|
|
1843
2631
|
class SampleAction < Benry::CmdApp::Action
|
1844
2632
|
|
1845
2633
|
@action.("test action #1")
|
1846
|
-
def hello(user="world")
|
2634
|
+
def <strong>hello</strong>(user="world")
|
1847
2635
|
puts "Hello, #{user}!"
|
1848
2636
|
end
|
1849
2637
|
|
1850
2638
|
@action.("test action #2")
|
1851
|
-
def hi(user="world")
|
2639
|
+
def <strong>hi</strong>(user="world")
|
1852
2640
|
puts "Hi, #{user}!"
|
1853
2641
|
end
|
1854
2642
|
|
@@ -1856,7 +2644,7 @@ end
|
|
1856
2644
|
|
1857
2645
|
## (a) use method alias
|
1858
2646
|
class SampleAction # open existing class
|
1859
|
-
<strong>alias __old_hello hello</strong> # alias
|
2647
|
+
<strong>alias __old_hello hello</strong> # alias for existing method
|
1860
2648
|
def <strong>hello</strong>(user="world") # override existing method
|
1861
2649
|
puts "---- >8 ---- >8 ----"
|
1862
2650
|
<strong>__old_hello(user)</strong> # call original method
|
@@ -1874,27 +2662,29 @@ end
|
|
1874
2662
|
end
|
1875
2663
|
SampleAction<strong>.prepend(SampleMod)</strong> # prepend it to existing class
|
1876
2664
|
|
1877
|
-
|
1878
|
-
app = Benry::CmdApp::Application.new(config)
|
1879
|
-
exit app.main()
|
2665
|
+
exit Benry::CmdApp.main("sample app")
|
1880
2666
|
</pre>
|
1881
2667
|
<p>Output:</p>
|
1882
2668
|
<pre class="language-console">
|
1883
|
-
[bash]$ ruby
|
2669
|
+
[bash]$ ruby ex61.rb hello
|
1884
2670
|
---- >8 ---- >8 ----
|
1885
2671
|
Hello, world!
|
1886
2672
|
---- 8< ---- 8< ----
|
1887
2673
|
|
1888
|
-
[bash]$ ruby
|
2674
|
+
[bash]$ ruby ex61.rb hi Alice
|
1889
2675
|
~~~~ >8 ~~~~ >8 ~~~~
|
1890
2676
|
Hi, Alice!
|
1891
2677
|
~~~~ 8< ~~~~ 8< ~~~~
|
1892
2678
|
</pre>
|
1893
2679
|
</section>
|
1894
|
-
<section class="subsection" id="q-how-to-
|
1895
|
-
<h3>Q: How to
|
1896
|
-
<p>A:
|
1897
|
-
|
2680
|
+
<section class="subsection" id="q-how-to-delete-an-existing-actionalias">
|
2681
|
+
<h3>Q: How to delete an existing action/alias?</h3>
|
2682
|
+
<p>A: Call <code>Benry::CmdApp.undef_action("<action>")</code> or <code>Benry::CmdApp.undef_alias("<alias>")</code>.</p>
|
2683
|
+
</section>
|
2684
|
+
<section class="subsection" id="q-how-to-re-define-an-existing-action">
|
2685
|
+
<h3>Q: How to re-define an existing action?</h3>
|
2686
|
+
<p>A: First remove the existing action, then re-define the action.</p>
|
2687
|
+
<p>File: ex62.rb</p>
|
1898
2688
|
<pre class="language-ruby">
|
1899
2689
|
require 'benry/cmdapp'
|
1900
2690
|
|
@@ -1907,7 +2697,7 @@ class <strong>SampleAction</strong> < Benry::CmdApp::Action
|
|
1907
2697
|
|
1908
2698
|
end
|
1909
2699
|
|
1910
|
-
Benry::CmdApp<strong>.
|
2700
|
+
Benry::CmdApp<strong>.undef_action("hello")</strong> # !!!!
|
1911
2701
|
|
1912
2702
|
class <strong>OtherAction</strong> < Benry::CmdApp::Action
|
1913
2703
|
|
@@ -1918,33 +2708,30 @@ class <strong>OtherAction</strong> < Benry::CmdApp::Action
|
|
1918
2708
|
|
1919
2709
|
end
|
1920
2710
|
|
1921
|
-
|
1922
|
-
app = Benry::CmdApp::Application.new(config)
|
1923
|
-
exit app.main()
|
2711
|
+
exit Benry::CmdApp.main("sample app")
|
1924
2712
|
</pre>
|
1925
2713
|
<p>Help message:</p>
|
1926
2714
|
<pre class="language-console">
|
1927
|
-
[bash]$ ruby
|
1928
|
-
|
2715
|
+
[bash]$ ruby ex62.rb -h
|
2716
|
+
ex62.rb --- sample app
|
1929
2717
|
|
1930
2718
|
Usage:
|
1931
|
-
$
|
2719
|
+
$ ex62.rb [<options>] <action> [<arguments>...]
|
1932
2720
|
|
1933
2721
|
Options:
|
1934
|
-
-h, --help : print help message (of action if
|
2722
|
+
-h, --help : print help message (of action if specified)
|
2723
|
+
-l, --list : list actions and aliases
|
2724
|
+
-a, --all : list hidden actions/options, too
|
1935
2725
|
|
1936
2726
|
Actions:
|
1937
2727
|
<strong>hello : other action</strong> # !!!!
|
2728
|
+
help : print help message (of action if specified)
|
1938
2729
|
</pre>
|
1939
2730
|
</section>
|
1940
|
-
<section class="subsection" id="q-how-to-
|
1941
|
-
<h3>Q: How to
|
1942
|
-
<p>A: Call <code>Benry::CmdApp.delete_action("<action>")</code> or <code>Benry::CmdApp.delete_alias("<alias>")</code>.</p>
|
1943
|
-
</section>
|
1944
|
-
<section class="subsection" id="q-how-to-show-entering-into-or-exitting-from-action">
|
1945
|
-
<h3>Q: How to Show Entering Into or Exitting From Action?</h3>
|
2731
|
+
<section class="subsection" id="q-how-to-show-entering-into-or-exitting-from-actions">
|
2732
|
+
<h3>Q: How to show entering into or exitting from actions?</h3>
|
1946
2733
|
<p>A: Set <code>config.option_trace = true</code> and pass <code>-T</code> (or <code>--trace</code>) option.</p>
|
1947
|
-
<p>File:
|
2734
|
+
<p>File: ex63.rb</p>
|
1948
2735
|
<pre class="language-ruby">
|
1949
2736
|
require 'benry/cmdapp'
|
1950
2737
|
|
@@ -1957,106 +2744,108 @@ class SampleAction < Benry::CmdApp::Action
|
|
1957
2744
|
|
1958
2745
|
@action.("build")
|
1959
2746
|
def build()
|
1960
|
-
|
2747
|
+
run_once("prepare")
|
1961
2748
|
puts "... build something ..."
|
1962
2749
|
end
|
1963
2750
|
|
1964
2751
|
end
|
1965
2752
|
|
1966
|
-
|
1967
|
-
<strong>
|
1968
|
-
app = Benry::CmdApp::Application.new(config)
|
1969
|
-
exit app.main()
|
2753
|
+
exit Benry::CmdApp.main("sample app", "1.0.0",
|
2754
|
+
<strong>option_trace: true</strong>) # !!!! (or `:hidden`)
|
1970
2755
|
</pre>
|
1971
2756
|
<p>Output:</p>
|
1972
2757
|
<pre class="language-console">
|
1973
|
-
[bash]$ ruby
|
1974
|
-
<strong
|
1975
|
-
<strong
|
2758
|
+
[bash]$ ruby ex63.rb <strong>--trace</strong> build # !!!!
|
2759
|
+
<strong>### enter: build</strong>
|
2760
|
+
<strong>### enter: prepare</strong>
|
1976
2761
|
... prepare something ...
|
1977
|
-
<strong
|
2762
|
+
<strong>### exit: prepare</strong>
|
1978
2763
|
... build something ...
|
1979
|
-
<strong
|
2764
|
+
<strong>### exit: build</strong>
|
1980
2765
|
</pre>
|
1981
2766
|
</section>
|
1982
2767
|
<section class="subsection" id="q-how-to-enabledisable-color-mode">
|
1983
|
-
<h3>Q: How to
|
2768
|
+
<h3>Q: How to enable/disable color mode?</h3>
|
1984
2769
|
<p>A: Set <code>config.option_color = true</code> and pass <code>--color=on</code> or <code>--color=off</code> option.</p>
|
1985
|
-
<p>File:
|
2770
|
+
<p>File: ex64.rb</p>
|
1986
2771
|
<pre class="language-ruby">
|
1987
2772
|
require 'benry/cmdapp'
|
1988
2773
|
|
1989
2774
|
class SampleAction < Benry::CmdApp::Action
|
1990
2775
|
|
1991
|
-
@action.("greeting message")
|
2776
|
+
@action.("print greeting message")
|
1992
2777
|
def hello(user="world")
|
1993
2778
|
puts "Hello, #{user}!"
|
1994
2779
|
end
|
1995
2780
|
|
1996
2781
|
end
|
1997
2782
|
|
1998
|
-
|
1999
|
-
<strong>
|
2000
|
-
app = Benry::CmdApp::Application.new(config)
|
2001
|
-
exit app.main()
|
2783
|
+
exit Benry::CmdApp.main("sample app",
|
2784
|
+
<strong>option_color: true</strong>) # !!!!
|
2002
2785
|
</pre>
|
2003
2786
|
<p>Help message:</p>
|
2004
2787
|
<pre class="language-console">
|
2005
|
-
[bash]$ ruby
|
2006
|
-
|
2788
|
+
[bash]$ ruby ex64.rb -h
|
2789
|
+
ex64.rb --- sample app
|
2007
2790
|
|
2008
2791
|
Usage:
|
2009
|
-
$
|
2792
|
+
$ ex64.rb [<options>] <action> [<arguments>...]
|
2010
2793
|
|
2011
2794
|
Options:
|
2012
|
-
-h, --help : print help message (of action if
|
2795
|
+
-h, --help : print help message (of action if specified)
|
2796
|
+
-l, --list : list actions and aliases
|
2797
|
+
-a, --all : list hidden actions/options, too
|
2013
2798
|
<strong>--color[=<on|off>] : enable/disable color</strong> # !!!!
|
2014
2799
|
|
2015
2800
|
Actions:
|
2016
|
-
hello : greeting message
|
2801
|
+
hello : print greeting message
|
2017
2802
|
|
2018
|
-
[bash]$ ruby
|
2803
|
+
[bash]$ ruby ex64.rb -h <strong>--color=off</strong> # !!!!
|
2019
2804
|
|
2020
|
-
[bash]$ ruby
|
2805
|
+
[bash]$ ruby ex64.rb -h <strong>--color=on</strong> # !!!!
|
2806
|
+
[bash]$ ruby ex64.rb -h <strong>--color</strong> # !!!!
|
2021
2807
|
</pre>
|
2022
2808
|
</section>
|
2023
|
-
<section class="subsection" id="q-how-to-define-
|
2024
|
-
<h3>Q: How to
|
2809
|
+
<section class="subsection" id="q-how-to-define--vvv-style-option">
|
2810
|
+
<h3>Q: How to define <code>-vvv</code> style option?</h3>
|
2025
2811
|
<p>A: Provide block parameter on <code>@option.()</code>.</p>
|
2026
|
-
<p>File:
|
2812
|
+
<p>File: ex65.rb</p>
|
2027
2813
|
<pre class="language-ruby">
|
2028
2814
|
require 'benry/cmdapp'
|
2029
2815
|
|
2030
2816
|
class TestAction < Benry::CmdApp::Action
|
2031
2817
|
|
2032
|
-
@action.("
|
2033
|
-
@option.(:
|
2034
|
-
<strong>
|
2035
|
-
<strong>
|
2036
|
-
|
2037
|
-
|
2038
|
-
|
2039
|
-
<strong>}</strong> # !!!!
|
2040
|
-
def test(path: [])
|
2041
|
-
puts "path=#{path.inspect}" #=> path=["/tmp", "/var/tmp"]
|
2818
|
+
@action.("set verbose level")
|
2819
|
+
@option.(:verbose, "-v", "verbose level") <strong>{|opts, key, val|</strong> # !!!!
|
2820
|
+
<strong>opts[key] ||= 0</strong> # !!!!
|
2821
|
+
<strong>opts[key] += 1</strong> # !!!!
|
2822
|
+
<strong>}</strong> # !!!!
|
2823
|
+
def test_(verbose: 0)
|
2824
|
+
puts "verbose=#{verbose}"
|
2042
2825
|
end
|
2043
2826
|
|
2044
2827
|
end
|
2045
2828
|
|
2046
|
-
|
2047
|
-
app = Benry::CmdApp::Application.new(config)
|
2048
|
-
exit app.main()
|
2829
|
+
exit Benry::CmdApp.main("test app")
|
2049
2830
|
</pre>
|
2050
2831
|
<p>Output:</p>
|
2051
2832
|
<pre class="language-console">
|
2052
|
-
[bash]$ ruby
|
2053
|
-
|
2833
|
+
[bash]$ ruby ex65.rb test <strong>-v</strong> # !!!!
|
2834
|
+
verbose=<strong>1</strong>
|
2835
|
+
[bash]$ ruby ex65.rb test <strong>-vv</strong> # !!!!
|
2836
|
+
verbose=<strong>2</strong>
|
2837
|
+
[bash]$ ruby ex65.rb test <strong>-vvv</strong> # !!!!
|
2838
|
+
verbose=<strong>3</strong>
|
2054
2839
|
</pre>
|
2055
2840
|
</section>
|
2056
|
-
<section class="subsection" id="q-how-to-
|
2057
|
-
<h3>Q: How to
|
2841
|
+
<section class="subsection" id="q-how-to-show-global-option--l-topic-in-help-message">
|
2842
|
+
<h3>Q: How to show global option <code>-L <topic></code> in help message?</h3>
|
2843
|
+
<p>A: Set <code>config.option_topic = true</code> (default: <code>:hidden</code>).</p>
|
2844
|
+
</section>
|
2845
|
+
<section class="subsection" id="q-how-to-specify-detailed-description-of-options">
|
2846
|
+
<h3>Q: How to specify detailed description of options?</h3>
|
2058
2847
|
<p>A: Add <code>detail:</code> keyword argument to <code>@option.()</code>.</p>
|
2059
|
-
<p>File:
|
2848
|
+
<p>File: ex66.rb</p>
|
2060
2849
|
<pre class="language-ruby">
|
2061
2850
|
require 'benry/cmdapp'
|
2062
2851
|
|
@@ -2064,218 +2853,119 @@ class TestAction < Benry::CmdApp::Action
|
|
2064
2853
|
|
2065
2854
|
@action.("detailed description test")
|
2066
2855
|
@option.(:mode, "-m <mode>", "output mode", <strong>detail:</strong> <<"END")
|
2067
|
-
|
2068
|
-
|
2069
|
-
|
2856
|
+
v, verbose: print many output
|
2857
|
+
q, quiet: print litte output
|
2858
|
+
c, compact: print summary output
|
2070
2859
|
END
|
2071
|
-
def
|
2860
|
+
def test_(mode: nil)
|
2072
2861
|
puts "mode=#{mode.inspect}"
|
2073
2862
|
end
|
2074
2863
|
|
2075
2864
|
end
|
2076
2865
|
|
2077
|
-
|
2078
|
-
app = Benry::CmdApp::Application.new(config)
|
2079
|
-
exit app.main()
|
2866
|
+
exit Benry::CmdApp.main("test app")
|
2080
2867
|
</pre>
|
2081
2868
|
<p>Help message:</p>
|
2082
2869
|
<pre class="language-console">
|
2083
|
-
[bash]$ ruby
|
2084
|
-
|
2870
|
+
[bash]$ ruby ex66.rb -h test
|
2871
|
+
ex66.rb test --- detailed description test
|
2085
2872
|
|
2086
2873
|
Usage:
|
2087
|
-
$
|
2874
|
+
$ ex66.rb test [<options>]
|
2088
2875
|
|
2089
2876
|
Options:
|
2090
2877
|
-m <mode> : output mode
|
2091
|
-
|
2092
|
-
|
2093
|
-
|
2094
|
-
</pre>
|
2095
|
-
</section>
|
2096
|
-
<section class="subsection" id="q-how-to-copy-all-options-from-other-action">
|
2097
|
-
<h3>Q: How to Copy All Options from Other Action?</h3>
|
2098
|
-
<p>A: Use <code>@copy_options.()</code>.</p>
|
2099
|
-
<p>File: ex47.rb</p>
|
2100
|
-
<pre class="language-ruby">
|
2101
|
-
require 'benry/cmdapp'
|
2102
|
-
|
2103
|
-
class SampleAction < Benry::CmdApp::Action
|
2104
|
-
|
2105
|
-
@action.("test action #1")
|
2106
|
-
@option.(:verbose, "-v, --verbose", "verbose mode")
|
2107
|
-
@option.(:file, "-f, --file=<file>", "filename")
|
2108
|
-
@option.(:indent, "-i, --indent[=<N>]", "indent")
|
2109
|
-
def test1(verbose: false, file: nil, indent: nil)
|
2110
|
-
puts "verbose=#{verbose}, file=#{file}, indent=#{indent}"
|
2111
|
-
end
|
2112
|
-
|
2113
|
-
@action.("test action #2")
|
2114
|
-
<strong>@copy_options.("test1")</strong> # !!!! copy options from test1 !!!!
|
2115
|
-
@option.(:debug, "-D, --debug", "debug mode")
|
2116
|
-
def test2(verbose: false, file: nil, indent: nil, debug: false)
|
2117
|
-
puts "verbose=#{verbose}, file=#{file}, indent=#{indent}, debug=#{debug}"
|
2118
|
-
end
|
2119
|
-
|
2120
|
-
end
|
2121
|
-
|
2122
|
-
config = Benry::CmdApp::Config.new("sample app")
|
2123
|
-
app = Benry::CmdApp::Application.new(config)
|
2124
|
-
exit app.main()
|
2125
|
-
</pre>
|
2126
|
-
<p>Help message of <code>test2</code> action:</p>
|
2127
|
-
<pre class="language-console">
|
2128
|
-
[bash]$ ruby ex47.rb -h test2
|
2129
|
-
ex47.rb test2 -- test action #2
|
2130
|
-
|
2131
|
-
Usage:
|
2132
|
-
$ ex47.rb test2 [<options>]
|
2133
|
-
|
2134
|
-
Options:
|
2135
|
-
-v, --verbose : verbose mode # copied!!
|
2136
|
-
-f, --file=<file> : filename # copied!!
|
2137
|
-
-i, --indent[=<N>] : indent # copied!!
|
2138
|
-
-D, --debug : debug mode
|
2878
|
+
<strong>v, verbose: print many output</strong>
|
2879
|
+
<strong>q, quiet: print litte output</strong>
|
2880
|
+
<strong>c, compact: print summary output</strong>
|
2139
2881
|
</pre>
|
2140
2882
|
</section>
|
2141
|
-
<section class="subsection" id="q-
|
2142
|
-
<h3>Q:
|
2143
|
-
<p>A:
|
2144
|
-
<p>File: ex48.rb</p>
|
2145
|
-
<pre class="language-ruby">
|
2146
|
-
require 'benry/cmdapp'
|
2147
|
-
|
2148
|
-
class AaaAction < Benry::CmdApp::Action
|
2149
|
-
prefix "aaa", <strong>alias_of:</strong> :print_ # (or) alias_of: "print"
|
2150
|
-
|
2151
|
-
@action.("test #1")
|
2152
|
-
def print_()
|
2153
|
-
puts "test"
|
2154
|
-
end
|
2155
|
-
|
2156
|
-
end
|
2157
|
-
|
2158
|
-
class BbbAction < Benry::CmdApp::Action
|
2159
|
-
prefix "bbb", <strong>action:</strong> :print_ # (or) action: "print"
|
2160
|
-
|
2161
|
-
@action.("test #2")
|
2162
|
-
def print_()
|
2163
|
-
puts "test"
|
2164
|
-
end
|
2165
|
-
|
2166
|
-
end
|
2167
|
-
|
2168
|
-
config = Benry::CmdApp::Config.new("sample app")
|
2169
|
-
app = Benry::CmdApp::Application.new(config)
|
2170
|
-
exit app.main()
|
2171
|
-
</pre>
|
2172
|
-
<p>Help message:</p>
|
2883
|
+
<section class="subsection" id="q-how-to-list-only-aliases-or-actions-excluding-actions-or-aliases-">
|
2884
|
+
<h3>Q: How to list only aliases (or actions) excluding actions (or aliases) ?</h3>
|
2885
|
+
<p>A: Specify global option <code>-L alias</code> or <code>-L action</code>.</p>
|
2173
2886
|
<pre class="language-console">
|
2174
|
-
[bash]$ ruby
|
2175
|
-
|
2176
|
-
|
2177
|
-
|
2178
|
-
|
2179
|
-
|
2180
|
-
|
2181
|
-
|
2182
|
-
|
2887
|
+
[bash]$ ruby gitexample.rb -l
|
2888
|
+
Actions:
|
2889
|
+
git : alias for 'git:status'
|
2890
|
+
git:stage : put changes of files into staging area
|
2891
|
+
git:staged : show changes in staging area
|
2892
|
+
git:status : show status in compact format
|
2893
|
+
git:unstage : remove changes from staging area
|
2894
|
+
stage : alias for 'git:stage'
|
2895
|
+
staged : alias for 'git:staged'
|
2896
|
+
unstage : alias for 'git:unstage'
|
2897
|
+
|
2898
|
+
### list only aliases (ordered by action name automatically)
|
2899
|
+
[bash]$ ruby gitexample.rb <strong>-L alias</strong> # !!!!
|
2900
|
+
Aliases:
|
2901
|
+
stage : alias for 'git:stage'
|
2902
|
+
staged : alias for 'git:staged'
|
2903
|
+
git : alias for 'git:status'
|
2904
|
+
unstage : alias for 'git:unstage'
|
2905
|
+
|
2906
|
+
### list only actions
|
2907
|
+
[bash]$ ruby gitexample.rb <strong>-L action</strong> # !!!!
|
2183
2908
|
Actions:
|
2184
|
-
|
2185
|
-
|
2186
|
-
|
2909
|
+
git:stage : put changes of files into staging area
|
2910
|
+
git:staged : show changes in staging area
|
2911
|
+
git:status : show status in compact format
|
2912
|
+
git:unstage : remove changes from staging area
|
2187
2913
|
</pre>
|
2188
|
-
<p>
|
2189
|
-
|
2914
|
+
<p>Notice that <code>-L alias</code> sorts aliases by action names.
|
2915
|
+
This is the intended behaviour.</p>
|
2190
2916
|
</section>
|
2191
|
-
<section class="subsection" id="q-how-to-change-order-of-options-in-help-message">
|
2192
|
-
<h3>Q: How to
|
2193
|
-
<p>A: Call <code>
|
2194
|
-
<p>File:
|
2917
|
+
<section class="subsection" id="q-how-to-change-the-order-of-options-in-help-message">
|
2918
|
+
<h3>Q: How to change the order of options in help message?</h3>
|
2919
|
+
<p>A: Call <code>GlobalOptionSchema#reorder_options()</code>.</p>
|
2920
|
+
<p>File: ex68.rb</p>
|
2195
2921
|
<pre class="language-ruby">
|
2196
2922
|
require 'benry/cmdapp'
|
2197
2923
|
|
2198
2924
|
config = Benry::CmdApp::Config.new("sample app", "1.0.0",
|
2199
|
-
|
2925
|
+
option_verbose: true,
|
2200
2926
|
option_quiet: true,
|
2201
2927
|
option_color: true,
|
2202
2928
|
)
|
2203
|
-
schema = Benry::CmdApp::
|
2204
|
-
<strong>keys = [:
|
2205
|
-
<strong>schema.
|
2929
|
+
schema = Benry::CmdApp::GlobalOptionSchema.new(config)
|
2930
|
+
<strong>keys = [:verbose, :quiet, :color, :help, :version, :all, :target, :list]</strong> # !!!!
|
2931
|
+
<strong>schema.reorder_options(*keys)</strong> # !!!!
|
2206
2932
|
app = Benry::CmdApp::Application.new(config, schema)
|
2207
2933
|
## or:
|
2208
2934
|
#app = Benry::CmdApp::Application.new(config)
|
2209
|
-
#<strong>app.schema.
|
2935
|
+
#<strong>app.schema.reorder_options(*keys)</strong> # !!!!
|
2210
2936
|
exit app.main()
|
2211
2937
|
</pre>
|
2212
2938
|
<p>Help message:</p>
|
2213
2939
|
<pre class="language-console">
|
2214
|
-
[bash]$ ruby
|
2215
|
-
|
2940
|
+
[bash]$ ruby ex68.rb -h
|
2941
|
+
ex68.rb (1.0.0) --- sample app
|
2216
2942
|
|
2217
2943
|
Usage:
|
2218
|
-
$
|
2944
|
+
$ ex68.rb [<options>] <action> [<arguments>...]
|
2219
2945
|
|
2220
2946
|
Options:
|
2221
|
-
-
|
2947
|
+
-v, --verbose : verbose mode
|
2222
2948
|
-q, --quiet : quiet mode
|
2223
|
-
--color[=<on|off>] :
|
2224
|
-
-h, --help : print help message (of action if
|
2949
|
+
--color[=<on|off>] : color mode
|
2950
|
+
-h, --help : print help message (of action if specified)
|
2225
2951
|
-V, --version : print version
|
2952
|
+
-a, --all : list hidden actions/options, too
|
2953
|
+
-L <topic> : topic list (actions|aliases|categories|abbrevs)
|
2954
|
+
-l, --list : list actions and aliases
|
2226
2955
|
|
2227
2956
|
Actions:
|
2228
|
-
|
2229
|
-
</pre>
|
2230
|
-
</section>
|
2231
|
-
<section class="subsection" id="q-is-it-possible-to-make-action-names-emphasised-or-weaken">
|
2232
|
-
<h3>Q: Is It Possible to Make Action Names Emphasised or Weaken?</h3>
|
2233
|
-
<p>A: Yes. When you pass <code>important: true</code> to <code>@action.()</code>, that action will be printed with unerline in help message. When you pass <code>important: false</code>, that action will be printed in gray color.</p>
|
2234
|
-
<p>File: ex50.rb</p>
|
2235
|
-
<pre class="language-ruby">
|
2236
|
-
require 'benry/cmdapp'
|
2237
|
-
|
2238
|
-
class SampleAction < Benry::CmdApp::Action
|
2239
|
-
|
2240
|
-
@action.("empasized", <strong>important: true</strong>) # !!!!
|
2241
|
-
def test1()
|
2242
|
-
end
|
2243
|
-
|
2244
|
-
@action.("weaken", <strong>important: false</strong>) # !!!!
|
2245
|
-
def test2()
|
2246
|
-
end
|
2247
|
-
|
2248
|
-
end
|
2249
|
-
|
2250
|
-
config = Benry::CmdApp::Config.new("sample app")
|
2251
|
-
app = Benry::CmdApp::Application.new(config)
|
2252
|
-
exit app.main()
|
2253
|
-
</pre>
|
2254
|
-
<p>Help message:</p>
|
2255
|
-
<pre class="language-console">
|
2256
|
-
[bash]$ ruby ex50.rb -h
|
2257
|
-
ex50.rb -- sample app
|
2258
|
-
|
2259
|
-
Usage:
|
2260
|
-
$ ex50.rb [<options>] [<action> [<arguments>...]]
|
2261
|
-
|
2262
|
-
Options:
|
2263
|
-
-h, --help : print help message (of action if action specified)
|
2264
|
-
|
2265
|
-
Actions:
|
2266
|
-
<strong>test1 : empasized</strong> # !!!! printed with underline !!!!
|
2267
|
-
<strong>test2 : weaken</strong> # !!!! printed in gray color !!!!
|
2957
|
+
help : print help message (of action if specified)
|
2268
2958
|
</pre>
|
2269
2959
|
</section>
|
2270
|
-
<section class="subsection" id="q-
|
2271
|
-
<h3>Q:
|
2272
|
-
<p>A:
|
2960
|
+
<section class="subsection" id="q-how-to-add-metadata-to-actions-or-options">
|
2961
|
+
<h3>Q: How to add metadata to actions or options?</h3>
|
2962
|
+
<p>A: Pass <code>tag:</code> keyword argument to <code>@action.()</code> or <code>@option.()</code>.</p>
|
2273
2963
|
<ul>
|
2274
2964
|
<li><code>tag:</code> keyword argument accept any type of value such as symbol, string, array, and so on.</li>
|
2275
|
-
<li>Currenty, Benry
|
2276
|
-
This feature may be used by command-line application or framework based on Benry
|
2965
|
+
<li>Currenty, Benry-CmdApp doesn't provide the good way to use it effectively.
|
2966
|
+
This feature may be used by command-line application or framework based on Benry-CmdApp.</li>
|
2277
2967
|
</ul>
|
2278
|
-
<p>File:
|
2968
|
+
<p>File: ex69.rb</p>
|
2279
2969
|
<pre class="language-ruby">
|
2280
2970
|
require 'benry/cmdapp'
|
2281
2971
|
|
@@ -2291,14 +2981,28 @@ class SampleAction < Benry::CmdApp::Action
|
|
2291
2981
|
|
2292
2982
|
end
|
2293
2983
|
|
2294
|
-
|
2295
|
-
|
2296
|
-
|
2984
|
+
exit Benry::CmdApp.main("sample app")
|
2985
|
+
</pre>
|
2986
|
+
</section>
|
2987
|
+
<section class="subsection" id="q-how-to-remove-common-help-option-from-all-actions">
|
2988
|
+
<h3>Q: How to remove common help option from all actions?</h3>
|
2989
|
+
<p>A: Clears <code>Benry::CmdApp::ACTION_SHARED_OPTIONS</code> which is an array of option item.</p>
|
2990
|
+
<p>File: ex70.rb</p>
|
2991
|
+
<pre class="language-ruby">
|
2992
|
+
require 'benry/cmdapp'
|
2993
|
+
|
2994
|
+
arr = <strong>Benry::CmdApp::ACTION_SHARED_OPTIONS</strong>
|
2995
|
+
arr.clear()
|
2297
2996
|
</pre>
|
2298
2997
|
</section>
|
2998
|
+
<section class="subsection" id="q-is-it-possible-to-show-details-of-actions-and-aliases">
|
2999
|
+
<h3>Q: Is it possible to show details of actions and aliases?</h3>
|
3000
|
+
<p>A: Try global option <code>-L metadata</code>.
|
3001
|
+
It prints detailed data of actions and aliases in YAML format.</p>
|
3002
|
+
</section>
|
2299
3003
|
<section class="subsection" id="q-how-to-make-error-messages-i18ned">
|
2300
|
-
<h3>Q: How to
|
2301
|
-
<p>A: Currently not supported. May be supported in
|
3004
|
+
<h3>Q: How to make error messages I18Ned?</h3>
|
3005
|
+
<p>A: Currently not supported. May be supported in a future release.</p>
|
2302
3006
|
</section>
|
2303
3007
|
</section>
|
2304
3008
|
<section class="section" id="license-and-copyright">
|