como 0.1.2 → 0.1.3

data/doc/top-level-namespace.html

@@ -103,7 +103,7 @@
 </div>
 
     <div id="footer">
-  Generated on Wed Apr 23 19:33:20 2014 by
+  Generated on Wed Jul  9 14:02:42 2014 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.8.6.1 (ruby-1.9.3).
 </div>

data/examples/como_simple

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "como"
+include Como
+
+# Define command line arguments:
+Spec.command( "como_simple", "Programmer", "2013",
+  [
+    [ :single, "file",  "-f", "File argument." ],
+    [ :switch, "debug", "-d", "Enable debugging." ],
+  ] )
+
+puts "  File option: #{Opt['file'].value}"
+puts "  Debugging selected!" if Opt['debug'].given

data/examples/como_subcmd

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+
+require "como"
+include Como
+
+Spec.program( "Programmer", "2013" ) do
+
+    command( "como_subcmd", [
+       [ :subcmd,      "add",       nil,  "Add file." ],
+       [ :subcmd,      "rm",        nil,  "Remove file." ],
+      ], )
+
+    subcmd( "add", [
+       [ :switch,      "force",     "-fo", "Force operation." ],
+       [ :opt_single,  "password",  "-p",  "User password." ],
+       [ :opt_single,  "username",  "-u",  "Username." ],
+       [ :single,      "file",      "-f",  "File." ],
+      ] )
+
+    check do
+        one(
+            '-fo',
+            all( 'password', 'username' )
+            )
+    end
+
+    subcmd( "rm", [
+       [ :single,  "file",      "-f",  "File." ],
+      ] )
+
+end
+
+subcmd = Opt.master.givenSubcmd
+
+case subcmd.name
+when 'add'; puts "  Adding file \"#{subcmd['file'].value}\"..."
+when 'rm';  puts "  Removing file \"#{subcmd['file'].value}\"..."
+end

data/lib/como.rb

@@ -1,6 +1,6 @@
-# = Como
+# Como
 #
-# == Introduction
+# = Introduction
 #
 # Como provides low manifest command line option parsing and
 # deployment. The command line options are described in compact table
@@ -12,18 +12,18 @@
 #
 #
 #
-# == Usage Examples
+# = Usage Examples
 #
 # Two simple examples are presented in this section. First one
 # includes a straight forward command definition and the second is a
 # bit more complicated with subcommand feature in use.
 #
-# === Simple example
+# == Simple example
 #
 # Below is a small example program ("como_simple") that demonstrates
 # typical usage.
 #
-# ==== Program listing
+# === Program listing
 #
 #  require "como"
 #  include Como
@@ -76,7 +76,7 @@
 # "help" ("-h") option is given. Help option is added to the command
 # automatically as default behavior.
 #
-# ==== Simple example executions
+# === Simple example executions
 #
 # Normal behavior would be achieved by executing:
 #   shell> como_simple -f example -d
@@ -101,8 +101,7 @@
 #
 #  como_simple error: Option "-f" missing for "como_simple"...
 #
-#    Usage:
-#      como_simple -f <file> [-d]
+#    como_simple -f <file> [-d]
 #
 #    -f          File argument.
 #    -d          Enable debugging.
@@ -122,19 +121,19 @@
 # would display the same "usage" screen except without the error
 # line.
 #
-# === Subcommand example
+# == Subcommand example
 #
 # Subcmd example includes a program which has subcommands. Subcommands
 # can have their own command line switches and options.
 #
-# ==== Program listing
+# === Program listing
 #
 #  require "como"
 #  include Como
 #
 #  Spec.program( "Programmer", "2013" ) do
 #
-#      subcmd( "como_subcmd", [
+#      command( "como_subcmd", [
 #         [ :subcmd,      "add",       nil,  "Add file." ],
 #         [ :subcmd,      "rm",        nil,  "Remove file." ],
 #        ], )
@@ -146,7 +145,7 @@
 #         [ :single,      "file",      "-f",  "File." ],
 #        ] )
 #
-#      checkRule do
+#      check do
 #          one(
 #              '-fo',
 #              all( 'password', 'username' )
@@ -170,18 +169,18 @@
 # subcommands. The author and date are provided as parameters, and the
 # program and subcommand options are defined in block.
 #
-# The first "subcmd" method call defines the main command
+# The first "command" (or "subcmd") method call defines the main command
 # ("Opt.main") which represents the program. It has two "subcmd"
