calibrate 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6a9efa272faf23fed111b7446d58878d2534bace
+  data.tar.gz: c13706c1ddaf9ed6a3298e4b55e1e4f491a1e208
+SHA512:
+  metadata.gz: 9b3895aa4322307c3f8d1145adf7004b103008c12f50b3e1566b4c8292161962fc2f281b7d3c58a12fc17a9e8a3ade56cc059cbf79f71c39b8b27a258cd3f141
+  data.tar.gz: e0ac1bc4a4be8dead4626ee2296e00330cd788df779ca82a47d874b4bbcf4615125e43ac2fa9a2015db5f501f7f8062ec64b4cffbed5b6222188cc90d11d664d

data/lib/calibrate.rb

@@ -0,0 +1 @@
+require 'calibrate/configurable'

data/lib/calibrate/configurable.rb

@@ -0,0 +1,29 @@
+module Calibrate
+  #Handles setting options on objects it's mixed into
+  #
+  #Settings can have default values or be required (as opposed to defaulting to
+  #nil).  Settings and their defaults are inherited (and can be overridden) by
+  #subclasses.
+  #
+  #Calibrate also includes a yard-extension that will document settings of a
+  #Configurable
+  #
+  #@example (see ClassMethods)
+  module Configurable
+    class Exception < ::StandardError
+    end
+
+    class NoDefaultValue < Exception
+      def initialize(field_name, klass)
+        super("No default value for field #{field_name} on class #{klass.name}")
+      end
+    end
+  end
+end
+
+require 'calibrate/configurable/field-metadata'
+require 'calibrate/configurable/proxy-value'
+require 'calibrate/configurable/field-processor'
+require 'calibrate/configurable/class-methods'
+require 'calibrate/configurable/instance-methods'
+require 'calibrate/configurable/directory-structure'

data/lib/calibrate/configurable/class-methods.rb

