activefacts-api 0.9.5 → 0.9.6

data/VERSION

@@ -1 +1 @@
-0.9.5
+0.9.6

data/activefacts-api.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "activefacts-api"
-  s.version = "0.9.5"
+  s.version = "0.9.6"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Clifford Heath"]
-  s.date = "2013-01-16"
+  s.date = "2013-01-22"
   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 = [
@@ -62,7 +62,8 @@ Gem::Specification.new do |s|
     "spec/object_type/value_type/numeric_spec.rb",
     "spec/object_type/value_type/value_type_spec.rb",
     "spec/simplecov_helper.rb",
-    "spec/spec_helper.rb"
+    "spec/spec_helper.rb",
+    "spec/support/reduce_exceptions_helper.rb"
   ]
   s.homepage = "http://github.com/cjheath/activefacts-api"
   s.licenses = ["MIT"]

data/lib/activefacts/api/constellation.rb

@@ -34,8 +34,17 @@ module ActiveFacts
     class Constellation
       attr_reader :vocabulary
 
-      def valid_object_type klass
-	klass.is_a?(Class) and klass.modspace == @vocabulary and klass.respond_to?(:assert_instance)
+      def invalid_object_type klass
+	case
+	when !klass.is_a?(Class)
+	  'is not a Class'
+	when klass.modspace != @vocabulary
+	  "is defined in #{klass.modspace}, not #{@vocabulary.name}"
+	when !klass.respond_to?(:assert_instance)
+	  "is not declared as an object type"
+	else
+	  nil
+	end
       end
 
       # "instances" is an index (keyed by the Class object) of indexes to instances.
@@ -43,8 +52,8 @@ module ActiveFacts
       # 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}"
+	    if reason = invalid_object_type(k)
+	      raise InvalidObjectType.new(@vocabulary, k, reason)
 	    end
 	    h[k] = InstanceIndex.new(self, k)
 	  end
@@ -98,7 +107,7 @@ module ActiveFacts
       end
 
       def has_candidate klass, key
-	@candidates && @candidates.detect{|c| c.is_a?(klass) && c.identifying_role_values == key }
+	@candidates && @candidates.detect{|c| c.is_a?(klass) && c.identifying_role_values(klass) == key }
       end
 
       # Create a new empty Constellation over the given Vocabulary
@@ -155,11 +164,11 @@ module ActiveFacts
       # 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
+	if invalid_object_type klass
+	  super
+        else
 	  define_class_accessor m, klass
           send(m, *args, &b)
-        else
-          super
         end
       end
 
@@ -188,9 +197,9 @@ module ActiveFacts
                     role_values = 
                       single_roles.map{|role|
 			  value =
-			    begin
+			    if instance.respond_to?(role)
 			      value = instance.send(role)
-			    rescue NoMethodError
+			    else
 			      instance.class.roles(role) # This role has not yet been realised
 			    end
 			  [ role_name = role.to_s.camelcase, value ]

data/lib/activefacts/api/date.rb

@@ -60,7 +60,9 @@ class ::DateTime
 end
 
 class ::Time
-  def identifying_role_values; self; end
+  def identifying_role_values klass = nil
+    self
+  end
 
   def self.new_instance constellation, *a
     t =

data/lib/activefacts/api/entity.rb

@@ -26,7 +26,7 @@ module ActiveFacts
       # 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)
+	raise ArgumentError.new("#{self}.new expects a hash. You should use assert instead anyhow") unless arg_hash.is_a?(Hash)
 
         super(arg_hash)
 
@@ -129,9 +129,10 @@ module ActiveFacts
 
       # 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
+        klass.identifying_roles.map do |role|
+          value = send(role.name)
+	  counterpart_class = role.counterpart && role.counterpart.object_type
+          value.identifying_role_values(counterpart_class)
         end
       end
 
@@ -152,6 +153,56 @@ module ActiveFacts
         roles_hash
       end
 
+      # This role is identifying, so if is changed, not only
+      # must the current object be re-indexed, but also entities
+      # identified by this entity.  Save the current key and
+      # class for each such instance.
+      # This function is transitive!
+      def analyse_impacts role
+	impacts = []
+
+	# Consider the object itself and all its supertypes
+	([self.class]+self.class.supertypes_transitive).map do |supertype|
+	  next unless supertype.identifying_roles.include?(role)
+
+	  old_key = identifying_role_values(supertype)
+	  # puts "Need to reindex #{self.class} as #{supertype} from #{old_key.inspect}"
+	  impacts << [supertype, self, old_key]
+	end
+
+	# Now consider objects whose identifiers include this object.
+	# Find our roles in those identifiers first.
+	impacted_roles = []
+	self.class.all_roles.each do |n, role|
+	  if role.counterpart && role.counterpart.is_identifying
+	    # puts "Changing #{role.inspect} affects #{role.inspect}"
+	    impacted_roles << role
+	  end
+	end
+
+	impacted_roles.each do |role|
+	  affected_instances = Array(instance_variable_get(role.variable))
+	  # puts "considering #{affected_instances.size} #{role.object_type.name} instances that include #{role.inspect}: #{affected_instances.map(&:identifying_role_values).inspect}"
+	  affected_instances.each do |counterpart|
+	    impacts.concat(counterpart.analyse_impacts(role.counterpart))
+	  end
+	end
+	impacts
+      end
+
+      def apply_impacts impacts
+	impacts.each do |klass, entity, old_key|
+	  instance_index = entity.constellation.instances[klass]
+	  new_key = entity.identifying_role_values(klass)
+	  # puts "Reindexing #{klass} from #{old_key.inspect} to #{new_key.inspect}"
+
+	  if new_key != old_key
+	    instance_index.delete(old_key)
+	    instance_index[new_key] = entity
+	  end
+	end
+      end
+
       # All classes that become Entity types receive the methods of this class as class methods:
       module ClassMethods
         include Instance::ClassMethods
@@ -190,21 +241,22 @@ module ActiveFacts
 
 	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)
