taxonomite 0.1.0 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 23b3b1dfb04a5bba6964518d64495f5ce765a401
-  data.tar.gz: 8b97678d947fb2f0fea89b2298885bad97e01f61
+  metadata.gz: 3e1a9457110c23a02d4d8f75753b972457abb2d1
+  data.tar.gz: dc4cda724409ded545dd499b0ef7d70676b7fa88
 SHA512:
-  metadata.gz: ab087ff6284c6b3208d6dc1be6b64aa6cd47c0464f5dbc9cd3abc4074f8fdfdd7c0685118350b98393bbb5f42534b7a042d47211927b778a36cf4b33427dfc34
-  data.tar.gz: 263d4a6ca733fad72e9074e6c852f4d36da4a00324c85523671ffa8a246c97c3982b3a193f96c01a40a40a9031d79dc5f1407040f0a4f8c7ecba740d6c8883ce
+  metadata.gz: 0e680ba41a6ac6e7ea6e5bda6bb0bfc311779203951c7e915b8b6194d5d6f45b222e09aa7b4cd71d51c678143a6c287f5aed5c70f8337e2d3f2b50f2236d528b
+  data.tar.gz: b09f729c8a5b7addf448dffa31f96f462f87231bc13288aab14ae6be210f96b65f0a3fdb5c6cbe223d2197f629eec21c5f2ac9d1957f7b822701a3b7fc27e218

data/lib/taxonomite/exceptions.rb

@@ -1,7 +1,46 @@
 # taxonomite/exceptions.rb
 
 module Taxonomite
-  class InvalidChild < RuntimeError; end
-  class InvalidParent < RuntimeError; end
-  class CircularRelation < RuntimeError; end
+
+  module CreateClassMethod
+    def create(parent, child)
+      new("", parent, child)
+    end
+  end
+
+  class InvalidChild < RuntimeError
+    extend CreateClassMethod
+
+    def initialize(msg = "Invalid attempt to add Taxonomite::Node.", parent = nil, child = nil)
+      msg = "Cannot add " +
+            ( child.nil? ? "nil child" : "#{child.name} (#{child.entity_type})" ) +
+            " as child of #{parent.name} (#{parent.entity_type})" unless parent.nil?
+      super(msg)
+    end
+  end
+
+  class InvalidParent < RuntimeError
+    extend CreateClassMethod
+
+    def initialize(msg = "Invalid attempt to add Taxonomite::Node.", parent = nil, child = nil)
+      unless (parent.nil? && child.nil?)
+        msg = "Cannot add " +
+              ( child.nil? ? "nil child" : "#{child.name} (#{child.entity_type})" ) +
+              " as child of #{parent.name} (#{parent.entity_type})" unless parent.nil?
+      end
+      super(msg)
+    end
+  end
+
+  class CircularRelation < RuntimeError
+    extend CreateClassMethod
+
+    def initialize(msg = "Circular relation in attempt to add Taxonomite::Node.", parent = nil, child = nil)
+      msg = "Circular reference in adding " +
+            ( child.nil? ? "nil child" : "#{child.name} (#{child.entity_type})" ) +
+            " as child of #{parent.name} (#{parent.entity_type})" unless parent.nil?
+      super(msg)
+    end
+  end
+
 end # taxonomite

data/lib/taxonomite/node.rb

@@ -1,158 +1,154 @@
 require 'taxonomite/taxonomite_configuration'
 require 'taxonomite/tree'
+require 'mongoid'
 
 module Taxonomite
+  ##
+  # Class which defines a node within a tree hierarchy. Validation on addition
+  # of children and parents does occur in this class to provide for class specific
+  # validation in subclasses. That said, enforcing a taxonomy (rules about how the
+  # hierarchy is constructed) falls to the Taxonomite::Taxonomy class which is
+  # used to join parents and children according to specified rules. Thus, if
+  # someone does Obj.children << node -- no special validation will occur, other
+  # than that provided within this class or subclasses via is_valid_child? and
+  # is_valid_parent?
+  #
   class Node
