chess_engine_rb 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 00dbb28085362bcf277a8ee0da5ff60b7676485a8a24e2354ae25a6925438c36
+  data.tar.gz: 35eb6625b09d3773c7bbafac6de105d39aa54cff374e9ed547dae91a2d766ad2
+SHA512:
+  metadata.gz: 90b584edd11dc6e21186536305ce6a9f8d55198741cd6aee1a40a56689d024d14d3eb2b618b65e90c0886fc19817c21493ae8bdd50201868d4d6fcd72e0bbc1a
+  data.tar.gz: c7d92097b4c1d562acd39bdc8fe1a893d018393ac512d013c3c6557270edcafe747254887752ad0722d94886dcbccca51aeb7cd882f31debc86c08884d7cc083

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nadav Levi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,83 @@
+# Ruby Chess Engine
+A modular, deterministic chess engine built around immutable objects.
+Cleanly expresses chess concepts in code and designed for easy integration with any UI.
+
+> ⚠️ Note: This is not a competitive chess engine like Stockfish.
+While AI features could be added in the future, the core purpose of this project is to provide a ruby gem for cleanly representing chess in code.
+
+# Features
+- UI-agnostic design
+- Fully immutable game state representation
+- Modular: components can be used separately or coordinated via the `Engine` class
+- Chess concepts map cleanly to code: squares, pieces, board, rules, etc
+- Pluggable notation systems for both parsing and formatting: a custom notation called ERAN is the default,
+  but parsers & formatters for any other notation system(SAN, LAN, etc) can be implemented and plugged in instead
+- FEN import and export
+
+# Examples
+### Simple usage
+```ruby
+require 'chess_engine_rb'
+
+engine = ChessEngine::Engine.new
+engine.new_game
+engine.play_turn('P e2-e4') # play a move
+puts engine.status.board # prints the board
+puts engine.to_fen # prints FEN
+engine.from_fen('rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1') # Load from FEN
+```
+
+### Using a listener
+```ruby
+require 'chess_engine_rb'
+
+class Listener
+  FORMATTER = ChessEngine::Formatters::ERANShortFormatter
+
+  def on_game_update(update)
+    if update.failure?
+      puts "Update failed: #{update.error}"
+    elsif update.game_ended?
+      puts "Game over! Reason: #{update.endgame_status.cause}"
+    elsif update.offered_draw
+      puts 'Draw has been offered'
+    else
+      puts "Move accepted: #{FORMATTER.call(update.event)}"
+    end
+  end
+end
+
+engine = ChessEngine::Engine.new
+engine.add_listener(Listener.new)
+engine.play_turn('P e7-e6') # => Move accepted: P e7-e6
+engine.play_turn('HA!') # => Update failed: invalid_notation
+engine.offer_draw # => Draw has been offered
+engine.resign # => Game over! Reason: resignation
+```
+
+For more complete examples, see the examples folder.
+
+# Installation
+## From RubyGems (recommended)
+- Install Ruby (version >= 3.4.1) if you haven't already (on Windows, you can use [RubyInstaller](https://rubyinstaller.org/downloads/))
+- Install the gem: `gem install chess_engine_rb`
+- If you want to see the engine in action, download the example CLI `examples/chess_cli.rb`  and run it: `ruby chess_cli.rb`
+
+## From source
+- Make sure Ruby (version >= 3.4.1) and Bundler are installed
+- Clone the repository and run `bundle install` from the project's root directory
+
+# More information
+- See the [architectural overview](docs/architecture.md)
+- Browse the docs and examples for more information
+
+# Possible future additions
+- Move undo
+- SAN and LAN parsers/formatters
+- PGN import/export
+- Performance improvements
+- Comprehensive perft testing
+- Basic AI
+
+# License
+This project is licensed under the [MIT License](LICENSE).

data/lib/chess_engine/data_definitions/README.md

@@ -0,0 +1,10 @@
+# `data_definitions/`
+
+This folder contains the core data types used within the engine.
+Those include immutable value objects that model engine entities, and primitive static definitions.
+
+# structure
+- **Top-level:** meaningful value objects - `Piece`, `Square`, `Board`, `Position`, and events.
+- **Subfolders:**
+  - `primitives/` - static definitions of core concepts, such as colors and core notation.
+  - `components/` - internal dependencies of the top-level types, such as the persistent array underpinning `Board`.

