activefacts 0.6.0

data/lib/activefacts/api/role.rb

@@ -0,0 +1,94 @@
+## The ActiveFacts Runtime API Concept class
+# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#
+module ActiveFacts
+  module API
+
+    # A Role represents the relationship of one object to another (or to a boolean condition).
+    # Relationships (or binary fact types) have a Role at each end; one is declared using _has_one_
+    # 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 :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
+
+      def initialize(player, counterpart, name, mandatory = false, unique = true)
+        @player = player
+        @counterpart = counterpart
+        @name = name
+        @mandatory = mandatory
+        @unique = unique
+      end
+
+      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
+      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
+          # 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
+          end
+          value.constellation = constellation if constellation
+        else
+          value = [value] unless Array === value
+          raise "No parameters were provided to identify an #{@player.basename} instance" if value == []
+          if constellation
+            value = constellation.send(@player.basename.to_sym, *value)
+          else
+            value = @player.new(*value)
+          end
+        end
+        value
+      end
+    end
+
+    # Every Concept has a Role collection
+    # REVISIT: You can enumerate the concept's own roles, or inherited roles as well.
+    class RoleCollection < Hash #:nodoc:
+      def verbalise
+        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

data/lib/activefacts/api/standard_types.rb

@@ -0,0 +1,67 @@
+#
+# The ActiveFacts Runtime API Standard types extensions.
+# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#
+# These extensions add ActiveFacts Concept and Instance behaviour into base Ruby classes.
+#
+require 'date'
+
+module ActiveFacts
+  module API
+    # Adapter module to add value_type to all potential value classes
+    module ValueClass #:nodoc:
+      def value_type *args, &block #:nodoc:
+        include ActiveFacts::API::Value
+        # the included method adds the Value::ClassMethods
+        initialise_value_type(*args, &block)
+      end
+    end
+  end
+end
+
+require 'activefacts/api/numeric'
+
+# Add the methods that convert our classes into Concept types:
+
+ValueClasses = [String, Date, DateTime, Time, Int, Real, AutoCounter]
+ValueClasses.each{|c|
+    c.send :extend, ActiveFacts::API::ValueClass
+  }
+
+class TrueClass #:nodoc:
+  def verbalise(role_name = nil); role_name ? "#{role_name}: true" : "true"; end
+end
+
+class NilClass #:nodoc:
+  def verbalise; "nil"; end
+end
+
+class Class
+  def identified_by *args
+    raise "not an entity type" if respond_to? :value_type  # Don't make a ValueType into an EntityType
+    include ActiveFacts::API::Entity
+    initialise_entity_type(*args)
+  end
+end
+
+# REVISIT: Fix these NORMA types
+class Decimal < Int #:nodoc:
+end
+class SignedInteger < Int #:nodoc:
+end
+class SignedSmallInteger < Int #:nodoc:
+end
+class UnsignedInteger < Int #:nodoc:
+end
+class UnsignedSmallInteger < Int #:nodoc:
+end
+class LargeLengthText < String #:nodoc:
+end
+class FixedLengthText < String #:nodoc:
+end
+class PictureRawData < String #:nodoc:
+end
+class DateAndTime < DateTime #:nodoc:
+end
+class Money < Decimal #:nodoc:
+end

data/lib/activefacts/api/support.rb

