sashite-snn 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 189a182b820d000660357679c628df3f1adf451b8fd462f4e667ba9170453a03
-  data.tar.gz: 17a1049e333427994c977efe5c1170fa8114685515f0ff91b9abfb4bcdbe5963
+  metadata.gz: c75eb6af8fa8c0ff0a9791e0ecc0fe49b7e6c0827733e96f2e37e552ddca50b0
+  data.tar.gz: 2ac49000ca7ff3f2ae01e0a7d240f2fb99d5cab34a915b9799a5088c7461b4f3
 SHA512:
-  metadata.gz: 6843ef5ffa7f5affa4acfe88b52eb1b837112c853d0668df67f75ac3aedbe1e0f569bd52941626417cf0a66956d472bab61f7f76fedf531a36c6fe60695f0539
-  data.tar.gz: 8b641153ba70b214a4bf7176169d9f456a771347851ec50618777f86b2129381c3f3b6bdb4ccb98b42975651e2d6c14930e69a42bfc233b795251ac2d14fea10
+  metadata.gz: 9ec03703cf421329344a597f91d4157e4b44f1d5347cb4f8eea1a5c9e79e6800ad0880f6d9a8ad003df18d48ab5afb084d6526ffcbf6df14323b21ee751fc54e
+  data.tar.gz: e95c9a8e58fbe6254e546456a5de92a79de1eeb33688292ec1c58f58ba30b6a94357a61d1396a1a639e0051c772b888af355e421a3726b2faf3ae7179450afd6

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 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.
+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/documents/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,236 +26,455 @@ Or install manually:
 gem install sashite-snn
 ```
 
-## SNN Format
+## Usage
 
-A SNN record consists of an identifier starting with an alphabetic character, followed by optional alphabetic characters and digits:
+```ruby
+require "sashite/snn"
 
-```
-<style-id>
+# 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"
 ```
 
-Where:
-- The identifier starts with an alphabetic character (`A-Z` for uppercase, `a-z` for lowercase)
-- Subsequent characters may include alphabetic characters and digits (`A-Z`, `0-9` for uppercase styles; `a-z`, `0-9` for lowercase styles)
-- **Uppercase** format denotes styles belonging to the first player
-- **Lowercase** format denotes styles belonging to the second player
-- The entire identifier must be entirely uppercase or entirely lowercase
+## Format Specification
 
-## Basic Usage
+### Structure
+```
+<style-identifier>
+```
 
-### Creating Style Objects
+### Components
 
-The primary interface is the `Sashite::Snn::Style` class, which represents a style identifier in SNN format:
+- **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)
 
+### Regular Expression
 ```ruby
-require "sashite/snn"
+/\A([A-Z][A-Z0-9]*|[a-z][a-z0-9]*)\z/
+```
 
-# Parse a SNN string into a style object
-style = Sashite::Snn::Style.parse("CHESS")
-# => #<Sashite::Snn::Style:0x... @identifier="CHESS">
+### 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
 
-lowercase_style = Sashite::Snn::Style.parse("shogi")
-# => #<Sashite::Snn::Style:0x... @identifier="shogi">
+## Game Examples
 
-# Create directly with constructor
-style = Sashite::Snn::Style.new("CHESS")
-lowercase_style = Sashite::Snn::Style.new("makruk")
+### 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"
+```
 
-# Convenience method
-style = Sashite::Snn.style("XIANGQI")
+### Chess Variants
+```ruby
+# Fischer Random Chess
+chess960_white = Sashite::Snn.style(:Chess960, :first)
+chess960_black = chess960_white.flip
+chess960_black.to_s                               # => "chess960"
+
+# King of the Hill Chess
+koth = Sashite::Snn.style(:Koth, :first)
+koth.to_s                                         # => "KOTH"
+
+# Three-Check Chess
+threecheck = Sashite::Snn.style(:Threecheck, :first)
 ```
 
-### Converting to String and Symbol
+### Shōgi Variants
+```ruby
+# Traditional Shōgi
+standard_shogi = Sashite::Snn.style(:Shogi, :first)
+
+# Mini Shōgi
+mini_shogi = Sashite::Snn.style(:Minishogi, :first)
 
