qi 10.0.0.beta9 → 10.0.0.beta11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 807fc7b14621e81663ea476f2d737352d455d4d2ab1d49efbe722c3ce571ed15
-  data.tar.gz: 9244deacf36f2717897a23b56de132af40ce308cd5977ee92899f57c49368f0e
+  metadata.gz: 79ffab5e654d14cf9f3f7dac1c50bc5b5c612452d0fdea35a00d3529337fbff2
+  data.tar.gz: b8fecf9ff5dd97923070809b6a906c8b44cebbee9695ea242e314d53afb9fad8
 SHA512:
-  metadata.gz: 87cedbb94ddcecb3026647893aac63ce6559c92d37dc65121850efca0eb1ddd7a1616e441a0c40463a2bbe664de59d4498bbcfcfd3aa3caae6075a65851c57c5
-  data.tar.gz: 62a213dcaeb4d68cc6c4bc01b4d9b4a2df33b3d8bcca09c5e494e6a5b0eb349b236907437caa12c11777c6eaac559402e927f3db972f89acb4cd07f77408c4d9
+  metadata.gz: cb36bd477ba3e756b116e3f2ab55bdb15ea50834461cc614865d8fdda56e271eff4675d998172bd766b8ca33e6944be3bbf567a1eba96b6215816234c485f6c9
+  data.tar.gz: e56b5f73bf2c0a1a3a256f813acfcf24af3bc3cdd570f2fb6ab1aa2f7ebc194ddd0b82e5ade5cbc052229377a8c768d3f49f45188d811a756ab7781481c69f08

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.beta11"
 ```
 
 And then execute:
@@ -45,30 +45,30 @@ 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===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"
+qi0.inspect         # => "<Qi South-turn===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>"
 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"},
+#  {}]
 
-qi1 = qi0.commit({ 43 => nil, 13 => "+B" })
+qi1 = qi0.commit(43, 13, "+B", nil)
 
 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===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,13:+B,22:+P"
+qi1.inspect         # => "<Qi North-turn===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,13:+B,22:+P>"
 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"},
+#  {}]
 ```
 
 ## 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,84 @@
 require "digest"
 require_relative "qi/error/drop"
 
-# A class that represents the state of a game.
+# Qi is a class for representing a state of games like Shogi. It includes
+# information about the current turn, captures, game board, and other game options.
 class Qi
-  # @!attribute [r] north_captures
-  #   @return [Array] an array of pieces captured by the north player
-  # @!attribute [r] south_captures
-  #   @return [Array] an array of pieces captured by the south player
-  # @!attribute [r] squares
-  #   @return [Hash] a hash of pieces on the board
-  attr_reader :north_captures, :south_captures, :squares
-
-  # Initializes a new Qi object with the given attributes.
-  #
-  # @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.
+  # Constants for representing the North and South players.
+  North = :North
+  South = :South
+
+  # @return [Array] the pieces captured by the north player
+  attr_reader :north_captures
+
+  # @return [Array] the pieces captured by the south player
+  attr_reader :south_captures
+
+  # @return [Hash] the current state of the game board
+  attr_reader :squares
+
+  # @return [Hash] additional game options
+  attr_reader :options
+
+  # Initialize a new Qi object.
+  #
+  # @example Creating a new Qi object
+  #   qi = Qi.new(true, ['P', 'G'], ['B', '+B'], {56 => 'P', 3 => 'g', 64 => '+B'}, fullmove_number: 42, is_in_check: false)
+  #
+  # @param [Boolean] is_north_turn true if it's the north player's turn, false otherwise
+  # @param [Array] north_captures the pieces captured by the north player
+  # @param [Array] south_captures the pieces captured by the south player
+  # @param [Hash] squares the current state of the game board
+  # @param [Hash] options additional game options
+  def initialize(is_north_turn, north_captures, south_captures, squares, **options)
     @is_north_turn  = is_north_turn
     @north_captures = north_captures.sort
     @south_captures = south_captures.sort
     @squares        = squares.compact
+    @options        = options
   end
 
-  # Returns a new Qi object that represents the state after applying the given changes.
+  # Apply a move or a drop on the board.
+  #
+  # The method creates a new instance of Qi representing the state of the game after the move.
+  # This includes updating the captures and the positions of the pieces on the board.
+  #
+  # @param src_square [Object, nil] the source square, or nil if dropping a piece from hand
+  # @param dst_square [Object] the destination square
+  # @param piece_name [String] the name of the piece to move
+  # @param in_hand [String, nil] the piece in hand, or nil if moving a piece from a square
+  # @param options [Hash] options to pass to the new instance
+  #
+  # @example Applying a move
+  #   qi = Qi.new(true, ['P', 'B'], ['G', '+B'], {56 => 'P', 64 => '+B'})
+  #   qi.commit(56, 47, 'P', nil) #=> <Qi South-turn===B,P,+B,G===47:P,64:+B>
   #
