configliere 0.3.4 → 0.4.4

data/examples/env_var_script.rb

@@ -2,7 +2,7 @@
 $: << File.dirname(__FILE__)+'/../lib'
 require 'configliere'
 
-Settings.use :define, :env_var, :commandline
+Settings.use :env_var, :commandline
 Settings.define :underpants, :env_var => 'UNDERPANTS', :default => "boxers"
 Settings.resolve!
 
@@ -18,7 +18,7 @@ UNDERPANTS="commando" ./env_var_script.rb --underpants=briefs # commandline wins
 }
 
 puts %Q{Using
-* the default setting of:   #{Settings.param_definitions[:underpants][:default].inspect}
+* the default setting of:   #{Settings.definition_of(:underpants, :default).inspect}
 * the environment variable: #{ENV['UNDERPANTS'].inspect}
 * the commandline setting:  #{ARGV.grep(/^--underpants/).inspect}
 your configliere advises that

data/examples/help_message_demo.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+$: << File.dirname(__FILE__)+"/../lib"
+require 'configliere'
+Settings.use :commandline
+
+Settings.define :logfile, :type => String,     :description => "Log file name", :default => 'myapp.log', :required => false
+Settings.define :debug, :type => :boolean,     :description => "Log debug messages to console?", :required => false
+Settings.define :dest_time, :type => DateTime, :description => "Arrival time", :required => true
+Settings.define :takes_opt, :flag => 't',      :description => "Takes a single-letter flag '-t'"
+Settings.define :foobaz, :internal => true,    :description => "You won't see me"
+Settings.define 'delorean.power_source', :env_var => 'POWER_SOURCE', :description => 'Delorean subsytem supplying power to the Flux Capacitor.'
+Settings.define :password, :required => true, :encrypted => true
+Settings.description = 'This is a sample script to demonstrate the help message. Notice how pretty everything lines up YAY'
+
+Settings.resolve! rescue nil
+puts "Run me again with --help to see the auto-generated help message!"

data/examples/independent_config.rb

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+$: << File.dirname(__FILE__)+'/../lib'
+require 'configliere'
+require 'gorillib/metaprogramming/class_attribute'
+
+class Wolfman
+  class_attribute :config
+  self.config = Configliere::Param.new.use(:commandline).defaults({
+      :moon    => 'full',
+      :nards   => true,
+    })
+end
+
+Wolfman.config.description = 'Run this with commandline args: Wolfman uses them, Settings does not'
+
+teen_wolf = Wolfman.new
+teen_wolf.config.defaults(:give_me => 'keg of beer')
+
+Wolfman.config.resolve!
+Settings.resolve!
+
+# run this with ./examples/independent_config.rb --hi=there :
+puts "If you run this with #{$0} --hi=there, you should expect:"
+puts '{:moon=>"full", :nards=>true, :give_me=>"keg of beer", :hi=>"there"}'
+p teen_wolf.config
+
+puts 'the Settings hash should be empty:'
+p Settings         #=> {}

data/examples/prompt.rb

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+$: << File.dirname(__FILE__)+'/../lib'
+require 'configliere'
+
+Settings.use :commandline, :prompt
+Settings.define :underpants, :description => 'boxers or briefs'
+Settings.resolve!
+
+puts %Q{
+Configliere can prompt for a parameter value if none is given.
+If you call this with a value for --underpants, you will not see a prompt
+}
+
+puts %Q{Using the commandline setting #{ARGV.grep(/^--underpants/).inspect}
+your configliere advises that the settings are
+  #{Settings.inspect}
+}
+
+puts Settings.prompt_for(:underpants)
+
+puts %Q{Now the Settings are
+  #{Settings.inspect}
+}

data/examples/simple_script.rb

@@ -3,32 +3,45 @@ $: << File.dirname(__FILE__)+'/../lib'
 require 'configliere'
 
 puts "This is a demo of Configliere in a simple script."
-Settings.use :commandline, :config_file, :define
+Settings.use :commandline
+
+puts "\n\nSet default values inline:"
 
-puts "You can set default values:"
 Settings({
-  :dest_time => '1955-11-05',
+  :heavy => true,
   :delorean => {
     :power_source => 'plutonium',
     :roads_needed => true,
     },
-})
-puts "  #{Settings.inspect}"
+  :username => 'marty',
+  })
+puts "\n  #{Settings.inspect}"
+
+puts "\nYou can define settings' type, default value, and description (that shows up with --help), and more. It's purely optional, but it's very convenient:"
+
+Settings.define :dest_time, :default => '11-05-1955', :type => Time, :description => "Target date"
+# This defines a 'deep key': it controls Settings[:delorean][:roads_needed]
+Settings.define 'delorean.roads_needed', :type => :boolean
+Settings.define 'username', :env_var => 'DRIVER'
+puts "\n  #{Settings.inspect}"
 
 config_filename = File.dirname(__FILE__)+'/simple_script.yaml'
