sashite-pan 1.3.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12680869115791fc6fe8332162cbeaa71174b8ba5c5d74ebb531a805355dae1b
-  data.tar.gz: 1147d462de504b726ec26337bf8bfa69b28a8d3e195dbf6b2922b9b3ccaa9cf3
+  metadata.gz: 2e35bec227c5721965c2355d4534738acc1cc54807a7e3358a944c0c60cf3fd3
+  data.tar.gz: 30ba0f48da191edf2b971e8eb2fb3d94ff03a7f39580bfb25d334b15cb692a5f
 SHA512:
-  metadata.gz: 8bcb5c10788c3ba49269612062c6eea16251f372a176efd8c390fbe2e7967562bb4c83a27f7f70dd4f5af4af8f3a9ee33695f5d2a1394d105dff00e65043b45d
-  data.tar.gz: 0afbe377cfe6b68a5748f74221ef4e6084c55e0439ae6d7234e6864d5403e65a3b2d19f1c5f6579869a795c994c1ccc3f8b1ef0c8bc5ed2df8734318817c0c9a
+  metadata.gz: 44bb851835eeb4327ddd27aa82068332460571083f02af9100d4bcb37aa8944dea0e700a606496eeb1ae295f377a0e8dda2f737b00d50d191c9489083a21e629
+  data.tar.gz: ad48f345973e0ccf6582446ab35cf02828eab72e0399297fef89dd713e43173f47780ea6214880d6924da73965037ac95175bf79d5cfc40da0b65d518314cced

data/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2014-2021 Cyril Kato
+Copyright (c) 2014-2025 Cyril Kato
 
 MIT License
 

data/README.md

@@ -1,102 +1,283 @@
-# Portable Action Notation
+# Pan.rb
 
