sashite-snn 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 517b0310bd57b5d0b931a5f14eb1c4d6257bbd6d4f215c467ff475c8b42542fc
-  data.tar.gz: 2fa5a177d6350dd2501b87eac5a567f5cf48c681439b3af23f2bae1df99579a3
+  metadata.gz: 1528b909fb1159a1b9d3fb06e4b62114efa110d991226945024f442fb08501e9
+  data.tar.gz: 3c6c44c3d69d1eacad6141d9309a27e5972dde45067bc8272e9584ed6cfc56ee
 SHA512:
-  metadata.gz: 200ef38765b8c581f93c51657699e4b420c26abe1d355227ff47892b493f787ec9c03e7202a91b9466c99c97a95a1b914837e59bb2784ef6568cc2ca3f94dd49
-  data.tar.gz: 6b01e73ad4e61246e8e61a4e0bd85f7b3f0fcb964f7532c42d6c95a2b5b665c64487e032e46cb7b77806b3a410137536812aac3278428b2c31af8d91811597ec
+  metadata.gz: fc20688ee514ec76125132aba5b121aa4b705230eb716f2abee6c5c1a88978aadfa52bf8cfa1c870315284050808f5fe5903a5e141c760af92f7aaca9bac82d5
+  data.tar.gz: b44e7af48ae53d52ca2b1961831b5eca677c2b8182589062139af966d3e960f0638720fba33c7e9099b6a8fe9424124f49386e3c9b025e71f93edfb797e9e558

data/README.md

@@ -9,16 +9,20 @@
 
 ## What is SNN?
 
