activefacts 0.7.0 → 0.7.1

data/lib/activefacts/persistence/reference.rb

@@ -1,4 +1,9 @@
 #
+#       ActiveFacts Relational mapping and persistence.
+#       Reference from one Concept to another, used to decide the relational mapping.
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
 # A Reference from one Concept to another is created for each many-1 or 1-1 relationship
 # (including subtyping), and also for a unary role (implicitly to Boolean concept).
 # A 1-1 or subtyping reference should be created in only one direction, and may be flipped
@@ -11,12 +16,25 @@
 #
 # Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
 #
-# REVISIT: References need is_mandatory
-# REVISIT: Need to index References by to_role, to help in finding PK references etc.
 
 module ActiveFacts
-  module Metamodel
-
+  module Persistence
+
+    # This class contains the core data structure used in composing a relational schema.
+    #
+    # A Reference is *from* one Concept *to* another Concept, and relates to the *from_role* and the *to_role*.
+    # When either Concept is an objectified fact type, the corresponding role is nil.
+    # When the Reference from_role is of a unary fact type, there's no to_role or to Concept.
+    # The final kind of Reference is a self-reference which is added to a ValueType that becomes a table.
+    #
+    # When the underlying fact type is a one-to-one (including an inheritance fact type), the Reference may be flipped.
+    #
+    # Each Reference has a name; an array of names in fact, in case of adjectives, etc.
+    # Each Refererence can produce the reading of the underlying fact type.
+    #
+    # A Reference is indexed in the player's *references_from* and *references_to*, and flipping updates those.
+    # Finally, a Reference may be marked as absorbing the whole referenced object, and that can flip too.
+    #
     class Reference
       attr_reader :from, :to            # A "from" instance is related to one "to" instance
       attr_reader :from_role, :to_role  # For objectified facts, one role will be nil (a phantom)
@@ -46,44 +64,53 @@ module ActiveFacts
         end
       end
 
+      # What type of Role did this Reference arise from?
       def role_type
         role = @from_role||@to_role
         role && role.role_type
       end
 
+      # Is this Reference covered by a mandatory constraint (implicitly or explicitly)
       def is_mandatory
         !@from_role ||        # All phantom roles of fact types are mandatory
         is_unary ||           # Unary fact types become booleans, which must be true or false
         @from_role.is_mandatory
       end
 
+      # Is this Reference from a unary Role?
       def is_unary
         !@to && @to_role && @to_role.fact_type.all_role.size == 1
       end
 
-      # This case is the only one that cannot be used in the preferred identifier of @from
+      # If this Reference is to an objectified FactType, there is no *to_role*
       def is_to_objectified_fact
+        # This case is the only one that cannot be used in the preferred identifier of @from
         @to && !@to_role && @from_role
       end
 
+      # If this Reference is from an objectified FactType, there is no *from_role*
       def is_from_objectified_fact
         @to && @to_role && !@from_role
       end
 
+      # Is this reference an injected role as a result a ValueType being a table?
       def is_self_value
         !@to && !@to_role
       end
 
+      # Is the *to* concept fully absorbed through this reference?
       def is_absorbing
         @to && @to.absorbed_via == self
       end
 
+      # Is this a simple reference?
       def is_simple_reference
         # It's a simple reference to a thing if that thing is a table,
         # or is fully absorbed into another table but not via this reference.
         @to && (@to.is_table or @to.absorbed_via && !is_absorbing)
       end
 
+      # Return the array of names for the (perhaps implicit) *to_role* of this Reference
       def to_names
         case
         when is_unary
@@ -100,8 +127,8 @@ module ActiveFacts
         end
       end
 
-      # For a one-to-one (or a subtyping fact type), reverse the direction:
-      def flip
+      # For a one-to-one (or a subtyping fact type), reverse the direction.
+      def flip                          #:nodoc:
         raise "Illegal flip of #{self}" unless @to and [:one_one, :subtype, :supertype].include?(role_type)
 
         detabulate
@@ -118,7 +145,7 @@ module ActiveFacts
         tabulate
       end
 
-      def tabulate
+      def tabulate        #:nodoc:
         # Add to @to and @from's reference lists
         @from.references_from << self
         @to.references_to << self if @to        # Guard against self-values
@@ -127,7 +154,7 @@ module ActiveFacts
         self
       end
 
-      def detabulate
+      def detabulate        #:nodoc:
         # Remove from @to and @from's reference lists if present
         return unless @from.references_from.delete(self)
         @to.references_to.delete self if @to    # Guard against self-values