-  # @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)
-    modified_squares = squares.merge(diffs)
-    modified_captures = update_captures(in_hand, is_drop:)
-    self.class.new(!north_turn?, *modified_captures, modified_squares)
+  # @example Applying a capture
+  #   qi = Qi.new(true, ['P', 'B'], ['G', '+B'], {56 => 'P', 64 => '+B'})
+  #   qi.commit(56, 47, 'P', 'G') #=> <Qi South-turn===B,G,P,+B,G===47:P,64:+B>
+  #
+  # @example Applying a drop
+  #   qi = Qi.new(true, ['P', 'B', 'G'], ['G', '+B'], {56 => 'P', 64 => '+B'})
+  #   qi.commit(nil, 47, 'G', 'G') #=> <Qi South-turn===B,P,+B,G===47:G,56:P,64:+B>
+  #
+  # @return [Qi] the new game state after the move
+  def commit(src_square, dst_square, piece_name, in_hand, **options)
+    raise ::ArgumentError, "Both src_square and in_hand cannot be nil" if src_square.nil? && in_hand.nil?
+
+    modified_captures = update_captures(src_square, in_hand)
+    modified_squares = squares.merge({ src_square => nil, dst_square => piece_name })
+    self.class.new(south_turn?, *modified_captures, modified_squares, **options)
   end
 
+  # Compare this Qi object with another for equality.
+  #
+  # @example Comparing two Qi objects
+  #   qi1 = Qi.new(...)
+  #   qi2 = Qi.new(...)
+  #   qi1.eql?(qi2) #=> true or false
+  #
+  # @param [Qi] other the other Qi object to compare with
+  # @return [Boolean] true if the two objects represent the same game state, false otherwise
   def eql?(other)
     return false unless other.respond_to?(:serialize)
 
@@ -49,130 +88,180 @@ class Qi
   end
   alias == eql?
 
-  def other_captures
-    if north_turn?
-      south_captures
-    else
-      north_captures
-    end
+  # Get the captures of the current player.
+  #
+  # The method returns the north player's captures when it's their turn,
+  # and the south player's captures when it's their turn.
+  #
+  # @example When it's the north player's turn
+  #   qi = Qi.new(true, ['P', 'B'], ['G', '+B'], {56 => 'P', 64 => '+B'})
+  #   qi.current_captures #=> ['B', 'P']
+  #
+  # @example When it's the south player's turn
+  #   qi = Qi.new(false, ['P', 'B'], ['G', '+B'], {56 => 'P', 64 => '+B'})
+  #   qi.current_captures #=> ['+B', 'G']
+  #
+  # @return [Array] the captures of the current player
+  def current_captures
+    north_turn? ? north_captures : south_captures
   end
 
-  def owned_captures
-    if north_turn?
-      north_captures
-    else
-      south_captures
-    end
+  # Get the captures of the opponent player.
+  #
+  # @return [Array] the captures of the opponent player
+  def opponent_captures
+    north_turn? ? south_captures : north_captures
   end
 
-  def side_name
-    if north_turn?
-      "north"
-    else
-      "south"
-    end
+  # Get the current turn.
+  #
+  # @return [Symbol] :North if it's the north player's turn, :South otherwise
+  def current_turn
+    north_turn? ? North : South
   end
 
-  # Checks if it is the north turn or not.
+  # Get the next turn.
   #
-  # @return [Boolean] true if it is the north turn and false otherwise
+  # @return [Symbol] :South if it's the north player's turn, :North otherwise
+  def next_turn
+    north_turn? ? South : North
+  end
+
+  # Check if it's the north player's turn.
+  #
+  # @return [Boolean] true if it's the north player's turn, false otherwise
   def north_turn?
     @is_north_turn
   end
 
-  # Checks if it is not the north turn or not.
+  # Check if it's the south player's turn.
   #
-  # @return [Boolean] true if it is not the north turn and false otherwise
+  # @return [Boolean] true if it's the south player's turn, false otherwise
   def south_turn?
     !north_turn?
   end
 
-  # Returns an array representation of the Qi object's attributes.
+  # Convert the state to an array.
+  #
+  # @example Converting the state to an array
+  #   qi.to_a #=> [true, ['P', 'G'], ['B', '+B'], {56 => 'P', 3 => 'g', 64 => '+B'}, {}]
   #
-  # @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] an array representing the game state
   def to_a
     [
       north_turn?,
       north_captures,
       south_captures,
-      squares
+      squares,
+      options
     ]
   end
 
-  # Returns a hash representation of the Qi object's attributes.
+  # Convert the state to a hash.
   #