+	    supertype.identifying_roles.each do |role|
+	      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
+	      counterpart_class = role.counterpart && role.counterpart.object_type
+	      next if existing_value == new_value or existing_value.identifying_role_values(counterpart_class) == new_value
 
 	      # Coerce the new value to identifying values for the counterpart role's type:
-	      role = supertype.roles(role_name)
+	      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
+	      existing_key = existing_value.identifying_role_values(counterpart_class)
 	      next if existing_key == new_key
 	      raise TypeConflictException.new(basename, supertype, new_key, existing_key)
 	    end
@@ -248,7 +300,7 @@ module ActiveFacts
 
 	  # 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}"
+            raise UnexpectedIdentifyingValueException.new(self, irns, args)
 	  end
 
 	  # The arg_hash will be used to construct a new instance, if necessary
@@ -266,7 +318,8 @@ module ActiveFacts
 	      end
 	    elsif proto
 	      value = proto.send(n)
-	      value = value.identifying_role_values
+	      counterpart_class = role.counterpart && role.counterpart.object_type
+	      value = value.identifying_role_values(counterpart_class)
 	      arg_hash[n] = value # Save the value for making a new instance
 	      next value if (role.is_unary)
 	    else
@@ -338,7 +391,7 @@ module ActiveFacts
         # which is a list of roles it plays. The identification scheme may be
         # inherited from a superclass.
         def identified_by(*args) #:nodoc:
-          raise "You must list the roles which will identify #{self.basename}" unless args.size > 0
+          raise MissingIdentificationException.new(self) unless args.size > 0
 
           # Catch the case where we state the same identification as our superclass:
           inherited_role_names = identifying_role_names

data/lib/activefacts/api/exceptions.rb

@@ -9,31 +9,79 @@ module ActiveFacts
     class ActiveFactsException < StandardError
     end
 
-    class ActiveFactsSchemaException < ActiveFactsException
+    class SchemaException < ActiveFactsException
     end
 
-    class ActiveFactsRuntimeException < ActiveFactsException
+    class RuntimeException < ActiveFactsException
     end
 
-    class CrossVocabularyRoleException < ActiveFactsSchemaException
+    class CrossVocabularyRoleException < SchemaException
       def initialize klass, vocabulary
         super "#{klass} must be an object type in #{vocabulary.name}"
       end
     end
 
-    class RoleNotDefinedException < ActiveFactsRuntimeException
+    class InvalidEntityException < SchemaException
+      def initialize klass
+	super "#{klass.basename} may not be an entity type"
+      end
+    end
+
+    class InvalidIdentificationException < SchemaException
+      def initialize object_type, role, is_single
+	msg =
+	  if is_single
+	    "#{object_type} has a single identifying role '#{role}' which is has_one, but must be one_to_one"
+	  else
+	    raise "#{object_type} has an identifying role '#{role}' which is one_to_one, but must be has_one"
+	  end
+	super msg
+      end
+    end
+
+    class MissingIdentificationException < SchemaException
+      def initialize klass
+	super "You must list the roles which will identify #{klass.basename}"
+      end
+    end
+
+    class InvalidObjectType < SchemaException
+      def initialize vocabulary, klass, reason
+	raise "A constellation over #{vocabulary.name} cannot index instances of #{klass} because it #{reason}"
+      end
+    end
+
+    class InvalidSupertypeException < SchemaException
+    end
+
+    class DuplicateRoleException < SchemaException
+    end
+
+    class UnrecognisedOptionsException < SchemaException
+      def initialize declaration, instance, option_names
+        raise "Unrecognised options on declaration of #{declaration} #{instance}: #{option_names.inspect}"
+      end
+    end
+
+    class RoleNotDefinedException < RuntimeException
       def initialize klass, role_name
         super "Role #{klass.basename}.#{role_name} is not defined"
       end
     end
 
