sashite-sin 2.1.0 → 3.1.0

data/lib/sashite/sin/parser.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+require_relative "errors"
+
+module Sashite
+  module Sin
+    # Parses SIN (Style Identifier Notation) strings.
+    #
+    # The parser uses byte-level validation to ensure security against
+    # malformed input, Unicode lookalikes, and injection attacks.
+    #
+    # @example Parsing a valid SIN string
+    #   Parser.parse("C")  # => { abbr: :C, side: :first }
+    #   Parser.parse("c")  # => { abbr: :C, side: :second }
+    #
+    # @example Validation
+    #   Parser.valid?("C")   # => true
+    #   Parser.valid?("CC")  # => false
+    #
+    # @see https://sashite.dev/specs/sin/1.0.0/
+    module Parser
+      # Parses a SIN string into its components.
+      #
+      # @param input [String] The SIN string to parse
+      # @return [Hash] Hash with :abbr and :side keys
+      # @raise [Errors::Argument] If the input is invalid
+      #
+      # @example
+      #   Parser.parse("C")  # => { abbr: :C, side: :first }
+      #   Parser.parse("s")  # => { abbr: :S, side: :second }
+      def self.parse(input)
+        validate_input_type!(input)
+        validate_not_empty!(input)
+        validate_length!(input)
+
+        byte = input.getbyte(0)
+        validate_letter!(byte)
+
+        extract_components(byte)
+      end
+
+      # Reports whether the input is a valid SIN string.
+      #
+      # @param input [String] The string to validate
+      # @return [Boolean] true if valid, false otherwise
+      #
+      # @example
+      #   Parser.valid?("C")   # => true
+      #   Parser.valid?("c")   # => true
+      #   Parser.valid?("")    # => false
+      #   Parser.valid?("CC")  # => false
+      def self.valid?(input)
+        parse(input)
+        true
+      rescue Errors::Argument
+        false
+      end
+
+      # @!group Private Class Methods
+
+      # Validates that input is a String.
+      #
+      # @param input [Object] The input to validate
+      # @raise [Errors::Argument] If input is not a String
+      # @return [void]
+      private_class_method def self.validate_input_type!(input)
+        return if ::String === input
+
+        raise Errors::Argument, Errors::Argument::Messages::MUST_BE_LETTER
+      end
+
+      # Validates that input is not empty.
+      #
+      # @param input [String] The input to validate
+      # @raise [Errors::Argument] If input is empty
+      # @return [void]
+      private_class_method def self.validate_not_empty!(input)
+        return unless input.empty?
+
+        raise Errors::Argument, Errors::Argument::Messages::EMPTY_INPUT
+      end
+
+      # Validates that input does not exceed maximum length.
+      #
+      # @param input [String] The input to validate
+      # @raise [Errors::Argument] If input exceeds maximum length
+      # @return [void]
+      private_class_method def self.validate_length!(input)
+        return if input.bytesize <= Constants::MAX_STRING_LENGTH
+
+        raise Errors::Argument, Errors::Argument::Messages::INPUT_TOO_LONG
+      end
+
+      # Validates that byte is an ASCII letter.
+      #
+      # @param byte [Integer] The byte to validate
+      # @raise [Errors::Argument] If byte is not a letter
+      # @return [void]
+      private_class_method def self.validate_letter!(byte)
+        return if uppercase_letter?(byte) || lowercase_letter?(byte)
+
+        raise Errors::Argument, Errors::Argument::Messages::MUST_BE_LETTER
+      end
+
+      # Extracts abbr and side from a validated byte.
+      #
+      # @param byte [Integer] A validated ASCII letter byte
+      # @return [Hash] Hash with :abbr and :side keys
+      private_class_method def self.extract_components(byte)
+        if uppercase_letter?(byte)
+          { abbr: byte.chr.to_sym, side: :first }
+        else
+          { abbr: byte.chr.upcase.to_sym, side: :second }
+        end
+      end
+
+      # Reports whether byte is an uppercase ASCII letter (A-Z).
+      #
+      # @param byte [Integer] The byte to check
+      # @return [Boolean] true if A-Z
+      private_class_method def self.uppercase_letter?(byte)
+        byte >= 0x41 && byte <= 0x5A
+      end
+
+      # Reports whether byte is a lowercase ASCII letter (a-z).
+      #
+      # @param byte [Integer] The byte to check
+      # @return [Boolean] true if a-z
+      private_class_method def self.lowercase_letter?(byte)
+        byte >= 0x61 && byte <= 0x7A
+      end
+
+      # @!endgroup
+    end
+  end
+end

data/lib/sashite/sin.rb

