activefacts-api 0.8.12 → 0.9.1

data/.rspec

@@ -1 +1,2 @@
+--require spec_helper
 --color

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - jruby-18mode
+  - jruby-19mode
+  - rbx-18mode
+  - rbx-19mode

data/Gemfile

@@ -0,0 +1,14 @@
+source 'https://rubygems.org'
+
+gem 'rake', :group => [:development, :test]
+
+group :development do
+  gem 'jeweler'
+  gem 'rspec', '~>2.6.0'
+end
+
+group :test do
+  # rcov 1.0.0 is broken for jruby, so 0.9.11 is the only one available.
+  gem 'rcov', '~>0.9.11', :platforms => [:jruby, :mri_18], :require => false
+  gem 'simplecov', '~>0.6.4', :platforms => :mri_19, :require => false
+end

data/Rakefile

@@ -29,19 +29,31 @@ 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
+require 'rdoc/task'
+
+task :default => :spec
 
-RSpec::Core::RakeTask.new(:rcov) do |spec|
-  spec.pattern = 'spec/**/*_spec.rb'
-  spec.rcov_opts = [ '--exclude', 'spec', '--exclude', 'lib/activefacts/tracer.rb' ]
-  spec.rcov = true
+desc "Run Rspec tests"
+RSpec::Core::RakeTask.new(:spec)
+
+desc "Run RSpec tests and produce coverage files (results viewable in coverage/index.html)"
+RSpec::Core::RakeTask.new(:coverage) do |spec|
+  if RUBY_VERSION < '1.9'
+    spec.rcov_opts = [
+        '--exclude', 'spec',
+        '--exclude', 'lib/activefacts/tracer.rb',
+        '--exclude', 'gem/*'
+      ]
+    spec.rcov = true
+  else
+    spec.rspec_opts = ['--require', 'simplecov_helper']
+  end
 end
 
-task :default => :spec
+task :cov => :coverage
+task :rcov => :coverage
+task :simplecov => :coverage
 
-require 'rdoc/task'
 Rake::RDocTask.new do |rdoc|
   version = File.exist?('VERSION') ? File.read('VERSION') : ""
 

data/VERSION

@@ -1 +1 @@
-0.8.12
+0.9.1

data/activefacts-api.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "activefacts-api"
-  s.version = "0.8.12"
+  s.version = "0.9.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Clifford Heath"]
-  s.date = "2012-01-03"
+  s.date = "2012-10-17"
   s.description = "\nThe ActiveFacts API is a Ruby DSL for managing constellations of elementary facts.\nEach fact is either existential (a value or an entity), characteristic (boolean) or\nbinary relational (A rel B). Relational facts are consistently co-referenced, so you\ncan traverse them efficiently in any direction. Each constellation maintains constraints\nover the fact population.\n"
   s.email = "clifford.heath@gmail.com"
   s.extra_rdoc_files = [
@@ -20,6 +20,8 @@ Gem::Specification.new do |s|
   s.files = [
     ".document",
     ".rspec",
+    ".travis.yml",
+    "Gemfile",
     "LICENSE.txt",
     "README.rdoc",
     "Rakefile",
@@ -28,6 +30,7 @@ Gem::Specification.new do |s|
     "lib/activefacts/api.rb",
     "lib/activefacts/api/constellation.rb",
     "lib/activefacts/api/entity.rb",
+    "lib/activefacts/api/exceptions.rb",
     "lib/activefacts/api/instance.rb",
     "lib/activefacts/api/instance_index.rb",
     "lib/activefacts/api/numeric.rb",
@@ -39,37 +42,53 @@ Gem::Specification.new do |s|
     "lib/activefacts/api/value.rb",
     "lib/activefacts/api/vocabulary.rb",
     "lib/activefacts/tracer.rb",
-    "spec/autocounter_spec.rb",
-    "spec/constellation_spec.rb",
-    "spec/entity_type_spec.rb",
-    "spec/identification_spec.rb",
-    "spec/instance_spec.rb",
-    "spec/role_values_spec.rb",
-    "spec/roles_spec.rb",
-    "spec/spec_helper.rb",
-    "spec/value_type_spec.rb"
+    "spec/constellation/constellation_spec.rb",
+    "spec/constellation/instance_index_spec.rb",
+    "spec/constellation/instance_spec.rb",
+    "spec/fact_type/role_values_spec.rb",
+    "spec/fact_type/roles_spec.rb",
+    "spec/fixtures/tax.rb",
+    "spec/identification_scheme/identification_spec.rb",
+    "spec/identification_scheme/identity_change_spec.rb",
+    "spec/identification_scheme/identity_supertype_change_spec.rb",
+    "spec/object_type/entity_type/entity_type_spec.rb",
+    "spec/object_type/entity_type/multipart_identification_spec.rb",
+    "spec/object_type/value_type/autocounter_spec.rb",
+    "spec/object_type/value_type/numeric_spec.rb",
+    "spec/object_type/value_type/value_type_spec.rb",
+    "spec/simplecov_helper.rb",
+    "spec/spec_helper.rb"
   ]
   s.homepage = "http://github.com/cjheath/activefacts-api"
   s.licenses = ["MIT"]
   s.require_paths = ["lib"]
-  s.rubygems_version = "1.8.10"
+  s.rubygems_version = "1.8.24"
   s.summary = "A fact-based data model DSL and API"
 
   if s.respond_to? :specification_version then
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rake>, [">= 0"])
+      s.add_development_dependency(%q<jeweler>, [">= 0"])
+      s.add_development_dependency(%q<rspec>, ["~> 2.6.0"])
       s.add_development_dependency(%q<rspec>, ["~> 2.3.0"])
       s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
       s.add_development_dependency(%q<jeweler>, ["~> 1.5.2"])
       s.add_development_dependency(%q<rdoc>, [">= 2.4.2"])
     else
