pgn2 1.5.0 → 2.0.1

data/lib/pgn/node.rb

@@ -0,0 +1,372 @@
+# 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)
+        vars = cont.variations
+        pos = @index + 1
+        old_tail = @line[(pos + 1)..] || []
+        n0 = new_line[0]
+        @line[pos] = n0
+        @line[(pos + 1)..] = (new_line[1..] || [])
+        cont.variations = []
+        n0.variations = [[cont, *old_tail], *vars]
+      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
+      return @game.root if root?
+
+      i = sibling_index
+      return @game.root if i.nil? || i <= 1
+
+      cont = parent_continuation
+      normalize_branch_point(cont)
+      vars = cont.variations
+      vars[i - 1], vars[i - 2] = vars[i - 2], vars[i - 1]
+      @game.root
+    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
+      return @game.root if root?
+
+      i = sibling_index
+      sibs = @parent.children
+      return @game.root if i.nil? || i == sibs.size - 1
+
+      cont = parent_continuation
+      normalize_branch_point(cont)
+      vars = cont.variations
+      if i.zero?
+        v1 = vars.shift
+        make_mainline(cont, v1, vars, old_main_position: :first)
+      else
+        vars[i - 1], vars[i] = vars[i], vars[i - 1]
+      end
+      @game.root
+    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
+      return @game.root if root?
+
+      i = sibling_index
+      return @game.root if i.nil? || i.zero?
+
+      cont = parent_continuation
+      normalize_branch_point(cont)
+      vars = cont.variations
+      vk = vars.delete_at(i - 1)
+      make_mainline(cont, vk, vars, old_main_position: :first)
+      @game.root
+    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
+      return @game.root if root?
+
+      i = sibling_index
+      return @game.root if i.nil?
+
+      cont = parent_continuation
+      normalize_branch_point(cont)
+      vars = cont.variations
+      if i.zero?
+        return @game.root if vars.empty?
+
+        last = vars.pop
+        make_mainline(cont, last, vars, old_main_position: :last)
+      else
+        el = vars.delete_at(i - 1)
+        vars.push(el)
+      end
+      @game.root
+    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
+      return @game.root if root?
+
+      i = sibling_index
+      return @game.root if i.nil?
+
+      cont = parent_continuation
+      normalize_branch_point(cont)
+      vars = cont.variations
+      if i.zero?
+        delete_mainline_continuation(cont, vars)
+      else
+        vars.delete_at(i - 1)
+      end
+      @game.root
+    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(normalize_castling(s)) }
+    end
+
+    def normalize_castling(san)
+      san.include?('0') ? san.gsub('0', 'O') : san
+    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
+
+    # Make +vk+ (= [vk0, *tail]) the new mainline continuation at the
+    # parent's position, 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(cont, variation, others, old_main_position:)
+      line = @parent.line
+      pos = @parent.index + 1
+      old_tail = line[(pos + 1)..] || []
+      variation0 = variation[0]
+      line[pos] = variation0
+      line[(pos + 1)..] = (variation[1..] || [])
+      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
+        first_variation_move = first_variation[0]
+        line[pos] = first_variation_move
+        line[(pos + 1)..] = (first_variation[1..] || [])
+        cont.variations = []
+        first_variation_move.variations = vars
+      end
+    end
+  end
+end

data/lib/pgn/notation.rb

@@ -133,7 +133,7 @@ module PGN
     # Other squares holding `piece` whose move to `to_idx` is legal.
     def same_type_legals(piece, from_idx, to_idx)
       (0...128).each_with_object([]) do |idx, acc|
-        next if (idx & 0x88) != 0
+        next if idx.anybits?(0x88)
         next if idx == from_idx
         next unless @board.at_index(idx) == piece
 
@@ -145,8 +145,8 @@ module PGN
 
     def suffix(from_idx, to_idx, piece, promotion, castling)
       nb = apply_move(from_idx, to_idx, piece, promotion, castling)