-    class MissingMandatoryRoleValueException < ActiveFactsRuntimeException
+    class UnexpectedIdentifyingValueException < RuntimeException
+      def initialize object_type, identifying_role_names, extra_args
+	super "#{object_type.basename} expects only (#{identifying_role_names*', '}) for its identifier, but you provided additional values #{extra_args.inspect}"
+      end
+    end
+
+    class MissingMandatoryRoleValueException < RuntimeException
       def initialize klass, role
         super "A #{role.counterpart.object_type.basename} is required to satisfy the #{role.name.inspect} role of #{klass.basename}"
       end
     end
 
-    class DuplicateIdentifyingValueException < ActiveFactsRuntimeException
+    class DuplicateIdentifyingValueException < RuntimeException
       def initialize(klass, role_name, value)
         super("Illegal attempt to assert #{klass.basename} having identifying value" +
               " (#{role_name} is #{value.verbalise})," +
@@ -42,14 +90,14 @@ module ActiveFacts
     end
 
     # When an existing object having multiple identification patterns is re-asserted, all the keys must match the existing object
-    class TypeConflictException < ActiveFactsRuntimeException
+    class TypeConflictException < RuntimeException
       def initialize(klass, supertype, key, existing)
 	super "#{klass} cannot be asserted to have #{supertype} identifier #{key.inspect} because the existing object has #{existing.inspect}"
       end
     end
 
     # When a new entity is asserted, but a supertype identifier matches an existing object of a different type, type migration is implied but unfortunately is impossible in Ruby
-    class TypeMigrationException < ActiveFactsRuntimeException
+    class TypeMigrationException < RuntimeException
       def initialize(klass, supertype, key)
 	super "#{klass} cannot be asserted due to the prior existence of a conflicting #{supertype} identified by #{key.inspect}"
       end

data/lib/activefacts/api/guid.rb

@@ -16,7 +16,7 @@ class Guid
     elsif (v = i.to_s).length == 36 and !(v !~ /[^0-9a-f]/i)
       @value = v.clone.freeze
     else
-      raise "Illegal non-Guid value #{i.inspect} given for Guid"
+      raise ArgumentError.new("Illegal non-Guid value #{i.inspect} given for Guid")
     end
   end
 

data/lib/activefacts/api/instance.rb

@@ -34,19 +34,20 @@ module ActiveFacts
 
       # If this instance's role is updated to the new value, does that cause a collision?
       # We need to check each superclass that has a different identification pattern
-      def check_value_change_legality(role, value)
+      def check_identification_change_legality(role, value)
         return unless @constellation && role.is_identifying
 
 	klasses = [self.class] + self.class.supertypes_transitive
 	last_identity = nil
 	last_irns = nil
+	counterpart_class = role.counterpart ? role.counterpart.object_type : value.class
         duplicate = klasses.detect do |klass|
           next false unless klass.identifying_roles.include?(role)
 	  irns = klass.identifying_role_names
 	  if last_irns != irns
 	    last_identity = identifying_role_values(klass)
 	    role_position = irns.index(role.name)
-	    last_identity[role_position] = value.identifying_role_values
+	    last_identity[role_position] = value.identifying_role_values(counterpart_class)
 	  end
 	  @constellation.instances[klass][last_identity]
         end
@@ -90,11 +91,19 @@ module ActiveFacts
 	    # Objects being created do not have to have non-identifying mandatory roles,
 	    # so we allow retracting to the same state.
             if role.unique
+	      i = send(role.getter)
+	      next unless i
 	      if counterpart.is_identifying && counterpart.mandatory
-		i = send(role.name) and i.retract
+		i.retract
 	      else
-		send role.setter, nil
+		if (counterpart.unique)
+		  # REVISIT: This will incorrectly fail to propagate a key change for a non-mandatory role
+		  i.send(counterpart.setter, nil, false)
+		else
+		  i.send(role.counterpart.getter).update(self, nil)
+		end
 	      end
+	      instance_variable_set(role.variable, nil)
             else
               # puts "Not removing role #{role_name} from counterpart RoleValues #{counterpart.name}"
               # Duplicate the array using to_a, as the RoleValues here will be modified as we traverse it:
@@ -104,9 +113,10 @@ module ActiveFacts
                 if counterpart.is_identifying && counterpart.mandatory
                   counterpart_instance.retract
                 else
-                  counterpart_instance.send(counterpart.setter, nil)
+                  counterpart_instance.send(counterpart.setter, nil, false)
                 end
               end
+	      instance_variable_set(role.variable, nil)
             end
           end
         end

data/lib/activefacts/api/instance_index.rb

@@ -43,7 +43,7 @@ module ActiveFacts
 
       def refresh_key(key)
         value = @hash.delete(key)
-        @hash[value.identifying_role_values] = value if value
+        @hash[value.identifying_role_values(@klass)] = value if value
       end
     end
   end

data/lib/activefacts/api/numeric.rb

@@ -116,7 +116,7 @@ class AutoCounter
   attr_reader :place_holder_number
   def initialize(i = :new)
     unless i == :new or i.is_a?(Integer) or i.is_a?(AutoCounter)
-      raise "AutoCounter #{self.class} may not be #{i.inspect}"
+      raise ArgumentError.new("AutoCounter #{self.class} may not be #{i.inspect}")
     end
     @@place_holder ||= 0
     case i
@@ -191,7 +191,7 @@ class AutoCounter
     to_s.eql?(o.to_s)
   end
 
-  def identifying_role_values
+  def identifying_role_values klass = nil
     self
   end
 

data/lib/activefacts/api/object_type.rb

@@ -46,6 +46,15 @@ module ActiveFacts
         end
       end
 
+      def all_roles
+	return @all_roles if @all_roles
+	@all_roles = roles.dup
+	supertypes_transitive.each do |klass|
+	  @all_roles.merge!(klass.roles)
+	end
+	@all_roles
+      end
+
       # Define a unary fact type attached to this object_type; in essence, a boolean attribute.
       #
       # Example: maybe :is_ceo
@@ -91,11 +100,11 @@ module ActiveFacts
           case type
           when :has_one
             if identifying_role_names.size == 1
-              raise "Entity type #{self} cannot be identified by a single role '#{role}' unless that role is one_to_one"
+	      raise InvalidIdentificationException.new(self, role, true)
             end
           when :one_to_one
             if identifying_role_names.size > 1
-              raise "Entity type #{self} cannot be identified by a single role '#{role}' unless that role is has_one"
+	      raise InvalidIdentificationException.new(self, role, false)
             end
           end
         end
@@ -120,12 +129,14 @@ module ActiveFacts
 	      # No late binding here:
 	      (object_type = vocabulary.const_get(object_type.to_s.camelcase))
 	    else
-	      raise "Illegal supertype #{object_type.inspect} for #{self.class.basename}"
+	      raise InvalidSupertypeException.new("Illegal supertype #{object_type.inspect} for #{self.class.basename}")
 	    end
-	  raise "#{supertype.name} must be an object type in #{vocabulary.name}" unless supertype.respond_to?(:vocabulary) and supertype.vocabulary == self.vocabulary
+	  unless supertype.respond_to?(:vocabulary) and supertype.vocabulary == self.vocabulary
+	    raise InvalidSupertypeException.new("#{supertype.name} must be an object type in #{vocabulary.name}")
+	  end
 
 	  if is_entity_type != supertype.is_entity_type
-	    raise "#{self} < #{supertype}: A value type may not be a supertype of an entity type, and vice versa"
+	    raise InvalidSupertypeException.new("#{self} < #{supertype}: A value type may not be a supertype of an entity type, and vice versa")
 	  end
 
 	  @supertypes << supertype
@@ -194,8 +205,11 @@ module ActiveFacts
 
       # Shared code for both kinds of binary fact type (has_one and one_to_one)
       def define_binary_fact_type(one_to_one, role_name, related, mandatory, related_role_name)
-        # REVISIT: What if the role exists on a supertype? This won't prevent that:
-        raise "#{name} cannot have more than one role named #{role_name}" if roles[role_name]
+	# REVISIT: This should be all_roles, to catch duplicate role name in a supertype
+	# if all_roles[role_name]
+	if roles[role_name]
+	  raise DuplicateRoleException.new("#{name} cannot have more than one role named #{role_name}")
+	end
         roles[role_name] = role = Role.new(self, nil, role_name, mandatory)
 
         # There may be a forward reference here where role_name is a Symbol,
@@ -228,7 +242,9 @@ module ActiveFacts
 
       def define_single_role_getter(role)
 	define_method role.getter do |*a|
-	  raise "Parameters passed to #{self.class.name}\##{role.name}" if a.size > 0
+	  if a.size > 0
+	    raise ArgumentError.new("wrong number of arguments (#{a.size} for 0)")
+	  end
 	  instance_variable_get(role.variable)
 	end
       end
@@ -236,46 +252,40 @@ module ActiveFacts
       def define_one_to_one_accessor(role)
         define_single_role_getter(role)
 
-	define_method role.setter do |value|
-	  old = instance_variable_get(role.variable)
+	# What I want is the following, but it doesn't work in Ruby 1.8
+	# define_method role.setter do |value, mutual_propagation = true|
+	define_method role.setter do |*a|
+	  value, mutual_propagation = *a
+	  mutual_propagation = true if a.size < 2
+	  role_var = role.variable
 
-	  # When exactly the same value instance is assigned, we're done:
-	  return true if old == value
+	  # Get old value, and jump out early if it's unchanged:
+	  old = instance_variable_get(role_var)
+	  return value if old == value
 
+	  # assert a new instance for the role value if necessary
 	  if value and o = role.counterpart.object_type and (!value.is_a?(o) || value.constellation != @constellation)
 	    value = @constellation.assert(o, *Array(value))
-	    # return true if old.equal?(value)         # Occurs when same value but not same instance is assigned
-	    return true if old == value
+	    return value if old == value
 	  end
 
-	  dependent_entities = nil
-	  if (role.is_identifying)
-	    check_value_change_legality(role, value)
+	  if (role.is_identifying)	# We're changing this object's key. Check legality and prepare to propagate
+	    check_identification_change_legality(role, value)
 
-	    # We're changing this object's key.
-	    # Find all object which are identified by this object, and save their old keys
-	    if @constellation && old
-	      dependent_entities = old.related_entities.map do |entity|
-		[entity.identifying_role_values, entity]
-	      end
-	    end
+	    # puts "Starting to analyse impact of changing 1-1 #{role.inspect} to #{value.inspect}"
+	    impacts = analyse_impacts(role)
 	  end
 
-	  instance_variable_set(role.variable, value)
+	  instance_variable_set(role_var, value)
 
 	  # Remove self from the old counterpart:
-	  old.send(role.counterpart.setter, nil) if old
+	  old.send(role.counterpart.setter, nil, false) if old and mutual_propagation
 
 	  @constellation.when_admitted do
 	    # Assign self to the new counterpart
 	    value.send(role.counterpart.setter, self) if value
 
-	    # Propagate dependent key changes
-	    if dependent_entities
-	      dependent_entities.each do |old_key, entity|
-		entity.instance_index.refresh_key(old_key)
-	      end
-	    end
+	    apply_impacts(impacts) if impacts	# Propagate dependent key changes
 	  end
 
 	  value
@@ -285,46 +295,40 @@ module ActiveFacts
       def define_one_to_many_accessor(role)
         define_single_role_getter(role)
 
-	define_method role.setter do |value|
+	# What I want is the following, but it doesn't work in Ruby 1.8
+	# define_method role.setter do |value, mutual_propagation = true|
+	define_method role.setter do |*a|
+	  value, mutual_propagation = *a
+	  mutual_propagation = true if a.size < 2
 	  role_var = role.variable
 
 	  # Get old value, and jump out early if it's unchanged:
 	  old = instance_variable_get(role_var)
-	  return value if old.equal?(value)         # Occurs during one_to_one assignment, for example
+	  return value if old == value
 
 	  # assert a new instance for the role value if necessary
 	  if value and o = role.counterpart.object_type and (!value.is_a?(o) || value.constellation != @constellation)
 	    value = @constellation.assert(o, *Array(value))
-	    return value if old.equal?(value)         # Occurs when another instance having the same value is assigned
+	    return value if old == value	# Occurs when another instance having the same value is assigned
 	  end
 
-	  dependent_entities = nil
-	  if (role.is_identifying)
-	    check_value_change_legality(role, value) if value
+	  if (role.is_identifying)	# We're changing this object's key. Check legality and prepare to propagate
+	    check_identification_change_legality(role, value)
 
-	    if old && old.constellation
-	      # If our identity has changed and we identify others, prepare to reindex them
-	      dependent_entities = old.related_entities.map do |entity|
-		[entity.identifying_role_values, entity]
-	      end
-	    end
+	    # puts "Starting to analyse impact of changing 1-N #{role.inspect} to #{value.inspect}"
+	    impacts = analyse_impacts(role)
 	  end
 
 	  instance_variable_set(role_var, value)
 
 	  # Remove "self" from the old counterpart:
-	  old.send(getter = role.counterpart.getter).update(self, nil) if old
+	  old.send(getter = role.counterpart.getter).update(self, nil) if old && mutual_propagation
 
 	  @constellation.when_admitted do
-	    # REVISIT: Delay co-referencing here if the object is still a candidate
 	    # Add "self" into the counterpart
 	    value.send(getter ||= role.counterpart.getter).update(old, self) if value
 
-	    if dependent_entities
-	      dependent_entities.each do |key, entity|
-		entity.instance_index.refresh_key(key)
-	      end
-	    end
+	    apply_impacts(impacts) if impacts	# Propagate dependent key changes
 	  end
 
 	  value
@@ -391,7 +395,7 @@ module ActiveFacts
           related = related_name
           related_name = related_name.to_s.snakecase
         else
-          raise "Invalid type for :class option on :#{role_name}"
+          raise ArgumentError.new("Invalid type #{related_name.class} for :class option on :#{role_name}, must be a Class, Symbol or String")
         end
 
         # resolve the Symbol to a Class now if possible:
@@ -412,11 +416,15 @@ module ActiveFacts
         reading = options.delete(:reading)        # REVISIT: Implement verbalisation
         role_value_constraint = options.delete(:restrict)   # REVISIT: Implement role value constraints
 
-        raise "Unrecognised options on #{role_name}: #{options.keys.inspect}" unless options.empty?
+	additional_role_options options
+
+	raise UnrecognisedOptionsException.new("role", role_name, options.keys) unless options.empty?
 
-        # Avoid a confusing mismatch:
-        # Note that if you have a role "supervisor" and a sub-class "Supervisor", this'll bitch.
-        if (!specified_class && Class === related && (indicated = vocabulary.object_type(role_name)) && indicated != related)
+        # If you have a role "supervisor" and a sub-class "Supervisor", this'll bitch.
+        if !specified_class and		# No specified :class was provided
+	    related.is_a?(Class) and
+	    (indicated = vocabulary.object_type(role_name)) and
+	    indicated != related
           raise "Role name #{role_name} indicates a different counterpart object_type #{indicated} than specified"
         end
 
@@ -439,6 +447,10 @@ module ActiveFacts
         ]
       end
 
