sashite-pin 1.1.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6affbdb49961967a41cadbd94ced4b32f27279d2fbd7fcc06f74fe58e400184b
-  data.tar.gz: 5d3ea8362f3d4329cf748f36713d89456e624cc2de0dc238fb784421811e5e81
+  metadata.gz: 0335d119541a7fa271689c6235a9c785a4c46f6c70e9577d4cddcc597d520dd5
+  data.tar.gz: 7d95e04c803457156561bfe0fd8e270db5df1929b58721b9ed8266646f60e7e1
 SHA512:
-  metadata.gz: 71ef6fc371601e9845b667085eed4222f3bd2e03bcac2d076a653632dd535bd2eb139ca59d3e3e257a9fdb33ba6d1ce7435ea2dafe34efe7423cdbefef5d5ede
-  data.tar.gz: 70684742e2d2406f35a6259d34788ad3545880feb5ba407e993544c78da98f4930dbaccd7a1943579061cf8ab26e0737e8e5eb5dad03b55c7b422a314bc19c8c
+  metadata.gz: 6904c80bee041595400f4074ed48a975ad6337c3c5a8c66f9d18ad7864f19e23d04e34b30c725d37ce9c4bfde58667328a82bbd1c38208c123cb44a9da00b283
+  data.tar.gz: 32289d6453d81ff2e1920aeb7d69eedfac6bc61f9acdd1929e7ca4bc09c6988bb2a64bc3620130cfb63024977e0508b7c5ffce695590382eac3420d85454c67a

data/README.md

@@ -32,11 +32,15 @@ gem install sashite-pin
 require "sashite/pin"
 
 # Parse PIN strings into piece objects
-piece = Sashite::Pin.parse("K")          # => #<Pin::Piece letter="K" type="K" player=first>
+piece = Sashite::Pin.parse("K")          # => #<Pin::Piece type=:K side=:first state=:normal>
 piece.to_s                               # => "K"
-piece.first_player?                      # => true
-piece.type                               # => "K"
+piece.type                               # => :K
 piece.side                               # => :first
+piece.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>
 
 # Validate PIN strings
 Sashite::Pin.valid?("K")                 # => true
@@ -44,32 +48,45 @@ Sashite::Pin.valid?("+R")                # => true
 Sashite::Pin.valid?("invalid")           # => false
 
 # State manipulation (returns new immutable instances)
-enhanced = piece.enhance                 # => #<Pin::Piece letter="K" type="K" player=first enhanced=true>
+enhanced = piece.enhance                 # => #<Pin::Piece type=:K side=:first state=:enhanced>
 enhanced.to_s                            # => "+K"
-diminished = piece.diminish              # => #<Pin::Piece letter="K" type="K" player=first diminished=true>
+diminished = piece.diminish              # => #<Pin::Piece type=:K side=:first state=:diminished>
 diminished.to_s                          # => "-K"
 
-# Player manipulation
-flipped = piece.flip                     # => #<Pin::Piece letter="k" type="K" player=second>
+# Side manipulation
+flipped = piece.flip                     # => #<Pin::Piece 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"
+
 # State queries
 piece.normal?                            # => true
 enhanced.enhanced?                       # => true
 diminished.diminished?                   # => true
 
-# Type and player comparison
+# Side queries
+piece.first_player?                      # => true
+flipped.second_player?                   # => true
+
+# Attribute access
+piece.letter                             # => "K"
+enhanced.prefix                          # => "+"
+piece.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_player?(queen)                # => true (both first player)
+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" (black promoted pawn)
+enemy_promoted = pawn.flip.enhance       # => "+p" (second player promoted pawn)
 ```
 
 ## Format Specification
@@ -81,7 +98,7 @@ enemy_promoted = pawn.flip.enhance       # => "+p" (black promoted pawn)
 
 ### Components
 
-- **Letter** (`A-Z`, `a-z`): Represents piece type and player
+- **Letter** (`A-Z`, `a-z`): Represents piece type and side
   - Uppercase: First player pieces
   - Lowercase: Second player pieces
 - **State** (optional prefix):
@@ -105,70 +122,73 @@ enemy_promoted = pawn.flip.enhance       # => "+p" (black promoted pawn)
 ### Western Chess
 ```ruby
 # Standard pieces
