sashite-epin 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b308beb3213522cf87199c0b28e1abe7a9d767260ac6ec3ee5f9581ae1ef1bdb
-  data.tar.gz: 3c965f92446dbcf1965844e7454c3bdf1152e2c3e7a74953e974e1239ae6137a
+  metadata.gz: 43dd91dce36507e42cf07b57202cff4d323fb889fde7d8daf62498b8bf588f04
+  data.tar.gz: b4237ab78e18f3e879893fd934f438aa3729d60508dbf8c5378727b84b2a9b7c
 SHA512:
-  metadata.gz: 99a9d2ec0c5834a886517746e7d50206dbb1f331043133df7f1e919a47f506d71a7d5f58798680b3d005640983ab8c22ad7e892b57a0b7df04c8a6401ee28512
-  data.tar.gz: 56d10546fb4068fc8e3ccdaf5f36de9d947b7f7cb2c3cc3a4fd8c9a9c01acfeb7258de0a833a85ddd64d4f889a49e274b045a07d73892e06d774812f0d849729
+  metadata.gz: 75122035fe9b0a3a0d4bda91518761b57a12a1551eb7743b27e31775c5007df75da1bd470f8b0cd69037d33bfafbc2c3c1773f7f7eb52fc083e6928989266c76
+  data.tar.gz: '087da6655e1528df88d86b276eff52fb1ae71e4d3b83295b105135b4ba22f5d8c75f2675fac9f3cbc61dcb94aeda9ab7c6de274dc4a8e614ca9549d4583df002'

data/lib/sashite/epin/identifier.rb

@@ -6,37 +6,44 @@ module Sashite
   module Epin
     # Represents an identifier in EPIN (Extended Piece Identifier Notation) format.
     #
-    # An identifier consists of a PIN component with an optional derivation marker:
-    # - PIN component: [<state>]<letter> (from PIN specification)
-    # - Derivation marker: "'" (foreign style) or none (native style)
+    # EPIN extends PIN by adding a derivation marker to encode Piece Style relative to Piece Side.
     #
-    # The case of the letter determines ownership:
-    # - Uppercase (A-Z): first player
-    # - Lowercase (a-z): second player
+    # Format: [<state>]<letter>[<terminal>][<derivation>]
+    # - State modifier: "+" (enhanced), "-" (diminished), or none (normal)
+    # - Letter: A-Z (first player), a-z (second player)
+    # - Terminal marker: "^" (terminal piece)
+    # - Derivation marker: "'" (foreign/derived style) or none (native style)
     #
-    # Style derivation logic:
-    # - No suffix: piece has the native style of its current side
+    # Style Derivation Logic:
+    # - No apostrophe suffix: piece has the native style of its current side
     # - Apostrophe suffix: piece has the foreign style (opposite side's native style)
     #
-    # All instances are immutable - state manipulation methods return new instances.
+    # All instances are immutable - transformations return new instances.
     # This extends the Game Protocol's piece model with Style support through derivation.
+    #
+    # @see https://sashite.dev/specs/epin/1.0.0/
     class Identifier
-      # Valid derivation suffixes
-      DERIVATION_SUFFIX = "'"
-      NATIVE_SUFFIX = ""
+      # EPIN validation pattern matching the specification: /\A[-+]?[A-Za-z]\^?'?\z/
+      EPIN_PATTERN = /\A[-+]?[A-Za-z]\^?'?\z/
+
+      # Derivation marker for foreign/derived style
+      DERIVATION_MARKER = "'"
+
+      # No derivation marker (native style)
+      NATIVE_MARKER = ""
 
-      # Derivation constants
+      # Style constants
       NATIVE = true
       FOREIGN = false
 
-      # Valid derivations
+      # Valid derivation values
       VALID_DERIVATIONS = [NATIVE, FOREIGN].freeze
 
       # Error messages
       ERROR_INVALID_EPIN = "Invalid EPIN string: %s"
       ERROR_INVALID_DERIVATION = "Derivation must be true (native) or false (foreign), got: %s"
 
-      # @return [Symbol] the piece type (:A to :Z)
+      # @return [Symbol] the piece type (:A to :Z, always uppercase)
       def type
         @pin_identifier.type
       end
@@ -51,27 +58,36 @@ module Sashite
         @pin_identifier.state
       end
 
