sashite-pin 3.1.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e469a5469a29de49338f5066b5b5743860459709ab2e771209d1c55ab7e7ff0d
-  data.tar.gz: 680f65379ee7ea0ead2238ed646a29ee54d673a80de7f0c54f1c56a11cf8f98f
+  metadata.gz: 629bf8b689b39a81e6b52ca9b1386f53c6c807f5f57ae608fb99449ceb08854e
+  data.tar.gz: '0883b5de633e958ddbf72908ffd49832e999e0a1f99b615ce8aa5fa1222cd4f5'
 SHA512:
-  metadata.gz: 1a4b4ce38433cdf1cd9a26baaba13fa8e48ff21676976287422ac917d3a41bc67e7eb688bf347a94cefb294542e98fa7d2bd292f923b7a8c6b66d73edfaebdd2
-  data.tar.gz: 5da68a02154b85ab6a9b1070954f14be0a4f79e11e07c54448c0aae40772e4664c2b3368067a44c8fdef5a43b122a3c868e2cc8c6df5ed52f46afa2a2b65f021
+  metadata.gz: a64ac32e1afb6b84c388823f81022efe6eda1a469ce82920b4d8119f0e747e4f5a8788c92d397a48165b36fcfda45111df785dad8523f3e861e31acb55e6fd68
+  data.tar.gz: 99a1e0e87304f2b1f525483cf952a4a0d9fdf0768297010894e6d429f4431b7c5476f287f94e3e85dd9c4c46669546ed094c2afc0fdd6296c9bccebcd8aa255b

data/README.md