-king = Sashite::Pin.parse("K")        # => white king
-king.first_player?                    # => true
-king.type                             # => "K"
+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"
+castling_king = king.enhance                      # => castling-eligible king
+castling_king.to_s                                # => "+K"
 
-vulnerable_pawn = Sashite::Pin.parse("P").diminish  # => en passant vulnerable
-vulnerable_pawn.to_s                  # => "-P"
+vulnerable_pawn = Sashite::Pin.piece(:P, :first, :diminished)  # => en passant vulnerable
+vulnerable_pawn.to_s                              # => "-P"
 
 # All piece types
-pieces = %w[K Q R B N P].map { |type| Sashite::Pin.parse(type) }
-black_pieces = pieces.map(&:flip)     # Convert to black pieces
+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
 ```
 
 ### Japanese Chess (Shōgi)
 ```ruby
 # Basic pieces
-rook = Sashite::Pin.parse("R")        # => white rook
-bishop = Sashite::Pin.parse("B")      # => white bishop
+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_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"
+dragon_horse = bishop.enhance                     # => promoted bishop (Dragon Horse)
+dragon_horse.to_s                                 # => "+B"
 
 # Promoted pawn
-pawn = Sashite::Pin.parse("P")
-tokin = pawn.enhance                  # => promoted pawn (Tokin)
-tokin.to_s                            # => "+P"
+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 = %w[R B S N L P].map { |type| Sashite::Pin.parse(type) }
+promotable_types = [:R, :B, :S, :N, :L, :P]
+promotable = promotable_types.map { |type| Sashite::Pin.piece(type, :first, :normal) }
 promoted = promotable.map(&:enhance)
 ```
 
 ### Thai Chess (Makruk)
 ```ruby
 # Basic pieces
-met = Sashite::Pin.parse("M")         # => white Met (queen)
-pawn = Sashite::Pin.parse("P")        # => white Bia (pawn)
+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"
+bia_kaew = pawn.enhance                           # => promoted pawn (Bia Kaew)
+bia_kaew.to_s                                     # => "+P"
 
 # Makruk pieces
-makruk_pieces = %w[K M R B N P].map { |type| Sashite::Pin.parse(type) }
+makruk_types = [:K, :M, :R, :B, :N, :P]
+makruk_pieces = makruk_types.map { |type| Sashite::Pin.piece(type, :first, :normal) }
 ```
 
 ### Chinese Chess (Xiangqi)
 ```ruby
 # Pieces with positional states
-general = Sashite::Pin.parse("G")     # => red general
-flying_general = general.enhance      # => flying general (special state)
-flying_general.to_s                   # => "+G"
+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.parse("P")
-crossed_soldier = soldier.enhance     # => soldier with enhanced movement
-crossed_soldier.to_s                  # => "+P"
+soldier = Sashite::Pin.piece(:P, :first, :normal)
+crossed_soldier = soldier.enhance                 # => soldier with enhanced movement
+crossed_soldier.to_s                              # => "+P"
 ```
 
 ## API Reference
@@ -177,26 +197,44 @@ crossed_soldier.to_s                  # => "+P"
 
 - `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
 
 ### Piece Class
 
 #### Creation and Parsing
-- `Sashite::Pin::Piece.new(letter, enhanced: false, diminished: false)` - Create piece instance
+- `Sashite::Pin::Piece.new(type, side, state = :normal)` - Create piece instance
 - `Sashite::Pin::Piece.parse(pin_string)` - Parse PIN string (same as module method)
 
