configliere 0.3.4 → 0.4.4

data/lib/configliere/define.rb

@@ -1,8 +1,16 @@
 module Configliere
   module Define
-    # Definitions for params: :description, :type, :encrypted, etc.
-    attr_writer :param_definitions
 
+    # Define arbitrary attributes of a param, notably:
+    #
+    # [:description]  Documentation for the param, used in the --help message
+    # [:default]      Sets a default value (applied immediately)
+    # [:env_var]      Environment variable to adopt (applied immediately, and after +:default+)
+    # [:encrypted]    Obscures/Extracts the contents of this param when serialized
+    # [:type]         Converts param's value to the given type, just before the finally block is called
+    # [:finally]      Block of code to postprocess settings or handle complex configuration.
+    # [:required]     Raises an error if, at the end of calling resolve!, the param's value is nil.
+    #
     # @param param the setting to describe. Either a simple symbol or a dotted param string.
     # @param definitions the defineables to set (:description, :type, :encrypted, etc.)
     #
@@ -10,30 +18,28 @@ module Configliere
     #   Settings.define :dest_time, :type => Date, :description => 'Arrival time. If only a date is given, the current time of day on that date is assumed.'
     #   Settings.define 'delorean.power_source', :description => 'Delorean subsytem supplying power to the Flux Capacitor.'
     #   Settings.define :password, :required => true, :obscure => true
-    #
-    def define param, definitions={}, &block
-      self.param_definitions[param].merge! definitions
-      self.use(:env_var)      if definitions.include?(:env_var)
-      self.use(:encrypted)    if definitions.include?(:encrypted)
-      self.use(:config_block) if definitions.include?(:finally)
-      self[param] = definitions[:default] if definitions.include?(:default)
-      self.env_vars param => definitions[:env_var] if definitions.include?(:env_var)
-      self.finally(&definitions[:finally]) if definitions.include?(:finally)
+    #   Settings.define :danger, :finally => lambda{|c| if c[:delorean][:power_source] == 'plutonium' than c.danger = 'high' }
+    #
+    def define param, pdefs={}, &block
+      param = param.to_sym
+      definitions[param].merge! pdefs
+      self.use(:env_var)                      if pdefs.include?(:env_var)
+      self.use(:encrypted)                    if pdefs.include?(:encrypted)
+      self.use(:config_block)                 if pdefs.include?(:finally)
+      self[param] = pdefs[:default]           if pdefs.include?(:default)
+      self.env_vars param => pdefs[:env_var]  if pdefs.include?(:env_var)
+      self.finally(&pdefs[:finally])          if pdefs.include?(:finally)
       self.finally(&block) if block
     end
 
-    def param_definitions
-      # initialize the param_definitions as an auto-vivifying hash if it's never been set
-      @param_definitions ||= Sash.new{|hsh, key| hsh[key] = Sash.new  }
-    end
-
-    # performs type coercion
+    # performs type coercion, continues up the resolve! chain
     def resolve!
       resolve_types!
       super()
       self
     end
 
+    # ensures required types are defined, continues up the validate! chain
     def validate!
       validate_requireds!
       super()
@@ -42,25 +48,55 @@ module Configliere
 
     # ===========================================================================
     #
-    # Describe params with
-    #
-    #   Settings.define :param, :description => '...'
+    # Helpers for retrieving definitions
     #
 
-    # gets the description (if any) for the param
-    # @param param the setting to describe. Either a simple symbol or a dotted param string.
-    def description_for param
-      param_definitions[param][:description]
+    private
+    def definitions
+      @definitions ||= Hash.new{|hsh, key| hsh[key.to_sym] = Hash.new  }
     end
+    public
 
-    # All described params with their descriptions
-    def descriptions
-      definitions_for(:description).reject{ |param, desc| param_definitions[param][:no_help] }
+    # Is the param defined?
+    def has_definition? param
+      definitions.has_key?(param.to_sym)
+    end
+
+    # all params with a value for the given aspect
+    #
+    # @example
+    #   @config.define :has_description,  :description => 'desc 1', :foo => 'bar'
+    #   #
+    #   definition_of(:has_description)
+    #   # => {:description => 'desc 1', :foo => 'bar'}
+    #   definition_of(:has_description, :description)
+    #   # => 'desc 1'
+    #
+    # @param aspect [Symbol] the aspect to list (:description, :type, :encrypted, etc.)
+    # @return [Hash, Object]
+    def definition_of(param, attr=nil)
+      attr ? definitions[param.to_sym][attr] : definitions[param.to_sym]
     end
 
