activefacts 0.7.0 → 0.7.1

data/lib/activefacts/api/constellation.rb

@@ -1,10 +1,12 @@
 #
-# The ActiveFacts Runtime API Constellation class
-# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#       ActiveFacts Runtime API
+#       Constellation class
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 #
 
 module ActiveFacts
-  module API
+  module API      #:nodoc:
     # A Constellation is a population of instances of the Concept classes of a Vocabulary.
     # Every concept class is either a Value type or an Entity type.
     #
@@ -37,7 +39,7 @@ module ActiveFacts
       # Create a new empty Constellation over the given Vocabulary
       def initialize(vocabulary)
         @vocabulary = vocabulary
-        @instances = Hash.new{|h,k| h[k] = {} }
+        @instances = Hash.new{|h,k| h[k] = InstanceIndex.new }
       end
 
       def inspect #:nodoc:
@@ -52,7 +54,7 @@ module ActiveFacts
         end
       end
 
-      # With parameters, assert an instance of the concept whose name is the missing method.
+      # With parameters, assert an instance of the concept whose name is the missing method, identified by the values passed as *args*.
       # With no parameters, return the collection of all instances of that concept.
       def method_missing(m, *args)
         if klass = @vocabulary.const_get(m)
@@ -77,7 +79,7 @@ module ActiveFacts
 
             # REVISIT: It would be better not to rely on the role name pattern here:
             single_roles, multiple_roles = klass.roles.keys.sort_by(&:to_s).partition{|r| r.to_s !~ /\Aall_/ }
-            single_roles -= klass.identifying_roles if (klass.respond_to?(:identifying_roles))
+            single_roles -= klass.identifying_role_names if (klass.respond_to?(:identifying_role_names))
             # REVISIT: Need to include superclass roles also.
 
             instances = send(concept.to_sym)

data/lib/activefacts/api/entity.rb

@@ -1,12 +1,13 @@
 #
-# The ActiveFacts Runtime API Entity class
-# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#       ActiveFacts Runtime API
+#       Entity class (a mixin module for the class Class)
 #
-# An Entity type is any Concept that isn't a value type.
-# All Entity types must have an identifier made up of one or more roles.
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 #
 module ActiveFacts
   module API
+    # An Entity type is any Concept that isn't a value type.
+    # All Entity types must have an identifier made up of one or more roles.
     module Entity
       include Instance
 
@@ -25,23 +26,23 @@ module ActiveFacts
         hash = {}
         hash = args.pop.clone if Hash === args[-1]
 
-        # Pick any missing identifying_roles out of the hash if possible:
-        while args.size < (ir = klass.identifying_roles).size
+        # Pick any missing identifying roles out of the hash if possible:
+        while args.size < (ir = klass.identifying_role_names).size
           value = hash[role = ir[args.size]]
           hash.delete(role)
           args.push value
         end
 
         # If one arg is expected but more are passed, they might be the args for the object that plays the identifying role:
-        args = [args] if klass.identifying_roles.size == 1 && args.size > 1
+        args = [args] if klass.identifying_role_names.size == 1 && args.size > 1
 
         # This should now only occur when there are too many args passed:
         raise "Wrong number of parameters to #{klass}.new, " +
-            "expect (#{klass.identifying_roles*","}) " +
-            "got (#{args.map{|a| a.to_s.inspect}*", "})" if args.size != klass.identifying_roles.size
+            "expect (#{klass.identifying_role_names*","}) " +
+            "got (#{args.map{|a| a.to_s.inspect}*", "})" if args.size != klass.identifying_role_names.size
 
         # Assign the identifying roles in order, then the other roles passed as a hash:
-        (klass.identifying_roles.zip(args) + hash.entries).each do |role_name, value|
+        (klass.identifying_role_names.zip(args) + hash.entries).each do |role_name, value|
           role = klass.roles(role_name)
           send("#{role_name}=", value)
         end
@@ -56,15 +57,15 @@ module ActiveFacts
           constellation ? " in #{constellation.inspect}" : ""
         } #{
           # REVISIT: Where there are one-to-one roles, this cycles
-          self.class.identifying_roles.map{|role| "@#{role}="+send(role).inspect }*" "
+          self.class.identifying_role_names.map{|role| "@#{role}="+send(role).inspect }*" "
         }>"
       end
 
       # When used as a hash key, the hash key of this entity instance is calculated
       # by hashing the values of its identifying roles
       def hash