@@ -1,17 +1,17 @@
-# Pin.rb
+# Sashite::Pin
 
 [![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.
+> **PIN** (Piece Identifier Notation) implementation for Ruby.
 
 ## 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 identifier objects and functional programming principles.
+This gem implements the [PIN Specification v1.0.0](https://sashite.dev/specs/pin/1.0.0/).
 
 ## Installation
 
@@ -31,62 +31,74 @@ gem install sashite-pin
 ```ruby
 require "sashite/pin"
 
-# 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
+# Parse PIN strings
+pin = Sashite::Pin.parse("K")
+pin.type      # => :K
+pin.side      # => :first
+pin.state     # => :normal
+pin.terminal  # => false
+
+pin.to_s  # => "K"
+
+# Parse with different attributes
+king = Sashite::Pin.parse("K^")      # Terminal king
+rook = Sashite::Pin.parse("+R")      # Enhanced rook
+pawn = Sashite::Pin.parse("-p")      # Diminished second player pawn
 
 # 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>
+pin = Sashite::Pin.new(:K, :first)
+pin = Sashite::Pin.new(:R, :second, :enhanced)
+pin = Sashite::Pin.new(:K, :first, :normal, terminal: true)
+
+# Validation
+Sashite::Pin.valid?("K")        # => true
+Sashite::Pin.valid?("+R")       # => true
+Sashite::Pin.valid?("K^")       # => true
+Sashite::Pin.valid?("invalid")  # => false
+
+# State transformations (return new instances)
+enhanced = pin.enhance
+enhanced.to_s  # => "+K"
+
+diminished = pin.diminish
+diminished.to_s  # => "-K"
 
-# Validate PIN strings
-Sashite::Pin.valid?("K")                 # => true
-Sashite::Pin.valid?("+R")                # => true
-Sashite::Pin.valid?("invalid")           # => false
+normalized = enhanced.normalize
+normalized.to_s  # => "K"
 
-# State manipulation (returns new immutable instances)
-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 transformation
+flipped = pin.flip
+flipped.to_s  # => "k"
 
-# Side manipulation
-flipped = identifier.flip                     # => #<Pin::Identifier type=:K side=:second state=:normal>
-flipped.to_s                                  # => "k"
+# Terminal transformations
+terminal = pin.mark_terminal
+terminal.to_s  # => "K^"
 
-# Type manipulation
-queen = identifier.with_type(:Q)              # => #<Pin::Identifier type=:Q side=:first state=:normal>
-queen.to_s                                    # => "Q"
+non_terminal = terminal.unmark_terminal
+non_terminal.to_s  # => "K"
+
+# Type transformation
+queen = pin.with_type(:Q)
+queen.to_s  # => "Q"
 
 # State queries
-identifier.normal?                            # => true
-enhanced.enhanced?                            # => true
-diminished.diminished?                        # => true
+pin.normal?     # => true
+enhanced.enhanced?    # => true
+diminished.diminished?  # => true
 
 # Side queries
-identifier.first_player?                      # => true
-flipped.second_player?                        # => true
+pin.first_player?   # => true
+flipped.second_player?  # => true
 
-# Attribute access
-identifier.letter                             # => "K"
-enhanced.prefix                               # => "+"
-identifier.prefix                             # => ""
+# Terminal queries
+terminal.terminal?  # => true
 
-# Type and side comparison
+# 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)
 
-# Functional transformations can be chained
-pawn = Sashite::Pin.parse("P")
-enemy_promoted = pawn.flip.enhance            # => "+p" (second player promoted pawn)
+king1.same_type?(king2)  # => true
+king1.same_side?(king2)  # => false
 ```
 
 ## Format Specification
@@ -94,348 +106,130 @@ enemy_promoted = pawn.flip.enhance            # => "+p" (second player promoted
 ### Structure
 
 ```
-[<state>]<letter>
+[<state-modifier>]<letter>[<terminal-marker>]
 ```
 
 ### 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
+| Component | Values | Description |
+|-----------|--------|-------------|
+| Letter | `A-Z`, `a-z` | Piece type and side |
+| State Modifier | `+`, `-`, (none) | Enhanced, diminished, or normal |
+| Terminal Marker | `^`, (none) | Terminal piece or not |
 
-### Regular Expression
+### Side Convention
 
-```ruby
-/\A[-+]?[A-Za-z]\z/
-```
+- **Uppercase** (`A-Z`): First player
+- **Lowercase** (`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)
+| PIN | Side | State | Terminal | Description |
+|-----|------|-------|----------|-------------|
+| `K` | First | Normal | No | Standard king |
+| `K^` | First | Normal | Yes | Terminal king |
+| `+R` | First | Enhanced | No | Promoted rook |
+| `-p` | Second | Diminished | No | Weakened pawn |
+| `+K^` | First | Enhanced | Yes | Enhanced terminal king |
 
 ## 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 Identifier object
-* `Sashite::Pin.identifier(type, side, state = :normal)` - Create identifier instance directly
-
-### Identifier Class
-
-#### Creation and Parsing
-
-* `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 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:
+### Parsing and Validation
 
 ```ruby
-# Both create the same internal type representation
-identifier1 = Sashite::Pin.parse("K")  # type: :K, side: :first
-identifier2 = Sashite::Pin.parse("k")  # type: :K, side: :second
-
-identifier1.type    # => :K (uppercase symbol)
-identifier2.type    # => :K (same uppercase symbol)
-
-identifier1.letter  # => "K" (uppercase display)
-identifier2.letter  # => "k" (lowercase display)
+Sashite::Pin.parse(pin_string)  # => Sashite::Pin | raises ArgumentError
+Sashite::Pin.valid?(pin_string) # => boolean
 ```
 
-#### State Queries
-
-* `#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 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)
-
-#### Attribute Transformations (immutable - return new instances)
-
-* `#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
-
-### Constants
-
-* `Sashite::Pin::Identifier::PIN_PATTERN` - Regular expression for PIN validation (internal use)
-
-## Advanced Usage
-
-### Type Normalization Examples
+### Creation
 
 ```ruby
-# Parsing different cases results in same type
-white_king = Sashite::Pin.parse("K")
-black_king = Sashite::Pin.parse("k")
+Sashite::Pin.new(type, side)
+Sashite::Pin.new(type, side, state)
+Sashite::Pin.new(type, side, state, terminal: boolean)
+```
 
-# Types are normalized to uppercase
-white_king.type  # => :K
-black_king.type  # => :K (same type!)
+### Conversion
 
-# Sides are different
-white_king.side  # => :first
-black_king.side  # => :second
+```ruby
+pin.to_s    # => String
+pin.letter  # => String (case determined by side)
+pin.prefix  # => String ("+" | "-" | "")
+pin.suffix  # => String ("^" | "")
+```
 
-# Display follows side convention
-white_king.letter # => "K"
-black_king.letter # => "k"
+### Transformations
 
-# Same type, different sides
-white_king.same_type?(black_king)  # => true
-white_king.same_side?(black_king)  # => false
-```
+All transformations return new `Sashite::Pin` instances:
 
-### Immutable Transformations
 ```ruby
-# All transformations return new instances
-original = Sashite::Pin.piece(:K, :first, :normal)
-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.with_type(:Q)
-puts result.to_s      # => "+q"
+# State
+pin.enhance     # => Sashite::Pin with :enhanced state
+pin.diminish    # => Sashite::Pin with :diminished state
+pin.normalize   # => Sashite::Pin with :normal state
+
+# Side
+pin.flip        # => Sashite::Pin with opposite side
+
+# Terminal
+pin.mark_terminal    # => Sashite::Pin with terminal: true
+pin.unmark_terminal  # => Sashite::Pin with terminal: false
+
+# Attribute changes
+pin.with_type(new_type)       # => Sashite::Pin with different type
+pin.with_side(new_side)       # => Sashite::Pin with different side
+pin.with_state(new_state)     # => Sashite::Pin with different state
+pin.with_terminal(boolean)    # => Sashite::Pin with specified terminal status
 ```
 
-### Game State Management
-```ruby
-class GameBoard
-  def initialize
-    @pieces = {}
-  end
-
-  def place(square, piece)
-    @pieces[square] = piece
-  end
-
-  def promote(square, new_type = :Q)
-    piece = @pieces[square]
-    return nil unless piece&.normal?  # Can only promote normal pieces
-
-    @pieces[square] = piece.with_type(new_type).enhance
-  end
-
-  def capture(from_square, to_square)
-    captured = @pieces[to_square]
-    @pieces[to_square] = @pieces.delete(from_square)
-    captured
-  end
-
-  def pieces_by_side(side)
-    @pieces.select { |_, piece| piece.side == side }
-  end
-
-  def promoted_pieces
-    @pieces.select { |_, piece| piece.enhanced? }
-  end
-end
-
-# Usage
-board = GameBoard.new
-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", :Q)
-promoted = board.promoted_pieces
-puts promoted.values.first.to_s  # => "+Q"
-```
+### Queries
 
-### Piece Analysis
 ```ruby
-def analyze_pieces(pins)
-  pieces = pins.map { |pin| Sashite::Pin.parse(pin) }
-
-  {
-    total: pieces.size,
-    by_side: 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_side][:first].size  # => 6
-puts analysis[:promoted]              # => 2
+# State
+pin.normal?
+pin.enhanced?
+pin.diminished?
+
+# Side
+pin.first_player?
+pin.second_player?
+
+# Terminal
+pin.terminal?
+
+# Comparison
+pin.same_type?(other)
+pin.same_side?(other)
+pin.same_state?(other)
+pin.same_terminal?(other)
 ```
 
-### Move Validation Example
+## Data Structure
+
 ```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.piece(:P, :first, :normal)
-puts can_promote?(pawn, 8)          # => true
-
-promoted_pawn = pawn.enhance
-puts can_promote?(promoted_pawn, 8) # => false (already promoted)
+Sashite::Pin
+  #type     => :A..:Z           # Piece type (always uppercase symbol)
+  #side     => :first | :second # Player side
+  #state    => :normal | :enhanced | :diminished
+  #terminal => true | false
 ```
 
 ## Protocol Mapping
 
 Following the [Game Protocol](https://sashite.dev/game-protocol/):
 
-| 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/).
-
-## 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
-* **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)
-- **Exactly 2 players** (uppercase/lowercase distinction)
-- **3 state levels** (enhanced, normal, diminished)
+| Protocol Attribute | PIN Encoding |
+|-------------------|--------------|
+| Piece Name | ASCII letter choice |
+| Piece Side | Letter case |
+| Piece State | Optional prefix (`+`/`-`) |
+| Terminal Status | Optional suffix (`^`) |
 
 ## 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
+- [Game Protocol](https://sashite.dev/game-protocol/) — Conceptual foundation
+- [PNN](https://sashite.dev/specs/pnn/) — Piece Name Notation
+- [PIN Specification](https://sashite.dev/specs/pin/1.0.0/) — Official specification
 
 ## License