gorillib-model 0.0.1

data/lib/gorillib/model/field.rb

@@ -0,0 +1,168 @@
+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(model, name, type, options={})
+        Validate.identifier!(name)
+        type_opts         = options.extract!(:blankish, :empty_product, :items, :keys, :of)
+        type_opts[:items] = type_opts.delete(:of) if type_opts.has_key?(:of)
+        #
+        @model            = model
+        @name             = name.to_sym
+        @type             = Gorillib::Factory.factory_for(type, type_opts)
+        default_visibilities = visibilities
+        @visibilities     = default_visibilities.merge( options.extract!(*default_visibilities.keys).compact )
+        @doc              = options.delete(:name){ "#{name} field" }
+        receive!(options)
+      end
+
+      # __________________________________________________________________________
+
+      # @return [String] the field name
+      def to_s
+        name.to_s
+      end
+
+      # @return [String] Human-readable presentation of the field definition
+      def inspect
+        args = [name.inspect, type.to_s, attributes.reject{|k,v| k =~ /^(name|type)$/}.inspect]
+        "field(#{args.join(",")})"
+      end
+      def inspect_compact
+        "field(#{name})"
+      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(model, name, type, 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.
+      #
+
+      field :position, Integer, :tester => true,       :doc => "Indicates this is a positional initialization arg -- you can pass it as a plain value in the given slot to #initialize"
+
+      # 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, position: 0, writer: false, doc: "The field name. Must start with `[A-Za-z_]` and subsequently contain only `[A-Za-z0-9_]` (required)"
+
+      field :type, Class,  position: 1,                doc: "Factory to generate field's values"
+
+      field :doc,  String,                             doc: "Field's description"
+
+      # remove the attr_reader method (needed for scaffolding), leaving the meta_module method to remain
+      remove_possible_method(:name)
+
+    end
+
+
+    class SimpleCollectionField < Gorillib::Model::Field
+      field :item_type,        Class, default: Whatever, doc: "Factory for collection items"
+      # field :collection_attrs, Hash,  default: Hash.new, doc: "Extra attributes to pass to the collection on creation -- eg. key_method"
+
+      def initialize(model, name, type, options={})
+        super
+        collection_type = self.type
+        item_type       = self.item_type
+        key_method      = options[:key_method] if options[:key_method]
+        raise "Please supply an item type for #{self.inspect} -- eg 'collection #{name.inspect}, of: FooClass'" unless item_type
+        self.default ||= ->{ collection_type.new(item_type: item_type, belongs_to: self, key_method: key_method) }
+      end
+
+      def inscribe_methods(model)
+        super
+        model.__send__(:define_collection_receiver, self)
+      end
+    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/lint.rb

@@ -0,0 +1,24 @@
+module Gorillib
+  module Model
+    #
+    # A set of guards for good behavior:
+    #
+    # * checks that fields given to read_attribute, write_attribute, etc are defined
+    #
+    module Lint
+      def read_attribute(field_name, *)  check_field(field_name) ; super ; end
+      def write_attribute(field_name, *) check_field(field_name) ; super ; end
+      def unset_attribute(field_name, *) check_field(field_name) ; super ; end
+      def attribute_set?(field_name, *)  check_field(field_name) ; super ; end
+
+    protected
+      # @return [true] if the field exists
+      # @raise [UnknownFieldError] if the field is missing
+      def check_field(field_name)
+        return true if self.class.has_field?(field_name)
+        raise UnknownFieldError, "unknown field: #{field_name} for #{self}"
+      end
+
+    end
+  end
+end

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/positional_fields.rb

@@ -0,0 +1,35 @@
+module Gorillib
+  module Model
+
+    #
+    # give each field the next position in order
+    #
+    # @example
+    #   class Foo
+    #     include Gorillib::Model
+    #     field :bob,    String               # not positional
+    #     field :zoe,    String, position: 0  # positional 0 (explicit)
+    #   end
+    #   class Subby < Foo
+    #     include Gorillib::Model::PositionalFields
+    #     field :wun, String                  # positional 1
+    #   end
+    #   Foo.field    :nope, String            # not positional
+    #   Subby.field  :toofer, String          # positional 2
+    #
+    # @note: make sure you're keeping positionals straight in super classes, or
+    # in anything added after this.
+    #
+    module PositionalFields
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        def field(*args)
+          options = args.extract_options!
+          super(*args, {position: positionals.count}.merge(options))
+        end
+      end
+
+    end
+  end
+end

data/lib/gorillib/model/schema_magic.rb

@@ -0,0 +1,163 @@
+module Gorillib
+  module Model
+
+    module ClassMethods
+
+      # Defines a new field
+      #
+      # For each field that is defined, a getter and setter will be added as
+      # an instance method to the model. An Field instance will be added to
+      # result of the fields class method.
+      #
+      # @example
+      #   field :height, Integer
+      #
+      # @param [Symbol] field_name             The field name. Must start with `[A-Za-z_]` and subsequently contain only `[A-Za-z0-9_]`
+      # @param [Class]  type                   The field's type (required)
+      # @option options [String] doc           Documentation string for the field (optional)
+      # @option options [Proc, Object] default Default value, or proc that instance can evaluate to find default value
+      #
+      # @return Gorillib::Model::Field
+      def field(field_name, type, options={})
+        options = options.symbolize_keys
+        field_type = options.delete(:field_type){ ::Gorillib::Model::Field }
+        fld = field_type.new(self, field_name, type, options)
+        @_own_fields[fld.name] = fld
+        _reset_descendant_fields
+        fld.send(:inscribe_methods, self)
+        fld
+      end
+
+      def collection(field_name, collection_type, options={})
+        options[:item_type] = options[:of] if options.has_key?(:of)
+        field(field_name, collection_type, {
+            field_type: ::Gorillib::Model::SimpleCollectionField}.merge(options))
+      end
+
+      # @return [{Symbol => Gorillib::Model::Field}]
+      def fields
+        return @_fields if defined?(@_fields)
+        @_fields = ancestors.reverse.inject({}){|acc, ancestor| acc.merge!(ancestor.try(:_own_fields) || {}) }
+      end
+
+      # @return [true, false] true if the field is defined on this class
+      def has_field?(field_name)
+        fields.has_key?(field_name)
+      end
+
+      # @return [Array<Symbol>] The attribute names
+      def field_names
+        @_field_names ||= fields.keys
+      end
+
+      def positionals
+        @_positionals ||= assemble_positionals
+      end
+
+      def assemble_positionals
+        positionals = fields.values.keep_if{|fld| fld.position? }.sort_by!{|fld| fld.position }
+        return [] if positionals.empty?
+        if (positionals.map(&:position) != (0..positionals.length-1).to_a) then raise ConflictingPositionError, "field positions #{positionals.map(&:position).join(",")} for #{positionals.map(&:name).join(",")} aren't in strict minimal order"  ; end
+        positionals.map!(&:name)
+      end
+
+      # turn model constructor args (`*positional_args, {attrs}`) into a combined
+      # attrs hash. positional_args are mapped to the set of attribute names in
+      # order -- by default, the class' field names.
+      #
+      # Notes:
+      #
+      # * Positional args always clobber elements of the attribute hash.
+      # * Nil positional args are treated as present-and-nil (this might change).
+      # * Raises an error if positional args
+      #
+      # @param [Array[Symbol]] args list of attributes, in order, to map.
+      #
+      # @return [Hash] a combined, reconciled hash of attributes to set
+      def attrs_hash_from_args(args)
+        attrs = args.extract_options!
+        if args.present?
+          ArgumentError.check_arity!(args, 0..positionals.length){ "extracting args #{args} for #{self}" }
+          positionals_to_map = positionals[0..(args.length-1)]
+          attrs = attrs.merge(Hash[positionals_to_map.zip(args)])
+        end
+        attrs
+      end
+
+    protected
+
+      attr_reader :_own_fields
+
+      # Ensure that classes inherit all their parents' fields, even if fields
+      # are added after the child class is defined.
+      def _reset_descendant_fields
+        ObjectSpace.each_object(::Class) do |klass|
+          klass.__send__(:remove_instance_variable, '@_fields')      if (klass <= self) && klass.instance_variable_defined?('@_fields')
+          klass.__send__(:remove_instance_variable, '@_field_names') if (klass <= self) && klass.instance_variable_defined?('@_field_names')
+          klass.__send__(:remove_instance_variable, '@_positionals') if (klass <= self) && klass.instance_variable_defined?('@_positionals')
+        end
+      end
+
+      # define the reader method `#foo` for a field named `:foo`
+      def define_attribute_reader(field_name, field_type, visibility)
+        define_meta_module_method(field_name, visibility) do
+          begin
+            read_attribute(field_name)
+          rescue StandardError => err ; err.polish("#{self.class}.#{field_name}") rescue nil ; raise ; end
+        end
+      end
+
+      # define the writer method `#foo=` for a field named `:foo`
+      def define_attribute_writer(field_name, field_type, visibility)
+        define_meta_module_method("#{field_name}=", visibility) do |val|
+          write_attribute(field_name, val)
+        end
+      end
+
+      # define the present method `#foo?` for a field named `:foo`
+      def define_attribute_tester(field_name, field_type, visibility)
+        field = fields[field_name]
+        define_meta_module_method("#{field_name}?", visibility) do
+          attribute_set?(field_name) || field.has_default?
+        end
+      end
+
+      def define_attribute_receiver(field_name, field_type, visibility)
+        # @param  [Object] val the raw value to type-convert and adopt
+        # @return [Object] the attribute's new value
+        define_meta_module_method("receive_#{field_name}", visibility) do |val|
+          begin
+            val = field_type.receive(val)
+            write_attribute(field_name, val)
+          rescue StandardError => err ; err.polish("#{self.class}.#{field_name} type #{type} on #{val}") rescue nil ; raise ; end
+        end
+      end
+
+      #
+      # Collection receiver --
+      #
+      def define_collection_receiver(field)
+        collection_field_name = field.name; collection_type = field.type
+        # @param  [Array[Object],Hash[Object]] the collection to merge
+        # @return [Gorillib::Collection] the updated collection
+        define_meta_module_method("receive_#{collection_field_name}", true) do |coll, &block|
+          begin
+            if collection_type.native?(coll)
+              write_attribute(collection_field_name, coll)
+            else
+              read_attribute(collection_field_name).receive!(coll, &block)
+            end
+          rescue StandardError => err ; err.polish("#{self.class} #{collection_field_name} collection on #{args}'") rescue nil ; raise ; end
+        end
+      end
+
+      def inherited(base)
+        base.instance_eval do
+          self.meta_module
+          @_own_fields ||= {}
+        end
+        super
+      end
+    end
+  end
+end

data/lib/gorillib/model/serialization/csv.rb

@@ -0,0 +1,60 @@
+require 'csv'
+
+module Gorillib
+  module Model
+
+    module LoadFromCsv
+      extend ActiveSupport::Concern
+      included do |base|
+        # Options that will be passed to CSV. Be careful to modify with assignment (`+=`) and not in-place (`<<`)
+        base.class_attribute :csv_options
+        base.csv_options = Hash.new
+      end
+
+      module ClassMethods
+
+        # Iterate a block over each line of a CSV file
+        #
+        # @raise [Gorillib::Model::RawDataMismatchError] if a line has too many or too few fields
+        # @yield an object instantiated from each line in the file.
+        def each_in_csv(filename, options={})
+          filename = Pathname.new(filename)
+          options = csv_options.merge(options)
+          #
+          pop_headers = options.delete(:pop_headers)
+          num_fields  = options.delete(:num_fields){ (fields.length .. fields.length) }
+          raise ArgumentError, "The :headers option to CSV changes its internal behavior; use 'pop_headers: true' to ignore the first line" if options[:headers]
+          #
+          CSV.open(filename, options) do |csv_file|
+            csv_file.shift if pop_headers
+            csv_file.each do |tuple|
+              next if tuple.empty?
+              unless num_fields.include?(tuple.length) then raise Gorillib::Model::RawDataMismatchError, "yark, spurious fields: #{tuple.inspect}" ; end
+              yield from_tuple(*tuple)
+            end
+            nil
+          end
+        end
+
+        # With a block, calls block on each object in turn (and returns nil)
+        #
+        # With no block, accumulates all the instances into the array it
+        # returns. As opposed to the with-a-block case, the memory footprint of
+        # this increases as the filesize does, so use caution with large files.
+        #
+        # @return with a block, returns nil; with no block, an array of this class' instances
+        def load_csv(*args)
+          if block_given?
+            each_in_csv(*args, &Proc.new)
+          else
+            objs = []
+            each_in_csv(*args){|obj| objs << obj }
+            objs
+          end
+        end
+
+      end
+    end
+
+  end
+end

data/lib/gorillib/model/serialization/json.rb

@@ -0,0 +1,44 @@
+require 'multi_json'
+
+module Gorillib
+  module Model
+
+    module LoadFromJson
+      extend  ActiveSupport::Concern
+      include LoadLines
+
+      module ClassMethods
+
+        # Iterate a block over each line of a file having JSON records, one per
+        # line, in a big stack
+        #
+        # @yield an object instantiated from each line in the file.
+        def _each_from_json(filename, options={})
+          _each_raw_line(filename, options) do |line|
+            hsh = MultiJson.load(line)
+            yield receive(hsh)
+          end
+        end
+
+        # With a block, calls block on each object in turn (and returns nil)
+        #
+        # With no block, accumulates all the instances into the array it
+        # returns. As opposed to the with-a-block case, the memory footprint of
+        # this increases as the filesize does, so use caution with large files.
+        #
+        # @return with a block, returns nil; with no block, an array of this class' instances
+        def load_json(*args)
+          if block_given?
+            _each_from_json(*args, &Proc.new)
+          else
+            objs = []
+            _each_from_json(*args){|obj| objs << obj }
+            objs
+          end
+        end
+
+      end
+    end
+
+  end
+end

data/lib/gorillib/model/serialization/lines.rb

@@ -0,0 +1,30 @@
+module Gorillib
+  module Model
+
+    module LoadLines
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+
+        # Iterate a block over each line of a file
+        # @yield each line in the file.
+        def _each_raw_line(filename, options={})
+          filename = Pathname.new(filename)
+          #
+          pop_headers = options.delete(:pop_headers)
+          #
+          File.open(filename) do |file|
+            file.readline if pop_headers
+            file.each do |line|
+              line.chomp! ; next if line.empty?
+              yield line
+            end
+            nil
+          end
+        end
+
+      end
+    end
+
+  end
+end

data/lib/gorillib/model/serialization/to_wire.rb

@@ -0,0 +1,54 @@
+module Gorillib
+
+  module Hashlike
+    module Serialization
+      #
+      # Returns a hash with each key set to its associated value
+      #
+      # @example
+      #    my_hshlike = MyHashlike.new
+      #    my_hshlike[:a] = 100; my_hshlike[:b] = 200
+      #    my_hshlike.to_hash # => { :a => 100, :b => 200 }
+      #
+      # @return [Hash] a new Hash instance, with each key set to its associated value.
+      #
+      def to_wire(options={})
+        {}.tap do |hsh|
+          each do |attr,val|
+            hsh[attr] =
+              case
+              when val.respond_to?(:to_wire) then val.to_wire(options)
+              when val.respond_to?(:to_hash) then val.to_hash
+              else val ; end
+          end
+        end
+      end
+    end
+  end
+end
+
+module Gorillib::Hashlike
+  include ::Gorillib::Hashlike::Serialization
+end
+
+class ::Array
+  def to_wire(options={})
+    map{|item| item.respond_to?(:to_wire) ? item.to_wire : item }
+  end
+end
+
+class ::Hash
+  include ::Gorillib::Hashlike::Serialization
+end
+
+class ::Time
+  def to_wire(options={})
+    self.iso8601
+  end
+end
+
+class ::NilClass
+  def to_wire(options={})
+    nil
+  end
+end

data/lib/gorillib/model/serialization/tsv.rb

@@ -0,0 +1,53 @@
+module Gorillib
+  module Model
+
+    module LoadFromTsv
+      extend  ActiveSupport::Concern
+      include LoadLines
+
+      included do |base|
+        # Options that will be passed to CSV. Be careful to modify with assignment (`+=`) and not in-place (`<<`)
+        base.class_attribute :tsv_options
+        base.tsv_options = Hash.new
+      end
+
+      module ClassMethods
+
+        # Iterate a block over each line of a TSV file
+        #
+        # @raise [Gorillib::Model::RawDataMismatchError] if a line has too many or too few fields
+        # @yield an object instantiated from each line in the file.
+        def _each_from_tsv(filename, options={})
+          options = tsv_options.merge(options)
+          num_fields  = options.delete(:num_fields){ (fields.length .. fields.length) }
+          max_fields  = num_fields.max # need to make sure "1\t2\t\t\t" becomes ["1","2","","",""]
+          #
+          _each_raw_line(filename, options) do |line|
+            tuple = line.split("\t", max_fields)
+            unless num_fields.include?(tuple.length) then raise Gorillib::Model::RawDataMismatchError, "yark, spurious fields: #{tuple.inspect}" ; end
+            yield from_tuple(*tuple)
+          end
+        end
+
+        # With a block, calls block on each object in turn (and returns nil)
+        #
+        # With no block, accumulates all the instances into the array it
+        # returns. As opposed to the with-a-block case, the memory footprint of
+        # this increases as the filesize does, so use caution with large files.
+        #
+        # @return with a block, returns nil; with no block, an array of this class' instances
+        def load_tsv(*args)
+          if block_given?
+            _each_from_tsv(*args, &Proc.new)
+          else
+            objs = []
+            _each_from_tsv(*args){|obj| objs << obj }
+            objs
+          end
+        end
+
+      end
+    end
+
+  end
+end