-    # Class declarations
-    #
-    # configuration
-    #
-    # !! note that configuration is class-wide, rather than on an
-    #    instance-instance value; this could be changed, for example if
-    #    two simultaneous persistence models for the place were desired
-    #
-    class << self
-        attr_writer :configiration
-    end
-
-    def self.config
-        @configuration ||= Taxonomite::Configuration.new
-    end
+    extend Taxonomite::ConfiguredGlobally
 
-    def self.configure
-        yield(config)
-    end
+    # handle configurable options - this is essentially how the tree is stored.
+    case Node.config.use_tree_model
+      when :self
+        include ::Mongoid::Document
 
-    def self.reset
-        @configuration = Taxonomite::Configuration.new
-    end
+        # make this protected such that other objects cannot access
+        include Taxonomite::Tree
 
-    def self.primary_key
-      "_id"
-    end
+        # configure the way the tree behaves
+        before_destroy :nullify_children
 
-    case Node.config.use_tree_model
-    when :self
-      include ::Mongoid::Document
-      include Taxonomite::Tree
-
-      # configure the way the tree behaves
-      before_destroy :nullify_children
-    else
-      raise RuntimeError, 'Invalid option for Node.config.use_tree_model: #{Node.config.use_tree_model}'
+      else
+        raise RuntimeError, 'Invalid option for Node.config.use_tree_model: #{Node.config.use_tree_model}'
     end
 
     field :name, type: String         # name of this particular object (not really node)
-    field :description, type: String  # description of this item
     field :entity_type, type: String, default: ->{ self.get_entity_type }  # type of entity (i.e. state, county, city, etc.)
 
     belongs_to :owner, polymorphic: true # this is the associated object
 
-    ## Data collection methods
-
-    # aggregates the results of calling method m on all leaves of the tree and returns that
-    def aggregate_leaves(m)
-      if self.leaf?
-        return self.owner.instance_eval(m) if self.owner != nil && self.owner.respond_to?(m)
-        return self.instance_eval(m) if self.respond_to?(m)
-        return 0
-      else
-        res = 0
-        self.children.each do |c|
-          res = res + c.aggregate_leaves(m)
-        end
-        return res
-      end
+    ##
+    # evaluate a method on the owner of this node (if present). If an owner is
+    # not present, then the method is evaluated on this object. In either case
+    # a check is made to ensure that the object will respond_to? the method call.
+    # If the owner exists but does not respond to the method, then the method is
+    # tried on this node object in similar fashion.
+    # !!! SHOULD THIS JUST OVERRIDE instance_eval ??
+    # @param [Method] m method to call
+    # @return [] the result of the method call, or nil if unable to evaluate
+    def evaluate(m)
+      return self.owner.instance_eval(m) if self.owner != nil && self.owner.respond_to?(m)
+      return self.instance_eval(m) if self.respond_to?(m)
+      nil
     end
 
-    ## Typeification methods
-
+    ##
     # typeify name w entity (i.e. 'Washington state' vs. 'Seattle')
+    # @return [String] the typeified name
     def typeifiedname
       s = self.name
       s += (" " + self.entity_type.capitalize) if self.includetypeinname?
       return s
     end
 
-    # subclasses should override to make sure the parent is appropriate for this child
-    # !! could move this to the tree structure
-    def is_valid_parent?(pa)
-        # !! need to figure out how to do this with regexp
-        unless self.invalid_parent_types.include?(pa.entity_type)
-          s = self.valid_parent_types
-          if s.include?('*')
-            return true
-          else
-            return s.include?(pa.entity_type)
-          end
-        else
-          return false
-        end
+    ##
+    # determine whether child is a valid child based upon class evalution
+    # (outside of a taxonomy). Default is always true - subclasses should
+    # override if validation outside of a separate taxonomy class is desired.
+    # @param [Taxonomite::Node] child child to evaluate
+    # @return [Boolean] default is true
+    def is_valid_child?(child)
+      return true
     end
 
