activefacts-api 0.8.9 → 0.8.10

data/Rakefile

@@ -7,7 +7,7 @@ Jeweler::Tasks.new do |gem|
   gem.name = "activefacts-api"
   gem.homepage = "http://github.com/cjheath/activefacts-api"
   gem.license = "MIT"
-  gem.summary = "A semantic modeling and query language (CQL) and application runtime (the Constellation API)"
+  gem.summary = "A fact-based data model DSL and API"
   gem.description = %q{
 The ActiveFacts API is a Ruby DSL for managing constellations of elementary facts.
 Each fact is either existential (a value or an entity), characteristic (boolean) or
@@ -23,6 +23,7 @@ over the fact population.
   gem.add_development_dependency "bundler", "~> 1.0.0"
   gem.add_development_dependency "jeweler", "~> 1.5.2"
   # gem.add_development_dependency "rcov", ">= 0"
+  gem.add_development_dependency "rdoc", ">= 2.4.2"
 end
 Jeweler::RubygemsDotOrgTasks.new
 
@@ -34,12 +35,13 @@ end
 
 RSpec::Core::RakeTask.new(:rcov) do |spec|
   spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov_opts = [ '--exclude', 'spec', '--exclude', 'lib/activefacts/tracer.rb' ]
   spec.rcov = true
 end
 
 task :default => :spec
 
-require 'rake/rdoctask'
+require 'rdoc/task'
 Rake::RDocTask.new do |rdoc|
   version = File.exist?('VERSION') ? File.read('VERSION') : ""
 

data/TODO

@@ -0,0 +1,29 @@
+Performance
+	Pre-define ObjectType accessor methods on constellation, rather than using method_missing
+
+Role objects:
+        TEST: Access through class-level accessors
+
+Reindexing on identifier change
+	De-index on change, arrange for re-index on completion
+	Re-index all objects this identifies (keep track of roles-as-identifier)
+	Save "key" value
+	Nested block to accumulate changed identifiers and re-index at end?
+
+Switch to rbtree from Hash
+        For InstanceIndex
+	For RoleValues
+	Index into RoleValues by key residual, not full key (worth doing?)
+
+Testing
+	Complete pending tests
+	Add heckle coverage
+
+Constraints
+	Ensure role methods arguments are flexible for plugins
+	Make mandatory work (propagate retraction? or just optionally?)
+
+Functionality
+	Finish Constellation.assert
+	Replace inspect by verbalise
+	Query API and execution

data/VERSION

@@ -1 +1 @@
-0.8.9
+0.8.10

data/lib/activefacts/api.rb

@@ -32,13 +32,13 @@
 
 require 'activefacts/api/support'               # General support code and core patches
 require 'activefacts/api/vocabulary'            # A Ruby module may become a Vocabulary
-require 'activefacts/api/role_proxy'            # Experimental proxy for has_one/one_to_one role accessors
 require 'activefacts/api/instance_index'        # The index used by a constellation to record every instance
 require 'activefacts/api/constellation'         # A Constellation is a query result or fact population
-require 'activefacts/api/object_type'               # A Ruby class may become a ObjectType in a Vocabulary
+require 'activefacts/api/object_type'           # A Ruby class may become a ObjectType in a Vocabulary
 require 'activefacts/api/role'                  # A ObjectType has a collection of Roles
 require 'activefacts/api/role_values'           # The container used for sets of role players in many_one's
 require 'activefacts/api/instance'              # An Instance is an instance of a ObjectType class
 require 'activefacts/api/value'                 # A Value is an Instance of a value class (String, Numeric, etc)
 require 'activefacts/api/entity'                # An Entity class is an Instance not of a value class
 require 'activefacts/api/standard_types'        # Value classes are augmented so their subclasses may become Value Types
+require 'activefacts/tracer'

data/lib/activefacts/api/constellation.rb

@@ -42,7 +42,7 @@ module ActiveFacts
         @vocabulary = vocabulary
         @instances = Hash.new do |h,k|
           raise "A constellation over #{@vocabulary.name} can only index instances of object_types in that vocabulary, not #{k.inspect}" unless k.is_a?(Class) and k.modspace == vocabulary
-          h[k] = InstanceIndex.new
+          h[k] = InstanceIndex.new(self, k)
         end
       end
 
@@ -51,9 +51,9 @@ module ActiveFacts
       end
 
       # Evaluate assertions against the population of this Constellation
-      def populate *args, &block
-        # REVISIT: Use args for something? Like options to enable/disable validation?
+      def populate &block
         instance_eval(&block)
+        self
       end
 
       # Delete instances from the constellation, nullifying (or cascading) the roles each plays
@@ -61,13 +61,35 @@ module ActiveFacts
         Array(instances).each do |i|
           i.retract
         end
+        self
       end
 
+=begin
+      def assert *args
+        case
+        when args.size >= 1
+          args.each do |arg|
+            assert arg
+          end
+        when args[0].is_a?(Hash)
+          args[0].each do |key, value|
+            klass_name = key.is_a?(Symbol) ? key.to_s.camelcase : key.to_s
+            klass = vocabulary.const_get(klass_name)
+            send(klass_name).assert(*Array(value))
+          end
+        else
+          args.each do |arg|
+            assert(arg)
+          end
+        end
+      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.object_type.keys.sort.map{|object_type|
+        vocabulary.object_type.keys.sort.map do |object_type|
             klass = vocabulary.const_get(object_type)
 
             # REVISIT: It would be better not to rely on the role name pattern here:
@@ -78,7 +100,7 @@ module ActiveFacts
             instances = send(object_type.to_sym)
             next nil unless instances.size > 0
             "\tEvery #{object_type}:\n" +
-              instances.map{|key, instance|
+              instances.map do |key, instance|
                   s = "\t\t" + instance.verbalise
                   if (single_roles.size > 0)
                     role_values = 
@@ -93,8 +115,8 @@ module ActiveFacts
                     s += " where " + role_values*", " if role_values.size > 0
                   end
                   s
-                } * "\n"
-          }.compact*"\n"
+                end * "\n"
+          end.compact*"\n"
       end
 
       # This method removes the given instance from this constellation's indexes
@@ -108,19 +130,29 @@ module ActiveFacts
         # If mandatory on the counterpart side, this may/must propagate the delete (without mutual recursion!)
       end
 
-      # With parameters, assert an instance of the object_type whose name is the missing method, identified by the values passed as *args*.
+      # If a missing method is the name of a class in the vocabulary module for this constellation,
+      # then we want to access the collection of instances of that class, and perhaps assert new ones.
       # With no parameters, return the collection of all instances of that object_type.
-      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 (object_type instance) of the specified class, identified by args:
-            # REVISIT: create a constructor method here instead?
-            instance, key = klass.assert_instance(self, args)
-            instance
-          end
+      # With parameters, assert an instance of the object_type identified by the values passed as args.
+      def method_missing(m, *args, &b)
+        if klass = @vocabulary.const_get(m) and klass.is_a?(Class) and klass.respond_to?(:assert_instance)
+
+          (class << self; self; end).
+            send(:define_method, sym = m.to_sym) do |*args|
+              instance_index = @instances[klass]
+              if args.size == 0
+                # Return the collection of all instances of this class in the constellation:
+                instance_index
+              else
+                # Assert a new ground fact (object_type instance) of the specified class, identified by args:
+                instance_index.assert(*args)
+              end
+            end
+
+          # This is the last time it'll be missing, so call it.
+          send(sym, *args, &b)
+        else
+          super
         end
       end
     end

data/lib/activefacts/api/entity.rb

@@ -19,53 +19,71 @@ module ActiveFacts
       # 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.
+      # If a supertype (including a secondary supertype) has a different
+      # identifier, the identifying roles must be provided in the hash.
+      #
+      # Any additional (non-identifying) roles in the hash are ignored
       def initialize(*args)
-        super(args)
         klass = self.class
-        hash = {}
-        hash = args.pop.clone if Hash === args[-1]
+        while klass.identification_inherited_from
+          klass = klass.superclass
+        end
+
+#        if (o = klass.overrides_identification_of and !(o.identifying_role_names-klass.identifying_role_names).empty?)
+          # This is a class which must initialise its superclass' identifying roles
+          # The hash can provide the values, but those values must already be asserted
+          # in the constellation this object will exist in, since they won't get
+          # attached to/cloned into that constellation merely by being assigned here.
+          # REVISIT: Nothing takes care of that, currently.
+          #
+          # The solution to this is to have an empty initialize, add the new instance
+          # to the Constellation, then initialise_roles using normal assignment.
+#        end
+
+        hash = args[-1].is_a?(Hash) ? args.pop.clone : nil
+
+        # Pass just the hash, if there is one, else no arguments:
+        super(*(hash ? [hash] : []))
 
         # 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]]
+        irns = klass.identifying_role_names
+        while hash && args.size < irns.size
+          value = hash[role = irns[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:
+        # If one arg is expected but more are passed, they might be the
+        # args for the object that plays a single 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:
+        # This occur when there are too many args passed, or too few
+        # and no hash. Otherwise the missing ones will be nil.
         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)
+        # Assign the identifying roles in order. Any other roles will be assigned by our caller
+        klass.identifying_role_names.zip(args).each do |role_name, value|
+          role = self.class.roles(role_name)
+          send(role.setter, 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 }*" "
-        }>"
+        inc = constellation ? " in #{constellation.inspect}" : ""
+        # REVISIT: Where there are one-to-one roles, this cycles
+        irnv = self.class.identifying_role_names.map do |role_name|
+          "@#{role_name}="+send(role_name).inspect
+        end
+        "\#<#{self.class.basename}:#{object_id}#{inc} #{ irnv*' ' }>"
       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}")
