activefacts 0.7.0 → 0.7.1

data/README.rdoc

@@ -26,9 +26,6 @@ SQL is.
 
  * Queries are parsed, but not yet generated to SQL. DDL is complete.
 
- * SQL generation handles some one-to-one relationships wrongly,
-   including subtypes when independent of the supertype's table.
-
  * The Constellation API lacks SQL persistence (but is already useful;
    the CQL compiler uses the generated Ruby code extensively)
 

data/Rakefile

@@ -16,11 +16,13 @@ $hoe = Hoe.new('activefacts', ActiveFacts::VERSION) do |p|
     ['newgem', ">= #{::Newgem::VERSION}"]
   ]
   p.spec_extras[:extensions] = 'lib/activefacts/cql/Rakefile'
-  p.spec_extras[:rdoc_options] = [
-      "-x", "lib/activefacts/cql/.*.rb",
-      "-x", "lib/activefacts/vocabulary/.*.rb",
-      "-x", "lib/activefacts/persistence/.*.rb",
-    ]
+  # Magic Hoe hook to prevent the generation of diagrams:
+  ENV['NODOT'] = 'yes'
+  p.spec_extras[:rdoc_options] = %w{
+      -A has_one -A one_to_one -A maybe
+      -x lib/activefacts/cql/.*.rb
+      -x lib/activefacts/vocabulary/.*.rb
+    }
   p.clean_globs |= %w[**/.DS_Store tmp *.log]
   path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
   p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')

data/bin/afgen

@@ -1,8 +1,8 @@
 #! env ruby
 #
-# Read an ORM2 Vocabulary from a NORMA, CQL or other file
+#	ActiveFacts: Read a Vocabulary (from a NORMA, CQL or other file) and run a generator
 #
-# Copyright (c) 2007 Clifford Heath. Read the LICENSE file.
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 #
 $:.unshift File.dirname(File.expand_path(__FILE__))+"/../lib"
 
@@ -11,6 +11,9 @@ require 'ruby-debug'
 require 'activefacts'
 require 'activefacts/vocabulary'
 
+debugger if debug :exception
+true # Ok, got the stack set up, continue to the fault
+
 arg = ARGV.shift
 
 # Load the required generator, or the default "text" generator:

data/bin/cql

@@ -1,7 +1,8 @@
 #! env ruby
 #
-# Interactive CQL command-line.
-# Copyright (c) 2007 Clifford Heath. Read the LICENSE file.
+#	ActiveFacts: Interactive CQL command-line. Incomplete; only parses CQL and shows the parse trees
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 #
 
 require 'activefacts'

data/examples/CQL/Genealogy.cql

@@ -9,10 +9,10 @@ Day is defined as UnsignedInteger(32) restricted to {1..31};
 Email is defined as VariableLengthText(64);
 EventID is defined as AutoCounter();
 EventLocation is defined as VariableLengthText(128);
-EventRoleName is defined as VariableLengthText() restricted to {'Subject', 'Father', 'Mother', 'Husband', 'Wife', 'Celebrant'};
+EventRoleName is defined as VariableLengthText() restricted to {'Celebrant', 'Father', 'Husband', 'Mother', 'Subject', 'Wife'};
 EventTypeID is defined as AutoCounter();
-EventTypeName is defined as VariableLengthText(16) restricted to {'Birth', 'Christening', 'Marriage', 'Divorce', 'Death', 'Burial'};
-Gender is defined as FixedLengthText(1) restricted to {'M', 'F'};
+EventTypeName is defined as VariableLengthText(16) restricted to {'Birth', 'Burial', 'Christening', 'Death', 'Divorce', 'Marriage'};
+Gender is defined as FixedLengthText(1) restricted to {'F', 'M'};
 Month is defined as UnsignedInteger(32) restricted to {1..12};
 Name is defined as VariableLengthText(128);
 Occupation is defined as VariableLengthText(128);

data/examples/CQL/Metamodel.cql

@@ -108,10 +108,10 @@ Vocabulary contains Constraint,
 Import is where
 	Vocabulary imports imported-Vocabulary [acyclic];
 
-Feature is identified by Name and Vocabulary where
-	Feature is called one Name,
+Feature is identified by Vocabulary and Name where
 	Feature belongs to at most one Vocabulary,
-	Vocabulary contains Feature;
+	Vocabulary contains Feature,
+	Feature is called one Name;
 Correspondence is where
 	in Import imported-Feature corresponds to at most one local-Feature;
 
