pgn2 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d90a73cdcc2fc1b2765b35315935c6f20272a0e2374863d0d7c491a21f815ff
-  data.tar.gz: e4b34dfcb1e2d0c63ed479d338a0d58f3808f965db99000844cf7dcfa3af8fc9
+  metadata.gz: da98f302d6785b75581d53fbe6dab4b7ccad9f5514f7ad278be12a540633d572
+  data.tar.gz: 9b22f32a2b44bd06cfd8d29c82f9b4af8c1c4687ed9650df33c4d5fdc76dd49e
 SHA512:
-  metadata.gz: b222778b4e25b13fbe5e62fe694d1e5189099d8cafd7b5a15f579e3df7413aa60f43a69ee299d3a37fa312c3baf25e798a54e432ad199ec118ebd56e35b9949b
-  data.tar.gz: eacb82757bb6876272f320b6b5402a449d3954d0c39052ef4304682c00435b559b49a29379f77a9c7f34dbbf210c4b1865b59df66f19ae1a72bfb5c0050e1df7
+  metadata.gz: 0c99f7034728254221189f9af053bc6c57938d24c96d83d8dacce7ad78cf2bc8b23de3b28a497c9b750b12f63dd17a9ca6ed65b293c5f8f0188d4f79b188e5d2
+  data.tar.gz: 437fbf1d534aa15578bef06c4ca5020116f6b2385d81c886104f69bb8db0124d7e220b3d566a22f8df4e93180929519891ba71279db21e0e2f541f1b6f0f8892

data/CHANGELOG.md

@@ -1,6 +1,40 @@
 # Changelog
 
-## 1.4.0 (unreleased)
+## 1.5.0 (2026-08-13)
+
+### Summary
+
+Clarity refactor on the 0x88 hot path, plus a small parser perf win: no
+public API changes, no behavior change; serialized PGN/FEN output stays
+byte-identical; all 201 specs green.
+
+### Changed
+- **`PGN::Board`**: promoted the on-board bitmask test and square-name
+  lookup to public `on_board?(idx)` / `square_name(idx)` methods,
+  replacing private duplicates of the same logic in `MoveCalculator`.
+  Added a named `Board.from_cells(cells)` factory for building a board
+  directly from a 128-cell 0x88 array; `#dup` (called every move) now
+  routes through it instead of reaching around the constructor via
+  `Board.allocate` + `instance_variable_set` directly. Performance is
+  identical — same allocate + one ivar set — just a documented factory
+  instead of a reflective one-off.
+- **`PGN::MoveCalculator`**: calls `board.on_board?`/`board.square_name`
+  instead of its own private copies; named the castling-table square
+  literals (`C1`..`G8`) instead of raw 0x88 integers in `CASTLING`, for
+  readability. `#board`/`#move` are now `attr_reader` instead of
+  `attr_accessor` — there was no external writer, and the `@dest_idx`
+  memo already silently relied on both never changing after
+  `#initialize`; dropping the setters enforces that invariant in the
+  type instead of by convention.
+- **`PGN::Lexer`**: dropped the per-token `@line` counter (one
+  `str.count("\n")` via `advance_line` on every `next_token`/
+  `next_token_pair` call) in favor of a lazy `line_at(off)`, computed
+  only when a line number is actually needed (error messages, the spec
+  `tokens` helper) — the parser itself never reads it. Removes a
+  `str.count("\n")` call from the parse hot path (~6% of parse CPU for
+  a value that was never read).
+
+## 1.4.0 (2026-08-13)
 
 ### Summary
 

data/TODO.md

@@ -17,31 +17,45 @@
     `#tokens` spec helper. Parse allocations −42% (603537 → 347037 / 500 games).
 - Speed up replay via a board-representation rewrite ("Approach B"): done.
   (b) ✓ (done in 1.3.0) Rewrote `Board` internals to the classic 0x88