-SNN (Style Name Notation) is a formal, rule-agnostic naming system for identifying **styles** in abstract strategy board games such as chess, shōgi, xiangqi, and their many variants. Each style is represented by a canonical, human-readable ASCII name (e.g., `"Chess"`, `"Shogi"`, `"Xiangqi"`, `"Minishogi"`).
+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 gem implements the [SNN Specification v1.0.0](https://sashite.dev/specs/snn/1.0.0/), supporting validation, parsing, and comparison of style names.
+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
+
+This gem implements the [SNN Specification v1.0.0](https://sashite.dev/specs/snn/1.0.0/) as a foundational primitive with no dependencies.
 
 ## Installation
 
 ```ruby
 # In your Gemfile
 gem "sashite-snn"
-````
+```
 
 Or install manually:
 
@@ -26,130 +30,320 @@ Or install manually:
 gem install sashite-snn
 ```
 
-## Usage
-
-### Basic Operations
+## 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"
+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">
+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?("Go9x9")                   # => true
-Sashite::Snn.valid?("chess")                   # => false (must start with uppercase)
-Sashite::Snn.valid?("3DChess")                 # => false (invalid character)
+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)
+
+```bnf
+<snn> ::= <uppercase-name> | <lowercase-name>
+
+<uppercase-name> ::= <uppercase-letter>+
+<lowercase-name> ::= <lowercase-letter>+
+
+<uppercase-letter> ::= "A" | "B" | "C" | ... | "Z"
+<lowercase-letter> ::= "a" | "b" | "c" | ... | "z"
 ```
 
-### Normalization and Comparison
+### Regular Expression
 
 ```ruby
-a = Sashite::Snn.parse("Chess960")
-b = Sashite::Snn.parse("Chess960")
+/\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
 
-a == b                                         # => true
-a.same_base_name?(Sashite::Snn.parse("Chess")) # => true if both resolve to same SIN
-a.to_s # => "Chess960"
+#### `Sashite::Snn.valid?(string)`
+
+Returns `true` if the string is valid SNN notation.
+
+- **Parameter**: `string` (String) - String to validate
+- **Returns**: `Boolean` - `true` if valid, `false` otherwise
+
+```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)
 ```
 
-### Canonical Representation
+#### `Sashite::Snn.parse(string)`
+
+Parses an SNN string into a `Name` object.
+
+- **Parameter**: `string` (String) - SNN notation string
+- **Returns**: `Name` - Immutable name object
+- **Raises**: `ArgumentError` if the string is invalid
 
 ```ruby
-# All names are normalized to a canonical format
-name = Sashite::Snn.parse("Minishogi")
-name.value                                    # => "Minishogi"
-name.to_s                                     # => "Minishogi"
+name = Sashite::Snn.parse("SHOGI")    # => #<Snn::Name value="SHOGI">
+name = Sashite::Snn.parse("chess")    # => #<Snn::Name value="chess">
 ```
 
-### Collections and Filtering
+#### `Sashite::Snn.name(value)`
+
+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
-names = %w[Chess Shogi Makruk Antichess Minishogi].map { |n| Sashite::Snn.parse(n) }
+Sashite::Snn.name("XIANGQI")  # => #<Snn::Name value="XIANGQI">
+Sashite::Snn.name(:makruk)    # => #<Snn::Name value="makruk">
+```
 
-# Filter by prefix
-names.select { |n| n.value.start_with?("Mini") }.map(&:to_s)
-# => ["Minishogi"]
+### Name Object
+
+The `Name` object is immutable and provides read-only access to the style name:
+
+```ruby
+name = Sashite::Snn.parse("SHOGI")
+
+name.value    # => "SHOGI"
+name.to_s     # => "SHOGI"
+name.frozen?  # => true
 ```
 
-## Format Specification
+**Equality and hashing:**
+```ruby
+name1 = Sashite::Snn.parse("CHESS")
+name2 = Sashite::Snn.parse("CHESS")
+name3 = Sashite::Snn.parse("chess")
 
-### Structure
+name1 == name2 # => true
+name1.hash == name2.hash # => true
+name1 == name3 # => false (different case = different player)
+```
+
+## Examples
 
+### Traditional Chess Family
+
+```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")
 ```
-<uppercase-letter>[<lowercase-letter | digit>]*
+
+### Historical Games
+
+```ruby
+chaturanga = Sashite::Snn.parse("CHATURANGA")  # Ancient Indian Chess
+shatranj = Sashite::Snn.parse("SHATRANJ")      # Medieval Islamic Chess
 ```
 
-### Grammar (BNF)
+### Modern Variants
 
-```bnf
-<snn> ::= <uppercase-letter> <tail>
+```ruby
+raumschach = Sashite::Snn.parse("RAUMSCHACH")  # 3D Chess
+omega = Sashite::Snn.parse("OMEGA")            # Omega Chess
+```
 
-<tail> ::= ""                                ; Single letter (e.g., "X")
-        | <alphanumeric-char> <tail>         ; Extended name
+### Case Consistency
 
-<alphanumeric-char> ::= <lowercase-letter> | <digit>
+```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
+```
 
-<uppercase-letter> ::= "A" | "B" | "C" | ... | "Z"
-<lowercase-letter> ::= "a" | "b" | "c" | ... | "z"
-<digit> ::= "0" | "1" | "2" | "3" | ... | "9"
+### Working with Names
+
+```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
 ```
 
-### Regular Expression
+### Collections
 
 ```ruby
-/\A[A-Z][a-z0-9]*\z/
+# 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"
+}
 ```
 
-## Design Principles
+## Relationship with SIN
 
-* **Human-readable**: Names like `"Shogi"` or `"Chess960"` are intuitive and descriptive.
-* **Canonical**: One valid name per game style within a given context.
-* **ASCII-only**: Compatible with all systems.
-* **Scalable**: Supports unlimited distinct names for current and future game variants.
+**SNN and SIN are independent primitives** that serve complementary roles:
 
-## Integration with SIN
+- **SNN**: Human-readable, descriptive names (`CHESS`, `SHOGI`)
+- **SIN**: Compact, single-character identification (`C`, `S`)
 
-SNN names serve as the formal source for SIN character identifiers. For example:
+### Optional Correspondence
 
-| SNN       | SIN     |
-| --------- | ------- |
-| `Chess`   | `C`/`c` |
-| `Shogi`   | `S`/`s` |
-| `Xiangqi` | `X`/`x` |
-| `Makruk`  | `M`/`m` |
+While both specifications can be used independently, they may be related through:
 
-Multiple SNN names may map to the same SIN character (e.g., `"Chess"` and `"Chess960"` both → `C`), but SNN provides unambiguous naming within broader contexts.
+- **Mapping tables**: External context defining SNN ↔ SIN relationships
+- **Case consistency**: When mapped, case must be preserved (`CHESS` ↔ `C`, `chess` ↔ `c`)
 
-## Examples
+```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"
+```
+
+### 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
 
 ```ruby
-Sashite::Snn.parse("Chess")       # => #<Snn::Name value="Chess">
-Sashite::Snn.parse("Chess960")    # => #<Snn::Name value="Chess960">
-Sashite::Snn.valid?("Minishogi")  # => true
-Sashite::Snn.valid?("miniShogi")  # => false
+begin
+  name = Sashite::Snn.parse("Chess960")
+rescue ArgumentError => e
+  warn "Invalid SNN: #{e.message}"
+  # => "Invalid SNN string: \"Chess960\""
+end
 ```
 
-## API Reference
+### 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"
+
+# Contains special characters
+Sashite::Snn.parse("MINI_SHOGI")
+# => ArgumentError: Invalid SNN string: "MINI_SHOGI"
+
+# Empty string
+Sashite::Snn.parse("")
+# => ArgumentError: Invalid SNN string: ""
+```
+
+## 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
 
-### Main Module
+## Properties
 
-* `Sashite::Snn.valid?(str)` – Returns `true` if the string is valid SNN.
-* `Sashite::Snn.parse(str)` – Returns a `Sashite::Snn::Name` object.
-* `Sashite::Snn.name(sym_or_str)` – Alias for constructing a name.
+- **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
 
-### `Sashite::Snn::Name`
+## Documentation
 
-* `#value` – Returns the canonical string value.
-* `#to_s` – Returns the string representation.
-* `#==`, `#eql?`, `#hash` – Value-based equality.
-* `#same_base_name?(other)` – Optional helper for SIN mapping equivalence.
+- [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
 
 ## Development
 

data/lib/sashite/snn/name.rb

@@ -4,16 +4,36 @@ module Sashite
   module Snn
     # Represents a style name in SNN (Style Name Notation) format.
     #
-    # SNN provides a canonical naming system for abstract strategy game styles.
-    # Each name must start with an uppercase ASCII letter, followed by zero or more
-    # lowercase letters or digits.
+    # SNN provides a foundational naming system for abstract strategy game styles.
+    # Each name must consist of alphabetic characters only, all in the same case
+    # (either all uppercase or all lowercase).
+    #
+    # Case encoding:
+    #   - UPPERCASE names represent the first player's style
+    #   - lowercase names represent the second player's style
+    #
+    # Constraints:
+    #   - Alphabetic characters only (A-Z or a-z)
+    #   - Case consistency required (all uppercase OR all lowercase)
+    #   - No digits, no special characters, no mixed case
     #
     # All instances are immutable.
+    #
+    # @example Valid names
+    #   Sashite::Snn::Name.new("CHESS")    # => #<Snn::Name value="CHESS">
+    #   Sashite::Snn::Name.new("shogi")    # => #<Snn::Name value="shogi">
+    #   Sashite::Snn::Name.new("XIANGQI")  # => #<Snn::Name value="XIANGQI">
+    #
+    # @example Invalid names
+    #   Sashite::Snn::Name.new("Chess")    # => ArgumentError (mixed case)
+    #   Sashite::Snn::Name.new("CHESS960") # => ArgumentError (contains digits)
+    #   Sashite::Snn::Name.new("GO9X9")    # => ArgumentError (contains digits)
     class Name
       # SNN validation pattern matching the specification
-      SNN_PATTERN = /\A[A-Z][a-z0-9]*\z/
+      # Format: All uppercase OR all lowercase alphabetic characters
+      SNN_PATTERN = /\A([A-Z]+|[a-z]+)\z/
 
-      # Error messages
+      # Error message for invalid SNN strings
       ERROR_INVALID_NAME = "Invalid SNN string: %s"
 
       # @return [String] the canonical style name
@@ -21,8 +41,20 @@ module Sashite
 
       # Create a new style name instance
       #
-      # @param name [String, Symbol] the style name (e.g., "Shogi", :Chess960)
+      # The name must follow SNN format rules: all uppercase or all lowercase
+      # alphabetic characters only. No digits, special characters, or mixed case.
+      #
+      # @param name [String, Symbol] the style name (e.g., "SHOGI", :chess)
       # @raise [ArgumentError] if the name does not match SNN pattern
+      #
+      # @example Create valid names
+      #   Sashite::Snn::Name.new("CHESS")    # First player Chess
+      #   Sashite::Snn::Name.new("shogi")    # Second player Shōgi
+      #   Sashite::Snn::Name.new(:XIANGQI)   # First player Xiangqi
+      #
+      # @example Invalid names raise errors
+      #   Sashite::Snn::Name.new("Chess")    # Mixed case
+      #   Sashite::Snn::Name.new("CHESS960") # Contains digits
       def initialize(name)
         string_value = name.to_s
         self.class.validate_format(string_value)
@@ -33,57 +65,103 @@ module Sashite
 
       # Parse an SNN string into a Name object
       #
+      # This is an alias for the constructor, provided for consistency
+      # with other Sashité specifications.
+      #
       # @param string [String] the SNN-formatted style name
       # @return [Name] a new Name instance
       # @raise [ArgumentError] if the string is invalid
       #
-      # @example
-      #   Sashite::Snn::Name.parse("Shogi") # => #<Snn::Name value="Shogi">
+      # @example Parse valid names
+      #   Sashite::Snn::Name.parse("SHOGI") # => #<Snn::Name value="SHOGI">
+      #   Sashite::Snn::Name.parse("chess") # => #<Snn::Name value="chess">
       def self.parse(string)
         new(string)
       end
 
       # Check whether the given string is a valid SNN name
       #
+      # Valid SNN strings must:
+      #   - Contain only alphabetic characters (A-Z or a-z)
+      #   - Have consistent case (all uppercase OR all lowercase)
+      #   - Contain at least one character
+      #
       # @param string [String] input string to validate
       # @return [Boolean] true if valid, false otherwise
       #
-      # @example
-      #   Sashite::Snn::Name.valid?("Chess")    # => true
-      #   Sashite::Snn::Name.valid?("chess")    # => false
+      # @example Valid names
+      #   Sashite::Snn::Name.valid?("CHESS")    # => true
+      #   Sashite::Snn::Name.valid?("shogi")    # => true
+      #   Sashite::Snn::Name.valid?("XIANGQI")  # => true
+      #
+      # @example Invalid names
+      #   Sashite::Snn::Name.valid?("Chess")    # => false (mixed case)
+      #   Sashite::Snn::Name.valid?("CHESS960") # => false (contains digits)
+      #   Sashite::Snn::Name.valid?("GO9X9")    # => false (contains digits)
+      #   Sashite::Snn::Name.valid?("")         # => false (empty)
       def self.valid?(string)
         string.is_a?(::String) && string.match?(SNN_PATTERN)
       end
 
       # Returns the string representation of the name
       #
-      # @return [String]
+      # @return [String] the canonical style name
+      #
+      # @example
+      #   name = Sashite::Snn::Name.new("SHOGI")
+      #   name.to_s # => "SHOGI"
       def to_s
         value
       end
 
-      # Equality based on normalized string value
+      # Equality based on string value
       #
-      # @param other [Object]
-      # @return [Boolean]
+      # Two names are equal if they have the same string value. Case matters:
+      # "CHESS" (first player) is not equal to "chess" (second player).
+      #
+      # @param other [Object] object to compare with
+      # @return [Boolean] true if equal, false otherwise
+      #
+      # @example
+      #   name1 = Sashite::Snn::Name.new("CHESS")
+      #   name2 = Sashite::Snn::Name.new("CHESS")
+      #   name3 = Sashite::Snn::Name.new("chess")
+      #
+      #   name1 == name2  # => true
+      #   name1 == name3  # => false (different case = different player)
       def ==(other)
         other.is_a?(self.class) && value == other.value
       end
 
-      # Required for correct Set/hash behavior
+      # Required for correct Set/Hash behavior
       alias eql? ==
 
       # Hash based on class and value
       #
-      # @return [Integer]
+      # Enables Name objects to be used as hash keys and in sets.
+      #
+      # @return [Integer] hash code
+      #
+      # @example Use as hash key
+      #   styles = {
+      #     Sashite::Snn::Name.new("CHESS") => "Western Chess",
+      #     Sashite::Snn::Name.new("SHOGI") => "Japanese Chess"
+      #   }
       def hash
         [self.class, value].hash
       end
 
       # Validate that the string is in proper SNN format
       #
-      # @param str [String]
-      # @raise [ArgumentError] if invalid
+      # @param str [String] string to validate
+      # @raise [ArgumentError] if the string does not match SNN pattern
+      #
+      # @example Valid format
+      #   Sashite::Snn::Name.validate_format("CHESS")  # No error
+      #   Sashite::Snn::Name.validate_format("shogi")  # No error
+      #
+      # @example Invalid format
+      #   Sashite::Snn::Name.validate_format("Chess")  # Raises ArgumentError
       def self.validate_format(str)
         raise ::ArgumentError, format(ERROR_INVALID_NAME, str.inspect) unless str.match?(SNN_PATTERN)
       end

data/lib/sashite/snn.rb

@@ -5,53 +5,87 @@ require_relative "snn/name"
 module Sashite
   # SNN (Style Name Notation) implementation for Ruby
   #
-  # Provides a formal naming system for identifying styles in abstract strategy board games.
-  # SNN uses canonical, human-readable ASCII names beginning with an uppercase letter.
-  # It supports unlimited unique style identifiers with consistent, rule-agnostic semantics.
+  # Provides a foundational naming system for identifying styles in abstract strategy board games.
+  # SNN uses canonical, human-readable alphabetic names with case encoding to represent both
+  # style identity and player assignment.
   #
-  # Format: <uppercase-letter>[<lowercase-letter | digit>]*
+  # Format: All uppercase OR all lowercase alphabetic characters
   #
   # Examples:
-  #   "Chess"       - Standard Western chess
-  #   "Shogi"       - Japanese chess
-  #   "Minishogi"   - 5×5 compact shōgi variant
-  #   "Chess960"    - Fischer random chess
+  #   "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
+  #   "XIANGQI"  - Xiangqi style for first player
+  #   "xiangqi"  - Xiangqi style for second player
+  #
+  # Case Encoding:
+  #   - UPPERCASE names represent the first player's style
+  #   - lowercase names represent the second player's style
+  #
+  # Constraints:
+  #   - Alphabetic characters only (A-Z, a-z)
+  #   - Case consistency required (all uppercase OR all lowercase)
+  #   - No digits, no special characters, no mixed case
+  #
+  # As a foundational primitive, SNN has no dependencies and serves as a building block
+  # for formal style identification in the Sashité ecosystem.
   #
   # See: https://sashite.dev/specs/snn/1.0.0/
   module Snn
     # Check if a string is valid SNN notation
     #
+    # Valid SNN strings must contain only alphabetic characters in consistent case
+    # (either all uppercase or all lowercase).
+    #
     # @param snn_string [String] the string to validate
     # @return [Boolean] true if valid SNN, false otherwise
     #
     # @example Validate SNN strings
-    #   Sashite::Snn.valid?("Chess")     # => true
-    #   Sashite::Snn.valid?("minishogi") # => false
-    #   Sashite::Snn.valid?("Go9x9")     # => true
+    #   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?("GO9X9")     # => false (contains digits)
     def self.valid?(snn_string)
       Name.valid?(snn_string)
     end
 
     # Parse an SNN string into a Name object
     #
+    # Converts a valid SNN string into an immutable Name object. The name must follow
+    # SNN format rules: all uppercase or all lowercase alphabetic characters only.
+    #
     # @param snn_string [String] the name string
     # @return [Snn::Name] a parsed name object
     # @raise [ArgumentError] if the name is invalid
     #
     # @example Parse valid SNN names
-    #   Sashite::Snn.parse("Shogi")    # => #<Snn::Name value="Shogi">
+    #   Sashite::Snn.parse("SHOGI")    # => #<Snn::Name value="SHOGI">
+    #   Sashite::Snn.parse("chess")    # => #<Snn::Name value="chess">
+    #
+    # @example Invalid names raise errors
+    #   Sashite::Snn.parse("Chess")    # => ArgumentError (mixed case)
+    #   Sashite::Snn.parse("CHESS960") # => ArgumentError (contains digits)
     def self.parse(snn_string)
       Name.parse(snn_string)
     end
 
     # Create a new Name instance directly
     #
+    # Constructs a Name object from a string or symbol. The value must follow
+    # SNN format rules: all uppercase or all lowercase alphabetic characters only.
+    #
     # @param value [String, Symbol] style name to construct
     # @return [Snn::Name] new name instance
     # @raise [ArgumentError] if name format is invalid
     #
-    # @example
-    #   Sashite::Snn.name("Xiangqi") # => #<Snn::Name value="Xiangqi">
+    # @example Create names
+    #   Sashite::Snn.name("XIANGQI") # => #<Snn::Name value="XIANGQI">
+    #   Sashite::Snn.name(:makruk)   # => #<Snn::Name value="makruk">
+    #
+    # @example Invalid formats raise errors
+    #   Sashite::Snn.name("Chess960") # => ArgumentError
     def self.name(value)
       Name.new(value)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-snn
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -10,12 +10,18 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |
-  SNN (Style Name Notation) provides a rule-agnostic, scalable naming system for identifying
-  abstract strategy board game styles. This gem implements the SNN Specification v1.0.0 with
-  a modern Ruby interface featuring immutable style name objects and functional programming
-  principles. SNN uses canonical ASCII names (e.g., "Shogi", "Go9x9") to unambiguously refer
-  to game styles across variants and traditions. Ideal for engines, protocols, and tools that
-  need clear and extensible style identifiers.
+  SNN (Style Name Notation) provides a foundational, rule-agnostic naming system for identifying
+  game styles in abstract strategy board games. This gem implements the SNN Specification v1.0.0
+  with a modern Ruby interface featuring immutable style name objects and functional programming
+  principles.
+
+  SNN uses case-consistent alphabetic names (e.g., "CHESS", "SHOGI", "XIANGQI" for first player;
+  "chess", "shogi", "xiangqi" for second player) to unambiguously represent both style identity
+  and player assignment. As a foundational primitive with no dependencies, SNN serves as a building
+  block for formal style identification across the Sashité ecosystem.
+
+  Format: All uppercase OR all lowercase alphabetic characters only (no digits, no special characters).
+  Ideal for game engines, protocols, and tools requiring clear and extensible style identifiers.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -50,8 +56,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.1
 specification_version: 4
-summary: SNN (Style Name Notation) implementation for Ruby with immutable style name
-  objects
+summary: SNN (Style Name Notation) - foundational naming system for abstract strategy
+  game styles
 test_files: []