-Convert a style object to different representations:
+# Chu Shōgi
+chu_shogi = Sashite::Snn.style(:Chushogi, :first)
+```
 
+### Multi-Style Gaming
 ```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
+# 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
+
+# Style compatibility check
+def compatible_styles?(style1, style2)
+  # Styles are compatible if they have different sides
+  !style1.same_side?(style2)
 end
+
+chess_white = Sashite::Snn.parse("CHESS")
+shogi_black = Sashite::Snn.parse("shogi")
+puts compatible_styles?(chess_white, shogi_black)  # => true
 ```
 
-### Player Association
+## API Reference
 
-Check which player a style belongs to:
+### Main Module Methods
 
-```ruby
-first_player_style = Sashite::Snn::Style.parse("CHESS")
-first_player_style.first_player?  # => true
-first_player_style.second_player? # => false
+- `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
 
-second_player_style = Sashite::Snn::Style.parse("shogi")
-second_player_style.first_player?  # => false
-second_player_style.second_player? # => true
-```
+### Style Class
 
-## Validation
+#### 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)
 
-All parsing automatically validates input according to the SNN specification:
+#### Attribute Access
+- `#name` - Get style name (symbol with proper capitalization)
+- `#side` - Get player side (:first or :second)
+- `#to_s` - Convert to SNN string representation
+
+#### Name and Case Handling
+
+**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
-# Valid SNN strings
-Sashite::Snn::Style.parse("CHESS")      # ✓
-Sashite::Snn::Style.parse("shogi")      # ✓
-Sashite::Snn::Style.parse("CHESS960")   # ✓
-Sashite::Snn::Style.parse("makruk")     # ✓
-
-# Valid constructor calls
-Sashite::Snn::Style.new("XIANGQI")      # ✓
-Sashite::Snn::Style.new("janggi")       # ✓
-
-# Convenience method
-Sashite::Snn.style("MINISHOGI") # ✓
-
-# Check validity
-Sashite::Snn.valid?("CHESS")    # => true
-Sashite::Snn.valid?("Chess")    # => false (mixed case)
-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)
+# 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)
 ```
 
-## Examples of SNN in Practice
+#### Side Queries
+- `#first_player?` - Check if first player style
+- `#second_player?` - Check if second player style
 
-### Classic Game Styles
+#### 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
+
+#### Comparison Methods
+- `#same_name?(other)` - Check if same style name
+- `#same_side?(other)` - Check if same side
+- `#==(other)` - Full equality comparison
+
+### Constants
+- `Sashite::Snn::SNN_REGEX` - Regular expression for SNN validation
+
+## Advanced Usage
+
+### Name Normalization Examples
 
 ```ruby
-# International Chess
-first_player = Sashite::Snn::Style.parse("CHESS")   # First player uses chess pieces
-second_player = Sashite::Snn::Style.parse("chess")  # Second player uses chess pieces
+# Parsing different cases results in same name
+white_chess = Sashite::Snn.parse("CHESS")
+black_chess = Sashite::Snn.parse("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
+# Names are normalized with proper capitalization
+white_chess.name  # => :Chess
+black_chess.name  # => :Chess (same name!)
 
-# 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
+# Sides are different
+white_chess.side  # => :first
+black_chess.side  # => :second
+
+# Display follows side convention
+white_chess.to_s  # => "CHESS"
+black_chess.to_s  # => "chess"
+
+# Same name, different sides
+white_chess.same_name?(black_chess)  # => true
+white_chess.same_side?(black_chess)  # => false
 ```
 
-### Variant Styles
+### 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"
+```
 
+### Game Configuration Management
 ```ruby
-# Chess variants
-fischer_random = Sashite::Snn::Style.parse("CHESS960")
-king_of_hill = Sashite::Snn::Style.parse("CHESSKING")
+class GameConfiguration
+  def initialize
+    @player_styles = {}
+  end
 
