sashite-pan 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eec6ed9599bc268e1ef620b16fb261435b718bd6f95be8b74d82d31047caaf78
-  data.tar.gz: 57b17727d5e48a9a749af2962caa97e7e646ea91130fa9a44bb8eedc9690f7be
+  metadata.gz: 2e35bec227c5721965c2355d4534738acc1cc54807a7e3358a944c0c60cf3fd3
+  data.tar.gz: 30ba0f48da191edf2b971e8eb2fb3d94ff03a7f39580bfb25d334b15cb692a5f
 SHA512:
-  metadata.gz: 1f0b7ff44689f303b3555b3aad7e64b4960a3f1f9a51ed7830312a2110536e9ff834f448c3145271a2206d60669374cab1b1a0637317bc7d391e8a93de3c3dba
-  data.tar.gz: c14bcb71d0703847b7c073c30cb66ea2c785502daf21ecf08cc384576849795944f06df6142d11dde9c09fa1efca612078445a17de255af2cdd4975e076f5e2f
+  metadata.gz: 44bb851835eeb4327ddd27aa82068332460571083f02af9100d4bcb37aa8944dea0e700a606496eeb1ae295f377a0e8dda2f737b00d50d191c9489083a21e629
+  data.tar.gz: ad48f345973e0ccf6582446ab35cf02828eab72e0399297fef89dd713e43173f47780ea6214880d6924da73965037ac95175bf79d5cfc40da0b65d518314cced

data/README.md

@@ -9,16 +9,15 @@
 
 ## What is PAN?
 
-PAN (Portable Action Notation) is a compact, string-based format for representing **executed moves** in abstract strategy board games. PAN serves as a human-readable and space-efficient alternative to PMN (Portable Move Notation), expressing the same semantic information in a condensed textual format.
+PAN (Portable Action Notation) is a compact, string-based format for representing **executed moves** in abstract strategy board games played on coordinate-based boards. PAN provides a human-readable and space-efficient notation for expressing move actions in a rule-agnostic manner.
 
