qi 10.0.0.beta10 → 10.0.0.beta12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a009476d5905ba232aed52cafd6f8331632167af3a56c331be1d057b4a1ec964
-  data.tar.gz: f9a652c101b851e7e07d3b5fd69df6cb1965351697163e73c9600ff4b05251f4
+  metadata.gz: 7f3a609bb51c87ae5486c9244b948899f4e6ae46747ac80bf3be5f83ae76826a
+  data.tar.gz: 1843fa6cc35f2dcaaab08a7772abeb9f56fa3e7d0dc5dc69f9a742ec47e81169
 SHA512:
-  metadata.gz: 31c3aa57ebd829dcf24ca9604ef9a17dfb6a44fd0fd727dae76a730d3908c2f8cd2ba17d6dbc037ca9de88ac5913b4b4e759a967426d3e0c39b2100abb4891b1
-  data.tar.gz: 7b95a0bfdddd2be4fcdda01b64b2e42fc120f84d8becc5a5561383a41d88394a8d3a4e7b58a6d0721505d316c5e6e1357a0ddfff28f4179dec25c6af8e4b7688
+  metadata.gz: f79f7dc430f3e84b5cf816492c4f31c7776db329fffd18e161df929ccf18cb85b37cdd69e35c2b93da0e983e976d765bf69e8a33f1e946ec62d61c7b5583d164
+  data.tar.gz: '059b84b8c426af80188f0b6885ff921ab86f7015756d5309d75fd0ab621f1d93322be5f83f603a02535850645da432219af815871c480b56dec0e8f67db738bb'

data/README.md