@@ -0,0 +1,227 @@
+module Calibrate
+  module Configurable
+    RequiredField = Object.new.freeze
+
+    #Describes class level DSL & machinery for working with configuration
+    #managment.
+    #
+    #@example
+    #    class ConfExample
+    #      include Configurable
+    #
+    #      setting :foo
+    #      settings :bar => 1, :baz => 3
+    #      nil_fields :hoo, :ha, :harum
+    #      required_fields :must
+    #
+    #      def initialize
+    #        setup_defaults
+    #      end
+    #    end
+    #
+    #    ce = ConfExample.new
+    #    ce.bar #=> 1
+    #    ce.hoo #=> nil
+    #    ce.hoo = "hallo"
+    #    ce.check_required #=> raises error because :must and :foo aren't set
+    module ClassMethods
+      def inspect_instance(instance, indent="")
+        field_names.map do |name|
+          meta = field_metadata(name)
+          "#{indent}#{meta.inspect_on(instance, indent * 2)}"
+        end.join("\n")
+      end
+
+      def default_values
+        @default_values ||= []
+      end
+
+      def field_names
+        names = default_values.map{|field| field.name}
+        if Configurable > superclass
+          names | superclass.field_names
+        else
+          names
+        end
+      end
+
+      def field_metadata(name)
+        field = default_values.find{|field| field.name == name}
+        if field.nil? and Configurable > superclass
+          superclass.field_metadata(name)
+        else
+          field
+        end
+      end
+
+      #@raises NoDefaultValue
+      def default_value_for(name)
+        field = field_metadata(name)
+        raise NoDefaultValue.new(name,self) unless field.is?(:defaulting)
+        return field.default_value
+      end
+
+      #Creates an anonymous Configurable - useful in complex setups for nested
+      #settings
+      #@example SSH options
+      #  setting :ssh => nested(:username => "me", :password => nil)
+      def nested(hash=nil, &block)
+        nested = Class.new(Struct)
+        nested.settings(hash || {})
+        if block_given?
+          nested.instance_eval(&block)
+        end
+        return nested
+      end
+
+      #Quick list of setting fields with a default value of nil.  Useful
+      #especially with {CascadingDefinition#resolve_configuration}
+      def nil_fields(*names)
+        names.each do |name|
+          setting(name, nil)
+        end
+        self
+      end
+      alias nil_field nil_fields
+
+      #List fields with no default for with a value must be set before
+      #definition.
+      def required_fields(*names)
+        names.each do |name|
+          setting(name)
+        end
+        self
+      end
+      alias required_field required_fields
+
+      #Defines a setting on this class - much like a attr_accessible call, but
+      #allows for defaults and required settings
+      def setting(name, default_value = RequiredField)
+        name = name.to_sym
+        metadata =
+          if default_value == RequiredField
+            FieldMetadata.new(name, nil).is(:required).isnt(:defaulting)
+          else
+            FieldMetadata.new(name, default_value)
+          end
+
+        attr_writer(name)
+        define_method(metadata.reader_method) do
+          metadata.value_on(self)
+        end
+
+        if existing = default_values.find{|field| field.name == name} and existing.default_value != default_value
+          source_line = caller.drop_while{|line| /#{__FILE__}/ =~ line}.first
+            warn "Changing default value of #{self.name}##{name} from #{existing.default_value.inspect} to #{default_value.inspect} (at: #{source_line})"
+        end
+        default_values << metadata
+        metadata
+      end
+
+      def runtime_required_fields(*names)
+        names.each do |name|
+          runtime_setting(name)
+        end
+        self
+      end
+      alias runtime_required_field runtime_required_fields
+
+      def runtime_setting(name, default_value = RequiredField)
+        setting(name, default_value).is(:runtime)
+      end
+
+      #@param [Hash] hash Pairs of name/value to be converted into
+      #  setting/default
+      def settings(hash)
+        hash.each_pair do |name, value|
+          setting(name, value)
+        end
+        return self
+      end
+      alias runtime_settings settings
+
+      def set_defaults_on(instance)
+        if Configurable > superclass
+          superclass.set_defaults_on(instance)
+        end
+        default_values.each do |field|
+          next unless field.is? :defaulting
+          value = field.build_default_value
+          instance.__send__(field.writer_method, value)
+        end
+      end
+
+      def missing_required_fields_on(instance)
+        missing = []
+        if Configurable > superclass
+          missing = superclass.missing_required_fields_on(instance)
+        end
+        default_values.each do |field|
+          if field.missing_on?(instance)
+            missing << field.name
+          else
+            set_value = instance.__send__(field.reader_method)
+            if Configurable === set_value
+              missing += set_value.class.missing_required_fields_on(set_value).map do |sub_field|
+                [field.name, sub_field].join(".")
+              end
+            end
+          end
+        end
+        return missing
+      end
+
+      def to_hash(obj)
+        hash = if Configurable > superclass
+                 superclass.to_hash(obj)
+               else
+                 {}
+               end
+        hash.merge( Hash[default_values.map{|field|
+          begin
+            value = obj.__send__(field.reader_method)
+            value =
+              case value
+              when Configurable
+                value.to_hash
+              else
+                value
+              end
+            [field.name, value]
+          rescue NoMethodError
+          end
+        }])
+      end
+
+      def from_hash(obj, hash) #XXX It'd be really nice if this could report unused fields
+        if Configurable > superclass
+          superclass.from_hash(obj, hash)
+        end
+        default_values.each do |field|
+          catch :next do
+            key = field.reader_method.to_s
+            value = hash.fetch(key.to_s) do
+              key = key.to_sym
+              hash.fetch(key) do
+                throw :next
+              end
+            end
+
+            existing_value = obj.__send__(field.reader_method)
+            if Configurable === existing_value and value.is_a? Hash
+              existing_value.from_hash(value)
+            else
+              obj.__send__(field.writer_method, value)
+            end
+          end
+        end
+      end
+
+      def included(mod)
+        mod.extend ClassMethods
+      end
+    end
+
+    extend ClassMethods
+  end
+end

data/lib/calibrate/configurable/directory-structure.rb

@@ -0,0 +1,163 @@
+require 'rake'
+
+module Calibrate
+  module Configurable
+    class MissingRelativePaths < Exception; end
+
+    #XXX Consider making the actual dir/path settings r/o
+    #Very easy to say
+    #  filename = "string"
+    #rather than
+    #  filename.relative_path = "string"
+    #and it isn't clear which (abs/rel) you mean
+    #
+    module DirectoryStructure
+      class StructurePath
+        include Configurable
+
+        setting :absolute_path
+        setting :relative_path
+
+        alias abspath absolute_path
+        alias relpath relative_path
+
+        #No #path - ambiguous whether that would be abspath or pathname
+
+        def initialize(rel_path)
+          self.relative_path = rel_path unless rel_path == Configurable::RequiredField
+        end
+
+        def pathname
+          @pathname ||=
+            begin
+              fail_unless_set(:absolute_path)
+              require 'pathname'
+              Pathname.new(absolute_path)
+            end
+        end
+        alias path_name pathname
+
+        def to_s
+          fail_unless_set(:absolute_path)
+          absolute_path
+        end
+
+        def inspect
+          "<path: #{
+            if field_unset?(:absolute_path)
+              if field_unset?(:relative_path)
+                "<<?>>"
+              else
+                "?/#{relative_path}"
+              end
+            else
+              absolute_path.inspect
+            end
+          }>"
+        end
+      end
+
+      module ClassMethods
+        RequiredField = Configurable::RequiredField
+
+        def root_paths
+          @root_paths ||= []
+        end
+
+        def path_heirarchy
+          @path_heirarchy ||= []
+        end
+        attr_writer :path_heirarchy
+
+        def path_fields
+          @path_fields ||= []
+        end
+
+        def dir(field_name, *args)
+          rel_path = RequiredField
+          if String === args.first
+            rel_path = args.shift
+          end
+          parent_field = path(field_name, rel_path)
+
+          self.path_heirarchy += args.map do |child_field|
+            [parent_field, child_field]
+          end
+          return parent_field
+        end
+
+        def path(field_name, rel_path=RequiredField)
+          field = setting(field_name, StructurePath.new(rel_path))
+          root_paths << field
+          path_fields << field
+          return field
+        end
+
+        def resolve_path_on(instance, parent, child_field, missing_relatives)
+          child = child_field.value_on(instance)
+          return unless child.field_unset?(:absolute_path)
+          if child.field_unset?(:relative_path)
+            missing_relatives << child_field
+            return
+          end
+          child.absolute_path = File::join(parent.absolute_path, child.relative_path)
+        end
+
+        def resolve_paths_on(instance)
+          superclass_exception = nil
+          if superclass < DirectoryStructure
+            begin
+            superclass.resolve_paths_on(instance)
+            rescue MissingRelativePaths => mrp
+              superclass_exception = mrp
+            end
+          end
+          missing_relatives = []
+
+          (root_paths - path_heirarchy.map{|_, child| child }).each do |field|
+            resolve_path_on(instance, instance, field, missing_relatives)
+          end
+
+          path_heirarchy.reverse.each do |parent_field, child_field|
+            next if missing_relatives.include?(parent_field)
+            parent = parent_field.value_on(instance)
+            resolve_path_on(instance, parent, child_field, missing_relatives)
+          end
+
+          case [missing_relatives.empty?, superclass_exception.nil?]
+          when [true, false]
+            raise superclass_exception
+          when [false, true]
+            raise MissingRelativePaths, "Required field#{missing_relatives.length == 1 ? "" : "s"} #{missing_relatives.map{|field| "#{field.name}.relative_path".inspect}.join(", ")} unset on #{self.inspect}"
+          when [false, false]
+            raise MissingRelativePaths, "Required field#{missing_relatives.length == 1 ? "" : "s"} #{missing_relatives.map{|field| "#{field.name}.relative_path".inspect}.join(", ")} unset on #{self.inspect}" + "\n" + superclass_exception.message
+          end
+
+          path_fields.each do |field|
+            value = field.value_on(instance)
+            next unless value.field_unset?(:relative_path)
+            value.relative_path = value.absolute_path
+          end
+        end
+      end
+
+      def self.included(sub)
+        sub.extend ClassMethods
+        dir_path =
+          if not (file_path = ::Rake.application.rakefile).nil?
+            File::dirname(File::expand_path(file_path))
+          elsif not (dir_path = ::Rake.application.original_dir).nil?
+            dir_path
+          else
+            file_path = caller[0].split(':')[0]
+            File::dirname(File::expand_path(file_path))
+          end
+        sub.setting :absolute_path, dir_path
+      end
+
+      def resolve_paths
+        self.class.resolve_paths_on(self)
+      end
+    end
+  end
+end

