portable_move_notation 2.1.1 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f936c1b2bb3ed48727315af5aba93953ca053b535b043c95dbcb12a061d82c50
-  data.tar.gz: 56e2bc34c31919f0853f2f97709f576ed49453ef95cc410a8273c60bb76d1250
+  metadata.gz: 9133acb705a120376e5045428a24e3625ff82641c1628b5885feabe69d00259a
+  data.tar.gz: f898676def7e06bc14df0a998a28eac970413a0793e5b43bd16b67d8fda23312
 SHA512:
-  metadata.gz: 3e297be0fab49c4b4a62ee8b57158a1c325b66c32084b54f9aad6640495ae5432d104f852d3ab16f7bce508c242096772e57957f04766127c961c71eedbbaedd
-  data.tar.gz: ec03950b1e5884085491828dc79199958fa76f950c7c79358251a566862de80e8f9777a3c241a6f7b1a782adbb708e818f43d0f1049e51bc1e68617f13d331f1
+  metadata.gz: ee79ca0d901bc10a36fffd1d7a6af726fdfa4d73ccb53318722c3c73d71da51f2893f4e7a4e597e239cabdedf87faa98ff92d0f76527e0632c00de44f1083937
+  data.tar.gz: bd11df77a4ef1d2e6b96d4c648e65609630d711bb128a344cac7d7990b5b45cb7e398da3c978035c34d1fd22969406d40355fe04c00ca52e9a9a26ff6bd80746

data/README.md

@@ -48,7 +48,7 @@ require "portable_move_notation" # provides the PortableMoveNotation namespace
 
 ## Quick Start
 
-Dump a single action (dropping a Shogi pawn on square 27):
+Dump a single action (dropping a Shogi pawn on square "27"):
 
 ```ruby
 require "portable_move_notation"
@@ -56,7 +56,7 @@ require "portable_move_notation"
 move = PortableMoveNotation::Move.new(
   PortableMoveNotation::Action.new(
     src_square: nil,
-    dst_square: 27,
+    dst_square: "27",
     piece_name: "p",
     piece_hand: nil
   )
@@ -70,7 +70,7 @@ Parse it back:
 
 ```ruby
 restored = PortableMoveNotation::Move.from_json(move.to_json)
-puts restored.actions.first.dst_square # => 27
+puts restored.actions.first.dst_square # => "27"
 ```
 
 ---
@@ -83,10 +83,10 @@ puts restored.actions.first.dst_square # => 27
 require "portable_move_notation"
 
 king = PortableMoveNotation::Action.new(
-  src_square: 60, dst_square: 62, piece_name: "K", piece_hand: nil
+  src_square: "e1", dst_square: "g1", piece_name: "K", piece_hand: nil
 )
 rook = PortableMoveNotation::Action.new(
-  src_square: 63, dst_square: 61, piece_name: "R", piece_hand: nil
+  src_square: "h1", dst_square: "f1", piece_name: "R", piece_hand: nil
 )
 
 puts PortableMoveNotation::Move.new(king, rook).to_json
@@ -103,8 +103,8 @@ puts PortableMoveNotation::Move.new(king, rook).to_json
 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" }]')
+# 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
 ```
 
@@ -112,7 +112,7 @@ You can also validate single actions:
 
 ```ruby
 # Check if an individual action is valid
-action_data = { "dst_square" => 12, "piece_name" => "P" }
+action_data = { "dst_square" => "e4", "piece_name" => "P" }
 puts PortableMoveNotation::Action.valid?(action_data) # => true
 ```
 

data/lib/portable_move_notation/action.rb

@@ -3,16 +3,16 @@
 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.
   #
   # | 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}          |
+  # | `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+                    |
+  # | `piece_hand` | Bare letter that enters the mover's hand – or +nil+                    |
   #
   # The implicit side‑effects are rule‑agnostic:
   # * `src_square` (when not +nil+) becomes empty.
@@ -22,17 +22,17 @@ module PortableMoveNotation
   #
   # === Examples
   #
-  # @example Basic piece movement (Chess pawn e2 → e4)
-  #   PortableMoveNotation::Action.new(src_square: 52, dst_square: 36, piece_name: "P")
+  # @example Basic piece movement (Chess pawn e2 → e4)
+  #   PortableMoveNotation::Action.new(src_square: "e2", dst_square: "e4", piece_name: "P")
   #
   # @example Drop from hand (Shogi pawn onto 27)
-  #   PortableMoveNotation::Action.new(src_square: nil, dst_square: 27, piece_name: "p")
+  #   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")
+  #   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
+  # @see https://sashite.dev/documents/pmn/ Portable Move Notation specification
+  # @see https://sashite.dev/documents/pnn/ Piece Name Notation specification
   class Action
     # Regular expression for validating piece identifiers as per PNN.
     # Matches: optional '+'/ '-' prefix, a single ASCII letter, optional "'" suffix.
