pgn2 1.5.0 → 2.0.1

data/lib/pgn/attack.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module PGN
+  # {PGN::Attack} is the single source of truth for square-attack queries on
+  # a {PGN::Board}. It factors the private attack logic that {PGN::Notation}
+  # previously duplicated, so {PGN::Position} (and other consumers) can ask
+  # "is this square attacked?" and "which squares attack this square?".
+  #
+  # Squares are 0x88 indices (see {PGN::Board}); on-board when
+  # `(idx & 0x88).zero?`. `color` is 'w' or 'b'.
+  module Attack
+    BISHOP_DIRS = [-15, 15, -17, 17].freeze
+    ROOK_DIRS = [-1, 1, -16, 16].freeze
+
+    # The 0x88 index of the `color` king on +board+, or nil if absent.
+    def self.king_idx(board, color)
+      king = color == 'w' ? 'K' : 'k'
+      (0...128).each do |idx|
+        next if idx.anybits?(0x88)
+
+        return idx if board.at_index(idx) == king
+      end
+      nil
+    end
+
+    # Whether +target+ (a 0x88 index) is attacked by any `color` piece.
+    def self.attacked?(board, target, color)
+      attackers(board, target, color).any?
+    end
+
+    # The algebraic squares of every `color` piece on +board+ that attacks
+    # +target+ (a 0x88 index), in no particular order.
+    def self.attackers(board, target, color)
+      pawn_attackers(board, target, color) +
+        knight_attackers(board, target, color) +
+        king_attackers(board, target, color) +
+        slider_attackers(board, target, color)
+    end
+
+    class << self
+      private
+
+      def pawn_attackers(board, target, color)
+        offs = color == 'w' ? [-15, -17] : [15, 17]
+        pawn = color == 'w' ? 'P' : 'p'
+        offs.each_with_object([]) do |off, a|
+          i = target + off
+          a << board.square_name(i) if i.nobits?(0x88) && board.at_index(i) == pawn
+        end
+      end
+
+      def knight_attackers(board, target, color)
+        knight = color == 'w' ? 'N' : 'n'
+        Board::KNIGHT_ATTACKS[target].each_with_object([]) do |i, a|
+          a << board.square_name(i) if board.at_index(i) == knight
+        end
+      end
+
+      def king_attackers(board, target, color)
+        king = color == 'w' ? 'K' : 'k'
+        Board::KING_ATTACKS[target].each_with_object([]) do |i, a|
+          a << board.square_name(i) if board.at_index(i) == king
+        end
+      end
+
+      def slider_attackers(board, target, color)
+        bishop = color == 'w' ? 'B' : 'b'
+        rook = color == 'w' ? 'R' : 'r'
+        queen = color == 'w' ? 'Q' : 'q'
+        squares = []
+        ray_attackers(board, target, BISHOP_DIRS) do |piece, sq|
+          squares << sq if piece == bishop || piece == queen
+        end
+        ray_attackers(board, target, ROOK_DIRS) do |piece, sq|
+          squares << sq if piece == rook || piece == queen
+        end
+        squares
+      end
+
+      # Walk each ray from +target+; yield the first piece hit on that ray
+      # along with its square.
+      def ray_attackers(board, target, dirs)
+        dirs.each do |off|
+          i = target + off
+          while i.nobits?(0x88)
+            piece = board.at_index(i)
+            if piece
+              yield(piece, board.square_name(i))
+              break
+            end
+            i += off
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pgn/bitboard.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Load the chessie-backed native bitboard engine if the compiled
+# extension is available. End users get the precompiled native gem (no
+# Rust toolchain needed); if the extension is absent (e.g. running from a
+# source checkout without `rake compile`), the load fails silently so
+# the rest of the gem still works. Code that calls PGN::Bitboard::Engine
+# will raise NameError naturally.
+begin
+  require 'pgn2_native/pgn2_native'
+rescue StandardError
+  LoadError
+end

data/lib/pgn/board.rb

@@ -32,6 +32,31 @@ module PGN
     RANK_TO_INDEX = ('1'..'8').each_with_index.to_h
     INDEX_TO_RANK = RANK_TO_INDEX.invert
 
