pgn2 2.0.0 → 2.0.2

data/lib/pgn/fen.rb

@@ -1,4 +1,44 @@
 module PGN
+  # Shared FEN/EPD board-field parsing and serialization: the piece-placement
+  # field, and the '-'-normalized castling/en-passant fields. {PGN::FEN} and
+  # {PGN::EPD} both include this rather than each carrying their own copy.
+  module PositionFields
+    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 FEN/EPD board-string portion
+    def board_string
+      board.fen_board_string
+    end
+
+    private
+
+    # The player/castling-rights/en-passant args shared by FEN#to_position
+    # and EPD#to_position (which differ only in halfmove/fullmove).
+    def position_fields
+      player = active == 'w' ? :white : :black
+      castling_rights = castling.chars - ['-']
+      ep = en_passant == '-' ? nil : en_passant
+      [player, castling_rights, ep]
+    end
+  end
+
   # {PGN::FEN} is responsible for translating between strings in FEN
   # notation and an internal representation of the board.
   #
@@ -35,14 +75,17 @@ module PGN
   #     plays.
   #
   class FEN
+    include PositionFields
+
     # The FEN string representing the starting position in chess
     #
     INITIAL = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'.freeze
 
     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).
+    # `castling` and `en_passant` have custom writers in {PositionFields}
+    # (normalize nil/empty to '-'), so expose readers here and rely on the
+    # module for the writers, 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
@@ -75,52 +118,19 @@ module PGN
         self.fullmove = fen_string.split
     end
 
-    def en_passant=(val)
-      @en_passant = val.nil? ? '-' : val
-    end
-
-    def castling=(val)
-      @castling = val.nil? || val.empty? ? '-' : val
-    end
-
-    # @param board_fen [String] the fen representation of the board
-    # @example
-    #   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(&:chars)
-                         .map { |row| row.map { |e| e == '_' ? nil : e } }
-                         .reverse
-                         .transpose
-      self.board = PGN::Board.new(squares)
-    end
-
-    # @return [String] the fen representation of the board
-    # @example
-    #   PGN::FEN.start.board_string #=> "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR"
-    #
-    def board_string
-      board.fen_board_string
-    end
-
     # @return [PGN::Position] a {PGN::Position} representing the current
     #   position
     #
     def to_position
-      player     = active == 'w' ? :white : :black
-      castling   = self.castling.chars - ['-']
-      en_passant = nil if self.en_passant == '-'
+      player, castling_rights, ep = position_fields
+      PGN::Position.new(board, player, castling_rights, ep, halfmove.to_i, fullmove.to_i)
+    end
 
-      PGN::Position.new(
-        board,
-        player,
-        castling,
-        en_passant,
-        halfmove.to_i,
-        fullmove.to_i
-      )
+    # @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

data/lib/pgn/game.rb

@@ -29,10 +29,20 @@ module PGN
       @notation
     end
 
+    # Normalize UCI-style castling ('0-0') to canonical SAN ('O-O').
+    def self.normalize_castling(san)
+      san.include?('0') ? san.gsub('0', 'O') : san
+    end
+
     def clean_text(text)
       return unless text
 
-      text.gsub(/{(.*)}/, '\1').gsub(/\s+/, ' ').strip
+      # 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
 
