como 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -103,7 +103,7 @@
103
103
  </div>
104
104
 
105
105
  <div id="footer">
106
- Generated on Wed Apr 23 19:33:20 2014 by
106
+ Generated on Wed Jul 9 14:02:42 2014 by
107
107
  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
108
108
  0.8.6.1 (ruby-1.9.3).
109
109
  </div>
@@ -0,0 +1,14 @@
1
+ #!/usr/bin/env ruby
2
+
3
+ require "como"
4
+ include Como
5
+
6
+ # Define command line arguments:
7
+ Spec.command( "como_simple", "Programmer", "2013",
8
+ [
9
+ [ :single, "file", "-f", "File argument." ],
10
+ [ :switch, "debug", "-d", "Enable debugging." ],
11
+ ] )
12
+
13
+ puts " File option: #{Opt['file'].value}"
14
+ puts " Debugging selected!" if Opt['debug'].given
@@ -0,0 +1,38 @@
1
+ #!/usr/bin/env ruby
2
+
3
+ require "como"
4
+ include Como
5
+
6
+ Spec.program( "Programmer", "2013" ) do
7
+
8
+ command( "como_subcmd", [
9
+ [ :subcmd, "add", nil, "Add file." ],
10
+ [ :subcmd, "rm", nil, "Remove file." ],
11
+ ], )
12
+
13
+ subcmd( "add", [
14
+ [ :switch, "force", "-fo", "Force operation." ],
15
+ [ :opt_single, "password", "-p", "User password." ],
16
+ [ :opt_single, "username", "-u", "Username." ],
17
+ [ :single, "file", "-f", "File." ],
18
+ ] )
19
+
20
+ check do
21
+ one(
22
+ '-fo',
23
+ all( 'password', 'username' )
24
+ )
25
+ end
26
+
27
+ subcmd( "rm", [
28
+ [ :single, "file", "-f", "File." ],
29
+ ] )
30
+
31
+ end
32
+
33
+ subcmd = Opt.master.givenSubcmd
34
+
35
+ case subcmd.name
36
+ when 'add'; puts " Adding file \"#{subcmd['file'].value}\"..."
37
+ when 'rm'; puts " Removing file \"#{subcmd['file'].value}\"..."
38
+ end
data/lib/como.rb CHANGED
@@ -1,6 +1,6 @@
1
- # = Como
1
+ # Como
2
2
  #
3
- # == Introduction
3
+ # = Introduction
4
4
  #
5
5
  # Como provides low manifest command line option parsing and
6
6
  # deployment. The command line options are described in compact table
@@ -12,18 +12,18 @@
12
12
  #
13
13
  #
14
14
  #
15
- # == Usage Examples
15
+ # = Usage Examples
16
16
  #
17
17
  # Two simple examples are presented in this section. First one
18
18
  # includes a straight forward command definition and the second is a
19
19
  # bit more complicated with subcommand feature in use.
20
20
  #
21
- # === Simple example
21
+ # == Simple example
22
22
  #
23
23
  # Below is a small example program ("como_simple") that demonstrates
24
24
  # typical usage.
25
25
  #
26
- # ==== Program listing
26
+ # === Program listing
27
27
  #
28
28
  # require "como"
29
29
  # include Como
@@ -76,7 +76,7 @@
76
76
  # "help" ("-h") option is given. Help option is added to the command
77
77
  # automatically as default behavior.
78
78
  #
79
- # ==== Simple example executions
79
+ # === Simple example executions
80
80
  #
81
81
  # Normal behavior would be achieved by executing:
82
82
  # shell> como_simple -f example -d
@@ -101,8 +101,7 @@
101
101
  #
102
102
  # como_simple error: Option "-f" missing for "como_simple"...
103
103
  #
104
- # Usage:
105
- # como_simple -f <file> [-d]
104
+ # como_simple -f <file> [-d]
106
105
  #
107
106
  # -f File argument.
108
107
  # -d Enable debugging.
@@ -122,19 +121,19 @@
122
121
  # would display the same "usage" screen except without the error
123
122
  # line.
124
123
  #
125
- # === Subcommand example
124
+ # == Subcommand example
126
125
  #
127
126
  # Subcmd example includes a program which has subcommands. Subcommands
128
127
  # can have their own command line switches and options.
129
128
  #
130
- # ==== Program listing
129
+ # === Program listing
131
130
  #
132
131
  # require "como"
133
132
  # include Como
134
133
  #
135
134
  # Spec.program( "Programmer", "2013" ) do
136
135
  #
