pgn2 2.0.2 → 2.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fdc6dcb9543c25e2e1102902d031f9d733463780b6f5d16a1a4713c6cfe16b9
-  data.tar.gz: 051ba77cdb0e657909ef5a22c1470f229c883e2bcb70cbfd3b9dbfbb83e92b8e
+  metadata.gz: 26cc37d3385d1f5516a2cff916f3219198914295b2ea83b587f1a8a6ee267480
+  data.tar.gz: 7efabc9471ace989a11a48879fb496f3999d35dbb42b3c8c138bdc392beeb597
 SHA512:
-  metadata.gz: 3999930da7369748415bfb222108d436a64c67bf8e91c5b0d12d9dc5ab38f64c78f1e1e56abca9454ed8e1a215df0918d152e37b1271808d8e1962088029a0e7
-  data.tar.gz: 2dec3d79ee03350d252bd846a789b3b96091f6ec34cd788d60e267506c2837436659395472fef192f3aeec8290ef32e3f7bd235308062a1de12f1add0e110ab7
+  metadata.gz: 3622fadf7c7918121f2c3e6700d1bb4284d9a258d76f56a2b47d20813f7f837ad357ff45892e252da96b6c52694909241809f203b97872b5bdb3dbe5a2b33023
+  data.tar.gz: e3205c5033d63601f1a64e175e7e1799ab9c698e736d216e15408c4eb358851ba8bf415139bf66780dbc5bd559fde6468ca06cf81a29df056d50c6ba52f9b6b9

data/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 2.0.3 (2026-08-20)
+
+### Summary
+
+Parser fix: a move may now be followed by any number of comments, NAGs,
+and variations, in any order (PGN spec §3.2.5). Previously the grammar
+accepted only a single trailing comment before a variation, so common
+real-world annotations like `1... Kxh7 {a} {[%cal ...]} (20... Kf8)` raised
+`parse error on value "("` and whole files were skipped. No public API
+changes; `MoveText#comment` and `#variations` keep their existing shapes.
+
+### Changed
+
+- **`PGN::PgnParser` (grammar)** — replace the single-comment
+  `move_trailer` + separate `variation_list` with a `move_suffix` list of
+  `[:comment, c] | [:nags, a] | [:variation, v]` items folded onto the
+  move by the new `build_move` helper. Multiple comments on one move are
+  concatenated with a space (each cleaned individually); variations keep
+  the legacy reversed storage order so round-trip and serializer behavior
+  are unchanged.
+- **`PGN::MoveText.clean_text`** — extracted as a class method so the
+  parser can clean each trailing comment before merging; the instance
+  method delegates to it (behavior unchanged).
+
+### Fixed
+
+- Two (or more) comments before a variation no longer abort parsing.
+- A comment appearing after a variation now attaches to the move it
+  follows instead of becoming a stray game comment.
+- `PGN.parse` no longer mutates the caller's input string (it dups before
+  `force_encoding`), so frozen-string-literal callers no longer raise
+  FrozenError on the target Ruby.
+
+### Known issues
+
+- A lone backslash inside a comment that is not part of `\\`, `\{`, or
+  `\}` (e.g. `{/\Ba3#}`) still raises an "Unmatched input" lexer error;
+  the comment escape grammar remains stricter than the PGN spec.
+
+---
+
 ## 2.0.2 (2026-08-18)
 
 ### Summary

data/lib/pgn/game.rb

@@ -9,7 +9,7 @@ module PGN
     def initialize(notation, annotation = nil, comment = nil, variations = [])
       @notation = notation
       @annotation = annotation
-      @comment = clean_text(comment)
+      @comment = MoveText.clean_text(comment)
       @variations = variations
     end
 
@@ -34,16 +34,22 @@ module PGN
       san.include?('0') ? san.gsub('0', 'O') : san
     end
 
-    def clean_text(text)
+    # Strip the single outermost brace pair, then unescape \{ \} \\ so
+    # the internal representation is the raw comment body. {Serializer}
+    # re-escapes on output, so parse -> serialize -> parse is byte-stable.
+    # Exposed as a class method so the parser can clean each trailing comment
+    # individually before concatenating multiple comments on one move.
+    def self.clean_text(text)
       return unless text
 
-      # Strip the single outermost brace pair, then unescape \{ \} \\ so
-      # the internal representation is the raw comment body. {Serializer}
-      # re-escapes on output, so parse -> serialize -> parse is byte-stable.
       text = text[1..-2] if text.start_with?('{') && text.end_with?('}')
       text = text.gsub(/\\([\\{}])/, '\1')
       text.gsub(/\s+/, ' ').strip
     end
