sashite-pan 2.0.0 → 4.0.0

data/lib/sashite/pan/action/static_capture.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "sashite/cell"
+
+module Sashite
+  module Pan
+    module Action
+      # Static capture action class
+      #
+      # Handles capture actions without movement - removing a piece from the board
+      # without the capturing piece moving.
+      #
+      # Format: +<square>
+      # Examples: "+d4", "+e5"
+      class StaticCapture
+        # Action type
+        TYPE = :static_capture
+
+        # Operator constant
+        OPERATOR = "+"
+
+        # Error messages
+        ERROR_INVALID_STATIC_CAPTURE = "Invalid static capture notation: %s"
+        ERROR_INVALID_SQUARE = "Invalid square coordinate: %s"
+
+        # @return [String] destination CELL coordinate (square where piece is captured)
+        attr_reader :destination
+
+        # Check if a string represents a valid static capture action
+        #
+        # @param pan_string [String] the string to validate
+        # @return [Boolean] true if valid static capture notation
+        #
+        # @example
+        #   StaticCapture.valid?("+d4")       # => true
+        #   StaticCapture.valid?("+e5")       # => true
+        #   StaticCapture.valid?("d4")        # => false
+        def self.valid?(pan_string)
+          return false unless pan_string.is_a?(::String)
+          return false unless pan_string.start_with?(OPERATOR)
+          return false if pan_string.length < 2
+
+          square = pan_string[1..]
+          ::Sashite::Cell.valid?(square)
+        end
+
+        # Parse a static capture notation string into a StaticCapture instance
+        #
+        # @param pan_string [String] static capture notation string
+        # @return [StaticCapture] static capture action instance
+        # @raise [ArgumentError] if the string is not valid static capture notation
+        #
+        # @example
+        #   StaticCapture.parse("+d4")      # => #<StaticCapture destination="d4">
+        def self.parse(pan_string)
+          raise ::ArgumentError, format(ERROR_INVALID_STATIC_CAPTURE, pan_string) unless valid?(pan_string)
+
+          square = pan_string[1..]
+          new(square)
+        end
+
+        # Create a new static capture action instance
+        #
+        # @param square [String] CELL coordinate of piece to capture
+        # @raise [ArgumentError] if coordinate is invalid
+        #
+        # @example
+        #   StaticCapture.new("d4")  # => #<StaticCapture ...>
+        def initialize(square)
+          raise ::ArgumentError, format(ERROR_INVALID_SQUARE, square) unless ::Sashite::Cell.valid?(square)
+
+          @destination = square
+
+          freeze
+        end
+
+        # Get the action type
+        #
+        # @return [Symbol] :static_capture
+        def type
+          TYPE
+        end
+
+        # Get the source coordinate
+        #
+        # @return [nil] static capture actions have no source
+        def source
+          nil
+        end
+
+        # Get the piece identifier
+        #
+        # @return [nil] static capture actions have no piece identifier
+        def piece
+          nil
+        end
+
+        # Get the transformation piece
+        #
+        # @return [nil] static capture actions have no transformation
+        def transformation
+          nil
+        end
+
+        # Convert the action to its PAN string representation
+        #
+        # @return [String] static capture notation
+        #
+        # @example
+        #   action.to_s  # => "+d4"
+        def to_s
+          "#{OPERATOR}#{destination}"
+        end
+
+        # Check if this is a pass action
+        #
+        # @return [Boolean] false
+        def pass?
+          false
+        end
+
+        # Check if this is a move action
+        #
+        # @return [Boolean] false
+        def move?
+          false
+        end
+
+        # Check if this is a capture action
+        #
+        # @return [Boolean] false
+        def capture?
+          false
+        end
+
+        # Check if this is a special action
+        #
+        # @return [Boolean] false
+        def special?
+          false
+        end
+
+        # Check if this is a static capture action
+        #
+        # @return [Boolean] true
+        def static_capture?
+          true
+        end
+
+        # Check if this is a drop action
+        #
+        # @return [Boolean] false
+        def drop?
+          false
+        end
+
+        # Check if this is a drop capture action
+        #
+        # @return [Boolean] false
+        def drop_capture?
+          false
+        end
+
+        # Check if this is a modify action
+        #
+        # @return [Boolean] false
+        def modify?
+          false
+        end
+
+        # Check if this is a movement action
+        #
+        # @return [Boolean] false
+        def movement?
+          false
+        end
+
+        # Check if this is a drop action (drop or drop_capture)
+        #
+        # @return [Boolean] false
+        def drop_action?
+          false
+        end
+
+        # Custom equality comparison
+        #
+        # @param other [Object] object to compare with
+        # @return [Boolean] true if actions are equal
+        def ==(other)
+          return false unless other.is_a?(self.class)
+
+          destination == other.destination
+        end
+
+        # Alias for == to ensure Set functionality works correctly
+        alias eql? ==
+
+        # Custom hash implementation for use in collections
+        #
+        # @return [Integer] hash value
+        def hash
+          [self.class, destination].hash
+        end
+      end
+    end
+  end
+end

