cli_helper 0.1.6 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 914907ac3588871959a3bcb3facdd987f0cd66db
-  data.tar.gz: 4215cb566324eb7466a90b688f8c83cf180769e4
+  metadata.gz: daf61d8cbabeb65a4cca02b574eec433477be112
+  data.tar.gz: d7bda7e83f7f3c2f9bbabf66df68f0b398b4466f
 SHA512:
-  metadata.gz: d5284dc8b2af8af0391465ea12e588403eea653038a26b6e4f2546261509aaa7ee95ea6ff9e45144cc626617308b9af44bdfa2d2a9fa185859bd9304834e704c
-  data.tar.gz: 789e72bb764bd2de7989394b5a600a53403029f3e194a7ffafe4f53e0e5d7ed61d9211a487dc8357d27127976bde83e533749c17215c4f4400fd64c4cb3faf02
+  metadata.gz: 42014bd7d2a2718ba08ab8dc01d0b87f45116903a85634c04b3a104761cd34e48ccec049b1f51bb18b9c55c83371fe1e78adbb34a1a9b9e33d46d017bb93898d
+  data.tar.gz: d7bbf67ba09b13516d3e02536eb1b20a9a7a40b484aca5c468386c8e03ededb478d98acf9d66f0b27f4e3be2e4d577691315359ee9a2d688466e879639d07aa4

data/cli_helper.gemspec

@@ -4,7 +4,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
   spec.name          = "cli_helper"
-  spec.version       = '0.1.6'
+  spec.version       = '0.1.8'
   spec.authors       = ["Dewayne VanHoozer"]
   spec.email         = ["dvanhoozer@gmail.com"]
 
@@ -31,10 +31,10 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'configatron'
   spec.add_dependency 'nenv'
   spec.add_dependency 'inifile'
-  spec.add_dependency 'slop', "~> 4.0"
+  spec.add_dependency 'slop', "~> 4.2"
 
-  spec.add_development_dependency "bundler", "~> 1.9"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake"
   spec.add_development_dependency 'kick_the_tires'
   spec.add_development_dependency 'awesome_print'
   spec.add_development_dependency 'debug_me'

data/example/cli_stub.rb

@@ -7,34 +7,40 @@
 ##  By:   Dewayne VanHoozer (dvanhoozer@gmail.com)
 #
 
+require 'debug_me'
+include DebugMe
+
 require 'awesome_print'
 
 require '../lib/cli_helper'
 include CliHelper
 
-configatron.version = '0.0.2' # the version of this utility program
-configatron.enable_config_files = true # default is false
+configatron.version = '0.0.3' # the version of this utility program
+configatron.enable_config_files = false # default is false
 configatron.disable_help    = false # default is false set true to remove the option
 configatron.disable_verbose = false # ditto
 configatron.disable_debug   = false # ditto
 configatron.disable_version = false # ditto
-configatron.suppress_errors = false # set to true to eat exceptions; unknown options added to arguments
+configatron.suppress_errors = true  # default is true; set to false to receive exceptions from Slop
 
 
 # Sometimes you may have a few default config files that you
 # want to apply before the command-line options.  Do it like
-# something like this:
+# this:
+
+=begin
 %w[
   ../tests/config/sample.yml
   ../tests/config/sample.yml.erb
 ].each do |dcf|
   cli_helper_process_config_file(dcf)
 end
+=end
 
 # OR just pass a directory and all of the config files in the
 # directory will be processed:
 
-cli_helper_process_config_file('../tests/config')
+#  cli_helper_process_config_file('../tests/config')
 
 
 # HELP is extra stuff shown with usage.  It is optional.  You
@@ -66,7 +72,7 @@ EOHELP
 #
 # -h, --help will automatically show a usage message on STDOUT and exit the program
 # --version will print the program's version string to STDOUT and exit
