birman 0.2.1 → 0.3.0

data/lib/birman/matchers.rb

@@ -1,6 +1,16 @@
 # frozen_string_literal: true
 
+# [file]
+# purpose = "The matcher types and the methods every matcher responds to"
+# responsibility = "Matching at a byte position against a Context; building ASTs for EBNF"
+# dependencies = ["Birman::Context", "StringScanner (via Context#scanner)"]
+# pattern = "Immutable Data objects composed into a tree; packrat memoization at rule refs"
+# public_api = "Birman::Matcher (operators and modifiers below); the Data classes are internal"
 module Birman
+  # [method."Birman.coerce"]
+  # params = ["x: String | Regexp | Matcher"]
+  # returns = "Matcher: String -> literal (Lit), Regexp -> raw pattern (Pat), matcher unchanged"
+  # raises = ["ArgumentError (only(...) outside seq, or anything else)"]
   def self.coerce(x)
     case x
     when Matcher then x
@@ -22,41 +32,128 @@ module Birman
   #
   # So `a > b >> c` means `a > (b >> c)`, and a commit inside a choice
   # needs parentheses: `(keyword("if") > body) | other`.
+  # [module.Matcher]
+  # purpose = "Operators and modifiers shared by every matcher"
+  # notes = "Arguments go through Birman.coerce, so bare strings are literals"
   module Matcher
-    def >>(other) = Seq.new([self, Birman.coerce(other)])
-    def |(other)  = Choice.new([self, Birman.coerce(other)])
+    # [method.">>"]
+    # params = ["other: String | Regexp | Matcher"]
+    # returns = "Sequence of self then other: a chain of >> is one seq"
+    # notes = "A seq from seq(...), or with a commit or only, is one part, as in seq(self, other)"
+    def >>(other) = Seq.new(parts: [*inline_parts(self), *inline_parts(Birman.coerce(other))], open: true)
+
+    # [method."|"]
+    # params = ["other: String | Regexp | Matcher"]
+    # returns = "Ordered choice: self, else other"
+    def |(other) = Choice.new([self, Birman.coerce(other)])
 
     # Conjunction: self must match here (without consuming input),
     # then other is matched from the same spot. Value is other's.
+    # [method."&"]
+    # params = ["other: String | Regexp | Matcher"]
+    # returns = "self as a guard (lookahead), then other from the same position"
+    # value = "other's value"
     def &(other) = Both.new(self, Birman.coerce(other))
 
     # Commit: once self matches, everything after it must match too, or
     # parsing stops right here with an error instead of backtracking.
     # This is dry-logic's implication operator, applied to parsing.
+    # [method.">"]
+    # params = ["other: String | Regexp | Matcher"]
+    # returns = "Sequence of self then other, committed after self (like seq(self, commit, other))"
     def >(other)
-      left  = uncommitted_parts(self)
-      right = uncommitted_parts(Birman.coerce(other))
+      left  = inline_parts(self)
+      right = inline_parts(Birman.coerce(other))
       Seq.new([*left, *right], left.size)
     end
 
+    # [method.rep]
+    # params = ["min: Integer = 0", "max: Integer | nil = nil (unbounded)"]
+    # returns = "Matcher for self repeated min..max times"
+    # value = "Array of values; an empty first match counts once, then ends the loop"
     def rep(min = 0, max = nil) = Rep.new(self, min, max)