+      # @return [Boolean] whether the piece is a terminal piece
+      def terminal
+        @pin_identifier.terminal
+      end
+
       # @return [Boolean] the style derivation (true for native, false for foreign)
       attr_reader :native
 
-      # Create a new identifier instance
+      # Create a new EPIN identifier instance
       #
       # @param type [Symbol] piece type (:A to :Z)
       # @param side [Symbol] player side (:first or :second)
       # @param state [Symbol] piece state (:normal, :enhanced, or :diminished)
       # @param native [Boolean] style derivation (true for native, false for foreign)
+      # @param terminal [Boolean] whether the piece is a terminal piece
       # @raise [ArgumentError] if parameters are invalid
+      #
       # @example
-      #   Identifier.new(:K, :first, :normal, true)
-      #   Identifier.new(:P, :second, :enhanced, false)
-      def initialize(type, side, state = Pin::Identifier::NORMAL_STATE, native = NATIVE)
+      #   Identifier.new(:K, :first, :normal, true)           # => "K"
+      #   Identifier.new(:K, :first, :normal, true, terminal: true)  # => "K^"
+      #   Identifier.new(:K, :first, :normal, false, terminal: true) # => "K^'"
+      #   Identifier.new(:P, :second, :enhanced, false)       # => "+p'"
+      def initialize(type, side, state = Pin::Identifier::NORMAL_STATE, native = NATIVE, terminal: false)
         # Validate using PIN class methods for type, side, and state
         Pin::Identifier.validate_type(type)
         Pin::Identifier.validate_side(side)
         Pin::Identifier.validate_state(state)
         self.class.validate_derivation(native)
 
-        @pin_identifier = Pin::Identifier.new(type, side, state)
+        @pin_identifier = Pin::Identifier.new(type, side, state, terminal: terminal)
         @native = native
 
         freeze
@@ -79,56 +95,72 @@ module Sashite
 
       # Parse an EPIN string into an Identifier object
       #
+      # EPIN format: [<state>]<letter>[<terminal>][<derivation>]
+      # where terminal marker (^) comes BEFORE derivation marker (')
+      #
       # @param epin_string [String] EPIN notation string
       # @return [Identifier] new identifier instance
       # @raise [ArgumentError] if the EPIN string is invalid
+      #
       # @example
-      #   Epin::Identifier.parse("k")     # => #<Epin::Identifier type=:K side=:second state=:normal native=true>
-      #   Epin::Identifier.parse("+R'")   # => #<Epin::Identifier type=:R side=:first state=:enhanced native=false>
-      #   Epin::Identifier.parse("-p")    # => #<Epin::Identifier type=:P side=:second state=:diminished native=true>
+      #   Epin::Identifier.parse("k")       # => native second player king
+      #   Epin::Identifier.parse("K^")      # => native terminal first player king
+      #   Epin::Identifier.parse("+R'")     # => foreign enhanced first player rook
+      #   Epin::Identifier.parse("+K^'")    # => foreign enhanced terminal first player king
+      #   Epin::Identifier.parse("-p")      # => native diminished second player pawn
       def self.parse(epin_string)
         string_value = String(epin_string)
 
-        # Check for derivation suffix
-        if string_value.end_with?(DERIVATION_SUFFIX)
+        # Validate EPIN pattern first
+        raise ::ArgumentError, format(ERROR_INVALID_EPIN, string_value) unless string_value.match?(EPIN_PATTERN)
+
+        # Check for derivation marker (must be at the end)
+        if string_value.end_with?(DERIVATION_MARKER)
           pin_part = string_value[0...-1] # Remove the apostrophe
-          foreign = true
+          derived = true
         else
           pin_part = string_value
-          foreign = false
+          derived = false
         end
 
         # Validate and parse the PIN part using existing PIN logic
         raise ::ArgumentError, format(ERROR_INVALID_EPIN, string_value) unless Pin::Identifier.valid?(pin_part)
 
         pin_identifier = Pin::Identifier.parse(pin_part)
-        identifier_native = !foreign
+        identifier_native = !derived
 
-        new(pin_identifier.type, pin_identifier.side, pin_identifier.state, identifier_native)
+        new(pin_identifier.type, pin_identifier.side, pin_identifier.state, identifier_native, terminal: pin_identifier.terminal)
       end
 
       # Check if a string is a valid EPIN notation
       #
