Sashite.Pin.Identifier (Sashite.Pin v3.1.0)

Represents a parsed PIN (Piece Identifier Notation) identifier.

An Identifier encodes four attributes of a piece:

Abbr: the piece name abbreviation (A-Z as uppercase atom)
Side: the piece side (:first or :second)
State: the piece state (:normal, :enhanced, or :diminished)
Terminal: whether the piece is terminal (true or false)

All structs are immutable. Transformation functions return new structs.

Examples

iex> pin = Sashite.Pin.Identifier.new(:K, :first)
iex> pin.abbr
:K
iex> pin.side
:first

iex> pin = Sashite.Pin.Identifier.new(:R, :second, :enhanced)
iex> Sashite.Pin.Identifier.to_string(pin)
"+r"

Summary

Functions

diminish(identifier)

Returns a new Identifier with diminished state.

diminished?(identifier)

Checks if the Identifier has diminished state.

enhance(identifier)

Returns a new Identifier with enhanced state.

enhanced?(identifier)

Checks if the Identifier has enhanced state.

first_player?(identifier)

Checks if the Identifier belongs to the first player.

flip(identifier)

Returns a new Identifier with the opposite side.

new(abbr, side, state \\ :normal, terminal \\ false)

Creates a new Identifier instance.

non_terminal(identifier)

Returns a new Identifier unmarked as terminal.

normal?(identifier)

Checks if the Identifier has normal state.

normalize(identifier)

Returns a new Identifier with normal state.

same_abbr?(identifier1, identifier2)

Checks if two Identifiers have the same abbreviation.

same_side?(identifier1, identifier2)

Checks if two Identifiers have the same side.

same_state?(identifier1, identifier2)

Checks if two Identifiers have the same state.

same_terminal?(identifier1, identifier2)

Checks if two Identifiers have the same terminal status.

second_player?(identifier)

Checks if the Identifier belongs to the second player.

terminal(identifier)

Returns a new Identifier marked as terminal.

to_string(identifier)

Returns the PIN string representation.

with_abbr(identifier, abbr)

Returns a new Identifier with a different abbreviation.

with_side(identifier, side)

Returns a new Identifier with a different side.

with_state(identifier, state)

Returns a new Identifier with a different state.

with_terminal(identifier, terminal)

Returns a new Identifier with a different terminal status.

Types

t()

@type t() :: %Sashite.Pin.Identifier{
  abbr: atom(),
  side: :first | :second,
  state: :normal | :enhanced | :diminished,
  terminal: boolean()
}

Functions

diminish(identifier)

@spec diminish(t()) :: t()

Returns a new Identifier with diminished state.

Examples

iex> pin = Sashite.Pin.Identifier.new(:K, :first)
iex> diminished = Sashite.Pin.Identifier.diminish(pin)
iex> diminished.state
:diminished

diminished?(identifier)

@spec diminished?(t()) :: boolean()

Checks if the Identifier has diminished state.

Examples

iex> pin = Sashite.Pin.Identifier.new(:K, :first, :diminished)
iex> Sashite.Pin.Identifier.diminished?(pin)
true

iex> pin = Sashite.Pin.Identifier.new(:K, :first, :normal)
iex> Sashite.Pin.Identifier.diminished?(pin)
false

enhance(identifier)

@spec enhance(t()) :: t()

Returns a new Identifier with enhanced state.

Examples

iex> pin = Sashite.Pin.Identifier.new(:K, :first)
iex> enhanced = Sashite.Pin.Identifier.enhance(pin)
iex> enhanced.state
:enhanced

enhanced?(identifier)

@spec enhanced?(t()) :: boolean()

Checks if the Identifier has enhanced state.

Examples

iex> pin = Sashite.Pin.Identifier.new(:K, :first, :enhanced)
iex> Sashite.Pin.Identifier.enhanced?(pin)
true

iex> pin = Sashite.Pin.Identifier.new(:K, :first, :normal)
iex> Sashite.Pin.Identifier.enhanced?(pin)
false

first_player?(identifier)

@spec first_player?(t()) :: boolean()

Checks if the Identifier belongs to the first player.

Examples

iex> pin = Sashite.Pin.Identifier.new(:K, :first)
iex> Sashite.Pin.Identifier.first_player?(pin)
true

