sashite-sin 2.1.0 → 3.0.0

data/README.md

@@ -1,17 +1,15 @@
-# Sin.rb
+# sin.rb
 
 [![Version](https://img.shields.io/github/v/tag/sashite/sin.rb?label=Version&logo=github)](https://github.com/sashite/sin.rb/tags)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/sin.rb/main)
-![Ruby](https://github.com/sashite/sin.rb/actions/workflows/main.yml/badge.svg?branch=main)
-[![License](https://img.shields.io/github/license/sashite/sin.rb?label=License&logo=github)](https://github.com/sashite/sin.rb/raw/main/LICENSE.md)
+[![CI](https://github.com/sashite/sin.rb/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/sashite/sin.rb/actions)
+[![License](https://img.shields.io/github/license/sashite/sin.rb?label=License&logo=github)](https://github.com/sashite/sin.rb/raw/main/LICENSE)
 
-> **SIN** (Style Identifier Notation) implementation for the Ruby language.
+> **SIN** (Style Identifier Notation) implementation for Ruby.
 
-## What is SIN?
+## Overview
 
-SIN (Style Identifier Notation) provides a compact, ASCII-based format for identifying **styles** in abstract strategy board games. SIN uses single-character identifiers with case encoding to represent both style identity and player assignment simultaneously.
-
-This gem implements the [SIN Specification v1.0.0](https://sashite.dev/specs/sin/1.0.0/) exactly, providing a rule-agnostic notation system for style identification in board games.
+This library implements the [SIN Specification v1.0.0](https://sashite.dev/specs/sin/1.0.0/).
 
 ## Installation
 
@@ -28,321 +26,205 @@ gem install sashite-sin
 
 ## Usage
 
-### Basic Operations
+### Parsing (String → Identifier)
+
+Convert a SIN string into an `Identifier` object.
 
 ```ruby
 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)
-```
+# Standard parsing (raises on error)
+sin = Sashite::Sin.parse("C")
+sin.style  # => :C
+sin.side   # => :first
 
-### Identifier Transformations
+# Lowercase indicates second player
+sin = Sashite::Sin.parse("c")
+sin.style  # => :C
+sin.side   # => :second
 
-```ruby
-# All transformations return new immutable instances
-identifier = Sashite::Sin.parse("C")
+# Invalid input raises ArgumentError
+Sashite::Sin.parse("")    # => raises ArgumentError
+Sashite::Sin.parse("CC")  # => raises ArgumentError
+```
 
-# Flip player assignment
-flipped = identifier.flip # Family=:C, Side=:second
-flipped.to_s # => "c"
+### Formatting (Identifier → String)
 
-# Change family
-changed = identifier.with_family(:S) # Family=:S, Side=:first
-changed.to_s # => "S"
+Convert an `Identifier` back to a SIN string.
 
-# Change side
-other_side = identifier.with_side(:second) # Family=:C, Side=:second
-other_side.to_s # => "c"
+```ruby
+# From Identifier object
+sin = Sashite::Sin::Identifier.new(:C, :first)
+sin.to_s  # => "C"
 
-# Chain transformations
-result = identifier.flip.with_family(:M) # Family=:M, Side=:second
-result.to_s # => "m"
+sin = Sashite::Sin::Identifier.new(:C, :second)
+sin.to_s  # => "c"
 ```
 
-### Player and Style Queries
+### Validation
 
 ```ruby
-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)
+# 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
 ```
 
-### Identifier Collections
+### Accessing Identifier Data
 
 ```ruby
-# 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"]
+sin = Sashite::Sin.parse("C")
 
-# Group by family
-by_family = identifiers.group_by(&:family)
-by_family[:C].size # => 2 (both C and c)
+# Get attributes
+sin.style  # => :C
+sin.side   # => :first
 
-# Find specific families
-chess_identifiers = identifiers.select { |i| i.family == :C }
-chess_identifiers.map(&:to_s) # => ["C", "c"]
+# Get string component
+sin.letter  # => "C"
 ```
 
-## Format Specification
+### Transformations
 
-### Structure
-```
-<style-letter>
-```
-
-### Grammar (BNF)
-```bnf
-<sin> ::= <uppercase-letter> | <lowercase-letter>
+All transformations return new immutable `Identifier` objects.
 
-<uppercase-letter> ::= "A" | "B" | "C" | ... | "Z"
-<lowercase-letter> ::= "a" | "b" | "c" | ... | "z"
-```
-
-### Regular Expression
 ```ruby
-/\A[A-Za-z]\z/
-```
+sin = Sashite::Sin.parse("C")
 
-### Style Attribute Mapping
+# Side transformation
+sin.flip.to_s  # => "c"
 
-SIN encodes style attributes using the following correspondence:
-
-| Style Attribute | SIN Encoding | Examples |
-|-----------------|--------------|----------|
-| **Family** | Style family symbol | `:C`, `:S`, `:X` |
-| **Side** | Player assignment | `:first`, `:second` |
-| **Letter** | Combined representation | `"C"`, `"c"`, `"S"`, `"s"` |
-
-#### Dual-Purpose Encoding
-
-The **Letter** combines two distinct semantic components:
-- **Style Family**: The underlying family symbol (:A-:Z), representing the game tradition or rule system
-- **Player Assignment**: The side (:first or :second), encoded as case in the letter representation
-
-**Examples**:
-- Family `:C` + Side `:first` → Letter `"C"` (Chess, First player)
-- Family `:C` + Side `:second` → Letter `"c"` (Chess, Second player)
-- Family `:S` + Side `:first` → Letter `"S"` (Shōgi, First player)
-- Family `:S` + Side `:second` → Letter `"s"` (Shōgi, Second player)
-
-## Traditional Game Style Examples
+# Attribute changes
+sin.with_style(:S).to_s  # => "S"
+sin.with_side(:second).to_s  # => "c"
+```
 
-The SIN specification is rule-agnostic and does not define specific letter assignments. However, here are common usage patterns following [SIN Examples](https://sashite.dev/specs/sin/1.0.0/examples/):
+### Queries
 
 ```ruby
-# 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 後手)
+sin = Sashite::Sin.parse("C")
 
-# Xiangqi (9×10 board)
-xiangqi_red = Sashite::Sin.parse("X")    # First player (Red pieces)
-xiangqi_black = Sashite::Sin.parse("x")  # Second player (Black pieces)
+# Side queries
+sin.first_player?   # => true
+sin.second_player?  # => false
 
-# 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 한)
+# Comparison queries
+other = Sashite::Sin.parse("c")
+sin.same_style?(other)  # => true
+sin.same_side?(other)   # => false
 ```
 
-## Cross-Style Scenarios
+## API Reference
+
+### Types
 
 ```ruby
-# 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
-  ]
+# Identifier represents a parsed SIN identifier with style and side.
+class Sashite::Sin::Identifier
+  # Creates an Identifier from style and side.
+  # Raises ArgumentError if attributes are invalid.
+  #
+  # @param style [Symbol] Style abbreviation (:A through :Z)
+  # @param side [Symbol] Player side (:first or :second)
+  # @return [Identifier]
+  def initialize(style, side)
+
+  # Returns the style as an uppercase symbol.
+  #
+  # @return [Symbol]
+  def style
+
+  # Returns the player side.
+  #
+  # @return [Symbol] :first or :second
+  def side
+
+  # Returns the SIN string representation.
+  #
+  # @return [String]
+  def to_s
 end
-
-identifiers = create_hybrid_match
-identifiers[0].same_side?(identifiers[1])    # => false (different players)
-identifiers[0].same_family?(identifiers[1])  # => false (different families)
 ```
 
-## System Constraints
-
-### Character Limitation
-SIN provides **26 possible identifiers** per player using ASCII letters (A-Z, a-z).
-
-### Player Limitation
-SIN supports exactly **two players** through case distinction:
-- **First player**: Uppercase letters (A-Z) → `:first`
-- **Second player**: Lowercase letters (a-z) → `:second`
-
-### Context Dependency
-The specific SIN assignment for a style may vary between different game contexts based on collision avoidance, historical precedence, and community conventions.
-
-## API Reference
-
-### Main Module Methods
-
-- `Sashite::Sin.valid?(sin_string)` - Check if string is valid SIN notation
-- `Sashite::Sin.parse(sin_string)` - Parse SIN string into Identifier object
-- `Sashite::Sin.identifier(family, side)` - Create identifier instance directly
-
-### Identifier Class
-
-#### Creation and Parsing
-- `Sashite::Sin::Identifier.new(family, side)` - Create identifier instance
-- `Sashite::Sin::Identifier.parse(sin_string)` - Parse SIN string
-
-#### Attribute Access
-- `#family` - Get style family (symbol :A through :Z)
-- `#side` - Get player side (:first or :second)
-- `#letter` - Get combined letter representation (string)
-- `#to_s` - Convert to SIN string representation
-
-#### Player Queries
-- `#first_player?` - Check if first player identifier
-- `#second_player?` - Check if second player identifier
-
-#### Transformations (immutable - return new instances)
-- `#flip` - Switch player assignment
-- `#with_family(new_family)` - Create identifier with different family
-- `#with_side(new_side)` - Create identifier with different side
-
-#### Comparison Methods
-- `#same_family?(other)` - Check if same style family
-- `#same_side?(other)` - Check if same player side
-- `#==(other)` - Full equality comparison
-- `#same_letter?(other)` - Alias for `same_family?` (deprecated)
-
 ### Constants
 
-- `Sashite::Sin::Identifier::FIRST_PLAYER` - Symbol for first player (`:first`)
-- `Sashite::Sin::Identifier::SECOND_PLAYER` - Symbol for second player (`:second`)
-- `Sashite::Sin::Identifier::VALID_FAMILIES` - Array of valid families (`:A` to `:Z`)
-- `Sashite::Sin::Identifier::VALID_SIDES` - Array of valid sides
-- `Sashite::Sin::Identifier::SIN_PATTERN` - Regular expression for SIN validation
-
-## Advanced Usage
+```ruby
+Sashite::Sin::Identifier::VALID_STYLES  # => [:A, :B, ..., :Z]
+Sashite::Sin::Identifier::VALID_SIDES   # => [:first, :second]
+```
 
-### Family and Side Separation
+### Parsing
 
 ```ruby
-# 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
+# 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)
 ```
 
-### Immutable Transformations
+### Validation
 
 ```ruby
-# 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"
+# Reports whether string is a valid SIN identifier.
+#
+# @param string [String] SIN string
+# @return [Boolean]
+def Sashite::Sin.valid?(string)
 ```
 
-## Design Properties
+### Transformations
 
-Following the SIN v1.0.0 specification, this implementation provides:
+All transformations return new `Sashite::Sin::Identifier` objects:
 
-- **ASCII compatibility**: Maximum portability across systems
-- **Rule-agnostic**: Independent of specific game mechanics
-- **Minimal overhead**: Single character per style-player combination
-- **Flexible collision resolution**: Systematic approaches for identifier conflicts
-- **Semantic clarity**: Distinct concepts for Family, Side, and Letter
-- **SNN coordination**: Works harmoniously with formal style naming
-- **Context-aware**: Adapts to avoid conflicts within specific game scenarios
-- **Canonical representation**: Each style-player combination has exactly one SIN identifier
-- **Immutable**: All identifier instances are frozen and transformations return new objects
-- **Functional**: Pure functions with no side effects
+```ruby
+# Side transformation
+def flip  # => Identifier
 
-## Related Specifications
+# Attribute changes
+def with_style(style)  # => Identifier
+def with_side(side)    # => Identifier
+```
 
-- [SIN Specification v1.0.0](https://sashite.dev/specs/sin/1.0.0/) - Complete technical specification
-- [SIN Examples](https://sashite.dev/specs/sin/1.0.0/examples/) - Practical implementation examples
-- [Style Name Notation (SNN)](https://sashite.dev/specs/snn/) - Formal naming for game styles
-- [Sashité Protocol](https://sashite.dev/protocol/) - Conceptual foundation for abstract strategy board games
+### Queries
 
-## Documentation
+```ruby
+# Side queries
+def first_player?   # => Boolean
+def second_player?  # => Boolean
 
-- [Official SIN Specification v1.0.0](https://sashite.dev/specs/sin/1.0.0/)
-- [SIN Examples Documentation](https://sashite.dev/specs/sin/1.0.0/examples/)
-- [API Documentation](https://rubydoc.info/github/sashite/sin.rb/main)
+# Comparison queries
+def same_style?(other)  # => Boolean
+def same_side?(other)   # => Boolean
+```
 
-## Development
+### Errors
 
-```sh
-# Clone the repository
-git clone https://github.com/sashite/sin.rb.git
-cd sin.rb
+All parsing and validation errors raise `ArgumentError` with descriptive messages:
 
-# Install dependencies
-bundle install
+| 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 |
 
-# Run tests
-ruby test.rb
+## Design Principles
 
-# Generate documentation
-yard doc
-```
+- **Bounded values**: Explicit validation of styles and sides
+- **Object-oriented**: `Identifier` class enables methods and encapsulation
+- **Ruby idioms**: `valid?` predicate, `to_s` conversion, `ArgumentError` for invalid input
+- **Immutable identifiers**: All transformations return new objects
+- **No dependencies**: Pure Ruby standard library only
 
-## License
+## Related Specifications
 
-Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
+- [Game Protocol](https://sashite.dev/game-protocol/) — Conceptual foundation
+- [SIN Specification](https://sashite.dev/specs/sin/1.0.0/) — Official specification
+- [SIN Examples](https://sashite.dev/specs/sin/1.0.0/examples/) — Usage examples
 
-## About
+## License
 
-Maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of board game cultures.
+Available as open source under the [Apache License 2.0](https://opensource.org/licenses/Apache-2.0).

data/lib/sashite/sin/constants.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Sin
+    # Constants for the SIN (Style Identifier Notation) specification.
+    #
+    # Defines valid values for styles and sides, as well as formatting constants.
+    #
+    # @example Accessing valid styles
+    #   Constants::VALID_STYLES  # => [:A, :B, ..., :Z]
+    #
+    # @example Accessing valid sides
+    #   Constants::VALID_SIDES  # => [:first, :second]
+    #
+    # @see https://sashite.dev/specs/sin/1.0.0/
+    module Constants
+      # Valid style symbols (A-Z as uppercase symbols).
+      #
+      # @return [Array<Symbol>] Array of 26 valid style symbols
+      VALID_STYLES = %i[A B C D E F G H I J K L M N O P Q R S T U V W X Y Z].freeze
+
+      # Valid side symbols.
+      #
+      # @return [Array<Symbol>] Array of valid side symbols
+      VALID_SIDES = %i[first second].freeze
+
+      # Maximum length of a valid SIN string.
+      #
+      # @return [Integer] Maximum string length (1)
+      MAX_STRING_LENGTH = 1
+
+      # Empty string constant for internal use.
+      #
+      # @return [String] Empty string
+      EMPTY_STRING = ""
+    end
+  end
+end

data/lib/sashite/sin/errors/argument/messages.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Sin
+    module Errors
+      class Argument < ::ArgumentError
+        # Error messages for SIN parsing and validation.
+        #
+        # Provides centralized, immutable error message constants for consistent
+        # error reporting across the library.
+        #
+        # @example Using an error message
+        #   raise ArgumentError, Messages::EMPTY_INPUT
+        #
+        # @see https://sashite.dev/specs/sin/1.0.0/
+        module Messages
+          # Error message for empty input string.
+          #
+          # @return [String] Error message
+          EMPTY_INPUT = "empty input"
+
+          # Error message for input exceeding maximum length.
+          #
+          # @return [String] Error message
+          INPUT_TOO_LONG = "input exceeds 1 character"
+
+          # Error message for invalid character (not a letter).
+          #
+          # @return [String] Error message
+          MUST_BE_LETTER = "must be a letter"
+
+          # Error message for invalid style value.
+          #
+          # @return [String] Error message
+          INVALID_STYLE = "invalid style"
+
+          # Error message for invalid side value.
+          #
+          # @return [String] Error message
+          INVALID_SIDE = "invalid side"
+        end
+      end
+    end
+  end
+end

data/lib/sashite/sin/errors/argument.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "argument/messages"
+
+module Sashite
+  module Sin
+    module Errors
+      # Namespace for ArgumentError-related constants and messages.
+      #
+      # Provides structured access to error messages used when raising
+      # ArgumentError exceptions throughout the library.
+      #
+      # @example Raising an error with a message
+      #   raise ArgumentError, Argument::Messages::EMPTY_INPUT
+      #
+      # @see Argument::Messages
+      class Argument < ::ArgumentError
+      end
+    end
+  end
+end

data/lib/sashite/sin/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "errors/argument"
+
+module Sashite
+  module Sin
+    # Namespace for error-related constants and messages.
+    #
+    # Provides structured access to error messages used throughout the library.
+    #
+    # @example Accessing error messages
+    #   Errors::Argument::Messages::EMPTY_INPUT  # => "empty input"
+    #
+    # @see Errors::Argument
+    # @see Errors::Argument::Messages
+    module Errors
+    end
+  end
+end