sashite-snn 1.0.1 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f0f7d4b0f73aa8c0d12c8d7cdbcd910d667f6f87a2edf24ad2d97c177749d21
-  data.tar.gz: 13e22095a02f4b7f51d0b93d602974a2d6e3571db880524330e897f584d08e00
+  metadata.gz: c3327ae1106ccede78736585e812180c12d7a56852a82ae70b7745e233ef5496
+  data.tar.gz: ba5892640791f51341e52c883f52f9f21bac64e21001052e1fcbc17965a156a7
 SHA512:
-  metadata.gz: b6e76c3b7058d5ae8cf82cde6a67f7690bc87017b127da8eae4c1389dc0d67924956bad2d4347119fa4e870f63a2e76d57910a1184f6e761b23bad53d80aad9b
-  data.tar.gz: 8b17d5c49b83f6408d5c99a28a5bf06929e6b1088daeea9b679b67eb24c8cd0dc8bf45db780ccda5497fb368fc9e8037b61003fa4c4d10d10797f41f4cde941d
+  metadata.gz: 1798b7aec7b88cc2baddcd9fa7f3518c2d97bf16343caac92ec84f9bfad3dc0ac20830d95144984ea27795d867e80c008a090f9de7fc8d284ac853f9c326b144
+  data.tar.gz: a6a548c819cf763b914cc1b70ce82ba86d86b7973f0231df5075931788d19fb2732d4138896b347cf6a1842c554116578e59cdfb619408acb370c2c43d469753

data/README.md

@@ -5,13 +5,13 @@
 ![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)
 
-> **SNN** (Style Name Notation) support for the Ruby language.
+> **SNN** (Style Name Notation) implementation for the Ruby language.
 
 ## What is SNN?
 