+      # Valid EPIN format: [<state>]<letter>[<terminal>][<derivation>]
+      # - State: + or - (optional)
+      # - Letter: A-Z or a-z (required)
+      # - Terminal: ^ (optional)
+      # - Derivation: ' (optional)
+      #
       # @param epin_string [String] The string to validate
       # @return [Boolean] true if valid EPIN, false otherwise
       #
       # @example
-      #   Sashite::Epin::Identifier.valid?("K")    # => true
-      #   Sashite::Epin::Identifier.valid?("+R'")  # => true
-      #   Sashite::Epin::Identifier.valid?("-p")   # => true
-      #   Sashite::Epin::Identifier.valid?("KK")   # => false
-      #   Sashite::Epin::Identifier.valid?("++K")  # => false
+      #   Sashite::Epin::Identifier.valid?("K")      # => true
+      #   Sashite::Epin::Identifier.valid?("K^")     # => true
+      #   Sashite::Epin::Identifier.valid?("+R'")    # => true
+      #   Sashite::Epin::Identifier.valid?("+K^'")   # => true
+      #   Sashite::Epin::Identifier.valid?("KK")     # => false
+      #   Sashite::Epin::Identifier.valid?("++K")    # => false
+      #   Sashite::Epin::Identifier.valid?("K'^")    # => false (wrong order)
       def self.valid?(epin_string)
         return false unless epin_string.is_a?(::String)
         return false if epin_string.empty?
 
-        # Check for derivation suffix
-        if epin_string.end_with?(DERIVATION_SUFFIX)
-          pin_part = epin_string[0...-1] # Remove the apostrophe
-          return false if pin_part.empty? # Can't have just an apostrophe
-        else
-          pin_part = epin_string
-        end
+        # Check EPIN pattern
+        return false unless epin_string.match?(EPIN_PATTERN)
+
+        # Extract PIN part (remove derivation marker if present)
+        pin_part = epin_string.end_with?(DERIVATION_MARKER) ? epin_string[0...-1] : epin_string
+        return false if pin_part.empty? # Can't have just an apostrophe
 
         # Validate the PIN part using existing PIN validation
         Pin::Identifier.valid?(pin_part)
@@ -136,13 +168,17 @@ module Sashite
 
       # Convert the identifier to its EPIN string representation
       #
+      # Format: [<state>]<letter>[<terminal>][<derivation>]
+      #
       # @return [String] EPIN notation string
+      #
       # @example
       #   identifier.to_s  # => "+R'"
+      #   identifier.to_s  # => "K^"
+      #   identifier.to_s  # => "+K^'"
       #   identifier.to_s  # => "-p"
-      #   identifier.to_s  # => "K"
       def to_s
-        "#{prefix}#{letter}#{suffix}"
+        "#{prefix}#{letter}#{terminal_marker}#{derivation_marker}"
       end
 
       # Get the letter representation (inherited from PIN logic)
@@ -152,156 +188,237 @@ module Sashite
         @pin_identifier.letter
       end
 
-      # Get the prefix representation (inherited from PIN logic)
+      # Get the state prefix (inherited from PIN logic)
       #
-      # @return [String] prefix representing the state
+      # @return [String] prefix representing the state ("+" / "-" / "")
       def prefix
         @pin_identifier.prefix
       end
 
-      # Get the suffix representation
+      # Get the terminal marker (inherited from PIN logic)
       #
-      # @return [String] suffix representing the derivation
-      def suffix
-        native? ? NATIVE_SUFFIX : DERIVATION_SUFFIX
+      # @return [String] terminal marker ("^" or "")
+      def terminal_marker
+        @pin_identifier.suffix
       end
 
+      # Get the derivation marker (EPIN-specific)
+      #
+      # @return [String] derivation marker ("'" for foreign, "" for native)
+      def derivation_marker
+        native? ? NATIVE_MARKER : DERIVATION_MARKER
+      end
+
+      # Alias for backward compatibility
+      alias suffix derivation_marker
+
       # Create a new identifier with enhanced state
       #
+      # Preserves type, side, terminal status, and derivation.
+      #
       # @return [Identifier] new identifier instance with enhanced state
