portable_move_notation 2.2.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9133acb705a120376e5045428a24e3625ff82641c1628b5885feabe69d00259a
-  data.tar.gz: f898676def7e06bc14df0a998a28eac970413a0793e5b43bd16b67d8fda23312
+  metadata.gz: 9f3e75f9a5f80aaa8aeb581c90b4b20d318010cef492504174d970fe1386dc82
+  data.tar.gz: 4f5c513685589d247c8f9fa9fb5d98f353489b83c06d33601b46d940956e0fb6
 SHA512:
-  metadata.gz: ee79ca0d901bc10a36fffd1d7a6af726fdfa4d73ccb53318722c3c73d71da51f2893f4e7a4e597e239cabdedf87faa98ff92d0f76527e0632c00de44f1083937
-  data.tar.gz: bd11df77a4ef1d2e6b96d4c648e65609630d711bb128a344cac7d7990b5b45cb7e398da3c978035c34d1fd22969406d40355fe04c00ca52e9a9a26ff6bd80746
+  metadata.gz: 2b7a3c4f1a55ce2bd5a98a2770433962df67cf5649581db47abd13e433afe7eb4afdb26d68186fc133bb416c7a689044a0db0de7b53d0f4cda5c48d7853c3cd8
+  data.tar.gz: b5ccec6fb58bbb550fdf75df81ba692442799393d802372cc2e158ca44342659e2e0b14b9703810b8859354e1f64ae5566bc739b081d0b855374178dc31b1a1f

data/README.md

@@ -13,7 +13,9 @@
 
 ## Why PMN?
 
-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.
+PMN expresses **state‑changing actions** using a simple, deterministic array format without embedding game rules. Whether you are writing a Chess engine, a Shogi server, or a hybrid variant, PMN gives you a compact, game‑neutral core that travels well across languages and databases.
+
+Each action is represented as a 4-element array: `[source_square, destination_square, piece_name, captured_piece]`.
 
 ---
 
@@ -48,29 +50,24 @@ require "portable_move_notation" # provides the PortableMoveNotation namespace
 
 ## Quick Start
 
-Dump a single action (dropping a Shogi pawn on square "27"):
+Create a simple pawn move (e2 to e4):
 
 ```ruby
 require "portable_move_notation"
 
-move = PortableMoveNotation::Move.new(
-  PortableMoveNotation::Action.new(
-    src_square: nil,
-    dst_square: "27",
-    piece_name: "p",
-    piece_hand: nil
-  )
-)
+# Create an action using the array format: [source, destination, piece, captured]
+action = PortableMoveNotation::Action.new("e2", "e4", "P", nil)
+move = PortableMoveNotation::Move.new(action)
 
 puts move.to_json
-# Output: A JSON array with the move data
+# Output: [["e2","e4","P",null]]
 ```
 
 Parse it back:
 
 ```ruby
 restored = PortableMoveNotation::Move.from_json(move.to_json)
-puts restored.actions.first.dst_square # => "27"
+restored.actions.first.dst_square # => "e4"
 ```
 
 ---
@@ -82,49 +79,154 @@ puts restored.actions.first.dst_square # => "27"
 ```ruby
 require "portable_move_notation"
 
-king = PortableMoveNotation::Action.new(
-  src_square: "e1", dst_square: "g1", piece_name: "K", piece_hand: nil
-)
-rook = PortableMoveNotation::Action.new(
-  src_square: "h1", dst_square: "f1", piece_name: "R", piece_hand: nil
-)
+# Two separate actions for castling
+king_move = PortableMoveNotation::Action.new("e1", "g1", "K", nil)
+rook_move = PortableMoveNotation::Action.new("h1", "f1", "R", nil)
+
+castling = PortableMoveNotation::Move.new(king_move, rook_move)
+puts castling.to_json
+# Output: [["e1","g1","K",null],["h1","f1","R",null]]
+```
+
+### Shogi · Drop from Hand
+
+```ruby
+# Drop a pawn onto square 27 (source is nil for drops)
+drop = PortableMoveNotation::Action.new(nil, "27", "p", nil)
+move = PortableMoveNotation::Move.new(drop)
+
+puts move.to_json
+# Output: [[null,"27","p",null]]
+```
 
