pgn2 0.4.0 → 1.0.0

data/lib/pgn/pgn_parser.rb

@@ -0,0 +1,392 @@
+#
+# DO NOT MODIFY!!!!
+# This file is automatically generated by Racc 1.8.1
+# from Racc grammar file "pgn_parser.y".
+#
+
+require 'racc/parser.rb'
+module PGN
+  class PgnParser < Racc::Parser
+
+module_eval(<<'...end pgn_parser.y/module_eval...', 'pgn_parser.y', 91)
+
+  def parse(input)
+    @lexer = PGN::Lexer.new(input)
+    @input = input
+    games = do_parse
+    assign_pgn!(games)
+    games
+  end
+
+  def next_token
+    t = @lexer.next_token
+    return [false, false] unless t
+    [translate_type(t.type), t.value]
+  end
+
+  private
+
+  def translate_type(sym)
+    case sym
+    when :string           then :STRING
+    when :comment          then :COMMENT
+    when :game_termination  then :GAME_TERMINATION
+    when :san_move         then :SAN_MOVE
+    when :nag              then :NAG
+    when :move_number      then :MOVE_NUMBER
+    when :tag_name         then :TAG_NAME
+    when :lbracket         then '['
+    when :rbracket         then ']'
+    when :lparen           then '('
+    when :rparen           then ')'
+    else
+      raise "PGN::Lexer produced an unknown token type: #{sym.inspect}"
+    end
+  end
+
+  # Slice the verbatim raw PGN text per game out of the original input using
+  # the per-game content-start byte offsets recorded by the lexer.
+  #
+  # Game 0 spans from byte 0; game k (k >= 1) spans from its first
+  # non-discarded token's offset; each game ends where the next game begins
+  # (or at EOF for the last game). Leading/trailing discarded tokens (a
+  # game's leading `%` comment, or the whitespace between games) fold into
+  # the adjacent game's span, reproducing the legacy accumulator output.
+  def assign_pgn!(games)
+    starts = @lexer.game_starts
+    total  = @input.bytesize
+    games.each_with_index do |game, k|
+      start = (k == 0) ? 0 : starts[k]
+      fin   = (k + 1 < games.length) ? starts[k + 1] : total
+      game[:pgn] = @input.byteslice(start...fin)
+    end
+  end
+...end pgn_parser.y/module_eval...
+##### State transition tables begin ###
+
+racc_action_table = [
+     2,    16,     7,    17,    22,    14,     6,    24,    11,     6,
+    31,    16,    12,    17,    29,    14,    18,    30,    21,    25,
+    21,    24,    30 ]
+
+racc_action_check = [
+     1,    27,     2,    27,    17,    27,     5,    17,     6,     1,
+    27,     9,     9,     9,    23,     9,    11,    23,    15,    18,
+    20,    22,    28 ]
+
+racc_action_pointer = [
+   nil,     0,     2,   nil,   nil,    -3,     0,   nil,   nil,     8,
+   nil,    14,   nil,   nil,   nil,     7,   nil,     1,     9,   nil,
+     9,   nil,    15,    11,   nil,   nil,   nil,    -2,    16,   nil,
+   nil,   nil ]
+
+racc_action_default = [
+    -1,   -24,   -24,    -2,    -8,    -4,   -24,    32,    -3,   -24,
+    -5,   -24,    -7,    -9,   -10,   -11,   -13,   -14,   -24,   -12,
+   -21,    -8,   -15,   -16,   -19,    -6,   -22,   -24,   -18,   -17,
+   -20,   -23 ]
+
+racc_goto_table = [
+     9,    19,    23,     1,     4,     3,    26,    28,    10,     8,
+   nil,   nil,   nil,   nil,   nil,   nil,   nil,    27 ]
+
+racc_goto_check = [
+     6,     9,    10,     1,     3,     2,     9,    10,     3,     4,
+   nil,   nil,   nil,   nil,   nil,   nil,   nil,     6 ]
+
+racc_goto_pointer = [
+   nil,     3,     4,     3,     5,   nil,    -4,   nil,   nil,   -14,
+   -15,   nil ]
+
+racc_goto_default = [
+   nil,   nil,   nil,   nil,   nil,     5,   nil,    13,    15,   nil,
+   nil,    20 ]
+
+racc_reduce_table = [
+  0, 0, :racc_error,
+  0, 14, :_reduce_1,
+  2, 14, :_reduce_2,
+  2, 15, :_reduce_3,
+  1, 16, :_reduce_4,
+  2, 16, :_reduce_5,
+  4, 18, :_reduce_6,
+  2, 17, :_reduce_7,
+  0, 19, :_reduce_8,
+  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,
+  2, 21, :_reduce_16,
+  3, 21, :_reduce_17,
+  3, 21, :_reduce_18,
+  1, 23, :_reduce_19,
+  2, 23, :_reduce_20,
+  1, 22, :_reduce_21,
+  2, 22, :_reduce_22,
+  3, 24, :_reduce_23 ]
+
+racc_reduce_n = 24
+
+racc_shift_n = 32
+
+racc_token_table = {
+  false => 0,
+  :error => 1,
+  :STRING => 2,
+  :COMMENT => 3,
+  :GAME_TERMINATION => 4,
+  :SAN_MOVE => 5,
+  :NAG => 6,
+  :MOVE_NUMBER => 7,
+  :TAG_NAME => 8,
+  "[" => 9,
+  "]" => 10,
+  "(" => 11,
+  ")" => 12 }
+
+racc_nt_base = 13
+
+racc_use_result_var = true
+
+Racc_arg = [
+  racc_action_table,
+  racc_action_check,
+  racc_action_default,
+  racc_action_pointer,
+  racc_goto_table,
+  racc_goto_check,
+  racc_goto_default,
+  racc_goto_pointer,
+  racc_nt_base,
+  racc_reduce_table,
+  racc_token_table,
+  racc_shift_n,
+  racc_reduce_n,
+  racc_use_result_var ]
+Ractor.make_shareable(Racc_arg) if defined?(Ractor)
+
+Racc_token_to_s_table = [
+  "$end",
+  "error",
+  "STRING",
+  "COMMENT",
+  "GAME_TERMINATION",
+  "SAN_MOVE",
+  "NAG",
+  "MOVE_NUMBER",
+  "TAG_NAME",
+  "\"[\"",
+  "\"]\"",
+  "\"(\"",
+  "\")\"",
+  "$start",
+  "pgn_database",
+  "pgn_game",
+  "tag_section",
+  "movetext_section",
+  "tag_pair",
+  "element_sequence",
+  "element",
+  "san_move_annotated",
+  "variation_list",
+  "annotation_list",
+  "variation" ]
+Ractor.make_shareable(Racc_token_to_s_table) if defined?(Ractor)
+
+Racc_debug_parser = false
+
+##### State transition tables end #####
+
+# reduce 0 omitted
+
+module_eval(<<'.,.,', 'pgn_parser.y', 7)
+  def _reduce_1(val, _values, result)
+     result = []
+    result
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 8)
+  def _reduce_2(val, _values, result)
+     result = val[0] << val[1]
+    result
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 13)
+  def _reduce_3(val, _values, result)
+            result = val[1].pop
+        result = {
+          tags:    val[0],
+          result:  result,
+          moves:   val[1],
+          pgn:     nil,
+          comment: (@game_comment.tap { @game_comment = nil }),
+        }
+
+    result
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 24)
+  def _reduce_4(val, _values, result)
+     result = val[0]
+    result
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 27)
+  def _reduce_5(val, _values, result)
+            # Right-recursive with section.merge(pair) reproduces the legacy
+        # whittle parser's tag semantics exactly: reverse source insertion
+        # order, and first-occurrence-wins on duplicate keys. This keeps
+        # serialized tag order byte-compatible with the legacy behavior.
+        result = val[1].merge(val[0])
+
+    result
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 35)
+  def _reduce_6(val, _values, result)
+     result = { val[1] => val[2][1...-1] }
+    result
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 38)
+  def _reduce_7(val, _values, result)
+     result = val[0] << val[1]
+    result
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 41)
+  def _reduce_8(val, _values, result)
+     result = []
+    result
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 44)
+  def _reduce_9(val, _values, result)
+            result = val[1].nil? ? val[0] : val[0] << val[1]
+
+    result
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 48)
+  def _reduce_10(val, _values, result)
+     result = nil
+    result
+  end
+.,.,
+
+# reduce 11 omitted
+
+module_eval(<<'.,.,', 'pgn_parser.y', 52)
+  def _reduce_12(val, _values, result)
+            result = val[0]
+        result.variations = val[1]
+        result
+
+    result
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 58)
+  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
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 65)
+  def _reduce_14(val, _values, result)
+     result = MoveText.new(val[0])
+    result
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 66)
+  def _reduce_15(val, _values, result)
+     result = MoveText.new(val[0], nil, val[1])
+    result
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 67)
+  def _reduce_16(val, _values, result)
+     result = MoveText.new(val[0], val[1])
+    result
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 68)
+  def _reduce_17(val, _values, result)
+     result = MoveText.new(val[0], val[1], val[2])
+    result
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 69)
+  def _reduce_18(val, _values, result)
+     result = MoveText.new(val[0], val[2], val[1])
+    result
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 72)
+  def _reduce_19(val, _values, result)
+     result = [val[0]]
+    result
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 73)
+  def _reduce_20(val, _values, result)
+     result = val[0] << val[1]
+    result
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 76)
+  def _reduce_21(val, _values, result)
+     result = [val[0]]
+    result
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 79)
+  def _reduce_22(val, _values, result)
+            # Right-recursive prepend reproduces the legacy whittle parser's
+        # variation-order reversal on every parse. This keeps parsed-game
+        # serialization byte-compatible with the legacy behavior; the quirk
+        # can be fixed in a separate change.
+        result = val[1] << val[0]
+
+    result
+  end
+.,.,
+
+module_eval(<<'.,.,', 'pgn_parser.y', 87)
+  def _reduce_23(val, _values, result)
+     result = val[1]
+    result
+  end
+.,.,
+
+def _reduce_none(val, _values, result)
+  val[0]
+end
+
+  end   # class PgnParser
+end   # module PGN

