sashite-epin 2.1.0 → 2.2.0

data/lib/sashite/epin/identifier.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+require_relative "errors"
+
+module Sashite
+  module Epin
+    # Represents a parsed EPIN (Extended Piece Identifier Notation) identifier.
+    #
+    # 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
+    #
+    # Instances are immutable (frozen after creation).
+    #
+    # @example Creating identifiers
+    #   pin = Sashite::Pin.parse("K^")
+    #   epin = Identifier.new(pin)
+    #   epin = Identifier.new(pin, derived: true)
+    #
+    # @example String conversion
+    #   Identifier.new(pin).to_s                  # => "K^"
+    #   Identifier.new(pin, derived: true).to_s   # => "K^'"
+    #
+    # @see https://sashite.dev/specs/epin/1.0.0/
+    class Identifier
+      # @return [Sashite::Pin::Identifier] PIN component
+      attr_reader :pin
+
+      # Creates a new Identifier instance.
+      #
+      # @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
+      #   pin = Sashite::Pin.parse("K^")
+      #   Identifier.new(pin)
+      #   Identifier.new(pin, derived: true)
+      def initialize(pin, derived: false)
+        validate_pin!(pin)
+        validate_derived!(derived)
+
+        @pin = pin
+        @derived = derived
+
+        freeze
+      end
+
+      # Returns the derived status.
+      #
+      # @return [Boolean] true if derived style, false otherwise
+      #
+      # @example
+      #   Identifier.new(pin).derived?                  # => false
+      #   Identifier.new(pin, derived: true).derived?   # => true
+      def derived?
+        @derived
+      end
+
+      # Returns the native status.
+      #
+      # @return [Boolean] true if native style, false otherwise
+      #
+      # @example
+      #   Identifier.new(pin).native?                  # => true
+      #   Identifier.new(pin, derived: true).native?   # => false
+      def native?
+        !@derived
+      end
+
+      # ========================================================================
+      # String Conversion
+      # ========================================================================
+
+      # Returns the EPIN string representation.
+      #
+      # @return [String] The EPIN string
+      #
+      # @example
+      #   Identifier.new(pin).to_s                  # => "K^"
+      #   Identifier.new(pin, derived: true).to_s   # => "K^'"
+      def to_s
+        derived? ? "#{pin}#{Constants::DERIVATION_SUFFIX}" : pin.to_s
+      end
+
+      # ========================================================================
+      # Transformations
+      # ========================================================================
+
+      # Returns a new Identifier with a different PIN component.
+      #
+      # @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
+      #   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)
+        return self if pin == new_pin
+
+        self.class.new(new_pin, derived: @derived)
+      end
+
+      # Returns a new Identifier marked as derived.
+      #
+      # @return [Identifier] A new Identifier with derived: true
+      #
+      # @example
+      #   epin = Identifier.new(pin)
+      #   epin.derive.to_s  # => "K^'"
+      def derive
+        return self if derived?
+
+        self.class.new(pin, derived: true)
+      end
+
+      # Returns a new Identifier marked as native.
+      #
+      # @return [Identifier] A new Identifier with derived: false
+      #
+      # @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
+
+      # ========================================================================
+      # Comparison Queries
+      # ========================================================================
+
+      # Checks if two Identifiers have the same derived status.
+      #
+      # @param other [Identifier] The other Identifier to compare
+      # @return [Boolean] true if same derived status
+      #
+      # @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
+
+      # ========================================================================
+      # Equality
+      # ========================================================================
+
+      # Checks equality with another Identifier.
+      #
+      # @param other [Object] The object to compare
+      # @return [Boolean] true if equal
+      def ==(other)
+        return false unless self.class === other
+
+        pin == other.pin && @derived == other.derived?
+      end
+
+      alias eql? ==
+
+      # Returns a hash code for the Identifier.
+      #
+      # @return [Integer] Hash code
+      def hash
+        [pin, @derived].hash
+      end
+
+      # Returns an inspect string for the Identifier.
+      #
+      # @return [String] Inspect representation
+      def inspect
+        "#<#{self.class} #{self}>"
+      end
+
+      private
+
+      # ========================================================================
+      # Private Validation
+      # ========================================================================
+
+      def validate_pin!(pin)
+        return if ::Sashite::Pin::Identifier === pin
+
+        raise Errors::Argument, Errors::Argument::Messages::INVALID_PIN
+      end
+
+      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