-puts PortableMoveNotation::Move.new(king, rook).to_json
-# Output: A JSON array containing both king and rook move data
+### Chess · En Passant Capture
+
+```ruby
+# En passant involves removing the captured pawn from its square
+capture_move = PortableMoveNotation::Action.new("d4", "e3", "p", nil)
+remove_pawn = PortableMoveNotation::Action.new("e4", "e4", nil, "P")
+
+en_passant = PortableMoveNotation::Move.new(capture_move, remove_pawn)
+puts en_passant.to_json
+# Output: [["d4","e3","p",null],["e4","e4",null,"P"]]
 ```
 
+### Shogi · Promotion with Capture
+
+```ruby
+# Bishop captures a promoted pawn and promotes itself
+promote_capture = PortableMoveNotation::Action.new("36", "27", "+B", "P")
+move = PortableMoveNotation::Move.new(promote_capture)
+
+puts move.to_json
+# Output: [["36","27","+B","P"]]
+```
+
+---
+
+## Core Concepts
+
+### Action Format
+
+Each action is a 4-element array representing:
+
+1. **Source square** (`String` or `nil`) - Where the piece comes from (`nil` for drops)
+2. **Destination square** (`String`) - Where the piece ends up (required)
+3. **Piece name** (`String`) - What sits on the destination after the action
+4. **Captured piece** (`String` or `nil`) - What enters the mover's reserve
+
+### Semantic Side Effects
+
+Every action produces deterministic changes:
+
+- **Board Removal**: Source square becomes empty (if not `nil`)
+- **Board Placement**: Destination square contains the piece
+- **Hand Addition**: Captured piece enters the mover's reserve (if not `nil`)
+- **Hand Removal**: For drops (`source` is `nil`), remove piece from hand
+
 ---
 
 ## Validation
 
-`PortableMoveNotation::Move.valid?(data)` checks **shape compliance** against the spec — not game legality:
+The library validates PMN structure but **not game legality**:
 
 ```ruby
 require "portable_move_notation"
 require "json"
 
-# 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
+# Valid PMN structure
+pmn_data = [["e2", "e4", "P", nil]]
+puts PortableMoveNotation::Move.valid?(pmn_data) # => true
+
+# Parse and validate
+move = PortableMoveNotation::Move.from_pmn(pmn_data)
+puts move.actions.size # => 1
 ```
 
-You can also validate single actions:
+Individual action validation:
 
 ```ruby
-# Check if an individual action is valid
-action_data = { "dst_square" => "e4", "piece_name" => "P" }
-puts PortableMoveNotation::Action.valid?(action_data) # => true
+# Check array format compliance
+action_array = ["e2", "e4", "P", nil]
+puts PortableMoveNotation::Action.valid?(action_array) # => true
 ```
 
 ---
 
-## License
+## Piece Notation
 