+      #
       # @example
       #   identifier.enhance  # (:K, :first, :normal, true) => (:K, :first, :enhanced, true)
       def enhance
         return self if enhanced?
 
-        self.class.new(type, side, Pin::Identifier::ENHANCED_STATE, native)
+        self.class.new(type, side, Pin::Identifier::ENHANCED_STATE, native, terminal: terminal)
       end
 
       # Create a new identifier without enhanced state
       #
-      # @return [Identifier] new identifier instance without enhanced state
+      # @return [Identifier] new identifier instance with normal state
+      #
       # @example
       #   identifier.unenhance  # (:K, :first, :enhanced, true) => (:K, :first, :normal, true)
       def unenhance
         return self unless enhanced?
 
-        self.class.new(type, side, Pin::Identifier::NORMAL_STATE, native)
+        self.class.new(type, side, Pin::Identifier::NORMAL_STATE, native, terminal: terminal)
       end
 
       # Create a new identifier with diminished state
       #
       # @return [Identifier] new identifier instance with diminished state
+      #
       # @example
       #   identifier.diminish  # (:K, :first, :normal, true) => (:K, :first, :diminished, true)
       def diminish
         return self if diminished?
 
-        self.class.new(type, side, Pin::Identifier::DIMINISHED_STATE, native)
+        self.class.new(type, side, Pin::Identifier::DIMINISHED_STATE, native, terminal: terminal)
       end
 
       # Create a new identifier without diminished state
       #
-      # @return [Identifier] new identifier instance without diminished state
+      # @return [Identifier] new identifier instance with normal state
+      #
       # @example
       #   identifier.undiminish  # (:K, :first, :diminished, true) => (:K, :first, :normal, true)
       def undiminish
         return self unless diminished?
 
-        self.class.new(type, side, Pin::Identifier::NORMAL_STATE, native)
+        self.class.new(type, side, Pin::Identifier::NORMAL_STATE, native, terminal: terminal)
       end
 
-      # Create a new identifier with normal state (no modifiers)
+      # Create a new identifier with normal state (no state modifiers)
       #
       # @return [Identifier] new identifier instance with normal state
+      #
       # @example
       #   identifier.normalize  # (:K, :first, :enhanced, true) => (:K, :first, :normal, true)
       def normalize
         return self if normal?
 
-        self.class.new(type, side, Pin::Identifier::NORMAL_STATE, native)
+        self.class.new(type, side, Pin::Identifier::NORMAL_STATE, native, terminal: terminal)
+      end
+
+      # Create a new identifier marked as terminal
+      #
+      # @return [Identifier] new identifier instance marked as terminal
+      #
+      # @example
+      #   identifier.mark_terminal  # "K" => "K^"
+      #   identifier.mark_terminal  # "K'" => "K^'"
+      def mark_terminal
+        return self if terminal?
+
+        self.class.new(type, side, state, native, terminal: true)
+      end
+
+      # Create a new identifier unmarked as terminal
+      #
+      # @return [Identifier] new identifier instance unmarked as terminal
+      #
+      # @example
+      #   identifier.unmark_terminal  # "K^" => "K"
+      #   identifier.unmark_terminal  # "K^'" => "K'"
+      def unmark_terminal
+        return self unless terminal?
+
+        self.class.new(type, side, state, native, terminal: false)
       end
 
       # Create a new identifier with opposite side
       #
       # @return [Identifier] new identifier instance with opposite side
+      #
       # @example
       #   identifier.flip  # (:K, :first, :normal, true) => (:K, :second, :normal, true)
       def flip
-        self.class.new(type, opposite_side, state, native)
+        self.class.new(type, opposite_side, state, native, terminal: terminal)
       end
 
-      # Create a new identifier with foreign style (derivation marker)
+      # Create a new identifier with foreign/derived style
+      #
+      # Converts a native piece to foreign style (opposite side's native style).
       #
       # @return [Identifier] new identifier instance with foreign style
+      #
       # @example
       #   identifier.derive  # (:K, :first, :normal, true) => (:K, :first, :normal, false)
+      #   # "K" => "K'"
       def derive
         return self if derived?
 
-        self.class.new(type, side, state, FOREIGN)
+        self.class.new(type, side, state, FOREIGN, terminal: terminal)
       end
 
