activefacts-api 0.8.9

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rspec

@@ -0,0 +1 @@
+--color

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2008 Clifford Heath.
+
+This software is provided 'as-is', without any express or implied warranty.
+In no event will the authors be held liable for any damages arising from the
+use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not
+   claim that you wrote the original software. If you use this software
+   in a product, an acknowledgment in the product documentation would be
+   appreciated but is not required.
+
+2. Altered source versions must be plainly marked as such, and must not be
+   misrepresented as being the original software.
+
+3. This notice may not be removed or altered from any source distribution.

data/README.rdoc

@@ -0,0 +1,41 @@
+= activefacts-api
+
+The ActiveFacts API provides the fact-oriented information management API
+for the ActiveFacts project.  It is a Ruby DSL for managing constellations
+of elementary facts.  Each fact is either existential (a value or an entity),
+characteristic (boolean) or binary relational (A rel B). Relational facts are
+consistently co-referenced, so you can traverse them efficiently in any
+direction. Each constellation maintains constraints over the fact population.
+
+Contrary to object-oriented and relational modeling, fact oriented models
+do not use the concept of attributes. Fact types which express one-to-one or
+many-to-one relationships are fully mutual relationships between independent
+objects, which play the respective roles in the fact relationship. In addition,
+all objects are intrinsically identified, not by an external object-id. A
+constellation can not contain more than one instance of an object having the
+same identification. Accordingly there is no 'new' or 'delete' operations,
+just 'assert' and 'retract'. This prevents problems caused by having duplicate
+representations of the same object.
+
+The constellation is a universal and liberating data structure.
+
+* http://dataconstellation.com/ActiveFacts/
+
+== INSTALL:
+
+* sudo gem install activefacts-api
+
+== Contributing to activefacts-api
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2008-2011 Clifford Heath. See LICENSE.txt for further details.
+

data/Rakefile

