sashite-epin 2.0.0 → 2.2.0

data/lib/sashite/epin/constants.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Epin
+    # Constants for EPIN (Extended Piece Identifier Notation).
+    #
+    # EPIN extends PIN with a single derivation marker.
+    # PIN constants (VALID_TYPES, VALID_SIDES, VALID_STATES, etc.)
+    # are accessed through the sashite-pin dependency.
+    module Constants
+      # Derivation marker suffix.
+      DERIVATION_SUFFIX = "'"
+    end
+  end
+end

data/lib/sashite/epin/errors/argument/messages.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Epin
+    module Errors
+      class Argument < ::ArgumentError
+        # Centralized error messages for EPIN parsing and validation.
+        #
+        # PIN-related errors (empty input, must contain exactly one letter, etc.)
+        # are propagated from the sashite-pin dependency.
+        #
+        # @example
+        #   raise Errors::Argument, Messages::INVALID_DERIVATION_MARKER
+        module Messages
+          # Parsing error
+          INVALID_DERIVATION_MARKER = "invalid derivation marker"
+
+          # Validation errors (constructor)
+          INVALID_PIN = "pin must be a Sashite::Pin::Identifier"
+          INVALID_DERIVED = "derived must be true or false"
+        end
+      end
+    end
+  end
+end

data/lib/sashite/epin/errors/argument.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "argument/messages"
+
+module Sashite
+  module Epin
+    module Errors
+      # Error raised when EPIN parsing or validation fails.
+      #
+      # @example
+      #   raise Argument, Argument::Messages::INVALID_DERIVATION_MARKER
+      class Argument < ::ArgumentError
+      end
+    end
+  end
+end

data/lib/sashite/epin/errors.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "errors/argument"

data/lib/sashite/epin/identifier.rb

@@ -1,293 +1,200 @@
 # frozen_string_literal: true
 
-require "sashite/pin"
+require_relative "constants"
+require_relative "errors"
 
 module Sashite
   module Epin
-    # Represents an identifier in EPIN (Extended Piece Identifier Notation) format.
+    # Represents a parsed EPIN (Extended Piece Identifier Notation) identifier.
     #
-    # EPIN extends PIN by adding a derivation marker to track piece style in cross-style games.
-    # An EPIN identifier is simply a PIN identifier plus a boolean flag indicating whether
-    # the piece uses its own side's native style (native) or the opponent's style (derived).
+    # An Identifier combines a PIN component with a derivation status:
+    # - PIN: encodes abbr, side, state, and terminal status
+    # - Derived: indicates whether the piece uses native or derived style
     #
-    # ## Pure Composition Design
+    # Instances are immutable (frozen after creation).
     #
-    # EPIN doesn't reimplement PIN features - it's pure composition:
-    # - All piece attributes (name, side, state, terminal) come from the PIN component
-    # - EPIN adds only style derivation tracking (native vs derived)
-    # - Zero code duplication
-    #
-    # ## Minimal API
-    #
-    # Core methods (6 total):
-    # 1. new(pin, derived: false) - create from PIN component
-    # 2. pin - get PIN component
-    # 3. derived? - check derivation status
-    # 4. to_s - serialize
-    # 5. with_pin(new_pin) - replace PIN component
-    # 6. with_derived(boolean) - change derivation status
-    #
-    # Everything else uses the PIN component API directly.
-    #
-    # All instances are immutable - transformation methods return new instances.
-    #
-    # @example Basic usage
-    #   # Create from PIN component
+    # @example Creating identifiers
     #   pin = Sashite::Pin.parse("K^")
-    #   epin = Sashite::Epin::Identifier.new(pin, derived: false)
-    #   epin.to_s           # => "K^" (native)
-    #
-    #   # Mark as derived
-    #   derived = epin.mark_derived
-    #   derived.to_s        # => "K^'" (derived from opponent's style)
+    #   epin = Identifier.new(pin)
+    #   epin = Identifier.new(pin, derived: true)
     #