+    # 0x88 knight offsets (a1 + 33 = b3, etc.).
+    KNIGHT_OFFS = [33, 31, -31, -33, 18, 14, -14, -18].freeze
+    KING_OFFS = [-1, 1, -16, 16, -15, 15, -17, 17].freeze
+
+    # Precomputed on-board attack masks: entry `idx` is the frozen Array of
+    # on-board 0x88 target indices reachable from `idx` by that piece. Built
+    # once at load time so the per-call offset + off-board test is replaced by
+    # a direct array iteration.
+    KNIGHT_ATTACKS = Array.new(128) do |idx|
+      next nil if (idx & 0x88) != 0 # rubocop:disable Style/BitwisePredicate
+
+      KNIGHT_OFFS.each_with_object([]) do |off, a|
+        t = idx + off
+        a << t if (t & 0x88).zero? # rubocop:disable Style/BitwisePredicate
+      end.freeze
+    end.freeze
+    KING_ATTACKS = Array.new(128) do |idx|
+      next nil if (idx & 0x88) != 0 # rubocop:disable Style/BitwisePredicate
+
+      KING_OFFS.each_with_object([]) do |off, a|
+        t = idx + off
+        a << t if (t & 0x88).zero? # rubocop:disable Style/BitwisePredicate
+      end.freeze
+    end.freeze
+
     # algebraic to unicode piece lookup
     #
     UNICODE_PIECES = {
@@ -264,6 +289,45 @@ module PGN
       INDEX_TO_FILE[idx & 0x0F] + INDEX_TO_RANK[idx >> 4]
     end
 
+    # Serializes the board to the FEN board-string portion (ranks 8→1,
+    # files a→h, runs of empty squares collapsed to a digit) by walking
+    # the 0x88 `@cells` array directly. This avoids rebuilding the 8x8
+    # `squares` array on every FEN generation.
+    #
+    # @return [String] e.g. "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR"
+    def fen_board_string
+      rows = []
+      7.downto(0) do |rank|
+        s = String.new
+        run = 0
+        0.upto(7) do |file|
+          piece = @cells[(rank * 16) + file]
+          if piece.nil?
+            run += 1
+          else
+            s << run.to_s if run.positive?
+            run = 0
+            s << piece
+          end
+        end
+        s << run.to_s if run.positive?
+        rows << s
+      end
+      rows.join('/')
+    end
+
+    # Boards are equal when every cell holds the same piece (or is
+    # empty), including off-board padding, which is always nil on both.
+    def eql?(other)
+      other.is_a?(Board) && cells == other.cells
+    end
+
+    alias == eql?
+
+    protected
+
+    attr_reader :cells
+
     private
 
     def file_of(square)

data/lib/pgn/epd.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module PGN
+  # {PGN::EPD} translates between strings in Extended Position Description
+  # and a {PGN::Position}. EPD is the FEN-like position format used by
+  # {http://www.chessprogramming.org/Extended_Position_Description EPD tools}:
+  # it shares FEN's first four fields (piece placement, side to move,
+  # castling availability, en passant target square) and then carries a
+  # trailing list of operations (`ops`) instead of the halfmove/fullmove
+  # counters.
+  #
+  # @example
+  #   PGN::EPD.new('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -')
+  #   PGN::FEN.start.to_epd #=> "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -"
+  #
+  class EPD
+    attr_accessor :board, :active, :ops
+    attr_reader :castling, :en_passant
+
+    # @param epd_string [String] an EPD string: four FEN fields followed by
+    #   zero or more operation fields (kept verbatim as {#ops}).
+    #
+    def initialize(epd_string = nil)
+      return unless epd_string
+
+      fields = epd_string.split(' ', 5)
+      self.board_string = fields[0]
+      self.active = fields[1]
+      self.castling = fields[2]
+      self.en_passant = fields[3]
+      self.ops = fields[4]
+    end
+
+    def castling=(val)
+      @castling = val.nil? || val.empty? ? '-' : val
+    end
+
+    def en_passant=(val)
+      @en_passant = val.nil? ? '-' : val
+    end
+
+    # @param board_fen [String] the FEN/EPD representation of the board
+    #
+    def board_string=(board_fen)
+      squares = board_fen.gsub(/\d/) { |match| '_' * match.to_i }
+                         .split('/')
+                         .map(&:chars)
+                         .map { |row| row.map { |e| e == '_' ? nil : e } }
+                         .reverse
+                         .transpose
+      self.board = PGN::Board.new(squares)
+    end
+
+    # @return [String] the EPD board-string portion
+    #
+    def board_string
+      board.fen_board_string
+    end
+
+    # @return [PGN::Position] a {PGN::Position} for this EPD. Halfmove and
+    #   fullmove default to 0 and 1 (EPD does not carry them).
+    #
+    def to_position
+      player = active == 'w' ? :white : :black
+      castling_rights = castling.chars - ['-']
+      ep = en_passant == '-' ? nil : en_passant
+
+      PGN::Position.new(board, player, castling_rights, ep, 0, 1)
+    end
+
+    # @return [String] the EPD string (four fields, then +ops+ if present)
+    #
+    def to_s
+      [board_string, active, castling, en_passant, ops].compact.reject(&:empty?).join(' ')
+    end
+
+    def inspect
+      to_s
+    end
+  end
+end

data/lib/pgn/fen.rb

@@ -37,9 +37,13 @@ module PGN
   class FEN
     # The FEN string representing the starting position in chess
     #
-    INITIAL = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
+    INITIAL = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'.freeze
 
-    attr_accessor :board, :active, :castling, :en_passant, :halfmove, :fullmove
+    attr_accessor :board, :active, :halfmove, :fullmove
+    # `castling` and `en_passant` have custom writers below (normalize nil/empty
+    # to '-'), so expose readers here and define the writers explicitly to avoid
+    # redefining the accessors generated by attr_accessor (Lint/DuplicateMethods).
+    attr_reader :castling, :en_passant
 
     # @return [PGN::FEN] a {PGN::FEN} object representing the starting
     #   position
@@ -61,22 +65,22 @@ module PGN
     # @param fen_string [String] a string in Forsyth-Edwards Notation
     #
     def initialize(fen_string = nil)
-      if fen_string
-        self.board_string,
-          self.active,
-          self.castling,
-          self.en_passant,
-          self.halfmove,
-          self.fullmove = fen_string.split
-      end
+      return unless fen_string
+
+      self.board_string,
+        self.active,
+        self.castling,
+        self.en_passant,
+        self.halfmove,
+        self.fullmove = fen_string.split
     end
 
     def en_passant=(val)
-      @en_passant = val.nil? ? "-" : val
+      @en_passant = val.nil? ? '-' : val
     end
 
     def castling=(val)
-      @castling = (val.nil? || val.empty?) ? "-" : val
+      @castling = val.nil? || val.empty? ? '-' : val
     end
 
     # @param board_fen [String] the fen representation of the board
@@ -84,10 +88,10 @@ module PGN
     #   fen.board_string = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR"
     #
     def board_string=(board_fen)
-      squares = board_fen.gsub(/\d/) {|match| "_" * match.to_i }
-                         .split("/")
-                         .map {|row| row.split('') }
-                         .map {|row| row.map {|e| e == "_" ? nil : e } }
+      squares = board_fen.gsub(/\d/) { |match| '_' * match.to_i }
+                         .split('/')
+                         .map(&:chars)
+                         .map { |row| row.map { |e| e == '_' ? nil : e } }
                          .reverse
                          .transpose
       self.board = PGN::Board.new(squares)
@@ -98,59 +102,51 @@ module PGN
     #   PGN::FEN.start.board_string #=> "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR"
     #
     def board_string
-      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("/")
+      board.fen_board_string
     end
 
     # @return [PGN::Position] a {PGN::Position} representing the current
     #   position
     #
     def to_position
-      player     = self.active == 'w' ? :white : :black
-      castling   = self.castling.split('') - ['-']
-      en_passant = self.en_passant == '-' ? nil : en_passant
+      player     = active == 'w' ? :white : :black
+      castling   = self.castling.chars - ['-']
+      en_passant = self.en_passant == '-' ? nil : self.en_passant
 
       PGN::Position.new(
-        self.board,
+        board,
         player,
         castling,
         en_passant,
-        self.halfmove.to_i,
-        self.fullmove.to_i,
+        halfmove.to_i,
+        fullmove.to_i
       )
     end
 
+    # @return [String] the EPD string for this position (the first four FEN
+    #   fields, dropping the halfmove/fullmove counters)
+    #
+    def to_epd
+      PGN::EPD.new("#{board_string} #{active} #{castling} #{en_passant}").to_s
+    end
+
     # @return [String] the FEN string
     # @example
     #   PGN::FEN.start.to_s #=> "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
     #
     def to_s
       [
-        self.board_string,
-        self.active,
-        self.castling,
-        self.en_passant,
-        self.halfmove,
-        self.fullmove,
-      ].join(" ")
+        board_string,
+        active,
+        castling,
+        en_passant,
+        halfmove,
+        fullmove
+      ].join(' ')
     end
 
     def inspect