137
- # subcmd( "como_subcmd", [
136
+ # command( "como_subcmd", [
138
137
  # [ :subcmd, "add", nil, "Add file." ],
139
138
  # [ :subcmd, "rm", nil, "Remove file." ],
140
139
  # ], )
@@ -146,7 +145,7 @@
146
145
  # [ :single, "file", "-f", "File." ],
147
146
  # ] )
148
147
  #
149
- # checkRule do
148
+ # check do
150
149
  # one(
151
150
  # '-fo',
152
151
  # all( 'password', 'username' )
@@ -170,18 +169,18 @@
170
169
  # subcommands. The author and date are provided as parameters, and the
171
170
  # program and subcommand options are defined in block.
172
171
  #
173
- # The first "subcmd" method call defines the main command
172
+ # The first "command" (or "subcmd") method call defines the main command
174
173
  # ("Opt.main") which represents the program. It has two "subcmd"
175
- # options.
174
+ # options ("add" and "rm").
176
175
  #
177
176
  # The rest of the "subcmd" methods define subcommands for the parent
178
177
  # command. This example includes one subcommand level, but multiple
179
178
  # levels are allowed.
180
179
  #
181
- # The "checkRule" method defines option combination (RuleCheck) for
182
- # the previous subcommand definition. In this case the definition
183
- # allows "add" to have either the "-fo" option defined or "password"
184
- # and "username" in combination.
180
+ # The "check" (or "checkRule") method defines option combination
181
+ # ({RuleCheck}) for the previous subcommand definition. In this case the
182
+ # definition allows "add" to have either the "-fo" option defined or
183
+ # "password" and "username" in combination.
185
184
  #
186
185
  # Main (root) commands can be referenced through
187
186
  # Opt.main
@@ -198,7 +197,7 @@
198
197
  # The given subcommand can be accessed with "givenSubcmd" method from
199
198
  # each parent command.
200
199
  #
201
- # ==== Subcommand example executions
200
+ # === Subcommand example executions
202
201
  #
203
202
  # Normal behavior would be achieved by executing:
204
203
  # shell> como_subcmd add -fo -f example
@@ -229,8 +228,8 @@
229
228
  # | | |--<password>
230
229
  # | | |--<username>
231
230
  #
232
- # Since the combination rule requires either "-fo" or both "password"
233
- # and "username" in a pair.
231
+ # since the combination rule requires either "-fo", or both "password"
232
+ # and "username".
234
233
  #
235
234
  # Help is automatically provided on each command level, thus these are
236
235
  # both valid.
@@ -240,9 +239,9 @@
240
239
  #
241
240
  #
242
241
  #
243
- # == Option specification
242
+ # = Option specification
244
243
  #
245
- # === Overview
244
+ # == Overview
246
245
  #
247
246
  # Option specification includes the minimum set of information
248
247
  # required for command line parsing. It is used to:
@@ -254,7 +253,7 @@
254
253
  # switches.
255
254
  # * Generate Usage Help printout.
256
255
  #
257
- # === Option types
256
+ # == Option types
258
257
  #
259
258
  # The following types can be defined for the command line options:
260
259
  # [:subcmd] Subcmd option. Subcmd specific options are provided
@@ -299,7 +298,7 @@
299
298
  # [ :silent, "terminator", "-", "The terminator." ],
300
299
  #
301
300
  #
302
- # === Option specification method configuration
301
+ # == Option specification method configuration
303
302
  #
304
303
  # Option behavior can be controlled with several configuration options.
305
304
  #
@@ -324,12 +323,13 @@
324
323
  # [:check_invalid] Error for unknown options (default: true).
325
324
  # [:tab] Tab stop column for option documentation (default: 12).
326
325
  # [:help_exit] Exit program if help displayed (default: true).
326
+ # [:copyright] Display copyright/author in usage printout (default: true).
327
327
  #
328
328
  #
329
329
  #
330
- # == Option referencing
330
+ # = Option referencing
331
331
  #
332
- # === Existence and values
332
+ # == Existence and values
333
333
  #
334
334
  # Opt class includes the parsed option values. All options can be
335
335
  # tested whether they are specified on the command line using:
@@ -363,7 +363,7 @@
363
363
  # Opt['many_files_or_none'].value.length
364
364
  # And finally decide what to do.
365
365
  #
366
- # === Options including parameters
366
+ # == Options including parameters
367
367
  #
368
368
  # Sometimes it is convenient for the program to use an option to
369
369
  # include multiple parameter settings. These settings can be parsed
@@ -375,7 +375,7 @@
375
375
  # And a Hash is returned:
