Module: Sashite::Gan

Defined in:
lib/sashite/qpi.rb,
lib/sashite/qpi/actor.rb

Overview

GAN (General Actor Notation) implementation for Ruby

Provides a rule-agnostic format for identifying game actors in abstract strategy board games by combining Style Name Notation (SNN) and Piece Identifier Notation (PIN) with a colon separator and consistent case encoding.

GAN represents all four fundamental piece attributes from the Game Protocol:

  • Type → PIN component (ASCII letter choice)

  • Side → Consistent case encoding across both SNN and PIN components

  • State → PIN component (optional prefix modifier)

  • Style → SNN component (explicit style identifier)

Format: <snn>:<pin>

  • SNN component: Style identifier with case-based side encoding

  • Colon separator: Literal “:”

  • PIN component: Piece with optional state and case-based ownership

  • Case consistency: SNN and PIN components must have matching case

Examples:

"CHESS:K"    - First player chess king
"chess:k"    - Second player chess king
"SHOGI:+P"   - First player enhanced shōgi pawn
"xiangqi:-g" - Second player diminished xiangqi general

See: sashite.dev/specs/gan/1.0.0/

Defined Under Namespace

Classes: Actor

Class Method Summary collapse

Class Method Details

.actor(name, type, side, state = :normal) ⇒ Gan::Actor

Create a new actor instance

Examples:

Create actors directly

Sashite::Gan.actor(:Chess, :K, :first, :normal)     # => #<Gan::Actor name=:Chess type=:K side=:first state=:normal>
Sashite::Gan.actor(:Shogi, :P, :second, :enhanced)  # => #<Gan::Actor name=:Shogi type=:P side=:second state=:enhanced>

Parameters:

  • name (Symbol) —

    style name (with proper capitalization)

  • type (Symbol) —

    piece type (:A to :Z)

  • side (Symbol) —

    player side (:first or :second)

  • state (Symbol) (defaults to: :normal) —

    piece state (:normal, :enhanced, or :diminished)

Returns:

Raises:

  • (ArgumentError) —

    if parameters are invalid



72
73
74
 
# File 'lib/sashite/qpi.rb', line 72

def self.actor(name, type, side, state = :normal)
  Actor.new(name, type, side, state)
end

.parse(gan_string) ⇒ Gan::Actor

Parse a GAN string into an Actor object

Examples:

Parse different GAN formats

Sashite::Gan.parse("CHESS:K")     # => #<Gan::Actor name=:Chess type=:K side=:first state=:normal>
Sashite::Gan.parse("shogi:+p")    # => #<Gan::Actor name=:Shogi type=:P side=:second state=:enhanced>
Sashite::Gan.parse("XIANGQI:-G")  # => #<Gan::Actor name=:Xiangqi type=:G side=:first state=:diminished>

Parameters:

  • gan_string (String) —

    GAN notation string

Returns:

Raises:

  • (ArgumentError) —

    if the GAN string is invalid



57
58
59
 
# File 'lib/sashite/qpi.rb', line 57

def self.parse(gan_string)
  Actor.parse(gan_string)
end

.valid?(gan_string) ⇒ Boolean

Check if a string is valid GAN notation

Examples:

Validate various GAN formats

Sashite::Gan.valid?("CHESS:K")      # => true
Sashite::Gan.valid?("shogi:+p")     # => true
Sashite::Gan.valid?("Chess:K")      # => false (mixed case in style)
Sashite::Gan.valid?("CHESS:k")      # => false (case mismatch)
Sashite::Gan.valid?("CHESS")        # => false (missing piece)
Sashite::Gan.valid?("")             # => false (empty string)

Parameters:

  • gan_string (String) —

    The string to validate

Returns:

  • (Boolean) —

    true if valid GAN, false otherwise



44
45
46
 
# File 'lib/sashite/qpi.rb', line 44

def self.valid?(gan_string)
  Actor.valid?(gan_string)
end