data/lib/pgn/pgn_parser.y

@@ -0,0 +1,142 @@
+class PGN::PgnParser
+
+token STRING COMMENT GAME_TERMINATION SAN_MOVE NAG MOVE_NUMBER TAG_NAME
+
+rule
+
+  pgn_database:
+      /* empty */                         { result = [] }
+    | pgn_database pgn_game               { result = val[0] << val[1] }
+
+  pgn_game:
+      tag_section movetext_section
+      {
+        result = val[1].pop
+        result = {
+          tags:    val[0],
+          result:  result,
+          moves:   val[1],
+          pgn:     nil,
+          comment: (@game_comment.tap { @game_comment = nil }),
+        }
+      }
+
+  tag_section:
+      tag_pair                            { result = val[0] }
+    | tag_pair tag_section
+      {
+        # Right-recursive with section.merge(pair) reproduces the legacy
+        # whittle parser's tag semantics exactly: reverse source insertion
+        # order, and first-occurrence-wins on duplicate keys. This keeps
+        # serialized tag order byte-compatible with the legacy behavior.
+        result = val[1].merge(val[0])
+      }
+
+  tag_pair:
+      '[' TAG_NAME STRING ']'              { result = { val[1] => val[2][1...-1] } }
+
+  movetext_section:
+      element_sequence GAME_TERMINATION   { result = val[0] << val[1] }
+
+  element_sequence:
+      /* empty */                         { result = [] }
+    | element_sequence element
+      {
+        result = val[1].nil? ? val[0] : val[0] << val[1]
+      }
+
+  element:
+      MOVE_NUMBER                         { result = nil }
+    | san_move_annotated
+    | san_move_annotated variation_list
+      {
+        result = val[0]
+        result.variations = val[1]
+        result
+      }
+    | COMMENT
+      {
+        # 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
+      }
+
+  san_move_annotated:
+      SAN_MOVE                            { result = MoveText.new(val[0]) }
+    | SAN_MOVE COMMENT                    { result = MoveText.new(val[0], nil, val[1]) }
+    | SAN_MOVE annotation_list            { result = MoveText.new(val[0], val[1]) }
+    | SAN_MOVE annotation_list COMMENT    { result = MoveText.new(val[0], val[1], val[2]) }
+    | SAN_MOVE COMMENT annotation_list   { result = MoveText.new(val[0], val[2], val[1]) }
+
+  annotation_list:
+      NAG                                 { result = [val[0]] }
+    | annotation_list NAG                  { result = val[0] << val[1] }
+
+  variation_list:
+      variation                           { result = [val[0]] }
+    | variation variation_list
+      {
+        # Right-recursive prepend reproduces the legacy whittle parser's
+        # variation-order reversal on every parse. This keeps parsed-game
+        # serialization byte-compatible with the legacy behavior; the quirk
+        # can be fixed in a separate change.
+        result = val[1] << val[0]
+      }
+
+  variation:
+      '(' element_sequence ')'            { result = val[1] }
+
+---- inner
+
+  def parse(input)
+    @lexer = PGN::Lexer.new(input)
+    @input = input
+    games = do_parse
+    assign_pgn!(games)
+    games
+  end
+
+  def next_token
+    t = @lexer.next_token
+    return [false, false] unless t
+    [translate_type(t.type), t.value]
+  end
+
+  private
+
+  def translate_type(sym)
+    case sym
+    when :string           then :STRING
+    when :comment          then :COMMENT
+    when :game_termination  then :GAME_TERMINATION
+    when :san_move         then :SAN_MOVE
+    when :nag              then :NAG
+    when :move_number      then :MOVE_NUMBER
+    when :tag_name         then :TAG_NAME
+    when :lbracket         then '['
+    when :rbracket         then ']'
+    when :lparen           then '('
+    when :rparen           then ')'
+    else
+      raise "PGN::Lexer produced an unknown token type: #{sym.inspect}"
+    end
+  end
+
+  # Slice the verbatim raw PGN text per game out of the original input using
+  # the per-game content-start byte offsets recorded by the lexer.
+  #
+  # Game 0 spans from byte 0; game k (k >= 1) spans from its first
+  # non-discarded token's offset; each game ends where the next game begins
+  # (or at EOF for the last game). Leading/trailing discarded tokens (a
+  # game's leading `%` comment, or the whitespace between games) fold into
+  # the adjacent game's span, reproducing the legacy accumulator output.
+  def assign_pgn!(games)
+    starts = @lexer.game_starts
+    total  = @input.bytesize
+    games.each_with_index do |game, k|
+      start = (k == 0) ? 0 : starts[k]
+      fin   = (k + 1 < games.length) ? starts[k + 1] : total
+      game[:pgn] = @input.byteslice(start...fin)
+    end
+  end