@@ -129,7 +129,10 @@ Population includes RoleValue,
 
 SetComparisonConstraint is a kind of SetConstraint;
 SetComparisonRoles is where
-	SetComparisonConstraint covers at least one RoleSequence;
+	SetComparisonConstraint has in Ordinal position at most one RoleSequence,
+	RoleSequence is Ordinal in SetComparisonConstraint,
+	in Ordinal position SetComparisonConstraint has RoleSequence,
+	SetComparisonConstraint has RoleSequence in at most one Ordinal position;
 
 SetEqualityConstraint is a kind of SetComparisonConstraint;
 
@@ -224,9 +227,6 @@ each combination EntityType, TypeInheritance occurs at most one time in
 	TypeInheritance provides identification;
 each FactType occurs at least one time in
 	FactType has Ordinal role played by Concept;
-each combination Name, Vocabulary occurs at most one time in
-	Name is of Constraint,
-	Vocabulary contains Constraint;
 each PresenceConstraint occurs at least one time in
 	PresenceConstraint has min-Frequency,
 	PresenceConstraint has max-Frequency,
@@ -236,3 +236,6 @@ each RoleSequence occurs at least one time in
 each ValueRange occurs at least one time in
 	ValueRange has minimum-Bound,
 	ValueRange has maximum-Bound;
+each combination Vocabulary, Name occurs at most one time in
+	Vocabulary contains Constraint,
+	Name is of Constraint;

data/examples/CQL/MultiInheritance.cql

@@ -13,7 +13,8 @@ TFN is defined as FixedLengthText(9);
 Person is identified by its Name;
 
 Australian is a kind of Person;
-Australian has at most one TFN;
+Australian has at most one TFN,
+	TFN is of one Australian;
 
 Employee is a kind of Person identified by its ID;
 

data/examples/CQL/OilSupply.cql

@@ -9,7 +9,7 @@ ProductName is defined as VariableLengthText();
 Quantity is defined as UnsignedInteger(32);
 RefineryName is defined as VariableLengthText(80);
 RegionName is defined as VariableLengthText();
-Season is defined as VariableLengthText(6) restricted to {'Spring', 'Summer', 'Autumn', 'Winter'};
+Season is defined as VariableLengthText(6) restricted to {'Autumn', 'Spring', 'Summer', 'Winter'};
 TransportMethod is defined as VariableLengthText() restricted to {'Rail', 'Road', 'Sea'};
 YearNr is defined as SignedInteger(32);
 
@@ -34,9 +34,9 @@ TransportRoute incurs at most one Cost per kl;
 
 Year is identified by its Nr;
 
-SupplyPeriod is identified by Month and Year where
-	SupplyPeriod is in one Month,
-	SupplyPeriod is in one Year;
+SupplyPeriod is identified by Year and Month where
+	SupplyPeriod is in one Year,
+	SupplyPeriod is in one Month;
 ProductionForecast is where
 	Refinery forecasts production of Product in SupplyPeriod;
 RegionalDemand is where

data/examples/CQL/Orienteering.cql

@@ -12,7 +12,7 @@ EntryID is defined as AutoCounter();
 EventID is defined as AutoCounter();
 EventName is defined as VariableLengthText(50);
 FamilyName is defined as VariableLengthText(48);
-Gender is defined as FixedLengthText(1) restricted to {'M', 'F'};
+Gender is defined as FixedLengthText(1) restricted to {'F', 'M'};
 GivenName is defined as VariableLengthText(48);
 Location is defined as VariableLengthText(200);
 MapID is defined as AutoCounter();
@@ -24,7 +24,7 @@ PointValue is defined as UnsignedInteger(32);
 PostCode is defined as UnsignedInteger(32);
 PunchID is defined as AutoCounter();
 Score is defined as SignedInteger(32);
-ScoringMethod is defined as VariableLengthText(32) restricted to {'Score', 'Scatter', 'Special'};
+ScoringMethod is defined as VariableLengthText(32) restricted to {'Scatter', 'Score', 'Special'};
 SeriesID is defined as AutoCounter();
 SeriesName is defined as VariableLengthText(40);
 StartTime is defined as DateAndTime();

data/lib/activefacts.rb

@@ -1,7 +1,8 @@
 #
 # ActiveFacts Swiss-army knife.
+# Include all that's required for a non-persistent runtime application.
 #
-# Copyright (c) 2007 Clifford Heath. Read the LICENSE file.
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 # Author: Clifford Heath.
 #
 require 'rubygems'