data/lib/chess_engine/data_definitions/board.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require_relative 'piece'
+require_relative 'square'
+require_relative '../errors'
+require_relative 'components/persistent_array'
+
+module ChessEngine
+  # `Board` is an immutable chessboard representation.
+  # Each square is mapped to either a piece or nil, using `Square` objects for coordinates.
+  # Provides query methods (e.g., `#get`, `#pieces_with_squares`) to inspect board state,
+  # and manipulation methods that return new `Board` instances with the desired changes.
+  # Designed for safe, functional-style updates and efficient state sharing.
+  class Board
+    SIZE = 8 # the board dimensions
+
+    # Constructs a `Board` from a flat array of 64 items.
+    # Each item's index maps to a board square as follows:
+    # 0 -> a1, 2 -> b1, ... 8 -> a2, ... 63 -> h8
+    # Each item should be a `Piece` or nil, representing the contents of that square.
+    def self.from_flat_array(values)
+      raise ArgumentError, 'Expected 64 elements' unless values.size == SIZE * SIZE
+      raise ArgumentError, 'Expected nil or Piece objects' unless values.all? { it.nil? || it.is_a?(Piece) }
+
+      array = PersistentArray.from_values(values)
+      new(array)
+    end
+
+    # An empty board
+    def self.empty
+      from_flat_array(Array.new(SIZE * SIZE))
+    end
+
+    # A board with all pieces set up at their starting squares
+    def self.start
+      back_row = %i[rook knight bishop queen king bishop knight rook]
+      ranks = [
+        back_row.map { |t| Piece.new(:white, t) }, # Rank 1
+        Array.new(8) { Piece.new(:white, :pawn) }, # Rank 2
+        Array.new(4) { Array.new(8) }, # Ranks 3–6
+        Array.new(8) { Piece.new(:black, :pawn) }, # Rank 7
+        back_row.map { |t| Piece.new(:black, t) } # Rank 8
+      ]
+
+      from_flat_array(ranks.flatten)
+    end
+
+    # Use only internally
+    def initialize(array)
+      @array = array
+    end
+
+    ######## Queries
+
+    # Get the piece at the given square, or nil if the square is unoccupied
+    def get(square)
+      index = square_to_index(square)
+      @array.get(index)
+    end
+
+    # Returns an array of all pieces, with their squares, matching the criteria.
+    # The result is an array of elements of the form: [piece, square]
+    # If type or color is nil, that attribute is ignored.
+    # Examples:
+    #   All black pieces: find_pieces(color: :black)
+    #   All pieces:       find_pieces
+    #   White rooks:      find_pieces(type: :rook, color: :white)
+    def pieces_with_squares(color: nil, type: nil)
+      @array.filter_map.with_index do |piece, index|
+        next if piece.nil?
+
+        [piece, index_to_square(index)] if [nil, piece.type].include?(type) && [nil, piece.color].include?(color)
+      end
+    end
+
+    # Returns an array of all pieces matching the criteria.
+    # Internally delegates to `#pieces_with_squares`, stripping the squares.
+    def find_pieces(color: nil, type: nil)
+      pieces_with_squares(color: color, type: type).map(&:first)
+    end
+
+    def each_square_content(&)
+      return enum_for(__method__) unless block_given?
+
+      SIZE.times do |row|
+        SIZE.times do |col|
+          yield @array.get((row * SIZE) + col)
+        end
+      end
+    end
+
+    def each_rank(&)
+      return enum_for(__method__) unless block_given?
+
+      SIZE.times do |row|
+        yield SIZE.times.map { |col| @array.get((row * SIZE) + col) }
+      end
+    end
+
+    def each_file(&)
+      return enum_for(__method__) unless block_given?
+
+      SIZE.times do |col|
+        yield SIZE.times.map { |row| @array.get((row * SIZE) + col) }
+      end
+    end
+
+    ######## Manipulation
+
+    def move(from, to)
+      from_index = square_to_index from
+      piece = @array.get from_index
+      to_index = square_to_index to
+      raise BoardManipulationError, 'No piece to move' if piece.nil?
+      raise BoardManipulationError, 'Destination is already occupied' unless @array.get(to_index).nil?
+      raise BoardManipulationError, 'Cannot move to the same square' if from == to
+
+      Board.new(@array.set(from_index, nil).set(to_index, piece))
+    end
+
+    def remove(square)
+      index = square_to_index square
+      raise BoardManipulationError, 'Square is unoccupied' if get(square).nil?
+
+      Board.new(@array.set(index, nil))
+    end
+
+    # Inserts the given piece to an empty square
+    def insert(piece, square)
+      index = square_to_index(square)
+      raise ArgumentError, 'Not a valid piece' unless piece.is_a?(Piece)
+      raise BoardManipulationError, 'Square is occupied' unless @array.get(index).nil?
+
+      Board.new(@array.set(index, piece))
+    end
+
+    # For debugging mainly
+    def to_s # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+      rows = []
+      rows << '   a b c d e f g h'
+      rows << ' ┌─────────────────┐'
+      (0...SIZE).each do |row|
+        row_str = "#{row + 1}│ "
+        (0...SIZE).each do |col|
+          index = square_to_index(Square.from_index(row, col))
+          piece = @array.get(index)
+          row_str += if piece
+                       "#{piece} "
+                     else
+                       (row + col).odd? ? '□ ' : '■ '
+                     end
+        end
+        rows << "#{row_str.chomp}│#{row + 1}"
+      end
+      rows << ' └─────────────────┘'
+      rows << '   a b c d e f g h'
+      rows.join("\n")
+    end
+
+    def inspect
+      "#<Board #{pieces_with_squares.map { |piece, pos| "#{piece}@#{pos}" }.join(', ')}>"
+    end
+
+    def ==(other)
+      other.is_a?(Board) && pieces_with_squares == other.pieces_with_squares
+    end
+
+    def eql?(other)
+      self == other
+    end
+
+    def hash
+      # Doesn't use the exact same hash as `#pieces_with_squares` to avoid clashes
+      [pieces_with_squares, 0].hash
+    end
+
+    private
+
+    def square_to_index(square)
+      raise ArgumentError, "#{square.inspect} is not a Square" unless square.is_a?(Square)
+      raise InvalidSquareError, "#{square.inspect} is not a valid square" unless square.valid?
+
+      row, col = square.to_a
+      (row * SIZE) + col
+    end
+
+    def index_to_square(index)
+      row, col = index.divmod(SIZE)
+      Square.from_index(row, col)
+    end
+  end
+end