-[![Version](https://img.shields.io/github/v/tag/sashite/pan.rb?label=Version&logo=github)](https://github.com/sashite/pan.rb/releases)
+[![Version](https://img.shields.io/github/v/tag/sashite/pan.rb?label=Version&logo=github)](https://github.com/sashite/pan.rb/tags)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/pan.rb/main)
-[![CI](https://github.com/sashite/pan.rb/workflows/CI/badge.svg?branch=main)](https://github.com/sashite/pan.rb/actions?query=workflow%3Aci+branch%3Amain)
-[![RuboCop](https://github.com/sashite/pan.rb/workflows/RuboCop/badge.svg?branch=main)](https://github.com/sashite/pan.rb/actions?query=workflow%3Arubocop+branch%3Amain)
+![Ruby](https://github.com/sashite/pan.rb/actions/workflows/main.yml/badge.svg?branch=main)
 [![License](https://img.shields.io/github/license/sashite/pan.rb?label=License&logo=github)](https://github.com/sashite/pan.rb/raw/main/LICENSE.md)
 
-A Ruby interface for data serialization in [PAN](https://developer.sashite.com/specs/portable-action-notation) format.
+> **PAN** (Portable Action Notation) support for the Ruby language.
 
-## Installation
+## What is PAN?
+
+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.
+
+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:
 
-Add this line to your application's Gemfile:
+- Parsing PAN strings into structured move data
+- Validating PAN strings according to the specification
+- Converting between PAN and other move representations
+
+## Installation
 
 ```ruby
+# In your Gemfile
 gem "sashite-pan"
 ```
 
-And then execute:
+Or install manually:
 
 ```sh
-bundle
+gem install sashite-pan
 ```
 
-Or install it yourself as:
+## PAN Format
 
-```sh
-gem install sashite-pan
+PAN uses three fundamental move types with intuitive operators:
+
+### Simple Move (Non-capture)
+```
+<source>-<destination>
+```
+**Example**: `e2-e4` - Moves a piece from e2 to e4
+
+### Capture Move
+```
+<source>x<destination>
+```
+**Example**: `e4xd5` - Moves a piece from e4 to d5, capturing the piece at d5
+
+### Drop/Placement
 ```
+*<destination>
+```
+**Example**: `*e4` - Places a piece at e4 from off-board (hand, reserve, etc.)
+
+### Coordinate System
+
+PAN uses algebraic coordinates consisting of:
+- **File**: A single lowercase letter (`a-z`)
+- **Rank**: A single digit (`0-9`)
+
+Examples: `e4`, `a1`, `h8`, `d5`
 
-## Usage
+## Basic Usage
 
-Working with PAN can be very simple, for example:
+### Parsing PAN Strings
+
+Convert a PAN string into structured move data:
 
 ```ruby
-require "sashite/pan"
+require "sashite-pan"
+
+# Simple move
+result = Sashite::Pan.parse("e2-e4")
+# => {type: :move, source: "e2", destination: "e4"}
+
+# Capture
+result = Sashite::Pan.parse("e4xd5")
+# => {type: :capture, source: "e4", destination: "d5"}
+
+# Drop from hand
+result = Sashite::Pan.parse("*e4")
+# => {type: :drop, destination: "e4"}
+```
 
-# Emit a PAN string
+### Safe Parsing
 
-actions = [
-  [52, 36, "♙"]
-]
+Parse a PAN string without raising exceptions:
 
-Sashite::PAN.dump(*actions) # => "52,36,♙"
+```ruby
+require "sashite-pan"
 
-# Parse a PAN string
+# Valid PAN string
+result = Sashite::Pan.safe_parse("e2-e4")
+# => {type: :move, source: "e2", destination: "e4"}
 
-Sashite::PAN.parse("52,36,♙") # => [[52, 36, "♙", nil]]
+# Invalid PAN string
+result = Sashite::Pan.safe_parse("invalid")
+# => nil
 ```
 
-## Example
+### Validation
 
-### Promoting a chess pawn into a knight
+Check if a string is valid PAN notation:
 
 ```ruby
-Sashite::PAN.dump([12, 4, "♘"]) # => "12,4,♘"
-Sashite::PAN.parse("12,4,♘") # => [[12, 4, "♘", nil]]
+require "sashite-pan"
+
+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 (source equals destination)
+Sashite::Pan.valid?("E2-e4")    # => false (uppercase file)
+Sashite::Pan.valid?("e2 - e4")  # => false (spaces not allowed)
 ```
 
-### Capturing a rook and promoting a shogi pawn
+## Examples
+
+### Chess Examples
 
 ```ruby
-Sashite::PAN.dump([33, 24, "+P", "R"]) # => "33,24,+P,R"
-Sashite::PAN.parse("33,24,+P,R") # => [[33, 24, "+P", "R"]]
+require "sashite-pan"
+
+# Pawn advance
+Sashite::Pan.parse("e2-e4")
+# => {type: :move, source: "e2", destination: "e4"}
+
+# Capture
+Sashite::Pan.parse("exd5")
+# => {type: :capture, source: "e4", destination: "d5"}
+
+# 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
 ```
 
-### Dropping a shogi pawn
+### Shogi Examples
 
 ```ruby
-Sashite::PAN.dump([nil, 42, "P"]) # => "*,42,P"
-Sashite::PAN.parse("*,42,P") # => [[nil, 42, "P", nil]]
+require "sashite-pan"
+
+# 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"}
+
+# Note: PAN cannot specify which piece type is being dropped
+# or whether a piece is promoted
 ```
 
-***
+## Limitations and Context Dependency
 
-In the context of a game with several possible actions per turn, like in
-Western chess, more than one action could be consider like a move, and joined
-thanks to the [`portable_move_notation`](https://rubygems.org/gems/portable_move_notation) gem.
+**Important**: PAN is intentionally minimal and rule-agnostic. It has several important limitations:
 
-### Black castles on king-side
+### What PAN Cannot Represent
+
+- **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
+
+### Examples of Ambiguity
 
 ```ruby
-Sashite::PAN.dump([60, 62, "♔"], [63, 61, "♖"]) # => "60,62,♔;63,61,♖"
-Sashite::PAN.parse("60,62,♔;63,61,♖") # => [[60, 62, "♔", nil], [63, 61, "♖", nil]]
+# 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
 ```
 
-### Capturing a white chess pawn en passant
+### 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
-Sashite::PAN.dump([33, 32, "♟"], [32, 40, "♟"]) # => "33,32,♟;32,40,♟"
-Sashite::PAN.parse("33,32,♟;32,40,♟") # => [[33, 32, "♟", nil], [32, 40, "♟", nil]]
+require "sashite-pan"
+
+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
 ```
 
-## License
+## Regular Expression Pattern
+
+PAN strings can be validated using this pattern:
+
+```ruby
+PAN_PATTERN = /\A(\*|[a-z][0-9][-x])([a-z][0-9])\z/
+
+def valid_pan?(string)
+  return false unless string.match?(PAN_PATTERN)
+
+  # Additional validation for source != destination
+  if string.include?('-') || string.include?('x')
+    source = string[0..1]
+    destination = string[-2..-1]
+    return source != destination
+  end
 
-The code is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+  true
+end
+```
+
+## Use Cases
+
+### Optimal for 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
+
+### Consider Alternatives When
+
+- **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
+
+## Integration Considerations
+
+When using PAN in your applications:
+
+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
+
+## 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)
+
+## License
 
-## About Sashite
+The [gem](https://rubygems.org/gems/sashite-pan) is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-This [gem](https://rubygems.org/gems/sashite-pan) is maintained by [Sashite](https://sashite.com/).
+## About Sashité
 
-With some [lines of code](https://github.com/sashite/), let's share the beauty of Chinese, Japanese and Western cultures through the game of chess!
+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/sashite/pan/dumper.rb

@@ -1,35 +1,120 @@
 # frozen_string_literal: true
 
-require_relative "action"
-
 module Sashite
-  module PAN
-    # Dumper class
-    class Dumper < Action
-      def self.call(*actions)
-        actions.map { |action_items| new(*action_items).call }
-               .join(separator)
+  module Pan
+    # Dumper for converting structured move data to PAN strings
+    module Dumper
+      class Error < ::StandardError
       end
 
-      def initialize(src_square, dst_square, piece_name, piece_hand = nil)
-        super()
+      # Convert structured move data to PAN string
+      #
+      # @param move_data [Hash] Move data with type, source, destination
+      # @return [String] PAN string representation
+      # @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)
 
-        @src_square = src_square.nil? ? drop_char : Integer(src_square)
-        @dst_square = Integer(dst_square)
-        @piece_name = piece_name.to_s
-        @piece_hand = piece_hand&.to_s
-      end
+        validate_move_data(move_data)
 
-      def call
-        action_items.join(separator)
+        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
 
-      def action_items
-        return [src_square, dst_square, piece_name] if piece_hand.nil?
+      # Validate the structure of move data
+      #
+      # @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
+
+        unless move_data.key?(:destination)
+          raise Dumper::Error, "Move data must have :destination key"
+        end
+
+        validate_coordinate(move_data[:destination], "destination")
+
+        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 a coordinate follows PAN format
+      #
+      # @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
+
+      # Validate that source and destination are different
+      #
+      # @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
+
+      # Generate PAN string for simple move
+      #
+      # @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
 
-        [src_square, dst_square, piece_name, piece_hand]
+      # 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,29 +1,103 @@
 # frozen_string_literal: true
 
-require_relative "action"
-
 module Sashite
-  module PAN
-    # Parser class
-    class Parser < Action
-      def self.call(serialized_move)
-        serialized_move.split(separator)
-                       .map { |serialized_action| new(serialized_action).call }
+  module Pan
+    # Parser for Portable Action Notation (PAN) strings
+    module Parser
+      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 [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?
+
+        validate_format(pan_string)
+        parse_move(pan_string)
+      end
+
+      private
+
+      # Validate the basic format of a PAN string
+      #
+      # @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
+
+        # 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
 
-      def initialize(serialized_action)
-        super()
+      # Parse the move based on its type
+      #
+      # @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
+          # This should never happen due to earlier validation
+          raise Parser::Error, "Unexpected PAN format: #{pan_string}"
+        end
+      end
+
+      # Parse a simple move (non-capture)
+      #
+      # @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
 
-        action_args = serialized_action.split(separator)
-        src_square  = action_args.fetch(0)
-        @src_square = src_square.eql?(drop_char) ? nil : Integer(src_square)
-        @dst_square = Integer(action_args.fetch(1))
-        @piece_name = action_args.fetch(2)
-        @piece_hand = action_args.fetch(3, nil)
+      # Parse a capture move
+      #
+      # @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
 
-      def call
-        [src_square, dst_square, piece_name, piece_hand]
+      # 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

@@ -1,17 +1,165 @@
 # frozen_string_literal: true
 
+require_relative "pan/dumper"
+require_relative "pan/parser"
+
 module Sashite
   # The PAN (Portable Action Notation) module
-  module PAN
-    def self.dump(*actions)
-      Dumper.call(*actions)
+  module Pan
+    # Main interface for PAN operations
+    module_function
+
+    # Parse a PAN string into structured move data
+    #
+    # @param pan_string [String] The PAN string to parse
+    # @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 structured move data to PAN string
+    #
+    # @param move_data [Hash] Structured move data with type, source, and destination
+    # @return [String] PAN string representation
+    # @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
+    rescue Parser::Error
+      false
+    end
+
+    # Parse a PAN string without raising exceptions
+    #
+    # @param pan_string [String] The PAN string to parse
+    # @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 structured move data to PAN string without raising exceptions
+    #
+    # @param move_data [Hash] Structured move data with type, source, and destination
+    # @return [String, nil] PAN string or nil if invalid
+    # @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
 
-    def self.parse(string)
-      Parser.call(string)
+    # 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
-
-require_relative "pan/dumper"
-require_relative "pan/parser"

data/lib/sashite-pan.rb

@@ -1,6 +1,15 @@
 # frozen_string_literal: true
 
-# Sashite namespace
-module Sashite; end
+# 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,157 +1,20 @@
 --- !ruby/object:Gem::Specification
 name: sashite-pan
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Cyril Kato
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-08-17 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: awesome_print
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: byebug
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-md
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-performance
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-thread_safety
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: yard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-description: A Ruby interface for data serialization in PAN (Portable Action Notation)
-  format.
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+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: []
@@ -161,17 +24,18 @@ files:
 - README.md
 - lib/sashite-pan.rb
 - lib/sashite/pan.rb
-- lib/sashite/pan/action.rb
 - lib/sashite/pan/dumper.rb
 - lib/sashite/pan/parser.rb
-homepage: https://developer.sashite.com/specs/portable-action-notation
+homepage: https://github.com/sashite/pan.rb
 licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/sashite/pan.rb/issues
-  documentation_uri: https://rubydoc.info/gems/sashite-pan/index
+  documentation_uri: https://rubydoc.info/github/sashite/pan.rb/main
+  homepage_uri: https://github.com/sashite/pan.rb
   source_code_uri: https://github.com/sashite/pan.rb
-post_install_message:
+  specification_uri: https://sashite.dev/documents/pan/1.0.0/
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -179,15 +43,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.15
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
-summary: Data serialization in PAN format.
+summary: Compact notation for board game moves - parse chess, shogi, and strategy
+  game actions
 test_files: []

data/lib/sashite/pan/action.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-module Sashite
-  module PAN
-    # Action class
-    class Action
-      attr_reader :src_square, :dst_square, :piece_name, :piece_hand
-
-      private_class_method def self.separator
-        ";"
-      end
-
-      private
-
-      def separator
-        ","
-      end
-
-      def drop_char
-        "*"
-      end
-    end
-  end
-end