sashite-pin 2.0.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0335d119541a7fa271689c6235a9c785a4c46f6c70e9577d4cddcc597d520dd5
-  data.tar.gz: 7d95e04c803457156561bfe0fd8e270db5df1929b58721b9ed8266646f60e7e1
+  metadata.gz: f69bdd89484b5fc844f13c7cedbbdf2efe15f75620fe1eb695d0258120cf16d6
+  data.tar.gz: 38c51ef6f22d3267c26f5baa425306645e2a17f8448575da6759112a6b71f115
 SHA512:
-  metadata.gz: 6904c80bee041595400f4074ed48a975ad6337c3c5a8c66f9d18ad7864f19e23d04e34b30c725d37ce9c4bfde58667328a82bbd1c38208c123cb44a9da00b283
-  data.tar.gz: 32289d6453d81ff2e1920aeb7d69eedfac6bc61f9acdd1929e7ca4bc09c6988bb2a64bc3620130cfb63024977e0508b7c5ffce695590382eac3420d85454c67a
+  metadata.gz: c98b8c1e383c0414341be4ea7ea9f3f5f5864330f16f3faed608a315cd46a52e039f539c4d45f45d8b84aa6965d999560f0d0d937cf4743ec6c05655e9b6470d
+  data.tar.gz: 847ca5d4e6c6bd5697d665bebc103e01f876fc2a5f8c0947a27ef3589de94bd9d482bb69322817985e9dc6d23a3588801c8021ab54467b70bda49929cd62aef4

data/README.md