-    # List of params that have descriptions
-    def described_params
-      params_with(:description)
+    # a hash holding every param with that aspect and its definition
+    #
+    # @example
+    #   @config.define :has_description,      :description => 'desc 1'
+    #   @config.define :also_has_description, :description => 'desc 2'
+    #   @config.define :no_description,       :something_else => 'foo'
+    #   #
+    #   params_with(:description)
+    #   # => { :has_description => 'desc 1', :also_has_description => 'desc 2' }
+    #
+    # @param aspect [Symbol] the aspect to list (:description, :type, :encrypted, etc.)
+    # @return [Hash]
+    def params_with(aspect)
+      hsh = {}
+      definitions.each do |param_name, param_def|
+        next unless param_def.has_key?(aspect)
+        hsh[param_name] = definition_of(param_name, aspect)
+      end
+      hsh
     end
 
     # ===========================================================================
@@ -72,44 +108,28 @@ module Configliere
     #   Settings.define :param, :type => Date
     #
 
-    def type_for param
-      param_definitions[param][:type]
-    end
-
-    # All typed params with their descriptions
-    def typed_params
-      definitions_for(:type)
-    end
-
-    # List of params that have descriptions
-    def typed_param_names
-      params_with(:type)
-    end
-
-    require 'date'
-
     # Coerce all params with types defined to their proper form
     def resolve_types!
-      typed_params.each do |param, type|
-        val = self[param]
+      params_with(:type).each do |param, type|
+        val  = self[param]
         case
         when val.nil?            then val = nil
         when (type == :boolean)  then
           if ['false', false, 0, '0', ''].include?(val) then val = false else val = true end
-        when ((type == Array) && val.is_a?(String))
-          val = val.split(",")   rescue nil
-          # following types map blank to nil
-        when (val.blank?)        then val = nil
+        when (type == Array)
+          if val.is_a?(String) then val = val.split(",") rescue nil ; end
+        # for all following types, map blank/empty to nil
+        when (val.respond_to?(:empty?) && val.empty?) then val = nil
         when (type == :filename) then val = File.expand_path(val)
         when (type == Float)     then val = val.to_f
         when (type == Integer)   then val = val.to_i
         when (type == Symbol)    then val = val.to_s.to_sym     rescue nil
+        when (type == Regexp)    then val = Regexp.new(val)     rescue nil
         when ((val.to_s == 'now') && (type == Date))     then val = Date.today
         when ((val.to_s == 'now') && (type == DateTime)) then val = DateTime.now
-        when (type == Date)     then val = Date.parse(val)     rescue nil
-        when (type == DateTime) then val = DateTime.parse(val) rescue nil
-        when (type == Regexp)   then val = Regexp.new(val)     rescue nil
-        else # nothing
+        when ((val.to_s == 'now') && (type == Time))     then val = Time.now
+        when [Date, Time, DateTime].include?(type)       then val = type.parse(val) rescue nil
+        else true # nothing
         end
         self[param] = val
       end
@@ -124,41 +144,14 @@ module Configliere
     #   Settings.define :param, :required => true
     #
 
-    # List of params that are required
-    # @return [Array] list of required params
-    def required_params
-      params_with(:required)
-    end
-
     # Check that all required params are present.
     def validate_requireds!
       missing = []
-      required_params.each do |param|
-        missing << param if self[param].nil?
+      params_with(:required).each do |param, is_required|
+        missing << param if self[param].nil? && is_required
       end
-      raise "Missing values for:\n #{missing.map{|s| "  --" + s.to_s + (description_for(s) ? (" (" + description_for(s).to_s + ") ") : '') }.sort.join("\n")}" if (! missing.empty?)
-    end
-
-    # all params with a value for the definable aspect
-    #
-    # @param definable the aspect to list (:description, :type, :encrypted, etc.)
-    def params_with defineable
-      param_definitions.keys.find_all{|param| param_definitions[param][defineable] } || []
-    end
-
-    # all params without a value for the definable aspect
-    #
-    # @param definable the aspect to reject (:description, :type, :encrypted, etc.)
-    def params_without defineable
-      param_definitions.keys.reject{|param| param_definitions[param].include?(defineable) } || []
-    end
-
-    def definitions_for defineable
-      hsh = {}
-      param_definitions.each do |param, defs|
-        hsh[param] = defs[defineable] if defs[defineable]
-      end
-      hsh
+      return if missing.empty?
+      raise "Missing values for: #{missing.map{|pn| d = definition_of(pn, :description) ; (d ? "#{pn} (#{d})" : pn.to_s) }.sort.join(", ")}"
     end
 
     # Pretend that any #define'd parameter is a method
