sashite-pin 4.0.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d3f359a3d215523ac369b662e9a6d1a290acd6076db4f34829d0eb579ac8e2a
-  data.tar.gz: a25dc1c9f2f47ed6121f82a839ee28d070c5a5c8bb11bd10abeb2e589d4dae30
+  metadata.gz: 654a422f7d1d03a9b2e474e6f29644c7d8636cc6a7da60100fc49efa87ccda02
+  data.tar.gz: c9548c761f14c4dc76acc1376fda12fa64339bbe7d6b2567b49f205113c89b59
 SHA512:
-  metadata.gz: 79a1949901c57b7057498f1157a68cf71169a034f2645d6f69c9cb2d4a1272a422d54b794930013af7b0042277951dc32bffaa80a49abc88e7fe8ed5161a8644
-  data.tar.gz: e475211bb7e79ac75df02bfcf58023354e602479e40b76ae453942ae5f3fe38a1af310f477db8ccbf57c070bd1e0d0dab2422c2eab9013e896b5f90f79d4b007
+  metadata.gz: fc265f0049d911133c3de8910ed15911a207fcec239aa97d8c4a9766242f2f5ca53d80802e36c9aafeac525eb79a01ef4f3625738f04622db97b210d8094296c
+  data.tar.gz: 5a5254e21d89dfec797ce72c62d1a65689c9db5460a91c13edba6360655483b7dd1c0a024c04ee35e5e35971c30e08518b540086112334da0a662d2ea1f3b432

data/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2025 Cyril Kato
+   Copyright 2025-2026 Cyril Kato
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

data/README.md

@@ -11,6 +11,18 @@
 
 This library implements the [PIN Specification v1.0.0](https://sashite.dev/specs/pin/1.0.0/).
 
+PIN is a compact, ASCII-only token format encoding a **Piece Identity**: the tuple (**Piece Name**, **Piece Side**, **Piece State**, **Terminal Status**). Case encodes side, an optional `+`/`-` prefix encodes state, and an optional `^` suffix marks terminal pieces.
+
+### Implementation Constraints
+
+| Constraint | Value | Rationale |
+|------------|-------|-----------|
+| Token length | 1–3 characters | `[+-]?[A-Za-z]\^?` per spec |
+| Character space | 312 tokens | 26 abbreviations × 2 sides × 3 states × 2 terminal |
+| Instance pool | 312 objects | All identifiers are pre-instantiated and frozen |
+
+The closed domain of 312 possible values enables a flyweight architecture with zero allocation on the hot path.
+
 ## Installation
 
 ```ruby
@@ -35,7 +47,7 @@ require "sashite/pin"
 
 # Standard parsing (raises on error)
 pin = Sashite::Pin.parse("K")
-pin.type       # => :K
+pin.abbr       # => :K
 pin.side       # => :first
 pin.state      # => :normal
 pin.terminal?  # => false
@@ -53,57 +65,73 @@ pin = Sashite::Pin.parse("+K^")
 pin.state      # => :enhanced
 pin.terminal?  # => true
 
+# Returns a cached instance — no allocation
+Sashite::Pin.parse("+K^").equal?(Sashite::Pin.parse("+K^"))  # => true
+
 # Invalid input raises ArgumentError
 Sashite::Pin.parse("invalid")  # => raises ArgumentError
 ```
 
+### Safe Parsing (String → Identifier | nil)
+
+Parse without raising exceptions. Returns `nil` on invalid input.
+
+```ruby
+# Valid input returns an Identifier
+Sashite::Pin.safe_parse("K")     # => #<Sashite::Pin::Identifier K>
+Sashite::Pin.safe_parse("+R^")   # => #<Sashite::Pin::Identifier +R^>
+
+# Invalid input returns nil — no exception allocated
+Sashite::Pin.safe_parse("")        # => nil
+Sashite::Pin.safe_parse("invalid") # => nil
+Sashite::Pin.safe_parse(nil)       # => nil
+```
+
+### Fetching by Components (Symbol, Symbol, ... → Identifier)
+
+Retrieve a cached identifier directly by components, bypassing string parsing entirely.
+
+```ruby
+# Direct lookup — no string parsing, no allocation
+Sashite::Pin.fetch(:K, :first)                              # => #<Sashite::Pin::Identifier K>
+Sashite::Pin.fetch(:R, :second, :enhanced)                   # => #<Sashite::Pin::Identifier +r>
+Sashite::Pin.fetch(:K, :first, :normal, terminal: true)      # => #<Sashite::Pin::Identifier K^>
+
+# Same cached instance as parse
+Sashite::Pin.fetch(:K, :first).equal?(Sashite::Pin.parse("K"))  # => true
+
+# Invalid components raise ArgumentError
+Sashite::Pin.fetch(:KK, :first)     # => raises ArgumentError
+Sashite::Pin.fetch(:K, :third)      # => raises ArgumentError
+```
+
 ### Formatting (Identifier → String)
 
 Convert an `Identifier` back to a PIN string.
 
 ```ruby
-# From Identifier object
-pin = Sashite::Pin::Identifier.new(:K, :first)
-pin.to_s  # => "K"
-
-# With attributes
-pin = Sashite::Pin::Identifier.new(:R, :second, :enhanced)
-pin.to_s  # => "+r"
+pin = Sashite::Pin.parse("+K^")
+pin.to_s  # => "+K^"
 
-pin = Sashite::Pin::Identifier.new(:K, :first, :normal, terminal: true)
-pin.to_s  # => "K^"
+pin = Sashite::Pin.parse("r")
+pin.to_s  # => "r"
 ```
 
 ### Validation
 
 ```ruby
-# Boolean check
+# Boolean check (never raises)
+# Uses an exception-free code path internally for performance.
 Sashite::Pin.valid?("K")        # => true
 Sashite::Pin.valid?("+R")       # => true
 Sashite::Pin.valid?("K^")       # => true
 Sashite::Pin.valid?("invalid")  # => false
-```
-
-### Accessing Identifier Data
-
-```ruby
-pin = Sashite::Pin.parse("+K^")
-
-# Get attributes
-pin.type       # => :K
-pin.side       # => :first
-pin.state      # => :enhanced
-pin.terminal?  # => true
-
-# Get string components
-pin.letter  # => "K"
-pin.prefix  # => "+"
-pin.suffix  # => "^"
+Sashite::Pin.valid?(nil)        # => false
 ```
 
 ### Transformations
 
-All transformations return new immutable instances.
+All transformations return cached instances from the flyweight pool — no new object is ever allocated.
 
 ```ruby
 pin = Sashite::Pin.parse("K")
@@ -117,14 +145,17 @@ pin.normalize.to_s  # => "K"
 pin.flip.to_s  # => "k"
 
 # Terminal transformations
-pin.mark_terminal.to_s    # => "K^"
-pin.unmark_terminal.to_s  # => "K"
+pin.terminal.to_s      # => "K^"
+pin.non_terminal.to_s  # => "K"
 
 # Attribute changes
-pin.with_type(:Q).to_s       # => "Q"
-pin.with_side(:second).to_s  # => "k"
+pin.with_abbr(:Q).to_s            # => "Q"
+pin.with_side(:second).to_s       # => "k"
 pin.with_state(:enhanced).to_s    # => "+K"
 pin.with_terminal(true).to_s      # => "K^"
+
+# Transformations return cached instances
+pin.enhance.equal?(Sashite::Pin.parse("+K"))  # => true
 ```
 
 ### Queries
@@ -146,7 +177,7 @@ pin.terminal?  # => true
 
 # Comparison queries
 other = Sashite::Pin.parse("k")
-pin.same_type?(other)      # => true
+pin.same_abbr?(other)      # => true
 pin.same_side?(other)      # => false
 pin.same_state?(other)     # => false
 pin.same_terminal?(other)  # => false
@@ -154,27 +185,60 @@ pin.same_terminal?(other)  # => false
 
 ## API Reference
 
-### Types
+### Module Methods
+
+```ruby
+# Parses a PIN string into a cached Identifier.
+# Returns a pre-instantiated, frozen instance.
+# Raises ArgumentError if the string is not valid.
+#
+# @param string [String] PIN string
+# @return [Identifier]
+# @raise [ArgumentError] if invalid
+def Sashite::Pin.parse(string)
+
+# Parses a PIN string without raising.
+# Returns a cached Identifier on success, nil on failure.
+# Never allocates exception objects or captures backtraces.
+#
+# @param string [String] PIN string
+# @return [Identifier, nil]
+def Sashite::Pin.safe_parse(string)
+
+# Retrieves a cached Identifier by components.
+# Bypasses string parsing entirely — direct hash lookup.
+# Raises ArgumentError if components are invalid.
+#
+# @param abbr [Symbol] Piece abbreviation (:A through :Z)
+# @param side [Symbol] Piece side (:first or :second)
+# @param state [Symbol] Piece state (:normal, :enhanced, or :diminished)
+# @param terminal [Boolean] Terminal status
+# @return [Identifier]
+# @raise [ArgumentError] if invalid
+def Sashite::Pin.fetch(abbr, side, state = :normal, terminal: false)
+
+# Reports whether string is a valid PIN.
+# Never raises; returns false for any invalid input.
+# Uses an exception-free code path internally for performance.
+#
+# @param string [String] PIN string
+# @return [Boolean]
+def Sashite::Pin.valid?(string)
+```
+
+### Identifier
 
 ```ruby
 # Identifier represents a parsed PIN with all attributes.
+# All instances are frozen and pre-instantiated — never construct directly,
+# use Sashite::Pin.parse, .safe_parse, or .fetch instead.
 class Sashite::Pin::Identifier
-  # Creates an Identifier from attributes.
-  # Raises ArgumentError if attributes are invalid.
+  # Returns the piece name abbreviation (always uppercase symbol).
   #
-  # @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] Terminal status
-  # @return [Identifier]
-  def initialize(type, side, state = :normal, terminal: false)
-
-  # Returns the piece type (always uppercase symbol).
-  #
-  # @return [Symbol]
-  def type
+  # @return [Symbol] :A through :Z
+  def abbr
 
-  # Returns the player side.
+  # Returns the piece side.
   #
   # @return [Symbol] :first or :second
   def side
@@ -196,41 +260,12 @@ class Sashite::Pin::Identifier
 end
 ```
 
-### Constants
-
-```ruby
-Sashite::Pin::Constants::VALID_TYPES       # => [:A, :B, ..., :Z]
-Sashite::Pin::Constants::VALID_SIDES       # => [:first, :second]
-Sashite::Pin::Constants::VALID_STATES      # => [:normal, :enhanced, :diminished]
-Sashite::Pin::Constants::MAX_STRING_LENGTH # => 3
-```
-
-### Parsing
-
-```ruby
-# Parses a PIN string into an Identifier.
-# Raises ArgumentError if the string is not valid.
-#
-# @param string [String] PIN string
-# @return [Identifier]
-# @raise [ArgumentError] if invalid
-def Sashite::Pin.parse(string)
-```
-
-### Validation
-
-```ruby
-# Reports whether string is a valid PIN.
-#
-# @param string [String] PIN string
-# @return [Boolean]
-def Sashite::Pin.valid?(string)
-```
-
 ### Transformations
 
+All transformations return cached `Sashite::Pin::Identifier` instances from the flyweight pool:
+
 ```ruby
-# State transformations (return new Identifier)
+# State transformations
 def enhance     # => Identifier with :enhanced state
 def diminish    # => Identifier with :diminished state
 def normalize   # => Identifier with :normal state
@@ -239,19 +274,50 @@ def normalize   # => Identifier with :normal state
 def flip        # => Identifier with opposite side
 
 # Terminal transformations
-def mark_terminal    # => Identifier with terminal: true
-def unmark_terminal  # => Identifier with terminal: false
+def terminal      # => Identifier with terminal: true
+def non_terminal  # => Identifier with terminal: false
 
 # Attribute changes
-def with_type(new_type)        # => Identifier with different type
-def with_side(new_side)        # => Identifier with different side
-def with_state(new_state)      # => Identifier with different state
+def with_abbr(new_abbr)         # => Identifier with different abbreviation
+def with_side(new_side)         # => Identifier with different side
+def with_state(new_state)       # => Identifier with different state
 def with_terminal(new_terminal) # => Identifier with specified terminal status
 ```
 
+### Queries
+
+```ruby
+# State queries
+def normal?      # => Boolean
+def enhanced?    # => Boolean
+def diminished?  # => Boolean
+
+# Side queries
+def first_player?   # => Boolean
+def second_player?  # => Boolean
+
+# Terminal query
+def terminal?  # => Boolean
+
+# Comparison queries
+def same_abbr?(other)      # => Boolean
+def same_side?(other)      # => Boolean
+def same_state?(other)     # => Boolean
+def same_terminal?(other)  # => Boolean
+```
+
+### Constants
+
+```ruby
+Sashite::Pin::Constants::VALID_ABBRS       # => [:A, :B, ..., :Z]
+Sashite::Pin::Constants::VALID_SIDES       # => [:first, :second]
+Sashite::Pin::Constants::VALID_STATES      # => [:normal, :enhanced, :diminished]
+Sashite::Pin::Constants::MAX_STRING_LENGTH # => 3
+```
+
 ### Errors
 
-All parsing and validation errors raise `ArgumentError` with descriptive messages:
+All errors raise `ArgumentError` with descriptive messages:
 
 | Message | Cause |
 |---------|-------|
@@ -263,13 +329,30 @@ All parsing and validation errors raise `ArgumentError` with descriptive message
 
 ## Design Principles
 
-- **Bounded values**: Explicit validation of types, sides, states
-- **Object-oriented**: `Identifier` class enables methods and encapsulation
+- **Spec conformance**: Strict adherence to PIN v1.0.0
+- **Flyweight identifiers**: All 312 possible instances are pre-built and frozen; parsing, fetching, and transformations return cached objects with zero allocation
+- **Performance-oriented internals**: Exception-free validation path; exceptions only at the public API boundary
 - **Ruby idioms**: `valid?` predicate, `to_s` conversion, `ArgumentError` for invalid input
-- **Immutable identifiers**: Frozen instances prevent mutation
-- **Transformation methods**: Return new instances for state changes
+- **Immutable identifiers**: All instances are frozen after creation
 - **No dependencies**: Pure Ruby standard library only
 
+### Performance Architecture
+
+PIN has a closed domain of exactly 312 valid tokens (26 letters × 2 cases × 3 states × 2 terminal). The implementation exploits this constraint through three complementary strategies.
+
+**Flyweight instance pool** — All 312 `Identifier` objects are pre-instantiated and frozen at load time. `parse`, `safe_parse`, `fetch`, and all transformation methods return these cached instances via hash lookup. No `Identifier` is ever allocated after the module loads. This makes PIN essentially free to call from EPIN, FEEN, or any other hot loop — every call is a hash lookup returning a pre-existing frozen object.
+
+**Dual-path parsing** — Parsing is split into two layers to avoid using exceptions for control flow:
+
+- **Validation layer** — `safe_parse` performs all validation and returns the cached `Identifier` on success, or `nil` on failure, without raising, without allocating exception objects, and without capturing backtraces.
+- **Public API layer** — `parse` calls `safe_parse` internally. On failure, it raises `ArgumentError` exactly once, at the boundary. `valid?` calls `safe_parse` and returns a boolean directly, never raising.
+
+**Zero-allocation transformations** — Every transformation method (`flip`, `enhance`, `diminish`, `terminal`, `with_abbr`, etc.) computes the target component values and performs a direct lookup into the instance pool. The result is always a cached object — transformations never allocate. Chaining like `pin.enhance.flip.terminal` performs three hash lookups and zero allocations.
+
+**Direct component lookup** — `fetch` bypasses string parsing entirely. Given components `(:K, :first, :enhanced, terminal: true)`, it performs a single hash lookup into the instance pool. This is the fastest path for callers that already have structured data (e.g., EPIN's internal construction from parsed components).
+
+This architecture ensures that PIN never becomes a bottleneck when called from higher-level parsers like EPIN or FEEN, where it may be invoked hundreds of times per position.
+
 ## Related Specifications
 
 - [Game Protocol](https://sashite.dev/game-protocol/) — Conceptual foundation

data/lib/sashite/pin/constants.rb

@@ -2,12 +2,17 @@
 
 module Sashite
   module Pin
-    # Constants for PIN (Piece Identifier Notation).
+    # Performance-oriented constants for PIN (Piece Identifier Notation).
     #
-    # This module defines the valid values for PIN attributes.
+    # All lookups are O(1) frozen Hashes. Byte-level constants eliminate
+    # repeated method calls in the parser hot path.
     module Constants
-      # Valid piece types (uppercase symbols A-Z).
-      VALID_TYPES = %i[A B C D E F G H I J K L M N O P Q R S T U V W X Y Z].freeze
+      # ====================================================================
+      # Domain values
+      # ====================================================================
+
+      # Valid piece name abbreviations (uppercase symbols :A..:Z).
+      VALID_ABBRS = %i[A B C D E F G H I J K L M N O P Q R S T U V W X Y Z].freeze
 
       # Valid player sides.
       VALID_SIDES = %i[first second].freeze
@@ -15,21 +20,54 @@ module Sashite
       # Valid piece states.
       VALID_STATES = %i[normal enhanced diminished].freeze
 
-      # Maximum length of a valid PIN string.
-      # Corresponds to "+K^" (state modifier + letter + terminal marker).
-      MAX_STRING_LENGTH = 3
+      # ====================================================================
+      # O(1) validation lookups (frozen Hashes → faster than Array#include?)
+      # ====================================================================
+
+      # { :A => true, :B => true, … :Z => true }
+      ABBR_SET = VALID_ABBRS.each_with_object({}) { |a, h| h[a] = true }.freeze
+
+      # { :first => true, :second => true }
+      SIDE_SET = VALID_SIDES.each_with_object({}) { |s, h| h[s] = true }.freeze
 
-      # State modifier for enhanced state.
-      ENHANCED_PREFIX = "+"
+      # { :normal => true, :enhanced => true, :diminished => true }
+      STATE_SET = VALID_STATES.each_with_object({}) { |s, h| h[s] = true }.freeze
 
-      # State modifier for diminished state.
+      # ====================================================================
+      # String fragments (frozen, reused by Identifier#to_s)
+      # ====================================================================
+
+      ENHANCED_PREFIX  = "+"
       DIMINISHED_PREFIX = "-"
+      TERMINAL_SUFFIX  = "^"
+      EMPTY_STRING     = ""
+
+      # ====================================================================
+      # Byte constants (used by Parser for zero-allocation character checks)
+      # ====================================================================
+
+      # State modifier bytes
+      BYTE_PLUS  = 0x2B # '+'
+      BYTE_MINUS = 0x2D # '-'
+
+      # Terminal marker byte
+      BYTE_CARET = 0x5E # '^'
+
+      # ASCII letter ranges
+      BYTE_UPPER_A = 0x41 # 'A'
+      BYTE_UPPER_Z = 0x5A # 'Z'
+      BYTE_LOWER_A = 0x61 # 'a'
+      BYTE_LOWER_Z = 0x7A # 'z'
+
+      # Case conversion offset (lowercase - uppercase = 32)
+      CASE_OFFSET = 0x20
 
-      # Empty string (no modifier).
-      EMPTY_STRING = ""
+      # ====================================================================
+      # Token length
+      # ====================================================================
 
-      # Terminal marker suffix.
-      TERMINAL_SUFFIX = "^"
+      # Maximum byte length of a valid PIN string: "+K^"
+      MAX_BYTE_LENGTH = 3
     end
   end
 end

data/lib/sashite/pin/errors/argument/messages.rb

@@ -5,21 +5,18 @@ module Sashite
     module Errors
       class Argument < ::ArgumentError
         # Centralized error messages for PIN parsing and validation.
-        #
-        # @example
-        #   raise Errors::Argument, Messages::EMPTY_INPUT
         module Messages
           # Parsing errors
-          EMPTY_INPUT = "empty input"
-          INPUT_TOO_LONG = "input exceeds 3 characters"
+          EMPTY_INPUT             = "empty input"
+          INPUT_TOO_LONG          = "input exceeds 3 characters"
           MUST_CONTAIN_ONE_LETTER = "must contain exactly one letter"
-          INVALID_STATE_MODIFIER = "invalid state modifier"
+          INVALID_STATE_MODIFIER  = "invalid state modifier"
           INVALID_TERMINAL_MARKER = "invalid terminal marker"
 
-          # Validation errors (constructor)
-          INVALID_TYPE = "type must be a symbol from :A to :Z"
-          INVALID_SIDE = "side must be :first or :second"
-          INVALID_STATE = "state must be :normal, :enhanced, or :diminished"
+          # Validation errors (constructor / fetch)
+          INVALID_ABBR     = "abbr must be a symbol from :A to :Z"
+          INVALID_SIDE     = "side must be :first or :second"
+          INVALID_STATE    = "state must be :normal, :enhanced, or :diminished"
           INVALID_TERMINAL = "terminal must be true or false"
         end
       end

data/lib/sashite/pin/errors/argument.rb

@@ -6,9 +6,6 @@ module Sashite
   module Pin
     module Errors
       # Error raised when PIN parsing or validation fails.
-      #
-      # @example
-      #   raise Argument, Argument::Messages::EMPTY_INPUT
       class Argument < ::ArgumentError
       end
     end