activefacts 0.7.0 → 0.7.1

data/lib/activefacts/api/standard_types.rb

@@ -1,8 +1,11 @@
 #
-# The ActiveFacts Runtime API Standard types extensions.
-# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#       ActiveFacts Runtime API
+#       Standard types extensions.
 #
-# These extensions add ActiveFacts Concept and Instance behaviour into base Ruby classes.
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
+# These extensions add ActiveFacts Concept and Instance behaviour into base Ruby value classes,
+# and allow any Class to become an Entity.
 #
 require 'date'
 
@@ -37,6 +40,8 @@ class NilClass #:nodoc:
 end
 
 class Class
+  # Make this Class into a Concept and if necessary its module into a Vocabulary.
+  # The parameters are the names (Symbols) of the identifying roles.
   def identified_by *args
     raise "not an entity type" if respond_to? :value_type  # Don't make a ValueType into an EntityType
     include ActiveFacts::API::Entity

data/lib/activefacts/api/support.rb

@@ -1,8 +1,8 @@
 #
-# ActiveFacts runtime API.
-# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#       ActiveFacts Runtime API.
+#       Various additions or patches to Ruby built-in classes, and some global support methods
 #
-# Note that we still require facets/basicobject, see numeric.rb
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 #
 
 class Symbol #:nodoc:
@@ -21,7 +21,7 @@ class String #:nodoc:
   end
 
   def snakecase
-    gsub(/([A-Z]+)([A-Z])/,'\1_\2').gsub(/([a-z])([A-Z])/,'\1_\2').downcase
+    gsub(/([a-z])([A-Z])/,'\1_\2').downcase
   end
 end
 

data/lib/activefacts/api/value.rb

@@ -1,6 +1,8 @@
 #
-# The ActiveFacts Runtime API Value extension module
-# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#       ActiveFacts Runtime API
+#       Value module (mixins for ValueType classes and instances)
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 #
 # The methods of this module are added to Value type classes.
 #
@@ -13,6 +15,7 @@ module ActiveFacts
 
       # Value instance methods:
       def initialize(*args) #:nodoc:
+        args[0] = args[0].__getobj__ if RoleProxy === args[0]
         super(args)
       end
 
@@ -59,7 +62,10 @@ module ActiveFacts
         def identifying_role_values(*args)  #:nodoc:
           # If the single arg is the correct class or a subclass, use it directly
           #puts "#{basename}.identifying_role_values#{args.inspect}"
-          return args[0] if (args.size == 1 and self.class === args[0])   # No secondary supertypes allowed for value types
+          if (args.size == 1 and (arg = args[0]).is_a?(self.class))   # No secondary supertypes allowed for value types
+            arg = arg.__getobj__ if RoleProxy === arg
+            return arg
+          end
           new(*args)
         end
 

data/lib/activefacts/api/vocabulary.rb

@@ -1,15 +1,21 @@
 #
-# The ActiveFacts Runtime API Vocabulary extension module.
-# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#       ActiveFacts Runtime API
+#       Vocabulary module (mixin for any Module that contains classes having Concept mixed in)
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 #
 # The methods of this module are extended into any module that contains
 # a Concept class (Entity type or Value type).
 #
 module ActiveFacts
   module API
+    # Vocabulary is a mixin that adds methods to any Module which has any Concept classes (ValueType or EntityType).
+    # A Vocabulary knows all the Concept classes including forward-referenced ones,
+    # and can resolve the forward references when the class is finally defined.
+    # Construction of a Constellation requires a Vocabuary as argument.
     module Vocabulary
       # With a parameter, look up a concept class by name.
-      # Without, return the hash of all concepts in this vocabulary
+      # Without, return the hash (keyed by the class' basename) of all concepts in this vocabulary
       def concept(name = nil)
         @concept ||= {}
         return @concept unless name
@@ -61,6 +67,7 @@ module ActiveFacts
             }*"\n\t"
       end
 
+=begin
       # Create or find an instance of klass in constellation using value to identify it
       def adopt(klass, constellation, value)  #:nodoc:
         puts "Adopting #{ value.verbalise rescue value.class.to_s+' '+value.inspect} as #{klass} into constellation #{constellation.object_id}"