@@ -11,14 +11,14 @@
 
 PIN (Piece Identifier Notation) provides an ASCII-based format for representing pieces in abstract strategy board games. PIN translates piece attributes from the [Game Protocol](https://sashite.dev/game-protocol/) into a compact, portable notation system.
 
-This gem implements the [PIN Specification v1.0.0](https://sashite.dev/specs/pin/1.0.0/), providing a modern Ruby interface with immutable piece objects and functional programming principles.
+This gem implements the [PIN Specification v1.0.0](https://sashite.dev/specs/pin/1.0.0/), providing a modern Ruby interface with immutable identifier objects and functional programming principles.
 
 ## Installation
 
 ```ruby
 # In your Gemfile
 gem "sashite-pin"
-```
+````
 
 Or install manually:
 
@@ -31,16 +31,16 @@ gem install sashite-pin
 ```ruby
 require "sashite/pin"
 
-# Parse PIN strings into piece objects
-piece = Sashite::Pin.parse("K")          # => #<Pin::Piece type=:K side=:first state=:normal>
-piece.to_s                               # => "K"
-piece.type                               # => :K
-piece.side                               # => :first
-piece.state                              # => :normal
+# Parse PIN strings into identifier objects
+identifier = Sashite::Pin.parse("K")          # => #<Pin::Identifier type=:K side=:first state=:normal>
+identifier.to_s                               # => "K"
+identifier.type                               # => :K
+identifier.side                               # => :first
+identifier.state                              # => :normal
 
-# Create pieces directly
-piece = Sashite::Pin.piece(:K, :first, :normal)    # => #<Pin::Piece type=:K side=:first state=:normal>
-piece = Sashite::Pin::Piece.new(:R, :second, :enhanced)  # => #<Pin::Piece type=:R side=:second state=:enhanced>
+# Create identifiers directly
+identifier = Sashite::Pin.identifier(:K, :first, :normal)    # => #<Pin::Identifier type=:K side=:first state=:normal>
+identifier = Sashite::Pin::Identifier.new(:R, :second, :enhanced)  # => #<Pin::Identifier type=:R side=:second state=:enhanced>
 
 # Validate PIN strings
 Sashite::Pin.valid?("K")                 # => true
@@ -48,170 +48,104 @@ Sashite::Pin.valid?("+R")                # => true
 Sashite::Pin.valid?("invalid")           # => false
 
 # State manipulation (returns new immutable instances)
-enhanced = piece.enhance                 # => #<Pin::Piece type=:K side=:first state=:enhanced>
-enhanced.to_s                            # => "+K"
-diminished = piece.diminish              # => #<Pin::Piece type=:K side=:first state=:diminished>
-diminished.to_s                          # => "-K"
+enhanced = identifier.enhance                 # => #<Pin::Identifier type=:K side=:first state=:enhanced>
+enhanced.to_s                                 # => "+K"
+diminished = identifier.diminish              # => #<Pin::Identifier type=:K side=:first state=:diminished>
+diminished.to_s                               # => "-K"
 
 # Side manipulation
-flipped = piece.flip                     # => #<Pin::Piece type=:K side=:second state=:normal>
-flipped.to_s                             # => "k"
+flipped = identifier.flip                     # => #<Pin::Identifier type=:K side=:second state=:normal>
+flipped.to_s                                  # => "k"
 
 # Type manipulation
-queen = piece.with_type(:Q)              # => #<Pin::Piece type=:Q side=:first state=:normal>
-queen.to_s                               # => "Q"
+queen = identifier.with_type(:Q)              # => #<Pin::Identifier type=:Q side=:first state=:normal>
+queen.to_s                                    # => "Q"
 
 # State queries
-piece.normal?                            # => true
-enhanced.enhanced?                       # => true
-diminished.diminished?                   # => true
+identifier.normal?                            # => true
+enhanced.enhanced?                            # => true
+diminished.diminished?                        # => true
 
 # Side queries
-piece.first_player?                      # => true
-flipped.second_player?                   # => true
+identifier.first_player?                      # => true
+flipped.second_player?                        # => true
 
 # Attribute access
-piece.letter                             # => "K"
-enhanced.prefix                          # => "+"
-piece.prefix                             # => ""
+identifier.letter                             # => "K"
+enhanced.prefix                               # => "+"
+identifier.prefix                             # => ""
 
 # Type and side comparison
 king1 = Sashite::Pin.parse("K")
 king2 = Sashite::Pin.parse("k")
 queen = Sashite::Pin.parse("Q")
 
-king1.same_type?(king2)                  # => true (both kings)
-king1.same_side?(queen)                  # => true (both first player)
-king1.same_type?(queen)                  # => false (different types)
+king1.same_type?(king2)                       # => true (both kings)
+king1.same_side?(queen)                       # => true (both first player)
+king1.same_type?(queen)                       # => false (different types)
 
 # Functional transformations can be chained
 pawn = Sashite::Pin.parse("P")
-enemy_promoted = pawn.flip.enhance       # => "+p" (second player promoted pawn)
+enemy_promoted = pawn.flip.enhance            # => "+p" (second player promoted pawn)
 ```
 
 ## Format Specification
 
 ### Structure
+
 ```
 [<state>]<letter>
 ```
 
 ### Components
 
-- **Letter** (`A-Z`, `a-z`): Represents piece type and side
-  - Uppercase: First player pieces
-  - Lowercase: Second player pieces
-- **State** (optional prefix):
-  - `+`: Enhanced state (promoted, upgraded, empowered)
-  - `-`: Diminished state (weakened, restricted, temporary)
-  - No prefix: Normal state
-
-### Regular Expression
-```ruby
-/\A[-+]?[A-Za-z]\z/
-```
+* **Letter** (`A-Z`, `a-z`): Represents piece type and side
 
-### 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)
+  * Uppercase: First player pieces
+  * Lowercase: Second player pieces
+* **State** (optional prefix):
 
-## Game Examples
+  * `+`: Enhanced state (promoted, upgraded, empowered)
+  * `-`: Diminished state (weakened, restricted, temporary)
+  * No prefix: Normal state
 
-### Western Chess
-```ruby
-# Standard pieces
-king = Sashite::Pin.piece(:K, :first, :normal)    # => white king
-king.first_player?                                # => true
-king.type                                         # => :K
-
-# State modifiers for special conditions
-castling_king = king.enhance                      # => castling-eligible king
-castling_king.to_s                                # => "+K"
-
-vulnerable_pawn = Sashite::Pin.piece(:P, :first, :diminished)  # => en passant vulnerable
-vulnerable_pawn.to_s                              # => "-P"
-
-# All piece types
-piece_types = [:K, :Q, :R, :B, :N, :P]
-white_pieces = piece_types.map { |type| Sashite::Pin.piece(type, :first, :normal) }
-black_pieces = white_pieces.map(&:flip)           # Convert to black pieces
-```
+### Regular Expression
 
-### Japanese Chess (Shōgi)
 ```ruby
-# Basic pieces
-rook = Sashite::Pin.piece(:R, :first, :normal)    # => white rook
-bishop = Sashite::Pin.piece(:B, :first, :normal)  # => white bishop
-
-# Promoted pieces (enhanced state)
-dragon_king = rook.enhance                        # => promoted rook (Dragon King)
-dragon_king.to_s                                  # => "+R"
-
-dragon_horse = bishop.enhance                     # => promoted bishop (Dragon Horse)
-dragon_horse.to_s                                 # => "+B"
-
-# Promoted pawn
-pawn = Sashite::Pin.piece(:P, :first, :normal)
-tokin = pawn.enhance                              # => promoted pawn (Tokin)
-tokin.to_s                                        # => "+P"
-
-# All promotable pieces can use the same pattern
-promotable_types = [:R, :B, :S, :N, :L, :P]
-promotable = promotable_types.map { |type| Sashite::Pin.piece(type, :first, :normal) }
-promoted = promotable.map(&:enhance)
+/\A[-+]?[A-Za-z]\z/
 ```
 
-### Thai Chess (Makruk)
-```ruby
-# Basic pieces
-met = Sashite::Pin.piece(:M, :first, :normal)     # => white Met (queen)
-pawn = Sashite::Pin.piece(:P, :first, :normal)    # => white Bia (pawn)
-
-# Promoted pawns
-bia_kaew = pawn.enhance                           # => promoted pawn (Bia Kaew)
-bia_kaew.to_s                                     # => "+P"
-
-# Makruk pieces
-makruk_types = [:K, :M, :R, :B, :N, :P]
-makruk_pieces = makruk_types.map { |type| Sashite::Pin.piece(type, :first, :normal) }
-```
+### Examples
 
-### Chinese Chess (Xiangqi)
-```ruby
-# Pieces with positional states
-general = Sashite::Pin.piece(:G, :first, :normal) # => red general
-flying_general = general.enhance                  # => flying general (special state)
-flying_general.to_s                               # => "+G"
-
-# Soldiers that crossed the river
-soldier = Sashite::Pin.piece(:P, :first, :normal)
-crossed_soldier = soldier.enhance                 # => soldier with enhanced movement
-crossed_soldier.to_s                              # => "+P"
-```
+* `K` - First player king (normal state)
+* `k` - Second player king (normal state)
+* `+R` - First player rook (enhanced state)
+* `-p` - Second player pawn (diminished state)
 
 ## API Reference
 
 ### Main Module Methods
 
-- `Sashite::Pin.valid?(pin_string)` - Check if string is valid PIN notation
-- `Sashite::Pin.parse(pin_string)` - Parse PIN string into Piece object
-- `Sashite::Pin.piece(type, side, state = :normal)` - Create piece instance directly
+* `Sashite::Pin.valid?(pin_string)` - Check if string is valid PIN notation
+* `Sashite::Pin.parse(pin_string)` - Parse PIN string into Identifier object
+* `Sashite::Pin.identifier(type, side, state = :normal)` - Create identifier instance directly
 
-### Piece Class
+### Identifier Class
 
 #### Creation and Parsing
-- `Sashite::Pin::Piece.new(type, side, state = :normal)` - Create piece instance
-- `Sashite::Pin::Piece.parse(pin_string)` - Parse PIN string (same as module method)
+
+* `Sashite::Pin::Identifier.new(type, side, state = :normal)` - Create identifier instance
+* `Sashite::Pin::Identifier.parse(pin_string)` - Parse PIN string (same as module method)
+* `Sashite::Pin::Identifier.valid?(pin_string)` - Validate PIN string (class method)
 
 #### Attribute Access
-- `#type` - Get piece type (symbol :A to :Z, always uppercase)
-- `#side` - Get player side (:first or :second)
-- `#state` - Get state (:normal, :enhanced, or :diminished)
-- `#letter` - Get letter representation (string, case determined by side)
-- `#prefix` - Get state prefix (string: "+", "-", or "")
-- `#to_s` - Convert to PIN string representation
+
+* `#type` - Get piece type (symbol \:A to \:Z, always uppercase)
+* `#side` - Get player side (\:first or \:second)
+* `#state` - Get state (\:normal, \:enhanced, or \:diminished)
+* `#letter` - Get letter representation (string, case determined by side)
+* `#prefix` - Get state prefix (string: "+", "-", or "")
+* `#to_s` - Convert to PIN string representation
 
 #### Type and Case Handling
 
@@ -219,46 +153,52 @@ crossed_soldier.to_s                              # => "+P"
 
 ```ruby
 # Both create the same internal type representation
-piece1 = Sashite::Pin.parse("K")  # type: :K, side: :first
-piece2 = Sashite::Pin.parse("k")  # type: :K, side: :second
+identifier1 = Sashite::Pin.parse("K")  # type: :K, side: :first
+identifier2 = Sashite::Pin.parse("k")  # type: :K, side: :second
 
-piece1.type    # => :K (uppercase symbol)
-piece2.type    # => :K (same uppercase symbol)
+identifier1.type    # => :K (uppercase symbol)
+identifier2.type    # => :K (same uppercase symbol)
 
-piece1.letter  # => "K" (uppercase display)
-piece2.letter  # => "k" (lowercase display)
+identifier1.letter  # => "K" (uppercase display)
+identifier2.letter  # => "k" (lowercase display)
 ```
 
 #### State Queries
-- `#normal?` - Check if normal state (no modifiers)
-- `#enhanced?` - Check if enhanced state
-- `#diminished?` - Check if diminished state
+
+* `#normal?` - Check if normal state (no modifiers)
+* `#enhanced?` - Check if enhanced state
+* `#diminished?` - Check if diminished state
 
 #### Side Queries
-- `#first_player?` - Check if first player piece
-- `#second_player?` - Check if second player piece
+
+* `#first_player?` - Check if first player identifier
+* `#second_player?` - Check if second player identifier
 
 #### State Transformations (immutable - return new instances)
-- `#enhance` - Create enhanced version
-- `#unenhance` - Remove enhanced state
-- `#diminish` - Create diminished version
-- `#undiminish` - Remove diminished state
-- `#normalize` - Remove all state modifiers
-- `#flip` - Switch player (change side)
+
+* `#enhance` - Create enhanced version
+* `#unenhance` - Remove enhanced state
+* `#diminish` - Create diminished version
+* `#undiminish` - Remove diminished state
+* `#normalize` - Remove all state modifiers
+* `#flip` - Switch player (change side)
 
 #### Attribute Transformations (immutable - return new instances)
-- `#with_type(new_type)` - Create piece with different type
-- `#with_side(new_side)` - Create piece with different side
-- `#with_state(new_state)` - Create piece with different state
+
+* `#with_type(new_type)` - Create identifier with different type
+* `#with_side(new_side)` - Create identifier with different side
+* `#with_state(new_state)` - Create identifier with different state
 
 #### Comparison Methods
-- `#same_type?(other)` - Check if same piece type
-- `#same_side?(other)` - Check if same side
-- `#same_state?(other)` - Check if same state
-- `#==(other)` - Full equality comparison
+
+* `#same_type?(other)` - Check if same piece type
+* `#same_side?(other)` - Check if same side
+* `#same_state?(other)` - Check if same state
+* `#==(other)` - Full equality comparison
 
 ### Constants
-- `Sashite::Pin::PIN_REGEX` - Regular expression for PIN validation
+
+* `Sashite::Pin::Identifier::PIN_PATTERN` - Regular expression for PIN validation (internal use)
 
 ## Advanced Usage
 

data/lib/sashite/pin/{piece.rb → identifier.rb}

@@ -2,9 +2,9 @@
 
 module Sashite
   module Pin
-    # Represents a piece in PIN (Piece Identifier Notation) format.
+    # Represents an identifier in PIN (Piece Identifier Notation) format.
     #
-    # A piece consists of a single ASCII letter with optional state modifiers:
+    # An identifier consists of a single ASCII letter with optional state modifiers:
     # - Enhanced state: prefix '+'
     # - Diminished state: prefix '-'
     # - Normal state: no modifier
@@ -15,7 +15,7 @@ module Sashite
     #
     # All instances are immutable - state manipulation methods return new instances.
     # This follows the Game Protocol's piece model with Type, Side, and State attributes.
-    class Piece
+    class Identifier
       # PIN validation pattern matching the specification
       PIN_PATTERN = /\A(?<prefix>[-+])?(?<letter>[a-zA-Z])\z/
 
@@ -57,7 +57,7 @@ module Sashite
       # @return [Symbol] the piece state (:normal, :enhanced, or :diminished)
       attr_reader :state
 
-      # Create a new piece instance
+      # Create a new identifier instance
       #
       # @param type [Symbol] piece type (:A to :Z)
       # @param side [Symbol] player side (:first or :second)
@@ -75,15 +75,15 @@ module Sashite
         freeze
       end
 
-      # Parse a PIN string into a Piece object
+      # Parse a PIN string into an Identifier object
       #
       # @param pin_string [String] PIN notation string
-      # @return [Piece] new piece instance
+      # @return [Identifier] new identifier instance
       # @raise [ArgumentError] if the PIN string is invalid
       # @example
-      #   Pin::Piece.parse("k")     # => #<Pin::Piece type=:K side=:second state=:normal>
-      #   Pin::Piece.parse("+R")    # => #<Pin::Piece type=:R side=:first state=:enhanced>
-      #   Pin::Piece.parse("-p")    # => #<Pin::Piece type=:P side=:second state=:diminished>
+      #   Pin::Identifier.parse("k")     # => #<Pin::Identifier type=:K side=:second state=:normal>
+      #   Pin::Identifier.parse("+R")    # => #<Pin::Identifier type=:R side=:first state=:enhanced>
+      #   Pin::Identifier.parse("-p")    # => #<Pin::Identifier type=:P side=:second state=:diminished>
       def self.parse(pin_string)
         string_value = String(pin_string)
         matches = match_pattern(string_value)
@@ -92,27 +92,41 @@ module Sashite
         enhanced = matches[:prefix] == ENHANCED_PREFIX
         diminished = matches[:prefix] == DIMINISHED_PREFIX
 
-        # Extract type and side from letter
-        piece_type = letter.upcase.to_sym
-        piece_side = letter == letter.upcase ? FIRST_PLAYER : SECOND_PLAYER
-        piece_state = if enhanced
-                        ENHANCED_STATE
-                      elsif diminished
-                        DIMINISHED_STATE
-                      else
-                        NORMAL_STATE
-                      end
-
-        new(piece_type, piece_side, piece_state)
+        type = letter.upcase.to_sym
+        side = letter == letter.upcase ? FIRST_PLAYER : SECOND_PLAYER
+        state = if enhanced
+                  ENHANCED_STATE
+                elsif diminished
+                  DIMINISHED_STATE
+                else
+                  NORMAL_STATE
+                end
+
+        new(type, side, state)
       end
 
-      # Convert the piece to its PIN string representation
+      # Check if a string is a valid PIN notation
+      #
+      # @param pin_string [String] The string to validate
+      # @return [Boolean] true if valid PIN, false otherwise
+      #
+      # @example
+      #   Sashite::Pin::Identifier.valid?("K")    # => true
+      #   Sashite::Pin::Identifier.valid?("+R")   # => true
+      #   Sashite::Pin::Identifier.valid?("-p")   # => true
+      #   Sashite::Pin::Identifier.valid?("KK")   # => false
+      #   Sashite::Pin::Identifier.valid?("++K")  # => false
+      def self.valid?(pin_string)
+        return false unless pin_string.is_a?(::String)
+
+        pin_string.match?(PIN_PATTERN)
+      end
+
+      # Convert the identifier to its PIN string representation
       #
       # @return [String] PIN notation string
       # @example
-      #   piece.to_s  # => "+R"
-      #   piece.to_s  # => "-p"
-      #   piece.to_s  # => "K"
+      #   identifier.to_s  # => "+R"
       def to_s
         "#{prefix}#{letter}"
       end
@@ -135,76 +149,62 @@ module Sashite
         end
       end
 
-      # Create a new piece with enhanced state
+      # Create a new identifier with enhanced state
       #
-      # @return [Piece] new piece instance with enhanced state
-      # @example
-      #   piece.enhance  # (:K, :first, :normal) => (:K, :first, :enhanced)
+      # @return [Identifier] new identifier instance with enhanced state
       def enhance
         return self if enhanced?
 
         self.class.new(type, side, ENHANCED_STATE)
       end
 
-      # Create a new piece without enhanced state
+      # Create a new identifier without enhanced state
       #
-      # @return [Piece] new piece instance without enhanced state
-      # @example
-      #   piece.unenhance  # (:K, :first, :enhanced) => (:K, :first, :normal)
+      # @return [Identifier] new identifier instance with normal state
       def unenhance
         return self unless enhanced?
 
         self.class.new(type, side, NORMAL_STATE)
       end
 
-      # Create a new piece with diminished state
+      # Create a new identifier with diminished state
       #
-      # @return [Piece] new piece instance with diminished state
-      # @example
-      #   piece.diminish  # (:K, :first, :normal) => (:K, :first, :diminished)
+      # @return [Identifier] new identifier instance with diminished state
       def diminish
         return self if diminished?
 
         self.class.new(type, side, DIMINISHED_STATE)
       end
 
-      # Create a new piece without diminished state
+      # Create a new identifier without diminished state
       #
-      # @return [Piece] new piece instance without diminished state
-      # @example
-      #   piece.undiminish  # (:K, :first, :diminished) => (:K, :first, :normal)
+      # @return [Identifier] new identifier instance with normal state
       def undiminish
         return self unless diminished?
 
         self.class.new(type, side, NORMAL_STATE)
       end
 
-      # Create a new piece with normal state (no modifiers)
+      # Create a new identifier with normal state (no modifiers)
       #
-      # @return [Piece] new piece instance with normal state
-      # @example
-      #   piece.normalize  # (:K, :first, :enhanced) => (:K, :first, :normal)
+      # @return [Identifier] new identifier instance with normal state
       def normalize
         return self if normal?
 
         self.class.new(type, side, NORMAL_STATE)
       end
 
-      # Create a new piece with opposite ownership (case)
+      # Create a new identifier with opposite side
       #
-      # @return [Piece] new piece instance with flipped case
-      # @example
-      #   piece.flip  # (:K, :first, :normal) => (:K, :second, :normal)
+      # @return [Identifier] new identifier instance with opposite side
       def flip
         self.class.new(type, opposite_side, state)
       end
 
-      # Create a new piece with a different type (keeping same side and state)
+      # Create a new identifier with a different type
       #
       # @param new_type [Symbol] new type (:A to :Z)
-      # @return [Piece] new piece instance with different type
-      # @example
-      #   piece.with_type(:Q)  # (:K, :first, :normal) => (:Q, :first, :normal)
+      # @return [Identifier] new identifier instance with new type
       def with_type(new_type)
         self.class.validate_type(new_type)
         return self if type == new_type
@@ -212,12 +212,10 @@ module Sashite
         self.class.new(new_type, side, state)
       end
 
-      # Create a new piece with a different side (keeping same type and state)
+      # Create a new identifier with a different side
       #
-      # @param new_side [Symbol] :first or :second
-      # @return [Piece] new piece instance with different side
-      # @example
-      #   piece.with_side(:second)  # (:K, :first, :normal) => (:K, :second, :normal)
+      # @param new_side [Symbol] new side (:first or :second)
+      # @return [Identifier] new identifier instance with new side
       def with_side(new_side)
         self.class.validate_side(new_side)
         return self if side == new_side
@@ -225,12 +223,10 @@ module Sashite
         self.class.new(type, new_side, state)
       end
 
-      # Create a new piece with a different state (keeping same type and side)
+      # Create a new identifier with a different state
       #
-      # @param new_state [Symbol] :normal, :enhanced, or :diminished
-      # @return [Piece] new piece instance with different state
-      # @example
-      #   piece.with_state(:enhanced)  # (:K, :first, :normal) => (:K, :first, :enhanced)
+      # @param new_state [Symbol] new state (:normal, :enhanced, or :diminished)
+      # @return [Identifier] new identifier instance with new state
       def with_state(new_state)
         self.class.validate_state(new_state)
         return self if state == new_state
@@ -238,56 +234,54 @@ module Sashite
         self.class.new(type, side, new_state)
       end
 
-      # Check if the piece has enhanced state
+      # Check if the identifier has enhanced state
       #
       # @return [Boolean] true if enhanced
       def enhanced?
         state == ENHANCED_STATE
       end
 
-      # Check if the piece has diminished state
+      # Check if the identifier has diminished state
       #
       # @return [Boolean] true if diminished
       def diminished?
         state == DIMINISHED_STATE
       end
 
-      # Check if the piece has normal state (no modifiers)
+      # Check if the identifier has normal state
       #
-      # @return [Boolean] true if no modifiers are present
+      # @return [Boolean] true if normal
       def normal?
         state == NORMAL_STATE
       end
 
-      # Check if the piece belongs to the first player
+      # Check if the identifier belongs to the first player
       #
       # @return [Boolean] true if first player
       def first_player?
         side == FIRST_PLAYER
       end
 
-      # Check if the piece belongs to the second player
+      # Check if the identifier belongs to the second player
       #
       # @return [Boolean] true if second player
       def second_player?
         side == SECOND_PLAYER
       end
 
-      # Check if this piece is the same type as another (ignoring side and state)
+      # Check if this identifier is the same type as another
       #
-      # @param other [Piece] piece to compare with
+      # @param other [Identifier] identifier to compare with
       # @return [Boolean] true if same type
-      # @example
-      #   king1.same_type?(king2)  # (:K, :first, :normal) and (:K, :second, :enhanced) => true
       def same_type?(other)
         return false unless other.is_a?(self.class)
 
         type == other.type
       end
 
-      # Check if this piece belongs to the same side as another
+      # Check if this identifier has the same side as another
       #
-      # @param other [Piece] piece to compare with
+      # @param other [Identifier] identifier to compare with
       # @return [Boolean] true if same side
       def same_side?(other)
         return false unless other.is_a?(self.class)
@@ -295,9 +289,9 @@ module Sashite
         side == other.side
       end
 
-      # Check if this piece has the same state as another
+      # Check if this identifier has the same state as another
       #
-      # @param other [Piece] piece to compare with
+      # @param other [Identifier] identifier to compare with
       # @return [Boolean] true if same state
       def same_state?(other)
         return false unless other.is_a?(self.class)
@@ -308,7 +302,7 @@ module Sashite
       # Custom equality comparison
       #
       # @param other [Object] object to compare with
-      # @return [Boolean] true if pieces are equal
+      # @return [Boolean] true if identifiers are equal
       def ==(other)
         return false unless other.is_a?(self.class)
 
@@ -371,7 +365,7 @@ module Sashite
 
       private
 
-      # Get the opposite side of the current piece
+      # Get the opposite side of the current identifier
       #
       # @return [Symbol] :first if current side is :second, :second if current side is :first
       def opposite_side

data/lib/sashite/pin.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "pin/piece"
+require_relative "pin/identifier"
 
 module Sashite
   # PIN (Piece Identifier Notation) implementation for Ruby
@@ -20,13 +20,9 @@ module Sashite
   #
   # See: https://sashite.dev/specs/pin/1.0.0/
   module Pin
-    # Regular expression for PIN validation
-    # Matches: optional state modifier followed by a single letter
-    PIN_REGEX = /\A[-+]?[A-Za-z]\z/
-
     # Check if a string is a valid PIN notation
     #
-    # @param pin [String] The string to validate
+    # @param pin_string [String] The string to validate
     # @return [Boolean] true if valid PIN, false otherwise
     #
     # @example
@@ -35,38 +31,36 @@ module Sashite
     #   Sashite::Pin.valid?("-p")   # => true
     #   Sashite::Pin.valid?("KK")   # => false
     #   Sashite::Pin.valid?("++K")  # => false
-    def self.valid?(pin)
-      return false unless pin.is_a?(::String)
-
-      pin.match?(PIN_REGEX)
+    def self.valid?(pin_string)
+      Identifier.valid?(pin_string)
     end
 
-    # Parse a PIN string into a Piece object
+    # Parse a PIN string into an Identifier object
     #
     # @param pin_string [String] PIN notation string
-    # @return [Pin::Piece] new piece instance
+    # @return [Pin::Identifier] new identifier instance
     # @raise [ArgumentError] if the PIN string is invalid
     # @example
-    #   Sashite::Pin.parse("K")     # => #<Pin::Piece type=:K side=:first state=:normal>
-    #   Sashite::Pin.parse("+R")    # => #<Pin::Piece type=:R side=:first state=:enhanced>
-    #   Sashite::Pin.parse("-p")    # => #<Pin::Piece type=:P side=:second state=:diminished>
+    #   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)
-      Piece.parse(pin_string)
+      Identifier.parse(pin_string)
     end
 
-    # Create a new piece instance
+    # Create a new identifier instance
     #
     # @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)
-    # @return [Pin::Piece] new piece instance
+    # @return [Pin::Identifier] new identifier instance
     # @raise [ArgumentError] if parameters are invalid
     # @example
-    #   Sashite::Pin.piece(:K, :first, :normal)     # => #<Pin::Piece type=:K side=:first state=:normal>
-    #   Sashite::Pin.piece(:R, :first, :enhanced)   # => #<Pin::Piece type=:R side=:first state=:enhanced>
-    #   Sashite::Pin.piece(:P, :second, :diminished) # => #<Pin::Piece type=:P side=:second state=:diminished>
-    def self.piece(type, side, state = :normal)
-      Piece.new(type, side, state)
+    #   Sashite::Pin.identifier(:K, :first, :normal)     # => #<Pin::Identifier type=:K side=:first state=:normal>
+    #   Sashite::Pin.identifier(:R, :first, :enhanced)   # => #<Pin::Identifier type=:R side=:first state=:enhanced>
+    #   Sashite::Pin.identifier(:P, :second, :diminished) # => #<Pin::Identifier type=:P side=:second state=:diminished>
+    def self.identifier(type, side, state = :normal)
+      Identifier.new(type, side, state)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-pin
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 3.0.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -10,13 +10,13 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |
-  PIN (Piece Identifier Notation) provides an ASCII-based format for representing pieces
+  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 piece objects and functional programming
-  principles. PIN translates piece attributes from the Game Protocol into a compact,
-  portable notation system using ASCII letters with optional state modifiers and
-  case-based side encoding. Perfect for game engines, board game notation systems,
-  and multi-game environments.
+  a modern Ruby interface featuring immutable identifier objects and functional programming
+  principles. PIN uses single ASCII letters with optional state modifiers 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.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -26,7 +26,7 @@ files:
 - README.md
 - lib/sashite-pin.rb
 - lib/sashite/pin.rb
-- lib/sashite/pin/piece.rb
+- lib/sashite/pin/identifier.rb
 homepage: https://github.com/sashite/pin.rb
 licenses:
 - MIT
@@ -53,6 +53,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: PIN (Piece Identifier Notation) implementation for Ruby with immutable piece
+summary: PIN (Piece Identifier Notation) implementation for Ruby with immutable identifier
   objects
 test_files: []