stupidedi 1.3.23 → 1.4.0

data/lib/stupidedi/interchanges/element_types/special_val.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+module Stupidedi
+  using Refinements
+
+  module Interchanges
+    module ElementTypes
+      AN        = Versions::Common::ElementTypes::AN
+      StringVal = Versions::Common::ElementTypes::StringVal
+
+      #
+      # The specifications declare ISA02 and ISA04 are required elements, but
+      # they only have "meaningful information" when ISA01 and ISA03 qualifiers
+      # aren't "00".
+      #
+      # Without specifications regarding what should be entered in these
+      # required elements, our best option is to defer to convention, which
+      # seems to be that these elements should have 10 spaces -- which means
+      # they're blank. So we can't really make these elements required! Even
+      # stupider, these are the only blank elements that should be written out
+      # space-padded to the min_length -- every other element should be
+      # collapsed to an empty string.
+      #
+      # So this "Special" class overrides to_x12 for empty values, but it
+      # otherwise looks and acts like a normal AN and StringVal
+      #
+      class SpecialAN < AN
+        def companion
+          SpecialVal
+        end
+      end
+
+      class SpecialVal < StringVal
+        class Empty < StringVal::Empty
+          # @return [String]
+          def to_x12
+            " " * definition.min_length
+          end
+        end
+
+        class NonEmpty < StringVal::NonEmpty
+          def too_short?
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stupidedi/parser.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+module Stupidedi
+  module Parser
+    autoload :ConstraintTable,      "stupidedi/parser/constraint_table"
+    autoload :Instruction,          "stupidedi/parser/instruction"
+    autoload :InstructionTable,     "stupidedi/parser/instruction_table"
+
+    autoload :BuilderDsl,           "stupidedi/parser/builder_dsl"
+    autoload :Generation,           "stupidedi/parser/generation"
+    autoload :Navigation,           "stupidedi/parser/navigation"
+    autoload :Tokenization,         "stupidedi/parser/tokenization"
+    autoload :StateMachine,         "stupidedi/parser/state_machine"
+    autoload :IdentifierStack,      "stupidedi/parser/identifier_stack"
+
+    autoload :AbstractState,        "stupidedi/parser/states/abstract_state"
+    autoload :FailureState,         "stupidedi/parser/states/failure_state"
+    autoload :FunctionalGroupState, "stupidedi/parser/states/functional_group_state"
+    autoload :InitialState,         "stupidedi/parser/states/initial_state"
+    autoload :InterchangeState,     "stupidedi/parser/states/interchange_state"
+    autoload :LoopState,            "stupidedi/parser/states/loop_state"
+    autoload :TableState,           "stupidedi/parser/states/table_state"
+    autoload :TransactionSetState,  "stupidedi/parser/states/transaction_set_state"
+    autoload :TransmissionState,    "stupidedi/parser/states/transmission_state"
+  end
+
+  class << Parser
+    # @return [StateMachine]
+    def build(*args)
+      Parser::StateMachine.build(*args)
+    end
+  end
+end

