activefacts 0.7.3 → 0.8.5

data/examples/local.css

@@ -0,0 +1,20 @@
+@charset "utf-8";
+
+.offline {
+	display: none;
+}
+
+.localnav {
+	position:fixed;
+	left:25px;
+	top:210px;
+}
+
+.hangleft {
+	margin-left: -220px;
+}
+
+.examples td {
+	vertical-align: top;
+	padding: 3px 5px 3px 5px;
+}

data/index.html

@@ -0,0 +1,96 @@
+<!--#include virtual="/header.html" -->
+<!--#include virtual="navbar.html" -->
+
+<link rel="stylesheet" href="css/offline.css" media="screen" type="text/css" />
+<link rel="stylesheet" href="css/print.css" media="print" type="text/css" />
+
+  <!-- Things to show only in the online version -->
+  <div id="sidebar" class="online">
+    <h3>Quotes</h3>
+    <!--p><em>&ldquo;epic, a masterwork&rdquo;</em></p>
+    <p align="right">Who</p-->
+
+    <p><em>&ldquo;I've long believed there must be a way to do this, but could never
+    work out how to start.&rdquo;</em></p>
+    <p align="right">OSDC conference attendee</p>
+
+    <!--p><em>&ldquo;Six months ago I quit my job and sold my house to fund a related
+    project that now seems trivial and unnecessary in comparison&rdquo;</em></p>
+    <p align="right">OSDC conference attendee</p>
+
+    <p><em>&ldquo;Epic, a major achievement. Your approach is so far ahead of the
+    industry it's hard to believe it possible.&rdquo;</em></p>
+    <p align="right">Who</p-->
+
+    <p><em>&ldquo;Inspirational!&rdquo;</em></p>
+    <p align="right">Sven Dowideit</p>
+  </div>
+
+  <div id="top" class="content">
+    <h2>ActiveFacts</h2>
+
+    <!-- Things to show only in the offline version -->
+    <div class="localnav offline noprint">
+      <ul>
+	<li><a href="http://dataconstellation.com" title="Data Constellation Home">Data Constellation</a></li>
+	<li><a href="http://dataconstellation.com/ActiveFacts" title="ActiveFacts Home Page">ActiveFacts Home</a></li>
+	<li><a href="examples/index.html" title="Example Models">Example Models</a></li>
+	<li><a href="examples/intro.html" title="Introduction to ORM2">Introduction to ORM2</a></li>
+	<li><a href="http://dataconstellation.com/ActiveFacts/CQLIntroduction.html" title="The Constellation Query Language">Constellation Query Language</a></li>
+	<li><a href="status.html" title="Project Status">Project Status</a></li>
+	<li><a href="download.html" title="Download">Download</a></li>
+	<!--li><a href="resources.html" title="Resources">Resources</a></li-->
+      </ul>
+    </div>
+
+    <p>
+    ActiveFacts is a <strong>semantic modeling toolkit</strong> that
+    revolutionises the processes of software <strong>specification</strong>,
+    <strong>design</strong>, and <strong>implementation</strong>. It
+    incorporates the Constellation Query Language (CQL) and the Constellation
+    API, which together enable your data to be designed, expressed and
+    queried in a completely natural form for the first time. The language
+    is so easy to learn and use because of the way it incorporates natural
+    language expressions into a formal framework. This allows the business
+    user (in conjunction with the programmer and database experts) to use
+    the language to express the rules and behaviour of the business domain,
+    in the process formulating efficient database designs without needing
+    specialist database skills.
+
+    <h3> Constellation Query Language </h3>
+
+      <p> CQL combines the power of a formal language with the intuitive feel
+	  of natural language. It can be used both to define and query semantic
+	  models. You can write CQL models directly, use APRIMO, or import ORM2
+	  models from <a href="http://www.ormfoundation.org/files/">NORMA</a>.
+      </p>
+
+    <h3> Constellation API </h3>
+      <p> The Constellation API introduces a new way to code
+	  transactional applications. Each user action results
+	  in a single query, which can span deeply into and
+	  across the whole database, returning only the data
+	  required to respond to that action. Any required
+	  changes are made to the result Constellation, and
+	  a single <em>save</em> operation pushes all the
+	  changes resulting from the user's action back into
+	  the database in a single atomic action.
+      </p>
+
+    <h3> Code generators </h3>
+      <p> The ActiveFacts code generation framework reads CQL
+	  and emits extensible and effective object models for
+	  use with the Constellation API, and efficient SQL
+	  for whatever relational database product you're using.
+      </p>
+
+    <h3> APRIMO </h3>
+      <p> APRIMO is a semantic model development environment,
+	  incorporating a Flash-based graphical designer that
+	  implements ORM2 diagrams, with direct CQL entry and
+	  even reverse engineering tools for existing databases.
+	  APRIMO is not yet publicly available.
+
+</div>
+
+<!--#include virtual="/footer.html" -->

