sashite-pin 2.0.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a140d90c9c73aeb4773d2e94c0825cdddfe6ce5dff722325eb58bbea896ba62e
-  data.tar.gz: 273fbe7adfa54613f4d582feb053690724d686f2f1d966d0f6871d33e77450b3
+  metadata.gz: 0335d119541a7fa271689c6235a9c785a4c46f6c70e9577d4cddcc597d520dd5
+  data.tar.gz: 7d95e04c803457156561bfe0fd8e270db5df1929b58721b9ed8266646f60e7e1
 SHA512:
-  metadata.gz: dcdd60202c06776b8243d1330c54f93d6a38d919f9d5201660287967c987c69a119c9f1884a0c8bf3f3099d14b715b3c2d656c8725b39092df352f6ea9d5a2d8
-  data.tar.gz: 4e87b25c1180e9cebcf47756cce651022d5c5b3227200010f2de408744910f20f596ee80bd34d6bf0ee597982189c92c22aed88907de30fea4c6c2455ac92072
+  metadata.gz: 6904c80bee041595400f4074ed48a975ad6337c3c5a8c66f9d18ad7864f19e23d04e34b30c725d37ce9c4bfde58667328a82bbd1c38208c123cb44a9da00b283
+  data.tar.gz: 32289d6453d81ff2e1920aeb7d69eedfac6bc61f9acdd1929e7ca4bc09c6988bb2a64bc3620130cfb63024977e0508b7c5ffce695590382eac3420d85454c67a

data/README.md

@@ -206,13 +206,29 @@ crossed_soldier.to_s                              # => "+P"
 - `Sashite::Pin::Piece.parse(pin_string)` - Parse PIN string (same as module method)
 
 #### Attribute Access
-- `#type` - Get piece type (symbol :A to :Z)
+- `#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)
+- `#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
+
+**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
@@ -246,6 +262,30 @@ 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
@@ -356,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** | Symbol choice | `:K`/`:k` = King, `:P`/`:p` = Pawn |
-| **Side** | Symbol value | `:first` = First player, `:second` = Second player |
-| **State** | Symbol value | `:enhanced` = Enhanced, `:diminished` = Diminished, `:normal` = 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/).
 
@@ -370,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

@@ -196,8 +196,7 @@ module Sashite
       # @example
       #   piece.flip  # (:K, :first, :normal) => (:K, :second, :normal)
       def flip
-        new_side = first_player? ? SECOND_PLAYER : FIRST_PLAYER
-        self.class.new(type, new_side, state)
+        self.class.new(type, opposite_side, state)
       end
 
       # Create a new piece with a different type (keeping same side and state)
@@ -369,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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-pin
 version: !ruby/object:Gem::Version
-  version: 2.0.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: []