# In your Gemfile
gem "sashite-sin"

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

# 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"

# 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

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

# 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

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

# 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)

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

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

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