iex> pin = Sashite.Pin.Identifier.new(:K, :second)
iex> Sashite.Pin.Identifier.first_player?(pin)
false

flip(identifier)

@spec flip(t()) :: t()

Returns a new Identifier with the opposite side.

Examples

iex> pin = Sashite.Pin.Identifier.new(:K, :first)
iex> flipped = Sashite.Pin.Identifier.flip(pin)
iex> flipped.side
:second

iex> pin = Sashite.Pin.Identifier.new(:K, :second)
iex> flipped = Sashite.Pin.Identifier.flip(pin)
iex> flipped.side
:first

new(abbr, side, state \\ :normal, terminal \\ false)

@spec new(atom(), atom(), atom(), boolean()) :: t()

Creates a new Identifier instance.

Validates all components through guards that expand to compile-time pattern matching — no runtime helper calls.

Parameters

abbr - Piece name abbreviation (:A to :Z)
side - Piece side (:first or :second)
state - Piece state (:normal, :enhanced, or :diminished), defaults to :normal
terminal - Terminal status (true or false), defaults to false

Examples

iex> Sashite.Pin.Identifier.new(:K, :first)
%Sashite.Pin.Identifier{abbr: :K, side: :first, state: :normal, terminal: false}

iex> Sashite.Pin.Identifier.new(:R, :second, :enhanced)
%Sashite.Pin.Identifier{abbr: :R, side: :second, state: :enhanced, terminal: false}

iex> Sashite.Pin.Identifier.new(:K, :first, :normal, true)
%Sashite.Pin.Identifier{abbr: :K, side: :first, state: :normal, terminal: true}

Raises

ArgumentError if any attribute is invalid

non_terminal(identifier)

@spec non_terminal(t()) :: t()

Returns a new Identifier unmarked as terminal.

Examples

iex> pin = Sashite.Pin.Identifier.new(:K, :first, :normal, true)
iex> non_term = Sashite.Pin.Identifier.non_terminal(pin)
iex> non_term.terminal
false

normal?(identifier)

@spec normal?(t()) :: boolean()

Checks if the Identifier has normal state.

Examples

iex> pin = Sashite.Pin.Identifier.new(:K, :first, :normal)
iex> Sashite.Pin.Identifier.normal?(pin)
true

iex> pin = Sashite.Pin.Identifier.new(:K, :first, :enhanced)
iex> Sashite.Pin.Identifier.normal?(pin)
false

normalize(identifier)

@spec normalize(t()) :: t()

Returns a new Identifier with normal state.

Examples

iex> pin = Sashite.Pin.Identifier.new(:K, :first, :enhanced)
iex> normalized = Sashite.Pin.Identifier.normalize(pin)
iex> normalized.state
:normal

same_abbr?(identifier1, identifier2)

@spec same_abbr?(t(), t()) :: boolean()

Checks if two Identifiers have the same abbreviation.

Examples

iex> pin1 = Sashite.Pin.Identifier.new(:K, :first)
iex> pin2 = Sashite.Pin.Identifier.new(:K, :second)
iex> Sashite.Pin.Identifier.same_abbr?(pin1, pin2)
true

iex> pin1 = Sashite.Pin.Identifier.new(:K, :first)
iex> pin2 = Sashite.Pin.Identifier.new(:Q, :first)
iex> Sashite.Pin.Identifier.same_abbr?(pin1, pin2)
false

same_side?(identifier1, identifier2)

@spec same_side?(t(), t()) :: boolean()

Checks if two Identifiers have the same side.

Examples

iex> pin1 = Sashite.Pin.Identifier.new(:K, :first)
iex> pin2 = Sashite.Pin.Identifier.new(:Q, :first)
iex> Sashite.Pin.Identifier.same_side?(pin1, pin2)
true

iex> pin1 = Sashite.Pin.Identifier.new(:K, :first)
iex> pin2 = Sashite.Pin.Identifier.new(:K, :second)
iex> Sashite.Pin.Identifier.same_side?(pin1, pin2)
false

same_state?(identifier1, identifier2)

@spec same_state?(t(), t()) :: boolean()

Checks if two Identifiers have the same state.

Examples