+        self.class.identifying_role_names.map{|role_name|
+            instance_variable_get("@#{role_name}")
           }.inject(0) { |h,v|
             h ^= v.hash
             h
@@ -76,80 +94,89 @@ module ActiveFacts
       # 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))
+        self.class.identifying_role_names.each{|role_name|
+            return false unless send(role_name).eql?(other.send(role_name))
           }
         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
-              value ? value.verbalise(role_name) : "nil"
-            }*", "
-        })"
+        irnv = self.class.identifying_role_names.map do |role_sym|
+            value = send(role_sym)
+            identifying_role_name = self.class.roles(role_sym).name.to_s.camelcase
+            value ? value.verbalise(identifying_role_name) : "nil"
+          end
+        "#{role_name || self.class.basename}(#{ irnv*', ' })"
       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)
-          }
+        self.class.identifying_role_names.map do |role_name|
+          send(role_name).identifying_role_values
+        end
       end
 
       # All classes that become Entity types receive the methods of this class as class methods:
       module ClassMethods
         include Instance::ClassMethods
 
+        attr_accessor :identification_inherited_from
+        attr_accessor :overrides_identification_of
+
         # Return the array of Role objects that define the identifying relationships of this Entity type:
         def identifying_role_names
-          @identifying_role_names ||= []
+          if identification_inherited_from
+            superclass.identifying_role_names
+          else
+            @identifying_role_names ||= []
+          end
         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"}"