data/lib/activefacts/api.rb

@@ -1,6 +1,7 @@
 #
-# ActiveFacts runtime API.
-# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#       ActiveFacts Runtime API.
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 #
 # The ActiveFacts API is heavily metaprogrammed, so difficult to document.
 #
@@ -13,12 +14,30 @@
 # contains the methods of the class Concept.
 #
 # A module becomes a Vocabulary when the first Concept class is defined within it.
+# A Constellation is a unique collection of Concept 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 Concepts 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
+# concept 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 Concept may only be played by another Instance
+# of the counterpart Concept. 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/concept'               # A Ruby class may become a Concept in a Vocabulary
 require 'activefacts/api/role'                  # A Concept 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 Concept 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

data/lib/activefacts/api/concept.rb

@@ -1,7 +1,10 @@
 #
-# The ActiveFacts Runtime API Concept class
-# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#       ActiveFacts Runtime API
+#       Concept (a mixin module for the class Class)
 #
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
+
 module ActiveFacts
   module API
     module Vocabulary; end
@@ -34,7 +37,7 @@ module ActiveFacts
           end
           raise "Role #{basename}.#{name} is not defined" unless role
           # Bind the role if possible, but don't require it:
-          role.resolve_player(vocabulary) rescue nil unless Class === role.player
+          role.resolve_counterpart(vocabulary) rescue nil unless role.counterpart_concept.is_a?(Class)
           role
         else
           nil
@@ -45,7 +48,7 @@ module ActiveFacts
       #
       # Example: maybe :is_ceo
       def maybe(role_name)
-        realise_role(roles[role_name] = Role.new(TrueClass, nil, role_name))
+        realise_role(roles[role_name] = Role.new(self, TrueClass, nil, role_name))
       end
 
       # Define a binary fact type relating this concept to another,
@@ -55,7 +58,7 @@ module ActiveFacts
       # * role_name - a Symbol for the name of the role (this end of the relationship).
       # * other_player - A class name, Symbol or String naming a class, required if it doesn't match the role_name. Use a symbol or string if the class isn't defined yet, and the methods will be created later, when the class is first defined.
       # * :mandatory - if this role may not be NULL in a valid fact population. Mandatory constraints are only enforced during validation (e.g. before saving).
-      # * :other_role_name - use if the role at the other end should have a name other than the default :all_<concept> or :all_<concept>_by_<role_name>
+      # * :other_role_name - use if the role at the other end should have a name other than the default :all_<concept> or :all_<concept>\_as_<role_name>
       def has_one(*args)
         role_name, related, mandatory, related_role_name = extract_binary_params(false, args)
         define_binary_fact_type(false, role_name, related, mandatory, related_role_name)
@@ -68,7 +71,7 @@ module ActiveFacts
       # * role_name - a Symbol for the name of the role (this end of the relationship)
       # * other_player - A class name, Symbol or String naming a class, required if it doesn't match the role_name. Use a symbol or string if the class isn't defined yet, and the methods will be created later, when the class is first defined
       # * :mandatory - if this role may not be NULL in a valid fact population. Mandatory constraints are only enforced during validation (e.g. before saving)
-      # * :other_role_name - use if the role at the other end should have a name other than the default :<concept> or :<concept>_by_<role_name>
+      # * :other_role_name - use if the role at the other end should have a name other than the default :<concept> or :<concept>_as_<role_name>
       def one_to_one(*args)
         role_name, related, mandatory, related_role_name =
           extract_binary_params(true, args)
@@ -95,7 +98,7 @@ module ActiveFacts
             end
 
             # Realise the roles (create accessors) of this supertype.
-            # REVISIT: The existing accessors at the other end will need to allow this class as role player
+            # REVISIT: The existing accessors at the other end will need to allow this class as role counterpart
             # REVISIT: Need to check all superclass roles recursively, unless we hit a common supertype
             #puts "Realising concept #{concept.name} in #{basename}"
             realise_supertypes(concept, all_supertypes)
@@ -120,7 +123,7 @@ module ActiveFacts
 
       # Every new role added or inherited comes through here:
       def realise_role(role) #:nodoc:
-        #puts "Realising role #{role.player.basename rescue role.player}.#{role.name} in #{basename}"
+        #puts "Realising role #{role.counterpart_concept.basename rescue role.counterpart_concept}.#{role.name} in #{basename}"
 
         if (!role.counterpart)
           # Unary role
@@ -132,7 +135,7 @@ module ActiveFacts
         end
       end
 
