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.
@@ -21,23 +21,23 @@
21
21
  <ul class="nav">
22
22
  </ul>
23
23
  </nav>
24
- <p>($Release: 0.2.0 $)</p>
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>Base idea:</p>
30
+ <p>Basic idea:</p>
31
31
  <ul>
32
- <li>Sub-command (= action) is defined as a method in Ruby.</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>&ltcommand&gt; foo</code> in command-line invokes action method <code>foo()</code> in Ruby.</li>
39
- <li><code>&ltcommand&gt; foo arg1 arg2</code> invokes <code>foo("arg1", "arg2")</code>.</li>
40
- <li><code>&ltcommand&gt; foo arg --opt=val</code> invokes <code>foo("arg", opt: "val")</code>.</li>
38
+ <li><code>&ltcommand&gt; hello</code> in command-line invokes action method <code>hello()</code> in Ruby.</li>
39
+ <li><code>&ltcommand&gt; hello arg1 arg2</code> invokes <code>hello("arg1", "arg2")</code>.</li>
40
+ <li><code>&ltcommand&gt; 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="#prefix-of-action-name">Prefix of Action Name</a></li>
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="#action-alias">Action Alias</a></li>
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="#default-help">Default Help</a></li>
70
- <li><a href="#private-hidden-action">Private (Hidden) Action</a></li>
71
- <li><a href="#private-hidden-option">Private (Hidden) Option</a></li>
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-command-help-message">Customization of Command Help Message</a></li>
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 &amp; A</a>
83
96
  <ul>
84
- <li><a href="#q-how-to-append-some-tasks-to-existing-action">Q: How to Append Some Tasks to Existing Action?</a></li>
85
- <li><a href="#q-how-to-re-define-existing-action">Q: How to Re-define Existing Action?</a></li>
86
- <li><a href="#q-how-to-delete-existing-actionalias">Q: How to Delete Existing Action/Alias?</a></li>
87
- <li><a href="#q-how-to-show-entering-into-or-exitting-from-action">Q: How to Show Entering Into or Exitting From Action?</a></li>
88
- <li><a href="#q-how-to-enabledisable-color-mode">Q: How to Enable/Disable Color Mode?</a></li>
89
- <li><a href="#q-how-to-define-multiple-option-like--i-option-of-ruby">Q: How to Define Multiple Option, like <code>-I</code> Option of Ruby?</a></li>
90
- <li><a href="#q-how-to-specify-detailed-description-of-option">Q: How to Specify Detailed Description of Option?</a></li>
91
- <li><a href="#q-how-to-copy-all-options-from-other-action">Q: How to Copy All Options from Other Action?</a></li>
92
- <li><a href="#q-what-is-the-difference-between-prefixalias_of-and-prefixaction">Q: What is the Difference Between <code>prefix(alias_of:)</code> and <code>prefix(action:)</code>?</a></li>
93
- <li><a href="#q-how-to-change-order-of-options-in-help-message">Q: How to Change Order of Options in Help Message?</a></li>
94
- <li><a href="#q-is-it-possible-to-make-action-names-emphasised-or-weaken">Q: Is It Possible to Make Action Names Emphasised or Weaken?</a></li>
95
- <li><a href="#q-is-it-possible-to-add-metadata-to-action-or-option">Q: Is It Possible to Add Metadata to Action or Option?</a></li>
96
- <li><a href="#q-how-to-make-error-messages-i18ned">Q: How to Make Error Messages I18Ned?</a></li>
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 &lttopic&gt;</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>Inherit action class and define action methods in it.</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
- #!/usr/bin/env ruby
144
+ # coding: utf-8
122
145
  <strong>require 'benry/cmdapp'</strong>
123
146
 
124
- ## action
147
+ ## (1) Inherit action class.
125
148
  class MyAction &lt <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(user="world")</strong> # !!!!
129
- puts "Hello, #{user}!"
152
+ <strong>def hello(name="world")</strong> # !!!!
153
+ puts "Hello, #{name}!"
130
154
  end
131
155
 
132
156
  end
133
157
 
134
- ## configuration
135
- config = <strong>Benry::CmdApp::Config.new("sample app", "1.0.0")</strong>
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) -- sample app
178
+ ex01.rb (1.0.0) --- sample app
155
179
 
156
180
  Usage:
157
- $ ex01.rb [&ltoptions&gt;] [&ltaction&gt; [&ltarguments&gt;...]]
181
+ $ ex01.rb [&ltoptions&gt;] &ltaction&gt; [&ltarguments&gt;...]
158
182
 
159
183
  Options:
160
- -h, --help : print help message (of action if action specified)
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 -- print greeting message
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 [&ltname&gt;]
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 [&ltuser&gt;]
210
+ $ ex01.rb hello [&ltname&gt;]
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
- #!/usr/bin/env ruby
224
+ # coding: utf-8
186
225
  require 'benry/cmdapp'
187
226
 
188
227
  class SampleAction &lt Benry::CmdApp::Action
@@ -201,30 +240,37 @@ class SampleAction &lt Benry::CmdApp::Action
201
240
 
202
241
  ## 'foo__bar__baz' =&gt; 'foo:bar:baz'
203
242
  @action.("sample #3")
204
- def foo<strong>__</strong>ba<strong>r__</strong>baz() # !!!!
243
+ def foo<strong>__</strong>bar<strong>__</strong>baz() # !!!!
205
244
  puts __method__
206
245
  end
207
246
 
208
247
  end
209
248
 
210
- config = Benry::CmdApp::Config.new("test app")
211
- app = Benry::CmdApp::Application.new(config)
212
- exit app.main()
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 -- test app
260
+ ex02.rb --- test app
218
261
 
219
262
  Usage:
220
- $ ex02.rb [&ltoptions&gt;] [&ltaction&gt; [&ltarguments&gt;...]]
263
+ $ ex02.rb [&ltoptions&gt;] &ltaction&gt; [&ltarguments&gt;...]
221
264
 
222
265
  Options:
223
- -h, --help : print help message (of action if action specified)
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>&ltfoo&gt;</code>.</li>
247
293
  <li>Parameter <code>foo_bar_baz</code> is printed as <code>&ltfoo-bar-baz&gt;</code>.</li>
248
294
  <li>Parameter <code>foo_or_bar_or_baz</code> is printed as <code>&ltfoo|bar|baz&gt;</code>.</li>
295
+ <li>Parameter <code>foobar__xxx</code> is printed as <code>&ltfoobar.xxx&gt;</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>&ltfoo&gt;</code>.</li>
253
300
  <li>If parameter <code>foo</code> is optional (= has default value), it will be printed as <code>[&ltfoo&gt;]</code>.</li>
254
301
  <li>If parameter <code>foo</code> is variable length (= <code>*foo</code> style), it will be printed as <code>[&ltfoo&gt;...]</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>&ltfoo&gt;...</code>.</li>
255
303
  </ul>
256
304
  <p>File: ex03.rb</p>
257
305
  <pre class="language-ruby">
258
- #!/usr/bin/env ruby
306
+ # coding: utf-8
259
307
  require 'benry/cmdapp'
260
308
 
261
309
  class SampleAction &lt Benry::CmdApp::Action
262
310
 