data/lib/sashite/epin.rb

@@ -2,300 +2,79 @@
 
 require "sashite/pin"
 
+require_relative "epin/constants"
+require_relative "epin/errors"
+require_relative "epin/identifier"
+require_relative "epin/parser"
+
 module Sashite
   # EPIN (Extended Piece Identifier Notation) implementation for Ruby.
   #
-  # EPIN extends PIN by adding a **derivation marker** to track piece style
-  # in cross-style games.
-  #
-  # **EPIN is simply: PIN + optional style derivation marker (`'`)**
+  # EPIN extends PIN with an optional derivation marker (') that flags
+  # whether a piece uses a native or derived style.
   #
   # == Format
   #
-  #   <pin-token>[<derivation-marker>]
-  #
-  # Where +<pin-token>+ is a valid PIN token and +<derivation-marker>+ is
-  # an optional trailing apostrophe (<tt>'</tt>).
+  #   <pin>[']
   #
-  # == Five Fundamental Attributes
-  #
-  # EPIN exposes all five attributes from the Sashité Game Protocol:
-  #
-  # - *Piece Name* â†' +epin.pin.type+
-  # - *Piece Side* â†' +epin.pin.side+
-  # - *Piece State* â†' +epin.pin.state+
-  # - *Terminal Status* â†' +epin.pin.terminal+
-  # - *Piece Style* â†' +epin.derived+ (native vs derived)
+  # - *PIN*: Any valid PIN token (abbr, side, state, terminal)
+  # - *Derivation marker*: <tt>'</tt> (derived) or absent (native)
   #
   # == Examples
   #
   #   epin = Sashite::Epin.parse("K^'")
-  #   epin.pin.type      # => :K
-  #   epin.pin.terminal  # => true
-  #   epin.derived       # => true
+  #   epin.pin.abbr      # => :K
+  #   epin.pin.side      # => :first
+  #   epin.pin.terminal? # => true
+  #   epin.derived?      # => true
   #
-  #   pin = Sashite::Pin.parse("K^")
-  #   epin = Sashite::Epin.new(pin, derived: true)
-  #   epin.to_s  # => "K^'"
+  #   epin = Sashite::Epin.parse("+R")
+  #   epin.to_s  # => "+R"
   #
-  #   Sashite::Epin.valid?("K^'")   # => true
-  #   Sashite::Epin.valid?("K'^")   # => false
+  #   Sashite::Epin.valid?("K^'")     # => true
+  #   Sashite::Epin.valid?("invalid") # => false
   #