data/lib/sashite/pan/action.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require_relative "action/pass"
+require_relative "action/move"
+require_relative "action/capture"
+require_relative "action/special"
+require_relative "action/static_capture"
+require_relative "action/drop"
+require_relative "action/drop_capture"
+require_relative "action/modify"
+
+module Sashite
+  module Pan
+    # Action module
+    #
+    # Orchestrates all action types in PAN (Portable Action Notation) format.
+    # Each action type is implemented as a separate, autonomous class.
+    #
+    # This module provides a unified interface for validation, parsing,
+    # and factory methods that delegate to the appropriate action class.
+    module Action
+      # Error messages
+      ERROR_INVALID_PAN = "Invalid PAN string: %s"
+
+      # Check if a string represents a valid PAN action
+      #
+      # @param pan_string [String] the string to validate
+      # @return [Boolean] true if the string is a valid PAN action
+      #
+      # @example
+      #   Action.valid?("e2-e4")     # => true
+      #   Action.valid?("P*e5")      # => true
+      #   Action.valid?("...")       # => true
+      #   Action.valid?("invalid")   # => false
+      def self.valid?(pan_string)
+        return false unless pan_string.is_a?(::String)
+        return false if pan_string.empty?
+
+        # Try each action type's validation
+        Pass.valid?(pan_string) ||
+          Move.valid?(pan_string) ||
+          Capture.valid?(pan_string) ||
+          Special.valid?(pan_string) ||
+          StaticCapture.valid?(pan_string) ||
+          Drop.valid?(pan_string) ||
+          DropCapture.valid?(pan_string) ||
+          Modify.valid?(pan_string)
+      end
+
+      # Parse a PAN string into an action object
+      #
+      # @param pan_string [String] PAN notation string
+      # @return [Pass, Move, Capture, Special, StaticCapture, Drop, DropCapture, Modify] immutable action instance
+      # @raise [ArgumentError] if the PAN string is invalid
+      #
+      # @example
+      #   Action.parse("e2-e4")      # => #<Move ...>
+      #   Action.parse("d1+f3")      # => #<Capture ...>
+      #   Action.parse("...")        # => #<Pass ...>
+      def self.parse(pan_string)
+        string_value = String(pan_string)
+
+        # Try each action type's parser in order of specificity
+        return Pass.parse(string_value) if Pass.valid?(string_value)
+        return Move.parse(string_value) if Move.valid?(string_value)
+        return Capture.parse(string_value) if Capture.valid?(string_value)
+        return Special.parse(string_value) if Special.valid?(string_value)
+        return StaticCapture.parse(string_value) if StaticCapture.valid?(string_value)
+        return Drop.parse(string_value) if Drop.valid?(string_value)
+        return DropCapture.parse(string_value) if DropCapture.valid?(string_value)
+        return Modify.parse(string_value) if Modify.valid?(string_value)
+
+        raise ::ArgumentError, format(ERROR_INVALID_PAN, string_value)
+      end
+
+      # Create a pass action
+      #
+      # @return [Pass] pass action instance
+      #
+      # @example
+      #   Action.pass  # => #<Pass>
+      def self.pass
+        Pass.instance
+      end
+
+      # Create a move action to an empty square
+      #
+      # @param source [String] source CELL coordinate
+      # @param destination [String] destination CELL coordinate
+      # @param transformation [String, nil] optional EPIN transformation
+      # @return [Move] move action instance
+      #
+      # @example
+      #   Action.move("e2", "e4")                        # => #<Move ...>
+      #   Action.move("e7", "e8", transformation: "Q")   # => #<Move ...>
+      def self.move(source, destination, transformation: nil)
+        Move.new(source, destination, transformation: transformation)
+      end
+
+      # Create a capture action at destination
+      #
+      # @param source [String] source CELL coordinate
+      # @param destination [String] destination CELL coordinate
+      # @param transformation [String, nil] optional EPIN transformation
+      # @return [Capture] capture action instance
+      #
+      # @example
+      #   Action.capture("d1", "f3")                      # => #<Capture ...>
+      #   Action.capture("b7", "a8", transformation: "R") # => #<Capture ...>
+      def self.capture(source, destination, transformation: nil)
+        Capture.new(source, destination, transformation: transformation)
+      end
+
+      # Create a special move action with implicit side effects
+      #
+      # @param source [String] source CELL coordinate
+      # @param destination [String] destination CELL coordinate
+      # @param transformation [String, nil] optional EPIN transformation
+      # @return [Special] special action instance
+      #
+      # @example
+      #   Action.special("e1", "g1")  # => #<Special ...>
+      def self.special(source, destination, transformation: nil)
+        Special.new(source, destination, transformation: transformation)
+      end
+
+      # Create a static capture action (remove piece without movement)
+      #
+      # @param square [String] CELL coordinate of piece to capture
+      # @return [StaticCapture] static capture action instance
+      #
+      # @example
+      #   Action.static_capture("d4")  # => #<StaticCapture ...>
+      def self.static_capture(square)
+        StaticCapture.new(square)
+      end
+
+      # Create a drop action to empty square
+      #
+      # @param destination [String] destination CELL coordinate
+      # @param piece [String, nil] optional EPIN piece identifier
+      # @param transformation [String, nil] optional EPIN transformation
+      # @return [Drop] drop action instance
+      #
+      # @example
+      #   Action.drop("e5", piece: "P")                           # => #<Drop ...>
+      #   Action.drop("d4")                                       # => #<Drop ...>
+      #   Action.drop("c3", piece: "S", transformation: "+S")     # => #<Drop ...>
+      def self.drop(destination, piece: nil, transformation: nil)
+        Drop.new(destination, piece: piece, transformation: transformation)
+      end
+
+      # Create a drop action with capture
+      #
+      # @param destination [String] destination CELL coordinate
+      # @param piece [String, nil] optional EPIN piece identifier
+      # @param transformation [String, nil] optional EPIN transformation
+      # @return [DropCapture] drop capture action instance
+      #
+      # @example
+      #   Action.drop_capture("b4", piece: "L")  # => #<DropCapture ...>
+      def self.drop_capture(destination, piece: nil, transformation: nil)
+        DropCapture.new(destination, piece: piece, transformation: transformation)
+      end
+
+      # Create an in-place transformation action
+      #
+      # @param square [String] CELL coordinate
+      # @param piece [String] EPIN piece identifier (final state)
+      # @return [Modify] modification action instance
+      #
+      # @example
+      #   Action.modify("e4", "+P")   # => #<Modify ...>
+      #   Action.modify("c3", "k'")   # => #<Modify ...>
+      def self.modify(square, piece)
+        Modify.new(square, piece)
+      end
+    end
+  end
+end

