gorillib 0.1.11 → 0.4.0pre

data/lib/gorillib/model/factories.rb

@@ -0,0 +1,372 @@
+require 'pathname'
+require 'gorillib/type/extended'
+
+def Gorillib::Factory(*args)
+  ::Gorillib::Factory.receive(*args)
+end
+
+module Gorillib
+
+  module Factory
+    class FactoryMismatchError < ArgumentError ; end
+
+    def self.receive(type)
+      case
+      when type.is_a?(Proc) || type.is_a?(Method) then return Gorillib::Factory::ApplyProcFactory.new(type)
+      when type.respond_to?(:receive)             then return type
+      when factories.include?(type)               then return factories[type]
+      when type.is_a?(String)                     then
+        return Gorillib::Inflector.constantize(Gorillib::Inflector.camelize(type.gsub(/\./, '/')))
+      else raise ArgumentError, "Don't know which factory makes a #{type}"
+      end
+    end
+
+    private
+    def self.factories
+      @factories ||= Gorillib::Collection.new.tap{|f| f.key_method = :name }
+    end
+    public
+
+    def self.register_factory(factory, *typenames)
+      if typenames.blank?
+        typenames = [factory.typename, factory.product]
+      end
+      typenames.each{|typename| factories[typename] = factory }
+    end
+
+    class BaseFactory
+      # [Class] The type of objects produced by this factory
+      class_attribute :product
+
+      # [Array<Symbol>] methods that can be redefined by passing a block to an
+      # instance No not add to your superclass' value in-place; instead, use
+      # `self.redefinable_methods += [...]`.
+      # @see #redefine
+      class_attribute :redefinable_methods, :instance_writer => false
+      self.redefinable_methods = Set.new([:blankish?, :convert])
+
+      # [Array<Object>] objects considered to be equivalent to `nil`
+      class_attribute :blankish_vals
+      self.blankish_vals = Set.new([ nil, "" ]) # note: [] {} and false are NOT blankish by default
+
+      def initialize(options={})
+        @product       = options.delete(:product)       if options.has_key?(:product)
+        @blankish_vals = options.delete(:blankish_vals) if options.has_key?(:blankish_vals)
+        options.extract!(*redefinable_methods).each do |meth, value_or_block|
+          redefine(meth, value_or_block)
+        end
+        warn "Unknown options #{options.keys}" unless options.empty?
+      end
+
+      def self.typename
+        Gorillib::Inflector.underscore(product.name).to_sym
+      end
+      def typename ; self.class.typename ; end
+
+      def self.receive(*args, &block)
+        self.new.receive(*args, &block)
+      end
+
+      # A `native` object does not need any transformation; it is accepted directly.
+      # By default, an object is native if it `is_a?(product)`
+      #
+      # @param   [Object]      obj the object to convert and receive
+      # @return [true, false] true if the item does not need conversion
+      def native?(obj)
+        obj.is_a?(product)
+      end
+      def self.native?(obj) self.new.native?(obj) ; end
+
+      # A `blankish` object should be converted to `nil`, not a value
+      #
+      # @param   [Object]      obj the object to convert and receive
+      # @return [true, false] true if the item is equivalent to a nil value
+      def blankish?(obj)
+        blankish_vals.include?(obj)
+      end
+      def self.blankish?(obj) self.new.blankish?(obj) ; end
+
+      def redefine(meth, *args, &block)
+        raise ArgumentError, "Cannot redefine #{meth} -- only #{redefinable_methods.inspect} are redefinable" unless redefinable_methods.include?(meth)
+        if args.present?
+          val = args.first
+          case
+          when block_given? then raise ArgumentError, "Pass a block or a value, not both"
+          when val.is_a?(Proc) || val.is_a?(Method) then block = val
+          else block = ->(*){ val.try_dup }
+          end
+        end
+        define_singleton_method(meth, &block)
+        self
+      end
+
+    protected
+
+      # Raises a FactoryMismatchError.
+      def mismatched!(obj, message=nil, *args)
+        message ||= "item cannot be converted to #{product}"
+        message <<  (" got #{obj.inspect}" rescue ' (and is uninspectable)')
+        raise FactoryMismatchError, message, *args
+      end
+
+      def self.register_factory!(*args)
+        Gorillib::Factory.register_factory(self, *args)
+      end
+    end
+
+    class ConvertingFactory < BaseFactory
+      def receive(obj)
+        return nil  if blankish?(obj)
+        return obj  if native?(obj)
+        convert(obj)
+      rescue NoMethodError, TypeError, RangeError => err
+        mismatched!(obj, err.message, err.backtrace)
+      end
+    protected
+      # Convert a receivable object to the factory's product type. This method
+      # should convert an object to `native?` form or die trying; any
+      # polymorphism (such as converting an empty string to nil) happens in
+      # other methods called by `receive`.
+      #
+      # @param [Object] obj the object to convert.
+      def convert(obj)
+        obj.dup
+      end
+    end
+
+    #
+    # A NonConvertingFactory accepts objects that are *already* native, and
+    # throws a mismatch error for anything else.
+    #
+    # @example
+    #   ff = Gorillib::Factory::NonConvertingFactory.new(:product => String, :blankish_vals => [nil])
+    #   ff.receive(nil)    #=> nil
+    #   ff.receive("bob")  #=> "bob"
+    #   ff.receive(:bob)   #=> Gorillib::Factory::FactoryMismatchError: must be an instance of String, got 3
+    #
+    class NonConvertingFactory < BaseFactory
+      self.blankish_vals = [nil]
+
+      def receive(obj)
+        return nil  if blankish?(obj)
+        return obj  if native?(obj)
+        mismatched!(obj, "must be an instance of #{product},")
+      rescue NoMethodError => err
+        mismatched!(obj, err.message, err.backtrace)
+      end
+    end
+
+    class IdenticalFactory < BaseFactory
+      self.redefinable_methods = []
+      self.blankish_vals       = []
+      def native?(obj)   true  ; end
+      def blankish?(obj) false ; end
+      def receive(obj)
+        obj
+      end
+      register_factory!(:identical, :whatever)
+    end
+    ::Whatever = IdenticalFactory unless defined?(Whatever)
+
+    # __________________________________________________________________________
+    #
+    #  Concrete Factories
+    # __________________________________________________________________________
+
+    class StringFactory < ConvertingFactory
+      self.product = String
+      self.blankish_vals -= [""]
+      def native?(obj)      obj.respond_to?(:to_str)  end
+      def convert(obj)      obj.to_s                  end
+      register_factory!
+    end
+
+    class GuidFactory      < StringFactory ; self.product = ::Guid      ; register_factory! ; end
+    class HostnameFactory  < StringFactory ; self.product = ::Hostname  ; register_factory! ; end
+    class IpAddressFactory < StringFactory ; self.product = ::IpAddress ; register_factory! ; end
+
+    class BinaryFactory < StringFactory
+      def convert(obj)
+        super.force_encoding("BINARY")
+      end
+      register_factory!(:binary)
+    end
+
+    class PathnameFactory  < ConvertingFactory
+      self.product = ::Pathname
+      def convert(obj)      Pathname.new(obj)         end
+      register_factory!
+    end
+
+    class SymbolFactory < ConvertingFactory
+      self.product = Symbol
+      def convert(obj)      obj.to_sym                end
+      register_factory!
+    end
+
+    class RegexpFactory < ConvertingFactory
+      self.product = Regexp
+      def convert(obj)      Regexp.new(obj)           end
+      register_factory!
+    end
+
+    class IntegerFactory < ConvertingFactory
+      self.product = Integer
+      def convert(obj)      obj.to_i                  end
+      register_factory!(:int, :integer, Integer)
+    end
+    class BignumFactory < IntegerFactory
+      self.product = Bignum
+      register_factory!
+    end
+    class FloatFactory < ConvertingFactory
+      self.product = Float
+      def convert(obj)      obj.to_f                  end
+      register_factory!
+    end
+    class ComplexFactory < ConvertingFactory
+      self.product = Complex
+      def convert(obj)      obj.to_c                  end
+      register_factory!
+    end
+    class RationalFactory < ConvertingFactory
+      self.product = Rational
+      def convert(obj)      obj.to_r                  end
+      register_factory!
+    end
+
+    class TimeFactory < ConvertingFactory
+      self.product = Time
+      def convert(obj)
+        case obj
+        when String
+          Time.parse(obj).utc
+        when Numeric
+          Time.at(obj).utc
+        end
+      rescue ArgumentError => err
+        warn "Cannot parse time #{obj}: #{err}"
+        return nil
+      end
+      register_factory!
+    end
+
+    # __________________________________________________________________________
+
+    class ClassFactory  < NonConvertingFactory ; self.product = Class      ; register_factory! ; end
+    class ModuleFactory < NonConvertingFactory ; self.product = Module     ; register_factory! ; end
+    class TrueFactory   < NonConvertingFactory ; self.product = TrueClass  ; register_factory!(:true, TrueClass) ; end
+    class FalseFactory  < NonConvertingFactory ; self.product = FalseClass ; register_factory!(:false, FalseClass) ; end
+
+    class ExceptionFactory < NonConvertingFactory ; self.product = Exception ; register_factory!(:exception, Exception) ; end
+
+    class NilFactory    < NonConvertingFactory
+      self.product       = NilClass
+      self.blankish_vals = []
+      register_factory!(:nil, NilClass)
+    end
+
+    class BooleanFactory < ConvertingFactory
+      self.product       = [TrueClass, FalseClass]
+      self.blankish_vals = [nil]
+      def native?(obj)     obj.equal?(true) || obj.equal?(false) ; end
+      def convert(obj)     (obj.to_s == "false") ? false : true ; end
+      register_factory!(:boolean)
+      def self.typename() :boolean ; end
+    end
+
+    #
+    #
+    #
+
+    class EnumerableFactory < ConvertingFactory
+      # [#receive] factory for converting items
+      attr_reader :items_factory
+      self.redefinable_methods += [:empty_product]
+      self.blankish_vals = Set.new([ nil ])
+
+      def initialize(options={})
+        @items_factory = Gorillib::Factory.receive( options.delete(:items){ IdenticalFactory.new } )
+        super(options)
+      end
+
+      def native?(obj)
+        false
+      end
+
+      def empty_product
+        product.new
+      end
+
+      def convert(obj)
+        clxn = empty_product
+        obj.each do |val|
+          clxn << items_factory.receive(val)
+        end
+        clxn
+      end
+    end
+
+    class ArrayFactory < EnumerableFactory
+      self.product = Array
+      register_factory!
+    end
+
+    class SetFactory < EnumerableFactory
+      self.product = Set
+      register_factory!
+    end
+
+    class HashFactory < EnumerableFactory
+      # [#receive] factory for converting keys
+      attr_reader :keys_factory
+      self.product = Hash
+
+      def initialize(options={})
+        @keys_factory = Gorillib::Factory( options.delete(:keys){ Whatever.new } )
+        super(options)
+      end
+
+      def convert(obj)
+        hsh = empty_product
+        obj.each_pair do |key, val|
+          hsh[keys_factory.receive(key)] = items_factory.receive(val)
+        end
+        hsh
+      end
+      register_factory!
+    end
+
+    class RangeFactory < NonConvertingFactory
+      self.product       = Range
+      self.blankish_vals = [ nil, [] ]
+      register_factory!
+    end
+
+    # __________________________________________________________________________
+
+    class ApplyProcFactory < ConvertingFactory
+      attr_reader :callable
+      self.blankish_vals = Set.new([nil])
+
+      def initialize(callable=nil, options={}, &block)
+        if block_given?
+          raise ArgumentError, "Pass a block or a value, not both" unless callable.nil?
+          callable = block
+        end
+        @callable = callable
+        super(options)
+      end
+      def native?(val)
+        false
+      end
+      def convert(obj)
+        callable.call(obj)
+      end
+      register_factory!(:proc)
+    end
+
+
+  end
+
+end