-  # @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
+  # @example Converting the state to a hash
+  #   qi.to_h #=> {is_north_turn: true, north_captures: ['P', 'G'], south_captures: ['B', '+B'], squares: {56 => 'P', 3 => 'g', 64 => '+B'}, options: {}}
+  #
+  # @return [Hash] a hash representing the game state
   def to_h
     {
       is_north_turn:  north_turn?,
       north_captures:,
       south_captures:,
-      squares:
+      squares:,
+      options:
     }
   end
 
-  # Returns the hash-code for the position.
+  # Generate a hash value for the game state.
+  #
+  # @example Generating a hash value
+  #   qi.hash #=> "10dfb778f6559dd368c510a27e3b00bdb5b4ad88d4d67f38864d7e36de7c2f9c"
+  #
+  # @return [String] a SHA256 hash of the serialized game state
   def hash
     ::Digest::SHA256.hexdigest(serialize)
   end
 
-  # Returns a string representation of the Qi object's attributes.
+  # Serialize the game state.
   #
-  # @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 ","
+  # @example Serializing the game state
+  #   qi.serialize #=> "North-turn===P,G,B,+B===3:g,56:P,64:+B"
+  #
+  # @return [String] a string representation of the game state
   def serialize
-    serialized_turn     = "#{side_name}-turn"
-    serialized_captures = (north_captures + south_captures).sort.join(",")
-    serialized_squares  = squares.keys.map { |i| "#{i}:#{squares.fetch(i)}" }.join(",")
+    serialized_turn     = "#{current_turn}-turn"
+    serialized_captures = (north_captures + south_captures).join(",")
+    serialized_squares  = squares.keys.sort.map { |i| "#{i}:#{squares.fetch(i)}" }.join(",")
 
     "#{serialized_turn}===#{serialized_captures}===#{serialized_squares}"
   end
 
-  # Returns a human-readable representation of the Qi object.
+  # Provide a string representation of the game state for debugging.
+  #
+  # @example Getting a string representation of the game state
+  #   qi.inspect #=> "<Qi North-turn===P,G,B,+B===3:g,56:P,64:+B>"
   #
-  # @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.
+  # Update captures based on the source square and the piece in hand.
   #
-  # @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
-  def update_captures(in_hand, is_drop:)
+  # If the source square is not nil and in_hand is nil (i.e., we're moving a piece on the board),
+  # the captures remain the same. If the source square is not nil and in_hand is not nil
+  # (i.e., we're capturing a piece that will remain in hand), the piece is added to the
+  # current player's captures. If the source square is nil (i.e., we're dropping a piece from hand),
+  # the piece is removed from the current player's captures.
+  #
+  # @param src_square [Object, nil] the source square, or nil if dropping a piece from hand
+  # @param in_hand [String, nil] the piece in hand, or nil if moving a piece from a square
+  #
+  # @example When moving a piece on the board
+  #   qi = Qi.new(true, ['P', 'B'], ['G', '+B'], {56 => 'P', 64 => '+B'})
+  #   qi.send(:update_captures, 56, nil) #=> [['B', 'P'], ['G', '+B']]
+  #
+  # @example When capturing a piece that will remain in hand
+  #   qi = Qi.new(true, ['P', 'B'], ['G', '+B'], {56 => 'P', 64 => '+B'})
+  #   qi.send(:update_captures, 56, 'G') #=> [['B', 'P', 'G'], ['G', '+B']]
+  #
+  # @example When dropping a piece from hand
+  #   qi = Qi.new(true, ['P', 'B', 'G'], ['G', '+B'], {56 => 'P', 64 => '+B'})
+  #   qi.send(:update_captures, nil, 'G') #=> [['B', 'P'], ['G', '+B']]
+  #
+  # @return [Array] a two-element array with the updated north and south captures
+  def update_captures(src_square, in_hand)
     return [north_captures, south_captures] if in_hand.nil?
 
-    captures = if is_drop
-                 remove_from_captures(in_hand, *owned_captures)
+    captures = if src_square.nil?
+                 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.
+  #
+  # If the piece is not found in the captures, an Error::Drop exception is raised.
+  #
+  # @param piece [String] the piece to remove from the captures
+  # @param captures [Array] the captures to update
+  #
+  # @example
+  #   qi = Qi.new(true, ['P', 'B', 'G'], ['G', '+B'], {56 => 'P', 64 => '+B'})
+  #   qi.send(:remove_from_captures, 'G', *qi.current_captures) #=> ['P', 'B']
+  #
+  # @raise [Error::Drop] 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
+  # @return [Array] the captures after removing the piece
   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.beta11
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-05-06 00:00:00.000000000 Z
+date: 2023-05-12 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.