263
- @action.("parameter names test")
264
- def test1(<strong>aaa, bbb_or_ccc, ddd=nil, eee=nil, *fff</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
- config = Benry::CmdApp::Config.new("sample app")
271
- app = Benry::CmdApp::Application.new(config)
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
- hoge.rb test1 -- parameter names test
335
+ ex03.rb test1 --- name conversion test
336
+
337
+ Usage:
338
+ $ ex03.rb test1 <strong>&ltfile-name&gt; &ltfile|dir&gt; &ltfile.html&gt;</strong> # !!!!
339
+
340
+ [bash]$ ruby ex03.rb -h test2
341
+ ex03.rb test2 --- parameter kind test
342
+
343
+ Usage:
344
+ $ ex03.rb test2 <strong>&ltaaa&gt; &ltbbb&gt; [&ltccc&gt; [&ltddd&gt; [&lteee&gt;...]]]</strong> # !!!!
345
+
346
+ [bash]$ ruby ex03.rb -h test3
347
+ ex03.rb test3 --- parameter combination test
278
348
 
279
349
  Usage:
280
- $ ex03.rb test1 <strong>&ltaaa&gt; &ltbbb|ccc&gt; [&ltddd&gt; [&lteee&gt; [&ltfff&gt;...]]]</strong> # !!!!
350
+ $ ex03.rb test3 <strong>&ltfile&gt;...</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 actio method as keyword arguments.</li>
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
- #!/usr/bin/env ruby
361
+ # coding: utf-8
292
362
  require 'benry/cmdapp'
293
363
 
294
- ## action
295
364
  class MyAction &lt Benry::CmdApp::Action
296
365
 
297
366
  @action.("print greeting message")
@@ -302,20 +371,13 @@ class MyAction &lt Benry::CmdApp::Action
302
371
  when "fr" ; puts "Bonjour, #{user}!"
303
372
  when "it" ; puts "Ciao, #{user}!"
304
373
  else
305
- raise "#{lang}: unknown language."
374
+ raise "#{lang}: Unknown language."
306
375
  end
307
376
  end
308
377
 
309
378
  end
310
379
 
311
- ## configuration
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
- #!/usr/bin/env ruby
399
+ # coding: utf-8
338
400
  require 'benry/cmdapp'
339
401
 
340
- ## action
341
402
  class MyAction &lt Benry::CmdApp::Action
342
403
 
343
404
  @action.("print greeting message")
@@ -351,21 +412,14 @@ class MyAction &lt Benry::CmdApp::Action
351
412
  when "fr" ; puts "Bonjour, #{user}!"
352
413
  when "it" ; puts "Ciao, #{user}!"
353
414
  else
354
- raise "#{lang}: unknown language."
415
+ raise "#{lang}: Unknown language."
355
416
  end
356
417
  end
357
418
  end
358
419
 
359
420
  end
360
421
 
361
- ## configuration
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
- Help message:
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 -- print greeting message
434
+ ex05.rb hello --- print greeting message
383
435
 
384
436
  Usage:
385
437
  $ ex05.rb hello [&ltoptions&gt;] [&ltuser&gt;]
386
438
 
387
439
  Options:
388
- -l, --lang=&lten|fr|it&gt; : language # !!!!
440
+ -l, --lang=&lten|fr|it&gt; : language
389
441
  <strong> --repeat=&ltN&gt; : repeat &ltN&gt; times</strong> # !!!!
390
442
  </pre>
391
- <p>For usability reason, Benry::CmdApp supports <code>--lang=&ltval&gt;</code> style long option
392
- and doesn't support <code>--lang &ltval&gt;</code> style option.
393
- Benry::CmdApp regards <code>--lang &ltval&gt;</code> as 'long option without argument'
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 &ltlang&gt;", "language")
451
+ @option.(<strong>:repeat</strong>, "-n &ltN&gt;" , "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 &ltlang&gt;", "language")
459
+ @option.(:repeat, "-n &ltN&gt;" , "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=&ltval&gt;</code> style of long option
465
+ but doesn't support <code>--lang &ltval&gt;</code> style.
466
+ Benry-CmdApp regards <code>--lang &ltval&gt;</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: argument required.</strong>
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>Option definition format should be one of:</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 &ltpath&gt;</code> --- Short style.</li>
486
+ <li><code>--file=&ltpath&gt;</code> --- Long style.</li>
487
+ <li><code>-f, --file=&ltpath&gt;</code> --- Short and long style.</li>
488
+ </ul></li>
489
+ <li>When the option takes an optional value:
403
490
  <ul>
404
- <li>(short option) <code>-q</code> : no values.</li>
405
- <li>(short option) <code>-f &ltfile&gt;</code> : value required.</li>
406
- <li>(short option) <code>-i[&ltwidth&gt;]</code> : value is optional.</li>
407
- <li>(long option) <code>--quiet</code> : no values.</li>
408
- <li>(long option) <code>--file=&ltfile&gt;</code> : value required.</li>
409
- <li>(long option) <code>--indent[=&ltwidth&gt;]</code> : value is optional.</li>
410
- <li>(short &amp; long) <code>-q, --quiet</code> : no values.</li>
411
- <li>(short &amp; long) <code>-f, --file=&ltfile&gt;</code> : value required.</li>
412
- <li>(short &amp; long) <code>-i, --indent[=&ltwidth&gt;]</code> : value is optional.</li>
491
+ <li><code>-i[&ltN&gt;]</code> --- Short style.</li>
492
+ <li><code>--indent[=&ltN&gt;]</code> --- Long style.</li>
493
+ <li><code>-i, --indent[=&ltN&gt;]</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
- #!/usr/bin/env ruby
498
+ # coding: utf-8
417
499
  require 'benry/cmdapp'
418
500
 
419
501
  class SampleAction &lt Benry::CmdApp::Action
@@ -447,9 +529,7 @@ class SampleAction &lt Benry::CmdApp::Action
447
529
 
448
530
  end
449
531
 
450
- config = Benry::CmdApp::Config.new("test app")
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 -- short options
562
+ ex06.rb test1 --- short options
483
563
 
484
564
  Usage:
485
565
  $ ex06.rb test1 [&ltoptions&gt;]
@@ -490,7 +570,7 @@ Options:
490
570
  <strong>-i[&ltN&gt;]</strong> : indent width
491
571
 
492
572
  [bash]$ ruby ex06.rb -h test2
493
- ex06.rb test2 -- long options
573
+ ex06.rb test2 --- long options
494
574
 
495
575
  Usage:
496
576
  $ ex06.rb test2 [&ltoptions&gt;]
@@ -501,7 +581,7 @@ Options:
501
581
  <strong>--indent[=&ltN&gt;]</strong> : indent width
502
582
 
503
583
  [bash]$ ruby ex06.rb -h test3
504
- ex06.rb test3 -- short and long options
584
+ ex06.rb test3 --- short and long options
505
585
 
506
586
  Usage:
507
587
  $ ex06.rb test3 [&ltoptions&gt;]
@@ -524,10 +604,9 @@ Options:
524
604
  </ul>
525
605
  <p>File: ex07.rb</p>
526
606
  <pre class="language-ruby">
527
- #!/usr/bin/env ruby
607
+ # coding: utf-8
528
608
  require 'benry/cmdapp'
529
609
 
530
- ## action
531
610
  class MyAction &lt Benry::CmdApp::Action
532
611
 
533
612
  @action.("print greeting message")
@@ -544,32 +623,25 @@ class MyAction &lt Benry::CmdApp::Action
544
623
  when "fr" ; puts "Bonjour, #{user}!"
545
624
  when "it" ; puts "Ciao, #{user}!"
546
625
  else
547
- raise "#{lang}: unknown language."
626
+ raise "#{lang}: Unknown language."
548
627
  end
549
628
  end
550
629
  end
551
630
 
552
631
  end
553
632
 
554
- ## configuration
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: pattern unmatched.</strong>
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: expected one of en/fr/it.</strong>
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: integer expected.</strong>
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
- #!/usr/bin/env ruby
660
+ # coding: utf-8
589
661
  require 'benry/cmdapp'
590
662
 
591
- ## action
592
663
  class MyAction &lt Benry::CmdApp::Action
593
664
 
594
665
  @action.("print greeting message")
@@ -597,7 +668,7 @@ class MyAction &lt Benry::CmdApp::Action
597
668
  rexp: /\A\w\w\z/) <strong>{|v| v.downcase }</strong> # !!!!
598
669
  @option.(:repeat, " --repeat=&ltN&gt;", "repeat &ltN&gt; times",
599
670
  type: Integer) <strong>{|v|</strong> # !!!!
600
- <strong>v &gt; 0 or raise "not positive value."</strong> # !!!!
671
+ <strong>v &gt; 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 &lt Benry::CmdApp::Action
607
678
  when "fr" ; puts "Bonjour, #{user}!"
608
679
  when "it" ; puts "Ciao, #{user}!"
609
680
  else
610
- raise "#{lang}: unknown language."
681
+ raise "#{lang}: Unknown language."
611
682
  end
612
683
  end
613
684
  end
614
685
 
615
686
  end
616
687
 
617
- ## configuration
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: not positive value.</strong>
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::CmdApp doesn't support <code>--[no-]foobar</code> style option.
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
- #!/usr/bin/env ruby
710
+ # coding: utf-8
647
711
  require 'benry/cmdapp'
648
712
 
649
713
  class SampleAction &lt Benry::CmdApp::Action
@@ -658,9 +722,7 @@ class SampleAction &lt Benry::CmdApp::Action
658
722
 
659
723
  end
660
724
 
661
- config = Benry::CmdApp::Config.new("sample app", "1.0.0")
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
- #!/usr/bin/env ruby
757
+ # coding: utf-8
696
758
  require 'benry/cmdapp'
697
759
 
698
760
  class SampleAction &lt Benry::CmdApp::Action
@@ -706,9 +768,7 @@ class SampleAction &lt Benry::CmdApp::Action
706
768
 
707
769
  end
708
770
 
709
- config = Benry::CmdApp::Config.new("git helper")
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: unexpected argument.</strong>
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>[=&lton|off]</strong>", "quiet mode", # !!!!
732
- <strong>type: TrueClass</strong>, value: false) # !!!!
791
+ @option.(:verbose, "-q, --quiet<strong>[=&lton|off&gt;]</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="prefix-of-action-name">
741
- <h3>Prefix of Action Name</h3>
742
- <ul>
743
- <li><code>prefix: "foo:bar"</code> in action class adds prefix <code>foo:bar:</code> to each action name.</li>
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
- #!/usr/bin/env ruby
806
+ # coding: utf-8
749
807
  require 'benry/cmdapp'
750
808
 
751
809
  class SampleAction &lt Benry::CmdApp::Action
752
- <strong>prefix "foo:bar"</strong> # !!!!
753
810
 
754
- @action.("test action #1")
755
- def <strong>test1</strong>() # action name: 'foo:bar:test1'
756
- puts __method__
811
+ optset1 = <strong>optionset()</strong> { # !!!!
812
+ @option.(:host , "-H, --host=&lthost&gt;" , "host name")
813
+ @option.(:port , "-p, --port=&ltport&gt;" , "port number", type: Integer)
814
+ }
815
+ optset2 = <strong>optionset()</strong> { # !!!!
816
+ @option.(:user , "-u, --user=&ltuser&gt;" , "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.("test action #2")
760
- def <strong>baz__test2</strong>() # action name: 'foo:bar:baz:test2'
761
- puts __method__
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
- config = Benry::CmdApp::Config.new("sample app")
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 -- sample app
837
+ [bash]$ ruby ex11.rb -h <strong>postgresql</strong> # !!!!
838
+ ex11.rb postgresql --- connect to postgresql
782
839
 
783
840
  Usage:
784
- $ ex11.rb [&ltoptions&gt;] [&ltaction&gt; [&ltarguments&gt;...]]
841
+ $ ex11.rb postgresql [&ltoptions&gt;]
785
842
 
786
843
  Options:
787
- -h, --help : print help message (of action if action specified)
844
+ <strong>-H, --host=&lthost&gt; : host name</strong> # !!!!
845
+ <strong>-p, --port=&ltport&gt; : port number</strong> # !!!!
846
+ <strong>-u, --user=&ltuser&gt; : user name</strong> # !!!!
788
847
 
789
- Actions:
790
- <strong>foo:bar:baz:test2</strong> : test action #2
791
- <strong>foo:bar:test1</strong> : test action #1
848
+ [bash]$ ruby ex11.rb -h <strong>mysql</strong> # !!!!
849
+ ex11.rb mysql --- connect to mysql
850
+
851
+ Usage:
852
+ $ ex11.rb mysql [&ltoptions&gt;]
853
+
854
+ Options:
855
+ <strong>-H, --host=&lthost&gt; : host name</strong> # !!!!
856
+ <strong>-p, --port=&ltport&gt; : port number</strong> # !!!!
857
+ <strong>-u, --user=&ltuser&gt; : user name</strong> # !!!!
792
858
  </pre>
859
+ <p>Option set object has the following methods.</p>
793
860
  <ul>
794
- <li><code>prefix: "foo:bar", action: :test</code> defines <code>foo:bar</code> action (intead of <code>foo:bar:test</code>) with <code>test()</code> method.</li>
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
- #!/usr/bin/env ruby
885
+ # coding: utf-8
799
886
  require 'benry/cmdapp'
800
887
 
801
888
  class SampleAction &lt 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.("test action #1")
807
- def test1() # action name: 'foo:bar:test1'
808
- puts __method__
890
+ @action.("connect to postgresql")
891
+ @option.(:host , "-H, --host=&lthost&gt;" , "host name")
892
+ @option.(:port , "-p, --port=&ltport&gt;" , "port number", type: Integer)
893
+ @option.(:user , "-u, --user=&ltuser&gt;" , "user name")
894
+ def postgresql(host: nil, port: nil, user: nil)
895
+ puts "psql ...."
809
896
  end
810
897
 
811
- @action.("test action #3")
812
- def <strong>test3_</strong>() # action name: 'foo:bar'
813
- puts __method__
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
- config = Benry::CmdApp::Config.new("sample app")
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 -- sample app
910
+ [bash]$ ruby ex12.rb -h <strong>mysql</strong> # !!!!
911
+ ex12.rb mysql --- connect to mysql
837
912
 
838
913
  Usage:
839
- $ ex12.rb [&ltoptions&gt;] [&ltaction&gt; [&ltarguments&gt;...]]
914
+ $ ex12.rb mysql [&ltoptions&gt;]
840
915
 
841
916
  Options:
842
- -h, --help : print help message (of action if action specified)
843
-
844
- Actions:
845
- <strong>foo:bar</strong> : test action #3
846
- foo:bar:test1 : test action #1
917
+ <strong>-H, --host=&lthost&gt; : host name</strong>
918
+ <strong>-p, --port=&ltport&gt; : port number</strong>
919
+ <strong>-u, --user=&ltuser&gt; : 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="invoke-other-action">
850
- <h3>Invoke Other Action</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>run_action!()</code> invokes other action.</li>
853
- <li><code>run_action_once()</code> invokes other action only once.
854
- This is equivarent to 'prerequisite task' feature in task runner application.</li>
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
- #!/usr/bin/env ruby
933
+ # coding: utf-8
859
934
  require 'benry/cmdapp'
860
935
 
861
936
  class SampleAction &lt Benry::CmdApp::Action
862
937
 
863
- @action.("create build dir")
864
- def <strong>prepare</strong>()
865
- puts <strong>"rm -rf build"</strong>
866
- puts <strong>"mkdir build"</strong>
867
- end
868
-
869
- @action.("build something")
870
- def build()
871
- <strong>run_action_once("prepare")</strong> # !!!!
872
- <strong>run_action_once("prepare")</strong> # skipped because already invoked
873
- puts "echo 'README' &gt; build/README.txt"
874
- puts "zip -r build.zip build"
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 &amp;&amp; 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
- config = Benry::CmdApp::Config.new("sample app")
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 build
886
- <strong>rm -rf build</strong> # invoked only once!!!!
887
- <strong>mkdir build</strong> # invoked only once!!!!
888
- echo 'README' &gt; build/README.txt
889
- zip -r build.zip build
959
+ [bash]$ ruby ex13.rb openssl file.txt
960
+ <strong>[ERROR] Required '--encrypt' or '--decrypt' option.</strong> #&lt== 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> #&lt== action_error()
965
+ From ex13.rb:17:in `openssl'
966
+ raise action_error("Command failed: #{command}")
967
+ From ex13.rb:25:in `&ltmain&gt;'
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>When looped action is detected, Benry::CmdApp aborts action.</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: ex14.rb</p>
994
+ <p>File: ex21.rb</p>
895
995
  <pre class="language-ruby">
896
- #!/usr/bin/env ruby
996
+ # coding: utf-8
897
997
  require 'benry/cmdapp'
898
998
 
899
- class LoopedAction &lt Benry::CmdApp::Action
900
-
901
- @action.("test #1")
902
- def test1()
903
- run_action_once("test2")
904
- end
999
+ class SampleAction &lt Benry::CmdApp::Action
1000
+ <strong>category "foo:bar:"</strong> # !!!!
905
1001
 
906
- @action.("test #2")
907
- def test2()
908
- run_action_once("test3")
1002
+ @action.("test action #1")
1003
+ def <strong>test1</strong>() # action name: 'foo:bar:test1'
1004
+ puts __method__ #=&gt; test1
1005
+ puts methods().grep(/test1/) #=&gt; foo__bar__test1
909
1006
  end
910
1007
 
911
- @action.("test #3")
912
- def test3()
913
- <strong>run_action_once("test1")</strong> # !!!!
1008
+ @action.("test action #2")
1009
+ def <strong>baz__test2</strong>() # action name: 'foo:bar:baz:test2'
1010
+ puts __method__ #=&gt; baz__test2
1011
+ puts methods().grep(/test2/) #=&gt; foo__bar__baz__test2
914
1012
  end
915
1013
 
916
1014
  end
917
1015
 
918
- config = Benry::CmdApp::Config.new("sample app")
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 ex14.rb test1
925
- <strong>[ERROR] test1: looped action detected.</strong>
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 # &lt== puts __method__
1028
+ foo__bar__test1 # &lt== puts methods().grep(/test1/)
926
1029
 
927
- [bash]$ ruby ex14.rb test3
928
- <strong>[ERROR] test3: looped action detected.</strong>
1030
+ [bash]$ ruby ex21.rb <strong>foo:bar:baz:test2</strong>
1031
+ baz__test2 # &lt== puts __method__
1032
+ foo__bar__baz__test2 # &lt== puts methods().grep(/test1/)
929
1033
  </pre>
930
- </section>
931
- <section class="subsection" id="action-alias">
932
- <h3>Action Alias</h3>
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>Alias of action provides alternative short name of action.</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
- <p>File: ex15.rb</p>
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
- #!/usr/bin/env ruby
1050
+ # coding: utf-8
939
1051
  require 'benry/cmdapp'
940
1052
 
941
- class SampleAction &lt Benry::CmdApp::Action
942
- <strong>prefix "foo:bar"</strong>
1053
+ class GitAction &lt Benry::CmdApp::Action
1054
+ <strong>category "git:"</strong> # top level category
943
1055
 
944
- @action.("test action #1")
945
- def <strong>test1</strong>() # action name: 'foo:bar:test1'
946
- puts __method__
1056
+ @action.("show current status in compact format")
1057
+ def status(path=".")
1058
+ puts "git status -sb #{path}"
947
1059
  end
948
1060
 
949
- end
1061
+ <strong>category "commit:" do</strong> # sub level category
950
1062
 
951
- <strong>Benry::CmdApp.action_alias "test", "foo:bar:test1"</strong> # !!!!
1063
+ @action.("create a new commit")
1064
+ def create(message: nil)
1065
+ puts "git commit"
1066
+ end
952
1067
 
953
- config = Benry::CmdApp::Config.new("sample app")
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
- [bash]$ ruby ex15.rb <strong>foo:bar:test1</strong> # original action name
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
- Usage:
971
- $ ex15.rb [&ltoptions&gt;] [&ltaction&gt; [&ltarguments&gt;...]]
1072
+ @action.("create a new branch")
1073
+ def create(branch)
1074
+ puts "git checkout -b #{branch}"
1075
+ end
972
1076
 
973
- Options:
974
- -h, --help : print help message (of action if action specified)
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
- foo:bar:test1 : test action #1
978
- <strong>test : alias to 'foo:bar:test1' action</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
- <ul>
981
- <li>Alias can include positional and keyword arguments in definition.</li>
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
- #!/usr/bin/env ruby
1095
+ # coding: utf-8
986
1096
  require 'benry/cmdapp'
987
1097
 
988
- class MyAction &lt Benry::CmdApp::Action
1098
+ class GitAction &lt 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=&ltlang&gt;", "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.action_alias("bonjour", "hello", <strong>"--lang=fr"</strong>) # !!!!
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 ex16.rb hello
1014
- Hello, world!
1015
-
1016
- [bash]$ ruby ex16.rb <strong>bonjour</strong> # !!!!
1017
- Bonjour, world!
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="default-action">
1027
- <h3>Default Action</h3>
1141
+ <section class="subsection" id="category-action-or-alias">
1142
+ <h3>Category Action or Alias</h3>
1028
1143
  <ul>
1029
- <li><code>config.default = "test1"</code> defines default action.
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: ex17.rb</p>
1146
+ <p>File: ex24.rb</p>
1034
1147
  <pre class="language-ruby">
1035
- #!/usr/bin/env ruby
1148
+ # coding: utf-8
1036
1149
  require 'benry/cmdapp'
1037
1150
 
1038
1151
  class SampleAction &lt 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
- config = Benry::CmdApp::Config.new("sample app")
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 ex17.rb test1
1055
- test1
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]$ <strong>ruby ex17.rb</strong> # no action name!!!!
1176
+ [bash]$ ruby ex24.rb foo:bar:test1
1058
1177
  test1
1059
- </pre>
1060
- <p>Help message:</p>
1061
- <pre class="language-console">
1062
- [bash]$ ruby ex17.rb -h
1063
- ex17.rb -- sample app
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> #=&gt; error
1191
+ category "foo:", action: <strong>:blabla</strong> #=&gt; 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 &lt 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' &gt; 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' &gt; 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 &lt 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 &lt 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' &gt; 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' &gt; 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 &lt 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
- $ ex17.rb [&ltoptions&gt;] [&ltaction&gt; [&ltarguments&gt;...]]
1369
+ $ ex28.rb [&ltoptions&gt;] &ltaction&gt; [&ltarguments&gt;...]
1067
1370
 
1068
1371
  Options:
1069
- -h, --help : print help message (of action if action specified)
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: <strong>(default: test1)</strong> # !!!!
1072
- test1 : test action #1
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 &lt Benry::CmdApp::Action
1435
+
1436
+ @action.("print greeting message")
1437
+ @option.(:lang, "-l, --lang=&ltlang&gt;", "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="default-help">
1076
- <h3>Default Help</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 &lt 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: =&gt; 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.default_help = true</code> prints help message if action not specified in command-line.</li>
1079
- <li>This is very useful when you don't have proper default action. It's recommended.</li>
1080
- <li><code>config.default_action</code> is prior than <code>config.default_help</code>.</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: ex18.rb</p>
1540
+ <p>File: ex32.rb</p>
1083
1541
  <pre class="language-ruby">
1084
- #!/usr/bin/env ruby
1542
+ # coding: utf-8
1085
1543
  require 'benry/cmdapp'
1086
1544
 
1087
1545
  class SampleAction &lt Benry::CmdApp::Action
@@ -1093,37 +1551,234 @@ class SampleAction &lt Benry::CmdApp::Action
1093
1551
 
1094
1552
  end
1095
1553
 
1096
- config = Benry::CmdApp::Config.new("sample app")
1097
- <strong>config.default_help = true</strong> # !!!!
1098
- app = Benry::CmdApp::Application.new(config)
1099
- exit app.main()
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]$ <strong>ruby ex18.rb</strong> # no action name!!!!
1104
- ex18.rb -- sample app
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
- $ ex18.rb [&ltoptions&gt;] [&ltaction&gt; [&ltarguments&gt;...]]
1576
+ $ ex32.rb [&ltoptions&gt;] &ltaction&gt; [&ltarguments&gt;...]
1108
1577
 
1109
1578
  Options:
1110
- -h, --help : print help message (of action if action specified)
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="private-hidden-action">
1117
- <h3>Private (Hidden) Action</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 &lt 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 &lt 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 &lt 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::CmdApp regards that action as private.</li>
1121
- <li>Private actions are hidden in help message.</li>
1122
- <li>Private actions are shown when <code>-a</code> or <code>--all</code> option enabled and specified.</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: ex20.rb</p>
1779
+ <p>File: ex36.rb</p>
1125
1780
  <pre class="language-ruby">
1126
- #!/usr/bin/env ruby
1781
+ # coding: utf-8
1127
1782
  require 'benry/cmdapp'
1128
1783
 
1129
1784
  class SampleAction &lt Benry::CmdApp::Action
@@ -1147,54 +1802,35 @@ class SampleAction &lt Benry::CmdApp::Action
1147
1802
 
1148
1803
  end
1149
1804
 
1150
- config = Benry::CmdApp::Config.new("sample app")
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>Help message (without <code>-a</code> nor <code>--all</code>):</p>
1807
+ <p>Action list (without <code>-a</code> nor <code>--all</code>):</p>
1156
1808
  <pre class="language-console">
1157
- [bash]$ ruby ex20.rb <strong>-h</strong>
1158
- ex20.rb -- sample app
1159
-
1160
- Usage:
1161
- $ ex20.rb [&ltoptions&gt;] [&ltaction&gt; [&ltarguments&gt;...]]
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>Help message (with <code>-a</code> or <code>--all</code>):</p>
1814
+ <p>Action list (with <code>-a</code> or <code>--all</code>):</p>
1171
1815
  <pre class="language-console">
1172
- [bash]$ ruby ex20.rb <strong>-h --all</strong> # !!!!
1173
- ex20.rb -- sample app
1174
-
1175
- Usage:
1176
- $ ex20.rb [&ltoptions&gt;] [&ltaction&gt; [&ltarguments&gt;...]]
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="private-hidden-option">
1189
- <h3>Private (Hidden) Option</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 private option.</li>
1192
- <li>Private options are hidden in help message of action.</li>
1193
- <li>Private options are shown when <code>-a</code> or <code>--all</code> option enabled and specified.</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: ex21.rb</p>
1831
+ <p>File: ex37.rb</p>
1196
1832
  <pre class="language-ruby">
1197
- #!/usr/bin/env ruby
1833
+ # coding: utf-8
1198
1834
  require 'benry/cmdapp'
1199
1835
 
1200
1836
  class SampleAction &lt Benry::CmdApp::Action
@@ -1203,38 +1839,117 @@ class SampleAction &lt 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=#{_debug}"
1842
+ puts "verbose=#{verbose}, debug=#{debug}"
1207
1843
  end
1208
1844
 
1209
1845
  end
1210
1846
 
1211
- config = Benry::CmdApp::Config.new("sample app")
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 ex21.rb -h test1
1219
- ex21.rb test1 -- test action
1851
+ [bash]$ ruby ex37.rb -h test1
1852
+ ex37.rb test1 --- test action
1220
1853
 
1221
1854
  Usage:
1222
- $ ex21.rb test1 [&ltoptions&gt;]
1855
+ $ ex37.rb test1 [&ltoptions&gt;]
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 ex21.rb -h <strong>--all</strong> test1 # !!!!
1230
- ex21.rb test1 -- test action
1862
+ [bash]$ ruby ex37.rb -h <strong>--all</strong> test1 # !!!!
1863
+ ex37.rb test1 --- test action
1231
1864
 
1232
1865
  Usage:
1233
- $ ex21.rb test1 [&ltoptions&gt;]
1866
+ $ ex37.rb test1 [&ltoptions&gt;]
1234
1867
 
1235
1868
  Options:
1869
+ <strong>-h, --help : print help message</strong> # !!!!
1236
1870
  -v : verbose mode
1237
- -D : debug mode # !!!!
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 &lt 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 [&ltoptions&gt;]
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 &lt Benry::CmdApp::Action
1938
+
1939
+ @action.("multiple option test")
1940
+ @option.(:path, "-I &ltpath&gt;", "path", <strong>multiple: true</strong>)
1941
+ def test_(path: [])
1942
+ puts "path=#{path.inspect}" #=&gt; 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 = "&ltcommand&gt;"</code> sets command name which is shown in help message. (default: <code>File.basname($0)</code>)</li>
1965
+ <li><code>config.app_name = "&ltstring&gt;"</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 = "&lttext&gt;" (or </code>["&lttext1&gt;", "&lttext2&gt;", ...]<code>) sets usage string in help message. (default: </code>" &ltaction&gt; [&ltarguments&gt;...]"``)</li>
1250
1967
  <li><code>config.app_detail = "&lttext&gt;"</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 = "&lttext&gt;"</code> sets text of 'Description:' section in help message. (default: <code>nil</code>)</li>
1970
+ <li><code>config.help_postamble = {"&ltTitle&gt;:" =&gt; "&lttext&gt;"}</code> sets postamble of help message, such as 'Example:' or 'Tips:'. (default: <code>nil</code>)</li>
1251
1971
  <li><code>config.default_action = "&ltaction&gt;"</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.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>false</code>)</li>
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 &lttopic&gt;</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[=&lton|off&gt;]</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>false</code>)</li>
1259
- <li><code>config.option_trace = true</code> enables <code>-T</code> and <code>--trace</code> options which sets <code>$TRACE_MODE = true</code>. Entering into and exitting from action are reported when trace mode is on. (default: <code>false</code>)</li>
1260
- <li><code>config.help_aliases = true</code> adds <code>Aliases:</code> section in help message. (default: <code>false</code>)</li>
1261
- <li><code>config.help_sections = [["&lttitle&gt;", "&lttext&gt;"], ...]</code> adds section title and text into help message. (default: <code>[]</code>)</li>
1262
- <li><code>config.help_postamble = "&lttext&gt;"</code> sets postamble text in help message, such as 'Examples:' or 'Tips:'. (default: <code>nil</code>)</li>
1263
- <li><code>config.feat_candidate = true</code> enables feature to list action names starting with 'foo:' when action name specified in command-line is <code>foo:</code>. (default: <code>true</code>)</li>
1264
- <li><code>config.format_help = " %-18s : %s"</code> sets format of options and actions in help message. (default: <code>" \e[1m%-18s\e[0m : %s"</code>)</li>
1265
- <li><code>config.format_usage = " $ %s %s"</code> sets format of usage in help message. (default: <code>" $ \e[1m%s\e[0m %s"</code>)</li>
1266
- <li><code>config.format_heading = "[%s]"</code> sets format of heading in help message. (default: <code>"\e[34m%s\e[0m"</code>)</li>
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 =&gt; %s"</code> sets format of abbreviations in output of <code>-L abbrev</code> option. (default: <code>" %-10s =&gt; %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: ex22.rb</p>
1990
+ <p>File: ex41.rb</p>
1269
1991
  <pre class="language-ruby">
1270
- #!/usr/bin/env ruby
1992
+ # coding: utf-8
1271
1993
  require 'benry/cmdapp'
1272
1994
 
1273
- config = Benry::CmdApp::Config.new("sample app", "1.0.0")
1274
- #config.default_help = true
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 ex22.rb
1286
- config<strong>.app_desc</strong> = "sample app"
1287
- config<strong>.app_version</strong> = "1.0.0"
1288
- config<strong>.app_name</strong> = "ex22.rb"
1289
- config<strong>.app_command</strong> = "ex22.rb"
1290
- config<strong>.app_detail</strong> = nil
1291
- config<strong>.default_action</strong> = nil
1292
- config<strong>.default_help</strong> = false
1293
- config<strong>.option_help</strong> = true
1294
- config<strong>.option_all</strong> = false
1295
- config<strong>.option_verbose</strong> = false
1296
- config<strong>.option_quiet</strong> = false
1297
- config<strong>.option_color</strong> = false
1298
- config<strong>.option_debug</strong> = false
1299
- config<strong>.option_trace</strong> = false
1300
- config<strong>.help_aliases</strong> = false
1301
- config<strong>.help_sections</strong> = []
1302
- config<strong>.help_postamble</strong> = nil
1303
- config<strong>.feat_candidate</strong> = true
1304
- config<strong>.format_help</strong> = " \e[1m%-18s\e[0m : %s"
1305
- config<strong>.format_usage</strong> = " $ \e[1m%s\e[0m %s"
1306
- config<strong>.format_heading</strong> = "\e[34m%s\e[0m"
1307
- config<strong>.format_appname</strong> = "\e[1m%s\e[0m"
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 [&ltoptions&gt;] &ltaction&gt; [&ltarguments&gt;...]
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: ex23.rb</p>
2068
+ <p>File: ex42.rb</p>
1319
2069
  <pre class="language-ruby">
1320
- #!/usr/bin/env ruby
2070
+ # coding: utf-8
1321
2071
  require 'benry/cmdapp'
1322
2072
 
1323
2073
  class SampleAction &lt 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::AppOptionSchema.new(config)</strong> # !!!!
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 ex23.rb -h
1347
- ex23.rb -- sample app
2096
+ [bash]$ ruby ex42.rb -h
2097
+ ex42.rb --- sample app
1348
2098
 
1349
2099
  Usage:
1350
- $ ex23.rb [&ltoptions&gt;] [&ltaction&gt; [&ltarguments&gt;...]]
2100
+ $ ex42.rb [&ltoptions&gt;] &ltaction&gt; [&ltarguments&gt;...]
1351
2101
 
1352
2102
  Options:
1353
- -h, --help : print help message (of action if action specified)
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>AppOptionSchema</code> object.</li>
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: ex24.rb</p>
2118
+ <p>File: ex43.rb</p>
1366
2119
  <pre class="language-ruby">
1367
- #!/usr/bin/env ruby
2120
+ # coding: utf-8
1368
2121
  require 'benry/cmdapp'
1369
2122
 
1370
- ## (1) Create empty ``AppOptionSchema`` object.
1371
- <strong>schema = Benry::CmdApp::AppOptionSchema.new(nil)</strong> # !!!!
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>(:all , "-a, --all" , "list all actions/options")
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[=&lton|off&gt;]", "enable/disable color", type: TrueClass)
2133
+ <strong>schema.add</strong>(:color , "--color[=&lton|off&gt;]", "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 [&ltoptions&gt;] &ltaction&gt; [&ltarguments&gt;...]
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[=&lton|off&gt;] : 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>#do_toggle_global_switches()</code> method.</li>
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: ex25.rb</p>
2172
+ <p>File: ex44.rb</p>
1397
2173
  <pre class="language-ruby">
1398
- #!/usr/bin/env ruby
2174
+ # coding: utf-8
1399
2175
  require 'benry/cmdapp'
1400
2176
 
1401
2177
  ## (1) Define subclass of ``Application`` class.
1402
2178
  <strong>class MyApplication &lt Benry::CmdApp::Application</strong>
1403
2179
 
1404
- ## (2) Override ``#do_toggle_global_switches()`` method.
1405
- <strong>def do_toggle_global_switches(_args, global_opts)</strong>
1406
- <strong>super</strong>
1407
- ## here is original behaviour
1408
- #global_opts.each do |key, val|
1409
- # case key
1410
- # when :verbose ; $QUIET_MODE = ! val
1411
- # when :quiet ; $QUIET_MODE = val
1412
- # when :color ; $COLOR_MODE = val
1413
- # when :debug ; $DEBUG_MODE = val
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: ex26.rb</p>
2200
+ <p>File: ex45.rb</p>
1429
2201
  <pre class="language-ruby">
1430
- #!/usr/bin/env ruby
2202
+ # coding: utf-8
1431
2203
  require 'benry/cmdapp'
1432
2204
 
1433
2205
  <strong>module MyApplicationMod</strong>
1434
2206
 
1435
- <strong>def do_toggle_global_switches(_args, global_opts)</strong>
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 callback method.</li>
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: ex27.rb</p>
2227
+ <p>File: ex46.rb</p>
1456
2228
  <pre class="language-ruby">
1457
- #!/usr/bin/env ruby
2229
+ # coding: utf-8
1458
2230
  require 'benry/cmdapp'
1459
2231
 
1460
2232
  class SampleAction &lt Benry::CmdApp::Action
@@ -1469,74 +2241,33 @@ end
1469
2241
  ## (1) Define subclass of Application class
1470
2242
  <strong>class MyApplication &lt Benry::CmdApp::Application</strong> # !!!!
1471
2243
 
1472
- ## (2) Override callback method
1473
- <strong>def do_callback(args, global_opts)</strong> # !!!!
2244
+ ## (2) Override method
2245
+ <strong>def handle_action(action, args)</strong> # !!!!
1474
2246
  #p @config
1475
- #p @schema
1476
- if global_opts[:logging]
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::AppOptionSchema.new(config)
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 &lt 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-command-help-message">
1534
- <h3>Customization of Command Help Message</h3>
1535
- <p>If you want to just add more text into command help message,
1536
- set <code>config.app_detail</code>, <code>config.help_sections</code>, and/or <code>config.help_postamble</code>.</p>
1537
- <p>File: ex29.rb</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 = &lttext&gt;</code> --- print text before 'Usage:' section.
2266
+ .* <code>config.help_description = &lttext&gt;</code> --- print text after 'Usage:' section as 'Description:' section.
2267
+ .* <code>config.help_postamble = {&lthead&gt; =&gt; &lttext&gt;}</code> --- print at end of help message.</p>
2268
+ <p>File: ex47.rb</p>
1538
2269
  <pre class="language-ruby">
1539
- #!/usr/bin/env ruby
2270
+ # coding: utf-8
1540
2271
  require 'benry/cmdapp'
1541
2272
 
1542
2273
  class SampleAction &lt Benry::CmdApp::Action
@@ -1548,307 +2279,364 @@ class SampleAction &lt Benry::CmdApp::Action
1548
2279
 
1549
2280
  end
1550
2281
 
1551
- config = Benry::CmdApp::Config.new("sample app")
1552
- <strong>config.app_detail</strong> = "Document: https://...." # !!!!
1553
- config.help_sections</strong> = [ # !!!!
1554
- ["Example:", " $ &ltcommand&gt; hello Alice"], # !!!!
1555
- ] # !!!!
1556
- <strong>config.help_postamble</strong> = "(Tips: ....)" # !!!!
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:" =&gt; " $ &ltcommand&gt; 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 ex29.rb -h
1563
- ex29.rb -- sample app
2295
+ [bash]$ ruby ex47.rb -h
2296
+ ex47.rb --- sample app
1564
2297
 
1565
- <strong>Document: https://....</strong> # !!!! app.detail !!!!
2298
+ <strong>See https://....</strong> # !!!!
1566
2299
 
1567
2300
  Usage:
1568
- $ ex29.rb [&ltoptions&gt;] [&ltaction&gt; [&ltarguments&gt;...]]
2301
+ $ ex47.rb [&ltoptions&gt;] &ltaction&gt; [&ltarguments&gt;...]
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 action specified)
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> # !!!! help_sections !!!!
1577
- <strong>$ &ltcommand&gt; hello Alice</strong> # !!!! help_sections !!!!
2314
+ <strong>Example:</strong> # !!!!
2315
+ <strong>$ &ltcommand&gt; hello Alice</strong> # !!!!
1578
2316
 
1579
- <strong>(Tips: ....)</strong> # !!!! help_postamble !!!!
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::AppHelpBuilder</code> class.</li>
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: ex30.rb</p>
2326
+ <p>File: ex48.rb</p>
1589
2327
  <pre class="language-ruby">
1590
- #!/usr/bin/env ruby
2328
+ # coding: utf-8
1591
2329
  require 'benry/cmdapp'
1592
2330
 
1593
2331
  class SampleAction &lt 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::AppHelpBuilder`` class.
1603
- <strong>class MyAppHelpBuilder &lt Benry::CmdApp::AppHelpBuilder</strong>
2340
+ ## (1) Define subclass of ``Benry::CmdApp::ApplicationHelpBuilder`` class.
2341
+ <strong>class MyAppHelpBuilder &lt Benry::CmdApp::ApplicationHelpBuilder</strong>
1604
2342
 
1605
2343
  ## (2) Override methods.
1606
- def <strong>build_help_message</strong>(all=false, format=nil)
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>build_usage</strong>(all=false)
2347
+ def <strong>section_preamble</strong>()
1613
2348
  super
1614
2349
  end
1615
- def <strong>build_options</strong>(all=false, format=nil)
2350
+ def <strong>section_usage</strong>()
1616
2351
  super
1617
2352
  end
1618
- def <strong>build_actions</strong>(all=false, format=nil)
2353
+ def <strong>section_options</strong>(global_opts_schema, all: false)
1619
2354
  super
1620
2355
  end
1621
- def <strong>build_postamble</strong>(all=false)
2356
+ def <strong>section_actions</strong>(include_aliases=true, all: false)
1622
2357
  super
1623
2358
  end
1624
- def <strong>heading</strong>(str)
2359
+ def <strong>section_postamble</strong>()
1625
2360
  super
1626
2361
  end
2362
+ ### optional (for `-L &lttopic&gt;` 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::AppOptionSchema.new(config)
2371
+ schema = Benry::CmdApp::GlobalOptionSchema.new(config)
1632
2372
  schema.add(:logging, "--logging", "enable logging")
1633
- help_builder = <strong>MyAppHelpBuilder</strong>.new(config, schema) # !!!!
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>help_builder</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::AppHelpBuilder</code> class.</li>
1642
- <li>(2) Prepend it to <code>Benry::CmdApp::AppHelpBuilder</code> class.</li>
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: ex31.rb</p>
2385
+ <p>File: ex49.rb</p>
1646
2386
  <pre class="language-ruby">
1647
- #!/usr/bin/env ruby
2387
+ # coding: utf-8
1648
2388
  require 'benry/cmdapp'
1649
2389
 
1650
2390
  class SampleAction &lt 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 ``AppHelpBuilder`` class.
2399
+ ## (1) Create a module and override methods of ``ApplicationHelpBuilder`` class.
1660
2400
  <strong>module MyHelpBuilderMod</strong>
1661
- def build_help_message(all=false, format=nil)
2401
+ def build_help_message(gschema, all: false)
1662
2402
  super
1663
2403
  end
1664
- def build_preamble(all=false)
2404
+ def section_preamble()
1665
2405
  super
1666
2406
  end
1667
- def build_usage(all=false)
2407
+ def section_usage()
1668
2408
  super
1669
2409
  end
1670
- def build_options(all=false, format=nil)
2410
+ def section_options(global_opts_schema, all: false)
1671
2411
  super
1672
2412
  end
1673
- def build_actions(all=false, format=nil)
2413
+ def section_actions(include_aliases=true, all: false)
1674
2414
  super
1675
2415
  end
1676
- def build_postamble(all=false)
1677
- super
1678
- end
1679
- def heading(str)
2416
+ def section_postamble()
1680
2417
  super
1681
2418
  end
2419
+ ### optional (for `-L &lttopic&gt;` 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::AppHelpBuilder`` class.
1685
- <strong>Benry::CmdApp::AppHelpBuilder.prepend(MyHelpBuilderMod)</strong>
2426
+ ## (2) Prepend it to ``Benry::CmdApp::ApplicationHelpBuilder`` class.
2427
+ <strong>Benry::CmdApp::ApplicationHelpBuilder.prepend(MyHelpBuilderMod)</strong>
1686
2428
 
1687
- ## (3) Create and execute Application object.
1688
- config = Benry::CmdApp::Config.new("sample app")
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 <code>detail:</code> and/or <code>postamble:</code> keyword arguments to <code>@action.()</code>.</p>
1697
- <p>File: ex32.rb</p>
2436
+ pass the following keyword arguments to <code>@action.()</code>.</p>
2437
+ <ul>
2438
+ <li><code>detail: &lttext&gt;</code> --- printed before 'Usage:' section.</li>
2439
+ <li><code>description: &lttext&gt;</code> --- printed after 'Usage:' section as 'Description:' section, like <code>man</code> command in UNIX.</li>
2440
+ <li><code>postamble: {&ltheader&gt; =&gt; &lttext&gt;}</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
- #!/usr/bin/env ruby
2444
+ # coding: utf-8
1700
2445
  require 'benry/cmdapp'
1701
2446
 
1702
2447
  class SampleAction &lt Benry::CmdApp::Action
1703
2448
 
1704
2449
  @action.("test action #1",
1705
- <strong>detail:</strong> "Document: https://....", # !!!!
1706
- <strong>postamble:</strong> "(Tips: ....)") # !!!!
2450
+ <strong>detail: "See https://...."</strong>, # !!!!
2451
+ <strong>description: " Bla bla bla"</strong>, # !!!!
2452
+ <strong>postamble: {"Example:" =&gt; " ...."}</strong>) # !!!!
1707
2453
  def hello(user="world")