-#### String Representation
+#### 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
-- `#letter` - Get the letter (type + side)
-- `#type` - Get piece type (uppercase letter)
-- `#side` - Get player side (`:first` or `:second`)
-- `#state` - Get state (`:normal`, `:enhanced`, or `:diminished`)
+
+#### Type and Case Handling
+
+**Important**: The `type` attribute is always stored as an uppercase symbol (`:A` to `:Z`), regardless of the input case when parsing. The display case in `#letter` and `#to_s` is determined by the `side` attribute:
+
+```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
+
+piece1.type    # => :K (uppercase symbol)
+piece2.type    # => :K (same uppercase symbol)
+
+piece1.letter  # => "K" (uppercase display)
+piece2.letter  # => "k" (lowercase display)
+```
 
 #### State Queries
 - `#normal?` - Check if normal state (no modifiers)
 - `#enhanced?` - Check if enhanced state
 - `#diminished?` - Check if diminished state
 
-#### Player Queries
+#### Side Queries
 - `#first_player?` - Check if first player piece
 - `#second_player?` - Check if second player piece
 
@@ -206,11 +244,17 @@ crossed_soldier.to_s                  # => "+P"
 - `#diminish` - Create diminished version
 - `#undiminish` - Remove diminished state
 - `#normalize` - Remove all state modifiers
-- `#flip` - Switch player (change case)
+- `#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
 
 #### Comparison Methods
 - `#same_type?(other)` - Check if same piece type
-- `#same_player?(other)` - Check if same player
+- `#same_side?(other)` - Check if same side
+- `#same_state?(other)` - Check if same state
 - `#==(other)` - Full equality comparison
 
 ### Constants
@@ -218,10 +262,34 @@ crossed_soldier.to_s                  # => "+P"
 
 ## Advanced Usage
 
+### Type Normalization Examples
+
+```ruby
+# Parsing different cases results in same type
+white_king = Sashite::Pin.parse("K")
+black_king = Sashite::Pin.parse("k")
+
+# Types are normalized to uppercase
+white_king.type  # => :K
+black_king.type  # => :K (same type!)
+
+# Sides are different
+white_king.side  # => :first
+black_king.side  # => :second
+
+# Display follows side convention
+white_king.letter # => "K"
+black_king.letter # => "k"
+
+# Same type, different sides
+white_king.same_type?(black_king)  # => true
+white_king.same_side?(black_king)  # => false
+```
+
 ### Immutable Transformations
 ```ruby
 # All transformations return new instances
-original = Sashite::Pin.parse("K")
+original = Sashite::Pin.piece(:K, :first, :normal)
 enhanced = original.enhance
 diminished = original.diminish
 
@@ -231,8 +299,8 @@ puts enhanced.to_s    # => "+K"
 puts diminished.to_s  # => "-K"
 
 # Transformations can be chained
-result = original.flip.enhance.flip.diminish
-puts result.to_s      # => "-K"
+result = original.flip.enhance.with_type(:Q)
+puts result.to_s      # => "+q"
 ```
 
 ### Game State Management
@@ -242,15 +310,15 @@ class GameBoard
     @pieces = {}
   end
 
-  def place(square, pin_string)
-    @pieces[square] = Sashite::Pin.parse(pin_string)
+  def place(square, piece)
+    @pieces[square] = piece
   end
 
-  def promote(square)
+  def promote(square, new_type = :Q)
     piece = @pieces[square]
     return nil unless piece&.normal?  # Can only promote normal pieces
 
-    @pieces[square] = piece.enhance
+    @pieces[square] = piece.with_type(new_type).enhance
   end
 
   def capture(from_square, to_square)
@@ -259,8 +327,8 @@ class GameBoard
     captured
   end
 
-  def pieces_by_player(first_player: true)
-    @pieces.select { |_, piece| piece.first_player? == first_player }
+  def pieces_by_side(side)
+    @pieces.select { |_, piece| piece.side == side }
   end
 
   def promoted_pieces
@@ -270,24 +338,24 @@ end
 
 # Usage
 board = GameBoard.new
-board.place("e1", "K")
-board.place("e8", "k")
-board.place("a7", "P")
+board.place("e1", Sashite::Pin.piece(:K, :first, :normal))
+board.place("e8", Sashite::Pin.piece(:K, :second, :normal))
+board.place("a7", Sashite::Pin.piece(:P, :first, :normal))
 
 # Promote pawn
-board.promote("a7")
+board.promote("a7", :Q)
 promoted = board.promoted_pieces