@@ -68,20 +75,21 @@ module ActiveFacts
         path = "unknown"
         # Create a value instance we can hack if the value isn't already in this constellation
         if (c = constellation)
-          if klass === value            # Right class?
+          if value.is_a?(klass)            # Right class?
+            value = value.__getobj__ if RoleProxy === value
             vc = value.constellation rescue nil
             if (c == vc)                # Right constellation?
               # Already right class, in the right constellation
               path = "right constellation, right class, just use it"
             else
               # We need a new object from our constellation, so copy the value.
-              if klass.respond_to?(:identifying_roles)
+              if klass.respond_to?(:identifying_role_names)
                 # Make a new entity having only the identifying roles set.
                 # Someone will complain that this is wrong, and all functional role values should also
                 # be cloned, and I'm listening... but not there yet. Why just those?
                 cloned = c.send(
                     :"#{klass.basename}",
-                    *klass.identifying_roles.map{|role| value.send(role) }
+                    *klass.identifying_role_names.map{|role| value.send(role) }
                   )
                 path = "wrong constellation, right class, cloned entity"
               else
@@ -99,7 +107,8 @@ module ActiveFacts
           end
         else
           # This object's not in a constellation
-          if klass === value            # Right class?
+          if value.is_a?(klass)            # Right class?
+            value = value.__getobj__ if RoleProxy === value
             if vc = value.constellation rescue nil
               raise "REVISIT: Assigning to #{self.class.basename}.#{role_name} with constellation=#{c.inspect}: Can't dis-associate object from its constellation #{vc.object_id} yet"
             end
@@ -114,6 +123,7 @@ module ActiveFacts
         # print "#{path}"; puts ", adopted as #{value.verbalise rescue value.inspect}"
         value
       end
+=end
 
     end
   end

data/lib/activefacts/cql.rb

@@ -1,6 +1,8 @@
 #
-# ActiveFacts CQL loader.
-# Copyright (c) 2007 Clifford Heath. Read the LICENSE file.
+#       ActiveFacts CQL loader.
+#       Use Polyglot to patch things so you can *require* a CQL file and have it define a Ruby module.
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 #
 require 'rubygems'
 require 'polyglot'
@@ -9,12 +11,13 @@ require 'activefacts/input/cql'
 require 'activefacts/generate/ruby'
 
 module ActiveFacts
-  # Extend the generated parser:
+  # This class has a load method for Polyglot to tell it how to _require_ a CQL file.
+  # The CQL file is parsed to a vocabulary constellation, which is generated
+  # to Ruby code and eval'd, making the generated classes available.
+  # To make this Loader available, simply
+  #   require 'activefacts/cql'
   class CQLLoader
-    # This load method for Polyglot tells it how to _require_ a CQL file.
-    # The CQL file is parsed to a vocabulary constellation, which is generated
-    # to Ruby code and eval'd, making the generated classes available.
-    def self.load(file)
+    def self.load(file) #:nodoc:
       debug "Loading #{file}" do
         vocabulary = ActiveFacts::Input::CQL.readfile(file)
 

data/lib/activefacts/cql/CQLParser.treetop

@@ -1,3 +1,9 @@
+#
+#       ActiveFacts CQL Parser.
+#       Parse rules relating to high-level CQL definitions and constraints.
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
 module ActiveFacts
   grammar CQL
     include LexicalRules

data/lib/activefacts/cql/Concepts.treetop

@@ -1,3 +1,9 @@
+#
+#       ActiveFacts CQL Parser.
+#       Parse rules relating to Concept definitions.
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
 module ActiveFacts
   module CQL
     grammar Concepts
@@ -22,8 +28,8 @@ module ActiveFacts
 
       rule basetype
         is s
-	# independency?
-	identification
+        # independency?
+        identification
         { def supers; [] end
           def identifier; identification.value; end
         }
@@ -31,8 +37,8 @@ module ActiveFacts
 
       rule subtype
         subtype_prefix