-SNN (Style Name Notation) is a rule-agnostic format for identifying piece styles in abstract strategy board games, as defined in the [Game Protocol](https://sashite.dev/game-protocol/). It provides unambiguous identification of piece styles using standardized naming conventions with case-based player assignment, enabling clear distinction between different piece traditions in multi-style gaming environments.
+SNN (Style Name Notation) provides a rule-agnostic format for identifying styles in abstract strategy board games. SNN uses standardized naming conventions with case-based side encoding, enabling clear distinction between different traditions in multi-style gaming environments.
 
-This gem implements the [SNN Specification v1.0.0](https://sashite.dev/specs/snn/1.0.0/), providing a Ruby interface for working with style identifiers through a clean and minimal API.
+This gem implements the [SNN Specification v1.0.0](https://sashite.dev/specs/snn/1.0.0/), providing a modern Ruby interface with immutable style objects and functional programming principles.
 
 ## Installation
 
@@ -26,289 +26,421 @@ Or install manually:
 gem install sashite-snn
 ```
 
-## SNN Format
+## Usage
 
-A SNN record consists of a style identifier that maps to the **Style attribute** from the [Game Protocol](https://sashite.dev/game-protocol/):
+```ruby
+require "sashite/snn"
+
+# Parse SNN strings into style objects
+style = Sashite::Snn.parse("CHESS")         # => #<Snn::Style name=:Chess side=:first>
+style.to_s                                  # => "CHESS"
+style.name                                  # => :Chess
+style.side                                  # => :first
+
+# Create styles directly
+style = Sashite::Snn.style(:Chess, :first)         # => #<Snn::Style name=:Chess side=:first>
+style = Sashite::Snn::Style.new(:Shogi, :second)   # => #<Snn::Style name=:Shogi side=:second>
+
+# Validate SNN strings
+Sashite::Snn.valid?("CHESS")                # => true
+Sashite::Snn.valid?("chess")                # => true
+Sashite::Snn.valid?("Chess")                # => false (mixed case)
+Sashite::Snn.valid?("123")                  # => false (must start with letter)
+
+# Side manipulation (returns new immutable instances)
+black_chess = style.flip                    # => #<Snn::Style name=:Chess side=:second>
+black_chess.to_s                            # => "chess"
+
+# Name manipulation
+shogi_style = style.with_name(:Shogi)       # => #<Snn::Style name=:Shogi side=:first>
+shogi_style.to_s                            # => "SHOGI"
+
+# Side queries
+style.first_player?                         # => true
+black_chess.second_player?                  # => true
+
+# Name and side comparison
+chess1 = Sashite::Snn.parse("CHESS")
+chess2 = Sashite::Snn.parse("chess")
+shogi = Sashite::Snn.parse("SHOGI")
+
+chess1.same_name?(chess2)                   # => true (both chess)
+chess1.same_side?(shogi)                    # => true (both first player)
+chess1.same_name?(shogi)                    # => false (different styles)
+
+# Functional transformations can be chained
+black_shogi = Sashite::Snn.parse("CHESS").with_name(:Shogi).flip
+black_shogi.to_s                            # => "shogi"
+```
 
+## Format Specification
+
+### Structure
 ```
 <style-identifier>
 ```
 
-### Grammar Specification
+### Components
+
+- **Identifier**: Alphanumeric string starting with a letter
+  - Uppercase: First player styles (`CHESS`, `SHOGI`, `XIANGQI`)
+  - Lowercase: Second player styles (`chess`, `shogi`, `xiangqi`)
+- **Case Consistency**: Entire identifier must be uppercase or lowercase (no mixed case)
 
-```bnf
-<snn> ::= <uppercase-style> | <lowercase-style>
+### Regular Expression
+```ruby
+# Pattern accessible via Sashite::Snn::Style::SNN_PATTERN
+/\A([A-Z][A-Z0-9]*|[a-z][a-z0-9]*)\z/
+```
 
-<uppercase-style> ::= <letter-uppercase> <identifier-tail-uppercase>*
-<lowercase-style> ::= <letter-lowercase> <identifier-tail-lowercase>*
+### Examples
+- `CHESS` - First player chess style
+- `chess` - Second player chess style
+- `CHESS960` - First player Fischer Random Chess style
+- `SHOGI` - First player shōgi style
+- `shogi` - Second player shōgi style
+- `XIANGQI` - First player xiangqi style
 
-<identifier-tail-uppercase> ::= <letter-uppercase> | <digit>
-<identifier-tail-lowercase> ::= <letter-lowercase> | <digit>
+## Game Examples
 
-<letter-uppercase> ::= "A" | "B" | "C" | ... | "Z"
-<letter-lowercase> ::= "a" | "b" | "c" | ... | "z"
-<digit> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
+### Classic Styles
+```ruby
+# Traditional game styles
+chess = Sashite::Snn.style(:Chess, :first)        # => traditional chess
+shogi = Sashite::Snn.style(:Shogi, :first)        # => traditional shōgi
+xiangqi = Sashite::Snn.style(:Xiangqi, :first)    # => traditional xiangqi
+makruk = Sashite::Snn.style(:Makruk, :first)      # => traditional makruk
+
+# Player variations
+white_chess = chess                               # => first player
+black_chess = chess.flip                          # => second player
+black_chess.to_s                                  # => "chess"
 ```
 
-### Protocol Mapping
+### Chess Variants
+```ruby
+# Fischer Random Chess
+chess960_white = Sashite::Snn.style(:Chess960, :first)
+chess960_black = chess960_white.flip
+chess960_black.to_s                               # => "chess960"
 
-SNN encodes style information with player association according to the Game Protocol:
+# King of the Hill Chess
+koth = Sashite::Snn.style(:Koth, :first)
+koth.to_s                                         # => "KOTH"
 
-| Protocol Attribute | SNN Encoding | Examples |
-|-------------------|--------------|----------|
-| **Style** | Alphanumeric identifier | `CHESS`, `SHOGI`, `XIANGQI` |
-| **Player Association** | Case encoding | `CHESS` = First player, `chess` = Second player |
+# Three-Check Chess
+threecheck = Sashite::Snn.style(:Threecheck, :first)
+```
 
-### Format Rules
+### Shōgi Variants
+```ruby
+# Traditional Shōgi
+standard_shogi = Sashite::Snn.style(:Shogi, :first)
 
-- **Start character**: Must be alphabetic (`A-Z` for first player, `a-z` for second player)
-- **Subsequent characters**: Alphabetic characters and digits only
-- **Case consistency**: Entire identifier must be uppercase or lowercase (no mixed case)
-- **Player assignment**: Uppercase = first player, lowercase = second player
-- **Fixed assignment**: Player-style association remains constant throughout the match
+# Mini Shōgi
+mini_shogi = Sashite::Snn.style(:Minishogi, :first)
 
-## Basic Usage
+# Chu Shōgi
+chu_shogi = Sashite::Snn.style(:Chushogi, :first)
+```
 
-### Creating Style Objects
+### Multi-Style Gaming
+```ruby
+# Cross-tradition match
+def create_hybrid_match
+  styles = [
+    Sashite::Snn.style(:Chess, :first),     # White uses chess pieces
+    Sashite::Snn.style(:Shogi, :second)     # Black uses shōgi pieces
+  ]
+
+  # Each player uses their preferred piece style
+  styles
+end
 
-The primary interface is the `Sashite::Snn::Style` class, which represents a style identifier in SNN format:
+# Style compatibility check
+def compatible_styles?(style1, style2)
+  # Styles are compatible if they have different sides
+  !style1.same_side?(style2)
+end
 
-```ruby
-require "sashite/snn"
+chess_white = Sashite::Snn.parse("CHESS")
+shogi_black = Sashite::Snn.parse("shogi")
+puts compatible_styles?(chess_white, shogi_black)  # => true
+```
+
+## API Reference
 
-# Parse a SNN string into a style object
-style = Sashite::Snn::Style.parse("CHESS")
-# => #<Sashite::Snn::Style:0x... @identifier="CHESS">
+### Main Module Methods
 
-lowercase_style = Sashite::Snn::Style.parse("shogi")
-# => #<Sashite::Snn::Style:0x... @identifier="shogi">
+- `Sashite::Snn.valid?(snn_string)` - Check if string is valid SNN notation
+- `Sashite::Snn.parse(snn_string)` - Parse SNN string into Style object
+- `Sashite::Snn.style(name, side)` - Create style instance directly
 
-# Create directly with constructor
-style = Sashite::Snn::Style.new("CHESS")
-lowercase_style = Sashite::Snn::Style.new("makruk")
+### Style Class
 
-# Convenience method
-style = Sashite::Snn.style("XIANGQI")
-```
+#### Creation and Parsing
+- `Sashite::Snn::Style.new(name, side)` - Create style instance
+- `Sashite::Snn::Style.parse(snn_string)` - Parse SNN string (same as module method)
+
+#### Attribute Access
+- `#name` - Get style name (symbol with proper capitalization)
+- `#side` - Get player side (:first or :second)
+- `#to_s` - Convert to SNN string representation
 
-### Converting to String and Symbol
+#### Name and Case Handling
 
-Convert a style object to different representations:
+**Important**: The `name` attribute is always stored with proper capitalization (first letter uppercase, rest lowercase), regardless of the input case when parsing. The display case in `#to_s` is determined by the `side` attribute:
 
 ```ruby
-style = Sashite::Snn::Style.parse("CHESS")
-style.to_s   # => "CHESS"
-style.to_sym # => :CHESS
-
-variant_style = Sashite::Snn::Style.parse("chess960")
-variant_style.to_s   # => "chess960"
-variant_style.to_sym # => :chess960
-
-# Useful for hash keys and case statements
-game_config = {
-  style.to_sym => { pieces: chess_pieces, rules: chess_rules }
-}
-
-case style.to_sym
-when :CHESS then setup_chess_game
-when :SHOGI then setup_shogi_game
-end
+# Both create the same internal name representation
+style1 = Sashite::Snn.parse("CHESS")  # name: :Chess, side: :first
+style2 = Sashite::Snn.parse("chess")  # name: :Chess, side: :second
+
+style1.name    # => :Chess (proper capitalization)
+style2.name    # => :Chess (same capitalization)
+
+style1.to_s    # => "CHESS" (uppercase display)
+style2.to_s    # => "chess" (lowercase display)
 ```
 
-### Player Association
+#### Side Queries
+- `#first_player?` - Check if first player style
+- `#second_player?` - Check if second player style
 
-Check which player a style belongs to according to the Game Protocol:
+#### Transformations (immutable - return new instances)
+- `#flip` - Switch player (change side)
+- `#with_name(new_name)` - Create style with different name
+- `#with_side(new_side)` - Create style with different side
 
-```ruby
-first_player_style = Sashite::Snn::Style.parse("CHESS")
-first_player_style.first_player?  # => true (uppercase = first player)
-first_player_style.second_player? # => false
+#### Comparison Methods
+- `#same_name?(other)` - Check if same style name
+- `#same_side?(other)` - Check if same side
+- `#==(other)` - Full equality comparison
 
-second_player_style = Sashite::Snn::Style.parse("shogi")
-second_player_style.first_player?  # => false
-second_player_style.second_player? # => true (lowercase = second player)
-```
+### Style Class Constants
+
+- `Sashite::Snn::Style::FIRST_PLAYER` - Symbol for first player (:first)
+- `Sashite::Snn::Style::SECOND_PLAYER` - Symbol for second player (:second)
+- `Sashite::Snn::Style::VALID_SIDES` - Array of valid sides
+- `Sashite::Snn::Style::SNN_PATTERN` - Regular expression for SNN validation
 
-## Validation
+## Advanced Usage
 
-All parsing automatically validates input according to the SNN specification:
+### Name Normalization Examples
 
 ```ruby
-# Valid SNN strings
-Sashite::Snn::Style.parse("CHESS")      # ✓ First player chess
-Sashite::Snn::Style.parse("shogi")      # ✓ Second player shogi
-Sashite::Snn::Style.parse("CHESS960")   # ✓ First player Chess960 variant
-Sashite::Snn::Style.parse("makruk")     # ✓ Second player makruk
-
-# Valid constructor calls
-Sashite::Snn::Style.new("XIANGQI")      # ✓ First player xiangqi
-Sashite::Snn::Style.new("janggi")       # ✓ Second player janggi
-
-# Convenience method
-Sashite::Snn.style("MINISHOGI") # ✓ First player minishogi
-
-# Check validity
-Sashite::Snn.valid?("CHESS")    # => true
-Sashite::Snn.valid?("Chess")    # => false (mixed case not allowed)
-Sashite::Snn.valid?("123")      # => false (must start with letter)
-Sashite::Snn.valid?("")         # => false (empty string)
-
-# Invalid SNN strings raise ArgumentError
-Sashite::Snn::Style.parse("")           # ✗ ArgumentError
-Sashite::Snn::Style.parse("Chess")      # ✗ ArgumentError (mixed case)
-Sashite::Snn::Style.parse("9CHESS")     # ✗ ArgumentError (starts with digit)
-Sashite::Snn::Style.parse("CHESS-960")  # ✗ ArgumentError (contains hyphen)
-```
+# Parsing different cases results in same name
+white_chess = Sashite::Snn.parse("CHESS")
+black_chess = Sashite::Snn.parse("chess")
 
-## Examples of SNN in Practice
+# Names are normalized with proper capitalization
+white_chess.name  # => :Chess
+black_chess.name  # => :Chess (same name!)
 
-### Classic Game Styles
+# Sides are different
+white_chess.side  # => :first
+black_chess.side  # => :second
 
-```ruby
-# Traditional chess match (both players use chess pieces)
-first_player = Sashite::Snn::Style.parse("CHESS")   # First player
-second_player = Sashite::Snn::Style.parse("chess")  # Second player
+# Display follows side convention
+white_chess.to_s  # => "CHESS"
+black_chess.to_s  # => "chess"
 
-# Cross-style game: Chess vs Shogi
-first_player = Sashite::Snn::Style.parse("CHESS")   # First player uses chess pieces
-second_player = Sashite::Snn::Style.parse("shogi")  # Second player uses shogi pieces
+# Same name, different sides
+white_chess.same_name?(black_chess)  # => true
+white_chess.same_side?(black_chess)  # => false
+```
 
-# Variant games
-first_player = Sashite::Snn::Style.parse("CHESS960") # First player uses Chess960 variant
-second_player = Sashite::Snn::Style.parse("chess960") # Second player uses Chess960 variant
+### Immutable Transformations
+```ruby
+# All transformations return new instances
+original = Sashite::Snn.style(:Chess, :first)
+flipped = original.flip
+renamed = original.with_name(:Shogi)
+
+# Original style is never modified
+puts original.to_s  # => "CHESS"
+puts flipped.to_s   # => "chess"
+puts renamed.to_s   # => "SHOGI"
+
+# Transformations can be chained
+result = original.flip.with_name(:Xiangqi)
+puts result.to_s    # => "xiangqi"
 ```
 
-### Style Examples from SNN Specification
+### Game Configuration Management
+```ruby
+class GameConfiguration
+  def initialize
+    @player_styles = {}
+  end
 
-According to the [SNN Examples Documentation](https://sashite.dev/specs/snn/1.0.0/examples/):
+  def set_player_style(player, style_name)
+    side = player == :white ? :first : :second
+    @player_styles[player] = Sashite::Snn.style(style_name, side)
+  end
 
-| SNN | Interpretation |
-|-----|----------------|
-| `CHESS` | Chess first player (white) |
-| `chess` | Chess second player (black) |
-| `SHOGI` | Shōgi first player (sente) |
-| `shogi` | Shōgi second player (gote) |
-| `XIANGQI` | Xiangqi first player (red) |
-| `xiangqi` | Xiangqi second player (black) |
+  def get_player_style(player)
+    @player_styles[player]
+  end
 
-```ruby
-# Standard game representations
-chess_white = Sashite::Snn::Style.parse("CHESS")    # White pieces (first player)
-chess_black = Sashite::Snn::Style.parse("chess")    # Black pieces (second player)
+  def style_mismatch?
+    return false if @player_styles.size < 2
 
-shogi_sente = Sashite::Snn::Style.parse("SHOGI")    # Sente (first player)
-shogi_gote = Sashite::Snn::Style.parse("shogi")     # Gote (second player)
+    styles = @player_styles.values
+    !styles.all? { |style| style.same_name?(styles.first) }
+  end
 
-xiangqi_red = Sashite::Snn::Style.parse("XIANGQI")  # Red pieces (first player)
-xiangqi_black = Sashite::Snn::Style.parse("xiangqi") # Black pieces (second player)
-```
+  def cross_tradition_match?
+    return false if @player_styles.size < 2
 
-### Variant Styles
+    style_names = @player_styles.values.map(&:name).uniq
+    style_names.size > 1
+  end
+end
 
-```ruby
-# Chess variants
-fischer_random = Sashite::Snn::Style.parse("CHESS960")
-king_of_hill = Sashite::Snn::Style.parse("CHESSKING")
+# Usage
+config = GameConfiguration.new
+config.set_player_style(:white, :Chess)
+config.set_player_style(:black, :Shogi)
 
-# Shogi variants
-mini_shogi = Sashite::Snn::Style.parse("MINISHOGI")
-handicap_shogi = Sashite::Snn::Style.parse("SHOGI9")
+puts config.cross_tradition_match?  # => true
+puts config.style_mismatch?         # => true
 
-# Other traditions
-thai_makruk = Sashite::Snn::Style.parse("MAKRUK")
-korean_janggi = Sashite::Snn::Style.parse("JANGGI")
+white_style = config.get_player_style(:white)
+puts white_style.to_s               # => "CHESS"
 ```
 
-### Cross-Style Gaming
+### Style Analysis
+```ruby
+def analyze_styles(snns)
+  styles = snns.map { |snn| Sashite::Snn.parse(snn) }
+
+  {
+    total: styles.size,
+    by_side: styles.group_by(&:side),
+    by_name: styles.group_by(&:name),
+    unique_names: styles.map(&:name).uniq.size,
+    cross_tradition: styles.map(&:name).uniq.size > 1
+  }
+end
+
+snns = %w[CHESS chess SHOGI shogi XIANGQI xiangqi]
+analysis = analyze_styles(snns)
+puts analysis[:by_side][:first].size   # => 3
+puts analysis[:unique_names]           # => 3
+puts analysis[:cross_tradition]        # => true
+```
 
+### Tournament Style Management
 ```ruby
-# Create a cross-style game setup
-first_player_style = Sashite::Snn::Style.parse("CHESS")
-second_player_style = Sashite::Snn::Style.parse("makruk")
-
-puts "Game: #{first_player_style} vs #{second_player_style}"
-# => "Game: CHESS vs makruk"
-
-# This represents a unique game where chess pieces face makruk pieces
-
-# Each player keeps their assigned style throughout the game
-game_config = {
-  first_player:  first_player_style, # Fixed: CHESS
-  second_player: second_player_style # Fixed: makruk
-}
-
-# Using symbols for configuration
-style_configs = {
-  first_player_style.to_sym  => { piece_set: :western, board: :"8x8" },
-  second_player_style.to_sym => { piece_set: :thai, board: :"8x8" }
-}
+class TournamentStyleRegistry
+  def initialize
+    @registered_styles = Set.new
+  end
+
+  def register_style(style_name)
+    # Register both sides of a style
+    first_player_style = Sashite::Snn.style(style_name, :first)
+    second_player_style = first_player_style.flip
+
+    @registered_styles.add(first_player_style)
+    @registered_styles.add(second_player_style)
+
+    [first_player_style, second_player_style]
+  end
+
+  def valid_pairing?(style1, style2)
+    @registered_styles.include?(style1) &&
+    @registered_styles.include?(style2) &&
+    !style1.same_side?(style2)
+  end
+
+  def available_styles_for_side(side)
+    @registered_styles.select { |style| style.side == side }
+  end
+
+  def supported_traditions
+    @registered_styles.map(&:name).uniq
+  end
+end
+
+# Usage
+registry = TournamentStyleRegistry.new
+registry.register_style(:Chess)
+registry.register_style(:Shogi)
+
+chess_white = Sashite::Snn.parse("CHESS")
+shogi_black = Sashite::Snn.parse("shogi")
+
+puts registry.valid_pairing?(chess_white, shogi_black)  # => true
+puts registry.supported_traditions                      # => [:Chess, :Shogi]
 ```
 
-## API Reference
+## Protocol Mapping
 
-### Module Methods
+Following the [Game Protocol](https://sashite.dev/game-protocol/):
 
-- `Sashite::Snn.valid?(snn_string)` - Check if a string is valid SNN notation
-- `Sashite::Snn.style(identifier)` - Convenience method to create style objects
+| Protocol Attribute | SNN Encoding | Examples | Notes |
+|-------------------|--------------|----------|-------|
+| **Style** | Alphanumeric identifier | `CHESS`, `SHOGI`, `XIANGQI` | Name is always stored with proper capitalization |
+| **Side** | Case encoding | `CHESS` = First player, `chess` = Second player | Case is determined by side during rendering |
 
-### Sashite::Snn::Style Class Methods
+**Name Convention**: All style names are internally represented with proper capitalization (first letter uppercase, rest lowercase). The display case is determined by the `side` attribute: first player styles display as uppercase, second player styles as lowercase.
 
-- `Sashite::Snn::Style.parse(snn_string)` - Parse a SNN string into a style object
-- `Sashite::Snn::Style.new(identifier)` - Create a new style instance
+**Canonical principle**: Identical styles must have identical SNN representations.
 
-### Instance Methods
+## Properties
 
-#### Player Queries
-- `#first_player?` - Check if style belongs to first player (uppercase)
-- `#second_player?` - Check if style belongs to second player (lowercase)
-- `#uppercase?` - Check if identifier is uppercase
-- `#lowercase?` - Check if identifier is lowercase
+* **Rule-Agnostic**: Independent of specific game mechanics
+* **Cross-Style Support**: Enables multi-tradition gaming environments
+* **Canonical Representation**: Consistent naming for equivalent styles
+* **Name Normalization**: Consistent proper capitalization representation internally
+* **Immutable**: All style instances are frozen and transformations return new objects
+* **Functional**: Pure functions with no side effects
 
-#### Conversion
-- `#to_s` - Convert to SNN string representation
-- `#to_sym` - Convert to symbol representation
-- `#inspect` - Detailed string representation for debugging
+## Implementation Notes
 
-## Design Properties
+### Name Normalization Convention
 
-Following the SNN specification, this implementation provides:
+SNN follows a strict name normalization convention:
 
-- **Rule-agnostic**: Independent of specific game mechanics
-- **Unambiguous identification**: Clear distinction between different piece traditions
-- **Cross-style support**: Enables multi-tradition gaming environments
-- **Canonical representation**: Consistent naming for equivalent styles
-- **Player clarity**: Case-based player association throughout gameplay
+1. **Internal Storage**: All style names are stored with proper capitalization (first letter uppercase, rest lowercase)
+2. **Input Flexibility**: Both `"CHESS"` and `"chess"` are valid input during parsing
+3. **Case Semantics**: Input case determines the `side` attribute, not the `name`
+4. **Display Logic**: Output case is computed from `side` during rendering
 
-## System Constraints
+This design ensures:
+- Consistent internal representation regardless of input format
+- Clear separation between style identity (name) and ownership (side)
+- Predictable behavior when comparing styles of the same name
 
-* SNN supports exactly **two players**
-* Players are distinguished by casing: **uppercase** for first player, **lowercase** for second player
-* Style identifiers must start with an alphabetic character
-* Subsequent characters may include alphabetic characters and digits only
-* Mixed casing is not permitted within a single identifier
-* Style assignment to players remains **fixed throughout a game**
-* Total piece count must remain constant (Game Protocol conservation principle)
+### Example Flow
 
-## Use Cases
+```ruby
+# Input: "chess" (lowercase)
+# ↓ Parsing
+# name: :Chess (normalized with proper capitalization)
+# side: :second (inferred from lowercase input)
+# ↓ Display
+# SNN: "chess" (final representation)
+```
 
-SNN is particularly useful in the following scenarios:
+This ensures that `parse(snn).to_s == snn` for all valid SNN strings while maintaining internal consistency.
 
-1. **Multi-style environments**: When games involve pieces from multiple traditions or variants
-2. **Game engine development**: When implementing engines that need to distinguish between different piece style traditions
-3. **Hybrid games**: When creating or analyzing games that combine elements from different piece traditions
-4. **Database systems**: When storing game data that must avoid naming conflicts between similar styles
-5. **Cross-tradition analysis**: When comparing or analyzing strategic elements across different piece traditions
-6. **Tournament systems**: When organizing events that allow players to choose from different piece style traditions
+## System Constraints
 
-## Game Protocol Compliance
+- **Alphanumeric identifiers** starting with a letter
+- **Exactly 2 players** (uppercase/lowercase distinction)
+- **Case consistency** within each identifier (no mixed case)
 
-This implementation fully complies with the [Game Protocol](https://sashite.dev/game-protocol/) by:
+## Related Specifications
 
-- Representing the **Style attribute** of pieces
-- Supporting **two-player** constraint
-- Maintaining **piece conservation** (styles are immutable)
-- Enabling **cross-style** gameplay scenarios
-- Providing **deterministic** style identification
+- [Game Protocol](https://sashite.dev/game-protocol/) - Conceptual foundation for abstract strategy board games
+- [PIN](https://sashite.dev/specs/pin/) - Piece Identifier Notation (ASCII piece representation)
+- [PNN](https://sashite.dev/specs/pnn/) - Piece Name Notation (style-aware piece representation)
+- [CELL](https://sashite.dev/specs/cell/) - Board position coordinates
+- [HAND](https://sashite.dev/specs/hand/) - Reserve location notation
+- [PMN](https://sashite.dev/specs/pmn/) - Portable Move Notation
 
 ## Documentation
 
@@ -317,6 +449,33 @@ This implementation fully complies with the [Game Protocol](https://sashite.dev/
 - [Game Protocol Foundation](https://sashite.dev/game-protocol/)
 - [API Documentation](https://rubydoc.info/github/sashite/snn.rb/main)
 
+## 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
+
 ## License
 
 Available as open source under the [MIT License](https://opensource.org/licenses/MIT).

data/lib/sashite/snn/style.rb

@@ -2,141 +2,261 @@
 
 module Sashite
   module Snn
-    # Represents a style identifier in SNN format
+    # Represents a style in SNN (Style Name Notation) format.
     #
-    # A style represents a particular tradition, variant, or design approach for game pieces.
-    # The casing of the identifier determines player association:
-    # - Uppercase identifiers belong to the first player
-    # - Lowercase identifiers belong to the second player
+    # A style consists of an alphanumeric identifier with case-based side encoding:
+    # - Uppercase identifier: first player (CHESS, SHOGI, XIANGQI)
+    # - Lowercase identifier: second player (chess, shogi, xiangqi)
     #
-    # @example
-    #   # First player styles (uppercase)
-    #   chess_style = Sashite::Snn::Style.new("CHESS")
-    #   shogi_style = Sashite::Snn::Style.new("SHOGI")
-    #
-    #   # Second player styles (lowercase)
-    #   makruk_style = Sashite::Snn::Style.new("makruk")
-    #   chess960_style = Sashite::Snn::Style.new("chess960")
+    # All instances are immutable - transformation methods return new instances.
+    # This follows the Game Protocol's style model with Name and Side attributes.
     class Style
-      # @return [String] The style identifier
-      attr_reader :identifier
+      # SNN validation pattern matching the specification
+      SNN_PATTERN = /\A(?<identifier>[A-Z][A-Z0-9]*|[a-z][a-z0-9]*)\z/
+
+      # Pattern for proper name capitalization (first letter uppercase, rest lowercase/digits)
+      PROPER_NAME_PATTERN = /\A[A-Z][a-z0-9]*\z/
+
+      # Player side constants
+      FIRST_PLAYER = :first
+      SECOND_PLAYER = :second
+
+      # Valid sides
+      VALID_SIDES = [FIRST_PLAYER, SECOND_PLAYER].freeze
+
+      # Error messages
+      ERROR_INVALID_SNN = "Invalid SNN string: %s"
+      ERROR_INVALID_NAME = "Name must be a symbol with proper capitalization (first letter uppercase, rest lowercase), got: %s"
+      ERROR_INVALID_SIDE = "Side must be :first or :second, got: %s"
+
+      # @return [Symbol] the style name (with proper capitalization)
+      attr_reader :name
+
+      # @return [Symbol] the player side (:first or :second)
+      attr_reader :side
 
       # Create a new style instance
       #
-      # @param identifier [String] The style identifier
-      # @raise [ArgumentError] if the identifier is invalid SNN notation
-      #
-      # @example
-      #   style = Sashite::Snn::Style.new("CHESS")
-      #   # => #<Sashite::Snn::Style:0x... @identifier="CHESS">
-      def initialize(identifier)
-        raise ArgumentError, "Invalid SNN format: #{identifier.inspect}" unless Snn.valid?(identifier)
+      # @param name [Symbol] style name (with proper capitalization)
+      # @param side [Symbol] player side (:first or :second)
+      # @raise [ArgumentError] if parameters are invalid
+      def initialize(name, side)
+        self.class.validate_name(name)
+        self.class.validate_side(side)
 
-        @identifier = identifier.freeze
+        @name = name
+        @side = side
 
         freeze
       end
 
-      # Parse a SNN string into a style object
+      # Parse an SNN string into a Style object
       #
-      # @param snn_string [String] The SNN string to parse
-      # @return [Sashite::Snn::Style] A new style object
-      # @raise [ArgumentError] if the string is invalid SNN notation
-      #
-      # @example
-      #   style = Sashite::Snn::Style.parse("CHESS")
-      #   # => #<Sashite::Snn::Style:0x... @identifier="CHESS">
+      # @param snn_string [String] SNN notation string
+      # @return [Style] parsed style object with normalized name and inferred side
+      # @raise [ArgumentError] if the SNN string is invalid
+      # @example Parse SNN strings with case normalization
+      #   Sashite::Snn::Style.parse("CHESS") # => #<Snn::Style name=:Chess side=:first>
+      #   Sashite::Snn::Style.parse("chess") # => #<Snn::Style name=:Chess side=:second>
+      #   Sashite::Snn::Style.parse("SHOGI") # => #<Snn::Style name=:Shogi side=:first>
       def self.parse(snn_string)
-        new(snn_string)
+        string_value = String(snn_string)
+        matches = match_pattern(string_value)
+
+        identifier = matches[:identifier]
+
+        # Determine side from case
+        style_side = identifier == identifier.upcase ? FIRST_PLAYER : SECOND_PLAYER
+
+        # Normalize name to proper capitalization
+        style_name = normalize_name(identifier)
+
+        new(style_name, style_side)
       end
 
-      # Check if this style belongs to the first player
+      # Check if a string is a valid SNN notation
       #
-      # @return [Boolean] true if the style is uppercase (first player), false otherwise
+      # @param snn_string [String] the string to validate
+      # @return [Boolean] true if valid SNN, false otherwise
       #
-      # @example
-      #   Sashite::Snn::Style.new("CHESS").first_player?  # => true
-      #   Sashite::Snn::Style.new("shogi").first_player?  # => false
-      def first_player?
-        uppercase?
+      # @example Validate SNN strings
+      #   Sashite::Snn::Style.valid?("CHESS") # => true
+      #   Sashite::Snn::Style.valid?("chess") # => true
+      #   Sashite::Snn::Style.valid?("Chess") # => false
+      def self.valid?(snn_string)
+        return false unless snn_string.is_a?(::String)
+
+        snn_string.match?(SNN_PATTERN)
       end
 
-      # Check if this style belongs to the second player
+      # Convert the style to its SNN string representation
       #
-      # @return [Boolean] true if the style is lowercase (second player), false otherwise
-      #
-      # @example
-      #   Sashite::Snn::Style.new("CHESS").second_player?  # => false
-      #   Sashite::Snn::Style.new("shogi").second_player?  # => true
-      def second_player?
-        lowercase?
+      # @return [String] SNN notation string with case based on side
+      # @example Display different sides
+      #   style.to_s  # => "CHESS" (first player)
+      #   style.to_s  # => "chess" (second player)
+      #   style.to_s  # => "SHOGI" (first player)
+      def to_s
+        first_player? ? name.to_s.upcase : name.to_s.downcase
       end
 
-      # Check if the style identifier is uppercase
-      #
-      # @return [Boolean] true if the identifier is uppercase, false otherwise
+      # Create a new style with opposite ownership (side)
       #
-      # @example
-      #   Sashite::Snn::Style.new("CHESS").uppercase?  # => true
-      #   Sashite::Snn::Style.new("chess").uppercase?  # => false
-      def uppercase?
-        identifier == identifier.upcase
+      # @return [Style] new immutable style instance with flipped side
+      # @example Flip player sides
+      #   style.flip  # (:Chess, :first) => (:Chess, :second)
+      def flip
+        self.class.new(name, opposite_side)
       end
 
-      # Check if the style identifier is lowercase
+      # Create a new style with a different name (keeping same side)
       #
-      # @return [Boolean] true if the identifier is lowercase, false otherwise
-      #
-      # @example
-      #   Sashite::Snn::Style.new("CHESS").lowercase?  # => false
-      #   Sashite::Snn::Style.new("chess").lowercase?  # => true
-      def lowercase?
-        identifier == identifier.downcase
+      # @param new_name [Symbol] new name (with proper capitalization)
+      # @return [Style] new immutable style instance with different name
+      # @example Change style name
+      #   style.with_name(:Shogi)  # (:Chess, :first) => (:Shogi, :first)
+      def with_name(new_name)
+        self.class.validate_name(new_name)
+        return self if name == new_name
+
+        self.class.new(new_name, side)
       end
 
-      # Convert the style to its string representation
+      # Create a new style with a different side (keeping same name)
       #
-      # @return [String] The style identifier
+      # @param new_side [Symbol] :first or :second
+      # @return [Style] new immutable style instance with different side
+      # @example Change player side
+      #   style.with_side(:second)  # (:Chess, :first) => (:Chess, :second)
+      def with_side(new_side)
+        self.class.validate_side(new_side)
+        return self if side == new_side
+
+        self.class.new(name, new_side)
+      end
+
+      # Check if the style belongs to the first player
       #
-      # @example
-      #   Sashite::Snn::Style.new("CHESS").to_s  # => "CHESS"
-      def to_s
-        identifier
+      # @return [Boolean] true if first player
+      def first_player?
+        side == FIRST_PLAYER
       end
 
-      # Convert the style to a symbol
+      # Check if the style belongs to the second player
       #
-      # @return [Symbol] The style identifier as a symbol
+      # @return [Boolean] true if second player
+      def second_player?
+        side == SECOND_PLAYER
+      end
+
+      # Check if this style has the same name as another
       #
-      # @example
-      #   Sashite::Snn::Style.new("CHESS").to_sym  # => :CHESS
-      def to_sym
-        identifier.to_sym
+      # @param other [Style] style to compare with
+      # @return [Boolean] true if both styles have the same name
+      # @example Compare style names
+      #   chess1.same_name?(chess2)  # (:Chess, :first) and (:Chess, :second) => true
+      def same_name?(other)
+        return false unless other.is_a?(self.class)
+
+        name == other.name
       end
 
-      # String representation for debugging
+      # Check if this style belongs to the same side as another
       #
-      # @return [String] A detailed string representation
-      def inspect
-        "#<#{self.class}:0x#{object_id.to_s(16)} @identifier=#{identifier.inspect}>"
+      # @param other [Style] style to compare with
+      # @return [Boolean] true if both styles belong to the same side
+      def same_side?(other)
+        return false unless other.is_a?(self.class)
+
+        side == other.side
       end
 
-      # Equality comparison
+      # Custom equality comparison
       #
-      # @param other [Object] The object to compare with
-      # @return [Boolean] true if both objects are Style instances with the same identifier
+      # @param other [Object] object to compare with
+      # @return [Boolean] true if both objects are styles with identical name and side
       def ==(other)
-        other.is_a?(Style) && identifier == other.identifier
+        return false unless other.is_a?(self.class)
+
+        name == other.name && side == other.side
       end
 
-      # Alias for equality comparison
+      # Alias for == to ensure Set functionality works correctly
       alias eql? ==
 
-      # Hash code for use in hashes and sets
+      # Custom hash implementation for use in collections
       #
-      # @return [Integer] The hash code
+      # @return [Integer] hash value based on class, name, and side
       def hash
-        [self.class, identifier].hash
+        [self.class, name, side].hash
+      end
+
+      # Validate that the name is a valid symbol with proper capitalization
+      #
+      # @param name [Symbol] the name to validate
+      # @raise [ArgumentError] if invalid
+      def self.validate_name(name)
+        return if valid_name?(name)
+
+        raise ::ArgumentError, format(ERROR_INVALID_NAME, name.inspect)
+      end
+
+      # Validate that the side is a valid symbol
+      #
+      # @param side [Symbol] the side to validate
+      # @raise [ArgumentError] if invalid
+      def self.validate_side(side)
+        return if VALID_SIDES.include?(side)
+
+        raise ::ArgumentError, format(ERROR_INVALID_SIDE, side.inspect)
+      end
+
+      # Check if a name is valid (symbol with proper capitalization)
+      #
+      # @param name [Object] the name to check
+      # @return [Boolean] true if valid
+      def self.valid_name?(name)
+        return false unless name.is_a?(::Symbol)
+
+        name_string = name.to_s
+        return false if name_string.empty?
+
+        # Must match proper capitalization pattern
+        name_string.match?(PROPER_NAME_PATTERN)
+      end
+
+      # Normalize identifier to proper capitalization symbol
+      #
+      # @param identifier [String] the identifier to normalize
+      # @return [Symbol] normalized name symbol
+      def self.normalize_name(identifier)
+        # Convert to proper capitalization: first letter uppercase, rest lowercase
+        normalized = identifier.downcase
+        normalized[0] = normalized[0].upcase if normalized.length > 0
+        normalized.to_sym
+      end
+
+      # Match SNN pattern against string
+      #
+      # @param string [String] string to match
+      # @return [MatchData] match data
+      # @raise [ArgumentError] if string doesn't match
+      def self.match_pattern(string)
+        matches = SNN_PATTERN.match(string)
+        return matches if matches
+
+        raise ::ArgumentError, format(ERROR_INVALID_SNN, string)
+      end
+
+      private_class_method :valid_name?, :normalize_name, :match_pattern
+
+      private
+
+      # Get the opposite side
+      #
+      # @return [Symbol] the opposite side
+      def opposite_side
+        first_player? ? SECOND_PLAYER : FIRST_PLAYER
       end
     end
   end

data/lib/sashite/snn.rb

@@ -3,47 +3,61 @@
 require_relative "snn/style"
 
 module Sashite
-  # Style Name Notation (SNN) module
+  # SNN (Style Name Notation) implementation for Ruby
   #
-  # SNN provides a consistent and rule-agnostic format for identifying piece styles
-  # in abstract strategy board games. It enables clear distinction between different
-  # piece traditions, variants, or design approaches within multi-style gaming environments.
+  # Provides a rule-agnostic format for identifying styles in abstract strategy board games.
+  # SNN uses standardized naming conventions with case-based side encoding, enabling clear
+  # distinction between different traditions in multi-style gaming environments.
   #
-  # @see https://sashite.dev/documents/snn/1.0.0/ SNN Specification v1.0.0
+  # Format: <style-identifier>
+  # - Uppercase identifier: First player styles (CHESS, SHOGI, XIANGQI)
+  # - Lowercase identifier: Second player styles (chess, shogi, xiangqi)
+  # - Case consistency: Entire identifier must be uppercase or lowercase
+  #
+  # Examples:
+  #   "CHESS"  - First player chess style
+  #   "chess"  - Second player chess style
+  #   "SHOGI"  - First player shōgi style
+  #   "shogi"  - Second player shōgi style
+  #
+  # See: https://sashite.dev/specs/snn/1.0.0/
   module Snn
-    # SNN validation regular expression
-    # Matches: uppercase style (A-Z followed by A-Z0-9*) or lowercase style (a-z followed by a-z0-9*)
-    VALIDATION_REGEX = /\A([A-Z][A-Z0-9]*|[a-z][a-z0-9]*)\z/
-
-    # Check if a string is valid SNN notation
+    # Check if a string is a valid SNN notation
     #
-    # @param snn_string [String] The string to validate
-    # @return [Boolean] true if the string is valid SNN notation, false otherwise
+    # @param snn_string [String] the string to validate
+    # @return [Boolean] true if valid SNN, false otherwise
     #
-    # @example
-    #   Sashite::Snn.valid?("CHESS")      # => true
-    #   Sashite::Snn.valid?("shogi")      # => true
-    #   Sashite::Snn.valid?("Chess")      # => false (mixed case)
-    #   Sashite::Snn.valid?("123")        # => false (must start with letter)
-    #   Sashite::Snn.valid?("")           # => false (empty string)
+    # @example Validate various SNN formats
+    #   Sashite::Snn.valid?("CHESS") # => true
+    #   Sashite::Snn.valid?("Chess") # => false
     def self.valid?(snn_string)
-      return false unless snn_string.is_a?(String)
-      return false if snn_string.empty?
-
-      VALIDATION_REGEX.match?(snn_string)
+      Style.valid?(snn_string)
     end
 
-    # Convenience method to create a style object
+    # Parse an SNN string into a Style object
     #
-    # @param identifier [String] The style identifier
-    # @return [Sashite::Snn::Style] A new style object
-    # @raise [ArgumentError] if the identifier is invalid
+    # @param snn_string [String] SNN notation string
+    # @return [Snn::Style] parsed style object with name and side attributes
+    # @raise [ArgumentError] if the SNN string is invalid
+    # @example Parse different SNN formats
+    #   Sashite::Snn.parse("CHESS") # => #<Snn::Style name=:Chess side=:first>
+    #   Sashite::Snn.parse("chess") # => #<Snn::Style name=:Chess side=:second>
+    #   Sashite::Snn.parse("SHOGI") # => #<Snn::Style name=:Shogi side=:first>
+    def self.parse(snn_string)
+      Style.parse(snn_string)
+    end
+
+    # Create a new style instance
     #
-    # @example
-    #   style = Sashite::Snn.style("CHESS")
-    #   # => #<Sashite::Snn::Style:0x... @identifier="CHESS">
-    def self.style(identifier)
-      Style.new(identifier)
+    # @param name [Symbol] style name (with proper capitalization)
+    # @param side [Symbol] player side (:first or :second)
+    # @return [Snn::Style] new immutable style instance
+    # @raise [ArgumentError] if parameters are invalid
+    # @example Create styles directly
+    #   Sashite::Snn.style(:Chess, :first)  # => #<Snn::Style name=:Chess side=:first>
+    #   Sashite::Snn.style(:Shogi, :second) # => #<Snn::Style name=:Shogi side=:second>
+    def self.style(name, side)
+      Style.new(name, side)
     end
   end
 end

data/lib/sashite-snn.rb

@@ -1,18 +1,14 @@
 # frozen_string_literal: true
 
+require_relative "sashite/snn"
+
 # Sashité namespace for board game notation libraries
+#
+# Sashité provides a collection of libraries for representing and manipulating
+# board game concepts according to the Game Protocol specifications.
+#
+# @see https://sashite.dev/game-protocol/ Game Protocol Foundation
+# @see https://sashite.dev/specs/ Sashité Specifications
+# @author Sashité
 module Sashite
-  # Style Name Notation (SNN) implementation for Ruby
-  #
-  # SNN is a consistent and rule-agnostic format for identifying piece styles
-  # in abstract strategy board games. It provides unambiguous identification
-  # of piece styles by using standardized naming conventions, enabling clear
-  # distinction between different piece traditions, variants, or design
-  # approaches within multi-style gaming environments.
-  #
-  # @see https://sashite.dev/documents/snn/1.0.0/ SNN Specification v1.0.0
-  # @author Sashité
-  # @since 1.0.0
 end
-
-require_relative "sashite/snn"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-snn
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.1
 platform: ruby
 authors:
 - Cyril Kato
@@ -10,12 +10,12 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |
-  A clean, minimal Ruby implementation of Style Name Notation (SNN) for abstract strategy games.
-  SNN provides a consistent and rule-agnostic format for identifying piece styles, enabling
-  clear distinction between different piece traditions, variants, or design approaches within
-  multi-style gaming environments. Features include player-based casing, style validation,
-  and cross-style compatibility. Perfect for game engines, multi-tradition environments,
-  and hybrid gaming systems.
+  SNN (Style Name Notation) provides a rule-agnostic format for identifying styles
+  in abstract strategy board games. This gem implements the SNN Specification v1.0.0 with
+  a modern Ruby interface featuring immutable style objects and functional programming
+  principles. SNN uses standardized naming conventions with case-based side encoding,
+  enabling clear distinction between different traditions in multi-style gaming environments.
+  Perfect for cross-tradition matches, game engines, and hybrid gaming systems.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -52,5 +52,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Style Name Notation (SNN) support for the Ruby language.
+summary: SNN (Style Name Notation) implementation for Ruby with immutable style objects
 test_files: []