birman 0.2.2 → 0.3.0

data/lib/birman/matchers.rb

@@ -38,8 +38,9 @@ module Birman
   module Matcher
     # [method.">>"]
     # params = ["other: String | Regexp | Matcher"]
-    # returns = "Sequence of self then other (flattens into an existing sequence)"
-    def >>(other) = Seq.new([self, Birman.coerce(other)])
+    # 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"]
@@ -61,8 +62,8 @@ module Birman
     # 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
 
@@ -75,7 +76,7 @@ module Birman
     # [method.maybe]
     # returns = "Optional self"
     # value = "self's value, or nil when absent"
-    def maybe = rep(0, 1).map(&:first)
+    def maybe = Maybe.new(self)
 
     # [method.absent]
     # returns = "Negative lookahead: succeeds, consuming nothing, when self doesn't match here"
@@ -87,10 +88,46 @@ module Birman
     # 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 = ["fn: block taking self's value"]
-    # returns = "Matcher whose value is fn's result (self's .as name is kept)"
-    def map(&fn) = Action.new(self, fn)
+    # 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"]
@@ -124,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
@@ -134,7 +173,8 @@ 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).
@@ -169,25 +209,59 @@ 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 = Array.new(parts.size)
@@ -204,8 +278,46 @@ 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
@@ -251,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
@@ -271,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
 
@@ -291,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.
@@ -350,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
-      Match.new(r.pos, 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>"
@@ -387,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
@@ -403,7 +587,10 @@ 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 }
+      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
 
@@ -411,27 +598,26 @@ module Birman
     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)
-      @ignore_ref = ignore && Ref.new(ignore) # built once, not per token
-      super
-    end
+    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 = @ignore_ref.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
 

data/lib/birman/result.rb