data/lib/calibrate/configurable/field-metadata.rb

@@ -0,0 +1,157 @@
+module Calibrate
+  module Configurable
+    class FieldMetadata
+      attr_accessor :name, :default_value
+
+      DEFAULT_PROPERTIES = {
+        :copiable => true,
+        :proxiable => true,
+        :required => false,
+        :runtime => false,
+        :defaulting => true,
+      }
+      def initialize(name, value)
+        @name = name
+        @default_value = value
+        @properties = DEFAULT_PROPERTIES.clone
+      end
+
+      def inspect
+        set_props = DEFAULT_PROPERTIES.keys.find_all do |prop|
+          @properties[prop]
+        end
+        "Field: #{name}: #{default_value.inspect} #{set_props.inspect}"
+      end
+
+      def inspect_on(instance, indent=nil)
+        set_props = DEFAULT_PROPERTIES.keys.find_all do |prop|
+          @properties[prop]
+        end
+        "Field: #{name}: #{value_on(instance).inspect} \n#{indent||""}(default: #{default_value.inspect} immediate: #{immediate_value_on(instance).inspect}) #{set_props.inspect}"
+      end
+
+      def validate_property_name(name)
+        unless DEFAULT_PROPERTIES.has_key?(name)
+          raise "Invalid field property #{name.inspect} - valid are: #{DEFAULT_PROPERTIES.keys.inspect}"
+        end
+      end
+
+      def is?(property)
+        validate_property_name(property)
+        @properties[property]
+      end
+
+      def is_not?(property)
+        validate_property_name(property)
+        !@properties[property]
+      end
+      alias isnt? is_not?
+
+      def is(property)
+        validate_property_name(property)
+        @properties[property] = true
+        self
+      end
+
+      def is_not(property)
+        validate_property_name(property)
+        @properties[property] = false
+        self
+      end
+      alias isnt is_not
+
+      def ivar_name
+        "@#{name}"
+      end
+
+      def writer_method
+        "#{name}="
+      end
+
+      def reader_method
+        name
+      end
+
+      def copy_from(instance)
+        return if unset_on?(instance)
+        copy_value(immediate_value_on(instance))
+      end
+
+      def build_default_value
+        if Module === @default_value and Configurable > @default_value
+          value = @default_value.new
+          value.class.set_defaults_on(value)
+          value
+        else
+          copy_value(@default_value)
+        end
+      end
+
+      def copy_value(value)
+        case value
+        when Symbol, Numeric, NilClass, TrueClass, FalseClass
+          value
+        else
+          if value.class == BasicObject
+            value
+          elsif value.respond_to?(:dup)
+            value.dup
+          elsif value.respond_to?(:clone)
+            value.clone
+          else
+            value
+          end
+        end
+      end
+
+      def immediate_value_on(instance)
+        instance.instance_variable_get(ivar_name)
+        #instance.__send__(reader_method)
+      end
+
+      def value_on(instance)
+        value = immediate_value_on(instance)
+        if ProxyValue === value
+          value.field.value_on(value.source)
+        else
+          value
+        end
+      end
+
+      def set_on?(instance)
+        return true unless instance.__send__(reader_method).nil?
+        return false unless instance.instance_variable_defined?(ivar_name)
+        value = immediate_value_on(instance)
+        if ProxyValue === value
+          value.field.set_on?(value.source)
+        else
+          true
+        end
+      end
+
+      def unset_on?(instance)
+        !set_on?(instance)
+      end
+
+      def missing_on?(instance)
+        return false unless is?(:required)
+        if instance.respond_to?(:runtime?) and !instance.runtime?
+          return runtime_missing_on?(instance)
+        else
+          return !set_on?(instance)
+        end
+      end
+
+      def runtime_missing_on?(instance)
+        return false if is?(:runtime)
+        return true unless instance.instance_variable_defined?(ivar_name)
+        value = immediate_value_on(instance)
+        if ProxyValue === value
+          value.field.runtime_missing_on?(value.source)
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/calibrate/configurable/field-processor.rb

