RubyGems - activefacts - Versions diffs - 0.6.0 - Mend

activefacts 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (84) hide show

data/History.txt +4 -0
data/Manifest.txt +83 -0
data/README.rdoc +81 -0
data/Rakefile +41 -0
data/bin/afgen +46 -0
data/bin/cql +52 -0
data/examples/CQL/Address.cql +46 -0
data/examples/CQL/Blog.cql +54 -0
data/examples/CQL/CompanyDirectorEmployee.cql +51 -0
data/examples/CQL/Death.cql +16 -0
data/examples/CQL/Genealogy.cql +95 -0
data/examples/CQL/Marriage.cql +18 -0
data/examples/CQL/Metamodel.cql +238 -0
data/examples/CQL/MultiInheritance.cql +19 -0
data/examples/CQL/OilSupply.cql +47 -0
data/examples/CQL/Orienteering.cql +108 -0
data/examples/CQL/PersonPlaysGame.cql +17 -0
data/examples/CQL/SchoolActivities.cql +31 -0
data/examples/CQL/SimplestUnary.cql +12 -0
data/examples/CQL/SubtypePI.cql +32 -0
data/examples/CQL/Warehousing.cql +99 -0
data/examples/CQL/WindowInRoomInBldg.cql +22 -0
data/lib/activefacts.rb +10 -0
data/lib/activefacts/api.rb +25 -0
data/lib/activefacts/api/concept.rb +384 -0
data/lib/activefacts/api/constellation.rb +106 -0
data/lib/activefacts/api/entity.rb +239 -0
data/lib/activefacts/api/instance.rb +54 -0
data/lib/activefacts/api/numeric.rb +158 -0
data/lib/activefacts/api/role.rb +94 -0
data/lib/activefacts/api/standard_types.rb +67 -0
data/lib/activefacts/api/support.rb +59 -0
data/lib/activefacts/api/value.rb +122 -0
data/lib/activefacts/api/vocabulary.rb +120 -0
data/lib/activefacts/cql.rb +31 -0
data/lib/activefacts/cql/CQLParser.treetop +104 -0
data/lib/activefacts/cql/Concepts.treetop +112 -0
data/lib/activefacts/cql/DataTypes.treetop +66 -0
data/lib/activefacts/cql/Expressions.treetop +113 -0
data/lib/activefacts/cql/FactTypes.treetop +185 -0
data/lib/activefacts/cql/Language/English.treetop +92 -0
data/lib/activefacts/cql/LexicalRules.treetop +169 -0
data/lib/activefacts/cql/Rakefile +6 -0
data/lib/activefacts/cql/parser.rb +88 -0
data/lib/activefacts/generate/absorption.rb +87 -0
data/lib/activefacts/generate/cql.rb +441 -0
data/lib/activefacts/generate/cql/html.rb +397 -0
data/lib/activefacts/generate/null.rb +19 -0
data/lib/activefacts/generate/ordered.rb +557 -0
data/lib/activefacts/generate/ruby.rb +326 -0
data/lib/activefacts/generate/sql/server.rb +164 -0
data/lib/activefacts/generate/text.rb +21 -0
data/lib/activefacts/input/cql.rb +1268 -0
data/lib/activefacts/input/orm.rb +926 -0
data/lib/activefacts/persistence.rb +1 -0
data/lib/activefacts/persistence/composition.rb +653 -0
data/lib/activefacts/support.rb +51 -0
data/lib/activefacts/version.rb +3 -0
data/lib/activefacts/vocabulary.rb +6 -0
data/lib/activefacts/vocabulary/extensions.rb +343 -0
data/lib/activefacts/vocabulary/metamodel.rb +303 -0
data/script/txt2html +71 -0
data/spec/absorption_spec.rb +95 -0
data/spec/api/autocounter.rb +82 -0
data/spec/api/constellation.rb +130 -0
data/spec/api/entity_type.rb +101 -0
data/spec/api/instance.rb +428 -0
data/spec/api/roles.rb +122 -0
data/spec/api/value_type.rb +112 -0
data/spec/api_spec.rb +14 -0
data/spec/cql_cql_spec.rb +58 -0
data/spec/cql_parse_spec.rb +31 -0
data/spec/cql_ruby_spec.rb +60 -0
data/spec/cql_sql_spec.rb +54 -0
data/spec/cql_symbol_tables_spec.rb +259 -0
data/spec/cql_unit_spec.rb +336 -0
data/spec/cqldump_spec.rb +169 -0
data/spec/norma_cql_spec.rb +48 -0
data/spec/norma_ruby_spec.rb +50 -0
data/spec/norma_sql_spec.rb +45 -0
data/spec/norma_tables_spec.rb +94 -0
data/spec/spec.opts +1 -0
data/spec/spec_helper.rb +10 -0
metadata +173 -0

data/lib/activefacts/generate/cql/html.rb ADDED Viewed