@@ -6,14 +6,25 @@
 [![RuboCop](https://github.com/sashite/qi.rb/workflows/RuboCop/badge.svg?branch=main)](https://github.com/sashite/qi.rb/actions?query=workflow%3Arubocop+branch%3Amain)
 [![License](https://img.shields.io/github/license/sashite/qi.rb?label=License&logo=github)](https://github.com/sashite/qi.rb/raw/main/LICENSE.md)
 
-> `Qi` (Chinese: 棋; pinyin: _qí_) is an abstraction that could help to update positions for games like Shogi.
+Welcome to `Qi` (Chinese: 棋; pinyin: _qí_), a flexible and customizable library designed to represent and manipulate board game positions. `Qi` is ideal for a variety of board games, including chess, shogi, xiangqi, makruk, and more.
+
+With `Qi`, you can easily track the game state, including which pieces are on the board and where, as well as any captured pieces. The library allows for the application of game moves, updating the state of the game and generating a new position, all while preserving the original state.
+
+## Features:
+
+- **Flexible representation of game states:** `Qi`'s design allows it to adapt to different games with varying rules and pieces.
+- **Immutable positions:** Every move generates a new position, preserving the original one. This is particularly useful for scenarios like undoing moves or exploring potential future states in the game.
+- **Compact serialization:** `Qi` provides a compact string serialization method for game states, which is useful for saving game progress or transmitting game states over the network.
+- **Check state tracking:** In addition to the positions and captured pieces, `Qi` also allows tracking of specific game states such as check in chess.
+
+While `Qi` does not generate game moves itself, it serves as a solid foundation upon which game engines can be built. Its design is focused on providing a robust and adaptable representation of game states, paving the way for the development of diverse board game applications.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "qi", ">= 10.0.0.beta10"
+gem "qi", ">= 10.0.0.beta12"
 ```
 
 And then execute:
@@ -33,42 +44,40 @@ gem install qi --pre
 ```ruby
 require "qi"
 
-is_north_turn   = false
 north_captures  = %w[r r b g g g g s n n n n p p p p p p p p p p p p p p p p p]
 south_captures  = %w[S]
+captures        = north_captures + south_captures
 squares         = { 3 => "s", 4 => "k", 5 => "s", 22 => "+P", 43 => "+B" }
 
-qi0 = Qi.new(is_north_turn, north_captures, south_captures, squares, false)
-
-qi0.north_captures  # => ["b", "g", "g", "g", "g", "n", "n", "n", "n", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "r", "r", "s"]
-qi0.south_captures  # => ["S"]
-qi0.squares         # => {3=>"s", 4=>"k", 5=>"s", 22=>"+P", 43=>"+B"}
-qi0.north_turn?     # => false
-qi0.south_turn?     # => true
-qi0.serialize       # => "South-turn===S,b,g,g,g,g,n,n,n,n,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,r,r,s===3:s,4:k,5:s,22:+P,43:+B===not-in-check"
-qi0.inspect         # => "<Qi South-turn===S,b,g,g,g,g,n,n,n,n,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,r,r,s===3:s,4:k,5:s,22:+P,43:+B===not-in-check>"
+qi0 = Qi.new(*captures, **squares)
 
+qi0.captures      # => ["S", "b", "g", "g", "g", "g", "n", "n", "n", "n", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "r", "r", "s"]
+qi0.squares       # => {3=>"s", 4=>"k", 5=>"s", 22=>"+P", 43=>"+B"}
+qi0.in_check?     # => false
+qi0.not_in_check? # => true
+qi0.north_turn?   # => false
+qi0.south_turn?   # => true
+qi0.serialize     # => "{ S;b;g;g;g;g;n;n;n;n;p;p;p;p;p;p;p;p;p;p;p;p;p;p;p;p;p;r;r;s s@3;k@4;s@5;+P@22;+B@43 ."
+qi0.inspect       # => "<Qi { S;b;g;g;g;g;n;n;n;n;p;p;p;p;p;p;p;p;p;p;p;p;p;p;p;p;p;r;r;s s@3;k@4;s@5;+P@22;+B@43 .>"
 qi0.to_a
 # [false,
-#  ["b", "g", "g", "g", "g", "n", "n", "n", "n", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "r", "r", "s"],
-#  ["S"],
+#  ["S", "b", "g", "g", "g", "g", "n", "n", "n", "n", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "r", "r", "s"],
 #  {3=>"s", 4=>"k", 5=>"s", 22=>"+P", 43=>"+B"},
 #  false]
 
-qi1 = qi0.commit({ 43 => nil, 13 => "+B" }, nil, is_drop: nil, is_in_check: true)
-
-qi1.north_captures  # => ["b", "g", "g", "g", "g", "n", "n", "n", "n", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "r", "r", "s"]
-qi1.south_captures  # => ["S"]
-qi1.squares         # => {3=>"s", 4=>"k", 5=>"s", 22=>"+P", 13=>"+B"}
-qi1.north_turn?     # => true
-qi1.south_turn?     # => false
-qi1.serialize       # => "North-turn===S,b,g,g,g,g,n,n,n,n,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,r,r,s===3:s,4:k,5:s,22:+P,13:+B===in-check"
-qi1.inspect         # => "<Qi North-turn===S,b,g,g,g,g,n,n,n,n,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,p,r,r,s===3:s,4:k,5:s,22:+P,13:+B===in-check>"
+qi1 = qi0.commit(is_in_check: true, 43 => nil, 13 => "+B")
 
+qi1.captures      # => ["S", "b", "g", "g", "g", "g", "n", "n", "n", "n", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "r", "r", "s"]
+qi1.squares       # => {3=>"s", 4=>"k", 5=>"s", 22=>"+P", 13=>"+B"}
+qi1.in_check?     # => true
+qi1.not_in_check? # => false
+qi1.north_turn?   # => true
+qi1.south_turn?   # => false
+qi1.serialize     # => "} S;b;g;g;g;g;n;n;n;n;p;p;p;p;p;p;p;p;p;p;p;p;p;p;p;p;p;r;r;s s@3;k@4;s@5;+B@13;+P@22 +"
+qi1.inspect       # => "<Qi } S;b;g;g;g;g;n;n;n;n;p;p;p;p;p;p;p;p;p;p;p;p;p;p;p;p;p;r;r;s s@3;k@4;s@5;+B@13;+P@22 +>"
 qi1.to_a
 # [true,
-#  ["b", "g", "g", "g", "g", "n", "n", "n", "n", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "r", "r", "s"],
-#  ["S"],
+#  ["S", "b", "g", "g", "g", "g", "n", "n", "n", "n", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "r", "r", "s"],
 #  {3=>"s", 4=>"k", 5=>"s", 22=>"+P", 13=>"+B"},
 #  true]
 ```

data/lib/qi.rb

@@ -1,263 +1,132 @@
 # frozen_string_literal: true
 
 require "digest"
-require_relative "qi/error/drop"
+require "kernel/boolean"
 
-# The Qi class represents the current state of a game, tracking both the positions of pieces on the board and the pieces captured by each player.
-# It provides methods for manipulating the game state, including moving pieces around the board, capturing opponent's pieces, and dropping pieces from hand onto the board.
-# Additionally, it maintains information about the current game turn (which player's turn it is) and whether a player is in check.
+# The Qi class represents a state of games such as Shogi.
 class Qi
-  # Constant representing the North player.
-  North = "North"
+  # @return [Array] the pieces captured by the current player.
+  attr_reader :captures
 
-  # Constant representing the South player.
-  South = "South"
-
-  # @!attribute [r] north_captures
-  # @return [Array] The list of pieces captured by the North player.
-  attr_reader :north_captures
-
-  # @!attribute [r] south_captures
-  # @return [Array] The list of pieces captured by the South player.
-  attr_reader :south_captures
-
-  # @!attribute [r] squares
-  # @return [Hash] The current state of the board, represented as a hash where each key is a position and each value is the state of that position.
+  # @return [Hash] the current state of the board.
   attr_reader :squares
 
-  # Initializes a new instance of the game state.
-  #
-  # @param is_north_turn [Boolean] True if it's North's turn, false otherwise.
-  # @param north_captures [Array] An array representing the pieces captured by North.
-  # @param south_captures [Array] An array representing the pieces captured by South.
-  # @param squares [Hash] A hash representing the state of the squares on the board.
-  # @param is_in_check [Boolean] True if the current player is in check, false otherwise.
-  def initialize(is_north_turn, north_captures, south_captures, squares, is_in_check)
-    @is_north_turn  = is_north_turn
-    @north_captures = north_captures.sort
-    @south_captures = south_captures.sort
+  # Initializes a new game state.
+  #
+  # @param capture [String, nil] the piece to be captured.
+  # @param captures [Array] the pieces already captured.
+  # @param drop [String, nil] the piece to be dropped.
+  # @param is_in_check [Boolean] whether the current player is in check.
+  # @param is_north_turn [Boolean] whether it's North's turn.
+  # @param squares [Hash] the current state of the board.
+  def initialize(capture = nil, *captures, drop: nil, is_in_check: false, is_north_turn: false, **squares)
+    captures << capture                       unless capture.nil?
+    captures.delete_at(captures.rindex(drop)) unless drop.nil?
+
+    @captures       = captures.sort
+    @is_in_check    = Boolean(is_in_check)
+    @is_north_turn  = Boolean(is_north_turn)
     @squares        = squares.compact
-    @is_in_check    = is_in_check
-  end
-
-  # Creates a new game state by applying a set of diffs to the squares and the captures.
-  # Raises an error if in_hand is provided but is_drop is not, or vice versa.
-  #
-  # @param diffs [Hash] A hash representing the changes to the squares. Each key is a position, and each value is the new state of that position.
-  # @param in_hand [String, nil] A string representing the piece that the current player has in hand, or nil if no piece is in hand.
-  # @param is_drop [Boolean, nil] True if the current player is dropping a piece, false if they are not, or nil if there is no piece in hand.
-  # @param is_in_check [Boolean] True if the current player is in check after the move, false otherwise.
-  # @return [Qi] The new game state after applying the diffs.
-  # @raise [ArgumentError] If in_hand is provided but is_drop is not, or vice versa.
-  def commit(diffs, in_hand, is_drop:, is_in_check:)
-    if !in_hand.nil? && is_drop.nil?
-      raise ::ArgumentError, "A piece is in hand, but is_drop is not provided"
-    elsif in_hand.nil? && !is_drop.nil?
-      raise ::ArgumentError, "No piece is in hand, but is_drop is provided"
-    end
-
-    modified_squares = squares.merge(diffs)
-    modified_captures = update_captures(in_hand, is_drop:)
-    self.class.new(south_turn?, *modified_captures, modified_squares, is_in_check)
-  end
-
-  # Checks if this game state is equal to another.
-  # Two game states are considered equal if they can be serialized to the same string.
-  #
-  # @param other [Object] The object to compare with this game state.
-  # @return [Boolean] True if the other object can be serialized and its serialized form is equal to this game state's serialized form, false otherwise.
-  def eql?(other)
-    return false unless other.respond_to?(:serialize)
-
-    other.serialize == serialize
   end
-  alias == eql?
 
-  # Returns the captures of the current player.
+  # Commits a move and returns a new game state.
   #
-  # @return [Array] An array or other iterable representing the pieces captured by the current player.
-  def current_captures
-    if north_turn?
-      north_captures
-    else
-      south_captures
-    end
+  # @param capture [String, nil] the piece to be captured.
+  # @param drop [String, nil] the piece to be dropped.
+  # @param is_in_check [Boolean] whether the current player is in check.
+  # @param diffs [Hash] the differences in the state of the board.
+  # @return [Qi] the new game state.
+  def commit(capture: nil, drop: nil, is_in_check: false, **diffs)
+    self.class.new(capture, *captures, drop:, is_in_check:, is_north_turn: south_turn?, **squares.merge(diffs))
   end
 
-  # Returns the list of pieces that the current player's opponent has captured.
-  #
-  # @return [Array] An array of pieces that the opponent has captured.
-  def opponent_captures
-    if north_turn?
-      south_captures
-    else
-      north_captures
-    end
-  end
-
-  # Returns the name of the current side.
-  #
-  # @return [String] "North" if it's North's turn, "South" otherwise.
-  def current_turn
-    if north_turn?
-      North
-    else
-      South
-    end
+  # @return [Boolean] whether the current player is in check.
+  def in_check?
+    @is_in_check
   end
 
-  # Returns the name of the next side.
-  # If it's currently the North player's turn, this method will return "South", and vice versa.
-  #
-  # @return [String] "South" if it's North's turn, "North" otherwise.
-  def next_turn
-    if north_turn?
-      South
-    else
-      North
-    end
+  # @return [Boolean] whether the current player is not in check.
+  def not_in_check?
+    !in_check?
   end
 
-  # Checks if it's North's turn.
-  #
-  # @return [Boolean] True if it's North's turn, false otherwise.
+  # @return [Boolean] whether it's North's turn.
   def north_turn?
     @is_north_turn
   end
 
-  # Checks if it's South's turn.
-  #
-  # @return [Boolean] True if it's South's turn, false otherwise.
+  # @return [Boolean] whether it's South's turn.
   def south_turn?
     !north_turn?
   end
 
-  # Checks if the current player is in check.
-  #
-  # @return [Boolean] True if the current player is in check, false otherwise.
-  def in_check?
-    @is_in_check
-  end
+  # @return [Boolean] whether the other game state is equal to this one.
+  def eql?(other)
+    return false unless other.respond_to?(:serialize)
 
-  # Checks if the current player is not in check.
-  #
-  # @return [Boolean] True if the current player is not in check, false otherwise.
-  def not_in_check?
-    !in_check?
+    other.serialize == serialize
   end
+  alias == eql?
 
-  # Converts the current game state to an array. The resulting array includes:
-  # whether it's North's turn, the pieces captured by North, the pieces captured by South,
-  # the state of the squares, and whether the current player is in check.
-  # This array can be used for various purposes, such as saving the game state,
-  # transmitting the game state over a network, or analyzing the game state.
-  #
-  # @return [Array] The game state, represented as an array. The elements of the array are:
-  #   - A boolean indicating whether it's North's turn,
-  #   - An array or other iterable representing the pieces captured by North,
-  #   - An array or other iterable representing the pieces captured by South,
-  #   - A data structure representing the state of the squares on the board,
-  #   - A boolean indicating whether the current player is in check.
+  # @return [Array] the array representation of the game state.
   def to_a
     [
       north_turn?,
-      north_captures,
-      south_captures,
+      captures,
       squares,
       in_check?
     ]
   end
 
-  # Converts the current game state to a hash. The resulting hash includes:
-  # whether it's North's turn, the pieces captured by North, the pieces captured by South,
-  # the state of the squares, and whether the current player is in check.
-  # This hash can be used for various purposes, such as saving the game state,
-  # transmitting the game state over a network, or analyzing the game state.
-  #
-  # @return [Hash] The game state, represented as a hash. The keys of the hash are:
-  #   - :is_north_turn, a boolean indicating whether it's North's turn,
-  #   - :north_captures, an array or other iterable representing the pieces captured by North,
-  #   - :south_captures, an array or other iterable representing the pieces captured by South,
-  #   - :squares, a data structure representing the state of the squares on the board,
-  #   - :is_in_check, a boolean indicating whether the current player is in check.
+  # @return [Hash] the hash representation of the game state.
   def to_h
     {
-      is_north_turn:  north_turn?,
-      north_captures:,
-      south_captures:,
+      is_north_turn: north_turn?,
+      captures:,
       squares:,
-      is_in_check:    in_check?
+      is_in_check:   in_check?
     }
   end
 
-  # Returns the hash-code for the position.
+  # @return [String] the SHA-256 hash of the serialized game state.
   def hash
     ::Digest::SHA256.hexdigest(serialize)
   end
 
-  # Returns a sorted list of all pieces currently on the board.
-  #
-  # @return [Array] An array of all pieces currently on the board.
-  def board_pieces
-    squares.keys.sort
-  end
-
-  # Serialize the current game state to a string. The serialized state includes:
-  # the current turn, the captured pieces, the state of the squares, and whether
-  # the current player is in check. The serialized state can be used to save
-  # the game, or to transmit the game state over a network.
-  #
-  # @return [String] The serialized game state.
+  # @return [String] the string representation of the game state.
   def serialize
-    serialized_turn     = "#{current_turn}-turn"
-    serialized_captures = (north_captures + south_captures).sort.join(",")
-    serialized_squares  = board_pieces.map { |i| "#{i}:#{squares.fetch(i)}" }.join(",")
-    serialized_check    = (in_check? ? "in-check" : "not-in-check")
-
-    "#{serialized_turn}===#{serialized_captures}===#{serialized_squares}===#{serialized_check}"
+    [
+      serialized_turn,
+      serialized_captures,
+      serialized_squares,
+      serialized_in_check
+    ].join(" ")
   end
 
-  # Provides a string representation of the game state, including the class name and the serialized game state.
-  #
-  # @return [String] A string representation of the game state.
+  # @return [String] the string representation of the object.
   def inspect
     "<#{self.class} #{serialize}>"
   end
 
   private
 
-  # Updates the list of captures based on the piece in hand and whether the move is a drop.
-  # If the in_hand parameter is nil, the method returns the current captures without modification.
-  # Otherwise, the method either adds the piece in hand to the current player's captures (if is_drop is false),
-  # or removes the piece in hand from the current player's captures (if is_drop is true).
-  #
-  # @param in_hand [String, nil] The piece in hand, or nil if no piece is in hand.
-  # @param is_drop [Boolean] True if the current move is a drop, false otherwise.
-  # @return [Array] The updated list of captures for North and South.
-  def update_captures(in_hand, is_drop:)
-    return [north_captures, south_captures] if in_hand.nil?
-
-    captures = if is_drop
-                 remove_from_captures(in_hand, *current_captures)
-               else
-                 current_captures + [in_hand]
-               end
+  # @return [String] the serialized turn.
+  def serialized_turn
+    north_turn? ? "}" : "{"
+  end
 
-    north_turn? ? [captures, opponent_captures] : [opponent_captures, captures]
+  # @return [String] the serialized captures.
+  def serialized_captures
+    captures.join(";")
   end
 
-  # Removes a piece from the captures.
-  # The method raises an error if the piece is not found in the captures.
-  #
-  # @param piece [String] The piece to remove from the captures.
-  # @param captures [Array] The list of captures.
-  # @return [Array] The updated list of captures.
-  # @raise [Error::Drop] If the piece is not found in the captures.
-  def remove_from_captures(piece, *captures)
-    index = captures.rindex(piece)
-    raise Error::Drop, "There are no #{piece} in hand" if index.nil?
+  # @return [String] the serialized board state.
+  def serialized_squares
+    squares.keys.sort.map { |i| "#{squares.fetch(i)}@#{i}" }.join(";")
+  end
 
-    captures.delete_at(index)
-    captures
+  # @return [String] the serialized check state.
+  def serialized_in_check
+    in_check? ? "+" : "."
   end
 end

metadata

@@ -1,16 +1,31 @@
 --- !ruby/object:Gem::Specification
 name: qi
 version: !ruby/object:Gem::Version
-  version: 10.0.0.beta10
+  version: 10.0.0.beta12
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-05-11 00:00:00.000000000 Z
-dependencies: []
-description: An abstraction that could help to update positions for games like Shogi.
+date: 2023-05-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: kernel-boolean
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A flexible and customizable library for representing and manipulating
+  game states, ideal for developing board games like chess, shogi, or xiangqi.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -19,7 +34,6 @@ files:
 - LICENSE.md
 - README.md
 - lib/qi.rb
-- lib/qi/error/drop.rb
 homepage: https://github.com/sashite/qi.rb
 licenses:
 - MIT
@@ -43,5 +57,5 @@ requirements: []
 rubygems_version: 3.4.10
 signing_key: 
 specification_version: 4
-summary: An abstraction that could help to update positions for games like Shogi.
+summary: Versatile Board Game Position Representation
 test_files: []

data/lib/qi/error/drop.rb

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-class Qi
-  # The Error module contains custom error classes for the Qi game.
-  module Error
-    # The Drop class is a custom error class that inherits from IndexError.
-    # It is raised when a drop operation in the game of Qi is invalid.
-    #
-    # @see IndexError
-    class Drop < ::IndexError
-    end
-  end
-end