-# options.
+# options ("add" and "rm").
 #
 # The rest of the "subcmd" methods define subcommands for the parent
 # command. This example includes one subcommand level, but multiple
 # levels are allowed.
 #
-# The "checkRule" method defines option combination (RuleCheck) for
-# the previous subcommand definition. In this case the definition
-# allows "add" to have either the "-fo" option defined or "password"
-# and "username" in combination.
+# The "check" (or "checkRule") method defines option combination
+# ({RuleCheck}) for the previous subcommand definition. In this case the
+# definition allows "add" to have either the "-fo" option defined or
+# "password" and "username" in combination.
 #
 # Main (root) commands can be referenced through
 #   Opt.main
@@ -198,7 +197,7 @@
 # The given subcommand can be accessed with "givenSubcmd" method from
 # each parent command.
 #
-# ==== Subcommand example executions
+# === Subcommand example executions
 #
 # Normal behavior would be achieved by executing:
 #   shell> como_subcmd add -fo -f example
@@ -229,8 +228,8 @@
 #      |     |     |--<password>
 #      |     |     |--<username>
 #
-# Since the combination rule requires either "-fo" or both "password"
-# and "username" in a pair.
+# since the combination rule requires either "-fo", or both "password"
+# and "username".
 #
 # Help is automatically provided on each command level, thus these are
 # both valid.
@@ -240,9 +239,9 @@
 #
 #
 #
-# == Option specification
+# = Option specification
 #
-# === Overview
+# == Overview
 #
 # Option specification includes the minimum set of information
 # required for command line parsing. It is used to:
@@ -254,7 +253,7 @@
 #   switches.
 # * Generate Usage Help printout.
 #
-# === Option types
+# == Option types
 #
 # The following types can be defined for the command line options:
 # [:subcmd] Subcmd option. Subcmd specific options are provided
@@ -299,7 +298,7 @@
 #   [ :silent, "terminator", "-", "The terminator." ],
 #
 #
-# === Option specification method configuration
+# == Option specification method configuration
 #
 # Option behavior can be controlled with several configuration options.
 #
@@ -324,12 +323,13 @@
 # [:check_invalid] Error for unknown options (default: true).
 # [:tab] Tab stop column for option documentation (default: 12).
 # [:help_exit] Exit program if help displayed (default: true).
+# [:copyright] Display copyright/author in usage printout (default: true).
 #
 #
 #
-# == Option referencing
+# = Option referencing
 #
-# === Existence and values
+# == Existence and values
 #
 # Opt class includes the parsed option values. All options can be
 # tested whether they are specified on the command line using:
@@ -363,7 +363,7 @@
 #   Opt['many_files_or_none'].value.length
 # And finally decide what to do.
 #
-# === Options including parameters
+# == Options including parameters
 #
 # Sometimes it is convenient for the program to use an option to
 # include multiple parameter settings. These settings can be parsed
@@ -375,7 +375,7 @@
 # And a Hash is returned:
 #   { 'rounds' => 10, 'length' => 5 }
 #
-# === Subcommand options
+# == Subcommand options
 #
 # The given subcommand for the parent command is return by
 # "givenSubcmd". Commonly the program creator should just check
@@ -384,14 +384,14 @@
 #   if Opt['como_subcmd']['add'].given
 #      ...
 #
-# === Program external options
+# == Program external options
 #
 # If the user gives the "--" option (double-dash), the arguments after
-# that option is returned as an Array with "Opt.external".
+# that option are returned as an Array with "Opt.external".
 #
 #
 #
-# == Option combination checks
+# = Option combination checks
 #
 # Como provides a facility to create relations between options using
 # RuleCheck DSL. This is needed since sometimes options have to be
@@ -413,11 +413,51 @@
 # Examples can be found above.
 #
 #
-# == Customization
+# = Customization
 #
