activefacts-api 0.9.9 → 1.0.0

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: d98f2a57181b4caad266b2b2aee333fe9f685835
-  data.tar.gz: 8d32f6cb29ad9020d0e4ddc268bee3dc59cd7b9f
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MDI2NTVhZWJlYmU5NDhlNmFlZTg5ZjBkNzY2YTMxMDI2MjJiYWRlZA==
+  data.tar.gz: !binary |-
+    NzJjODlmMmNjZjgxMmIxNzFkZmJkZjNmMGYyZDNkOGZkMTIxNGRhYg==
 SHA512:
-  metadata.gz: a1f5f6c8d57a313f4185690394f93d6ff467849c311d790f5b7cb72f2da0676a3ee81d7edaa2595bf4d9fd5389393c392465d4a673c8064740a82365c14d9fc1
-  data.tar.gz: 108dd965bb01572596358a5cca3fa7f0c9f31c279c425ccd622e0ffb926e80550b471d9e32844cd38b15a0946f21c08503511e9213784992e44237006dea3f82
+  metadata.gz: !binary |-
+    MGU5M2Y2ZWM1YjgwN2ZjMWM2MjBlOGVhYzAyOGRhNjBjZWY2YTM5ZmNjZWQz
+    ZTJlYTY2YTQ2YzE3YjA2ZDA2NWVmZmM4YmRiMmEwZDRiNmU2NDBlYzQ3ODc2
+    YjhjOTNmMTA1MDhiZWFiOGRkMjc3YzE1NjIxMGUzOTEzMTYxYTE=
+  data.tar.gz: !binary |-
+    OWFkY2JiMTQwZTBkYjlhNGFhNGNiOWIxMWZmODEzZjcyYmNhZjNkZWM0N2U4
+    M2ZhMGNlYTBjNTAxNzdiZDAwNzc5ZDY1ZWNhYTY3MTNlNDBhMGQwZjFiNGZh
+    MTc2NGMxN2VmYmZjYTEzOWYxODdmMjM4NDkyNzRkMmI4MDUzN2Q=

data/TODO

@@ -1,45 +1,7 @@
-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:
-        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
+Default 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.9.9
+1.0.0

data/activefacts-api.gemspec

@@ -2,16 +2,16 @@
 # DO NOT EDIT THIS FILE DIRECTLY
 # Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
-# stub: activefacts-api 0.9.9 ruby lib
+# stub: activefacts-api 1.0.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "activefacts-api"
-  s.version = "0.9.9"
+  s.version = "1.0.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib"]
   s.authors = ["Clifford Heath"]
-  s.date = "2014-02-14"
+  s.date = "2014-02-18"
   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 = [
@@ -70,7 +70,7 @@ Gem::Specification.new do |s|
   ]
   s.homepage = "http://github.com/cjheath/activefacts-api"
   s.licenses = ["MIT"]
-  s.rubygems_version = "2.2.1"
+  s.rubygems_version = "2.2.2"
   s.summary = "A fact-based data model DSL and API"
 
   if s.respond_to? :specification_version then

data/lib/activefacts/api/constellation.rb

@@ -55,7 +55,7 @@ module ActiveFacts
 	    if reason = invalid_object_type(k)
 	      raise InvalidObjectType.new(@vocabulary, k, reason)
 	    end
-	    h[k] = InstanceIndex.new(self, k, !!(@options[:sort] || ENV['ACTIVEFACTS_SORT']))
+	    h[k] = InstanceIndex.new(self, k, (@options.include?(:sort) ? @options[:sort] : API::sorted))
 	  end
       end
 
@@ -87,8 +87,6 @@ module ActiveFacts
 	      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
@@ -149,8 +147,6 @@ module ActiveFacts
 	  end
           instances[klass].delete(last_irvs)
         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
@@ -191,10 +187,11 @@ module ActiveFacts
         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:
-            single_roles, multiple_roles = klass.roles.keys.sort_by(&:to_s).partition{|r| r.to_s !~ /\Aall_/ }
+            single_roles, multiple_roles = klass.all_role.
+		partition{|n, r| r.unique }.
+		map{ |rs| rs.map{|n, r| n}.sort_by(&:to_s) }
+
             single_roles -= klass.identifying_role_names if (klass.is_entity_type)
-            # REVISIT: Need to include superclass roles also.
 
             instances = send(object_type.to_sym)
             next nil unless instances.size > 0
@@ -203,19 +200,21 @@ module ActiveFacts
                   s = "\t\t" + instance.verbalise
                   if (single_roles.size > 0)
                     role_values = 