data/lib/sashite/pan.rb

@@ -1,61 +1,44 @@
 # frozen_string_literal: true
 
-require_relative "pan/dumper"
-require_relative "pan/parser"
+require_relative "pan/action"
 
 module Sashite
-  # The PAN (Portable Action Notation) module
+  # PAN (Portable Action Notation) implementation for Ruby
+  #
+  # Provides functionality for working with atomic actions in abstract strategy board games
+  # using a human-readable string format with intuitive operator-based syntax.
+  #
+  # This implementation is strictly compliant with PAN Specification v1.0.0
+  # @see https://sashite.dev/specs/pan/1.0.0/ PAN Specification v1.0.0
   module Pan
-    # Main interface for PAN operations
-    module_function
-
-    # Parse a PAN string into PMN format
-    #
-    # @param pan_string [String] The PAN string to parse
-    # @return [Array<Hash>] Array of PMN action objects
-    # @raise [Parser::Error] If the PAN string is invalid
-    def parse(pan_string)
-      Parser.call(pan_string)
-    end
-
-    # Convert PMN actions to PAN string
+    # Check if a string represents a valid PAN action
     #
-    # @param pmn_actions [Array<Hash>] Array of PMN action objects
-    # @return [String] PAN string representation
-    # @raise [Dumper::Error] If the PMN data is invalid
-    def dump(pmn_actions)
-      Dumper.call(pmn_actions)
-    end
-
-    # Validate a PAN string without raising exceptions
+    # @param pan_string [String] the string to validate
+    # @return [Boolean] true if the string is a valid PAN action
     #
-    # @param pan_string [String] The PAN string to validate
-    # @return [Boolean] True if valid, false otherwise
-    def valid?(pan_string)
-      parse(pan_string)
-      true
-    rescue Parser::Error
-      false
+    # @example
+    #   Sashite::Pan.valid?("e2-e4")     # => true
+    #   Sashite::Pan.valid?("d1+f3")     # => true
+    #   Sashite::Pan.valid?("...")       # => true
+    #   Sashite::Pan.valid?("P*e5")      # => true
+    #   Sashite::Pan.valid?("invalid")   # => false
+    def self.valid?(pan_string)
+      Action.valid?(pan_string)
     end
 
-    # Parse a PAN string without raising exceptions
+    # Parse a PAN string into an Action object
     #