@@ -0,0 +1,54 @@
+module Calibrate
+  module Configurable
+    class FieldProcessor
+      def initialize(source)
+        @source = source
+        @field_names = filter(source.class.field_names)
+      end
+      attr_accessor :field_names
+      attr_reader :source
+
+      def filter(field_names)
+        field_names.find_all do |name|
+          source.class.field_metadata(name).is?(filter_attribute)
+        end
+      end
+
+      def can_process(field, target)
+        target.respond_to?(field.writer_method)
+      end
+
+      def to(target)
+        field_names.each do |name|
+          field = source.class.field_metadata(name)
+          next unless can_process(field, target)
+          target.__send__(field.writer_method, value(field))
+        end
+      end
+    end
+
+    class SettingsCopier < FieldProcessor
+      def filter_attribute
+        :copiable
+      end
+
+      def can_process(field, target)
+        super and not( field.unset_on?(source) and field.unset_on?(target) )
+      end
+
+      def value(field)
+        return field.copy_from(source)
+      end
+    end
+
+    class SettingsProxier < FieldProcessor
+      def filter_attribute
+        :proxiable
+      end
+
+      def value(field)
+        ProxyValue.new(source, field)
+      end
+    end
+  end
+end

data/lib/calibrate/configurable/instance-methods.rb