-# =v, --verbose will set the verbose boolean to true.
+# -v, --verbose will set the verbose boolean to true.
 # -d, --debug will set the debug boolean to true.
 # All boolean options have '?' and '!' methods generated,  For example debug? and
 # verbose? are automatically generated.  Any program-specific booleans specified will
@@ -78,26 +84,55 @@ cli_helper("An example use of cli_helper") do |o|
   # For a complete list of stuff see Slop on github.com
   # https://github.com/leejarvis/slop
 
+  # boolean parameters will also generate the methods long-parameter? and long-parameter!
+  # for example this line:
+  o.bool    '-b', '--bullstuff', default: false
+
+  # will auto generate the methods bullstuff? and bullstuff!
+  # where bullstuff? returns the value of configatron.bullstuff
+  #   and bullstuff! sets the value of configatron.bullstuff to true
+  #
+  # NOTE: boolean options are special in that default: false is assumed
+  #       when no default item is provided.  This means that
+  #         o.bool '-e', 'Example', default: false
+  #   and   o.bool '-e', 'Example'
+  #   are treated identically.  The value for the parameter will be false when the
+  #   parameter is included on the command line.
+  #
+  #   This is NOT the case for other parameter classes.  For them, if no default is
+  #   provided AND they are not present on the command line, THEN their value will be
+  #   nil AND they will (by convention) be treated as a required parameter that has
+  #   not been provided.  This will result in a warning message being generated.
+
+
   o.string  '-s', '--string', 'example string parameter',  default: 'IamDefault'
-  o.int     '-i', '--int',    'example integer parameter', default: 42
+  o.string  '-r', '--required', 'a required parameter'     # I know its required because there is no default
+  o.bool          '--xyzzy',  'a required boolean without a default', required: true
+  
+  # NOTE: you can use many "flags" in defining an option.  Each is valid on the command line.
+  # However, only the last flag can be used to retrieve the value via the configatron capability.
+  # To get the value entered by the user for this integer parameter you must use:
+  #    configatron.i3  or  configatron['i3']  or  configatron[:i3]
 
-  # FIXME: an issue with Slop
-  #o.float   '-f', '--float',  'example float parameter', default: (22.0 / 7.0)
+  o.int     '-i', '--i2', '--i3', 'example integer parameter', default: 42
 
+
+  o.float   '-f', '--float',  'example float parameter', default: (22.0 / 7.0)
   o.array   '-a', '--array',  'example array parameter',   default: [:bob, :carol, :ted, :alice]
   o.path    '-p', '--path',   'example Pathname parameter', default: Pathname.new('default/path/to/file.txt')
-  o.paths         '--paths',  'example Pathnames parameter', delimiter: ',', default: ['default/path/to/file.txt',
-'file2.txt'].map{|f| Pathname.new f}
+  o.paths         '--paths',  'example Pathnames parameter', delimiter: ',', 
+    default: ['default/path/to/file.txt', 'file2.txt'].map{|f| Pathname.new f}
 
-  # FIXME: Issue with Slop; default is not passed to the block.  When no parameter is
-  #        given, an exception is raised.  Using the suppress_errors: true option silents
-  #        the exception BUT still the default value is not passed to the block.
-  #        This issue has been raised with the Slop author and a fix is in the works.
   o.string '-n', '--name', 'print Hello <name>', default: 'World!', suppress_errors: true do |a_string|
     a_string = 'world' if a_string.empty?
     puts "Hello #{a_string}"
   end
 
+  o.on '--quit', "print 'Take this option and do it!' and then exit" do
+    puts 'Take this option and do it!'
+    exit
+  end
+
 end
 
 # ARGV is not touched.  However all command line parameters that are not consummed
@@ -125,8 +160,6 @@ if configatron.arguments.include?('warning')
 end
 
 =begin
-
-rescue
   configatron.errors and configatron.warnings are of type Array.
   All warnings will be presented to the user.  The user will
   be asked wither the program should be aborted.
@@ -172,3 +205,42 @@ EOS
 
 puts stub
 