iex> pin1 = Sashite.Pin.Identifier.new(:K, :first, :enhanced)
iex> pin2 = Sashite.Pin.Identifier.new(:Q, :second, :enhanced)
iex> Sashite.Pin.Identifier.same_state?(pin1, pin2)
true

iex> pin1 = Sashite.Pin.Identifier.new(:K, :first, :enhanced)
iex> pin2 = Sashite.Pin.Identifier.new(:K, :first, :normal)
iex> Sashite.Pin.Identifier.same_state?(pin1, pin2)
false

same_terminal?(identifier1, identifier2)

@spec same_terminal?(t(), t()) :: boolean()

Checks if two Identifiers have the same terminal status.

Examples

iex> pin1 = Sashite.Pin.Identifier.new(:K, :first, :normal, true)
iex> pin2 = Sashite.Pin.Identifier.new(:Q, :second, :enhanced, true)
iex> Sashite.Pin.Identifier.same_terminal?(pin1, pin2)
true

iex> pin1 = Sashite.Pin.Identifier.new(:K, :first, :normal, true)
iex> pin2 = Sashite.Pin.Identifier.new(:K, :first, :normal, false)
iex> Sashite.Pin.Identifier.same_terminal?(pin1, pin2)
false

second_player?(identifier)

@spec second_player?(t()) :: boolean()

Checks if the Identifier belongs to the second player.

Examples

iex> pin = Sashite.Pin.Identifier.new(:K, :second)
iex> Sashite.Pin.Identifier.second_player?(pin)
true

iex> pin = Sashite.Pin.Identifier.new(:K, :first)
iex> Sashite.Pin.Identifier.second_player?(pin)
false

terminal(identifier)

@spec terminal(t()) :: t()

Returns a new Identifier marked as terminal.

Examples

iex> pin = Sashite.Pin.Identifier.new(:K, :first)
iex> term = Sashite.Pin.Identifier.terminal(pin)
iex> term.terminal
true

to_string(identifier)

@spec to_string(t()) :: String.t()

Returns the PIN string representation.

Each valid combination has its own function clause, generated at compile time. The BEAM dispatches directly to the correct clause and returns a pre-computed binary literal — zero concatenation, zero allocation.

Examples

iex> pin = Sashite.Pin.Identifier.new(:K, :first)
iex> Sashite.Pin.Identifier.to_string(pin)
"K"

iex> pin = Sashite.Pin.Identifier.new(:R, :second, :enhanced)
iex> Sashite.Pin.Identifier.to_string(pin)
"+r"

iex> pin = Sashite.Pin.Identifier.new(:K, :first, :normal, true)
iex> Sashite.Pin.Identifier.to_string(pin)
"K^"

iex> pin = Sashite.Pin.Identifier.new(:K, :first, :enhanced, true)
iex> Sashite.Pin.Identifier.to_string(pin)
"+K^"

with_abbr(identifier, abbr)

@spec with_abbr(t(), atom()) :: t()

Returns a new Identifier with a different abbreviation.

Examples

iex> pin = Sashite.Pin.Identifier.new(:K, :first)
iex> queen = Sashite.Pin.Identifier.with_abbr(pin, :Q)
iex> queen.abbr
:Q

Raises

ArgumentError if the abbreviation is invalid

with_side(identifier, side)

@spec with_side(t(), atom()) :: t()

Returns a new Identifier with a different side.

Examples

iex> pin = Sashite.Pin.Identifier.new(:K, :first)
iex> second = Sashite.Pin.Identifier.with_side(pin, :second)
iex> second.side
:second

Raises

ArgumentError if the side is invalid

with_state(identifier, state)

@spec with_state(t(), atom()) :: t()

Returns a new Identifier with a different state.

Examples

iex> pin = Sashite.Pin.Identifier.new(:K, :first)
iex> enhanced = Sashite.Pin.Identifier.with_state(pin, :enhanced)
iex> enhanced.state
:enhanced

Raises

ArgumentError if the state is invalid

with_terminal(identifier, terminal)

@spec with_terminal(t(), boolean()) :: t()

Returns a new Identifier with a different terminal status.

Examples

iex> pin = Sashite.Pin.Identifier.new(:K, :first)
iex> term = Sashite.Pin.Identifier.with_terminal(pin, true)
iex> term.terminal
true

Raises

ArgumentError if the terminal is not a boolean