-    representation (128-cell array indexed by `rank*16+file`) and rewrote
-    `MoveCalculator` to work entirely in single-integer square indices via
-    `Board#at_index`/`#apply!`, so the replay hot path no longer allocates
-    `[file,rank]` coordinate arrays or square-name strings. Off-board is a
-    single bitmask (`(idx & 0x88).zero?`, ~1.6x faster than a 0..7 bounds
-    check) and ray stepping is a single integer add. Algorithm unchanged, so
-    output is byte-identical. Measured (immortal game): replay 798→535 µs/i
-    (+49% throughput), allocations 1571→976 objects (−38%) / 92440→62064 bytes
-    (−33%); parse+replay +21% throughput. 182 specs green, 0 new rubocop
-    offenses vs main. The public string/coord API is preserved (additive).
+  representation (128-cell array indexed by `rank*16+file`) and rewrote
+  `MoveCalculator` to work entirely in single-integer square indices via
+  `Board#at_index`/`#apply!`, so the replay hot path no longer allocates
+  `[file,rank]` coordinate arrays or square-name strings. Off-board is a
+  single bitmask (`(idx & 0x88).zero?`, ~1.6x faster than a 0..7 bounds
+  check) and ray stepping is a single integer add. Algorithm unchanged, so
+  output is byte-identical. Measured (immortal game): replay 798→535 µs/i
+  (+49% throughput), allocations 1571→976 objects (−38%) / 92440→62064 bytes
+  (−33%); parse+replay +21% throughput. 182 specs green, 0 new rubocop
+  offenses vs main. The public string/coord API is preserved (additive).
+  (c) One related idea was left alone during cleanup rather than "fixed",
+  since fixing it would cost more than it's worth right now: `Board#squares`
+  rebuilds the full 8x8 array from `@cells` on every call (9 allocations,
+  64 reads); it's off the replay hot path by design, but `FEN#to_s`
+  round-trips through it on every position-to-FEN call, so FEN generation
+  pays that cost repeatedly. Memoizing would mean invalidating the cache
+  from `update`/`apply!`, i.e. adding a write to the actual hot path to
+  speed up a path that isn't hot -- the wrong trade; if FEN generation
+  becomes hot, have it read `@cells` directly instead. Also considered
+  and not attempted: column-granularity copy-on-write in `dup` (the pre-0x88
+  Board only duplicated touched file-columns on write); the flat 0x88 array
+  trades that away for simplicity and the +49% throughput measured above,
+  and reintroducing it would need its own A/B before it's worth the
+  complexity.
   (a) ✗ (attempted, rejected) A piece-location index (piece → 0x88 indices)