data/lib/gorillib/model/field.rb

@@ -0,0 +1,146 @@
+module Gorillib
+  module Model
+
+    # Represents a field for reflection
+    #
+    # @example Usage
+    #   Gorillib::Model::Field.new(:name => 'problems', type => Integer, :doc => 'Count of problems')
+    #
+    #
+    class Field
+      include Gorillib::Model
+      remove_possible_method(:type)
+
+      # [Gorillib::Model] Model owning this field
+      attr_reader :model
+
+      # [Hash] all options passed to the field not recognized by one of its own current fields
+      attr_reader :extra_attributes
+
+      # Note: `Gorillib::Model::Field` is assembled in two pieces, so that it
+      # can behave as a model itself. Defining `name` here, along with some
+      # fudge in #initialize, provides enough functionality to bootstrap.
+      # The fields are then defined properly at the end of the file.
+
+      attr_reader :name
+      attr_reader :type
+
+      class_attribute :visibilities, :instance_writer => false
+      self.visibilities = { :reader => :public, :writer => :public, :receiver => :public, :tester => false }
+
+
+      # @param [#to_sym]                name    Field name
+      # @param [#receive]               type    Factory for field values. To accept any object as-is, specify `Object` as the type.
+      # @param [Gorillib::Model]       model   Field's owner
+      # @param [Hash{Symbol => Object}] options Extended attributes
+      # @option options [String] doc Description of the field's purpose
+      # @option options [true, false, :public, :protected, :private] :reader   Visibility for the reader (`#foo`) method; `false` means don't create one.
+      # @option options [true, false, :public, :protected, :private] :writer   Visibility for the writer (`#foo=`) method; `false` means don't create one.
+      # @option options [true, false, :public, :protected, :private] :receiver Visibility for the receiver (`#receive_foo`) method; `false` means don't create one.
+      #
+      def initialize(name, type, model, options={})
+        Validate.identifier!(name)
+        @model            = model
+        @name             = name.to_sym
+        @type             = self.factory_for(type)
+        default_visabilities = visibilities
+        @visibilities     = default_visabilities.merge( options.extract!(*default_visabilities.keys) )
+        @doc              = options.delete(:name){ "#{name} field" }
+        receive!(options)
+      end
+
+      # __________________________________________________________________________
+
+      # @return [String] the field name
+      def to_s
+        name.to_s
+      end
+
+      def factory_for(type)
+        Gorillib::Factory(type)
+      end
+
+      # @return [String] Human-readable presentation of the field definition
+      def inspect
+        args = [name.inspect, type.to_s]
+        "field(#{args.join(", ")})"
+      end
+
+      def to_hash
+        attributes.merge!(@visibility).merge!(@extra_attributes)
+      end
+
+      def ==(val)
+        super && (val.extra_attributes == self.extra_attributes) && (val.model == self.model)
+      end
+
+      def self.receive(hsh)
+        name  = hsh.fetch(:name)
+        type  = hsh.fetch(:type)
+        model = hsh.fetch(:model)
+        new(name, type, model, hsh)
+      end
+
+      #
+      # returns the visibility
+      #
+      # @example reader is protected, no writer:
+      #   Foo.field :granuloxity, :reader => :protected, :writer => false
+      #
+      def visibility(meth_type)
+        Validate.included_in!("method type", meth_type, @visibilities.keys)
+        @visibilities[meth_type]
+      end
+
+    protected
+
+      #
+      #
+      #
+      def inscribe_methods(model)
+        model.__send__(:define_attribute_reader,   self.name, self.type, visibility(:reader))
+        model.__send__(:define_attribute_writer,   self.name, self.type, visibility(:writer))
+        model.__send__(:define_attribute_tester,   self.name, self.type, visibility(:tester))
+        model.__send__(:define_attribute_receiver, self.name, self.type, visibility(:receiver))
+      end
+
+    public
+
+      #
+      # Now we can construct the actual fields.
+      #
+
+      # Name of this field. Must start with `[A-Za-z_]` and subsequently contain only `[A-Za-z0-9_]` (required)
+      # @macro [attach] field
+      #   @attribute $1
+      #   @return [$2] the $1 field $*
+      field :name, String, :writer => false, :doc => "The field name. Must start with `[A-Za-z_]` and subsequently contain only `[A-Za-z0-9_]` (required)"
+
+      # Factory for the field's values
+      field :type, Class
+
+      # Field's description
+      field :doc, String
+
+      # remove the attr_reader method (needed for scaffolding), leaving the meta_module method to remain
+      remove_possible_method(:name)
+
+    end
+  end
+end
+
+# * aliases
+# * order
+# * dirty
+# * lazy
+# * mass assignable
+# * identifier / index
+# * hook
+# * validates / required
+#   - presence     => true
+#   - uniqueness   => true
+#   - numericality => true             # also :==, :>, :>=, :<, :<=, :odd?, :even?, :equal_to, :less_than, etc
+#   - length       => { :<  => 7 }     # also :==, :>=, :<=, :is, :minimum, :maximum
+#   - format       => { :with => /.*/ }
+#   - inclusion    => { :in => [1,2,3] }
+#   - exclusion    => { :in => [1,2,3] }

