mattock 0.4.1 → 0.5.0

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

@@ -0,0 +1,208 @@
+module Mattock
+  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
+          value = 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.default_value
+          if Module === value and Configurable > value
+            value = value.new
+            value.class.set_defaults_on(value)
+          end
+          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 included(mod)
+        mod.extend ClassMethods
+      end
+    end
+
+    extend ClassMethods
+  end
+end

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

@@ -0,0 +1,147 @@
+module Mattock
+  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
+
+        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 inspect
+          "<path: #{
+            if unset?(:absolute_path)
+              "<<?>>/#{relative_path.inspect}"
+            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)
+
+          root_paths << parent_field
+          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|
+            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/mattock/configurable/field-metadata.rb

@@ -0,0 +1,125 @@
+module Mattock
+  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 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