376
376
  # { 'rounds' => 10, 'length' => 5 }
377
377
  #
378
- # === Subcommand options
378
+ # == Subcommand options
379
379
  #
380
380
  # The given subcommand for the parent command is return by
381
381
  # "givenSubcmd". Commonly the program creator should just check
@@ -384,14 +384,14 @@
384
384
  # if Opt['como_subcmd']['add'].given
385
385
  # ...
386
386
  #
387
- # === Program external options
387
+ # == Program external options
388
388
  #
389
389
  # If the user gives the "--" option (double-dash), the arguments after
390
- # that option is returned as an Array with "Opt.external".
390
+ # that option are returned as an Array with "Opt.external".
391
391
  #
392
392
  #
393
393
  #
394
- # == Option combination checks
394
+ # = Option combination checks
395
395
  #
396
396
  # Como provides a facility to create relations between options using
397
397
  # RuleCheck DSL. This is needed since sometimes options have to be
@@ -413,11 +413,51 @@
413
413
  # Examples can be found above.
414
414
  #
415
415
  #
416
- # == Customization
416
+ # = Customization
417
417
  #
418
- # If the default behavior is not satisfactory, changes can be
419
- # implemented simply by overloading the existing functions. Some
420
- # knowledge of the internal workings of Como is required though.
418
+ # A user specific customization file can be referenced through the
419
+ # "COMO" environment variable. If environment variable "COMO" is
420
+ # defined, the referenced file is read in as Ruby file as a last phase
421
+ # when Como is loaded from the program (require). Proposed naming
422
+ # convention for the customization is:
423
+ #
424
+ # $HOME/.como
425
+ #
426
+ # User can define a pre and a post action hook in the file.
427
+ #
428
+ # The pre-hook can be used for example to change the Como config
429
+ # defaults. It is run before the body of "Spec.command" or
430
+ # "Spec.program" is executed. It is passed all the parameters that has
431
+ # been passed to "Spec.command" or "Spec.program", only collected into
432
+ # a Hash. The Hash keys are method parameter names as symbols.
433
+ #
434
+ # Example:
435
+ # # Define pre parser hook for Como.
436
+ # Como.preHook do |args|
437
+ #
438
+ # # Get default config for options.
439
+ # config = Como::Opt.configGet
440
+ #
441
+ # # Disable 'copyright' lines from usage.
442
+ # config[ :copyright ] = false
443
+ #
444
+ # # Test if "Spec.command" is the entry method (it has arg named "prog").
445
+ # if args[ :prog ]
446
+ # # Place a custom header for all programs.
447
+ # config[ :header ] = "\nProgram \"#{args[ :prog ]}\" is ...\n\n"
448
+ # end
449
+ # end
450
+ #
451
+ # There is no predefined use cases for post-hook. Post-hook is passed
452
+ # the Opt.main as parameter.
453
+ #
454
+ # If the provided customization facilities are not satisfactory,
455
+ # changes can be implemented simply by overloading the existing
456
+ # functions. Some knowledge of the internal workings of Como is
457
+ # required though.
458
+ #
459
+ # Como version is returned with:
460
+ # Como.version
421
461
 
422
462
  module Como
423
463
 
@@ -428,6 +468,9 @@ module Como
428
468
  # Default value for display output.
429
469
  @@io = STDOUT
430
470
 
471
+ # Hooks.
472
+ @@hook = {}
473
+
431
474
  # Set @@io.
432
475
  def ComoCommon.setIo( io )
433
476
  @@io = io
@@ -437,6 +480,27 @@ module Como
437
480
  def ComoCommon.getIo
438
481
  @@io
439
482
  end
483
+
484
+ def ComoCommon.setHook( name, &code )
485
+ @@hook[ name ] = code
486
+ end
487
+
488
+ def ComoCommon.runHook( name, args )
489
+ @@hook[ name ].yield( args ) if @@hook[ name ]
490
+ end
491
+
492
+ end
493
+
494
+
495
+ # Set "preHook" routine.
496
+ def Como.preHook( &code )
497
+ ComoCommon.setHook( :preHook, &code )
498
+ end
499
+
500
+
501
+ # Set "postHook" routine.
502
+ def Como.postHook( &code )
503
+ ComoCommon.setHook( :postHook, &code )
440
504
  end
441
505
 
442
506
 
@@ -449,12 +513,24 @@ module Como
449
513
  # @param year [String] Year (or dates) for program.
450
514
  # @yield [] Subcmd definitions.
451
515
  def Spec.program( author, year, config = nil, &defs )