-      # Create a new identifier with native style (no derivation marker)
+      # Create a new identifier with native style
+      #
+      # Converts a foreign piece to native style (current side's native style).
       #
       # @return [Identifier] new identifier instance with native style
+      #
       # @example
       #   identifier.underive  # (:K, :first, :normal, false) => (:K, :first, :normal, true)
+      #   # "K'" => "K"
       def underive
         return self if native?
 
-        self.class.new(type, side, state, NATIVE)
+        self.class.new(type, side, state, NATIVE, terminal: terminal)
       end
 
-      # Create a new identifier with a different type (keeping same side, state, and derivation)
+      # Create a new identifier with a different type
+      #
+      # Preserves side, state, terminal status, and derivation.
       #
       # @param new_type [Symbol] new type (:A to :Z)
       # @return [Identifier] new identifier instance with different type
+      #
       # @example
       #   identifier.with_type(:Q)  # (:K, :first, :normal, true) => (:Q, :first, :normal, true)
       def with_type(new_type)
         Pin::Identifier.validate_type(new_type)
         return self if type == new_type
 
-        self.class.new(new_type, side, state, native)
+        self.class.new(new_type, side, state, native, terminal: terminal)
       end
 
-      # Create a new identifier with a different side (keeping same type, state, and derivation)
+      # Create a new identifier with a different side
+      #
+      # Preserves type, state, terminal status, and derivation.
       #
       # @param new_side [Symbol] :first or :second
       # @return [Identifier] new identifier instance with different side
+      #
       # @example
       #   identifier.with_side(:second)  # (:K, :first, :normal, true) => (:K, :second, :normal, true)
       def with_side(new_side)
         Pin::Identifier.validate_side(new_side)
         return self if side == new_side
 
-        self.class.new(type, new_side, state, native)
+        self.class.new(type, new_side, state, native, terminal: terminal)
       end
 
-      # Create a new identifier with a different state (keeping same type, side, and derivation)
+      # Create a new identifier with a different state
+      #
+      # Preserves type, side, terminal status, and derivation.
       #
       # @param new_state [Symbol] :normal, :enhanced, or :diminished
       # @return [Identifier] new identifier instance with different state
+      #
       # @example
       #   identifier.with_state(:enhanced)  # (:K, :first, :normal, true) => (:K, :first, :enhanced, true)
       def with_state(new_state)
         Pin::Identifier.validate_state(new_state)
         return self if state == new_state
 
-        self.class.new(type, side, new_state, native)
+        self.class.new(type, side, new_state, native, terminal: terminal)
       end
 
-      # Create a new identifier with a different derivation (keeping same type, side, and state)
+      # Create a new identifier with a different derivation
+      #
+      # Preserves type, side, state, and terminal status.
       #
       # @param new_native [Boolean] true for native, false for foreign
       # @return [Identifier] new identifier instance with different derivation
+      #
       # @example
       #   identifier.with_derivation(false)  # (:K, :first, :normal, true) => (:K, :first, :normal, false)
       def with_derivation(new_native)
         self.class.validate_derivation(new_native)
         return self if native == new_native
 
-        self.class.new(type, side, state, new_native)
+        self.class.new(type, side, state, new_native, terminal: terminal)
+      end
+
+      # Create a new identifier with a different terminal status
+      #
+      # Preserves type, side, state, and derivation.
+      #
+      # @param new_terminal_bool [Boolean] terminal status
+      # @return [Identifier] new identifier instance with different terminal status
+      #
+      # @example
+      #   identifier.with_terminal(true)  # "K" => "K^"
+      def with_terminal(new_terminal_bool)
+        raise ::TypeError unless [true, false].include?(new_terminal_bool)
+
+        return self if terminal? == new_terminal_bool
+
+        self.class.new(type, side, state, native, terminal: new_terminal_bool)
       end
 
       # Check if the identifier has enhanced state
@@ -318,9 +435,9 @@ module Sashite
         @pin_identifier.diminished?
       end
 
-      # Check if the identifier has normal state (no modifiers)
+      # Check if the identifier has normal state (no state modifiers)
       #
-      # @return [Boolean] true if no modifiers are present
+      # @return [Boolean] true if normal
       def normal?
         @pin_identifier.normal?
       end
