sashite-snn 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 189a182b820d000660357679c628df3f1adf451b8fd462f4e667ba9170453a03
+  data.tar.gz: 17a1049e333427994c977efe5c1170fa8114685515f0ff91b9abfb4bcdbe5963
+SHA512:
+  metadata.gz: 6843ef5ffa7f5affa4acfe88b52eb1b837112c853d0668df67f75ac3aedbe1e0f569bd52941626417cf0a66956d472bab61f7f76fedf531a36c6fe60695f0539
+  data.tar.gz: 8b641153ba70b214a4bf7176169d9f456a771347851ec50618777f86b2129381c3f3b6bdb4ccb98b42975651e2d6c14930e69a42bfc233b795251ac2d14fea10

data/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2025 Cyril Kato
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,261 @@
+# Snn.rb
+
+[![Version](https://img.shields.io/github/v/tag/sashite/snn.rb?label=Version&logo=github)](https://github.com/sashite/snn.rb/tags)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/snn.rb/main)
+![Ruby](https://github.com/sashite/snn.rb/actions/workflows/main.yml/badge.svg?branch=main)
+[![License](https://img.shields.io/github/license/sashite/snn.rb?label=License&logo=github)](https://github.com/sashite/snn.rb/raw/main/LICENSE.md)
+
+> **SNN** (Style Name Notation) support 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.
+
+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.
+
+## Installation
+
+```ruby
+# In your Gemfile
+gem "sashite-snn"
+```
+
+Or install manually:
+
+```sh
+gem install sashite-snn
+```
+
+## SNN Format
+
+A SNN record consists of an identifier starting with an alphabetic character, followed by optional alphabetic characters and digits:
+
+```
+<style-id>
+```
+
+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
+
+## Basic Usage
+
+### Creating Style Objects
+
+The primary interface is the `Sashite::Snn::Style` class, which represents a style identifier in SNN format:
+
+```ruby
+require "sashite/snn"
+
+# Parse a SNN string into a style object
+style = Sashite::Snn::Style.parse("CHESS")
+# => #<Sashite::Snn::Style:0x... @identifier="CHESS">
+
+lowercase_style = Sashite::Snn::Style.parse("shogi")
+# => #<Sashite::Snn::Style:0x... @identifier="shogi">
+
+# Create directly with constructor
+style = Sashite::Snn::Style.new("CHESS")
+lowercase_style = Sashite::Snn::Style.new("makruk")
+
+# Convenience method
+style = Sashite::Snn.style("XIANGQI")
+```
+
+### Converting to String and Symbol
+
+Convert a style object to different representations:
+
+```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
+```
+
+### Player Association
+
+Check which player a style belongs to:
+
+```ruby
+first_player_style = Sashite::Snn::Style.parse("CHESS")
+first_player_style.first_player?  # => true
+first_player_style.second_player? # => false
+
+second_player_style = Sashite::Snn::Style.parse("shogi")
+second_player_style.first_player?  # => false
+second_player_style.second_player? # => true
+```
+
+## Validation
+
+All parsing automatically validates input according to the SNN specification:
+
+```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)
+```
+
+## Examples of SNN in Practice
+
+### Classic Game Styles
+
+```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
+
+# 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
+
+# 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
+```
+
+### Variant Styles
+
+```ruby
+# Chess variants
+fischer_random = Sashite::Snn::Style.parse("CHESS960")
+king_of_hill = Sashite::Snn::Style.parse("CHESSKING")
+
+# Shogi variants
+mini_shogi = Sashite::Snn::Style.parse("MINISHOGI")
+handicap_shogi = Sashite::Snn::Style.parse("SHOGI9")
+
+# Other traditions
+thai_makruk = Sashite::Snn::Style.parse("MAKRUK")
+korean_janggi = Sashite::Snn::Style.parse("JANGGI")
+```
+
+### Cross-Style Gaming
+
+```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" }
+}
+```
+
+## API Reference
+
+### Module Methods
+
+- `Sashite::Snn.valid?(snn_string)` - Check if a string is valid SNN notation
+- `Sashite::Snn.style(identifier)` - Convenience method to create style objects
+
+### Sashite::Snn::Style Class Methods
+
+- `Sashite::Snn::Style.parse(snn_string)` - Parse a SNN string into a style object
+- `Sashite::Snn::Style.new(identifier)` - Create a new style instance
+
+### Instance Methods
+
+#### 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?`
+
+#### Conversion
+- `#to_s` - Convert to SNN string representation
+- `#to_sym` - Convert to symbol representation
+- `#inspect` - Detailed string representation for debugging
+
+## Properties of SNN
+
+* **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
+
+## Constraints
+
+* 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**
+
+## Use Cases
+
+SNN is particularly useful in the following scenarios:
+
+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
+
+## Documentation
+
+- [Official SNN Specification](https://sashite.dev/documents/snn/1.0.0/)
+- [API Documentation](https://rubydoc.info/github/sashite/snn.rb/main)
+
+## 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).
+
+## About Sashité
+
+This project is maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of Chinese, Japanese, and Western chess cultures.

data/lib/sashite/snn/style.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Snn
+    # Represents a style identifier in SNN 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
+    #
+    # @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")
+    class Style
+      # @return [String] The style identifier
+      attr_reader :identifier
+
+      # 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)
+
+        @identifier = identifier.freeze
+
+        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
+      #
+      # @example
+      #   style = Sashite::Snn::Style.parse("CHESS")
+      #   # => #<Sashite::Snn::Style:0x... @identifier="CHESS">
+      def self.parse(snn_string)
+        new(snn_string)
+      end
+
+      # Check if this style belongs to the first player
+      #
+      # @return [Boolean] true if the style is uppercase (first player), false otherwise
+      #
+      # @example
+      #   Sashite::Snn::Style.new("CHESS").first_player?  # => true
+      #   Sashite::Snn::Style.new("shogi").first_player?  # => false
+      def first_player?
+        uppercase?
+      end
+
+      # Check if this style belongs to the second player
+      #
+      # @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?
+      end
+
+      # Check if the style identifier is uppercase
+      #
+      # @return [Boolean] true if the identifier is uppercase, false otherwise
+      #
+      # @example
+      #   Sashite::Snn::Style.new("CHESS").uppercase?  # => true
+      #   Sashite::Snn::Style.new("chess").uppercase?  # => false
+      def uppercase?
+        identifier == identifier.upcase
+      end
+
+      # Check if the style identifier is lowercase
+      #
+      # @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
+      end
+
+      # Convert the style to its string representation
+      #
+      # @return [String] The style identifier
+      #
+      # @example
+      #   Sashite::Snn::Style.new("CHESS").to_s  # => "CHESS"
+      def to_s
+        identifier
+      end
+
+      # Convert the style to a symbol
+      #
+      # @return [Symbol] The style identifier as a symbol
+      #
+      # @example
+      #   Sashite::Snn::Style.new("CHESS").to_sym  # => :CHESS
+      def to_sym
+        identifier.to_sym
+      end
+
+      # String representation for debugging
+      #
+      # @return [String] A detailed string representation
+      def inspect
+        "#<#{self.class}:0x#{object_id.to_s(16)} @identifier=#{identifier.inspect}>"
+      end
+
+      # Equality comparison
+      #
+      # @param other [Object] The object to compare with
+      # @return [Boolean] true if both objects are Style instances with the same identifier
+      def ==(other)
+        other.is_a?(Style) && identifier == other.identifier
+      end
+
+      # Alias for equality comparison
+      alias eql? ==
+
+      # Hash code for use in hashes and sets
+      #
+      # @return [Integer] The hash code
+      def hash
+        [self.class, identifier].hash
+      end
+    end
+  end
+end

data/lib/sashite/snn.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "snn/style"
+
+module Sashite
+  # Style Name Notation (SNN) module
+  #
+  # 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.
+  #
+  # @see https://sashite.dev/documents/snn/1.0.0/ SNN Specification v1.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
+    #
+    # @param snn_string [String] The string to validate
+    # @return [Boolean] true if the string is valid SNN notation, 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?
+
+      VALIDATION_REGEX.match?(snn_string)
+    end
+
+    # Convenience method to create a style object
+    #
+    # @param identifier [String] The style identifier
+    # @return [Sashite::Snn::Style] A new style object
+    # @raise [ArgumentError] if the identifier is invalid
+    #
+    # @example
+    #   style = Sashite::Snn.style("CHESS")
+    #   # => #<Sashite::Snn::Style:0x... @identifier="CHESS">
+    def self.style(identifier)
+      Style.new(identifier)
+    end
+  end
+end

data/lib/sashite-snn.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Sashité namespace for board game notation libraries
+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

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: sashite-snn
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Cyril Kato
+bindir: bin
+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.
+email: contact@cyril.email
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- lib/sashite-snn.rb
+- lib/sashite/snn.rb
+- lib/sashite/snn/style.rb
+homepage: https://github.com/sashite/snn.rb
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/sashite/snn.rb/issues
+  documentation_uri: https://rubydoc.info/github/sashite/snn.rb/main
+  homepage_uri: https://github.com/sashite/snn.rb
+  source_code_uri: https://github.com/sashite/snn.rb
+  specification_uri: https://sashite.dev/documents/snn/1.0.0/
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Style Name Notation (SNN) support for the Ruby language.
+test_files: []