qi 10.0.0.beta9 → 10.0.0.beta10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 807fc7b14621e81663ea476f2d737352d455d4d2ab1d49efbe722c3ce571ed15
-  data.tar.gz: 9244deacf36f2717897a23b56de132af40ce308cd5977ee92899f57c49368f0e
+  metadata.gz: a009476d5905ba232aed52cafd6f8331632167af3a56c331be1d057b4a1ec964
+  data.tar.gz: f9a652c101b851e7e07d3b5fd69df6cb1965351697163e73c9600ff4b05251f4
 SHA512:
-  metadata.gz: 87cedbb94ddcecb3026647893aac63ce6559c92d37dc65121850efca0eb1ddd7a1616e441a0c40463a2bbe664de59d4498bbcfcfd3aa3caae6075a65851c57c5
-  data.tar.gz: 62a213dcaeb4d68cc6c4bc01b4d9b4a2df33b3d8bcca09c5e494e6a5b0eb349b236907437caa12c11777c6eaac559402e927f3db972f89acb4cd07f77408c4d9
+  metadata.gz: 31c3aa57ebd829dcf24ca9604ef9a17dfb6a44fd0fd727dae76a730d3908c2f8cd2ba17d6dbc037ca9de88ac5913b4b4e759a967426d3e0c39b2100abb4891b1
+  data.tar.gz: 7b95a0bfdddd2be4fcdda01b64b2e42fc120f84d8becc5a5561383a41d88394a8d3a4e7b58a6d0721505d316c5e6e1357a0ddfff28f4179dec25c6af8e4b7688

data/README.md

@@ -13,7 +13,7 @@
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "qi", ">= 10.0.0.beta9"
+gem "qi", ">= 10.0.0.beta10"
 ```
 
 And then execute:
@@ -38,37 +38,39 @@ 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]
 squares         = { 3 => "s", 4 => "k", 5 => "s", 22 => "+P", 43 => "+B" }
 
-qi0 = Qi.new(is_north_turn, north_captures, south_captures, squares)
+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"
-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>"
+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.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"],
-#  {3=>"s", 4=>"k", 5=>"s", 22=>"+P", 43=>"+B"}]
+#  {3=>"s", 4=>"k", 5=>"s", 22=>"+P", 43=>"+B"},
+#  false]
 
-qi1 = qi0.commit({ 43 => nil, 13 => "+B" })
+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"
-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>"
+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.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"],
-#  {3=>"s", 4=>"k", 5=>"s", 22=>"+P", 13=>"+B"}]
+#  {3=>"s", 4=>"k", 5=>"s", 22=>"+P", 13=>"+B"},
+#  true]
 ```
 
 ## License

data/lib/qi/error/drop.rb

@@ -1,7 +1,12 @@
 # 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

data/lib/qi.rb

@@ -3,45 +3,69 @@
 require "digest"
 require_relative "qi/error/drop"
 
-# A class that represents the state of a game.
+# 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.
 class Qi
+  # Constant representing the North player.
+  North = "North"
+
+  # Constant representing the South player.
+  South = "South"
+
   # @!attribute [r] north_captures
-  #   @return [Array] an array of pieces captured by the north player
+  # @return [Array] The list of pieces captured by the North player.
+  attr_reader :north_captures
+
   # @!attribute [r] south_captures
-  #   @return [Array] an array of pieces captured by the south player
+  # @return [Array] The list of pieces captured by the South player.
+  attr_reader :south_captures
+
   # @!attribute [r] squares
-  #   @return [Hash] a hash of pieces on the board
-  attr_reader :north_captures, :south_captures, :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.
+  attr_reader :squares
 
-  # Initializes a new Qi object with the given attributes.
+  # Initializes a new instance of the game state.
   #
-  # @param is_north_turn [Boolean] a boolean value indicating whose turn it is
-  # @param north_captures [Array<Object>] an array of pieces captured by the north player
-  # @param south_captures [Array<Object>] an array of pieces captured by the south player
-  # @param squares [Hash<Object, Object>] a hash of squares on the board
-  def initialize(is_north_turn, north_captures, south_captures, squares)
-    # Assign the parameters to instance variables.
+  # @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
     @squares        = squares.compact
+    @is_in_check    = is_in_check
   end
 
-  # Returns a new Qi object that represents the state after applying the given changes.
+  # 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<Object, Object>] a hash of changes to apply to the squares hash
-  # @param in_hand [Object, nil] the piece that is in hand or nil if none
-  # @param is_drop [Boolean] a boolean value indicating whether the in hand piece is dropped or not
-  # @return [Qi] a new Qi object with modified attributes, where:
-  #   - the turn is switched
-  #   - the captures are updated according to the in hand piece and the drop flag
-  #   - the squares are merged with the diffs hash
-  def commit(diffs = {}, in_hand = nil, is_drop: false)
+  # @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(!north_turn?, *modified_captures, modified_squares)
+    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)
 
@@ -49,7 +73,21 @@ class Qi
   end
   alias == eql?
 
