sashite-snn 3.1.0 → 4.0.0

data/lib/sashite/snn/parser.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+require_relative "errors"
+
+module Sashite
+  module Snn
+    # Secure parser for SNN (Style Name Notation) strings.
+    #
+    # Designed for untrusted input: validates bounds first, parses character
+    # by character, and enforces strict constraints at every step.
+    #
+    # @example
+    #   Parser.parse("Chess")     # => "Chess"
+    #   Parser.parse("Chess960")  # => "Chess960"
+    #   Parser.parse("chess")     # => raises Errors::Argument
+    #
+    # @see https://sashite.dev/specs/snn/1.0.0/
+    module Parser
+      # Byte ranges for validation
+      UPPERCASE_MIN = 0x41  # A
+      UPPERCASE_MAX = 0x5A  # Z
+      LOWERCASE_MIN = 0x61  # a
+      LOWERCASE_MAX = 0x7A  # z
+      DIGIT_MIN     = 0x30  # 0
+      DIGIT_MAX     = 0x39  # 9
+
+      class << self
+        # Parses an SNN string, validating its format.
+        #
+        # @param input [String] The SNN string to parse
+        # @return [String] The validated SNN string
+        # @raise [Errors::Argument] If the input is invalid
+        #
+        # @example
+        #   Parser.parse("Chess")     # => "Chess"
+        #   Parser.parse("Chess960")  # => "Chess960"
+        #   Parser.parse("")          # => raises Errors::Argument
+        def parse(input)
+          validate_input_type!(input)
+          validate_not_empty!(input)
+          validate_length!(input)
+          validate_format!(input)
+
+          input
+        end
+
+        # Reports whether the input is a valid SNN string.
+        #
+        # @param input [Object] The input to validate
+        # @return [Boolean] true if valid, false otherwise
+        #
+        # @example
+        #   Parser.valid?("Chess")  # => true
+        #   Parser.valid?("chess")  # => false
+        #   Parser.valid?(nil)      # => false
+        def valid?(input)
+          parse(input)
+          true
+        rescue Errors::Argument
+          false
+        end
+
+        private
+
+        # Validates input is a String.
+        def validate_input_type!(input)
+          return if ::String === input
+
+          raise Errors::Argument, Errors::Argument::Messages::INVALID_FORMAT
+        end
+
+        # Validates input is not empty.
+        def validate_not_empty!(input)
+          return unless input.empty?
+
+          raise Errors::Argument, Errors::Argument::Messages::EMPTY_INPUT
+        end
+
+        # Validates input does not exceed maximum length.
+        def validate_length!(input)
+          return if input.bytesize <= Constants::MAX_STRING_LENGTH
+
+          raise Errors::Argument, Errors::Argument::Messages::INPUT_TOO_LONG
+        end
+
+        # Validates the SNN format using byte-level parsing.
+        #
+        # Format: uppercase letter, then letters, then optional digits at end.
+        def validate_format!(input)
+          bytes = input.bytes
+          index = 0
+
+          # State 1: First byte must be uppercase letter
+          raise_invalid_format! unless uppercase?(bytes[index])
+          index += 1
+
+          # State 2: Parse letters (transition to digits allowed)
+          while index < bytes.length
+            byte = bytes[index]
+
+            if letter?(byte)
+              index += 1
+            elsif digit?(byte)
+              # Transition to digit state
+              index += 1
+              break
+            else
+              raise_invalid_format!
+            end
+          end
+
+          # State 3: Parse remaining digits only (no return to letters)
+          while index < bytes.length
+            byte = bytes[index]
+            raise_invalid_format! unless digit?(byte)
+            index += 1
+          end
+        end
+
+        # Character class predicates
+
+        def uppercase?(byte)
+          byte >= UPPERCASE_MIN && byte <= UPPERCASE_MAX
+        end
+
+        def lowercase?(byte)
+          byte >= LOWERCASE_MIN && byte <= LOWERCASE_MAX
+        end
+
+        def letter?(byte)
+          uppercase?(byte) || lowercase?(byte)
+        end
+
+        def digit?(byte)
+          byte >= DIGIT_MIN && byte <= DIGIT_MAX
+        end
+
+        def raise_invalid_format!
+          raise Errors::Argument, Errors::Argument::Messages::INVALID_FORMAT
+        end
+      end
+    end
+  end
+end

