pgn2 0.4.0 → 1.1.0

data/docs/superpowers/specs/2026-08-13-pgn-performance-quick-wins-design.md

@@ -0,0 +1,227 @@
+# PGN2 performance quick wins — Approach A (quick, behavior-compatible micro-opts)
+
+> "Approach A" denotes the safe, allocation-focused track. A later, larger
+> design (Approach B) will cover architectural changes: piece-location indexes,
+> lazy position computation, and a coordinate-only internal board
+> representation.
+
+## Goal
+
+Make the gem faster on the combined **parse + replay** workload after the
+whittle → Racc migration, with only safe, behavior-compatible micro-optimizations
+(no public API changes, no serialized-output changes).
+
+## Scope
+
+This design covers the five highest-ROI quick wins identified in the profiles:
+
+1. Remove per-token `PGN::Lexer::Token` allocation on the parser hot path.
+2. Avoid double `MoveText` wrapping in `PGN::Game#moves=`.
+3. Replace `PGN::Move` SAN regex with hand-rolled parsing.
+4. Reduce small temporary allocations in `PGN::Position#move` and
+   `PGN::MoveCalculator`.
+5. Promote the Racc parse baseline to canonical and record new baselines in
+   `bench/baseline_*.txt` after verification.
+
+Out of scope: larger architecture changes such as piece-location indexes,
+lazy position computation, or coordinate-only internal board representation.
+
+## Context / baseline
+
+Measured on the current checkout with `bundle exec rake bench` (Racc parser);
+these are the canonical `bench/baseline_*.txt` values refreshed as the
+prerequisite in item 5:
+
+- **Parse-only:** ~125 k objects / 7.88 MB for 100 copies of the immortal game
+  (= 626,037 objects / 39.4 MB for the 500-game corpus in `bench/baseline_parse.txt`).
+- **Parse + replay:** ~337 k objects / 21.6 MB for the same per-100 ratio
+  (= 1,683,087 objects / 108 MB for 500 games).
+- **Replay only:** 2,177 objects / 142 kB for the 45-ply immortal game
+  (`bench/baseline_moves.txt`).
+
+Historical snapshots are kept in `bench/baseline_*.pre-quickwins.txt` and
+`bench/baseline_parse.racc.txt` for reference. The previously committed
+`baseline_parse.txt` held stale pre-migration whittle numbers and has been
+overwritten by the current Racc output.
+
+Top allocation hot spots:
+
+- `PGN::Lexer::Token` creation (parse-only).
+- `PGN::MoveText` created twice per parsed move (parser + `Game#moves=`).
+- `Move#initialize` SAN regex (`Regexp` + `MatchData` objects, replay).
+- Small throw-away arrays and string conversions in `MoveCalculator` and
+  `Position#move`.
+
+## Detailed changes
+
+### 1. Lexer: parser hot path avoids `Token` objects
+
+`lib/pgn/lexer.rb`
+
+- Add a fast public method `next_token_pair` that returns `[type, value]`
+  directly, without allocating a `PGN::Lexer::Token` Struct.
+  The byte offset is **not** expensive (`@ss.pos`) and is still required, so
+  the saving is the Struct allocation, not offset computation.
+- **Correctness requirement:** `next_token_pair` must invoke the same
+  `note_token(type, off)` and `advance_line(value)` side effects as
+  `next_token`. In particular `note_token` maintains `game_starts`, which
+  `PgnParser#assign_pgn!` relies on to slice each game's verbatim raw `pgn`
+  text — skipping it would corrupt `Game#pgn`.
+- Keep `next_token` and `tokens` unchanged (they continue to return `Token`
+  objects and are used by specs/other callers).
+- Implement both methods on top of a shared private scanning routine so the
+  scanning logic is not duplicated.
+- The single-byte literal path already returns frozen strings via
+  `LITERAL_BYTES` under `# frozen_string_literal: true`; preserve that in
+  `next_token_pair` (no change needed beyond routing through the shared
+  routine).
+
+`lib/pgn/pgn_parser.y`
+
+- Change `PgnParser#next_token` to call `@lexer.next_token_pair` and return the
+  resulting array directly.
+- Regenerate `lib/pgn/pgn_parser.rb` from the `.y` file with Racc.
+- No changes to grammar or semantics.
+
+### 2. Game#moves=: stop re-wrapping existing MoveText objects
+
+`lib/pgn/game.rb`
+
+- Detect when an element is already a `PGN::MoveText` instance and reuse it
+  directly instead of creating a new one.
+- Still perform castling normalization (`0` → `O`) for raw strings.
+- Preserve `clean_text` behavior for fresh comments only.
+- **Reuse-safety invariant:** reusing the parser's `MoveText` shares one object
+  between the parser's move tree and `Game#moves`. This is safe only because
+  nothing mutates a `MoveText` after construction; record that invariant in a
+  comment so a future mutation doesn't silently corrupt both holders.
+
+Expected effect: roughly halves `MoveText` allocations on the parse path while
+keeping serialized output identical.
+
+### 3. Move#initialize: hand-rolled SAN parser (highest-risk item — quantify first)
+
+`lib/pgn/move.rb`
+
+This is the highest-risk, and likely lowest-allocation-payoff, item: the SAN
+regex produces ~1 `MatchData` per ply (~2.1% of the 2,177-object replay
+baseline). Before committing to a full hand-roll, **measure #3 in isolation**
+and confirm the payoff; if marginal, ship #1, #2, #4 alone and defer #3.
+
+Trivial independent sub-win (do regardless of the full hand-roll):
+
+- In `Move#piece=`, replace `return if san.match('O-O')` (which allocates a
+  `MatchData` on every `Move.new`, castling or not) with a non-allocating
+  check such as `san.include?('O-O')` or `san.start_with?('O')`.
+
+Full hand-roll (if pursued):
+
+- Replace `move.match(SAN_REGEX)` with a manual parse over the byte/string
+  representation of the SAN notation.
+- Populate all existing attributes (`piece`, `destination`, `promotion`,
+  `check`, `capture`, `disambiguation`, `castle`) with the same values as
+  today, including the `piece=` early-return for castling.
+- Keep setter methods (`piece=`, `promotion=`, `capture=`, `disambiguation=`,
+  `castle=`) so external callers that assign attributes manually are unaffected.
+- Use frozen constants for frequently-checked piece sets (`pawn?` lives here,
+  in `move.rb` — see item 4).
+- **Upfront fixtures:** add a dedicated spec pinning every attribute for a
+  comprehensive set of SAN strings: `O-O`, `O-O-O`, `O-O+`, `O-O-O#`;
+  pawn moves and captures incl. promotion (`e4`, `exd5`, `e8=Q`, `exd8=Q+`,
+  `b1=N#`); piece moves with file/rank/full disambiguation (`Nbd2`, `R1e2`,
+  `Qh4e1`); captures with check/mate; and the `--` "don't care" move. Do this
+  before implementation, not only if ambiguity surfaces.
+
+### 4. Position / MoveCalculator: fewer throw-away allocations
+
+`lib/pgn/position.rb`
+
+- Inline `next_player` logic in `Position#move` (or simply rewrite its body to
+  `player == :white ? :black : :white`) to avoid the `(PLAYERS - [player])`
+  array allocation per ply.
+- Apply `castling_restrictions` only when non-empty; avoid array subtraction
+  when there is nothing to remove. (Safe to return the existing `castling`
+  array directly because castling arrays are replaced, never mutated.)
+
+`lib/pgn/move_calculator.rb`
+
+- Compute and cache destination coordinates in `initialize` instead of calling
+  `board.coordinates_for(move.destination)` repeatedly (it can be invoked 2–3
+  times per move across `direction_origins` / `move_origins` / `pawn_origins`).
+- Inline `valid_square?` boundary checks to remove the per-call method dispatch
+  (note: `(0..7)` are frozen range literals already cached by the VM, so the
+  win is call overhead, not Range allocation — don't claim the latter).
+- Replace run-time array/hash literals with frozen constants or `case`/`when`
+  where they appear on hot paths (e.g. rook-origin lookup in
+  `castling_restrictions`, the per-call hash literals `{ 'a1' => 'Q', ... }`).
+- Keep semantic behavior identical (same board updates, same disambiguation,
+  same `king_position` scan — Approach A deliberately defers indexing/caching
+  to a later design).
+
+`lib/pgn/move.rb` (relocated from move_calculator)
+
+- `Move#pawn?` uses `%w[P p].include?(piece)`, allocating an array each call;
+  it's invoked from `MoveCalculator#increment_halfmove?` and `pawn_origins`.
+  Replace with a frozen constant or `piece == 'P' || piece == 'p'`.
+
+## Testing & behavior preservation
+
+- All existing specs must pass without modification (`bundle exec rspec`).
+- The `bench/baseline_moves.txt` and `bench/baseline_parse.txt` files will be
+  regenerated with `bundle exec rake bench` and committed if they show lower
+  object/byte counts and equal or better throughput.
+- Public API remains unchanged: `PGN.parse`, `Game#moves=`, `Move.new`,
+  `Position#move`, etc. accept the same inputs and produce the same outputs and
+  side effects.
+- No changes to PGN/FEN serialization format.
+- **Lexer non-regression:** because `next_token_pair` shares the scanning
+  routine with `next_token`/`tokens`, the existing `tokens`/`next_token` specs
+  and the `game_starts`-driven `Game#pgn` raw-text slicing output must stay
+  byte-identical across the fixtures and inline inputs in
+  `spec/parser_explicit_spec.rb`.
+
+## Risks & mitigations
+
+| Risk | Mitigation |
+|---|---|
+| Hand-rolled SAN parser mishandles an edge case | Upfront comprehensive SAN fixture spec (castling both sides, promotion with/without check, pawn & piece captures, file/rank/full disambiguation, `--`) added before implementation; full suite must stay green. |
+| `next_token_pair` drifts from `next_token` behavior | Both methods share the private scanning routine, the same `RULES` ordering, and the same `note_token`/`advance_line` side effects (incl. `game_starts`). |
+| `Game#moves=` no longer applies castling normalization | Continue normalizing raw strings; only skip work when input is already `MoveText`. |
+| Performance wins smaller than expected | Measure before/after with the committed baseline harness. |
+
+## Acceptance criteria
+
+1. `bundle exec rspec` passes (0 failures).
+2. `lib/pgn/pgn_parser.rb` is regenerated and in sync with `.y`
+   (`git diff --stat` should reflect the generation, and CI racc-sync check
+   passes).
+3. `bundle exec rake bench` shows lower allocated objects/bytes than the
+   **post-Racc** committed baselines (`baseline_moves.txt` and
+   `baseline_parse.txt`, the latter promoted from `baseline_parse.racc.txt`
+   per item 5). Comparing against the old whittle `baseline_parse.txt` would
+   not be a meaningful gate.
+4. IPS numbers are equal or higher than current baselines.
+5. Baseline files are updated and committed as part of the change set.
+6. Lexer non-regression: `tokens`/`next_token` spec output and `Game#pgn`
+   raw-text slicing are byte-identical to the pre-change checkout.
+
+## Estimated impact
+
+Per-item expectations (to be confirmed by measurement, not assumed in
+aggregate):
+
+- **Items 1, 2, 4 (low-risk):** the largest reliable wins. Parse-side `Token`
+  elimination (#1) and halved `MoveText` allocation (#2) should show up directly
+  in parse-only object counts; `next_player`/`pawn?`/`castling_restrictions`
+  (#4) trim a handful of objects per ply.
+- **Item 3 (SAN hand-roll):** ~1 `MatchData` per ply (~2.1% of the 2,177-object
+  replay baseline) plus the `piece=` guard fix — modest, and the bulk of the
+  estimate does **not** come from this item.
+- **Replay allocations are dominated by `Position.new` + `Board#dup` +
+  `MoveCalculator` arrays**, which Approach A only trims at the edges; the big
+  replay win is deferred to Approach B.
+
+Conservative aggregate guess once #1/#2/#4 land: parse-only allocations down
+~10–15%, replay allocations down in the single-digit-percent range (lower than
+a naive reading of these micro-opts might suggest). Actual numbers will come
+from the baseline run; revise this section with measured per-item deltas.

data/lib/pgn/board.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module PGN
   # {PGN::Board} represents the squares of a chess board and the pieces on
   # each square. It is responsible for translating between a human readable
@@ -73,6 +75,7 @@ module PGN
     #
     def initialize(squares)
       self.squares = squares
+      @owned = Array.new(8, false)
     end
 
     # @overload at(str)
@@ -88,13 +91,12 @@ module PGN
     #   board.at(4,3)  #=> "P"
     #   board.at("e4") #=> "P"
     #
-    def at(*args)
-      case args.length
-      when 1
-        at(*coordinates_for(args.first))
-      when 2
-        squares[args[0]][args[1]]
-      end
+    # String squares are parsed with getbyte arithmetic (a=0x61, '1'=0x31)
+    # so the common string lookup allocates nothing.
+    def at(arg0, arg1 = nil)
+      return squares[arg0][arg1] unless arg1.nil?
+
+      squares[file_of(arg0)][rank_of(arg0)]
     end
 
     # @param changes [Hash<String, <String, nil>>] changes to make to the board
@@ -115,9 +117,16 @@ module PGN
     # @example
     #   board.update("e4", "P")
     #
+    # Copy-on-write: clone only the column being mutated, and only once per
+    # instance, so unchanged columns stay shared with any board this one was
+    # duped from.
     def update(square, piece)
-      coords = coordinates_for(square)
-      squares[coords[0]][coords[1]] = piece
+      file = file_of(square)
+      unless @owned[file]
+        squares[file] = squares[file].dup
+        @owned[file] = true
+      end
+      squares[file][rank_of(square)] = piece
       self
     end
 
@@ -127,10 +136,7 @@ module PGN
     #   board.coordinates_for("e4") #=> [4, 3]
     #
     def coordinates_for(position)
-      file_chr, rank_chr = position.chars.to_a
-      file = FILE_TO_INDEX[file_chr]
-      rank = RANK_TO_INDEX[rank_chr]
-      [file, rank]
+      [file_of(position), rank_of(position)]
     end
 
     # @param coordinates [Array<Integer>] the coordinates of the square
@@ -154,10 +160,22 @@ module PGN
       end.join("\n")
     end
 
-    # @return [PGN::Board] a copy of self with duplicated squares
+    # @return [PGN::Board] a copy of self. The outer array is copied; the
+    # 8 column arrays are shared and cloned lazily by #update on first
+    # mutation (copy-on-write).
     #
     def dup
-      PGN::Board.new(squares.map(&:dup))
+      PGN::Board.new(squares.dup)
+    end
+
+    private
+
+    def file_of(square)
+      square.getbyte(0) - 97
+    end
+
+    def rank_of(square)
+      square.getbyte(1) - 49
     end
   end
 end

data/lib/pgn/fen.rb

@@ -98,14 +98,22 @@ module PGN
     #   PGN::FEN.start.board_string #=> "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR"
     #
     def board_string
-      self.board
-          .squares
-          .transpose
-          .reverse
-          .map {|row| row.map {|e| e.nil? ? "_" : e } }
-          .map {|row| row.join }
-          .join("/")
-          .gsub(/_+/) {|match| match.length }
+      rows = self.board.squares.transpose.reverse
+      rows.map do |row|
+        s = +""
+        run = 0
+        row.each do |e|
+          if e.nil?
+            run += 1
+          else
+            s << run.to_s if run > 0
+            run = 0
+            s << e
+          end
+        end
+        s << run.to_s if run > 0
+        s
+      end.join("/")
     end
 
     # @return [PGN::Position] a {PGN::Position} representing the current

data/lib/pgn/game.rb

@@ -77,17 +77,37 @@ module PGN
     #
     # Standardize castling moves to use O's instead of 0's
     #
+    # Reuse-safety invariant: when an element is already a MoveText we reuse
+    # it directly (sharing one object between the parser's move tree and
+    # Game#moves) whenever its comment is already fully cleaned. This is safe
+    # because nothing mutates a MoveText after this assignment returns. We
+    # still re-wrap when the comment carries braces: the parser's single-pass
+    # clean_text leaves braces on multi-line/nested comments, and the second
+    # clean_text that MoveText.new applies here is load-bearing for those
+    # (matches the legacy whittle byte-output). Skipping it would change
+    # serialized comments.
     def moves=(moves)
       @moves =
         moves.map do |m|
-          if m.is_a? String
-            MoveText.new(m.gsub('0', 'O'))
-          else
+          if m.is_a?(String)
+            MoveText.new(m.include?('0') ? m.gsub('0', 'O') : m)
+          elsif m.notation.include?('0')
             MoveText.new(m.notation.gsub('0', 'O'), m.annotation, m.comment, m.variations)
+          elsif m.comment.nil? || !m.comment.include?('{')
+            m
+          else
+            MoveText.new(m.notation, m.annotation, m.comment, m.variations)
           end
         end
     end
 
+    # @return [String] a canonical PGN string for this game, ending with a
+    #   trailing newline.
+    #
+    def to_pgn
+      PGN::Serializer.new(self).to_s
+    end
+
     def initial_fen
       tags && tags['FEN']
     end

data/lib/pgn/lexer.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require 'strscan'
+
+module PGN
+  # {PGN::Lexer} is a {StringScanner}-based tokenizer for PGN. It reuses the
+  # same terminal patterns as the legacy whittle parser so tokenization is
+  # byte-compatible, but performs far fewer Ruby allocations because the
+  # scanning happens in the C-backed StringScanner.
+  #
+  # The lexer also records, per game, the byte offset of the game's first
+  # non-discarded token ({#game_starts}). The parser uses these offsets to
+  # slice the verbatim {PGN::Game#pgn} raw text out of the original input,
+  # reproducing the legacy accumulator's output exactly.
+  #
+  # All offsets are byte offsets (StringScanner works in bytes); slicing is
+  # done with {String#byteslice} so multibyte (UTF-8) input stays intact.
+  #
+  class Lexer
+    Token = Struct.new(:type, :value, :offset, :line, keyword_init: true) do
+      def inspect
+        "#<PGN::Lexer::Token #{type.inspect} value=#{value.inspect} @#{offset} L#{line}>"
+      end
+    end
+
+    # Discarded: insignificant whitespace.
+    WSP = /\s+/
+
+    # Discarded: a PGN "rest of line" comment beginning with `%`.
+    PGN_COMMENT = /% .*/
+
+    # A tag value string. Allows unescaped double-quotes inside the value
+    # (a form seen in real-world PGN files) — only a bare backslash starts
+    # an escape. Matches the legacy parser's relaxed string rule.
+    STRING = /
+      "                          # beginning of string
+      (
+        [[:print:]&&[^\\]] |    # printing characters except backslash
+        \\\\                |    # escaped backslashes
+        \\"                      # escaped quotation marks
+      )*                         # zero or more of the above
+      "                          # end of string
+    /x
+
+    # A brace-delimited comment, with recursive nesting via \g<1>.
+    COMMENT = /
+      (
+        \{                           # beginning of comment
+        (
+          [[:print:]&&[^\\{}]] |   # printing characters except brace and backslash
+          \n                     |
+          \\\\                   |   # escaped backslashes
+          \\\{|\\\}              |   # escaped braces
+          \n                     |   # newlines
+          \g<1>                      # recursive
+        )*                           # zero or more of the above
+          \}                           # end of comment
+      )
+    /x
+
+    # Game termination marker.
+    GAME_TERMINATION = %r{
+      1-0       |    # white wins
+      0-1       |    # black wins
+      1/2-1/2 |    # draw
+      \*             # ?
+    }x
+
+    # A move in standard algebraic notation (incl. castling, promotion,
+    # check/mate, the `--` "don't care" move).
+    SAN_MOVE = %r{
+      (
+        --                           |    # "don't care" move (used in variations)
+        [O0](-[O0]){1,2}             |    # castling (O-O, O-O-O)
+        [a-h][1-8]                   |    # pawn moves (e4, d7)
+        [BKNQR][a-h1-8]?x?[a-h][1-8] |    # major piece moves w/ optional specifier
+        [a-h][1-8]?x[a-h][1-8]            # pawn captures
+      )
+      (
+        =[BNQR]                            # optional promotion (d8=Q)
+      )?
+      (
+        \+                            |    # check (g5+)
+        \#                                 # checkmate (Qe7#)
+      )?
+    }x
+
+    # A move number indication, e.g. `1.`, `12.`, `1...`.
+    MOVE_NUMBER = /[[:digit:]]+\.*/
+
+    # A tag name (letters, digits, underscores).
+    TAG_NAME = /[A-Za-z0-9_]+/
+
+    # A numeric annotation glyph (`$1`) or a punctuation annotation (`?!`,
+    # `!?`, `??`, ...).
+    NAG = /
+      \$\d+       | # dollar sign followed by an integer
+      [?!][?!]?   # support the most used annotations directly
+    /x
+
+    # Order matters: more specific / longer tokens are tried first so that
+    # e.g. `1-0` (termination) wins over `1` (move number), and `0-0`
+    # (castling) wins over `0` (move number). Whitespace and `%` comments
+    # are discarded (consumed but not emitted). Beyond that constraint,
+    # rules are ordered most- to least-frequent (one san_move/move_number
+    # per ply/full-move vs. a handful of comments/strings per game) so the
+    # common case fails the fewest regexes before matching.
+    RULES = [
+      [:wsp,              WSP,              true],   # discarded
+      [:pgn_comment,      PGN_COMMENT,      true],   # discarded
+      [:game_termination, GAME_TERMINATION, false],
+      [:san_move,         SAN_MOVE,         false],
+      [:move_number,      MOVE_NUMBER,      false],
+      [:nag,              NAG,              false],
+      [:comment,          COMMENT,          false],
+      [:string,           STRING,           false],
+      [:tag_name,         TAG_NAME,         false]
+    ].freeze.each(&:freeze)
+
+    # Single-character literals, matched by their byte value: [type, frozen value].
+    LITERAL_BYTES = {
+      91 => [:lbracket, '['], # [
+      93 => [:rbracket, ']'], # ]
+      40 => [:lparen,   '('], # (
+      41 => [:rparen,   ')'] # )
+    }.freeze
+
+    def initialize(input)
+      @input = input
+      @ss = StringScanner.new(input)
+      @line = 1
+      @game_starts = []
+      @between_games = true # at start we are "between" games
+    end
+
+    attr_reader :game_starts
+
+    # The list of {Token}s for the whole input. Convenience for specs.
+    def tokens
+      result = []
+      while (t = next_token)
+        result << t
+      end
+      result
+    end
+
+    # Returns the next {Token}, or +nil+ at end of input.
+    def next_token
+      type, value, off = scan_next
+      return nil unless type
+      Token.new(type: type, value: value, offset: off, line: @line)
+    end
+
+    # Fast path for the parser: returns [type, value] for the next
+    # non-discarded token, or +nil+ at end of input. Does not allocate a
+    # {Token} Struct. Shares the same scanning routine and the same
+    # +note_token+ / +advance_line+ side effects as +next_token+ (so
+    # +game_starts+ tracking is preserved).
+    def next_token_pair
+      type, value, = scan_next
+      return nil unless type
+      [type, value]
+    end
+
+    private
+
+    # Scan to the next non-discarded token and return [type, value, offset],
+    # or nil at end of input. Performs the exact +advance_line+ and
+    # +note_token+ side effects that +next_token+ historically did, so
+    # +game_starts+ (used for verbatim +Game#pgn+ slicing) stays correct.
+    def scan_next
+      until @ss.eos?
+        off = @ss.pos
+
+        if (lit = LITERAL_BYTES[@input.getbyte(off)])
+          type, value = lit
+          @ss.pos = off + 1
+          note_token(type, off)
+          return [type, value, off]
+        end
+
+        type, value, discarded = scan_one
+        advance_line(value)
+        next if discarded
+
+        note_token(type, off)
+        return [type, value, off]
+      end
+      nil
+    end
+
+    # Try each terminal rule in order; return [type, matched_string, discarded]
+    # for the first match, or raise if nothing matches at the current position.
+    def scan_one
+      RULES.each do |(type, re, discarded)|
+        if (m = @ss.scan(re))
+          return [type, m, discarded]
+        end
+      end
+      raise UnconsumedInputError,
+            "Unmatched input #{@input.byteslice(@ss.pos..).inspect} on line #{@line}"
+    end
+
+    # Track per-game content-start offsets for verbatim pgn slicing.
+    # game_termination belongs to the current game and marks that the NEXT
+    # non-discarded token begins a new game.
+    def note_token(type, off)
+      if type == :game_termination
+        @between_games = true
+      elsif @between_games
+        @game_starts << off
+        @between_games = false
+      end
+    end
+
+    def advance_line(str)
+      @line += str.count("\n")
+    end
+  end
+
+  # Raised when the lexer cannot match the input at the current position.
+  class UnconsumedInputError < StandardError; end
+end

data/lib/pgn/move.rb

@@ -95,13 +95,20 @@ module PGN
       match = move.match(SAN_REGEX)
       return  if match.nil?
 
-      match.names.each do |name|
-        send("#{name}=", match[name]) if respond_to?(name)
-      end
+      self.piece          = match[:piece]
+      self.destination    = match[:destination]
+      self.promotion      = match[:promotion]
+      self.check          = match[:check]
+      self.capture        = match[:capture]
+      self.disambiguation = match[:disambiguation]
+      self.castle         = match[:castle]
     end
 
     def piece=(val)
-      return if san.match('O-O')
+      # Castling SAN (O-O / O-O-O) has no piece attribute; the castle attribute
+      # is set later in #initialize. Use a non-allocating prefix check instead
+      # of `san.match('O-O')`, which allocated a MatchData on every Move.new.
+      return if san.start_with?('O')
 
       val ||= 'P'
       @piece = black? ? val.downcase : val
@@ -157,7 +164,7 @@ module PGN
     # @return [Boolean] whether the piece being moved is a pawn
     #
     def pawn?
-      %w[P p].include?(piece)
+      piece == 'P' || piece == 'p'
     end
   end
 end