@@ -0,0 +1,59 @@
+#
+# ActiveFacts runtime API.
+# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#
+# Note that we still require facets/basicobject, see numeric.rb
+#
+
+class Symbol #:nodoc:
+  def to_proc
+    Proc.new{|*args| args.shift.__send__(self, *args)}
+  end
+end
+
+class String #:nodoc:
+  def camelcase(first=false, on='_\s')
+    if first
+      gsub(/(^|[#{on}]+)([A-Za-z])/){ $2.upcase }
+    else
+      gsub(/([#{on}]+)([A-Za-z])/){ $2.upcase }
+    end
+  end
+
+  def snakecase
+    gsub(/([A-Z]+)([A-Z])/,'\1_\2').gsub(/([a-z])([A-Z])/,'\1_\2').downcase
+  end
+end
+
+class Module #:nodoc:
+  def modspace
+    space = name[ 0...(name.rindex( '::' ) || 0)]
+    space == '' ? Object : eval(space)
+  end
+
+  def basename
+    name.gsub(/.*::/, '')
+  end
+end
+
+module ActiveFacts #:nodoc:
+  # If the args array ends with a hash, remove it.
+  # If the remaining args are fewer than the arg_names,
+  # extract values from the hash and append them to args.
+  # Return the new args array and the hash.
+  # In any case leave the original args unmodified.
+  def self.extract_hash_args(arg_names, args)
+    if Hash === args[-1]
+      arg_hash = args[-1]     # Don't pop args, leave it unmodified
+      args = args[0..-2]
+      arg_hash = arg_hash.clone if (args.size < arg_names.size)
+      while args.size < arg_names.size
+        args << arg_hash[n = arg_names[args.size]]
+        arg_hash.delete(n)
+      end
+    else
+      arg_hash = {}
+    end
+    return args, arg_hash
+  end
+end

data/lib/activefacts/api/value.rb

@@ -0,0 +1,122 @@
+#
+# The ActiveFacts Runtime API Value extension module
+# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#
+# The methods of this module are added to Value type classes.
+#
+module ActiveFacts
+  module API
+
+    # All Value instances include the methods defined here
+    module Value
+      include Instance
+
+      # Value instance methods:
+      def initialize(*args) #:nodoc:
+        super(args)
+      end
+
+      # verbalise this Value
+      def verbalise(role_name = nil)
+        "#{role_name || self.class.basename} '#{to_s}'"
+      end
+
+      # A value is its own key
+      def identifying_role_values #:nodoc:
+        self
+      end
+
+      # All ValueType classes include the methods defined here
+      module ClassMethods
+        include Instance::ClassMethods
+
+        def initialise_value_type *args, &block #:nodoc:
+          # REVISIT: args could be a hash, with keys :length, :scale, :unit, :allow
+          #raise "value_type args unexpected" if args.size > 0
+        end
+
+        class_eval do
+          define_method :length do |*args|
+            @length = args[0] if args.length > 0
+            @length
+          end
+        end
+
+        class_eval do
+          define_method :scale do |*args|
+            @scale = args[0] if args.length > 0
+            @scale
+          end
+        end
+
+        # verbalise this ValueType
+        def verbalise
+          # REVISIT: Add length and scale here, if set
+          # REVISIT: Set vocabulary name of superclass if not same as this
+          "#{basename} = #{superclass.basename}();"
+        end
+
+        def identifying_role_values(*args)  #:nodoc:
+          # If the single arg is the correct class or a subclass, use it directly
+          #puts "#{basename}.identifying_role_values#{args.inspect}"
+          return args[0] if (args.size == 1 and self.class === args[0])   # No secondary supertypes allowed for value types
+          new(*args)
+        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)
+          #puts "#{klass} key is #{key.inspect}"
+
+          # 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
+
+          instance = new(*args)
+
+          instance.constellation = constellation
+          return *index_instance(instance)
+        end
+
+        def index_instance(instance, key = nil) #:nodoc:
+          instances = instance.constellation.instances[self]
+          key = instance.identifying_role_values
+          instances[key] = instance
+          # DEBUG: puts "indexing value #{basename} using #{key.inspect} in #{constellation.object_id}"
+
+          # Index the instance for each supertype:
+          supertypes.each do |supertype|
+            supertype.index_instance(instance, key)
+          end
+
+          return instance, key
+        end
+
+        def inherited(other)  #:nodoc:
+          #puts "REVISIT: ValueType #{self} < #{self.superclass} was inherited by #{other}; not implemented" #+"from #{caller*"\n\t"}"
+          # Copy the type parameters here, etc?
+          other.send :realise_supertypes, self
+          vocabulary.add_concept(other)
+          super
+        end
+      end
+
+      def self.included other #:nodoc:
+        other.send :extend, ClassMethods
+
+        #puts "ValueType included in #{other.basename} from #{caller*"\n\t"}"
+
+        # 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/vocabulary.rb

@@ -0,0 +1,120 @@
+#
+# The ActiveFacts Runtime API Vocabulary extension module.
+# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#
+# The methods of this module are extended into any module that contains
+# a Concept class (Entity type or Value type).
+#
+module ActiveFacts
+  module API
+    module Vocabulary
+      # With a parameter, look up a concept class by name.
+      # Without, return the hash of all concepts in this vocabulary
+      def concept(name = nil)
+        @concept ||= {}
+        return @concept unless name
+
+        return name if name.is_a? Class
+
+        # puts "Looking up concept #{name} in #{self.name}"
+        camel = name.to_s.camelcase(true)
+        if (c = @concept[camel])
+          __bind(camel)
+          return c
+        end
+        return (const_get(camel) rescue nil)
+      end
+
+      def add_concept(klass)  #:nodoc:
+        name = klass.basename
+        __bind(name)
+        # puts "Adding concept #{name} to #{self.name}"
+        @concept ||= {}
+        @concept[klass.basename] = klass
+      end
+
+      def __delay(concept_name, args, &block) #:nodoc:
+        # puts "Arranging for delayed binding on #{concept_name.inspect}"
+        @delayed ||= Hash.new { |h,k| h[k] = [] }
+        @delayed[concept_name] << [args, block]
+      end
+
+      # __bind raises an error if the named class doesn't exist yet.
+      def __bind(concept_name)  #:nodoc:
+        concept = const_get(concept_name)
+        if (@delayed && @delayed.include?(concept_name))
+          # $stderr.puts "#{concept_name} was delayed, binding now"
+          d = @delayed[concept_name]
+          d.each{|(a,b)|
+              b.call(concept, *a)
+            }
+          @delayed.delete(concept_name)
+        end
+      end
+
+      def verbalise
+        "Vocabulary #{name}:\n\t" +
+          @concept.keys.sort.map{|concept|
+              c = @concept[concept]
+              __bind(c.basename)
+              c.verbalise + "\n\t\t// Roles played: " + c.roles.verbalise
+            }*"\n\t"
+      end
+
+      # Create or find an instance of klass in constellation using value to identify it
+      def adopt(klass, constellation, value)  #:nodoc:
+        puts "Adopting #{ value.verbalise rescue value.class.to_s+' '+value.inspect} as #{klass} into constellation #{constellation.object_id}"
+
+        path = "unknown"
+        # Create a value instance we can hack if the value isn't already in this constellation
+        if (c = constellation)
+          if klass === value            # Right class?
+            vc = value.constellation rescue nil
+            if (c == vc)                # Right constellation?
+              # Already right class, in the right constellation
+              path = "right constellation, right class, just use it"
+            else
+              # We need a new object from our constellation, so copy the value.
+              if klass.respond_to?(:identifying_roles)
+                # Make a new entity having only the identifying roles set.
+                # Someone will complain that this is wrong, and all functional role values should also
+                # be cloned, and I'm listening... but not there yet. Why just those?
+                cloned = c.send(
+                    :"#{klass.basename}",
+                    *klass.identifying_roles.map{|role| value.send(role) }
+                  )
+                path = "wrong constellation, right class, cloned entity"
+              else
+                # Just copy a value:
+                cloned = c.send(:"#{klass.basename}", *value)
+                path = "wrong constellation, right class, copied value"
+              end
+              value.constellation = c
+            end
+          else
+            # Wrong class, assume it's a valid constructor arg. Get our constellation to find/make it:
+            value = [ value ] unless Array === value
+            value = c.send(:"#{klass.basename}", *value)
+            path = "right constellation but wrong class, constructed from args"
+          end
+        else
+          # This object's not in a constellation
+          if klass === value            # Right class?
+            if vc = value.constellation rescue nil
+              raise "REVISIT: Assigning to #{self.class.basename}.#{role_name} with constellation=#{c.inspect}: Can't dis-associate object from its constellation #{vc.object_id} yet"
+            end
+            # Right class, no constellation, just use it
+            path = "no constellation, correct class"
+          else
+            # Wrong class, construct one
+            value = klass.send(:new, *value)
+            path = "no constellation, constructed from wrong class"
+          end
+        end
+        # print "#{path}"; puts ", adopted as #{value.verbalise rescue value.inspect}"
+        value
+      end
+
+    end
+  end
+end