@@ -0,0 +1,397 @@
+#
+# Generate HTML-highlighted CQL from an ActiveFacts vocabulary.
+# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#
+# The text generated here is pre-formatted, and in spans haing the following styles:
+# keyword: ORM2 standard colour is #00C (blue)
+# concept: ORM2 standard concept is #808 (purple)
+# copula: ORM2 standard concept is #060 (green)
+#
+require 'activefacts/vocabulary'
+require 'activefacts/api'
+require 'activefacts/generate/ordered'
+require 'activefacts/generate/cql'
+module ActiveFacts
+  module Generate
+    class CQL
+    class HTML < CQL
+      def initialize(vocabulary, *options)
+        super
+      end
+      def puts s
+        super(s.gsub(/[,;]/) do |p| keyword p; end)
+      end
+      def keyword(str)
+        "<span class='keyword'>#{str}</span>"
+      end
+      def concept(str)
+        "<span class='concept'>#{str}</span>"
+      end
+      def copula(str)
+        "<span class='copula'>#{str}</span>"
+      end
+      def vocabulary_start(vocabulary)
+        puts %q{<head>
+          <link rel="stylesheet" href="css/orm2.css" type="text/css"/>
+          </head>
+          <pre class="copula">}
+        puts "#{keyword "vocabulary"} #{concept(vocabulary.name)};\n\n"
+      end
+      def vocabulary_end
+        puts %q{</pre>}
+      end
+      def value_type_banner
+        puts "/*\n * Value Types\n */"
+      end
+      def value_type_dump(o)
+        return unless o.supertype    # An imported type
+        if o.name == o.supertype.name
+            # In ActiveFacts, parameterising a ValueType will create a new datatype
+            # throw Can't handle parameterized value type of same name as its datatype" if ...
+        end
+        parameters =
+          [ o.length != 0 || o.scale != 0 ? o.length : nil,
+            o.scale != 0 ? o.scale : nil
+          ].compact
+        parameters = parameters.length > 0 ? "("+parameters.join(",")+")" : "()"
+        puts "#{concept o.name} #{keyword "is defined as"} #{concept o.supertype.name + parameters }#{
+            if (o.value_restriction)
+              keyword("restricted to")+
+              o.value_restriction.all_allowed_range.map{|ar|
+                  # REVISIT: Need to display as string or numeric according to type here...
+                  min = ar.value_range.minimum_bound
+                  max = ar.value_range.maximum_bound
+                  range = (min ? min.value : "") +
+                    (min.value != (max&&max.value) ? (".." + (max ? max.value : "")) : "")
+                  keyword range
+                }*", "
+            else
+              ""
+            end
+          };"
+      end
+      def append_ring_to_reading(reading, ring)
+        reading << keyword(" [#{(ring.ring_type.scan(/[A-Z][a-z]*/)*", ").downcase}]")
+      end
+      def identified_by_roles_and_facts(entity_type, identifying_roles, identifying_facts, preferred_readings)
+        identifying_role_names = identifying_roles.map{|role|
+            preferred_role_ref = preferred_readings[role.fact_type].role_sequence.all_role_ref.detect{|reading_rr|
+                reading_rr.role == role
+              }
+            role_words = []
+            # REVISIT: Consider whether NOT to use the adjective if it's a prefix of the role_name
+            role_name = role.role_name
+            role_name = nil if role_name == ""
+            # debug "concept.name=#{preferred_role_ref.role.concept.name}, role_name=#{role_name.inspect}, preferred_role_name=#{preferred_role_ref.role.role_name.inspect}"
+            if (role.fact_type.all_role.size == 1)
+              # REVISIT: Guard against unary reading containing the illegal words "and" and "where".
+              role.fact_type.default_reading    # Need whole reading for a unary.
+            elsif (role_name)
+              role_name
+            else
+              role_words << preferred_role_ref.leading_adjective if preferred_role_ref.leading_adjective != ""
+              role_words << preferred_role_ref.role.concept.name
+              role_words << preferred_role_ref.trailing_adjective if preferred_role_ref.trailing_adjective != ""
+              role_words.compact*"-"
+            end
+          }
+        # REVISIT: Consider emitting extra fact types here, instead of in entity_type_dump?
+        # Just beware that readings having the same players will be considered to be of the same fact type, even if they're not.
+        # Detect standard reference-mode scenarios
+        ft = identifying_facts[0]
+        fact_constraints = nil
+        if identifying_facts.size == 1 and
+          entity_role = ft.all_role[n = (ft.all_role[0].concept == entity_type ? 0 : 1)] and
+          value_role = ft.all_role[1-n] and
+          value_name = value_role.concept.name and
+          residual = value_name.gsub(%r{#{entity_role.concept.name}},'') and
+          residual != '' and
+          residual != value_name
+          # The EntityType is identified by its association with a single ValueType
+          # whose name is an extension (the residual) of the EntityType's name.
+          # Detect standard reference-mode readings:
+          forward_reading = reverse_reading = nil
+          ft.all_reading.each do |reading|
+            if reading.reading_text =~ /^\{(\d)\} has \{\d\}$/
+              if reading.role_sequence.all_role_ref[$1.to_i].role == entity_role
+                forward_reading = reading
+              else
+                reverse_reading = reading
+              end
+            elsif reading.reading_text =~ /^\{(\d)\} is of \{\d\}$/
+              if reading.role_sequence.all_role_ref[$1.to_i].role == value_role
+                reverse_reading = reading
+              else
+                forward_reading = reading
+              end
+            end
+          end
+          debug :mode, "------------------- Didn't find standard forward reading" unless forward_reading
+          debug :mode, "------------------- Didn't find standard reverse reading" unless reverse_reading
+          # If we didn't find at least one of the standard readings, don't use a refmode:
+          if (forward_reading || reverse_reading)
+            # Elide the constraints that would have been emitted on those readings.
+            # If there is a UC that's not in the standard form for a reference mode,
+            # we have to emit the standard reading anyhow.
+            fact_constraints = @presence_constraints_by_fact[ft]
+            fact_constraints.each do |pc|
+              if (pc.role_sequence.all_role_ref.size == 1 and pc.max_frequency == 1)
+                # It's a uniqueness constraint, and will be regenerated
+                @constraints_used[pc] = true
+              end
+            end
+            @fact_types_dumped[ft] = true
+            # Figure out whether any non-standard readings exist:
+            other_readings = ft.all_reading - [forward_reading] - [reverse_reading]
+            debug :mode, "--- other_readings.size now = #{other_readings.size}" if other_readings.size > 0
+            fact_text = other_readings.map do |reading|
+              expanded_reading(reading, fact_constraints, true)
+            end*",\n\t"
+            return keyword(" identified by its ") +
+              concept(residual) +
+              (fact_text != "" ? keyword(" where\n\t") + fact_text : "")
+          end
+        end
+        identifying_facts.each{|f| @fact_types_dumped[f] = true }
+        @identifying_fact_text =
+            identifying_facts.map{|f|
+                fact_readings_with_constraints(f, fact_constraints)
+            }.flatten*",\n\t"
+        keyword(" identified by ") +
+          identifying_role_names.map{|n| concept n} * keyword(" and ") +
+          keyword(" where\n\t") +
+          @identifying_fact_text
+      end
+      def show_frequency role, constraint
+        # REVISIT: Need to also colorize the adjectives here:
+        [ constraint ? keyword(constraint.frequency) : nil, concept(role.concept.name) ]
+      end
+      def entity_type_banner
+        puts(keyword("/*\n * Entity Types\n */"))
+      end
+      def fact_readings(fact_type)
+        constrained_fact_readings = fact_readings_with_constraints(fact_type)
+        constrained_fact_readings*",\n\t"
+      end
+      def subtype_dump(o, supertypes, pi)
+        print "#{concept o.name} #{keyword "is a kind of"} #{ o.supertypes.map(&:name).map{|n| concept n}*keyword(", ") }"
+        if pi
+          print identified_by(o, pi)
+        end
+        # If there's a preferred_identifier for this subtype, identifying readings were emitted
+        if o.fact_type
+          print(
+            (pi ? "," : keyword(" where")) +
+            "\n\t" +
+            fact_readings(o.fact_type)
+          )
+        end
+        puts ";\n"
+      end
+      def non_subtype_dump(o, pi)
+        print "#{concept(o.name)} #{keyword "is"}" +
+          identified_by(o, pi)
+        print(keyword(" where\n\t") + fact_readings(o.fact_type)) if o.fact_type
+        puts ";\n"
+      end
+      def fact_type_dump(fact_type, name)
+        @identifying_fact_text = nil
+        if (o = fact_type.entity_type)
+          print "#{concept o.name} #{keyword "is"}"
+          if !o.all_type_inheritance_by_subtype.empty?
+            print(keyword(" a kind of ") + o.supertypes.map(&:name).map{|n| concept n}*", ")
+          end
+          # Alternate identification of objectified fact type?
+          primary_supertype = o.supertypes[0]
+          pi = fact_type.entity_type.preferred_identifier
+          if pi && primary_supertype && primary_supertype.preferred_identifier != pi
+            print identified_by(o, pi)
+            print ";\n"
+          end
+        end
+        unless @identifying_fact_text
+          print(keyword(" where\n\t")) if o
+          puts(fact_readings(fact_type)+";")
+        end
+      end
+      def fact_type_banner
+        puts keyword("/*\n * Fact Types\n */")
+      end
+      def constraint_banner
+        puts keyword("/*\n * Constraints:\n */")
+      end
+      def dump_presence_constraint(c)
+        roles = c.role_sequence.all_role_ref.map{|rr| rr.role }
+        # REVISIT: If only one role is covered and it's mandatory >=1 constraint, use SOME/THAT form:
+        # each Bug SOME Tester logged THAT Bug;
+        players = c.role_sequence.all_role_ref.map{|rr| rr.role.concept.name}.uniq
+        fact_types = c.role_sequence.all_role_ref.map{|rr| rr.role.fact_type}.uniq
+        puts \
+          "#{keyword "each #{players.size > 1 ? "combination " : ""}"}"+
+          "#{players.map{|n| concept n}*", "} "+
+          "#{keyword "occurs #{c.frequency} time in"}\n\t"+
+          "#{fact_types.map{|ft| ft.default_reading([], nil)}*",\n\t"}" +
+            ";"
+      end
+      def dump_set_constraint(c)
+        # REVISIT exclusion: every <player-list> must<?> either reading1, reading2, ...
+        # Each constraint involves two or more occurrences of one or more players.
+        # For each player, a subtype may be involved in the occurrences.
+        # Find the common supertype of each player.
+        scrs = c.all_set_comparison_roles
+        player_count = scrs[0].role_sequence.all_role_ref.size
+        role_seq_count = scrs.size
+        #raise "Can't verbalise constraint over many players and facts" if player_count > 1 and role_seq_count > 1
+        players_differ = []   # Record which players are also played by subclasses
+        players = (0...player_count).map do |pi|
+          # Find the common supertype of the players of the pi'th role in each sequence
+          concepts = scrs.map{|r| r.role_sequence.all_role_ref[pi].role.concept }
+          player, players_differ[pi] = common_supertype(concepts)
+          raise "Role sequences of #{c.class.basename} must have concepts matching #{c.name} in position #{pi}" unless player
+          player
+        end
+        #puts "#{c.class.basename} has players #{players.map{|p| p.name}*", "}"
+        if (SetEqualityConstraint === c)
+          # REVISIT: Need a proper approach to some/that and adjective disambiguation:
+          puts \
+            scrs.map{|scr|
+              scr.role_sequence.all_role_ref.map{|rr|
+                rr.role.fact_type.default_reading([], nil)
+              }*keyword(" and ")
+            } * keyword("\n\tif and only if\n\t") + ";"
+          return
+        end
+        mode = c.is_mandatory ? "exactly one" : "at most one"
+        puts "#{keyword "for each"} #{players.map{|p| concept p.name}*", "} #{keyword(mode + " of these holds")}:\n\t" +
+          (scrs.map do |scr|
+            constrained_roles = scr.role_sequence.all_role_ref.map{|rr| rr.role }
+            fact_types = constrained_roles.map{|r| r.fact_type }.uniq
+            fact_types.map do |fact_type|
+              # REVISIT: future: Use "THAT" and "SOME" only when:
+              # - the role player occurs twice in the reading, or
+              # - is a subclass of the constrained concept, or
+              reading = fact_type.preferred_reading
+              expand_constrained(reading, constrained_roles, players, players_differ)
+            end * keyword(" and ")
+          end*",\n\t"
+          )+';'
+      end
+      # Expand this reading using (in)definite articles where needed
+      # Handle any roles in constrained_roles specially.
+      def expand_constrained(reading, constrained_roles, players, players_differ)
+        frequency_constraints = reading.role_sequence.all_role_ref.map {|role_ref|
+            i = constrained_roles.index(role_ref.role)
+            if !i
+              v = [ "some", role_ref.role.concept.name]
+            elsif players_differ[i]
+              v = [ "that", players[i].name ]   # Make sure to use the superclass name
+            else
+              if reading.fact_type.all_role.select{|r| r.concept == role_ref.role.concept }.size > 1
+                v = [ "that", role_ref.role.concept.name ]
+              else
+                v = [ "some", role_ref.role.concept.name ]
+              end
+            end
+            v[0] = keyword(v[0])
+            v[1] = concept(v[1])
+            v
+          }
+        frequency_constraints = [] unless frequency_constraints.detect{|fc| fc[0] =~ /some/ }
+        #$stderr.puts "fact_type roles (#{fact_type.all_role.map{|r| r.concept.name}*","}) default_reading '#{fact_type.preferred_reading.reading_text}' roles (#{fact_type.preferred_reading.role_sequence.all_role_ref.map{|rr| rr.role.concept.name}*","}) #{frequency_constraints.inspect}"
+        # REVISIT: Make sure that we refer to the constrained players by their common supertype
+        reading.expand(frequency_constraints, nil)
+      end
+      def dump_subset_constraint(c)
+        # If the role players are identical and not duplicated, we can simply say "reading1 only if reading2"
+        subset_roles = c.subset_role_sequence.all_role_ref.map{|rr| rr.role}
+        superset_roles = c.superset_role_sequence.all_role_ref.map{|rr| rr.role}
+        subset_players = subset_roles.map(&:concept)
+        superset_players = superset_roles.map(&:concept)
+        subset_fact_types = c.subset_role_sequence.all_role_ref.map{|rr| rr.role.fact_type }.uniq
+        superset_fact_types = c.superset_role_sequence.all_role_ref.map{|rr| rr.role.fact_type }.uniq
+        # We need to ensure that if the player of any constrained role also exists
+        # as the player of a role that's not a constrained role, there are different
+        # adjectives or other qualifiers qualifier applied to distinguish that role.
+        fact_type_roles = (subset_fact_types+superset_fact_types).map{|ft| ft.all_role }.flatten
+        non_constrained_roles = fact_type_roles - subset_roles - superset_roles
+        if (r = non_constrained_roles.detect{|r| (subset_roles+superset_roles).include?(r) })
+          # REVISIT: Find a way to deal with this problem, should it arise.
+          # It would help, but not entirely fix it, to use SOME/THAT to identify the constrained roles.
+          # See ServiceDirector's DataStore<->Client fact types for example
+          # Use SOME on the subset, THAT on the superset.
+          raise "Critical ambiguity, #{r.concept.name} occurs both constrained and unconstrained in #{c.name}"
+        end
+        puts \
+          "#{subset_fact_types.map{|ft| ft.default_reading([], nil)}*" and "}" +
+          "\n\t#{keyword "only if"} " +
+          "#{superset_fact_types.map{|ft| ft.default_reading([], nil)}*" and "}" +
+          ";"
+      end
+    end
+    end
+  end
+end

data/lib/activefacts/generate/null.rb ADDED Viewed

@@ -0,0 +1,19 @@
+#
+# Generate text output for ActiveFacts vocabularies.
+#
+# Copyright (c) 2007 Clifford Heath. Read the LICENSE file.
+# Author: Clifford Heath.
+#
+module ActiveFacts
+  module Generate
+    class NULL
+      def initialize(vocabulary)
+        @vocabulary = vocabulary
+      end
+      def generate(out = $>)
+      end
+    end
+  end
+end

data/lib/activefacts/generate/ordered.rb ADDED Viewed

@@ -0,0 +1,557 @@
+#
+# Generator superclass for ActiveFacts vocabularies that performs sequencing to avoid forward references.
+#
+# Copyright (c) 2008 Clifford Heath. Read the LICENSE file.
+#
+require 'activefacts/api'
+module ActiveFacts
+  class OrderedDumper #:nodoc:
+    include Metamodel
+    def initialize(vocabulary, *options)
+      @vocabulary = vocabulary
+      @vocabulary = @vocabulary.Vocabulary.values[0] if ActiveFacts::API::Constellation === @vocabulary
+      options.each{|option| set_option(option) }
+    end
+    def set_option(option)
+    end
+    def puts(*a)
+      @out.puts *a
+    end
+    def print(*a)
+      @out.print *a
+    end
+    def generate(out = $>)
+      @out = out
+      vocabulary_start(@vocabulary)
+      build_indices
+      @concept_types_dumped = {}
+      @fact_types_dumped = {}
+      value_types_dump()
+      entity_types_dump()
+      fact_types_dump()
+      constraints_dump(@constraints_used)
+      vocabulary_end
+    end
+    def build_indices
+      @presence_constraints_by_fact = Hash.new{ |h, k| h[k] = [] }
+      @ring_constraints_by_fact = Hash.new{ |h, k| h[k] = [] }
+      @vocabulary.all_constraint.each { |c|
+          case c
+          when PresenceConstraint
+            fact_types = c.role_sequence.all_role_ref.map{|rr| rr.role.fact_type}.uniq  # All fact types spanned by this constraint
+            if fact_types.size == 1     # There's only one, save it:
+              # debug "Single-fact constraint on #{fact_types[0].fact_type_id}: #{c.name}"
+              (@presence_constraints_by_fact[fact_types[0]] ||= []) << c
+            end
+          when RingConstraint
+            (@ring_constraints_by_fact[c.role.fact_type] ||= []) << c
+          else
+            # debug "Found unhandled constraint #{c.class} #{c.name}"
+          end
+        }
+      @constraints_used = {}
+    end
+    def value_types_dump
+      done_banner = false
+      @vocabulary.all_feature.sort_by{|o| o.name}.each{|o|
+          next unless ValueType === o
+          value_type_banner unless done_banner
+          done_banner = true
+          value_type_dump(o)
+          @concept_types_dumped[o] = true
+        }
+      value_type_end if done_banner
+    end
+    # Try to dump entity types in order of name, but we need
+    # to dump ETs before they're referenced in preferred ids
+    # if possible (it's not always, there may be loops!)
+    def entity_types_dump
+      # Build hash tables of precursors and followers to use:
+      precursors, followers = *build_entity_dependencies
+      done_banner = false
+      sorted = @vocabulary.all_feature.select{|o| EntityType === o and !o.fact_type }.sort_by{|o| o.name}
+      panic = nil
+      while true do
+        count_this_pass = 0
+        skipped_this_pass = 0
+        sorted.each{|o|
+            next if @concept_types_dumped[o]    # Already done
+            # Can we do this yet?
+            if (o != panic and                  # We don't *have* to do it (panic mode)
+                (p = precursors[o]) and         # There might be...
+                p.size > 0)                     # precursors - still blocked
+              skipped_this_pass += 1
+              next
+            end
+            entity_type_banner unless done_banner
+            done_banner = true
+            # We're going to emit o - remove it from precursors of others:
+            (followers[o]||[]).each{|f|
+                precursors[f] -= [o]
+              }
+            count_this_pass += 1
+            panic = nil
+            entity_type_dump(o)
+            released_fact_types_dump(o)
+            entity_type_group_end
+          }
+          # Check that we made progress if there's any to make:
+          if count_this_pass == 0 && skipped_this_pass > 0
+            if panic        # We were already panicing... what to do now?
+              # This won't happen again unless the above code is changed to decide it can't dump "panic".
+              raise "Unresolvable cycle of forward references: " +
+                (bad = sorted.select{|o| EntityType === o && !@concept_types_dumped[o]}).map{|o| o.name }.inspect +
+                ":\n\t" + bad.map{|o|
+                  o.name +
+                  ": " +
+                  precursors[o].map{|p| p.name}.uniq.inspect
+                } * "\n\t" + "\n"
+            else
+              # Find the object that has the most followers and no fwd-ref'd supertypes:
+              # This selection might be better if we allow PI roles to be fwd-ref'd...
+              panic = sorted.
+                select{|o| !@concept_types_dumped[o] }.
+                sort_by{|o|
+                    f = followers[o] || [];
+                    o.supertypes.detect{|s| !@concept_types_dumped[s] } ? 0 : -f.size
+                  }[0]
+              # debug "Panic mode, selected #{panic.name} next"
+            end
+          end
+          break if skipped_this_pass == 0       # All done.
+      end
+    end
+    def entity_type_dump(o)
+      @concept_types_dumped[o] = true
+      pi = o.preferred_identifier
+      supers = o.supertypes
+      if (supers.size > 0)
+        # Ignore identification by a supertype:
+        pi = nil if pi && pi.role_sequence.all_role_ref[0].role.fact_type.is_a?(TypeInheritance)
+        subtype_dump(o, supers, pi)
+      else
+        non_subtype_dump(o, pi)
+      end
+      @constraints_used[pi] = true
+    end
+    def identified_by(o, pi)
+      # Different adjectives might be used for different readings.
+      # Here, we must find the role_ref containing the adjectives that we need for each identifier,
+      # which will be attached to the uniqueness constraint on this object in the binary FT that
+      # attaches that identifying role.
+      role_refs = pi.role_sequence.all_role_ref.sort_by{|role_ref| role_ref.ordinal}
+      # We need to get the adjectives for the roles from the identifying fact's preferred readings:
+      identifying_facts = role_refs.map{|rr| rr.role.fact_type }.uniq
+      preferred_readings = identifying_facts.inject({}){|reading_hash, fact_type|
+          pr = fact_type.preferred_reading
+          reading_hash[fact_type] = pr
+          reading_hash
+        }
+      #p identifying_facts.map{|f| f.preferred_reading }
+      identifying_roles = role_refs.map(&:role)
+      identification = identified_by_roles_and_facts(o, identifying_roles, identifying_facts, preferred_readings)
+      #identifying_facts.each{|f| @fact_types_dumped[f] = true }
+      identification
+    end
+    def fact_readings_with_constraints(fact_type, fact_constraints = nil)
+      define_role_names = true
+      fact_constraints ||= @presence_constraints_by_fact[fact_type]
+      readings = fact_type.all_reading_by_ordinal.inject([]) do |reading_array, reading|
+        reading_array << expanded_reading(reading, fact_constraints, define_role_names)
+        define_role_names = false     # No need to define role names in subsequent readings
+        reading_array
+      end
+      readings
+    end
+    def expanded_reading(reading, fact_constraints, define_role_names)
+      # Find all role numbers in order of occurrence in this reading:
+      role_refs = reading.role_sequence.all_role_ref.sort_by{|role_ref| role_ref.ordinal}
+      role_numbers = reading.reading_text.scan(/\{(\d)\}/).flatten.map{|m| Integer(m) }
+      roles = role_numbers.map{|m| role_refs[m].role }
+      # debug "Considering #{reading.reading_text} having #{role_numbers.inspect}"
+      # Find the constraints that constrain frequency over each role we can verbalise:
+      frequency_constraints = []
+      roles.each do |role|
+        # Find a mandatory constraint that's *not* unique; this will need an extra reading
+        role_is_first_in = reading.fact_type.all_reading.detect{|r|
+            role == r.role_sequence.all_role_ref.sort_by{|role_ref|
+                role_ref.ordinal
+              }[0].role
+          }
+        if (role == roles.last)   # First role of the reading?
+          # REVISIT: With a ternary, doing this on other than the last role can be ambiguous,
+          # in case both the 2nd and 3rd roles have frequencies. Think some more!
+          constraint = fact_constraints.find{|c|  # Find a UC that spans all other Roles
+              # internal uniqueness constraints span all roles but one, the residual:
+              PresenceConstraint === c &&
+                !@constraints_used[c] &&  # Already verbalised
+                roles-c.role_sequence.all_role_ref.map(&:role) == [role]
+            }
+          # Index the frequency implied by the constraint under the role position in the reading
+          if constraint     # Mark this constraint as "verbalised" so we don't do it again:
+            @constraints_used[constraint] = true
+          end
+          frequency_constraints << show_frequency(role, constraint)
+        else
+          frequency_constraints << show_frequency(role, nil)
+        end
+      end
+      expanded = reading.expand(frequency_constraints, define_role_names)
+      if (ft_rings = @ring_constraints_by_fact[reading.fact_type]) &&
+         (ring = ft_rings.detect{|rc| !@constraints_used[rc]})
+        @constraints_used[ring] = true
+        append_ring_to_reading(expanded, ring)
+      end
+      expanded
+    end
+    def show_frequency role, constraint
+      constraint ? constraint.frequency : nil
+    end
+    def describe_fact_type(fact_type, highlight = nil)
+      (fact_type.entity_type ? fact_type.entity_type.name : "")+
+      describe_roles(fact_type.all_role, highlight)
+    end
+    def describe_roles(roles, highlight = nil)
+      "("+
+      roles.map{|role| role.concept.name + (role == highlight ? "*" : "")}*", "+
+      ")"
+    end
+    def describe_role_sequence(role_sequence)
+      "("+
+      role_sequence.all_role_ref.map{|role_ref| role_ref.role.concept.name }*", "+
+      ")"
+    end
+    # This returns an array of two hash tables each keyed by an EntityType.
+    # The values of each hash entry are the precursors and followers (respectively) of that entity.
+    def build_entity_dependencies
+      @vocabulary.all_feature.inject([{},{}]) { |a, o|
+          if EntityType === o && !o.fact_type
+            precursor = a[0]
+            follower = a[1]
+            blocked = false
+            pi = o.preferred_identifier
+            if pi
+              pi.role_sequence.all_role_ref.each{|rr|
+                  role = rr.role
+                  player = role.concept
+                  next unless EntityType === player
+                  # player is a precursor of o
+                  (precursor[o] ||= []) << player if (player != o)
+                  (follower[player] ||= []) << o if (player != o)
+                }
+            end
+            # Supertypes are precursors too:
+            subtyping = o.all_type_inheritance_by_supertype
+            next a if subtyping.size == 0
+            subtyping.each{|ti|
+                # debug ti.class.roles.verbalise; debug "all_type_inheritance_by_supertype"; exit
+                s = ti.subtype
+                (precursor[s] ||= []) << o
+                (follower[o] ||= []) << s
+              }
+          end
+          a
+        }
+    end
+    # Dump all fact types for which all precursors (of which "o" is one) have been emitted:
+    def released_fact_types_dump(o)
+      roles = o.all_role
+      begin
+        progress = false
+        roles.map(&:fact_type).uniq.select{|fact_type|
+            # The fact type hasn't already been dumped but all its role players have
+            !@fact_types_dumped[fact_type] &&
+              !fact_type.all_role.detect{|r| !@concept_types_dumped[r.concept] }
+          }.sort_by{|fact_type|
+            fact_type_key(fact_type)
+          }.each{|fact_type|
+            fact_type_dump_with_dependents(fact_type)
+            # Objectified Fact Types may release additional fact types
+            roles += fact_type.entity_type.all_role if fact_type.entity_type
+            progress = true
+          }
+      end while progress
+    end
+    def skip_fact_type(f)
+      # REVISIT: There might be constraints we have to merge into the nested entity or subtype.
+      # These will come up as un-handled constraints:
+      pcs = @presence_constraints_by_fact[f]
+      TypeInheritance === f ||
+        (pcs && pcs.size > 0 && !pcs.detect{|c| !@constraints_used[c] })
+    end
+    # Dump one fact type.
+    # Include as many as possible internal constraints in the fact type readings.
+    def fact_type_dump_with_dependents(fact_type)
+      @fact_types_dumped[fact_type] = true
+      # debug "Trying to dump FT again" if @fact_types_dumped[fact_type]
+      return if skip_fact_type(fact_type)
+      if (et = fact_type.entity_type) &&
+          (pi = et.preferred_identifier) &&
+          pi.role_sequence.all_role_ref[0].role.fact_type != fact_type
+        # debug "Dumping objectified FT #{et.name} as an entity, non-fact PI"
+        entity_type_dump(et)
+        released_fact_types_dump(et)
+        return
+      end
+      fact_constraints = @presence_constraints_by_fact[fact_type]
+      # debug "for fact type #{fact_type.to_s}, considering\n\t#{fact_constraints.map(&:to_s)*",\n\t"}"
+      # debug "#{fact_type.name} has readings:\n\t#{fact_type.readings.map(&:name)*"\n\t"}"
+      # debug "Dumping #{fact_type.fact_type_id} as a fact type"
+      # Fact types that aren't nested have no names
+      name = fact_type.entity_type && fact_type.entity_type.name
+      fact_type_dump(fact_type, name)
+      # REVISIT: Go through the residual constraints and re-process appropriate readings to show them
+      @fact_types_dumped[fact_type] = true
+      @concept_types_dumped[fact_type.entity_type] = true if fact_type.entity_type
+    end
+    # Arrange for objectified fact types to appear in order of name, after other fact types.
+    # Facts are ordered alphabetically by the names of their role players,
+    # then by preferred_reading (subtyping fact types have no preferred_reading).
+    def fact_type_key(fact_type)
+      role_names =
+        if (pr = fact_type.preferred_reading)
+          pr.role_sequence.
+            all_role_ref.
+            sort_by{|role_ref| role_ref.ordinal}.
+            map{|role_ref| [ role_ref.leading_adjective, role_ref.role.concept.name, role_ref.trailing_adjective ].compact*"-" } +
+            [pr.reading_text]
+        else
+          fact_type.all_role.map{|role| role.concept.name }
+        end
+      (fact_type.entity_type ? [fact_type.entity_type.name] : [""]) + role_names
+    end
+    def role_ref_key(role_ref)
+      [ role_ref.leading_adjective, role_ref.role.concept.name, role_ref.trailing_adjective ].compact*"-"
+    end
+    # Dump fact types.
+    def fact_types_dump
+      # REVISIT: Uniqueness on the LHS of a binary can be coded using "distinct"
+      # The only fact types that can be remaining are those involving only value types,
+      # since we dumped every fact type as soon as all relevant entities were dumped.
+      # Iterate over all fact types of all value types, looking for these strays.
+      done_banner = false
+      fact_collection = @vocabulary.constellation.FactType
+      fact_collection.keys.select{|fact_id|
+              fact_type = fact_collection[fact_id]
+              !(TypeInheritance === fact_type) and
+              !@fact_types_dumped[fact_type] and
+              !skip_fact_type(fact_type) and
+              !fact_type.all_role.detect{|r| EntityType === r.concept }
+          }.sort_by{|fact_id|
+              fact_type = fact_collection[fact_id]
+              fact_type_key(fact_type)
+          }.each{|fact_id|
+              fact_type = fact_collection[fact_id]
+              fact_type_banner unless done_banner
+              done_banner = true
+              fact_type_dump_with_dependents(fact_type)
+        }
+      # REVISIT: Find out why some fact types are missed during entity dumping:
+      @vocabulary.constellation.FactType.values.select{|fact_type|
+          !(TypeInheritance === fact_type)
+        }.sort_by{|fact_type|
+          fact_type_key(fact_type)
+        }.each{|fact_type|
+          next if @fact_types_dumped[fact_type]
+          # debug "Not dumped #{fact_type.verbalise}(#{fact_type.all_role.map{|r| r.concept.name}*", "})"
+          fact_type_banner unless done_banner
+          done_banner = true
+          fact_type_dump_with_dependents(fact_type)
+        }
+      fact_type_end if done_banner
+      # unused = constraints - @constraints_used.keys
+      # debug "residual constraints are\n\t#{unused.map(&:to_s)*",\n\t"}"
+      @constraints_used
+    end
+    def fact_instances_dump
+      @vocabulary.fact_types.each{|f|
+          # Dump the instances:
+          f.facts.each{|i|
+            raise "REVISIT: Not dumping fact instances"
+            debug "\t\t"+i.to_s
+          }
+      }
+    end
+    def constraint_sort_key(c)
+      case c
+      when RingConstraint
+        [1, c.ring_type, c.role.concept.name, c.other_role.concept.name, c.name||""]
+      when SetComparisonConstraint
+        [2, c.all_set_comparison_roles.map{|scrs| scrs.role_sequence.all_role_ref.map{|rr| role_ref_key(rr)}}, c.name||""]
+      when SubsetConstraint
+        [3, [c.superset_role_sequence, c.subset_role_sequence].map{|rs| rs.all_role_ref.map{|rr| role_ref_key(rr)}}, c.name||""]
+      when PresenceConstraint
+        [4, c.role_sequence.all_role_ref.map{|rr| role_ref_key(rr)}, c.name||""]
+      end
+    end
+    def constraints_dump(except = {})
+      heading = false
+      @vocabulary.all_constraint.reject{|c| except[c]}.sort_by{ |c| constraint_sort_key(c) }.each do|c|
+        # Skip some PresenceConstraints:
+        if PresenceConstraint === c
+          # Skip uniqueness constraints that cover all roles of a fact type, they're implicit
+          role_refs = c.role_sequence.all_role_ref
+          if role_refs.size == 0
+            constraint_banner unless heading
+            heading = true
+            puts "PresenceConstraint without roles!"
+            next
+          end
+          fact_type0 = role_refs[0].role.fact_type
+          next if c.max_frequency == 1 &&         # Uniqueness
+            role_refs.size == fact_type0.all_role.size &&     # Same number of roles
+            fact_type0.all_role.all?{|r| role_refs.map(&:role).include? r}    # All present
+          # Skip internal PresenceConstraints over TypeInheritances:
+          next if TypeInheritance === fact_type0 &&
+            !c.role_sequence.all_role_ref.detect{|rr| rr.role.fact_type != fact_type0 }
+        end
+        constraint_banner unless heading
+        heading = true
+        # Skip presence constraints on value types:
+        # next if ActiveFacts::PresenceConstraint === c &&
+        #     ActiveFacts::ValueType === c.concept
+        constraint_dump(c)
+      end
+      constraint_end if heading
+    end
+    def vocabulary_start(vocabulary)
+      debug "Should override vocabulary_start"
+    end
+    def vocabulary_end
+      debug "Should override vocabulary_end"
+    end
+    def value_type_banner
+      debug "Should override value_type_banner"
+    end
+    def value_type_end
+      debug "Should override value_type_end"
+    end
+    def value_type_dump(o)
+      debug "Should override value_type_dump"
+    end
+    def entity_type_banner
+      debug "Should override entity_type_banner"
+    end
+    def entity_type_group_end
+      debug "Should override entity_type_group_end"
+    end
+    def non_subtype_dump(o, pi)
+      debug "Should override non_subtype_dump"
+    end
+    def subtype_dump(o, supertypes, pi = nil)
+      debug "Should override subtype_dump"
+    end
+    def append_ring_to_reading(reading, ring)
+      debug "Should override append_ring_to_reading"
+    end
+    def fact_type_banner
+      debug "Should override fact_type_banner"
+    end
+    def fact_type_end
+      debug "Should override fact_type_end"
+    end
+    def fact_type_dump(fact_type, name)
+      debug "Should override fact_type_dump"
+    end
+    def constraint_banner
+      debug "Should override constraint_banner"
+    end
+    def constraint_end
+      debug "Should override constraint_end"
+    end
+    def constraint_dump(c)
+      debug "Should override constraint_dump"
+    end
+  end
+  def dump(vocabulary, out = $>)
+    OrderedDumper.new(vocabulary).dump(out)
+  end
+end