-    maintained in `update`/`apply!` and used for O(1) slider/leaper/king
-    origin lookups. Implemented on top of (b), all 182 specs green, but it
-    **regressed**: replay 526→727 µs/i (+38% slower), allocations 976→1591
-    objects (+63%). Root cause: `Board#dup` (called every move) must clone
-    the index (`transform_values(&:dup)` ≈ 12 piece arrays) — Board#dup went
-    91→676 objects — and every move pays per-update index maintenance
-    (`<<`/`delete`) that pawns (the most common move type, whose origins are
-    geometry-fixed and can't use the index) pay for no benefit. The index
-    helps sliders/leapers (minority of moves) but the dup + maintenance cost
-    is paid by every move. Conclusion: a global piece index is a loss for
-    replay (where only ONE given move is validated, so ray-scanning from the
-    destination is already cheap); it pays in move-*generation* libraries
-    (chess.js/python-chess) that enumerate ALL legal moves. Not worth a COW
-    variant either (maintenance + pawns). Reverted; (b) alone is the winner.
+  maintained in `update`/`apply!` and used for O(1) slider/leaper/king
+  origin lookups. Implemented on top of (b), all 182 specs green, but it
+  **regressed**: replay 526→727 µs/i (+38% slower), allocations 976→1591
+  objects (+63%). Root cause: `Board#dup` (called every move) must clone
+  the index (`transform_values(&:dup)` ≈ 12 piece arrays) — Board#dup went
+  91→676 objects — and every move pays per-update index maintenance
+  (`<<`/`delete`) that pawns (the most common move type, whose origins are
+  geometry-fixed and can't use the index) pay for no benefit. The index
+  helps sliders/leapers (minority of moves) but the dup + maintenance cost
+  is paid by every move. Conclusion: a global piece index is a loss for
+  replay (where only ONE given move is validated, so ray-scanning from the
+  destination is already cheap); it pays in move-_generation_ libraries
+  (chess.js/python-chess) that enumerate ALL legal moves. Not worth a COW
+  variant either (maintenance + pawns). Reverted; (b) alone is the winner.
 - Replace the right-recursive `tag_section`/`variation_list` rules in
   `pgn_parser.y` with ordinary left-recursion plus one explicit `.reverse`
   at the point each list is consumed, so the legacy whittle-order
@@ -53,10 +67,3 @@
   to reuse as-is. The brace check is a bandaid for `clean_text` not fully
   normalizing multi-line/nested comments in one pass; fixing that at the
   source would let `moves=` reuse unconditionally.
-- `MoveCalculator#destination_coords` memoizes into `@dest_coords` based on
-  `board`/`move`/`origin` never changing after `#initialize` — true today,
-  but only by convention, since `board`, `move`, `origin` are all public
-  `attr_accessor`s with no cache invalidation tied to their setters. If a
-  future caller ever mutates and reuses a `MoveCalculator` instance, this
-  memo goes stale silently. Either drop the public setters or invalidate
-  `@dest_coords` when they're used.

data/lib/pgn/board.rb

@@ -27,10 +27,10 @@ module PGN
     ].freeze
 
     FILE_TO_INDEX = ('a'..'h').each_with_index.to_h
-    INDEX_TO_FILE = FILE_TO_INDEX.map(&:reverse).to_h
+    INDEX_TO_FILE = FILE_TO_INDEX.invert
 
     RANK_TO_INDEX = ('1'..'8').each_with_index.to_h
-    INDEX_TO_RANK = RANK_TO_INDEX.map(&:reverse).to_h
+    INDEX_TO_RANK = RANK_TO_INDEX.invert
 
     # algebraic to unicode piece lookup
     #
@@ -102,7 +102,6 @@ module PGN
           @cells[(r * 16) + f] = squares[f][r]
         end
       end
-      @cells
     end
 
     # @overload at(str)
@@ -119,9 +118,9 @@ module PGN
     #   board.at("e4") #=> "P"
     #
     def at(arg0, arg1 = nil)
-      return @cells[(arg1 * 16) + arg0] unless arg1.nil?
+      return at_index(index_for(arg0, arg1)) unless arg1.nil?
 
-      @cells[(rank_of(arg0) * 16) + file_of(arg0)]
+      at_index(index_of(arg0))
     end
 
     # @param changes [Hash<String, <String, nil>>] changes to make to the board
@@ -141,8 +140,7 @@ module PGN
     #   board.update("e4", "P")
     #
     def update(square, piece)
-      @cells[(rank_of(square) * 16) + file_of(square)] = piece
-      self
+      update_index(index_of(square), piece)
     end
 
     # @param position [String] the square in algebraic notation
@@ -173,13 +171,25 @@ module PGN
       end.join("\n")
     end
 
+    # Build a {Board} directly from a 0x88 cell array, bypassing the 8x8
+    # -> 0x88 conversion in {#initialize}. Used by {#dup} (which runs every
+    # move) to skip the per-square rebuild; the cell array is already in the
+    # canonical 128-cell layout.
+    #
+    # @param cells [Array<String, nil>] a 128-cell 0x88 array
+    # @return [PGN::Board]
+    #
+    def self.from_cells(cells)
+      board = allocate
+      board.instance_variable_set(:@cells, cells)
+      board
+    end
+
     # @return [PGN::Board] a copy of self. Copies the 128-cell 0x88 array;
     #   mutations to the copy do not affect the original.
     #
     def dup
-      copy = PGN::Board.allocate
-      copy.instance_variable_set(:@cells, @cells.dup)
-      copy
+      self.class.from_cells(@cells.dup)
     end
 
     # -- 0x88 hot-path API (integer indices) ---------------------------------
@@ -235,6 +245,25 @@ module PGN
       self
     end
 
+    # Whether a 0x88 index is on the board (see the class doc for the
+    # bitmask this tests).
+    #
+    # @param idx [Integer] a 0x88 square index
+    # @return [Boolean]
+    #
+    def on_board?(idx)
+      (idx & 0x88).zero? # rubocop:disable Style/BitwisePredicate
+    end
+
+    # The algebraic square name of a 0x88 index.
+    #
+    # @param idx [Integer] a 0x88 square index
+    # @return [String] e.g. "e4"
+    #
+    def square_name(idx)
+      INDEX_TO_FILE[idx & 0x0F] + INDEX_TO_RANK[idx >> 4]
+    end
+
     private
 
     def file_of(square)

data/lib/pgn/lexer.rb

@@ -161,7 +161,6 @@ module PGN
     def initialize(input)
       @input = input
       @ss = StringScanner.new(input)
-      @line = 1
       @game_starts = []
       @between_games = true # at start we are "between" games
     end
@@ -182,7 +181,8 @@ module PGN
       type, value = next_token_pair
       return nil unless type
 
-      Token.new(type: type, value: value, offset: @last_offset, line: @line)
+      Token.new(type: type, value: value, offset: @last_offset,
+                line: line_at(@last_offset))
     end
 
     # Fast path for the parser: returns [type, value] for the next
@@ -203,7 +203,6 @@ module PGN
         end
 
         value = scan_one
-        advance_line(value)
         next if @scan_discarded
 
         note_token(@scan_type, off)
@@ -231,7 +230,7 @@ module PGN
         return m
       end
       raise UnconsumedInputError,
-            "Unmatched input #{@input.byteslice(@ss.pos..).inspect} on line #{@line}"
+            "Unmatched input #{@input.byteslice(@ss.pos..).inspect} on line #{line_at(@ss.pos)}"
     end
 
     # Track per-game content-start offsets for verbatim pgn slicing.
@@ -246,8 +245,12 @@ module PGN
       end
     end
 
-    def advance_line(str)
-      @line += str.count("\n")
+    # Line number at a byte offset, computed lazily only for error messages
+    # and the spec `tokens` helper. Keeping a running `@line` on the parse hot
+    # path (one `str.count("\n")` per token) was ~6% of parse CPU for a value
+    # the parser never reads.
+    def line_at(off)
+      1 + @input.byteslice(0, off).count("\n")
     end
   end
 

data/lib/pgn/move_calculator.rb

@@ -30,7 +30,7 @@ module PGN
     # 0x88 single-step offsets for knight and king.
     #
     STEP = {
-      'k' => [-1, 1, -16, 16, -15, 15, -17, 17],
+      'k' => SLIDE['q'],
       'n' => [33, 31, -31, -33, 18, 14, -14, -18]
     }.freeze
 
@@ -42,15 +42,6 @@ module PGN
       'p' => { capture: [15, 17], normal: [16], double: [32] }
     }.freeze
 