-      opp_king = king_idx(nb, @enemy)
-      return '' unless opp_king && attacked?(nb, opp_king, @mover)
+      opp_king = PGN::Attack.king_idx(nb, @enemy)
+      return '' unless opp_king && PGN::Attack.attacked?(nb, opp_king, @mover)
 
       result_pos = PGN::Position.new(
         nb,
@@ -219,8 +219,8 @@ module PGN
       nb.update_index(ep, nil) if ep
       nb.update_index(from_idx, nil)
       nb.update_index(to_idx, piece)
-      king = king_idx(nb, @mover)
-      king && !attacked?(nb, king, @enemy)
+      king = PGN::Attack.king_idx(nb, @mover)
+      king && !PGN::Attack.attacked?(nb, king, @enemy)
     end
 
     # Does `piece` at `from_idx` pseudo-legally reach `to_idx` on the board?
@@ -230,9 +230,9 @@ module PGN
 
       case piece.upcase
       when 'N'
-        KNIGHT_OFFS.any? { |o| (from_idx + o) == to_idx }
+        Board::KNIGHT_ATTACKS[from_idx].include?(to_idx)
       when 'K'
-        KING_OFFS.any? { |o| (from_idx + o) == to_idx }
+        Board::KING_ATTACKS[from_idx].include?(to_idx)
       when 'B', 'R', 'Q'
         slider_reaches?(piece.upcase, from_idx, to_idx)
       else
@@ -243,7 +243,7 @@ module PGN
     def slider_reaches?(piece_up, from_idx, to_idx)
       slider_dirs(piece_up).any? do |off|
         i = from_idx + off
-        while (i & 0x88).zero?
+        while i.nobits?(0x88)
           return true if i == to_idx
           break if @board.at_index(i)
 
@@ -264,7 +264,7 @@ module PGN
     end
 
     def own?(piece, color)
-      color == 'w' ? piece == piece.upcase : piece == piece.downcase
+      piece == (color == 'w' ? piece.upcase : piece.downcase)
     end
 
     # Slider ray directions for a piece letter ('B'/'R'/'Q').
@@ -278,71 +278,8 @@ module PGN
 
     # -- attack / legality helpers ----------------------------------------
 
-    def king_idx(board, color)
-      king = color == 'w' ? 'K' : 'k'
-      (0...128).each do |idx|
-        next if (idx & 0x88) != 0
-
-        return idx if board.at_index(idx) == king
-      end
-      nil
-    end
-
-    # Is `target` attacked by `color`-colored pieces on `board`?
-    def attacked?(board, target, color)
-      pawn_attacked?(board, target, color) ||
-        knight_attacked?(board, target, color) ||
-        king_attacked?(board, target, color) ||
-        slider_attacked?(board, target, color)
-    end
-
-    def pawn_attacked?(board, target, color)
-      offs = color == 'w' ? [-15, -17] : [15, 17]
-      pawn = color == 'w' ? 'P' : 'p'
-      offs.any? do |off|
-        i = target + off
-        (i & 0x88).zero? && board.at_index(i) == pawn
-      end
-    end
-
-    def knight_attacked?(board, target, color)
-      knight = color == 'w' ? 'N' : 'n'
-      KNIGHT_OFFS.any? do |off|
-        i = target + off
-        (i & 0x88).zero? && board.at_index(i) == knight
-      end
-    end
-
-    def king_attacked?(board, target, color)
-      king = color == 'w' ? 'K' : 'k'
-      KING_OFFS.any? do |off|
-        i = target + off
-        (i & 0x88).zero? && board.at_index(i) == king
-      end
-    end
-
-    def slider_attacked?(board, target, color)
-      bishop = color == 'w' ? 'B' : 'b'
-      rook = color == 'w' ? 'R' : 'r'
-      queen = color == 'w' ? 'Q' : 'q'
-      ray_hit?(board, target, BISHOP_DIRS) { |p| p == bishop || p == queen } ||
-        ray_hit?(board, target, ROOK_DIRS) { |p| p == rook || p == queen }
-    end
-
-    def ray_hit?(board, target, dirs)
-      dirs.each do |off|
-        i = target + off
-        while (i & 0x88).zero?
-          piece = board.at_index(i)
-          if piece
-            return true if yield(piece)
-            break
-          end
-          i += off
-        end
-      end
-      false
-    end
+    # (Attack detection is delegated to {PGN::Attack}, the shared source of
+    # truth used by {PGN::Position#in_check?} and {PGN::Position#attackers}.)
 
     # -- legal-move generation (for checkmate detection) ------------------
 
@@ -352,7 +289,7 @@ module PGN
       ep_idx = ep_target_idx(position, board)
 
       (0...128).any? do |idx|
-        next if (idx & 0x88) != 0
+        next if idx.anybits?(0x88)
 
         piece = board.at_index(idx)
         piece && own?(piece, color) && move_from?(board, idx, piece, color, ep_idx)
@@ -370,8 +307,8 @@ module PGN
     def move_from?(board, idx, piece, color, ep_idx)
       up = piece.upcase
       case up
-      when 'N' then leaper_moves?(board, idx, piece, color, KNIGHT_OFFS)
-      when 'K' then leaper_moves?(board, idx, piece, color, KING_OFFS)
+      when 'N' then leaper_moves?(board, idx, piece, color, Board::KNIGHT_ATTACKS[idx])
+      when 'K' then leaper_moves?(board, idx, piece, color, Board::KING_ATTACKS[idx])
       when 'B', 'R', 'Q'
         slider_moves?(board, idx, piece, color, slider_dirs(up))
       when 'P'
@@ -381,22 +318,22 @@ module PGN
       end
     end
 
-    def leaper_moves?(board, idx, piece, color, offs)
-      offs.any? do |off|
-        t = idx + off
-        (t & 0x88).zero? && landable?(board, t, color) && safe?(board, idx, t, piece, nil)
+    def leaper_moves?(board, idx, piece, color, targets)
+      targets.any? do |t|
+        landable?(board, t, color) && safe?(board, idx, t, piece, nil)
       end
     end
 
     def slider_moves?(board, idx, piece, color, dirs)
       dirs.any? do |off|
         t = idx + off
-        while (t & 0x88).zero?
+        while t.nobits?(0x88)
           tp = board.at_index(t)
           if tp.nil?
             return true if safe?(board, idx, t, piece, nil)
           else
             return true if !own?(tp, color) && safe?(board, idx, t, piece, nil)
+
             break
           end
           t += off
@@ -416,24 +353,24 @@ module PGN
       promo_rank = color == 'w' ? 7 : 0
 
       t = idx + dir
-      return false unless (t & 0x88).zero? && board.at_index(t).nil?
+      return false unless t.nobits?(0x88) && board.at_index(t).nil?
 
-      promo = (t >> 4 == promo_rank) ? 'Q' : nil
+      promo = t >> 4 == promo_rank ? 'Q' : nil
       return true if safe?(board, idx, t, piece, promo)
 
       t2 = idx + (dir * 2)
       (idx >> 4) == start_rank && board.at_index(t2).nil? && safe?(board, idx, t2, piece, nil)
     end
 
-    def pawn_captures?(board, idx, piece, color, ep_idx) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    def pawn_captures?(board, idx, piece, color, ep_idx)
       promo_rank = color == 'w' ? 7 : 0
       caps = color == 'w' ? [15, 17] : [-15, -17]
       caps.any? do |off|
         t = idx + off
-        next false unless (t & 0x88).zero?
+        next false unless t.nobits?(0x88)
 
         tp = board.at_index(t)
-        promo = (t >> 4 == promo_rank) ? 'Q' : nil
+        promo = t >> 4 == promo_rank ? 'Q' : nil
         if tp && !own?(tp, color)
           safe?(board, idx, t, piece, promo)
         elsif tp.nil? && t == ep_idx
@@ -459,8 +396,8 @@ module PGN
       nb.update_index(from_idx, nil)
       nb.update_index(to_idx, place_piece(piece, promotion))
       color = own?(piece, 'w') ? 'w' : 'b'
-      king = king_idx(nb, color)
-      king && !attacked?(nb, king, color == 'w' ? 'b' : 'w')
+      king = PGN::Attack.king_idx(nb, color)
+      king && !PGN::Attack.attacked?(nb, king, color == 'w' ? 'b' : 'w')
     end
 
     # The piece letter to place on the destination after a pseudo-move.