-    # check for validity, with adding error checking this would be the appropriate
-    # place to add exceptions, etc. (to allow recovery);
-    # !! could move this to the tree structure
-    def is_valid_child?(ch)
-        # !! need to figure out how to do this with regexp
-        unless self.invalid_child_types.include?(ch.entity_type)
-          s = self.valid_child_types
-          if s.include?('*') || s.include?(ch.entity_type)
-            return ch.is_valid_parent?(self)
-          else
-            return false
-          end
-        else
-          return false
-        end
+    ##
+    # determine whether parent is a valid parent based upon class evalution
+    # (outside of a taxonomy). Default is always true - subclasses should
+    # override if validation outside of a separate taxonomy class is desired.
+    # @param [Taxonomite::Node] parent parent to evaluate
+    # @return [Boolean] default is true
+    def is_valid_parent?(child)
+      return true
     end
 
-    # default parent types (subclasses should override as needed) - default specifies any
-    def valid_parent_types
-      '*'
+    ##
+    # add a child to this object; default is that each parent may have many children;
+    # this will validate the child using thetaxonomy object passed in to the field.
+    # @param [Taxonomite::Node] child the node to evaluate
+    def add_child(child)
+      self.children << child
     end
 
-    # default child types (subclasses should override as needed) - default specifies any
-    def valid_child_types
-      '*'
+    ##
+    # add a parent for this object (default is that each object can have only one
+    # parent).
+    # this will validate the child using the taxonomy object passed in to the field.
+    # @param [Taxonomite::Node] parent the node to evaluate
+    # @param [Taxonomite::Taxonomy] taxonomy to use to validate the hierarchy
+    def add_parent(parent)
+      parent.add_child(self)
     end
 
-    # default invalid child types
-    def invalid_child_types
-      ""
+    ##
+    # remove a child from this node.
+    # @param [Taxonomite::Node] child node to remove
+    def remove_child(child)
+      self.children.delete(child)
     end
 
-    # default invalid parent types
-    def invalid_parent_types
-      ""
+    ##
+    # remove the parent from this node. This should cause a reciprocal removal
+    # of self from the parent's children
+    def remove_parent
+      self.parent.remove_child(self) unless self.parent.nil?
     end
 
-    # don't want to index off of place name? - could have multiple entries w. similar names
-    # create an index off of the place name, alone; will later create on off of the
-    # geo locations *additionally*
-    # index({ place_name: 1 }, { unique: false, name: "name_index"})
-
-    # ** would like to hide these interfaces in a private/protected manner, not clear
-    # ** how to do this in Ruby - doesn't have 'const' access similar to c++, etc.
     protected
-
+        ##
         # include type in the name of this place (i.e. 'Washington state')
+        # @return [Boolean]
         def includetypeinname?
           return false
         end
 
-        # set the entity type (each subclass should override)
+        ##
+        # access the entity type for this Object
+        # @return [String]
         def get_entity_type
-          'Node'
+          'node'
         end
 
-        def validate_child(ch)
-          raise InvalidChild, "Cannot add #{ch.name} (#{ch.entity_type}) as child of #{self.name} (#{self.entity_type})" if !is_valid_child?(ch)
-        end
+    private
+      ##
+      # determine whether the child is valid for this object; there are two
+      # layers to validation 1) provided by this method is_valid_parent? (and subclasses which override
+      # is_valid_parent?).
+      # @param [Taxonomite::Node] child the parent to validate
+      # @return [Boolean] whether validation was successful
+      def validate_child(child)
+        raise InvalidParent.create(self, child) unless (!child.nil? && is_valid_child?(child))
+        true
+      end
 
-        def validate_parent(pa)
-          raise InvalidParent, "Cannot add #{pa.name} (#{pa.enity_type}) as parent of #{self.name} (#{self.entity_type})" if !is_valid_parent?(pa)
-        end
+      ##
+      # determine whether the parent is valid for this object. See description of
+      # validate_child for more detail. This method calls validate_child to perform
+      # the actual validation.
+      # @param [Taxonomite::Node] parent the parent to validate
+      # @return [Boolean] whether validation was successful
+      def validate_parent(parent)
+        raise InvalidParent.create(parent, self) unless (!parent.nil? && is_valid_parent?(parent))
+        parent.validate_child(self)
+      end
 
   end   # class Node
 end # module Taxonomite

data/lib/taxonomite/taxonomite_configuration.rb

@@ -3,15 +3,68 @@
 #
 
 module Taxonomite
