sashite-epin 1.2.0 → 2.1.0

data/lib/sashite/epin.rb

@@ -1,83 +1,301 @@
 # frozen_string_literal: true
 
-require_relative "epin/identifier"
+require "sashite/pin"
 
 module Sashite
-  # EPIN (Extended Piece Identifier Notation) implementation for Ruby
+  # EPIN (Extended Piece Identifier Notation) implementation for Ruby.
   #
-  # Provides style-aware ASCII-based format for representing pieces in abstract strategy board games.
-  # EPIN extends PIN by adding derivation markers that distinguish pieces by their style origin,
-  # enabling cross-style game scenarios and piece origin tracking.
+  # EPIN extends PIN by adding a **derivation marker** to track piece style
+  # in cross-style games.
   #
-  # 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)
+  # **EPIN is simply: PIN + optional style derivation marker (`'`)**
   #
-  # Examples:
-  #   "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)
+  # == Format
   #
-  # @see https://sashite.dev/specs/epin/1.0.0/
-  module Epin
-    # Check if a string is a valid EPIN notation
+  #   <pin-token>[<derivation-marker>]
+  #
+  # Where +<pin-token>+ is a valid PIN token and +<derivation-marker>+ is
+  # an optional trailing apostrophe (<tt>'</tt>).
+  #
+  # == 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)
+  #
+  # == Examples
+  #
+  #   epin = Sashite::Epin.parse("K^'")
+  #   epin.pin.type      # => :K
+  #   epin.pin.terminal  # => true
+  #   epin.derived       # => true
+  #
+  #   pin = Sashite::Pin.parse("K^")
+  #   epin = Sashite::Epin.new(pin, derived: true)
+  #   epin.to_s  # => "K^'"
+  #
+  #   Sashite::Epin.valid?("K^'")   # => true
+  #   Sashite::Epin.valid?("K'^")   # => 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.
+    #
+    # @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
+    #
+    # @example
+    #   Sashite::Epin.parse("K")
+    #   # => #<Sashite::Epin K>
+    #
+    #   Sashite::Epin.parse("K'")
+    #   # => #<Sashite::Epin K'>
+    #
+    #   Sashite::Epin.parse("+R^'")
+    #   # => #<Sashite::Epin +R^'>
+    #
+    #   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)
+    end
+
+    # Checks if a string is a valid EPIN notation.
     #
     # @param epin_string [String] The string to validate
-    # @return [Boolean] true if valid EPIN, false otherwise
+    # @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^'")   # => true
-    #   Sashite::Epin.valid?("-p")     # => true
-    #   Sashite::Epin.valid?("KK")     # => false
-    #   Sashite::Epin.valid?("++K")    # => false
-    #   Sashite::Epin.valid?("K'^")    # => false (wrong order)
+    #   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)
-      Identifier.valid?(epin_string)
+      return false unless epin_string.is_a?(String)
+
+      EPIN_PATTERN.match?(epin_string)
     end
 
-    # Parse an EPIN string into an Identifier object
+    # ========================================================================
+    # Conversion
+    # ========================================================================
+
+    # Converts the Epin to its string representation.
     #
-    # @param epin_string [String] EPIN notation string
-    # @return [Epin::Identifier] new identifier instance
-    # @raise [ArgumentError] if the EPIN string is invalid
+    # @return [String] The EPIN string
     #
     # @example
-    #   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)
+    #   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
 
-    # Create a new identifier instance
+    # Checks if two Epins have the same derivation status.
     #
-    # @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
-    # @return [Epin::Identifier] new identifier instance
-    # @raise [ArgumentError] if parameters are invalid
+    # @param other [Epin] The other Epin to compare
+    # @return [Boolean] true if same derivation status
     #
     # @example
-    #   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)
+    #   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 ? "'" : ""
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-epin
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -15,22 +15,18 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.2.0
+        version: 3.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.2.0
+        version: 3.3.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
-  a modern Ruby interface featuring immutable identifier objects and functional programming
-  principles. EPIN adds derivation markers to PIN that distinguish pieces by their style
-  origin, enabling cross-style game scenarios and piece origin tracking. Represents all
-  four Game Protocol piece attributes with full PIN backward compatibility. Perfect for
-  game engines, cross-tradition tournaments, and hybrid board game environments.
+  EPIN (Extended Piece Identifier Notation) implementation for Ruby.
+  Extends PIN by adding a derivation marker to track piece style in cross-style
+  abstract strategy board games with a minimal compositional API.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -40,7 +36,6 @@ files:
 - README.md
 - lib/sashite-epin.rb
 - lib/sashite/epin.rb
-- lib/sashite/epin/identifier.rb
 homepage: https://github.com/sashite/epin.rb
 licenses:
 - MIT