activefacts 0.6.0

data/lib/activefacts/support.rb

@@ -0,0 +1,51 @@
+#module ActiveFacts
+  $debug_indent = nil
+  $debug_nested = false
+  $debug_keys = nil
+  def debug(*args, &block)
+    unless $debug_indent
+      # First time, initialise the tracing environment
+      $debug_indent = 0
+      $debug_keys = {}
+      if (e = ENV["DEBUG"])
+        e.split(/[^a-z]/).each{|k| $debug_keys[k.to_sym] = true }
+      end
+    end
+
+    # Figure out whether this trace is enabled and nests:
+    control = (!args.empty? && Symbol === args[0]) ? args.shift : :all
+    key = control.to_s.sub(/_\Z/, '')
+    enabled = $debug_nested || $debug_keys[key.to_sym]
+    nesting = control.to_s =~ /_\Z/
+    old_nested = $debug_nested
+    $debug_nested = nesting
+
+    # Emit the message if enabled or a parent is:
+    puts "# "+"  "*$debug_indent + args.join(' ') if args.size > 0 && enabled
+
+    if block
+      begin
+        $debug_indent += 1 if enabled
+        r = yield       # Return the value of the block
+      ensure
+        $debug_indent -= 1 if enabled
+        $debug_nesting = old_nested
+      end
+    else
+      r = enabled     # Return whether enabled
+    end
+    r
+  end
+#end
+
+class Array
+  def duplicates(&b)
+    inject({}) do |h,e|
+      h[e] ||= 0
+      h[e] += 1
+      h
+    end.reject do |k,v|
+      v == 1
+    end.keys
+  end
+end

data/lib/activefacts/version.rb

@@ -0,0 +1,3 @@
+module ActiveFacts
+  VERSION = '0.6.0'
+end

data/lib/activefacts/vocabulary.rb

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

data/lib/activefacts/vocabulary/extensions.rb