+      def additional_role_options options
+	# This is a hook for extensions to override. Any extension options should be deleted from the options hash.
+      end
+
       def when_bound(object_type, *args, &block)
         case object_type
         when Class

data/lib/activefacts/api/standard_types.rb

@@ -33,19 +33,25 @@ ValueClasses.each{|c|
 # Cannot subclass or delegate True, False or nil, so inject the required behaviour
 class TrueClass #:nodoc:
   def verbalise(role_name = nil); role_name ? "#{role_name}: true" : "true"; end
-  def identifying_role_values; self; end
+  def identifying_role_values klass = nil
+    self
+  end
   def self.identifying_role_values(*a); a.replace([{}]); true end
 end
 
 class FalseClass #:nodoc:
   def verbalise(role_name = nil); role_name ? "#{role_name}: false" : "false"; end
-  def identifying_role_values; self; end
+  def identifying_role_values klass = nil
+    self
+  end
   def self.identifying_role_values(*a); a.replace([{}]); false end
 end
 
 class NilClass #:nodoc:
   def verbalise; "nil"; end
-  def identifying_role_values; self; end
+  def identifying_role_values klass = nil
+    self
+  end
   def self.identifying_role_values(*a); a.replace([{}]); nil end
 end
 
@@ -53,7 +59,7 @@ class Class
   # Make this Class into a ObjectType and if necessary its module into a Vocabulary.
   # The parameters are the names (Symbols) of the identifying roles.
   def identified_by *args, &b
-    raise "#{basename} is not an entity type" if respond_to? :value_type  # Don't make a ValueType into an EntityType
+    raise InvalidEntityException(self) if respond_to? :value_type  # Don't make a ValueType into an EntityType
 
     # The inclusion of instance methods triggers ClassMethods to be included in the class too
     include ActiveFacts::API::Entity

data/lib/activefacts/api/value.rb

@@ -28,9 +28,8 @@ module ActiveFacts
 
       # A value is its own key, unless it's a delegate for a raw value
       def identifying_role_values(klass = nil) #:nodoc:
-	# The identifying role value for the supertype of a value type is always the same as for the subtype:
-	# raise "Value Types cannot return identifying_role_values for supertypes" if klass and klass != self.class
-        __getobj__ rescue self
+	# The identifying role value for the supertype of a value type is always the same as for the subtype
+	respond_to?(:__getobj__) ? __getobj__ : self
       end
 
       # All ValueType classes include the methods defined here
@@ -41,7 +40,7 @@ module ActiveFacts
           # REVISIT: args could be a hash, with keys :length, :scale, :unit, :allow
           options = (args[-1].is_a?(Hash) ? args.pop : {})
           options.each do |key, value|
-            raise "unknown value type option #{key}" unless respond_to?(key)
+	    raise UnrecognisedOptionsException.new('value_type', basename, key) unless respond_to?(key)
             send(key, value)
           end
         end
@@ -84,7 +83,7 @@ module ActiveFacts
 	    instance = new_instance(constellation, *args)
           end
 	  args.replace([arg_hash])
-	  instance.identifying_role_values
+	  instance.identifying_role_values(self)
         end
 
 	def assert_instance(constellation, args)
@@ -116,7 +115,7 @@ module ActiveFacts
         def index_instance(constellation, instance) #:nodoc:
 	  # Index the instance in the constellation's InstanceIndex for this class:
           instances = constellation.instances[self]
-          key = instance.identifying_role_values
+          key = instance.identifying_role_values(self)
           instances[key] = instance
 
           # Index the instance for each supertype:

data/lib/activefacts/api/vocabulary.rb

@@ -32,11 +32,15 @@ module ActiveFacts
           __bind(camel)
           c
         else
-          begin
-            const_get(camel)
-          rescue NameError
-            nil
-          end
+	  if defined?(camel)
+	    begin
+	      const_get(camel)
+	    rescue NameError
+	      nil
+	    end
+	  else
+	    nil
+	  end
         end
       end
 

data/spec/constellation/constellation_spec.rb

@@ -84,8 +84,8 @@ describe "A Constellation instance" do
 
   it "should complain when accessing a class that isn't an object type" do
     class Mod::Bar; end
-    lambda { @constellation.Bar }.should raise_error
-    lambda { @constellation.instances.Bar }.should raise_error
+    proc { @constellation.Bar }.should raise_error
+    proc { @constellation.instances[Mod::Bar] }.should raise_error
   end
 
   it "should deny handling an object type defined outside the current module" do
@@ -200,7 +200,7 @@ describe "A Constellation instance" do
 
   it "Should raise an exception with assigning a role whose referent (object type) has not yet been defined" do
     n = @constellation.Name("Fred")
-    # This does n;t raise the "settable_roles_exception". I'm no longer sure how I did this, so I can't get coverage on this code :(
+    # This does not raise the "settable_roles_exception". I'm no longer sure how I did this, so I can't get coverage on this code :(
     proc { n.undefined_role = 'foo' }.should raise_error
   end
 
@@ -447,7 +447,7 @@ describe "A Constellation instance" do
           supertypes Bignum
         end
       end
-    }.should raise_error(RuntimeError)
+    }.should raise_error(ActiveFacts::API::InvalidSupertypeException)
 
     lambda {
       module Mod
@@ -455,7 +455,7 @@ describe "A Constellation instance" do
           supertypes 3
         end
       end
-    }.should raise_error(RuntimeError)
+    }.should raise_error(ActiveFacts::API::InvalidSupertypeException)
   end
 
   it "should allow supertypes with supertypes" do