-The [gem](https://rubygems.org/gems/portable_move_notation) is released under the [MIT License](https://opensource.org/licenses/MIT).
+PMN is agnostic to piece notation systems. This implementation supports any UTF-8 string for piece identifiers:
+
+- **Traditional**: `"K"`, `"Q"`, `"R"`, `"B"`, `"N"`, `"P"`
+- **Descriptive**: `"WhiteKing"`, `"BlackQueen"`
+- **Shogi**: `"p"`, `"+P"`, `"B'"`
+- **Custom**: `"MagicDragon_powered"`, `"42"`
+
+---
+
+## JSON Schema Compliance
+
+All output conforms to the official PMN JSON Schema:
+
+- **Schema URL**: [`https://sashite.dev/schemas/pmn/1.0.0/schema.json`](https://sashite.dev/schemas/pmn/1.0.0/schema.json)
+- **Format**: Array of 4-element arrays
+- **Types**: `[string|null, string, string, string|null]`
+
+---
+
+## Implementation Notes
+
+### Performance
+
+- Actions are immutable (frozen) after creation
+- Moves are lightweight containers for action arrays
+- JSON serialization follows the official schema exactly
+
+### Thread Safety
+
+All objects are immutable after construction, making them thread-safe by design.
+
+### Error Handling
+
+- `ArgumentError` for malformed data during construction
+- `JSON::ParserError` for invalid JSON input
+- `KeyError` for missing required elements
 
 ---
 
+## Related Specifications
+
+- [Portable Move Notation (PMN)](https://sashite.dev/documents/pmn/1.0.0/) — This specification
+- [Piece Name Notation (PNN)](https://sashite.dev/documents/pnn/1.0.0/) — Piece identifier format
+- [General Actor Notation (GAN)](https://sashite.dev/documents/gan/1.0.0/) — Game-qualified pieces
+- [Forsyth‑Edwards Enhanced Notation (FEEN)](https://sashite.dev/documents/feen/1.0.0/) — Static positions
+
+---
+
+## License
+
+The [gem](https://rubygems.org/gems/portable_move_notation) is released under the [MIT License](https://opensource.org/licenses/MIT).
+
 ## About Sashité
 
-*Celebrating the beauty of Chinese, Japanese, and Western chess cultures.*
-Find more projects & research at **[sashite.com](https://sashite.com/)**.
+This project is maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of Chinese, Japanese, and Western chess cultures.

data/lib/portable_move_notation/action.rb

@@ -3,117 +3,115 @@
 module PortableMoveNotation
   # == Action
   #
-  # An **Action** is the *atomic* unit of Portable Move Notation.  Each instance
+  # 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.
+  # or the mover's reserve using the PMN v1.0.0 array format.
   #
-  # | Field        | Meaning                                                                |
-  # |--------------|------------------------------------------------------------------------|
-  # | `src_square` | String label of the square *vacated* – or +nil+ when dropping         |
-  # | `dst_square` | String label 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+                    |
+  # PMN v1.0.0 uses a 4-element array format:
+  # `[source_square, destination_square, piece_name, captured_piece]`
+  #
+  # | Index | Field            | Type           | Meaning                                                    |
+  # |-------|------------------|----------------|------------------------------------------------------------|
+  # | 0     | `src_square`     | String or nil  | Square vacated (nil when dropping from hand)              |
+  # | 1     | `dst_square`     | String         | Square now occupied by piece_name                          |
+  # | 2     | `piece_name`     | String         | Post-action piece identifier (may contain modifiers)      |
+  # | 3     | `captured_piece` | String or nil  | Piece entering mover's reserve (nil if nothing captured)  |
   #
   # 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.
+  # * `src_square` (when not nil) becomes empty.
+  # * `dst_square` now contains `piece_name`.
+  # * If `captured_piece` is set, add exactly one such piece to the mover's reserve.
+  # * If `src_square` is nil, remove one copy of `piece_name` from hand.
   #
   # === Examples
   #
   # @example Basic piece movement (Chess pawn e2 → e4)
-  #   PortableMoveNotation::Action.new(src_square: "e2", dst_square: "e4", piece_name: "P")
+  #   PortableMoveNotation::Action.new("e2", "e4", "P", nil)
   #
   # @example Drop from hand (Shogi pawn onto 27)
-  #   PortableMoveNotation::Action.new(src_square: nil, dst_square: "27", piece_name: "p")
+  #   PortableMoveNotation::Action.new(nil, "27", "p", nil)
   #
-  # @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")
+  # @example Capture with promotion (Bishop captures +p, promotes, P enters hand)
+  #   PortableMoveNotation::Action.new("36", "27", "+B", "P")
   #
-  # @see https://sashite.dev/documents/pmn/ Portable Move Notation specification
-  # @see https://sashite.dev/documents/pnn/ Piece Name Notation specification
+  # @see https://sashite.dev/documents/pmn/1.0.0/ Portable Move Notation specification
   class Action
-    # 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*.)
+    # Validates that *action_data* is a structurally correct PMN **action array**.
+    # Expects a 4-element array following the PMN v1.0.0 format.
     #
-    # @param action_data [Hash] Raw PMN action hash.
-    # @return [Boolean] +true+ if the hash can be converted into a valid {Action}.
+    # @param action_data [Array] Raw PMN action array.
+    # @return [Boolean] +true+ if the array 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")
-
-      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"]
-      )
+      return false unless action_data.is_a?(::Array)
+      return false unless action_data.size == 4
+
+      src_square, dst_square, piece_name, captured_piece = action_data
+
+      # Validate dst_square and piece_name are non-empty strings
+      return false unless dst_square.is_a?(::String) && !dst_square.empty?
+      return false unless piece_name.is_a?(::String) && !piece_name.empty?
+
+      # Validate src_square is either nil or non-empty string
+      return false unless src_square.nil? || (src_square.is_a?(::String) && !src_square.empty?)
+
+      # Validate captured_piece is either nil or non-empty string
+      return false unless captured_piece.nil? || (captured_piece.is_a?(::String) && !captured_piece.empty?)
+
       true
-    rescue ::ArgumentError
+    rescue StandardError
       false
     end
 
-    # Builds an {Action} from keyword parameters.
+    # Builds an {Action} from an array following PMN v1.0.0 format.
     #
-    # @param params [Hash] Keyword parameters.
-    # @option params [String, nil] :src_square Source coordinate, or +nil+ when dropping from hand.
-    # @option params [String] :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.
+    # @param action_array [Array] 4-element array [src_square, dst_square, piece_name, captured_piece]
     # @return [Action]
-    # @raise [KeyError] If +:dst_square+ or +:piece_name+ is missing.
-    def self.from_params(**params)
-      new(
-        src_square: params[:src_square],
-        dst_square: params.fetch(:dst_square),
-        piece_name: params.fetch(:piece_name),
-        piece_hand: params[:piece_hand]
-      )
+    # @raise [ArgumentError] If array format is invalid.
+    def self.from_array(action_array)
+      raise ArgumentError, "Expected 4-element array" unless action_array.is_a?(::Array) && action_array.size == 4
+
+      src_square, dst_square, piece_name, captured_piece = action_array
+      new(src_square, dst_square, piece_name, captured_piece)
     end
 
     # ------------------------------------------------------------------
     # Attributes
     # ------------------------------------------------------------------
 
-    # @return [String, nil] Source square (or +nil+ for drops)
+    # @return [String, nil] Source square (or nil for drops)
     attr_reader :src_square
     # @return [String] Destination square
     attr_reader :dst_square
-    # @return [String] Post‑move piece identifier
+    # @return [String] Post‑action piece identifier
     attr_reader :piece_name
-    # @return [String, nil] Captured piece that enters hand, or +nil+
-    attr_reader :piece_hand
+    # @return [String, nil] Captured piece that enters hand, or nil
+    attr_reader :captured_piece
 
     # ------------------------------------------------------------------
     # Construction
     # ------------------------------------------------------------------
 
-    # Instantiates a new {Action}.
+    # Instantiates a new {Action} using PMN v1.0.0 array semantics.
     #
-    # @param dst_square [String] Destination coordinate.
-    # @param piece_name [String]  Post‑move piece identifier.
-    # @param src_square [String, nil] Source coordinate or +nil+.
-    # @param piece_hand [String, nil] Captured piece entering hand.
+    # @param src_square [String, nil] Source coordinate or nil for drops.
+    # @param dst_square [String] Destination coordinate (required).
+    # @param piece_name [String] Post‑action piece identifier (required).
+    # @param captured_piece [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)
+    def initialize(src_square, dst_square, piece_name, captured_piece)
       validate_square(src_square) unless src_square.nil?
       validate_square(dst_square)
       validate_piece_name(piece_name)
-      validate_piece_hand(piece_hand) unless piece_hand.nil?
+      validate_captured_piece(captured_piece) unless captured_piece.nil?
 
       @src_square = src_square
       @dst_square = dst_square
       @piece_name = piece_name
-      @piece_hand = piece_hand
+      @captured_piece = captured_piece
 
       freeze
     end
@@ -122,28 +120,42 @@ module PortableMoveNotation
     # Serialisation helpers
     # ------------------------------------------------------------------
 
-    # Returns a **symbol‑keyed** parameter hash (useful for duplication).
+    # Returns the PMN v1.0.0 array representation.
+    # This is the canonical format for JSON serialization.
     #
-    # @return [Hash]
-    def to_params
-      {
-        src_square:,
-        dst_square:,
-        piece_name:,
-        piece_hand:
-      }.compact
+    # @return [Array] 4-element array [src_square, dst_square, piece_name, captured_piece]
+    def to_a
+      [src_square, dst_square, piece_name, captured_piece]
     end
 
-    # Returns a **string‑keyed** hash that conforms to the PMN JSON schema.
-    #
-    # @return [Hash]
-    def to_h
-      {
-        "src_square" => src_square,
-        "dst_square" => dst_square,
-        "piece_name" => piece_name,
-        "piece_hand" => piece_hand
-      }
+    # Alias for to_a for backward compatibility
+    alias to_pmn to_a
+
+    # ------------------------------------------------------------------
+    # Comparison and inspection
+    # ------------------------------------------------------------------
+
+    # Compare actions based on their array representation
+    def ==(other)
+      other.is_a?(Action) && to_a == other.to_a
+    end
+
+    # Hash based on array representation
+    def hash
+      to_a.hash
+    end
+
+    def eql?(other)
+      self == other
+    end
+
+    # Human-readable string representation
+    def inspect
+      "#<#{self.class.name} #{to_a.inspect}>"
+    end
+
+    def to_s
+      to_a.to_s
     end
 
     private
@@ -155,27 +167,29 @@ module PortableMoveNotation
     def validate_square(square)
       return if square.is_a?(::String) && !square.empty?
 
-      raise ::ArgumentError, "Square must be a non-empty string"
+      raise ::ArgumentError, "Square must be a non-empty string, got #{square.inspect}"
     end
 
-    # Validates {#piece_name} format.
+    # Validates piece_name format.
+    # PMN v1.0.0 allows any non-empty UTF-8 string for piece identifiers.
     #
     # @param piece_name [Object]
     # @raise [ArgumentError] If invalid.
     def validate_piece_name(piece_name)
-      return if piece_name.is_a?(::String) && piece_name.match?(PIECE_NAME_PATTERN)
+      return if piece_name.is_a?(::String) && !piece_name.empty?
 
-      raise ::ArgumentError, "Invalid piece_name format: #{piece_name.inspect}"
+      raise ::ArgumentError, "Piece name must be a non-empty string, got #{piece_name.inspect}"
     end
 
-    # Validates {#piece_hand} format.
+    # Validates captured_piece format.
+    # PMN v1.0.0 allows any non-empty UTF-8 string for piece identifiers.
     #
-    # @param piece_hand [Object]
+    # @param captured_piece [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/)
+    def validate_captured_piece(captured_piece)
+      return if captured_piece.is_a?(::String) && !captured_piece.empty?
 
-      raise ::ArgumentError, "Invalid piece_hand format: #{piece_hand.inspect}"
+      raise ::ArgumentError, "Captured piece must be a non-empty string, got #{captured_piece.inspect}"
     end
   end
 end

data/lib/portable_move_notation/move.rb

@@ -7,11 +7,14 @@ module PortableMoveNotation
   #
   # 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.
+  # Notation (PMN) v1.0.0. 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.
+  #
+  # PMN v1.0.0 uses an array-of-arrays format where each inner array represents
+  # a single action: `[source_square, destination_square, piece_name, captured_piece]`
   #
   # The class is deliberately **rule‑agnostic**: it guarantees only that the
-  # underlying data *matches the PMN schema*.  Whether the move is *legal* in a
+  # 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.
   #
@@ -21,15 +24,10 @@ module PortableMoveNotation
   # require "portable_move_notation"
   #
   # # Plain chess pawn move: e2 → e4
-  # pawn = PortableMoveNotation::Action.new(
-  #   src_square: "e2",
-  #   dst_square: "e4",
-  #   piece_name: "P"
-  # )
-  #
+  # pawn = PortableMoveNotation::Action.new("e2", "e4", "P", nil)
   # move = PortableMoveNotation::Move.new(pawn)
   # puts move.to_json
-  # # => JSON representation of the move
+  # # => [["e2","e4","P",null]]
   #
   # parsed = PortableMoveNotation::Move.from_json(move.to_json)
   # parsed.actions.first.dst_square  # => "e4"
@@ -38,48 +36,42 @@ module PortableMoveNotation
   # === Composite example (Chess kingside castling)
   #
   # ```ruby
-  # king = PortableMoveNotation::Action.new(
-  #   src_square: "e1", dst_square: "g1", piece_name: "K"
-  # )
-  # rook = PortableMoveNotation::Action.new(
-  #   src_square: "h1", dst_square: "f1", piece_name: "R"
-  # )
-  #
+  # king = PortableMoveNotation::Action.new("e1", "g1", "K", nil)
+  # rook = PortableMoveNotation::Action.new("h1", "f1", "R", nil)
   # castle = PortableMoveNotation::Move.new(king, rook)
   # ```
   #
-  # @see https://sashite.dev/documents/pmn/ Portable Move Notation specification
+  # @see https://sashite.dev/documents/pmn/1.0.0/ Portable Move Notation specification
   class Move
     # --------------------------------------------------------------------
     # Class helpers
     # --------------------------------------------------------------------
 
-    # Validates that *pmn_data* is an **array of PMN action hashes**.
+    # Validates that *pmn_data* is an **array of PMN action arrays**.
     # 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`).
+    # @param pmn_data [Array<Array>] Raw PMN structure (array of 4-element arrays).
     # @return [Boolean] +true+ when every element passes {Action.valid?}.
     #
     # @example Validate PMN parsed from JSON
-    #   data = JSON.parse('[{"dst_square":"e7","piece_name":"p"}]')
+    #   data = JSON.parse('[["e2","e4","P",null]]')
     #   PortableMoveNotation::Move.valid?(data)  # => true
     def self.valid?(pmn_data)
       return false unless pmn_data.is_a?(::Array) && !pmn_data.empty?
 
-      pmn_data.all? { |hash| Action.valid?(hash) }
+      pmn_data.all? { |action_array| Action.valid?(action_array) }
     end
 
     # Constructs a {Move} from its canonical **JSON** representation.
     #
-    # @param json_string [String] PMN‑formatted JSON.
+    # @param json_string [String] PMN‑formatted JSON (array of action arrays).
     # @return [Move]
     # @raise [JSON::ParserError] If +json_string+ is not valid JSON.
-    # @raise [KeyError] If an action hash lacks required keys.
+    # @raise [ArgumentError] If an action array is malformed.
     #
     # @example
-    #   json = '[{"src_square":null,"dst_square":"e7","piece_name":"p"}]'
+    #   json = '[["e2","e4","P",null]]'
     #   PortableMoveNotation::Move.from_json(json)
     def self.from_json(json_string)
       from_pmn(::JSON.parse(json_string))
@@ -87,37 +79,16 @@ module PortableMoveNotation
 
     # Constructs a {Move} from an *already parsed* PMN array.
     #
-    # @param pmn_array [Array<Hash>] PMN action hashes (string keys).
+    # @param pmn_array [Array<Array>] PMN action arrays (4-element arrays).
     # @return [Move]
-    # @raise [KeyError] If an action hash lacks required keys.
+    # @raise [ArgumentError] If an action array is malformed.
     def self.from_pmn(pmn_array)
-      actions = pmn_array.map do |hash|
-        Action.new(
-          src_square: hash["src_square"],
-          dst_square: hash.fetch("dst_square"),
-          piece_name: hash.fetch("piece_name"),
-          piece_hand: hash["piece_hand"]
-        )
+      actions = pmn_array.map do |action_array|
+        Action.from_array(action_array)
       end
       new(*actions)
     end
 
-    # 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.
-    #
-    # @example
-    #   Move.from_params(actions: [src_square: nil, dst_square: "e7", 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(*array)
-    end
-
     # --------------------------------------------------------------------
     # Attributes & construction
     # --------------------------------------------------------------------
@@ -139,20 +110,75 @@ module PortableMoveNotation
     # Serialisation helpers
     # --------------------------------------------------------------------
 
-    # Converts the move to an **array of PMN hashes** (string keys).
+    # Converts the move to an **array of PMN action arrays**.
+    # This is the canonical PMN v1.0.0 format.
     #
-    # @return [Array<Hash>]
+    # @return [Array<Array>] Array of 4-element action arrays
     def to_pmn
-      actions.map(&:to_h)
+      actions.map(&:to_a)
     end
 
-    # Converts the move to a **JSON string**.
+    # Alias for to_pmn for clarity
+    alias to_a to_pmn
+
+    # Converts the move to a **JSON string** following PMN v1.0.0 format.
     #
-    # @return [String]
+    # @return [String] JSON representation as array of action arrays
     def to_json(*_args)
       ::JSON.generate(to_pmn)
     end
 
+    # --------------------------------------------------------------------
+    # Comparison and inspection
+    # --------------------------------------------------------------------
+
+    # Compare moves based on their PMN array representation
+    def ==(other)
+      other.is_a?(Move) && to_pmn == other.to_pmn
+    end
+
+    # Hash based on PMN array representation
+    def hash
+      to_pmn.hash
+    end
+
+    def eql?(other)
+      self == other
+    end
+
+    # Human-readable string representation
+    def inspect
+      "#<#{self.class.name} #{to_pmn.inspect}>"
+    end
+
+    def to_s
+      to_pmn.to_s
+    end
+
+    # --------------------------------------------------------------------
+    # Utility methods
+    # --------------------------------------------------------------------
+
+    # Number of actions in this move
+    def size
+      actions.size
+    end
+
+    # Check if move is empty (shouldn't happen with current validation)
+    def empty?
+      actions.empty?
+    end
+
+    # Iterate over actions
+    def each(&)
+      actions.each(&)
+    end
+
+    # Access individual actions by index
+    def [](index)
+      actions[index]
+    end
+
     private
 
     # Ensures +actions+ is a non‑empty array of {Action} instances.

data/lib/portable_move_notation.rb

@@ -2,8 +2,44 @@
 
 # Portable Move Notation module
 #
-# @see https://sashite.dev/documents/pmn/1.0.0/
+# PMN v1.0.0 implementation providing rule-agnostic representation of
+# state-changing actions in abstract strategy board games.
+#
+# This implementation follows the PMN v1.0.0 specification which uses
+# an array-of-arrays format: each action is a 4-element array containing
+# [source_square, destination_square, piece_name, captured_piece].
+#
+# @see https://sashite.dev/documents/pmn/1.0.0/ PMN v1.0.0 Specification
+# @see https://sashite.dev/schemas/pmn/1.0.0/schema.json JSON Schema
 module PortableMoveNotation
+  # Schema URL for validation
+  SCHEMA_URL = "https://sashite.dev/schemas/pmn/1.0.0/schema.json"
+
+  # Quick validation method for PMN data
+  #
+  # @param pmn_data [Array] Array of action arrays to validate
+  # @return [Boolean] true if data conforms to PMN v1.0.0 format
+  def self.valid?(pmn_data)
+    Move.valid?(pmn_data)
+  end
+
+  # Parse PMN JSON string into a Move object
+  #
+  # @param json_string [String] JSON string containing PMN data
+  # @return [Move] Parsed move object
+  # @raise [JSON::ParserError] If JSON is invalid
+  # @raise [ArgumentError] If PMN structure is invalid
+  def self.parse(json_string)
+    Move.from_json(json_string)
+  end
+
+  # Generate PMN JSON from a Move object
+  #
+  # @param move [Move] Move object to serialize
+  # @return [String] JSON string in PMN v1.0.0 format
+  def self.generate(move)
+    move.to_json
+  end
 end
 
 require_relative File.join("portable_move_notation", "move")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: portable_move_notation
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -9,11 +9,13 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-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.
+description: 'Portable Move Notation (PMN) v1.0.0 is a rule-agnostic, JSON-based format
+  using arrays to represent deterministic state-changing actions in abstract strategy
+  board games. This gem provides a consistent Ruby interface for serializing, deserializing,
+  and validating moves across Chess, Shogi, Xiangqi, and other traditional or non-traditional
+  variants. The v1.0.0 format uses simple 4-element arrays: [source_square, destination_square,
+  piece_name, captured_piece], making it compact and language-agnostic while focusing
+  on deterministic state transformations independent of game-specific rules.'
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -50,6 +52,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.7
 specification_version: 4
-summary: A pure Ruby implementation of Portable Move Notation (PMN) for abstract strategy
-  board games.
+summary: A pure Ruby implementation of Portable Move Notation (PMN) v1.0.0 for abstract
+  strategy board games.
 test_files: []