sashite-snn 3.1.0 → 4.0.0

data/README.md

@@ -1,21 +1,23 @@
-# Snn.rb
+# snn.rb
 
 [![Version](https://img.shields.io/github/v/tag/sashite/snn.rb?label=Version&logo=github)](https://github.com/sashite/snn.rb/tags)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/snn.rb/main)
-![Ruby](https://github.com/sashite/snn.rb/actions/workflows/main.yml/badge.svg?branch=main)
-[![License](https://img.shields.io/github/license/sashite/snn.rb?label=License&logo=github)](https://github.com/sashite/snn.rb/raw/main/LICENSE.md)
+[![CI](https://github.com/sashite/snn.rb/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/sashite/snn.rb/actions)
+[![License](https://img.shields.io/github/license/sashite/snn.rb)](https://github.com/sashite/snn.rb/blob/main/LICENSE)
 
-> **SNN** (Style Name Notation) implementation for the Ruby language.
+> **SNN** (Style Name Notation) implementation for Ruby.
 
-## What is SNN?
+## Overview
 
-SNN (Style Name Notation) is a **foundational**, human-readable naming system for identifying game styles in abstract strategy board games. SNN serves as a primitive building block using descriptive alphabetic names with case encoding to represent style identity and player assignment.
+This library implements the [SNN Specification v1.0.0](https://sashite.dev/specs/snn/1.0.0/).
 
-Each SNN name is a case-consistent alphabetic identifier where:
-- **Uppercase names** (e.g., `CHESS`, `SHOGI`) represent the **first player's** style
-- **Lowercase names** (e.g., `chess`, `shogi`) represent the **second player's** style
+### Implementation Constraints
 
-This gem implements the [SNN Specification v1.0.0](https://sashite.dev/specs/snn/1.0.0/) as a foundational primitive with no dependencies.
+| Constraint | Value | Rationale |
+|------------|-------|-----------|
+| Max string length | 32 | Sufficient for realistic style names |
+
+These constraints enable bounded memory usage and safe parsing.
 
 ## Installation
 
@@ -30,352 +32,138 @@ Or install manually:
 gem install sashite-snn
 ```
 
-## Quick Start
-
-```ruby
-require "sashite/snn"
-
-# Parse SNN strings into style name objects
-name = Sashite::Snn.parse("SHOGI")             # => #<Snn::Name value="SHOGI">
-name.to_s                                      # => "SHOGI"
-name.value                                     # => "SHOGI"
-
-# Create from string or symbol
-name = Sashite::Snn.name("CHESS")              # => #<Snn::Name value="CHESS">
-name = Sashite::Snn::Name.new(:xiangqi)        # => #<Snn::Name value="xiangqi">
-
-# Validate SNN strings
-Sashite::Snn.valid?("MAKRUK")                  # => true
-Sashite::Snn.valid?("shogi")                   # => true
-Sashite::Snn.valid?("Chess")                   # => false (mixed case)
-Sashite::Snn.valid?("Chess960")                # => false (contains digits)
-```
-
-## SNN Format
-
-An SNN string consists of alphabetic characters only, all in the same case:
-
-```
-<alphabetic-name>
-```
-
-**Examples:**
-- `CHESS` — Chess style for first player
-- `chess` — Chess style for second player
-- `SHOGI` — Shōgi style for first player
-- `shogi` — Shōgi style for second player
-
-## Format Specification
-
-### Structure
-
-```
-<alphabetic-name>
-```
-
-Where the name directly represents the style identity and player assignment through case.
-
-### Grammar (BNF)
+## Usage
 
-```bnf
-<snn> ::= <uppercase-name> | <lowercase-name>
+### Parsing (String → StyleName)
 
-<uppercase-name> ::= <uppercase-letter>+
-<lowercase-name> ::= <lowercase-letter>+
-
-<uppercase-letter> ::= "A" | "B" | "C" | ... | "Z"
-<lowercase-letter> ::= "a" | "b" | "c" | ... | "z"
-```
-
-### Regular Expression
+Convert an SNN string into a `StyleName` object.
 
 ```ruby
-/\A([A-Z]+|[a-z]+)\z/
-```
-
-### Constraints
-
-1. **Case consistency**: All letters must be either uppercase OR lowercase
-2. **Alphabetic only**: Only ASCII letters allowed (no digits, no special characters)
-3. **Direct assignment**: Names represent styles through explicit association
-
-## API Reference
-
-### Module Methods
-
-#### `Sashite::Snn.valid?(string)`
+require "sashite/snn"
 
-Returns `true` if the string is valid SNN notation.
+# Standard parsing (raises on error)
+snn = Sashite::Snn.parse("Chess")
+snn.name  # => "Chess"
 
-- **Parameter**: `string` (String) - String to validate
-- **Returns**: `Boolean` - `true` if valid, `false` otherwise
+# With numeric suffix
+snn = Sashite::Snn.parse("Chess960")
+snn.name  # => "Chess960"
 
-```ruby
-Sashite::Snn.valid?("CHESS")      # => true
-Sashite::Snn.valid?("shogi")      # => true
-Sashite::Snn.valid?("Chess")      # => false (mixed case)
-Sashite::Snn.valid?("CHESS960")   # => false (contains digits)
-Sashite::Snn.valid?("3DChess")    # => false (starts with digit)
+# Invalid input raises ArgumentError
+Sashite::Snn.parse("chess")  # => raises ArgumentError, "invalid format"
+Sashite::Snn.parse("")       # => raises ArgumentError, "empty input"
 ```
 
-#### `Sashite::Snn.parse(string)`
-
-Parses an SNN string into a `Name` object.
+### Formatting (StyleName → String)
 
-- **Parameter**: `string` (String) - SNN notation string
-- **Returns**: `Name` - Immutable name object
-- **Raises**: `ArgumentError` if the string is invalid
+Convert a `StyleName` back to an SNN string.
 
 ```ruby
-name = Sashite::Snn.parse("SHOGI")    # => #<Snn::Name value="SHOGI">
-name = Sashite::Snn.parse("chess")    # => #<Snn::Name value="chess">
-```
-
-#### `Sashite::Snn.name(value)`
+# From StyleName object
+snn = Sashite::Snn::StyleName.new("Chess")
+snn.to_s  # => "Chess"
 
-Creates a new `Name` instance directly.
-
-- **Parameter**: `value` (String, Symbol) - Style name to construct
-- **Returns**: `Name` - New name instance
-- **Raises**: `ArgumentError` if name format is invalid
-
-```ruby
-Sashite::Snn.name("XIANGQI")  # => #<Snn::Name value="XIANGQI">
-Sashite::Snn.name(:makruk)    # => #<Snn::Name value="makruk">
+# String interpolation
+"Playing #{snn}"  # => "Playing Chess"
 ```
 
-### Name Object
-
-The `Name` object is immutable and provides read-only access to the style name:
+### Validation
 
 ```ruby
-name = Sashite::Snn.parse("SHOGI")
-
-name.value    # => "SHOGI"
-name.to_s     # => "SHOGI"
-name.frozen?  # => true
+# Boolean check
+Sashite::Snn.valid?("Chess")     # => true
+Sashite::Snn.valid?("Chess960")  # => true
+Sashite::Snn.valid?("chess")     # => false (lowercase start)
+Sashite::Snn.valid?("")          # => false (empty)
 ```
 
-**Equality and hashing:**
-```ruby
-name1 = Sashite::Snn.parse("CHESS")
-name2 = Sashite::Snn.parse("CHESS")
-name3 = Sashite::Snn.parse("chess")
-
-name1 == name2 # => true
-name1.hash == name2.hash # => true
-name1 == name3 # => false (different case = different player)
-```
-
-## Examples
-
-### Traditional Chess Family
+### Accessing Data
 
 ```ruby
-# First player styles (uppercase)
-chess = Sashite::Snn.parse("CHESS")      # Western Chess
-shogi = Sashite::Snn.parse("SHOGI")      # Japanese Chess
-xiangqi = Sashite::Snn.parse("XIANGQI")  # Chinese Chess
-makruk = Sashite::Snn.parse("MAKRUK")    # Thai Chess
-
-# Second player styles (lowercase)
-chess_p2 = Sashite::Snn.parse("chess")
-shogi_p2 = Sashite::Snn.parse("shogi")
-```
-
-### Historical Games
+snn = Sashite::Snn.parse("Chess960")
 
-```ruby
-chaturanga = Sashite::Snn.parse("CHATURANGA")  # Ancient Indian Chess
-shatranj = Sashite::Snn.parse("SHATRANJ")      # Medieval Islamic Chess
+# Get the name (attribute)
+snn.name  # => "Chess960"
 ```
 
-### Modern Variants
-
-```ruby
-raumschach = Sashite::Snn.parse("RAUMSCHACH")  # 3D Chess
-omega = Sashite::Snn.parse("OMEGA")            # Omega Chess
-```
+## API Reference
 
-### Case Consistency
+### Types
 
 ```ruby
-# Valid - all uppercase
-Sashite::Snn.valid?("CHESS")      # => true
-Sashite::Snn.valid?("XIANGQI")    # => true
-
-# Valid - all lowercase
-Sashite::Snn.valid?("shogi")      # => true
-Sashite::Snn.valid?("makruk")     # => true
-
-# Invalid - mixed case
-Sashite::Snn.valid?("Chess")      # => false
-Sashite::Snn.valid?("Shogi")      # => false
-Sashite::Snn.valid?("XiangQi")    # => false
-
-# Invalid - contains non-alphabetic characters
-Sashite::Snn.valid?("CHESS960")   # => false
-Sashite::Snn.valid?("GO9X9")      # => false
-Sashite::Snn.valid?("MINI_SHOGI") # => false
-```
+# StyleName represents a validated SNN style name.
+class Sashite::Snn::StyleName
+  # Creates a StyleName from a valid name string.
+  # Raises ArgumentError if the name is invalid.
+  #
+  # @param name [String] SNN style name
+  # @return [StyleName]
+  def initialize(name)
 
-### Working with Names
+  # Returns the style name.
+  #
+  # @return [String]
+  def name
 
-```ruby
-# Create and compare
-name1 = Sashite::Snn.parse("SHOGI")
-name2 = Sashite::Snn.parse("SHOGI")
-name1 == name2 # => true
-
-# String and symbol inputs
-name1 = Sashite::Snn.name("XIANGQI")
-name2 = Sashite::Snn.name(:XIANGQI)
-name1 == name2 # => true
-
-# Immutability
-name = Sashite::Snn.parse("CHESS")
-name.frozen?        # => true
-name.value.frozen?  # => true
+  # Returns the SNN string representation.
+  #
+  # @return [String]
+  def to_s
+end
 ```
 
-### Collections
+### Constants
 
 ```ruby
-# Create a set of styles
-styles = %w[CHESS SHOGI XIANGQI MAKRUK].map { |n| Sashite::Snn.parse(n) }
-
-# Filter by prefix
-styles.select { |s| s.value.start_with?("X") }.map(&:to_s)
-# => ["XIANGQI"]
-
-# Use in hash
-style_map = {
-  Sashite::Snn.parse("CHESS") => "Western Chess",
-  Sashite::Snn.parse("SHOGI") => "Japanese Chess"
-}
+Sashite::Snn::StyleName::MAX_STRING_LENGTH  # => 32
 ```
 
-## Relationship with SIN
-
-**SNN and SIN are independent primitives** that serve complementary roles:
-
-- **SNN**: Human-readable, descriptive names (`CHESS`, `SHOGI`)
-- **SIN**: Compact, single-character identification (`C`, `S`)
-
-### Optional Correspondence
-
-While both specifications can be used independently, they may be related through:
-
-- **Mapping tables**: External context defining SNN ↔ SIN relationships
-- **Case consistency**: When mapped, case must be preserved (`CHESS` ↔ `C`, `chess` ↔ `c`)
+### Parsing
 
 ```ruby
-# Example mapping (defined externally, not part of SNN)
-SNN_TO_SIN = {
-  "CHESS" => "C",
-  "chess" => "c",
-  "SHOGI" => "S",
-  "shogi" => "s"
-}
-
-# Multiple SNN names may map to the same SIN
-SNN_TO_SIN["CAPABLANCA"] = "C"  # Also maps to "C"
-SNN_TO_SIN["COURIER"] = "C"     # Also maps to "C"
+# Parses an SNN string into a StyleName.
+# Raises ArgumentError if the string is not valid.
+#
+# @param string [String] SNN style name string
+# @return [StyleName]
+# @raise [ArgumentError] if invalid
+def Sashite::Snn.parse(string)
 ```
 
-### Important Notes
-
-1. **No dependency**: SNN does not depend on SIN, nor SIN on SNN
-2. **Bidirectional mapping requires context**: Converting between SNN and SIN requires external mapping information
-3. **Independent usage**: Systems may use SNN alone, SIN alone, or both with defined mappings
-4. **Multiple mappings**: One SNN name may correspond to multiple SIN characters in different contexts, and vice versa
-
-## Error Handling
+### Validation
 
 ```ruby
-begin
-  name = Sashite::Snn.parse("Chess960")
-rescue ArgumentError => e
-  warn "Invalid SNN: #{e.message}"
-  # => "Invalid SNN string: \"Chess960\""
-end
+# Reports whether string is a valid SNN style name.
+#
+# @param string [String] SNN style name string
+# @return [Boolean]
+def Sashite::Snn.valid?(string)
 ```
 
-### Common Errors
-
-```ruby
-# Mixed case
-Sashite::Snn.parse("Chess")
-# => ArgumentError: Invalid SNN string: "Chess"
-
-# Contains digits
-Sashite::Snn.parse("CHESS960")
-# => ArgumentError: Invalid SNN string: "CHESS960"
+### Errors
 
-# Contains special characters
-Sashite::Snn.parse("MINI_SHOGI")
-# => ArgumentError: Invalid SNN string: "MINI_SHOGI"
+All parsing and validation errors raise `ArgumentError` with descriptive messages:
 
-# Empty string
-Sashite::Snn.parse("")
-# => ArgumentError: Invalid SNN string: ""
-```
+| Message | Cause |
+|---------|-------|
+| `"empty input"` | String length is 0 |
+| `"input too long"` | String exceeds 32 characters |
+| `"invalid format"` | Does not match SNN format |
 
 ## Design Principles
 
-- **Human-readable**: Descriptive names for better usability
-- **Case-consistent**: Visual distinction between players through case
-- **Foundational primitive**: Serves as building block for formal style identification
-- **Rule-agnostic**: Independent of specific game mechanics
-- **Self-contained**: No external dependencies
-- **Immutable**: All objects are frozen and thread-safe
-- **Canonical**: Each style has one valid representation per context
-
-## Properties
-
-- **Purely functional**: Immutable data structures, no side effects
-- **Specification compliant**: Strict adherence to [SNN v1.0.0](https://sashite.dev/specs/snn/1.0.0/)
-- **Minimal API**: Simple validation, parsing, and comparison
-- **Universal**: Supports any abstract strategy board game style
-- **No dependencies**: Foundational primitive requiring no external gems
-
-## Documentation
+- **Bounded values**: Maximum string length prevents resource exhaustion
+- **Object-oriented**: `StyleName` class enables methods and encapsulation
+- **Ruby idioms**: `valid?` predicate, `to_s` conversion, `ArgumentError` for invalid input
+- **Immutable style names**: `freeze` after construction
+- **No dependencies**: Pure Ruby standard library only
 
-- [SNN Specification v1.0.0](https://sashite.dev/specs/snn/1.0.0/) — Complete technical specification
-- [SNN Examples](https://sashite.dev/specs/snn/1.0.0/examples/) — Comprehensive examples
-- [API Documentation](https://rubydoc.info/github/sashite/snn.rb/main) — Full API reference
+## Related Specifications
 
-## Development
-
-```sh
-# Clone the repository
-git clone https://github.com/sashite/snn.rb.git
-cd snn.rb
-
-# Install dependencies
-bundle install
-
-# Run tests
-ruby test.rb
-
-# Generate documentation
-yard doc
-```
-
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/new-feature`)
-3. Add tests for your changes
-4. Ensure all tests pass (`ruby test.rb`)
-5. Commit your changes (`git commit -am 'Add new feature'`)
-6. Push to the branch (`git push origin feature/new-feature`)
-7. Create a Pull Request
+- [Game Protocol](https://sashite.dev/game-protocol/) — Conceptual foundation
+- [SNN Specification](https://sashite.dev/specs/snn/1.0.0/) — Official specification
+- [SNN Examples](https://sashite.dev/specs/snn/1.0.0/examples/) — Usage examples
 
 ## License
 
-Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
-
-## About
-
-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/snn/constants.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Snn
+    # Constants for the SNN (Style Name Notation) specification.
+    #
+    # Defines validation constraints for SNN tokens.
+    #
+    # @example
+    #   Sashite::Snn::Constants::MAX_STRING_LENGTH  # => 32
+    #
+    # @see https://sashite.dev/specs/snn/1.0.0/
+    module Constants
+      # Maximum length of a valid SNN string.
+      #
+      # @return [Integer] 32
+      MAX_STRING_LENGTH = 32
+
+      # Empty string constant for internal use.
+      #
+      # @return [String] ""
+      EMPTY_STRING = ""
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Snn
+    module Errors
+      class Argument < ::ArgumentError
+        # Error messages for SNN parsing and validation.
+        #
+        # @example
+        #   Messages::EMPTY_INPUT       # => "empty input"
+        #   Messages::INPUT_TOO_LONG    # => "input too long"
+        #   Messages::INVALID_FORMAT    # => "invalid format"
+        module Messages
+          # Parsing error messages.
+
+          # Error message for empty input string.
+          EMPTY_INPUT = "empty input"
+
+          # Error message for input exceeding maximum length.
+          INPUT_TOO_LONG = "input too long"
+
+          # Error message for invalid SNN format.
+          INVALID_FORMAT = "invalid format"
+        end
+      end
+    end
+  end
+end

data/lib/sashite/snn/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/snn/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "errors/argument"
+
+module Sashite
+  module Snn
+    # Namespace for SNN error classes.
+    module Errors
+    end
+  end
+end