activefacts 0.8.9 → 0.8.10

data/lib/activefacts/api/constellation.rb

@@ -1,128 +0,0 @@
-#
-#       ActiveFacts Runtime API
-#       Constellation class
-#
-# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
-#
-
-module ActiveFacts
-  module API      #:nodoc:
-    # A Constellation is a population of instances of the Concept classes of a Vocabulary.
-    # Every concept class is either a Value type or an Entity type.
-    #
-    # Value types are uniquely identified by their value, and a constellation will only
-    # ever have a single instance of a given value of that class.
-    #
-    # Entity instances are uniquely identified by their identifying roles, and again, a
-    # constellation will only ever have a single entity instance for the values of those
-    # identifying roles.
-    #
-    # As a result, you cannot "create" an object in a constellation - you merely _assert_
-    # its existence. This is done using method_missing; @constellation.Thing(3) creates
-    # an instance (or returns the existing instance) of Thing identified by the value 3.
-    # You can also use the populate() method to apply a block of assertions.
-    #
-    # You can instance##retract any instance, and that removes it from the constellation (will
-    # delete it from the database when the constellation is saved), and nullifies any
-    # references to it.
-    #
-    # A Constellation may or not be valid according to the vocabulary's constraints,
-    # but it may also represent a portion of a larger population (a database) with
-    # which it may be merged to form a valid population. In other words, an invalid
-    # Constellation may be invalid only because it lacks some of the facts.
-    #
-    class Constellation
-      attr_reader :vocabulary
-      # All instances are indexed in this hash, keyed by the class object. Each instance is indexed for every supertype it has (including multiply-inherited ones). It's a bad idea to try to modify these indexes!
-      attr_reader :instances      # Can say c.instances[MyClass].each{|k, v| ... }
-                                  # Can also say c.MyClass.each{|k, v| ... }
-
-      # Create a new empty Constellation over the given Vocabulary
-      def initialize(vocabulary)
-        @vocabulary = vocabulary
-        @instances = Hash.new do |h,k|
-          raise "A constellation over #{@vocabulary.name} can only index instances of concepts in that vocabulary, not #{k.inspect}" unless k.is_a?(Class) and k.modspace == vocabulary
-          h[k] = InstanceIndex.new
-        end
-      end
-
-      def inspect #:nodoc:
-        "Constellation:#{object_id}"
-      end
-
-      # Evaluate assertions against the population of this Constellation
-      def populate *args, &block
-        # REVISIT: Use args for something? Like options to enable/disable validation?
-        instance_eval(&block)
-      end
-
-      # Delete instances from the constellation, nullifying (or cascading) the roles each plays
-      def retract(*instances)
-        Array(instances).each do |i|
-          i.retract
-        end
-      end
-
-      # Constellations verbalise all members of all classes in alphabetical order, showing
-      # non-identifying role values as well
-      def verbalise
-        "Constellation over #{vocabulary.name}:\n" +
-        vocabulary.concept.keys.sort.map{|concept|
-            klass = vocabulary.const_get(concept)
-
-            # REVISIT: It would be better not to rely on the role name pattern here:
-            single_roles, multiple_roles = klass.roles.keys.sort_by(&:to_s).partition{|r| r.to_s !~ /\Aall_/ }
-            single_roles -= klass.identifying_role_names if (klass.is_entity_type)
-            # REVISIT: Need to include superclass roles also.
-
-            instances = send(concept.to_sym)
-            next nil unless instances.size > 0
-            "\tEvery #{concept}:\n" +
-              instances.map{|key, instance|
-                  s = "\t\t" + instance.verbalise
-                  if (single_roles.size > 0)
-                    role_values = 
-                      single_roles.map{|role|
-                          [ role_name = role.to_s.camelcase(true),
-                            value = instance.send(role)]
-                        }.select{|role_name, value|
-                          value
-                        }.map{|role_name, value|
-                          "#{role_name} = #{value ? value.verbalise : "nil"}"
-                        }
-                    s += " where " + role_values*", " if role_values.size > 0
-                  end
-                  s
-                } * "\n"
-          }.compact*"\n"
-      end
-
-      # This method removes the given instance from this constellation's indexes
-      # It must be called before the identifying roles get deleted or nullified.
-      def __retract(instance) #:nodoc:
-        # REVISIT: Need to search, as key values are gone already. Is there a faster way?
-        ([instance.class]+instance.class.supertypes_transitive).each do |klass|
-          @instances[klass].delete_if{|k,v| v == instance }
-        end
-        # REVISIT: Need to nullify all the roles this object plays.
-        # If mandatory on the counterpart side, this may/must propagate the delete (without mutual recursion!)
-      end
-
-      # With parameters, assert an instance of the concept whose name is the missing method, identified by the values passed as *args*.
-      # With no parameters, return the collection of all instances of that concept.
-      def method_missing(m, *args)
-        if klass = @vocabulary.const_get(m)
-          if args.size == 0
-            # Return the collection of all instances of this class in the constellation:
-            @instances[klass]
-          else
-            # Assert a new ground fact (concept instance) of the specified class, identified by args:
-            # REVISIT: create a constructor method here instead?
-            instance, key = klass.assert_instance(self, args)
-            instance
-          end
-        end
-      end
-    end
-  end
-end