516
+
517
+ preHookArgs = {
518
+ :author => author,
519
+ :year => year,
520
+ :config => config,
521
+ :defs => defs,
522
+ }
523
+
524
+ ComoCommon.runHook( :preHook, preHookArgs )
525
+
452
526
  if config
453
527
  Opt.configOverlay( config )
454
528
  end
455
529
  spec = Spec.new( author, year )
456
530
  spec.instance_eval( &defs )
457
531
  Opt.main.check( ArgsParseState.new( @@argv ) )
532
+
533
+ ComoCommon.runHook( :postHook, Opt.main )
458
534
  end
459
535
 
460
536
 
@@ -469,15 +545,29 @@ module Como
469
545
  # @param config [Hash] Option definition's behavioral config
470
546
  # (changes @@config defaults).
471
547
  def Spec.command( prog, author, year, defs, config = {} )
548
+
549
+ preHookArgs = {
550
+ :prog => prog,
551
+ :author => author,
552
+ :year => year,
553
+ :defs => defs,
554
+ :config => config,
555
+ }
556
+
557
+ ComoCommon.runHook( :preHook, preHookArgs )
558
+
472
559
  Spec.defineCheck( prog, author, year, defs, config )
473
- # Spec.usage if Opt['help'].given
560
+
561
+ ComoCommon.runHook( :postHook, Opt.main )
474
562
  end
475
563
 
564
+
476
565
  # Alias to Spec.command.
477
566
  def Spec.defineCheckHelp( prog, author, year, defs, config = {} )
478
567
  Spec.command( prog, author, year, defs, config )
479
568
  end
480
569
 
570
+
481
571
  # Same as "defineCheckHelp" except without automatic "help"
482
572
  # option processing.
483
573
  def Spec.defineCheck( prog, author, year, defs, config = {} )
@@ -538,6 +628,10 @@ module Como
538
628
  end
539
629
 
540
630
 
631
+ # Alias to subcmd to highlight the main command.
632
+ alias command subcmd
633
+
634
+
541
635
  # Specify and check options spec.
542
636
  #
543
637
  # @param table [Array<Array>] Option definition table.
@@ -645,6 +739,9 @@ module Como
645
739
  end
646
740
 
647
741
 
742
+ # Alias for Spec.checkRule.
743
+ def Spec.check( opt = nil, &rule ) Spec.checkRule( opt = nil, &rule ) end
744
+
648
745
  # Check option combination rules.
649
746
  #
650
747
  # @param opt [String] Opt name to which rules are set. If not
@@ -659,6 +756,11 @@ module Como
659
756
  opt.setRuleCheck( &rule )
660
757
  end
661
758
 
759
+
760
+ # Alias for checkRule
761
+ alias check checkRule
762
+
763
+
662
764
  # Additional option check.
663
765
  # @param opt [String] Option name.
664
766
  # @param error [String] Error string for false return values (from check).
@@ -731,6 +833,7 @@ module Como
731
833
  :check_invalid => true,
732
834
  :tab => 12,
733
835
  :help_exit => true,
836
+ :copyright => true,
734
837
  }
735
838
 
736
839
 
@@ -864,6 +967,20 @@ module Como
864
967
  end
865
968
 
866
969
 
970
+ # Return default config for Como options.
971
+ def Opt.configGet
972
+ @@config
973
+ end
974
+
975
+
976
+ # Set default config for Como options. User can manipulate the
977
+ # defaults with "preHook".
978
+ def Opt.configSet( config )
979
+ @@config = config
980
+ end
981
+
982
+
983
+
867
984
  # ------------------------------------------------------------
868
985
  # Opt properties:
869
986
 
@@ -1516,33 +1633,12 @@ module Como
1516
1633
  str += "\
1517
1634
  Subcommand \"#{@name}\" usage:
1518
1635
  #{fullCommand} #{cmdline.join(" ")}
1519
-
1520
1636
  "
1521
1637
  str += suboptDoc
1522
1638
 
1523
1639
  str += "\n"
1524
1640
  end
1525
1641
 
1526
- # Usage info for Opt:s.
1527
- def usageNormalOld
1528
- str = ""
1529
-
1530
- if @config[ :header ]
1531
- str += "\n"
1532
- str += @config[ :header ]
1533
- str += "\n"
1534
- end
1535
-
1536
- str += usageCommand
1537
-
1538
- if @config[ :footer ]
1539
- str += @config[ :footer ]
1540
- str += "\n"
1541
- end
1542
-
1543
- str
1544
- end
1545
-
1546
1642
  # Usage info for Opt:s.