@@ -1,188 +1,70 @@
 # frozen_string_literal: true
 
+require_relative "sin/constants"
+require_relative "sin/errors"
 require_relative "sin/identifier"
+require_relative "sin/parser"
 
 module Sashite
-  # SIN (Style Identifier Notation) implementation for Ruby
+  # SIN (Style Identifier Notation) implementation for Ruby.
   #
-  # Provides a compact, ASCII-based format for identifying styles in abstract strategy board games.
-  # SIN uses single-character identifiers with case encoding to represent both style identity
-  # and player assignment simultaneously.
+  # SIN provides a compact, ASCII-based format for encoding Player Style
+  # with Player Side assignment in abstract strategy board games.
   #
-  # ## Concept
+  # A SIN token is exactly one ASCII letter:
+  # - Uppercase (A-Z) indicates first player
+  # - Lowercase (a-z) indicates second player
   #
-  # SIN addresses the fundamental need to identify which style system governs piece behavior
-  # while simultaneously indicating which player controls pieces of that style. In cross-style
-  # scenarios where different players use different game traditions, this dual encoding becomes
-  # essential for unambiguous piece identification.
+  # @example Parsing SIN strings
+  #   sin = Sashite::Sin.parse("C")
+  #   sin.abbr  # => :C
+  #   sin.side  # => :first
+  #   sin.to_s  # => "C"
   #
-  # ## Dual-Purpose Encoding
+  # @example Creating identifiers directly
+  #   sin = Sashite::Sin::Identifier.new(:C, :first)
+  #   sin.to_s  # => "C"
   #
-  # Each SIN identifier serves two functions:
-  # - **Style Family Identification**: The letter choice indicates which rule system applies
-  # - **Player Assignment**: The letter case indicates which player uses this style as their native system
+  # @example Validation
+  #   Sashite::Sin.valid?("C")   # => true
+  #   Sashite::Sin.valid?("CC")  # => false
   #
-  # ## Format Specification
-  #
-  # Structure: `<style-letter>`
-  #
-  # Grammar (BNF):
-  #   <sin> ::= <uppercase-letter> | <lowercase-letter>
-  #   <uppercase-letter> ::= "A" | "B" | "C" | ... | "Z"
-  #   <lowercase-letter> ::= "a" | "b" | "c" | ... | "z"
-  #
-  # Regular Expression: `/\A[A-Za-z]\z/`
-  #
-  # ## Style Attribute Mapping
-  #
-  # SIN encodes style attributes using the following correspondence:
-  #
-  # | Style Attribute | SIN Encoding | Examples |
-  # |-----------------|--------------|----------|
-  # | **Letter** | Single ASCII character | `C`, `c`, `S`, `s` |
-  # | **Style Family** | ASCII letter choice (A-Z) | `C`/`c` = Chess, `S`/`s` = Shōgi |
-  # | **Player Assignment** | Letter case | `C` = First player, `c` = Second player |
-  #
-  # The **Letter** attribute combines two distinct semantic components:
-  # - **Style Family**: The underlying ASCII character (A-Z), representing the game tradition or rule system
-  # - **Player Assignment**: The case of the character (uppercase/lowercase), representing which player uses this style
-  #
-  # ## Character Selection Conventions
-  #
-  # ### Primary Convention: First Letter
-  # By convention, SIN identifiers should preferably use the **first letter** of the corresponding SNN style name:
-  # - `Chess` → `C`/`c`
-  # - `Shogi` → `S`/`s`
-  # - `Xiangqi` → `X`/`x`
-  # - `Makruk` → `M`/`m`
-  # - `Janggi` → `J`/`j`
-  #
-  # ### Collision Resolution
-  # When multiple styles would claim the same first letter, systematic collision resolution applies
-  # using sequential letter selection from the SNN name until a unique identifier is found.
-  #
-  # ### Compatibility Groups
-  # Styles requiring incompatible board structures can safely share SIN letters since they
-  # cannot coexist in the same match.
-  #
-  # ## System Constraints
-  #
-  # - **26 possible identifiers** per player using ASCII letters
-  # - **Exactly 2 players** through case distinction:
-  #   - First player: Uppercase letters (`A-Z`)
-  #   - Second player: Lowercase letters (`a-z`)
-  # - **Single character** per style-player combination
-  # - **Rule-agnostic** - independent of specific game mechanics
-  #
-  # ## Examples
-  #
-  # ### Traditional Game Styles
-  #
-  #   # Chess (8×8)
-  #   chess_white = Sashite::Sin.parse("C")    # First player (White pieces)
-  #   chess_black = Sashite::Sin.parse("c")    # Second player (Black pieces)
-  #
-  #   # Shōgi (9×9)
-  #   shogi_sente = Sashite::Sin.parse("S")    # First player (Sente 先手)
-  #   shogi_gote  = Sashite::Sin.parse("s")    # Second player (Gote 後手)
-  #
-  #   # Xiangqi (9×10)
-  #   xiangqi_red   = Sashite::Sin.parse("X")  # First player (Red pieces)
-  #   xiangqi_black = Sashite::Sin.parse("x")  # Second player (Black pieces)
-  #
-  # ### Cross-Style Scenarios
-  #
-  #   # Chess vs. Ōgi Match (both 8×8 compatible)
-  #   chess_style = Sashite::Sin.parse("C")    # Chess style, first player
-  #   ogi_style   = Sashite::Sin.parse("o")    # Ōgi style, second player
-  #
-  # ### All 26 Letters
-  #
-  #   # First player identifiers (A-Z)
-  #   ("A".."Z").each { |letter| Sashite::Sin.parse(letter).first_player? }  # => all true
-  #
-  #   # Second player identifiers (a-z)
-  #   ("a".."z").each { |letter| Sashite::Sin.parse(letter).second_player? } # => all true
-  #
-  # ## Design Properties
-  #
-  # - **ASCII compatibility**: Maximum portability across systems
-  # - **Rule-agnostic**: Independent of specific game mechanics
-  # - **Minimal overhead**: Single character per style-player combination
-  # - **Flexible collision resolution**: Systematic approaches for identifier conflicts
-  # - **Semantic clarity**: Distinct concepts for Letter (Style Family + Player Assignment)
-  # - **SNN coordination**: Works harmoniously with formal style naming
-  # - **Context-aware**: Adapts to avoid conflicts within specific game scenarios
-  #
-  # @see https://sashite.dev/specs/sin/1.0.0/ SIN Specification v1.0.0
-  # @see https://sashite.dev/specs/sin/1.0.0/examples/ SIN Examples
-  # @see https://sashite.dev/specs/snn/ Style Name Notation (SNN)
+  # @see https://sashite.dev/specs/sin/1.0.0/
   module Sin
