Sin.rb

# In your Gemfile
gem "sashite-sin"

require "sashite/sin"

# Parse SIN strings into identifier objects
identifier = Sashite::Sin.parse("C")           # Family=:C, Side=:first
identifier.to_s                                # => "C"
identifier.family                              # => :C
identifier.side                                # => :first
identifier.letter                              # => "C" (combined representation)

# Create identifiers directly
identifier = Sashite::Sin.identifier(:C, :first)           # Family=:C, Side=:first
identifier = Sashite::Sin::Identifier.new(:C, :second)     # Family=:C, Side=:second

# Validate SIN strings
Sashite::Sin.valid?("C")                 # => true
Sashite::Sin.valid?("c")                 # => true
Sashite::Sin.valid?("1")                 # => false (not a letter)
Sashite::Sin.valid?("CC")                # => false (not single character)

# All transformations return new immutable instances
identifier = Sashite::Sin.parse("C")

# Flip player assignment
flipped = identifier.flip # Family=:C, Side=:second
flipped.to_s # => "c"

# Change family
changed = identifier.with_family(:S) # Family=:S, Side=:first
changed.to_s # => "S"

# Change side
other_side = identifier.with_side(:second) # Family=:C, Side=:second
other_side.to_s # => "c"

# Chain transformations
result = identifier.flip.with_family(:M) # Family=:M, Side=:second
result.to_s # => "m"

identifier = Sashite::Sin.parse("C")
opposite = Sashite::Sin.parse("s")

# Player identification
identifier.first_player?                       # => true
identifier.second_player?                      # => false
opposite.first_player?                         # => false
opposite.second_player?                        # => true

# Family and side comparison
chess1 = Sashite::Sin.parse("C")
chess2 = Sashite::Sin.parse("c")
shogi = Sashite::Sin.parse("S")

chess1.same_family?(chess2)               # => true (both Chess family)
chess1.same_side?(shogi)                  # => true (both first player)
chess1.same_family?(shogi)                # => false (different families)

# Working with multiple identifiers
identifiers = %w[C c S s M m].map { |sin| Sashite::Sin.parse(sin) }

# Filter by player
first_player_identifiers = identifiers.select(&:first_player?)
first_player_identifiers.map(&:to_s) # => ["C", "S", "M"]

# Group by family
by_family = identifiers.group_by(&:family)
by_family[:C].size # => 2 (both C and c)

# Find specific families
chess_identifiers = identifiers.select { |i| i.family == :C }
chess_identifiers.map(&:to_s) # => ["C", "c"]

/\A[A-Za-z]\z/

# Chess (8×8 board)
chess_white = Sashite::Sin.parse("C")    # First player (White pieces)
chess_black = Sashite::Sin.parse("c")    # Second player (Black pieces)

# Shōgi (9×9 board)
shogi_sente = Sashite::Sin.parse("S")    # First player (Sente 先手)
shogi_gote = Sashite::Sin.parse("s")     # Second player (Gote 後手)

# Xiangqi (9×10 board)
xiangqi_red = Sashite::Sin.parse("X")    # First player (Red pieces)
xiangqi_black = Sashite::Sin.parse("x")  # Second player (Black pieces)

# Makruk (8×8 board)
makruk_white = Sashite::Sin.parse("M")   # First player (White pieces)
makruk_black = Sashite::Sin.parse("m")   # Second player (Black pieces)

# Janggi (9×10 board)
janggi_cho = Sashite::Sin.parse("J")     # First player (Cho 초)
janggi_han = Sashite::Sin.parse("j")     # Second player (Han 한)

# Chess vs. Ōgi Match (both 8×8 compatible)
chess_white = Sashite::Sin.parse("C")    # Chess style, first player
ogi_black = Sashite::Sin.parse("o")      # Ōgi style, second player

# Cross-Style Match Setup
def create_hybrid_match
  [
    Sashite::Sin.parse("C"),             # First player uses Chess family
    Sashite::Sin.parse("s")              # Second player uses Shōgi family
  ]
end

identifiers = create_hybrid_match
identifiers[0].same_side?(identifiers[1])    # => false (different players)
identifiers[0].same_family?(identifiers[1])  # => false (different families)

# Clear separation of concerns
identifier = Sashite::Sin.parse("C")
identifier.family  # => :C (Style Family - invariant)
identifier.side    # => :first (Player Assignment)
identifier.letter  # => "C" (Combined representation)

# Transformations are explicit
chess_white = Sashite::Sin.identifier(:C, :first)
shogi_white = chess_white.with_family(:S) # Change family, keep side
chess_black = chess_white.with_side(:second) # Change side, keep family

# All transformations return new instances
original = Sashite::Sin.identifier(:C, :first)
flipped = original.flip
changed_family = original.with_family(:S)

# Original identifier is never modified
original.to_s         # => "C" (unchanged)
flipped.to_s          # => "c"
changed_family.to_s   # => "S"

# Transformations can be chained
result = original.flip.with_family(:M).flip
result.to_s # => "M"