activefacts 0.6.0

data/lib/activefacts/api/constellation.rb

@@ -0,0 +1,106 @@
+#
+# The ActiveFacts Runtime API Constellation class
+# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#
+
+module ActiveFacts
+  module API
+    # 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.
+    #
+    # Value types are uniquely identified by their value, and a constellation will only
+    # ever have a single instance of a given value of that class.
+    #
+    # Entity instances are uniquely identified by their identifying roles, and again, a
+    # constellation will only ever have a single entity instance for the values of those
+    # identifying roles.
+    #
+    # As a result, you cannot "create" an object in a constellation - you merely _assert_
+    # its existence. This is done using method_missing; @constellation.Thing(3) creates
+    # an instance (or returns the existing instance) of Thing identified by the value 3.
+    #
+    # You can ##delete any instance, and that removes it from the constellation (will delete
+    # it from the database when the constellation is saved), and nullifies any references
+    # to it.
+    #
+    # A Constellation may or not be valid according to the vocabulary's constraints,
+    # but it may also represent a portion of a larger population (a database) with
+    # which it may be merged to form a valid population. In other words, an invalid
+    # Constellation may be invalid only because it lacks some of the facts.
+    #
+    class Constellation
+      attr_reader :vocabulary
+      # All instances are indexed in this hash, keyed by the class object. 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| ... }
+
+      # Create a new empty Constellation over the given Vocabulary
+      def initialize(vocabulary)
+        @vocabulary = vocabulary
+        @instances = Hash.new{|h,k| h[k] = {} }
+      end
+
+      def inspect #:nodoc:
+        "Constellation:#{object_id}"
+      end
+
+      # This method removes the given instance from this constellation's indexes
+      def delete(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
+      end
+
+      # With parameters, assert an instance of the concept whose name is the missing method.
+      # With no parameters, return the collection of all instances of that concept.
+      def method_missing(m, *args)
+        if klass = @vocabulary.const_get(m)
+          if args.size == 0
+            # Return the collection of all instances of this class in the constellation:
+            @instances[klass]
+          else
+            # Assert a new ground fact (concept instance) of the specified class, identified by args:
+            # REVISIT: create a constructor method here instead?
+            instance, key = klass.assert_instance(self, args)
+            instance
+          end
+        end
+      end
+
+      # Constellations verbalise all members of all classes in alphabetical order, showing
+      # non-identifying role values as well
+      def verbalise
+        "Constellation over #{vocabulary.name}:\n" +
+        vocabulary.concept.keys.sort.map{|concept|
+            klass = vocabulary.const_get(concept)
+
+            # 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))
+            # REVISIT: Need to include superclass roles also.
+
+            instances = send(concept.to_sym)
+            next nil unless instances.size > 0
+            "\tEvery #{concept}:\n" +
+              instances.map{|key, instance|
+                  s = "\t\t" + instance.verbalise
+                  if (single_roles.size > 0)
+                    role_values = 
+                      single_roles.map{|role|
+                          [ role_name = role.to_s.camelcase(true),
+                            value = instance.send(role)]
+                        }.select{|role_name, value|
+                          value
+                        }.map{|role_name, value|
+                          "#{role_name} = #{value ? value.verbalise : "nil"}"
+                        }
+                    s += " where " + role_values*", " if role_values.size > 0
+                  end
+                  s
+                } * "\n"
+          }.compact*"\n"
+      end
+    end
+  end
+end

data/lib/activefacts/api/entity.rb

@@ -0,0 +1,239 @@
+#
+# The ActiveFacts Runtime API Entity class
+# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#
+# 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 ActiveFacts
+  module API
+    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.
+      #
+      # A value must be provided for every identifying role, but if the
+      # last argument is a hash, they may come from there.
+      #
+      # Any additional (non-identifying) roles may also be passed in the final hash.
+      def initialize(*args)
+        super(args)
+        klass = self.class
+        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
+          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
+
+        # 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
+
+        # 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|
+          role = klass.roles(role_name)
+          send("#{role_name}=", value)
+        end
+      end
+
+      def inspect #:nodoc:
+        "\#<#{
+          self.class.basename
+        }:#{
+          object_id
+        }#{
+          constellation ? " in #{constellation.inspect}" : ""
+        } #{
+          # REVISIT: Where there are one-to-one roles, this cycles
+          self.class.identifying_roles.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
+          }.inject(0) { |h,v|
+            h ^= v.hash
+            h
+          }
+      end
+
+      # When used as a hash key, this entity instance is compared with another by
+      # comparing the values of its identifying roles
+      def eql?(other)
+        return false unless self.class == other.class
+        self.class.identifying_roles.each{|role|
+            return false unless send(role).eql?(other.send(role))
+          }
+        return true
+      end
+
+      # Verbalise this entity instance
+      def verbalise(role_name = nil)
+        "#{role_name || self.class.basename}(#{
+          self.class.identifying_roles.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"
+            }*", "
+        })"
+      end
+
+      # Return the array of the values of this entity instance's identifying roles
+      def identifying_role_values
+        self.class.identifying_roles.map{|role|
+            send(role)
+          }
+      end
+
+      # All classes that become Entity types receive the methods of this class as class methods:
+      module ClassMethods
+        include Instance::ClassMethods
+
+        # Return the array of Role objects that define the identifying relationships of this Entity type:
+        def identifying_roles
+          @identifying_roles ||= []
+        end
+
+        # Return 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}"
+
+          # 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
+          end
+
+          ir = identifying_roles
+          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)*', '}"
+          elsif args.size > ir.size
+            raise "#{basename} requires all identifying values, you have #{args.size-ir.size} extras #{args[ir.size..-1].map(&:inspect)*', '}"
+          end
+
+          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}"
+            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
+              next arg.identifying_role_values
+            end
+            role.player.identifying_role_values(*arg)
+          end
+        end
+
+        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]
+          # DEBUG: puts "assert #{self.basename} #{key.inspect} #{instance ? "exists" : "new"}"
+          return instance, key if instance      # A matching instance of this class
+
+          # Now construct each of this object's identifying roles
+          ir = identifying_roles
+          args, arg_hash = ActiveFacts::extract_hash_args(ir, args)
+          role_values = ir.map{|role_sym| roles(role_sym)}.zip(args)
+          key = []    # Gather the actual key (AutoCounters are special)
+          values = role_values.map do |role, arg|
+              if !arg
+                value = role_key = nil          # No value
+              elsif !role.counterpart
+                value = role_key = !!arg        # Unary
+              elsif role.player === arg         # REVISIT: or a secondary supertype
+                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))
+              end
+              key << role_key
+              value
+            end
+          values << arg_hash if arg_hash and !arg_hash.empty?
+
+          #puts "Creating new #{basename} using #{values.inspect}"
+          instance = new(*values)
+
+          # Make the new entity instance a member of this constellation:
+          instance.constellation = constellation
+          return *index_instance(instance, key, ir)
+        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_roles
+            key = (key_roles = identifying_roles).map do |role_name|
+              instance.send role_name
+            end
+          end
+
+          # Index the instance for this class in the constellation
+          instances = instance.constellation.instances[self]
+          instances[key] = instance
+          # DEBUG: puts "indexing entity #{basename} using #{key.inspect} in #{constellation.object_id}"
+
+          # Index the instance for each supertype:
+          supertypes.each do |supertype|
+            supertype.index_instance(instance, key, key_roles)
+          end
+
+          return instance, key
+        end
+
+        # A concept that isn't a ValueType must have an identification scheme,
+        # which is a list of roles it plays. The identification scheme may be
+        # inherited from a superclass.
+        def initialise_entity_type(*args) #:nodoc:
+          #puts "Initialising entity type #{self} using #{args.inspect}"
+          @identifying_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.
+          # We'd need late binding to use Role objects...
+          @identifying_roles = args if args.size > 0 || !@identifying_roles
+        end
+
+        def inherited(other) #:nodoc:
+          other.identified_by *identifying_roles
+          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 "};"
+        end
+      end
+
+      def Entity.included other #:nodoc:
+        other.send :extend, ClassMethods
+
+        # Register ourselves with the parent module, which has become a Vocabulary:
+        vocabulary = other.modspace
+        unless vocabulary.respond_to? :concept  # Extend module with Vocabulary if necessary
+          vocabulary.send :extend, Vocabulary
+        end
+        vocabulary.add_concept(other)
+      end
+    end
+  end
+end