data/lib/stupidedi/parser/builder_dsl.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+module Stupidedi
+  using Refinements
+
+  module Parser
+    class BuilderDsl
+      include Inspect
+      include Tokenization
+
+      # @private
+      SEGMENT_ID = /^[A-Z][A-Z0-9]{1,2}$/
+
+      # @return [StateMachine]
+      attr_reader :machine
+
+      # @return [Boolean]
+      attr_writer :strict
+
+      # @return [DslReader]
+      attr_reader :reader
+
+      def_delegators :@machine, :pretty_print, :segment, :element, :zipper, :successors, :empty?, :first?, :last?, :deterministic?
+
+      def initialize(machine, strict = true)
+        @machine = machine
+        @strict  = strict
+        @reader  = DslReader.new(Reader::Separators.empty,
+                                 Reader::SegmentDict.empty)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        SEGMENT_ID =~ name.to_s || super
+      end
+
+      def strict?
+        @strict
+      end
+
+      # @return [BuilderDsl]
+      def segment!(name, position, *elements)
+        segment_tok     = mksegment_tok(@reader.segment_dict, name, elements, position)
+        machine, reader = @machine.insert(segment_tok, @strict, @reader)
+
+        if @strict
+          unless machine.deterministic?
+            matches = machine.active.map do |m|
+              segment_def = m.node.zipper.node.definition
+              "#{segment_def.id} #{segment_def.name}"
+            end.join(", ")
+
+            raise Exceptions::ParseError,
+              "non-deterministic machine state: #{matches}"
+          end
+
+          # Validate the new segment (recursively, including its children)
+          machine.active.each{|m| critique(m.node.zipper) }
+
+          # We want to detect when we've ended a syntax node (or more), like
+          # starting a new interchange will end all previously "open" syntax
+          # nodes. So we compare the state before adding `segment_tok` to the
+          # corresponding state after we've added `segment_tok`.
+
+          machine.prev.tap do |prev|
+            prev.active.zip(machine.active) do |p, q|
+              # If the new state `q` is a descendent of `p`, we know that `p`
+              # and all of its ancestors are unterminated. However, if `q` is
+              # not a descendent of `p`, but is a descendent of one of `p`s
+              # descendents, then `p` and perhaps some of its ancestors were
+              # terminated when the state transitioned to `q`.
+              qancestors = Set.new
+
+              # Operate on the syntax tree (instead of the state tree)
+              q = q.node.zipper
+              p = p.node.zipper
+
+              while q.respond_to?(:parent)
+                qancestors << q.parent
+                q = q.parent
+              end
+
+              while p.respond_to?(:parent)
+                break if qancestors.include?(p)
+
+                # Now that we're sure that this syntax node (loop, table, etc)
+                # is done being constructed, we can perform more validations.
+                critique(p)
+                p = p.parent
+              end
+            end
+          end
+        end
+
+        @machine = machine
+        @reader  = reader
+
+        self
+      end
+
+    private
+
+      def method_missing(name, *args)
+        if SEGMENT_ID =~ name.to_s
+          segment!(name, Reader::Position.caller(2), *args)
+        else
+          super
+        end
+      end
+
+      # The `zipper` argument should be a _completed_ syntax node, meaning all
+      # children have already been added. This is invariably true for segments,
+      # because the {StateMachine} does not accept smaller units of syntax.
+      def critique(zipper, recursive = false, position = false)
+        if zipper.node.simple? or zipper.node.component?
+          if zipper.node.invalid?
+            raise Exceptions::ParseError,
+              "invalid #{zipper.node.descriptor} at #{zipper.node.position.inspect}"
+          elsif zipper.node.blank?
+            if zipper.node.usage.required?
+              raise Exceptions::ParseError,
+                "required #{zipper.node.descriptor} is blank at #{zipper.node.position.inspect}"
+            end
+          elsif zipper.node.usage.forbidden?
+            raise Exceptions::ParseError,
+              "forbidden #{zipper.node.descriptor} is present at #{zipper.node.position.inspect}"
+          elsif not zipper.node.allowed?
+            raise Exceptions::ParseError,
+              "value #{zipper.node.to_s} is not allowed in #{zipper.node.descriptor} at #{zipper.node.position.inspect}"
+          elsif zipper.node.too_long?
+            raise Exceptions::ParseError,
+              "value is too long in #{zipper.node.descriptor} at #{zipper.node.position.inspect}"
+          elsif zipper.node.too_short?
+            raise Exceptions::ParseError,
+              "value is too short in #{zipper.node.descriptor} at #{zipper.node.position.inspect}"
+          end
+
+        elsif zipper.node.composite?
+          if zipper.node.blank?
+            if zipper.node.usage.required?
+              raise Exceptions::ParseError,
+                "required element #{zipper.node.descriptor} is blank at #{zipper.node.position.inspect}"
+            end
+          elsif zipper.node.usage.forbidden?
+            raise Exceptions::ParseError,
+              "forbidden #{zipper.node.descriptor} is present at #{zipper.node.position.inspect}"
+          else
+            if zipper.node.present?
+              zipper.children.each_with_index do |z, i|
+                critique(z)
+              end
+
+              d = zipper.node.definition
+              d.syntax_notes.each do |s|
+                unless s.satisfied?(zipper)
+                  raise Exceptions::ParseError,
+                    "for #{zipper.node.descriptor}, #{s.reason(zipper)} at #{zipper.node.position.inspect}"
+                end
+              end
+            end
+          end
+
+        elsif zipper.node.repeated?
+          unless zipper.node.usage.repeat_count.include?(zipper.node.children.length)
+            raise Exceptions::ParseError,
+              "repeating #{zipper.node.descriptor} occurs too many times at #{zipper.node.position.inspect}"
+          end
+
+          zipper.children.each{|z| critique(z) }
+
+        elsif zipper.node.segment?
+          if zipper.node.invalid?
+            if zipper.up.node.invalid?
+              # parent is an InvalidEnvelopeVal
+              raise Exceptions::ParseError,
+                "#{zipper.first.node.reason} at #{zipper.first.node.position.inspect}"
+            else
+              raise Exceptions::ParseError,
+                "#{zipper.node.descriptor} at #{zipper.node.position.inspect}"
+            end
+          else
+            zipper.children.each_with_index do |z, i|
+              critique(z)
+            end
+
+            d = zipper.node.definition
+            d.syntax_notes.each do |s|
+              raise Exceptions::ParseError,
+                "for #{zipper.node.descriptor}, #{s.reason(zipper)} at #{zipper.node.position.inspect}" \
+                unless s.satisfied?(zipper)
+            end
+          end
+
+        elsif zipper.node.loop?
+          critique_occurences zipper, recursive
+
+        elsif zipper.node.table?
+          critique_occurences zipper, recursive
+
+        elsif zipper.node.transaction_set?
+          critique_occurences zipper, recursive
+
+        elsif zipper.node.functional_group?
+          critique_occurences zipper, recursive
+
+        elsif zipper.node.interchange?
+          critique_occurences zipper, recursive
+
+        elsif zipper.node.transmission?
+          if recursive
+            zipper.children.each_with_index do |z, i|
+              critique(z, recursive)
+            end
+          end
+        end
+      end
+
+      def critique_occurences(zipper, recursive)
+        occurences = Hash.new{|h,k| h[k] = 0 }
+
+        zipper.children.each do |child|
+          if child.node.respond_to?(:usage)
+            occurences[child.node.usage] += 1
+          elsif child.node.invalid?
+            raise Exceptions::ParseError,
+              "#{child.node.descriptor} at #{child.node.position.inspect}"
+          else
+            occurences[child.node.definition] += 1
+          end
+
+          if recursive
+            critique(child, "", recursive)
+          end
+        end
+
+        zipper.node.definition.children.each do |child|
+          bound = child.repeat_count
+          count = occurences.at(child)
+
+          if count.zero? and child.required?
+            raise Exceptions::ParseError,
+              "required #{child.descriptor} is missing from #{zipper.node.descriptor} at #{zipper.node.position.inspect}"
+          elsif bound < count
+            raise Exceptions::ParseError,
+              "#{child.descriptor} occurs too many times in #{zipper.node.descriptor} at #{zipper.node.position.inspect}"
+          end
+        end
+      end
+
+      # @endgroup
+      #########################################################################
+    end
+
+    class << BuilderDsl
+      # @group Constructors
+      #########################################################################
+
+      # @return [BuilderDsl]
+      def build(config, strict = true)
+        new(StateMachine.build(config), strict)
+      end
+
+      # @endgroup
+      #########################################################################
+    end
+
+    # @private
+    class DslReader
+      # @return [Reader::Separators]
+      attr_reader :separators
+
+      # @return [Reader::SegmentDict]
+      attr_reader :segment_dict
+
+      def initialize(separators, segment_dict)
+        @separators, @segment_dict = separators, segment_dict
+      end
+
+      # @return [DslReader]
+      def copy(changes = {})
+        @separators   = changes.fetch(:separators, @separators)
+        @segment_dict = changes.fetch(:segment_dict, @segment_dict)
+        self
+      end
+
+      def stream?
+        false
+      end
+    end
+  end
+end