data/lib/gorillib/model/named_schema.rb

@@ -0,0 +1,53 @@
+module Gorillib
+  module Model
+    module NamedSchema
+
+    protected
+
+      #
+      # Returns the meta_module -- a module extending the type, on which all the
+      # model methods are inscribed. This allows you to override the model methods
+      # and call +super()+ to get the generic behavior.
+      #
+      # The meta_module is named for the including class, but with 'Meta::'
+      # prepended and 'Type' appended -- so Geo::Place has meta_module
+      # "Meta::Geo::PlaceType"
+      #
+      def meta_module
+        return @_meta_module if defined?(@_meta_module)
+        if self.name
+          @_meta_module = ::Gorillib::Model::NamedSchema.get_nested_module("Meta::#{self.name}Type")
+        else
+          @_meta_module = Module.new
+        end
+        self.class_eval{ include(@_meta_module) }
+        @_meta_module
+      end
+
+      def define_meta_module_method(method_name, visibility=:public, &block)
+        if (visibility == false) then return               ; end
+        if (visibility == true)  then visibility = :public ; end
+        Validate.included_in!("visibility", visibility, [:public, :private, :protected])
+        meta_module.module_eval{ define_method(method_name, &block) }
+        meta_module.module_eval "#{visibility} :#{method_name}", __FILE__, __LINE__
+      end
+
+      # Returns a module for the given names, rooted at Object (so
+      # implicity with '::').
+      # @example
+      #   get_nested_module(["This", "That", "TheOther"])
+      #   # This::That::TheOther
+      def self.get_nested_module(name)
+        name.split('::').inject(Object) do |parent_module, module_name|
+          # inherit = false makes these methods be scoped to parent_module instead of universally
+          if parent_module.const_defined?(module_name, false)
+            parent_module.const_get(module_name, false)
+          else
+            parent_module.const_set(module_name.to_sym, Module.new)
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/gorillib/model/record_schema.rb

