qi 10.0.0.beta11 → 10.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79ffab5e654d14cf9f3f7dac1c50bc5b5c612452d0fdea35a00d3529337fbff2
-  data.tar.gz: b8fecf9ff5dd97923070809b6a906c8b44cebbee9695ea242e314d53afb9fad8
+  metadata.gz: 4a98ed653f1c1d21ae215f4a8ab481a0a19dd93551a9a3ba0faf9ee8e541291f
+  data.tar.gz: d1291d436f366c70e07a64a3a6390a3a9d99d56cfeb8b0b85c1002addbe7b540
 SHA512:
-  metadata.gz: cb36bd477ba3e756b116e3f2ab55bdb15ea50834461cc614865d8fdda56e271eff4675d998172bd766b8ca33e6944be3bbf567a1eba96b6215816234c485f6c9
-  data.tar.gz: e56b5f73bf2c0a1a3a256f813acfcf24af3bc3cdd570f2fb6ab1aa2f7ebc194ddd0b82e5ade5cbc052229377a8c768d3f49f45188d811a756ab7781481c69f08
+  metadata.gz: 154aa839e292e2cadfbafe8c64e324285216da01a491ef98815479bf1bd735dc2ec747ad31e6ef479ea4d913b262dbcb9ad6399f13cdf5199dddb3403d7091ee
+  data.tar.gz: 52c5ca680fb11577fc2aa84931900b9f8c712e6c300ca5774f918f144fd1c999f1e34387e8827fe5f7f3d55ed192d04dabb310acc538c19bee3b941effb68637

data/README.md