@@ -339,27 +456,44 @@ module Sashite
         @pin_identifier.second_player?
       end
 
-      # Check if the identifier has native style (no derivation marker)
+      # Check if the identifier is a terminal piece
+      #
+      # A terminal piece is one whose presence, condition, or capacity for action
+      # determines whether the match can continue.
+      #
+      # @return [Boolean] true if terminal
+      def terminal?
+        @pin_identifier.terminal?
+      end
+
+      # Check if the identifier has native style
+      #
+      # A native piece has the native style of its current side.
       #
       # @return [Boolean] true if native style
       def native?
         native == NATIVE
       end
 
-      # Check if the identifier has foreign style (derivation marker)
+      # Check if the identifier has foreign/derived style
+      #
+      # A derived piece has the foreign style (opposite side's native style).
       #
-      # @return [Boolean] true if foreign style
+      # @return [Boolean] true if foreign/derived style
       def derived?
         native == FOREIGN
       end
 
-      # Alias for derived? to match the specification terminology
+      # Alias for derived? to match specification terminology
       alias foreign? derived?
 
-      # Check if this identifier is the same type as another (ignoring side, state, and derivation)
+      # Check if this identifier is the same type as another
+      #
+      # Ignores side, state, terminal status, and derivation.
       #
       # @param other [Identifier] identifier to compare with
       # @return [Boolean] true if same type
+      #
       # @example
       #   king1.same_type?(king2)  # (:K, :first, :normal, true) and (:K, :second, :enhanced, false) => true
       def same_type?(other)
@@ -388,6 +522,16 @@ module Sashite
         @pin_identifier.same_state?(other.instance_variable_get(:@pin_identifier))
       end
 
+      # Check if this identifier has the same terminal status as another
+      #
+      # @param other [Identifier] identifier to compare with
+      # @return [Boolean] true if same terminal status
+      def same_terminal?(other)
+        return false unless other.is_a?(self.class)
+
+        @pin_identifier.same_terminal?(other.instance_variable_get(:@pin_identifier))
+      end
+
       # Check if this identifier has the same style derivation as another
       #
       # @param other [Identifier] identifier to compare with
@@ -400,6 +544,9 @@ module Sashite
 
       # Custom equality comparison
       #
+      # Two identifiers are equal if they have the same type, side, state,
+      # terminal status, and derivation.
+      #
       # @param other [Object] object to compare with
       # @return [Boolean] true if identifiers are equal
       def ==(other)

data/lib/sashite/epin.rb

@@ -9,16 +9,20 @@ module Sashite
   # EPIN extends PIN by adding derivation markers that distinguish pieces by their style origin,
   # enabling cross-style game scenarios and piece origin tracking.
   #
-  # Format: [<state>]<letter>[<derivation>]
+  # Format: [<state>]<letter>[<terminal>][<derivation>]
   # - State modifier: "+" (enhanced), "-" (diminished), or none (normal)
   # - Letter: A-Z (first player), a-z (second player)
+  # - Terminal marker: "^" (terminal piece)
   # - Derivation marker: "'" (foreign style), or none (native style)
   #
   # Examples:
-  #   "K"   - First player king (native style, normal state)
-  #   "k'"  - Second player king (foreign style, normal state)
-  #   "+R'" - First player rook (foreign style, enhanced state)
-  #   "-p"  - Second player pawn (native style, diminished state)
+  #   "K"    - First player king (native style, normal state, non-terminal)
+  #   "K^"   - First player king (native style, normal state, terminal)
+  #   "k'"   - Second player king (foreign style, normal state, non-terminal)
+  #   "k^'"  - Second player king (foreign style, normal state, terminal)
+  #   "+R'"  - First player rook (foreign style, enhanced state, non-terminal)
+  #   "+K^'" - First player king (foreign style, enhanced state, terminal)
+  #   "-p"   - Second player pawn (native style, diminished state, non-terminal)
   #
   # @see https://sashite.dev/specs/epin/1.0.0/
   module Epin
@@ -28,11 +32,14 @@ module Sashite
     # @return [Boolean] true if valid EPIN, false otherwise
     #
     # @example