-    # Check if a string is a valid SIN notation
+    # Parses a SIN string into an Identifier.
     #
-    # @param sin_string [String] the string to validate
-    # @return [Boolean] true if valid SIN, false otherwise
+    # @param input [String] The SIN string to parse
+    # @return [Identifier] The parsed identifier
+    # @raise [Errors::Argument] If the input is invalid
     #
-    # @example Validate various SIN formats
-    #   Sashite::Sin.valid?("C")      # => true (Chess first player)
-    #   Sashite::Sin.valid?("c")      # => true (Chess second player)
-    #   Sashite::Sin.valid?("S")      # => true (Shōgi first player)
-    #   Sashite::Sin.valid?("s")      # => true (Shōgi second player)
-    #   Sashite::Sin.valid?("CHESS")  # => false (multi-character)
-    #   Sashite::Sin.valid?("1")      # => false (not a letter)
-    #   Sashite::Sin.valid?("")       # => false (empty string)
-    def self.valid?(sin_string)
-      Identifier.valid?(sin_string)
-    end
-
-    # Parse an SIN string into an Identifier object
-    #
-    # The identifier will have both letter and side attributes inferred from the case:
-    # - Uppercase letter → first player (:first)
-    # - Lowercase letter → second player (:second)
-    #
-    # @param sin_string [String] SIN notation string (single ASCII letter)
-    # @return [Sin::Identifier] parsed identifier object with letter and side attributes
-    # @raise [ArgumentError] if the SIN string is invalid
-    #
-    # @example Parse different SIN formats with dual-purpose encoding
-    #   Sashite::Sin.parse("C")  # => #<Sashite::Sin::Identifier @family=:C, @side=:first>
-    #   Sashite::Sin.parse("c")  # => #<Sashite::Sin::Identifier @family=:C, @side=:second>
-    #   Sashite::Sin.parse("S")  # => #<Sashite::Sin::Identifier @family=:S, @side=:first>
-    #   Sashite::Sin.parse("s")  # => #<Sashite::Sin::Identifier @family=:S, @side=:second>
+    # @example Parsing uppercase (first player)
+    #   sin = Sashite::Sin.parse("C")
+    #   sin.abbr  # => :C
+    #   sin.side  # => :first
     #