data/lib/chess_engine/data_definitions/components/castling_rights.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ChessEngine
+  module PositionModule
+    # Represents complete castling rights of both color for a certain position
+    CastlingRights = Data.define(
+      :white, :black
+    ) do
+      def self.start
+        new(CastlingSides.start, CastlingSides.start)
+      end
+
+      def self.none
+        new(CastlingSides.none, CastlingSides.none)
+      end
+
+      def sides(color)
+        case color
+        when :white then white
+        when :black then black
+        else
+          raise ArgumentError, "Invalid color: #{color.inspect}"
+        end
+      end
+    end
+
+    # Tracks whether each side still retains castling rights.
+    # Rights may be lost due to moving the king or rook, or other game events.
+    CastlingSides = Data.define(:kingside, :queenside) do
+      def self.start
+        new(true, true)
+      end
+
+      def self.none
+        new(false, false)
+      end
+
+      def side?(side)
+        case side
+        when :kingside then kingside
+        when :queenside then queenside
+        else
+          raise ArgumentError, "Invalid castling side: #{side.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/chess_engine/data_definitions/components/persistent_array.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module ChessEngine
+  class Board
+    module PersistentArrayModule
+      SIZE = 64
+      BRANCHING_FACTOR = 8
+
+      # `PersistentArray` provides an immutable, tree-based fixed-size array.
+      # It's designed specifically for use by the `Board` class to support immutable updates,
+      # allowing efficient structural sharing of board state.
+      #
+      # Not intended as a general-purpose data structure outside of this context.
+      class PersistentArray
+        include Enumerable
+
+        # The public interface
+        def self.from_values(values)
+          raise ArgumentError, "Expected exactly #{SIZE} elements, got #{values.size}" unless values.size == SIZE
+
+          new(InternalNode.from_values(values))
+        end
+
+        # Do not use directly - intended to be private
+        def initialize(root)
+          @root = root
+        end
+
+        def get(index)
+          raise IndexError, "Index #{index} out of bounds" unless (0...SIZE).cover?(index)
+
+          @root.get(index, SIZE)
+        end
+
+        def set(index, new_value)
+          raise IndexError, "Index #{index} out of bounds" unless (0...SIZE).cover?(index)
+
+          PersistentArray.new(@root.set(index, new_value, SIZE))
+        end
+
+        def each(&)
+          @root.each(&)
+        end
+
+        def to_s
+          "[#{map(&:inspect).join(', ')}]"
+        end
+      end
+
+      # A PersistentArray node that holds references to other nodes
+      class InternalNode
+        def self.from_values(values)
+          chunk_size = values.size / BRANCHING_FACTOR
+          node_class = chunk_size == BRANCHING_FACTOR ? LeafNode : InternalNode
+          branches = Array.new(BRANCHING_FACTOR) do |i|
+            node_class.from_values(values[chunk_size * i, chunk_size])
+          end
+
+          InternalNode.new(branches)
+        end
+
+        def initialize(branches)
+          @branches = branches.freeze
+        end
+
+        def get(index, chunk_size)
+          new_chunk_size = chunk_size / BRANCHING_FACTOR
+          branch_index, inner_index = index.divmod(new_chunk_size)
+          @branches[branch_index].get(inner_index, new_chunk_size)
+        end
+
+        def set(index, value, chunk_size)
+          new_chunk_size = chunk_size / BRANCHING_FACTOR
+          branch_index, inner_index = index.divmod(new_chunk_size)
+          new_branches = @branches.dup
+          new_branches[branch_index] = new_branches[branch_index].set(inner_index, value, new_chunk_size)
+          InternalNode.new(new_branches)
+        end
+
+        def each(&)
+          @branches.each { |branch| branch.each(&) }
+        end
+      end
+
+      # A PersistentArray node that holds values
+      class LeafNode
+        # For compatibility with InternalNode
+        def self.from_values(values)
+          LeafNode.new(values)
+        end
+
+        def initialize(values)
+          @values = values.freeze
+        end
+
+        def get(index, _)
+          @values[index]
+        end
+
+        def set(index, value, _)
+          new_values = @values.dup
+          new_values[index] = value
+          LeafNode.new(new_values)
+        end
+
+        def each(&)
+          @values.each(&)
+        end
+      end
+    end
+
+    PersistentArray = PersistentArrayModule::PersistentArray
+  end
+end