@@ -0,0 +1,343 @@
+#
+# Extensions to the ActiveFacts Vocabulary API (which is generated from the Metamodel)
+# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#
+module ActiveFacts
+  module Metamodel
+
+    class FactType
+      def all_reading_by_ordinal
+        all_reading.sort_by{|reading| reading.ordinal}
+      end
+
+      def preferred_reading
+        all_reading_by_ordinal[0]
+      end
+
+      def describe(highlight = nil)
+        (entity_type ? entity_type.name : "")+
+        '('+all_role.map{|role| role.describe(highlight) }*", "+')'
+      end
+
+      def default_reading(frequency_constraints = [], define_role_names = false)
+        preferred_reading.expand(frequency_constraints, define_role_names)
+      end
+    end
+
+    class Role
+      def describe(highlight = nil)
+        concept.name + (self == highlight ? "*" : "")
+      end
+
+      # Is there are internal uniqueness constraint on this role only?
+      def unique
+        all_role_ref.detect{|rr|
+          rs = rr.role_sequence
+          rs.all_role_ref.size == 1 and
+          rs.all_presence_constraint.detect{|pc|
+            pc.max_frequency == 1
+          }
+        }
+      end
+
+      # Return the RoleRef to this role from its fact type's preferred_reading
+      def preferred_reference
+        fact_type.preferred_reading.role_sequence.all_role_ref.detect{|rr| rr.role == self }
+      end
+    end
+
+    class JoinPath
+      def column_name(joiner = '-')
+        concept == input_role.concept ? input_role.preferred_reference.role_name(joiner) : Array(concept.name)
+      end
+
+      def describe
+        "#{input_role.fact_type.describe(input_role)}->" +
+          concept.name +
+          (output_role ? "->#{output_role.fact_type.describe(output_role)}":"")
+      end
+    end
+
+    class RoleRef
+      def describe
+        # The reference traverses the JoinPaths in sequence to the final role:
+        all_join_path.sort_by{|jp| jp.join_step}.map{ |jp| jp.describe + "." }*"" + role_name
+      end
+
+      def role_name(joiner = "-")
+        name_array =
+          if role.fact_type.all_role.size == 1
+            role.fact_type.preferred_reading.reading_text.gsub(/\{[0-9]\}/,'').strip.split(/\s/)
+          else
+            role.role_name || [leading_adjective, role.concept.name, trailing_adjective].compact.map{|w| w.split(/\s/)}.flatten
+          end
+        return joiner ? Array(name_array)*joiner : Array(name_array)
+      end
+    end
+
+    class RoleSequence
+      def describe
+        "("+
+          all_role_ref.sort_by{|rr| rr.ordinal}.map{|rr| rr.describe }*", "+
+        ")"
+      end
+    end
+
+    class ValueType
+      def supertypes_transitive
+        [self] + (supertype ? supertype.supertypes_transitive : [])
+      end
+
+      def subtypes
+        all_value_type_by_supertype
+      end
+    end
+
+    class EntityType
+      include ActiveFacts
+      def preferred_identifier
+        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
+          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
+                    r.all_role_ref.map{|rr|               # All role sequences that reference this role
+                        role_sequence = rr.role_sequence
+
+                        # The role sequence is only interesting if it cover only this fact's roles
+                        next if role_sequence.all_role_ref.size < fact_roles.size-1 # Not enough roles
+                        next if role_sequence.all_role_ref.size > fact_roles.size   # Too many roles
+                        next if role_sequence.all_role_ref.detect{|rsr| ft = rsr.role.fact_type; ft != fact_type }
+
+                        # This role sequence is a candidate
+                        pc = role_sequence.all_presence_constraint.detect{|c|
+                            c.max_frequency == 1 && c.is_preferred_identifier
+                          }
+                        throw :pi, pc if pc
+                      }
+                  }
+                throw :pi, nil
+              end
+            debug :pi, "Got PI #{pi.name||pi.object_id} for nested #{name}" if pi
+            debug :pi, "Looking for PI on entity that nests this fact" unless pi
+            raise "Oops, pi for nested fact is #{pi.class}" unless !pi || PresenceConstraint === pi
+            return pi if pi
+          end
+        end
+
+        debug :pi, "Looking for PI for ordinary entity #{name} with #{all_role.size} roles:" do
+          debug :pi, "Roles are in fact types #{all_role.map{|r| r.fact_type.describe(r)}*", "}"
+          pi = catch :pi do
+              all_supertypes = supertypes_transitive
+              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
+
+                  # Skip roles in ternary and higher fact types, they're objectified, and in unaries, they can't identify us.
+                  next if ftroles.size != 2
+
+                  debug :pi, "Considering role in #{role.fact_type.describe(role)}"
+
+                  # Find the related role which must be included in any PI:
+                  # Note this works with unary fact types:
+                  pi_role = ftroles[ftroles[0] != role ? 0 : -1]
+
+                  next if ftroles.size == 2 && pi_role.concept == self
+                  debug :pi, "  Considering #{pi_role.concept.name} as a PI role"
+
+                  # If this is an identifying role, the PI is a PC whose role_sequence spans the role.
+                  # Walk through all role_sequences that span this role, and test each:
+                  pi_role.all_role_ref.each{|rr|
+                      role_sequence = rr.role_sequence  # A role sequence that includes a possible role
+
+                      debug :pi, "    Considering role sequence #{role_sequence.describe}"
+
+                      # All roles in this role_sequence must be in fact types which
+                      # (apart from that role) only have roles played by the original
+                      # entity type or a supertype.
+                      #debug :pi, "      All supertypes #{all_supertypes.map{|st| "#{st.object_id}=>#{st.name}"}*", "}"
+                      if role_sequence.all_role_ref.detect{|rsr|
+                          fact_type = rsr.role.fact_type
+                          debug :pi, "      Role Sequence touches #{fact_type.describe(pi_role)}"
+
+                          fact_type_roles = fact_type.all_role
+                          debug :pi, "      residual is #{fact_type_roles.map{|r| r.concept.name}.inspect} minus #{rsr.role.concept.name}"
+                          residual_roles = fact_type_roles-[rsr.role]
+                          residual_roles.detect{|rfr|
+                              debug :pi, "        Checking residual role #{rfr.concept.object_id}=>#{rfr.concept.name}"
+# This next line looks right, but breaks things. Find out what and why:
+#                              !rfr.unique or
+                                !all_supertypes.include?(rfr.concept)
+                            }
+                        }
+                        debug :pi, "      Discounting this role_sequence because it includes alien roles"
+                        next
+                      end
+
+                      # Any presence constraint over this role sequence is a candidate
+                      rr.role_sequence.all_presence_constraint.detect{|pc|
+                          # Found it!
+                          if pc.is_preferred_identifier
+                            debug :pi, "found PI #{pc.name||pc.object_id}, is_preferred_identifier=#{pc.is_preferred_identifier.inspect} over #{pc.role_sequence.describe}"
+                            throw :pi, pc
+                          end
+                        }
+                    }
+                }
+              throw :pi, nil
+            end
+          raise "Oops, pi for entity is #{pi.class}" if pi && !(PresenceConstraint === pi)
+          debug :pi, "Got PI #{pi.name||pi.object_id} for #{name}" if pi
+
+          if !pi
+            if (supertype = identifying_supertype)
+              # This shouldn't happen now, as an identifying supertype is connected by a fact type
+              # that has a uniqueness constraint marked as the preferred identifier.
+              #debug :pi, "PI not found for #{name}, looking in supertype #{supertype.name}"
+              #pi = supertype.preferred_identifier
+              #return nil
+            elsif fact_type
+              fact_type.all_role.each{|role|
+                role.all_role_ref.each{|role_ref|
+                  # Discount role sequences that contain roles not in this fact type:
+                  next if role_ref.role_sequence.all_role_ref.detect{|rr| rr.role.fact_type != fact_type }
+                  role_ref.role_sequence.all_presence_constraint.each{|pc|
+                    next unless pc.is_preferred_identifier and pc.max_frequency == 1
+                    pi = pc
+                    break
+                  }
+                  break if pi
+                }
+                break if pi
+              }
+            else
+              debug :pi, "No PI found for #{name}"
+            end
+          end
+          raise "No PI found for #{name}" unless pi
+          pi
+        end
+      end
+
+      # 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 }
+      end
+
+      def all_supertype_inheritance
+        all_type_inheritance_by_subtype.sort_by{|ti|
+            [ti.provides_identification ? 0 : 1, ti.supertype.name]
+          }
+      end
+
+      # An array all direct supertypes
+      def supertypes
+        all_supertype_inheritance.map{|ti|
+            ti.supertype
+          }
+      end
+
+      # An array of self followed by all supertypes in order:
+      def supertypes_transitive
+          ([self] + all_type_inheritance_by_subtype.map{|ti|
+              # debug ti.class.roles.verbalise; exit
+              ti.supertype.supertypes_transitive
+            }).flatten.uniq
+      end
+
+      # 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|
+            debug "considering supertype #{ti.supertype.name}"
+            next unless ti.provides_identification
+            debug "found identifying supertype of #{name}, it's #{ti.supertype.name}"
+            return ti.supertype
+          }
+        debug "Failed to find identifying supertype of #{name}"
+        return nil
+      end
+    end
+
+    class Reading
+      # The frequency_constraints array here, if supplied, may provide for each role either:
+      # * a PresenceConstraint to be verbalised against the relevant role, or
+      # * a String, used as a definite or indefinite article on the relevant role, or
+      # * an array containing two strings (an article and a super-type name)
+      # The order in the array is the same as the reading's role-sequence.
+      # REVISIT: This should probably be changed to be the fact role sequence.
+      #
+      # define_role_names here is false (use defined names), true (define names) or nil (neither)
+      def expand(frequency_constraints = [], define_role_names = false)
+        expanded = "#{reading_text}"
+        role_refs = role_sequence.all_role_ref.sort_by{|role_ref| role_ref.ordinal}
+        (0...role_refs.size).each{|i|
+            role_ref = role_refs[i]
+            role = role_ref.role
+            la = "#{role_ref.leading_adjective}"
+            la.sub!(/(.\b|.\Z)/, '\1-')
+            la = nil if la == ""
+            ta = "#{role_ref.trailing_adjective}"
+            ta.sub!(/(\b.|\A.)/, '-\1')
+            ta = nil if ta == ""
+
+            expanded.gsub!(/\{#{i}\}/) {
+                player = role_refs[i].role.concept
+                role_name = role.role_name
+                role_name = nil if role_name == ""
+                if role_name && define_role_names == false
+                  la = ta = nil   # When using role names, don't add adjectives
+                end
+                fc = frequency_constraints[i]
+                fc = fc.frequency if fc && PresenceConstraint === fc
+                if Array === fc
+                  fc, player_name = *fc
+                else
+                  player_name = player.name
+                end
+                [
+                  fc ? fc : nil,
+                  la,
+                  define_role_names == false && role_name ? role_name : player_name,
+                  ta,
+                  define_role_names && role_name && player.name != role_name ? "(as #{role_name})" : nil
+                ].compact*" "
+            }
+        }
+        expanded.gsub!(/ *- */, '-')      # Remove spaces around adjectives
+        #debug "Expanded '#{expanded}' using #{frequency_constraints.inspect}"
+        expanded
+      end
+
+      def words_and_role_refs
+        reading_text.
+        scan(/(?: |\{[0-9]+\}|[^{} ]+)/).   # split up the text into words
+        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]
+          else
+            frag
+          end
+        end
+      end
+    end
+
+    class PresenceConstraint
+      def frequency
+        min = min_frequency
+        max = max_frequency
+        [
+            ((min && min > 0 && min != max) ? "at least #{min == 1 ? "one" : min.to_s}" : nil),
+            ((max && min != max) ? "at most #{max == 1 ? "one" : max.to_s}" : nil),
+            ((max && min == max) ? "#{max == 1 ? "one" : max.to_s}" : nil)
+        ].compact * " and"
+      end
+    end
+
+  end
+end