data/lib/activefacts/api/concept.rb

@@ -54,27 +54,31 @@ module ActiveFacts
       # Define a binary fact type relating this concept to another,
       # with a uniqueness constraint only on this concept's role.
       # This method creates two accessor methods, one in this concept and one in the other concept.
-      # Parameters after the role_name may be omitted if not required:
-      # * 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>\_as_<role_name>
-      def has_one(*args)
-        role_name, related, mandatory, related_role_name = extract_binary_params(false, args)
+      # * role_name is a Symbol for the name of the role (this end of the relationship)
+      # Options contain optional keys:
+      # * :class - 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, say :mandatory => true. Mandatory constraints are only enforced during validation (e.g. before saving).
+      # * :counterpart - use if the role at the other end should have a name other than the default :all_<concept> or :all_<concept>\_as_<role_name>
+      # * :reading - for verbalisation. Not used yet.
+      # * :restrict - a list of values or ranges which this role may take. Not used yet.
+      def has_one(role_name, options = {})
+        role_name, related, mandatory, related_role_name = extract_binary_params(false, role_name, options)
         define_binary_fact_type(false, role_name, related, mandatory, related_role_name)
       end
 
       # Define a binary fact type joining this concept to another,
       # with uniqueness constraints in both directions, i.e. a one-to-one relationship
       # This method creates two accessor methods, one in this concept and one in the other concept.
-      # Parameters after the role_name may be omitted if not required:
-      # * 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>_as_<role_name>
-      def one_to_one(*args)
+      # * role_name is a Symbol for the name of the role (this end of the relationship)
+      # Options contain optional keys:
+      # * :class - 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, say :mandatory => true. Mandatory constraints are only enforced during validation (e.g. before saving).
+      # * :counterpart - use if the role at the other end should have a name other than the default :all_<concept> or :all_<concept>\_as_<role_name>
+      # * :reading - for verbalisation. Not used yet.
+      # * :restrict - a list of values or ranges which this role may take. Not used yet.
+      def one_to_one(role_name, options = {})
         role_name, related, mandatory, related_role_name =
-          extract_binary_params(true, args)
+          extract_binary_params(true, role_name, options)
         define_binary_fact_type(true, role_name, related, mandatory, related_role_name)
       end
 
@@ -291,6 +295,16 @@ module ActiveFacts
 
       # Extract the parameters to a role definition and massage them into the right shape.
       #
+      # The first parameter, role_name, is mandatory. It may be a Symbol, a String or a Class.
+      # New proposed input options:
+      # :class => the related class (Class object or Symbol). Not allowed if role_name was a class.
+      # :mandatory => true. There must be a related object for this object to be valid.
+      # :counterpart => Symbol/String. The name of the counterpart role. Will be to_s.snakecase'd and maybe augmented with "all_" and/or "_as_<role_name>"
+      # :reading => "forward/reverse". Forward and reverse readings. Must include MARKERS for the player names. May include adjectives. REVISIT: define MARKERS!
+      # LATER:
+      # :order => :local_role OR lambda{} (for sort_by)
+      # :restriction => Range or Array of Range/value or respond_to?(include?)
+      #
       # This function returns an array:
       # [ role_name,
       # related,
@@ -307,46 +321,34 @@ module ActiveFacts
       #   Role counterpart_concept name (not role name)
       #   Trailing Adjective
       # "_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)
+      def extract_binary_params(one_to_one, role_name, options)
+        # Options:
         #   other counterpart_concept (Symbol or Class)
         #   mandatory (:mandatory)
         #   other end role name if any (Symbol),
-        role_name = nil
         related = nil
         mandatory = false
         related_role_name = nil
         role_player = self.basename.snakecase
 
-        # Get the role name first:
-        case a = args.shift
-        when Symbol, String
-          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
-        # puts "role_name = #{role_name.inspect}"
+        role_name = a.name.snakecase.to_sym if Class === role_name
+        role_name = role_name.to_sym
 
         # The related class might be forward-referenced, so handle a Symbol/String instead of a Class.
-        case related_name = a = args.shift
+        related_name = options.delete(:class)
+        case related_name
+        when nil
+          related = role_name # No :class provided, assume it matches the role_name
+          related_name ||= role_name.to_s
         when Class
-          related = a
-          related_name = a.basename
-        when :mandatory, Numeric
-          args.unshift(a)       # Oops, undo.
-          related_name =
-          related = role_name
+          related = related_name
+          related_name = related_name.basename.to_s.snakecase
         when Symbol, String