1547
1643
  def usageNormal
1548
1644
  str = ""
@@ -1616,6 +1712,8 @@ module Como
1616
1712
  str = ""
1617
1713
  # format = Proc.new do |s,d| ( " %-#{@config[ :tab ]}s%s\n" % [ s, d ] ) end
1618
1714
 
1715
+ str += "\n"
1716
+
1619
1717
  str += " Options:\n" if hasSubcmd && hasVisibleOptions
1620
1718
 
1621
1719
  @subopt.each do |o|
@@ -1771,34 +1869,21 @@ module Como
1771
1869
  end
1772
1870
 
1773
1871
 
1774
- # Usage printout for command.
1775
- def usageCommandOld
1776
- str = "
1777
- Usage:
1778
- #{fullCommand} #{cmdline.join(" ")}
1779
-
1780
- "
1781
- str += suboptDoc
1782
-
1783
- str += "
1784
-
1785
- Copyright (c) #{Opt.year} by #{Opt.author}
1786
-
1787
- "
1788
- end
1789
-
1790
1872
  # Usage printout for command.
1791
1873
  def usageCommand
1792
1874
  str = "\
1793
1875
  #{fullCommand} #{cmdline.join(" ")}
1794
-
1795
1876
  "
1796
1877
  str += suboptDoc
1797
1878
 
1798
- str += "
1879
+ if @config[ :copyright ]
1880
+ str += "
1799
1881
 
1800
1882
  Copyright (c) #{Opt.year} by #{Opt.author}
1801
1883
  "
1884
+ end
1885
+
1886
+ str
1802
1887
  end
1803
1888
 
1804
1889
  end
@@ -2103,3 +2188,11 @@ module Como
2103
2188
 
2104
2189
 
2105
2190
  end
2191
+
2192
+
2193
+ # Include version definitions.
2194
+ require 'version'
2195
+
2196
+
2197
+ # Load user customizations (if any).
2198
+ load ENV['COMO'] if ENV['COMO']
data/lib/version.rb ADDED
@@ -0,0 +1,11 @@
1
+ module Como
2
+
3
+ def Como.version
4
+ ComoCommon::VERSION
5
+ end
6
+
7
+ class ComoCommon
8
+ VERSION="0.1.3"
9
+ end
10
+
11
+ end
data/test/como_rule_1 CHANGED
@@ -17,7 +17,7 @@ Spec.command( "como_rule_1", "Como Tester", "2013",
17
17
  ] )
18
18
 
19
19
 
20
- Spec.checkRule do
20
+ Spec.check do
21
21
  one(
22
22
  none,
23
23
  any( 'debug', 'mode' ),
@@ -5,7 +5,7 @@ include Como
5
5
 
6
6
  Spec.program( "Como Tester", "2013" ) do
7
7
 
8
- subcmd( "como_subcmd",
8
+ command( "como_subcmd",
9
9
  [
10
10
  [ :opt_single, "password", "-p", "User password." ],
11
11
  [ :opt_multi, "username", "-u", "Username(s)." ],
@@ -28,7 +28,7 @@ Spec.program( "Como Tester", "2013" ) do
28
28
  ] )
29
29
 
30
30
 
31
- checkRule do
31
+ check do
32
32
  one( 'file', 'username', inv( '-fo' ) )
33
33
  end
34
34
 
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: como
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.2
4
+ version: 0.1.3
5
5
  prerelease:
6
6
  platform: ruby
7
7
  authors:
@@ -9,7 +9,7 @@ authors:
9
9
  autorequire:
10
10
  bindir: bin
11
11
  cert_chain: []
12
- date: 2014-04-23 00:00:00.000000000 Z
12
+ date: 2014-07-09 00:00:00.000000000 Z
13
13
  dependencies: []
14
14
  description: ! 'Como provides low manifest command line option parsing and deployment.
15
15
  The command line options are described in compact table format and option values
@@ -30,6 +30,7 @@ files:
30
30
  - LICENSE
31
31
  - Rakefile
32
32
  - lib/como.rb
33
+ - lib/version.rb
33
34
  - test/test_subcmd
34
35
  - test/como_subcmd_rule
35
36
  - test/test_como.rb
@@ -86,6 +87,8 @@ files:
86
87
  - doc/Como/Spec.html
87
88
  - doc/file.CHANGELOG.html
88
89
  - doc/frames.html
90
+ - examples/como_simple
91
+ - examples/como_subcmd
89
92
  homepage:
90
93
  licenses:
91
94
  - Ruby