-    # @param pan_string [String] The PAN string to parse
-    # @return [Array<Hash>, nil] Array of PMN actions or nil if invalid
-    def safe_parse(pan_string)
-      parse(pan_string)
-    rescue Parser::Error
-      nil
-    end
-
-    # Convert PMN actions to PAN string without raising exceptions
+    # @param pan_string [String] PAN notation string
+    # @return [Pan::Action] immutable action instance
+    # @raise [ArgumentError] if the PAN string is invalid
     #
-    # @param pmn_actions [Array<Hash>] Array of PMN action objects
-    # @return [String, nil] PAN string or nil if invalid
-    def safe_dump(pmn_actions)
-      dump(pmn_actions)
-    rescue Dumper::Error
-      nil
+    # @example
+    #   Sashite::Pan.parse("e2-e4")      # => #<Pan::Action type=:move ...>
+    #   Sashite::Pan.parse("d1+f3")      # => #<Pan::Action type=:capture ...>
+    #   Sashite::Pan.parse("...")        # => #<Pan::Action type=:pass>
+    #   Sashite::Pan.parse("P*e5")       # => #<Pan::Action type=:drop ...>
+    def self.parse(pan_string)
+      Action.parse(pan_string)
     end
   end
 end

data/lib/sashite-pan.rb

@@ -1,7 +1,14 @@
 # frozen_string_literal: true
 
-# Sashité namespace
+require_relative "sashite/pan"
+
+# Sashité namespace for board game notation libraries
+#
+# Sashité provides a collection of libraries for representing and manipulating
+# board game concepts according to the Sashité Protocol specifications.
+#
+# @see https://sashite.dev/protocol/ Sashité Protocol
+# @see https://sashite.dev/specs/ Sashité Specifications
+# @author Sashité
 module Sashite
 end
-
-require_relative "sashite/pan"

metadata

@@ -1,15 +1,46 @@
 --- !ruby/object:Gem::Specification
 name: sashite-pan
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Cyril Kato
 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.
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sashite-cell
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: sashite-epin
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+description: |
+  Parse and generate Portable Action Notation (PAN) strings for representing atomic actions in abstract strategy board games including chess, shogi, xiangqi, and others. PAN provides an intuitive operator-based syntax with six core operators: "-" (move to empty square), "+" (capture), "~" (special moves with side effects), "*" (drop to board), "." (drop with capture), and "=" (in-place transformation), plus "..." (pass turn).
+  Supports coordinates via CELL specification and piece identifiers via EPIN specification. Handles transformations ("e7-e8=Q"), enhanced/diminished states ("+R", "-P"), and style derivation markers ("K'"). Provides comprehensive validation, immutable action objects, and functional API design.
+  Examples: "e2-e4" (move), "d1+f3" (capture), "e1~g1" (castling), "P*e5" (drop), "e7-e8=Q" (promotion), "..." (pass), "+d4" (static capture), "e4=+P" (modify).
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -19,10 +50,15 @@ files:
 - README.md
 - 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
+- lib/sashite/pan/action.rb
+- lib/sashite/pan/action/capture.rb
+- lib/sashite/pan/action/drop.rb
+- lib/sashite/pan/action/drop_capture.rb
+- lib/sashite/pan/action/modify.rb
+- lib/sashite/pan/action/move.rb
+- lib/sashite/pan/action/pass.rb
+- lib/sashite/pan/action/special.rb
+- lib/sashite/pan/action/static_capture.rb
 homepage: https://github.com/sashite/pan.rb
 licenses:
 - MIT
@@ -31,7 +67,7 @@ metadata:
   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
-  specification_uri: https://sashite.dev/documents/pan/1.0.0/
+  specification_uri: https://sashite.dev/specs/pan/1.0.0/
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -47,7 +83,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.1
 specification_version: 4
-summary: Portable Action Notation (PAN) parser and validator for Ruby
+summary: Portable Action Notation (PAN) - operator-based notation for abstract 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/dumper.rb

@@ -1,81 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "dumper/error"
-
-module Sashite
-  module Pan
-    # Dumper for converting PMN format to PAN strings
-    module Dumper
-      # Convert PMN actions to PAN string
-      #
-      # @param pmn_actions [Array<Hash>] Array of PMN action objects
-      # @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)
-
-        pmn_actions.map { |action| dump_action(action) }.join(";")
-      end
-
-      private
-
-      # Convert a single PMN action to PAN format
-      #
-      # @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)
-
-        components = [
-          dump_source_square(action["src_square"]),
-          action["dst_square"],
-          action["piece_name"]
-        ]
-
-        components << action["piece_hand"] if action["piece_hand"]
-
-        components.join(",")
-      end
-
-      # Validate PMN action structure
-      #
-      # @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"]
-      end
-
-      # Convert source square, handling drops
-      #
-      # @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
-      end
-
-      # Validate piece identifier follows PNN specification
-      #
-      # @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
-      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