@@ -135,96 +162,104 @@ module ActiveFacts
         self
       end
 
-      def to_s
+      def to_s              #:nodoc:
         "reference from #{@from.name}#{@to ? " to #{@to.name}" : ""}" + (@fact_type ? " in '#{@fact_type.default_reading}'" : "")
       end
 
+      # The reading for the fact type underlying this Reference
       def reading
         is_self_value ? "#{from.name} has value" : @fact_type.default_reading
       end
 
-      def inspect; to_s; end
+      def inspect #:nodoc:
+        to_s
+      end
     end
+  end
 
+  module Metamodel          #:nodoc:
     class Concept
       # Say whether the independence of this object is still under consideration
       # This is used in detecting dependency cycles, such as occurs in the Metamodel
-      attr_accessor :tentative
-      attr_writer :is_table     # The two Concept subclasses provide the reader
+      attr_accessor :tentative          #:nodoc:
+      attr_writer :is_table             # The two Concept subclasses provide the attr_reader method
 
-      def show_tabular
+      def show_tabular                  #:nodoc:
         (tentative ? "tentatively " : "") +
         (is_table ? "" : "not ")+"a table"
       end
 
-      def definitely_table
+      def definitely_table              #:nodoc:
         @is_table = true
         @tentative = false
       end
 
-      def definitely_not_table
+      def definitely_not_table          #:nodoc:
         @is_table = false
         @tentative = false
       end
 
-      def probably_table
+      def probably_table                #:nodoc:
         @is_table = true
         @tentative = true
       end
 
-      def probably_not_table
+      def probably_not_table            #:nodoc:
         @is_table = false
         @tentative = true
       end
 
+      # References from this Concept
       def references_from
         @references_from ||= []
       end
 
+      # References to this Concept
       def references_to
         @references_to ||= []
       end
 
-      def has_references
+      # True if this Concept has any References (to or from)
+      def has_references                #:nodoc:
         @references_from || @references_to
       end
 
-      def clear_references
+      def clear_references              #:nodoc:
         # Clear any previous references:
         @references_to = nil
         @references_from = nil
       end
 
-      def populate_references
+      def populate_references           #:nodoc:
         all_role.each do |role|
           populate_reference role
         end
       end
 
-      def populate_reference role
+      def populate_reference role       #:nodoc:
         role_type = role.role_type
         debug :references, "#{name} has #{role_type} role in '#{role.fact_type.describe}'"
         case role_type
         when :many_one
-          Reference.new(self, role).tabulate      # A simple reference
+          ActiveFacts::Persistence::Reference.new(self, role).tabulate      # A simple reference
 
         when :one_many
           if role.fact_type.entity_type == self   # A Role of this objectified FactType
-            Reference.new(self, role).tabulate    # A simple reference; check that
+            ActiveFacts::Persistence::Reference.new(self, role).tabulate    # A simple reference; check that
           else
             # Can't absorb many of these into one of those
             #debug :references, "Ignoring #{role_type} reference from #{name} to #{Reference.new(self, role).to.name}"
           end
 
         when :unary
-          Reference.new(self, role).tabulate      # A simple reference
+          ActiveFacts::Persistence::Reference.new(self, role).tabulate      # A simple reference
 
         when :supertype   # A subtype absorbs a reference to its supertype when separate, or all when partitioned
           # REVISIT: Or when partitioned
           if role.fact_type.subtype.is_independent
             debug :references, "supertype #{name} doesn't absorb a reference to separate subtype #{role.fact_type.subtype.name}"
           else
-            r = Reference.new(self, role)
+            r = ActiveFacts::Persistence::Reference.new(self, role)
             r.to.absorbed_via = r
             debug :references, "supertype #{name} absorbs subtype #{r.to.name}"
             r.tabulate
@@ -232,14 +267,14 @@ module ActiveFacts
 
         when :subtype    # This object is a supertype, which can absorb the subtype unless that's independent
           if is_independent    # REVISIT: Or when partitioned
-            Reference.new(self, role).tabulate
+            ActiveFacts::Persistence::Reference.new(self, role).tabulate
             # If partitioned, the supertype is absorbed into *each* subtype; a reference to the supertype needs to know which
           else
             # debug :references, "subtype #{name} is absorbed into #{role.fact_type.supertype.name}"
           end
 
         when :one_one