-While PMN uses JSON arrays to describe move sequences, PAN encodes the same information using a delimited string format that is easier to read, write, and transmit in contexts where JSON overhead is undesirable.
+PAN focuses on representing the spatial aspects of moves: where pieces move from and to, and whether the move involves capture or placement. The notation is designed to be intuitive and compatible with standard algebraic coordinate systems.
 
 This gem implements the [PAN Specification v1.0.0](https://sashite.dev/documents/pan/1.0.0/), providing a Ruby interface for:
 
-- Converting between PAN strings and PMN format
 - Parsing PAN strings into structured move data
-- Creating PAN strings from move components
 - Validating PAN strings according to the specification
+- Converting between PAN and other move representations
 
 ## Installation
 
@@ -35,54 +34,54 @@ gem install sashite-pan
 
 ## PAN Format
 
-A PAN string represents one or more **actions** that constitute a complete move in a game. The format structure is:
-
-### Single Action
+PAN uses three fundamental move types with intuitive operators:
 
+### Simple Move (Non-capture)
 ```
-<source>,<destination>,<piece>[,<hand_piece>]
+<source>-<destination>
 ```
+**Example**: `e2-e4` - Moves a piece from e2 to e4
 
-### Multiple Actions
+### Capture Move
+```
+<source>x<destination>
+```
+**Example**: `e4xd5` - Moves a piece from e4 to d5, capturing the piece at d5
 
+### Drop/Placement
 ```
-<action1>;<action2>[;<action3>...]
+*<destination>
 ```
+**Example**: `*e4` - Places a piece at e4 from off-board (hand, reserve, etc.)
+
+### Coordinate System
 
-Where:
+PAN uses algebraic coordinates consisting of:
+- **File**: A single lowercase letter (`a-z`)
+- **Rank**: A single digit (`0-9`)
 
-- **source**: Origin square label, or `*` for drops from hand
-- **destination**: Target square label
-- **piece**: Piece being moved (PNN format with optional modifiers)
-- **hand_piece**: Optional piece added to mover's hand (captures, promotions)
+Examples: `e4`, `a1`, `h8`, `d5`
 
 ## Basic Usage
 
 ### Parsing PAN Strings
 
-Convert a PAN string into PMN format (array of action hashes):
+Convert a PAN string into structured move data:
 
 ```ruby
 require "sashite-pan"
 
 # Simple move
-result = Sashite::Pan.parse("27,18,+P")
-# => [{"src_square"=>"27", "dst_square"=>"18", "piece_name"=>"+P"}]
+result = Sashite::Pan.parse("e2-e4")
+# => {type: :move, source: "e2", destination: "e4"}
 
-# Capture with hand piece
-result = Sashite::Pan.parse("36,27,B,P")
-# => [{"src_square"=>"36", "dst_square"=>"27", "piece_name"=>"B", "piece_hand"=>"P"}]
+# Capture
+result = Sashite::Pan.parse("e4xd5")
+# => {type: :capture, source: "e4", destination: "d5"}
 
 # Drop from hand
-result = Sashite::Pan.parse("*,27,p")
-# => [{"src_square"=>nil, "dst_square"=>"27", "piece_name"=>"p"}]
-
-# Multiple actions (castling)
-result = Sashite::Pan.parse("e1,g1,K;h1,f1,R")
-# => [
-#   {"src_square"=>"e1", "dst_square"=>"g1", "piece_name"=>"K"},
-#   {"src_square"=>"h1", "dst_square"=>"f1", "piece_name"=>"R"}
-# ]
+result = Sashite::Pan.parse("*e4")
+# => {type: :drop, destination: "e4"}
 ```
 
 ### Safe Parsing
@@ -93,199 +92,187 @@ Parse a PAN string without raising exceptions:
 require "sashite-pan"
 
 # Valid PAN string
-result = Sashite::Pan.safe_parse("e2,e4,P'")
-# => [{"src_square"=>"e2", "dst_square"=>"e4", "piece_name"=>"P'"}]
+result = Sashite::Pan.safe_parse("e2-e4")
+# => {type: :move, source: "e2", destination: "e4"}
 
 # Invalid PAN string
-result = Sashite::Pan.safe_parse("invalid pan string")
+result = Sashite::Pan.safe_parse("invalid")
 # => nil
 ```
 
-### Creating PAN Strings
+### Validation
 
-Convert PMN actions (array of hashes) into a PAN string:
+Check if a string is valid PAN notation:
 
 ```ruby
 require "sashite-pan"
 
-# Simple move
-pmn_actions = [{"src_square" => "27", "dst_square" => "18", "piece_name" => "+P"}]
-pan_string = Sashite::Pan.dump(pmn_actions)
-# => "27,18,+P"
-
-# Capture with hand piece
-pmn_actions = [{"src_square" => "36", "dst_square" => "27", "piece_name" => "B", "piece_hand" => "P"}]
-pan_string = Sashite::Pan.dump(pmn_actions)
-# => "36,27,B,P"
+Sashite::Pan.valid?("e2-e4")    # => true
+Sashite::Pan.valid?("*e4")      # => true
+Sashite::Pan.valid?("e4xd5")    # => true
 
-# Drop from hand
-pmn_actions = [{"src_square" => nil, "dst_square" => "27", "piece_name" => "p"}]
-pan_string = Sashite::Pan.dump(pmn_actions)
-# => "*,27,p"
-
-# Multiple actions (castling)
-pmn_actions = [
-  {"src_square" => "e1", "dst_square" => "g1", "piece_name" => "K"},
-  {"src_square" => "h1", "dst_square" => "f1", "piece_name" => "R"}
-]
-pan_string = Sashite::Pan.dump(pmn_actions)
-# => "e1,g1,K;h1,f1,R"
+Sashite::Pan.valid?("")         # => false
+Sashite::Pan.valid?("e2-e2")    # => false (source equals destination)
+Sashite::Pan.valid?("E2-e4")    # => false (uppercase file)
+Sashite::Pan.valid?("e2 - e4")  # => false (spaces not allowed)
 ```
 
-### Safe Dumping
+## Examples
 
-Create PAN strings without raising exceptions:
+### Chess Examples
 
 ```ruby
 require "sashite-pan"
 
-# Valid PMN data
-pmn_actions = [{"src_square" => "e2", "dst_square" => "e4", "piece_name" => "P"}]
-result = Sashite::Pan.safe_dump(pmn_actions)
-# => "e2,e4,P"
+# Pawn advance
+Sashite::Pan.parse("e2-e4")
+# => {type: :move, source: "e2", destination: "e4"}
 
-# Invalid PMN data
-invalid_data = [{"invalid" => "data"}]
-result = Sashite::Pan.safe_dump(invalid_data)
-# => nil
-```
+# Capture
+Sashite::Pan.parse("exd5")
+# => {type: :capture, source: "e4", destination: "d5"}
 
-### Validation
+# Note: PAN cannot distinguish piece types or promotion choices
+# These moves require game context for complete interpretation:
+Sashite::Pan.parse("e7-e8")  # Could be pawn promotion to any piece
+Sashite::Pan.parse("a1-a8")  # Could be rook, queen, or promoted piece
+```
 
-Check if a string is valid PAN notation:
+### Shogi Examples
 
 ```ruby
 require "sashite-pan"
 
-Sashite::Pan.valid?("27,18,+P")           # => true
-Sashite::Pan.valid?("*,27,p")             # => true
-Sashite::Pan.valid?("e1,g1,K;h1,f1,R")   # => true
+# Piece movement
+Sashite::Pan.parse("g7-f7")
+# => {type: :move, source: "g7", destination: "f7"}
+
+# Drop from hand
+Sashite::Pan.parse("*e5")
+# => {type: :drop, destination: "e5"}
+
+# Capture (captured piece goes to hand in Shogi)
+Sashite::Pan.parse("h2xg2")
+# => {type: :capture, source: "h2", destination: "g2"}
 
-Sashite::Pan.valid?("")                   # => false
-Sashite::Pan.valid?("invalid")            # => false
-Sashite::Pan.valid?("27,18")              # => false (missing piece)
+# Note: PAN cannot specify which piece type is being dropped
+# or whether a piece is promoted
 ```
 
-## Examples
+## Limitations and Context Dependency
 
-### Shogi Examples
+**Important**: PAN is intentionally minimal and rule-agnostic. It has several important limitations:
 
-```ruby
-require "sashite-pan"
+### What PAN Cannot Represent
 
-# Pawn promotion
-Sashite::Pan.parse("27,18,+P")
-# => [{"src_square"=>"27", "dst_square"=>"18", "piece_name"=>"+P"}]
+- **Piece types**: Cannot distinguish between different pieces making the same move
+- **Promotion choices**: Cannot specify what piece a pawn promotes to
+- **Game state**: No encoding of check, checkmate, or game conditions
+- **Complex moves**: Castling requires external representation
+- **Piece identity**: Multiple pieces of the same type making similar moves
 
-# Bishop captures promoted pawn
-Sashite::Pan.parse("36,27,B,P")
-# => [{"src_square"=>"36", "dst_square"=>"27", "piece_name"=>"B", "piece_hand"=>"P"}]
+### Examples of Ambiguity
 
-# Drop pawn from hand
-Sashite::Pan.parse("*,27,p")
-# => [{"src_square"=>nil, "dst_square"=>"27", "piece_name"=>"p"}]
+```ruby
+# These PAN strings are syntactically valid but may be ambiguous:
+
+"e7-e8"    # Pawn promotion - but to what piece?
+"*g4"      # Drop - but which piece from hand?
+"a1-a8"    # Movement - but which piece type?
+"e1-g1"    # Could be castling, but rook movement not shown
 ```
 
-### Chess Examples
+### When PAN is Insufficient
+
+- Games where multiple pieces can make the same spatial move
+- Games requiring promotion choice specification
+- Analysis requiring piece type identification
+- Self-contained game records without context
+
+## Error Handling
+
+The library provides detailed error messages for invalid input:
 
 ```ruby
 require "sashite-pan"
 
-# Kingside castling
-Sashite::Pan.parse("e1,g1,K;h1,f1,R")
-# => [
-#   {"src_square"=>"e1", "dst_square"=>"g1", "piece_name"=>"K"},
-#   {"src_square"=>"h1", "dst_square"=>"f1", "piece_name"=>"R"}
-# ]
-
-# Pawn with state modifier (can be captured en passant)
-Sashite::Pan.parse("e2,e4,P'")
-# => [{"src_square"=>"e2", "dst_square"=>"e4", "piece_name"=>"P'"}]
-
-# En passant capture (multi-step)
-Sashite::Pan.parse("d4,e3,p;e3,e4,p")
-# => [
-#   {"src_square"=>"d4", "dst_square"=>"e3", "piece_name"=>"p"},
-#   {"src_square"=>"e3", "dst_square"=>"e4", "piece_name"=>"p"}
-# ]
+begin
+  Sashite::Pan.parse("e2-e2")  # Source equals destination
+rescue Sashite::Pan::Parser::Error => e
+  puts e.message  # => "Source and destination cannot be identical"
+end
+
+begin
+  Sashite::Pan.parse("E2-e4")  # Invalid uppercase file
+rescue Sashite::Pan::Parser::Error => e
+  puts e.message  # => "Invalid PAN format: E2-e4"
+end
+
+begin
+  Sashite::Pan.parse("")  # Empty string
+rescue Sashite::Pan::Parser::Error => e
+  puts e.message  # => "PAN string cannot be empty"
+end
 ```
 
-## Integration with PMN
+## Regular Expression Pattern
 
-PAN is designed to work seamlessly with PMN (Portable Move Notation). You can easily convert between the two formats:
+PAN strings can be validated using this pattern:
 
 ```ruby
-require "sashite-pan"
-require "portable_move_notation"
-
-# Start with a PAN string
-pan_string = "e2,e4,P';d7,d5,p"
-
-# Convert to PMN format
-pmn_actions = Sashite::Pan.parse(pan_string)
-# => [
-#   {"src_square"=>"e2", "dst_square"=>"e4", "piece_name"=>"P'"},
-#   {"src_square"=>"d7", "dst_square"=>"d5", "piece_name"=>"p"}
-# ]
-
-# Use with PMN library
-move = PortableMoveNotation::Move.new(*pmn_actions.map { |action|
-  PortableMoveNotation::Action.new(**action.transform_keys(&:to_sym))
-})
-
-# Convert back to PAN
-new_pan_string = Sashite::Pan.dump(pmn_actions)
-# => "e2,e4,P';d7,d5,p"
-```
+PAN_PATTERN = /\A(\*|[a-z][0-9][-x])([a-z][0-9])\z/
 
-## Use Cases
+def valid_pan?(string)
+  return false unless string.match?(PAN_PATTERN)
 
-PAN is optimal for:
+  # Additional validation for source != destination
+  if string.include?('-') || string.include?('x')
+    source = string[0..1]
+    destination = string[-2..-1]
+    return source != destination
+  end
 
-- **Move logging and game records**: Compact storage of game moves
-- **Network transmission**: Efficient move data transmission
-- **Command-line interfaces**: Human-readable move input/output
-- **Quick manual entry**: Easy to type and edit move sequences
-- **Storage optimization**: Space-efficient alternative to JSON
+  true
+end
+```
 
-PMN is optimal for:
+## Use Cases
 
-- **Programmatic analysis**: Complex move processing and validation
-- **JSON-based systems**: Direct integration with JSON APIs
-- **Structured data processing**: Schema validation and type checking
+### Optimal for PAN
 
-## Properties of PAN
+- **Move logs**: Simple game records where context is available
+- **User interfaces**: Command input for move entry
+- **Network protocols**: Compact move transmission
+- **Quick notation**: Manual notation for simple games
 
-- **Rule-agnostic**: PAN does not encode legality, validity, or game-specific conditions
-- **Space-efficient**: Significantly more compact than equivalent JSON representation
-- **Human-readable**: Easy to read, write, and understand
-- **Lossless conversion**: Perfect bidirectional conversion with PMN format
+### Consider Alternatives When
 
-## Error Handling
+- **Ambiguous games**: Multiple pieces can make the same spatial move
+- **Complex promotions**: Games with multiple promotion choices
+- **Analysis tools**: When piece identity is crucial
+- **Self-contained records**: When context is not available
 
-The library provides detailed error messages for invalid input:
+## Integration Considerations
 
-```ruby
-require "sashite-pan"
+When using PAN in your applications:
 
-begin
-  Sashite::Pan.parse("invalid,pan")  # Missing piece component
-rescue Sashite::Pan::Parser::Error => e
-  puts e.message  # => "Action must have at least 3 components (source, destination, piece)"
-end
+1. **Always pair with context**: Store board state alongside PAN moves
+2. **Document assumptions**: Clearly specify how ambiguities are resolved
+3. **Validate rigorously**: Check both syntax and semantic validity
+4. **Handle edge cases**: Plan for promotion and drop ambiguities
 
-begin
-  Sashite::Pan.dump([{"invalid" => "data"}])  # Missing required fields
-rescue Sashite::Pan::Dumper::Error => e
-  puts e.message  # => "Action must have dst_square"
-end
-```
+## Properties of PAN
+
+- **Rule-agnostic**: Does not encode piece types, legality, or game-specific conditions
+- **Compact**: Minimal character overhead (3-5 characters per move)
+- **Human-readable**: Intuitive algebraic notation
+- **Space-efficient**: Excellent for large game databases
+- **Context-dependent**: Requires external game state for complete interpretation
 
 ## Documentation
 
 - [Official PAN Specification](https://sashite.dev/documents/pan/1.0.0/)
 - [API Documentation](https://rubydoc.info/github/sashite/pan.rb/main)
-- [PMN Specification](https://sashite.dev/documents/pmn/1.0.0/)
 
 ## License
 

data/lib/sashite/pan/dumper.rb

@@ -1,80 +1,120 @@
 # frozen_string_literal: true
 
-require_relative "dumper/error"
-
 module Sashite
   module Pan
-    # Dumper for converting PMN format to PAN strings
+    # Dumper for converting structured move data to PAN strings
     module Dumper
-      # Convert PMN actions to PAN string
+      class Error < ::StandardError
+      end
+
+      # Convert structured move data to PAN string
       #
-      # @param pmn_actions [Array<Hash>] Array of PMN action objects
+      # @param move_data [Hash] Move data with type, source, destination
       # @return [String] PAN string representation
-      # @raise [Dumper::Error] If the PMN data is invalid
-      def self.call(pmn_actions)
-        raise Dumper::Error, "PMN actions cannot be nil" if pmn_actions.nil?
-        raise Dumper::Error, "PMN actions cannot be empty" if pmn_actions.empty?
-        raise Dumper::Error, "PMN actions must be an array" unless pmn_actions.is_a?(::Array)
+      # @raise [Dumper::Error] If the move data is invalid
+      def self.call(move_data)
+        raise Dumper::Error, "Move data cannot be nil" if move_data.nil?
+        raise Dumper::Error, "Move data must be a Hash" unless move_data.is_a?(::Hash)
 
-        pmn_actions.map { |action| dump_action(action) }.join(";")
+        validate_move_data(move_data)
+
+        case move_data[:type]
+        when :move
+          dump_simple_move(move_data)
+        when :capture
+          dump_capture_move(move_data)
+        when :drop
+          dump_drop_move(move_data)
+        else
+          raise Dumper::Error, "Invalid move type: #{move_data[:type]}"
+        end
       end
 
       private
 
-      # Convert a single PMN action to PAN format
+      # Validate the structure of move data
       #
-      # @param action [Hash] PMN action object
-      # @return [String] PAN action string
-      # @raise [Dumper::Error] If the action is invalid
-      def self.dump_action(action)
-        validate_pmn_action(action)
+      # @param move_data [Hash] Move data to validate
+      # @raise [Dumper::Error] If move data is invalid
+      def self.validate_move_data(move_data)
+        unless move_data.key?(:type)
+          raise Dumper::Error, "Move data must have :type key"
+        end
 
-        components = [
-          dump_source_square(action["src_square"]),
-          action["dst_square"],
-          action["piece_name"]
-        ]
+        unless move_data.key?(:destination)
+          raise Dumper::Error, "Move data must have :destination key"
+        end
 
-        components << action["piece_hand"] if action["piece_hand"]
+        validate_coordinate(move_data[:destination], "destination")
 
-        components.join(",")
+        case move_data[:type]
+        when :move, :capture
+          unless move_data.key?(:source)
+            raise Dumper::Error, "Move and capture types must have :source key"
+          end
+          validate_coordinate(move_data[:source], "source")
+          validate_different_coordinates(move_data[:source], move_data[:destination])
+        when :drop
+          if move_data.key?(:source)
+            raise Dumper::Error, "Drop type cannot have :source key"
+          end
+        else
+          raise Dumper::Error, "Invalid move type: #{move_data[:type]}"
+        end
       end
 
-      # Validate PMN action structure
+      # Validate a coordinate follows PAN format
       #
-      # @param action [Hash] PMN action to validate
-      # @raise [Dumper::Error] If action is invalid
-      def self.validate_pmn_action(action)
-        raise Dumper::Error, "Action must be a Hash" unless action.is_a?(::Hash)
-        raise Dumper::Error, "Action must have dst_square" unless action.key?("dst_square")
-        raise Dumper::Error, "Action must have piece_name" unless action.key?("piece_name")
-
-        raise Dumper::Error, "dst_square cannot be nil or empty" if action["dst_square"].nil? || action["dst_square"].empty?
-        raise Dumper::Error, "piece_name cannot be nil or empty" if action["piece_name"].nil? || action["piece_name"].empty?
-
-        validate_piece_identifier(action["piece_name"])
-        validate_piece_identifier(action["piece_hand"]) if action["piece_hand"]
+      # @param coordinate [String] Coordinate to validate
+      # @param field_name [String] Name of the field for error messages
+      # @raise [Dumper::Error] If coordinate is invalid
+      def self.validate_coordinate(coordinate, field_name)
+        if coordinate.nil? || coordinate.empty?
+          raise Dumper::Error, "#{field_name.capitalize} coordinate cannot be nil or empty"
+        end
+
+        unless coordinate.is_a?(::String)
+          raise Dumper::Error, "#{field_name.capitalize} coordinate must be a String"
+        end
+
+        unless coordinate.match?(/\A[a-z][0-9]\z/)
+          raise Dumper::Error, "Invalid #{field_name} coordinate format: #{coordinate}. Must be lowercase letter followed by digit (e.g., 'e4')"
+        end
       end
 
-      # Convert source square, handling drops
+      # Validate that source and destination are different
       #
-      # @param src_square [String, nil] Source square or nil for drop
-      # @return [String] "*" for drops, otherwise the square identifier
-      def self.dump_source_square(src_square)
-        src_square.nil? ? "*" : src_square
+      # @param source [String] Source coordinate
+      # @param destination [String] Destination coordinate
+      # @raise [Dumper::Error] If coordinates are the same
+      def self.validate_different_coordinates(source, destination)
+        if source == destination
+          raise Dumper::Error, "Source and destination coordinates cannot be identical: #{source}"
+        end
       end
 
-      # Validate piece identifier follows PNN specification
+      # Generate PAN string for simple move
       #
-      # @param piece [String] Piece identifier to validate
-      # @raise [Dumper::Error] If piece identifier is invalid
-      def self.validate_piece_identifier(piece)
-        return if piece.nil?
-
-        # PNN pattern: optional prefix (+/-), letter (a-z/A-Z), optional suffix (')
-        unless piece.match?(/\A[-+]?[a-zA-Z][']?\z/)
-          raise Dumper::Error, "Invalid piece identifier: #{piece}"
-        end
+      # @param move_data [Hash] Move data with :source and :destination
+      # @return [String] PAN string in format "source-destination"
+      def self.dump_simple_move(move_data)
+        "#{move_data[:source]}-#{move_data[:destination]}"
+      end
+
+      # Generate PAN string for capture move
+      #
+      # @param move_data [Hash] Move data with :source and :destination
+      # @return [String] PAN string in format "sourcexdestination"
+      def self.dump_capture_move(move_data)
+        "#{move_data[:source]}x#{move_data[:destination]}"
+      end
+
+      # Generate PAN string for drop move
+      #
+      # @param move_data [Hash] Move data with :destination
+      # @return [String] PAN string in format "*destination"
+      def self.dump_drop_move(move_data)
+        "*#{move_data[:destination]}"
       end
     end
   end

data/lib/sashite/pan/parser.rb

@@ -1,89 +1,103 @@
 # frozen_string_literal: true
 
-require_relative "parser/error"
-
 module Sashite
   module Pan
     # Parser for Portable Action Notation (PAN) strings
     module Parser
-      # Parse a PAN string into PMN format
+      class Error < ::StandardError
+      end
+
+      # Regular expression pattern for validating PAN strings
+      PAN_PATTERN = /\A(\*|[a-z][0-9][-x])([a-z][0-9])\z/
+
+      # Parse a PAN string into structured move data
       #
       # @param pan_string [String] The PAN string to parse
-      # @return [Array<Hash>] Array of PMN action objects
+      # @return [Hash] Structured move data with type, source, and destination
       # @raise [Parser::Error] If the PAN string is invalid
       def self.call(pan_string)
         raise Parser::Error, "PAN string cannot be nil" if pan_string.nil?
+        raise Parser::Error, "PAN string must be a String" unless pan_string.is_a?(::String)
         raise Parser::Error, "PAN string cannot be empty" if pan_string.empty?
 
-        actions = pan_string.split(";").map(&:strip)
-        raise Parser::Error, "No actions found" if actions.empty?
-
-        actions.map { |action| parse_action(action) }
+        validate_format(pan_string)
+        parse_move(pan_string)
       end
 
       private
 
-      # Parse a single action string into a PMN action hash
+      # Validate the basic format of a PAN string
       #
-      # @param action_string [String] Single action in PAN format
-      # @return [Hash] PMN action object
-      # @raise [Parser::Error] If the action is invalid
-      def self.parse_action(action_string)
-        components = action_string.split(",").map(&:strip)
-
-        validate_action_components(components)
+      # @param pan_string [String] The PAN string to validate
+      # @raise [Parser::Error] If format is invalid
+      def self.validate_format(pan_string)
+        unless pan_string.match?(PAN_PATTERN)
+          raise Parser::Error, "Invalid PAN format: #{pan_string}"
+        end
 
-        {
-          "src_square" => parse_source_square(components[0]),
-          "dst_square" => components[1],
-          "piece_name" => components[2],
-          "piece_hand" => components[3] || nil
-        }.compact
+        # Additional validation for source != destination in moves and captures
+        if pan_string.include?('-') || pan_string.include?('x')
+          source = pan_string[0..1]
+          destination = pan_string[-2..-1]
+          if source == destination
+            raise Parser::Error, "Source and destination cannot be identical: #{source}"
+          end
+        end
       end
 
-      # Validate action components structure
+      # Parse the move based on its type
       #
-      # @param components [Array<String>] Components of the action
-      # @raise [Parser::Error] If components are invalid
-      def self.validate_action_components(components)
-        case components.length
-        when 0, 1, 2
-          raise Parser::Error, "Action must have at least 3 components (source, destination, piece)"
-        when 3, 4
-          # Valid number of components
+      # @param pan_string [String] The validated PAN string
+      # @return [Hash] Structured move data
+      def self.parse_move(pan_string)
+        case pan_string
+        when /\A([a-z][0-9])-([a-z][0-9])\z/
+          parse_simple_move($1, $2)
+        when /\A([a-z][0-9])x([a-z][0-9])\z/
+          parse_capture_move($1, $2)
+        when /\A\*([a-z][0-9])\z/
+          parse_drop_move($1)
         else
-          raise Parser::Error, "Action cannot have more than 4 components"
+          # This should never happen due to earlier validation
+          raise Parser::Error, "Unexpected PAN format: #{pan_string}"
         end
-
-        components.each_with_index do |component, index|
-          if component.nil? || component.empty?
-            raise Parser::Error, "Component #{index} cannot be empty"
-          end
-        end
-
-        validate_piece_identifier(components[2])
-        validate_piece_identifier(components[3]) if components[3]
       end
 
-      # Parse source square, handling drop notation
+      # Parse a simple move (non-capture)
       #
-      # @param source [String] Source square or "*" for drop
-      # @return [String, nil] Square identifier or nil for drops
-      def self.parse_source_square(source)
-        source == "*" ? nil : source
+      # @param source [String] Source coordinate
+      # @param destination [String] Destination coordinate
+      # @return [Hash] Move data for simple move
+      def self.parse_simple_move(source, destination)
+        {
+          type: :move,
+          source: source,
+          destination: destination
+        }
       end
 
-      # Validate piece identifier follows PNN specification
+      # Parse a capture move
       #
-      # @param piece [String] Piece identifier to validate
-      # @raise [Parser::Error] If piece identifier is invalid
-      def self.validate_piece_identifier(piece)
-        return if piece.nil?
+      # @param source [String] Source coordinate
+      # @param destination [String] Destination coordinate
+      # @return [Hash] Move data for capture move
+      def self.parse_capture_move(source, destination)
+        {
+          type: :capture,
+          source: source,
+          destination: destination
+        }
+      end
 
-        # PNN pattern: optional prefix (+/-), letter (a-z/A-Z), optional suffix (')
-        unless piece.match?(/\A[-+]?[a-zA-Z][']?\z/)
-          raise Parser::Error, "Invalid piece identifier: #{piece}"
-        end
+      # Parse a drop/placement move
+      #
+      # @param destination [String] Destination coordinate
+      # @return [Hash] Move data for drop move
+      def self.parse_drop_move(destination)
+        {
+          type: :drop,
+          destination: destination
+        }
       end
     end
   end

data/lib/sashite/pan.rb

@@ -9,28 +9,53 @@ module Sashite
     # Main interface for PAN operations
     module_function
 
-    # Parse a PAN string into PMN format
+    # Parse a PAN string into structured move data
     #
     # @param pan_string [String] The PAN string to parse
-    # @return [Array<Hash>] Array of PMN action objects
+    # @return [Hash] Structured move data with type, source, and destination
     # @raise [Parser::Error] If the PAN string is invalid
+    # @example
+    #   Sashite::Pan.parse("e2-e4")
+    #   # => {type: :move, source: "e2", destination: "e4"}
+    #
+    #   Sashite::Pan.parse("e4xd5")
+    #   # => {type: :capture, source: "e4", destination: "d5"}
+    #
+    #   Sashite::Pan.parse("*e4")
+    #   # => {type: :drop, destination: "e4"}
     def parse(pan_string)
       Parser.call(pan_string)
     end
 
-    # Convert PMN actions to PAN string
+    # Convert structured move data to PAN string
     #
-    # @param pmn_actions [Array<Hash>] Array of PMN action objects
+    # @param move_data [Hash] Structured move data with type, source, and destination
     # @return [String] PAN string representation
-    # @raise [Dumper::Error] If the PMN data is invalid
-    def dump(pmn_actions)
-      Dumper.call(pmn_actions)
+    # @raise [Dumper::Error] If the move data is invalid
+    # @example
+    #   Sashite::Pan.dump({type: :move, source: "e2", destination: "e4"})
+    #   # => "e2-e4"
+    #
+    #   Sashite::Pan.dump({type: :capture, source: "e4", destination: "d5"})
+    #   # => "e4xd5"
+    #
+    #   Sashite::Pan.dump({type: :drop, destination: "e4"})
+    #   # => "*e4"
+    def dump(move_data)
+      Dumper.call(move_data)
     end
 
     # Validate a PAN string without raising exceptions
     #
     # @param pan_string [String] The PAN string to validate
     # @return [Boolean] True if valid, false otherwise
+    # @example
+    #   Sashite::Pan.valid?("e2-e4")    # => true
+    #   Sashite::Pan.valid?("*e4")      # => true
+    #   Sashite::Pan.valid?("e4xd5")    # => true
+    #   Sashite::Pan.valid?("")         # => false
+    #   Sashite::Pan.valid?("e2-e2")    # => false
+    #   Sashite::Pan.valid?("E2-e4")    # => false
     def valid?(pan_string)
       parse(pan_string)
       true
@@ -41,21 +66,100 @@ module Sashite
     # Parse a PAN string without raising exceptions
     #
     # @param pan_string [String] The PAN string to parse
-    # @return [Array<Hash>, nil] Array of PMN actions or nil if invalid
+    # @return [Hash, nil] Structured move data or nil if invalid
+    # @example
+    #   Sashite::Pan.safe_parse("e2-e4")
+    #   # => {type: :move, source: "e2", destination: "e4"}
+    #
+    #   Sashite::Pan.safe_parse("invalid")
+    #   # => nil
     def safe_parse(pan_string)
       parse(pan_string)
     rescue Parser::Error
       nil
     end
 
-    # Convert PMN actions to PAN string without raising exceptions
+    # Convert structured move data to PAN string without raising exceptions
     #
-    # @param pmn_actions [Array<Hash>] Array of PMN action objects
+    # @param move_data [Hash] Structured move data with type, source, and destination
     # @return [String, nil] PAN string or nil if invalid
-    def safe_dump(pmn_actions)
-      dump(pmn_actions)
+    # @example
+    #   Sashite::Pan.safe_dump({type: :move, source: "e2", destination: "e4"})
+    #   # => "e2-e4"
+    #
+    #   Sashite::Pan.safe_dump({invalid: :data})
+    #   # => nil
+    def safe_dump(move_data)
+      dump(move_data)
     rescue Dumper::Error
       nil
     end
+
+    # Check if a coordinate is valid according to PAN specification
+    #
+    # @param coordinate [String] The coordinate to validate
+    # @return [Boolean] True if valid, false otherwise
+    # @example
+    #   Sashite::Pan.valid_coordinate?("e4")   # => true
+    #   Sashite::Pan.valid_coordinate?("a1")   # => true
+    #   Sashite::Pan.valid_coordinate?("E4")   # => false (uppercase)
+    #   Sashite::Pan.valid_coordinate?("e10")  # => false (multi-digit rank)
+    def valid_coordinate?(coordinate)
+      return false unless coordinate.is_a?(::String)
+      coordinate.match?(/\A[a-z][0-9]\z/)
+    end
+
+    # Get the regular expression pattern used for PAN validation
+    #
+    # @return [Regexp] The regex pattern for PAN strings
+    # @example
+    #   pattern = Sashite::Pan.pattern
+    #   pattern.match?("e2-e4")  # => true
+    def pattern
+      Parser::PAN_PATTERN
+    end
+
+    # Convert a PAN string to a human-readable description
+    #
+    # @param pan_string [String] The PAN string to describe
+    # @return [String] Human-readable description
+    # @raise [Parser::Error] If the PAN string is invalid
+    # @example
+    #   Sashite::Pan.describe("e2-e4")
+    #   # => "Move from e2 to e4"
+    #
+    #   Sashite::Pan.describe("e4xd5")
+    #   # => "Capture from e4 to d5"
+    #
+    #   Sashite::Pan.describe("*e4")
+    #   # => "Drop to e4"
+    def describe(pan_string)
+      move_data = parse(pan_string)
+
+      case move_data[:type]
+      when :move
+        "Move from #{move_data[:source]} to #{move_data[:destination]}"
+      when :capture
+        "Capture from #{move_data[:source]} to #{move_data[:destination]}"
+      when :drop
+        "Drop to #{move_data[:destination]}"
+      end
+    end
+
+    # Convert a PAN string to a human-readable description without raising exceptions
+    #
+    # @param pan_string [String] The PAN string to describe
+    # @return [String, nil] Human-readable description or nil if invalid
+    # @example
+    #   Sashite::Pan.safe_describe("e2-e4")
+    #   # => "Move from e2 to e4"
+    #
+    #   Sashite::Pan.safe_describe("invalid")
+    #   # => nil
+    def safe_describe(pan_string)
+      describe(pan_string)
+    rescue Parser::Error
+      nil
+    end
   end
 end

data/lib/sashite-pan.rb

@@ -1,7 +1,15 @@
 # frozen_string_literal: true
 
-# Sashité namespace
+# Sashité namespace for board game notation libraries
 module Sashite
+  # Portable Action Notation (PAN) implementation for Ruby
+  #
+  # PAN is a compact, string-based format for representing executed moves
+  # in abstract strategy board games played on coordinate-based boards.
+  #
+  # @see https://sashite.dev/documents/pan/1.0.0/ PAN Specification v1.0.0
+  # @author Sashité
+  # @since 1.0.0
 end
 
 require_relative "sashite/pan"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-pan
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -9,7 +9,12 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: A Ruby implementation of the Portable Action Notation (PAN) specification.
+description: |
+  Parse and generate Portable Action Notation (PAN) strings for representing moves
+  in chess, shogi, and other strategy board games. PAN provides a compact,
+  human-readable format for move logging, game transmission, and database storage.
+  Supports simple moves (e2-e4), captures (exd5), and piece drops (*e4) with
+  comprehensive validation and error handling.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -20,9 +25,7 @@ files:
 - lib/sashite-pan.rb
 - lib/sashite/pan.rb
 - lib/sashite/pan/dumper.rb
-- lib/sashite/pan/dumper/error.rb
 - lib/sashite/pan/parser.rb
-- lib/sashite/pan/parser/error.rb
 homepage: https://github.com/sashite/pan.rb
 licenses:
 - MIT
@@ -49,5 +52,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Portable Action Notation (PAN) parser and validator for Ruby
+summary: Compact notation for board game moves - parse chess, shogi, and strategy
+  game actions
 test_files: []

data/lib/sashite/pan/dumper/error.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Sashite
-  module Pan
-    module Dumper
-      # Error raised when PAN dumping fails
-      class Error < ::StandardError
-      end
-    end
-  end
-end

data/lib/sashite/pan/parser/error.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Sashite
-  module Pan
-    module Parser
-      # Error raised when PAN parsing fails
-      class Error < ::StandardError
-      end
-    end
-  end
-end