-    def maybe       = rep(0, 1).map(&:first)
-    def absent      = Not.new(self)
-    def present     = And.new(self)
-    def map(&fn)    = Action.new(self, fn)
+
+    # [method.maybe]
+    # returns = "Optional self"
+    # value = "self's value, or nil when absent"
+    def maybe = Maybe.new(self)
+
+    # [method.absent]
+    # returns = "Negative lookahead: succeeds, consuming nothing, when self doesn't match here"
+    # value = "nil"
+    def absent = Not.new(self)
+
+    # [method.present]
+    # returns = "Positive lookahead: succeeds, consuming nothing, when self matches here"
+    # value = "nil"
+    def present = And.new(self)
+
+    # Prefer a Symbol to a block: a Symbol is data a compiler can read,
+    # while a block's source is lost and it can capture local variables.
+    # [method.map]
+    # params = ["method_name: Symbol, called on self's value", "or fn: block taking self's value"]
+    # returns = "Matcher whose value is the method's (or block's) result (self's .as name is kept)"
+    # raises = ["ArgumentError (both a Symbol and a block, or neither)"]
+    def map(method_name = nil, &fn)
+      return Send.new(self, method_name) if method_name && !fn
+      return Map.new(self, fn) if fn && !method_name
+
+      raise ArgumentError, "map takes a method name or a block (one, not both)"
+    end
+
+    # Pass the value to a method of the grammar, for real work such as
+    # decoding escapes or parsing numbers. The method may be private,
+    # and subclasses can override it.
+    # [method.action]
+    # params = ["method_name: Symbol, a grammar instance method taking one argument"]
+    # returns = "Matcher whose value is grammar.method_name(self's value) (self's .as name is kept)"
+    def action(method_name) = Action.new(self, method_name)
+
+    # Reject a match the grammar can't accept for reasons a pattern
+    # can't express (1979-02-30 isn't a date). The method may be
+    # private, and, like an action, must depend only on the value: it
+    # runs inside lookaheads, and its result is memoized with the rule.
+    # A rejection is an ordinary failure where self began, so a choice
+    # backtracks past it (and a later alternative that gets further
+    # owns the error) unless an enclosing seq has committed.
+    # [method.check]
+    # params = ["method_name: Symbol, a grammar instance method taking one argument", "name: String"]
+    # returns = "self, failing as \"expected <name>\" when grammar.method_name(self's value) is falsy"
+    # value = "self's value (self's .as name is kept)"
+    def check(method_name, name) = Check.new(self, method_name, name)
+
+    # Replace the value with a constant: lit("null").means(nil). The
+    # same object comes back from every match.
+    # [method.means]
+    # params = ["value: any object"]
+    # returns = "Matcher whose value is always value (self's .as name is kept)"
+    def means(value) = Const.new(self, value)
+
+    # [method.label]
+    # params = ["name: String"]
+    # returns = "self, reported as \"expected <name>\" when it fails without consuming input"
     def label(name) = Label.new(self, name)
 
     # Never mention this matcher in error messages (for whitespace,
     # comments, and other things nobody wants to be told to type).
+    # [method.quiet]
+    # returns = "self, never mentioned in error messages"
     def quiet = Quiet.new(self)
 
     # Name this part of a sequence. A sequence with any named parts
     # produces a hash of just those parts instead of an array.
+    # [method.as]
+    # params = ["key: Symbol"]
+    # returns = "self, named: the enclosing seq's value becomes a Hash of named parts"
     def as(key) = Named.new(self, key)
 
     # Build a node from the value: a hash of named parts becomes
     # keyword arguments; anything else fills the node's first field.
     # Nodes made with Birman.node get a source span.
+    # [method.to]
+    # params = ["node: node class (or any Data class)"]
+    # returns = "Matcher whose value is node built from self's value"
+    # value = "node.new(**hash), or node.new(first_field => value); with a span for node(...) classes"
     def to(node) = To.new(self, node)
 
     # The name given by #as, seen through wrappers like labels.
@@ -64,7 +161,9 @@ module Birman
 
     private
 
-    def uncommitted_parts(m) = m.is_a?(Seq) && m.commit_at.nil? && m.only_at.nil? ? m.parts : [m]
+    # Only a seq built by >> joins the enclosing one, and only if that
+    # can't change what it means: a commit or only(...) would apply to the whole.
+    def inline_parts(m) = m.is_a?(Seq) && m.open? && m.commit_at.nil? && m.only_at.nil? ? m.parts : [m]
   end
 
   # A bare string: a literal (see Combinators#literal_matcher). What a
@@ -74,19 +173,24 @@ module Birman
     include Matcher
 
     def match(ctx, pos) = ctx.grammar.literal_matcher(text).match(ctx, pos)
