portable_move_notation 2.0.0 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 235dc58e056f7f8191c003a52248c1dadec9baabb5cc0393fd741bc7109abefa
-  data.tar.gz: f694111d3222b01a42e93eb39f72bd6dbaf369639ed8f7a5874dde60d09d66ef
+  metadata.gz: f936c1b2bb3ed48727315af5aba93953ca053b535b043c95dbcb12a061d82c50
+  data.tar.gz: 56e2bc34c31919f0853f2f97709f576ed49453ef95cc410a8273c60bb76d1250
 SHA512:
-  metadata.gz: d294c9796295c57415879911ab0aabfc370aff963f772fd088f1be7f8f9532f93773fe0c1f4748f89534fd20609c1b303e68f0962d4e43e39ee8e48410cda5ad
-  data.tar.gz: 7f2e37453b62b9407240cead2ac809d230fe464f2a9ce2a4877262e5b6531384d564fe43ec20089d22b4b9337b3a3c05507eb9d4acc562de1ca7eb11cc533d22
+  metadata.gz: 3e297be0fab49c4b4a62ee8b57158a1c325b66c32084b54f9aad6640495ae5432d104f852d3ab16f7bce508c242096772e57957f04766127c961c71eedbbaedd
+  data.tar.gz: ec03950b1e5884085491828dc79199958fa76f950c7c79358251a566862de80e8f9777a3c241a6f7b1a782adbb708e818f43d0f1049e51bc1e68617f13d331f1

data/README.md

@@ -1,279 +1,130 @@
 # Pmn.rb
 