+          # REVISIT: Should this return nil if identification_inherited_from?
+          @identifying_roles ||=
+            identifying_role_names.map do |role_name|
+              role = roles[role_name] || (!superclass.is_entity_type || superclass.roles[role_name])
               role
-            }
-          end
+            end
         end
 
-        # Convert the passed arguments into an array of Instance objects that can identify an instance of this Entity type:
+        # Convert the passed arguments into an array of raw values (or arrays of values, transitively)
+        # that 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}"
+          irns = identifying_role_names
 
           # 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
+          has_hash = args[-1].is_a?(Hash)
+          if (args.size == 1+(has_hash ?1:0) and (arg = args[0]).is_a?(self))
+            # With a secondary supertype or a subtype having separate identification,
+            # we would get the wrong identifier from arg.identifying_role_values:
+            return irns.map do |role_name|
+                # Use the identifier for the class expected, not the actual:
+                value = arg.send(role_name)
+                value && arg.class.roles(role_name).counterpart_object_type.identifying_role_values(value)
+              end
           end
 
-          ir = identifying_role_names
-          args, arg_hash = ActiveFacts::extract_hash_args(ir, args)
+          args, arg_hash = ActiveFacts::extract_hash_args(irns, args)
 
-          if args.size > ir.size
-            raise "You've provided too many values for the identifier of #{basename}, which expects (#{ir*', '})"
+          if args.size > irns.size
+            raise "You've provided too many values for the identifier of #{basename}, which expects (#{irns*', '})"
           end
 
-          role_args = ir.map{|role_sym| roles(role_sym)}.zip(args)
+          role_args = irns.map{|role_sym| roles(role_sym)}.zip(args)
           role_args.map do |role, arg|
-            #puts "Getting identifying_role_value for #{role.counterpart_object_type.basename} using #{arg.inspect}"
             next !!arg unless role.counterpart  # Unary
-            arg = arg.__getobj__ if RoleProxy === arg
-            if arg.is_a?(role.counterpart_object_type)              # 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
+            if arg.is_a?(role.counterpart.object_type)              # includes secondary supertypes
+              # With a secondary supertype or a type having separate identification,
+              # we would get the wrong identifier from arg.identifying_role_values:
+              next role.counterpart_object_type.identifying_role_values(arg)
             end
             if arg == nil # But not false
               if role.mandatory
