pgn2 0.4.0 → 1.0.0

data/lib/pgn/lexer.rb

@@ -0,0 +1,201 @@
+# 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+/.freeze
+
+    # Discarded: a PGN "rest of line" comment beginning with `%`.
+    PGN_COMMENT = /% .*/.freeze
+
+    # 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.freeze
+
+    # 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.freeze
+
+    # Game termination marker.
+    GAME_TERMINATION = %r{
+      1-0       |    # white wins
+      0-1       |    # black wins
+      1\/2-1\/2 |    # draw
+      \*             # ?
+    }x.freeze
+
+    # 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.freeze
+
+    # A move number indication, e.g. `1.`, `12.`, `1...`.
+    MOVE_NUMBER = /[[:digit:]]+\.*/.freeze
+
+    # A tag name (letters, digits, underscores).
+    TAG_NAME = /[A-Za-z0-9_]+/.freeze
+
+    # A numeric annotation glyph (`$1`) or a punctuation annotation (`?!`,
+    # `!?`, `??`, ...).
+    NAG = /
+      \$\d+       | # dollar sign followed by an integer
+      [\?!][\?!]?   # support the most used annotations directly
+    /x.freeze
+
+    # 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).
+    RULES = [
+      [:wsp,              WSP,              true],   # discarded
+      [:pgn_comment,      PGN_COMMENT,      true],   # discarded
+      [:comment,          COMMENT,          false],
+      [:string,           STRING,           false],
+      [:game_termination, GAME_TERMINATION, false],
+      [:san_move,         SAN_MOVE,         false],
+      [:nag,              NAG,              false],
+      [:move_number,      MOVE_NUMBER,      false],
+      [:tag_name,         TAG_NAME,         false],
+    ].freeze.each(&:freeze)
+
+    # Single-character literals, matched by their byte 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
+      until @ss.eos?
+        off = @ss.pos
+
+        if (lit = LITERAL_BYTES[@input.getbyte(off)])
+          @ss.pos = off + 1
+          note_token(lit, off)
+          return Token.new(type: lit, value: @input.byteslice(off, 1),
+                           offset: off, line: @line)
+        end
+
+        type, value = scan_one
+        advance_line(value)
+        if type == :wsp || type == :pgn_comment
+          # discarded: keep looping without emitting
+          next
+        end
+        note_token(type, off)
+        return Token.new(type: type, value: value, offset: off, line: @line)
+      end
+      nil
+    end
+
+    private
+
+    # Try each terminal rule in order; return [type, matched_string] 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]
+        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,9 +95,13 @@ 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)

data/lib/pgn/move_calculator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module PGN
   # {PGN::MoveCalculator} is responsible for computing all of the ways that a
   # specific move changes the current position. This includes which squares on
@@ -80,9 +82,7 @@ module PGN
       }
     }.freeze
 
-    attr_accessor :board
-    attr_accessor :move
-    attr_accessor :origin
+    attr_accessor :board, :move, :origin
 
     # @param board [PGN::Board] the current board
     # @param move [PGN::Move] the current move
@@ -149,12 +149,12 @@ module PGN
     def en_passant_square
       return nil if move.castle
 
-      if move.pawn? && (origin[1].to_i - move.destination[1].to_i).abs == 2
-        if move.white?
-          origin[0] + '3'
-        else
-          origin[0] + '6'
-end
+      return unless move.pawn? && (origin[1].to_i - move.destination[1].to_i).abs == 2
+
+      if move.white?
+        "#{origin[0]}3"
+      else
+        "#{origin[0]}6"
       end
     end
 
@@ -260,7 +260,7 @@ end
         possibilities.select { |p| board.position_for(p).match(move.disambiguation) }
       else
         possibilities
-end
+      end
     end
 
     # A pawn can't move two spaces if there is a pawn in front of it.
@@ -270,17 +270,19 @@ end
         possibilities.reject { |p| board.position_for(p).match(/2|7/) }
       else
         possibilities