-    # @example Accessing attributes via PIN component
-    #   epin = Sashite::Epin.parse("+R^'")
-    #   epin.pin.type       # => :R (Piece Name)
-    #   epin.pin.side       # => :first (Piece Side)
-    #   epin.pin.state      # => :enhanced (Piece State)
-    #   epin.pin.terminal?  # => true (Terminal Status)
-    #   epin.derived?       # => true (Piece Style)
+    # @example String conversion
+    #   Identifier.new(pin).to_s                  # => "K^"
+    #   Identifier.new(pin, derived: true).to_s   # => "K^'"
     #
-    # @example Transformations
-    #   epin = Sashite::Epin.parse("K^")
-    #
-    #   # Transform PIN component
-    #   epin.with_pin(epin.pin.with_type(:Q))  # => "Q^"
-    #
-    #   # Transform derivation
-    #   epin.mark_derived                       # => "K^'"
-    #   epin.with_derived(true)                 # => "K^'"
-    #
-    # @see https://sashite.dev/specs/epin/1.0.0/ EPIN Specification v1.0.0
+    # @see https://sashite.dev/specs/epin/1.0.0/
     class Identifier
-      # EPIN validation pattern matching the specification
-      # Grammar: <epin> ::= <pin> | <pin> "'"
-      EPIN_PATTERN = /\A[-+]?[A-Za-z]\^?'?\z/
-
-      # Derivation marker character
-      DERIVATION_MARKER = "'"
-
-      # Error messages
-      ERROR_INVALID_EPIN = "Invalid EPIN string: %s"
-      ERROR_INVALID_PIN = "PIN component must be a Pin::Identifier, got: %s"
-      ERROR_MULTIPLE_MARKERS = "EPIN string cannot have multiple derivation markers: %s"
-
-      # @return [Pin::Identifier] the PIN component
+      # @return [Sashite::Pin::Identifier] PIN component
       attr_reader :pin
 
-      # @return [Boolean] whether the piece uses derived style (opponent's native style)
-      def derived?
-        @derived
-      end
-
-      # Create a new EPIN identifier from PIN component and derivation flag
+      # Creates a new Identifier instance.
       #
-      # @param pin [Pin::Identifier] the PIN component
-      # @param derived [Boolean] whether the piece uses derived style (default: false)
-      # @raise [ArgumentError] if pin is not a Pin::Identifier
+      # @param pin [Sashite::Pin::Identifier] PIN component
+      # @param derived [Boolean] Derived status
+      # @return [Identifier] A new frozen Identifier instance
+      # @raise [Errors::Argument] If any attribute is invalid
       #
-      # @example Create EPIN identifiers
+      # @example
       #   pin = Sashite::Pin.parse("K^")
-      #   native = Sashite::Epin::Identifier.new(pin, derived: false)  # => "K^"
-      #   derived = Sashite::Epin::Identifier.new(pin, derived: true)  # => "K^'"
+      #   Identifier.new(pin)
+      #   Identifier.new(pin, derived: true)
       def initialize(pin, derived: false)
-        raise ::ArgumentError, format(ERROR_INVALID_PIN, pin.class) unless pin.is_a?(Pin::Identifier)
+        validate_pin!(pin)
+        validate_derived!(derived)
 
         @pin = pin
-        @derived = !!derived
+        @derived = derived
 
         freeze
       end
 
-      # Parse an EPIN string into an Identifier object
+      # Returns the derived status.
       #
-      # @param epin_string [String] EPIN notation string
-      # @return [Identifier] new identifier instance
-      # @raise [ArgumentError] if the EPIN string is invalid
+      # @return [Boolean] true if derived style, false otherwise
       #
-      # @example Parse EPIN strings
-      #   Sashite::Epin::Identifier.parse("K^")   # => Native king
-      #   Sashite::Epin::Identifier.parse("K^'")  # => Derived king
-      #   Sashite::Epin::Identifier.parse("+R'")  # => Derived enhanced rook
-      def self.parse(epin_string)
-        string_value = String(epin_string)
-        validate_epin_string(string_value)
-
-        # Check for derivation marker
-        has_marker = string_value.end_with?(DERIVATION_MARKER)
-
-        # Extract PIN part (remove derivation marker if present)
-        pin_part = has_marker ? string_value[0...-1] : string_value
-
-        # Parse PIN component
-        pin_identifier = Pin::Identifier.parse(pin_part)
-
-        new(pin_identifier, derived: has_marker)
+      # @example
+      #   Identifier.new(pin).derived?                  # => false
+      #   Identifier.new(pin, derived: true).derived?   # => true
+      def derived?
+        @derived
       end
 
