cli_helper 0.0.4 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a11b406f6718dfb39018945bf80702fcb80cf1c8
-  data.tar.gz: 3056af86e1e54c03f0bb8f6bd48384592f60062e
+  metadata.gz: 2bf433b3f85f6369eda6ca70e7270c62ea73de64
+  data.tar.gz: 9c080c925aa6f8e106d2cd7055e8015cd9391bc4
 SHA512:
-  metadata.gz: 81dbaebdbdb4b38801da2cd6147a3bf04a83a4b2350e56a13671ee66dab13625a8e1392a4e876f09c9b22a8e9f93f20b12f8284fa2621542c19c6e0d72cb2807
-  data.tar.gz: cc5a251148d8812a9410654c93625ba148f4d32915c6cc9526dc9a0fb08ccab51a05a0dcc6c2f50095e5bb9f25ba84985f799e961e9bd8af425db7d7ee0a011c
+  metadata.gz: b4c1bf70ad6f53fd6c1a6578be150a8621c9588452cad240c233500a00aea0613fa7f4b428caf5c029fb806c5b9ba537f0c78e60aa58af727e1f83116915b65b
+  data.tar.gz: 86d255f5568ff8ce8ea8d1ce024f7ddf7eabb5d22f1e05cd7dfd8322de57edb241795c96ace9b20458c856ebfd8a08d6f7f4eadbece59b6b341df6a01904265f

data/README.md

@@ -1,22 +1,233 @@
-# cli_helper.rb
+# cli_helper
+
+If you write lots of command-line utility programs, or
+even if you don't the cli_helper gem can be a helper
+to you.  It integrates several common gems to give
+a comprehensive configuration management experience.
+
+Here are the gems used and what they do:
+
+* configatron
+  * makes config info available
+  * http://github.com/markbates/configatron
+
+* nenv
+  * parses ENV for friendly use
+  * http://github.com/e2/nenv
+
+* parseconfig
+  * parses INI files
+  * http://github.com/datafolklabs/ruby-parseconfig
+
+* slop
+  * parses ARGV
+  * http://github.com/leejarvis/slop
+
+
+## Convention
+
+The convention w/r/t what value amoung concurrent sources
+is the correct one to use is hierarchic
+where the layer above trumps all the layers below.  This is the order:
+
+* command-line parameter
+  * config file value
+    * system environment variable
+      * default
+
+This ordering says that regardless what you have set in
+a config file or ENV or as a default, the value of the
+command line parameter will be used.
+
+I like to use ERB within my config files.  Consider 'default.yml.erb'
+below:
+
+```ruby
+---
+  host: <%= Nenv.host || 'localhost' %>
+```
+
+Processing this file will give me either the default value for host
+of 'localhost' or if defined the value of the system environment
+variable HOST.  I like Nenv over ENV.
+
+Now suppose I use cli_helper within a program and execute the
+program like this:
+
+```ruby
+program.rb --host devhost --config default.yml.erb,prod.ini
+```
+
+Because I have specifically called out the value of host on the
+command line, that value will trump anything that comes from the
+config file.
+
+Did you notice that I had two files specified with the --config option?
+
+The config files are processed in the order that they are given on the command
+line.  Whatever values were obtained from the first file will be over-written
+by the second and any subsequent config files.  Regardless of their
+values for host, the command-line value trumps them all.
+
+
+## Config files
+
+cli_helper supports multiple types of configuration files:
+
+```text
+  *.rb
+  *.yml
+  *.yml.erb
+  *.ini
+  *.txt (in the INI format)
+  *.ini.erb  -- not currently supported
+  *.txt.erb  -- not currenly supported
+```
+
+All values obtained from config files and command line parameters are
+held in the configatron structure.
+
+
+## Common Command-line Options
+
+cli_helper predefines common command-line options.  These
+can to disabled by the program if necessary.  The common options
+are:
+
+```text
+  -h, --help
+  -d, --debug
+  -v, --verbose
+  --version
+  --config (optional)
+```
+
+To enable the support for config files do this before
+calling the #cli_helger() method:
+
+```ruby
+configatron.support_config_files = true
+```
 
-I had this code just being lazy on my computer.  It might be of use
-to someone else; but, its just really intended to support my own
-quick and dirty command-line based utilities.  Mostly they are one-offs
-but sometimes they hang around.
+To disable any of the other common options do this before
+involking cli_helper:
 
