activefacts-api 0.8.9

data/lib/activefacts/api/role.rb

@@ -0,0 +1,80 @@
+#
+#       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
+
+    # 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 ObjectType class maintains
+    # an array of the roles it plays.
+    class Role
+      attr_accessor :owner            # The ObjectType to which this role belongs
+      attr_accessor :name             # The name of the role (a Symbol)
+      attr_accessor :counterpart_object_type  # A ObjectType Class (may be temporarily a Symbol before the class is defined)
+      attr_accessor :counterpart      # All roles except unaries have a binary counterpart
+      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_constraint  # Counterpart Instances playing this role must meet this constraint
+      attr_reader :is_identifying     # Is this an identifying role for owner?
+
+      def initialize(owner, counterpart_object_type, counterpart, name, mandatory = false, unique = true)
+        @owner = owner
+        @counterpart_object_type = counterpart_object_type
+        @counterpart = counterpart
+        @name = name
+        @mandatory = mandatory
+        @unique = unique
+        @is_identifying = @owner.is_entity_type && @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_counterpart(vocabulary)  #:nodoc:
+        return @counterpart_object_type if @counterpart_object_type.is_a?(Class)   # Done already
+        klass = vocabulary.object_type(@counterpart_object_type)   # Trigger the binding
+        raise "Cannot resolve role counterpart_object_type #{@counterpart_object_type.inspect} for role #{name} in vocabulary #{vocabulary.basename}; still forward-declared?" unless klass
+        @counterpart_object_type = 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 value.is_a?(@counterpart_object_type)  # REVISIT: may be a non-primary subtype of counterpart_object_type
+          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
+          end
+          value.constellation = constellation if constellation
+        else
+          value = [value] unless Array === value
+          raise "No parameters were provided to identify an #{@counterpart_object_type.basename} instance" if value == []
+          if constellation
+            value = constellation.send(@counterpart_object_type.basename.to_sym, *value)
+          else
+            value = @counterpart_object_type.new(*value)
+          end
+        end
+        value
+      end
+    end
+
+    # Every ObjectType has a Role collection
+    # REVISIT: You can enumerate the object_type's own roles, or inherited roles as well.
+    class RoleCollection < Hash #:nodoc:
+      def verbalise
+        keys.sort_by(&:to_s).inspect
+      end
+    end
+  end
+end

data/lib/activefacts/api/role_proxy.rb

@@ -0,0 +1,71 @@
+#
+#       ActiveFacts Runtime API
+#       RoleProxy class, still somewhat experimental
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
+require 'delegate'
+
+module ActiveFacts
+  module API
+    #
+    # When you use the accessor method created by has_one, one_to_one, or maybe, you get a RoleProxy for the actual value.
+    # This behaves almost exactly as the value, but it knows through which role you fetched it.
+    # That will allow it to verbalise itself using the correct reading for that role.
+    #
+    # Don't use "SomeClass === role_value" to test the type, use "role_value.is_a?(SomeClass)" instead.
+    #
+    # In future, retrieving a value by indexing into a RoleValues array will do the same thing.
+    #
+    class RoleProxy < SimpleDelegator
+      def initialize(role, o = nil)     #:nodoc:
+        @role = role                    # REVISIT: Use this to implement verbalise()
+        __setobj__(o)
+      end
+
+      def method_missing(m, *a, &b)     #:nodoc:
+        begin
+          super                         # Delegate first
+        rescue NoMethodError => e
+          __getobj__.method_missing(m, *a, &b)
+        rescue => e
+          raise
+        end
+      end
+
+      def class                         #:nodoc:
+        __getobj__.class
+      end
+
+      def is_a? klass                   #:nodoc:
+        __getobj__.is_a? klass
+      end
+
+      def to_s                          #:nodoc:
+        __getobj__.to_s
+      end
+
+      # This is strongly deprecated, and omitting it doesn't seem to hurt:
+      #def object_id                     #:nodoc:
+      #  __getobj__.object_id
+      #end
+
+      # REVISIT: Should Proxies hash and eql? the same as their wards?
+      def hash                          #:nodoc:
+        __getobj__.hash ^ self.class.hash
+      end
+
+      def eql?(o)                       #:nodoc:
+        self.class == o.class and __getobj__.eql?(o)
+      end
+
+      def ==(o)                         #:nodoc:
+        __getobj__.==(o)
+      end
+
+      def inspect                       #:nodoc:
+        "Proxy:#{__getobj__.inspect}"
+      end
+    end
+  end
+end

data/lib/activefacts/api/role_values.rb