data/lib/chess_engine/data_definitions/events.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'immutable'
+require 'wholeable'
+require_relative 'square'
+require_relative 'piece'
+require_relative 'primitives/colors'
+require_relative 'primitives/castling_data'
+
+module ChessEngine
+  # Events are immutable records representing game actions or state changes.
+  # They are produced by the parser (user intent) and by the engine (execution outcome).
+  #
+  # The parser may generate incomplete events.
+  # The event handler **must** populate all *required* fields, but **must not** populate *optional* fields.
+  #
+  # **NOTE:** The declaration of a field as optional is made explicitly within the event subclass definition.
+  module Events
+    # Base class for all events
+    class BaseEvent
+      include Wholeable[:assertions]
+
+      def initialize(assertions: nil)
+        # Assertions reflect the annotations sometimes appended to algebraic chess notation moves (e.g. "!", "?", "e.p.").
+        # Handlers must not depend on them for correctness.
+        # If assertions state plain falsehoods (e.g. claim check when not in check),
+        # the event may be considered invalid.
+        @assertions = assertions
+
+        # Get `BaseEvent#inspect` and `#to_s` specifically, since `Wholeable` overrides them
+        define_singleton_method(:inspect) do
+          BaseEvent.instance_method(:inspect).bind(self).call
+        end
+
+        define_singleton_method(:to_s) do
+          BaseEvent.instance_method(:to_s).bind(self).call
+        end
+      end
+
+      def inspect
+        filled, nils = to_h.partition { |_, v| !v.nil? }
+        filled_s = filled.map { |k, v| "#{k}=#{v.inspect}" }.join(', ')
+        nils = nils.map(&:first)
+        parts = [
+          filled_s.empty? ? nil : filled_s,
+          nils.empty? ? nil : "nil: [#{nils.join(', ')}]"
+        ].compact
+        "#<#{self.class} #{parts.join(', ')}>"
+      end
+
+      def to_s = inspect
+
+      def with(*, **)
+        raise NotImplementedError, "#with doesn't work for wholeables defined with positional arguments"
+      end
+    end
+
+    # Move a piece from one square to another.
+    # `captured` and `promote_to` are optional - only for captures and promotion, respectively.
+    class MovePieceEvent < BaseEvent
+      include Wholeable[:piece, :from, :to, :captured, :promote_to]
+
+      def initialize(piece, from, to, captured = nil, promote_to = nil, **)
+        super(**)
+        @piece = piece
+        @from = from
+        @to = to
+        @captured = captured
+        @promote_to = promote_to
+      end
+
+      def capture(captured_square = nil, captured_piece = nil)
+        with(captured: CaptureData[captured_square, captured_piece])
+      end
+
+      def promote(piece_type)
+        with(promote_to: piece_type)
+      end
+
+      def with(piece: self.piece, from: self.from, to: self.to, captured: self.captured, promote_to: self.promote_to,
+               assertions: self.assertions)
+        self.class.new(piece, from, to, captured, promote_to,
+                       assertions: assertions)
+      end
+    end
+
+    # Castling move.
+    class CastlingEvent < BaseEvent
+      include Wholeable[:color, :side]
+
+      SIDES = CastlingData::SIDES
+
+      def initialize(color, side, **)
+        super(**)
+        @color = color
+        @side = side
+      end
+
+      def king_from
+        ensure_validity
+        CastlingData.king_from(color, side)
+      end
+
+      def king_to
+        ensure_validity
+        CastlingData.king_to(color, side)
+      end
+
+      def rook_from
+        ensure_validity
+        CastlingData.rook_from(color, side)
+      end
+
+      def rook_to
+        ensure_validity
+        CastlingData.rook_to(color, side)
+      end
+
+      # For compatibility with the other events
+      def captured = nil
+
+      def with(color: self.color, side: self.side, assertions: self.assertions)
+        self.class.new(color, side, assertions: assertions)
+      end
+
+      private
+
+      def ensure_validity
+        return if Colors.valid?(color) && SIDES.include?(side)
+
+        raise ArgumentError, "Invalid fields for CastlingEvent: #{color}, #{side}"
+      end
+    end
+
+    # En passant move.
+    class EnPassantEvent < BaseEvent
+      include Wholeable[:color, :from, :to]
+
+      def initialize(color, from, to, **)
+        super(**)
+        @color = color
+        @from = from
+        @to = to
+      end
+
+      def piece
+        Piece[color, :pawn]
+      end
+
+      def captured
+        opponent_color = if Colors.valid?(color)
+                           color == :white ? :black : :white
+                         end
+
+        CaptureData[Square[to&.file, from&.rank], Piece[opponent_color, :pawn]]
+      end
+
+      def with(color: self.color, from: self.from, to: self.to, assertions: self.assertions)
+        self.class.new(color, from, to, assertions: assertions)
+      end
+    end
+
+    # Information about a captured piece. Used as a field/getter in certain events.
+    CaptureData = Data.define(:square, :piece) do
+      def initialize(square: nil, piece: nil)
+        super
+      end
+    end
+  end
+
+  MovePieceEvent = Events::MovePieceEvent
+  CastlingEvent = Events::CastlingEvent
+  EnPassantEvent = Events::EnPassantEvent
+end