-      self.to_s
+      to_s
     end
   end
 end

data/lib/pgn/game.rb

@@ -30,7 +30,14 @@ module PGN
     end
 
     def clean_text(text)
-      text&.gsub(/{(.*)}/, '\1')&.gsub(/\s+/, ' ')&.strip
+      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
   end
 
@@ -106,16 +113,25 @@ module PGN
     # @return [Array<PGN::Position>] list of the {PGN::Position}s in the game
     #
     def positions
-      @positions ||= begin
-        position = starting_position
-        arr = [position]
-        moves.each do |move|
-          new_pos = position.move(move.notation)
-          arr << new_pos
-          position = new_pos
-        end
-        arr
+      @positions ||= each_position.to_a
+    end
+
+    # @return [Enumerator, self] with a block: yields each {PGN::Position}
+    #   in order (starting position, then one per move) and returns self.
+    #   Without a block: returns an Enumerator that yields the same.
+    #
+    # The replay loop is shared with {#positions} so eager and lazy paths
+    # produce identical position objects in identical order.
+    def each_position
+      return enum_for(:each_position) unless block_given?
+
+      position = starting_position
+      yield position
+      moves.each do |move|
+        position = position.move(move.notation)
+        yield position
       end
+      self
     end
 
     # @return [Array<String>] list of the fen representations of the positions
