sin.rb

SIN (Style Identifier Notation) implementation for Ruby.

Overview

This library implements the SIN Specification v1.0.0.

Installation

# In your Gemfile
gem "sashite-sin"

Or install manually:

gem install sashite-sin

Usage

Parsing (String → Identifier)

Convert a SIN string into an Identifier object.

require "sashite/sin"

# Standard parsing (raises on error)
sin = Sashite::Sin.parse("C")
sin.abbr  # => :C
sin.side  # => :first

# Lowercase indicates second player
sin = Sashite::Sin.parse("c")
sin.abbr  # => :C
sin.side  # => :second

# Invalid input raises ArgumentError
Sashite::Sin.parse("")    # => raises ArgumentError
Sashite::Sin.parse("CC")  # => raises ArgumentError

Formatting (Identifier → String)

Convert an Identifier back to a SIN string.

# From Identifier object
sin = Sashite::Sin::Identifier.new(:C, :first)
sin.to_s  # => "C"

sin = Sashite::Sin::Identifier.new(:C, :second)
sin.to_s  # => "c"

Validation

# Boolean check
Sashite::Sin.valid?("C")   # => true
Sashite::Sin.valid?("c")   # => true
Sashite::Sin.valid?("")    # => false
Sashite::Sin.valid?("CC")  # => false
Sashite::Sin.valid?("1")   # => false

Queries

sin = Sashite::Sin.parse("C")

# Side queries
sin.first_player?   # => true
sin.second_player?  # => false

# Comparison queries
other = Sashite::Sin.parse("c")
sin.same_abbr?(other)  # => true
sin.same_side?(other)  # => false

API Reference

Types

# Identifier represents a parsed SIN identifier with abbreviation and side.
class Sashite::Sin::Identifier
  # Creates an Identifier from abbreviation and side.
  # Raises ArgumentError if attributes are invalid.
  #
  # @param abbr [Symbol] Style abbreviation (:A through :Z)
  # @param side [Symbol] Player side (:first or :second)
  # @return [Identifier]
  def initialize(abbr, side)

  # Returns the style abbreviation as an uppercase symbol.
  #
  # @return [Symbol]
  def abbr

  # Returns the player side.
  #
  # @return [Symbol] :first or :second
  def side

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

Constants

Sashite::Sin::Identifier::VALID_ABBRS  # => [:A, :B, ..., :Z]
Sashite::Sin::Identifier::VALID_SIDES  # => [:first, :second]

Parsing

# Parses a SIN string into an Identifier.
# Raises ArgumentError if the string is not valid.
#
# @param string [String] SIN string
# @return [Identifier]
# @raise [ArgumentError] if invalid
def Sashite::Sin.parse(string)

Validation

# Reports whether string is a valid SIN identifier.
#
# @param string [String] SIN string
# @return [Boolean]
def Sashite::Sin.valid?(string)

Queries

# Side queries
def first_player?   # => Boolean
def second_player?  # => Boolean

# Comparison queries
def same_abbr?(other)  # => Boolean
def same_side?(other)  # => Boolean

Errors

All parsing and validation errors raise ArgumentError with descriptive messages:

Message	Cause
`"empty input"`	String length is 0
`"input exceeds 1 character"`	String too long
`"must be a letter"`	Character is not A-Z or a-z

Design Principles

Bounded values: Explicit validation of abbreviations and sides
Object-oriented: Identifier class enables methods and encapsulation
Ruby idioms: valid? predicate, to_s conversion, ArgumentError for invalid input
Immutable identifiers: Instances are frozen after creation
No dependencies: Pure Ruby standard library only

Related Specifications

Game Protocol — Conceptual foundation
SIN Specification — Official specification
SIN Examples — Usage examples

License

Available as open source under the Apache License 2.0.