-          related = a
+          related = related_name
+          related_name = related_name.to_s.snakecase
         else
-          related = role_name
+          raise "Invalid type for :class option on :#{role_name}"
         end
-        related_name ||= role_name
-        related_name = related_name.to_s.snakecase
 
         # resolve the Symbol to a Class now if possible:
         resolved = vocabulary.concept(related) rescue nil
@@ -354,16 +356,16 @@ module ActiveFacts
         related = resolved if resolved
         # puts "related = #{related.inspect}"
 
-        if args[0] == :mandatory
+        if options.delete(:mandatory) == true
           mandatory = true
-          args.shift
         end
 
-        if Symbol === args[0]
-          related_role_name = args.shift.to_s
-        end
+        related_role_name = related_role_name.to_s if related_role_name = options.delete(:counterpart)
+
+        reading = options.delete(:reading)        # REVISIT: Implement verbalisation
+        restriction = options.delete(:restrict)   # REVISIT: Implement role value restrictions
 
-        reading = args[0]
+        raise "Unrecognised options on #{role_name}: #{options.keys.inspect}" unless options.empty?
 
         # Avoid a confusing mismatch:
         # Note that if you have a role "supervisor" and a sub-class "Supervisor", this'll bitch.

data/lib/activefacts/api/constellation.rb

@@ -20,10 +20,11 @@ module ActiveFacts
     # As a result, you cannot "create" an object in a constellation - you merely _assert_
     # its existence. This is done using method_missing; @constellation.Thing(3) creates
     # an instance (or returns the existing instance) of Thing identified by the value 3.
+    # You can also use the populate() method to apply a block of assertions.
     #
-    # You can ##delete any instance, and that removes it from the constellation (will delete
-    # it from the database when the constellation is saved), and nullifies any references
-    # to it.
+    # You can instance##deny any instance, and that removes it from the constellation (will
+    # delete it from the database when the constellation is saved), and nullifies any
+    # references to it.
     #
     # A Constellation may or not be valid according to the vocabulary's constraints,
     # but it may also represent a portion of a larger population (a database) with
@@ -39,34 +40,26 @@ module ActiveFacts
       # Create a new empty Constellation over the given Vocabulary
       def initialize(vocabulary)
         @vocabulary = vocabulary
-        @instances = Hash.new{|h,k| h[k] = InstanceIndex.new }
+        @instances = Hash.new do |h,k|
+          raise "A constellation over #{@vocabulary.name} can only index instances of concepts in that vocabulary, not #{k.inspect}" unless k.is_a?(Class) and k.modspace == vocabulary
+          h[k] = InstanceIndex.new
+        end
       end
 
       def inspect #:nodoc:
         "Constellation:#{object_id}"
       end
 
-      # This method removes the given instance from this constellation's indexes
-      def delete(instance) #:nodoc:
-        # REVISIT: Need to search, as key values are gone already. Is there a faster way?
-        ([instance.class]+instance.class.supertypes_transitive).each do |klass|
-          @instances[klass].delete_if{|k,v| v == instance }
-        end
+      # Evaluate assertions against the population of this Constellation
+      def populate *args, &block
+        # REVISIT: Use args for something? Like options to enable/disable validation?
+        instance_eval(&block)
       end
 
-      # With parameters, assert an instance of the concept whose name is the missing method, identified by the values passed as *args*.
-      # With no parameters, return the collection of all instances of that concept.
-      def method_missing(m, *args)
-        if klass = @vocabulary.const_get(m)
-          if args.size == 0
-            # Return the collection of all instances of this class in the constellation:
-            @instances[klass]
-          else
-            # Assert a new ground fact (concept instance) of the specified class, identified by args:
-            # REVISIT: create a constructor method here instead?
-            instance, key = klass.assert_instance(self, args)
-            instance
-          end
+      # Delete instances from the constellation, nullifying (or cascading) the roles each plays
+      def deny(*instances)
+        Array(instances).each do |i|
+          i.deny
         end
       end
 
@@ -103,6 +96,33 @@ module ActiveFacts
                 } * "\n"
           }.compact*"\n"
       end
+
+      # This method removes the given instance from this constellation's indexes
+      # It must be called before the identifying roles get deleted or nullified.
+      def __deny(instance) #:nodoc:
+        # REVISIT: Need to search, as key values are gone already. Is there a faster way?
+        ([instance.class]+instance.class.supertypes_transitive).each do |klass|
+          @instances[klass].delete_if{|k,v| v == instance }
+        end
+        # REVISIT: Need to nullify all the roles this object plays.
+        # If mandatory on the counterpart side, this may/must propagate the delete (without mutual recursion!)
+      end
+
+      # With parameters, assert an instance of the concept whose name is the missing method, identified by the values passed as *args*.
+      # With no parameters, return the collection of all instances of that concept.
+      def method_missing(m, *args)
+        if klass = @vocabulary.const_get(m)
+          if args.size == 0
+            # Return the collection of all instances of this class in the constellation:
+            @instances[klass]
+          else
+            # Assert a new ground fact (concept instance) of the specified class, identified by args:
+            # REVISIT: create a constructor method here instead?
+            instance, key = klass.assert_instance(self, args)
+            instance
+          end
+        end
+      end
     end
   end
 end