@@ -124,6 +140,70 @@ module PGN
       positions.map { |p| p.to_fen.inspect }
     end
 
+    # The current {PGN::Position} (the last position after replaying all
+    # moves), or the starting position when there are no moves.
+    #
+    # @return [PGN::Position]
+    def current_position
+      positions.last
+    end
+
+    # Append a move in SAN, validating legality when the native engine is
+    # available. Raises ArgumentError for an illegal move (when the engine is
+    # loaded) and invalidates the memoized position list.
+    #
+    # @param san [String, PGN::MoveText] the move to append
+    # @return [self]
+    def push(san)
+      move = standardize_castling(san)
+      if PGN::Bitboard.const_defined?(:Engine, false) && !current_position.legal?(move.notation)
+        raise ArgumentError, "illegal move: #{san}"
+      end
+
+      @moves << move
+      @positions = nil
+      self
+    end
+
+    # Remove and return the last move, or nil if there are none. Invalidates
+    # the memoized position list.
+    #
+    # @return [PGN::MoveText, nil]
+    def pop
+      return nil if @moves.empty?
+
+      move = @moves.pop
+      @positions = nil
+      move
+    end
+
+    # Whether any position has occurred three times in this game (the
+    # threefold-repetition draw). Uses {PGN::Position#hash} (the Zobrist
+    # hash of the FEN-relevant state), streaming {#each_position} so the
+    # full position array need not be materialized for this check.
+    #
+    # @return [Boolean]
+    def threefold?
+      counts = Hash.new(0)
+      each_position { |position| counts[position.hash] += 1 }
+      counts.any? { |_, count| count >= 3 }
+    end
+
+    # The terminal status of the game: :checkmate, :stalemate, or :draw
+    # (insufficient material, 50-move rule, or threefold repetition). nil
+    # if the game is still in progress. Requires the native extension for
+    # checkmate/stalemate detection.
+    #
+    # @return [Symbol, nil]
+    def outcome
+      final = positions.last
+      result = final&.outcome
+      return result if result
+      return :draw if threefold?
+
+      nil
+    end
+
     # Interactively step through the game
     #
     # Use +d+ to move forward, +a+ to move backward, and +^C+ to exit.
@@ -148,19 +228,27 @@ module PGN
       end
     end
 
+    # Build a fresh, navigable {PGN::Node} tree over the mainline. The tree
+    # is a live view of the underlying +MoveText+ structure; mutate it
+    # through the node API, then call +#root+ again for a fresh tree.
+    def root
+      PGN::Node.new(
+        move: nil, parent: nil, line: @moves, index: -1,
+        starting_position: starting_position, game: self
+      )
+    end
+
     private
 
     # A MoveText is reused as-is (no new object) when its notation needs no