-# If the default behavior is not satisfactory, changes can be
-# implemented simply by overloading the existing functions. Some
-# knowledge of the internal workings of Como is required though.
+# A user specific customization file can be referenced through the
+# "COMO" environment variable. If environment variable "COMO" is
+# defined, the referenced file is read in as Ruby file as a last phase
+# when Como is loaded from the program (require). Proposed naming
+# convention for the customization is:
+#
+#   $HOME/.como
+#
+# User can define a pre and a post action hook in the file.
+#
+# The pre-hook can be used for example to change the Como config
+# defaults. It is run before the body of "Spec.command" or
+# "Spec.program" is executed. It is passed all the parameters that has
+# been passed to "Spec.command" or "Spec.program", only collected into
+# a Hash. The Hash keys are method parameter names as symbols.
+#
+# Example:
+#  # Define pre parser hook for Como.
+#  Como.preHook do |args|
+#
+#      # Get default config for options.
+#      config = Como::Opt.configGet
+#
+#      # Disable 'copyright' lines from usage.
+#      config[ :copyright ] = false
+#
+#      # Test if "Spec.command" is the entry method (it has arg named "prog").
+#      if args[ :prog ]
+#          # Place a custom header for all programs.
+#          config[ :header ] = "\nProgram \"#{args[ :prog ]}\" is ...\n\n"
+#      end
+#  end
+#
+# There is no predefined use cases for post-hook. Post-hook is passed
+# the Opt.main as parameter.
+#
+# If the provided customization facilities are not satisfactory,
+# changes can be implemented simply by overloading the existing
+# functions. Some knowledge of the internal workings of Como is
+# required though.
+#
+# Como version is returned with:
+#  Como.version
 
 module Como
 
@@ -428,6 +468,9 @@ module Como
         # Default value for display output.
         @@io = STDOUT
 
+        # Hooks.
+        @@hook = {}
+
         # Set @@io.
         def ComoCommon.setIo( io )
             @@io = io
@@ -437,6 +480,27 @@ module Como
         def ComoCommon.getIo
             @@io
         end
+
+        def ComoCommon.setHook( name, &code )
+            @@hook[ name ] = code
+        end
+
+        def ComoCommon.runHook( name, args )
+            @@hook[ name ].yield( args ) if @@hook[ name ]
+        end
+
+    end
+
+
+    # Set "preHook" routine.
+    def Como.preHook( &code )
+        ComoCommon.setHook( :preHook, &code )
+    end
+
+
+    # Set "postHook" routine.
+    def Como.postHook( &code )
+        ComoCommon.setHook( :postHook, &code )
     end
 
 
@@ -449,12 +513,24 @@ module Como
         # @param year [String] Year (or dates) for program.
         # @yield [] Subcmd definitions.
         def Spec.program( author, year, config = nil, &defs )
+
+            preHookArgs = {
+                :author => author,
+                :year => year,
+                :config => config,
+                :defs => defs,
+            }
+
+            ComoCommon.runHook( :preHook, preHookArgs )
+
             if config
                 Opt.configOverlay( config )
             end
             spec = Spec.new( author, year )
             spec.instance_eval( &defs )
             Opt.main.check( ArgsParseState.new( @@argv ) )
+
+            ComoCommon.runHook( :postHook, Opt.main )
         end
 
 
@@ -469,15 +545,29 @@ module Como
         # @param config [Hash] Option definition's behavioral config
         #                      (changes @@config defaults).
         def Spec.command( prog, author, year, defs, config = {} )
+
+            preHookArgs = {
+                :prog => prog,
+                :author => author,
+                :year => year,
+                :defs => defs,
+                :config => config,
+            }
+
+            ComoCommon.runHook( :preHook, preHookArgs )
+
             Spec.defineCheck( prog, author, year, defs, config )
-            # Spec.usage if Opt['help'].given
+
+            ComoCommon.runHook( :postHook, Opt.main )
         end
 
+
         # Alias to Spec.command.
         def Spec.defineCheckHelp( prog, author, year, defs, config = {} )
             Spec.command( prog, author, year, defs, config )
         end
 
+
         # Same as "defineCheckHelp" except without automatic "help"
         # option processing.
         def Spec.defineCheck( prog, author, year, defs, config = {} )
@@ -538,6 +628,10 @@ module Como
         end
 
 
+        # Alias to subcmd to highlight the main command.
+        alias command subcmd
+
+
         # Specify and check options spec.
         #
         # @param table [Array<Array>] Option definition table.
@@ -645,6 +739,9 @@ module Como
         end
 
 
+        # Alias for Spec.checkRule.
+        def Spec.check( opt = nil, &rule ) Spec.checkRule( opt = nil, &rule ) end
+
         # Check option combination rules.
         #
         # @param opt [String] Opt name to which rules are set. If not
@@ -659,6 +756,11 @@ module Como
             opt.setRuleCheck( &rule )
         end
 
+
+        # Alias for checkRule
+        alias check checkRule
+
+
         # Additional option check.
         # @param opt [String] Option name.
         # @param error [String] Error string for false return values (from check).