-    def to_ast = [:str, text]
+    # Its spacing comes after the text, so it's a lexeme only when empty.
+    def to_ast = text.empty? ? [:lexeme, [:str, text]] : [:str, text]
   end
 
   # Exact string, nothing skipped (see Combinators#str).
   Str = Data.define(:str) do
     include Matcher
 
+    # The error text is worked out once, not on every failed attempt.
+    def initialize(str:)
+      @expected = str.inspect.freeze
+      super
+    end
+
     def match(ctx, pos)
-      if ctx.input.byteslice(pos, str.bytesize) == str
-        Match.new(pos + str.bytesize, str)
-      else
-        ctx.fail_at(pos, str.inspect)
-      end
+      scanner = ctx.scanner
+      scanner.pos = pos
+      scanner.match?(str) ? Match.new(pos + str.bytesize, str) : ctx.fail_at(pos, @expected)
     end
 
     def to_ast = [:str, str]
@@ -105,35 +209,66 @@ module Birman
       Match.new(pos + len, scanner.matched)
     end
 
+    # [method.captures]
+    # returns = "Matcher for the regexp whose value is a Hash of its named groups"
+    # value = "{name: text} for each named group, in order (Symbol keys); nil for a group that didn't match"
+    # raises = ["ArgumentError (no named groups, or a name used twice)"]
+    def captures = Captures.new(self)
+
     def to_ast = [:pat, source]
   end
 
+  # A regexp's named groups as a Hash (see Pat#captures). It does its
+  # own scan, so nothing can move the scanner before the groups are read.
+  Captures = Data.define(:pat) do
+    include Matcher
+
+    def initialize(pat:)
+      twice, = pat.re.named_captures.find { |_, groups| groups.size > 1 }
+      problem = pat.re.names.empty? ? "has no named groups" : twice && "names #{twice} more than once"
+      raise ArgumentError, "captures needs groups named once each, (?<name>...): #{pat.source} #{problem}" if problem
+
+      @names = pat.re.names.map(&:to_sym).freeze
+      super
+    end
+
+    def match(ctx, pos)
+      scanner = ctx.scanner
+      scanner.pos = pos
+      len = scanner.match?(pat.re) or return ctx.fail_at(pos, pat.source)
+      Match.new(pos + len, @names.each_with_index.to_h { |name, i| [name, scanner[i + 1]] })
+    end
+
+    def to_ast = pat.to_ast
+  end
+
   # Sequence: parts match in order. The value is an array, or a hash
   # of the named parts if any are named (see Matcher#as). Parts at
   # index `commit_at` and beyond are committed: if one fails, parsing stops.
+  # A name used twice, or a nested seq's names the value would drop, raise.
   Seq = Data.define(:parts, :commit_at, :only_at) do
     include Matcher
 
     # Arrays are copied and frozen so a matcher is immutable all the way down.
-    def initialize(parts:, commit_at: nil, only_at: nil)
-      if only_at && parts.each_with_index.any? { |part, i| i != only_at && part.capture_key }
-        raise ArgumentError, "a seq with only(...) can't also name parts with .as"
-      end
-
+    # `open` (built by >>, so a later >> extends it) isn't a member: it
+    # changes how the seq composes, not what it matches, so == ignores it.
+    def initialize(parts:, commit_at: nil, only_at: nil, open: false)
+      check_names(parts, only_at)
+      @open = open
       super(parts: parts.dup.freeze, commit_at:, only_at:)
     end
 
-    def >>(other) = with(parts: [*parts, Birman.coerce(other)])
+    def open? = @open
+
+    # Data#with rebuilds through initialize, which would close the copy.
+    def with(**changes) = changes.empty? ? self : Seq.new(open: open?, **to_h, **changes)
 
     def match(ctx, pos)
-      values = parts.each_with_index.map do |part, i|
-        r = part.match(ctx, pos)
-        unless r
-          fail_committed!(ctx, part, pos) if commit_at && i >= commit_at
-          return nil
-        end
+      values = Array.new(parts.size)
+      parts.each_with_index do |part, i|
+        r = part.match(ctx, pos) or return failed(ctx, part, pos, i)
+        values[i] = r.value
         pos = r.pos