1708
2454
  puts "Hello, #{user}!"
1709
2455
  end
1710
2456
 
1711
2457
  end
1712
2458
 
1713
- config = Benry::CmdApp::Config.new("sample app")
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 ex32.rb -h
1720
- ex32.rb hello -- test action #1
2463
+ [bash]$ ruby ex50.rb -h hello
2464
+ ex50.rb hello --- test action #1
1721
2465
 
1722
- <strong>Document: https://....</strong> # !!!!
2466
+ <strong>See https://....</strong> # !!!!
1723
2467
 
1724
2468
  Usage:
1725
- $ ex32.rb hello [&ltuser&gt;]
2469
+ $ ex50.rb hello [&ltuser&gt;]
1726
2470
 
1727
- <strong>(Tips: ....)</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) Create a module and override methods of <code>Benry::CmdApp::ActionHelpBuilder</code> class.</li>
1732
- <li>(2) Prepend it to <code>Benry::CmdApp::ActionHelpBuilder</code> class.</li>
1733
- <li>(3) Create and execute Application object.</li>
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: ex33.rb</p>
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 &lt 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) Create a module and override methods of ``ActionHelpBuilder`` class.
1750
- <strong>module MyActionHelpBuilderMod</strong>
1751
- def <strong>build_help_message</strong>(command, all=false)
2497
+ ## (1) Define subclass of ``ActionHelpBuilder`` class.
2498
+ <strong>class MyActionHelpBuilder &lt 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>build_preamble</strong>(command, all=false)
2503
+ def <strong>section_preamble</strong>(metadata)
1755
2504
  super