data/lib/activefacts/api/entity.rb

@@ -1,256 +0,0 @@
-#
-#       ActiveFacts Runtime API
-#       Entity class (a mixin module for the class Class)
-#
-# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
-#
-module ActiveFacts
-  module API
-    # An Entity type is any Concept that isn't a value type.
-    # All Entity types must have an identifier made up of one or more roles.
-    module Entity
-      include Instance
-
-      # Assign the identifying roles to initialise a new Entity instance.
-      # The role values are asserted in the constellation first, so you
-      # can pass bare values (array, string, integer, etc) for any role
-      # whose instances can be constructed using those values.
-      #
-      # A value must be provided for every identifying role, but if the
-      # last argument is a hash, they may come from there.
-      #
-      # Any additional (non-identifying) roles may also be passed in the final hash.
-      def initialize(*args)
-        super(args)
-        klass = self.class
-        hash = {}
-        hash = args.pop.clone if Hash === args[-1]
-
-        # Pick any missing identifying roles out of the hash if possible:
-        while args.size < (ir = klass.identifying_role_names).size
-          value = hash[role = ir[args.size]]
-          hash.delete(role)
-          args.push value
-        end
-
-        # If one arg is expected but more are passed, they might be the args for the object that plays the identifying role:
-        args = [args] if klass.identifying_role_names.size == 1 && args.size > 1
-
-        # This should now only occur when there are too many args passed:
-        raise "Wrong number of parameters to #{klass}.new, " +
-            "expect (#{klass.identifying_role_names*","}) " +
-            "got (#{args.map{|a| a.to_s.inspect}*", "})" if args.size != klass.identifying_role_names.size
-
-        # Assign the identifying roles in order, then the other roles passed as a hash:
-        (klass.identifying_role_names.zip(args) + hash.entries).each do |role_name, value|
-          role = klass.roles(role_name)
-          send("#{role_name}=", value)
-        end
-      end
-
-      def inspect #:nodoc:
-        "\#<#{
-          self.class.basename
-        }:#{
-          object_id
-        }#{
-          constellation ? " in #{constellation.inspect}" : ""
-        } #{
-          # REVISIT: Where there are one-to-one roles, this cycles
-          self.class.identifying_role_names.map{|role| "@#{role}="+send(role).inspect }*" "
-        }>"
-      end
-
-      # When used as a hash key, the hash key of this entity instance is calculated
-      # by hashing the values of its identifying roles
-      def hash
-        self.class.identifying_role_names.map{|role|
-            instance_variable_get("@#{role}")
-          }.inject(0) { |h,v|
-            h ^= v.hash
-            h
-          }
-      end
-
-      # When used as a hash key, this entity instance is compared with another by
-      # comparing the values of its identifying roles
-      def eql?(other)
-        return false unless self.class == other.class
-        self.class.identifying_role_names.each{|role|
-            return false unless send(role).eql?(other.send(role))
-          }
-        return true
-      end
-
-      # Verbalise this entity instance
-      def verbalise(role_name = nil)
-        "#{role_name || self.class.basename}(#{
-          self.class.identifying_role_names.map{|role_sym|
-              value = send(role_sym)
-              role_name = self.class.roles(role_sym).name.to_s.camelcase(true)
-              value ? value.verbalise(role_name) : "nil"
-            }*", "
-        })"
-      end
-
-      # Return the array of the values of this entity instance's identifying roles
-      def identifying_role_values
-        self.class.identifying_role_names.map{|role|
-            send(role)
-          }
-      end
-
-      # All classes that become Entity types receive the methods of this class as class methods:
-      module ClassMethods
-        include Instance::ClassMethods
-
-        # Return the array of Role objects that define the identifying relationships of this Entity type:
-        def identifying_role_names
-          @identifying_role_names ||= []
-        end
-
-        def identifying_roles
-          debug :persistence, "Identifying roles for #{basename}" do
-            @identifying_role_names.map{|name|
-              role = roles[name] || (!superclass.is_entity_type || superclass.roles[name])
-              debug :persistence, "#{name} -> #{role ? "found" : "NOT FOUND"}"
-              role
-            }
-          end
-        end
-
-        # Convert the passed arguments into an array of Instance objects that can identify an instance of this Entity type:
-        def identifying_role_values(*args)
-          #puts "Getting identifying role values #{identifying_role_names.inspect} of #{basename} using #{args.inspect}"
-
-          # If the single arg is an instance of the correct class or a subclass,
-          # use the instance's identifying_role_values
-          if (args.size == 1 and
-              (arg = args[0]).is_a?(self))       # REVISIT: or a secondary supertype
-            arg = arg.__getobj__ if RoleProxy === arg
-            return arg.identifying_role_values
-          end
-
-          ir = identifying_role_names
-          args, arg_hash = ActiveFacts::extract_hash_args(ir, args)
-          if args.size < ir.size
-            raise "#{basename} requires all identifying values, you're missing #{ir[args.size..-1].map(&:to_sym)*', '}"
-          elsif args.size > ir.size
-            raise "#{basename} requires all identifying values, you have #{args.size-ir.size} extras #{args[ir.size..-1].map(&:inspect)*', '}"
-          end
-
-          role_args = ir.map{|role_sym| roles(role_sym)}.zip(args)
-          role_args.map do |role, arg|
-            #puts "Getting identifying_role_value for #{role.counterpart_concept.basename} using #{arg.inspect}"
-            next nil unless arg
-            next !!arg unless role.counterpart  # Unary
-            arg = arg.__getobj__ if RoleProxy === arg
-            if arg.is_a?(role.counterpart_concept)              # REVISIT: or a secondary supertype
-              # Note that with a secondary supertype, it must still return the values of these identifying_role_names
-              next arg.identifying_role_values
-            end
-            role.counterpart_concept.identifying_role_values(*arg)
-          end
-        end
-
-        def assert_instance(constellation, args) #:nodoc:
-          # Build the key for this instance from the args
-          # The key of an instance is the value or array of keys of the identifying values.
-          # The key values aren't necessarily present in the constellation, even after this.
-          key = identifying_role_values(*args)
-
-          # Find and return an existing instance matching this key
-          instances = constellation.instances[self]   # All instances of this class in this constellation
-          instance = instances[key]
-          # DEBUG: puts "assert #{self.basename} #{key.inspect} #{instance ? "exists" : "new"}"
-          return instance, key if instance      # A matching instance of this class
-
-          # Now construct each of this object's identifying roles
-          ir = identifying_role_names
-          args, arg_hash = ActiveFacts::extract_hash_args(ir, args)
-          role_values = ir.map{|role_sym| roles(role_sym)}.zip(args)
-          key = []    # Gather the actual key (AutoCounters are special)
-          values = role_values.map do |role, arg|
-              if !arg
-                value = role_key = nil          # No value
-              elsif !role.counterpart
-                value = role_key = !!arg        # Unary
-              elsif arg.is_a?(role.counterpart_concept)      # REVISIT: or a secondary supertype
-                arg = arg.__getobj__ if RoleProxy === arg
-                raise "Connecting values across constellations" unless arg.constellation == constellation
-                value, role_key = arg, arg.identifying_role_values
-              else
-                value, role_key = role.counterpart_concept.assert_instance(constellation, Array(arg))
-              end
-              key << role_key
-              value
-            end
-          values << arg_hash if arg_hash and !arg_hash.empty?
-
-          #puts "Creating new #{basename} using #{values.inspect}"
-          instance = new(*values)
-
-          # Make the new entity instance a member of this constellation:
-          instance.constellation = constellation
-          return *index_instance(instance, key, ir)
-        end
-
-        def index_instance(instance, key = nil, key_roles = nil) #:nodoc:
-          # Derive a new key if we didn't receive one or if the roles are different:
-          unless key && key_roles && key_roles == identifying_role_names
-            key = (key_roles = identifying_role_names).map do |role_name|
-              instance.send role_name
-            end
-          end
-
-          # Index the instance for this class in the constellation
-          instances = instance.constellation.instances[self]
-          instances[key] = instance
-          # DEBUG: puts "indexing entity #{basename} using #{key.inspect} in #{constellation.object_id}"
-
-          # Index the instance for each supertype:
-          supertypes.each do |supertype|
-            supertype.index_instance(instance, key, key_roles)
-          end
-
-          return instance, key
-        end
-
-        # A concept that isn't a ValueType must have an identification scheme,
-        # which is a list of roles it plays. The identification scheme may be
-        # inherited from a superclass.
-        def initialise_entity_type(*args) #:nodoc:
-          #puts "Initialising entity type #{self} using #{args.inspect}"
-          @identifying_role_names = superclass.identifying_role_names if superclass.is_entity_type
-          # REVISIT: @identifying_role_names here are the symbols passed in, not the Role objects we should use.
-          # We'd need late binding to use Role objects...
-          @identifying_role_names = args if args.size > 0 || !@identifying_role_names
-        end
-
-        def inherited(other) #:nodoc:
-          other.identified_by *identifying_role_names
-          subtypes << other unless subtypes.include? other
-          #puts "#{self.name} inherited by #{other.name}"
-          vocabulary.__add_concept(other)
-        end
-
-        # verbalise this concept
-        def verbalise
-          "#{basename} is identified by #{identifying_role_names.map{|role_sym| role_sym.to_s.camelcase(true)}*" and "};"
-        end
-      end
-
-      def Entity.included other #:nodoc:
-        other.send :extend, ClassMethods
-
-        # Register ourselves with the parent module, which has become a Vocabulary:
-        vocabulary = other.modspace
-        # puts "Entity.included(#{other.inspect})"
-        unless vocabulary.respond_to? :concept  # Extend module with Vocabulary if necessary
-          vocabulary.send :extend, Vocabulary
-        end
-        vocabulary.__add_concept(other)
-      end
-    end
-  end
-end