-    # @example Traditional game styles
-    #   chess_white = Sashite::Sin.parse("C")  # Chess, first player (White)
-    #   chess_black = Sashite::Sin.parse("c")  # Chess, second player (Black)
-    #   shogi_sente = Sashite::Sin.parse("S")  # Shōgi, first player (Sente)
-    #   shogi_gote  = Sashite::Sin.parse("s")  # Shōgi, second player (Gote)
-    def self.parse(sin_string)
-      Identifier.parse(sin_string)
+    # @example Parsing lowercase (second player)
+    #   sin = Sashite::Sin.parse("c")
+    #   sin.abbr  # => :C
+    #   sin.side  # => :second
+    def self.parse(input)
+      components = Parser.parse(input)
+
+      Identifier.new(components.fetch(:abbr), components.fetch(:side))
     end
 
-    # Create a new identifier instance with canonical representation
-    #
-    # Ensures the letter case matches the specified side:
-    # - :first side → uppercase letter
-    # - :second side → lowercase letter
-    #
-    # @param family [Symbol] style family (:A to :Z representing Style Family)
-    # @param side [Symbol] player side (:first or :second)
-    # @return [Sin::Identifier] new immutable identifier instance
-    # @raise [ArgumentError] if parameters are invalid
-    #
-    # @example Create identifiers with family and side separation
-    #   Sashite::Sin.identifier(:C, :first)   # => #<Sashite::Sin::Identifier @family=:C, @side=:first>
-    #   Sashite::Sin.identifier(:C, :second)  # => #<Sashite::Sin::Identifier @family=:C, @side=:second>
+    # Reports whether the input is a valid SIN string.
     #
-    # @example Style family and player assignment
-    #   chess_first  = Sashite::Sin.identifier(:C, :first)   # Chess family, first player
-    #   chess_second = Sashite::Sin.identifier(:C, :second)  # Chess family, second player
+    # @param input [String] The string to validate
+    # @return [Boolean] true if valid, false otherwise
     #
-    #   chess_first.same_family?(chess_second)   # => true (same style family)
-    #   chess_first.same_side?(chess_second)     # => false (different players)
-    def self.identifier(family, side)
-      Identifier.new(family, side)
+    # @example
+    #   Sashite::Sin.valid?("C")   # => true
+    #   Sashite::Sin.valid?("c")   # => true
+    #   Sashite::Sin.valid?("")    # => false
+    #   Sashite::Sin.valid?("CC")  # => false
+    #   Sashite::Sin.valid?("1")   # => false
+    def self.valid?(input)
+      Parser.valid?(input)
     end
   end
 end

data/lib/sashite-sin.rb

@@ -1,14 +1,3 @@
 # frozen_string_literal: true
 
 require_relative "sashite/sin"
-
-# Sashité namespace for board game notation libraries
-#
-# 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/specs/ Sashité Specifications
-# @author Sashité
-module Sashite
-end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-sin
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -9,33 +9,35 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: |
-  SIN (Style Identifier Notation) provides a rule-agnostic format for identifying styles
-  in abstract strategy board games. This gem implements the SIN Specification v1.0.0 with
-  a modern Ruby interface featuring immutable identifier objects and functional programming
-  principles. SIN uses single ASCII letters with case-based side encoding (A-Z for first player,
-  a-z for second player), enabling clear distinction between different style families in
-  multi-style gaming environments. Perfect for cross-style matches, game engines, and hybrid
-  gaming systems requiring compact style identification with enhanced collision resolution.
+description: SIN (Style Identifier Notation) implementation for Ruby. Provides a rule-agnostic
+  format for identifying player styles in abstract strategy board games with immutable
+  identifier objects and functional programming principles.
 email: contact@cyril.email
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- LICENSE.md
+- LICENSE
 - README.md
 - lib/sashite-sin.rb
 - lib/sashite/sin.rb
+- lib/sashite/sin/constants.rb
+- lib/sashite/sin/errors.rb
+- lib/sashite/sin/errors/argument.rb
+- lib/sashite/sin/errors/argument/messages.rb
 - lib/sashite/sin/identifier.rb
+- lib/sashite/sin/parser.rb
 homepage: https://github.com/sashite/sin.rb
 licenses:
-- MIT
+- Apache-2.0
 metadata:
   bug_tracker_uri: https://github.com/sashite/sin.rb/issues
   documentation_uri: https://rubydoc.info/github/sashite/sin.rb/main
   homepage_uri: https://github.com/sashite/sin.rb
   source_code_uri: https://github.com/sashite/sin.rb
   specification_uri: https://sashite.dev/specs/sin/1.0.0/
+  wiki_uri: https://sashite.dev/specs/sin/1.0.0/examples/
+  funding_uri: https://github.com/sponsors/sashite
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -51,7 +53,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: SIN (Style Identifier Notation) implementation for Ruby with immutable identifier
   objects

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.