-    # The squares to update for each castling move, keyed by 0x88 index.
-    #
-    CASTLING = {
-      'Q' => { 0 => nil, 2 => 'K', 3 => 'R', 4 => nil },
-      'K' => { 4 => nil, 5 => 'R', 6 => 'K', 7 => nil },
-      'q' => { 112 => nil, 114 => 'k', 115 => 'r', 116 => nil },
-      'k' => { 116 => nil, 117 => 'r', 118 => 'k', 119 => nil }
-    }.freeze
-
     # Corner-square 0x88 indices, used for castling-restriction bookkeeping
     # (a rook leaving or being captured on a corner drops the matching right).
     #
@@ -59,6 +50,29 @@ module PGN
     A8 = 112
     H8 = 119
 
+    # King/rook landing squares for castling, named for readability in
+    # {CASTLING} below.
+    #
+    C1 = 2
+    D1 = 3
+    E1 = 4
+    F1 = 5
+    G1 = 6
+    C8 = 114
+    D8 = 115
+    E8 = 116
+    F8 = 117
+    G8 = 118
+
+    # The squares to update for each castling move, keyed by 0x88 index.
+    #
+    CASTLING = {
+      'Q' => { A1 => nil, C1 => 'K', D1 => 'R', E1 => nil },
+      'K' => { E1 => nil, F1 => 'R', G1 => 'K', H1 => nil },
+      'q' => { A8 => nil, C8 => 'k', D8 => 'r', E8 => nil },
+      'k' => { E8 => nil, F8 => 'r', G8 => 'k', H8 => nil }
+    }.freeze
+
     # rook-origin (0x88 index) -> castling restriction it drops.
     #
     ROOK_RESTRICTIONS = { A1 => 'Q', H1 => 'K', A8 => 'q', H8 => 'k' }.freeze