data/lib/activefacts/vocabulary/metamodel.rb

@@ -0,0 +1,303 @@
+require 'activefacts/api'
+
+module ActiveFacts
+  module Metamodel
+
+    class Adjective < String
+      value_type :length => 64
+    end
+
+    class ConstraintId < AutoCounter
+      value_type 
+    end
+
+    class Denominator < UnsignedInteger
+      value_type :length => 32
+    end
+
+    class Enforcement < String
+      value_type :length => 16
+    end
+
+    class Exponent < SignedSmallInteger
+      value_type :length => 32
+    end
+
+    class FactId < AutoCounter
+      value_type 
+    end
+
+    class FactTypeId < AutoCounter
+      value_type 
+    end
+
+    class Frequency < UnsignedInteger
+      value_type :length => 32
+    end
+
+    class InstanceId < AutoCounter
+      value_type 
+    end
+
+    class Length < UnsignedInteger
+      value_type :length => 32
+    end
+
+    class Name < String
+      value_type :length => 64
+    end
+
+    class Numerator < Decimal
+      value_type 
+    end
+
+    class Ordinal < UnsignedSmallInteger
+      value_type :length => 32
+    end
+
+    class ReadingText < String
+      value_type :length => 256
+    end
+
+    class RingType < String
+      value_type 
+    end
+
+    class RoleSequenceId < AutoCounter
+      value_type 
+    end
+
+    class Scale < UnsignedInteger
+      value_type :length => 32
+    end
+
+    class UnitId < AutoCounter
+      value_type 
+    end
+
+    class Value < String
+      value_type :length => 256
+    end
+
+    class ValueRestrictionId < AutoCounter
+      value_type 
+    end
+
+    class Bound
+      identified_by :value, :is_inclusive
+      maybe :is_inclusive
+      has_one :value                              # See Value.all_bound
+    end
+
+    class Coefficient
+      identified_by :numerator, :denominator
+      has_one :denominator                        # See Denominator.all_coefficient
+      maybe :is_precise
+      has_one :numerator                          # See Numerator.all_coefficient
+    end
+
+    class Constraint
+      identified_by :constraint_id
+      one_to_one :constraint_id                   # See ConstraintId.constraint
+      has_one :enforcement                        # See Enforcement.all_constraint
+      has_one :name                               # See Name.all_constraint
+      has_one :vocabulary                         # See Vocabulary.all_constraint
+    end
+
+    class Fact
+      identified_by :fact_id
+      one_to_one :fact_id                         # See FactId.fact
+      has_one :fact_type                          # See FactType.all_fact
+      has_one :population                         # See Population.all_fact
+    end
+
+    class FactType
+      identified_by :fact_type_id
+      one_to_one :fact_type_id                    # See FactTypeId.fact_type
+    end
+
+    class Instance
+      identified_by :instance_id
+      has_one :concept                            # See Concept.all_instance
+      one_to_one :instance_id                     # See InstanceId.instance
+      has_one :population                         # See Population.all_instance
+      has_one :value                              # See Value.all_instance
+    end
+
+    class PresenceConstraint < Constraint
+      maybe :is_mandatory
+      maybe :is_preferred_identifier
+      has_one :max_frequency, Frequency           # See Frequency.all_presence_constraint_by_max_frequency
+      has_one :min_frequency, Frequency           # See Frequency.all_presence_constraint_by_min_frequency
+      has_one :role_sequence                      # See RoleSequence.all_presence_constraint
+    end
+
+    class Reading
+      identified_by :fact_type, :ordinal
+      has_one :fact_type                          # See FactType.all_reading
+      has_one :ordinal                            # See Ordinal.all_reading
+      has_one :reading_text                       # See ReadingText.all_reading
+      has_one :role_sequence                      # See RoleSequence.all_reading
+    end
+
+    class RingConstraint < Constraint
+      has_one :other_role, "Role"                 # See Role.all_ring_constraint_by_other_role
+      has_one :ring_type                          # See RingType.all_ring_constraint
+      has_one :role                               # See Role.all_ring_constraint
+    end
+
+    class RoleSequence
+      identified_by :role_sequence_id
+      one_to_one :role_sequence_id                # See RoleSequenceId.role_sequence
+    end
+
+    class RoleValue
+      identified_by :instance, :fact
+      has_one :fact                               # See Fact.all_role_value
+      has_one :instance                           # See Instance.all_role_value
+      has_one :population                         # See Population.all_role_value
+      has_one :role                               # See Role.all_role_value
+    end
+
+    class SetConstraint < Constraint
+    end
+
+    class SubsetConstraint < SetConstraint
+      has_one :subset_role_sequence, RoleSequence  # See RoleSequence.all_subset_constraint_by_subset_role_sequence
+      has_one :superset_role_sequence, RoleSequence  # See RoleSequence.all_subset_constraint_by_superset_role_sequence
+    end
+
+    class Unit
+      identified_by :unit_id
+      has_one :coefficient                        # See Coefficient.all_unit
+      maybe :is_fundamental
+      has_one :name                               # See Name.all_unit
+      one_to_one :unit_id                         # See UnitId.unit
+    end
+
+    class UnitBasis
+      identified_by :base_unit, :derived_unit
+      has_one :base_unit, Unit                    # See Unit.all_unit_basis_by_base_unit
+      has_one :derived_unit, Unit                 # See Unit.all_unit_basis_by_derived_unit
+      has_one :exponent                           # See Exponent.all_unit_basis
+    end
+
+    class ValueRange
+      identified_by :minimum_bound, :maximum_bound
+      has_one :maximum_bound, Bound               # See Bound.all_value_range_by_maximum_bound
+      has_one :minimum_bound, Bound               # See Bound.all_value_range_by_minimum_bound
+    end
+
+    class ValueRestriction
+      identified_by :value_restriction_id
+      one_to_one :value_restriction_id            # See ValueRestrictionId.value_restriction
+    end
+
+    class AllowedRange
+      identified_by :value_range, :value_restriction
+      has_one :value_range                        # See ValueRange.all_allowed_range
+      has_one :value_restriction                  # See ValueRestriction.all_allowed_range
+    end
+
+    class Vocabulary
+      identified_by :name
+      one_to_one :name                            # See Name.vocabulary
+    end
+
+    class Import
+      identified_by :imported_vocabulary, :vocabulary
+      has_one :imported_vocabulary, Vocabulary    # See Vocabulary.all_import_by_imported_vocabulary
+      has_one :vocabulary                         # See Vocabulary.all_import
+    end
+
+    class Feature
+      identified_by :name, :vocabulary
+      has_one :name                               # See Name.all_feature
+      has_one :vocabulary                         # See Vocabulary.all_feature
+    end
+
+    class Correspondence
+      identified_by :imported_feature, :import
+      has_one :import                             # See Import.all_correspondence
+      has_one :imported_feature, Feature          # See Feature.all_correspondence_by_imported_feature
+      has_one :local_feature, Feature             # See Feature.all_correspondence_by_local_feature
+    end
+
+    class Population
+      identified_by :vocabulary, :name
+      has_one :name                               # See Name.all_population
+      has_one :vocabulary                         # See Vocabulary.all_population
+    end
+
+    class SetComparisonConstraint < SetConstraint
+    end
+
+    class SetComparisonRoles
+      identified_by :set_comparison_constraint, :role_sequence
+      has_one :role_sequence                      # See RoleSequence.all_set_comparison_roles
+      has_one :set_comparison_constraint          # See SetComparisonConstraint.all_set_comparison_roles
+    end
+
+    class SetEqualityConstraint < SetComparisonConstraint
+    end
+
+    class SetExclusionConstraint < SetComparisonConstraint
+      maybe :is_mandatory
+    end
+
+    class Alias < Feature
+    end
+
+    class Concept < Feature
+      maybe :is_independent
+      maybe :is_personal
+    end
+
+    class Role
+      identified_by :fact_type, :ordinal, :concept
+      has_one :concept                            # See Concept.all_role
+      has_one :fact_type                          # See FactType.all_role
+      has_one :ordinal                            # See Ordinal.all_role
+      has_one :role_name, Name                    # See Name.all_role_by_role_name
+      has_one :role_value_restriction, ValueRestriction  # See ValueRestriction.all_role_by_role_value_restriction
+    end
+
+    class RoleRef
+      identified_by :role_sequence, :ordinal
+      has_one :ordinal                            # See Ordinal.all_role_ref
+      has_one :role                               # See Role.all_role_ref
+      has_one :role_sequence                      # See RoleSequence.all_role_ref
+      has_one :leading_adjective, Adjective       # See Adjective.all_role_ref_by_leading_adjective
+      has_one :trailing_adjective, Adjective      # See Adjective.all_role_ref_by_trailing_adjective
+    end
+
+    class JoinPath
+      identified_by :role_ref, :join_step
+      has_one :join_step, Ordinal                 # See Ordinal.all_join_path_by_join_step
+      has_one :role_ref                           # See RoleRef.all_join_path
+      has_one :concept                            # See Concept.all_join_path
+      has_one :input_role, Role                   # See Role.all_join_path_by_input_role
+      has_one :output_role, Role                  # See Role.all_join_path_by_output_role
+    end
+
+    class EntityType < Concept
+      one_to_one :fact_type                       # See FactType.entity_type
+    end
+
+    class TypeInheritance < FactType
+      identified_by :subtype, :supertype
+      has_one :subtype, EntityType                # See EntityType.all_type_inheritance_by_subtype
+      has_one :supertype, EntityType              # See EntityType.all_type_inheritance_by_supertype
+      maybe :provides_identification
+    end
+
+    class ValueType < Concept
+      has_one :length                             # See Length.all_value_type
+      has_one :scale                              # See Scale.all_value_type
+      has_one :supertype, ValueType               # See ValueType.all_value_type_by_supertype
+      has_one :unit                               # See Unit.all_value_type
+      has_one :value_restriction                  # See ValueRestriction.all_value_type
+    end
+
+  end
+end