-                      single_roles.map{|role|
+                      single_roles.map do |role_name|
+			  #p klass, klass.all_role.keys; exit
+			  next nil if klass.all_role(role_name).fact_type.is_a?(TypeInheritanceFactType)
 			  value =
-			    if instance.respond_to?(role)
-			      value = instance.send(role)
+			    if instance.respond_to?(role_name)
+			      value = instance.send(role_name)
 			    else
-			      instance.class.roles(role) # This role has not yet been realised
+			      instance.class.all_role(role_name) # This role has not yet been realised
 			    end
-			  [ role_name = role.to_s.camelcase, value ]
-                        }.select{|role_name, value|
+			  [ role_name.to_s.camelcase, value ]
+                        end.compact.select do |role_name, value|
                           value
-                        }.map{|role_name, value|
+                        end.map do |role_name, value|
                           "#{role_name} = #{value ? value.verbalise : "nil"}"
-                        }
+                        end
                     s += " where " + role_values*", " if role_values.size > 0
                   end
                   s
@@ -224,5 +223,13 @@ module ActiveFacts
       end
 
     end
+
+    def self.sorted
+      # Sorting defaults to true, unless you set ACTIVEFACTS_SORT to "[n]o" or [f]false"
+      @@af_sort_name ||= "ACTIVEFACTS_SORT"
+      sort = ENV[@@af_sort_name]
+      !sort or !%w{n f}.include?(sort[0])
+    end
+
   end
 end

data/lib/activefacts/api/entity.rb

@@ -33,7 +33,7 @@ module ActiveFacts
         unless (klass = self.class).identification_inherited_from
 	  irns = klass.identifying_role_names
 	  irns.each do |role_name|
-	    role = klass.roles(role_name)
+	    role = klass.all_role(role_name)
 	    key = arg_hash.delete(role_name)
 	    value =
 	      if key == nil
@@ -78,7 +78,7 @@ module ActiveFacts
       def settable_roles
         ([self.class]+self.class.supertypes_transitive).
           map do |k|
-            k.roles.
+            k.all_role.
               map do |name, role|
                 role.unique ? name : nil
               end.
@@ -91,7 +91,6 @@ module ActiveFacts
     public
       def inspect #:nodoc:
         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
@@ -123,7 +122,7 @@ module ActiveFacts
       def 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
+            identifying_role_name = self.class.all_role(role_sym).name.to_s.camelcase
             value ? value.verbalise(identifying_role_name) : "nil"
           end
         "#{role_name || self.class.basename}(#{ irnv*', ' })"
@@ -175,7 +174,7 @@ module ActiveFacts
 	# 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|
+	self.class.all_role_transitive.each do |n, role|
 	  if role.counterpart && role.counterpart.is_identifying
 	    # puts "Changing #{role.inspect} affects #{role.inspect}"
 	    impacted_roles << role
@@ -223,19 +222,19 @@ module ActiveFacts
         end
 
         def identifying_roles
-          # REVISIT: Should this return nil if identification_inherited_from?
           @identifying_roles ||=
             identifying_role_names.map do |role_name|
-              role = roles[role_name] || find_inherited_role(role_name)
+              role = all_role[role_name] || find_inherited_role(role_name)
+	      raise "Illegal request for identifying_roles of #{self} before they're all defined" if role == false
               role
-            end
+            end.freeze
         end
 
         def find_inherited_role(role_name)
           if !superclass.is_entity_type
             false
-          elsif superclass.roles.has_key?(role_name)
-            superclass.roles[role_name]
+          elsif superclass.all_role.has_key?(role_name)
+            superclass.all_role[role_name]
           else
             superclass.find_inherited_role(role_name)
           end
@@ -253,9 +252,8 @@ module ActiveFacts
 	      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.all_role(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(counterpart_class)
@@ -309,7 +307,7 @@ module ActiveFacts
 	  args.push(arg_hash)
 
 	  irns.map do |role_name|
-	    roles(role_name)
+	    all_role(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]
@@ -358,7 +356,7 @@ module ActiveFacts
 	  # 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)
+	    role = instance.class.all_role(k)
 	    unless role.is_identifying && role.object_type == self
 	      value =
 		if v == nil
@@ -420,6 +418,7 @@ module ActiveFacts
         def inherited(other) #:nodoc:
           other.identification_inherited_from = self
           subtypes << other unless subtypes.include? other
+	  TypeInheritanceFactType.new(self, other)
           vocabulary.__add_object_type(other)
         end
 

data/lib/activefacts/api/fact_type.rb

@@ -10,9 +10,31 @@ module ActiveFacts
   module API
     class FactType
       attr_accessor :all_role
+      # invariant { self.all_role.each {|role| self.is_a?(ObjectifiedFactType) ? role.counterpart.object_type == self.objectified_as : role.fact_type == self } }
 
       def initialize
-	@all_role = []
+	@all_role ||= []
+      end
+    end
+
+    class ObjectifiedFactType < FactType
+      # The roles of an ObjectifiedFactType are roles in the link fact types.
+      # This means that all_role[*].fact_type does not point to this fact type,
+      # as would normally be the case.
+      # invariant { self.all_role.each {|role| role.counterpart.object_type == self.objectified_as } }
+      attr_reader :objectified_as
+      # invariant { self.objectified_as.objectification_of == self }
+    end
+
+    class TypeInheritanceFactType < FactType
+      attr_reader :supertype_role, :subtype_role
+    
+      def initialize(supertype, subtype)
+	super()
+
+	# The supertype role is not mandatory, but the subtype role is. Both are unique.
+	@supertype_role = Role.new(self, supertype, subtype.name.gsub(/.*::/,'').to_sym, false, true)
+	@subtype_role = Role.new(self, subtype, supertype.name.gsub(/.*::/,'').to_sym, true, true)
       end
     end
   end

data/lib/activefacts/api/instance.rb

@@ -57,7 +57,7 @@ module ActiveFacts
       # List entities which have an identifying role played by this object.
       def related_entities(indirectly = true, instances = [])
 	# Check all roles of this instance
-        self.class.roles.each do |role_name, role|
+        self.class.all_role.each do |role_name, role|
 	  # If the counterpart role is not identifying for its object type, skip it
 	  next unless c = role.counterpart and c.is_identifying
 
@@ -83,22 +83,25 @@ module ActiveFacts
         # The counterpart roles get cleared automatically.
 	klasses = [self.class]+self.class.supertypes_transitive
 
-	irvks = {}  # identifying_role_values by class
-	klasses.each do |klass|
-	  if !irvks[klass] and klass.roles.detect{|_, role| role.counterpart and !role.counterpart.unique and send(role.getter) }
-	    # We will need the identifying_role_values for this role's object_type
-	    irvks[klass] = identifying_role_values(klass)
-	  end
+	irvrvs = {}  # identifying_role_values by RoleValues
+	self.class.all_role_transitive.each do |_, role|
+	  next unless role.counterpart and
+	    role.unique and
+	    !role.counterpart.unique and
+	    counterpart = send(role.getter)
+	  role_values = counterpart.send(role.counterpart.getter)
+	  irvrvs[role_values] = role_values.index_values(self)
 	end
 
 	klasses.each do |klass|
-          klass.roles.each do |role_name, role|
+          klass.all_role.each do |role_name, role|
             next if role.unary?
             counterpart = role.counterpart
 
 	    # Objects being created do not have to have non-identifying mandatory roles,
 	    # so we allow retracting to the same state.
             if role.unique
+	      next if role.fact_type.is_a?(TypeInheritanceFactType)
 	      i = send(role.getter)
 	      next unless i
 	      if counterpart.is_identifying && counterpart.mandatory
@@ -110,13 +113,14 @@ module ActiveFacts
 		  i.send(counterpart.setter, nil, false)
 		else
 		  rv = i.send(role.counterpart.getter)
-		  rv.delete_instance(self, irvks[role.object_type])
+		  rv.delete_instance(self, irvrvs[rv])
 		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:
+	      next if role.fact_type.is_a?(TypeInheritanceFactType)
 	      counterpart_instances = send(role.name)
 	      counterpart_instances.to_a.each do |counterpart_instance|
 		# These actions deconstruct the RoleValues as we go:

data/lib/activefacts/api/object_type.rb

@@ -17,20 +17,20 @@ module ActiveFacts
       end
 
       # Each ObjectType maintains a list of the Roles it plays:
-      def roles(role_name = nil)
-        unless instance_variable_defined?(@@roles_name ||= "@roles")  # Avoid "instance variable not defined" warning from ||=
-          @roles = RoleCollection.new
+      def all_role(role_name = nil)
+        unless instance_variable_defined?(@@all_role_name ||= "@all_role")  # Avoid "instance variable not defined" warning from ||=
+          @all_role = RoleCollection.new
         end
         case role_name
         when nil
-          @roles
+          @all_role
         when Symbol, String
           # Search this class then all supertypes:
-          unless role = @roles[role_name.to_sym]
+          unless role = @all_role[role_name.to_sym]
             role = nil
             supertypes.each do |supertype|
                 begin
-                  role = supertype.roles(role_name)
+                  role = supertype.all_role(role_name)
                 rescue RoleNotDefinedException
                   next
                 end
@@ -46,13 +46,18 @@ module ActiveFacts
         end
       end
 
-      def all_roles
-	return @all_roles if @all_roles
-	@all_roles = roles.dup
+      def add_role(role)
+	all_role[role.name] = role
+	@all_role_transitive = nil  # Undo the caching
+      end
+
+      def all_role_transitive
+	return @all_role_transitive if @all_role_transitive
+	@all_role_transitive = all_role.dup
 	supertypes_transitive.each do |klass|
-	  @all_roles.merge!(klass.roles)
+	  @all_role_transitive.merge!(klass.all_role)
 	end
-	@all_roles
+	@all_role_transitive
       end
 
       # Define a unary fact type attached to this object_type; in essence, a boolean attribute.
@@ -61,7 +66,7 @@ module ActiveFacts
       def maybe(role_name, options = {})
 	raise UnrecognisedOptionsException.new("role", role_name, options.keys) unless options.empty?
 	fact_type = FactType.new
-        realise_role(roles[role_name] = Role.new(fact_type, self, role_name, false, true))
+        realise_role(Role.new(fact_type, self, role_name, false, true))
       end
 
       # Define a binary fact type relating this object_type to another,
@@ -141,11 +146,10 @@ module ActiveFacts
 	    raise InvalidSupertypeException.new("#{self} < #{supertype}: A value type may not be a supertype of an entity type, and vice versa")
 	  end
 
+	  TypeInheritanceFactType.new(supertype, self)
 	  @supertypes << supertype
 
 	  # Realise the roles (create accessors) of this supertype.
-	  # REVISIT: The existing accessors at the other end will need to allow this class as role counterpart
-	  # REVISIT: Need to check all superclass roles recursively, unless we hit a common supertype
 	  realise_supertypes(object_type, all_supertypes)
 	end
 	[(superclass.respond_to?(:vocabulary) ? superclass : nil), *@supertypes].compact
@@ -200,25 +204,23 @@ module ActiveFacts
 
       # Realise all the roles of a object_type on this object_type, used when a supertype is added:
       def realise_roles(object_type)
-        object_type.roles.each do |role_name, role|
+        object_type.all_role.each do |role_name, role|
           realise_role(role)
         end
       end
 
       # 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: This should be all_roles, to catch duplicate role name in a supertype
-	# if all_roles[role_name]
-	if roles[role_name]
+	if all_role_transitive[role_name]
 	  raise DuplicateRoleException.new("#{name} cannot have more than one role named #{role_name}")
 	end
 	fact_type = FactType.new
-        roles[role_name] = role = Role.new(fact_type, self, role_name, mandatory, true)
+        role = Role.new(fact_type, self, role_name, mandatory, true)
 
         # There may be a forward reference here where role_name is a Symbol,
         # and the block runs later when that Symbol is bound to the object_type.
         when_bound(related, self, role_name, related_role_name) do |target, definer, role_name, related_role_name|
-	  counterpart = target.roles[related_role_name] = Role.new(fact_type, target, related_role_name, false, one_to_one)
+	  counterpart = Role.new(fact_type, target, related_role_name, false, one_to_one)
           realise_role(role)
           target.realise_role(counterpart)
         end
@@ -232,7 +234,7 @@ module ActiveFacts
 	    else true
 	    end
 	  instance_variable_set(role.variable, assigned)
-	  # REVISIT: Provide a way to find all instances playing/not playing this role
+	  # REVISIT: Consider whether we want to provide a way to find all instances playing/not playing this boolean role
 	  # Analogous to true.all_thing_as_role_name...
 	  assigned
 	end
@@ -318,12 +320,15 @@ module ActiveFacts
 	    impacts = analyse_impacts(role)
 	  end
 
-	  old_key = identifying_role_values(role.object_type) if old && mutual_propagation
+	  if old && mutual_propagation
+	    old_role_values = old.send(getter = role.counterpart.getter)
+	    old_key = old_role_values.index_values(self)
+	  end
 
 	  instance_variable_set(role_var, value)
 
 	  # Remove "self" from the old counterpart:
-	  old.send(getter = role.counterpart.getter).delete_instance(self, old_key) if old_key
+	  old_role_values.delete_instance(self, old_key) if old_key
 
 	  @constellation.when_admitted do
 	    # Add "self" into the counterpart
@@ -337,10 +342,25 @@ module ActiveFacts
       end
 
       def define_many_to_one_accessor(role)
-	define_method role.getter do
+
+	define_method role.getter do |*keys|
 	  role_var = role.variable
-	  instance_variable_get(role_var) or
-	    instance_variable_set(role_var, RoleValues.new)
+	  role_values =
+	    instance_variable_get(role_var) || begin
+
+	      # Decide which roles this index will use (exclude the counterpart role from the id)
+	      if role.counterpart and
+		  counterpart = role.counterpart.object_type and
+		  counterpart.is_entity_type
+		index_roles = counterpart.identifying_roles - [role.counterpart]
+	      else
+		index_roles = nil
+	      end
+
+	      instance_variable_set(role_var, RoleValues.new(role.counterpart.object_type, index_roles))
+	    end
+	  # Look up a value by the key provided, or return the whole collection
+	  keys.size == 0 ? role_values : role_values.[](*keys)
         end
       end