@@ -65,8 +65,8 @@ module PortableMoveNotation
     # Builds an {Action} from keyword parameters.
     #
     # @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, 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.
     # @return [Action]
@@ -84,9 +84,9 @@ module PortableMoveNotation
     # Attributes
     # ------------------------------------------------------------------
 
-    # @return [Integer, nil] Source square (or +nil+ for drops)
+    # @return [String, nil] Source square (or +nil+ for drops)
     attr_reader :src_square
-    # @return [Integer] Destination square
+    # @return [String] Destination square
     attr_reader :dst_square
     # @return [String] Post‑move piece identifier
     attr_reader :piece_name
@@ -99,9 +99,9 @@ module PortableMoveNotation
 
     # Instantiates a new {Action}.
     #
-    # @param dst_square [Integer] Destination coordinate.
+    # @param dst_square [String] Destination coordinate.
     # @param piece_name [String]  Post‑move piece identifier.
-    # @param src_square [Integer, nil] Source coordinate or +nil+.
+    # @param src_square [String, 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)
@@ -148,14 +148,14 @@ module PortableMoveNotation
 
     private
 
-    # Validates that *square* is a non‑negative integer.
+    # Validates that *square* is a non‑empty string.
     #
     # @param square [Object]
     # @raise [ArgumentError] If invalid.
     def validate_square(square)
-      return if square.is_a?(::Integer) && square >= 0
+      return if square.is_a?(::String) && !square.empty?
 
-      raise ::ArgumentError, "Square must be a non-negative integer"
+      raise ::ArgumentError, "Square must be a non-empty string"
     end
 
     # Validates {#piece_name} format.

data/lib/portable_move_notation/move.rb

@@ -6,7 +6,7 @@ module PortableMoveNotation
   # == Move
   #
   # A **Move** is an *ordered list* of {Action} instances that, applied **in
-  # order**, realise a deterministic change of game state under Portable Move
+  # 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.
   #
@@ -15,15 +15,15 @@ module PortableMoveNotation
   # given game is beyond its responsibility and must be enforced by an engine
   # or referee layer.
   #
-  # === Quick start
+  # === Quick start
   #
   # ```ruby
   # require "portable_move_notation"
   #
   # # Plain chess pawn move: e2 → e4
   # pawn = PortableMoveNotation::Action.new(
-  #   src_square: 52,
-  #   dst_square: 36,
+  #   src_square: "e2",
+  #   dst_square: "e4",
   #   piece_name: "P"
   # )
   #
@@ -32,23 +32,23 @@ module PortableMoveNotation
   # # => JSON representation of the move
   #
   # parsed = PortableMoveNotation::Move.from_json(move.to_json)
-  # parsed.actions.first.dst_square  # => 36
+  # parsed.actions.first.dst_square  # => "e4"
   # ```
   #
   # === Composite example (Chess kingside castling)
   #
   # ```ruby
   # king = PortableMoveNotation::Action.new(
-  #   src_square: 60, dst_square: 62, piece_name: "K"
+  #   src_square: "e1", dst_square: "g1", piece_name: "K"
   # )
   # rook = PortableMoveNotation::Action.new(
-  #   src_square: 63, dst_square: 61, piece_name: "R"
+  #   src_square: "h1", dst_square: "f1", piece_name: "R"
   # )
   #
   # castle = PortableMoveNotation::Move.new(king, rook)
   # ```
   #
-  # @see https://sashite.dev/documents/pmn/ Portable Move Notation specification
+  # @see https://sashite.dev/documents/pmn/ Portable Move Notation specification
   class Move
     # --------------------------------------------------------------------
     # Class helpers
@@ -63,7 +63,7 @@ module PortableMoveNotation
     # @return [Boolean] +true+ when every element passes {Action.valid?}.
     #
     # @example Validate PMN parsed from JSON
-    #   data = JSON.parse('[{"dst_square":27,"piece_name":"p"}]')
+    #   data = JSON.parse('[{"dst_square":"e7","piece_name":"p"}]')
     #   PortableMoveNotation::Move.valid?(data)  # => true
     def self.valid?(pmn_data)
       return false unless pmn_data.is_a?(::Array) && !pmn_data.empty?
@@ -79,7 +79,7 @@ module PortableMoveNotation
     # @raise [KeyError] If an action hash lacks required keys.
     #
     # @example
-    #   json = '[{"src_square":nil,"dst_square":27,"piece_name":"p"}]'
+    #   json = '[{"src_square":null,"dst_square":"e7","piece_name":"p"}]'
     #   PortableMoveNotation::Move.from_json(json)
     def self.from_json(json_string)
       from_pmn(::JSON.parse(json_string))
@@ -110,7 +110,7 @@ module PortableMoveNotation
     # @raise [KeyError] If +actions+ is missing.
     #
     # @example
-    #   Move.from_params(actions: [src_square: nil, dst_square: 27, piece_name: "p"])
+    #   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)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: portable_move_notation
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  version: 2.2.0
 platform: ruby
 authors:
 - Cyril Kato