Module: Sashite::Qpi

Defined in:
lib/sashite/qpi.rb,
lib/sashite/qpi/parser.rb,
lib/sashite/qpi/constants.rb,
lib/sashite/qpi/identifier.rb,
lib/sashite/qpi/errors/argument.rb,
lib/sashite/qpi/errors/argument/messages.rb

Overview

QPI (Qualified Piece Identifier) implementation for Ruby.

QPI provides complete piece identification by combining two primitive notations:

  • SIN (Style Identifier Notation) for Piece Style

  • PIN (Piece Identifier Notation) for Piece Name, Side, State, and Terminal Status

Format

<sin>:<pin>

  • SIN: Single ASCII letter encoding Piece Style and a side tag

  • PIN: Piece identifier with optional state modifier and terminal marker

Piece Identity Attributes

A QPI token encodes complete Piece Identity:

  • *Piece Style* → SIN letter (case-insensitive identity)

  • *Piece Name* → PIN letter (case-insensitive identity)

  • *Piece Side* → PIN letter case (uppercase = first, lowercase = second)

  • *Piece State* → PIN modifier (+/-)

  • *Terminal Status* → PIN marker (^)

Native/Derived Relationship

QPI defines a deterministic relationship based on case comparison:

  • Native: SIN case matches PIN case (sin.side == pin.side)

  • Derived: SIN case differs from PIN case (sin.side != pin.side)

Examples

qpi = Sashite::Qpi.parse("C:K^")
qpi.sin.abbr       # => :C
qpi.pin.abbr       # => :K
qpi.pin.side       # => :first
qpi.pin.state      # => :normal
qpi.pin.terminal?  # => true
qpi.native?        # => true

qpi = Sashite::Qpi.parse("C:k")
qpi.derived?  # => true
qpi.native.to_s  # => "C:K"

Sashite::Qpi.valid?("C:K^")     # => true
Sashite::Qpi.valid?("invalid")  # => false

See Also:

Defined Under Namespace

Modules: Constants, Errors, Parser Classes: Identifier

Class Method Summary collapse

Class Method Details

.parse(string) ⇒ Identifier

Parses a QPI string into an Identifier.

Examples:

Sashite::Qpi.parse("C:K")
# => #<Sashite::Qpi::Identifier C:K>

Sashite::Qpi.parse("s:+r^")
# => #<Sashite::Qpi::Identifier s:+r^>

Sashite::Qpi.parse("invalid")
# => raises Errors::Argument

Parameters:

  • string (String) —

    The QPI string to parse

Returns:

Raises:



73
74
75
76
77
 
# File 'lib/sashite/qpi.rb', line 73

def self.parse(string)
  components = Parser.parse(string)

  Identifier.new(components[:sin], components[:pin])
end

.valid?(string) ⇒ Boolean

Checks if a string is a valid QPI notation.

Examples:

Sashite::Qpi.valid?("C:K")       # => true
Sashite::Qpi.valid?("s:+r^")     # => true
Sashite::Qpi.valid?("invalid")   # => false

Parameters:

  • string (String) —

    The string to validate

Returns:

  • (Boolean) —

    true if valid, false otherwise



88
89
90
 
# File 'lib/sashite/qpi.rb', line 88

def self.valid?(string)
  Parser.valid?(string)
end