@@ -0,0 +1,90 @@
+require 'calibrate/configurable/directory-structure'
+
+module Calibrate
+  class RequiredFieldUnset < StandardError
+  end
+
+  module Configurable
+    def initialize_copy(original)
+      original.copy_settings_to(self)
+    end
+
+    def copy_settings
+      SettingsCopier.new(self)
+    end
+
+    def copy_settings_to(other)
+      copy_settings.to(other)
+      self
+    end
+
+    def proxy_settings
+      SettingsProxier.new(self)
+    end
+
+    def proxy_settings_to(other)
+      proxy_settings.to(other)
+    end
+
+    def to_hash
+      self.class.to_hash(self)
+    end
+
+    def from_hash(hash)
+      self.class.from_hash(self, hash)
+    end
+
+    def unset_defaults_guard
+      raise "Tried to check required settings before running setup_defaults"
+    end
+
+    #Call during initialize to set default values on settings - if you're using
+    #Configurable outside of Calibrate, be sure this gets called.
+    def setup_defaults
+      def self.unset_defaults_guard
+      end
+
+      self.class.set_defaults_on(self)
+      self
+    end
+
+    #Checks that all required fields have be set, otherwise raises an error
+    #@raise RuntimeError if any required fields are unset
+    def check_required
+      unset_defaults_guard
+      missing = self.class.missing_required_fields_on(self)
+      unless missing.empty?
+        raise RequiredFieldUnset, "Required field#{missing.length > 1 ? "s" : ""} #{missing.map{|field| field.to_s.inspect}.join(", ")} unset on #{self.inspect}"
+      end
+      self
+    end
+
+    def proxy_value
+      ProxyDecorator.new(self)
+    end
+
+    #XXX deprecate
+    def unset?(value)
+      warn "#unset? is deprecated - use field_unset? instead"
+      value.nil?
+    end
+
+    def field_unset?(name)
+      self.class.field_metadata(name).unset_on?(self)
+    end
+
+    #Requires that a named field be set
+    def fail_unless_set(name)
+      if field_unset?(name)
+        raise "Assertion failed: Field #{name} unset"
+      end
+      true
+    end
+    alias fail_if_unset fail_unless_set
+
+    class Struct
+      include Configurable
+      include Configurable::DirectoryStructure
+    end
+  end
+end

data/lib/calibrate/configurable/proxy-value.rb

@@ -0,0 +1,30 @@
+module Calibrate
+  module Configurable
+    class ProxyValue
+      def initialize(source, field)
+        @source, @field = source, field
+      end
+      attr_reader :source, :field
+
+      def inspect
+        "#{self.class.name.split(':').last}: #{source.class.name}.#{field.inspect}"
+      end
+    end
+
+    class ProxyDecorator
+      def initialize(configurable)
+        @configurable = configurable
+      end
+
+      def method_missing(name, *args, &block)
+        unless block.nil? and args.empty?
+          raise NoMethodError, "method `#{name}' not defined with arguments or block when proxied"
+        end
+        unless @configurable.respond_to?(name)
+          raise NoMethodError, "cannot proxy `#{name}' - undefined on #{@configurable}"
+        end
+        return ProxyValue.new(@configurable, @configurable.class.field_metadata(name))
+      end
+    end
+  end
+end

data/lib/calibrate/yard-extensions.rb