-      # Check if a string is a valid EPIN notation
+      # Returns the native status.
       #
-      # @param epin_string [String] the string to validate
-      # @return [Boolean] true if valid EPIN, false otherwise
+      # @return [Boolean] true if native style, false otherwise
       #
-      # @example Validate EPIN strings
-      #   Sashite::Epin::Identifier.valid?("K^")     # => true
-      #   Sashite::Epin::Identifier.valid?("K^'")    # => true
-      #   Sashite::Epin::Identifier.valid?("+R'")    # => true
-      #   Sashite::Epin::Identifier.valid?("K^''")   # => false (multiple markers)
-      #   Sashite::Epin::Identifier.valid?("KK'")    # => false (invalid PIN)
-      def self.valid?(epin_string)
-        return false unless epin_string.is_a?(::String)
-        return false unless epin_string.match?(EPIN_PATTERN)
-
-        # Check for multiple derivation markers
-        marker_count = epin_string.count(DERIVATION_MARKER)
-        return false if marker_count > 1
-
-        # Validate PIN part
-        has_marker = epin_string.end_with?(DERIVATION_MARKER)
-        pin_part = has_marker ? epin_string[0...-1] : epin_string
-
-        Pin::Identifier.valid?(pin_part)
+      # @example
+      #   Identifier.new(pin).native?                  # => true
+      #   Identifier.new(pin, derived: true).native?   # => false
+      def native?
+        !@derived
       end
 
-      # Convert the identifier to its EPIN string representation
+      # ========================================================================
+      # String Conversion
+      # ========================================================================
+
+      # Returns the EPIN string representation.
       #
-      # @return [String] EPIN notation string
+      # @return [String] The EPIN string
       #
-      # @example Serialize identifiers
-      #   native.to_s   # => "K^"
-      #   derived.to_s  # => "K^'"
+      # @example
+      #   Identifier.new(pin).to_s                  # => "K^"
+      #   Identifier.new(pin, derived: true).to_s   # => "K^'"
       def to_s
-        pin.to_s + suffix
+        derived? ? "#{pin}#{Constants::DERIVATION_SUFFIX}" : pin.to_s
       end
 
-      # Get the derivation marker suffix
-      #
-      # @return [String] derivation marker if derived, empty string if native
-      def suffix
-        derived? ? DERIVATION_MARKER : ""
-      end
+      # ========================================================================
+      # Transformations
+      # ========================================================================
 
-      # Create a new identifier with a different PIN component
+      # Returns a new Identifier with a different PIN component.
       #
-      # @param new_pin [Pin::Identifier] new PIN component
-      # @return [Identifier] new identifier with different PIN
-      # @raise [ArgumentError] if new_pin is not a Pin::Identifier
+      # @param new_pin [Sashite::Pin::Identifier] The new PIN component
+      # @return [Identifier] A new Identifier with the specified PIN
+      # @raise [Errors::Argument] If the PIN is invalid
       #
-      # @example Replace PIN component
-      #   epin = Sashite::Epin.parse("K^'")
-      #   new_pin = epin.pin.with_type(:Q)
-      #   epin.with_pin(new_pin).to_s  # => "Q^'"
+      # @example
+      #   epin = Identifier.new(pin, derived: true)
+      #   new_pin = Sashite::Pin.parse("+Q^")
+      #   epin.with_pin(new_pin).to_s  # => "+Q^'"
       def with_pin(new_pin)
-        raise ::ArgumentError, format(ERROR_INVALID_PIN, new_pin.class) unless new_pin.is_a?(Pin::Identifier)
         return self if pin == new_pin
 