1756
2505
  end
1757
- def <strong>build_usage</strong>(command, all=false)
2506
+ def <strong>section_usage</strong>(metadata, all: false)
1758
2507
  super
1759
2508
  end
1760
- def <strong>build_options</strong>(command, all=false)
2509
+ def <strong>section_description</strong>(metadata)
1761
2510
  super
1762
2511
  end
1763
- def <strong>build_postamble</strong>(command, all=false)
2512
+ def <strong>section_options</strong>(metadata, all: false)
1764
2513
  super
1765
2514
  end
1766
- def <strong>heading</strong>(str)
2515
+ def <strong>section_postamble</strong>(metadata)
1767
2516
  super
1768
2517
  end
1769
2518
  end
1770
2519
 
1771
- ## (2) Prepend it to ``Benry::CmdApp::ActionHelpBuilder`` class.
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
- app = Benry::CmdApp::Application.new(config)
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) Define subclass of <code>ActionHelpBuilder</code> class.</li>
1782
- <li>(2) Set it to <code>ACTION_HELP_BUILDER_CLASS</code> constant value.</li>
1783
- <li>(3) Create and execute Application object.</li>
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: ex34.rb</p>
2535
+ <p>File: ex52.rb</p>
1786
2536
  <pre class="language-ruby">
1787
- #!/usr/bin/env ruby
2537
+ # coding: utf-8
1788
2538
  require 'benry/cmdapp'