-I typically create thes cli utilities using my own code generater which
-resulted in lots of duplicate source blocks roll around on the deck.  This
-little library will DRYup my code a little.
+```ruby
+configatron.disable_help = true
+configatron.disable_debug = true
+configatron.disable_verbose = true
+cpnfogatrpm/dosab;e_version = true
+```
+
+## Other options
+
+The default behavior is to raise an exception if an unspecified option is
+used on the command line.  For example if your program just uses the common
+options and someone invokes the program with --xyzzy then an exception will be
+raised saying that the option is unknown.
+
+To prevent this exception you can set the suppress_errors parameter.  With
+this parameter set to true an unknown option will just be added to the unprocessed
+arguments array.
+
+```ruby
+configatron.suppress_errors = true
+```
+
+The unprocessed options can be access via the arguments array:
+
+```ruby
+configatron.arguments
+```
+
+The arguments array is also where you will find anything else from the
+command line that was not processed by the cli_helper.  For example:
+
+```ruby
+my_program.rb -v *.txt
+```
+
+The file names matching the '*.txt' glob will be put into the configatron.arguments
+array.
+
+
+## Boolean options auto-generate methods
+
+Any boolean command-line option specified, even the predefined common ones,
+have two methods defined: query(?) and banger(!).  For the help options
+the methods look like this:
+
+```ruby
+def help?
+  configatron.help
+end
+
+def help!
+  configatron.help = true
+end
+```
+
+## Names of command-line options
+
+If you specify a command-line option of xyzzy, then an
+entry in the configatron structure will be created having the
+name 'xyzzy'.  If you do not use a long-form for the option
+the short option name will be used.  For example '-x' will
+be accessed as configatron.x
+
+
+## Support methods
+
+There are several support methods that I have included in cli_helper
+that you may want to use.  The first three deal with
+errors and warnings and what to do with them.
+
+* warning(a_string)
+* error(a_string)
+* abort_if_errors
+
+cli_helper defines two arrays within configatron: errors and warnings.  The
+warning() and error() methods insert their strings into these arrays.  The
+abort_if_errors method first looks at the warnings array and presents all of
+those strings to the user via STDOUT.  It then asks the user if they want
+to abort the program.  The default answer is no.
+
+After presenting the warnings to the user, the abort_if_error method presents
+all of the errors to the user.  Then it exits the program.
+
+These next support methods are self explanatory:
+
+* usage() #=> a_string
+* show_usage() #=> usage string sent to STDOUT
+* me()  #=> The full path to the file that "require 'cli_helper"" was involked
+* my_name() #=> the basename of me
+
+But this one needs some explaining:
+
+* get_pathnames_from(an_array, extnames=['.json', '.txt', '.docx'])
+
+The method get_pathnames_from() returns an array of pathnames matching a specific
+set of file types.  The default types are txt, json and docx because that tends to
+be the majority of the files in which I am interested.  Might add wcml to the default list
+later.  Regardless you propabily ought to provide your own array of file extensions.  And
+don't forget the dot!
+
+If an entry in the array is a directory then its children will be search including any sub-directories recursively.
+
+Here is how I typically use it :)
+
+```ruby
+get_pathnames_from(configatron.arguments, '.php').each do |f|
+  f.delete_without_regret!
+end
+```
 
 
 ## Usage
 
-TODO: Write usage instructions here in case someone can't figure it out
-      for themselves.
+Take a look at http://github.com/MadBomber/cli_helper/blob/master/example/cli_stub.rb
 
 
 ## License
 
 You want it?  Its yours.
-# cli_helper

data/cli_helper.gemspec

@@ -4,18 +4,20 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
   spec.name          = "cli_helper"
-  spec.version       = '0.0.4'
+  spec.version       = '0.1.0'
   spec.authors       = ["Dewayne VanHoozer"]
   spec.email         = ["dvanhoozer@gmail.com"]
 
-  spec.summary       = %q{An encapsulates of common junk used with Q&D CLI utilities.}
-  spec.description   = %q{An encapsulation of a convention I have been using
-   with the slop, nenv, and other gems for quick and dirty development of
-   command-line based utility programs.  Its not pretty.  It may even break
-   your code.  I wouldn't use it if I were you.  You could, if you wanted,
-   namespace this stuff within CliHelper and establish a new convention.
-   You might even wrap not only slop but some of those other ARGV parsers.
-   I only did this much after being shamed into it by rubycritic.}
+  spec.summary       = %q{An encapsulation of an integration of slop, nenv, parseconfig and configatron.}
+  spec.description   = %q{
+     An encapsulation of a convention I have been using
+     with the slop, nenv, parseconfig and configatron gems for quick and dirty
+     development of
+     command-line based utility programs.  Slop parses ARGV; Nenv parses ENV;
+     ParseConfig parses INI; Configatron keeps it all together.  YAML and ERB
+     preprocessing is also available.  Ruby configuration files are also supported.
+     and you can specify multiple config files of mixed types at once.
+  }
   spec.homepage      = "http://github.com/MadBomber/cli_helper"
   spec.license       = "You want it?  It's yours."
 