-# Shogi variants
-mini_shogi = Sashite::Snn::Style.parse("MINISHOGI")
-handicap_shogi = Sashite::Snn::Style.parse("SHOGI9")
+  def set_player_style(player, style_name)
+    side = player == :white ? :first : :second
+    @player_styles[player] = Sashite::Snn.style(style_name, side)
+  end
 
-# Other traditions
-thai_makruk = Sashite::Snn::Style.parse("MAKRUK")
-korean_janggi = Sashite::Snn::Style.parse("JANGGI")
+  def get_player_style(player)
+    @player_styles[player]
+  end
+
+  def style_mismatch?
+    return false if @player_styles.size < 2
+
+    styles = @player_styles.values
+    !styles.all? { |style| style.same_name?(styles.first) }
+  end
+
+  def cross_tradition_match?
+    return false if @player_styles.size < 2
+
+    style_names = @player_styles.values.map(&:name).uniq
+    style_names.size > 1
+  end
+end
+
+# Usage
+config = GameConfiguration.new
+config.set_player_style(:white, :Chess)
+config.set_player_style(:black, :Shogi)
+
+puts config.cross_tradition_match?  # => true
+puts config.style_mismatch?         # => true
+
+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 as uppercase symbol |
+| **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?` - Alias for `#first_player?`
-- `#lowercase?` - Alias for `#second_player?`
+* **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
+
+### Name Normalization Convention
+
+SNN follows a strict name normalization convention:
+
+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
 
-## Properties of SNN
+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
 
-* **Rule-agnostic**: SNN does not encode game states, legality, validity, or game-specific conditions
-* **Unambiguous identification**: Different piece styles can coexist without naming conflicts
-* **Canonical representation**: Equivalent styles yield identical strings
-* **Cross-style support**: Enables games where players use different piece traditions
-* **Case consistency**: Each identifier is entirely uppercase or entirely lowercase
-* **Fixed assignment**: Style assignment to players remains constant throughout a game
+### Example Flow
 
-## Constraints
+```ruby
+# Input: "chess" (lowercase)
+# ↓ Parsing
+# name: :Chess (normalized with proper capitalization)
+# side: :second (inferred from lowercase input)
+# ↓ Display
+# SNN: "chess" (final representation)
+```
 
-* 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
-* Mixed casing is not permitted within a single identifier
-* Style assignment to players remains **fixed throughout a game**
+This ensures that `parse(snn).to_s == snn` for all valid SNN strings while maintaining internal consistency.
 
-## Use Cases
+## System Constraints
 
-SNN is particularly useful in the following scenarios:
+- **Alphanumeric identifiers** starting with a letter
+- **Exactly 2 players** (uppercase/lowercase distinction)
+- **Case consistency** within each identifier (no mixed case)
 