data/lib/pgn/serializer.rb

@@ -0,0 +1,141 @@
+module PGN
+  # {PGN::Serializer} converts a {PGN::Game} into a canonical PGN string.
+  #
+  # Serialization is purely structural: it reads tags, moves, comments,
+  # annotations, variations, and result from the game and emits valid PGN
+  # without replaying any moves on a board. Move numbering state is seeded
+  # from `game.starting_position` so games starting from a FEN tag (e.g.
+  # with black to move) are numbered correctly.
+  #
+  # @see PGN::Game#to_pgn
+  #
+  class Serializer
+    # @param game [PGN::Game] the game to serialize
+    def initialize(game)
+      @game = game
+    end
+
+    # @return [String] a canonical PGN string ending with a trailing newline
+    def to_s
+      tag_section + "\n\n" + movetext_section + "\n"
+    end
+
+    private
+
+    # Tag section: one tag pair per line in the order of `game.tags`. If
+    # `tags` is nil or empty, synthesize a `[Result "..."]` tag so the output
+    # stays parseable by the current grammar (which requires at least one
+    # tag pair).
+    def tag_section
+      tags = @game.tags
+      if tags.nil? || tags.empty?
+        %([Result "#{result_token}"])
+      else
+        tags.map { |key, value| %([#{key} "#{escape_tag(value)}"]) }.join("\n")
+      end
+    end
+
+    # Movetext section: optional game comment, then the move line, then the
+    # result, all joined by spaces.
+    def movetext_section
+      tokens = []
+      if @game.comment && !@game.comment.empty?
+        tokens << "{ #{escape_comment(@game.comment)} }"
+      end
+      line = emit_line(@game.moves, starting_fullmove, starting_player)
+      tokens << line unless line.empty?
+      tokens << result_token
+      tokens.join(" ")
+    end
+
+    # The result token: the game's result if present and non-empty, else "*".
+    def result_token
+      (@game.result.nil? || @game.result.empty?) ? "*" : @game.result
+    end
+
+    # Emit a single line (mainline or variation) of movetext, tracking the
+    # numbering state described in the design spec.
+    def emit_line(moves, fullmove, player)
+      tokens = []
+      prev_player = nil
+      prev_had_extras = false
+
+      moves.each do |move|
+        if player == :white
+          tokens << "#{fullmove}."
+          tokens << move_token(move, fullmove, player)
+        else # black
+          need_number = prev_player.nil? || prev_had_extras || prev_player != :white
+          tokens << "#{fullmove}..." if need_number
+          tokens << move_token(move, fullmove, player)
+        end
+
+        prev_player = player
+        prev_had_extras = has_extras?(move)
+        fullmove += 1 if player == :black
+        player = opposite(player)
+      end
+
+      tokens.join(" ")
+    end
+
+    # A move token: notation plus trailing extras (annotation, comment,
+    # variations), joined by spaces. Variations are serialized recursively
+    # from the position *before* the move (the same fullmove/player).
+    def move_token(move, fullmove, player)
+      parts = [move.notation]
+      (move.annotation || []).each { |a| parts << a }
+      if move.comment && !move.comment.empty?
+        parts << "{ #{escape_comment(move.comment)} }"
+      end
+      (move.variations || []).each do |variation|
+        parts << "(#{emit_line(variation, fullmove, player)})"
+      end
+      parts.join(" ")
+    end
+
+    # Whether a move carries any annotation, comment, or variation.
+    def has_extras?(move)
+      (!move.annotation.nil? && !move.annotation.empty?) ||
+        (!move.comment.nil? && !move.comment.empty?) ||
+        (!move.variations.nil? && !move.variations.empty?)
+    end
+
+    def starting_fullmove
+      @game.starting_position.fullmove
+    end
+
+    def starting_player
+      @game.starting_position.player
+    end
+
+    def opposite(player)
+      player == :white ? :black : :white
+    end
+
+    # Escape backslashes and double quotes for a tag value. The block form of
+    # gsub is used so the replacement string is taken literally (gsub's
+    # string replacement would otherwise re-interpret backslashes).
+    def escape_tag(value)
+      value.to_s
+           .gsub("\\") { "\\\\" }
+           .gsub('"') { "\\\"" }
+    end
+
+    # Escape backslashes and braces for a comment body (block form, so the
+    # replacement string is taken literally — gsub's string replacement
+    # would otherwise re-interpret backslashes).
+    #
+    # Note: the current parser's `MoveText#clean_text` does not unescape,
+    # so comments containing literal braces (e.g. the `nested_comments.pgn`
+    # fixture) will not round-trip byte-for-byte until parser improvements
+    # (sub-project 3) add unescaping. This matches the design spec's
+    # acknowledged v1 limitation.
+    def escape_comment(text)
+      text.to_s
+          .gsub("\\") { "\\\\" }
+          .gsub("{") { "\\{" }
+          .gsub("}") { "\\}" }
+    end
+  end
+end

data/lib/pgn/version.rb

@@ -1,3 +1,3 @@
 module PGN
-  VERSION = '0.4.0'.freeze
+  VERSION = '1.0.0'.freeze
 end

data/lib/pgn.rb

@@ -3,8 +3,11 @@ require 'pgn/fen'
 require 'pgn/game'
 require 'pgn/move'
 require 'pgn/move_calculator'
+require 'pgn/lexer'
+require 'pgn/pgn_parser'
 require 'pgn/parser'
 require 'pgn/position'
+require 'pgn/serializer'
 require 'pgn/version'
 
 module PGN