@@ -731,6 +833,7 @@ module Como
             :check_invalid => true,
             :tab           => 12,
             :help_exit     => true,
+            :copyright     => true,
         }
 
 
@@ -864,6 +967,20 @@ module Como
         end
 
 
+        # Return default config for Como options.
+        def Opt.configGet
+            @@config
+        end
+
+
+        # Set default config for Como options. User can manipulate the
+        # defaults with "preHook".
+        def Opt.configSet( config )
+            @@config = config
+        end
+
+
+
         # ------------------------------------------------------------
         # Opt properties:
 
@@ -1516,33 +1633,12 @@ module Como
             str += "\
   Subcommand \"#{@name}\" usage:
     #{fullCommand} #{cmdline.join(" ")}
-
 "
             str += suboptDoc
 
             str += "\n"
         end
 
-        # Usage info for Opt:s.
-        def usageNormalOld
-            str = ""
-
-            if @config[ :header ]
-                str += "\n"
-                str += @config[ :header ]
-                str += "\n"
-            end
-
-            str += usageCommand
-
-            if @config[ :footer ]
-                str += @config[ :footer ]
-                str += "\n"
-            end
-
-            str
-        end
-
         # Usage info for Opt:s.
         def usageNormal
             str = ""
@@ -1616,6 +1712,8 @@ module Como
             str = ""
             # format = Proc.new do |s,d| ( "  %-#{@config[ :tab ]}s%s\n" % [ s, d ] ) end
 
+            str += "\n"
+
             str += "  Options:\n" if hasSubcmd && hasVisibleOptions
 
             @subopt.each do |o|
@@ -1771,34 +1869,21 @@ module Como
         end
 
 
-        # Usage printout for command.
-        def usageCommandOld
-            str = "
-  Usage:
-    #{fullCommand} #{cmdline.join(" ")}
-
-"
-            str += suboptDoc
-
-            str += "
-
-  Copyright (c) #{Opt.year} by #{Opt.author}
-
-"
-        end
-
         # Usage printout for command.
         def usageCommand
             str = "\
   #{fullCommand} #{cmdline.join(" ")}
-
 "
             str += suboptDoc
 
-            str += "
+            if @config[ :copyright ]
+                str += "
 
   Copyright (c) #{Opt.year} by #{Opt.author}
 "
+            end
+
+            str
         end
 
     end
@@ -2103,3 +2188,11 @@ module Como
 
 
 end
+
+
+# Include version definitions.
+require 'version'
+
+
+# Load user customizations (if any).
+load ENV['COMO'] if ENV['COMO']

data/lib/version.rb

@@ -0,0 +1,11 @@
+module Como
+
+    def Como.version
+        ComoCommon::VERSION
+    end
+
+    class ComoCommon
+        VERSION="0.1.3"
+    end
+
+end

data/test/como_rule_1

@@ -17,7 +17,7 @@ Spec.command( "como_rule_1", "Como Tester", "2013",
   ] )
 
 
-Spec.checkRule do
+Spec.check do
     one(
         none,
         any( 'debug', 'mode' ),

data/test/como_subcmd_rule

@@ -5,7 +5,7 @@ include Como
 
 Spec.program( "Como Tester", "2013" ) do
 
-    subcmd( "como_subcmd",
+    command( "como_subcmd",
       [
        [ :opt_single,  "password",  "-p", "User password." ],
        [ :opt_multi,   "username",  "-u", "Username(s)." ],
@@ -28,7 +28,7 @@ Spec.program( "Como Tester", "2013" ) do
       ] )
 
 
-    checkRule do
+    check do
         one( 'file', 'username', inv( '-fo' ) )
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: como
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-23 00:00:00.000000000 Z
+date: 2014-07-09 00:00:00.000000000 Z
 dependencies: []
 description: ! 'Como provides low manifest command line option parsing and deployment.
   The command line options are described in compact table format and option values
@@ -30,6 +30,7 @@ files:
 - LICENSE
 - Rakefile
 - lib/como.rb
+- lib/version.rb
 - test/test_subcmd
 - test/como_subcmd_rule
 - test/test_como.rb
@@ -86,6 +87,8 @@ files:
 - doc/Como/Spec.html
 - doc/file.CHANGELOG.html
 - doc/frames.html
+- examples/como_simple
+- examples/como_subcmd
 homepage: 
 licenses:
 - Ruby