@@ -0,0 +1,50 @@
+require 'rubygems'
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "activefacts-api"
+  gem.homepage = "http://github.com/cjheath/activefacts-api"
+  gem.license = "MIT"
+  gem.summary = "A semantic modeling and query language (CQL) and application runtime (the Constellation API)"
+  gem.description = %q{
+The ActiveFacts API is a Ruby DSL for managing constellations of elementary facts.
+Each fact is either existential (a value or an entity), characteristic (boolean) or
+binary relational (A rel B). Relational facts are consistently co-referenced, so you
+can traverse them efficiently in any direction. Each constellation maintains constraints
+over the fact population.
+}
+  gem.email = "clifford.heath@gmail.com"
+  gem.authors = ["Clifford Heath"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  gem.add_development_dependency "rspec", "~> 2.3.0"
+  gem.add_development_dependency "bundler", "~> 1.0.0"
+  gem.add_development_dependency "jeweler", "~> 1.5.2"
+  # gem.add_development_dependency "rcov", ">= 0"
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "activefacts-api #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.8.9

data/lib/activefacts/api.rb

@@ -0,0 +1,44 @@
+#
+#       ActiveFacts Runtime API.
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
+# The ActiveFacts API is heavily metaprogrammed, so difficult to document.
+#
+# It operates on the principle that a Ruby module is used to encapsulate
+# a Vocabulary (the methods of the class Vocabulary are extend()ed into
+# the module). A Vocabulary contains classes that either derive from a
+# builtin Value type class (see standard_types.rb), or that use the method
+# Class#_identified_by_ to become an Entity (their classes are extend()ed
+# by the class Entity::ClassMethods). Each Value and Entity class also
+# contains the methods of the class ObjectType.
+#
+# A module becomes a Vocabulary when the first ObjectType class is defined within it.
+# A Constellation is a unique collection of ObjectType instances; no two instances may
+# exist of the same value of a ValueType, or having the same identifying roles for
+# an Entity type.
+#
+# Both kinds of ObjectTypes play Roles, which are either binary or unary. Each Role
+# corresponds to an accessor method on Instances which are used to access the
+# counterpart. Roles are created by the class methods *has_one*, *one_to_one*,
+# and *maybe*. The former two create *two* roles, since the role has a counterpart
+# object_type that also plays a role. In the case of a has_one role, the counterpart
+# role is a set, implemented by the RoleValues class, and the accessor method is
+# named beginning with *all_*.
+#
+# The roles of any Instance of any ObjectType may only be played by another Instance
+# of the counterpart ObjectType. There are no raw values, only instances of ValueType
+# classes.
+
+require 'activefacts/api/support'               # General support code and core patches
+require 'activefacts/api/vocabulary'            # A Ruby module may become a Vocabulary
+require 'activefacts/api/role_proxy'            # Experimental proxy for has_one/one_to_one role accessors
+require 'activefacts/api/instance_index'        # The index used by a constellation to record every instance
+require 'activefacts/api/constellation'         # A Constellation is a query result or fact population
+require 'activefacts/api/object_type'               # A Ruby class may become a ObjectType in a Vocabulary
+require 'activefacts/api/role'                  # A ObjectType has a collection of Roles
+require 'activefacts/api/role_values'           # The container used for sets of role players in many_one's
+require 'activefacts/api/instance'              # An Instance is an instance of a ObjectType class
+require 'activefacts/api/value'                 # A Value is an Instance of a value class (String, Numeric, etc)
+require 'activefacts/api/entity'                # An Entity class is an Instance not of a value class
+require 'activefacts/api/standard_types'        # Value classes are augmented so their subclasses may become Value Types

data/lib/activefacts/api/constellation.rb

@@ -0,0 +1,128 @@
+#
+#       ActiveFacts Runtime API
+#       Constellation class
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
+
+module ActiveFacts
+  module API      #:nodoc:
+    # A Constellation is a population of instances of the ObjectType classes of a Vocabulary.
+    # Every object_type 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 also use the populate() method to apply a block of assertions.
+    #
+    # You can instance##retract 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 do |h,k|
+          raise "A constellation over #{@vocabulary.name} can only index instances of object_types in that vocabulary, not #{k.inspect}" unless k.is_a?(Class) and k.modspace == vocabulary
+          h[k] = InstanceIndex.new
+        end
+      end
+
+      def inspect #:nodoc:
+        "Constellation:#{object_id}"
+      end
+
+      # Evaluate assertions against the population of this Constellation
+      def populate *args, &block
+        # REVISIT: Use args for something? Like options to enable/disable validation?
+        instance_eval(&block)
+      end
+
+      # Delete instances from the constellation, nullifying (or cascading) the roles each plays
+      def retract(*instances)
+        Array(instances).each do |i|
+          i.retract
+        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.object_type.keys.sort.map{|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 -= 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
+            "\tEvery #{object_type}:\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,
+                            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
+
+      # This method removes the given instance from this constellation's indexes
+      # It must be called before the identifying roles get deleted or nullified.
+      def __retract(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
+        # 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
+
+      # With parameters, assert an instance of the object_type whose name is the missing method, identified by the values passed as *args*.
+      # With no parameters, return the collection of all instances of that object_type.
+      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 (object_type 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
+    end
+  end
+end

data/lib/activefacts/api/entity.rb

@@ -0,0 +1,260 @@
+#
+#       ActiveFacts Runtime API
+#       Entity class (a mixin module for the class Class)
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
+module ActiveFacts
+  module API
+    # An Entity type is any ObjectType that isn't a value type.
+    # All Entity types must have an identifier made up of one or more roles.
+    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_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_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_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_role_names.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_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_role_names.map{|role|
+            instance_variable_get("@#{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_role_names.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_role_names.map{|role_sym|
+              value = send(role_sym)
+              role_name = self.class.roles(role_sym).name.to_s.camelcase
+              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_role_names.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_role_names
+          @identifying_role_names ||= []
+        end
+
+        def identifying_roles
+          debug :persistence, "Identifying roles for #{basename}" do
+            @identifying_role_names.map{|name|
+              role = roles[name] || (!superclass.is_entity_type || superclass.roles[name])
+              debug :persistence, "#{name} -> #{role ? "found" : "NOT FOUND"}"
+              role
+            }
+          end
+        end
+
+        # 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_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
+              (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_role_names
+          args, arg_hash = ActiveFacts::extract_hash_args(ir, args)
+
+          if args.size > ir.size
+            raise "You've provided too many values for the identifier of #{basename}, which expects (#{ir*', '})"
+          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.counterpart_object_type.basename} using #{arg.inspect}"
+            next !!arg unless role.counterpart  # Unary
+            arg = arg.__getobj__ if RoleProxy === arg
+            if arg.is_a?(role.counterpart_object_type)              # 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
+            if arg == nil # But not false
+              if role.mandatory
+                raise "You must provide a #{role.counterpart_object_type.name} to identify a #{basename}"
+              end
+            else
+              role.counterpart_object_type.identifying_role_values(*arg)
+            end
+          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_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)
+          values = role_values.map do |role, arg|
+              if !arg
+                value = role_key = nil          # No value
+              elsif !role.counterpart
+                value = role_key = !!arg        # Unary
+              elsif arg.is_a?(role.counterpart_object_type)      # 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.counterpart_object_type.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_role_names
+            key = (key_roles = identifying_role_names).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 object_type 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_role_names = superclass.identifying_role_names if superclass.is_entity_type
+          # 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_role_names = args if args.size > 0 || !@identifying_role_names
+        end
+
+        def inherited(other) #:nodoc:
+          other.identified_by *identifying_role_names
+          subtypes << other unless subtypes.include? other
+          #puts "#{self.name} inherited by #{other.name}"
+          vocabulary.__add_object_type(other)
+        end
+
+        # verbalise this object_type
+        def verbalise
+          "#{basename} is identified by #{identifying_role_names.map{|role_sym| role_sym.to_s.camelcase}*" 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
+        # puts "Entity.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