@@ -36,6 +36,10 @@ 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 = [
@@ -45,8 +49,13 @@ module Birman
   # "committed: Boolean (failed after a commit)",
   # "reason: String | nil (set when it isn't about expectations, e.g. nesting too deep)"
   # ]
-  # methods = ["line", "column", "found", "message(formatter)", "value!(formatter) -> raises ParseError"]
+  # 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

data/lib/birman/rule_set.rb

@@ -38,21 +38,34 @@ module Birman
     # returns = "nil"
     # side_effects = ["Defines a rule that skips trailing spacing via the grammar's ignore rule"]
     def lexeme(name, &body)
-      rule(name) { Lexeme.new(Birman.coerce(instance_exec(&body)), ignore_rule) }
+      rule(name) { Lexeme.new(Birman.coerce(instance_exec(&body))) }
     end
 
     private
 
     # A rule named after a method the grammar relies on (send, class,
-    # match, token...) would silently replace it. Redefining a rule is
-    # fine, and so are private Kernel names like print or select.
+    # match, token, or a private helper in any of Birman's modules) would
+    # silently replace it. Redefining a rule is fine, and so are private
+    # Kernel names like print or select, and the grammar's own private
+    # helpers: those are the grammar's to replace.
     def check_rule_name!(name)
       return if private_method_defined?(:"__rule_#{name}")
 
-      owner = [Object, Combinators, Grammar].find { _1.public_method_defined?(name) } ||
-              [Combinators, Grammar].find { _1.private_method_defined?(name) } ||
+      birman = [Object, Combinators, Grammar] | ancestors.select { _1.name&.start_with?("Birman::") }
+      owner = birman.find { _1.public_method_defined?(name) } ||
+              (birman - [Object]).find { _1.private_method_defined?(name, false) } ||
               (instance_method(name).owner if method_defined?(name))
-      raise ArgumentError, "rule :#{name} would replace #{owner}##{name}; give the rule another name" if owner
+      return unless owner
+
+      raise ArgumentError, "rule :#{name} would replace #{owner}##{name}, #{why_taken(owner, birman)}, " \
+                           "since rules are methods too; give the rule another name"
+    end
+
+    def why_taken(owner, birman)
+      if owner == Object then "a method every Ruby object has"
+      elsif birman.include?(owner) then "which Birman relies on"
+      else "a method of this grammar"
+      end
     end
   end
 end

data/lib/birman/rules.rb

@@ -48,8 +48,8 @@ module Birman
     module Numbers
       extend RuleSet
 
-      lexeme(:integer) { match(/\d+/).map(&:to_i).label("integer") }
-      lexeme(:float)   { match(/\d+\.\d+/).map(&:to_f).label("float") }
+      lexeme(:integer) { match(/\d+/).map(:to_i).label("integer") }
+      lexeme(:float)   { match(/\d+\.\d+/).map(:to_f).label("float") }
       lexeme(:number)  { (float | integer).label("number") }
     end
 
@@ -57,6 +57,7 @@ module Birman
     # commits, so an unterminated string is reported where it breaks.
     # [module.Rules.Strings]
     # rules = ["string: double-quoted, escapes \\n \\t \\r \\0, value is the String"]
+    # helpers = ["decode_escape(text): the character a backslash escape stands for"]
     # notes = "The opening quote commits, so an unterminated string is reported where it breaks"
     module Strings
       extend RuleSet
@@ -64,15 +65,19 @@ module Birman
       ESCAPES = { "n" => "\n", "t" => "\t", "r" => "\r", "0" => "\0" }.freeze
 
       lexeme(:string) do
-        (str('"') > (string_part.rep >> str('"').label("closing quote")))
-          .map { |(_, parts, _)| parts.join }
+        seq(str('"'), commit, only(string_part.rep), str('"').label("closing quote"))
+          .map(:join)
           .label("string")
       end
 
       rule(:string_part) do
-        (match(/\\./).map { ESCAPES.fetch(_1[1], _1[1]) } |
+        (match(/\\./).action(:decode_escape) |
           match(/[^"\\\n]+/)).label("string character")
       end
+
+      private
+
+      def decode_escape(text) = ESCAPES.fetch(text[1], text[1])
     end
 
     # Identifiers that can't be reserved words. Declare those in the

data/lib/birman/standalone.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+# [file]
+# purpose = "Running a matcher without writing a grammar class"
+# responsibility = "Birman.parse and Birman.parse!, via a cached anonymous grammar per matcher"
+# dependencies = ["Birman::Grammar", "Birman::AST"]
+module Birman
+  # Parses input with matcher as the whole grammar: Success or Failure,
+  # exactly as Grammar.parse, and bad input never raises.
+  #
+  #   Birman.parse(Birman.seq("let", Birman.match(/\w+/)), "let x", ignore: /\s*/)
+  #   # => #<data Birman::Success value=["let", "x"]>
+  #
+  # ignore is a matcher (a String, Regexp or Matcher), not a rule name:
+  # there is no grammar here for a name to refer to. Literals skip it
+  # after themselves, and it's skipped at the start of input.
+  # [method."Birman.parse"]
+  # params = ["matcher: String | Regexp | Matcher", "input: String", "ignore: String | Regexp | Matcher | nil"]
+  # returns = "Birman::Success(value) when all of input parses, else Birman::Failure"
+  # raises = ["ArgumentError if matcher or ignore refers to a rule, or an .action/.check method Birman lacks"]
+  def self.parse(matcher, input, ignore: nil) = Standalone.grammar(matcher, ignore).parse(input)
+
+  # [method."Birman.parse!"]
+  # params = ["matcher, input, ignore: as Birman.parse", "formatter: #call(failure) = ErrorFormatter.new"]
+  # returns = "The parsed value"
+  # raises = ["Birman::ParseError", "ArgumentError, as Birman.parse"]
+  def self.parse!(matcher, input, ignore: nil, **) = Standalone.grammar(matcher, ignore).parse!(input, **)
+
+  # The anonymous grammar classes behind Birman.parse: the matcher is
+  # the root rule and ignore the ignore rule. Matchers are immutable
+  # values, so equal ones share a class, and with it the per-grammar
+  # caches (literal matchers, rule matchers). The cache is bounded, so
+  # matchers built afresh for each parse (with a new .map block, say)
+  # don't pile up.
+  # [module.Standalone]
+  # purpose = "Builds and caches the anonymous grammar Birman.parse runs"
+  module Standalone
+    ROOT = :__standalone_root
+    IGNORE = :__standalone_ignore
+    LIMIT = 256
+
+    @grammars = {}
+    @lock = Mutex.new
+
+    # [method."Standalone.grammar"]
+    # params = ["matcher: String | Regexp | Matcher", "ignore: String | Regexp | Matcher | nil"]
+    # returns = "A grammar class whose root rule is matcher (to_ebnf, to_ruby and parse work on it)"
+    # raises = ["ArgumentError if matcher or ignore refers to a rule, or an .action/.check method Birman lacks"]
+    def self.grammar(matcher, ignore)
+      key = [matcher, ignore].freeze
+      @lock.synchronize do
+        @grammars[key] ||= begin
+          @grammars.shift if @grammars.size >= LIMIT
+          build(matcher, ignore)
+        end
+      end
+    end
+
+    def self.build(matcher, ignore)
+      grammar = Class.new do
+        include Grammar
+
+        root ROOT
+        rule(ROOT) { matcher }
+        next unless ignore
+
+        rule(IGNORE) { ignore }
+        self.ignore IGNORE
+      end
+      check!(grammar, [matcher, ignore].compact.map { Birman.coerce(_1) })
+      grammar
+    end
+
+    # A rule reference, or an action or check calling a method only a
+    # grammar of your own would have, raises only when the parse reaches
+    # it (and the method as a NoMethodError on an anonymous class), so a
+    # mistake could hide in an untried alternative. Checked up front.
+    def self.check!(grammar, matchers)
+      matchers.each { each_matcher(_1) { |m| check_matcher!(grammar, m) } }
+    end
+
+    def self.check_matcher!(grammar, matcher)
+      case matcher
+      when Ref
+        raise ArgumentError, "undefined rule #{matcher.name.inspect}: " \
+                             "a matcher run by Birman.parse can't refer to rules; define them in a grammar class"
+      when Action, Check
+        name = matcher.method_name
+        return if grammar.method_defined?(name) || grammar.private_method_defined?(name)
+
+        raise ArgumentError, "undefined method #{name.inspect} for .#{matcher.is_a?(Action) ? "action" : "check"}: " \
+                             "a matcher run by Birman.parse can only use Birman's own methods there; " \
+                             "define yours in a grammar class"
+      end
+    end
+
+    # Every matcher inside root, root included, once each.
+    def self.each_matcher(root)
+      queue = [root]
+      seen = {}.compare_by_identity
+      while (m = queue.shift)
+        next if seen[m]
+
+        seen[m] = true
+        yield m
+        queue.concat(m.to_h.values.flat_map { Array(_1) }.grep(Matcher)) if m.is_a?(Data)
+      end
+    end
+    private_class_method :build, :check!, :check_matcher!, :each_matcher
+  end
+end

data/lib/birman/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Birman
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

data/lib/birman.rb

@@ -33,6 +33,25 @@ module Birman
   def self.char_offset(input, byte_pos)
     input.ascii_only? ? byte_pos : input.byteslice(0, byte_pos).length
   end
+
+  # The byte offset of the first byte in input that doesn't start a
+  # valid character, or nil if input is valid. Grammar#parse fails
+  # there before a regexp can raise on it. Ruby splits invalid bytes
+  # into characters of their own, so everything before it is valid,
+  # and a Failure's line and column count as usual.
+  # [method."Birman.invalid_byte"]
+  # params = ["input: String"]
+  # returns = "Integer | nil: the byte offset of the first invalid byte"
+  def self.invalid_byte(input)
+    return if input.valid_encoding?
+
+    pos = 0
+    input.each_char do |char|
+      return pos unless char.valid_encoding?
+
+      pos += char.bytesize
+    end
+  end
 end
 
 require "strscan"
@@ -45,6 +64,9 @@ require_relative "birman/matchers"
 require_relative "birman/rule_set"
 require_relative "birman/combinators"
 require_relative "birman/grammar"
+require_relative "birman/standalone"
 require_relative "birman/error_formatter"
 require_relative "birman/ast"
+require_relative "birman/left_recursion"
 require_relative "birman/rules"
+require_relative "birman/compiler"