sashite-pin 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a65bc46335f587c689efc712bc26efc23c236ecf4aeaf26ab6fe2a47fc6420a6
+  data.tar.gz: 5c1cde47d08f270ab0594917001b0427792d5b931a7de60327e59fc6764f53d8
+SHA512:
+  metadata.gz: 0c115d775f83ad50597f66478139720d9b6d1dfe970384d615ea1c25e96427b803dde10581a4349de1c0707064974d6f138ede38de175ed7168c5982482be9ea
+  data.tar.gz: ed8959e794d0d62ec73697b95a0ed18b19e150f9493e0db57d78c17d7bce1b122723847ef92470f528606eedec10900f3fce32a75360732e628b156da771f0ad

data/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2025 Cyril Kato
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,403 @@
+# Pin.rb
+
+[![Version](https://img.shields.io/github/v/tag/sashite/pin.rb?label=Version&logo=github)](https://github.com/sashite/pin.rb/tags)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/pin.rb/main)
+![Ruby](https://github.com/sashite/pin.rb/actions/workflows/main.yml/badge.svg?branch=main)
+[![License](https://img.shields.io/github/license/sashite/pin.rb?label=License&logo=github)](https://github.com/sashite/pin.rb/raw/main/LICENSE.md)
+
+> **PIN** (Piece Identifier Notation) implementation for the Ruby language.
+
+## What is PIN?
+
+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.
+
+## Installation
+
+```ruby
+# In your Gemfile
+gem "sashite-pin"
+```
+
+Or install manually:
+
+```sh
+gem install sashite-pin
+```
+
+## Usage
+
+```ruby
+require "sashite-pin"
+
+# Parse PIN strings into piece objects
+piece = Sashite::Pin.parse("K")          # => #<Pin::Piece letter="K" type="K" player=first>
+piece.to_s                               # => "K"
+piece.first_player?                      # => true
+piece.type                               # => "K"
+piece.side                               # => :first
+
+# Validate PIN strings
+Sashite::Pin.valid?("K")                 # => true
+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.to_s                           # => "+K"
+diminished = piece.diminish              # => #<Pin::Piece letter="K" type="K" player=first diminished=true>
+diminished.to_s                         # => "-K"
+
+# Player manipulation
+flipped = piece.flip                     # => #<Pin::Piece letter="k" type="K" player=second>
+flipped.to_s                            # => "k"
+
+# State queries
+piece.normal?                           # => true
+enhanced.enhanced?                      # => true
+diminished.diminished?                  # => true
+
+# Type and player 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_type?(queen)                 # => false (different types)
+
+# Functional transformations can be chained
+pawn = Sashite::Pin.parse("P")
+enemy_promoted = pawn.flip.enhance      # => "+p" (black promoted pawn)
+```
+
+## Format Specification
+
+### Structure
+```
+[<state>]<letter>
+```
+
+### Components
+
+- **Letter** (`A-Z`, `a-z`): Represents piece type and player
+  - 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/
+```
+
+### 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)
+
+## Game Examples
+
+### Western Chess
+```ruby
+# Standard pieces
+king = Sashite::Pin.parse("K")        # => 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.parse("P").diminish  # => 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
+```
+
+### Japanese Chess (Shōgi)
+```ruby
+# Basic pieces
+rook = Sashite::Pin.parse("R")        # => white rook
+bishop = Sashite::Pin.parse("B")      # => 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.parse("P")
+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) }
+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)
+
+# Promoted pawns
+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) }
+```
+
+### 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"
+
+# Soldiers that crossed the river
+soldier = Sashite::Pin.parse("P")
+crossed_soldier = soldier.enhance     # => soldier with enhanced movement
+crossed_soldier.to_s                 # => "+P"
+```
+
+## 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
+
+### Piece Class
+
+#### Creation and Parsing
+- `Sashite::Pin::Piece.new(letter, enhanced: false, diminished: false)` - Create piece instance
+- `Sashite::Pin::Piece.parse(pin_string)` - Parse PIN string (same as module method)
+
+#### String Representation
+- `#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`)
+
+#### State Queries
+- `#normal?` - Check if normal state (no modifiers)
+- `#enhanced?` - Check if enhanced state
+- `#diminished?` - Check if diminished state
+
+#### Player Queries
+- `#first_player?` - Check if first player piece
+- `#second_player?` - Check if second player piece
+
+#### 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 case)
+
+#### Comparison Methods
+- `#same_type?(other)` - Check if same piece type
+- `#same_player?(other)` - Check if same player
+- `#==(other)` - Full equality comparison
+
+### Constants
+- `Sashite::Pin::PIN_REGEX` - Regular expression for PIN validation
+
+## Advanced Usage
+
+### Immutable Transformations
+```ruby
+# All transformations return new instances
+original = Sashite::Pin.parse("K")
+enhanced = original.enhance
+diminished = original.diminish
+
+# Original piece is never modified
+puts original.to_s    # => "K"
+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"
+```
+
+### Game State Management
+```ruby
+class GameBoard
+  def initialize
+    @pieces = {}
+  end
+
+  def place(square, pin_string)
+    @pieces[square] = Sashite::Pin.parse(pin_string)
+  end
+
+  def promote(square)
+    piece = @pieces[square]
+    return nil unless piece&.normal?  # Can only promote normal pieces
+
+    @pieces[square] = piece.enhance
+  end
+
+  def capture(from_square, to_square)
+    captured = @pieces[to_square]
+    @pieces[to_square] = @pieces.delete(from_square)
+    captured
+  end
+
+  def pieces_by_player(first_player: true)
+    @pieces.select { |_, piece| piece.first_player? == first_player }
+  end
+
+  def promoted_pieces
+    @pieces.select { |_, piece| piece.enhanced? }
+  end
+end
+
+# Usage
+board = GameBoard.new
+board.place("e1", "K")
+board.place("e8", "k")
+board.place("a7", "P")
+
+# Promote pawn
+board.promote("a7")
+promoted = board.promoted_pieces
+puts promoted.values.first.to_s  # => "+P"
+```
+
+### Piece Analysis
+```ruby
+def analyze_pieces(pin_strings)
+  pieces = pin_strings.map { |pin| Sashite::Pin.parse(pin) }
+
+  {
+    total: pieces.size,
+    by_player: pieces.group_by(&:side),
+    by_type: pieces.group_by(&:type),
+    by_state: pieces.group_by(&:state),
+    promoted: pieces.count(&:enhanced?),
+    weakened: pieces.count(&:diminished?)
+  }
+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
+```
+
+### Move Validation Example
+```ruby
+def can_promote?(piece, target_rank)
+  return false unless piece.normal?  # Already promoted pieces can't promote again
+
+  case piece.type
+  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
+    true
+  else
+    false
+  end
+end
+
+pawn = Sashite::Pin.parse("P")
+puts can_promote?(pawn, 8)     # => true
+
+promoted_pawn = pawn.enhance
+puts can_promote?(promoted_pawn, 8)  # => false (already promoted)
+```
+
+## Protocol Mapping
+
+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 |
+
+**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/).
+
+## Properties
+
+* **ASCII Compatible**: Maximum portability across systems
+* **Rule-Agnostic**: Independent of specific game mechanics
+* **Compact Format**: 1-2 characters per piece
+* **Visual Distinction**: Clear player differentiation through case
+* **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
+
+## System Constraints
+
+- **Maximum 26 piece types** per game system (one per ASCII letter)
+- **Exactly 2 players** (uppercase/lowercase distinction)
+- **3 state levels** (enhanced, normal, diminished)
+
+## Related Specifications
+
+- [Game Protocol](https://sashite.dev/game-protocol/) - Conceptual foundation for abstract strategy board games
+- [PNN](https://sashite.dev/specs/pnn/) - Piece Name Notation (style-aware piece representation)
+- [CELL](https://sashite.dev/specs/cell/) - Board position coordinates
+- [HAND](https://sashite.dev/specs/hand/) - Reserve location notation
+- [PMN](https://sashite.dev/specs/pmn/) - Portable Move Notation
+
+## Documentation
+
+- [Official PIN Specification v1.0.0](https://sashite.dev/specs/pin/1.0.0/)
+- [PIN Examples Documentation](https://sashite.dev/specs/pin/1.0.0/examples/)
+- [Game Protocol Foundation](https://sashite.dev/game-protocol/)
+- [API Documentation](https://rubydoc.info/github/sashite/pin.rb/main)
+
+## Development
+
+```sh
+# Clone the repository
+git clone https://github.com/sashite/pin.rb.git
+cd pin.rb
+
+# Install dependencies
+bundle install
+
+# Run tests
+ruby test.rb
+
+# Generate documentation
+yard doc
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/new-feature`)
+3. Add tests for your changes
+4. Ensure all tests pass (`ruby test.rb`)
+5. Commit your changes (`git commit -am 'Add new feature'`)
+6. Push to the branch (`git push origin feature/new-feature`)
+7. Create a Pull Request
+
+## License
+
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
+
+## About
+
+Maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of board game cultures.

data/lib/sashite/pin/piece.rb

@@ -0,0 +1,329 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Pin
+    # Represents a piece in PIN (Piece Identifier Notation) format.
+    #
+    # A piece consists of a single ASCII letter with optional state modifiers:
+    # - Enhanced state: prefix '+'
+    # - Diminished state: prefix '-'
+    # - Normal state: no modifier
+    #
+    # The case of the letter determines ownership:
+    # - Uppercase (A-Z): first player
+    # - Lowercase (a-z): second player
+    #
+    # 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
+      # PIN validation pattern matching the specification
+      PIN_PATTERN = /\A(?<prefix>[-+])?(?<letter>[a-zA-Z])\z/
+
+      # Valid state modifiers
+      ENHANCED_PREFIX = "+"
+      DIMINISHED_PREFIX = "-"
+
+      # 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"
+
+      # @return [String] the base letter identifier (type + side)
+      attr_reader :letter
+
+      # 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
+      # @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)
+
+        @letter = letter.freeze
+        @enhanced = enhanced
+        @diminished = diminished
+
+        freeze
+      end
+
+      # Parse a PIN string into a Piece object
+      #
+      # @param pin_string [String] PIN notation string
+      # @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>
+      def self.parse(pin_string)
+        string_value = String(pin_string)
+        matches = match_pattern(string_value)
+
+        letter = matches[:letter]
+        enhanced = matches[:prefix] == ENHANCED_PREFIX
+        diminished = matches[:prefix] == DIMINISHED_PREFIX
+
+        new(
+          letter,
+          enhanced:   enhanced,
+          diminished: diminished
+        )
+      end
+
+      # Convert the piece to its PIN string representation
+      #
+      # @return [String] PIN notation string
+      # @example
+      #   piece.to_s  # => "+R"
+      #   piece.to_s  # => "-p"
+      #   piece.to_s  # => "K"
+      def to_s
+        prefix = if @enhanced
+                   ENHANCED_PREFIX
+                 else
+                   (@diminished ? DIMINISHED_PREFIX : "")
+                 end
+
+        "#{prefix}#{letter}"
+      end
+
+      # Create a new piece with enhanced state
+      #
+      # @return [Piece] new piece instance with enhanced state
+      # @example
+      #   piece.enhance  # k => +k
+      def enhance
+        return self if enhanced?
+
+        self.class.new(
+          letter,
+          enhanced:   true,
+          diminished: false
+        )
+      end
+
+      # Create a new piece without enhanced state
+      #
+      # @return [Piece] new piece instance without enhanced state
+      # @example
+      #   piece.unenhance  # +k => k
+      def unenhance
+        return self unless enhanced?
+
+        self.class.new(
+          letter,
+          enhanced:   false,
+          diminished: @diminished
+        )
+      end
+
+      # Create a new piece with diminished state
+      #
+      # @return [Piece] new piece instance with diminished state
+      # @example
+      #   piece.diminish  # k => -k
+      def diminish
+        return self if diminished?
+
+        self.class.new(
+          letter,
+          enhanced:   false,
+          diminished: true
+        )
+      end
+
+      # Create a new piece without diminished state
+      #
+      # @return [Piece] new piece instance without diminished state
+      # @example
+      #   piece.undiminish  # -k => k
+      def undiminish
+        return self unless diminished?
+
+        self.class.new(
+          letter,
+          enhanced:   @enhanced,
+          diminished: false
+        )
+      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
+      def normalize
+        return self if normal?
+
+        self.class.new(letter)
+      end
+
+      # Create a new piece with opposite ownership (case)
+      #
+      # @return [Piece] new piece instance with flipped case
+      # @example
+      #   piece.flip  # K => k, k => K
+      def flip
+        flipped_letter = letter.swapcase
+
+        self.class.new(
+          flipped_letter,
+          enhanced:   @enhanced,
+          diminished: @diminished
+        )
+      end
+
+      # Check if the piece has enhanced state
+      #
+      # @return [Boolean] true if enhanced
+      def enhanced?
+        @enhanced
+      end
+
+      # Check if the piece has diminished state
+      #
+      # @return [Boolean] true if diminished
+      def diminished?
+        @diminished
+      end
+
+      # Check if the piece has normal state (no modifiers)
+      #
+      # @return [Boolean] true if no modifiers are present
+      def normal?
+        !enhanced? && !diminished?
+      end
+
+      # Check if the piece belongs to the first player (uppercase)
+      #
+      # @return [Boolean] true if uppercase letter
+      def first_player?
+        letter == letter.upcase
+      end
+
+      # Check if the piece belongs to the second player (lowercase)
+      #
+      # @return [Boolean] true if lowercase letter
+      def second_player?
+        letter == letter.downcase
+      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)
+      #
+      # @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
+      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
+      #
+      # @param other [Piece] piece to compare with
+      # @return [Boolean] true if same player
+      def same_player?(other)
+        return false unless other.is_a?(self.class)
+
+        side == other.side
+      end
+
+      # Custom equality comparison
+      #
+      # @param other [Object] object to compare with
+      # @return [Boolean] true if pieces are equal
+      def ==(other)
+        return false unless other.is_a?(self.class)
+
+        letter == other.letter &&
+          enhanced? == other.enhanced? &&
+          diminished? == other.diminished?
+      end
+
+      # Custom hash implementation for use in collections
+      #
+      # @return [Integer] hash value
+      def hash
+        [letter, @enhanced, @diminished].hash
+      end
+
+      # Custom inspection for debugging
+      #
+      # @return [String] detailed string representation
+      def inspect
+        modifiers = []
+        modifiers << "enhanced=true" if enhanced?
+        modifiers << "diminished=true" if diminished?
+
+        modifier_str = modifiers.empty? ? "" : " #{modifiers.join(' ')}"
+        player = first_player? ? "first" : "second"
+        "#<#{self.class.name}:0x#{object_id.to_s(16)} letter='#{letter}' type='#{type}' player=#{player}#{modifier_str}>"
+      end
+
+      # Validate that the letter is a single ASCII letter
+      #
+      # @param letter [String] the letter 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/)
+
+        raise ::ArgumentError, format(ERROR_INVALID_LETTER, letter_str)
+      end
+
+      # Validate that enhanced and diminished states are not both true
+      #
+      # @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
+
+        raise ::ArgumentError, "A piece cannot be both enhanced and diminished"
+      end
+
+      # Match PIN pattern against string
+      #
+      # @param string [String] string to match
+      # @return [MatchData] match data
+      # @raise [ArgumentError] if string doesn't match
+      def self.match_pattern(string)
+        matches = PIN_PATTERN.match(string)
+        return matches if matches
+
+        raise ::ArgumentError, format(ERROR_INVALID_PIN, string)
+      end
+
+      private_class_method :match_pattern
+    end
+  end
+end

data/lib/sashite/pin.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "pin/piece"
+
+module Sashite
+  # PIN (Piece Identifier Notation) implementation for Ruby
+  #
+  # Provides 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.
+  #
+  # Format: [<state>]<letter>
+  # - State modifier: "+" (enhanced), "-" (diminished), or none (normal)
+  # - Letter: A-Z (first player), a-z (second player)
+  #
+  # 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)
+  #
+  # 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
+    # @return [Boolean] true if valid PIN, false otherwise
+    #
+    # @example
+    #   Sashite::Pin.valid?("K")    # => true
+    #   Sashite::Pin.valid?("+R")   # => true
+    #   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)
+    end
+
+    # Parse a PIN string into a Piece object
+    #
+    # @param pin_string [String] PIN notation string
+    # @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>
+    def self.parse(pin_string)
+      Piece.parse(pin_string)
+    end
+  end
+end

data/lib/sashite-pin.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Sashité namespace for board game notation libraries
+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

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: sashite-pin
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Cyril Kato
+bindir: bin
+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
+  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 player group classification.
+email: contact@cyril.email
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- lib/sashite-pin.rb
+- lib/sashite/pin.rb
+- lib/sashite/pin/piece.rb
+homepage: https://github.com/sashite/pin.rb
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/sashite/pin.rb/issues
+  documentation_uri: https://rubydoc.info/github/sashite/pin.rb/main
+  homepage_uri: https://github.com/sashite/pin.rb
+  source_code_uri: https://github.com/sashite/pin.rb
+  specification_uri: https://sashite.dev/specs/pin/1.0.0/
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: PIN (Piece Identifier Notation) implementation for Ruby with immutable piece
+  objects
+test_files: []