sashite-pin 4.1.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e00046935bd19fe218aed6188bc310389c9a93e5e36aad8b91890d36046c4165
-  data.tar.gz: e90e9430c444175c658262c486eddfe3c09a6e5da2c88b0b1365fb91f14616a0
+  metadata.gz: 654a422f7d1d03a9b2e474e6f29644c7d8636cc6a7da60100fc49efa87ccda02
+  data.tar.gz: c9548c761f14c4dc76acc1376fda12fa64339bbe7d6b2567b49f205113c89b59
 SHA512:
-  metadata.gz: f716220c9d53ba9003712d64c3335f20b395c2174637b2432f43ca01c654dca7586b84f3057747126cf899003478afc071de31cd93e76ce0dc49dd7f7a9f99d5
-  data.tar.gz: 0aedbcd707733bbd81dd6fa48608a52f66016aec2e63162c5f841cbaf359959d3f902d8dddca2e08848d57dce1f3ccb31e3baeebb791812bea91c678a1f9fe0f
+  metadata.gz: fc265f0049d911133c3de8910ed15911a207fcec239aa97d8c4a9766242f2f5ca53d80802e36c9aafeac525eb79a01ef4f3625738f04622db97b210d8094296c
+  data.tar.gz: 5a5254e21d89dfec797ce72c62d1a65689c9db5460a91c13edba6360655483b7dd1c0a024c04ee35e5e35971c30e08518b540086112334da0a662d2ea1f3b432

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
@@ -53,40 +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
+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")
@@ -108,6 +153,9 @@ 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
@@ -137,24 +185,57 @@ 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.
-  #
-  # @param abbr [Symbol] Piece name abbreviation (:A to :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]
-  def initialize(abbr, side, state = :normal, terminal: false)
-
   # Returns the piece name abbreviation (always uppercase symbol).
   #
-  # @return [Symbol]
+  # @return [Symbol] :A through :Z
   def abbr
 
   # Returns the piece side.
@@ -179,40 +260,9 @@ class Sashite::Pin::Identifier
 end
 ```
 
-### 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
-```
-
-### 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 new `Sashite::Pin::Identifier` instances:
+All transformations return cached `Sashite::Pin::Identifier` instances from the flyweight pool:
 
 ```ruby
 # State transformations
@@ -256,9 +306,18 @@ 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 |
 |---------|-------|
@@ -270,13 +329,30 @@ All parsing and validation errors raise `ArgumentError` with descriptive message
 
 ## Design Principles
 
-- **Bounded values**: Explicit validation of abbreviations, sides, and 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 attribute 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,11 +2,16 @@
 
 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 name abbreviations (uppercase symbols A-Z).
+      # ====================================================================
+      # 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.
@@ -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_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"
+          # 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