data/lib/sashite/snn/style_name.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+require_relative "errors"
+require_relative "parser"
+
+module Sashite
+  module Snn
+    # Represents a validated SNN (Style Name Notation) style name.
+    #
+    # A StyleName encodes a single attribute:
+    # - name: the validated SNN string (PascalCase with optional numeric suffix)
+    #
+    # Instances are immutable (frozen after creation).
+    #
+    # @example Creating style names
+    #   snn = StyleName.new("Chess")
+    #   snn = StyleName.new("Chess960")
+    #
+    # @example String conversion
+    #   StyleName.new("Chess").to_s     # => "Chess"
+    #   StyleName.new("Chess960").to_s  # => "Chess960"
+    #
+    # @see https://sashite.dev/specs/snn/1.0.0/
+    class StyleName
+      # Maximum length of a valid SNN string.
+      MAX_STRING_LENGTH = Constants::MAX_STRING_LENGTH
+
+      # @return [String] The validated SNN style name
+      attr_reader :name
+
+      # Creates a new StyleName instance.
+      #
+      # @param name [String] The SNN style name
+      # @return [StyleName] A new frozen StyleName instance
+      # @raise [Errors::Argument] If the name is invalid
+      #
+      # @example
+      #   StyleName.new("Chess")
+      #   StyleName.new("Chess960")
+      def initialize(name)
+        @name = Parser.parse(name)
+
+        freeze
+      end
+
+      # ========================================================================
+      # String Conversion
+      # ========================================================================
+
+      # Returns the SNN string representation.
+      #
+      # @return [String] The style name
+      #
+      # @example
+      #   StyleName.new("Chess").to_s  # => "Chess"
+      def to_s
+        name
+      end
+
+      # ========================================================================
+      # Equality
+      # ========================================================================
+
+      # Checks equality with another StyleName.
+      #
+      # @param other [Object] The object to compare
+      # @return [Boolean] true if equal
+      #
+      # @example
+      #   snn1 = StyleName.new("Chess")
+      #   snn2 = StyleName.new("Chess")
+      #   snn1 == snn2  # => true
+      def ==(other)
+        return false unless self.class === other
+
+        name == other.name
+      end
+
+      alias eql? ==
+
+      # Returns a hash code for the StyleName.
+      #
+      # @return [Integer] Hash code
+      def hash
+        name.hash
+      end
+
+      # Returns an inspect string for the StyleName.
+      #
+      # @return [String] Inspect representation
+      #
+      # @example
+      #   StyleName.new("Chess").inspect  # => "#<Sashite::Snn::StyleName Chess>"
+      def inspect
+        "#<#{self.class} #{self}>"
+      end
+    end
+  end
+end

data/lib/sashite/snn.rb

@@ -1,93 +1,56 @@
 # frozen_string_literal: true
 
-require_relative "snn/name"
+require_relative "snn/constants"
+require_relative "snn/errors"
+require_relative "snn/parser"
+require_relative "snn/style_name"
 
 module Sashite
-  # SNN (Style Name Notation) implementation for Ruby
+  # SNN (Style Name Notation) implementation for Ruby.
   #
-  # Provides a foundational naming system for identifying styles in abstract strategy board games.
-  # SNN uses canonical, human-readable alphabetic names with case encoding to represent both
-  # style identity and player assignment.
+  # SNN provides a human-readable naming system for game styles (Piece Styles)
+  # in abstract strategy board games. It uses PascalCase names with optional
+  # numeric suffixes to identify movement traditions or game variants.
   #
-  # Format: All uppercase OR all lowercase alphabetic characters
+  # @example Parsing
+  #   snn = Sashite::Snn.parse("Chess")
+  #   snn.name  # => "Chess"
   #
-  # Examples:
-  #   "CHESS"    - Chess style for first player
-  #   "chess"    - Chess style for second player
-  #   "SHOGI"    - Shōgi style for first player
-  #   "shogi"    - Shōgi style for second player
-  #   "XIANGQI"  - Xiangqi style for first player
-  #   "xiangqi"  - Xiangqi style for second player
+  # @example Validation
+  #   Sashite::Snn.valid?("Chess960")  # => true
+  #   Sashite::Snn.valid?("chess")     # => false
   #
-  # Case Encoding:
-  #   - UPPERCASE names represent the first player's style
-  #   - lowercase names represent the second player's style
-  #
-  # Constraints:
-  #   - Alphabetic characters only (A-Z, a-z)
-  #   - Case consistency required (all uppercase OR all lowercase)
-  #   - No digits, no special characters, no mixed case
-  #
-  # As a foundational primitive, SNN has no dependencies and serves as a building block
-  # for formal style identification in the Sashité ecosystem.
-  #
-  # See: https://sashite.dev/specs/snn/1.0.0/
+  # @see https://sashite.dev/specs/snn/1.0.0/
   module Snn
-    # Check if a string is valid SNN notation
+    # Parses an SNN string into a StyleName.
     #
-    # Valid SNN strings must contain only alphabetic characters in consistent case
-    # (either all uppercase or all lowercase).
+    # @param input [String] The SNN string to parse
+    # @return [StyleName] A new StyleName instance
+    # @raise [Errors::Argument] If the input is invalid
     #
-    # @param snn_string [String] the string to validate
-    # @return [Boolean] true if valid SNN, false otherwise
+    # @example
+    #   snn = Sashite::Snn.parse("Chess")
+    #   snn.name  # => "Chess"
     #
-    # @example Validate SNN strings
-    #   Sashite::Snn.valid?("CHESS")     # => true
-    #   Sashite::Snn.valid?("shogi")     # => true
-    #   Sashite::Snn.valid?("Chess")     # => false (mixed case)
-    #   Sashite::Snn.valid?("CHESS960")  # => false (contains digits)
-    #   Sashite::Snn.valid?("GO9X9")     # => false (contains digits)
-    def self.valid?(snn_string)
-      Name.valid?(snn_string)
+    # @example With numeric suffix
+    #   snn = Sashite::Snn.parse("Chess960")
+    #   snn.name  # => "Chess960"
+    def self.parse(input)
+      StyleName.new(input)
     end
 