-      # REVISIT: Use method_missing to catch all_some_role_by_other_role_and_third_role, to sort_by those roles?
+      # REVISIT: Use method_missing to catch all_some_role_as_other_role_and_third_role, to sort_by those roles?
 
       private
 
@@ -160,15 +163,16 @@ module ActiveFacts
       def define_binary_fact_type(one_to_one, role_name, related, mandatory, related_role_name)
         # puts "#{self}.#{role_name} is to #{related.inspect}, #{mandatory ? :mandatory : :optional}, related role is #{related_role_name}"
 
-        roles[role_name] = role = Role.new(related, nil, role_name, mandatory)
+        raise "#{self.class.basename} cannot have more than one role named #{role_name}" if roles[role_name]
+        roles[role_name] = role = Role.new(self, related, nil, role_name, mandatory)
 
         # There may be a forward reference here where role_name is a Symbol,
         # and the block runs later when that Symbol is bound to the concept.
         when_bound(related, self, role_name, related_role_name) do |target, definer, role_name, related_role_name|
           if (one_to_one)
-            target.roles[related_role_name] = role.counterpart = Role.new(definer, role, related_role_name, false)
+            target.roles[related_role_name] = role.counterpart = Role.new(target, definer, role, related_role_name, false)
           else
-            target.roles[related_role_name] = role.counterpart = Role.new(definer, role, related_role_name, false, false)
+            target.roles[related_role_name] = role.counterpart = Role.new(target, definer, role, related_role_name, false, false)
           end
           #puts "Realising role pair #{definer.basename}.#{role_name} <-> #{target.basename}.#{related_role_name}"
           realise_role(role)
@@ -183,7 +187,7 @@ module ActiveFacts
             #puts "Setting #{self.class.name} #{object_id}.@#{role.name} to #{(value ? true : nil).inspect}"
             instance_variable_set("@#{role.name}", value ? true : nil)
             # REVISIT: Provide a way to find all instances playing/not playing this role
-            # Analogous to true.all_thing_by_role_name...
+            # Analogous to true.all_thing_as_role_name...
           end
         end
         define_single_role_getter(role)
@@ -192,14 +196,16 @@ module ActiveFacts
       def define_single_role_getter(role)
         class_eval do
           define_method role.name do
-            instance_variable_get("@#{role.name}") rescue nil
+            i = instance_variable_get("@#{role.name}") rescue nil
+            i ? RoleProxy.new(role, i) : i
+            i
           end
         end
       end
 
       # REVISIT: Add __add_to(constellation) and __remove(constellation) here?
       def define_single_role_accessor(role, one_to_one)
-        # puts "Defining #{basename}.#{role.name} to #{role.player.basename} (#{one_to_one ? "assigning" : "populating"} #{role.counterpart.name})"
+        # puts "Defining #{basename}.#{role.name} to #{role.counterpart_concept.basename} (#{one_to_one ? "assigning" : "populating"} #{role.counterpart.name})"
         define_single_role_getter(role)
 
         if (one_to_one)
@@ -213,12 +219,11 @@ module ActiveFacts
           define_single_role_setter(role, nullify_reference, assign_reference)
         else
           # This gets called to delete this object from the role value array in the old correspondent
-          delete_reference = lambda{|from, role_name, value| from.send(role_name).__delete(value) }
+          delete_reference = lambda{|from, role_name, value| from.send(role_name).update(value, nil) }
 
           # This gets called to replace an old value by a new one in the related role value array of a new correspondent
           replace_reference = lambda{|from, role_name, old_value, value| 
-              array = from.send(role_name)
-              array.__replace(array - [old_value].compact + [value])
+              from.send(role_name).update(old_value, value)
             }
 
           define_single_role_setter(role, delete_reference, replace_reference)
@@ -230,8 +235,8 @@ module ActiveFacts
           define_method "#{role.name}=" do |value|
             role_var = "@#{role.name}"
 
-            # If role.player isn't bound to a class yet, bind it.
-            role.resolve_player(self.class.vocabulary) unless Class === role.player
+            # If role.counterpart_concept isn't bound to a class yet, bind it.
+            role.resolve_counterpart(self.class.vocabulary) unless role.counterpart_concept.is_a?(Class)
 
             # Get old value, and jump out early if it's unchanged:
             old = instance_variable_get(role_var) rescue nil
@@ -242,7 +247,13 @@ module ActiveFacts
 
             # DEBUG: puts "assign #{self.class.basename}.#{role.name} <-> #{value.inspect}.#{role.counterpart.name}#{old ? " (was #{old.inspect})" : ""}"
 