@@ -26,14 +28,15 @@ Gem::Specification.new do |spec|
     spec.metadata['allowed_push_host'] = 'https://rubygems.org'
   end
 
-  spec.add_dependency 'slop', "~> 4.0"
+  spec.add_dependency 'configatron'
   spec.add_dependency 'nenv'
-  spec.add_dependency 'awesome_print'
-  spec.add_dependency 'debug_me'
-
+  spec.add_dependency 'parseconfig'
+  spec.add_dependency 'slop', "~> 4.0"
 
   spec.add_development_dependency "bundler", "~> 1.9"
   spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency 'test_inline'
+  spec.add_development_dependency 'kick_the_tires'
+  spec.add_development_dependency 'awesome_print'
+  spec.add_development_dependency 'debug_me'
 
 end

data/example/cli_stub.rb

@@ -7,19 +7,55 @@
 ##  By:   Dewayne VanHoozer (dvanhoozer@gmail.com)
 #
 
-require 'cli_helper'
-
-$options[:version] = '0.0.1' # the version of this utility program
+require 'awesome_print'
 
-# HELP is extra stuff shown with usage.  It is optional.
+require 'cli_helper'
+include CliHelper
+
+configatron.version = '0.0.1' # the version of this utility program
+configatron.support_config_files = true # 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
+
+# HELP is extra stuff shown with usage.  It is optional.  You
+# can put anything you want into it.  Since it is optional, it
+# can be completely left out of your program.  This HELP text
+# will appear at the end of the usage message after the help
+# text for each option (command-line parameter).
 HELP = <<EOHELP
 Important:
 
   Put important stuff here.
 
+  Config files also support ERB preprocessing.  use
+  cile names like: *.uml.erb *.ini.erb *.txt.erb
+
+  Do not use *.rb.erb that's just silly.
+
 EOHELP
 
-# The description (aka banner) text is optional.  The block is required.
+# The description (aka banner) text is optional.  The block is not required.it
+# only the default options and config files are desired.  The block allows for
+# the definition of program-specific options.
+#
+# Default options for help, debug, verbose, and version are automatically inserted
+# by cli_helper.  If configatron.support_config_files is TRUE then a '--config' parameter
+# will also be presented.  '--config' takes a comma-separated list of file paths.  Each
+# config file is processed within cli_helper and results combined within the configatron
+# structure.
+#
+# -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.
+# -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
+# also get methods defined for them.  The debug! methods sets the debug boollean to true.
+# Same for verbose! etc.
+
 cli_helper("An example use of cli_helper") do |o|
 
   # For a complete list of stuff see Slop on github.com
@@ -33,11 +69,13 @@ cli_helper("An example use of cli_helper") do |o|
 
   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}"
@@ -46,7 +84,7 @@ cli_helper("An example use of cli_helper") do |o|
 end
 
 # ARGV is not touched.  However all command line parameters that are not consummed
-# are available in $options[:arguments]
+# are available in configatron.arguments
 
 # Display the usage info
 if  ARGV.empty?
@@ -57,14 +95,29 @@ end
 
 # Error check your stuff; use error('some message') and warning('some message')
 
-unless $options[:arguments].empty?
-  warning "These items were not processed #{$options[:arguments]}"
+unless configatron.arguments.empty?
+  warning "These items were not processed #{configatron.arguments}"
 end
 
-if $options[:arguments].include?('error')
+if configatron.arguments.include?('error')
   error "You wanted an error, so you got one."
 end
 
+if configatron.arguments.include?('warning')
+  warning "You wanted a warning, so you got one."
+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.
+=end
+
+# present all warnings and all errors to the user
+# if there are errors, the program will exit after
+# displaying the error messages.
 abort_if_errors
 
 
@@ -81,7 +134,7 @@ at_exit do
   puts
 end
 
-ap $options  if verbose? || debug?
+ap configatron.to_h  if verbose? || debug?
 
 stub = <<EOS