@@ -0,0 +1,190 @@
+require 'yard'
+YARD::Templates::Engine.register_template_path File::expand_path("../../../yard_templates", __FILE__)
+
+module Mattock
+  module YARDExtensions
+    class DefineHandler < YARD::Handlers::Ruby::Base
+      handles :def
+
+      def mattock_defining?(obj, method)
+        check_list = obj.inheritance_tree
+        until check_list.empty?
+          check_list.each do |co|
+            return true if [:CascadingDefinition, :Configurable, :Tasklib, :TaskLib].include? co.name and method == "define"
+            return true if [:TaskMixin, :Task, :FileTask, :MultiTask].include? co.name and method == "action"
+          end
+          check_list = (check_list.find_all{|co| co.respond_to?(:mixins)}||[]).map{|co| co.mixins}.flatten
+        end
+      end
+
+      def root
+        ns = namespace
+        until ns.root?
+          ns = ns.namespace
+        end
+        ns
+      end
+
+      def process
+        return unless mattock_defining?(namespace, statement[0][0])
+        (root[:tasklibs] ||= []) << namespace
+        namespace[:task_definition] = statement[2]
+      end
+    end
+
+    class SettingHandler < YARD::Handlers::Ruby::Base
+      include YARD::Parser::Ruby
+
+      handles method_call(:setting)
+      namespace_only
+
+      def mattock_configurable?(obj)
+        check_list = obj.inheritance_tree
+        until check_list.empty?
+          check_list.each do |co|
+            return true if [:CascadingDefinition, :Configurable, :Task, :Tasklib, :TaskLib].include? co.name
+          end
+          check_list = check_list.find_all{|co| co.respond_to?(:mixins)}.map{|co| co.mixins}.flatten
+        end
+      end
+
+      def extract_name(obj)
+        case obj.type
+        when :symbol_literal
+          obj.jump(:ident, :op, :kw, :const)[0]
+        when :string_literal
+          obj.jump(:tstring_content)[0]
+        else
+          raise YARD::Parser::UndocumentableError, obj.source
+        end
+      end
+
+      def append_name(sexp, name)
+        prefix = sexp.jump(:ident, :tstring_content)
+        if prefix == sexp
+          raise YARD::Parser::UndocumentableError, sexp.source
+        end
+
+        "#{prefix[0]}.#{name}"
+      end
+
+      def setting_method_name
+        "setting"
+      end
+
+      def synthetic_setting(name, value=nil)
+        args = s( s(:string_literal, s(:string_content, s(:tstring_content, name))))
+        args << value unless value.nil?
+        args << false
+        new_call = s(:fcall, s(:ident, setting_method_name), s(:arg_paren, args))
+        new_call.line_range = (1..1)
+        new_call.traverse do |node|
+          node.full_source ||= ""
+        end
+        new_call.full_source = "#{setting_method_name}('#{name}'#{value.nil? ? "" : ", #{value.source}"})"
+        new_call
+      end
+
+      def process
+        return unless mattock_configurable?(namespace)
+
+        #filter further based on NS === Configurable...
+        name = extract_name(statement.parameters.first)
+
+        value = statement.parameters(false)[1]
+        if !value.nil? and value.type == :fcall and value.jump(:ident)[0] == "nested"
+          remapped = (value.parameters.first||[]).map do |assoc|
+            new_name =
+                append_name(statement.parameters[0], extract_name(assoc[0]))
+            synthetic_setting(new_name, assoc[1])
+          end
+          parser.process(remapped)
+          return
+        end
+
+        setting = YARD::CodeObjects::MethodObject.new(namespace, name) do |set|
+          unless value.nil?
+            set['default_value'] = statement.parameters(false)[1].source
+          end
+          set.signature = "def #{name}"
+          if statement.comments.to_s.empty?
+            set.docstring = "The value of setting #{name}"
+          else
+            set.docstring = statement.comments
+          end
+
+          set.dynamic = true
+        end
+
+        register setting
+        (namespace[:settings] ||= []) << setting
+      end
+    end
+
+    class SettingsHandler < SettingHandler
+      handles method_call(:settings)
+      namespace_only
+
+      def process
+        return unless mattock_configurable?(namespace)
+
+        remapped = statement.parameters(false).first.map do |assoc|
+          synthetic_setting(extract_name(assoc[0]), assoc[1])
+        end
+        parser.process(remapped)
+      end
+    end
+
+    class NilFieldsHandler < SettingHandler
+      handles method_call(:nil_field)
+      handles method_call(:nil_fields)
+      namespace_only
+
+      def a_nil
+        v = s(:kw, nil)
+        v.full_source = "nil"
+        v
+      end
+
+      def process
+        return unless mattock_configurable?(namespace)
+        remapped = statement.parameters(false).map do |name|
+          synthetic_setting(extract_name(name), a_nil)
+        end
+        parser.process(remapped)
+      end
+    end
+
+    class RuntimeRequiredFieldsHandler < SettingHandler
+      handles method_call(:runtime_required_field)
+      handles method_call(:runtime_required_fields)
+      namespace_only
+
+      def setting_method_name
+        "runtime_setting"
+      end
+
+      def process
+        return unless mattock_configurable?(namespace)
+        remapped = statement.parameters(false).map do |name|
+          synthetic_setting(extract_name(name))
+        end
+        parser.process(remapped)
+      end
+    end
+
+    class RequiredFieldsHandler < SettingHandler
+      handles method_call(:required_field)
+      handles method_call(:required_fields)
+      namespace_only
+
+      def process
+        return unless mattock_configurable?(namespace)
+        remapped = statement.parameters(false).map do |name|
+          synthetic_setting(extract_name(name))
+        end
+        parser.process(remapped)
+      end
+    end
+  end
+end

data/spec/configurable.rb

