# In your Gemfile
gem "sashite-epin"

gem "sashite-pin"  # Piece Identifier Notation

require "sashite/epin"

# Standard parsing (raises on error)
epin = Sashite::Epin.parse("K^'")
epin.to_s  # => "K^'"

# Access PIN attributes through the component
epin.pin.abbr       # => :K
epin.pin.side       # => :first
epin.pin.state      # => :normal
epin.pin.terminal?  # => true

# Access derivation status
epin.derived?  # => true
epin.native?   # => false

# PIN component is a cached Sashite::Pin::Identifier instance
epin.pin.enhanced?      # => false
epin.pin.first_player?  # => true

# Returns a cached instance — no allocation
Sashite::Epin.parse("K^'").equal?(Sashite::Epin.parse("K^'"))  # => true

# Invalid input raises ArgumentError
Sashite::Epin.parse("invalid")  # => raises ArgumentError

# Valid input returns an Identifier
Sashite::Epin.safe_parse("K^'")   # => #<Sashite::Epin::Identifier K^'>
Sashite::Epin.safe_parse("+R")    # => #<Sashite::Epin::Identifier +R>

# Invalid input returns nil — no exception allocated
Sashite::Epin.safe_parse("")        # => nil
Sashite::Epin.safe_parse("invalid") # => nil
Sashite::Epin.safe_parse("K''")     # => nil
Sashite::Epin.safe_parse(nil)       # => nil

# From a cached PIN instance — direct hash lookup, no allocation
pin = Sashite::Pin.parse("K^")
Sashite::Epin.fetch(pin)                  # => #<Sashite::Epin::Identifier K^>
Sashite::Epin.fetch(pin, derived: true)   # => #<Sashite::Epin::Identifier K^'>

# Same cached instance as parse
Sashite::Epin.fetch(pin, derived: true).equal?(Sashite::Epin.parse("K^'"))  # => true

# Invalid PIN raises ArgumentError
Sashite::Epin.fetch(nil)  # => raises ArgumentError

epin = Sashite::Epin.parse("K^'")
epin.to_s  # => "K^'"

epin = Sashite::Epin.parse("+r")
epin.to_s  # => "+r"

# Boolean check (never raises)
# Uses an exception-free code path internally for performance.
Sashite::Epin.valid?("K")         # => true
Sashite::Epin.valid?("+R^'")      # => true
Sashite::Epin.valid?("invalid")   # => false
Sashite::Epin.valid?("K''")       # => false
Sashite::Epin.valid?("K'^")       # => false
Sashite::Epin.valid?(nil)         # => false

epin = Sashite::Epin.parse("K^")

# Derivation transformations
epin.derive.to_s  # => "K^'"
epin.native.to_s  # => "K^"

# Replace PIN component
new_pin = Sashite::Pin.parse("+Q^")
epin.with_pin(new_pin).to_s  # => "+Q^"

# Transformations return cached instances
epin.derive.equal?(Sashite::Epin.parse("K^'"))  # => true

epin = Sashite::Epin.parse("K^'")

# Change abbr
epin.with_pin(epin.pin.with_abbr(:Q)).to_s  # => "Q^'"

# Change state
epin.with_pin(epin.pin.enhance).to_s  # => "+K^'"

# Change side
epin.with_pin(epin.pin.flip).to_s  # => "k^'"

# Remove terminal
epin.with_pin(epin.pin.non_terminal).to_s  # => "K'"

epin = Sashite::Epin.parse("+R^'")

# Get PIN component (cached Pin::Identifier instance)
epin.pin       # => #<Sashite::Pin::Identifier +R^>
epin.pin.to_s  # => "+R^"

# Check derivation
epin.derived?  # => true
epin.native?   # => false

# Serialize
epin.to_s  # => "+R^'"

epin = Sashite::Epin.parse("+P^'")

# PIN queries
epin.pin.abbr          # => :P
epin.pin.side          # => :first
epin.pin.state         # => :enhanced
epin.pin.terminal?     # => true
epin.pin.first_player? # => true
epin.pin.enhanced?     # => true

# EPIN queries
epin.derived?  # => true
epin.native?   # => false

# Compare EPINs
other = Sashite::Epin.parse("+P^")
epin.pin.same_abbr?(other.pin)   # => true
epin.pin.same_state?(other.pin)  # => true
epin.same_derived?(other)        # => false

%w[K +R -p K^ +R^].each do |pin_token|
  epin = Sashite::Epin.parse(pin_token)
  epin.native?  # => true
  epin.to_s     # => pin_token
end

# Parses an EPIN string into a cached Identifier.
# Returns a pre-instantiated, frozen instance.
# Raises ArgumentError if the string is not valid.
#
# @param string [String] EPIN string
# @return [Identifier]
# @raise [ArgumentError] if invalid
def Sashite::Epin.parse(string)

# Parses an EPIN string without raising.
# Returns a cached Identifier on success, nil on failure.
# Never allocates exception objects or captures backtraces.
# Delegates to Pin.safe_parse for the PIN component.
#
# @param string [String] EPIN string
# @return [Identifier, nil]
def Sashite::Epin.safe_parse(string)

# Retrieves a cached Identifier by PIN component and derivation status.
# Bypasses string parsing entirely — direct hash lookup.
# Raises ArgumentError if the PIN is invalid.
#
# @param pin [Sashite::Pin::Identifier] PIN component
# @param derived [Boolean] Derived status
# @return [Identifier]
# @raise [ArgumentError] if invalid
def Sashite::Epin.fetch(pin, derived: false)

# Reports whether string is a valid EPIN.
# Never raises; returns false for any invalid input.
# Uses an exception-free code path internally for performance.
#
# @param string [String] EPIN string
# @return [Boolean]
def Sashite::Epin.valid?(string)

# Identifier represents a parsed EPIN combining PIN with derivation status.
# All instances are frozen and pre-instantiated — never construct directly,
# use Sashite::Epin.parse, .safe_parse, or .fetch instead.
class Sashite::Epin::Identifier
  # Returns the PIN component (a cached Sashite::Pin::Identifier instance).
  #
  # @return [Sashite::Pin::Identifier]
  def pin

  # Returns true if derived style.
  #
  # @return [Boolean]
  def derived?

  # Returns true if native style.
  #
  # @return [Boolean]
  def native?

  # Returns the EPIN string representation.
  #
  # @return [String]
  def to_s
end

# PIN replacement (returns cached Identifier)
def with_pin(new_pin)  # => Identifier with different PIN

# Derivation transformations
def derive  # => Identifier with derived: true
def native  # => Identifier with derived: false