+# The values of command line parameters are available anywhere via configatron as
+# either methods or hash keys.  The name of the method/key is the name of the
+# last "flag" defined for that option.  For example the name option was defined
+# with the flags "-n" and "--name" so you can access that parameter like this:
+
+puts "\n\nHello #{configatron.name}"
+
+# or like this:
+
+puts "Hello #{configatron['name']}"
+
+# or like this:
+
+puts "Hello #{configatron[:name]}\n\n"
+
+__END__
+
+The same thing is true if only a single letter "-z" is used.
+Access the value like this:
+
+  configatron.z
+  configatron['z']
+  configatron[:z]
+
+Regardless of how many "flags" are defined for an option, it is only the
+last one in the list that is used to access its value.  In the "name" example
+about you CANNOT access the value via configatron.n because "--name" was the
+last flag defined for the option.
+
+When the user enters a "flag" more than once on a command line only the value of
+The last entry will be kept.
+
+Run this program with the following parameters and see what happens:
+
+  -n Tom -n Dick -n Harry
+
+you should get a warning that there were multiple entries on the command
+line.  The value that is used will be the last one - "Harry"
+

data/lib/cli_helper.rb

@@ -60,11 +60,11 @@ module CliHelper
     disable_debug:  false,
     disable_verbose: false,
     disable_version: false,
-    suppress_errors: false,
+    suppress_errors: true,   # suppress the exceptions generated by Slop
     ini_comment:    '#',
     ini_seperator:  '=',
     ini_encoding:   'UTF-8',
-    user_name:      Nenv.user || Nenv.user_name || Nenv.logname || 'The Unknown Programmer',
+    user_name:      Nenv.user || Nenv.user_name || Nenv.logname || 'The Unknown User',
     home_path:      Pathname.new(Nenv.home),
     cli:            'a place holder for the Slop object',
     errors:         [],
@@ -75,8 +75,8 @@ module CliHelper
 
   configatron.required_by_filename = caller.last.split(':').first
   configatron.me       = Pathname.new(configatron.required_by_filename).realpath
-  configatron.my_dir   = Pathname.new(configatron.required_by_filename).realpath.parent
-  configatron.my_name  = Pathname.new(configatron.required_by_filename).realpath.basename.to_s
+  configatron.my_dir   = configatron.me.parent
+  configatron.my_name  = configatron.me.basename.to_s
 
 
   # Return full pathname of program
@@ -84,32 +84,41 @@ module CliHelper
     configatron.me
   end
 
+
   # Return full pathname of program
   def my_dir
     configatron.my_dir
   end
   alias :root :my_dir
 
+
   # Returns the basename of the program as a string
   def my_name
     configatron.my_name
   end
 
+
   # Returns the version of the program as a string
   def version
     configatron.version
   end
 
+
+  # Extract options and values from an ERB formatted config file
   def cli_helper_process_erb(file_contents)
     erb_contents = ERB.new(file_contents).result
     return erb_contents
   end
 
+
+  # Extract options and values from a YAML formatted config file
   def cli_helper_process_yaml(file_contents='')
     a_hash = YAML.load file_contents
     return a_hash
   end
 