-    # '0'->'O' fix and its comment has no braces left to clean; a braced
-    # comment still needs MoveText.new's second clean_text pass to match the
-    # legacy whittle byte-output.
+    # '0'->'O' fix; otherwise a new MoveText is built. clean_text is idempotent
+    # (it only strips a *single* outermost brace pair), so reusing or rebuilding
+    # a MoveText never corrupts a comment that still contains inner braces.
     def standardize_castling(entry)
       return MoveText.new(entry.include?('0') ? entry.gsub('0', 'O') : entry) if entry.is_a?(String)
 
       notation = entry.notation.include?('0') ? entry.notation.gsub('0', 'O') : entry.notation
-      if notation.equal?(entry.notation) && (entry.comment.nil? || !entry.comment.include?('{'))
-        return entry
-      end
+      return entry if notation.equal?(entry.notation)
 
       MoveText.new(notation, entry.annotation, entry.comment, entry.variations)
     end

data/lib/pgn/move.rb

@@ -57,8 +57,12 @@ module PGN
   #
 
   class Move
-    attr_accessor :san, :player
-    attr_accessor :piece, :destination, :promotion, :check, :capture, :disambiguation, :castle
+    attr_accessor :san, :player, :destination, :check
+    # piece/promotion/capture/disambiguation/castle have custom writers below
+    # (color normalization, nil-coalescing, etc.), so expose only readers here
+    # to avoid redefining attr_accessor setters (Lint/DuplicateMethods).
+    attr_reader :piece, :promotion, :capture, :disambiguation, :castle
+
     # A regular expression for matching moves in standard algebraic
     # notation
     #
@@ -70,7 +74,7 @@ module PGN
       (?<capture>        x            ){0}
       (?<disambiguation> [a-h]?[1-8]? ){0}
 
-      (?<castle>         O-O(-O)?     ){0}
+      (?<castle>         [O0]-[O0](?:-[O0])? ){0}
 
       (?<normal>
         \g<piece>?
@@ -80,8 +84,8 @@ module PGN
         \g<promotion>?
       ){0}
 
-      \A (\g<castle> | \g<normal>) \g<check>? \z
-    /x.freeze
+      \A (?:\g<castle> | \g<normal>) \g<check>? \z
+    /x
 
     # @param move [String] the move in SAN
     # @param player [Symbol] the player making the move
@@ -108,17 +112,17 @@ module PGN
       # 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')
+      return if san.start_with?('O') || san.start_with?('0')
 
       val ||= 'P'
       @piece = black? ? val.downcase : val
     end
 
     def promotion=(val)
-      if val
-        val.downcase! if black?
-        @promotion = val.delete('=')
-      end
+      return unless val
+
+      val.downcase! if black?
+      @promotion = val.delete('=')
     end
 
     def capture=(val)
@@ -130,11 +134,11 @@ module PGN
     end
 
     def castle=(val)
-      if val
-        @castle = 'K' if val == 'O-O'
-        @castle = 'Q' if val == 'O-O-O'
-        @castle.downcase! if black?
-      end
+      return unless val
+
+      @castle = 'K' if %w[O-O 0-0].include?(val)
+      @castle = 'Q' if %w[O-O-O 0-0-0].include?(val)
+      @castle.downcase! if black?
     end
 
     # @return [Boolean] whether the move results in check
@@ -164,7 +168,7 @@ module PGN
     # @return [Boolean] whether the piece being moved is a pawn
     #
     def pawn?
-      piece == 'P' || piece == 'p'
+      %w[P p].include?(piece)
     end
   end
 end

data/lib/pgn/move_calculator.rb

@@ -191,7 +191,7 @@ module PGN
 
       possibilities = case move.piece
                       when 'B', 'R', 'Q', 'b', 'r', 'q' then direction_origins
-                      when 'K', 'N', 'k', 'n' then move_origins
+                      when 'K', 'N', 'k', 'n' then leaper_origins
                       when 'P', 'p' then pawn_origins
                       else # don't care move, used in variations
                         return nil
@@ -237,6 +237,18 @@ module PGN
       possibilities
     end
 
+    # Knight/king origins use the precomputed on-board attack masks on
+    # {PGN::Board}, skipping the per-call off-board test.
+    def leaper_origins
+      dest  = dest_idx
+      mask  = move.piece.upcase == 'N' ? Board::KNIGHT_ATTACKS[dest] : Board::KING_ATTACKS[dest]
+      piece = move.piece
+
+      possibilities = []
+      mask.each { |t| possibilities << t if board.at_index(t) == piece }
+      possibilities
+    end
+
     # Computes the possible pawn origins based on the destination square
     # and whether or not the move is a capture.
     #