+
+    def clean_text(text)
+      MoveText.clean_text(text)
+    end
   end
 
   # {PGN::Game} holds all of the information about a game. It is either

data/lib/pgn/pgn_parser.rb

@@ -8,7 +8,7 @@ require 'racc/parser.rb'
 module PGN
   class PgnParser < Racc::Parser
 
-module_eval(<<'...end pgn_parser.y/module_eval...', 'pgn_parser.y', 96)
+module_eval(<<'...end pgn_parser.y/module_eval...', 'pgn_parser.y', 87)
 
   def parse(input)
     @lexer = PGN::Lexer.new(input)
@@ -29,6 +29,26 @@ module_eval(<<'...end pgn_parser.y/module_eval...', 'pgn_parser.y', 96)
 
   private
 
+  # Fold a move's trailing suffix (comments, NAGs, variations, in any
+  # order) onto a MoveText. Multiple comments are concatenated with a
+  # space after each is individually cleaned; NAGs are merged in order;
+  # variations are collected in source order and then reversed, preserving
+  # the legacy order the serializer and round-trip specs depend on.
+  def build_move(notation, suffix)
+    comment_parts = []
+    nags = nil
+    variations = []
+    suffix.each do |kind, payload|
+      case kind
+      when :comment   then comment_parts << MoveText.clean_text(payload)
+      when :nags       then nags = nags ? nags + payload : payload
+      when :variation  then variations << payload
+      end
+    end
+    comment = comment_parts.empty? ? nil : comment_parts.join(' ')
+    MoveText.new(notation, nags, comment, variations.reverse)
+  end
+
   # Punctuation tokens are racc'd by their literal character (taken from
   # PGN::Lexer::LITERAL_BYTES, the single source of truth for those
   # characters); everything else is racc'd by the upcased lexer symbol.
@@ -66,42 +86,44 @@ module_eval(<<'...end pgn_parser.y/module_eval...', 'pgn_parser.y', 96)
 ##### State transition tables begin ###
 
 racc_action_table = [
-     2,    16,     7,    17,    23,    14,     6,    25,    11,     6,
-    32,    16,    12,    17,    30,    14,    18,    31,    21,    26,
-    21,    25,    31 ]
+     2,    16,     7,    17,    21,    14,     6,    24,    21,     6,
+    30,    24,    25,    16,    12,    17,    25,    14,    11,    18,
+    26,    28 ]
 
 racc_action_check = [
-     1,    28,     2,    28,    17,    28,     4,    17,     6,     1,
-    28,    10,    10,    10,    24,    10,    11,    24,    15,    18,
-    19,    23,    29 ]
+     1,    29,     2,    29,    17,    29,     4,    17,    19,     1,
+    29,    19,    17,    10,    10,    10,    19,    10,     6,    11,
+    18,    22 ]
 
 racc_action_pointer = [
-   nil,     0,     2,   nil,    -3,   nil,     0,   nil,   nil,   nil,
-     8,    14,   nil,   nil,   nil,     7,   nil,     1,     9,     9,
-   nil,   nil,   nil,    15,    11,   nil,   nil,   nil,    -2,    16,
-   nil,   nil,   nil ]
+   nil,     0,     2,   nil,    -3,   nil,    10,   nil,   nil,   nil,
+    10,    17,   nil,   nil,   nil,   nil,   nil,     1,    10,     5,
+   nil,   nil,    15,   nil,   nil,   nil,   nil,   nil,   nil,    -2,
+   nil ]
 
 racc_action_default = [
-    -1,   -25,   -25,    -2,    -8,    -4,   -25,    33,    -3,    -5,
-   -25,   -25,    -7,    -9,   -10,   -11,   -13,   -14,   -25,   -12,
-   -22,    -8,   -15,   -16,   -17,   -20,    -6,   -23,   -25,   -19,
-   -18,   -21,   -24 ]
+    -1,   -23,   -23,    -2,    -8,    -4,   -23,    31,    -3,    -5,
+   -23,   -23,    -7,    -9,   -10,   -11,   -12,   -13,   -23,   -14,
+   -15,   -17,   -18,   -19,   -20,    -8,    -6,   -16,   -21,   -23,
+   -22 ]
 
 racc_goto_table = [
-    10,    24,    20,     1,     3,     5,    27,    29,     9,     4,
-     8,    19,    22,   nil,   nil,   nil,   nil,    28 ]
+    10,     5,     1,    20,     9,    27,     3,     4,     8,    19,
+   nil,   nil,   nil,   nil,   nil,   nil,   nil,   nil,   nil,   nil,
+   nil,    29 ]
 
 racc_goto_check = [
-     6,    11,    12,     1,     2,     5,    12,    11,     5,     3,
-     4,     9,    10,   nil,   nil,   nil,   nil,     6 ]
+     6,     5,     1,    10,     5,    10,     2,     3,     4,     9,
+   nil,   nil,   nil,   nil,   nil,   nil,   nil,   nil,   nil,   nil,
+   nil,     6 ]
 
 racc_goto_pointer = [
-   nil,     3,     3,     8,     6,     4,    -4,   nil,   nil,    -4,
-    -5,   -16,   -13 ]
+   nil,     2,     5,     6,     4,     0,    -4,   nil,   nil,    -8,
+   -14,   nil,   nil ]
 
 racc_goto_default = [
    nil,   nil,   nil,   nil,   nil,   nil,   nil,    13,    15,   nil,
-   nil,   nil,   nil ]
+   nil,    22,    23 ]
 
 racc_reduce_table = [
   0, 0, :racc_error,
@@ -116,23 +138,21 @@ racc_reduce_table = [
   2, 19, :_reduce_9,
   1, 20, :_reduce_10,
   1, 20, :_reduce_none,
-  2, 20, :_reduce_12,
-  1, 20, :_reduce_13,
-  1, 21, :_reduce_14,
-  2, 21, :_reduce_15,
-  1, 23, :_reduce_16,
+  1, 20, :_reduce_12,
+  1, 21, :_reduce_13,
+  2, 21, :_reduce_14,
+  1, 22, :_reduce_15,
+  2, 22, :_reduce_16,
   1, 23, :_reduce_17,
-  2, 23, :_reduce_18,
-  2, 23, :_reduce_19,
+  1, 23, :_reduce_18,
+  1, 23, :_reduce_19,
   1, 24, :_reduce_20,
   2, 24, :_reduce_21,
-  1, 22, :_reduce_22,
-  2, 22, :_reduce_23,
-  3, 25, :_reduce_24 ]
+  3, 25, :_reduce_22 ]
 