-        self.class.identifying_roles.map{|role|
-            send role
+        self.class.identifying_role_names.map{|role|
+            instance_variable_get("@#{role}")
           }.inject(0) { |h,v|
             h ^= v.hash
             h
@@ -75,7 +76,7 @@ module ActiveFacts
       # comparing the values of its identifying roles
       def eql?(other)
         return false unless self.class == other.class
-        self.class.identifying_roles.each{|role|
+        self.class.identifying_role_names.each{|role|
             return false unless send(role).eql?(other.send(role))
           }
         return true
@@ -84,7 +85,7 @@ module ActiveFacts
       # Verbalise this entity instance
       def verbalise(role_name = nil)
         "#{role_name || self.class.basename}(#{
-          self.class.identifying_roles.map{|role_sym|
+          self.class.identifying_role_names.map{|role_sym|
               value = send(role_sym)
               role_name = self.class.roles(role_sym).name.to_s.camelcase(true)
               value ? value.verbalise(role_name) : "nil"
@@ -94,7 +95,7 @@ module ActiveFacts
 
       # Return the array of the values of this entity instance's identifying roles
       def identifying_role_values
-        self.class.identifying_roles.map{|role|
+        self.class.identifying_role_names.map{|role|
             send(role)
           }
       end
@@ -104,22 +105,23 @@ module ActiveFacts
         include Instance::ClassMethods
 
         # Return the array of Role objects that define the identifying relationships of this Entity type:
-        def identifying_roles
-          @identifying_roles ||= []
+        def identifying_role_names
+          @identifying_role_names ||= []
         end
 
-        # Return an array of Instance objects that can identify an instance of this Entity type:
+        # Convert the passed arguments into an array of Instance objects that can identify an instance of this Entity type:
         def identifying_role_values(*args)
-          #puts "Getting identifying role values #{identifying_roles.inspect} of #{basename} using #{args.inspect}"
+          #puts "Getting identifying role values #{identifying_role_names.inspect} of #{basename} using #{args.inspect}"
 
           # If the single arg is an instance of the correct class or a subclass,
           # use the instance's identifying_role_values
           if (args.size == 1 and
-              self === args[0])       # REVISIT: or a secondary supertype
-            return args[0].identifying_role_values
+              (arg = args[0]).is_a?(self))       # REVISIT: or a secondary supertype
+            arg = arg.__getobj__ if RoleProxy === arg
+            return arg.identifying_role_values
           end
 
-          ir = identifying_roles
+          ir = identifying_role_names
           args, arg_hash = ActiveFacts::extract_hash_args(ir, args)
           if args.size < ir.size
             raise "#{basename} requires all identifying values, you're missing #{ir[args.size..-1].map(&:to_sym)*', '}"
@@ -129,14 +131,15 @@ module ActiveFacts
 
           role_args = ir.map{|role_sym| roles(role_sym)}.zip(args)
           role_args.map do |role, arg|
-            #puts "Getting identifying_role_value for #{role.player.basename} using #{arg.inspect}"
+            #puts "Getting identifying_role_value for #{role.counterpart_concept.basename} using #{arg.inspect}"
             next nil unless arg
             next !!arg unless role.counterpart  # Unary
-            if role.player === arg              # REVISIT: or a secondary supertype
-              # Note that with a secondary supertype, it must still return the values of these identifying_roles
+            arg = arg.__getobj__ if RoleProxy === arg
+            if arg.is_a?(role.counterpart_concept)              # REVISIT: or a secondary supertype
+              # Note that with a secondary supertype, it must still return the values of these identifying_role_names
               next arg.identifying_role_values
             end
-            role.player.identifying_role_values(*arg)
+            role.counterpart_concept.identifying_role_values(*arg)
           end
         end
 
@@ -153,7 +156,7 @@ module ActiveFacts
           return instance, key if instance      # A matching instance of this class
 
           # Now construct each of this object's identifying roles
-          ir = identifying_roles
+          ir = identifying_role_names
           args, arg_hash = ActiveFacts::extract_hash_args(ir, args)
           role_values = ir.map{|role_sym| roles(role_sym)}.zip(args)
           key = []    # Gather the actual key (AutoCounters are special)
@@ -162,11 +165,12 @@ module ActiveFacts
                 value = role_key = nil          # No value
               elsif !role.counterpart
                 value = role_key = !!arg        # Unary
-              elsif role.player === arg         # REVISIT: or a secondary supertype
+              elsif arg.is_a?(role.counterpart_concept)      # REVISIT: or a secondary supertype
+                arg = arg.__getobj__ if RoleProxy === arg
                 raise "Connecting values across constellations" unless arg.constellation == constellation
                 value, role_key = arg, arg.identifying_role_values
               else
-                value, role_key = role.player.assert_instance(constellation, Array(arg))
+                value, role_key = role.counterpart_concept.assert_instance(constellation, Array(arg))
               end
               key << role_key
               value
@@ -183,8 +187,8 @@ module ActiveFacts
 
         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_roles
-            key = (key_roles = identifying_roles).map do |role_name|
+          unless key && key_roles && key_roles == identifying_role_names
+            key = (key_roles = identifying_role_names).map do |role_name|
               instance.send role_name
             end
           end
@@ -207,20 +211,20 @@ module ActiveFacts
         # inherited from a superclass.
         def initialise_entity_type(*args) #:nodoc:
           #puts "Initialising entity type #{self} using #{args.inspect}"
-          @identifying_roles = superclass.identifying_roles if superclass.respond_to?(:identifying_roles)
-          # REVISIT: @identifying_roles here are the symbols passed in, not the Role objects we should use.
+          @identifying_role_names = superclass.identifying_role_names if superclass.respond_to?(:identifying_role_names)
+          # REVISIT: @identifying_role_names here are the symbols passed in, not the Role objects we should use.
           # We'd need late binding to use Role objects...
-          @identifying_roles = args if args.size > 0 || !@identifying_roles
+          @identifying_role_names = args if args.size > 0 || !@identifying_role_names
         end
 
         def inherited(other) #:nodoc:
-          other.identified_by *identifying_roles
+          other.identified_by *identifying_role_names
           vocabulary.add_concept(other)
         end
 
         # verbalise this concept
         def verbalise
-          "#{basename} = entity type known by #{identifying_roles.map{|role_sym| role_sym.to_s.camelcase(true)}*" and "};"
+          "#{basename} is identified by #{identifying_role_names.map{|role_sym| role_sym.to_s.camelcase(true)}*" and "};"
         end
       end
 

data/lib/activefacts/api/instance.rb

@@ -1,6 +1,8 @@
 #
-# The ActiveFacts Runtime API Instance extension module.
-# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#       ActiveFacts Runtime API
+#       Instance (mixin module for instances of a Concept - a class with Concept mixed in)
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 #
 # Instance methods are extended into all instances, whether of value or entity types.
 #
@@ -12,7 +14,7 @@ module ActiveFacts
       attr_accessor :constellation
 
       def initialize(args = []) #:nodoc:
-        unless (self.class.respond_to?(:identifying_roles))
+        unless (self.class.respond_to?(:identifying_role_names))
         #if (self.class.superclass != Object)
           # puts "constructing #{self.class.superclass} with #{args.inspect}"
           super(*args)

data/lib/activefacts/api/numeric.rb

@@ -1,32 +1,35 @@
 #
-# The ActiveFacts Runtime API Numeric hacks to handle immediate types.
-# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#       ActiveFacts Runtime API
+#       Numeric and Date delegates and hacks to handle immediate types.
 #
-# This hack is required because Integer & Float don't support new,
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
+# These delegates are required because Integer & Float don't support new,
 # and can't be sensibly subclassed. Just delegate to an instance var.
+# Date and DateTime don't have a sensible new() method, so we monkey-patch one here.
 #
 require 'delegate'
 require 'date'
 
 # It's not possible to subclass Integer, so instead we delegate to it.
 class Int < SimpleDelegator
-  def initialize(i = nil)
+  def initialize(i = nil)               #:nodoc:
     __setobj__(Integer(i))
   end
 
-  def to_s
+  def to_s                              #:nodoc:
     __getobj__.to_s
   end
 
-  def hash
+  def hash                              #:nodoc:
     __getobj__.hash ^ self.class.hash
   end
 
-  def eql?(o)
+  def eql?(o)                           #:nodoc:
     self.class == o.class and __getobj__.eql?(Integer(o))
   end
 
-  def ==(o)
+  def ==(o)                             #:nodoc:
     __getobj__.==(o)
   end
 
@@ -37,34 +40,35 @@ end
 
 # It's not possible to subclass Float, so instead we delegate to it.
 class Real < SimpleDelegator
-  def initialize(r = nil)
+  def initialize(r = nil)                               #:nodoc:
     __setobj__(Float(r))
   end
 
-  def hash
+  def hash                              #:nodoc:
     __getobj__.hash ^ self.class.hash
   end
 
-  def to_s
+  def to_s                              #:nodoc:
     __getobj__.to_s
   end
 
-  def eql?(o)
+  def eql?(o)                           #:nodoc:
     self.class == o.class and __getobj__.eql?(Float(o))
   end
 
-  def ==(o)
+  def ==(o)                             #:nodoc:
     __getobj__.==(o)
   end
 
-  def inspect
+  def inspect                           #:nodoc:
     "#{self.class.basename}:#{__getobj__.inspect}"
   end
 end
 
 # A Date can be constructed from any Date subclass, not just using the normal date constructors.
-class ::Date #:nodoc:
+class ::Date
   class << self; alias_method :old_new, :new end
+  # Date.new cannot normally be called passing a Date as the parameter. This allows that.
   def self.new(*a, &b)
     #puts "Constructing date with #{a.inspect} from #{caller*"\n\t"}"
     if (a.size == 1 && Date === a[0])
@@ -77,8 +81,9 @@ class ::Date #:nodoc:
 end
 
 # A DateTime can be constructed from any Date or DateTime subclass
-class ::DateTime #:nodoc:
+class ::DateTime
   class << self; alias_method :old_new, :new end
+  # DateTime.new cannot normally be called passing a Date or DateTime as the parameter. This allows that.
   def self.new(*a, &b)
     #puts "Constructing DateTime with #{a.inspect} from #{caller*"\n\t"}"
     if (a.size == 1)
@@ -99,8 +104,7 @@ end
 # The AutoCounter class is an integer, but only after the value
 # has been established in the database.
 # Construct it with the value :new to get an uncommitted value.
-# You can use this new instance as a role value to identify an entity instance,
-# or anywhere else for that matter.
+# You can use this new instance as a value of any role of this type, including to identify an entity instance.
 # The assigned value will be filled out everywhere it needs to be, upon save.
 class AutoCounter
   def initialize(i = :new)
@@ -109,11 +113,13 @@ class AutoCounter
     @value = i == :new ? nil : i
   end
 
+  # Assign a definite value to an AutoCounter; this may only be done once
   def assign(i)
     raise ArgumentError if @value
     @value = i.to_i
   end
 
+  # Ask whether a definite value has been assigned
   def defined?
     !@value.nil?
   end
@@ -126,6 +132,7 @@ class AutoCounter
     end
   end
 
+  # An AutoCounter may only be used in numeric expressions after a definite value has been assigned
   def self.coerce(i)
     raise ArgumentError unless @value
     [ i.to_i, @value ]
@@ -135,15 +142,15 @@ class AutoCounter
     "\#<AutoCounter "+to_s+">"
   end
 
-  def hash
+  def hash                              #:nodoc:
     to_s.hash ^ self.class.hash
   end
 
-  def eql?(o)
+  def eql?(o)                           #:nodoc:
     self.class == o.class and to_s.eql?(o.to_s)
   end
 
-  def self.inherited(other)
+  def self.inherited(other)             #:nodoc:
     def other.identifying_role_values(*args)
       return nil if args == [:new]  # A new object has no identifying_role_values
       return new(*args)

data/lib/activefacts/api/role.rb

@@ -1,5 +1,10 @@
-## The ActiveFacts Runtime API Concept class
-# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#
+#       ActiveFacts API
+#       Role class.
+#       Each accessor method created on an instance corresponds to a Role object in the instance's class.
+#       Binary fact types construct a Role at each end.
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 #
 module ActiveFacts
   module API
@@ -9,37 +14,43 @@ module ActiveFacts
     # or _one_to_one_, and the other is created on the counterpart class. Each Concept class maintains
     # an array of the roles it plays.
     class Role
-      attr_accessor :name
+      attr_accessor :owner            # The Concept to which this role belongs
+      attr_accessor :name             # The name of the role (a Symbol)
+      attr_accessor :counterpart_concept  # A Concept Class (may be temporarily a Symbol before the class is defined)
       attr_accessor :counterpart      # All roles except unaries have a binary counterpart
-      attr_accessor :player           # May be a Symbol, which will be converted to a Class/Concept
-      attr_accessor :unique
-      attr_accessor :mandatory
-      attr_accessor :value_restriction
+      attr_accessor :unique           # Is this role played by at most one instance, or more?
+      attr_accessor :mandatory        # In a valid fact population, is this role required to be played?
+      attr_accessor :value_restriction  # Counterpart Instances playing this role must meet these restrictions
+      attr_reader :is_identifying     # Is this an identifying role for owner?
 
-      def initialize(player, counterpart, name, mandatory = false, unique = true)
-        @player = player
+      def initialize(owner, counterpart_concept, counterpart, name, mandatory = false, unique = true)
+        @owner = owner
+        @counterpart_concept = counterpart_concept
         @counterpart = counterpart
         @name = name
         @mandatory = mandatory
         @unique = unique
+        @is_identifying = @owner.respond_to?(:identifying_role_names) && @owner.identifying_role_names.include?(@name)
       end
 
+      # Is this role a unary (created by maybe)? If so, it has no counterpart
       def unary?
         # N.B. A role with a forward reference looks unary until it is resolved.
         counterpart == nil
       end
 
-      def resolve_player(vocabulary)  #:nodoc:
-        return @player if Class === @player   # Done already
-        klass = vocabulary.concept(@player)   # Trigger the binding
-        raise "Cannot resolve role player #{@player.inspect} for role #{name} in vocabulary #{vocabulary.basename}; still forward-declared?" unless klass
-        @player = klass                       # Memoize a successful result
+      def resolve_counterpart(vocabulary)  #:nodoc:
+        return @counterpart_concept if @counterpart_concept.is_a?(Class)   # Done already
+        klass = vocabulary.concept(@counterpart_concept)   # Trigger the binding
+        raise "Cannot resolve role counterpart_concept #{@counterpart_concept.inspect} for role #{name} in vocabulary #{vocabulary.basename}; still forward-declared?" unless klass
+        @counterpart_concept = klass                       # Memoize a successful result
       end
 
       def adapt(constellation, value) #:nodoc:
         # If the value is a compatible class, use it (if in another constellation, clone it),
         # else create a compatible object using the value as constructor parameters.
-        if @player === value  # REVISIT: may be a non-primary subtype of player
+        if value.is_a?(@counterpart_concept)  # REVISIT: may be a non-primary subtype of counterpart_concept
+          value = value.__getobj__ if RoleProxy === value
           # Check that the value is in a compatible constellation, clone if not:
           if constellation && (vc = value.constellation) && vc != constellation
             value = value.clone   # REVISIT: There's sure to be things we should reset/clone here, like non-identifying roles
@@ -47,11 +58,11 @@ module ActiveFacts
           value.constellation = constellation if constellation
         else
           value = [value] unless Array === value
-          raise "No parameters were provided to identify an #{@player.basename} instance" if value == []
+          raise "No parameters were provided to identify an #{@counterpart_concept.basename} instance" if value == []
           if constellation
-            value = constellation.send(@player.basename.to_sym, *value)
+            value = constellation.send(@counterpart_concept.basename.to_sym, *value)
           else
-            value = @player.new(*value)
+            value = @counterpart_concept.new(*value)
           end
         end
         value
@@ -65,30 +76,5 @@ module ActiveFacts
         keys.sort_by(&:to_s).inspect
       end
     end
-
-    # A RoleValueArray is an array with all mutating methods hidden.
-    # We use these for the "many" side of a 1:many relationship.
-    # Only "replace" and "delete" are actually used (so far!).
-    #
-    # Don't rely on this implementation, as it must change to support
-    # persistence.
-    #
-    class RoleValueArray < Array  #:nodoc:
-      [ :"<<", :"[]=", :clear, :collect!, :compact!, :concat, :delete,
-        :delete_at, :delete_if, :fill, :flatten!, :insert, :map!, :pop,
-        :push, :reject!, :replace, :reverse!, :shift, :shuffle!, :slice!,
-        :sort!, :uniq!, :unshift
-      ].each{|s|
-          begin
-            alias_method("__#{s}", s)
-          rescue NameError  # shuffle! is in 1.9 only
-          end
-        }
-
-      def verbalise
-        "["+map{|e| e.verbalise}*", "+"]"
-      end
-    end
-
   end
 end