1789
2539
 
1790
2540
  class SampleAction &lt 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) Define subclass of ``ActionHelpBuilder`` class.
1800
- <strong>class MyActionHelpBuilder &lt Benry::CmdApp::ActionHelpBuilder</strong>
1801
- def build_help_message(command, all=false)
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 build_preamble(command, all=false)
2554
+ def <strong>section_preamble</strong>(metadata)
1805
2555
  super
1806
2556
  end
1807
- def build_usage(command, all=false)
2557
+ def <strong>section_usage</strong>(metadata, all: false)
1808
2558
  super
1809
2559
  end
1810
- def build_options(command, all=false)
2560
+ def <strong>section_description</strong>(metadata)
1811
2561
  super
1812
2562
  end
1813
- def build_postamble(command, all=false)
2563
+ def <strong>section_options</strong>(metadata, all: false)
1814
2564
  super
1815
2565
  end
1816
- def heading(str)
2566
+ def <strong>section_postamble</strong>(metadata)
1817
2567
  super
1818
2568
  end
1819
2569
  end
1820
2570
 
1821
- ## (2) Set it to ``ACTION_HELP_BUILDER_CLASS`` constant value.
1822
- Benry::CmdApp.module_eval do
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) Create and execute Application object.
1828
- config = Benry::CmdApp::Config.new("sample app")
1829
- app = Benry::CmdApp::Application.new(config)
1830
- exit app.main()
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 &amp; A</h2>
1836
- <section class="subsection" id="q-how-to-append-some-tasks-to-existing-action">
1837
- <h3>Q: How to Append Some Tasks to Existing Action?</h3>
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: ex41.rb</p>
2627
+ <p>File: ex61.rb</p>
1840
2628
  <pre class="language-ruby">