-        r.value
       end
       Match.new(pos, shape(values))
     end
@@ -143,8 +278,51 @@ module Birman
     # With only(...), the kept part's name (if any) passes outward.
     def capture_key = only_at && parts[only_at].capture_key
 
+    # The names a part's value is a hash of, when the part has no name of
+    # its own to carry that hash: seen through wrappers that keep the
+    # value, but not into rep, sep_by or a transform, which reshape it.
+    def self.names_inside(part) # rubocop:disable Metrics
+      case part
+      when Seq then part.only_at ? names_inside(part.parts[part.only_at]) : part.parts.filter_map(&:capture_key)
+      when Pick then names_inside(part.parts[part.index])
+      when Label, Quiet, Lexeme, Check, Maybe then names_inside(part.inner)
+      when Both then names_inside(part.right)
+      when Choice then part.alts.flat_map { names_inside(_1) }.uniq
+      when Captures then part.pat.re.names.map(&:to_sym)
+      else []
+      end
+    end
+
     private
 
+    def check_names(parts, only_at)
+      keys = parts.filter_map(&:capture_key)
+      twice = keys.find { keys.count(_1) > 1 }
+      raise ArgumentError, "a seq can't name two parts #{twice.inspect}" if twice
+
+      if only_at
+        check_dropped(parts.reject.with_index { |_, i| i == only_at })
+      elsif keys.any?
+        check_dropped(parts.reject(&:capture_key))
+      end
+    end
+
+    # Parts the seq's value leaves out can't have names.
+    def check_dropped(dropped)
+      raise ArgumentError, "a seq with only(...) can't also name parts with .as" if dropped.any?(&:capture_key)
+
+      hidden = dropped.flat_map { Seq.names_inside(_1) }
+      return if hidden.empty?
+
+      raise ArgumentError, "a seq inside a seq would lose its names #{hidden.map(&:inspect).join(", ")}: " \
+                           "list its parts in the outer seq, or name it with .as"
+    end
+
+    def failed(ctx, part, pos, index)
+      fail_committed!(ctx, part, pos) if commit_at && index >= commit_at
+      nil
+    end
+
     # If the failed part recorded nothing at or past pos (it's quiet,
     # or a negative lookahead), describe the part itself so the error
     # still says what was expected.
@@ -185,19 +363,26 @@ module Birman
     def capture_key = parts[index].capture_key
   end
 
-  # One or more items separated by sep. The value is an array of the
-  # items, and the name (see Matcher#as) is the item's.
-  SepBy = Data.define(:item, :sep) do
+  # Items separated by sep: at least one, or with min 0 possibly none.
+  # The value is an array of the items (a new one each time, even when
+  # empty), and the name (see Matcher#as) is the item's. With trailing,
+  # a separator with no item after it ends the list and is kept in the
+  # match; the item's failure there is still recorded, so whatever
+  # comes next shares the error ("expected value or ]").
+  SepBy = Data.define(:item, :sep, :min, :trailing) do
     include Matcher
 
+    def initialize(item:, sep:, min: 1, trailing: false) = super
+
     def match(ctx, pos)
-      r = item.match(ctx, pos) or return nil
+      r = item.match(ctx, pos) or return (min.zero? ? Match.new(pos, []) : nil)
       values = [r.value]
       pos = r.pos
       loop do
         s = sep.match(ctx, pos) or break
-        r = item.match(ctx, s.pos) or break
-        break if r.pos == pos # an empty separator and item would loop forever
+        r = item.match(ctx, s.pos)
+        pos = s.pos if r.nil? && trailing
+        break if r.nil? || r.pos == pos # an empty separator and item would loop forever
 
         values << r.value
         pos = r.pos
@@ -205,7 +390,13 @@ module Birman
       Match.new(pos, values)
     end
 