-    #   Sashite::Epin.valid?("K")     # => true
-    #   Sashite::Epin.valid?("+R'")   # => true
-    #   Sashite::Epin.valid?("-p")    # => true
-    #   Sashite::Epin.valid?("KK")    # => false
-    #   Sashite::Epin.valid?("++K")   # => false
+    #   Sashite::Epin.valid?("K")      # => true
+    #   Sashite::Epin.valid?("K^")     # => true
+    #   Sashite::Epin.valid?("+R'")    # => true
+    #   Sashite::Epin.valid?("+K^'")   # => true
+    #   Sashite::Epin.valid?("-p")     # => true
+    #   Sashite::Epin.valid?("KK")     # => false
+    #   Sashite::Epin.valid?("++K")    # => false
+    #   Sashite::Epin.valid?("K'^")    # => false (wrong order)
     def self.valid?(epin_string)
       Identifier.valid?(epin_string)
     end
@@ -42,10 +49,13 @@ module Sashite
     # @param epin_string [String] EPIN notation string
     # @return [Epin::Identifier] new identifier instance
     # @raise [ArgumentError] if the EPIN string is invalid
+    #
     # @example
-    #   Sashite::Epin.parse("K")     # => #<Epin::Identifier type=:K side=:first state=:normal native=true>
-    #   Sashite::Epin.parse("+R'")   # => #<Epin::Identifier type=:R side=:first state=:enhanced native=false>
-    #   Sashite::Epin.parse("-p")    # => #<Epin::Identifier type=:P side=:second state=:diminished native=true>
+    #   Sashite::Epin.parse("K")       # => #<Epin::Identifier type=:K side=:first state=:normal native=true terminal=false>
+    #   Sashite::Epin.parse("K^")      # => #<Epin::Identifier type=:K side=:first state=:normal native=true terminal=true>
+    #   Sashite::Epin.parse("+R'")     # => #<Epin::Identifier type=:R side=:first state=:enhanced native=false terminal=false>
+    #   Sashite::Epin.parse("+K^'")    # => #<Epin::Identifier type=:K side=:first state=:enhanced native=false terminal=true>
+    #   Sashite::Epin.parse("-p")      # => #<Epin::Identifier type=:P side=:second state=:diminished native=true terminal=false>
     def self.parse(epin_string)
       Identifier.parse(epin_string)
     end
@@ -56,14 +66,18 @@ module Sashite
     # @param side [Symbol] player side (:first or :second)
     # @param state [Symbol] piece state (:normal, :enhanced, or :diminished)
     # @param native [Boolean] style derivation (true for native, false for foreign)
+    # @param terminal [Boolean] whether the piece is a terminal piece
     # @return [Epin::Identifier] new identifier instance
     # @raise [ArgumentError] if parameters are invalid
+    #
     # @example
-    #   Sashite::Epin.identifier(:K, :first, :normal, true)      # => #<Epin::Identifier type=:K side=:first state=:normal native=true>
-    #   Sashite::Epin.identifier(:R, :first, :enhanced, false)   # => #<Epin::Identifier type=:R side=:first state=:enhanced native=false>
-    #   Sashite::Epin.identifier(:P, :second, :diminished, true) # => #<Epin::Identifier type=:P side=:second state=:diminished native=true>
-    def self.identifier(type, side, state, native)
-      Identifier.new(type, side, state, native)
+    #   Sashite::Epin.identifier(:K, :first, :normal, true)                     # => "K"
+    #   Sashite::Epin.identifier(:K, :first, :normal, true, terminal: true)     # => "K^"
+    #   Sashite::Epin.identifier(:R, :first, :enhanced, false)                  # => "+R'"
+    #   Sashite::Epin.identifier(:K, :first, :enhanced, false, terminal: true)  # => "+K^'"
+    #   Sashite::Epin.identifier(:P, :second, :diminished, true)                # => "-p"
+    def self.identifier(type, side, state, native, terminal: false)
+      Identifier.new(type, side, state, native, terminal: terminal)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-epin
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.1.0
+        version: 3.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.1.0
+        version: 3.2.0
 description: |
   EPIN (Extended Piece Identifier Notation) extends PIN to provide style-aware piece representation
   in abstract strategy board games. This gem implements the EPIN Specification v1.0.0 with
@@ -65,7 +65,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.2
 specification_version: 4
 summary: EPIN (Extended Piece Identifier Notation) implementation for Ruby extending
   PIN with style derivation markers.