@@ -170,7 +163,7 @@ module Configliere
     def method_missing meth, *args
       meth.to_s =~ /^(\w+)(=)?$/ or return super
       name, setter = [$1.to_sym, $2]
-      return(super) unless param_definitions.include?(name)
+      return(super) unless has_definition?(name)
       if setter && (args.size == 1)
         self[name] = args.first
       elsif (!setter) && args.empty?
@@ -179,8 +172,9 @@ module Configliere
     end
 
   end
+
+  # Define is included by default
   Param.class_eval do
     include Configliere::Define
   end
 end
-

data/lib/configliere/encrypted.rb

@@ -1,9 +1,6 @@
-Configliere.use :config_file, :define, :crypter
-
+require 'configliere/crypter'
 module Configliere
   module EncryptedParam
-    # The password used in encrypting params during serialization
-    attr_accessor :encrypt_pass
 
     # decrypts any encrypted params
     # then calls the next step in the resolve! chain.
@@ -17,7 +14,7 @@ module Configliere
     def resolve_encrypted!
       remove_and_adopt_encrypt_pass_param_if_any!
       encrypted_params.each do |param|
-        encrypted_val = deep_delete(*dotted_to_encrypted_keys(param)) or next
+        encrypted_val = deep_delete(*encrypted_key_path(param)) or next
         self[param] = self.decrypted(encrypted_val)
       end
     end
@@ -27,52 +24,54 @@ module Configliere
     # @example
     #   Settings.defaults :username=>"mysql_username", :password=>"mysql_password"
     #   Settings.define :password, :encrypted => true
-    #   Settings.exportable
+    #   Settings.export
     #     #=> {:username => 'mysql_username', :password=>"\345?r`\222\021"\210\312\331\256\356\351\037\367\326" }
     def export
+      remove_and_adopt_encrypt_pass_param_if_any!
       hsh = super()
       encrypted_params.each do |param|
         val = hsh.deep_delete(*convert_key(param)) or next
-        hsh.deep_set( *(dotted_to_encrypted_keys(param) | [encrypted(val)]) )
+        hsh.deep_set( *(encrypted_key_path(param) | [encrypted(val)]) )
       end
       hsh
     end
 
     # if :encrypted_pass was set as a param, remove it from the hash and set it as an attribute
     def remove_and_adopt_encrypt_pass_param_if_any!
-      @encrypt_pass = self.delete(:encrypt_pass) if self[:encrypt_pass]
+      @encrypt_pass ||= self.delete(:encrypt_pass) if self[:encrypt_pass]
+      @encrypt_pass ||= ENV['ENCRYPT_PASS']        if ENV['ENCRYPT_PASS']
     end
 
     # the chain of symbol keys for a dotted path key,
     # prefixing the last one with "encrypted_"
     #
     # @example
-    #    dotted_to_encrypted_keys('amazon.api.key')
+    #    encrypted_key_path('amazon.api.key')
     #    #=> [:amazon, :api, :encrypted_key]
-    def dotted_to_encrypted_keys param
-      encrypted_path = convert_key(param).dup
+    def encrypted_key_path param
+      encrypted_path = Array(convert_key(param))
       encrypted_path[-1] = "encrypted_#{encrypted_path.last}".to_sym
       encrypted_path
     end
 
     # list of all params to encrypt on serialization
     def encrypted_params
-      params_with(:encrypted)
+      params_with(:encrypted).keys.select{|p| definition_of(p, :encrypted) }
     end
 
     def decrypted val
-      return val if val.blank?
-      Configliere::Crypter.decrypt(val, encrypt_pass)
+      return val.to_s if val.to_s.empty?
+      Configliere::Crypter.decrypt(val, @encrypt_pass)
     end
 
     def encrypted val
       return unless val
-      Configliere::Crypter.encrypt(val, encrypt_pass)
+      Configliere::Crypter.encrypt(val, @encrypt_pass)
     end
   end
 
-  class Param
-    include EncryptedParam
+  Param.on_use(:encrypted) do
+    use :config_file, :define
+    extend EncryptedParam
   end
 end
-

data/lib/configliere/env_var.rb

@@ -1,5 +1,3 @@
-require 'yaml'
-Configliere.use :define
 module Configliere
   #
   # EnvVar -- load configuration from environment variables
@@ -18,19 +16,19 @@ module Configliere
         end
       end
     end
-    
+
   protected
     def adopt_env_var! param, env
       env   = env.to_s
-      param_definitions[param][:env_var] ||= env
+      definition_of(param)[:env_var] ||= env
       val = ENV[env]
       self[param] = val if val
     end
   end
 
-  Param.class_eval do
-    # include read / save operations
-    include EnvVar
+  Param.on_use(:env_var) do
+    use :commandline
+    extend Configliere::EnvVar
   end
 end
 

data/lib/configliere/param.rb

@@ -1,15 +1,24 @@
-require 'configliere/core_ext/sash.rb'
 module Configliere
-  class ParamParent < ::Hash
-    # default export method: self
+  #
+  # We want to be able to call super() on these methods in all included models,
+  # so we define them in this parent shim class.
+  #
+  class ParamParent < DeepHash
+    # default export method: dup of self
     def export
-      to_hash
+      dup.tap{|hsh| hsh.each{|k,v| hsh[k] = v.respond_to?(:export) ? v.export : v } }
     end
+
     # terminate resolution chain
+    # @return self
     def resolve!
+      self
     end
-    # terminate validation chain
+
+    # terminate validation chain.
+    # @return self
     def validate!
+      self
     end
   end
 
@@ -21,26 +30,6 @@ module Configliere
   #
   class Param < Configliere::ParamParent
 
-    # @param constructor<Object>
-    #   The default value for the mash. Defaults to an empty hash.
-    #
-    # @details [Alternatives]
-    #   If constructor is a Hash, a new mash will be created based on the keys of
-    #   the hash and no default value will be set.
-    def initialize(constructor = {})
-      if constructor.is_a?(Hash)
-        super()
-        update(constructor) unless constructor.empty?
-      else
-        super(constructor)
-      end
-    end
-
-    # @return [Hash] The mash as a Hash with string keys.
-    def to_hash
-      Hash.new(default).merge(self)
-    end
-
     #
     # Incorporates the given settings.
     # alias for deep_merge!
@@ -53,60 +42,44 @@ module Configliere
     #    Settings.defaults :basket => :tasket, :moon => { :cow => :smiling }
     #    Config  #=> { :hat => :cat, :basket => :tasket, :moon => { :man => :smiling, :cow => :jumping } }
     #
+    # @return self
     def defaults hsh
       deep_merge! hsh
+      self
     end
 
-    # Finalize and validate params
+    # Finalize and validate params. All include'd modules and subclasses *must* call super()
+    # @return self
     def resolve!
       super()
       validate!
+      self
     end
-    # Check that all defined params are valid
+
+    # Check that all defined params are valid. All include'd modules and subclasses *must*call super()
+    # @return self
     def validate!
       super()
+      self
     end
 
-    def []= param, val
-      if param =~ /\./
-        return deep_set( *(convert_key(param) | [val]) )
-      else
-        super param, val
+    def use *mws
+      hsh = mws.pop if mws.last.is_a?(Hash)
+      Configliere.use(*mws)
+      mws.each do |mw|
+        if (blk = USE_HANDLERS[mw])
+          instance_eval(&blk)
+        end
       end
+      self.deep_merge!(hsh) if hsh
+      self
     end
 
-    def [] param
-      if param =~ /\./
-        return deep_get( *convert_key(param) )
-      else
-        super param
-      end
-    end
-
-    def delete param
-      if param =~ /\./
-        return deep_delete( *convert_key(param) )
-      else
-        super param
-      end
-    end
-
-    def use *args
-      hsh = args.pop if args.last.is_a?(Hash)
-      Configliere.use(*args)
-      self.deep_merge!(hsh) unless hsh.nil?
-    end
-
-  protected
-    # @param key<Object> The key to convert.
-    #
-    # @param [Object]
-    #   The converted key. A dotted param ('moon.cheese.type') becomes
-    #   an array of sequential keys for deep_set and deep_get
-    #
-    # @api private
-    def convert_key dotted
-      dotted.to_s.split(".").map{|key| key.to_sym }
+    # @private
+    USE_HANDLERS = {} unless defined?(USE_HANDLERS)
+    # Block executed when use is invoked
+    def self.on_use mw, &block
+      USE_HANDLERS[mw] = block
     end
 
   end