@@ -0,0 +1,9 @@
+module Gorillib
+  module Model
+    class RecordSchema
+      field :name, String
+      field :doc,  String
+      field :type, Factory
+    end
+  end
+end

data/lib/gorillib/model/serialization.rb

@@ -0,0 +1,23 @@
+module Gorillib
+  module Model
+
+    def to_wire(options={})
+      attributes.merge(:_type => self.class.typename).inject({}) do |acc, (key,attr)|
+        acc[key] = attr.respond_to?(:to_wire) ? attr.to_wire(options) : attr
+        acc
+      end
+    end
+
+    def to_json(options={})
+      MultiJson.dump(to_wire(options), options)
+    end
+    alias_method(:as_json, :to_wire)
+
+    module ClassMethods
+      def from_tuple(*vals)
+        receive Hash[field_names[0..vals.length].zip(vals)]
+      end
+    end
+
+  end
+end

data/lib/gorillib/model/validate.rb

@@ -0,0 +1,22 @@
+module Gorillib
+  module Model
+    module Validate
+      module_function
+
+      VALID_NAME_RE = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+      def identifier!(name)
+        raise TypeError,     "can't convert #{name.class} into Symbol", caller unless name.respond_to? :to_sym
+        raise ArgumentError, "Name must start with [A-Za-z_] and subsequently contain only [A-Za-z0-9_]", caller unless name =~ VALID_NAME_RE
+      end
+
+      def hashlike!(desc, val)
+        return true if val.respond_to?(:[]) && val.respond_to?(:has_key?)
+        raise ArgumentError, "#{desc} should be something that behaves like a hash: #{val.inspect}", caller
+      end
+
+      def included_in!(desc, val, colxn)
+        raise ArgumentError, "#{desc} must be one of #{colxn.inspect}: got #{val.inspect}", caller unless colxn.include?(val)
+      end
+    end
+  end
+end

data/lib/gorillib/model.rb

@@ -0,0 +1,23 @@
+require 'set'
+#
+require 'gorillib/object/blank'
+require 'gorillib/object/try'
+require 'gorillib/object/try_dup'
+require 'gorillib/array/extract_options'
+require 'gorillib/hash/keys'
+require 'gorillib/hash/slice'
+require 'gorillib/string/inflector'
+require 'gorillib/exception/raisers'
+require 'gorillib/metaprogramming/concern'
+require 'gorillib/metaprogramming/class_attribute'
+#
+require 'gorillib/collection'
+require 'gorillib/type/extended'
+require 'gorillib/model/factories'
+require 'gorillib/model/named_schema'
+require 'gorillib/model/validate'
+require 'gorillib/model/errors'
+#
+require 'gorillib/model/base'
+require 'gorillib/model/field'
+require 'gorillib/model/defaults'