+
+  # Extract options and values from an INI formated config file
   def cli_helper_process_ini(file_contents='')
     an_ini_object = IniFile.new(
                       content: file_contents,
@@ -120,6 +129,8 @@ module CliHelper
     return an_ini_object.to_h
   end
 
+
+  # Obtain options and values from a config file
   def cli_helper_process_config_file(a_cf)
     cf = String == a_cf.class ? Pathname.new(a_cf) : a_cf
     if cf.directory?
@@ -184,8 +195,12 @@ module CliHelper
   # parameters provided via a block.  Create '?'
   # for all boolean parameters that have a '--name' flag form.
   # Returns a Slop::Options object
-  def cli_helper(my_banner='')
-    param = Slop::Options.new
+  def cli_helper( my_banner='', 
+                  slop_options_config={}
+                )
+    default_config = { suppress_errors: configatron.suppress_errors }
+
+    param = Slop::Options.new( default_config.merge(slop_options_config) )
 
     if my_banner.empty?
       param.banner = "Usage: #{my_name} [options] ..."
@@ -233,8 +248,38 @@ module CliHelper
     end
 
     parser = Slop::Parser.new(param, suppress_errors: configatron.suppress_errors)
+
     configatron.cli = parser.parse(ARGV)
 
+    # Lets do some error checking ...
+    configatron.cli.options.options.each do |opt|
+      if opt.count > 1
+        warning "#{opt.desc} #{opt.flags.inspect} entered more than once; only last value is used"
+      end
+      if opt.value.nil?
+        if opt.config.default.nil?
+          # NOTE: why is this a warning and not an error?
+          #       while it may be required, it might be set in a config file
+          #       so we let the user decide to continue or abort.
+          # SMELL: see below, past the loading of the config file values.
+          warning "Required parameter is missing: #{opt.desc} #{opt.flags.inspect}"
+        end
+      end
+    end
+
+    unless configatron.cli.arguments.empty?
+      bad_options = configatron.cli.arguments.select {|o| o.start_with?('-')}
+      unless bad_options.empty?
+        error "Invalid parameters: #{bad_options.inspect}"
+        bad_options.each do |o|
+          x = configatron.cli.arguments.index(o)
+          configatron.cli.arguments[x] = nil
+        end
+        configatron.cli.arguments.compact!
+      end
+    end
+
+
     # NOTE: The config files are being process before the
     #       command line options in order for the command
     #       line options to over-write the values from the
@@ -245,6 +290,10 @@ module CliHelper
       end # configatron.cli.config.each do |cf|
     end # if configatron.enable_config_files
 
+    # SMELL: a required parameter that is not entered on the command line
+    #        will have a value of nil.  IF THAT parameter had been
+    #        set in a config file, this will overlay the valid value
+    #        with an invalid nil.
     configatron.configure_from_hash(configatron.cli.to_hash)
     configatron.arguments = configatron.cli.arguments
 
@@ -272,6 +321,7 @@ module CliHelper
     return param
   end # def cli_helper
 
+
   # Returns the usage/help information as a string
   def usage
     a_string = configatron.cli.to_s + "\n"
@@ -279,13 +329,16 @@ module CliHelper
     return a_string
   end
 
+
   # Prints to STDOUT the usage/help string
   def show_usage
     puts usage()
   end
 
 
-  # Returns an array of valid files of one type
+  # Returns an array of valid files of valid type(s)
+  # Creates warnings for files not matching the valid extensions.
+  # Generates errors fpr files that do not exist
   def get_pathnames_from(an_array, extnames=['.json', '.txt', '.docx'])
     an_array = [an_array] unless an_array.is_a? Array
     extnames = [extnames] unless extnames.is_a? Array
@@ -300,7 +353,7 @@ module CliHelper
           if extnames.include?(pfn.extname.downcase)
             file_array << pfn
           else
-            error "File extension is not #{extnames.join(' or ')} file: #{pfn}"
+            warning "File ignored because extension is not #{extnames.join(' or ')} file: #{pfn}"
           end
         else
           error "File does not exist: #{pfn}"
@@ -337,15 +390,29 @@ module CliHelper
     end
   end # def abort_if_errors
 
+
   # Adds a string to the global $errors array
   def error(a_string)
     configatron.errors << a_string
   end
 
+
+  # Returns an Array of errors
+  def errors
+    configatron.errors
+  end
+
+
   # Adds a string to the global $warnings array
   def warning(a_string)
     configatron.warnings << a_string
   end
 
+
+  # Returns an Array of warnings
+  def warnings
+    configatron.warnings
+  end
+
 end # module CliHelper
 

data/tests/cli_helper_test.rb

@@ -160,9 +160,7 @@ end
 
 
 
-
-
-#it '888 prints usage()'  do
+#it '060 prints usage()'  do
   puts
   puts "="*45
   show_usage
@@ -215,6 +213,102 @@ EOS
   end
 #end
 
+#it '070 warns about multiple uses of a paramager on the command line' do
+  ARGV = "-n Tom -n Dick -n Harry".split
+  configatron.warnings = []
+  assert configatron.warnings.empty?
+
+  cli_helper do |o|
+    o.string '-n', '--name', 'Hello <name>'
+  end
+
+  assert_equal 1, configatron.warnings.size
+  assert configatron.warnings.first.include?('entered more than once; only last value is used')
+#end
+
+
+#it '080 warns about missiong value and undefined flag' do
+  ARGV = "--WooWho -n".split
+  configatron.warnings = []
+  configatron.errors   = []
+  assert configatron.warnings.empty?
+
+  cli_helper do |o|
+    o.string '-n', '--name', 'Hello <name>'
+  end
+
+  assert_equal 1, configatron.warnings.size
+  assert_equal 'Required parameter is missing: Hello <name> ["-n", "--name"]', configatron.warnings.first
+
+  assert_equal 1, configatron.errors.size
+  assert_equal 'Invalid parameters: ["--WooWho"]', configatron.errors.first
+#end
+
+
+#it '090 generates exception' do
+  # Do not recommend using exceptions to communicate errors and warnings.
+  # because only one exception can be generated at a time.  Its better to
+  # alert the user to all known problems than to just detect and report
+  # only one problem at a time.
+
+  ARGV = "--WooWho -n".split  # This string has two errors but only one will be deteched.
+  configatron.warnings = []
+  configatron.errors   = []
+  assert configatron.warnings.empty?
+
+  configatron.suppress_errors = false
+
+  exception_text = 'there was no exception'
+
+  begin
+    cli_helper do |o|
+      o.string '-n', '--name', 'Hello <name>'
+    end
+  rescue Exception => e
+    exception_text = e
+  end
+
+  assert_equal "unknown option `--WooWho'", exception_text
+
+  assert_equal 0, configatron.warnings.size
+  assert_equal 0, configatron.errors.size
+#end
+
+#it '092 generates exception' do
+  # Do not recommend using exceptions to communicate errors and warnings.
+  # because only one exception can be generated at a time.  Its better to
+  # alert the user to all known problems than to just detect and report
+  # only one problem at a time.
+
+  # change the order from the previous test does not change the results
+  # because the first this that is checked by Slop is unknown flags.  Then it checks
+  # for missing arguments in the remaining flags.  Slop will generate an exception
+  # on the first error it finds.  There is no way to cause Slop to resume checking
+  # the remaining command line parameters.
+  ARGV = "-n".split  # This string has no unknown flags.
+  configatron.warnings = []
+  configatron.errors   = []
+  assert configatron.warnings.empty?
+
+  configatron.suppress_errors = false
+
+  exception_text = 'there was no exception'
+
+  begin
+    cli_helper do |o|
+      o.string '-n', '--name', 'Hello <name>'
+    end
+  rescue Exception => e
+    exception_text = e
+  end
+
+  assert_equal "missing argument for -n, --name", exception_text
+
+  assert_equal 0, configatron.warnings.size
+  assert_equal 0, configatron.errors.size
+#end
+
+
 #it '999 Show the options structure' do
   puts '*'*45
   ap configatron.to_h

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cli_helper
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.8
 platform: ruby
 authors:
 - Dewayne VanHoozer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-11-02 00:00:00.000000000 Z
+date: 2016-05-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: configatron
@@ -58,42 +58,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '4.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '4.2'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.9'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.9'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: kick_the_tires
   requirement: !ruby/object:Gem::Requirement
@@ -201,7 +201,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.6.4
 signing_key: 
 specification_version: 4
 summary: An encapsulation of an integration of slop, nenv, inifile and configatron.