data/lib/activefacts/api/instance.rb

@@ -0,0 +1,54 @@
+#
+# The ActiveFacts Runtime API Instance extension module.
+# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#
+# Instance methods are extended into all instances, whether of value or entity types.
+#
+module ActiveFacts
+  module API
+    # Every Instance of a Concept (A Value type or an Entity type) includes the methods of this module:
+    module Instance
+      # What constellation does this Instance belong to (if any):
+      attr_accessor :constellation
+
+      def initialize(args = []) #:nodoc:
+        unless (self.class.respond_to?(:identifying_roles))
+        #if (self.class.superclass != Object)
+          # puts "constructing #{self.class.superclass} with #{args.inspect}"
+          super(*args)
+        end
+      end
+
+      # Verbalise this instance
+      def verbalise
+        # This method should always be overridden in subclasses
+        raise "#{self.class} Instance verbalisation needed"
+      end
+
+      # De-assign all functional roles and remove from constellation, if any.
+      def delete
+        # Delete from the constellation first, so it can remember our identifying role values
+        @constellation.delete(self) if @constellation
+
+        # Now, for all roles (from this class and all supertypes), assign nil to all functional roles
+        # The counterpart roles get cleared automatically.
+        ([self.class]+self.class.supertypes_transitive).each do |klass|
+          klass.roles.each do |role_name, role|
+            next if role.unary?
+            next if !role.unique
+            send "#{role.name}=", nil
+          end
+        end
+      end
+
+      module ClassMethods #:nodoc:
+        include Concept
+        # Add Instance class methods here
+      end
+
+      def Instance.included other #:nodoc:
+        other.send :extend, ClassMethods
+      end
+    end
+  end
+end