data/lib/activefacts/api/instance.rb

@@ -1,60 +0,0 @@
-#
-#       ActiveFacts Runtime API
-#       Instance (mixin module for instances of a Concept - a class with Concept mixed in)
-#
-# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
-#
-# Instance methods are extended into all instances, whether of value or entity types.
-#
-module ActiveFacts
-  module API
-    # Every Instance of a Concept (A Value type or an Entity type) includes the methods of this module:
-    module Instance
-      # What constellation does this Instance belong to (if any):
-      attr_accessor :constellation
-
-      def initialize(args = []) #:nodoc:
-        unless (self.class.is_entity_type)
-        #if (self.class.superclass != Object)
-          # puts "constructing #{self.class.superclass} with #{args.inspect}"
-          super(*args)
-        end
-      end
-
-      # Verbalise this instance
-      def verbalise
-        # This method should always be overridden in subclasses
-        raise "#{self.class} Instance verbalisation needed"
-      end
-
-      # De-assign all functional roles and remove from constellation, if any.
-      def retract
-        # Delete from the constellation first, so it can remember our identifying role values
-        @constellation.__retract(self) if @constellation
-
-        # Now, for all roles (from this class and all supertypes), assign nil to all functional roles
-        # The counterpart roles get cleared automatically.
-        ([self.class]+self.class.supertypes_transitive).each do |klass|
-          klass.roles.each do |role_name, role|
-            next if role.unary?
-            next if !role.unique
-
-            counterpart = role.counterpart
-            puts "Nullifying mandatory role #{role.name} of #{role.owner.name}" if counterpart.mandatory
-
-            send "#{role.name}=", nil
-          end
-        end
-      end
-
-      module ClassMethods #:nodoc:
-        include Concept
-        # Add Instance class methods here
-      end
-
-      def Instance.included other #:nodoc:
-        other.send :extend, ClassMethods
-      end
-    end
-  end
-end