1841
2629
  require 'benry/cmdapp'
1842
2630
 
1843
2631
  class SampleAction &lt 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 of existing method
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 "---- &gt;8 ---- &gt;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
- config = Benry::CmdApp::Config.new("sample app")
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 ex41.rb hello
2669
+ [bash]$ ruby ex61.rb hello
1884
2670
  ---- &gt;8 ---- &gt;8 ----
1885
2671
  Hello, world!
1886
2672
  ---- 8&lt ---- 8&lt ----
1887
2673
 
1888
- [bash]$ ruby ex41.rb hi Alice
2674
+ [bash]$ ruby ex61.rb hi Alice
1889
2675
  ~~~~ &gt;8 ~~~~ &gt;8 ~~~~
1890
2676
  Hi, Alice!
1891
2677
  ~~~~ 8&lt ~~~~ 8&lt ~~~~
1892
2678
  </pre>
1893
2679
  </section>
1894
- <section class="subsection" id="q-how-to-re-define-existing-action">
1895
- <h3>Q: How to Re-define Existing Action?</h3>
1896
- <p>A: Remove existing action at first, and re-define action.</p>
1897
- <p>File: ex42.rb</p>
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("&ltaction&gt;")</code> or <code>Benry::CmdApp.undef_alias("&ltalias&gt;")</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> &lt Benry::CmdApp::Action
1907
2697
 
