activefacts 0.8.16 → 0.8.18

data/lib/activefacts/support.rb

@@ -6,7 +6,7 @@
 # Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 #
 #module ActiveFacts
-  $debug_indent = nil
+  $debug_indent = 0
   $debug_nested = false   # Set when a block enables all enclosed debugging
   $debug_keys = nil
   $debug_available = {}
@@ -14,13 +14,15 @@
   def debug_initialize
     # First time, initialise the tracing environment
     $debug_indent = 0
-    $debug_keys = {}
-    if (e = ENV["DEBUG"])
-      e.split(/[^_a-zA-Z0-9]/).each{|k| debug_enable(k) }
-      if $debug_keys[:help]
-        at_exit {
-          $stderr.puts "---\nDebugging keys available: #{$debug_available.keys.map{|s| s.to_s}.sort*", "}"
-        }
+    unless $debug_keys
+      $debug_keys = {}
+      if (e = ENV["DEBUG"])
+	e.split(/[^_a-zA-Z0-9]/).each{|k| debug_enable(k) }
+	if $debug_keys[:help]
+	  at_exit {
+	    $stderr.puts "---\nDebugging keys available: #{$debug_available.keys.map{|s| s.to_s}.sort*", "}"
+	  }
+	end
       end
     end
   end
@@ -72,7 +74,9 @@
   end
 
   def debug_show(*args)
-    debug_initialize unless $debug_indent
+    unless $debug_keys
+      debug_initialize
+    end
 
     enabled, key_to_show = debug_selected(args)
 
@@ -152,7 +156,7 @@ class Array
 end
 
 # Load the ruby debugger before everything else, if requested
-if debug :debug
+if debug :debug or debug :firstaid
   begin
     require 'ruby-debug'
     Debugger.start # (:post_mortem => true)  # Some Ruby versions crash on post-mortem debugging
@@ -167,4 +171,18 @@ if debug :debug
       true
     end
   end
+
+  if debug :firstaid
+    puts "Preparing first aid kit"
+    class ::Exception
+      alias_method :firstaid_initialize, :initialize
+
+      def initialize *args, &b
+	send(:firstaid_initialize, *args, &b)
+	puts "Stopped due to #{self.class}: #{message} at "+caller*"\n\t"
+	debugger
+	true # Exception thrown
+      end
+    end
+  end
 end

data/lib/activefacts/version.rb

@@ -8,7 +8,7 @@ module ActiveFacts
   module Version
     MAJOR = 0
     MINOR = 8
-    PATCH = 16
+    PATCH = 18
 
     STRING = [MAJOR, MINOR, PATCH].compact.join('.')
   end

data/lib/activefacts/vocabulary/extensions.rb

@@ -6,15 +6,76 @@
 #
 module ActiveFacts
   module Metamodel