-  # See the EPIN Specification (https://sashite.dev/specs/epin/1.0.0/) for details.
-  class Epin
-    # Pattern for validating EPIN strings
-    EPIN_PATTERN = /\A(?<pin>[-+]?[A-Za-z]\^?)(?<derived>')?\z/
-
-    # @return [Sashite::Pin] The underlying PIN component
-    attr_reader :pin
-
-    # @return [Boolean] Derivation status (true = derived, false = native)
-    attr_reader :derived
-
-    # ========================================================================
-    # Creation and Parsing
-    # ========================================================================
-
-    # Creates a new EPIN instance from a PIN component.
+  # @see https://sashite.dev/specs/epin/1.0.0/
+  module Epin
+    # Parses an EPIN string into an Identifier.
     #
-    # @param pin [Sashite::Pin] The underlying PIN instance
-    # @param derived [Boolean] Derivation status (default: false)
-    # @return [Epin] A new frozen Epin instance
-    #
-    # @example
-    #   pin = Sashite::Pin.parse("K^")
-    #   Sashite::Epin.new(pin)
-    #   # => #<Sashite::Epin K^>
-    #
-    #   Sashite::Epin.new(pin, derived: true)
-    #   # => #<Sashite::Epin K^'>
-    def initialize(pin, derived: false)
-      raise ArgumentError, "Expected a Sashite::Pin instance, got: #{pin.inspect}" unless pin.is_a?(Pin)
-
-      @pin = pin
-      @derived = !!derived
-
-      freeze
-    end
-
-    # Parses an EPIN string into an Epin instance.
-    #
-    # @param epin_string [String] The EPIN string to parse
-    # @return [Epin] A new Epin instance
-    # @raise [ArgumentError] If the string is not a valid EPIN
+    # @param string [String] The EPIN string to parse
+    # @return [Identifier] A new Identifier instance
+    # @raise [Errors::Argument] If the string is not a valid EPIN
     #
     # @example
     #   Sashite::Epin.parse("K")
-    #   # => #<Sashite::Epin K>
-    #
-    #   Sashite::Epin.parse("K'")
-    #   # => #<Sashite::Epin K'>
+    #   # => #<Sashite::Epin::Identifier K>
     #
-    #   Sashite::Epin.parse("+R^'")
-    #   # => #<Sashite::Epin +R^'>
+    #   Sashite::Epin.parse("K^'")
+    #   # => #<Sashite::Epin::Identifier K^'>
     #
     #   Sashite::Epin.parse("invalid")
-    #   # => ArgumentError: Invalid EPIN string: invalid
-    def self.parse(epin_string)
-      raise ArgumentError, "Invalid EPIN string: #{epin_string.inspect}" unless epin_string.is_a?(String)
-
-      match = EPIN_PATTERN.match(epin_string)
-      raise ArgumentError, "Invalid EPIN string: #{epin_string}" unless match
-
-      pin_string = match[:pin]
-      derived_marker = match[:derived]
-
-      pin = Pin.parse(pin_string)
-      derived = derived_marker == "'"
-
-      new(pin, derived: derived)
+    #   # => raises Errors::Argument
+    def self.parse(string)
+      components = Parser.parse(string)
+
+      pin = ::Sashite::Pin::Identifier.new(
+        components[:pin][:abbr],
+        components[:pin][:side],
+        components[:pin][:state],
+        terminal: components[:pin][:terminal]
+      )
+
+      Identifier.new(pin, derived: components[:derived])
     end
 
     # Checks if a string is a valid EPIN notation.
     #
-    # @param epin_string [String] The string to validate
+    # @param string [String] The string to validate
     # @return [Boolean] true if valid, false otherwise
     #
     # @example
-    #   Sashite::Epin.valid?("K")      # => true
-    #   Sashite::Epin.valid?("K'")     # => true
-    #   Sashite::Epin.valid?("+R^'")   # => true
-    #   Sashite::Epin.valid?("K'^")    # => false
-    #   Sashite::Epin.valid?("K''")    # => false
-    #   Sashite::Epin.valid?("invalid") # => false
-    def self.valid?(epin_string)
-      return false unless epin_string.is_a?(String)
-
-      EPIN_PATTERN.match?(epin_string)
-    end
-
-    # ========================================================================
-    # Conversion
-    # ========================================================================
-
-    # Converts the Epin to its string representation.
-    #
-    # @return [String] The EPIN string
-    #
-    # @example
-    #   pin = Sashite::Pin.parse("K^")
-    #   Sashite::Epin.new(pin).to_s
-    #   # => "K^"
-    #
-    #   Sashite::Epin.new(pin, derived: true).to_s
-    #   # => "K^'"
-    def to_s
-      "#{pin}#{derivation_suffix}"
-    end
-
-    # ========================================================================
-    # Transformations
-    # ========================================================================
-
-    # Returns a new Epin with a different PIN component.
-    #
-    # @param new_pin [Sashite::Pin] The new PIN component
-    # @return [Epin] A new Epin with the specified PIN
-    #
-    # @example
-    #   epin = Sashite::Epin.parse("K^'")
-    #   new_pin = epin.pin.with_type(:Q)
-    #   epin.with_pin(new_pin).to_s
-    #   # => "Q^'"
-    def with_pin(new_pin)
-      return self if pin == new_pin
-
-      self.class.new(new_pin, derived: derived)
-    end
-
-    # Returns a new Epin with a different derivation status.
-    #
-    # @param new_derived [Boolean] The new derivation status
-    # @return [Epin] A new Epin with the specified derivation status
-    #
-    # @example
-    #   epin = Sashite::Epin.parse("K^")
-    #   epin.with_derived(true).to_s
-    #   # => "K^'"
-    #
-    #   epin = Sashite::Epin.parse("K^'")
-    #   epin.with_derived(false).to_s
-    #   # => "K^"
-    def with_derived(new_derived)
-      return self if derived == !!new_derived
-
-      self.class.new(pin, derived: !!new_derived)
-    end
-
-    # Returns a new Epin marked as derived.
-    #
-    # @return [Epin] A new Epin with derived: true
-    #
-    # @example
-    #   epin = Sashite::Epin.parse("K^")
-    #   epin.mark_derived.derived
-    #   # => true
-    def mark_derived
-      return self if derived
-
-      self.class.new(pin, derived: true)
-    end
-
-    # Returns a new Epin marked as native (not derived).
-    #
-    # @return [Epin] A new Epin with derived: false
-    #
-    # @example
-    #   epin = Sashite::Epin.parse("K^'")
-    #   epin.unmark_derived.derived
-    #   # => false
-    def unmark_derived
-      return self unless derived
-
-      self.class.new(pin, derived: false)
-    end
-
-    # ========================================================================
-    # Queries
-    # ========================================================================
-
-    # Checks if the Epin is derived (uses opponent's style).
-    #
-    # @return [Boolean] true if derived
-    #
-    # @example
-    #   Sashite::Epin.parse("K^'").derived?  # => true
-    #   Sashite::Epin.parse("K^").derived?   # => false
-    def derived?
-      derived
-    end
-
-    # Checks if the Epin is native (uses own side's style).
-    #
-    # @return [Boolean] true if native
-    #
-    # @example
-    #   Sashite::Epin.parse("K^").native?   # => true
-    #   Sashite::Epin.parse("K^'").native?  # => false
-    def native?
-      !derived
-    end
-
-    # Checks if two Epins have the same derivation status.
-    #
-    # @param other [Epin] The other Epin to compare
-    # @return [Boolean] true if same derivation status
-    #
-    # @example
-    #   epin1 = Sashite::Epin.parse("K^'")
-    #   epin2 = Sashite::Epin.parse("Q'")
-    #   epin1.same_derived?(epin2)
-    #   # => true
-    #
-    #   epin3 = Sashite::Epin.parse("K^")
-    #   epin1.same_derived?(epin3)
-    #   # => false
-    def same_derived?(other)
-      derived == other.derived
-    end
-
-    # ========================================================================
-    # Comparison
-    # ========================================================================
-
-    # Checks equality with another Epin.
-    #
-    # @param other [Object] The object to compare
-    # @return [Boolean] true if equal
-    def ==(other)
-      return false unless other.is_a?(self.class)
-
-      pin == other.pin && derived == other.derived
-    end
-
-    alias eql? ==
-
-    # Returns a hash code for the Epin.
-    #
-    # @return [Integer] Hash code
-    def hash
-      [pin, derived].hash
-    end
-
-    # Returns an inspect string for the Epin.
-    #
-    # @return [String] Inspect representation
-    def inspect
-      "#<#{self.class} #{self}>"
-    end
-
-    private
-
-    # Returns the derivation suffix for string representation.
-    #
-    # @return [String] "'" if derived, "" otherwise
-    def derivation_suffix
-      derived ? "'" : ""
+    #   Sashite::Epin.valid?("K")        # => true
+    #   Sashite::Epin.valid?("K^'")      # => true
+    #   Sashite::Epin.valid?("invalid")  # => false
+    def self.valid?(string)
+      Parser.valid?(string)
     end
   end
 end

data/lib/sashite-epin.rb

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