-          r = Reference.new(self, role)
+          r = ActiveFacts::Persistence::Reference.new(self, role)
 
           # Decide which way the one-to-one is likely to go; it will be flipped later if necessary.
           # Force the decision if just one is independent:
@@ -281,7 +316,7 @@ module ActiveFacts
     end
 
     class EntityType
-      def populate_references
+      def populate_references          #:nodoc:
         if fact_type && fact_type.all_role.size > 1
           # NOT: fact_type.all_role.each do |role|  # Place roles in the preferred order instead:
           fact_type.preferred_reading.role_sequence.all_role_ref.map(&:role).each do |role|
@@ -293,7 +328,7 @@ module ActiveFacts
     end
 
     class Vocabulary
-      def populate_all_references
+      def populate_all_references #:nodoc:
         debug :references, "Populating all concept references" do
           all_feature.each do |feature|
             next unless feature.is_a? Concept

data/lib/activefacts/persistence/tables.rb

@@ -1,14 +1,15 @@
 #
-# Calculate the relational composition of a given Vocabulary
-# The composition consists of decisiona about which Concepts are tables,
-# and what columns (absorbed roled) those tables will have.
+#       ActiveFacts Relational mapping and persistence.
+#       Tables; Calculate the relational composition of a given Vocabulary.
+#       The composition consists of decisions about which Concepts are tables,
+#       and what columns (absorbed roled) those tables will have.
 #
-# This module has the following known problems:
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 #
-# * Some one-to-ones absorb in both directions (ET<->FT in Metamodel, Blog model)
+# This module has the following known problems:
 #
-# * When a subtype has no mandatory roles, we should introduce
-#   a binary (is_subtype) to indicate it's that subtype.
+# * When a subtype has no mandatory roles, we should support an optional schema transformation step
+#   that introduces a boolean (is_subtype) to indicate it's that subtype.
 #
 
 require 'activefacts/persistence/reference'
@@ -17,9 +18,12 @@ module ActiveFacts
   module Metamodel
 
     class ValueType
-      def absorbed_via; nil; end  # ValueTypes aren't absorbed in the way EntityTypes are
+      def absorbed_via  #:nodoc:
+        # ValueTypes aren't absorbed in the way EntityTypes are
+        nil
+      end
 
-      # Say whether this object is currently considered a table or not:
+      # Returns true if this ValueType is a table
       def is_table
         return @is_table if @is_table != nil
 
@@ -42,20 +46,27 @@ module ActiveFacts
         @is_table
       end
 
-      # REVISIT: Find a better way to determine AutoCounters (ValueType unary role?)
+      # Is this ValueType auto-assigned on first save to the database?
       def is_auto_assigned
-        type = self;
+        # REVISIT: Find a better way to determine AutoCounters (ValueType unary role?)
+        type = self
         type = type.supertype while type.supertype
         type.name =~ /^Auto/
       end
     end
 
     class EntityType
-      attr_accessor :absorbed_via   # A reference from an entity type that fully absorbs this one
+      # A Reference from an entity type that fully absorbs this one
+      def absorbed_via; @absorbed_via; end
+      def absorbed_via=(r) #:nodoc:
+        @absorbed_via = r
+      end
 
-      def is_auto_assigned; false; end
+      def is_auto_assigned  #:nodoc:
+        false
+      end
 
-      # Decide whether this object is currently considered a table or not:
+      # Returns true if this EntityType is a table
       def is_table
         return @is_table if @is_table != nil  # We already make a guess or decision
 
@@ -99,7 +110,7 @@ module ActiveFacts
       end
     end # EntityType class
 
-    class Role
+    class Role    #:nodoc:
       def role_type
         # TypeInheritance roles are always 1:1
         if TypeInheritance === fact_type
@@ -123,7 +134,7 @@ module ActiveFacts
           all_uniqueness_constraints.
             detect do |c|
                 c.role_sequence.all_role_ref.size == 1 and
-                c.role_sequence.all_role_ref[0].role == self
+                c.role_sequence.all_role_ref.only.role == self
             end
 
         if fact_type.entity_type
@@ -152,7 +163,7 @@ module ActiveFacts
         @tables
       end
 
-      def decide_tables
+      def decide_tables #:nodoc:
         # Strategy:
         # 1) Populate references for all Concepts
         # 2) Decide which Concepts must be and must not be tables

data/lib/activefacts/support.rb

@@ -1,3 +1,10 @@
+#
+#       ActiveFacts Support code.
+#       The debug method supports indented tracing.
+#       Set the DEBUG environment variable to enable it. Search the code to find the DEBUG keywords, or use "all".
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
 #module ActiveFacts
   $debug_indent = nil
   $debug_nested = false