data/lib/activefacts/api/numeric.rb

@@ -0,0 +1,158 @@
+#
+# The ActiveFacts Runtime API Numeric hacks to handle immediate types.
+# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#
+# This hack is required because Integer & Float don't support new,
+# and can't be sensibly subclassed. Just delegate to an instance var.
+#
+require 'delegate'
+require 'date'
+
+# It's not possible to subclass Integer, so instead we delegate to it.
+class Int < SimpleDelegator
+  def initialize(i = nil)
+    __setobj__(Integer(i))
+  end
+
+  def to_s
+    __getobj__.to_s
+  end
+
+  def hash
+    __getobj__.hash ^ self.class.hash
+  end
+
+  def eql?(o)
+    self.class == o.class and __getobj__.eql?(Integer(o))
+  end
+
+  def ==(o)
+    __getobj__.==(o)
+  end
+
+  def inspect
+    "#{self.class.basename}:#{__getobj__.inspect}"
+  end
+end
+
+# It's not possible to subclass Float, so instead we delegate to it.
+class Real < SimpleDelegator
+  def initialize(r = nil)
+    __setobj__(Float(r))
+  end
+
+  def hash
+    __getobj__.hash ^ self.class.hash
+  end
+
+  def to_s
+    __getobj__.to_s
+  end
+
+  def eql?(o)
+    self.class == o.class and __getobj__.eql?(Float(o))
+  end
+
+  def ==(o)
+    __getobj__.==(o)
+  end
+
+  def inspect
+    "#{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 << self; alias_method :old_new, :new end
+  def self.new(*a, &b)
+    #puts "Constructing date with #{a.inspect} from #{caller*"\n\t"}"
+    if (a.size == 1 && Date === a[0])
+      a = a[0]
+      civil(a.year, a.month, a.day, a.start)
+    else
+      civil(*a, &b)
+    end
+  end
+end
+
+# A DateTime can be constructed from any Date or DateTime subclass
+class ::DateTime #:nodoc:
+  class << self; alias_method :old_new, :new end
+  def self.new(*a, &b)
+    #puts "Constructing DateTime with #{a.inspect} from #{caller*"\n\t"}"
+    if (a.size == 1)
+      a = a[0]
+      if (DateTime === a)
+        civil(a.year, a.month, a.day, a.hour, a.min, a.sec, a.start)
+      elsif (Date === a)
+        civil(a.year, a.month, a.day, a.start)
+      else
+        civil(*a, &b)
+      end
+    else
+      civil(*a, &b)
+    end
+  end
+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.
+# The assigned value will be filled out everywhere it needs to be, upon save.
+class AutoCounter
+  def initialize(i = :new)
+    raise "AutoCounter #{self.class} may not be #{i.inspect}" unless i == :new or Integer === i
+    # puts "new AutoCounter #{self.class} from\n\t#{caller.select{|s| s !~ %r{rspec}}*"\n\t"}"
+    @value = i == :new ? nil : i
+  end
+
+  def assign(i)
+    raise ArgumentError if @value
+    @value = i.to_i
+  end
+
+  def defined?
+    !@value.nil?
+  end
+
+  def to_s
+    if self.defined?
+      @value.to_s 
+    else
+      "new_#{object_id}"
+    end
+  end
+
+  def self.coerce(i)
+    raise ArgumentError unless @value
+    [ i.to_i, @value ]
+  end
+
+  def inspect
+    "\#<AutoCounter "+to_s+">"
+  end
+
+  def hash
+    to_s.hash ^ self.class.hash
+  end
+
+  def eql?(o)
+    self.class == o.class and to_s.eql?(o.to_s)
+  end
+
+  def self.inherited(other)
+    def other.identifying_role_values(*args)
+      return nil if args == [:new]  # A new object has no identifying_role_values
+      return new(*args)
+    end
+    super
+  end
+
+private
+  def clone
+    raise "Not allowed to clone AutoCounters"
+  end
+end