-[![Version](https://img.shields.io/github/v/tag/sashite/pmn.rb?label=Version&logo=github)](https://github.com/sashite/pmn.rb/tags)
-[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/pmn.rb/main)
-![Ruby](https://github.com/sashite/pmn.rb/actions/workflows/main.yml/badge.svg?branch=main)
-[![License](https://img.shields.io/github/license/sashite/pmn.rb?label=License&logo=github)](https://github.com/sashite/pmn.rb/raw/main/LICENSE.md)
+[![Gem Version](https://img.shields.io/gem/v/portable_move_notation.svg?logo=rubygems)](https://rubygems.org/gems/portable_move_notation)
+[![GitHub Version](https://img.shields.io/github/v/tag/sashite/pmn.rb?label=GitHub\&logo=github)](https://github.com/sashite/pmn.rb/tags)
+[![Build](https://github.com/sashite/pmn.rb/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/sashite/pmn.rb/actions/workflows/main.yml)
+[![Codecov](https://img.shields.io/codecov/c/github/sashite/pmn.rb?logo=codecov)](https://codecov.io/gh/sashite/pmn.rb)
+[![YARD Docs](https://img.shields.io/badge/YARD-Documentation-blue.svg?logo=ruby)](https://rubydoc.info/github/sashite/pmn.rb/main)
+[![License](https://img.shields.io/github/license/sashite/pmn.rb?label=License)](https://github.com/sashite/pmn.rb/raw/main/LICENSE.md)
 
-> **PMN** (Portable Move Notation) support for the Ruby language.
+> Parse, validate and emit [PMN v1.0.0](https://sashite.dev/documents/pmn/1.0.0/) — the rule‑agnostic *Portable Move Notation* — in pure Ruby.
 
-## What is PMN?
+---
 
-PMN (Portable Move Notation) is a rule-agnostic JSON-based format for representing moves in abstract strategy board games. It provides a consistent representation system for game actions across both traditional and non-traditional board games, supporting arbitrary dimensions and hybrid configurations while maintaining neutrality toward game-specific rules.
+## Why PMN?
 
-This gem implements the [PMN Specification v1.0.0](https://sashite.dev/documents/pmn/1.0.0/), providing a Ruby interface for:
-- Serializing game actions to PMN format
-- Parsing PMN data into structured Ruby objects
-- Validating PMN data according to the specification
+PMN expresses **state‑changing actions** without embedding game rules. Whether you are writing a Chess engine, a Shogi server, or a hybrid variant, PMN gives you a deterministic, game‑neutral core that travels well across languages and databases.
+
+---
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add to your **Gemfile**:
 
 ```ruby
+# Gemfile
 gem "portable_move_notation"
 ```
 
-And then execute:
+then:
 
-```sh
+```bash
 bundle install
 ```
 
-Or install it yourself as:
+Or grab it directly:
 
-```sh
+```bash
 gem install portable_move_notation
 ```
 
-## PMN Format
-
-A PMN record consists of an array of one or more action items, where each action item is a JSON object with precisely defined fields:
+Require it in your code:
 
-```json
-[
-  {
-    "src_square": <source-coordinate-or-null>,
-    "dst_square": <destination-coordinate>,
-    "piece_name": <piece-identifier>,
-    "piece_hand": <captured-piece-identifier-or-null>
-  },
-  ...
-]
+```ruby
+require "portable_move_notation" # provides the PortableMoveNotation namespace
 ```
 
-## Basic Usage
+---
 
-### Working with PMN Actions
+## Quick Start
 
-Create individual actions representing piece movement:
+Dump a single action (dropping a Shogi pawn on square 27):
 
 ```ruby
 require "portable_move_notation"
 
-# Create an action representing a chess pawn moving from e2 (52) to e4 (36)
-pawn_move = PortableMoveNotation::Action.new(
-  src_square: 52,
-  dst_square: 36,
-  piece_name: "P",
-  piece_hand: nil
+move = PortableMoveNotation::Move.new(
+  PortableMoveNotation::Action.new(
+    src_square: nil,
+    dst_square: 27,
+    piece_name: "p",
+    piece_hand: nil
+  )
 )
 
-# Generate the PMN representation
-pawn_move.to_h
-# => {"src_square"=>52, "dst_square"=>36, "piece_name"=>"P", "piece_hand"=>nil}
+puts move.to_json
+# Output: A JSON array with the move data
 ```
 
-### Working with PMN Moves
-
-Create compound moves consisting of multiple actions:
+Parse it back:
 
 ```ruby
-require "portable_move_notation"
-require "json"
-
-# Create actions for a kingside castle in chess:
-king_action = PortableMoveNotation::Action.new(
-  src_square: 60,
-  dst_square: 62,
-  piece_name: "K",
-  piece_hand: nil
-)
-
-rook_action = PortableMoveNotation::Action.new(
-  src_square: 63,
-  dst_square: 61,
-  piece_name: "R",
-  piece_hand: nil
-)
-
-# Create a complete move (notice the splat operator for multiple actions)
-castling_move = PortableMoveNotation::Move.new(king_action, rook_action)
-
-# Generate JSON representation
-json_string = castling_move.to_json
-puts json_string
-# => [{"src_square":60,"dst_square":62,"piece_name":"K","piece_hand":null},{"src_square":63,"dst_square":61,"piece_name":"R","piece_hand":null}]
+restored = PortableMoveNotation::Move.from_json(move.to_json)
+puts restored.actions.first.dst_square # => 27
 ```
 
-### Parsing PMN Data
+---
 
-Parse PMN data from JSON:
-
-```ruby
-require "portable_move_notation"
+## Advanced Examples
 
-# Parse a PMN string (representing a shogi pawn promotion)
-pmn_string = '[{"src_square":27,"dst_square":18,"piece_name":"+P","piece_hand":null}]'
-move = PortableMoveNotation::Move.from_json(pmn_string)
-
-# Access components of the move
-puts move.actions.first.piece_name  # => +P
-puts move.actions.first.src_square  # => 27
-puts move.actions.first.dst_square  # => 18
-```
-
-### Validation
-
-Validate PMN data for conformance to the specification:
+### Chess · Kingside Castling
 
 ```ruby
 require "portable_move_notation"
-require "json"
-
-# Valid PMN data
-valid_data = JSON.parse('[{"dst_square":27,"piece_name":"p"}]')
-PortableMoveNotation::Move.valid?(valid_data) # => true
-
-# Invalid PMN data (missing required field)
-invalid_data = JSON.parse('[{"src_square":27}]')
-PortableMoveNotation::Move.valid?(invalid_data) # => false
-```
-
-## Examples of Common Chess and Shogi Actions
-
-### Chess: Pawn Move
-
-A white pawn moves from e2 (52) to e4 (36):
-
-```ruby
-action = PortableMoveNotation::Action.new(
-  src_square: 52,
-  dst_square: 36,
-  piece_name: "P",
-  piece_hand: nil
-)
 
-move = PortableMoveNotation::Move.new(action)
-move.to_json
-# => [{"src_square":52,"dst_square":36,"piece_name":"P","piece_hand":null}]
-```
-
-### Chess: Castling Kingside
-
-White castles kingside:
-
-```ruby
-king_action = PortableMoveNotation::Action.new(
-  src_square: 60,
-  dst_square: 62,
-  piece_name: "K",
-  piece_hand: nil
+king = PortableMoveNotation::Action.new(
+  src_square: 60, dst_square: 62, piece_name: "K", piece_hand: nil
 )
-
-rook_action = PortableMoveNotation::Action.new(
-  src_square: 63,
-  dst_square: 61,
-  piece_name: "R",
-  piece_hand: nil
+rook = PortableMoveNotation::Action.new(
+  src_square: 63, dst_square: 61, piece_name: "R", piece_hand: nil
 )
 
-castling_move = PortableMoveNotation::Move.new(king_action, rook_action)
-castling_move.to_json
-# => [{"src_square":60,"dst_square":62,"piece_name":"K","piece_hand":null},{"src_square":63,"dst_square":61,"piece_name":"R","piece_hand":null}]
+puts PortableMoveNotation::Move.new(king, rook).to_json
+# Output: A JSON array containing both king and rook move data
 ```
 
-### Shogi: Dropping a Pawn
+---
 
-A pawn is dropped onto square 27 from the player's hand:
+## Validation
 
-```ruby
-action = PortableMoveNotation::Action.new(
-  src_square: nil,
-  dst_square: 27,
-  piece_name: "p",
-  piece_hand: nil
-)
-
-move = PortableMoveNotation::Move.new(action)
-move.to_json
-# => [{"src_square":null,"dst_square":27,"piece_name":"p","piece_hand":null}]
-```
-
-### Shogi: Piece Capture and Promotion
-
-A bishop (B) captures a promoted pawn (+p) at square 27 and becomes available for dropping:
+`PortableMoveNotation::Move.valid?(data)` checks **shape compliance** against the spec — not game legality:
 
 ```ruby
-action = PortableMoveNotation::Action.new(
-  src_square: 36,
-  dst_square: 27,
-  piece_name: "B",
-  piece_hand: "P"
-)
+require "portable_move_notation"
+require "json"
 
-move = PortableMoveNotation::Move.new(action)
-move.to_json
-# => [{"src_square":36,"dst_square":27,"piece_name":"B","piece_hand":"P"}]
+# Parse a simple JSON move with a pawn at square 27
+data = JSON.parse('[{ "dst_square" => 27, "piece_name" => "p" }]')
+puts PortableMoveNotation::Move.valid?(data) # => true
 ```
 
-### Chess: En Passant Capture
-
-After white plays a double pawn move from e2 (52) to e4 (36), black captures en passant:
+You can also validate single actions:
 
 ```ruby
-# First create the initial pawn move
-initial_move = PortableMoveNotation::Action.new(
-  src_square: 52,
-  dst_square: 36,
-  piece_name: "P",
-  piece_hand: nil
-)
-
-# Then create the en passant capture (represented as two actions)
-capture_action1 = PortableMoveNotation::Action.new(
-  src_square: 35,
-  dst_square: 36,
-  piece_name: "p",
-  piece_hand: nil
-)
-
-capture_action2 = PortableMoveNotation::Action.new(
-  src_square: 36,
-  dst_square: 44,
-  piece_name: "p",
-  piece_hand: null
-)
-
-en_passant_move = PortableMoveNotation::Move.new(capture_action1, capture_action2)
-en_passant_move.to_json
-# => [{"src_square":35,"dst_square":36,"piece_name":"p","piece_hand":null},{"src_square":36,"dst_square":44,"piece_name":"p","piece_hand":null}]
+# Check if an individual action is valid
+action_data = { "dst_square" => 12, "piece_name" => "P" }
+puts PortableMoveNotation::Action.valid?(action_data) # => true
 ```
 
-## Properties of PMN
-
-* **Rule-agnostic**: PMN does not encode game-specific legality, validity, or conditions.
-* **Arbitrary-dimensional**: PMN supports arbitrary board configurations through a unified coordinate system.
-* **Game-neutral**: PMN provides a common structure applicable to all abstract strategy games with piece movement.
-* **Hybrid-supporting**: PMN facilitates hybrid or cross-game scenarios where multiple game types coexist.
-* **Deterministic**: PMN is designed for deterministic representation of all possible state transitions in piece-placement games.
-
-## Related Specifications
-
-PMN is part of a family of specifications for representing abstract strategy board games:
-
-- [Piece Name Notation (PNN)](https://sashite.dev/documents/pnn/1.0.0/) - Defines the format for representing individual pieces.
-- [Forsyth-Edwards Enhanced Notation (FEEN)](https://sashite.dev/documents/feen/1.0.0/) - Defines the format for representing board positions.
-
-## Documentation
-
-- [Official PMN Specification](https://sashite.dev/documents/pmn/1.0.0/)
-- [API Documentation](https://rubydoc.info/github/sashite/pmn.rb/main)
+---
 
 ## License
 
-The [gem](https://rubygems.org/gems/portable_move_notation) is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The [gem](https://rubygems.org/gems/portable_move_notation) is released under the [MIT License](https://opensource.org/licenses/MIT).
+
+---
 
 ## About Sashité
 
-This project is maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of Chinese, Japanese, and Western chess cultures.
+*Celebrating the beauty of Chinese, Japanese, and Western chess cultures.*
+Find more projects & research at **[sashite.com](https://sashite.com/)**.

data/lib/portable_move_notation/action.rb

@@ -1,56 +1,76 @@
 # frozen_string_literal: true
 
 module PortableMoveNotation
-  # Represents an atomic action in PMN format
+  # == Action
   #
-  # An Action is the fundamental unit of PMN, representing a single piece movement
-  # from a source square to a destination square, with optional capture information.
+  # An **Action** is the *atomic* unit of Portable Move Notation.  Each instance
+  # describes **one** deterministic transformation applied to either the board
+  # or the mover's reserve.
   #
-  # PMN actions consist of four primary components:
-  # - src_square: Source coordinate (or nil for drops)
-  # - dst_square: Destination coordinate (required)
-  # - piece_name: Identifier of the moving piece (required)
-  # - piece_hand: Identifier of any captured piece (or nil)
+  # | Field        | Meaning                                                                |
+  # |--------------|------------------------------------------------------------------------|
+  # | `src_square` | Integer index of the square *vacated* – or +nil+ when dropping         |
+  # | `dst_square` | Integer index of the square now **occupied** by {#piece_name}          |
+  # | `piece_name` | Post‑action identifier on `dst_square` (may contain prefix/suffix)     |
+  # | `piece_hand` | Bare letter that enters the mover's hand – or +nil+                    |
   #
-  # @example Basic piece movement
-  #   Action.new(src_square: 52, dst_square: 36, piece_name: "P")
+  # The implicit side‑effects are rule‑agnostic:
+  # * `src_square` (when not +nil+) becomes empty.
+  # * `dst_square` now contains {#piece_name}.
+  # * If {#piece_hand} is set, add exactly one such piece to the mover's reserve.
+  # * If `src_square` is +nil+, remove one unmodified copy of {#piece_name} from hand.
   #
-  # @example Piece drop (from outside the board)
-  #   Action.new(src_square: nil, dst_square: 27, piece_name: "p")
+  # === Examples
   #
-  # @example Capture with piece becoming available for dropping
-  #   Action.new(src_square: 33, dst_square: 24, piece_name: "+P", piece_hand: "R")
+  # @example Basic piece movement (Chess pawn e2 → e4)
+  #   PortableMoveNotation::Action.new(src_square: 52, dst_square: 36, piece_name: "P")
   #
-  # @see https://sashite.dev/documents/pmn/1.0.0/ PMN Specification
-  # @see https://sashite.dev/documents/pnn/1.0.0/ PNN Specification for piece format
+  # @example Drop from hand (Shogi pawn onto 27)
+  #   PortableMoveNotation::Action.new(src_square: nil, dst_square: 27, piece_name: "p")
+  #
+  # @example Capture with demotion (Bishop captures +p and acquires P in hand)
+  #   PortableMoveNotation::Action.new(src_square: 36, dst_square: 27, piece_name: "B", piece_hand: "P")
+  #
+  # @see https://sashite.dev/documents/pmn/ Portable Move Notation specification
+  # @see https://sashite.dev/documents/pnn/ Piece Name Notation specification
   class Action
-    # Validates a PMN action hash
+    # Regular expression for validating piece identifiers as per PNN.
+    # Matches: optional '+'/ '-' prefix, a single ASCII letter, optional "'" suffix.
+    PIECE_NAME_PATTERN = /\A[-+]?[A-Za-z]['"]?\z/
+
+    # ------------------------------------------------------------------
+    # Class helpers
+    # ------------------------------------------------------------------
+
+    # Validates that *action_data* is a structurally correct PMN **action hash**.
+    # (Keys are expected to be *strings*.)
     #
-    # @param action_data [Hash] PMN action data to validate
-    # @return [Boolean] true if valid, false otherwise
+    # @param action_data [Hash] Raw PMN action hash.
+    # @return [Boolean] +true+ if the hash can be converted into a valid {Action}.
     def self.valid?(action_data)
       return false unless action_data.is_a?(::Hash)
       return false unless action_data.key?("dst_square") && action_data.key?("piece_name")
 
-      begin
-        # Use existing validation logic by attempting to create an instance
-        new(
-          src_square: action_data["src_square"],
-          dst_square: action_data["dst_square"],
-          piece_name: action_data["piece_name"],
-          piece_hand: action_data["piece_hand"]
-        )
-        true
-      rescue ::ArgumentError
-        false
-      end
+      new(
+        src_square: action_data["src_square"],
+        dst_square: action_data["dst_square"],
+        piece_name: action_data["piece_name"],
+        piece_hand: action_data["piece_hand"]
+      )
+      true
+    rescue ::ArgumentError
+      false
     end
 
-    # Creates an Action instance from parameters
+    # Builds an {Action} from keyword parameters.
     #
-    # @param params [Hash] Action parameters
-    # @return [Action] A new action instance
-    # @raise [KeyError] if required parameters are missing
+    # @param params [Hash] Keyword parameters.
+    # @option params [Integer, nil] :src_square Source coordinate, or +nil+ when dropping from hand.
+    # @option params [Integer] :dst_square Destination coordinate (required).
+    # @option params [String] :piece_name Post‑move piece identifier (required).
+    # @option params [String, nil] :piece_hand Captured piece letter entering hand.
+    # @return [Action]
+    # @raise [KeyError] If +:dst_square+ or +:piece_name+ is missing.
     def self.from_params(**params)
       new(
         src_square: params[:src_square],
@@ -60,31 +80,31 @@ module PortableMoveNotation
       )
     end
 
-    # The source coordinate of the action, or nil for drops
-    # @return [Integer, nil] Source square coordinate
-    attr_reader :src_square
+    # ------------------------------------------------------------------
+    # Attributes
+    # ------------------------------------------------------------------
 
-    # The destination coordinate of the action
-    # @return [Integer] Destination square coordinate
+    # @return [Integer, nil] Source square (or +nil+ for drops)
+    attr_reader :src_square
+    # @return [Integer] Destination square
     attr_reader :dst_square
-
-    # The piece identifier in PNN format
-    # @return [String] Piece name
+    # @return [String] Post‑move piece identifier
     attr_reader :piece_name
-
-    # The identifier of any captured piece that becomes available for dropping, or nil
-    # @return [String, nil] Captured piece identifier
+    # @return [String, nil] Captured piece that enters hand, or +nil+
     attr_reader :piece_hand
 
-    # Initializes a new action
+    # ------------------------------------------------------------------
+    # Construction
+    # ------------------------------------------------------------------
+
+    # Instantiates a new {Action}.
     #
-    # @param src_square [Integer, nil] Source square (nil for placements from outside the board)
-    # @param dst_square [Integer] Destination square (required)
-    # @param piece_name [String] Piece identifier in PNN format (required)
-    # @param piece_hand [String, nil] Captured piece identifier that becomes droppable, or nil
-    # @raise [ArgumentError] if any validation fails
+    # @param dst_square [Integer] Destination coordinate.
+    # @param piece_name [String]  Post‑move piece identifier.
+    # @param src_square [Integer, nil] Source coordinate or +nil+.
+    # @param piece_hand [String, nil] Captured piece entering hand.
+    # @raise [ArgumentError] If any value fails validation.
     def initialize(dst_square:, piece_name:, src_square: nil, piece_hand: nil)
-      # Input validation
       validate_square(src_square) unless src_square.nil?
       validate_square(dst_square)
       validate_piece_name(piece_name)
@@ -98,9 +118,13 @@ module PortableMoveNotation
       freeze
     end
 
-    # Converts the action to a parameter hash
+    # ------------------------------------------------------------------
+    # Serialisation helpers
+    # ------------------------------------------------------------------
+
+    # Returns a **symbol‑keyed** parameter hash (useful for duplication).
     #
-    # @return [Hash] Parameter hash representation of the action
+    # @return [Hash]
     def to_params
       {
         src_square:,
@@ -110,11 +134,9 @@ module PortableMoveNotation
       }.compact
     end
 
-    # Converts the action to a PMN-compatible hash
-    #
-    # This creates a hash with string keys as required by the PMN JSON format
+    # Returns a **string‑keyed** hash that conforms to the PMN JSON schema.
     #
-    # @return [Hash] PMN-compatible hash representation
+    # @return [Hash]
     def to_h
       {
         "src_square" => src_square,
@@ -126,36 +148,34 @@ module PortableMoveNotation
 
     private
 
-    # Validates that a square coordinate is a non-negative integer
+    # Validates that *square* is a non‑negative integer.
     #
-    # @param square [Object] Value to validate
-    # @raise [ArgumentError] if the value is not a non-negative integer
+    # @param square [Object]
+    # @raise [ArgumentError] If invalid.
     def validate_square(square)
       return if square.is_a?(::Integer) && square >= 0
 
       raise ::ArgumentError, "Square must be a non-negative integer"
     end
 
-    # Validates the piece name format according to PNN specification
+    # Validates {#piece_name} format.
     #
-    # @param piece_name [Object] Piece name to validate
-    # @raise [ArgumentError] if the format is invalid
+    # @param piece_name [Object]
+    # @raise [ArgumentError] If invalid.
     def validate_piece_name(piece_name)
-      return if piece_name.is_a?(::String) && piece_name.match?(/\A[-+]?[a-zA-Z][=<>]?\z/)
+      return if piece_name.is_a?(::String) && piece_name.match?(PIECE_NAME_PATTERN)
 
-      raise ::ArgumentError, "Invalid piece_name format: #{piece_name}"
+      raise ::ArgumentError, "Invalid piece_name format: #{piece_name.inspect}"
     end
 
-    # Validates the piece hand format according to PNN specification
-    #
-    # Piece hand must be a single letter with no modifiers
+    # Validates {#piece_hand} format.
     #
-    # @param piece_hand [Object] Piece hand value to validate
-    # @raise [ArgumentError] if the format is invalid
+    # @param piece_hand [Object]
+    # @raise [ArgumentError] If invalid.
     def validate_piece_hand(piece_hand)
-      return if piece_hand.is_a?(::String) && piece_hand.match?(/\A[a-zA-Z]\z/)
+      return if piece_hand.is_a?(::String) && piece_hand.match?(/\A[A-Za-z]\z/)
 
-      raise ::ArgumentError, "Invalid piece_hand format: #{piece_hand}"
+      raise ::ArgumentError, "Invalid piece_hand format: #{piece_hand.inspect}"
     end
   end
 end

data/lib/portable_move_notation/move.rb

@@ -1,129 +1,166 @@
 # frozen_string_literal: true
 
+require "json"
+
 module PortableMoveNotation
-  # Represents a PMN move - a collection of one or more atomic actions
-  # that together describe a game state transition
+  # == Move
+  #
+  # A **Move** is an *ordered list* of {Action} instances that, applied **in
+  # order**, realise a deterministic change of game state under Portable Move
+  # Notation (PMN).  A move can be as small as a single pawn push or as large as
+  # a compound fairy‐move that relocates several pieces at once.
+  #
+  # The class is deliberately **rule‑agnostic**: it guarantees only that the
+  # underlying data *matches the PMN schema*.  Whether the move is *legal* in a
+  # given game is beyond its responsibility and must be enforced by an engine
+  # or referee layer.
+  #
+  # === Quick start
+  #
+  # ```ruby
+  # require "portable_move_notation"
+  #
+  # # Plain chess pawn move: e2 → e4
+  # pawn = PortableMoveNotation::Action.new(
+  #   src_square: 52,
+  #   dst_square: 36,
+  #   piece_name: "P"
+  # )
+  #
+  # move = PortableMoveNotation::Move.new(pawn)
+  # puts move.to_json
+  # # => JSON representation of the move
   #
-  # A move may consist of one or more actions, allowing for representation
-  # of complex moves such as castling, en passant captures, or multi-step
-  # actions in various abstract strategy games.
+  # parsed = PortableMoveNotation::Move.from_json(move.to_json)
+  # parsed.actions.first.dst_square  # => 36
+  # ```
   #
-  # @example Creating a simple move
-  #   action = Action.new(src_square: 52, dst_square: 36, piece_name: "P")
-  #   move = Move.new(action)
+  # === Composite example (Chess kingside castling)
   #
-  # @example Creating a castling move
-  #   king_action = Action.new(src_square: 60, dst_square: 62, piece_name: "K")
-  #   rook_action = Action.new(src_square: 63, dst_square: 61, piece_name: "R")
-  #   castling = Move.new(king_action, rook_action)
+  # ```ruby
+  # king = PortableMoveNotation::Action.new(
+  #   src_square: 60, dst_square: 62, piece_name: "K"
+  # )
+  # rook = PortableMoveNotation::Action.new(
+  #   src_square: 63, dst_square: 61, piece_name: "R"
+  # )
   #
-  # @see https://sashite.dev/documents/pmn/1.0.0/ PMN Specification
+  # castle = PortableMoveNotation::Move.new(king, rook)
+  # ```
+  #
+  # @see https://sashite.dev/documents/pmn/ Portable Move Notation specification
   class Move
-    # Validates a PMN array data structure
+    # --------------------------------------------------------------------
+    # Class helpers
+    # --------------------------------------------------------------------
+
+    # Validates that *pmn_data* is an **array of PMN action hashes**.
+    # The method does **not** instantiate {Action} objects on success; it merely
+    # checks that each element *could* be turned into one.
+    #
+    # @param pmn_data [Array<Hash>] Raw PMN structure (commonly the result of
+    #   `JSON.parse`).
+    # @return [Boolean] +true+ when every element passes {Action.valid?}.
     #
-    # @param pmn_data [Array] PMN data to validate
-    # @return [Boolean] true if valid, false otherwise
+    # @example Validate PMN parsed from JSON
+    #   data = JSON.parse('[{"dst_square":27,"piece_name":"p"}]')
+    #   PortableMoveNotation::Move.valid?(data)  # => true
     def self.valid?(pmn_data)
-      return false unless pmn_data.is_a?(Array) && !pmn_data.empty?
+      return false unless pmn_data.is_a?(::Array) && !pmn_data.empty?
 
-      pmn_data.all? { |action_data| Action.valid?(action_data) }
+      pmn_data.all? { |hash| Action.valid?(hash) }
     end
 
-    # Creates a Move instance from a JSON string in PMN format
+    # Constructs a {Move} from its canonical **JSON** representation.
     #
-    # @param json_string [String] JSON string to parse
-    # @return [Move] A new move instance
-    # @raise [JSON::ParserError] if the JSON string is malformed
-    # @raise [KeyError] if required fields are missing
+    # @param json_string [String] PMN‑formatted JSON.
+    # @return [Move]
+    # @raise [JSON::ParserError] If +json_string+ is not valid JSON.
+    # @raise [KeyError] If an action hash lacks required keys.
+    #
+    # @example
+    #   json = '[{"src_square":nil,"dst_square":27,"piece_name":"p"}]'
+    #   PortableMoveNotation::Move.from_json(json)
     def self.from_json(json_string)
-      json_data = ::JSON.parse(json_string)
-
-      actions = json_data.map do |action_data|
-        Action.new(
-          src_square: action_data["src_square"],
-          dst_square: action_data.fetch("dst_square"),
-          piece_name: action_data.fetch("piece_name"),
-          piece_hand: action_data["piece_hand"]
-        )
-      end
-
-      new(*actions)
+      from_pmn(::JSON.parse(json_string))
     end
 
-    # Creates a Move instance from an array of PMN action hashes
+    # Constructs a {Move} from an *already parsed* PMN array.
     #
-    # @param pmn_array [Array<Hash>] Array of PMN action hashes
-    # @return [Move] A new move instance
-    # @raise [KeyError] if required fields are missing
+    # @param pmn_array [Array<Hash>] PMN action hashes (string keys).
+    # @return [Move]
+    # @raise [KeyError] If an action hash lacks required keys.
     def self.from_pmn(pmn_array)
-      actions = pmn_array.map do |action_data|
+      actions = pmn_array.map do |hash|
         Action.new(
-          src_square: action_data["src_square"],
-          dst_square: action_data.fetch("dst_square"),
-          piece_name: action_data.fetch("piece_name"),
-          piece_hand: action_data["piece_hand"]
+          src_square: hash["src_square"],
+          dst_square: hash.fetch("dst_square"),
+          piece_name: hash.fetch("piece_name"),
+          piece_hand: hash["piece_hand"]
         )
       end
-
       new(*actions)
     end
 
-    # Creates a Move instance from a parameters hash
+    # Constructs a {Move} from keyword parameters.
+    #
+    # @param actions [Array<Action, Hash>] One or more {Action} objects *or*
+    #   parameter hashes accepted by {Action.from_params}.
+    # @return [Move]
+    # @raise [KeyError] If +actions+ is missing.
     #
-    # @param params [Hash] Move parameters
-    # @option params [Array<Action, Hash>] :actions List of actions or action params
-    # @return [Move] A new move instance
-    # @raise [KeyError] if the :actions key is missing
-    def self.from_params(**params)
-      actions = Array(params.fetch(:actions)).map do |action_params|
-        if action_params.is_a?(Action)
-          action_params
-        else
-          Action.from_params(**action_params)
-        end
+    # @example
+    #   Move.from_params(actions: [src_square: nil, dst_square: 27, piece_name: "p"])
+    def self.from_params(actions:)
+      array = Array(actions).map do |obj|
+        obj.is_a?(Action) ? obj : Action.from_params(**obj)
       end
-
-      new(*actions)
+      new(*array)
     end
 
-    # The list of actions that compose this move
-    #
-    # @return [Array<Action>] List of action objects (frozen)
+    # --------------------------------------------------------------------
+    # Attributes & construction
+    # --------------------------------------------------------------------
+
+    # @return [Array<Action>] Ordered, frozen list of actions.
     attr_reader :actions
 
-    # Initializes a new move with the given actions
+    # Creates a new {Move}.
     #
-    # @param actions [Array<Action>] List of actions as splat arguments
-    # @raise [ArgumentError] if actions is not a non-empty array of Action objects
+    # @param actions [Array<Action>] One or more {Action} objects.
+    # @raise [ArgumentError] If +actions+ is empty or contains non‑Action items.
     def initialize(*actions)
-      validate_actions(*actions)
+      validate_actions(actions)
       @actions = actions.freeze
-
       freeze
     end
 
-    # Converts the move to PMN format (array of hashes)
+    # --------------------------------------------------------------------
+    # Serialisation helpers
+    # --------------------------------------------------------------------
+
+    # Converts the move to an **array of PMN hashes** (string keys).
     #
-    # @return [Array<Hash>] PMN representation of the move
+    # @return [Array<Hash>]
     def to_pmn
       actions.map(&:to_h)
     end
 
-    # Converts the move to a JSON string
+    # Converts the move to a **JSON string**.
     #
-    # @return [String] JSON string of the move in PMN format
+    # @return [String]
     def to_json(*_args)
       ::JSON.generate(to_pmn)
     end
 
     private
 
-    # Validates the actions array
+    # Ensures +actions+ is a non‑empty array of {Action} instances.
     #
-    # @param actions [Object] Actions to validate
-    # @raise [ArgumentError] if actions is not a non-empty array of Action objects
-    def validate_actions(*actions)
-      return if !actions.empty? && actions.all?(Action)
+    # @param actions [Array<Object>] Items to validate.
+    # @raise [ArgumentError] If validation fails.
+    def validate_actions(actions)
+      return if actions.any? && actions.all?(Action)
 
       raise ::ArgumentError, "Actions must be a non-empty array of Action objects"
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: portable_move_notation
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.1
 platform: ruby
 authors:
 - Cyril Kato
@@ -9,10 +9,11 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: A Ruby interface for serialization and deserialization of moves in PMN
-  format. PMN is a rule-agnostic JSON-based format for representing moves in abstract
-  strategy board games, providing a consistent representation system for game actions
-  across both traditional and non-traditional board games.
+description: Portable Move Notation (PMN) is a rule-agnostic, JSON-based format for
+  representing moves in abstract strategy board games. This gem provides a consistent
+  Ruby interface for serializing, deserializing, and validating actions across Chess,
+  Shogi, Xiangqi, and other traditional or non-traditional variants, focusing on deterministic
+  state transformations independent of game-specific rules.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -49,5 +50,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.7
 specification_version: 4
-summary: PMN (Portable Move Notation) support for the Ruby language.
+summary: A pure Ruby implementation of Portable Move Notation (PMN) for abstract strategy
+  board games.
 test_files: []