-  def other_captures
+  # Returns the captures of the current player.
+  #
+  # @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
+  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
@@ -57,65 +95,98 @@ class Qi
     end
   end
 
-  def owned_captures
+  # 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_captures
+      North
     else
-      south_captures
+      South
     end
   end
 
-  def side_name
+  # 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?
-      "north"
+      South
     else
-      "south"
+      North
     end
   end
 
-  # Checks if it is the north turn or not.
+  # Checks if it's North's turn.
   #
-  # @return [Boolean] true if it is the north turn and false otherwise
+  # @return [Boolean] True if it's North's turn, false otherwise.
   def north_turn?
     @is_north_turn
   end
 
-  # Checks if it is not the north turn or not.
+  # Checks if it's South's turn.
   #
-  # @return [Boolean] true if it is not the north turn and false otherwise
+  # @return [Boolean] True if it's South's turn, false otherwise.
   def south_turn?
     !north_turn?
   end
 
-  # Returns an array representation of the Qi object's attributes.
+  # 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
+
+  # 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?
+  end
+
+  # 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(Boolean, Array<Object>, Array<Object>, Hash<Object, Object>)] an array containing four elements:
-  #   - a boolean value indicating whose turn it is
-  #   - an array of pieces captured by the north player
-  #   - an array of pieces captured by the south player
-  #   - a hash of squares on the board
+  # @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.
   def to_a
     [
       north_turn?,
       north_captures,
       south_captures,
-      squares
+      squares,
+      in_check?
     ]
   end
 
-  # Returns a hash representation of the Qi object's attributes.
+  # 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{Symbol => Object}] a hash containing four key-value pairs:
-  #   - is_north_turn: a boolean value indicating whose turn it is
-  #   - north_captures: an array of pieces captured by the north player
-  #   - south_captures: an array of pieces captured by the south player
-  #   - squares: a hash of squares on the board
+  # @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.
   def to_h
     {
       is_north_turn:  north_turn?,
       north_captures:,
       south_captures:,
-      squares:
+      squares:,
+      is_in_check:    in_check?
     }
   end
 
@@ -124,55 +195,67 @@ class Qi
     ::Digest::SHA256.hexdigest(serialize)
   end
 
-  # Returns a string representation of the Qi object's attributes.
+  # 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] a string containing three parts separated by "===":
-  #   - the current turn, either "NorthTurn" or "SouthTurn"
-  #   - the captures, sorted and joined by ","
-  #   - the squares, mapped to "coordinate:piece" pairs and joined by ","
+  # @return [String] The serialized game state.
   def serialize
-    serialized_turn     = "#{side_name}-turn"
+    serialized_turn     = "#{current_turn}-turn"
     serialized_captures = (north_captures + south_captures).sort.join(",")
-    serialized_squares  = squares.keys.map { |i| "#{i}:#{squares.fetch(i)}" }.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_turn}===#{serialized_captures}===#{serialized_squares}===#{serialized_check}"
   end
 
-  # Returns a human-readable representation of the Qi object.
+  # Provides a string representation of the game state, including the class name and the serialized game state.
   #
-  # @return [String] a string containing the class name and the serialized attributes
+  # @return [String] A string representation of the game state.
   def inspect
     "<#{self.class} #{serialize}>"
   end
 
   private
 
-  # Updates the captures arrays based on the piece in hand and whether it is dropped or not.
+  # 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 [Object, nil] the piece that is in hand or nil if none
-  # @param is_drop [Boolean] a boolean value indicating whether the in hand piece is dropped or not
-  # @return [Array] an array containing the updated north and south captures arrays
+  # @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, *owned_captures)
+                 remove_from_captures(in_hand, *current_captures)
                else
-                 owned_captures + [in_hand]
+                 current_captures + [in_hand]
                end
 
-    north_turn? ? [captures, other_captures] : [other_captures, captures]
+    north_turn? ? [captures, opponent_captures] : [opponent_captures, captures]
   end
 
-  # Removes the last occurrence of a piece from an array of captures and returns the modified array.
+  # Removes a piece from the captures.
+  # The method raises an error if the piece is not found in the captures.
   #
-  # @param piece [Object] the piece to be removed
-  # @param captures [Array<Object>] the array of captures
-  # @return [Array<Object>] the modified array of captures
-  # @raise [Qi::Error::Drop] if the piece is not found in the array
+  # @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?
+    raise Error::Drop, "There are no #{piece} in hand" if index.nil?
 
     captures.delete_at(index)
     captures

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: qi
 version: !ruby/object:Gem::Version
-  version: 10.0.0.beta9
+  version: 10.0.0.beta10
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-05-06 00:00:00.000000000 Z
+date: 2023-05-11 00:00:00.000000000 Z
 dependencies: []
 description: An abstraction that could help to update positions for games like Shogi.
 email: contact@cyril.email
@@ -40,7 +40,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: 1.3.1
 requirements: []
-rubygems_version: 3.4.6
+rubygems_version: 3.4.10
 signing_key: 
 specification_version: 4
 summary: An abstraction that could help to update positions for games like Shogi.