-    def to_ast = [:seq, nil, [item.to_ast, [:rep, 0, nil, [:seq, nil, [sep.to_ast, item.to_ast]]]]]
+    def to_ast
+      parts = [item.to_ast, [:rep, 0, nil, [:seq, nil, [sep.to_ast, item.to_ast]]]]
+      parts << [:rep, 0, 1, sep.to_ast] if trailing
+      list = [:seq, nil, parts]
+      min.zero? ? [:rep, 0, 1, list] : list
+    end
+
     def capture_key = item.capture_key
   end
 
@@ -225,6 +416,9 @@ module Birman
     end
 
     def to_ast = [:choice, alts.map(&:to_ast)]
+
+    # A name every alternative has passes outward; differing names don't.
+    def capture_key = alts.map(&:capture_key).uniq.then { _1.size == 1 ? _1.first : nil }
   end
 
   # Repetition with min/max; value is an array.
@@ -259,7 +453,7 @@ module Birman
     include Matcher
 
     def match(ctx, pos)
-      r, = ctx.isolate(pos) { ctx.lookahead { inner.match(ctx, pos) } }
+      r = ctx.isolate(pos) { ctx.lookahead { inner.match(ctx, pos) } }
       r ? nil : Match.new(pos, nil)
     end
 
@@ -284,19 +478,57 @@ module Birman
     def to_ast = [:both, left.to_ast, right.to_ast]
   end
 
-  # Semantic action: transform the value of a successful match.
-  Action = Data.define(:inner, :fn) do
+  # Optional (see Matcher#maybe): inner's value, or nil. Never fails.
+  Maybe = Data.define(:inner) do
+    include Matcher
+
+    def match(ctx, pos) = inner.match(ctx, pos) || Match.new(pos, nil)
+    def to_ast = [:rep, 0, 1, inner.to_ast]
+    def capture_key = inner.capture_key
+  end
+
+  # A successful match whose value is replaced: the shared shape of
+  # Const, Map, Send and Action, each defining transform(value, ctx).
+  module Transform
     include Matcher
 
     def match(ctx, pos)
       r = inner.match(ctx, pos) or return nil
-      r.with(value: fn.call(r.value))
+      Match.new(r.pos, transform(r.value, ctx))
     end
 
     def to_ast = [:action, inner.to_ast]
     def capture_key = inner.capture_key
   end
 
+  # See Matcher#means.
+  Const = Data.define(:inner, :constant) do
+    include Transform
+
+    def transform(_value, _ctx) = constant
+  end
+
+  # Transform the value with a block (see Matcher#map).
+  Map = Data.define(:inner, :fn) do
+    include Transform
+
+    def transform(value, _ctx) = fn.call(value)
+  end
+
+  # Transform the value by calling one of its methods (see Matcher#map).
+  Send = Data.define(:inner, :method_name) do
+    include Transform
+
+    def transform(value, _ctx) = value.public_send(method_name)
+  end
+
+  # Semantic action: pass the value to a grammar method (see Matcher#action).
+  Action = Data.define(:inner, :method_name) do
+    include Transform
+
+    def transform(value, ctx) = ctx.grammar.__send__(method_name, value)
+  end
+
   # Names a matcher for error messages. If inner fails (or succeeds
   # while consuming nothing) without getting past its starting
   # position, the error says "expected <name>"
@@ -306,7 +538,9 @@ module Birman
     include Matcher
 
     def match(ctx, pos)
-      result, furthest, expected = ctx.isolate(pos) { inner.match(ctx, pos) }
+      result = ctx.isolate(pos) { inner.match(ctx, pos) }
+      furthest = ctx.isolated_furthest
+      expected = ctx.isolated_expected
       if furthest == pos && (result.nil? || (result.pos == pos && expected.any?))
         ctx.fail_at(pos, name)
       else
@@ -319,6 +553,24 @@ module Birman
     def capture_key = inner.capture_key
   end
 