+      s.add_dependency(%q<rake>, [">= 0"])
+      s.add_dependency(%q<jeweler>, [">= 0"])
+      s.add_dependency(%q<rspec>, ["~> 2.6.0"])
       s.add_dependency(%q<rspec>, ["~> 2.3.0"])
       s.add_dependency(%q<bundler>, ["~> 1.0.0"])
       s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
       s.add_dependency(%q<rdoc>, [">= 2.4.2"])
     end
   else
+    s.add_dependency(%q<rake>, [">= 0"])
+    s.add_dependency(%q<jeweler>, [">= 0"])
+    s.add_dependency(%q<rspec>, ["~> 2.6.0"])
     s.add_dependency(%q<rspec>, ["~> 2.3.0"])
     s.add_dependency(%q<bundler>, ["~> 1.0.0"])
     s.add_dependency(%q<jeweler>, ["~> 1.5.2"])

data/lib/activefacts/api.rb

@@ -41,4 +41,5 @@ require 'activefacts/api/instance'              # An Instance is an instance of
 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
+require 'activefacts/api/exceptions'            # Relevant exceptions
 require 'activefacts/tracer'

data/lib/activefacts/api/constellation.rb

@@ -33,7 +33,9 @@ module ActiveFacts
     #
     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!
+      # 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| ... }
 

data/lib/activefacts/api/entity.rb

@@ -29,17 +29,9 @@ module ActiveFacts
           klass = klass.superclass
         end
 
-#        if (o = klass.overrides_identification_of and !(o.identifying_role_names-klass.identifying_role_names).empty?)
-          # This is a class which must initialise its superclass' identifying roles
-          # The hash can provide the values, but those values must already be asserted
-          # in the constellation this object will exist in, since they won't get
-          # attached to/cloned into that constellation merely by being assigned here.
-          # REVISIT: Nothing takes care of that, currently.
-          #
-          # The solution to this is to have an empty initialize, add the new instance
-          # to the Constellation, then initialise_roles using normal assignment.
-#        end
-
+        if args[-1].respond_to?(:has_key?) && args[-1].has_key?(:constellation)
+          @constellation = args.pop[:constellation]
+        end
         hash = args[-1].is_a?(Hash) ? args.pop.clone : nil
 
         # Pass just the hash, if there is one, else no arguments:
@@ -93,11 +85,11 @@ module ActiveFacts
       # 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_name|
-            return false unless send(role_name).eql?(other.send(role_name))
-          }
-        return true
+        if self.class == other.class
+          identity_as_hash == other.identity_as_hash
+        else
+          false
+        end
       end
 
       # Verbalise this entity instance
@@ -117,12 +109,30 @@ module ActiveFacts
         end
       end
 
+      # Identifying role values in a hash form.
+      def identity_as_hash
+        identity_by(self.class)
+      end
+
+      # Identifying role values in a hash form by class (entity).
+      #
+      # Subtypes may have different identifying roles compared to their supertype, and therefore, a subtype entity
+      # may be identified differently if compared to one of its supertype.
+      def identity_by(klass)
+        roles_hash = {}
+        klass.identifying_roles.each do |role|
+          roles_hash[role.getter] = send(role.getter)
+        end
+        roles_hash
+      end
+
       # All classes that become Entity types receive the methods of this class as class methods:
       module ClassMethods
         include Instance::ClassMethods
 
         attr_accessor :identification_inherited_from
         attr_accessor :overrides_identification_of