-                raise "You must provide a #{role.counterpart_object_type.name} to identify a #{basename}"
+                raise "You must provide a #{role.counterpart.object_type.name} to identify a #{basename}"
               end
             else
               role.counterpart_object_type.identifying_role_values(*arg)
@@ -157,6 +184,10 @@ module ActiveFacts
           end
         end
 
+        # REVISIT: This method should verify that all identifying roles (including
+        # those required to identify any superclass) are present (if mandatory)
+        # and are unique... BEFORE it creates any new object(s)
+        # This is a hard problem because it's recursive.
         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.
@@ -166,37 +197,55 @@ module ActiveFacts
           # 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"}"
+          # REVISIT: This ignores any additional attribute assignments
           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_object_type)      # 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_object_type.assert_instance(constellation, Array(arg))
+          irns = identifying_role_names
+
+          has_hash = args[-1].is_a?(Hash)
+          if args.size == 1+(has_hash ?1:0) and args[0].is_a?(self)
+            # We received a single argument of a compatible type
+            # With a secondary supertype or a type having separate identification,
+            # we would get the wrong identifier from arg.identifying_role_values:
+            key = 
+              values = identifying_role_values(args[0])
+            values = values + [arg_hash = args.pop] if has_hash
+          else
+            args, arg_hash = ActiveFacts::extract_hash_args(irns, args)
+            roles_and_values = irns.map{|role_sym| roles(role_sym)}.zip(args)
+            key = []    # Gather the actual key (AutoCounters are special)
+            values = roles_and_values.map do |role, arg|
+                if role.unary?
+                  # REVISIT: This could be absorbed into a special counterpart.object_type.assert_instance
+                  value = role_key = arg ? true : arg   # Preserve false and nil
+                elsif !arg
+                  value = role_key = nil
+                else
+                  #trace :assert, "Asserting #{role.counterpart.object_type} with #{Array(arg).inspect} for #{self}.#{role.name}" do
+                    value, role_key = role.counterpart.object_type.assert_instance(constellation, Array(arg))
+                  #end
+                end
+                key << role_key
+                value
               end
-              key << role_key
-              value
-            end
-          values << arg_hash if arg_hash and !arg_hash.empty?
+            values << arg_hash if arg_hash and !arg_hash.empty?
+          end
 
-          #puts "Creating new #{basename} using #{values.inspect}"
-          instance = new(*values)
+          #trace :assert, "Constructing new #{self} with #{values.inspect}" do
+            instance = new(*values)
+          #end
 
           # Make the new entity instance a member of this constellation:
           instance.constellation = constellation
-          return *index_instance(instance, key, ir)
+
+          # Now assign any extra args in the hash which weren't identifiers (extra identifiers will be assigned again)
+          (arg_hash ? arg_hash.entries : []).each do |role_name, value|
+            role = roles(role_name)
+            instance.send(role.setter, value)
+          end
+
+          return *index_instance(instance, key, irns)
         end
 
         def index_instance(instance, key = nil, key_roles = nil) #:nodoc:
@@ -205,12 +254,12 @@ module ActiveFacts
             key = (key_roles = identifying_role_names).map do |role_name|
               instance.send role_name
             end
+            raise "You must pass values for #{key_roles.inspect} to identify a #{self.name}" if key.compact == []
           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|
@@ -223,18 +272,28 @@ module ActiveFacts
         # A object_type 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
+        def identified_by(*args) #:nodoc:
+          raise "You must list the roles which will identify #{self.basename}" unless args.size > 0
+
+          # Catch the case where we state the same identification as our superclass:
+          inherited_role_names = identifying_role_names
+          if !inherited_role_names.empty?
+            self.overrides_identification_of = superclass
+            while from = self.overrides_identification_of.identification_inherited_from
+              self.overrides_identification_of = from
+            end
+          end
+          return if inherited_role_names == args
+          self.identification_inherited_from = nil
+
+          # @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
         end
 
         def inherited(other) #:nodoc:
-          other.identified_by *identifying_role_names
+          other.identification_inherited_from = self
           subtypes << other unless subtypes.include? other
-          #puts "#{self.name} inherited by #{other.name}"
           vocabulary.__add_object_type(other)
         end
 
@@ -249,7 +308,6 @@ module ActiveFacts
 
         # Register ourselves with the parent module, which has become a Vocabulary:
         vocabulary = other.modspace
-        # puts "Entity.included(#{other.inspect})"
         unless vocabulary.respond_to? :object_type  # Extend module with Vocabulary if necessary
           vocabulary.send :extend, Vocabulary
         end