data/lib/stupidedi/parser/constraint_table.rb

@@ -0,0 +1,488 @@
+# frozen_string_literal: true
+module Stupidedi
+  using Refinements
+
+  module Parser
+    # The {ConstraintTable} is a data structure that contains one or more
+    # {Instruction} values for the same segment identifier. Each concrete
+    # subclass implements different strategies for narrowing down the
+    # {Instruction} list.
+    #
+    # Reducing the number of valid {Instruction} values is important because
+    # executing more than one {Instruction} creates a non-deterministic state --
+    # more than one valid parse tree exists -- which slows the parser. Most
+    # often there is only one valid {Instruction} but the parser cannot
+    # (efficiently or at all) narrow the tree down without evaluating the
+    # constraints declared by each {Instruction}'s {Schema::SegmentUse}, which
+    # is done here.
+    #
+    class ConstraintTable
+      # @return [Array<Instruction>]
+      abstract :matches, :args => %w(segment_tok strict mode)
+
+      # @return [Array<Instruction>]
+      attr_reader :instructions
+
+      def copy(changes = {})
+        self.class.new \
+          changes.fetch(:instructions, instructions)
+      end
+
+      # @return [void]
+      # :nocov:
+      def pretty_print(q)
+        name = self.class.name.split("::").last
+        q.text "#{name}.build"
+        q.group(2, "([", "])") do
+          q.breakable
+          instructions.each do |op|
+            unless q.current_group.first?
+              q.text ","
+              q.breakable
+            end
+            q.pp op
+          end
+        end
+      end
+      # :nocov:
+
+      # @todo
+      def critique(segment_tok, segment_uses)
+      end
+
+      # Performs no filtering of the {Instruction} list. This is used when there
+      # already is a single {Instruction} or when a {Reader::SegmentTok} doesn't
+      # provide any more information to filter the list.
+      #
+      class Stub < ConstraintTable
+        def initialize(instructions)
+          @instructions = instructions
+        end
+
+        # @return [Array<Instruction>]
+        def matches(segment_tok, strict, mode)
+          @instructions.tap do |xs|
+            critique(segment_tok, xs.map(&:segment_use)) if strict
+          end
+        end
+      end
+
+      # Chooses the {Instruction} that pops the fewest number of states. For
+      # example, in the X222 837P an HL segment signals the start of a new
+      # 2000 loop, but may or may not begin a new Table 2 -- the specifications
+      # aren't actually clear. This rule will not create a new Table 2, but
+      # just add a new 2000 loop under the current one.
+      #
+      class Shallowest < ConstraintTable
+        def initialize(instructions)
+          @instructions = instructions
+        end
+
+        # @return [Array<Instruction>]
+        def matches(segment_tok, strict, mode)
+          @__matches ||= begin
+            shallowest = @instructions.map(&:pop_count).min
+            @instructions.select{|i| i.pop_count == shallowest }.tap do |xs|
+              critique(segment_tok, xs.map(&:segment_use)) if strict
+            end
+          end
+        end
+      end
+
+      # Chooses the {Instruction} that pops the greatest number of states.
+      #
+      class Deepest < ConstraintTable
+      #   def initialize(instructions)
+      #     @instructions = instructions
+      #   end
+
+      #   # @return [Array<Instruction>]
+      #   def matches(segment_tok, strict, mode)
+      #     @__matches ||= begin
+      #       deepest = @instructions.map(&:pop_count).max
+      #       @instructions.select{|i| i.pop_count == deepest }.tap do |xs|
+      #         critique(segment_tok, xs.map(&:segment_use)) if strict
+      #       end
+      #     end
+      #   end
+      end
+
+      # Chooses the subset of {Instruction} values based on the distinguishing
+      # values allowed by each {Schema::SegmentUse}. For instance, there are
+      # often several loops that begin with `NM1`, which are distinguished by
+      # the qualifier in element `NM101`.
+      #
+      class ValueBased < ConstraintTable
+        def initialize(instructions)
+          @instructions = instructions
+          @__basis      = {}
+        end
+
+        # @return [Array<Instruction>]
+        def matches(segment_tok, strict, mode)
+          invalid = true  # Were all present possibly distinguishing elements invalid?
+          present = false # Were any possibly distinguishing elements present?
+
+          disjoint, distinct = basis(@instructions, mode)
+
+          # First check single elements that can narrow the search space to
+          # a single matching Instruction.
+          disjoint.each do |(n, m), map|
+            value = deconstruct(segment_tok.element_toks, n, m)
+
+            case value
+            when nil, :not_used, :default
+              # value wasn't present in segment_tok, can't use it to decide
+            else
+              singleton = map.at(value)
+              present   = true
+
+              unless singleton.nil?
+                # Success, search is terminated
+                return singleton
+              else
+                if strict
+                  designator = "#{segment_tok.id}#{"%02d" % (n + 1)}"
+                  designator = designator + "-%02d" % (m + 1) unless m.nil?
+
+                  raise ArgumentError,
+                    "value #{value.to_s} is not allowed in element #{designator}"
+                end
+              end
+            end
+          end
+
+          # If we reach this line, none of the present elements could, on its
+          # own, narrow the search space to a single Instruction. We now test
+          # the combination of elements to iteratively narrow the search space
+          space = @instructions
+
+          # @todo: These filters could be ordered by probable effectiveness,
+          # so we narrow the search space by the largest amount in the fewest
+          # number of steps.
+          distinct.each do |(n, m), map|
+            value = deconstruct(segment_tok.element_toks, n, m)
+
+            unless value.nil?
+              # Lookup which instructions are compatible with this input
+              subset  = map.at(value)
+              present = true
+
+              unless subset.blank?
+                invalid = false
+                space  &= subset
+
+                if space.length <= 1
+                  # Success, search is terminated
+                  return space
+                end
+              else
+                # This value isn't compatible with any instruction
+                if strict
+                  designator = "#{segment_tok.id}#{"%02d" % (n + 1)}"
+                  designator = designator + "-%02d" % (m + 1) unless m.nil?
+
+                  raise ArgumentError,
+                    "value #{value.to_s} is not allowed in element #{designator}"
+                end
+              end
+            end
+          end
+
+          if invalid and present
+            # Some elements were present, but all contained invalid values, and
+            # even ignoring those we could not narrow the matches to a single
+            # instruction.
+            #
+            # We could return the remaining search space, but it is safest to
+            # mark this as an invalid segment and avoid the non-determinism
+            []
+          else
+            # Some elements were present and none were invalid, but it was not
+            # possible to narrow the set of matches to a single instruction.
+            #
+            # It seems wrong to mark the segment invalid. The worst thing you
+            # could say about the input is that it may have been missing a
+            # required element that could have resolved the ambiguity; but it's
+            # also possible all required elements were present and the grammar
+            # is the problem (not the input). So here we return the remaining
+            # search space, which will cause non-determinism in the parser.
+            space
+          end
+        end
+
+        # Resolve conflicts between instructions that have identical SegmentUse
+        # values. For each SegmentUse, this chooses the Instruction that pops
+        # the fewest number of states.
+        #
+        # @return [Array<Instruction>]
+        def shallowest(instructions)
+          grouped = instructions.group_by{|i| i.segment_use.object_id }
+          grouped.flat_map do |k, is|
+            shallowest = is.map(&:pop_count).min
+            is.select{|i| i.pop_count == shallowest }
+          end
+        end
+
+        # @return [Array(Array<(Integer, Integer, Map)>, Array<(Integer, Integer, Map)>)]
+        def basis(instructions, mode)
+          @__basis[mode] ||= begin
+            # When inserting segments, given a choice between two otherwise
+            # equivalent instructions, prefer the one with smallest `pop_count`.
+            # For example, when inserting an HL*20 in X221 835, the new 2000A
+            # loop could potentially go in the current "Table 2 - Billing
+            # Provider Detail" (smaller pop_count), or the parser could create
+            # a whole new table (larger pop_count).
+            #
+            # When searching for segments in a parse tree (mode == :read), we
+            # need to try both choices. That's because this "Table 2 - Billing
+            # Provider Detail" could be followed by a different "Table 2 -
+            # Subscriber Detail", which is then followed by another "Table 2 -
+            # Billing Provider Detail". Then the next HL*20 would belong to the
+            # uncle table, not the current table.
+            if mode == :insert
+              instructions = shallowest(instructions)
+            end
+
+            disjoint_elements = []
+            distinct_elements = []
+
+            # The first SegmentUse is used to represent the structure that must
+            # be shared by the others: number of elements and type of elements
+            element_uses = instructions.head.segment_use.definition.element_uses
+
+            # Iterate over each element across all SegmentUses (think columns)
+            #   NM1*[IL]*[  ]*..*..*..*..*..*[  ]*..*..*{..}*..
+            #   NM1*[40]*[  ]*..*..*..*..*..*[  ]*..*..*{..}*..
+            element_uses.length.times do |n|
+              if element_uses.at(n).composite?
+                ms = 0 .. element_uses.at(n).definition.component_uses.length - 1
+              else
+                ms = [nil]
+              end
+
+              # If this is a composite element, we iterate over each component.
+              # Otherwise this loop iterates once with the index {m} set to nil.
+              ms.each do |m|
+                last  = nil        # the last subset we examined
+                total = Sets.empty # the union of all examined subsets
+
+                distinct = false
+                disjoint = true
+
+                instructions.each do |i|
+                  element_use = i.segment_use.definition.element_uses.at(n)
+
+                  unless m.nil?
+                    element_use = element_use.definition.component_uses.at(m)
+                  end
+
+                  allowed_vals = element_use.allowed_values
+
+                  # We want to know if every instruction's set of allowed values
+                  # is disjoint (with one another). Instead of comparing each set
+                  # with every other set, which takes (N-1)! comparisons, we can
+                  # do it in N steps.
+                  disjoint &&= allowed_vals.disjoint?(total)
+
+                  # We also want to know if one instruction's set of allowed vals
+                  # contains elements that aren't present in at least one other
+                  # set. The opposite condition is easy to test: all sets contain
+                  # the same elements (are equal). So we can similarly, check this
+                  # condition in N steps rather than (N-1)!
+                  distinct ||= allowed_vals != last unless last.nil?
+
+                  total = allowed_vals.union(total)
+                  last  = allowed_vals
+                end
+
+              # puts "#{n}.#{m}: disjoint(#{disjoint}) distinct(#{distinct})"
+
+                if disjoint
+                  # Since each instruction's set of allowed values is disjoint, we
+                  # can build a function/hash that returns the single instruction,
+                  # given one of the values. When given a value outside the set of
+                  # all (combined) values, it returns nil.
+                  disjoint_elements << [[n, m], build_disjoint(total, n, m, instructions)]
+                elsif distinct
+                  # Not all instructions have the same set of allowed values. So
+                  # we can build a function/hash that accepts one of the values
+                  # and returns the subset of the instructions where that value
+                  # can occur. This might be some, none, or all of the original
+                  # instructions, so clearly this provides less information than
+                  # if each allowed value set was disjoint.
+
+                  # Currently disabled (and untested) because it doesn't look like
+                  # any of the HIPAA schemas would use this -- so testing it would
+                  # be a pain.
+                  #
+                  distinct_elements << [[n, m], build_distinct(total, n, m, instructions)]
+                end
+              end
+            end
+
+            [disjoint_elements, distinct_elements]
+          end
+        end
+
+        # @return [Hash<String, Array<Instruction>>]
+        def build_disjoint(total, n, m, instructions)
+          if total.finite?
+            # The sum of all allowed value sets is finite, so we know that each
+            # individual allowed value set is finite (we can iterate over it).
+            map = Hash.new
+
+            instructions.each do |i|
+              element_use = i.segment_use.definition.element_uses.at(n)
+
+              unless m.nil?
+                element_use = element_use.definition.component_uses.at(m)
+              end
+
+              allowed_vals = element_use.allowed_values
+              allowed_vals.each{|v| map[v] = i.cons }
+            end
+
+            map
+          else
+            # At least one of allowed value sets is infinite. This happens when
+            # it is RelativeComplement, which declares the values that are *not*
+            # allowed in the set.
+            map = Hash.new{|h,k| h[k] = instructions }
+
+            instructions.each do |i|
+              element_use = i.segment_use.definition.element_uses.at(n)
+              unless m.nil?
+                element_use = element_use.definition.component_uses.at(m)
+              end
+
+              allowed_vals = element_use.allowed_values
+
+              unless allowed_vals.finite?
+                allowed_vals.complement.each{|v| map[v] -= i }
+              end
+            end
+
+            # Clear the default_proc so accesses don't change the Hash
+            map.default = instructions
+            map
+          end
+        end
+
+        # @return [Hash<String, Array<Instruction>>]
+        def build_distinct(total, n, m, instructions)
+          if total.finite?
+            # The sum of all allowed value sets is finite, so we know that each
+            # individual allowed value set is finite (we can iterate over it).
+            map = Hash.new{|h,k| h[k] = [] }
+
+            instructions.each do |i|
+              element_use  = i.segment_use.definition.element_uses.at(n)
+
+              unless m.nil?
+                element_use = element_use.definition.component_uses.at(m)
+              end
+
+              allowed_vals = element_use.allowed_values
+              allowed_vals.each{|v| map[v] << i }
+            end
+
+            # Clear the default_proc so accesses don't change the Hash
+            map.default = []
+            map
+          else
+            # At least one of allowed value sets is infinite. This happens when
+            # it is RelativeComplement, which declares the values that are *not*
+            # allowed in the set.
+            map = Hash.new{|h,k| h[k] = instructions }
+
+            instructions.each do |i|
+              element_use  = i.segment_use.definition.element_uses.at(n)
+
+              unless m.nil?
+                element_use = element_use.definition.component_uses.at(m)
+              end
+
+              allowed_vals = element_use.allowed_values
+
+              unless allowed_vals.finite?
+                allowed_vals.complement.each{|v| map[v] -= i }
+              end
+            end
+
+            # Clear the default_proc so accesses don't change the Hash
+            map.default = instructions
+            map
+          end
+        end
+
+        # Return the value of the `m`-th elemnt, or if `n` is not nil, return
+        # the value of the `n`-th component from the `n`-th element. When the
+        # value is blank, the function returns `nil`.
+        #
+        # @param [Array<Reader::SimpleElementTok, Reader::CompositeElementTok>] element_toks
+        # @param [Integer] m
+        # @param [Integer, nil] n
+        #
+        # @return [String, nil]
+        def deconstruct(element_toks, m, n)
+          element_tok = element_toks.at(m)
+          element_tok = element_tok.element_toks.at(0) if element_tok.try(:repeated?)
+
+          if element_tok.blank?
+            nil
+          elsif n.nil?
+            element_tok.value
+          else
+            element_tok = element_tok.component_toks.at(n)
+
+            if element_tok.blank?
+              nil
+            else
+              element_tok.value
+            end
+          end
+        end
+      end
+    end
+
+    class << ConstraintTable
+      # @group Constructors
+      #########################################################################
+
+      # Given a list of {Instruction} values for the same segment identifier,
+      # this method constructs the appropriate concrete subclass of
+      # {ConstraintTable}.
+      #
+      # @param [Array<Instruction>] instructions
+      # @return [ConstraintTable]
+      def build(instructions)
+        if instructions.length <= 1
+          ConstraintTable::Stub.new(instructions)
+        elsif instructions.any?{|i| i.segment_use.nil? } and
+          not instructions.all?{|i| i.segment_use.nil? }
+          # When one of the instructions has a nil segment_use, it means
+          # the SegmentUse is determined when pushing the new state. There
+          # isn't a way to know the segment constraints from here.
+          ConstraintTable::Stub.new(instructions)
+        else
+          segment_uses = instructions.map{|i| i.segment_use }
+
+          if segment_uses.map{|u| u.object_id }.uniq.length <= 1
+            # The same SegmentUse may appear more than once, because the
+            # segment can be placed at different levels in the tree. If
+            # all the instructions have the same SegmentUse, they also have
+            # the same element constraints so we can't use them to narrow
+            # down the instruction list.
+            ConstraintTable::Shallowest.new(instructions)
+          else
+            ConstraintTable::ValueBased.new(instructions)
+          end
+        end
+      end
+
+      # @endgroup
+      #########################################################################
+    end
+  end
+end