@@ -0,0 +1,117 @@
+#
+#       ActiveFacts Runtime API
+#       RoleValues, manages the set of instances involved in a many_to_one relationship.
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
+# There are two implementations here, one using an array and one using a hash.
+# The hash one has problems with keys being changed during object deletion, so
+# cannot be used yet; a fix is upcoming and will improve performance of large sets.
+#
+module ActiveFacts
+  module API
+
+    class RoleValues  #:nodoc:
+      include Enumerable
+
+#=begin
+      def initialize
+        @a = []
+      end
+
+      def each &b
+        # REVISIT: Provide a configuration variable to enable this heckling during testing:
+        #@a.sort_by{rand}.each &b
+        @a.each &b
+      end
+
+      def size
+        @a.size
+      end
+
+      def empty?
+        @a.size == 0
+      end
+
+      def +(a)
+        @a.+(a.is_a?(RoleValues) ? Array(a) : a)
+      end
+
+      def -(a)
+        @a - a
+      end
+
+      def single
+        @a.size > 1 ? nil : @a[0]
+      end
+
+      def update(old, value)
+        @a.delete(old) if old
+        @a << value if value
+        raise "Adding RoleProxy to RoleValues collection" if value && RoleProxy === value
+      end
+
+      def verbalise
+        "["+@a.to_a.map{|e| e.verbalise}*", "+"]"
+      end
+#=end
+
+=begin
+      def initialize
+        @h = {}
+      end
+
+      def each &b
+        @h.keys.each &b
+      end
+
+      def size
+        @h.size
+      end
+
+      def empty?
+        @h.size == 0
+      end
+
+      def +(a)
+        @h.keys.+(a.is_a?(RoleValues) ? Array(a) : a)
+      end
+
+      def -(a)
+        @h.keys - a
+      end
+
+      def single
+        @h.size > 1 ? nil : @h.keys[0]
+      end
+
+      def update(old, value)
+        if old
+          unless @h.delete(old)
+            @h.each { |k, v|
+              next if k != old
+              puts "#{@h.object_id}: Didn't delete #{k.verbalise} (hash=#{k.hash}) matching #{old.verbalise} (hash=#{old.hash})"
+              puts "They are #{k.eql?(old) ? "" : "not "}eql?"
+              found = @h[k]
+              puts "found #{found.inspect}" if found
+              debugger
+              x = k.eql?(old)
+              y = old.eql?(k)
+              p y
+            }
+            raise "failed to delete #{old.verbalise}, have #{map{|e| e.verbalise}.inspect}"
+          end
+        end
+        puts "#{@h.object_id}: Adding #{value.inspect}" if value && (value.name == 'Meetingisboardmeeting' rescue false)
+        @h[value] = true if value
+      end
+
+      def verbalise
+        "["+@h.keys.map{|e| e.verbalise}*", "+"]"
+      end
+=end
+
+    end
+
+  end
+end

data/lib/activefacts/api/standard_types.rb

@@ -0,0 +1,87 @@
+#
+#       ActiveFacts Runtime API
+#       Standard types extensions.
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
+# These extensions add ActiveFacts ObjectType and Instance behaviour into base Ruby value classes,
+# and allow any Class to become an Entity.
+#
+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 ObjectType 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
+  # 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
+    raise "#{basename} is 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
+
+  def is_entity_type
+    respond_to?(:identifying_role_names)
+  end
+end
+
+require 'bigdecimal'
+class Decimal < BigDecimal #:nodoc:
+  extend ActiveFacts::API::ValueClass
+  # The problem here is you can't pass a BigDecimal to BigDecimal.new. Fix it.
+  def self.new(v)
+    if v.is_a?(BigDecimal)
+      super(v.to_s)
+    else
+      super
+    end
+  end
+end
+
+# These types are generated on conversion from NORMA's types:
+class Char < String #:nodoc:  # FixedLengthText
+end
+class Text < String #:nodoc:  # LargeLengthText
+end
+class Image < String #:nodoc: # PictureRawData
+end
+class SignedInteger < Int #:nodoc:
+end
+class UnsignedInteger < Int   #:nodoc:
+end
+class AutoTimeStamp < String  #:nodoc: AutoTimeStamp
+end
+class Blob < String           #:nodoc: VariableLengthRawData
+end
+unless Object.const_defined?("Money")
+  class Money < Decimal       #:nodoc:
+  end
+end

data/lib/activefacts/api/support.rb

@@ -0,0 +1,66 @@
+#
+#       ActiveFacts Runtime API.
+#       Various additions or patches to Ruby built-in classes, and some global support methods
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
+
+class Symbol #:nodoc:
+  def to_proc
+    Proc.new{|*args| args.shift.__send__(self, *args)}
+  end
+end
+
+class String #:nodoc:
+  # This may be overridden by a version from ActiveSupport. For our purposes, either will work.
+  def camelcase(first_letter = :upper)
+    if first_letter == :upper
+      gsub(/(^|[_\s]+)([A-Za-z])/){ $2.upcase }
+    else
+      gsub(/([_\s]+)([A-Za-z])/){ $2.upcase }
+    end
+  end
+
+  def snakecase
+    gsub(/([a-z])([A-Z])/,'\1_\2').downcase
+  end
+
+  def camelwords
+    gsub(/-([a-zA-Z])/){ $1.upcase }.                 # Break and upcase on hyphenated words
+      gsub(/([a-z])([A-Z])/,'\1_\2').
+      split(/[_\s]+/)
+  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,135 @@
+#
+#       ActiveFacts Runtime API
+#       Value module (mixins for ValueType classes and instances)
+#
+# Copyright (c) 2009 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:
+        args[0] = args[0].__getobj__ if RoleProxy === args[0]
+        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
+
+        class_eval do
+          define_method :restrict do |*value_ranges|
+            @value_ranges = *value_ranges
+          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}"
+          if (args.size == 1 and (arg = args[0]).is_a?(self.class))   # No secondary supertypes allowed for value types
+            arg = arg.__getobj__ if RoleProxy === arg
+            return arg
+          end
+          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_object_type(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
+        # puts "ValueType.included(#{other.inspect})"
+        unless vocabulary.respond_to? :object_type  # Extend module with Vocabulary if necessary
+          vocabulary.send :extend, Vocabulary
+        end
+        vocabulary.__add_object_type(other)
+      end
+    end
+  end
+end