data/lib/activefacts/api/entity.rb

@@ -231,7 +231,7 @@ module ActiveFacts
           other.identified_by *identifying_role_names
           subtypes << other unless subtypes.include? other
           #puts "#{self.name} inherited by #{other.name}"
-          vocabulary.add_concept(other)
+          vocabulary.__add_concept(other)
         end
 
         # verbalise this concept
@@ -249,7 +249,7 @@ module ActiveFacts
         unless vocabulary.respond_to? :concept  # Extend module with Vocabulary if necessary
           vocabulary.send :extend, Vocabulary
         end
-        vocabulary.add_concept(other)
+        vocabulary.__add_concept(other)
       end
     end
   end

data/lib/activefacts/api/instance.rb

@@ -28,9 +28,9 @@ module ActiveFacts
       end
 
       # De-assign all functional roles and remove from constellation, if any.
-      def delete
+      def deny
         # Delete from the constellation first, so it can remember our identifying role values
-        @constellation.delete(self) if @constellation
+        @constellation.__deny(self) if @constellation
 
         # Now, for all roles (from this class and all supertypes), assign nil to all functional roles
         # The counterpart roles get cleared automatically.
@@ -38,6 +38,10 @@ module ActiveFacts
           klass.roles.each do |role_name, role|
             next if role.unary?
             next if !role.unique
+
+            counterpart = role.counterpart
+            puts "Nullifying mandatory role #{role.name} of #{role.owner.name}" if counterpart.mandatory
+
             send "#{role.name}=", nil
           end
         end

data/lib/activefacts/api/instance_index.rb

@@ -37,6 +37,11 @@ module ActiveFacts
         h.map &b
       end
 
+      def detect &b
+        r = h.detect &b
+        r ? r[1] : nil
+      end
+
       # Return an array of all the instances of this concept
       def values
         h.values

data/lib/activefacts/api/value.rb

@@ -52,6 +52,12 @@ module ActiveFacts
           end
         end
 
+        class_eval do
+          define_method :restrict do |*value_ranges|
+            @value_ranges = *value_ranges
+          end
+        end
+
         # verbalise this ValueType
         def verbalise
           # REVISIT: Add length and scale here, if set
@@ -106,7 +112,7 @@ module ActiveFacts
           #puts "REVISIT: ValueType #{self} < #{self.superclass} was inherited by #{other}; not implemented" #+"from #{caller*"\n\t"}"
           # Copy the type parameters here, etc?
           other.send :realise_supertypes, self
-          vocabulary.add_concept(other)
+          vocabulary.__add_concept(other)
           super
         end
       end
@@ -122,7 +128,7 @@ module ActiveFacts
         unless vocabulary.respond_to? :concept  # Extend module with Vocabulary if necessary
           vocabulary.send :extend, Vocabulary
         end
-        vocabulary.add_concept(other)
+        vocabulary.__add_concept(other)
       end
     end
   end

data/lib/activefacts/api/vocabulary.rb

@@ -31,7 +31,21 @@ module ActiveFacts
         return (const_get("#{name}::#{camel}") rescue nil)
       end
 
-      def add_concept(klass)  #:nodoc:
+      # Create a new constellation over this vocabulary
+      def constellation
+        Constellation.new(self)
+      end
+
+      def verbalise
+        "Vocabulary #{name}:\n\t" +
+          @concept.keys.sort.map{|concept|
+              c = @concept[concept]
+              __bind(c.basename)
+              c.verbalise + "\n\t\t// Roles played: " + c.roles.verbalise
+            }*"\n\t"
+      end
+
+      def __add_concept(klass)  #:nodoc:
         name = klass.basename
         __bind(name)
         # puts "Adding concept #{name} to #{self.name}"
@@ -59,15 +73,6 @@ module ActiveFacts
         end
       end
 
-      def verbalise
-        "Vocabulary #{name}:\n\t" +
-          @concept.keys.sort.map{|concept|
-              c = @concept[concept]
-              __bind(c.basename)
-              c.verbalise + "\n\t\t// Roles played: " + c.roles.verbalise
-            }*"\n\t"
-      end
-
     end
   end
 end