+        attr_accessor :created_instances
 
         # Return the array of Role objects that define the identifying relationships of this Entity type:
         def identifying_role_names
@@ -137,11 +147,21 @@ module ActiveFacts
           # REVISIT: Should this return nil if identification_inherited_from?
           @identifying_roles ||=
             identifying_role_names.map do |role_name|
-              role = roles[role_name] || (!superclass.is_entity_type || superclass.roles[role_name])
+              role = roles[role_name] || find_inherited_role(role_name)
               role
             end
         end
 
+        def find_inherited_role(role_name)
+          if !superclass.is_entity_type
+            false
+          elsif superclass.roles.has_key?(role_name)
+            superclass.roles[role_name]
+          else
+            superclass.find_inherited_role(role_name)
+          end
+        end
+
         # Convert the passed arguments into an array of raw values (or arrays of values, transitively)
         # that identify an instance of this Entity type:
         def identifying_role_values(*args)
@@ -150,7 +170,7 @@ module ActiveFacts
           # If the single arg is an instance of the correct class or a subclass,
           # use the instance's identifying_role_values
           has_hash = args[-1].is_a?(Hash)
-          if (args.size == 1+(has_hash ?1:0) and (arg = args[0]).is_a?(self))
+          if (args.size == 1+(has_hash ? 1 : 0) and (arg = args[0]).is_a?(self))
             # With a secondary supertype or a subtype having separate identification,
             # we would get the wrong identifier from arg.identifying_role_values:
             return irns.map do |role_name|
@@ -163,7 +183,7 @@ module ActiveFacts
           args, arg_hash = ActiveFacts::extract_hash_args(irns, args)
 
           if args.size > irns.size
-            raise "You've provided too many values for the identifier of #{basename}, which expects (#{irns*', '})"
+            raise "#{basename} expects only (#{irns*', '}) for its identifier, but you provided the extra values #{args[irns.size..-1].inspect}"
           end
 
           role_args = irns.map{|role_sym| roles(role_sym)}.zip(args)
@@ -198,13 +218,18 @@ module ActiveFacts
           instances = constellation.instances[self]   # All instances of this class in this constellation
           instance = instances[key]
           # REVISIT: This ignores any additional attribute assignments
-          return instance, key if instance      # A matching instance of this class
+          if instance
+            # raise "Additional role values are ignored when asserting an existing instance" if args[-1].is_a? Hash and !args[-1].empty?
+            assign_additional_roles(instance, args[-1]) if args[-1].is_a? Hash and !args[-1].empty?
+            return instance, key      # A matching instance of this class
+          end
 
           # Now construct each of this object's identifying roles
           irns = identifying_role_names
+          @created_instances ||= []
 
           has_hash = args[-1].is_a?(Hash)
-          if args.size == 1+(has_hash ?1:0) and args[0].is_a?(self)
+          if args.size == 1+(has_hash ? 1 : 0) and args[0].is_a?(self)
             # We received a single argument of a compatible type
             # With a secondary supertype or a type having separate identification,
             # we would get the wrong identifier from arg.identifying_role_values:
@@ -222,9 +247,13 @@ module ActiveFacts
                 elsif !arg
                   value = role_key = nil
                 else
-                  #trace :assert, "Asserting #{role.counterpart.object_type} with #{Array(arg).inspect} for #{self}.#{role.name}" do
-                    value, role_key = role.counterpart.object_type.assert_instance(constellation, Array(arg))
-                  #end
+                  if role.counterpart.object_type.is_entity_type
+                    add = !constellation.send(role.counterpart.object_type.basename.to_sym).include?([arg])
+                  else
+                    add = !constellation.send(role.counterpart.object_type.basename.to_sym).include?(arg)
+                  end
+                  value, role_key = role.counterpart.object_type.assert_instance(constellation, Array(arg))
+                  @created_instances << [role.counterpart, value] if add
                 end
                 key << role_key
                 value
@@ -233,19 +262,35 @@ module ActiveFacts
           end
 
           #trace :assert, "Constructing new #{self} with #{values.inspect}" do
-            instance = new(*values)
+          values << { :constellation => constellation }
+          instance = new(*values)
           #end
 
-          # Make the new entity instance a member of this constellation:
-          instance.constellation = constellation
+          assign_additional_roles(instance, arg_hash)
+
+          return *index_instance(instance, key, irns)
+
+        rescue DuplicateIdentifyingValueException
+          @created_instances.each do |role, v|
+            if !v.respond_to?(:retract)
+              v = constellation.send(role.object_type.basename.to_sym)[[v]]
+            end
+            v.retract if v
+          end
+          @created_instances = []
+          raise
+        end
 