-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
+## Related Specifications
+
+- [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
 
-- [Official SNN Specification](https://sashite.dev/documents/snn/1.0.0/)
+- [Official SNN Specification v1.0.0](https://sashite.dev/specs/snn/1.0.0/)
+- [SNN Examples Documentation](https://sashite.dev/specs/snn/1.0.0/examples/)
+- [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
 
-The [gem](https://rubygems.org/gems/sashite-snn) is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
 
-## About Sashité
+## About
 
-This project is maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of Chinese, Japanese, and Western chess cultures.
+Maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of board game cultures.

data/lib/sashite/snn/style.rb

@@ -2,141 +2,246 @@
 
 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
-      #
-      # @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
+      # Parse an SNN string into a Style object
       #
+      # @param snn_string [String] SNN notation string
+      # @return [Style] new style instance
+      # @raise [ArgumentError] if the SNN string is invalid
       # @example
-      #   style = Sashite::Snn::Style.parse("CHESS")
-      #   # => #<Sashite::Snn::Style:0x... @identifier="CHESS">
+      #   Snn::Style.parse("CHESS")     # => #<Snn::Style name=:Chess side=:first>
+      #   Snn::Style.parse("chess")     # => #<Snn::Style name=:Chess side=:second>
+      #   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
-      #
-      # @return [Boolean] true if the style is uppercase (first player), false otherwise
+      # Convert the style to its SNN string representation
       #
+      # @return [String] SNN notation string
       # @example
-      #   Sashite::Snn::Style.new("CHESS").first_player?  # => true
-      #   Sashite::Snn::Style.new("shogi").first_player?  # => false
-      def first_player?
-        uppercase?
+      #   style.to_s  # => "CHESS"
+      #   style.to_s  # => "chess"
+      #   style.to_s  # => "SHOGI"
+      def to_s
+        first_player? ? name.to_s.upcase : name.to_s.downcase
       end
 
-      # Check if this style belongs to the second player
-      #
-      # @return [Boolean] true if the style is lowercase (second player), false otherwise
+      # Create a new style with opposite ownership (side)
       #
+      # @return [Style] new style instance with flipped side
       # @example
-      #   Sashite::Snn::Style.new("CHESS").second_player?  # => false
-      #   Sashite::Snn::Style.new("shogi").second_player?  # => true
-      def second_player?
-        lowercase?
+      #   style.flip  # (:Chess, :first) => (:Chess, :second)
+      def flip
+        self.class.new(name, opposite_side)
       end
 
-      # Check if the style identifier is uppercase
-      #
-      # @return [Boolean] true if the identifier is uppercase, false otherwise
+      # Create a new style with a different name (keeping same side)
       #
+      # @param new_name [Symbol] new name (with proper capitalization)
+      # @return [Style] new style instance with different name
       # @example
-      #   Sashite::Snn::Style.new("CHESS").uppercase?  # => true
-      #   Sashite::Snn::Style.new("chess").uppercase?  # => false
-      def uppercase?
-        identifier == identifier.upcase
+      #   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
 
-      # Check if the style identifier is lowercase
-      #
-      # @return [Boolean] true if the identifier is lowercase, false otherwise
+      # Create a new style with a different side (keeping same name)
       #
+      # @param new_side [Symbol] :first or :second
+      # @return [Style] new style instance with different side
       # @example
-      #   Sashite::Snn::Style.new("CHESS").lowercase?  # => false
-      #   Sashite::Snn::Style.new("chess").lowercase?  # => true
-      def lowercase?
-        identifier == identifier.downcase
+      #   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
 
-      # Convert the style to its string representation
+      # Check if the style belongs to the first player
       #
-      # @return [String] The style identifier
-      #
-      # @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
       #
+      # @param other [Style] style to compare with
+      # @return [Boolean] true if same name
       # @example
-      #   Sashite::Snn::Style.new("CHESS").to_sym  # => :CHESS
-      def to_sym
-        identifier.to_sym
+      #   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 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 styles are equal
       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
       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,69 @@
 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/
+    # Regular expression for SNN validation
+    # Matches: uppercase alphanumeric identifier OR lowercase alphanumeric identifier
+    SNN_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] 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)
-    def self.valid?(snn_string)
-      return false unless snn_string.is_a?(String)
-      return false if snn_string.empty?
+    #   Sashite::Snn.valid?("CHESS")    # => true
+    #   Sashite::Snn.valid?("chess")    # => true
+    #   Sashite::Snn.valid?("Chess")    # => false
+    #   Sashite::Snn.valid?("123")      # => false
+    def self.valid?(snn)
+      return false unless snn.is_a?(::String)
 
-      VALIDATION_REGEX.match?(snn_string)
+      snn.match?(SNN_REGEX)
     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] new style instance
+    # @raise [ArgumentError] if the SNN string is invalid
+    # @example
+    #   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
     #
+    # @param name [Symbol] style name (with proper capitalization)
+    # @param side [Symbol] player side (:first or :second)
+    # @return [Snn::Style] new style instance
+    # @raise [ArgumentError] if parameters are invalid
     # @example
-    #   style = Sashite::Snn.style("CHESS")
-    #   # => #<Sashite::Snn::Style:0x... @identifier="CHESS">
-    def self.style(identifier)
-      Style.new(identifier)
+    #   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.0
+  version: 1.1.0
 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: []
@@ -50,7 +50,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+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: []