-racc_reduce_n = 25
+racc_reduce_n = 23
 
-racc_shift_n = 33
+racc_shift_n = 31
 
 racc_token_table = {
   false => 0,
@@ -193,8 +213,8 @@ Racc_token_to_s_table = [
   "element_sequence",
   "element",
   "san_move_annotated",
-  "variation_list",
-  "move_trailer",
+  "move_suffix",
+  "suffix_item",
   "annotation_list",
   "variation" ]
 Ractor.make_shareable(Racc_token_to_s_table) if defined?(Ractor)
@@ -293,101 +313,80 @@ module_eval(<<'.,.,', 'pgn_parser.y', 50)
 
 module_eval(<<'.,.,', 'pgn_parser.y', 54)
   def _reduce_12(val, _values, result)
-            result = val[0]
-        result.variations = val[1].reverse
-        result
+            # A standalone comment (not attached to a move) becomes the game
+        # comment; the last such comment in the game wins.
+        @game_comment = val[0]
+        result = nil
 
     result
   end
 .,.,
 
-module_eval(<<'.,.,', 'pgn_parser.y', 60)
+module_eval(<<'.,.,', 'pgn_parser.y', 61)
   def _reduce_13(val, _values, result)
-            # A standalone comment (not attached to a move) becomes the game
-        # comment; the last such comment in the game wins.
-        @game_comment = val[0]
-        result = nil
-
+     result = MoveText.new(val[0])
     result
   end
 .,.,
 
-module_eval(<<'.,.,', 'pgn_parser.y', 67)
+module_eval(<<'.,.,', 'pgn_parser.y', 62)
   def _reduce_14(val, _values, result)
-     result = MoveText.new(val[0])
+     result = build_move(val[0], val[1])
     result
   end
 .,.,
 
-module_eval(<<'.,.,', 'pgn_parser.y', 68)
+module_eval(<<'.,.,', 'pgn_parser.y', 70)
   def _reduce_15(val, _values, result)
-     result = MoveText.new(val[0], *val[1])
+     result = [val[0]]
     result
   end
 .,.,
 
-module_eval(<<'.,.,', 'pgn_parser.y', 72)
+module_eval(<<'.,.,', 'pgn_parser.y', 71)
   def _reduce_16(val, _values, result)
-     result = [nil, val[0]]
+     result = val[0] << val[1]
     result
   end
 .,.,
 
-module_eval(<<'.,.,', 'pgn_parser.y', 73)
+module_eval(<<'.,.,', 'pgn_parser.y', 74)
   def _reduce_17(val, _values, result)
-     result = [val[0], nil]
+     result = [:comment, val[0]]
     result
   end
 .,.,
 
-module_eval(<<'.,.,', 'pgn_parser.y', 74)
+module_eval(<<'.,.,', 'pgn_parser.y', 75)
   def _reduce_18(val, _values, result)
-     result = [val[0], val[1]]
+     result = [:nags, val[0]]
     result
   end
 .,.,
 
-module_eval(<<'.,.,', 'pgn_parser.y', 75)
+module_eval(<<'.,.,', 'pgn_parser.y', 76)
   def _reduce_19(val, _values, result)
-     result = [val[1], val[0]]
+     result = [:variation, val[0]]
     result
   end
 .,.,
 
-module_eval(<<'.,.,', 'pgn_parser.y', 78)
+module_eval(<<'.,.,', 'pgn_parser.y', 79)
   def _reduce_20(val, _values, result)
      result = [val[0]]
     result
   end
 .,.,
 
-module_eval(<<'.,.,', 'pgn_parser.y', 79)
+module_eval(<<'.,.,', 'pgn_parser.y', 80)
   def _reduce_21(val, _values, result)
      result = val[0] << val[1]
     result
   end
 .,.,
 
-module_eval(<<'.,.,', 'pgn_parser.y', 82)
+module_eval(<<'.,.,', 'pgn_parser.y', 83)
   def _reduce_22(val, _values, result)
-     result = [val[0]]
-    result
-  end
-.,.,
-
-module_eval(<<'.,.,', 'pgn_parser.y', 85)
-  def _reduce_23(val, _values, result)
-            # Left-recursive; the legacy variation-order reversal is applied as
-        # a single explicit `.reverse` where the list is consumed in
-        # {element}, instead of being implicit in recursion direction.
-        result = val[0] << val[1]
-
-    result
-  end
-.,.,
-
-module_eval(<<'.,.,', 'pgn_parser.y', 92)
-  def _reduce_24(val, _values, result)
      result = val[1]
     result
   end

data/lib/pgn/pgn_parser.y

@@ -50,12 +50,6 @@ rule
   element:
       MOVE_NUMBER                         { result = nil }
     | san_move_annotated
-    | san_move_annotated variation_list
-      {
-        result = val[0]
-        result.variations = val[1].reverse
-        result
-      }
     | COMMENT
       {
         # A standalone comment (not attached to a move) becomes the game
@@ -66,28 +60,25 @@ rule
 
   san_move_annotated:
       SAN_MOVE                            { result = MoveText.new(val[0]) }
-    | SAN_MOVE move_trailer                { result = MoveText.new(val[0], *val[1]) }
-
-  # [annotation_list, comment], in whichever order they followed the move.
-  move_trailer:
-      COMMENT                             { result = [nil, val[0]] }
-    | annotation_list                      { result = [val[0], nil] }
-    | annotation_list COMMENT              { result = [val[0], val[1]] }
-    | COMMENT annotation_list              { result = [val[1], val[0]] }
+    | SAN_MOVE move_suffix                { result = build_move(val[0], val[1]) }
+
+  # The trailing material after a move: any number of comments, NAGs, and
+  # variations, in any order (PGN spec §3.2.5). Each suffix item is tagged
+  # [:comment, c] | [:nags, a] | [:variation, v]; {build_move} folds them
+  # onto the MoveText. This generalizes the old single-comment move_trailer,
+  # which rejected two comments before a variation (`{a} {b} (...)`).
+  move_suffix:
+      suffix_item                        { result = [val[0]] }
+    | move_suffix suffix_item            { result = val[0] << val[1] }
+
+  suffix_item:
+      COMMENT                            { result = [:comment, val[0]] }
+    | annotation_list                    { result = [:nags, val[0]] }
+    | variation                          { result = [:variation, val[0]] }
 
   annotation_list:
-      NAG                                 { result = [val[0]] }
-    | annotation_list NAG                  { result = val[0] << val[1] }
-
-  variation_list:
-      variation                           { result = [val[0]] }
-    | variation_list variation
-      {
-        # Left-recursive; the legacy variation-order reversal is applied as
-        # a single explicit `.reverse` where the list is consumed in
-        # {element}, instead of being implicit in recursion direction.
-        result = val[0] << val[1]
-      }
+      NAG                                { result = [val[0]] }
+    | annotation_list NAG                 { result = val[0] << val[1] }
 
   variation:
       '(' element_sequence ')'            { result = val[1] }
@@ -113,6 +104,26 @@ rule
 
   private
 
+  # Fold a move's trailing suffix (comments, NAGs, variations, in any
+  # order) onto a MoveText. Multiple comments are concatenated with a
+  # space after each is individually cleaned; NAGs are merged in order;
+  # variations are collected in source order and then reversed, preserving
+  # the legacy order the serializer and round-trip specs depend on.
+  def build_move(notation, suffix)
+    comment_parts = []
+    nags = nil
+    variations = []
+    suffix.each do |kind, payload|
+      case kind
+      when :comment   then comment_parts << MoveText.clean_text(payload)
+      when :nags       then nags = nags ? nags + payload : payload
+      when :variation  then variations << payload
+      end
+    end
+    comment = comment_parts.empty? ? nil : comment_parts.join(' ')
+    MoveText.new(notation, nags, comment, variations.reverse)
+  end
+
   # Punctuation tokens are racc'd by their literal character (taken from
   # PGN::Lexer::LITERAL_BYTES, the single source of truth for those
   # characters); everything else is racc'd by the upcased lexer symbol.

data/lib/pgn/version.rb

@@ -1,3 +1,3 @@
 module PGN
-  VERSION = '2.0.2'.freeze
+  VERSION = '2.0.3'.freeze
 end

data/lib/pgn.rb

@@ -26,6 +26,10 @@ module PGN
   # @see http://www.chessclub.com/help/PGN-spec PGN Specification
   #
   def self.parse(pgn, encoding = Encoding::ISO_8859_1)
+    # Operate on a private copy so a frozen caller string is never mutated
+    # (force_encoding mutates its receiver; under frozen-string literals
+    # this would otherwise raise FrozenError on the target Ruby).
+    pgn = pgn.dup
     pgn.force_encoding(encoding) if encoding
 
     PGN::Parser.new.parse(pgn).map do |game|

data/spec/parser_explicit_spec.rb

@@ -176,12 +176,51 @@ RSpec.describe PGN, '.parse (racc parser)' do
     end
   end
 
+  describe 'move suffix (comments, NAGs, variations in any order)' do
+    it 'attaches two comments before a variation to the move' do
+      game = PGN.parse('[White "A"] 1. Bxh7+ Kxh7 {a} {b} (20... Kf8) 2. Ng5+ *').first
+      move = game.moves[1]
+      expect(move.notation).to eq('Kxh7')
+      expect(move.comment).to eq('a b')
+      expect(variations_as(move)).to eq([%w[Kf8]])
+    end
+
+    it 'attaches a comment after a variation to the same move' do
+      game = PGN.parse('[White "A"] 1. e4 (1... c5) {a} (2... f5) 2. Nf3 *').first
+      move = game.moves.first
+      expect(move.comment).to eq('a')
+      expect(variations_as(move).sort).to eq([%w[c5], %w[f5]].sort)
+    end
+
+    it 'merges an arbitrary mix of comments, NAGs, and variations' do
+      game = PGN.parse('[White "A"] 1. e4 {c1} $1 (1... d5) {c2} $2 *').first
+      move = game.moves.first
+      expect(move.comment).to eq('c1 c2')
+      expect(move.annotation).to eq(%w[$1 $2])
+      expect(variations_as(move)).to eq([%w[d5]])
+    end
+
+    it 'round-trips a multi-comment move through parse -> serialize -> parse' do
+      input = +"[White \"A\"]\n\n1. e4 {a} {b} (1... d5) *\n"
+      once = PGN.parse(input, Encoding::UTF_8).first.to_pgn
+      twice = PGN.parse(once, Encoding::UTF_8).first.to_pgn
+      expect(twice).to eq(once)
+    end
+  end
+
   describe 'pgn (verbatim raw text)' do
     it 'returns the verbatim text for a single game' do
       input = "[White \"A\"] 1. e4 1-0\n"
       expect(PGN.parse(input).first.pgn).to eq(input)
     end
 
+    it 'does not mutate a frozen input string' do
+      input = "[White \"A\"] 1. e4 1-0\n".freeze
+      expect { PGN.parse(input, Encoding::UTF_8) }.not_to raise_error
+      expect(input.encoding).to eq(Encoding::UTF_8)
+      expect(PGN.parse(input, Encoding::UTF_8).first.pgn).to eq(input)
+    end
+
     it 'partitions consecutive games contiguously' do
       input = "[White \"A\"] 1. e4 1-0\n\n[White \"B\"] 1. d4 0-1\n"
       games = PGN.parse(input)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgn2
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.0.3
 platform: ruby
 authors:
 - Stacey Touset
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-18 00:00:00.000000000 Z
+date: 2026-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys