sashite-pin 3.2.0 → 4.0.0

data/lib/sashite/pin/parser.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+require_relative "errors"
+
+module Sashite
+  module Pin
+    # Secure parser for PIN (Piece Identifier Notation) strings.
+    #
+    # This parser uses character-by-character validation without regex
+    # to prevent ReDoS attacks and ensure strict ASCII compliance.
+    #
+    # @example
+    #   Parser.parse("K")   # => { type: :K, side: :first, state: :normal, terminal: false }
+    #   Parser.parse("+r^") # => { type: :R, side: :second, state: :enhanced, terminal: true }
+    #
+    # @see https://sashite.dev/specs/pin/1.0.0/
+    module Parser
+      # Parses a PIN string into its components.
+      #
+      # @param input [String] The PIN string to parse
+      # @return [Hash] A hash with :type, :side, :state, and :terminal keys
+      # @raise [Errors::Argument] If the input is not a valid PIN string
+      def self.parse(input)
+        validate_input_type(input)
+        validate_not_empty(input)
+        validate_length(input)
+
+        parse_components(input)
+      end
+
+      # Validates a PIN string without raising an exception.
+      #
+      # @param input [String] The PIN string to validate
+      # @return [Boolean] true if valid, false otherwise
+      def self.valid?(input)
+        return false unless ::String === input
+
+        parse(input)
+        true
+      rescue Errors::Argument
+        false
+      end
+
+      class << self
+        private
+
+        # Validates that input is a String.
+        #
+        # @param input [Object] The input to validate
+        # @raise [Errors::Argument] If input is not a String
+        def validate_input_type(input)
+          return if ::String === input
+
+          raise Errors::Argument, Errors::Argument::Messages::MUST_CONTAIN_ONE_LETTER
+        end
+
+        # Validates that input is not empty.
+        #
+        # @param input [String] The input to validate
+        # @raise [Errors::Argument] If input is empty
+        def 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 is too long
+        def validate_length(input)
+          return if input.bytesize <= Constants::MAX_STRING_LENGTH
+
+          raise Errors::Argument, Errors::Argument::Messages::INPUT_TOO_LONG
+        end
+
+        # Parses the PIN string into its components.
+        #
+        # @param input [String] The validated PIN string
+        # @return [Hash] A hash with :type, :side, :state, and :terminal keys
+        # @raise [Errors::Argument] If the structure is invalid
+        def parse_components(input)
+          pos = 0
+          state = :normal
+          terminal = false
+
+          # Check for state modifier at position 0
+          byte = input.getbyte(pos)
+          if state_modifier?(byte)
+            state = decode_state_modifier(byte)
+            pos += 1
+          end
+
+          # Must have a letter at current position
+          raise Errors::Argument, Errors::Argument::Messages::MUST_CONTAIN_ONE_LETTER if pos >= input.bytesize
+
+          byte = input.getbyte(pos)
+          raise Errors::Argument, Errors::Argument::Messages::MUST_CONTAIN_ONE_LETTER unless ascii_letter?(byte)
+
+          type = byte.chr.upcase.to_sym
+          side = uppercase_letter?(byte) ? :first : :second
+          pos += 1
+
+          # Check for terminal marker
+          if pos < input.bytesize
+            byte = input.getbyte(pos)
+            raise Errors::Argument, Errors::Argument::Messages::INVALID_TERMINAL_MARKER unless terminal_marker?(byte)
+
+            terminal = true
+            pos += 1
+          end
+
+          # Ensure no extra characters
+          raise Errors::Argument, Errors::Argument::Messages::MUST_CONTAIN_ONE_LETTER if pos < input.bytesize
+
+          { type: type, side: side, state: state, terminal: terminal }
+        end
+
+        # Checks if a byte is a state modifier (+ or -).
+        #
+        # @param byte [Integer] The byte to check
+        # @return [Boolean] true if state modifier
+        def state_modifier?(byte)
+          byte == 0x2B || byte == 0x2D # '+' or '-'
+        end
+
+        # Decodes a state modifier byte to a state symbol.
+        #
+        # @param byte [Integer] The byte to decode
+        # @return [Symbol] :enhanced or :diminished
+        def decode_state_modifier(byte)
+          byte == 0x2B ? :enhanced : :diminished
+        end
+
+        # Checks if a byte is an ASCII letter (A-Z or a-z).
+        #
+        # @param byte [Integer] The byte to check
+        # @return [Boolean] true if ASCII letter
+        def ascii_letter?(byte)
+          uppercase_letter?(byte) || lowercase_letter?(byte)
+        end
+
+        # Checks if a byte is an uppercase ASCII letter (A-Z).
+        #
+        # @param byte [Integer] The byte to check
+        # @return [Boolean] true if uppercase letter
+        def uppercase_letter?(byte)
+          byte >= 0x41 && byte <= 0x5A # 'A' to 'Z'
+        end
+
+        # Checks if a byte is a lowercase ASCII letter (a-z).
+        #
+        # @param byte [Integer] The byte to check
+        # @return [Boolean] true if lowercase letter
+        def lowercase_letter?(byte)
+          byte >= 0x61 && byte <= 0x7A # 'a' to 'z'
+        end
+
+        # Checks if a byte is a terminal marker (^).
+        #
+        # @param byte [Integer] The byte to check
+        # @return [Boolean] true if terminal marker
+        def terminal_marker?(byte)
+          byte == 0x5E # '^'
+        end
+      end
+    end
+  end
+end

data/lib/sashite/pin.rb

@@ -1,68 +1,94 @@
 # frozen_string_literal: true
 
+require_relative "pin/constants"
+require_relative "pin/errors"
 require_relative "pin/identifier"
+require_relative "pin/parser"
 
 module Sashite
-  # PIN (Piece Identifier Notation) implementation for Ruby
+  # PIN (Piece Identifier Notation) implementation for Ruby.
   #
-  # Provides ASCII-based format for representing pieces in abstract strategy board games.
-  # PIN translates piece attributes from the Game Protocol into a compact, portable notation system.
+  # PIN provides an ASCII-based format for representing pieces in abstract strategy
+  # board games. It translates piece attributes from the Game Protocol into a compact,
+  # portable notation system.
   #
-  # Format: [<state>]<letter>
-  # - State modifier: "+" (enhanced), "-" (diminished), or none (normal)
-  # - Letter: A-Z (first player), a-z (second player)
+  # == Format
   #
-  # Examples:
-  #   "K"  - First player king (normal state)
-  #   "k"  - Second player king (normal state)
-  #   "+R" - First player rook (enhanced state)
-  #   "-p" - Second player pawn (diminished state)
+  #   [<state-modifier>]<letter>[<terminal-marker>]
+  #
+  # - *Letter* (+A-Z+, +a-z+): Piece type and side
+  # - *State modifier*: <tt>+</tt> (enhanced), <tt>-</tt> (diminished), or none (normal)
+  # - *Terminal marker*: <tt>^</tt> (terminal piece) or none
+  #
+  # == Attributes
+  #
+  # A PIN token encodes exactly these attributes:
+  #
+  # - *Piece Name* → one ASCII letter chosen by the Game / Rule System
+  # - *Piece Side* → the case of that letter (uppercase = first, lowercase = second)
+  # - *Piece State* → an optional prefix (<tt>+</tt> for enhanced, <tt>-</tt> for diminished)
+  # - *Terminal status* → an optional suffix (<tt>^</tt>)
+  #
+  # == Examples
+  #
+  #   pin = Sashite::Pin.parse("K")
+  #   pin.type       # => :K
+  #   pin.side       # => :first
+  #   pin.state      # => :normal
+  #   pin.terminal?  # => false
+  #
+  #   pin = Sashite::Pin.parse("+R")
+  #   pin.to_s  # => "+R"
+  #
+  #   pin = Sashite::Pin.parse("k^")
+  #   pin.terminal?  # => true
+  #
+  #   Sashite::Pin.valid?("K^")      # => true
+  #   Sashite::Pin.valid?("invalid") # => false
   #
   # @see https://sashite.dev/specs/pin/1.0.0/
   module Pin
-    # Check if a string is a valid PIN notation
+    # Parses a PIN string into an Identifier.
     #
-    # @param pin_string [String] The string to validate
-    # @return [Boolean] true if valid PIN, false otherwise
+    # @param string [String] The PIN string to parse
+    # @return [Identifier] A new Identifier instance
+    # @raise [Errors::Argument] If the string is not a valid PIN
     #
     # @example
-    #   Sashite::Pin.valid?("K")    # => true
-    #   Sashite::Pin.valid?("+R")   # => true
-    #   Sashite::Pin.valid?("-p")   # => true
-    #   Sashite::Pin.valid?("KK")   # => false
-    #   Sashite::Pin.valid?("++K")  # => false
-    def self.valid?(pin_string)
-      Identifier.valid?(pin_string)
-    end
-
-    # Parse a PIN string into an Identifier object
+    #   Sashite::Pin.parse("K")
+    #   # => #<Sashite::Pin::Identifier K>
     #
-    # @param pin_string [String] PIN notation string
-    # @return [Pin::Identifier] new identifier instance
-    # @raise [ArgumentError] if the PIN string is invalid
-    # @example
-    #   Sashite::Pin.parse("K")     # => #<Pin::Identifier type=:K side=:first state=:normal>
-    #   Sashite::Pin.parse("+R")    # => #<Pin::Identifier type=:R side=:first state=:enhanced>
-    #   Sashite::Pin.parse("-p")    # => #<Pin::Identifier type=:P side=:second state=:diminished>
-    def self.parse(pin_string)
-      Identifier.parse(pin_string)
+    #   Sashite::Pin.parse("+r")
+    #   # => #<Sashite::Pin::Identifier +r>
+    #
+    #   Sashite::Pin.parse("K^")
+    #   # => #<Sashite::Pin::Identifier K^>
+    #
+    #   Sashite::Pin.parse("invalid")
+    #   # => raises Errors::Argument
+    def self.parse(string)
+      components = Parser.parse(string)
+
+      Identifier.new(
+        components[:type],
+        components[:side],
+        components[:state],
+        terminal: components[:terminal]
+      )
     end
 
-    # Create a new identifier instance
+    # Checks if a string is a valid PIN notation.
+    #
+    # @param string [String] The string to validate
+    # @return [Boolean] true if valid, false otherwise
     #
-    # @param type [Symbol] piece type (:A to :Z)
-    # @param side [Symbol] player side (:first or :second)
-    # @param state [Symbol] piece state (:normal, :enhanced, or :diminished)
-    # @param terminal [Boolean] whether the piece is a terminal piece
-    # @return [Pin::Identifier] new identifier instance
-    # @raise [ArgumentError] if parameters are invalid
     # @example
-    #   Sashite::Pin.identifier(:K, :first, :normal)     # => #<Pin::Identifier type=:K side=:first state=:normal terminal=false>
-    #   Sashite::Pin.identifier(:R, :first, :enhanced)   # => #<Pin::Identifier type=:R side=:first state=:enhanced terminal=false>
-    #   Sashite::Pin.identifier(:P, :second, :diminished) # => #<Pin::Identifier type=:P side=:second state=:diminished terminal=false>
-    #   Sashite::Pin.identifier(:K, :first, :normal, terminal: true) # => #<Pin::Identifier type=:K side=:first state=:normal terminal=true>
-    def self.identifier(type, side, state, terminal: false)
-      Identifier.new(type, side, state, terminal: terminal)
+    #   Sashite::Pin.valid?("K")        # => true
+    #   Sashite::Pin.valid?("+R")       # => true
+    #   Sashite::Pin.valid?("K^")       # => true
+    #   Sashite::Pin.valid?("invalid")  # => false
+    def self.valid?(string)
+      Parser.valid?(string)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-pin
 version: !ruby/object:Gem::Version
-  version: 3.2.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -9,34 +9,35 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: |
-  PIN (Piece Identifier Notation) provides a rule-agnostic format for identifying pieces
-  in abstract strategy board games. This gem implements the PIN Specification v1.0.0 with
-  a modern Ruby interface featuring immutable identifier objects and functional programming
-  principles. PIN uses single ASCII letters with optional state modifiers, terminal markers,
-  and case-based side encoding (A-Z for first player, a-z for second player), enabling
-  precise and portable identification of pieces across multiple games. Perfect for game
-  engines, board game notation systems, and hybrid gaming platforms requiring compact,
-  stateful piece representation.
+description: PIN (Piece Identifier Notation) implementation for Ruby. Provides a rule-agnostic
+  format for identifying pieces 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-pin.rb
 - lib/sashite/pin.rb
+- lib/sashite/pin/constants.rb
+- lib/sashite/pin/errors.rb
+- lib/sashite/pin/errors/argument.rb
+- lib/sashite/pin/errors/argument/messages.rb
 - lib/sashite/pin/identifier.rb
+- lib/sashite/pin/parser.rb
 homepage: https://github.com/sashite/pin.rb
 licenses:
-- MIT
+- Apache-2.0
 metadata:
   bug_tracker_uri: https://github.com/sashite/pin.rb/issues
   documentation_uri: https://rubydoc.info/github/sashite/pin.rb/main
   homepage_uri: https://github.com/sashite/pin.rb
   source_code_uri: https://github.com/sashite/pin.rb
   specification_uri: https://sashite.dev/specs/pin/1.0.0/
+  wiki_uri: https://sashite.dev/specs/pin/1.0.0/examples/
+  funding_uri: https://github.com/sponsors/sashite
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -52,7 +53,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.3
 specification_version: 4
 summary: PIN (Piece 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.