benry-cmdapp 0.2.0 → 1.0.0

Sign up to get free protection for your applications and to get access to all the features.
@@ -21,23 +21,23 @@
21
21
  <ul class="nav">
22
22
  </ul>
23
23
  </nav>
24
- <p>($Release: 0.2.0 $)</p>
24
+ <p>($Release: 1.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,37 +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
1773
  <li>If <code>hidden: true</code> keyword argument passed to <code>@action.()</code>,
1120
- or action method is private, then Benry::CmdApp regards that action as private.</li>
1121
- <li>Private actions are hidden in help message.</li>
1122
- <li>Private actions are shown when <code>-a</code> or <code>--all</code> option enabled and specified.</li>
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>
1123
1777
  </ul>
1124
- <p>File: ex20.rb</p>
1778
+ <p>File: ex36.rb</p>
1125
1779
  <pre class="language-ruby">
1126
- #!/usr/bin/env ruby
1780
+ # coding: utf-8
1127
1781
  require 'benry/cmdapp'
1128
1782
 
1129
1783
  class SampleAction &lt Benry::CmdApp::Action
@@ -1147,54 +1801,35 @@ 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 defined with <code>hidden: true</code> keyword argument are treated as private option.</li>
1192
- <li>Private options are hidden in help message of action.</li>
1193
- <li>Private options are shown when <code>-a</code> or <code>--all</code> option enabled and specified.</li>
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
@@ -1203,38 +1838,91 @@ class SampleAction &lt Benry::CmdApp::Action
1203
1838
  @option.(:verbose, "-v", "verbose mode")
1204
1839
  @option.(:debug , "-D", "debug mode", <strong>hidden: true</strong>) # !!!!
1205
1840
  def test1(verbose: false, debug: false)
1206
- puts "verbose=#{verbose}, debug=#{_debug}"
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">