@@ -69,14 +83,14 @@ module PGN
     WHITE_CASTLE = %w[K Q].freeze
     BLACK_CASTLE = %w[k q].freeze
 
-    attr_accessor :board, :move
+    attr_reader :board, :move
 
     # @param board [PGN::Board] the current board
     # @param move [PGN::Move] the current move
     #
     def initialize(board, move)
-      self.board = board
-      self.move  = move
+      @board = board
+      @move  = move
       @origin_idx = compute_origin
     end
 
@@ -87,7 +101,7 @@ module PGN
     def origin
       return nil if @origin_idx.nil?
 
-      board.position_for([@origin_idx & 0x0F, @origin_idx >> 4])
+      board.square_name(@origin_idx)
     end
 
     # @return [PGN::Board] the board after the move is made
@@ -215,7 +229,7 @@ module PGN
       possibilities = []
       offsets.each do |off|
         target = dest + off
-        next unless (target & 0x88).zero? # rubocop:disable Style/BitwisePredicate
+        next unless board.on_board?(target)
 
         possibilities << target if board.at_index(target) == move.piece
       end
@@ -250,7 +264,7 @@ module PGN
       return possibilities unless move.disambiguation
 
       possibilities.select do |idx|
-        board.position_for([idx & 0x0F, idx >> 4]).match(move.disambiguation)
+        board.square_name(idx).match(move.disambiguation)
       end
     end
 
@@ -290,7 +304,7 @@ module PGN
     #
     def first_piece(idx, off)
       idx += off
-      while (idx & 0x88).zero? # rubocop:disable Style/BitwisePredicate
+      while board.on_board?(idx)
         square = board.at_index(idx)
         return idx if square
 
@@ -315,7 +329,7 @@ module PGN
       return nil if move.castle
       return nil unless move.capture && board.at_index(dest_idx).nil?
 
-      (origin_rank * 16) + (dest_idx & 0x0F)
+      board.index_for(dest_idx & 0x0F, origin_rank)
     end
 
     def king_position
@@ -323,7 +337,7 @@ module PGN
 
       0.upto(7) do |rank|
         0.upto(7) do |file|
-          idx = (rank * 16) + file
+          idx = board.index_for(file, rank)
           return idx if board.at_index(idx) == king
         end
       end

data/lib/pgn/version.rb

@@ -1,3 +1,3 @@
 module PGN
-  VERSION = '1.4.0'.freeze
+  VERSION = '1.5.0'.freeze
 end

metadata

@@ -1,14 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: pgn2
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Stacey Touset
 - Murilo Vasconcelos
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-08-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -209,6 +210,7 @@ metadata:
   source_code_uri: https://github.com/muriloime/pgn
   bug_tracker_uri: https://github.com/muriloime/pgn/issues
   changelog_uri: https://github.com/muriloime/pgn/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -223,7 +225,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: A PGN parser for Ruby
 test_files: