rabbitt-configurator 1.2.4

data/lib/configurator/option.rb

@@ -0,0 +1,281 @@
+=begin
+Copyright (C) 2013 Carl P. Corliss
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+=end
+
+require 'pathname'
+
+module Configurator
+  class Option
+    attr_accessor :name, :parent
+    attr_reader :type, :default, :caster, :validations, :required
+    private :validations, :required
+
+    UNDEFINED_OPTION = :__undefined__
+
+    def initialize(name, parent, options={})
+      @name     = name.to_sym
+      @value    = nil
+      @parent   = parent
+      @guarding = false
+
+      @default = (options.delete(:default) || UNDEFINED_OPTION).freeze
+      @type    = (type = options.delete(:type)).nil? ? compute_type(@default) : type
+      @caster  = (cast = options.delete(:cast)).nil? ? Cast::Director[@type] : Cast::Director[cast]
+
+      @required    = determine_if_required?(options)
+      @validations = gather_validations(options)
+
+      if options.count > 0
+        warn "#{path_name}: encountered unknown options: #{options.inspect}"
+      end
+    rescue StandardError => e
+      raise OptionInvalid.new("Failed to add option #{parent.path_name}.#{name}: #{e.class.name}: #{e.message}") { |ve|
+        ve.set_backtrace(e.backtrace)
+      }
+    end
+
+    def compute_type(type)
+      case type
+        when UNDEFINED_OPTION then :any
+        when OptionValue then type.type
+        when Bignum, Fixnum then :integer
+        when Float then :float
+        when Symbol then :symbol
+        when FalseClass, TrueClass, /(true|false|yes|no|enabled?|disabled?|on|off)/i then :boolean
+        when String then :string
+        when Pathname then :path
+        when URI then :uri
+        when Hash then :hash
+        when Array then
+          type.size <= 0 ? :array : [compute_type(type.first)]
+        when Proc then
+          with_loop_guard do
+            compute_type(type.call)
+          end rescue :any
+        else :any
+      end
+    end
+
+    def value=(v)
+      return nil unless validate(v)
+      @value = v
+    end
+
+    def value
+      return nil if @value.nil? && @default == UNDEFINED_OPTION
+
+      value = (@value || @default)
+
+      begin
+        with_loop_guard do
+          if value.respond_to? :call
+            unless value.arity == 0
+              raise OptionInvalidCallableDefault, "#{path_name}: callable defaults must not accept any arguments"
+            end
+            value = value.call
+          end
+        end
+      rescue OptionLoopError
+        raise # bubble up
+      rescue NoMethodError => e
+        method = e.message.match(/undefined method .([^']+)'.+/)[1]
+        raise OptionInvalidCallableDefault, "#{path_name}: bad method/option name #{method.inspect} in callable default."
+      rescue StandardError => e
+        excp = OptionInvalidCallableDefault.new "#{path_name}: error executing callable default: #{e.class.name}: #{e.message}"
+        excp.set_backtrace(e.backtrace)
+        raise excp
+      end
+
+      @caster.convert(value)
+    end
+
+    def include?(data)
+      value.respond_to?(:include?) ? value.include?(data) : false
+    end
+
+    def empty?; value.nil? || value.empty?; end
+    def valid?; validate(value); end
+    def required?; !!@required; end
+    def optional?; !required?; end
+    def path_name; [ parent.path_name, name ].join('.'); end
+    def deprecated?; false; end
+    def renamed?; false; end
+
+  private
+
+    def determine_if_required?(options)
+      if options.key?(:required) && options.key?(:optional)
+        unless !!options[:required] != !!options[:optional]
+          raise OptionInvalidArgument, "#{path_name}: can't be both required and optional at the same time!"
+        else
+          options.delete(:optional)
+          !!options.delete(:required)
+        end
+      elsif options.key?(:required)
+        !!options.delete(:required)
+      elsif options.key?(:optional)
+        not !!options.delete(:optional)
+      else
+        # if there's no default, require option
+        default == :__undefined__ ? true : false
+      end
+    end
+
+    def gather_validations(options)
+      # XXX: create Validation classes (Expection would derive from Validation) and
+      # move all validation logic into those classes
+      [].tap { |validations|
+        validation   = (v = options.delete(:validate)).nil? ? true : v
+        validate_msg = options.delete(:validate_message)
+
+        expectations = options.delete(:expect)
+        expect_msg   = options.delete(:expect_messgae)
+
+        type_validator     = options.delete(:type_validator)
+        type_validator_msg = options.delete(:type_validation_message)
+
+        if !validation
+          if expectations
+            raise OptionInvalidArgument, "#{path_name}: can't disable validations and set an expectation at the same time!"
+          elsif type_validator
+            raise OptionInvalidArgument, "#{path_name}: can't disable validations and assign a type validator at the same time!"
+          end
+        end
+
+        return [] unless validation
+
+        if type_validator
+          validations << lambda { |_value|
+            unless type_validator.call(_value)
+              if type_validator_msg
+                raise ValidationError, "#{path_name}: #{_value.inspect} fails to validate as custom type: #{type_validator_msg}"
+              else
+                raise ValidationError, "#{path_name}: #{_value.inspect} fails to validate as custom type."
+              end
+            end
+            true
+          }
+        else
+          validations << lambda { |_value|
+            unless validate_type(_value)
+              raise ValidationError, "#{path_name}: #{_value.inspect} fails to validate as #{type.inspect}"
+            end
+            true
+          }
+        end
+
+        validations << lambda { |_value|
+          unless validation.call(_value)
+            if validate_msg
+              raise ValidationError, "#{path_name}: #{_value.inspect} fails custom validation rule: #{validate_msg}"
+            else
+              raise ValidationError, "#{path_name}: #{_value.inspect} fails custom validation rule"
+            end
+          end
+          true
+        } if validation.respond_to?(:call)
+
+        unless expectations.nil?
+          if expectations.respond_to? :call
+            validations << lambda { |_value|
+              unless expectations.call(_value)
+                if expect_msg
+                  raise ValidationError, "#{path_name}: #{_value.inspect} fails custom expectation: #{expect_msg}"
+                else
+                  raise ValidationError, "#{path_name}: #{_value.inspect} fails custom expectation"
+                end
+              end
+              true
+            }
+          else
+            validations << lambda { |_value|
+              unless expectations.include?(_value)
+                raise ValidationError, "#{path_name}: Failed expectation: #{_value.inspect} not in list: #{expectations.collect(&:inspect).join(', ')}"
+              end
+              true
+            }
+          end
+        end
+      }
+    end
+
+    def validate(_value)
+      return true if type == :any && validations.empty?
+
+      begin
+        # try on just the raw value first
+        validations.all? { |validation| validation.call(_value.freeze) }
+      rescue StandardError => initial_exception
+        begin
+          # now try on the converted value
+          cast_value = @caster.convert(_value)
+          validations.all? { |validation| validation.call(cast_value) }
+        rescue ValidationError => e
+          raise ValidationError.new(e.message).tap {|ve| ve.set_backtrace(initial_exception.backtrace) }
+        rescue CastError
+          raise initial_exception
+        end
+      end
+    end
+
+    def validate_type(_value, validation_type = nil)
+      validation_type ||= type
+
+      case validation_type
+        when :any; true
+        when Array then
+          return _value.is_a?(Array) if validation_type.empty?
+          [*_value].flatten.all? { |v|
+            validate_type(v, validation_type.first)
+          }
+        when :scalar then
+          validate_type(_value, :integer) || validate_type(_value, :float) ||
+          validate_type(_value, :symbol) || validate_type(_value, :string) ||
+          validate_type(_value, :boolean)
+        when :boolean then
+          _value.is_a?(FalseClass) || _value.is_a?(TrueClass)
+        when :float then
+          ((Float(_value) rescue nil) == _value.to_f)
+        when :integer then
+          ((Float(_value).to_i rescue nil) == _value.to_i)
+        when :path then
+          _value.is_a?(Pathname)
+        when :array then _value.is_a?(Array)
+        when :hash then _value.is_a?(Hash)
+        when :string then _value.is_a? String
+        when :symbol then _value.is_a? Symbol
+        when :uri then !!(URI.parse(_value) rescue false)
+        else
+          warn "unable to validate - no handler for type: #{type.inspect}"
+          true # assume valid
+      end
+    end
+
+    def with_loop_guard(&block)
+      begin
+        raise OptionLoopError if @guarding
+        @guarding = true
+        yield
+      rescue OptionLoopError => error
+        raise error.tap { |e| e.stack << path_name }
+      ensure
+        @guarding = false
+      end
+    end
+
+  end
+end

data/lib/configurator/section.rb

@@ -0,0 +1,254 @@
+=begin
+Copyright (C) 2013 Carl P. Corliss
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+=end
+
+module Configurator
+  class Section
+    attr_accessor :name, :parent
+    attr_reader :table
+
+    def initialize(name, parent = nil, options = {})
+      @table  = {}
+      @name   = name
+      @parent = parent
+
+      load options
+    end
+
+    def type; :section; end
+    def deprecated?; false; end
+    def renamed?; false; end
+
+    def root; parent.nil? ? self : parent.root; end
+    def path_name; parent.nil? ? name : [ parent.path_name, name ].join('.'); end
+    def required?; options.any? { |k,o| o.required? }; end
+    def optional?; !required?; end
+
+    def include?(option_name)
+      @table.key? option_name.to_sym
+    end
+
+    def [](option_name)
+      @table[option_name.to_sym]
+    end
+
+    def []=(option_name, value)
+      @table[option_name.to_sym].value = value
+    end
+
+    def each(&block)
+      @table.each &block
+    end
+
+    def inject(*args, &block)
+      @table.inject(*args, &block)
+    end
+
+    def to_h
+      inject({}) { |hash,(_name,_option)|
+        hash.tap {|h|
+          unless _option.deprecated? || _option.renamed?
+            h[_name] = _option.to_h rescue _option.value
+          end
+        }
+      }
+    end
+
+    def config() self; end
+    alias :value :config
+
+    def load(data)
+      unless data.is_a? Hash
+        warn "#{path_name}: invalid load data for section (#{data.inspect}) - skipping..."
+      else
+        data.each { |key,value|
+          if not @table.key? key.to_sym
+            warn "#{path_name}: unable to load data for unknown key #{key.inspect} -> #{value.inspect}"
+            next
+          end
+          @table[key.to_sym].value = value
+        }
+      end
+    end
+    alias :value= :load
+
+    def requirements_fullfilled?
+      @table.collect { |k,v|
+        if v.respond_to? :requirements_fullfilled?
+          v.requirements_fullfilled?
+        else
+          next true unless v.required? && v.value.nil? && !(v.deprecated? rescue false)
+          warn "#{v.path_name}: option required but nil value."
+          false
+        end
+      }
+    end
+
+    def option(option_name, *args)
+      _options = args.last.is_a?(Hash) ? args.pop : {}
+      _options.merge!(:type => args.first)
+
+      option_name = option_name.to_sym
+      deprecated  = _options.delete(:deprecated)
+
+      option = Option.new(option_name, self, _options)
+
+      if deprecated
+        option = DelegatedOption::Deprecated.new(
+          option.name, option.parent, option, end_of_life
+        )
+      end
+
+      add_option option_name, option
+    end
+
+    def options(*names)
+      names.each do |option_name|
+        option option_name
+      end
+    end
+
+    def section(option_name, options = {}, &block)
+      option_name = option_name.to_sym
+      deprecated  = options.delete(:deprecated)
+
+      section = Section.new(option_name, self).tap { |s|
+        s.instance_eval(&block) if block_given?
+      }
+
+      if deprecated
+        section = DelegatedOption::Deprecated.new(
+          section.name, section.parent, section, end_of_life
+        )
+      end
+
+      add_option(option_name, section)
+    end
+
+    def alias!(orig_path, new_path)
+      orig_path = "root.#{orig_path}" unless orig_path.include? 'root.'
+      new_path  = "root.#{new_path}" unless new_path.include? 'root.'
+
+      unless _option = root.get_path(orig_path)
+        raise DeprecateFailed, "Unable to alias #{new_path} to #{orig_path} - option does not appear to be defined."
+      end
+
+      _option = root.get_path(orig_path)
+      _parent, _name = new_path.option_path_split
+
+      _parent = root.get_path(_parent)
+      new_option  = AliasedOption.new(_name, _parent, _option)
+      _parent.add_option(_name, new_option)
+    end
+    alias :aliased! :alias!
+
+    def deprecate!(option_paths, end_of_life = nil)
+      [*option_paths].collect {|option_path|
+        option_path = "root.#{option_path}" unless option_path.include? 'root.'
+
+        unless _option = root.get_path(option_path)
+          raise DeprecateFailed, "Unable to deprecated #{option_path} - option does not appear to be defined."
+        end
+
+        _option = DeprecatedOption.new(_option.name, _option.parent, _option, end_of_life)
+        _option.parent.replace_option(_option.name, _option)
+      }
+    end
+    alias :deprecated! :deprecate!
+
+    # like alias but with reversed arguments and a warning on assignment
+    # note: new path must already exist. old_path is created as an alias
+    # to new_path.
+    def rename!(old_path, target_path)
+      old_path    = "root.#{old_path}" unless old_path.include? 'root.'
+      target_path = "root.#{target_path}" unless target_path.include? 'root.'
+
+      unless _option = root.get_path(target_path)
+        raise OptionNotExist, "option #{target_path} does not exist -  target path must exist for rename."
+      end
+
+      _parent, _name = old_path.option_path_split
+      _section = root.get_path(_parent)
+
+      renamed_option = RenamedOption.new(_name, _section, _option)
+
+      begin
+        _section.add_option(_name, renamed_option)
+      rescue OptionExists => e
+        raise RenameFailed, "Unable to rename #{old_path} -> #{target_path}"
+      end
+    end
+    alias :renamed! :rename!
+    alias :moved! :rename!
+
+    def add_option(option_name, object)
+      option_name = option_name.to_sym
+      if @table.key? option_name
+        raise OptionExists, "Option #{path_name}.#{option_name} already exists"
+      end
+
+      @table[option_name] = object.tap {
+        self.class.class_eval(<<-EOF, __FILE__, __LINE__ + 1)
+          def #{option_name}()
+            OptionValue.new(@table[#{option_name.inspect}])
+          end
+
+          def #{option_name}=(_value)
+            @table[#{option_name.inspect}].value = _value
+          end
+        EOF
+      }
+    end
+
+    def replace_option(name, new_option)
+      name = name.to_sym
+      unless @table.include? name
+        raise OptionNotExist, "#{path_name}.#{name} doesn't exist"
+      end
+      @table[name] = new_option
+    end
+
+    def get_path(path)
+      begin
+        # remove the root - we start there anyway
+        path.gsub!(/^root\.?/, '')
+        current_path = [:root]
+
+        path.split('.').collect(&:to_sym).inject(root) do |option, path_component|
+          current_path << path_component
+          unless option.include? path_component
+            raise InvalidOptionPath, "#{current_path.join('.')}: doesn't exist in the current configuration."
+          else
+            option = option[path_component]
+          end
+        end
+      rescue StandardError => e
+        warn "#{e.class.name}: #{e.message}\n\t#{e.backtrace.join("\n\t")}"
+      end
+    end
+
+    alias :original_respond_to? :respond_to?
+    def respond_to?(method, include_private = false)
+      @table.key?(method) || original_respond_to?(method, include_private)
+    end
+
+    def method_missing(method, *args, &block)
+      return super unless respond_to?(method)
+      self[method] if include?(method)
+    end
+  end
+end

data/lib/configurator/validation.rb

@@ -0,0 +1,18 @@
+=begin
+Copyright (C) 2013 Carl P. Corliss
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+=end
+

data/lib/configurator/version.rb

@@ -0,0 +1,21 @@
+=begin
+Copyright (C) 2013 Carl P. Corliss
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+=end
+
+module Configurator
+  VERSION = "1.2.4"
+end

data/lib/configurator.rb

@@ -0,0 +1,30 @@
+=begin
+Copyright (C) 2013 Carl P. Corliss
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc.,
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+=end
+
+require 'configurator/errors'
+require 'configurator/dsl'
+require 'configurator/extensions'
+require 'configurator/delegated'
+
+module Configurator
+  autoload :Loader,      'configurator/loader'
+  autoload :Section,     'configurator/section'
+  autoload :Option,      'configurator/option'
+  autoload :Cast,        'configurator/cast'
+  autoload :VERSION,     'configurator/version'
+end