-        self.class.new(new_pin, derived: derived?)
-      end
-
-      # Create a new identifier with different derivation status
-      #
-      # @param new_derived [Boolean] new derivation status
-      # @return [Identifier] new identifier with different derivation
-      #
-      # @example Change derivation status
-      #   native = Sashite::Epin.parse("K^")
-      #   derived = native.with_derived(true)
-      #   derived.to_s  # => "K^'"
-      def with_derived(new_derived)
-        new_derived_bool = !!new_derived
-        return self if derived? == new_derived_bool
-
-        self.class.new(pin, derived: new_derived_bool)
+        self.class.new(new_pin, derived: @derived)
       end
 
-      # Create a new identifier marked as derived (opponent's native style)
+      # Returns a new Identifier marked as derived.
       #
-      # @return [Identifier] new identifier marked as derived
+      # @return [Identifier] A new Identifier with derived: true
       #
-      # @example Mark as derived
-      #   native = Sashite::Epin.parse("K^")
-      #   derived = native.mark_derived
-      #   derived.to_s  # => "K^'"
-      def mark_derived
+      # @example
+      #   epin = Identifier.new(pin)
+      #   epin.derive.to_s  # => "K^'"
+      def derive
         return self if derived?
 
         self.class.new(pin, derived: true)
       end
 
-      # Create a new identifier marked as native (own side's native style)
+      # Returns a new Identifier marked as native.
       #
-      # @return [Identifier] new identifier marked as native
+      # @return [Identifier] A new Identifier with derived: false
       #
-      # @example Mark as native
-      #   derived = Sashite::Epin.parse("K^'")
-      #   native = derived.unmark_native
-      #   native.to_s  # => "K^"
-      def unmark_native
-        return self unless derived?
+      # @example
+      #   epin = Identifier.new(pin, derived: true)
+      #   epin.native.to_s  # => "K^"
+      def native
+        return self if native?
 
         self.class.new(pin, derived: false)
       end
 
-      # Check if the identifier uses native style (own side's native style)
-      #
-      # @return [Boolean] true if native (not derived)
-      def native?
-        !derived?
-      end
+      # ========================================================================
+      # Comparison Queries
+      # ========================================================================
 
-      # Check if this identifier has the same derivation status as another
+      # Checks if two Identifiers have the same derived status.
       #
-      # @param other [Identifier] identifier to compare with
-      # @return [Boolean] true if same derivation status
+      # @param other [Identifier] The other Identifier to compare
+      # @return [Boolean] true if same derived status
       #
-      # @example Compare derivation status
-      #   native = Sashite::Epin.parse("K^")
-      #   derived = Sashite::Epin.parse("K^'")
-      #   native.same_derivation?(derived)  # => false
-      def same_derivation?(other)
-        return false unless other.is_a?(self.class)
-
-        derived? == other.derived?
+      # @example
+      #   epin1 = Identifier.new(pin1, derived: true)
+      #   epin2 = Identifier.new(pin2, derived: true)
+      #   epin1.same_derived?(epin2)  # => true
+      def same_derived?(other)
+        @derived == other.derived?
       end
 
-      # Custom equality comparison
+      # ========================================================================
+      # Equality
+      # ========================================================================
+
+      # Checks equality with another Identifier.
       #
-      # @param other [Object] object to compare with
-      # @return [Boolean] true if identifiers are equal
+      # @param other [Object] The object to compare
+      # @return [Boolean] true if equal
       def ==(other)
-        return false unless other.is_a?(self.class)
+        return false unless self.class === other
 
-        pin == other.pin && derived? == other.derived?
+        pin == other.pin && @derived == other.derived?
       end
 
-      # Alias for == to ensure Set functionality works correctly
       alias eql? ==
 
-      # Custom hash implementation for use in collections
+      # Returns a hash code for the Identifier.
       #
-      # @return [Integer] hash value
+      # @return [Integer] Hash code
       def hash
-        [self.class, pin, derived?].hash
+        [pin, @derived].hash
       end
 
-      # Validate EPIN string format
+      # Returns an inspect string for the Identifier.
       #
-      # @param string [String] string to validate
-      # @raise [ArgumentError] if string doesn't match EPIN pattern or has multiple markers
-      def self.validate_epin_string(string)
-        raise ::ArgumentError, format(ERROR_INVALID_EPIN, string) unless string.match?(EPIN_PATTERN)
+      # @return [String] Inspect representation
+      def inspect
+        "#<#{self.class} #{self}>"
+      end
+
+      private
+
+      # ========================================================================
+      # Private Validation
+      # ========================================================================
 