-	# independency?
-	supertype_list ident:identification?
+        # independency?
+        supertype_list ident:identification?
         {
           def supers; supertype_list.value; end
           def identifier; ident.empty? ? nil : ident.value; end
@@ -41,7 +47,7 @@ module ActiveFacts
 
       # REVISIT: This doesn't work, and I don't know why.
       rule independency
-	 ('independent' S / 'separate' S / 'partitioned' S)
+         ('independent' S / 'separate' S / 'partitioned' S)
       end
 
       rule supertype_list
@@ -54,12 +60,12 @@ module ActiveFacts
       end
 
       rule identification
-	# REVISIT: Consider distinguishing "-Id" from just "Id", and not prepending the entity type name if no "-"
-        identified_by its s id s	  # Reference Mode
-	  { def value; {:mode => id.text_value }; end }
-	/
+        # REVISIT: Consider distinguishing "-Id" from just "Id", and not prepending the entity type name if no "-"
+        identified_by its s id s          # Reference Mode
+          { def value; {:mode => id.text_value }; end }
+        /
         identified_by role_list
-	  { def value; {:roles => role_list.roles }; end }
+          { def value; {:roles => role_list.roles }; end }
       end
 
       # Identified by roles... also used for constraints, beware
@@ -75,24 +81,24 @@ module ActiveFacts
           # We can't tell which word is an adjective and which is a concept here.
           # The concept might be forward-referenced, but not if adjectives are used.
           # REVISIT: This accepts double-adjective expressions (three words) but they don't work elsewhere
-	  rule lead_adj
-	    role_player_id '-'
-	  end
+          rule lead_adj
+            role_player_id '-'
+          end
 
-	  rule trail_adj
-	    '-' role_player_id
-	  end
+          rule trail_adj
+            '-' role_player_id
+          end
 
-	  rule role_player
-	    l:lead_adj? tail:(s role_player_id)+ s t:trail_adj?
-	    {
-	      def value
-		(l.empty? ? [] : [l.role_player_id.text_value]) +
-		tail.elements.map{|e| e.role_player_id.text_value } +
-		(t.empty? ? [] : [t.role_player_id.text_value])
-	      end
-	    }
-	  end
+          rule role_player
+            l:lead_adj? tail:(s role_player_id)+ s t:trail_adj?
+            {
+              def value
+                (l.empty? ? [] : [l.role_player_id.text_value]) +
+                tail.elements.map{|e| e.role_player_id.text_value } +
+                (t.empty? ? [] : [t.role_player_id.text_value])
+              end
+            }
+          end
 
           rule role_player_id
             !(role_list_sep / quantifier) id

data/lib/activefacts/cql/DataTypes.treetop

@@ -1,3 +1,9 @@
+#
+#       ActiveFacts CQL Parser.
+#       Parse rules relating to ValueType definitions.
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
 module ActiveFacts
   module CQL
     grammar DataTypes

data/lib/activefacts/cql/Expressions.treetop

@@ -1,3 +1,9 @@
+#
+#       ActiveFacts CQL Parser.
+#       Parse rules relating to Expressions
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
 module ActiveFacts
   module CQL
     grammar Expressions

data/lib/activefacts/cql/FactTypes.treetop

@@ -1,3 +1,9 @@
+#
+#       ActiveFacts CQL Parser.
+#       Parse rules relating to FactType definitions.
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
 module ActiveFacts
   module CQL
     grammar FactTypes

data/lib/activefacts/cql/Language/English.treetop

@@ -1,3 +1,9 @@
+#
+#       ActiveFacts CQL Parser.
+#       Parse rules the English syntax of CQL.
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
 module ActiveFacts
   module CQL
     grammar Language
@@ -17,9 +23,9 @@ module ActiveFacts
       rule quantifier
         each s                    { def value; [1, nil]; end }
         / some s                  { def value; nil; end }
-	  # REVISIT: "Some" means that any prior occurrence of this role player is to be ignored; this is a new occurrence
-	  # "that" on the other hand means that this role player was *previously* designated using "some".
-	  # These distinctions are lost here
+          # REVISIT: "Some" means that any prior occurrence of this role player is to be ignored; this is a new occurrence
+          # "that" on the other hand means that this role player was *previously* designated using "some".
+          # These distinctions are lost here
         / that s                  { def value; nil; end }
         / one s                   { def value; [1, 1]; end }
         / no s                    { def value; [0, 0]; end }

data/lib/activefacts/cql/LexicalRules.treetop

@@ -1,3 +1,9 @@
+#
+#       ActiveFacts CQL Parser.
+#       Various lexical rules for CQL.
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
 module ActiveFacts
   module CQL
     grammar LexicalRules

data/lib/activefacts/cql/Rakefile

@@ -1,3 +1,11 @@
+#
+#       ActiveFacts CQL Parser.
+#       A Rakefile to run Treetop when the ActiveFacts gem is installed.
+#       This isn't mandatory but makes it much faster to start the parser.
+#       Delete the generated files during parser development.
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
+#
 task :default do
   pattern = File.dirname(__FILE__) + '**/*.treetop'
   files = Dir[pattern]

data/lib/activefacts/cql/parser.rb

@@ -1,6 +1,8 @@
 #
-# ActiveFacts CQL parser and loader.
-# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#       ActiveFacts CQL Parser.
+#       The parser turns CQL strings into abstract syntax trees ready for semantic analysis.
+#
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 #
 require 'rubygems'
 require 'treetop'

data/lib/activefacts/generate/absorption.rb

@@ -1,17 +1,27 @@
 #
-# Generate text output for ActiveFacts vocabularies.
+#       ActiveFacts Generators.
+#       Absorption generator.
 #
-# Copyright (c) 2007 Clifford Heath. Read the LICENSE file.
-# Author: Clifford Heath.
+# Copyright (c) 2009 Clifford Heath. Read the LICENSE file.
 #
 require 'activefacts/persistence'
 
 module ActiveFacts
   module Generate
+    # Emit the absorption (Relational summary) for vocabulary.
+    # Not currently working, it relies on the old relational composition code.
+    # Invoke as
+    #   afgen --absorption[=options] <file>.cql"
+    # Options are comma or space separated:
+    # * no_columns Don't emit the columns
+    # * dependent Show Concepts that are not tables as well
+    # * paths Show the references paths through which each column was defined
+    # * no_identifier Don't show the identified_by columns for an EntityType
+
     class ABSORPTION
       include Metamodel
 
-      def initialize(vocabulary, *options)
+      def initialize(vocabulary, *options)  #:nodoc:
         @vocabulary = vocabulary
         @vocabulary = @vocabulary.Vocabulary.values[0] if ActiveFacts::API::Constellation === @vocabulary
         @no_columns = options.include? "no_columns"
@@ -20,7 +30,7 @@ module ActiveFacts
         @no_identifier = options.include? "no_identifier"
       end
 
-      def generate(out = $>)
+      def generate(out = $>)  #:nodoc:
         no_absorption = 0
         single_absorption_vts = 0
         single_absorption_ets = 0
@@ -31,42 +41,24 @@ module ActiveFacts
           # Don't dump imported (base) ValueTypes:
           next if ValueType === o && !o.supertype
           show(o)
-
-          case o.absorption_paths.size
-          when 0; no_absorption += 1
-          when 1
-            if ValueType === o
-              single_absorption_vts += 1
-            else
-              single_absorption_ets += 1
-            end
-          else
-            if ValueType === o
-              multi_absorption_vts += 1
-            else
-              multi_absorption_ets += 1
-            end
-          end
-
         end
-        puts "#{no_absorption} concepts have no absorption paths, #{single_absorption_vts}/#{single_absorption_ets} value/entity types have only one path, #{multi_absorption_vts}/#{multi_absorption_ets} have more than one"
       end
 
-      def show concept
-        return unless concept.independent || @dependent
+      def show concept        #:nodoc:
+        return unless concept.is_table || @dependent
 
         print "#{concept.name}"
-        print " (#{concept.tentative ? "tentatively " : ""}#{concept.independent ? "in" : ""}dependent)" if @dependent
+        print " (#{concept.tentative ? "tentatively " : ""}#{concept.is_table ? "in" : ""}dependent)" if @dependent
 
         if !@no_identifier && concept.is_a?(EntityType)
           print " is identified by:\n\t#{
-              concept.absorbed_reference_roles.all_role_ref.map { |rr| rr.column_name(".") } * ",\n\t"
+"REVISIT" #              concept.references_from.to_s
             }"
         end
         print "\n"
 
         unless @no_columns
-          puts "#{ concept.absorbed_roles.all_role_ref.map do |role_ref|
+          puts "#{ concept.references_from.map do |role_ref|
               "\t#{role_ref.column_name(".")}\n"
             end*"" }"
         end