sashite-pan 3.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,165 +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 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"}
+    # Check if a string represents a valid PAN action
     #
-    #   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 pan_string [String] the string to validate
+    # @return [Boolean] true if the string is a valid PAN action
     #
-    # @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)
+    #   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
 
-    # Validate a PAN string without raising exceptions
+    # Parse a PAN string into an Action object
     #
-    # @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] PAN notation string
+    # @return [Pan::Action] immutable action instance
+    # @raise [ArgumentError] if the PAN string is invalid
     #
-    # @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
-
-    # 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
+    #   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,15 +1,14 @@
 # frozen_string_literal: true
 
+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
-  # 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"