+  # Semantic predicate (see Matcher#check). Like Label, inner runs
+  # isolated, so a rejection can drop what inner recorded (a rep's
+  # stopping point, say), as Not does, and report only its own name.
+  Check = Data.define(:inner, :method_name, :name) do
+    include Matcher
+
+    def match(ctx, pos)
+      result = ctx.isolate(pos) { inner.match(ctx, pos) }
+      return ctx.fail_at(pos, name) if result && !ctx.grammar.__send__(method_name, result.value)
+
+      ctx.merge(ctx.isolated_furthest, ctx.isolated_expected)
+      result
+    end
+
+    def to_ast = [:check, name, inner.to_ast]
+    def capture_key = inner.capture_key
+  end
+
   # See Matcher#as. Passes the value through; the enclosing Seq reads
   # the key.
   Named = Data.define(:inner, :key) do
@@ -335,32 +587,37 @@ module Birman
 
     def match(ctx, pos)
       r = inner.match(ctx, pos) or return nil
-      fields = r.value.is_a?(Hash) ? r.value : { node.members.first => r.value }
-      r.with(value: Birman.build(node, fields, ctx, pos, r.pos))
+      fields = if r.value.is_a?(Hash) then r.value
+               elsif node.members.empty? then {} # a node with no fields drops the value
+               else { node.members.first => r.value }
+               end
+      Match.new(r.pos, Birman.build(node, fields, ctx, pos, r.pos))
     end
 
     def to_ast = [:action, inner.to_ast]
     def capture_key = inner.capture_key
   end
 
-  # A token: inner, then the grammar's ignore rule (usually spacing),
-  # keeping inner's value. With no ignore rule it's just inner. `source`
-  # is how a literal shows up in EBNF ("let" rather than its internals).
-  Lexeme = Data.define(:inner, :ignore, :source) do
+  # A token: inner, then the ignore rule (usually spacing) of the
+  # grammar running it, keeping inner's value. With no ignore rule it's
+  # just inner. `source` is how a literal shows up in EBNF ("let"
+  # rather than its internals).
+  Lexeme = Data.define(:inner, :source) do
     include Matcher
 
-    def initialize(inner:, ignore:, source: nil) = super
+    def initialize(inner:, source: nil) = super
 
     def match(ctx, pos)
       r = inner.match(ctx, pos) or return nil
-      return r unless ignore
+      ignore = ctx.ignore_ref or return r
 
-      s = Ref.new(ignore).match(ctx, r.pos) or return r
+      s = ignore.match(ctx, r.pos) or return r
       ctx.ignored_after(r.pos, s.pos)
       Match.new(s.pos, r.value)
     end
 
-    def to_ast = source ? [:str, source] : inner.to_ast
+    # Shown as a lexeme unless it's a literal with text (see Lit#to_ast).
+    def to_ast = source.to_s.empty? ? [:lexeme, inner.to_ast] : [:str, source]
     def capture_key = inner.capture_key
   end
 
@@ -398,8 +655,7 @@ module Birman
     include Matcher
 
     def match(ctx, pos)
-      result, = ctx.isolate(pos) { inner.match(ctx, pos) }
-      result
+      ctx.isolate(pos) { inner.match(ctx, pos) }
     end
 
     def to_ast = [:quiet, inner.to_ast]
@@ -414,7 +670,8 @@ module Birman
 
     def match(ctx, pos)
       result, furthest, expected = ctx.memoize(name, pos) do
-        ctx.isolate(pos) { ctx.grammar.matcher_for(name).match(ctx, pos) }
+        r = ctx.isolate(pos) { ctx.grammar.matcher_for(name).match(ctx, pos) }
+        [r, ctx.isolated_furthest, ctx.isolated_expected]
       end
       ctx.merge(furthest, expected)
       result

data/lib/birman/nodes.rb

@@ -1,8 +1,16 @@
 # frozen_string_literal: true
 
+# [file]
+# purpose = "AST nodes with source spans"
+# responsibility = "node(...) classes, Span, and building nodes during a parse"
+# pattern = "Data classes plus a mixin"
 module Birman
   # Where a node came from in the source. Stored as byte offsets (see
   # Context); from, to, line and column count characters.