+        def assign_additional_roles(instance, arg_hash)
           # Now assign any extra args in the hash which weren't identifiers (extra identifiers will be assigned again)
           (arg_hash ? arg_hash.entries : []).each do |role_name, value|
             role = roles(role_name)
+
+            if !instance.instance_index_counterpart(role).include?(value)
+              @created_instances << [role, value]
+            end
             instance.send(role.setter, value)
           end
-
-          return *index_instance(instance, key, irns)
         end
 
         def index_instance(instance, key = nil, key_roles = nil) #:nodoc:

data/lib/activefacts/api/exceptions.rb

@@ -0,0 +1,17 @@
+#
+#       ActiveFacts Runtime API
+#       Custom exception classes
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+
+module ActiveFacts
+  module API
+    class DuplicateIdentifyingValueException < StandardError
+      def initialize(desc)
+        super("Illegal attempt to assert #{desc[:class].basename} having identifying value" +
+              " (#{desc[:role].name} is #{desc[:value].verbalise})," +
+              " when #{desc[:value].related_entities.map(&:verbalise).join(", ")} already exists")
+      end
+    end
+  end
+end

data/lib/activefacts/api/instance.rb

@@ -24,8 +24,99 @@ module ActiveFacts
         end
       end
 
+      # Detect inconsistencies within constellation if this entity was updated
+      # with the specified role/value pair.
+      def detect_inconsistencies(role, value)
+        if duplicate_identifying_values?(role, value)
+          exception_data = {
+            :value => value,
+            :role  => role,
+            :class => self.class
+          }
+
+          raise DuplicateIdentifyingValueException.new(exception_data)
+        end
+      end
+
+      # Checks if instance have duplicate values within its constellation.
+      #
+      # Only works on identifying roles.
+      def duplicate_identifying_values?(role, value)
+        @constellation && role.is_identifying && !is_unique?(:role => role, :value => value)
+      end
+
+      # Checks if instance would still be unique if it was updated with
+      # args.
+      #
+      # args should be a hash containing the role and value to update
+      # and the name of the identifying value as the key.
+      #
+      # For example, if a Person is identified by name and family_name:
+      # updated_values = { :name => "John" }
+      # Would merge this hash with the one defining the current instance
+      # and verify in our constellation if it exists.
+      #
+      # The uniqueness of the entity will also be checked within its supertypes.
+      #
+      # An Employee -subtype of a Person- identified by its employee_id would
+      # collide with a Person if it has the same name. But `name` may not be
+      # an identifying value for the Employee identification scheme.
+      def is_unique?(args)
+        duplicate = ([self.class] + self.class.supertypes_transitive).detect do |klass|
+          old_identity = identity_by(klass)
+          if klass.identifying_roles.include?(args[:role])
+            new_identity = old_identity.merge(args[:role].getter => args[:value])
+            @constellation.instances[klass].include?(new_identity)
+          else
+            false
+          end
+        end
+
+        !duplicate
+      end
+
+      # List entities which reference the current one.
+      #
+      # Once an entity is found, it will also search for
+      # related entities of this instance.
+      def related_entities(instances = [])
+        self.class.roles.each do |role_name, role|
+          instance_index_counterpart(role).each do |irv, instance|
+            if instance.class.is_entity_type && instance.is_identified_by?(self)
+              if !instances.include?(instance)
+                instances << instance
+                instance.related_entities(instances)
+              end
+            end
+          end
+        end
+        instances
+      end
+
+      # Determine if entity is an identifying value
+      # of the current instance.
+      def is_identified_by?(entity)
+        self.class.identifying_roles.detect do |role|
+          send(role.getter) == entity
+        end
+      end
+
+      def instance_index
+        @constellation.send(self.class.basename.to_sym)
+      end
+
+      def instance_index_counterpart(role)
+        if @constellation && role.counterpart
+          @constellation.send(role.counterpart.object_type.basename.to_sym)
+        else
+          []
+        end
+      end
+
       # Verbalise this instance
+      # REVISIT: Should it raise an error if it was not redefined ?
       def verbalise
+        # REVISIT: Should it raise an error if it was not redefined ?
         # This method should always be overridden in subclasses
       end
 
@@ -48,7 +139,11 @@ module ActiveFacts
               # puts "Not removing role #{role_name} from counterpart RoleValues #{counterpart.name}"
               # Duplicate the array using to_a, as the RoleValues here will be modified as we traverse it:
               send(role.name).to_a.each do |v|
-                v.send(counterpart.setter, nil)
+                if counterpart.is_identifying
+                  v.retract
+                else
+                  v.send(counterpart.setter, nil)
+                end
               end
             end
           end