-        # Check for multiple derivation markers
-        marker_count = string.count(DERIVATION_MARKER)
-        return unless marker_count > 1
+      def validate_pin!(pin)
+        return if ::Sashite::Pin::Identifier === pin
 
-        raise ::ArgumentError, format(ERROR_MULTIPLE_MARKERS, string)
+        raise Errors::Argument, Errors::Argument::Messages::INVALID_PIN
       end
 
-      private_class_method :validate_epin_string
+      def validate_derived!(derived)
+        return if ::TrueClass === derived || ::FalseClass === derived
+
+        raise Errors::Argument, Errors::Argument::Messages::INVALID_DERIVED
+      end
     end
   end
 end

data/lib/sashite/epin/parser.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+require_relative "errors"
+
+module Sashite
+  module Epin
+    # Parser for EPIN (Extended Piece Identifier Notation) strings.
+    #
+    # This parser extracts the derivation marker and delegates PIN parsing
+    # to the sashite-pin library.
+    #
+    # @example
+    #   Parser.parse("K")    # => { pin: { abbr: :K, side: :first, ... }, derived: false }
+    #   Parser.parse("K^'")  # => { pin: { abbr: :K, side: :first, ..., terminal: true }, derived: true }
+    #
+    # @see https://sashite.dev/specs/epin/1.0.0/
+    module Parser
+      # Parses an EPIN string into its components.
+      #
+      # @param input [String] The EPIN string to parse
+      # @return [Hash] A hash with :pin (PIN components hash) and :derived keys
+      # @raise [Errors::Argument] If the input is not a valid EPIN string
+      def self.parse(input)
+        validate_string!(input)
+
+        derived = has_derivation_marker?(input)
+
+        if derived
+          validate_derivation_marker!(input)
+          pin_string = input.chop
+        else
+          pin_string = input
+        end
+
+        pin_components = parse_pin_component(pin_string)
+
+        { pin: pin_components, derived: derived }
+      end
+
+      # Validates an EPIN string without raising an exception.
+      #
+      # @param input [String] The EPIN string to validate
+      # @return [Boolean] true if valid, false otherwise
+      def self.valid?(input)
+        return false unless ::String === input
+
+        parse(input)
+        true
+      rescue Errors::Argument
+        false
+      end
+
+      class << self
+        private
+
+        # Validates that input is a String.
+        #
+        # @param input [Object] The input to validate
+        # @raise [Errors::Argument] If input is not a String
+        def validate_string!(input)
+          return if ::String === input
+
+          raise Errors::Argument, "invalid PIN component: must contain exactly one letter"
+        end
+
+        # Checks if the input contains a derivation marker.
+        #
+        # @param input [String] The input to check
+        # @return [Boolean] true if contains derivation marker
+        def has_derivation_marker?(input)
+          input.include?(Constants::DERIVATION_SUFFIX)
+        end
+
+        # Validates derivation marker position and uniqueness.
+        #
+        # @param input [String] The input to validate
+        # @raise [Errors::Argument] If derivation marker is invalid
+        def validate_derivation_marker!(input)
+          count = input.count(Constants::DERIVATION_SUFFIX)
+          last_char = input[-1]
+
+          return if count == 1 && last_char == Constants::DERIVATION_SUFFIX
+
+          raise Errors::Argument, Errors::Argument::Messages::INVALID_DERIVATION_MARKER
+        end
+
+        # Parses the PIN component using sashite-pin.
+        #
+        # @param pin_string [String] The PIN string to parse
+        # @return [Hash] PIN components hash
+        # @raise [Errors::Argument] If PIN parsing fails
+        def parse_pin_component(pin_string)
+          ::Sashite::Pin::Parser.parse(pin_string)
+        rescue ::Sashite::Pin::Errors::Argument => e
+          raise Errors::Argument, "invalid PIN component: #{e.message}"
+        end
+      end
+    end
+  end
+end