sashite-pin 2.0.0 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a140d90c9c73aeb4773d2e94c0825cdddfe6ce5dff722325eb58bbea896ba62e
-  data.tar.gz: 273fbe7adfa54613f4d582feb053690724d686f2f1d966d0f6871d33e77450b3
+  metadata.gz: 70bbc211cb1dd38efa9f0c39b2d0e1b0fd09c2dcf2d7ac3773719ce11786a5ac
+  data.tar.gz: cd6831f22ee3e9fd8ce559f5535bbcbb1d9ca13ba9083a9d9c1fe66d41e2eef9
 SHA512:
-  metadata.gz: dcdd60202c06776b8243d1330c54f93d6a38d919f9d5201660287967c987c69a119c9f1884a0c8bf3f3099d14b715b3c2d656c8725b39092df352f6ea9d5a2d8
-  data.tar.gz: 4e87b25c1180e9cebcf47756cce651022d5c5b3227200010f2de408744910f20f596ee80bd34d6bf0ee597982189c92c22aed88907de30fea4c6c2455ac92072
+  metadata.gz: d0808aac8a46423256ec3546a4eb71d5882d3535b4a74929680cd31f84294ffd406716565f53ef072ff35c5c1131bb2612ab93398001d3d80772bb34a3dc3d07
+  data.tar.gz: ba7ecb1765c03c801f014bdbb9792fcae5dacd8d119890b0c73f0e550a345a8fc307cb39a82b803c986ef7fa50f76ad5fff39c6a7bffc5fe39e1b06bebe6b809

data/README.md

@@ -204,15 +204,32 @@ crossed_soldier.to_s                              # => "+P"
 #### 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::Piece.valid?(pin_string)` - Validate PIN string (class 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
@@ -242,10 +259,34 @@ crossed_soldier.to_s                              # => "+P"
 - `#==(other)` - Full equality comparison
 
 ### Constants
-- `Sashite::Pin::PIN_REGEX` - Regular expression for PIN validation
+- `Sashite::Pin::Piece::PIN_PATTERN` - Regular expression for PIN validation (internal use)
 
 ## 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 +397,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 +415,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

@@ -106,6 +106,23 @@ module Sashite
         new(piece_type, piece_side, piece_state)
       end
 
+      # 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::Piece.valid?("K")    # => true
+      #   Sashite::Pin::Piece.valid?("+R")   # => true
+      #   Sashite::Pin::Piece.valid?("-p")   # => true
+      #   Sashite::Pin::Piece.valid?("KK")   # => false
+      #   Sashite::Pin::Piece.valid?("++K")  # => false
+      def self.valid?(pin_string)
+        return false unless pin_string.is_a?(::String)
+
+        pin_string.match?(PIN_PATTERN)
+      end
+
       # Convert the piece to its PIN string representation
       #
       # @return [String] PIN notation string
@@ -190,14 +207,13 @@ module Sashite
         self.class.new(type, side, NORMAL_STATE)
       end
 
-      # Create a new piece with opposite ownership (case)
+      # Create a new piece with opposite side
       #
-      # @return [Piece] new piece instance with flipped case
+      # @return [Piece] new piece instance with opposite side
       # @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 +385,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

@@ -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,10 +31,8 @@ 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)
+      Piece.valid?(pin_string)
     end
 
     # Parse a PIN string into a Piece object

metadata

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