-puts "\nYou can load values from a file -- in this case, #{config_filename} -- which overrides the defaults:"
+puts "\nValues loaded from the file #{config_filename} merge with the existing defaults:"
+
 Settings.read config_filename
-Settings.resolve!
-puts "  #{Settings.inspect}"
+puts "\n  #{Settings.inspect}"
 
-puts %Q{\nTry running the script with commandline parameters, for example
-  #{$0} --dest_time=2015-11-05 --delorean.roads_needed="" --delorean.power_source="Mr. Fusion"
-In this case, you used
-  #{$0} #{ARGV.map{|argv| "'#{argv}'"}.join(" ")}
-and so the final parameter values are}
+puts %Q{\nFinally, call resolve! to load the commandline you gave (#{ARGV.inspect}), do type conversion (watch what happens to :dest_time), etc:}
 Settings.resolve!
-puts "  #{Settings.inspect}"
+puts "\n  #{Settings.inspect}"
 
 saved_filename = '/tmp/simple_script_saved.yaml'
-puts %Q{\nYou can save the defaults out to a config file.  These settings have been written to #{saved_filename}}
+puts %Q{\nYou can save the defaults out to a config file -- go look in #{saved_filename}}
 Settings.save!(saved_filename)
+
+if ARGV.empty?
+  puts %Q{\nTry running the script again, but supply some commandline args:\n
+    DRIVER=doc #{$0} --dest_time=11-05-2015 --delorean.roads_needed=false --delorean.power_source="Mr. Fusion"}
+end
+puts
+

data/examples/simple_script.yaml

@@ -1,5 +1,5 @@
 --- 
 # Settings for return
-:dest_time:       1985-11-05
+:dest_time:       11-05-1985
 :delorean:    
   :power_source:  1.21 jiggawatts

data/lib/configliere.rb

@@ -1,40 +1,38 @@
-require 'configliere/core_ext'
-require 'configliere/param'
-require 'configliere/define'
-require 'configliere/config_file'
+require 'date'                      # type conversion
+require 'time'                      # type conversion
+require 'yaml'                      # read files
+require 'fileutils'                 # so save! can mkdir
+require 'configliere/deep_hash'     # magic hash for params
+require 'configliere/param'         # params container
+require 'configliere/define'        # define param behavior
+require 'configliere/config_file'   # read / save! files
 
-module Configliere
-
-  # delegates to Configliere::Param
-  def self.new *args, &block
-    Configliere::Param.new(*args, &block)
-  end
+# use(:encrypted) will bring in 'digest/sha2' and 'openssl'
+# use(:prompt)    will bring in 'highline', which you must gem install
+# running the specs requires rspec and spork
 
-  ALL_MIXINS = [:define, :config_file, :commandline, :encrypted, :env_var, :config_block, :commands]
+module Configliere
+  ALL_MIXINS = [:define, :config_file, :commandline, :encrypted, :env_var, :config_block, :commands, :prompt]
   def self.use *mixins
     mixins = ALL_MIXINS if mixins.include?(:all) || mixins.empty?
     mixins.each do |mixin|
-      # backwards compatibility
-      if mixin.to_sym == :git_style_binaries
-        require "configliere/commands"
-      else
-        require "configliere/#{mixin}"
-      end
+      require "configliere/#{mixin}"
     end
   end
 
-  # Base class for Configliere errors.
-  Error = Class.new(StandardError)
-
 end
 
+# Base class for Configliere errors.
+class Configliere::Error           < StandardError      ; end
+# Feature is deprecated, has or will leave the building
+class Configliere::DeprecatedError < Configliere::Error ; end
+
 # Defines a global config object
-Settings = Configliere.new unless defined?(Settings)
+Settings = Configliere::Param.new unless defined?(Settings)
 
 #
-# Allows the
-#   Config :this => that, :cat => :hat
-# pattern.
+# Also define Settings as a function, so you can say
+#   Settings :this => that, :cat => :hat
 #
 def Settings *args
   Settings.defaults(*args)

data/lib/configliere/commandline.rb

@@ -1,25 +1,32 @@
-# Configliere.use :define
 module Configliere
 
   #
   # Command line tool to manage param info
   #
+  # @example
+  #   Settings.use :commandline
+  #
   module Commandline
     attr_accessor :rest
-    alias_method :argv, :rest
+    attr_accessor :description
+    attr_reader   :unknown_argvs
 
     # Processing to reconcile all options
     #
     # Configliere::Commandline's resolve!:
+    #
     # * processes all commandline params
-    # * if the --help param was given, prints out a usage statement (using
-    #   any +:description+ set with #define) and then exits
-    # * lastly, calls the next method in the resolve! chain.
+    # * if the --help param was given, prints out a usage statement describing all #define'd params and exits
+    # * calls up the resolve! chain.
     #
     def resolve!
       process_argv!
-      dump_help_if_requested
+      if self[:help]
+        dump_help
+        exit(2)
+      end
       super()
+      self
     end
 
     #
@@ -35,6 +42,7 @@ module Configliere
     def process_argv!
       args = ARGV.dup
       self.rest = []
+      @unknown_argvs = []
       until args.empty? do
         arg = args.shift
         case
@@ -42,69 +50,45 @@ module Configliere
         when arg == '--'
           self.rest += args
           break
-        # --param=val
+        # --param=val or --param
         when arg =~ /\A--([\w\-\.]+)(?:=(.*))?\z/
           param, val = [$1, $2]
-          param.gsub!(/\-/, '.')                        # translate --scoped-flag to --scoped.flag
-          param = param.to_sym unless (param =~ /\./)   # symbolize non-scoped keys
+          warn "Configliere uses _underscores not dashes for params" if param.include?('-')
+          @unknown_argvs << param.to_sym if (not has_definition?(param))
           self[param] = parse_value(val)
         # -abc
-        when arg =~ /\A-(\w+)\z/
+        when arg =~ /\A-(\w\w+)\z/
           $1.each_char do |flag|
-            param = param_with_flag(flag)
-            self[param] = true if param
+            param = find_param_for_flag(flag)
+            unless param then @unknown_argvs << flag ; next ; end
+            self[param] = true
           end
+        # -a val
+        when arg =~ /\A-(\w)\z/
+          flag = find_param_for_flag($1)
+          unless flag then @unknown_argvs << flag ; next ; end
+          if (not args.empty?) && (args.first !~ /\A-/)
+            val = args.shift
+          else
+            val = nil
+          end
+          self[flag] = parse_value(val)
         # -a=val
-        # when arg =~ /\A-(\w)=(.*)\z/
-        #   param, val = param_with_flag($1), $2
-        #   self[param] = parse_value(val) if param
+        when arg =~ /\A-(\w)=(.*)\z/
+          flag, val = [find_param_for_flag($1), $2]
+          unless flag then @unknown_argvs << flag ; next ; end
+          self[flag] = parse_value(val)
         else
           self.rest << arg
         end
       end
+      @unknown_argvs.uniq!
     end
 
-    def parse_value val
-      case
-      when val == nil then true            # --flag    option on its own means 'set that option'
-      when val == '' then nil             # --flag='' the explicit empty string means nil      
-      else val                             # else just return the value
-      end
-    end
-
-    # Configliere internal params
-    def define_special_params
-      Settings.define :encrypt_pass, :description => "Passphrase to extract encrypted config params.", :internal => true
-    end
-
-    # All commandline name-value params that aren't internal to configliere
-    def normal_params
-      reject{|param, val| param_definitions[param][:internal] }
-    end
-
-    # die with a warning
+    # ===========================================================================
+    #
+    # Recyle out our settings as a commandline
     #
-    # @param str [String] the string to dump out before exiting
-    # @param exit_code [Integer] UNIX exit code to set, default -1
-    def die str, exit_code=-1
-      dump_help "****\n#{str}\n****"
-      exit exit_code
-    end
-
-    # Retrieve the given param, or prompt for it
-    def param_or_ask attr, hint=nil
-      return self[attr] if include?(attr)
-      require 'highline/import'
-      self[attr] = ask("#{attr}"+(hint ? " for #{hint}?" : '?'))
-    end
-
-    # Retreive the first param defined with the given flag.
-    def param_with_flag flag
-      params_with(:flag).each do |param|
-        return param if param_definitions[param][:flag].to_s == flag.to_s
-      end
-      raise Configliere::Error.new("Unknown option: -#{flag}") if complain_about_bad_flags?
-    end
 
     # Returns a flag in dashed form, suitable for recycling into the commandline
     # of an external program.
@@ -117,91 +101,126 @@ module Configliere
     #   #=> --hello-friend=true
     #
     def dashed_flag_for setting_name, flag_name=nil
-      return unless Settings[setting_name]
+      return unless self[setting_name]
       flag_name ||= setting_name
-      (Settings[setting_name] == true ? "--#{flag_name.to_s.gsub(/_/,"-")}" : "--#{flag_name.to_s.gsub(/_/,"-")}=#{Settings[setting_name]}" )
+      (self[setting_name] == true ? "--#{flag_name.to_s.gsub(/_/,"-")}" : "--#{flag_name.to_s.gsub(/_/,"-")}=#{self[setting_name]}" )
     end
 
+    # dashed_flag_for each given setting that has a value
     def dashed_flags *settings_and_names
-      settings_and_names.map{|args| dashed_flag_for(*args) }
+      settings_and_names.map{|args| dashed_flag_for(*args) }.compact
     end
 
-    # Complain about bad flags?
-    def complain_about_bad_flags?
-      @complain_about_bad_flags
-    end
+    # ===========================================================================
+    #
+    # Commandline help
+    #
 
-    # Force this params object to complain about bad (single-letter)
-    # flags on the command-line.
-    def complain_about_bad_flags!
-      @complain_about_bad_flags = true
+    # Write the help string to stderr
+    def dump_help str=nil
+      warn help(str)+"\n"
     end
 
-    # Return the params for which a line should be printed giving
-    # their usage.
-    def params_with_command_line_help
-      descriptions.reject{ |param, desc| param_definitions[param][:no_command_line_help] }.sort_by{ |param, desc| param.to_s }
+    # The contents of the help message.
+    # Lists the usage as well as any defined parameters and environment variables
+    def help str=nil
+      buf = []
+      buf << usage
+      buf << "\n"+@description if @description
+      buf << param_lines
+      buf << commands_help if respond_to?(:commands_help)
+      buf << "\n\n"+str if str
+      buf.flatten.compact.join("\n")+"\n"
     end
 
-    # Help on the flags used.
-    def flags_help
-      help = ["\nParams"]
-      help += params_with_command_line_help.map do |param, desc|
-        if flag = param_definitions[param][:flag]
-          "  -%s, --%-21s %s" % [flag.to_s.first, param.to_s, desc]
-        else
-          "  --%-25s %s" % [param.to_s + ':', desc]
-        end
-      end
+    # Usage line
+    def usage
+      %Q{usage: #{raw_script_name} [...--param=val...]}
     end
 
-    # Return the params for which a line should be printing giving
-    # their dependence on environment variables.
-    def params_with_env_help
-      definitions_for(:env_var).reject { |param, desc| param_definitions[param][:no_help] || param_definitions[param][:no_env_help] }
+    # the script basename, for recycling into help messages
+    def raw_script_name
+      File.basename($0)
     end
 
-    # Help on environment variables.
-    def env_var_help
-      return if params_with_env_help.empty?
-      [ "\nEnvironment Variables can be used to set:"] + params_with_env_help.map{ |param, env| "  %-27s %s"%[env.to_s, param]}
+    # die with a warning
+    #
+    # @example
+    #    Settings.define :foo, :finally => lambda{ Settings.foo.to_i < 5 or die("too much foo!") }
+    #
+    # @param str [String] the string to dump out before exiting
+    # @param exit_code [Integer] UNIX exit code to set, default -1
+    def die str, exit_code=-1
+      dump_help "****\n#{str}\n****"
+      exit exit_code
     end
 
-    # Output the help message to $stderr, along with an optional extra message appended.
-    def dump_basic_help extra_msg=nil
-      $stderr.puts [:flags_help, :env_var_help].map { |help| send(help) }.flatten.compact.join("\n") if respond_to?(:descriptions)
-      $stderr.puts "\n\n"+extra_msg unless extra_msg.blank?
-      $stderr.puts ''
-    end
+  protected
 
-    def dump_help str=nil
-      dump_basic_help
-      dump_command_help if respond_to?(:dump_command_help)
-      puts str if str
-    end
-      
-    def raw_script_name
-      File.basename($0)
+    # handle --param (true), --param='' (set as ++nil++), --param=hi ('hi')
+    def parse_value val
+      case
+      when val == nil then true  # --flag    option on its own means 'set that option'
+      when val == '' then nil    # --flag='' the explicit empty string means nil
+      else val                   # else just return the value
+      end
     end
 
-    # Usage line
-    def usage
-      %Q{usage: #{raw_script_name} [...--param=val...]}
+    # Retrieve the first param defined with the given flag.
+    def find_param_for_flag(flag)
+      params_with(:flag).each do |param_name, param_flag|
+        return param_name if flag.to_s == param_flag.to_s
+      end
+      nil
     end
 
-  protected
-
-    # Ouput the help string if requested
-    def dump_help_if_requested
-      return unless self[:help]
-      $stderr.puts usage
-      dump_help
-      exit
+    def param_lines
+      pdefs = definitions.reject{|name, definition| definition[:internal] }
+      return if pdefs.empty?
+      buf = ["\nParams:"]
+      width     = find_width(pdefs.keys)
+      has_flags = (not params_with(:flag).empty?)
+      pdefs.sort_by{|pn, pd| pn.to_s }.each do |name, definition|
+        buf << param_line(name, definition, width, has_flags)
+      end
+      buf
+    end
+
+    # pretty-print a param
+    def param_line(name, definition, width, has_flags)
+      desc = definition_of(name, :description).to_s.strip
+      buf = ['  ']
+      buf << (definition[:flag] ? "-#{definition[:flag]}," : "   ") if has_flags
+      buf << sprintf("--%-#{width}s", param_with_type(name))
+      buf << (desc.empty? ? name : desc)
+      buf << "[Default: #{definition[:default]}]"  if definition[:default]
+      buf << '[Required]'                          if definition[:required]
+      buf << '[Encrypted]'                         if definition[:encrypted]
+      buf << "[Env Var: #{definition[:env_var]}]"  if definition[:env_var]
+      buf.join(' ')
+    end
+
+    # run through the params and find the width needed to pretty-print them
+    def find_width(param_names)
+      [ 20,
+        param_names.map{|param_name| param_with_type(param_name).length }
+      ].flatten.max + 2
+    end
+
+    def param_with_type(param)
+      str  = param.to_s
+      type = definition_of(param, :type)
+      case type
+      when :boolean then str += ''
+      when nil      then str += '=String'
+      else               str += "=#{type}"
+      end
+      str
     end
+
   end
 
-  Param.class_eval do
-    # include read / save operations
-    include Commandline
+  Param.on_use(:commandline) do
+    extend Configliere::Commandline
   end
 end