+  # [class.Span]
+  # purpose = "Where a node came from in the input"
+  # fields = ["input: String", "byte_from, byte_to: Integer (byte offsets)"]
+  # methods = ["from, to: character offsets", "text", "line", "column", "to_s => \"line L, column C\""]
   Span = Data.define(:input, :byte_from, :byte_to) do
     def from   = Birman.char_offset(input, byte_from)
     def to     = Birman.char_offset(input, byte_to)
@@ -22,6 +30,9 @@ module Birman
   # not a Data member, so equality and pattern matching ignore it:
   # `in Num(value)` still works, and two nodes with the same contents
   # are equal wherever they came from.
+  # [module.Node]
+  # purpose = "Mixed into every node(...) class"
+  # adds = ["span (ignored by == and pattern matching)", "with(**changes) keeping the span", "s-expression inspect"]
   module Node
     attr_reader :span
 
@@ -61,7 +72,13 @@ module Birman
   #   end
   #
   # Also available as Birman.node.
+  # [module.Nodes]
+  # purpose = "Provides node(...); grammars get it automatically, other modules can extend it"
   module Nodes
+    # [method.node]
+    # params = ["*members: Symbol (field names; not :span)", "body: optional block of methods (may define initialize)"]
+    # returns = "A Data class including Birman::Node"
+    # raises = ["ArgumentError if a field is named span"]
     def node(*members, &body)
       raise ArgumentError, "a node can't have a field named span: every node already has one" if members.include?(:span)
 

data/lib/birman/result.rb

@@ -1,10 +1,27 @@
 # frozen_string_literal: true
 
+# [file]
+# purpose = "What a parse returns"
+# responsibility = "Success and Failure values, and the ParseError that parse! raises"
+# pattern = "Result objects (Data), pattern-matchable"
 module Birman
-  # Internal: one matcher succeeded, ending at `pos` with `value`.
-  Match = Data.define(:pos, :value)
+  # Internal: one matcher succeeded, ending at `pos` with `value`. A
+  # plain class rather than Data: one is made for every successful
+  # match, and Data.new allocates a keyword Hash each time.
+  class Match
+    attr_reader :pos, :value
+
+    def initialize(pos, value)
+      @pos = pos
+      @value = value
+    end
+  end
 
   # Returned by Grammar#parse when the whole input parsed.
+  # [class.Success]
+  # purpose = "The whole input parsed"
+  # fields = ["value: whatever the root rule produced"]
+  # usage = "case grammar.parse(input) in Birman::Success(value) then ..."
   Success = Data.define(:value) do
     def success? = true
     def failure? = false
@@ -19,7 +36,26 @@ module Birman
   #
   # reason: set when the failure isn't about what was expected, such as
   # input nested too deeply for Ruby's stack.
+  #
+  # Failure.at(span, reason) is one for a check made after parsing, on
+  # the AST: it points at a node's span, committed, with no expected
+  # list, so the message reads "line L, column C: reason".
+  # [class.Failure]
+  # purpose = "The input didn't parse"
+  # fields = [
+  # "input: String",
+  # "pos: Integer (character offset of the furthest failure)",
+  # "expected: Array of String (what would have matched there)",
+  # "committed: Boolean (failed after a commit)",
+  # "reason: String | nil (set when it isn't about expectations, e.g. nesting too deep)"
+  # ]
+  # methods = [
+  # "Failure.at(span, reason) -> Failure at span's start (for checks after parsing)",
+  # "line", "column", "found", "message(formatter)", "value!(formatter) -> raises ParseError"
+  # ]
   Failure = Data.define(:input, :pos, :expected, :committed, :reason) do
+    def self.at(span, reason) = new(input: span.input, pos: span.from, expected: [], committed: true, reason:)
+
     def initialize(input:, pos:, expected:, committed:, reason: nil) = super
 
     def success? = false
@@ -42,6 +78,9 @@ module Birman
   end
 
   # Raised by parse! (and Failure#value!) with the formatted message.
+  # [class.ParseError]
+  # purpose = "Raised by parse! and Failure#value!"
+  # fields = ["failure: Birman::Failure", "message: formatted by the formatter given"]
   class ParseError < StandardError
     attr_reader :failure