-puts promoted.values.first.to_s  # => "+P"
+puts promoted.values.first.to_s  # => "+Q"
 ```
 
 ### Piece Analysis
 ```ruby
-def analyze_pieces(pin_strings)
-  pieces = pin_strings.map { |pin| Sashite::Pin.parse(pin) }
+def analyze_pieces(pins)
+  pieces = pins.map { |pin| Sashite::Pin.parse(pin) }
 
   {
     total: pieces.size,
-    by_player: pieces.group_by(&:side),
+    by_side: pieces.group_by(&:side),
     by_type: pieces.group_by(&:type),
     by_state: pieces.group_by(&:state),
     promoted: pieces.count(&:enhanced?),
@@ -297,8 +365,8 @@ end
 
 pins = %w[K Q +R B N P k q r +b n -p]
 analysis = analyze_pieces(pins)
-puts analysis[:by_player][:first].size  # => 6
-puts analysis[:promoted]                # => 2
+puts analysis[:by_side][:first].size  # => 6
+puts analysis[:promoted]              # => 2
 ```
 
 ### Move Validation Example
@@ -307,17 +375,17 @@ def can_promote?(piece, target_rank)
   return false unless piece.normal?  # Already promoted pieces can't promote again
 
   case piece.type
-  when "P"  # Pawn
+  when :P  # Pawn
     (piece.first_player? && target_rank == 8) ||
     (piece.second_player? && target_rank == 1)
-  when "R", "B", "S", "N", "L"  # Shōgi pieces that can promote
+  when :R, :B, :S, :N, :L  # Shōgi pieces that can promote
     true
   else
     false
   end
 end
 
-pawn = Sashite::Pin.parse("P")
+pawn = Sashite::Pin.piece(:P, :first, :normal)
 puts can_promote?(pawn, 8)          # => true
 
 promoted_pawn = pawn.enhance
@@ -328,11 +396,15 @@ puts can_promote?(promoted_pawn, 8) # => false (already promoted)
 
 Following the [Game Protocol](https://sashite.dev/game-protocol/):
 
-| Protocol Attribute | PIN Encoding | Examples |
-|-------------------|--------------|----------|
-| **Type** | ASCII letter choice | `K`/`k` = King, `P`/`p` = Pawn |
-| **Side** | Letter case | `K` = First player, `k` = Second player |
-| **State** | Optional prefix | `+K` = Enhanced, `-K` = Diminished, `K` = Normal |
+| Protocol Attribute | PIN Encoding | Examples | Notes |
+|-------------------|--------------|----------|-------|
+| **Type** | ASCII letter choice | `K`/`k` = King, `P`/`p` = Pawn | Type is always stored as uppercase symbol (`:K`, `:P`) |
+| **Side** | Letter case in display | `K` = First player, `k` = Second player | Case is determined by side during rendering |
+| **State** | Optional prefix | `+K` = Enhanced, `-K` = Diminished, `K` = Normal | |
+
+**Type Convention**: All piece types are internally represented as uppercase symbols (`:A` to `:Z`). The display case is determined by the `side` attribute: first player pieces display as uppercase, second player pieces as lowercase.
+
+**Canonical principle**: Identical pieces must have identical PIN representations.
 
 **Note**: PIN does not represent the **Style** attribute from the Game Protocol. For style-aware piece notation, see [Piece Name Notation (PNN)](https://sashite.dev/specs/pnn/).
 
@@ -342,10 +414,41 @@ Following the [Game Protocol](https://sashite.dev/game-protocol/):
 * **Rule-Agnostic**: Independent of specific game mechanics
 * **Compact Format**: 1-2 characters per piece
 * **Visual Distinction**: Clear player differentiation through case
+* **Type Normalization**: Consistent uppercase type representation internally
 * **Protocol Compliant**: Direct implementation of Sashité piece attributes
 * **Immutable**: All piece instances are frozen and transformations return new objects
 * **Functional**: Pure functions with no side effects
 
+## Implementation Notes
+
+### Type Normalization Convention
+
+PIN follows a strict type normalization convention:
+
+1. **Internal Storage**: All piece types are stored as uppercase symbols (`:A` to `:Z`)
+2. **Input Flexibility**: Both `"K"` and `"k"` are valid input during parsing
+3. **Case Semantics**: Input case determines the `side` attribute, not the `type`
+4. **Display Logic**: Output case is computed from `side` during rendering
+
+This design ensures:
+- Consistent internal representation regardless of input format
+- Clear separation between piece identity (type) and ownership (side)
+- Predictable behavior when comparing pieces of the same type
+
+### Example Flow
+
+```ruby
+# Input: "k" (lowercase)
+# ↓ Parsing
+# type: :K (normalized to uppercase)
+# side: :second (inferred from lowercase input)
+# ↓ Display
+# letter: "k" (computed from type + side)
+# PIN: "k" (final representation)
+```
+
+This ensures that `parse(pin).to_s == pin` for all valid PIN strings while maintaining internal consistency.
+
 ## System Constraints
 
 - **Maximum 26 piece types** per game system (one per ASCII letter)

data/lib/sashite/pin/piece.rb

@@ -22,27 +22,55 @@ module Sashite
       # Valid state modifiers
       ENHANCED_PREFIX = "+"
       DIMINISHED_PREFIX = "-"
+      NORMAL_PREFIX = ""
+
+      # State constants
+      ENHANCED_STATE = :enhanced
+      DIMINISHED_STATE = :diminished
+      NORMAL_STATE = :normal
+
+      # Player side constants
+      FIRST_PLAYER = :first
+      SECOND_PLAYER = :second
+
+      # Valid types (A-Z)
+      VALID_TYPES = (:A..:Z).to_a.freeze
+
+      # Valid sides
+      VALID_SIDES = [FIRST_PLAYER, SECOND_PLAYER].freeze
+
+      # Valid states
+      VALID_STATES = [NORMAL_STATE, ENHANCED_STATE, DIMINISHED_STATE].freeze
 
       # Error messages
       ERROR_INVALID_PIN = "Invalid PIN string: %s"
-      ERROR_INVALID_LETTER = "Letter must be a single ASCII letter (a-z or A-Z): %s"
+      ERROR_INVALID_TYPE = "Type must be a symbol from :A to :Z, got: %s"
+      ERROR_INVALID_SIDE = "Side must be :first or :second, got: %s"
+      ERROR_INVALID_STATE = "State must be :normal, :enhanced, or :diminished, got: %s"
+
+      # @return [Symbol] the piece type (:A to :Z)
+      attr_reader :type
+
+      # @return [Symbol] the player side (:first or :second)
+      attr_reader :side
 
-      # @return [String] the base letter identifier (type + side)
-      attr_reader :letter
+      # @return [Symbol] the piece state (:normal, :enhanced, or :diminished)
+      attr_reader :state
 
       # Create a new piece instance
       #
-      # @param letter [String] single ASCII letter (a-z or A-Z)
-      # @param enhanced [Boolean] whether the piece has enhanced state
-      # @param diminished [Boolean] whether the piece has diminished state
+      # @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)
       # @raise [ArgumentError] if parameters are invalid
-      def initialize(letter, enhanced: false, diminished: false)
-        self.class.validate_letter(letter)
-        self.class.validate_state_combination(enhanced, diminished)
+      def initialize(type, side, state = NORMAL_STATE)
+        self.class.validate_type(type)
+        self.class.validate_side(side)
+        self.class.validate_state(state)
 
-        @letter = letter.freeze
-        @enhanced = enhanced
-        @diminished = diminished
+        @type = type
+        @side = side
+        @state = state
 
         freeze
       end
@@ -53,9 +81,9 @@ module Sashite
       # @return [Piece] new piece instance
       # @raise [ArgumentError] if the PIN string is invalid
       # @example
-      #   Pin::Piece.parse("k")     # => #<Pin::Piece letter="k">
-      #   Pin::Piece.parse("+R")    # => #<Pin::Piece letter="R" enhanced=true>
-      #   Pin::Piece.parse("-p")    # => #<Pin::Piece letter="p" diminished=true>
+      #   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>
       def self.parse(pin_string)
         string_value = String(pin_string)
         matches = match_pattern(string_value)
@@ -64,11 +92,18 @@ module Sashite
         enhanced = matches[:prefix] == ENHANCED_PREFIX
         diminished = matches[:prefix] == DIMINISHED_PREFIX
 
-        new(
-          letter,
-          enhanced:   enhanced,
-          diminished: diminished
-        )
+        # 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)
       end
 
       # Convert the piece to its PIN string representation
@@ -79,180 +114,197 @@ module Sashite
       #   piece.to_s  # => "-p"
       #   piece.to_s  # => "K"
       def to_s
-        prefix = if @enhanced
-                   ENHANCED_PREFIX
-                 else
-                   (@diminished ? DIMINISHED_PREFIX : "")
-                 end
         "#{prefix}#{letter}"
       end
 
+      # Get the letter representation
+      #
+      # @return [String] letter representation combining type and side
+      def letter
+        first_player? ? type.to_s.upcase : type.to_s.downcase
+      end
+
+      # Get the prefix representation
+      #
+      # @return [String] prefix representing the state
+      def prefix
+        case state
+        when ENHANCED_STATE then ENHANCED_PREFIX
+        when DIMINISHED_STATE then DIMINISHED_PREFIX
+        else NORMAL_PREFIX
+        end
+      end
+
       # Create a new piece with enhanced state
       #
       # @return [Piece] new piece instance with enhanced state
       # @example
-      #   piece.enhance  # k => +k
+      #   piece.enhance  # (:K, :first, :normal) => (:K, :first, :enhanced)
       def enhance
         return self if enhanced?
 
-        self.class.new(
-          letter,
-          enhanced:   true,
-          diminished: false
-        )
+        self.class.new(type, side, ENHANCED_STATE)
       end
 
       # Create a new piece without enhanced state
       #
       # @return [Piece] new piece instance without enhanced state
       # @example
-      #   piece.unenhance  # +k => k
+      #   piece.unenhance  # (:K, :first, :enhanced) => (:K, :first, :normal)
       def unenhance
         return self unless enhanced?
 
-        self.class.new(
-          letter,
-          enhanced:   false,
-          diminished: @diminished
-        )
+        self.class.new(type, side, NORMAL_STATE)
       end
 
       # Create a new piece with diminished state
       #
       # @return [Piece] new piece instance with diminished state
       # @example
-      #   piece.diminish  # k => -k
+      #   piece.diminish  # (:K, :first, :normal) => (:K, :first, :diminished)
       def diminish
         return self if diminished?
 
-        self.class.new(
-          letter,
-          enhanced:   false,
-          diminished: true
-        )
+        self.class.new(type, side, DIMINISHED_STATE)
       end
 
       # Create a new piece without diminished state
       #
       # @return [Piece] new piece instance without diminished state
       # @example
-      #   piece.undiminish  # -k => k
+      #   piece.undiminish  # (:K, :first, :diminished) => (:K, :first, :normal)
       def undiminish
         return self unless diminished?
 
-        self.class.new(
-          letter,
-          enhanced:   @enhanced,
-          diminished: false
-        )
+        self.class.new(type, side, NORMAL_STATE)
       end
 
       # Create a new piece with normal state (no modifiers)
       #
       # @return [Piece] new piece instance with normal state
       # @example
-      #   piece.normalize  # +k => k, -k => k
+      #   piece.normalize  # (:K, :first, :enhanced) => (:K, :first, :normal)
       def normalize
         return self if normal?
 
-        self.class.new(letter)
+        self.class.new(type, side, NORMAL_STATE)
       end
 
       # Create a new piece with opposite ownership (case)
       #
       # @return [Piece] new piece instance with flipped case
       # @example
-      #   piece.flip  # K => k, k => K
+      #   piece.flip  # (:K, :first, :normal) => (:K, :second, :normal)
       def flip
-        flipped_letter = letter.swapcase
+        self.class.new(type, opposite_side, state)
+      end
 
-        self.class.new(
-          flipped_letter,
-          enhanced:   @enhanced,
-          diminished: @diminished
-        )
+      # Create a new piece with a different type (keeping same side and state)
+      #
+      # @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)
+      def with_type(new_type)
+        self.class.validate_type(new_type)
+        return self if type == new_type
+
+        self.class.new(new_type, side, state)
+      end
+
+      # Create a new piece with a different side (keeping same type and state)
+      #
+      # @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)
+      def with_side(new_side)
+        self.class.validate_side(new_side)
+        return self if side == new_side
+
+        self.class.new(type, new_side, state)
+      end
+
+      # Create a new piece with a different state (keeping same type and side)
+      #
+      # @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)
+      def with_state(new_state)
+        self.class.validate_state(new_state)
+        return self if state == new_state
+
+        self.class.new(type, side, new_state)
       end
 
       # Check if the piece has enhanced state
       #
       # @return [Boolean] true if enhanced
       def enhanced?
-        @enhanced
+        state == ENHANCED_STATE
       end
 
       # Check if the piece has diminished state
       #
       # @return [Boolean] true if diminished
       def diminished?
-        @diminished
+        state == DIMINISHED_STATE
       end
 
       # Check if the piece has normal state (no modifiers)
       #
       # @return [Boolean] true if no modifiers are present
       def normal?
-        !enhanced? && !diminished?
+        state == NORMAL_STATE
       end
 
-      # Check if the piece belongs to the first player (uppercase)
+      # Check if the piece belongs to the first player
       #
-      # @return [Boolean] true if uppercase letter
+      # @return [Boolean] true if first player
       def first_player?
-        letter == letter.upcase
+        side == FIRST_PLAYER
       end
 
-      # Check if the piece belongs to the second player (lowercase)
+      # Check if the piece belongs to the second player
       #
-      # @return [Boolean] true if lowercase letter
+      # @return [Boolean] true if second player
       def second_player?
-        letter == letter.downcase
+        side == SECOND_PLAYER
       end
 
-      # Get the piece type (uppercase letter regardless of player)
-      #
-      # @return [String] uppercase letter representing the piece type
-      # @example
-      #   piece.type  # "k" => "K", "R" => "R", "+p" => "P"
-      def type
-        letter.upcase
-      end
-
-      # Get the player side based on letter case
-      #
-      # @return [Symbol] :first or :second
-      def side
-        first_player? ? :first : :second
-      end
-
-      # Get the state as a symbol
-      #
-      # @return [Symbol] :enhanced, :diminished, or :normal
-      def state
-        return :enhanced if enhanced?
-        return :diminished if diminished?
-        :normal
-      end
-
-      # Check if this piece is the same type as another (ignoring player and state)
+      # Check if this piece is the same type as another (ignoring side and state)
       #
       # @param other [Piece] piece to compare with
       # @return [Boolean] true if same type
       # @example
-      #   king1.same_type?(king2)  # K and k => true, K and Q => false
+      #   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 player as another
+      # Check if this piece belongs to the same side as another
       #
       # @param other [Piece] piece to compare with
-      # @return [Boolean] true if same player
-      def same_player?(other)
+      # @return [Boolean] true if same side
+      def same_side?(other)
         return false unless other.is_a?(self.class)
+
         side == other.side
       end
 
+      # Check if this piece has the same state as another
+      #
+      # @param other [Piece] piece to compare with
+      # @return [Boolean] true if same state
+      def same_state?(other)
+        return false unless other.is_a?(self.class)
+
+        state == other.state
+      end
+
       # Custom equality comparison
       #
       # @param other [Object] object to compare with
@@ -260,9 +312,7 @@ module Sashite
       def ==(other)
         return false unless other.is_a?(self.class)
 
-        letter == other.letter &&
-          enhanced? == other.enhanced? &&
-          diminished? == other.diminished?
+        type == other.type && side == other.side && state == other.state
       end
 
       # Alias for == to ensure Set functionality works correctly
@@ -272,29 +322,37 @@ module Sashite
       #
       # @return [Integer] hash value
       def hash
-        [self.class, @letter, @enhanced, @diminished].hash
+        [self.class, type, side, state].hash
       end
 
-      # Validate that the letter is a single ASCII letter
+      # Validate that the type is a valid symbol
       #
-      # @param letter [String] the letter to validate
+      # @param type [Symbol] the type to validate
       # @raise [ArgumentError] if invalid
-      def self.validate_letter(letter)
-        letter_str = String(letter)
-        return if letter_str.match?(/\A[a-zA-Z]\z/)
+      def self.validate_type(type)
+        return if VALID_TYPES.include?(type)
 
-        raise ::ArgumentError, format(ERROR_INVALID_LETTER, letter_str)
+        raise ::ArgumentError, format(ERROR_INVALID_TYPE, type.inspect)
       end
 
-      # Validate that enhanced and diminished states are not both true
+      # Validate that the side is a valid symbol
       #
-      # @param enhanced [Boolean] enhanced state
-      # @param diminished [Boolean] diminished state
-      # @raise [ArgumentError] if both are true
-      def self.validate_state_combination(enhanced, diminished)
-        return unless enhanced && diminished
+      # @param side [Symbol] the side to validate
+      # @raise [ArgumentError] if invalid
+      def self.validate_side(side)
+        return if VALID_SIDES.include?(side)
 
-        raise ::ArgumentError, "A piece cannot be both enhanced and diminished"
+        raise ::ArgumentError, format(ERROR_INVALID_SIDE, side.inspect)
+      end
+
+      # Validate that the state is a valid symbol
+      #
+      # @param state [Symbol] the state to validate
+      # @raise [ArgumentError] if invalid
+      def self.validate_state(state)
+        return if VALID_STATES.include?(state)
+
+        raise ::ArgumentError, format(ERROR_INVALID_STATE, state.inspect)
       end
 
       # Match PIN pattern against string
@@ -310,6 +368,15 @@ module Sashite
       end
 
       private_class_method :match_pattern
+
+      private
+
+      # Get the opposite side of the current piece
+      #
+      # @return [Symbol] :first if current side is :second, :second if current side is :first
+      def opposite_side
+        first_player? ? SECOND_PLAYER : FIRST_PLAYER
+      end
     end
   end
 end

data/lib/sashite/pin.rb

@@ -47,10 +47,26 @@ module Sashite
     # @return [Pin::Piece] new piece instance
     # @raise [ArgumentError] if the PIN string is invalid
     # @example
-    #   Sashite::Pin.parse("K")     # => #<Pin::Piece letter="K">
-    #   Sashite::Pin.parse("+R")    # => #<Pin::Piece letter="R" enhanced=true>
+    #   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>
     def self.parse(pin_string)
       Piece.parse(pin_string)
     end
+
+    # Create a new piece 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
+    # @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)
+    end
   end
 end

data/lib/sashite-pin.rb

@@ -1,20 +1,14 @@
 # frozen_string_literal: true
 
+require_relative "sashite/pin"
+
 # Sashité namespace for board game notation libraries
+#
+# Sashité provides a collection of libraries for representing and manipulating
+# board game concepts according to the Game Protocol specifications.
+#
+# @see https://sashite.dev/game-protocol/ Game Protocol Foundation
+# @see https://sashite.dev/specs/ Sashité Specifications
+# @author Sashité
 module Sashite
-  # Piece Identifier Notation (PIN) implementation for Ruby
-  #
-  # PIN provides an 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 using ASCII letters with optional
-  # state modifiers and case-based player group classification.
-  #
-  # Format: [<state>]<letter>
-  # - State modifier: "+" (enhanced), "-" (diminished), or none (normal)
-  # - Letter: A-Z (first player), a-z (second player)
-  #
-  # @see https://sashite.dev/specs/pin/1.0.0/ PIN Specification v1.0.0
-  # @author Sashité
 end
-
-require_relative "sashite/pin"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-pin
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.1
 platform: ruby
 authors:
 - Cyril Kato
@@ -15,7 +15,8 @@ description: |
   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 player group classification.
+  case-based side encoding. Perfect for game engines, board game notation systems,
+  and multi-game environments.
 email: contact@cyril.email
 executables: []
 extensions: []