-    # Parse an SNN string into a Name object
-    #
-    # Converts a valid SNN string into an immutable Name object. The name must follow
-    # SNN format rules: all uppercase or all lowercase alphabetic characters only.
-    #
-    # @param snn_string [String] the name string
-    # @return [Snn::Name] a parsed name object
-    # @raise [ArgumentError] if the name is invalid
-    #
-    # @example Parse valid SNN names
-    #   Sashite::Snn.parse("SHOGI")    # => #<Snn::Name value="SHOGI">
-    #   Sashite::Snn.parse("chess")    # => #<Snn::Name value="chess">
-    #
-    # @example Invalid names raise errors
-    #   Sashite::Snn.parse("Chess")    # => ArgumentError (mixed case)
-    #   Sashite::Snn.parse("CHESS960") # => ArgumentError (contains digits)
-    def self.parse(snn_string)
-      Name.parse(snn_string)
-    end
-
-    # Create a new Name instance directly
-    #
-    # Constructs a Name object from a string or symbol. The value must follow
-    # SNN format rules: all uppercase or all lowercase alphabetic characters only.
-    #
-    # @param value [String, Symbol] style name to construct
-    # @return [Snn::Name] new name instance
-    # @raise [ArgumentError] if name format is invalid
-    #
-    # @example Create names
-    #   Sashite::Snn.name("XIANGQI") # => #<Snn::Name value="XIANGQI">
-    #   Sashite::Snn.name(:makruk)   # => #<Snn::Name value="makruk">
-    #
-    # @example Invalid formats raise errors
-    #   Sashite::Snn.name("Chess960") # => ArgumentError
-    def self.name(value)
-      Name.new(value)
+    # Reports whether the input is a valid SNN string.
+    #
+    # @param input [Object] The input to validate
+    # @return [Boolean] true if valid, false otherwise
+    #
+    # @example
+    #   Sashite::Snn.valid?("Chess")     # => true
+    #   Sashite::Snn.valid?("Chess960")  # => true
+    #   Sashite::Snn.valid?("chess")     # => false
+    #   Sashite::Snn.valid?("")          # => false
+    def self.valid?(input)
+      Parser.valid?(input)
     end
   end
 end

data/lib/sashite-snn.rb

@@ -7,7 +7,7 @@ require_relative "sashite/snn"
 # Sashité provides a collection of libraries for representing and manipulating
 # board game concepts according to the Sashité Protocol specifications.
 #
-# @see https://sashite.dev/protocol/ Sashité Protocol
+# @see https://sashite.dev/game-protocol/ Sashité Protocol
 # @see https://sashite.dev/specs/ Sashité Specifications
 # @author Sashité
 module Sashite

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-snn
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -9,38 +9,35 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: |
-  SNN (Style Name Notation) provides a foundational, rule-agnostic naming system for identifying
-  game styles in abstract strategy board games. This gem implements the SNN Specification v1.0.0
-  with a modern Ruby interface featuring immutable style name objects and functional programming
-  principles.
-
-  SNN uses case-consistent alphabetic names (e.g., "CHESS", "SHOGI", "XIANGQI" for first player;
-  "chess", "shogi", "xiangqi" for second player) to unambiguously represent both style identity
-  and player assignment. As a foundational primitive with no dependencies, SNN serves as a building
-  block for formal style identification across the Sashité ecosystem.
-
-  Format: All uppercase OR all lowercase alphabetic characters only (no digits, no special characters).
-  Ideal for game engines, protocols, and tools requiring clear and extensible style identifiers.
+description: SNN (Style Name Notation) implementation for Ruby. Provides a rule-agnostic
+  format for identifying game styles in abstract strategy board games with immutable
+  style name objects and functional programming principles.
 email: contact@cyril.email
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- LICENSE.md
+- LICENSE
 - README.md
 - lib/sashite-snn.rb
 - lib/sashite/snn.rb
-- lib/sashite/snn/name.rb
+- lib/sashite/snn/constants.rb
+- lib/sashite/snn/errors.rb
+- lib/sashite/snn/errors/argument.rb
+- lib/sashite/snn/errors/argument/messages.rb
+- lib/sashite/snn/parser.rb
+- lib/sashite/snn/style_name.rb
 homepage: https://github.com/sashite/snn.rb
 licenses:
-- MIT
+- Apache-2.0
 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/specs/snn/1.0.0/
+  wiki_uri: https://sashite.dev/specs/snn/1.0.0/examples/
+  funding_uri: https://github.com/sponsors/sashite
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -56,8 +53,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 4.0.3
 specification_version: 4
-summary: SNN (Style Name Notation) - foundational naming system for abstract strategy
-  game styles
+summary: SNN (Style Name Notation) implementation for Ruby with immutable style name
+  objects
 test_files: []

data/LICENSE.md

@@ -1,22 +0,0 @@
-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/lib/sashite/snn/name.rb

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