+    class Vocabulary
+      def finalise
+        constellation.FactType.values.each do |fact_type|
+          if c = fact_type.check_and_add_spanning_uniqueness_constraint
+            debug :constraint, "Checking for existence of at least one uniqueness constraint over the roles of #{fact_type.default_reading.inspect}"
+            fact_type.check_and_add_spanning_uniqueness_constraint = nil
+            c.call
+          end
+        end
+      end
+
+      # This name does not yet exist (at least not as we expect it to).
+      # If it in fact does exist (but as the wrong type), complain.
+      # If it doesn't exist, but its name would cause existing fact type
+      # readings to be re-interpreted to a different meaning, complain.
+      # Otherwise return nil.
+      def check_valid_nonexistent_object_type_name name
+        if ot = valid_object_type_name(name)
+          raise "Cannot redefine #{ot.class.basename} #{name}"
+        end
+      end
+
+      def valid_object_type_name name
+        # Raise an exception if adding this name to the vocabulary would create anomalies
+        anomaly = constellation.Reading.detect do |r_key, reading|
+            expanded = reading.expand do |role_ref, *words|
+                words.map! do |w|
+                  case
+                  when w == nil
+                    w
+                  when w[0...name.size] == name
+                    '_ok_'+w
+                  when w[-name.size..-1] == name
+                    w[-1]+'_ok_'
+                  else
+                    w
+                  end
+                end
+
+                words
+              end
+            expanded =~ %r{\b#{name}\b}
+          end
+        raise "Adding new term '#{name}' would create anomalous re-interpretation of '#{anomaly.expand}'" if anomaly
+        @constellation.ObjectType[[identifying_role_values, name]]
+      end
+
+      # If this entity type exists, ok, otherwise check it's ok to add it
+      def valid_entity_type_name name
+        @constellation.EntityType[[identifying_role_values, name]] or
+          check_valid_nonexistent_object_type_name name
+      end
+
+      # If this entity type exists, ok, otherwise check it's ok to add it
+      def valid_value_type_name name
+        @constellation.ValueType[[identifying_role_values, name]] or
+          check_valid_nonexistent_object_type_name name
+      end
+    end
 
     class FactType
+      attr_accessor :check_and_add_spanning_uniqueness_constraint
+
       def all_reading_by_ordinal
         all_reading.sort_by{|reading| reading.ordinal}
       end
 
-      def preferred_reading
-        pr = all_reading_by_ordinal[0]
-        raise "No reading for (#{all_role.map{|r| r.object_type.name}*", "})" unless pr
+      def preferred_reading negated = false
+        pr = all_reading_by_ordinal.detect{|r| !r.is_negative == !negated }
+        raise "No reading for (#{all_role.map{|r| r.object_type.name}*", "})" unless pr || negated
         pr
       end
 
@@ -37,21 +98,28 @@ module ActiveFacts
         end.flatten.compact.uniq
       end
 
+      def implicit_boolean_type vocabulary
+        @constellation.ImplicitBooleanValueType[[vocabulary.identifying_role_values, "_ImplicitBooleanValueType"]] ||
+        @constellation.ImplicitBooleanValueType(vocabulary.identifying_role_values, "_ImplicitBooleanValueType", :guid => :new)
+      end
+
       # This entity type has just objectified a fact type. Create the necessary ImplicitFactTypes with phantom roles
       def create_implicit_fact_type_for_unary
         role = all_role.single
-        return if role.implicit_fact_type     # Already exists
+        return if role.link_fact_type     # Already exists
         # NORMA doesn't create an implicit fact type here, rather the fact type has an implicit extra role, so looks like a binary
         # We only do it when the unary fact type is not objectified
-        implicit_fact_type = @constellation.ImplicitFactType(:new, :implying_role => role)
-        entity_type = @entity_type || @constellation.ImplicitBooleanValueType(role.object_type.vocabulary, "_ImplicitBooleanValueType", :guid => :new)
-        phantom_role = @constellation.Role(implicit_fact_type, 0, :object_type => entity_type, :guid => :new)
+        link_fact_type = @constellation.LinkFactType(:new, :implying_role => role)
+        entity_type = @entity_type || implicit_boolean_type(role.object_type.vocabulary)
+        phantom_role = @constellation.Role(link_fact_type, 0, :object_type => entity_type, :guid => :new)
       end
 
-      def reading_preferably_starting_with_role role
+      def reading_preferably_starting_with_role role, negated = false
         all_reading_by_ordinal.detect do |reading|
-          reading.text =~ /\{\d\}/ and reading.role_sequence.all_role_ref_in_order[$1.to_i].role == role
-        end || preferred_reading
+          reading.text =~ /\{\d\}/ and
+            reading.role_sequence.all_role_ref_in_order[$1.to_i].role == role and
+            reading.is_negative == !!negated
+        end || preferred_reading(negated)
       end
 
       def all_role_in_order
@@ -76,6 +144,7 @@ module ActiveFacts
       end
 
       def is_mandatory
+        link_fact_type ||
         all_role_ref.detect{|rr|
           rs = rr.role_sequence
           rs.all_role_ref.size == 1 and
@@ -85,7 +154,6 @@ module ActiveFacts
         } ? true : false
       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
@@ -103,19 +171,6 @@ module ActiveFacts
           end
       end
 
-      def role_method
-        if fact_type.all_role.size == 1
-          # The object of an objectified unary has no boolean; the existence of the object is the fact
-          return nil if fact_type.entity_type
-          return preferred_role_name(role)
-        end
-        if fact_type.is_a?(ActiveFacts::Metamodel::TypeInheritance)
-          # No method is available to indicate that the object is the specified subtype
-          # In future, this might be implemented using the type discriminator
-          return nil
-        end
-      end
-
     end
 
     class RoleRef
@@ -123,14 +178,14 @@ module ActiveFacts
         role_name
       end
 
-      def preferred_role_ref
-        role.fact_type.preferred_reading.role_sequence.all_role_ref.detect{|rr| rr.role == role}
+      def preferred_reference
+        role.preferred_reference
       end
 
-      def role_name(joiner = "-")
+      def role_name(separator = "-")
         name_array =
           if role.fact_type.all_role.size == 1
-            if role.fact_type.is_a?(ImplicitFactType)
+            if role.fact_type.is_a?(LinkFactType)
               "#{role.object_type.name} phantom for #{role.fact_type.role.object_type.name}"
             else
               role.fact_type.preferred_reading.text.gsub(/\{[0-9]\}/,'').strip.split(/\s/)
@@ -138,7 +193,7 @@ module ActiveFacts
           else
             role.role_name || [leading_adjective, role.object_type.name, trailing_adjective].compact.map{|w| w.split(/\s/)}.flatten
           end
-        return joiner ? Array(name_array)*joiner : Array(name_array)
+        return separator ? Array(name_array)*separator : Array(name_array)
       end
 
       def cql_name
@@ -167,6 +222,11 @@ module ActiveFacts
       end
     end
 
+    class ObjectType
+      # Placeholder for the surrogate transform
+      attr_reader :injected_surrogate_role
+    end
+
     class ValueType
       def supertypes_transitive
         [self] + (supertype ? supertype.supertypes_transitive : [])
@@ -182,9 +242,27 @@ module ActiveFacts
     end
 
     class EntityType
+      def identification_is_inherited
+        preferred_identifier and
+          preferred_identifier.role_sequence.all_role_ref.detect{|rr| rr.role.fact_type.is_a?(ActiveFacts::Metamodel::TypeInheritance) }
+      end
+
+      def assimilation
+        if rr = identification_is_inherited
+          rr.role.fact_type.assimilation
+        else
+          nil
+        end
+      end
+
       def preferred_identifier
         return @preferred_identifier if @preferred_identifier
         if fact_type
+          # When compiling a fact instance, the delayed creation of a preferred identifier might be necessary
+          if c = fact_type.check_and_add_spanning_uniqueness_constraint
+            fact_type.check_and_add_spanning_uniqueness_constraint = nil
+            c.call
+          end
 
           # For a nested fact type, the PI is a unique constraint over N or N-1 roles
           fact_roles = Array(fact_type.all_role)
@@ -369,12 +447,13 @@ module ActiveFacts
 
       # This entity type has just objectified a fact type. Create the necessary ImplicitFactTypes with phantom roles
       def create_implicit_fact_types
-        fact_type.all_role.each do |role|
-          next if role.implicit_fact_type     # Already exists
-          implicit_fact_type = @constellation.ImplicitFactType(:new, :implying_role => role)
-          phantom_role = @constellation.Role(implicit_fact_type, 0, :object_type => self, :guid => :new)
+        fact_type.all_role.map do |role|
+          next if role.link_fact_type     # Already exists
+          link_fact_type = @constellation.LinkFactType(:new, :implying_role => role)
+          phantom_role = @constellation.Role(link_fact_type, 0, :object_type => self, :guid => :new)
           # We could create a copy of the visible external role here, but there's no need yet...
           # Nor is there a need for a presence constraint, readings, etc.
+	  link_fact_type
         end
       end
     end
@@ -484,9 +563,13 @@ module ActiveFacts
 
     class ValueConstraint
       def describe
-        "restricted to {"+
-          all_allowed_range_sorted.map{|ar| ar.to_s(false) }*", "+
-          "}"
+        "restricted to "+
+	  ( if regular_expression
+	      '/' + regular_expression + '/'
+	    else
+	      '{' + all_allowed_range_sorted.map{|ar| ar.to_s(false) }*', ' + '}'
+	    end
+	  )
       end
 
       def all_allowed_range_sorted
@@ -515,7 +598,7 @@ module ActiveFacts
 
         if min = value_range.minimum_bound
           min = min.value
-          if min.is_a_string
+          if min.is_literal_string
             min_literal = min.literal.inspect.gsub(/\A"|"\Z/,"'")   # Escape string characters
           else
             min_literal = min.literal
@@ -525,7 +608,7 @@ module ActiveFacts
         end
         if max = value_range.maximum_bound
           max = max.value
-          if max.is_a_string
+          if max.is_literal_string
             max_literal = max.literal.inspect.gsub(/\A"|"\Z/,"'")   # Escape string characters
           else
             max_literal = max.literal
@@ -541,8 +624,19 @@ module ActiveFacts
 
     class Value
       def to_s
-        (is_a_string ? literal.inspect.gsub(/\A"|"\Z/,"'") : literal) + (unit ? " " + unit.name : "")
+        if is_literal_string
+          "'"+
+          literal.
+            inspect.            # Use Ruby's inspect to generate necessary escapes
+            gsub(/\A"|"\Z/,''). # Remove surrounding quotes
+            gsub(/'/, "\\'") +  # Escape any single quotes
+          "'"
+        else
+          literal
+        end +
+        (unit ? " " + unit.name : "")
       end
+
       def inspect
         to_s
       end
@@ -580,37 +674,37 @@ module ActiveFacts
       end
     end
 
-    class JoinStep
+    class Step
       def describe
-        "JoinStep " +
-          "#{is_outer && 'maybe '}" +
-          (is_unary_step ? " (unary) " : "from #{input_join_role.describe} ") +
-          "#{is_anti && 'not '}" +
-          "to #{output_join_role.describe} " +
+        "Step " +
+          "#{is_optional ? 'maybe ' : ''}" +
+          (is_unary_step ? '(unary) ' : "from #{input_play.describe} ") +
+          "#{is_disallowed ? 'not ' : ''}" +
+          "to #{output_play.describe} " +
           "over " +
           (is_objectification_step ? 'objectification ' : '') +
           "'#{fact_type.default_reading}'"
       end
 
       def is_unary_step
-        # Preserve this in case we have to use a real join_node for the phantom
-        input_join_role == output_join_role
+        # Preserve this in case we have to use a real variable for the phantom
+        input_play == output_play
       end
 
       def is_objectification_step
-        fact_type.is_a?(ImplicitFactType)
+        fact_type.is_a?(LinkFactType)
       end
 
-      def all_join_role
-        [input_join_role, output_join_role].uniq + all_incidental_join_role.to_a
+      def all_play
+        [input_play, output_play].uniq + all_incidental_play.to_a
       end
 
       def external_fact_type
-        fact_type.is_a?(ImplicitFactType) ? fact_type.role.fact_type : fact_type
+        fact_type.is_a?(LinkFactType) ? fact_type.role.fact_type : fact_type
       end
     end
 
-    class JoinNode
+    class Variable
       def describe
         object_type.name +
           (subscript ? "(#{subscript})" : '') +
@@ -618,79 +712,79 @@ module ActiveFacts
           (value ? ' = '+value.to_s : '')
       end
 
-      def all_join_step
-        all_join_role.map do |jr|
-          jr.all_join_step_as_input_join_role.to_a +
-            jr.all_join_step_as_output_join_role.to_a
+      def all_step
+        all_play.map do |jr|
+          jr.all_step_as_input_play.to_a +
+            jr.all_step_as_output_play.to_a
         end.
           flatten.
           uniq
       end
     end
 
-    class JoinRole
+    class Play
       def describe
-        "#{role.object_type.name} JN#{join_node.ordinal}" +
+        "#{role.object_type.name} JN#{variable.ordinal}" +
           (role_ref ? " (projected)" : "")
       end
 
-      def all_join_step
-        (all_join_step_as_input_join_role.to_a +
-          all_join_step_as_output_join_role.to_a +
-          [join_step]).flatten.compact.uniq
+      def all_step
+        (all_step_as_input_play.to_a +
+          all_step_as_output_play.to_a +
+          [step]).flatten.compact.uniq
       end
     end
 
-    class Join
+    class Query
       def show
         steps_shown = {}
-        debug :join, "Displaying full contents of Join #{guid}" do
-          all_join_node.sort_by{|jn| jn.ordinal}.each do |join_node|
-            debug :join, "#{join_node.describe}" do
-              join_node.all_join_step.
-                each do |join_step|
-                  next if steps_shown[join_step]
-                  steps_shown[join_step] = true
-                  debug :join, "#{join_step.describe}"
+        debug :query, "Displaying full contents of Query #{guid}" do
+          all_variable.sort_by{|jn| jn.ordinal}.each do |variable|
+            debug :query, "#{variable.describe}" do
+              variable.all_step.
+                each do |step|
+                  next if steps_shown[step]
+                  steps_shown[step] = true
+                  debug :query, "#{step.describe}"
                 end
-              join_node.all_join_role.each do |join_role|
-                debug :join, "role of #{join_role.describe} in '#{join_role.role.fact_type.default_reading}'"
+              variable.all_play.each do |play|
+                debug :query, "role of #{play.describe} in '#{play.role.fact_type.default_reading}'"
               end
             end
           end
         end
       end
 
-      def all_join_step
-        all_join_node.map{|jn| jn.all_join_step.to_a}.flatten.uniq
+      def all_step
+        all_variable.map{|jn| jn.all_step.to_a}.flatten.uniq
       end
 
-      # Check all parts of this join for validity
+      # Check all parts of this query for validity
       def validate
         show
         return
 
-        # Check the join nodes:
-        join_steps = []
-        join_nodes = all_join_node.sort_by{|jn| jn.ordinal}
-        join_nodes.each_with_index do |join_node, i|
-          raise "Join node #{i} should have ordinal #{join_node.ordinal}" unless join_node.ordinal == i
-          raise "Join Node #{i} has missing object_type" unless join_node.object_type
-          join_node.all_join_role do |join_role|
-            raise "Join Node for #{object_type.name} includes role played by #{join_role.object_type.name}" unless join_role.object_type == object_type
+        # Check the variables:
+        steps = []
+        variables = all_variable.sort_by{|jn| jn.ordinal}
+        variables.each_with_index do |variable, i|
+          raise "Variable #{i} should have ordinal #{variable.ordinal}" unless variable.ordinal == i
+          raise "Variable #{i} has missing object_type" unless variable.object_type
+          variable.all_play do |play|
+            raise "Variable for #{object_type.name} includes role played by #{play.object_type.name}" unless play.object_type == object_type
           end
-          join_steps += join_node.all_join_step
+          steps += variable.all_step
         end
-        join_steps.uniq!
-
-        # Check the join steps:
-        join_steps.each do |join_step|
-          raise "Join Step has missing fact type" unless join_step.fact_type
-          raise "Join Step has missing input node" unless join_step.input_join_role
-          raise "Join Step has missing output node" unless join_step.output_join_role
-          if (role = input_join_role).role.fact_type != fact_type or
-            (role = output_join_role).role.fact_type != fact_type
-            raise "Join Step has role #{role.describe} which doesn't belong to the fact type '#{fact_type.default_reading}' it traverses"
+        steps.uniq!
+
+        # Check the steps:
+        steps.each do |step|
+          raise "Step has missing fact type" unless step.fact_type
+          raise "Step has missing input node" unless step.input_play
+          raise "Step has missing output node" unless step.output_play
+          if (role = input_play).role.fact_type != fact_type or
+            (role = output_play).role.fact_type != fact_type
+            raise "Step has role #{role.describe} which doesn't belong to the fact type '#{fact_type.default_reading}' it traverses"
           end
         end
 
@@ -698,10 +792,10 @@ module ActiveFacts
       end
     end
 
-    class ImplicitFactType
+    class LinkFactType
       def default_reading
         # There are two cases, where role is in a unary fact type, and where the fact type is objectified
-        # If a unary fact type is objectified, only the ImplicitFactType for the objectification is asserted
+        # If a unary fact type is objectified, only the LinkFactType for the objectification is asserted
         if objectification = implying_role.fact_type.entity_type
           "#{objectification.name} involves #{implying_role.object_type.name}"
         else
@@ -709,6 +803,20 @@ module ActiveFacts
         end
       end
 
+      def add_reading implicit_reading
+	@readings ||= []
+	@readings << implicit_reading
+      end
+
+      def all_reading
+        @readings ||=
+	  [ ImplicitReading.new(
+	      self,
+	      implying_role.fact_type.entity_type ? "{0} involves {1}" : implying_role.fact_type.default_reading+" Boolean"
+	    )
+	  ]
+      end
+
       # This is only used for debugging, from RoleRef#describe
       class ImplicitReading
         attr_accessor :fact_type, :text
@@ -726,8 +834,8 @@ module ActiveFacts
               @role = role
               @role_sequence = role_sequence
             end
-            def join_node; nil; end
-            def join_role; nil; end
+            def variable; nil; end
+            def play; nil; end
             def leading_adjective; nil; end
             def trailing_adjective; nil; end
             def describe
@@ -760,19 +868,12 @@ module ActiveFacts
           @fact_type.default_reading
         end
       end
-
-      def all_reading
-        [@reading ||= ImplicitReading.new(
-          self,
-          implying_role.fact_type.entity_type ? "{0} involves {1}" : implying_role.fact_type.default_reading+" Boolean"
-        )]
-      end
     end
 
-    # Some joins must be over the proximate roles, some over the counterpart roles.
+    # Some queries must be over the proximate roles, some over the counterpart roles.
     # Return the common superclass of the appropriate roles, and the actual roles
-    def self.join_roles_over roles, options = :both   # Or :proximate, :counterpart
-      # If we can stay inside this objectified FT, there's no join:
+    def self.plays_over roles, options = :both   # Or :proximate, :counterpart
+      # If we can stay inside this objectified FT, there's no query:
       roles = Array(roles)  # To be safe, in case we get a role collection proxy
       return nil if roles.size == 1 or
         options != :counterpart && roles.map{|role| role.fact_type}.uniq.size == 1
@@ -788,11 +889,11 @@ module ActiveFacts
           counterpart_role_supertypes =
             if fact_type.all_role.size > 2
               possible_roles = fact_type.all_role.select{|r| d_c_o && d_c_o[1].include?(r.object_type) }
-              if possible_roles.size == 1 # Only one candidate matches the types of the possible join nodes
+              if possible_roles.size == 1 # Only one candidate matches the types of the possible variables
                 counterpart_role = possible_roles[0]
                 d_c_o[1]  # No change
               else
-                # puts "#{constraint_type} #{name}: Awkward, try counterpart-role join on a >2ary '#{fact_type.default_reading}'"
+                # puts "#{constraint_type} #{name}: Awkward, try counterpart-role query on a >2ary '#{fact_type.default_reading}'"
                 # Try all roles; hopefully we don't have two roles with a matching candidate here:
                 # Find which role is compatible with the existing supertypes, if any
                 if d_c_o
@@ -815,7 +916,7 @@ module ActiveFacts
           if fact_type.entity_type
             objectification_role_supertypes =
               fact_type.entity_type.supertypes_transitive+object_type.supertypes_transitive
-            objectification_role = role.implicit_fact_type.all_role.single # Find the phantom role here
+            objectification_role = role.link_fact_type.all_role.single # Find the phantom role here
           else
             objectification_role_supertypes = counterpart_role_supertypes
             objectification_role = counterpart_role
@@ -835,12 +936,12 @@ module ActiveFacts
           d_c_o
         end # inject
 
-      # Discount a subtype join over an object type that's not a player here,
-      # if we can use an objectification join to an object type that is:
+      # Discount a subtype step over an object type that's not a player here,
+      # if we can use an objectification step to an object type that is:
       if counterpart_sups.size > 0 && obj_sups.size > 0 && counterpart_sups[0] != obj_sups[0]
-        debug :join, "ambiguous join, could be over #{counterpart_sups[0].name} or #{obj_sups[0].name}"
+        debug :query, "ambiguous query, could be over #{counterpart_sups[0].name} or #{obj_sups[0].name}"
         if !roles.detect{|r| r.object_type == counterpart_sups[0]} and roles.detect{|r| r.object_type == obj_sups[0]}
-          debug :join, "discounting #{counterpart_sups[0].name} in favour of direct objectification"
+          debug :query, "discounting #{counterpart_sups[0].name} in favour of direct objectification"
           counterpart_sups = []
         end
       end
@@ -898,7 +999,7 @@ module ActiveFacts
               "its #{identifying_instance.verbalise(context)}"
           else
             identifying_role_refs.map do |rr|
-              rr = rr.preferred_role_ref
+              rr = rr.preferred_reference
               [ (l = rr.leading_adjective) ? l+"-" : nil,
                 rr.role.role_name || rr.role.object_type.name,
                 (t = rr.trailing_adjective) ? l+"-" : nil
@@ -917,5 +1018,33 @@ module ActiveFacts
       end
     end
 
+    class ContextNote
+      def verbalise(context=nil)
+	' (' +
+	( if all_context_according_to
+	    'according to '
+	    all_context_according_to.map do |act|
+	      act.agent.agent_name+', '
+	    end.join('')
+	  end
+	) +
+	context_note_kind.gsub(/_/, ' ') +
+	' ' +
+	discussion +
+	( if agreement
+	    ', as agreed ' +
+	    (agreement.date ? ' on '+agreement.date+' ' : '') +
+	    'by '
+	    agreement.all_context_agreed_by.map do |acab|
+	      acab.agent.agent_name+', '
+	    end.join('')
+	  else
+	    ''
+	  end
+	) +
+	')'
+      end
+    end
+
   end
 end