data/lib/activefacts/api/instance_index.rb

@@ -1,80 +0,0 @@
-#
-#       ActiveFacts Runtime API
-#       InstanceIndex class
-#
-# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
-#
-module ActiveFacts
-  module API
-    #
-    # Each Constellation maintains an InstanceIndex for each Concept in its Vocabulary.
-    # The InstanceIndex object is returned when you call @constellation.Concept with no
-    # arguments (where Concept is the concept name you're interested in)
-    #
-    class InstanceIndex
-      def []=(key, value)   #:nodoc:
-        raise "Adding RoleProxy to InstanceIndex" if value && RoleProxy === value
-        h[key] = value
-      end
-
-      def [](*args)
-        a = args
-        #a = naked(args)
-#        p "vvvv",
-#          args,
-#          a,
-#          keys.map{|k| v=super(k); (RoleProxy === k ? "*" : "")+k.to_s+"=>"+(RoleProxy === v ? "*" : "")+v.to_s}*",",
-#          "^^^^"
-        h[*a]
-        #super(*a)
-      end
-
-      def size
-        h.size
-      end
-
-      def each &b
-        h.each &b
-      end
-
-      def map &b
-        h.map &b
-      end
-
-      def detect &b
-        r = h.detect &b
-        r ? r[1] : nil
-      end
-
-      # Return an array of all the instances of this concept
-      def values
-        h.values
-      end
-
-      # Return an array of the identifying role values arrays for all the instances of this concept
-      def keys
-        h.keys
-      end
-
-      def delete_if(&b)   #:nodoc:
-        h.delete_if &b
-      end
-
-    private
-      def h
-        @hash ||= {}
-      end
-
-      def naked(o)
-        case o
-        when Array
-          o.map{|e| naked(e) }
-        when RoleProxy
-          o.__getobj__
-        else
-          o
-        end
-      end
-    end
-  end
-end