+
+    ##
+    # Allows the class to be configured on its very own, such that it
+    # creates its own @configuration class object. Thus if ClassB inherited
+    # from ClassA and ClassA extends Configurable, then both could have their own
+    # configuration options? Any class that extends this must declare a
+    # create_configuration class method.
+    module Configurable
+      class << self
+        attr_writer :configuration
+      end
+
+      def config
+        @configuration ||= create_configuration
+      end
+
+      def configure
+        yield(config)
+      end
+
+      def reset
+        @configuration = create_configuration
+      end
+    end
+
+
+    ##
+    # The configuration class for Taxonomite gem. All classes which are configured via
+    # this mechanism should extend Taxonomite::Configured (below).
     class Configuration
-        # future versions may extend to using different tree models
-        # - for now uses a custom tree model (:self)
-        attr_accessor   :use_tree_model
+      extend Taxonomite::Configurable
+
+      def self.create_configuration
+        Taxonomite::Configuration.new
+      end
+
+      # future versions may extend to using different tree models
+      # - for now uses a custom tree model (:self)
+      attr_accessor   :use_tree_model
+      attr_accessor   :default_taxonomy_require_both
 
     protected
-        # initialize
+        ##
+        # initialize object variables to defaults
         def initialize
             @use_tree_model = :self
+            @default_taxonomy_require_both = true
         end
     end
+
+
+    ##
+    # All classes which are configured using Taxonomite::Configuration should
+    # extend this module, such that they can access the configuration via their
+    # own class methods (i.e. ClassA.config.option)
+    module ConfiguredGlobally
+      def config
+        Taxonomite::Configuration.config
+      end
+
+      def reset
+        Taxonomite::Configuration.reset
+      end
+    end
 end

data/lib/taxonomite/taxonomy.rb