@@ -6,14 +6,28 @@
 [![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.
+**Qi** (Chinese: 棋; pinyin: _qí_) is a lightweight, flexible, and adaptable tool for representing board game positions, built in Ruby. It is designed to be game-agnostic and can be used with a variety of board games such as Chess, Four-Player Chess, Go, Makruk, Shogi, and Xiangqi.
+
+Qi uses a unique approach where the state of a game is represented through capturing the pieces in play, the arrangement of pieces on the board, the sequence of turns, and other possible states that a game can have.
+
+## Features
+
+1. **Game Agnostic:** Qi can be used to represent board game positions for a wide variety of games. Whether you are playing Chess, Makruk, Shogi, or Xiangqi, Qi's flexible structure allows you to accurately capture the state of your game.
+2. **Flexible Position Representation:** Qi captures the state of the game by recording the pieces in play, their arrangement on the board, the sequence of turns, and other additional states of the game. This enables a comprehensive view of the game at any given point.
+3. **State Manipulation:** Qi allows for manipulation and update of game states through the `commit` method, allowing transitions between game states.
+4. **Equality Checks:** With the `eql?` method, Qi allows for comparisons between different game states, which can be useful for tracking game progress, detecting repeats, or even in creating AI for your games.
+5. **Turn Management:** Qi keeps track of the sequence of turns allowing users to identify whose turn it is currently.
+6. **Access to Game Data:** Qi provides methods to access the current arrangement of pieces on the board (`squares_hash`) and the pieces captured by each player (`captures_hash`), helping users understand the current status of the game. It also allows access to a list of captured pieces (`captures_array`).
+7. **Customizability:** Qi is flexible and allows for customization as per your needs. The keys and values of the `captures_hash` and `squares_hash` can be any kind of object, as well as the items from `turns` and values from `state`.
+
+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.beta11"
+gem "qi"
 ```
 
 And then execute:
@@ -25,58 +39,70 @@ bundle install
 Or install it yourself as:
 
 ```sh
-gem install qi --pre
+gem install qi
 ```
 
-## Example
+## Usage
+
+The following usage example is derived from a classic _tsume shogi_ (詰将棋) problem, which translates to _mate shogi_ - a popular genre of shogi problems where the goal is to checkmate the opponent's king.
+In the provided setup, the attacking side is in possession of a silver general (S), a promoted bishop (+B) positioned on square 43, and a promoted pawn (+P) on square 22.
+
+On the defending side, there is a king (k) situated on square 4, surrounded by two silver generals (s) on squares 3 and 5 respectively.
+
+In this scenario, `Qi` allows us to represent the state of the game and apply changes as moves are made. Please follow the given example to understand how to create such a representation and how to update it:
 
 ```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]
-squares         = { 3 => "s", 4 => "k", 5 => "s", 22 => "+P", 43 => "+B" }
-
-qi0 = Qi.new(is_north_turn, north_captures, south_captures, squares)
-
-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===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"},
-#  {}]
-
-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===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"},
-#  {}]
+# Initialize an array for each player's captured pieces
+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]
+
+# Combine and count each player's captured pieces
+captures = Hash.new(0)
+(north_captures + south_captures).each { |piece| captures[piece] += 1 }
+
+# Define the squares occupied by each piece on the board
+squares = { 3 => "s", 4 => "k", 5 => "s", 22 => "+P", 43 => "+B" }
+
+# Create a new game position
+qi0 = Qi.new(captures, squares, [0, 1])
+
+# Verify the properties of the game position
+qi0.captures_array                          # => ["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.captures_hash                           # => {"r"=>2, "b"=>1, "g"=>4, "s"=>1, "n"=>4, "p"=>17, "S"=>1}
+qi0.squares_hash                            # => {3=>"s", 4=>"k", 5=>"s", 22=>"+P", 43=>"+B"}
+qi0.state                                   # => {}
+qi0.turn                                    # => 0
+qi0.turns                                   # => [0, 1]
+qi0.eql?(Qi.new(captures, squares, [0, 1])) # => true
+qi0.eql?(Qi.new(captures, squares, [1, 0])) # => false
+
+# Move a piece on the board and check the game state
+qi1 = qi0.commit([], [], { 43 => nil, 13 => "+B" }, in_check: true)
+
+qi1.captures_array                          # => ["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.captures_hash                           # => {"r"=>2, "b"=>1, "g"=>4, "s"=>1, "n"=>4, "p"=>17, "S"=>1}
+qi1.squares_hash                            # => {3=>"s", 4=>"k", 5=>"s", 22=>"+P", 13=>"+B"}
+qi1.state                                   # => {:in_check=>true}
+qi1.turn                                    # => 1
+qi1.turns                                   # => [1, 0]
+qi1.eql?(Qi.new(captures, squares, [0, 1])) # => false
+qi1.eql?(Qi.new(captures, squares, [1, 0])) # => false
 ```
 
+In this example, we first create a `Qi` object to represent a game position with `Qi.new`. Then, we check various aspects of the game state using the methods provided by `Qi`. After that, we create a new game state `qi1` by committing changes to the existing state `qi0`. Finally, we again check various aspects of the new game state.
+
 ## License
 
 The code is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## About Sashité
 
-This [gem](https://rubygems.org/gems/qi) is maintained by [Sashité](https://sashite.com/).
+This [gem](https://rubygems.org/gems/qi) is proudly maintained and developed by [Sashité](https://sashite.com/). Our mission is to promote intercultural understanding and appreciation through the universal language of board games.
+
+At Sashité, we believe in the power of games as a medium for sharing and appreciating the richness of different cultures. From Chinese to Japanese, and Western traditions, every culture has its unique representation in the world of board games, particularly in chess.
+
+Our `Qi` gem is a testament to this belief - a flexible, efficient, and inclusive software that allows for the representation and interaction of diverse chess systems. This piece of software is not just a tool; it is a bridge connecting different cultures under the love of strategic play.
 
-With some [lines of code](https://github.com/sashite/), let's share the beauty of Chinese, Japanese and Western cultures through the game of chess!
+Join us in our journey as we continue to write [code](https://github.com/sashite/) to share the beauty of these cultures, one game at a time.

data/lib/qi.rb

@@ -1,269 +1,118 @@
 # frozen_string_literal: true
 
-require "digest"
-require_relative "qi/error/drop"
-
-# 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.
+# The Qi class provides a consistent representation of a game state
+# and supports changes in the game state through the commit method.
+# It is designed to be used in board games such as chess, makruk, shogi, xiangqi.
 class Qi
-  # 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
+  # @!attribute [r] captures_hash
+  #   @return [Hash<Object, Integer>] a hash of captured pieces
+  #   @example
+  #     {"r"=>2, "b"=>1, "g"=>4, "s"=>1, "n"=>4, "p"=>17, "S"=>1}
+
+  # @!attribute [r] squares_hash
+  #   @return [Hash<Object, Object>] A hash where the keys represent square
+  #     identifiers and the values represent the piece that will occupy each square.
+  #     Both the keys and values can be any type of Ruby object, such as integers, strings, symbols, etc.
+  #   @example
+  #     {A3: "s", E4: "k", B5: "s", C22: "+P", D43: "+B"}
+
+  # @!attribute [r] state
+  #   @return [Hash<Symbol, Object>] a hash of game states
+  #   @example
+  #     {:in_check=>true}
+
+  # @!attribute [r] turns
+  #   @return [Array<Object>] a rotation of turns
+  #   @example
+  #     ["Sente", "Gote"]
+
+  attr_reader :captures_hash, :squares_hash, :state, :turns
+
+  # @param captures_hash [Hash<Object, Integer>] a hash of captured pieces
+  # @param squares_hash [Hash<Object, Object>] A hash where the keys represent square
+  #   identifiers and the values represent the piece that will occupy each square.
+  #   Both the keys and values can be any type of Ruby object, such as integers, strings, symbols, etc.
+  # @param turns [Array<Object>] a rotation of turns
+  # @param state [Hash<Symbol, Object>] a hash of game states
+  #
+  # @example
+  #   captures = Hash.new(0)
+  #   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]
+  #   (north_captures + south_captures).each { |piece| captures[piece] += 1 }
+  #   squares = { 3 => "s", 4 => "k", 5 => "s", 22 => "+P", 43 => "+B" }
+  #   Qi.new(captures, squares, [0, 1])
+  def initialize(captures_hash, squares_hash, turns, **state)
+    @captures_hash = ::Hash.new(0).merge(captures_hash.select { |_, v| v > 0 })
+    @squares_hash = squares_hash.compact
+    @turns = turns
+    @state = state.transform_keys(&:to_sym)
 
-  # @return [Hash] additional game options
-  attr_reader :options
+    freeze
+  end
 
-  # Initialize a new Qi object.
+  # Return an array of captures containing piece names.
   #
-  # @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
+  # @return [Array<Object>] an array of captures
+  # @example
+  #   ["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"]
+  def captures_array
+    captures_hash.flat_map { |piece, count| ::Array.new(count, piece) }.sort
   end
 
-  # Apply a move or a drop on the board.
+  # Commit a change to the game state and return a new Qi object.
   #
-  # 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>
-  #
-  # @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)
+  # @param add_captures_array [Array<Object>] an array of pieces to be added to captures
+  # @param del_captures_array [Array<Object>] an array of pieces to be deleted from captures
+  # @param edit_squares_hash [Hash<Object, Object>] A hash where the keys represent square
+  #   identifiers and the values represent the piece that will occupy each square.
+  #   Both the keys and values can be any type of Ruby object, such as integers, strings, symbols, etc.
+  # @param state [Hash<Symbol, Object>] a hash of new game states
+  # @return [Qi] a new Qi object representing the updated game state
+  # @example
+  #   qi0.commit([], [], { D43: nil, B13: "+B" }, in_check: true)
+  def commit(add_captures_array, del_captures_array, edit_squares_hash, **state)
+    self.class.new(
+      edit_captures_hash(add_captures_array.compact, del_captures_array.compact, **captures_hash),
+      squares_hash.merge(edit_squares_hash),
+      turns.rotate,
+      **state
+    )
   end
 
-  # Compare this Qi object with another for equality.
+  # Check if the current Qi object is equal to another Qi object.
   #
-  # @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
+  # @param other [Qi] another Qi object
+  # @return [Boolean] returns true if the captures_hash, squares_hash, turn, and state of both Qi objects are equal, false otherwise
   def eql?(other)
-    return false unless other.respond_to?(:serialize)
+    return false unless other.captures_hash == captures_hash
+    return false unless other.squares_hash == squares_hash
+    return false unless other.turn == turn
+    return false unless other.state == state
 
-    other.serialize == serialize
+    true
   end
   alias == eql?
 
-  # 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
-
-  # 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
-
   # 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
-
-  # Get the next turn.
-  #
-  # @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
-
-  # Check if it's the south player's turn.
-  #
-  # @return [Boolean] true if it's the south player's turn, false otherwise
-  def south_turn?
-    !north_turn?
-  end
-
-  # 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] an array representing the game state
-  def to_a
-    [
-      north_turn?,
-      north_captures,
-      south_captures,
-      squares,
-      options
-    ]
-  end
-
-  # Convert the state to a hash.
-  #
-  # @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:,
-      options:
-    }
-  end
-
-  # 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
-
-  # Serialize the game state.
-  #
-  # @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     = "#{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
-
-  # 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 representation of the game state
-  def inspect
-    "<#{self.class} #{serialize}>"
+  # @return [Object] the current turn
+  def turn
+    turns.fetch(0)
   end
 
   private
 
-  # Update captures based on the source square and the piece in hand.
-  #
-  # 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 src_square.nil?
-                 remove_from_captures(in_hand, *current_captures)
-               else
-                 current_captures + [in_hand]
-               end
-
-    north_turn? ? [captures, opponent_captures] : [opponent_captures, captures]
-  end
-
-  # 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
+  # Edits the captures hash and returns it.
   #
-  # @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?
+  # @param add_captures_array [Array<Object>] an array of pieces to be added to captures
+  # @param del_captures_array [Array<Object>] an array of pieces to be deleted from captures
+  # @param hash [Hash<Object, Integer>] the current captures hash
+  # @return [Hash<Object, Integer>] the updated captures hash
+  def edit_captures_hash(add_captures_array, del_captures_array, **hash)
+    add_captures_array.each { |piece_name| hash[piece_name] += 1 }
+    del_captures_array.each { |piece_name| hash[piece_name] -= 1 }
 
-    captures.delete_at(index)
-    captures
+    hash
   end
 end

metadata

@@ -1,16 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: qi
 version: !ruby/object:Gem::Version
-  version: 10.0.0.beta11
+  version: 10.0.0
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-05-12 00:00:00.000000000 Z
+date: 2023-05-29 00:00:00.000000000 Z
 dependencies: []
-description: An abstraction that could help to update positions for games like Shogi.
+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 +20,6 @@ files:
 - LICENSE.md
 - README.md
 - lib/qi.rb
-- lib/qi/error/drop.rb
 homepage: https://github.com/sashite/qi.rb
 licenses:
 - MIT
@@ -36,12 +36,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 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