-end
+      end
     end
 
     # A piece can't move if it would result in a discovered check.
     #
     def disambiguate_discovered_check(possibilities)
+      king_pos = king_position
+
       DIRECTIONS.each do |attacking_piece, directions|
         attacking_piece = attacking_piece.upcase if move.black?
 
         directions.each do |dir|
-          piece, square = first_piece(king_position, dir)
+          piece, square = first_piece(king_pos, dir)
           next unless piece == move.piece && possibilities.include?(square)
 
           piece, = first_piece(square, dir)
@@ -298,7 +300,7 @@ end
       piece = nil
 
       while valid_square?(file += i, rank += j)
-        break if piece = board.at(file, rank)
+        break if (piece = board.at(file, rank))
       end
 
       [piece, [file, rank]]
@@ -316,18 +318,17 @@ end
     def king_position
       king = move.white? ? 'K' : 'k'
 
-      coords = nil
       0.upto(7) do |file|
         0.upto(7) do |rank|
-          coords = [file, rank] if board.at(file, rank) == king
+          return [file, rank] if board.at(file, rank) == king
         end
       end
 
-      coords
+      nil
     end
 
     def valid_square?(file, rank)
-      (0..7) === file && (0..7) === rank
+      (0..7).include?(file) && (0..7).include?(rank)
     end
 
     def destination_coords

data/lib/pgn/parser.rb

@@ -1,208 +1,28 @@
-require 'whittle'
+require 'pgn/pgn_parser'
 
 module PGN
-  # {PGN::Parser} uses the whittle gem to parse pgn files based on their
-  # context free grammar.
+  # {PGN::Parser} is the public entry point for parsing PGN text into a list
+  # of game hashes. It delegates to a concrete backend parser (currently the
+  # stdlib Racc + StringScanner parser {PGN::PgnParser}).
   #
-  class Parser < Whittle::Parser
-    def lex(input)
-      line   = 1
-      offset = 0
-      ending = input.length
-      @@pgn ||= ''
-      @@game_comment ||= nil
-
-      until offset == ending
-        next_token(input, offset, line).tap do |token|
-          if !token.nil?
-            token[:offset] = offset
-            line, token[:line] = token[:line], line
-            yield token unless token[:discarded]
-            @@pgn += token[:value]
-            offset += token[:value].length
-          else
-            raise Whittle::UnconsumedInputError,
-                  "Unmatched input #{input[offset..-1].inspect} on line #{line}"
-            # offset += 1
-          end
-        end
-      end
-
-      yield ({ name: :$end, line: line, value: nil, offset: offset })
+  # The +backend+ class attribute is retained so callers (tests, benchmarks)
+  # can substitute an alternative parser responding to +new.parse(pgn_string)+.
+  class Parser
+    class << self
+      # The backend parser class used by {.parse}.
+      # @return [Class]
+      attr_accessor :backend
     end
 
-    rule(wsp: /\s+/).skip!
-    rule(
-      pgn_comment: /\A% .*/x
-    ).skip!
-
-    rule('[')
-    rule(']')
-    rule('(')
-    rule(')')
+    # Default backend is the stdlib Racc + StringScanner parser.
+    self.backend = PGN::PgnParser
 
-    start(:pgn_database)
-
-    rule(:pgn_database) do |r|
-      r[].as { [] }
-      r[:pgn_comment, :pgn_database].as { |_title, db| db }
-      r[:pgn_database, :pgn_game].as { |database, game| database << game }
+    # @param input [String] the raw PGN text (already force-encoded by the
+    #   caller, e.g. via {PGN.parse}).
+    # @return [Array<Hash>] one Hash per game, with keys +:tags+, +:result+,
+    #   +:moves+, +:pgn+, +:comment+.
+    def parse(input)
+      self.class.backend.new.parse(input)
     end