data/spec/fact_type/role_values_spec.rb

@@ -160,7 +160,7 @@ describe "Object type role values" do
         instances.map{|k,o| o}.first.should == object
         unless object.class.is_entity_type
           # Look up value types using the value instance, not just the raw value:
-          instances[object].should == object
+          instances[object.identifying_role_values].should == object
         end
 
         # Make sure all the identifying roles are populated correctly:

data/spec/identification_scheme/identification_spec.rb

@@ -254,7 +254,7 @@ describe "An Entity Type" do
 
       it "should assert the identifying values" do
         @rn.should be_a(Mod::Number)
-        @c.Number[@rn].should == @rn    # Yes
+        @c.Number[@rn.identifying_role_values].should == @rn    # Yes
         @c.Number[101].should == @rn    # No
         @c.Number[101].should be_eql 101    # No
       end

data/spec/metadata_spec.rb

@@ -15,6 +15,7 @@ describe "In a vocabulary" do
   ObjectType_methods = [
     :has_one, :maybe, :one_to_one,
     :roles, :subtypes, :supertypes, :vocabulary,
+    :all_roles,
     # To make private:
     :check_identifying_role_has_valid_cardinality, :realise_role, :supertypes_transitive,
   ]
@@ -27,7 +28,7 @@ describe "In a vocabulary" do
   Instance_methods = [
     :constellation, :retract, :is_a?,
     # To remove or move to EntityType
-    :related_entities, :check_value_change_legality,
+    :related_entities, :check_identification_change_legality,
     :instance_index
   ]
   Value_methods = Instance_methods + [

data/spec/spec_helper.rb

@@ -9,4 +9,5 @@ Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
 
 RSpec.configure do |config|
   
-end
+end
+

data/spec/support/reduce_exceptions_helper.rb

@@ -0,0 +1,29 @@
+if ENV["RSPEC_REPORT_EXCEPTIONS"]
+  class Exception
+    alias_method :old_initialize, :initialize
+
+    def self.exceptions_seen
+      @@seen ||= {}
+    end
+
+    def self.see args
+      stack = caller[1..-1]
+      # Don't show expected exceptions or RSpec internal ones
+      return if caller.detect{|s| s =~ %r{rspec/matchers/raise_error}} or
+	self.name =~ /^RSpec::/
+      stack.reject!{|s| s =~ %r{/rspec/}}
+      key = stack[0,4]+[self.name]
+      return if exceptions_seen[key]
+
+      exceptions_seen[key] = show = stack
+      args[0] = args[0].to_str if args[0].class.name == "NameError::message"
+      puts "#{self.name}#{args.inspect}:\n\t#{show*"\n\t"}"
+    end
+
+    def initialize *args, &b
+      self.class.see args
+
+      send(:old_initialize, *args, &b)
+    end
+  end
+end

metadata

@@ -1,199 +1,190 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: activefacts-api
-version: !ruby/object:Gem::Version
-  version: 0.9.5
+version: !ruby/object:Gem::Version 
+  hash: 55
   prerelease: 
+  segments: 
+  - 0
+  - 9
+  - 6
+  version: 0.9.6
 platform: ruby
-authors:
+authors: 
 - Clifford Heath
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-16 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
+
+date: 2013-01-22 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
   name: rake
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  type: :development
+  requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
   name: jeweler
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  type: :development
+  requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
   name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: 2.6.0
-  type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  type: :development
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 2
+        - 6
+        - 0
         version: 2.6.0
-- !ruby/object:Gem::Dependency
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
   name: ruby-debug
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  type: :development
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
   name: debugger
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  type: :development
+  requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
   name: pry
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  type: :development
+  requirement: &id006 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
   name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: 2.3.0
-  type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  type: :development
+  requirement: &id007 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 2
+        - 3
+        - 0
         version: 2.3.0
-- !ruby/object:Gem::Dependency
+  version_requirements: *id007
+- !ruby/object:Gem::Dependency 
   name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: 1.0.0
-  type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  type: :development
+  requirement: &id008 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 0
+        - 0
         version: 1.0.0
-- !ruby/object:Gem::Dependency
+  version_requirements: *id008
+- !ruby/object:Gem::Dependency 
   name: jeweler
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: 1.5.2
-  type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  type: :development
+  requirement: &id009 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
+    requirements: 
     - - ~>
-      - !ruby/object:Gem::Version
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 1
+        - 5
+        - 2
         version: 1.5.2
-- !ruby/object:Gem::Dependency
+  version_requirements: *id009
+- !ruby/object:Gem::Dependency 
   name: rdoc
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 2.4.2
-  type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  type: :development
+  requirement: &id010 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 2
+        - 4
+        - 2
         version: 2.4.2
-description: ! '
-
+  version_requirements: *id010
+description: |
+  
   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
-
-  binary relational (A rel B). Relational facts are consistently co-referenced, so
-  you
-
+  Each fact is either existential (a value or an entity), characteristic (boolean) or
+  binary relational (A rel B). Relational facts are consistently co-referenced, so you
   can traverse them efficiently in any direction. Each constellation maintains constraints
-
   over the fact population.
 
-'
 email: clifford.heath@gmail.com
 executables: []
+
 extensions: []
-extra_rdoc_files:
+
+extra_rdoc_files: 
 - LICENSE.txt
 - README.rdoc
 - TODO
-files:
+files: 
 - .document
 - .rspec
 - .travis.yml
@@ -239,33 +230,40 @@ files:
 - spec/object_type/value_type/value_type_spec.rb
 - spec/simplecov_helper.rb
 - spec/spec_helper.rb
+- spec/support/reduce_exceptions_helper.rb
 - TODO
 homepage: http://github.com/cjheath/activefacts-api
-licenses:
+licenses: 
 - MIT
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
+required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-      segments:
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
       - 0
-      hash: 1210306376532031473
-required_rubygems_version: !ruby/object:Gem::Requirement
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
 requirements: []
+
 rubyforge_project: 
 rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: A fact-based data model DSL and API
 test_files: []
+