@@ -0,0 +1,270 @@
+require 'calibrate'
+
+describe Calibrate::Configurable do
+  class TestSuperStruct
+    include Calibrate::Configurable
+
+    setting(:three, 3)
+    required_field(:four)
+    required_field(:override)
+  end
+
+  class TestStruct < TestSuperStruct
+    settings(:one => 1, :two => nested(:a => "a"){ required_field(:b)} )
+    nil_field(:five)
+
+    def override
+      17
+    end
+  end
+
+  subject do
+    TestStruct.new.setup_defaults
+  end
+
+  it "should set defaults" do
+    expect(subject.one).to eq(1)
+    expect(subject.two.a).to eq("a")
+    expect(subject.three).to eq(3)
+    expect(subject.five).to be_nil
+  end
+
+  it "#to_hash" do
+    hash = subject.to_hash
+    expect(hash[:one]).to eq(1)
+    expect(hash[:two][:a]).to eq("a")
+  end
+
+  it "#from_hash" do
+    subject.from_hash({:one => 111, "two" => { :a => "aaa" }})
+
+    expect(subject.one).to eq(111)
+    expect(subject.two.a).to eq("aaa")
+  end
+
+  it "should complain about unset required fields" do
+    expect do
+      subject.check_required
+    end.to raise_error(Calibrate::RequiredFieldUnset)
+  end
+
+  it "should complain about unset nested required fields" do
+    subject.four = 4
+    expect do
+      subject.check_required
+    end.to raise_error(Calibrate::RequiredFieldUnset)
+  end
+
+  it "should not complain when required fields are set" do
+    subject.four = 4
+    subject.two.b = "b"
+    expect do
+      subject.check_required
+    end.to_not raise_error
+    expect(subject.override).to eq(17)
+  end
+
+  it "should inspect cleanly" do
+    expect(subject.inspect).to be_a(String)
+  end
+
+  describe "with DirectoryStructure" do
+    class DirectoryThing
+      include Calibrate::Configurable
+      include DirectoryStructure
+
+      dir(:ephemeral_mountpoint,
+          dir(:bundle_workdir, "bundle_workdir",
+              path(:bundle_manifest),
+              path(:credentials_archive, "aws-creds.tar.gz"),
+              dir(:credentials_dir, "aws-creds",
+                  path(:private_key_file, "pk.pem"),
+                  path(:certificate_file, "cert.pem")
+                 )
+             )
+         )
+
+      dir(:next_to_me, "rainbow", dir(:in_there, "a_place", path(:nearby, "a.file")))
+
+      path(:loose_path, "here")
+    end
+
+    describe "distinctness" do
+      let :one do
+        DirectoryThing.new.tap do |thing|
+          thing.setup_defaults
+        end
+      end
+
+      let :other do
+        DirectoryThing.new.tap do |thing|
+          thing.setup_defaults
+        end
+      end
+
+      it "should have same values" do
+        expect(one.bundle_workdir.relative_path).to eq(other.bundle_workdir.relative_path)
+      end
+
+      it "should have different actual objects" do
+        expect(one.bundle_workdir.relative_path).to_not equal other.bundle_workdir.relative_path
+        expect(one.bundle_workdir).to_not equal other.bundle_workdir
+      end
+
+    end
+
+    def subject
+      DirectoryThing.new.tap do |thing|
+        thing.setup_defaults
+      end
+    end
+
+    it "should complain about missing fields" do
+      expect do
+        subject.check_required
+      end.to raise_error(/Required field/)
+    end
+
+    it "should inspect cleanly" do
+      expect(subject.inspect).to be_a(String)
+    end
+
+    describe "with root path configured, but missing a relative path" do
+      def subject
+        DirectoryThing.new.tap do |thing|
+          thing.setup_defaults
+          thing.ephemeral_mountpoint.absolute_path = "/tmp"
+          thing.resolve_paths
+        end
+      end
+
+      it "should complain about missing fields" do
+        expect do
+          subject.check_required
+        end.to raise_error(/Required field/)
+      end
+    end
+
+    describe "with required paths configured" do
+      subject :thing do
+        DirectoryThing.new.tap do |thing|
+          thing.setup_defaults
+          thing.ephemeral_mountpoint.absolute_path = "/tmp"
+          thing.bundle_manifest.relative_path = "image.manifest.xml"
+          thing.resolve_paths
+        end
+      end
+
+      it "should not complain about required fields" do
+        expect do
+          subject.check_required
+        end.not_to raise_error
+      end
+
+      it{ expect(thing.nearby.absolute_path).to match(%r"rainbow/a_place/a.file$")}
+      it{ expect(thing.nearby.absolute_path).to match(%r"^#{subject.absolute_path}") }
+
+      it{ expect(thing.certificate_file.absolute_path).to eq("/tmp/bundle_workdir/aws-creds/cert.pem")}
+      it{ expect(thing.bundle_manifest.absolute_path).to eq("/tmp/bundle_workdir/image.manifest.xml") }
+      it{ expect(thing.credentials_dir.absolute_path).to eq("/tmp/bundle_workdir/aws-creds") }
+    end
+  end
+
+  describe "multiple instances" do
+    class MultiSource
+      include Calibrate::Configurable
+
+      setting :one, 1
+      setting :nest, nested{
+        setting :two, 2
+      }
+    end
+
+    let :first do
+      MultiSource.new.setup_defaults
+    end
+
+    let :second do
+      MultiSource.new.setup_defaults
+    end
+
+    before :each do
+      first.one = "one"
+      first.nest.two = "two"
+      second
+    end
+
+    it "should not have any validation errors" do
+      expect do
+        first.check_required
+        second.check_required
+      end.not_to raise_error
+    end
+
+    it "should accurately reflect settings" do
+      expect(first.one).to eq("one")
+      expect(second.one).to eq(1)
+
+      expect(first.nest.two).to eq("two")
+      expect(second.nest.two).to eq(2)
+    end
+  end
+
+  describe "copying settings" do
+    class LeftStruct
+      include Calibrate::Configurable
+
+      setting(:normal, "1")
+      setting(:nested, nested{
+        setting :value, "2"
+      })
+      setting(:no_copy, 2).isnt(:copiable)
+      setting(:no_proxy, 3).isnt(:proxiable)
+      setting(:no_nothing, 4).isnt(:copiable).isnt(:proxiable)
+      setting(:not_on_target, 5)
+    end
+
+    class RightStruct
+      include Calibrate::Configurable
+
+      required_fields(:normal, :nested, :no_copy, :no_proxy, :no_nothing)
+    end
+
+    let :left do
+      LeftStruct.new.setup_defaults
+    end
+
+    let :right do
+      RightStruct.new.setup_defaults
+    end
+
+    it "should make copies not references" do
+      left.copy_settings_to(right)
+      expect(right.normal).to eq(left.normal)
+      expect(right.normal).to_not equal(left.normal)
+      expect(right.nested.value).to eq(left.nested.value)
+      expect(right.nested).to_not equal(left.nested)
+      expect(right.nested.value).to_not equal left.nested.value
+    end
+
+    it "should not copy no_copy" do
+      left.copy_settings_to(right)
+      expect(right.field_unset?(:normal)).to eq(false)
+      expect(right.normal).to eq("1")
+      expect(right.field_unset?(:no_copy)).to eq(true)
+      expect(right.field_unset?(:no_proxy)).to eq(false)
+      expect(right.no_proxy).to eq(3)
+      expect(right.field_unset?(:no_nothing)).to eq(true)
+    end
+
+    it "should not proxy no_proxy" do
+      left.proxy_settings.to(right)
+      expect(right.field_unset?(:normal)).to eq(false)
+      expect(right.normal).to eq("1")
+      expect(right.field_unset?(:no_copy)).to eq(false)
+      expect(right.no_copy).to eq(2)
+      expect(right.field_unset?(:no_proxy)).to eq(true)
+      expect(right.field_unset?(:no_nothing)).to eq(true)
+    end
+  end
+end