1908
2698
  end
1909
2699
 
1910
- Benry::CmdApp<strong>.delete_action("hello")</strong> # !!!!
2700
+ Benry::CmdApp<strong>.undef_action("hello")</strong> # !!!!
1911
2701
 
1912
2702
  class <strong>OtherAction</strong> &lt Benry::CmdApp::Action
1913
2703
 
@@ -1918,33 +2708,30 @@ class <strong>OtherAction</strong> &lt Benry::CmdApp::Action
1918
2708
 
1919
2709
  end
1920
2710
 
1921
- config = Benry::CmdApp::Config.new("sample app")
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 ex42.rb -h
1928
- ex42.rb -- sample app
2715
+ [bash]$ ruby ex62.rb -h
2716
+ ex62.rb --- sample app
1929
2717
 
1930
2718
  Usage:
1931
- $ ex42.rb [&ltoptions&gt;] [&ltaction&gt; [&ltarguments&gt;...]]
2719
+ $ ex62.rb [&ltoptions&gt;] &ltaction&gt; [&ltarguments&gt;...]
1932
2720
 
1933
2721
  Options:
1934
- -h, --help : print help message (of action if action specified)
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-delete-existing-actionalias">
1941
- <h3>Q: How to Delete Existing Action/Alias?</h3>
1942
- <p>A: Call <code>Benry::CmdApp.delete_action("&ltaction&gt;")</code> or <code>Benry::CmdApp.delete_alias("&ltalias&gt;")</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: ex43.rb</p>
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 &lt Benry::CmdApp::Action
1957
2744
 
1958
2745
  @action.("build")
1959
2746
  def build()
1960
- run_action_once("prepare")
2747
+ run_once("prepare")
1961
2748
  puts "... build something ..."
1962
2749
  end
1963
2750
 
1964
2751
  end
1965
2752
 
1966
- config = Benry::CmdApp::Config.new("sample app")
1967
- <strong>config.option_trace = true</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 ex43.rb -T build # !!!!
1974
- <strong>## enter: build</strong>
1975
- <strong>## enter: prepare</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>## exit: prepare</strong>
2762
+ <strong>### exit: prepare</strong>
1978
2763
  ... build something ...