-            # REVISIT: Defend against changing identifying roles, and decide what to do.
+            # REVISIT: A frozen-key solution could be used to allow changing identifying roles.
+            # The key would be frozen, allowing indices and counterparts to de-assign,
+            # but delay re-assignment until defrosted.
+            # That would also allow caching the identifying_role_values, a performance win.
+
+            # This allows setting and clearing identifying roles, but not changing them.
+            raise "#{self.class.basename}: illegal attempt to modify identifying role #{role.name}" if role.is_identifying && value != nil && old != nil
 
             # puts "Setting binary #{role_var} to #{value.verbalise}"
             instance_variable_set(role_var, value)
@@ -260,7 +271,7 @@ module ActiveFacts
         class_eval do
           define_method "#{role.name}" do
             unless (r = instance_variable_get(role_var = "@#{role.name}") rescue nil)
-              r = instance_variable_set(role_var, RoleValueArray.new)
+              r = instance_variable_set(role_var, RoleValues.new)
             end
             # puts "fetching #{self.class.basename}.#{role.name} array, got #{r.class}, first is #{r[0] ? r[0].verbalise : "nil"}"
             r
@@ -283,13 +294,13 @@ module ActiveFacts
       #   Role Name
       # else:
       #   Leading Adjective
-      #   Role player name (not role name)
+      #   Role counterpart_concept name (not role name)
       #   Trailing Adjective
-      # "_by_<other_role_name>" if other_role_name != this role player's name, and not other_player_this_player
+      # "_as_<other_role_name>" if other_role_name != this role counterpart_concept's name, and not other_player_this_player
       def extract_binary_params(one_to_one, args)
         # Params:
         #   role_name (Symbol)
-        #   other player (Symbol or Class)
+        #   other counterpart_concept (Symbol or Class)
         #   mandatory (:mandatory)
         #   other end role name if any (Symbol),
         role_name = nil
@@ -304,6 +315,7 @@ module ActiveFacts
           role_name = a.to_sym
         when Class
           role_name = a.name.snakecase.to_sym
+          puts "#{a.name.snakecase} -> #{role_name}"
         else
           raise "Illegal first parameter to role: #{a.inspect}"
         end
@@ -336,8 +348,8 @@ module ActiveFacts
           args.shift
         end
 
-        if Symbol == args[0]
-          related_role_name = args.shift
+        if Symbol === args[0]
+          related_role_name = args.shift.to_s
         end
 
         reading = args[0]
@@ -345,25 +357,26 @@ module ActiveFacts
         # Avoid a confusing mismatch:
         # Note that if you have a role "supervisor" and a sub-class "Supervisor", this'll bitch.
         if (Class === related && (indicated = vocabulary.concept(role_name)) && indicated != related)
-          raise "Role name #{role_name} indicates a different player #{indicated} than specified"
+          raise "Role name #{role_name} indicates a different counterpart concept #{indicated} than specified"
         end
 
-        # puts "Calculating related method name for related_role_name=#{related_role_name.inspect}, related_name=#{related_name.inspect}, role_player=#{role_player.inspect}, role_name=#{role_name.inspect}:"
-
-        related_role_name ||= (role_player || "")  # REVISIT: Add adjectives here
-        unless one_to_one
-          related_role_name = "all_#{role_player}" +
-            if related_name == role_name.to_s || role_name.to_s == "#{role_player}_#{related_name}"
-              ""
-            else
-              "_by_#{role_name}"
-            end
+        # This code probably isn't as quick or simple as it could be, but it does work right,
+        # and that was pretty hard, because the variable naming is all over the shop. Should fix
+        # the naming first (here and in generate/oo.rb) then figure out how to speed it up.
+        # Note that oo.rb names things from the opposite end, so you wind up in a maze of mirrors.
+        other_role_method =
+          (one_to_one ? "" : "all_") +
+          (related_role_name || role_player)
+        if role_name.to_s != related_name and
+            (!related_role_name || related_role_name == role_player)
+          other_role_method += "_as_#{role_name}"
         end
+        #puts "On #{basename}: have related_role_name=#{related_role_name.inspect}, role_player=#{role_player}, role_name=#{role_name}, related_name=#{related_name.inspect} -> #{related_name}.#{other_role_method}"
 
         [ role_name,
           related,
           mandatory,
-          related_role_name.to_sym 
+          other_role_method.to_sym 
         ]
       end