data/spec_help/gem_test_suite.rb

@@ -0,0 +1,17 @@
+puts Dir::pwd
+require 'test/unit'
+begin
+  require 'spec'
+rescue LoadError
+  false
+end
+
+class RSpecTest < Test::Unit::TestCase
+  def test_that_rspec_is_available
+    assert_nothing_raised("\n\n *  RSpec isn't available - please run: gem install rspec  *\n\n"){ ::Spec }
+  end
+
+  def test_that_specs_pass
+    assert(system(*%w{spec -f e -p **/*.rb spec}),"\n\n *  Specs failed  *\n\n")
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: calibrate
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Judson Lester
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-08-06 00:00:00.000000000 Z
+dependencies: []
+description: |2
+    Add configurable settings to ruby object that can have defaults, be required, depend on one another.
+email:
+- nyarly@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/calibrate.rb
+- lib/calibrate/configurable.rb
+- lib/calibrate/configurable/class-methods.rb
+- lib/calibrate/configurable/directory-structure.rb
+- lib/calibrate/configurable/field-metadata.rb
+- lib/calibrate/configurable/field-processor.rb
+- lib/calibrate/configurable/instance-methods.rb
+- lib/calibrate/configurable/proxy-value.rb
+- lib/calibrate/yard-extensions.rb
+- spec/configurable.rb
+- spec_help/gem_test_suite.rb
+- spec_help/spec_helper.rb
+homepage: http://nyarly.github.com/calibrate
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--inline-source"
+- "--main"
+- doc/README
+- "--title"
+- calibrate-0.0.1 Documentation
+require_paths:
+- lib/
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: calibrate
+rubygems_version: 2.4.8
+signing_key: 
+specification_version: 4
+summary: Configuration fields for Ruby objects
+test_files:
+- spec_help/gem_test_suite.rb