@@ -38,6 +45,7 @@
   end
 #end
 
+# Return all duplicate objects in the array (using hash-equality)
 class Array
   def duplicates(&b)
     inject({}) do |h,e|

data/lib/activefacts/version.rb

@@ -1,3 +1,9 @@
+#
+#       ActiveFacts Support code.
+#       Version number file.
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
 module ActiveFacts
-  VERSION = '0.7.0'
+  VERSION = '0.7.1'
 end

data/lib/activefacts/vocabulary.rb

@@ -1,6 +1,8 @@
 #
-# The ActiveFacts Vocabulary API, generated from Metamodel.orm with extensions:
-# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#       ActiveFacts Vocabulary Metamodel.
+#       The ActiveFacts Vocabulary API is generated from Metamodel.orm with extensions:
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 #
 require 'activefacts/vocabulary/metamodel'
 require 'activefacts/vocabulary/extensions'

data/lib/activefacts/vocabulary/extensions.rb

@@ -1,6 +1,8 @@
 #
-# Extensions to the ActiveFacts Vocabulary API (which is generated from the Metamodel)
-# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#       ActiveFacts Vocabulary Metamodel.
+#       Extensions to the ActiveFacts Vocabulary classes (which are generated from the Metamodel)
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 #
 module ActiveFacts
   module Metamodel
@@ -112,7 +114,7 @@ module ActiveFacts
       end
 
       def subtypes
-        all_value_type_by_supertype
+        all_value_type_as_supertype
       end
     end
 
@@ -122,7 +124,7 @@ module ActiveFacts
         if fact_type
 
           # For a nested fact type, the PI is a unique constraint over N or N-1 roles
-          fact_roles = fact_type.all_role
+          fact_roles = Array(fact_type.all_role)
           debug :pi, "Looking for PI on nested fact type #{name}" do
             pi = catch :pi do
                 fact_roles[0,2].each{|r|                  # Try the first two roles of the fact type, that's enough
@@ -171,7 +173,7 @@ module ActiveFacts
               debug :pi, "PI roles must be played by one of #{all_supertypes.map(&:name)*", "}" if all_supertypes.size > 1
               all_role.each{|role|
                   next unless role.unique || fact_type
-                  ftroles = role.fact_type.all_role
+                  ftroles = Array(role.fact_type.all_role)
 
                   # Skip roles in ternary and higher fact types, they're objectified, and in unaries, they can't identify us.
                   next if ftroles.size != 2
@@ -262,11 +264,11 @@ module ActiveFacts
       # An array of all direct subtypes:
       def subtypes
         # REVISIT: There's no sorting here. Should there be?
-        all_type_inheritance_by_supertype.map{|ti| ti.subtype }
+        all_type_inheritance_as_supertype.map{|ti| ti.subtype }
       end
 
       def all_supertype_inheritance
-        all_type_inheritance_by_subtype.sort_by{|ti|
+        all_type_inheritance_as_subtype.sort_by{|ti|
             [ti.provides_identification ? 0 : 1, ti.supertype.name]
           }
       end
@@ -280,7 +282,7 @@ module ActiveFacts
 
       # An array of self followed by all supertypes in order:
       def supertypes_transitive
-        ([self] + all_type_inheritance_by_subtype.map{|ti|
+        ([self] + all_type_inheritance_as_subtype.map{|ti|
             # debug ti.class.roles.verbalise; exit
             ti.supertype.supertypes_transitive
           }).flatten.uniq
@@ -289,7 +291,7 @@ module ActiveFacts
       # A subtype does not have a identifying_supertype if it defines its own identifier
       def identifying_supertype
         debug "Looking for identifying_supertype of #{name}"
-        all_type_inheritance_by_subtype.detect{|ti|
+        all_type_inheritance_as_subtype.detect{|ti|
             debug "considering supertype #{ti.supertype.name}"
             next unless ti.provides_identification
             debug "found identifying supertype of #{name}, it's #{ti.supertype.name}"
@@ -356,7 +358,7 @@ module ActiveFacts
         reject{|s| s==' '}.                 # Remove white space
         map do |frag|                       # and go through the bits
           if frag =~ /\{([0-9]+)\}/
-            role_sequence.all_role_ref[$1.to_i]
+            role_sequence.all_role_ref.detect{|rr| rr.ordinal == $1.to_i}
           else
             frag
           end