RubyGems - qi - Versions diffs - 10.0.0.beta12 → 11.0.0 - Mend

qi 10.0.0.beta12 → 11.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f3a609bb51c87ae5486c9244b948899f4e6ae46747ac80bf3be5f83ae76826a
-  data.tar.gz: 1843fa6cc35f2dcaaab08a7772abeb9f56fa3e7d0dc5dc69f9a742ec47e81169
+  metadata.gz: 37ba6c52ebee303a717aa6e218cc7e4c1167658988b883692dbee1691c72df6f
+  data.tar.gz: a63f9d02091f7d379d2fa5d7d7dedbaff1df7eb9505f20bd50dcf228f8b6c319
 SHA512:
-  metadata.gz: f79f7dc430f3e84b5cf816492c4f31c7776db329fffd18e161df929ccf18cb85b37cdd69e35c2b93da0e983e976d765bf69e8a33f1e946ec62d61c7b5583d164
-  data.tar.gz: '059b84b8c426af80188f0b6885ff921ab86f7015756d5309d75fd0ab621f1d93322be5f83f603a02535850645da432219af815871c480b56dec0e8f67db738bb'
+  metadata.gz: 347722567e95439f0cb818cf929931315fdc081a72b9f50738aace03981e023c094b46b6010163e766e2f4b67476bc78b6a5718656c3b1c61c1aa31525838744
+  data.tar.gz: 4659c8825b38423cbfa539eb0c215b1503f997ce0d0fd972c3ee55cbe71719a6d61d65badb89866ae46cf87b935c4c1d05d4bb95f5f00b6614483548fe2b95cd

data/README.md CHANGED Viewed