@@ -0,0 +1,144 @@
+require 'taxonomite/taxonomite_configuration'
+require 'taxonomite/tree'
+
+module Taxonomite
+  ##
+  # Class which enforces a particular hierarchy among objects.
+  class Taxonomy
+    include Mongoid::Document
+    extend Taxonomite::ConfiguredGlobally
+
+    # ? whether this needs to be stored in the database or not, as most
+    # of the time would be instanciated by an application
+    field :down_taxonomy, type: Hash, default: ->{ Hash.new("*") }
+    field :up_taxonomy, type: Hash, default: ->{ Hash.new("*") }
+    field :require_both, type: Boolean, default: ->{ Taxonomite::Taxonomy.config.default_taxonomy_require_both }
+
+    ##
+    # verify according to the down-looking taxonomy hash.
+    # @param [Taxonomite::Node] parent the proposed parent node
+    # @param [Taxonomite::Node] child the proposed child node
+    # @return [Boolean] whether the child appropriate for the parent, default true
+    def is_valid_down_relation?(parent, child)
+      [self.down_taxonomy[parent.entity_type]].map { |t| return true if [child.entity_type, "*"].include?(t) }
+      false
+    end
+
+    ##
+    # verify according to the down-looking taxonomy hash.
+    # @param [Taxonomite::Node] parent the proposed parent node
+    # @param [Taxonomite::Node] child the proposed child node
+    # @return [Boolean] whether the child appropriate for the parent, default true
+    def is_valid_up_relation?(parent, child)
+      [self.up_taxonomy[child.entity_type]].map { |t| return true if [parent.entity_type, "*"].include?(t) }
+      false
+    end
+
+    ##
+    # determine whether the parent is a valid parent for the child. If no
+    # taxonomy is defined (i.e. the hashes are empty) then default is to return
+    # true. Requires that *both* an updward and a downward relation are present if
+    # the require_both flag is set (default is true -- this can be set via Taxonomite::Configuration).
+    # This flag can also be passed into the method here.
+    # @param [Taxonomite::Node] parent the proposed parent node
+    # @param [Taxonomite::Node] child the proposed child node
+    # @param [Boolean] require_both to require both downward and upward match, or just one or the other
+    # @return [Boolean] whether the child appropriate for the parent, default true
+    def is_valid_relation?(parent, child, require_both = self.require_both)
+      # depending upon the
+      require_both ? is_valid_down_relation?(parent, child) && is_valid_up_relation?(parent, child)
+                   : is_valid_down_relation?(parent, child) || is_valid_up_relation?(parent, child)
+    end
+
+    ##
+    # access the appropriate parent entity_types for a particular child or child entity_type
+    # @param [Taxonomy::Node, String] child the child object or entity_type string
+    # @return [Array] an array of strings which are the valid parent types for the child
+    def valid_parent_types(child)
+      # could be a node object, or maybe a string
+      str = child.respond_to?(:entity_type) ? child.entity_type : child
+      self.up_taxonomy[str]
+    end
+
+    ##
+    # access the appropriate child entity_types for a particular parent or parent entity_type
+    # @param [Taxonomy::Node, String] parent the parent object or entity_type string
+    # @return [Array] an array of strings which are the valid child types for the child
+    def valid_child_types(parent)
+      # could be a node object, or maybe a string
+      str = parent.respond_to?(:entity_type) ? parent.entity_type : child
+      self.down_taxonomy[str]
+    end
+
+    # ##
+    # # Is this the direct owner of the node passed. This allows for auto-organizing
+    # # hierarchies. Sublcasses should override this method. Defaults to false - hence
+    # # no structure.
+    # # @param [Taxonomite::Node] node node in question
+    # # @return [Boolean] whether self should directly own node as a child, default is false
+    # def contains?(node)
+    #   false
+    # end
+
+    ##
+    # Find the direct owner of a node within the tree. Returns nil if no direct
+    # owner exists within the tree starting at root self. This works down the
+    # tree (rather than up.) If root is nil it simply trys all of the Node objects
+    # which match the appropriate parent entity_type for node. The default simply
+    # finds the first available valid parent depending upon the search method employed.
+    # @param [Taxonomite::Node] node the node to evaluate
+    # @param [Taxonomite::Node] root the root of the tree to evaluate; if nil will search for the parents of the node first
+    # @return [Taxonomite::Node] the appropriate node or nil if none found
+    def find_owner(node, root = nil)
+      valid_parent_types(node).presence.each do |t|
+        getallnodes = lambda { |v| v == '*' ? Taxonomite::Node.find() : Taxonomite::Node.find_by(:entity_type => t) }
+        getrootnodes = lambda { |v| v == '*' ? root.self_and_descendants : root.self_and_descendants.find_by(:entity_type => t) }
+        ( root.nil? ? getallnodes.call(t) : getrootnodes.call(t) ).each { |n| return n if is_valid_relation(n,node) }
+      end
+      nil
+    end
+
+    ##
+    # see if this node belongs directly under a particular parent; this allows for
+    # assignment within a hierarchy. Subclasses should override to provide better
+    # functionality. Default behavior asks the node if it contains(self).
+    # @param [Taxonomite::Node] child the node to evaluate
+    # @param [Taxonomite::Parent] parent the parent node to evaluate for the child
+    def belongs_under?(parent, child)
+      self.find_owner(child, parent) != nil
+    end
+
+    # ##
+    # # see if this node belongs directly to another node (i.e. would appropriately)
+    # # be added as a child of the node. Default returns false. Convention to get
+    # # self-organizing hierarchy to work is for belongs_under to return true when
+    # # belongs_directly_to is true as well. Default behaviour is to ask the node if
+    # # it directly_contains(self).
+    # # @param [Taxonomite::Node] node to evaluate
+    # # @return [Boolean] whether node contains this object (self)
+    # def belongs_directly_to(node)
+    #   node.contains?(self)
+    # end
+
+    ##
+    # try to add a child to a parent, with validation by this Taxonomy
+    # @param [Taxonomite::Node] parent the parent node
+    # @param [Taxonomite::Node] child the child node
+    def add(parent, child)
+      raise InvalidChild::create(parent,child) unless self.is_valid_relation?(parent, child)
+      parent.add_child(child)
+    end
+
+    protected
+
+    # ##
+    # # return the default initial hash for this object, default is empty.
+    # # Subclasses should override to provide a default hash. A hierarchy could
+    # # be createed with this method alone.
+    # # @return [Hash] the default (initialized) taxonomy_hash values
+    # def initial_hash
+    #   {}
+    # end
+
+  end   # class Taxonomy
+end # module Taxonomite