@@ -135,6 +145,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). Grows the memoized position list in step, if it is populated.
+    #
+    # @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 << @positions.last.move(move.notation) if @positions
+      self
+    end
+
+    # Remove and return the last move, or nil if there are none. Shrinks the
+    # memoized position list in step, if it is populated.
+    #
+    # @return [PGN::MoveText, nil]
+    def pop
+      return nil if @moves.empty?
+
+      move = @moves.pop
+      @positions&.pop
+      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) over {#positions}, so a prior or
+    # subsequent call that also needs the position list shares the replay.
+    #
+    # @return [Boolean]
+    def threefold?
+      counts = Hash.new(0)
+      positions.each { |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.
@@ -159,17 +233,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)
+      return MoveText.new(MoveText.normalize_castling(entry)) if entry.is_a?(String)
 
-      notation = entry.notation.include?('0') ? entry.notation.gsub('0', 'O') : entry.notation
-      return entry if notation.equal?(entry.notation) && (entry.comment.nil? || !entry.comment.include?('{'))
+      notation = MoveText.normalize_castling(entry.notation)
+      return entry if notation.equal?(entry.notation)
 
       MoveText.new(notation, entry.annotation, entry.comment, entry.variations)
     end

data/lib/pgn/move.rb

@@ -74,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>?
@@ -112,7 +112,7 @@ 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
@@ -136,8 +136,8 @@ module PGN
     def castle=(val)
       return unless val
 
-      @castle = 'K' if val == 'O-O'
-      @castle = 'Q' if val == 'O-O-O'
+      @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
 

data/lib/pgn/node.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+module PGN
+  # {PGN::Node} is a live, lazily-built view over the {PGN::MoveText} tree.
+  #
+  # A node represents the position reached by playing +move+ from its
+  # +parent+'s position; the root has no move and is the game's starting
+  # position. The underlying {PGN::MoveText} structure is the source of
+  # truth (the parser builds it and the serializer reads it), so a node
+  # tree never disagrees with the serialized output.
+  #
+  # Mutations edit the underlying +MoveText+ arrays in place and, for
+  # sibling reorders, normalize the affected branching point to flat
+  # sibling storage. After any structural mutation, {PGN::Game#root}
+  # returns a fresh tree — outstanding node references are stale.
+  class Node
+    attr_reader :move, :parent, :line, :index
+
+    # @param move [PGN::MoveText, nil] the move played to reach this node
+    # @param parent [PGN::Node, nil] the parent node (nil for the root)
+    # @param line [Array<PGN::MoveText>, nil] the line this node's move
+    #   lives in (the mainline for mainline nodes, the variation Array for
+    #   variation nodes; nil conceptually for the root, which passes the
+    #   mainline)
+    # @param index [Integer] index of this node's move within +line+
+    #   (-1 for the root)
+    # @param starting_position [PGN::Position] the root's position
+    # @param game [PGN::Game] back-reference so mutations can return a
+    #   fresh root
+    def initialize(move:, parent:, line:, index:, starting_position: nil, game: nil)
+      @move = move
+      @parent = parent
+      @line = line
+      @index = index
+      @starting_position = starting_position
+      @game = game
+    end
+
+    def root?
+      @move.nil?
+    end
+
+    def notation
+      @move&.notation
+    end
+
+    def annotation
+      @move&.annotation
+    end
+
+    def comment
+      @move&.comment
+    end
+
+    # All moves playable from this node's position: the continuation move
+    # (the next MoveText in this node's line) plus every variation
+    # first-move branching at that same position, recursively through
+    # nested brackets. The first child is the mainline continuation; the
+    # rest are variations in source order.
+    def children
+      @children ||= begin
+        cont = continuation_movetext
+        list = []
+        collect_first_moves(cont, @line, @index + 1) do |mt, l, idx|
+          list << Node.new(move: mt, parent: self, line: l, index: idx, game: @game)
+        end
+        list
+      end
+    end
+
+    # The non-mainline alternatives at this node's position.
+    def variations
+      children[1..] || []
+    end
+
+    # The mainline continuation, or nil at a terminal position.
+    # (Defined via +define_method+ because +next+ is a Ruby keyword and
+    # cannot be used with +def+.)
+    define_method(:next) { children.first }
+
+    # The parent node, or nil for the root.
+    def previous
+      @parent
+    end
+
+    def [](idx)
+      children[idx]
+    end
+
+    # Yields each mainline node from +self.next+ onward (the root is
+    # excluded), so +main_line.map(&:notation) == game.moves.map(&:notation)+
+    # and +main_line.map(&:position) == game.positions[1..]+. Returns an
+    # Enumerator when called without a block.
+    def main_line
+      return enum_for(:main_line) unless block_given?
+
+      node = self.next
+      while node
+        yield node
+        node = node.next
+      end
+    end
+
+    # The position reached at this node: the starting position for the
+    # root, otherwise +parent.position+ with +move.notation+ applied. Pure
+    # Ruby (no native engine); raises on an illegal SAN exactly like
+    # {PGN::Game#positions}. Cached on the node.
+    def position
+      return @position if defined?(@position)
+
+      @position = if root?
+                    @starting_position
+                  else
+                    @parent.position.then { |p| p.move(@move.notation) }
+                  end
+    end
+
+    # Append a new variation line (a single SAN String or an Array<String>)
+    # branching before this node's next mainline move. Returns a fresh
+    # +game.root+. Raises +ArgumentError+ at a terminal node (a variation
+    # must branch before an existing move; use +add_main_variation+ to
+    # extend the line).
+    def add_variation(move_or_moves)
+      cont = continuation_movetext
+      raise ArgumentError, 'cannot add a variation at a terminal node' if cont.nil?
+
+      normalize_branch_point(cont)
+      cont.variations << build_movetexts(move_or_moves)
+      @game.root
+    end
+
+    # Make the given moves the new mainline continuation from this node's
+    # position. At a terminal node this extends the line; otherwise the old
+    # continuation becomes a variation of the new first move. Returns a
+    # fresh +game.root+.
+    def add_main_variation(move_or_moves)
+      new_line = build_movetexts(move_or_moves)
+      cont = continuation_movetext
+
+      if cont.nil?
+        @line.push(*new_line)
+      else
+        normalize_branch_point(cont)
+        make_mainline(@line, @index + 1, cont, new_line, cont.variations, old_main_position: :first)
+      end
+      @game.root
+    end
+
+    # Move this node one slot toward the mainline among its siblings.
+    # No-op for the mainline (index 0) or the first variation (index 1).
+    # Returns a fresh +game.root+.
+    def promote
+      mutate_sibling(noop: ->(i) { i <= 1 }) do |i, _cont, vars|
+        vars[i - 1], vars[i - 2] = vars[i - 2], vars[i - 1]
+      end
+    end
+
+    # Move this node one slot toward the end among its siblings. At index 0
+    # (the mainline) this is the inverse swap: variation #1 becomes the new
+    # mainline and the old mainline becomes variation #1. No-op at the last
+    # index. Returns a fresh +game.root+.
+    def demote
+      mutate_sibling(noop: ->(i) { i == @parent.children.size - 1 }) do |i, cont, vars|
+        if i.zero?
+          v1 = vars.shift
+          make_mainline(@parent.line, @parent.index + 1, cont, v1, vars, old_main_position: :first)
+        else
+          vars[i - 1], vars[i] = vars[i], vars[i - 1]
+        end
+      end
+    end
+
+    # Make this node the mainline at its branching point (the old mainline
+    # becomes variation #1). No-op if already the mainline. Returns a
+    # fresh +game.root+.
+    def promote_to_main
+      mutate_sibling(noop: lambda(&:zero?)) do |i, cont, vars|
+        vk = vars.delete_at(i - 1)
+        make_mainline(@parent.line, @parent.index + 1, cont, vk, vars, old_main_position: :first)
+      end
+    end
+
+    # Move this node to the last position among its siblings. At index 0
+    # the last variation becomes the new mainline and the old mainline
+    # becomes the last variation. Returns a fresh +game.root+.
+    def demote_to_last
+      mutate_sibling do |i, cont, vars|
+        if i.zero?
+          unless vars.empty?
+            last = vars.pop
+            make_mainline(@parent.line, @parent.index + 1, cont, last, vars, old_main_position: :last)
+          end
+        else
+          el = vars.delete_at(i - 1)
+          vars.push(el)
+        end
+      end
+    end
+
+    # Remove this node and its subtree. If it is the mainline continuation,
+    # the first remaining variation (if any) takes its place; otherwise the
+    # line is truncated at this point. Returns a fresh +game.root+.
+    def delete
+      mutate_sibling do |i, cont, vars|
+        if i.zero?
+          delete_mainline_continuation(cont, vars)
+        else
+          vars.delete_at(i - 1)
+        end
+      end
+    end
+
+    private
+
+    # The MoveText played from this node's position in the current line:
+    # the next entry in +line+ (nil at a terminal position). For the root,
+    # +index+ is -1, so this is +line[0]+ (the first mainline move).
+    def continuation_movetext
+      @line && @line[@index + 1]
+    end
+
+    # Yield every first-move branching at the position before +m+ (i.e. at
+    # this node's position): +m+ itself (in +l+ at +idx+), plus the first
+    # move of each of +m+'s variations, plus — recursively — the first
+    # moves of any variations nested on those first moves (they branch at
+    # the same point, since a variation branches before the move it
+    # attaches to).
+    def collect_first_moves(movetext, line, idx, &block)
+      return if movetext.nil?
+
+      block.call(movetext, line, idx)
+      (movetext.variations || []).each do |variation|
+        next unless variation && variation[0]
+
+        collect_first_moves(variation[0], variation, 0, &block)
+      end
+    end
+
+    # Index of this node among its parent's children, or nil if root.
+    def sibling_index
+      @parent.children.index(self)
+    end
+
+    # The MoveText that is the mainline continuation at the PARENT's
+    # position (the move this node is an alternative to, or this node
+    # itself if it is the continuation).
+    def parent_continuation
+      @parent.line[@parent.index + 1]
+    end
+
+    # Build an Array<PGN::MoveText> from a single SAN String or an Array of
+    # SANs, applying the same castling 0->O normalization as Game#moves=.
+    def build_movetexts(move_or_moves)
+      sans = move_or_moves.is_a?(String) ? [move_or_moves] : move_or_moves
+      sans.map { |s| PGN::MoveText.new(PGN::MoveText.normalize_castling(s)) }
+    end
+
+    # Shared prologue/epilogue for the sibling-reordering mutators (promote,
+    # demote, promote_to_main, demote_to_last, delete): no-op at the root or
+    # per +noop+ (checked against the sibling index before any mutation),
+    # otherwise normalize the branching point and yield the sibling index,
+    # the parent's mainline continuation, and its (now flat) variations to
+    # +block+ for the mutation proper. Always returns a fresh +game.root+.
+    def mutate_sibling(noop: nil)
+      return @game.root if root?
+
+      i = sibling_index
+      return @game.root if i.nil? || noop&.call(i)
+
+      cont = parent_continuation
+      normalize_branch_point(cont)
+      yield i, cont, cont.variations
+      @game.root
+    end
+
+    # Hoist every variation first-move branching at the position before
+    # +cont+ (recursively through nested brackets) into a single flat
+    # +cont.variations+ array, clearing the first-moves' at-point variations
+    # (they are now flat siblings). Internal structure of each variation
+    # line (tail moves and their deeper variations) is untouched. After
+    # this, +cont.variations+ is a flat Array<Array<MoveText>> in the same
+    # order +children+ yields.
+    def normalize_branch_point(cont)
+      return if cont.nil?
+
+      lines = []
+      collect_variation_lines(cont) { |v| lines << v }
+      lines.each { |v| v[0].variations = [] }
+      cont.variations = lines
+    end
+
+    # Yield each variation line branching at the position before +m+ (in
+    # DFS order): +m+'s direct variations, plus — recursively — the
+    # variations nested on each variation's first move (they branch at the
+    # same point).
+    def collect_variation_lines(movetext, &block)
+      (movetext.variations || []).each do |variation|
+        next unless variation && variation[0]
+
+        block.call(variation)
+        collect_variation_lines(variation[0], &block)
+      end
+    end
+
+    # Splice +movetexts+ (an Array<MoveText>) into +line+ starting at +pos+:
+    # its first entry replaces +line[pos]+, and the rest replace the tail
+    # after it (so a shorter +movetexts+ truncates +line+).
+    def splice_line!(line, pos, movetexts)
+      line[pos] = movetexts[0]
+      line[(pos + 1)..] = (movetexts[1..] || [])
+    end
+
+    # Make +vk+ (= [vk0, *tail]) the new mainline continuation at +line+/+pos+
+    # (the position before +cont+), replacing +cont+. The old mainline
+    # (+cont+ and its tail) becomes a variation appended to +others+ either
+    # before (+old_main_position == :first+) or after (+:last+).
+    # +cont.variations+ is cleared (its at-point variations are now +vk0+'s
+    # siblings).
+    def make_mainline(line, pos, cont, variation, others, old_main_position:)
+      old_tail = line[(pos + 1)..] || []
+      variation0 = variation[0]
+      splice_line!(line, pos, variation)
+      cont.variations = []
+      old_var = [cont, *old_tail]
+      variation0.variations =
+        old_main_position == :first ? [old_var, *others] : [*others, old_var]
+    end
+
+    # Replace the mainline continuation +cont+ with its first variation
+    # (+vars+ is +cont.variations+, flat). If there are no variations, the
+    # line is truncated at the continuation; otherwise the first variation
+    # takes the continuation's place and the remaining variations become
+    # its variations.
+    def delete_mainline_continuation(cont, vars)
+      line = @parent.line
+      pos = @parent.index + 1
+      if vars.empty?
+        line[pos..] = []
+      else
+        first_variation = vars.shift
+        splice_line!(line, pos, first_variation)
+        cont.variations = []
+        first_variation[0].variations = vars
+      end
+    end
+  end
+end