-
-    rule(:pgn_game) do |r|
-      r[:tag_section, :movetext_section].as do |tags, moves|
-        old_pgn = @@pgn
-        @@pgn = ''
-        comment = @@game_comment
-        @@game_comment = nil
-        { tags: tags, result: moves.pop, moves: moves, pgn: old_pgn, comment: comment }
-      end
-    end
-
-    rule(:tag_section) do |r|
-      r[:tag_pair, :tag_section].as { |pair, section| section.merge(pair) }
-      r[:tag_pair]
-    end
-
-    rule(:tag_pair) do |r|
-      r['[', :tag_name, :tag_value, ']'].as { |_, a, b, _| { a => b } }
-    end
-
-    rule(:tag_value) do |r|
-      r[:string].as { |value| value[1...-1] }
-    end
-
-    rule(:movetext_section) do |r|
-      r[:element_sequence, :game_termination].as { |a, b| a << b }
-    end
-
-    rule(:element_sequence) do |r|
-      r[:element_sequence, :element].as do |sequence, element|
-        element.nil? ? sequence : sequence << element
-      end
-      r[].as { [] }
-    end
-
-    rule(:element) do |r|
-      r[:move_number_indication].as { nil }
-      r[:san_move_annotated]
-      r[:san_move_annotated, :variation_list].as do |move, variations|
-        move.variations = variations
-        move
-      end
-      r[:comment].as { |c| @@game_comment = c; nil }
-    end
-
-    rule(:san_move_annotated) do |r|
-      r[:san_move].as { |move| MoveText.new(move) }
-      r[:san_move, :comment].as do |move, comment|
-        MoveText.new(move, nil, comment)
-      end
-      r[:san_move, :annotation_list].as do |move, annotation|
-        MoveText.new(move, annotation)
-      end
-      r[:san_move, :annotation_list, :comment].as do |move, annotation, comment|
-        MoveText.new(move, annotation, comment)
-      end
-      r[:san_move, :comment, :annotation_list].as do |move, comment, annotation|
-        MoveText.new(move, annotation, comment)
-      end
-    end
-
-    rule(:annotation_list) do |r|
-      r[:annotation_list, :numeric_annotation_glyph].as do |sequence, element|
-        element.nil? ? sequence : sequence << element
-      end
-      r[:numeric_annotation_glyph].as { |v| [v] }
-    end
-
-    rule(:variation_list) do |r|
-      r[:variation, :variation_list].as do |variation, sequence|
-        sequence << variation
-      end
-      r[:variation].as { |v| [v] }
-    end
-
-    rule(:variation) do |r|
-      r['(', :element_sequence, ')'].as { |_, sequence, _| sequence }
-    end
-
-    rule(
-      string: /
-        "                          # beginning of string
-        (
-          [[:print:]&&[^\\"]] |    # printing characters except quote and backslash
-          \\\\                |    # escaped backslashes
-          \\"                      # escaped quotation marks
-        )*                         # zero or more of the above
-        "                          # end of string
-      /x
-    )
-
-    rule(
-      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
-    )
-
-    rule(
-      game_termination: %r{
-        1-0       |    # white wins
-        0-1       |    # black wins
-        1\/2-1\/2 |    # draw
-        \*             # ?
-      }x
-    )
-
-    rule(
-      move_number_indication: /
-        [[:digit:]]+\.*    # one or more digits followed by zero or more periods
-      /x
-    )
-
-    rule(
-      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
-                                            # and capture
-                                            # (Bd2, N4c3, Raxc1)
-          [a-h][1-8]?x[a-h][1-8]            # pawn captures
-        )
-        (
-          =[BNQR]                            # optional promotion (d8=Q)
-        )?
-        (
-          \+                            |    # check (g5+)
-          \#                                 # checkmate (Qe7#)
-        )?
-      }x
-    )
-
-    rule(
-      tag_name: /
-        [A-Za-z0-9_]+    # letters, digits and underscores only
-      /x
-    )
-
-    rule(
-      numeric_annotation_glyph: /
-        \$\d+       | # dollar sign followed by an integer from 0 to 255
-        [\?!][\?!]?   # support the most used annotations directly
-      /x
-    )
   end
 end