1979
- <strong>## exit: build</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 Enable/Disable Color Mode?</h3>
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: ex44.rb</p>
2770
+ <p>File: ex64.rb</p>
1986
2771
  <pre class="language-ruby">
1987
2772
  require 'benry/cmdapp'
1988
2773
 
1989
2774
  class SampleAction &lt 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
- config = Benry::CmdApp::Config.new("sample app")
1999
- <strong>config.option_color = true</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 ex44.rb -h
2006
- ex44.rb -- sample app
2788
+ [bash]$ ruby ex64.rb -h
2789
+ ex64.rb --- sample app
2007
2790
 
2008
2791
  Usage:
2009
- $ ex44.rb [&ltoptions&gt;] [&ltaction&gt; [&ltarguments&gt;...]]
2792
+ $ ex64.rb [&ltoptions&gt;] &ltaction&gt; [&ltarguments&gt;...]
2010
2793
 
2011
2794
  Options:
2012
- -h, --help : print help message (of action if action specified)
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[=&lton|off&gt;] : enable/disable color</strong> # !!!!
2014
2799
 
2015
2800
  Actions:
2016
- hello : greeting message
2801
+ hello : print greeting message
2017
2802
 
2018
- [bash]$ ruby ex44.rb -h <strong>--color=off</strong> # !!!!
2803
+ [bash]$ ruby ex64.rb -h <strong>--color=off</strong> # !!!!
2019
2804
 
2020
- [bash]$ ruby ex44.rb -h <strong>--color=on</strong> # !!!!
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-multiple-option-like--i-option-of-ruby">
2024
- <h3>Q: How to Define Multiple Option, like <code>-I</code> Option of Ruby?</h3>
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: ex45.rb</p>
2812
+ <p>File: ex65.rb</p>
2027
2813
  <pre class="language-ruby">
2028
2814
  require 'benry/cmdapp'
2029
2815
 
2030
2816
  class TestAction &lt Benry::CmdApp::Action
2031
2817
 
2032
- @action.("multiple option test")
2033
- @option.(:path, "-I &ltpath&gt;", "path") <strong>{|options, key, val|</strong> # !!!!
2034
- <strong>arr = options[key] || []</strong> # !!!!
2035
- <strong>arr &lt&lt val</strong> # !!!!
2036
- <strong>arr</strong> # !!!!
2037
- ## or: # !!!!
2038
- #<strong>(options[key] || []) &lt&lt val</strong> # !!!!
2039
- <strong>}</strong> # !!!!
2040
- def test(path: [])
2041
- puts "path=#{path.inspect}" #=&gt; 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
- config = Benry::CmdApp::Config.new("test app")
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 ex45.rb test <strong>-I /tmp -I /var/tmp</strong> # !!!!
2053
- path=["/tmp", "/var/tmp"] # !!!!
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-specify-detailed-description-of-option">
2057
- <h3>Q: How to Specify Detailed Description of Option?</h3>
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 &lttopic&gt;</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: ex46.rb</p>
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 &lt Benry::CmdApp::Action
2064
2853
 
2065
2854
  @action.("detailed description test")
2066
2855
  @option.(:mode, "-m &ltmode&gt;", "output mode", <strong>detail:</strong> &lt&lt"END")
2067
- v, verbose: print many output
2068
- q, quiet: print litte output
2069
- c, compact: print summary output
2856
+ v, verbose: print many output
2857
+ q, quiet: print litte output
2858
+ c, compact: print summary output
2070
2859
  END
2071
- def test(mode: nil)
2860
+ def test_(mode: nil)
2072
2861
  puts "mode=#{mode.inspect}"
2073
2862
  end
2074
2863
 
2075
2864
  end
2076
2865
 
2077
- config = Benry::CmdApp::Config.new("test app")
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 ex46.rb -h test
2084
- ex46.rb test -- detailed description test
2870
+ [bash]$ ruby ex66.rb -h test
2871
+ ex66.rb test --- detailed description test
2085
2872
 
2086
2873
  Usage:
2087
- $ ex46.rb test [&ltoptions&gt;]
2874
+ $ ex66.rb test [&ltoptions&gt;]
2088
2875
 
2089
2876
  Options:
2090
2877
  -m &ltmode&gt; : output mode
2091
- <strong>v, verbose: print many output</strong>
2092
- <strong>q, quiet: print litte output</strong>
2093
- <strong>c, compact: print summary output</strong>
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 &lt Benry::CmdApp::Action
2104
-
2105
- @action.("test action #1")
2106
- @option.(:verbose, "-v, --verbose", "verbose mode")
2107
- @option.(:file, "-f, --file=&ltfile&gt;", "filename")
2108
- @option.(:indent, "-i, --indent[=&ltN&gt;]", "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 [&ltoptions&gt;]
2133
-
2134
- Options:
2135
- -v, --verbose : verbose mode # copied!!
2136
- -f, --file=&ltfile&gt; : filename # copied!!
2137
- -i, --indent[=&ltN&gt;] : 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-what-is-the-difference-between-prefixalias_of-and-prefixaction">
2142
- <h3>Q: What is the Difference Between <code>prefix(alias_of:)</code> and <code>prefix(action:)</code>?</h3>
2143
- <p>A: The former defines an alias, and the latter doesn't.</p>
2144
- <p>File: ex48.rb</p>
2145
- <pre class="language-ruby">
2146
- require 'benry/cmdapp'
2147
-
2148
- class AaaAction &lt 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 &lt 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 ex48.rb
2175
- ex48.rb -- sample app
2176
-
2177
- Usage:
2178
- $ ex48.rb [&ltoptions&gt;] [&ltaction&gt; [&ltarguments&gt;...]]
2179
-
2180
- Options:
2181
- -h, --help : print help message (of action if action specified)
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
- <strong>aaa : alias of 'aaa:print' action</strong> # !!!!
2185
- aaa:print : test #1
2186
- <strong>bbb : test #2</strong> # !!!!
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>In the above example, alias <code>aaa</code> is defined due to <code>prefix(alias_of:)</code>,
2189
- and action <code>bbb</code> is not an alias due to <code>prefix(action:)</code>.</p>
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 Change Order of Options in Help Message?</h3>
2193
- <p>A: Call <code>AppOptionSchema#sort_options_in_this_order()</code>.</p>
2194
- <p>File: ex49.rb</p>
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
- option_all: true,
2925
+ option_verbose: true,
2200
2926
  option_quiet: true,
2201
2927
  option_color: true,
2202
2928
  )
2203
- schema = Benry::CmdApp::AppOptionSchema.new(config)
2204
- <strong>keys = [:all, :quiet, :color, :help, :version]</strong> # !!!!
2205
- <strong>schema.sort_options_in_this_order(*keys)</strong> # !!!!
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.sort_options_in_this_order(*keys)</strong> # !!!!
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 ex49.rb -h
2215
- ex49.rb (1.0.0) -- sample app
2940
+ [bash]$ ruby ex68.rb -h
2941
+ ex68.rb (1.0.0) --- sample app
2216
2942
 
2217
2943
  Usage:
2218
- $ ex49.rb [&ltoptions&gt;] [&ltaction&gt; [&ltarguments&gt;...]]
2944
+ $ ex68.rb [&ltoptions&gt;] &ltaction&gt; [&ltarguments&gt;...]
2219
2945
 
2220
2946
  Options:
2221
- -a, --all : list all actions/options including private (hidden) ones
2947
+ -v, --verbose : verbose mode
2222
2948
  -q, --quiet : quiet mode
2223
- --color[=&lton|off&gt;] : enable/disable color
2224
- -h, --help : print help message (of action if action specified)
2949
+ --color[=&lton|off&gt;] : 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 &lttopic&gt; : 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 &lt 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 [&ltoptions&gt;] [&ltaction&gt; [&ltarguments&gt;...]]
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-is-it-possible-to-add-metadata-to-action-or-option">
2271
- <h3>Q: Is It Possible to Add Metadata to Action or Option?</h3>
2272
- <p>A: Yes. Pass <code>tag:</code> keyword argument to <code>@action.()</code> or <code>@option.()</code>.</p>
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::CmdApp doesn't provide the good way to use it effectively.
2276
- This feature may be used by command-line application or framework based on Benry::CmdApp.</li>
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: ex51.rb</p>
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 &lt Benry::CmdApp::Action
2291
2981
 
2292
2982
  end
2293
2983
 
2294
- config = Benry::CmdApp::Config.new("sample app")
2295
- app = Benry::CmdApp::Application.new(config)
2296
- exit app.main()
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 Make Error Messages I18Ned?</h3>
2301
- <p>A: Currently not supported. May be supported in the future release.</p>
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">