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