activefacts-api 0.9.3 → 0.9.4

data/TODO

@@ -1,4 +1,20 @@
 Performance
+	Each object type (class) needs fast access to:
+		Its identifying roles
+		Its supertypes that have alternate identification
+		The roles it plays in identifying other object types
+	Each one-to-many role needs:
+		A method to derive a counterpart (RoleValues) key from a full key
+	Each class needs
+		An adapt() method to convert offered values to a full key
+		an assign_all method
+			that can perform "atomic" identity change
+	Constellation needs assert_instance that for a given class:
+		adapts all keys from identifying values
+		checks either non-existence or uniqueness and type of the identified object for all such keys
+		instantiates the object if previously non-existent
+		(instantiates role subtypes by mixing in if this instance did not exist but the class is mixed in another extant object)
+		assigns non-identifying values
 	Pre-define ObjectType accessor methods on constellation, rather than using method_missing
 
 Role objects:

data/VERSION

@@ -1 +1 @@
-0.9.3
+0.9.4

data/activefacts-api.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "activefacts-api"
-  s.version = "0.9.3"
+  s.version = "0.9.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Clifford Heath"]
-  s.date = "2012-11-01"
+  s.date = "2013-01-14"
   s.description = "\nThe ActiveFacts API is a Ruby DSL for managing constellations of elementary facts.\nEach fact is either existential (a value or an entity), characteristic (boolean) or\nbinary relational (A rel B). Relational facts are consistently co-referenced, so you\ncan traverse them efficiently in any direction. Each constellation maintains constraints\nover the fact population.\n"
   s.email = "clifford.heath@gmail.com"
   s.extra_rdoc_files = [
@@ -29,6 +29,7 @@ Gem::Specification.new do |s|
     "activefacts-api.gemspec",
     "lib/activefacts/api.rb",
     "lib/activefacts/api/constellation.rb",
+    "lib/activefacts/api/date.rb",
     "lib/activefacts/api/entity.rb",
     "lib/activefacts/api/exceptions.rb",
     "lib/activefacts/api/guid.rb",
@@ -52,6 +53,7 @@ Gem::Specification.new do |s|
     "spec/identification_scheme/identification_spec.rb",
     "spec/identification_scheme/identity_change_spec.rb",
     "spec/identification_scheme/identity_supertype_change_spec.rb",
+    "spec/metadata_spec.rb",
     "spec/object_type/entity_type/entity_type_spec.rb",
     "spec/object_type/entity_type/multipart_identification_spec.rb",
     "spec/object_type/value_type/autocounter_spec.rb",

data/lib/activefacts/api/constellation.rb

@@ -33,25 +33,83 @@ module ActiveFacts
     #
     class Constellation
       attr_reader :vocabulary
-      # All instances are indexed in this hash, keyed by the class object.
+
+      def valid_object_type klass
+	klass.is_a?(Class) and klass.modspace == @vocabulary and klass.respond_to?(:assert_instance)
+      end
+
+      # "instances" is an index (keyed by the Class object) of indexes to instances.
       # 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| ... }
+      # The method_missing definition supports the syntax: c.MyClass.each{|k, v| ... }
+      def instances
+	@instances ||= Hash.new do |h,k|
+	    unless valid_object_type k
+	      raise "A constellation over #{@vocabulary.name} can only index instances of classes in that vocabulary, not #{k.inspect}"
+	    end
+	    h[k] = InstanceIndex.new(self, k)
+	  end
+      end
+
+      # Candidates is an array of object instances that do not already exist
+      # in the constellation but will be added if an assertion succeeds.
+      # After the assertion is found to be acceptable, these objects are indexed
+      # in the constellation and in the counterparts of their identifying roles,
+      # and the candidates array is nullified.
+      def with_candidates &b
+	# Multiple assignment reduces (s)teps while debugging
+	outermost, @candidates, @on_admission = @candidates.nil?, (@candidates || []), (@on_admission || [])
+	begin
+	  b.call
+	rescue Exception
+	  # Do not accept any of these candidates, there was a problem:
+	  @candidates = [] if outermost
+	  raise
+	ensure
+	  if outermost
+	    while @candidates
+	      # Index the accepted instances in the constellation:
+	      candidates = @candidates
+	      on_admission = @on_admission
+	      @candidates = nil
+	      @on_admission = nil
+	      candidates.each do |instance|
+		instance.class.index_instance(self, instance)
+	      end
+	      on_admission.each do |b|
+		b.call
+	      end
+	      # REVISIT: Admission should not create new candidates, but might start a fresh list
+	      # debugger if @candidates and @candidates.length > 0
+	    end
+	  end
+	end
+      end
+
+      def when_admitted &b
+	if @candidates.nil?
+	  b.call self
+	else
+	  @on_admission << b
+	end
+      end
+
+      def candidate instance
+	@candidates << instance unless @candidates[-1] == instance
+      end
+
+      def has_candidate klass, key
+	@candidates && @candidates.detect{|c| c.is_a?(klass) && c.identifying_role_values == key }
+      end
 
       # Create a new empty Constellation over the given Vocabulary
       def initialize(vocabulary)
         @vocabulary = vocabulary
-        @instances = Hash.new do |h,k|
-          unless k.is_a?(Class) and k.modspace == vocabulary
-            raise "A constellation over #{@vocabulary.name} can only index instances of classes in that vocabulary, not #{k.inspect}"
-          end
-          h[k] = InstanceIndex.new(self, k)
-        end
       end
 
-      def inspect #:nodoc:
-        "Constellation:#{object_id}"
+      def assert(klass, *args)
+	with_candidates do
+	  klass.assert_instance self, args
+	end
       end
 
       # Evaluate assertions against the population of this Constellation
@@ -68,6 +126,47 @@ module ActiveFacts
         self
       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 deindex_instance(instance) #:nodoc:
+        ([instance.class]+instance.class.supertypes_transitive).each do |klass|
+          instances[klass].delete(instance.identifying_role_values(klass))
+        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
+
+      def define_class_accessor m, klass
+	(class << self; self; end).
+	  send(:define_method, m) do |*args|
+	    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:
+	      assert(klass, *args)
+	    end
+	  end
+	end
+
+      # 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.
+      # With parameters, assert an instance of the object_type identified by the values passed as args.
+      def method_missing(m, *args, &b)
+        klass = @vocabulary.const_get(m)
+	if valid_object_type klass
+	  define_class_accessor m, klass
+          send(m, *args, &b)
+        else
+          super
+        end
+      end
+
+      def inspect #:nodoc:
+        "Constellation:#{object_id}"
+      end
+
       # Constellations verbalise all members of all classes in alphabetical order, showing
       # non-identifying role values as well
       def verbalise
@@ -88,8 +187,13 @@ module ActiveFacts
                   if (single_roles.size > 0)
                     role_values = 
                       single_roles.map{|role|
-                          [ role_name = role.to_s.camelcase,
-                            value = instance.send(role)]
+			  value =
+			    begin
+			      value = instance.send(role)
+			    rescue NoMethodError
+			      instance.class.roles(role) # This role has not yet been realised
+			    end
+			  [ role_name = role.to_s.camelcase, value ]
                         }.select{|role_name, value|
                           value
                         }.map{|role_name, value|
@@ -102,42 +206,6 @@ module ActiveFacts
           end.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
-
-      # 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.
-      # With parameters, assert an instance of the object_type identified by the values passed as args.
-      def method_missing(m, *args, &b)
-        klass = @vocabulary.const_get(m)
-        if klass 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
   end
 end

data/lib/activefacts/api/date.rb

@@ -0,0 +1,98 @@
+#
+#       ActiveFacts Runtime API
+#       Date hacks to handle immediate types.
+#
+# Copyright (c) 2013 Clifford Heath. Read the LICENSE file.
+#
+# Date and DateTime don't have a sensible new() method, so we monkey-patch one here.
+#
+require 'date'
+require 'time'
+
+# A Date can be constructed from any Date or DateTime subclass, or parsed from a String
+class ::Date
+  def self.new_instance constellation, *a, &b
+    if a[0].is_a?(String)
+      d = parse(*a)
+    elsif (a.size == 1)
+      case a[0]
+      when DateTime
+	d = civil(a[0].year, a[0].month, a[0].day, a[0].start)
+      when Date
+	d = civil(a[0].year, a[0].month, a[0].day, a[0].start)
+      when NilClass
+	d = civil()
+      else
+	d = civil(*a, &b)
+      end
+    else
+      d = civil(*a, &b)
+    end
+    d.send(:instance_variable_set, :@constellation, constellation)
+    d
+  end
+end
+
+# A DateTime can be constructed from any Date or DateTime subclass, or parsed from a String
+class ::DateTime
+
+  def self.new_instance constellation, *a, &b
+    if a[0].is_a?(String)
+      dt = parse(*a)
+    elsif (a.size == 1)
+      case a[0]
+      when DateTime
+	dt = civil(a[0].year, a[0].month, a[0].day, a[0].hour, a[0].min, a[0].sec, a[0].start)
+      when Date
+	dt = civil(a[0].year, a[0].month, a[0].day, 0, 0, 0, a[0].start)
+      when NilClass
+	dt = civil()
+      else
+	dt = civil(*a, &b)
+      end
+    else
+      dt = civil(*a, &b)
+    end
+    dt.send(:instance_variable_set, :@constellation, constellation)
+    dt
+  end
+
+end
+
+class ::Time
+  def identifying_role_values; self; end
+
+  def self.new_instance constellation, *a
+    t =
+      if a[0].is_a?(Time)
+       at(a[0])
+      else
+       begin
+         local(*a)
+       end
+      end
+
+=begin
+    if a[0].is_a?(String)
+      parse(*a)
+    elsif (a.size == 1)
+      case a[0]
+      when DateTime
+       a[0].clone
+      when Date
+       civil(a[0].year, a[0].month, a[0].day, 0, 0, 0, a[0].start)
+      when NilClass
+       civil()
+      else
+       civil(*a, &b)
+      end
+    else
+      civil(*a, &b)
+    end
+=end
+
+    t.send(:instance_variable_set, :@constellation, constellation)
+    t
+  end
+
+end

data/lib/activefacts/api/entity.rb

@@ -11,69 +11,61 @@ module ActiveFacts
     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.
+    private
+      # Initialise a new Entity instance.
       #
-      # A value must be provided for every identifying role, but if the
-      # last argument is a hash, they may come from there.
+      # arg_hash contains full-normalised and valid keys for the counterpart
+      # role values.
       #
-      # If a supertype (including a secondary supertype) has a different
-      # identifier, the identifying roles must be provided in the hash.
+      # This instance and its supertypes might have distinct identifiers,
+      # and none of the identifiers may already exist in the constellation.
       #
-      # Any additional (non-identifying) roles in the hash are ignored
-      def initialize(*args)
-        klass = self.class
-        while klass.identification_inherited_from
-          klass = klass.superclass
-        end
-
-        if args[-1].respond_to?(:has_key?) && args[-1].has_key?(:constellation)
-          @constellation = args.pop[:constellation]
-        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:
-        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 a single identifying role:
-        args = [args] if klass.identifying_role_names.size == 1 && args.size > 1
-
-        # 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. 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)
-          begin
-            send(role.setter, value)
-          rescue NoMethodError => e
-            raise settable_roles_exception(e, role_name)
-          end
+      # Pick out the identifying roles and assert the counterpart instances
+      # to assign as the new object's role values.
+      #
+      # The identifying roles of secondary supertypes must also be assigned
+      # here.
+      def initialize(arg_hash)
+	raise "REVISIT: Unexpected parameters in call to #{self}.new" unless arg_hash.is_a?(Hash)
+
+        super(arg_hash)
+
+        unless (klass = self.class).identification_inherited_from
+	  irns = klass.identifying_role_names
+	  irns.each do |role_name|
+	    role = klass.roles(role_name)
+	    key = arg_hash.delete(role_name)
+	    value =
+	      if key == nil
+		nil
+	      elsif role.is_unary
+		(key && true)	# Preserve nil and false
+	      else
+		role.counterpart.object_type.assert_instance(constellation, Array(key))
+	      end
+
+	    begin
+	      send(role.setter, value)
+#	    rescue NoMethodError => e
+#	      raise settable_roles_exception(e, role_name)
+	    end
+	    # instance_variable_set(role.setter, value)
+	  end
         end
       end
 
+=begin
+# I forget how it was possible to reproduce this exception,
+# so I can't get code coverage over it. It might not be still possible,
+# but I can't be sure so I'll leave the code here for now.
       def settable_roles_exception e, role_name
-        n = e.class.new(
-          "#{self.class} has no setter for #{role_name}.\n" +
+        n = NoMethodError.new(
+          "You cannot assert a #{self.class} until you define #{role_name}.\n" +
           "Settable roles are #{settable_roles*', '}.\n" +
           (if self.class.vocabulary.delayed.empty?
             ''
           else
-            "This could be because the following expected object types are still not defined: #{self.class.vocabulary.delayed.keys.sort*', '}\n"
+            "Please define these object types: #{self.class.vocabulary.delayed.keys.sort*', '}\n"
           end
           )
         )
@@ -92,7 +84,9 @@ module ActiveFacts
             end.
           flatten
       end
+=end
 
+    public
       def inspect #:nodoc:
         inc = constellation ? " in #{constellation.inspect}" : ""
         # REVISIT: Where there are one-to-one roles, this cycles
@@ -133,10 +127,11 @@ module ActiveFacts
         "#{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 do |role_name|
-          send(role_name).identifying_role_values
+      # Return the array of the values of this instance's identifying roles
+      def identifying_role_values(klass = self.class)
+        klass.identifying_role_names.map do |role_name|
+          value = send(role_name)
+	  value.identifying_role_values
         end
       end
 
@@ -193,160 +188,150 @@ module ActiveFacts
           end
         end
 
-        # 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)
-          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
-          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
-
-          args, arg_hash = ActiveFacts::extract_hash_args(irns, args)
-
-          if args.size > irns.size
-            raise "#{basename} expects only (#{irns*', '}) for its identifier, but you provided the extra values #{args[irns.size..-1].inspect}"
-          end
-
-          role_args = irns.map{|role_sym| roles(role_sym)}.zip(args)
-          role_args.map do |role, arg|
-            next !!arg unless role.counterpart  # Unary
-            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 MissingMandatoryRoleValueException.new(self, role)
-              end
-            else
-              role.counterpart_object_type.identifying_role_values(*arg)
-            end
-          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.
-          # 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]
-          @created_instances ||= []
-          if instance
-            # raise "Additional role values are ignored when asserting an existing instance" if args[-1].is_a? Hash and !args[-1].empty?
-            assign_additional_roles(instance, args[-1]) if args[-1].is_a? Hash and !args[-1].empty?
-            return instance, key      # A matching instance of this class
-          end
-
-          # Now construct each of this object's identifying roles
+	def check_supertype_identifiers_match instance, arg_hash
+	  supertypes_transitive.each do |supertype|
+	    supertype.identifying_role_names.each do |role_name|
+	      next unless arg_hash.include?(role_name)	  # No contradiction here
+	      new_value = arg_hash[role_name]
+	      existing_value = instance.send(role_name.to_sym)
+
+	      # Quick check for an exact match:
+	      next if existing_value == new_value or existing_value.identifying_role_values == new_value
+
+	      # Coerce the new value to identifying values for the counterpart role's type:
+	      role = supertype.roles(role_name)
+	      new_key = role.counterpart.object_type.identifying_role_values(instance.constellation, [new_value])
+	      # REVISIT: Check that the next line actually gets hit, otherwise strip it out
+	      next if existing_value == new_key	  # This can happen when the counterpart is a value type
+
+	      existing_key = existing_value.identifying_role_values
+	      next if existing_key.identifying_role_values == new_key
+	      raise TypeConflictException.new(basename, supertype, new_key, existing_key)
+	    end
+	  end
+	end
+
+	# all its candidate keys must match those from the arg_hash.
+	def check_no_supertype_instance_exists constellation, arg_hash
+	  supertypes_transitive.each do |supertype|
+	    key = supertype.identifying_role_values(constellation, [arg_hash])
+	    if constellation.instances[supertype][key]
+	      raise TypeMigrationException.new(basename, supertype, key)
+	    end
+	  end
+	end
+
+	# This method receives an array (possibly including a trailing arguments hash)
+	# from which the values of identifying roles must be coerced. Note that when a
+	# value which is not the corrent class is received, we recurse to ask that class
+	# to coerce what we *do* have.
+	# The return value is an array of (and arrays of) raw values, not object instances.
+	#
+	# No new instances may be asserted, nor may any roles of objects in the constellation be changed
+	def identifying_role_values(constellation, args)
           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
-=begin
-# REVISIT; These next few lines are bogus; they generate TypeError exceptions which are caught and ignored
-# A new approach will follow shortly which won't @create_instances that won't be needed
-                  if role.counterpart.object_type.is_entity_type
-                    add = !constellation.send(role.counterpart.object_type.basename.to_sym).include?([arg])
-                  else
-                    add = !constellation.send(role.counterpart.object_type.basename.to_sym).include?(arg)
-                  end
-=end
-                  value, role_key = role.counterpart.object_type.assert_instance(constellation, Array(arg))
-#                  @created_instances << [role.counterpart, value] if add
-                end
-                key << role_key
-                value
-              end
-            values << arg_hash if arg_hash and !arg_hash.empty?
-          end
-
-          #trace :assert, "Constructing new #{self} with #{values.inspect}" do
-          values << { :constellation => constellation }
-          instance = new(*values)
-          #end
-
-          assign_additional_roles(instance, arg_hash)
-
-          return *index_instance(instance, key, irns)
-
-        rescue DuplicateIdentifyingValueException
-          @created_instances.each do |role, v|
-            if !v.respond_to?(:retract)
-              v = constellation.send(role.object_type.basename.to_sym)[[v]]
-            end
-            v.retract if v
-          end
-          @created_instances = []
-          raise
-        end
-
-        def assign_additional_roles(instance, arg_hash)
-          # 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)
-
-            if !instance.instance_index_counterpart(role).include?(value)
-              @created_instances << [role, value]
-            end
-            instance.send(role.setter, value)
-          end
-        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
-            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
+	  # Normalise positional arguments into an arguments hash (this changes the passed parameter)
+	  arg_hash = args[-1].is_a?(Hash) ? args.pop : {}
+
+	  # If the first parameter is an object of type self, its
+	  # identifying roles provide any values missing from the array/hash.
+	  if args[0].is_a?(self)
+	    proto = args.shift
+	  end
+
+	  # Following arguments provide identifying values in sequence; put them into the hash:
+	  irns.each do |role_name|
+	    break if args.size == 0
+	    arg_hash[role_name] = args.shift
+	  end
+
+	  # Complain if we have left-over arguments
+	  if args.size > 0
+            raise "#{basename} expects only (#{irns*', '}) for its identifier, but you provided additional values #{args.inspect}"
+	  end
+
+	  # The arg_hash will be used to construct a new instance, if necessary
+	  args.push(arg_hash)
+
+	  irns.map do |role_name|
+	    roles(role_name)
+	  end.map do |role|
+	    if arg_hash.include?(n = role.name)	  # Do it this way to avoid problems where nil or false is provided
+	      value = arg_hash[n]
+	      next (value && true) if (role.is_unary)
+	      if value
+		klass = role.counterpart.object_type
+		value = klass.identifying_role_values(constellation, Array(value))
+	      end
+	    elsif proto
+	      value = proto.send(n)
+	      arg_hash[n] = value.identifying_role_values # Save the value for making a new instance
+	      next value if (role.is_unary)
+	    else
+	      value = nil
+	    end
+
+	    raise MissingMandatoryRoleValueException.new(self, role) if value.nil? && role.mandatory
+
+	    value
+	  end
+	end
+
+	def assert_instance(constellation, args)
+	  key = identifying_role_values(constellation, args)
+
+	  # The args is now normalized to an array containing a single Hash element
+	  arg_hash = args[-1]
+
+	  # Find or make an instance of the class:
+          instance_index = constellation.instances[self]   # All instances of this class in this constellation
+	  instance = constellation.has_candidate(self, key) || instance_index[key]
+	  if (instance)
+	    # Check that all assertions about supertype keys are non-contradictory
+	    check_supertype_identifiers_match(instance, arg_hash)
+	  else
+	    # Check that no instance of any supertype matches the keys given
+	    check_no_supertype_instance_exists(constellation, arg_hash)
+
+	    instance = new_instance(constellation, arg_hash)
+	    constellation.candidate(instance)
+	  end
+
+	  # Assign any extra roles that may have been passed.
+	  # An exception here leaves the object indexed,
+	  # but without the offending role (re-)assigned.
+	  arg_hash.each do |k, v|
+	    role = instance.class.roles(k)
+	    unless role.is_identifying && role.object_type == self
+	      value =
+		if v == nil
+		  nil
+		elsif role.is_unary
+		  (v && true)	# Preserve nil and false
+		else
+		  role.counterpart.object_type.assert_instance(constellation, Array(v))
+		end
+	      instance.send(:"#{k}=", value)
+	    end
+	  end
+
+	  instance
+	end
+
+        def index_instance(constellation, instance) #:nodoc:
+	  # Index the instance in the constellation's InstanceIndex for this class:
+	  instance_index = constellation.instances[self]
+	  key = instance.identifying_role_values(self)
+	  instance_index[key] = instance
 
           # Index the instance for each supertype:
-          supertypes.each do |supertype|
-            supertype.index_instance(instance, key, key_roles)
-          end
+	  supertypes.each do |supertype|
+	    supertype.index_instance(constellation, instance)
+	  end
 
-          return instance, key
-        end
+	  instance
+	end
 
         # 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
@@ -382,9 +367,16 @@ module ActiveFacts
         end
       end
 
-      def Entity.included other #:nodoc:
+      def self.included other #:nodoc:
         other.send :extend, ClassMethods
 
+	def other.new_instance constellation, *args
+	  instance = allocate
+	  instance.instance_variable_set("@constellation", constellation)
+	  instance.send(:initialize, *args)
+	  instance
+	end
+
         # Register ourselves with the parent module, which has become a Vocabulary:
         vocabulary = other.modspace
         unless vocabulary.respond_to? :object_type  # Extend module with Vocabulary if necessary