@@ -1,93 +1,188 @@
-# Qi.rb
+# Qi
-[![Version](https://img.shields.io/github/v/tag/sashite/qi.rb?label=Version&logo=github)](https://github.com/sashite/qi.rb/releases)
-[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/qi.rb/main)
-[![CI](https://github.com/sashite/qi.rb/workflows/CI/badge.svg?branch=main)](https://github.com/sashite/qi.rb/actions?query=workflow%3Aci+branch%3Amain)
-[![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)
+[![Version](https://img.shields.io/gem/v/qi.svg)](https://rubygems.org/gems/qi)
+[![Documentation](https://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/gems/qi)
+[![CI](https://github.com/sashite/qi.rb/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/sashite/qi.rb/actions)
+[![License](https://img.shields.io/gem/l/qi.svg)](https://github.com/sashite/qi.rb/blob/main/LICENSE)
-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.
+> A minimal, format-agnostic position model for two-player board games.
-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.
+## Overview
-## Features:
+`Qi` provides an immutable `Qi::Position` object that represents the state of a two-player, turn-based board game as defined by the [Sashité Game Protocol](https://sashite.dev/game-protocol/).
-- **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.
+A position encodes exactly four things:
-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.
+| Field    | Type                                        | Description                           |
+|----------|---------------------------------------------|---------------------------------------|
+| `board`  | nested `Array` (1D to 3D)                   | Board structure and occupancy         |
+| `hands`  | `Hash` with `:first` and `:second` keys     | Off-board pieces held by each player  |
+| `styles` | `Hash` with `:first` and `:second` keys     | Player style for each side            |
+| `turn`   | `:first` or `:second`                       | The active player's side              |
-## Installation
+Piece and style representations are **intentionally opaque** — `Qi` validates structure, not semantics. This makes the library reusable across [FEEN](https://sashite.dev/specs/feen/1.0.0/), [PON](https://sashite.dev/specs/pon/1.0.0/), or any other encoding that shares the same positional model.
+### Implementation Constraints
-Add this line to your application's Gemfile:
+| Constraint         | Value | Rationale                                 |
+|--------------------|-------|-------------------------------------------|
+| Max dimensions     | 3     | Covers 1D, 2D, 3D boards                 |
+| Max dimension size | 255   | Fits in 8-bit integer; covers 255×255×255 |
+| Board non-empty    | n ≥ 1 | A board must contain at least one square  |
+| Piece cardinality  | p ≤ n | Pieces cannot exceed the number of squares|
+## Installation
 ```ruby
-gem "qi", ">= 10.0.0.beta12"
+# In your Gemfile
+gem "qi", "~> 11.0"
 ```
-And then execute:
+Or install manually:
 ```sh
-bundle install
+gem install qi
 ```
-Or install it yourself as:
+## Dependencies
-```sh
-gem install qi --pre
+None. `Qi` is a zero-dependency library.
+## Usage
+### Creating a Position
+```ruby
+# Chess starting position
+board = [
+  [:r, :n, :b, :q, :k, :b, :n, :r],
+  [:p, :p, :p, :p, :p, :p, :p, :p],
+  [nil, nil, nil, nil, nil, nil, nil, nil],
+  [nil, nil, nil, nil, nil, nil, nil, nil],
+  [nil, nil, nil, nil, nil, nil, nil, nil],
+  [nil, nil, nil, nil, nil, nil, nil, nil],
+  [:P, :P, :P, :P, :P, :P, :P, :P],
+  [:R, :N, :B, :Q, :K, :B, :N, :R]
+]
+position = Qi.new(
+  board,
+  { first: [], second: [] },
+  { first: "C", second: "c" },
+  :first
+)
 ```
-## Example
+### Accessing Fields
 ```ruby
-require "qi"
-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(*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,
-#  ["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(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,
-#  ["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]
+position.board   #=> [[:r, :n, :b, ...], ...]
+position.hands   #=> { first: [], second: [] }
+position.styles  #=> { first: "C", second: "c" }
+position.turn    #=> :first
 ```
-## License
+All accessors return **frozen** objects. A `Qi::Position` is immutable once created.
+### Error Handling
+`Qi.new` raises `ArgumentError` on invalid input:
+```ruby
+begin
+  Qi.new([], { first: [], second: [] }, { first: "C", second: "c" }, :first)
+rescue ArgumentError => e
+  e.message #=> "board must not be empty"
+end
+```
+### Pieces as Arbitrary Objects
+Pieces are not restricted to any specific type. You can use symbols, strings (EPIN tokens), arrays, or any non-nil Ruby object:
+```ruby
+# Symbols
+Qi.new([:k, :p, nil, :P, :K], { first: [], second: [] }, { first: "C", second: "c" }, :first)
+# EPIN strings
+Qi.new([["K^", nil], [nil, "k^"]], { first: [], second: [] }, { first: "C", second: "c" }, :first)
+# Arrays as structured piece representations
+Qi.new(
+  [[[:king, :first, true], nil], [nil, [:king, :second, true]]],
+  { first: [], second: [] },
+  { first: :chess, second: :chess },
+  :first
+)
+```
+### Multi-dimensional Boards
-The code is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+```ruby
+# 1D board
+Qi.new([:a, nil, :b], { first: [], second: [] }, { first: "G", second: "g" }, :first)
+# 2D board (standard)
+Qi.new([[nil, nil], [nil, nil]], { first: [], second: [] }, { first: "C", second: "c" }, :first)
+# 3D board (2 layers × 2 ranks × 2 files)
+board_3d = [
+  [[:a, :b], [:c, :d]],
+  [[:A, :B], [:C, :D]]
+]
+Qi.new(board_3d, { first: [], second: [] }, { first: "R", second: "r" }, :first)
+```
-## About Sashité
+### Hands with Captured Pieces
-This [gem](https://rubygems.org/gems/qi) is maintained by [Sashité](https://sashite.com/).
+```ruby
+# Shogi-like position with pieces in hand
+Qi.new(
+  [[nil, nil, nil], [nil, "K^", nil], [nil, nil, nil]],
+  { first: ["P", "P", "B"], second: ["p"] },
+  { first: "S", second: "s" },
+  :first
+)
+```
+## Validation Errors
+| Error message                                                        | Cause                                          |
+|----------------------------------------------------------------------|-------------------------------------------------|
+| `"board must be an Array"`                                           | Board is not an Array                           |
+| `"board must not be empty"`                                          | Board is `[]`                                   |
+| `"board exceeds 3 dimensions (got N)"`                               | More than 3 nesting levels                      |
+| `"dimension size N exceeds maximum of 255"`                          | A dimension has more than 255 elements          |
+| `"non-rectangular board: expected N elements, got M"`                | Sub-arrays at the same level differ in length   |
+| `"inconsistent board structure: mixed arrays and non-arrays at same level"` | Mixed arrays and non-arrays at the same nesting level |
+| `"inconsistent board structure: expected flat squares at this level"` | An array found where a leaf square was expected |
+| `"hands must be a Hash with keys :first and :second"`               | Hands is not a Hash                             |
+| `"hands must have exactly keys :first and :second"`                  | Hash has missing or extra keys                  |
+| `"each hand must be an Array"`                                       | Hand value is not an Array                      |
+| `"hand pieces must not be nil"`                                      | `nil` found in a hand Array                     |
+| `"styles must be a Hash with keys :first and :second"`              | Styles is not a Hash                            |
+| `"styles must have exactly keys :first and :second"`                 | Hash has missing or extra keys                  |
+| `"first player style must not be nil"`                               | First style value is `nil`                      |
+| `"second player style must not be nil"`                              | Second style value is `nil`                     |
+| `"turn must be :first or :second"`                                   | Invalid turn value                              |
+| `"too many pieces for board size (P pieces, N squares)"`             | Piece cardinality violation                     |
+## Design Principles
+- **Format-agnostic**: No dependency on EPIN, SIN, or any specific encoding.
+- **Protocol-aligned**: Structurally compatible with the Game Protocol's Position model.
+- **Immutable**: Positions are frozen at construction; no mutation is possible.
+- **Validated at construction**: All invariants are enforced when building a position.
+- **Zero dependencies**: Only the Ruby standard library.
+## Related Specifications
+- [Game Protocol](https://sashite.dev/game-protocol/) — Conceptual foundation
+- [PON Specification](https://sashite.dev/specs/pon/1.0.0/) — JSON-based position format
+- [FEEN Specification](https://sashite.dev/specs/feen/1.0.0/) — Canonical string-based position format
+- [EPIN Specification](https://sashite.dev/specs/epin/1.0.0/) — Piece token format
+- [SIN Specification](https://sashite.dev/specs/sin/1.0.0/) — Style token format
+## License
-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!
+Available as open source under the [Apache License 2.0](https://opensource.org/licenses/Apache-2.0).

data/lib/qi/board.rb ADDED Viewed

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+module Qi
+  # Pure validation functions for multi-dimensional board structures.
+  #
+  # A board is represented as a nested Array where:
+  #
+  # - A *1D board* is a flat array of squares: +[nil, "K^", nil]+
+  # - A *2D board* is an array of ranks: +[[nil, nil], ["K^", nil]]+
+  # - A *3D board* is an array of layers, each an array of ranks.
+  #
+  # Each leaf element (square) is either +nil+ (empty) or any non-nil object (a piece).
+  #
+  # == Constraints
+  #
+  # - Maximum dimensionality: 3
+  # - Maximum size per dimension: 255
+  # - At least one square (non-empty board)
+  # - Rectangular structure: all sub-arrays at the same depth must have
+  #   identical length (enforced globally, not just per-sibling).
+  #
+  # @example Validate a 2D board
+  #   Qi::Board.validate([[:a, nil], [nil, :b]]) #=> [4, 2]
+  #
+  # @example Validate an empty board
+  #   Qi::Board.validate([[nil, nil, nil], [nil, nil, nil], [nil, nil, nil]]) #=> [9, 0]
+  module Board
+    MAX_DIMENSIONS    = 3
+    MAX_DIMENSION_SIZE = 255
+    # Validates a board and returns its square and piece counts.
+    #
+    # Validation proceeds in order of increasing cost: type check, emptiness,
+    # shape inference (first-path walk), dimension limits, then a single-pass
+    # structural verification with counting.
+    #
+    # @param board [Object] the board structure to validate.
+    # @return [Array(Integer, Integer)] +[square_count, piece_count]+.
+    # @raise [ArgumentError] if the board is structurally invalid.
+    #
+    # @example A 2D board
+    #   Qi::Board.validate([[:r, nil, nil], [nil, nil, :R]]) #=> [6, 2]
+    #
+    # @example A 1D board
+    #   Qi::Board.validate([:k, nil, nil, :K]) #=> [4, 2]
+    #
+    # @example A 3D board (2 layers × 2 ranks × 2 files)
+    #   Qi::Board.validate([[[:a, nil], [nil, :b]], [[nil, :c], [:d, nil]]]) #=> [8, 4]
+    #
+    # @example Non-rectangular boards are rejected
+    #   Qi::Board.validate([[:a, :b], [:c]])
+    #   # => ArgumentError: non-rectangular board: expected 2 elements, got 1
+    def self.validate(board)
+      validate_is_array(board)
+      validate_non_empty(board)
+      shape = compute_shape(board)
+      validate_max_dimensions(shape)
+      validate_dimension_sizes(shape)
+      verify_and_count(board, shape)
+    end
+    # --- Step 1: basic type checks -------------------------------------------
+    def self.validate_is_array(board)
+      return if board.is_a?(::Array)
+      raise ::ArgumentError, "board must be an Array"
+    end
+    def self.validate_non_empty(board)
+      return unless board.empty?
+      raise ::ArgumentError, "board must not be empty"
+    end
+    # --- Step 2: compute expected shape by walking the first element ----------
+    # The shape is an array of dimension sizes, e.g. [2, 3, 8] for
+    # 2 layers × 3 ranks × 8 files. We derive it by following the first
+    # child at each nesting level.
+    def self.compute_shape(board)
+      shape = []
+      current = board
+      while current.is_a?(::Array) && current.first.is_a?(::Array)
+        shape << current.size
+        current = current.first
+      end
+      shape << current.size
+      shape
+    end
+    # --- Step 3: validate dimension count and sizes ---------------------------
+    def self.validate_max_dimensions(shape)
+      dim = shape.size
+      return if dim <= MAX_DIMENSIONS
+      raise ::ArgumentError, "board exceeds #{MAX_DIMENSIONS} dimensions (got #{dim})"
+    end
+    def self.validate_dimension_sizes(shape)
+      oversized = shape.find { |size| size > MAX_DIMENSION_SIZE }
+      return unless oversized
+      raise ::ArgumentError, "dimension size #{oversized} exceeds maximum of #{MAX_DIMENSION_SIZE}"
+    end
+    # --- Step 4: verify structure and count in a single pass ------------------
+    def self.verify_and_count(board, shape)
+      if shape.size == 1
+        verify_and_count_rank(board, shape[0])
+      else
+        verify_and_count_multi(board, shape)
+      end
+    end
+    # For a 1D shape [n]: single-pass over the rank, verifying all elements are
+    # leaves (not arrays) while counting squares and pieces simultaneously.
+    def self.verify_and_count_rank(rank, expected)
+      unless rank.size == expected
+        raise ::ArgumentError, "non-rectangular board: expected #{expected} elements, got #{rank.size}"
+      end
+      piece_count = 0
+      rank.each do |square|
+        if square.is_a?(::Array)
+          raise ::ArgumentError, "inconsistent board structure: expected flat squares at this level"
+        end
+        piece_count += 1 unless square.nil?
+      end
+      [expected, piece_count]
+    end
+    # For a multi-dimensional shape [n, *rest]: check length, then recurse
+    # into each sub-array, accumulating counts.
+    def self.verify_and_count_multi(board, shape)
+      expected = shape[0]
+      rest = shape[1..]
+      unless board.size == expected
+        raise ::ArgumentError, "non-rectangular board: expected #{expected} elements, got #{board.size}"
+      end
+      total_squares = 0
+      total_pieces  = 0
+      board.each do |sub|
+        unless sub.is_a?(::Array)
+          raise ::ArgumentError, "inconsistent board structure: mixed arrays and non-arrays at same level"
+        end
+        sq, pc = verify_and_count(sub, rest)
+        total_squares += sq
+        total_pieces  += pc
+      end
+      [total_squares, total_pieces]
+    end
+    private_class_method :validate_is_array,
+                         :validate_non_empty,
+                         :compute_shape,
+                         :validate_max_dimensions,
+                         :validate_dimension_sizes,
+                         :verify_and_count,
+                         :verify_and_count_rank,
+                         :verify_and_count_multi
+  end
+end

data/lib/qi/hands.rb ADDED Viewed

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+module Qi
+  # Pure validation functions for player hands.
+  #
+  # Hands are represented as a Hash with exactly two keys:
+  #
+  # - +:first+ — array of pieces held by the first player.
+  # - +:second+ — array of pieces held by the second player.
+  #
+  # Each piece in a hand can be any non-nil object. The ordering of pieces
+  # within a hand carries no semantic meaning.
+  #
+  # @example Validate hands with pieces
+  #   Qi::Hands.validate({ first: ["+P", "+P"], second: ["b"] }) #=> 3
+  #
+  # @example Validate empty hands
+  #   Qi::Hands.validate({ first: [], second: [] }) #=> 0
+  module Hands
+    REQUIRED_KEYS = %i[first second].freeze
+    # Validates hands structure and returns the total piece count.
+    #
+    # Validation checks shape (exactly two keys), type (both values are arrays),
+    # then performs a single pass over each array to reject +nil+ elements and
+    # count pieces simultaneously.
+    #
+    # @param hands [Object] the hands structure to validate.
+    # @return [Integer] the total number of pieces across both hands.
+    # @raise [ArgumentError] if the hands structure is invalid.
+    #
+    # @example Valid hands
+    #   Qi::Hands.validate({ first: [:P, :B], second: [:p] }) #=> 3
+    #
+    # @example Nil piece rejected
+    #   Qi::Hands.validate({ first: [nil], second: [] })
+    #   # => ArgumentError: hand pieces must not be nil
+    #
+    # @example Missing key
+    #   Qi::Hands.validate({ first: [] })
+    #   # => ArgumentError: hands must have exactly keys :first and :second
+    def self.validate(hands)
+      validate_shape(hands)
+      validate_arrays(hands)
+      count_hand(hands[:first]) + count_hand(hands[:second])
+    end
+    # --- Shape validation -----------------------------------------------------
+    def self.validate_shape(hands)
+      unless hands.is_a?(::Hash)
+        raise ::ArgumentError, "hands must be a Hash with keys :first and :second"
+      end
+      return if hands.size == 2 && hands.key?(:first) && hands.key?(:second)
+      raise ::ArgumentError, "hands must have exactly keys :first and :second"
+    end
+    def self.validate_arrays(hands)
+      return if hands[:first].is_a?(::Array) && hands[:second].is_a?(::Array)
+      raise ::ArgumentError, "each hand must be an Array"
+    end
+    # --- Single pass: reject nil and count simultaneously ---------------------
+    def self.count_hand(pieces)
+      count = 0
+      pieces.each do |piece|
+        raise ::ArgumentError, "hand pieces must not be nil" if piece.nil?
+        count += 1
+      end
+      count
+    end
+    private_class_method :validate_shape,
+                         :validate_arrays,
+                         :count_hand
+  end
+end

data/lib/qi/position.rb ADDED Viewed

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+require_relative "board"
+require_relative "hands"
+require_relative "styles"
+module Qi
+  # An immutable, validated position for a two-player board game.
+  #
+  # A +Qi::Position+ is the in-memory representation of a game position
+  # as defined by the Sashité Game Protocol. It guarantees that all
+  # structural invariants hold at construction time.
+  #
+  # == Fields
+  #
+  # - +board+ — multi-dimensional Array representing board structure and occupancy.
+  # - +hands+ — +{ first: Array, second: Array }+ of off-board pieces.
+  # - +styles+ — +{ first: Object, second: Object }+ of player styles.
+  # - +turn+ — +:first+ or +:second+, the active player's side.
+  #
+  # == Construction
+  #
+  # Use +Qi.new+ to build positions. Direct instantiation via +Qi::Position.new+
+  # is also supported; both perform identical validation.
+  #
+  # @example
+  #   pos = Qi.new([["K^", nil], [nil, "k^"]], { first: [], second: [] }, { first: "C", second: "c" }, :first)
+  #   pos.board  #=> [["K^", nil], [nil, "k^"]]
+  #   pos.turn   #=> :first
+  class Position
+    VALID_TURNS = %i[first second].freeze
+    # @return [Array] the board structure.
+    attr_reader :board
+    # @return [Hash] off-board pieces for each player.
+    attr_reader :hands
+    # @return [Hash] style for each player.
+    attr_reader :styles
+    # @return [Symbol] the active player's side (+:first+ or +:second+).
+    attr_reader :turn
+    # Creates a validated, immutable position.
+    #
+    # Validation is performed in order of increasing cost: turn (symbol check),
+    # board (structural traversal), hands, styles, then cardinality.
+    #
+    # == Validated invariants
+    #
+    # - Turn is +:first+ or +:second+.
+    # - Board is a non-empty, rectangular, nested Array (1D to 3D).
+    # - Each dimension size is at most 255.
+    # - Hands is a Hash with +:first+ and +:second+ Arrays of non-nil pieces.
+    # - Styles is a Hash with +:first+ and +:second+ non-nil values.
+    # - Total piece count does not exceed total square count.
+    #
+    # @param board [Array] nested array representing the board (1D to 3D).
+    # @param hands [Hash] +{ first: Array, second: Array }+ of off-board pieces.
+    # @param styles [Hash] +{ first: Object, second: Object }+ of player styles.
+    # @param turn [Symbol] +:first+ or +:second+.
+    # @return [Qi::Position] a frozen, immutable position.
+    # @raise [ArgumentError] if any structural constraint is violated.
+    #
+    # @example A valid position
+    #   Qi::Position.new([nil, :k], { first: [], second: [] }, { first: :chess, second: :chess }, :second)
+    #
+    # @example Invalid turn
+    #   Qi::Position.new([nil], { first: [], second: [] }, { first: "C", second: "c" }, :third)
+    #   # => ArgumentError: turn must be :first or :second
+    def initialize(board, hands, styles, turn)
+      validate_turn(turn)
+      square_count, board_piece_count = Board.validate(board)
+      hand_piece_count = Hands.validate(hands)
+      Styles.validate(styles)
+      validate_cardinality(square_count, board_piece_count + hand_piece_count)
+      @board  = deep_freeze(board)
+      @hands  = deep_freeze(hands)
+      @styles = deep_freeze(styles)
+      @turn   = turn
+      freeze
+    end
+    # Returns a developer-friendly string representation.
+    #
+    # @return [String]
+    def inspect
+      "#<#{self.class} board=#{@board.inspect} hands=#{@hands.inspect} styles=#{@styles.inspect} turn=#{@turn.inspect}>"
+    end
+    private
+    def validate_turn(turn)
+      return if VALID_TURNS.include?(turn)
+      raise ::ArgumentError, "turn must be :first or :second"
+    end
+    def validate_cardinality(square_count, piece_count)
+      return if piece_count <= square_count
+      raise ::ArgumentError, "too many pieces for board size (#{piece_count} pieces, #{square_count} squares)"
+    end
+    # Recursively freezes an object and all its nested contents.
+    def deep_freeze(obj)
+      case obj
+      when ::Hash
+        obj.each_value { |v| deep_freeze(v) }
+        obj.freeze
+      when ::Array
+        obj.each { |e| deep_freeze(e) }
+        obj.freeze
+      else
+        obj.freeze
+      end
+    end
+  end
+end

data/lib/qi/styles.rb ADDED Viewed

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+module Qi
+  # Pure validation functions for player styles.
+  #
+  # Styles are represented as a Hash with exactly two keys:
+  #
+  # - +:first+ — the style associated with the first player side.
+  # - +:second+ — the style associated with the second player side.
+  #
+  # Style values are format-free: any non-nil object is accepted.
+  # Semantic validation (e.g., SIN compliance) is the responsibility
+  # of the encoding layer (FEEN, PON, etc.), not of Qi.
+  #
+  # @example Validate string styles
+  #   Qi::Styles.validate({ first: "C", second: "c" }) #=> nil
+  #
+  # @example Validate symbol styles
+  #   Qi::Styles.validate({ first: :chess, second: :shogi }) #=> nil
+  module Styles
+    # Validates the styles structure.
+    #
+    # Returns +nil+ if the Hash has exactly keys +:first+ and +:second+ with
+    # non-nil values, or raises +ArgumentError+ otherwise.
+    #
+    # @param styles [Object] the styles structure to validate.
+    # @return [nil]
+    # @raise [ArgumentError] if the styles structure is invalid.
+    #
+    # @example Valid styles
+    #   Qi::Styles.validate({ first: "S", second: "s" }) #=> nil
+    #
+    # @example Nil first style
+    #   Qi::Styles.validate({ first: nil, second: "c" })
+    #   # => ArgumentError: first player style must not be nil
+    #
+    # @example Nil second style
+    #   Qi::Styles.validate({ first: "C", second: nil })
+    #   # => ArgumentError: second player style must not be nil
+    #
+    # @example Missing key
+    #   Qi::Styles.validate({ first: "C" })
+    #   # => ArgumentError: styles must have exactly keys :first and :second
+    #
+    # @example Not a Hash
+    #   Qi::Styles.validate("not a hash")
+    #   # => ArgumentError: styles must be a Hash with keys :first and :second
+    def self.validate(styles)
+      validate_shape(styles)
+      validate_non_nil(styles)
+    end
+    def self.validate_shape(styles)
+      unless styles.is_a?(::Hash)
+        raise ::ArgumentError, "styles must be a Hash with keys :first and :second"
+      end
+      return if styles.size == 2 && styles.key?(:first) && styles.key?(:second)
+      raise ::ArgumentError, "styles must have exactly keys :first and :second"
+    end
+    def self.validate_non_nil(styles)
+      raise ::ArgumentError, "first player style must not be nil" if styles[:first].nil?
+      raise ::ArgumentError, "second player style must not be nil" if styles[:second].nil?
+    end
+    private_class_method :validate_shape,
+                         :validate_non_nil
+  end
+end

data/lib/qi.rb CHANGED Viewed

@@ -1,132 +1,50 @@
 # frozen_string_literal: true
-require "digest"
-require "kernel/boolean"
-# The Qi class represents a state of games such as Shogi.
-class Qi
-  # @return [Array] the pieces captured by the current player.
-  attr_reader :captures
-  # @return [Hash] the current state of the board.
-  attr_reader :squares
-  # Initializes a new game state.
+# A minimal, format-agnostic library for representing positions in
+# two-player, turn-based board games.
+#
+# Qi models the four components of a position as defined by the
+# Sashité Game Protocol:
+#
+# - *Board* — a multi-dimensional rectangular grid (1D, 2D, or 3D)
+#   where each square is either empty (+nil+) or occupied by a piece
+#   (any non-nil object).
+# - *Hands* — collections of off-board pieces held by each player.
+# - *Styles* — one style value per player side (format-free).
+# - *Turn* — which player is active (+:first+ or +:second+).
+#
+# Piece and style representations are intentionally opaque: Qi validates
+# structure, not semantics. This makes the library reusable across FEEN,
+# PON, or any other encoding that shares the same positional model.
+#
+# @example A 3×3 board with two kings and a pawn in hand
+#   board  = [[nil, nil, nil], [nil, "K^", nil], [nil, nil, "k^"]]
+#   hands  = { first: ["+P"], second: [] }
+#   pos    = Qi.new(board, hands, { first: "C", second: "c" }, :first)
+#   pos.turn          #=> :first
+#   pos.hands[:first] #=> ["+P"]
+module Qi
+  require_relative "qi/board"
+  require_relative "qi/hands"
+  require_relative "qi/styles"
+  require_relative "qi/position"
+  # Creates a new position after validating all structural constraints.
   #
-  # @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
-  end
-  # Commits a move and returns a new game state.
+  # @param board [Array] nested array representing the board (1D to 3D).
+  # @param hands [Hash] +{ first: Array, second: Array }+ of off-board pieces.
+  # @param styles [Hash] +{ first: Object, second: Object }+ of player styles.
+  # @param turn [Symbol] +:first+ or +:second+.
+  # @return [Qi::Position] an immutable, validated position.
+  # @raise [ArgumentError] if any structural constraint is violated.
   #
-  # @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
-  # @return [Boolean] whether the current player is in check.
-  def in_check?
-    @is_in_check
-  end
-  # @return [Boolean] whether the current player is not in check.
-  def not_in_check?
-    !in_check?
-  end
-  # @return [Boolean] whether it's North's turn.
-  def north_turn?
-    @is_north_turn
-  end
-  # @return [Boolean] whether it's South's turn.
-  def south_turn?
-    !north_turn?
-  end
-  # @return [Boolean] whether the other game state is equal to this one.
-  def eql?(other)
-    return false unless other.respond_to?(:serialize)
-    other.serialize == serialize
-  end
-  alias == eql?
-  # @return [Array] the array representation of the game state.
-  def to_a
-    [
-      north_turn?,
-      captures,
-      squares,
-      in_check?
-    ]
-  end
-  # @return [Hash] the hash representation of the game state.
-  def to_h
-    {
-      is_north_turn: north_turn?,
-      captures:,
-      squares:,
-      is_in_check:   in_check?
-    }
-  end
-  # @return [String] the SHA-256 hash of the serialized game state.
-  def hash
-    ::Digest::SHA256.hexdigest(serialize)
-  end
-  # @return [String] the string representation of the game state.
-  def serialize
-    [
-      serialized_turn,
-      serialized_captures,
-      serialized_squares,
-      serialized_in_check
-    ].join(" ")
-  end
-  # @return [String] the string representation of the object.
-  def inspect
-    "<#{self.class} #{serialize}>"
-  end
-  private
-  # @return [String] the serialized turn.
-  def serialized_turn
-    north_turn? ? "}" : "{"
-  end
-  # @return [String] the serialized captures.
-  def serialized_captures
-    captures.join(";")
-  end
-  # @return [String] the serialized board state.
-  def serialized_squares
-    squares.keys.sort.map { |i| "#{squares.fetch(i)}@#{i}" }.join(";")
-  end
-  # @return [String] the serialized check state.
-  def serialized_in_check
-    in_check? ? "+" : "."
+  # @example A valid position
+  #   Qi.new([[:a, nil], [nil, :b]], { first: [], second: [] }, { first: "C", second: "c" }, :first)
+  #
+  # @example An invalid position (too many pieces for the board)
+  #   Qi.new([:k], { first: [:P], second: [] }, { first: "C", second: "c" }, :first)
+  #   # => ArgumentError: too many pieces for board size (2 pieces, 1 squares)
+  def self.new(board, hands, styles, turn)
+    Position.new(board, hands, styles, turn)
   end
 end

metadata CHANGED Viewed

@@ -1,45 +1,32 @@
 --- !ruby/object:Gem::Specification
 name: qi
 version: !ruby/object:Gem::Version
-  version: 10.0.0.beta12
+  version: 11.0.0
 platform: ruby
 authors:
 - Cyril Kato
-autorequire:
 bindir: bin
 cert_chain: []
-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.
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A minimal, format-agnostic library for representing positions in two-player,
+  turn-based board games (chess, shogi, xiangqi, and variants).
 email: contact@cyril.email
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- LICENSE.md
 - README.md
 - lib/qi.rb
+- lib/qi/board.rb
+- lib/qi/hands.rb
+- lib/qi/position.rb
+- lib/qi/styles.rb
 homepage: https://github.com/sashite/qi.rb
 licenses:
-- MIT
+- Apache-2.0
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -50,12 +37,11 @@ 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:
+rubygems_version: 4.0.5
 specification_version: 4
-summary: Versatile Board Game Position Representation
+summary: A minimal, format-agnostic position model for two-player board games.
 test_files: []

data/LICENSE.md DELETED Viewed

@@ -1,21 +0,0 @@
-# The MIT License
-Copyright (c) 2015-2023 Sashité
-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.