pnn 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b48e598bec9d6aeb11a7212428d279f153bbfd00ae6f1a7dc3d0485f4985695c
-  data.tar.gz: d7d8c7da11021a1056e048ab17605bd5db9abdc4cbbdafc90bd00820e651fedc
+  metadata.gz: '0584c1ee7a42c3f556efe5e27e106c07b7e12c37148ba345238ef9fb02622c76'
+  data.tar.gz: b31fcbfb3442f0b130662a0cbd7e644c127b3c8a9247f3380f85056aa0be6ea1
 SHA512:
-  metadata.gz: 3957d2e98391d216817a37cf4c9ebc479172c1aeb3415ecc19c1e8abb2d9b29298277312c5b187cdbf1ede2a6f30414bf11b5b05a35ef324abf6a314fc5e7108
-  data.tar.gz: 10665b2f56ae9869dc68db08066dd2e1520691bc4e649ae48cf22643100427d0d0af9981708e3427aab0b8c0894feef37feda79a8c73bd036c020eb423052730
+  metadata.gz: 53b6236d8342e095d69a9779ec01b1f87fc992b2927ae29689930cb5dac3d9a36fcf7efce7004c468cf4d4221e59b563167d637d8d24e7afdf3c5501d88818d3
+  data.tar.gz: 2f3832ea59e253bf8e5abd69dfaa39413c272e118756906d86fc89f91774b77d57b8bc991d2e4288b44b817df83039e740b928b1bcec7d4ac5499db12bf7b380

data/README.md

@@ -11,10 +11,7 @@
 
 PNN (Piece Name Notation) is a consistent and rule-agnostic format for representing pieces in abstract strategy board games. It defines a standardized way to identify and represent pieces independent of any specific game rules or mechanics.
 
-This gem implements the [PNN Specification v1.0.0](https://sashite.dev/documents/pnn/1.0.0/), providing a Ruby interface for:
-- Serializing piece identifiers to PNN strings
-- Parsing PNN strings into their component parts
-- Validating PNN strings according to the specification
+This gem implements the [PNN Specification v1.0.0](https://sashite.dev/documents/pnn/1.0.0/), providing a Ruby interface for working with piece representations through an intuitive object-oriented API.
 
 ## Installation
 
@@ -39,163 +36,305 @@ A PNN record consists of a single ASCII letter that represents a piece, with opt
 
 Where:
 - `<letter>` is a single ASCII letter (`a-z` or `A-Z`), with uppercase representing the first player's pieces and lowercase representing the second player's pieces
-- `<prefix>` is an optional modifier preceding the letter (`+` or `-`)
-- `<suffix>` is an optional modifier following the letter (`'`)
+- `<prefix>` is an optional modifier preceding the letter (`+` for Enhanced or `-` for Diminished state)
+- `<suffix>` is an optional modifier following the letter (`'` for Intermediate state)
 
 ## Basic Usage
 
-### Parsing PNN Strings
+### Creating Piece Objects
 
-Convert a PNN string into a structured Ruby hash:
+The primary interface is the `Pnn::Piece` class, which represents a single piece in PNN format:
 
 ```ruby
 require "pnn"
 
-# Basic letter
-result = Pnn.parse("k")
-# => { letter: "k" }
+# Parse a PNN string into a piece object
+piece = Pnn::Piece.parse("k")
+# => #<Pnn::Piece:0x... @letter="k">
 
-# With prefix
-result = Pnn.parse("+k")
-# => { letter: "k", prefix: "+" }
+# With modifiers
+enhanced_piece = Pnn::Piece.parse("+k'")
+# => #<Pnn::Piece:0x... @letter="k", @enhanced=true, @intermediate=true>
 
-# With suffix
-result = Pnn.parse("k'")
-# => { letter: "k", suffix: "'" }
+# Create directly with constructor
+piece = Pnn::Piece.new("k")
+enhanced_piece = Pnn::Piece.new("k", enhanced: true, intermediate: true)
 
-# With both prefix and suffix
-result = Pnn.parse("+k'")
-# => { letter: "k", prefix: "+", suffix: "'" }
+# Convenience method
+piece = Pnn.piece("k", enhanced: true)
 ```
 
-### Safe Parsing
+### Converting to PNN String
 
-Parse a PNN string without raising exceptions:
+Convert a piece object back to its PNN string representation:
 
 ```ruby
-require "pnn"
-
-# Valid PNN string
-result = Pnn.safe_parse("+k'")
-# => { letter: "k", prefix: "+", suffix: "'" }
+piece = Pnn::Piece.parse("k")
+piece.to_s
+# => "k"
 
-# Invalid PNN string
-result = Pnn.safe_parse("invalid pnn string")
-# => nil
+enhanced_piece = Pnn::Piece.parse("+k'")
+enhanced_piece.to_s
+# => "+k'"
 ```
 
-### Creating PNN Strings
+### State Manipulation
 
-Convert piece components into a PNN string:
+Create new piece instances with different states:
 
 ```ruby
-require "pnn"
+piece = Pnn::Piece.parse("k")
 
-# Basic letter
-Pnn.dump(letter: "k")
-# => "k"
+# Enhanced state (+ prefix)
+enhanced = piece.enhance
+enhanced.to_s # => "+k"
+
+# Diminished state (- prefix)
+diminished = piece.diminish
+diminished.to_s # => "-k"
 
-# With prefix
-Pnn.dump(letter: "p", prefix: "+")
-# => "+p"
+# Intermediate state (' suffix)
+intermediate = piece.intermediate
+intermediate.to_s # => "k'"
 
-# With suffix
-Pnn.dump(letter: "k", suffix: "'")
-# => "k'"
+# Remove states
+restored = enhanced.unenhance
+restored.to_s # => "k"
 
-# With both prefix and suffix
-Pnn.dump(letter: "p", prefix: "+", suffix: "'")
-# => "+p'"
+# Combine states
+complex = piece.enhance.intermediate
+complex.to_s # => "+k'"
 ```
 
-### Validation
+### Ownership Changes
 
-Check if a string is valid PNN notation:
+Change piece ownership (case conversion):
 
 ```ruby
-require "pnn"
+white_king = Pnn::Piece.parse("K")
+black_king = white_king.flip
+black_king.to_s # => "k"
+
+# Works with modifiers too
+enhanced_white = Pnn::Piece.parse("+K'")
+enhanced_black = enhanced_white.flip
+enhanced_black.to_s # => "+k'"
+```
 
-Pnn.valid?("k")      # => true
-Pnn.valid?("+p")     # => true
-Pnn.valid?("k'")     # => true
-Pnn.valid?("+p'")    # => true
+### Clean State
 
-Pnn.valid?("")       # => false
-Pnn.valid?("kp")     # => false
-Pnn.valid?("++k")    # => false
-Pnn.valid?("k''")    # => false
+Get a piece without any modifiers:
+
+```ruby
+complex_piece = Pnn::Piece.parse("+k'")
+clean_piece = complex_piece.bare
+clean_piece.to_s # => "k"
 ```
 
-### Piece Modifiers
+## State Modifier Methods
+
+The `Pnn::Piece` class provides methods to manipulate piece states:
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `enhance` | Add Enhanced state (`+` prefix) | `k` → `+k` |
+| `unenhance` | Remove Enhanced state | `+k` → `k` |
+| `diminish` | Add Diminished state (`-` prefix) | `k` → `-k` |
+| `undiminish` | Remove Diminished state | `-k` → `k` |
+| `intermediate` | Add Intermediate state (`'` suffix) | `k` → `k'` |
+| `unintermediate` | Remove Intermediate state | `k'` → `k` |
+| `bare` | Remove all modifiers | `+k'` → `k` |
+| `flip` | Change ownership (case) | `K` → `k`, `k` → `K` |
+
+All state manipulation methods return new `Pnn::Piece` instances, leaving the original unchanged (immutable design).
+
+## Piece Modifiers
 
 PNN supports prefixes and suffixes for pieces to denote various states or capabilities. It's important to note that these modifiers are rule-agnostic - they provide a framework for representing piece states, but their specific meaning is determined by the game implementation:
 
-- **Prefix `+`**: Enhanced state
-  - Example in shogi: `+p` represents a promoted pawn with enhanced movement capabilities
+- **Enhanced state (`+`)**: Represents pieces with enhanced capabilities
+  - Example in shogi: `+p` represents a promoted pawn (tokin)
   - Example in chess variants: `+Q` might represent a queen with special powers
 
-- **Prefix `-`**: Diminished state
-  - Example in variants: `-R` might represent a rook with restricted movement abilities
-  - Example in weakened pieces: `-N` could indicate a knight that has been partially immobilized
+- **Diminished state (`-`)**: Represents pieces with reduced capabilities
+  - Example in variants: `-R` might represent a rook with restricted movement
+  - Example in chess: `-N` could indicate a knight that has been partially immobilized
 
-- **Suffix `'`**: Intermediate state
+- **Intermediate state (`'`)**: Represents pieces with special temporary states
   - Example in chess: `R'` represents a rook that can still be used for castling
   - Example in chess: `P'` represents a pawn that can be captured en passant
   - Example in variants: `B'` might indicate a bishop with a special one-time ability
 
-These modifiers have no intrinsic semantics in the PNN specification itself. They merely provide a flexible framework for representing piece-specific conditions or states while maintaining PNN's rule-agnostic nature. Game implementations are responsible for interpreting these modifiers according to their specific rules.
+These modifiers have no intrinsic semantics in the PNN specification itself. They merely provide a flexible framework for representing piece-specific conditions or states while maintaining PNN's rule-agnostic nature.
 
 ## Examples of PNN in Common Games
 
-The following examples demonstrate how PNN might be used in familiar games. Remember that PNN itself defines only the notation format, not the game-specific interpretations.
-
 ### Chess Examples
 
-In the context of chess:
+```ruby
+# Standard pieces
+king = Pnn::Piece.parse("K")           # White king
+black_king = Pnn::Piece.parse("k")     # Black king
+queen = Pnn::Piece.parse("Q")          # White queen
 
-```
-K       # King (first player)
-k       # King (second player)
-Q       # Queen (first player)
-R '      # Rook that has not moved yet and can be used for castling
-P'      # Pawn that can be captured en passant
+# Create pieces directly
+king = Pnn::Piece.new("K")             # White king
+black_king = Pnn::Piece.new("k")       # Black king
+
+# Pieces with special states
+unmoved_rook = Pnn::Piece.parse("R'") # Rook that can castle
+en_passant_pawn = Pnn::Piece.parse("P'") # Pawn vulnerable to en passant
+
+# Creating modified pieces
+promoted_pawn = Pnn::Piece.parse("p").enhance # "+p"
+weakened_queen = Pnn::Piece.parse("Q").diminish # "-Q"
+
+# Or create directly with modifiers
+promoted_pawn = Pnn::Piece.new("p", enhanced: true) # "+p"
+weakened_queen = Pnn::Piece.new("Q", diminished: true) # "-Q"
+
+# Using convenience method
+special_knight = Pnn.piece("N", intermediate: true) # "N'"
 ```
 
 ### Shogi Examples
 
-In the context of shogi:
+```ruby
+# Standard pieces
+king = Pnn::Piece.parse("K")           # Oushou (King)
+pawn = Pnn::Piece.parse("P")           # Fuhyou (Pawn)
 
+# Create directly
+king = Pnn::Piece.new("K")             # Oushou (King)
+pawn = Pnn::Piece.new("P")             # Fuhyou (Pawn)
+
+# Promoted pieces
+tokin = Pnn::Piece.parse("P").enhance # "+P" (Promoted pawn)
+narikyou = Pnn::Piece.parse("L").enhance # "+L" (Promoted lance)
+
+# Or create promoted pieces directly
+tokin = Pnn::Piece.new("P", enhanced: true) # "+P"
+narikyou = Pnn::Piece.new("L", enhanced: true) # "+L"
+
+# Using convenience method
+promoted_silver = Pnn.piece("S", enhanced: true) # "+S"
+
+# Converting between players (capture and drop)
+enemy_piece = Pnn::Piece.parse("p")
+captured_piece = enemy_piece.flip.bare # "P" (now belongs to other player, no modifiers)
 ```
-K       # King (first player)
-k       # King (second player)
-+P      # Promoted pawn (tokin)
-+L      # Promoted lance (narikyou)
+
+## Advanced Usage
+
+### Chaining State Changes
+
+```ruby
+piece = Pnn::Piece.parse("k")
+
+# Chain multiple state changes
+complex_piece = piece.enhance.intermediate.flip
+complex_piece.to_s # => "+K'"
+
+# Reverse the changes
+simple_piece = complex_piece.unenhance.unintermediate.flip
+simple_piece.to_s # => "k"
 ```
 
-### Example: A Complete Chess Position with PNN
+### Validation
 
-A chess position might contain a mix of standard and modified pieces. Here's an example after the moves 1. e4 c5 2. e5 d5:
+All parsing automatically validates input according to the PNN specification:
 
+```ruby
+# Valid PNN strings
+Pnn::Piece.parse("k")      # ✓
+Pnn::Piece.parse("+p")     # ✓
+Pnn::Piece.parse("K'")     # ✓
+Pnn::Piece.parse("+p'")    # ✓
+
+# Valid constructor calls
+Pnn::Piece.new("k") # ✓
+Pnn::Piece.new("p", enhanced: true) # ✓
+Pnn::Piece.new("K", intermediate: true) # ✓
+Pnn::Piece.new("p", enhanced: true, intermediate: true) # ✓
+
+# Convenience method
+Pnn.piece("k", enhanced: true) # ✓
+
+# Check validity
+Pnn.valid?("k'") # => true
+Pnn.valid?("invalid") # => false
+
+# Invalid PNN strings raise ArgumentError
+Pnn::Piece.parse("")       # ✗ ArgumentError
+Pnn::Piece.parse("kp")     # ✗ ArgumentError
+Pnn::Piece.parse("++k")    # ✗ ArgumentError
+Pnn::Piece.parse("k''")    # ✗ ArgumentError
+
+# Invalid constructor calls raise ArgumentError
+Pnn::Piece.new("")         # ✗ ArgumentError
+Pnn::Piece.new("kp")       # ✗ ArgumentError
+Pnn::Piece.new("k", enhanced: true, diminished: true) # ✗ ArgumentError
 ```
-r' n  b  q  k  b  n  r'    # Eighth rank with unmoved rooks (castling rights)
-p  p  .  .  p  p  p  p     # Seventh rank pawns (d and c pawns have moved)
-.  .  .  .  .  .  .  .     # Empty sixth rank
-.  .  p  p' P  .  .  .     # Fifth rank with pawn that can be captured en passant (d5) and other pawns
-.  .  .  .  .  .  .  .     # Empty fourth rank
-.  .  .  .  .  .  .  .     # Empty third rank
-P  P  P  P  .  P  P  P     # Second rank pawns (e pawn has moved)
-R' N  B  Q  K  B  N  R'    # First rank with unmoved rooks (castling rights)
+
+### Inspection and Debugging
+
+```ruby
+piece = Pnn::Piece.parse("+k'")
+
+# Get detailed information
+piece.inspect
+# => "#<Pnn::Piece:0x... letter='k' enhanced=true intermediate=true>"
+
+# Check individual states
+piece.enhanced?      # => true
+piece.diminished?    # => false
+piece.intermediate?  # => true
+piece.uppercase?     # => false (it's lowercase 'k')
+piece.lowercase?     # => true
 ```
 
-In this position, White could capture Black's queen pawn (d5) en passant with the e5 pawn moving to d6.
+## API Reference
+
+### Module Methods
+
+- `Pnn.valid?(pnn_string)` - Check if a string is valid PNN notation
+- `Pnn.piece(letter, **options)` - Convenience method to create pieces
+
+### Pnn::Piece Class Methods
+
+- `Pnn::Piece.parse(pnn_string)` - Parse a PNN string into a piece object
+- `Pnn::Piece.new(letter, **options)` - Create a new piece instance
+
+### Instance Methods
+
+#### State Queries
+- `#enhanced?` - Check if piece has enhanced state
+- `#diminished?` - Check if piece has diminished state
+- `#intermediate?` - Check if piece has intermediate state
+- `#bare?` - Check if piece has no modifiers
+- `#uppercase?` - Check if piece belongs to first player
+- `#lowercase?` - Check if piece belongs to second player
+
+#### State Manipulation
+- `#enhance` - Add enhanced state
+- `#unenhance` - Remove enhanced state
+- `#diminish` - Add diminished state
+- `#undiminish` - Remove diminished state
+- `#intermediate` - Add intermediate state
+- `#unintermediate` - Remove intermediate state
+- `#bare` - Remove all modifiers
+- `#flip` - Change ownership (case)
 
-Note: The above representation is merely illustrative; PNN itself only defines the notation for individual pieces, not complete board states.
+#### Conversion
+- `#to_s` - Convert to PNN string representation
+- `#inspect` - Detailed string representation for debugging
 
 ## Properties of PNN
 
 * **Rule-agnostic**: PNN does not encode legality, validity, or game-specific conditions.
 * **Canonical representation**: Ensures that equivalent pieces yield identical strings.
 * **State modifiers**: Express special conditions without compromising rule neutrality.
+* **Immutable objects**: All state changes return new instances, ensuring thread safety.
 
 ## Constraints
 

data/lib/pnn/piece.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+module Pnn
+  # Represents a piece in PNN (Piece Name Notation) format.
+  #
+  # A piece consists of a single ASCII letter with optional state modifiers:
+  # - Enhanced state: prefix '+'
+  # - Diminished state: prefix '-'
+  # - Intermediate state: suffix "'"
+  #
+  # 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.
+  class Piece
+    # PNN validation pattern matching the specification
+    PNN_PATTERN = /\A(?<prefix>[-+])?(?<letter>[a-zA-Z])(?<suffix>['])?\z/
+
+    # Valid state modifiers
+    ENHANCED_PREFIX = "+"
+    DIMINISHED_PREFIX = "-"
+    INTERMEDIATE_SUFFIX = "'"
+
+    # Error messages
+    ERROR_INVALID_PNN = "Invalid PNN string: %s"
+    ERROR_INVALID_LETTER = "Letter must be a single ASCII letter (a-z or A-Z): %s"
+
+    # @return [String] the base letter identifier
+    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
+    # @param intermediate [Boolean] whether the piece has intermediate state
+    # @raise [ArgumentError] if parameters are invalid
+    def initialize(letter, enhanced: false, diminished: false, intermediate: false)
+      self.class.validate_letter(letter)
+      self.class.validate_state_combination(enhanced, diminished)
+
+      @letter = letter.freeze
+      @enhanced = enhanced
+      @diminished = diminished
+      @intermediate = intermediate
+
+      freeze
+    end
+
+    # Parse a PNN string into a Piece object
+    #
+    # @param pnn_string [String] PNN notation string
+    # @return [Piece] new piece instance
+    # @raise [ArgumentError] if the PNN string is invalid
+    # @example
+    #   Pnn::Piece.parse("k")     # => #<Pnn::Piece letter="k">
+    #   Pnn::Piece.parse("+k'")   # => #<Pnn::Piece letter="k" enhanced=true intermediate=true>
+    def self.parse(pnn_string)
+      string_value = String(pnn_string)
+      matches = match_pattern(string_value)
+
+      letter = matches[:letter]
+      enhanced = matches[:prefix] == ENHANCED_PREFIX
+      diminished = matches[:prefix] == DIMINISHED_PREFIX
+      intermediate = matches[:suffix] == INTERMEDIATE_SUFFIX
+
+      new(
+        letter,
+        enhanced:     enhanced,
+        diminished:   diminished,
+        intermediate: intermediate
+      )
+    end
+
+    # Convert the piece to its PNN string representation
+    #
+    # @return [String] PNN notation string
+    # @example
+    #   piece.to_s  # => "+k'"
+    def to_s
+      prefix = if @enhanced
+                 ENHANCED_PREFIX
+               else
+                 (@diminished ? DIMINISHED_PREFIX : "")
+               end
+      suffix = @intermediate ? INTERMEDIATE_SUFFIX : ""
+      "#{prefix}#{letter}#{suffix}"
+    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,
+        intermediate: @intermediate
+      )
+    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,
+        intermediate: @intermediate
+      )
+    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,
+        intermediate: @intermediate
+      )
+    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,
+        intermediate: @intermediate
+      )
+    end
+
+    # Create a new piece with intermediate state
+    #
+    # @return [Piece] new piece instance with intermediate state
+    # @example
+    #   piece.intermediate  # k => k'
+    def intermediate
+      return self if intermediate?
+
+      self.class.new(
+        letter,
+        enhanced:     @enhanced,
+        diminished:   @diminished,
+        intermediate: true
+      )
+    end
+
+    # Create a new piece without intermediate state
+    #
+    # @return [Piece] new piece instance without intermediate state
+    # @example
+    #   piece.unintermediate  # k' => k
+    def unintermediate
+      return self unless intermediate?
+
+      self.class.new(
+        letter,
+        enhanced:     @enhanced,
+        diminished:   @diminished,
+        intermediate: false
+      )
+    end
+
+    # Create a new piece without any modifiers
+    #
+    # @return [Piece] new piece instance with only the base letter
+    # @example
+    #   piece.bare  # +k' => k
+    def bare
+      return self if bare?
+
+      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,
+        intermediate: @intermediate
+      )
+    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 intermediate state
+    #
+    # @return [Boolean] true if intermediate
+    def intermediate?
+      @intermediate
+    end
+
+    # Check if the piece has no modifiers
+    #
+    # @return [Boolean] true if no modifiers are present
+    def bare?
+      !enhanced? && !diminished? && !intermediate?
+    end
+
+    # Check if the piece belongs to the first player (uppercase)
+    #
+    # @return [Boolean] true if uppercase letter
+    def uppercase?
+      letter == letter.upcase
+    end
+
+    # Check if the piece belongs to the second player (lowercase)
+    #
+    # @return [Boolean] true if lowercase letter
+    def lowercase?
+      letter == letter.downcase
+    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? &&
+        intermediate? == other.intermediate?
+    end
+
+    # Custom hash implementation for use in collections
+    #
+    # @return [Integer] hash value
+    def hash
+      [letter, @enhanced, @diminished, @intermediate].hash
+    end
+
+    # Custom inspection for debugging
+    #
+    # @return [String] detailed string representation
+    def inspect
+      modifiers = []
+      modifiers << "enhanced=true" if enhanced?
+      modifiers << "diminished=true" if diminished?
+      modifiers << "intermediate=true" if intermediate?
+
+      modifier_str = modifiers.empty? ? "" : " #{modifiers.join(' ')}"
+      "#<#{self.class.name}:0x#{object_id.to_s(16)} letter='#{letter}'#{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 PNN 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 = PNN_PATTERN.match(string)
+      return matches if matches
+
+      raise ::ArgumentError, format(ERROR_INVALID_PNN, string)
+    end
+
+    private_class_method :match_pattern
+  end
+end

data/lib/pnn.rb

@@ -1,70 +1,67 @@
 # frozen_string_literal: true
 
-require_relative File.join("pnn", "dumper")
-require_relative File.join("pnn", "parser")
-require_relative File.join("pnn", "validator")
+require_relative File.join("pnn", "piece")
 
-# This module provides a Ruby interface for serialization and
-# deserialization of piece identifiers in PNN format.
+# This module provides a Ruby interface for working with piece identifiers
+# in PNN (Piece Name Notation) format.
 #
-# PNN (Piece Name Notation) defines a consistent and rule-agnostic
-# format for representing pieces in abstract strategy board games.
+# PNN defines a consistent and rule-agnostic format for representing pieces
+# in abstract strategy board games, providing a standardized way to identify
+# pieces independent of any specific game rules or mechanics.
+#
+# The primary interface is the `Pnn::Piece` class, which provides an
+# object-oriented API for creating, parsing, and manipulating piece representations.
+#
+# @example Basic usage with the Piece class
+#   # Parse a PNN string
+#   piece = Pnn::Piece.parse("k")
+#
+#   # Create directly
+#   piece = Pnn::Piece.new("k")
+#
+#   # Manipulate states
+#   enhanced = piece.enhance
+#   enhanced.to_s  # => "+k"
+#
+#   # Change ownership
+#   flipped = piece.flip
+#   flipped.to_s  # => "K"
 #
 # @see https://sashite.dev/documents/pnn/1.0.0/
+# @see Pnn::Piece
 module Pnn
-  # Serializes a piece identifier into a PNN string.
+  # Validate if the given string is a valid PNN string.
   #
-  # @param letter [String] A single ASCII letter ('a-z' or 'A-Z')
-  # @param prefix [String, nil] Optional modifier preceding the letter ('+' or '-')
-  # @param suffix [String, nil] Optional modifier following the letter (''')
-  # @return [String] PNN notation string
-  # @raise [ArgumentError] If any parameter is invalid
-  # @example
-  #   Pnn.dump(letter: "k", suffix: "'")
-  #   # => "k'"
-  def self.dump(letter:, prefix: nil, suffix: nil)
-    Dumper.dump(letter:, prefix:, suffix:)
-  end
-
-  # Parses a PNN string into its component parts.
-  #
-  # @param pnn_string [String] PNN notation string
-  # @return [Hash] Hash containing the parsed piece data with the following keys:
-  #   - :letter [String] - The base letter identifier
-  #   - :prefix [String, nil] - The prefix modifier if present
-  #   - :suffix [String, nil] - The suffix modifier if present
-  # @raise [ArgumentError] If the PNN string is invalid
+  # @param pnn_string [String] PNN string to validate
+  # @return [Boolean] True if the string is a valid PNN string
   # @example
-  #   Pnn.parse("+k'")
-  #   # => { letter: "k", prefix: "+", suffix: "'" }
-  def self.parse(pnn_string)
-    Parser.parse(pnn_string)
+  #   Pnn.valid?("k'")     # => true
+  #   Pnn.valid?("invalid") # => false
+  def self.valid?(pnn_string)
+    Piece.parse(pnn_string).to_s == pnn_string
+  rescue ArgumentError
+    false
   end
 
-  # Safely parses a PNN string into its component parts without raising exceptions.
+  # Create a new piece instance.
   #
-  # @param pnn_string [String] PNN notation string
-  # @return [Hash, nil] Hash containing the parsed piece data or nil if parsing fails
-  # @example
-  #   # Valid PNN string
-  #   Pnn.safe_parse("+k'")
-  #   # => { letter: "k", prefix: "+", suffix: "'" }
-  #
-  #   # Invalid PNN string
-  #   Pnn.safe_parse("invalid")
-  #   # => nil
-  def self.safe_parse(pnn_string)
-    Parser.safe_parse(pnn_string)
-  end
-
-  # Validates if the given string is a valid PNN string
+  # This is a convenience method that delegates to `Pnn::Piece.new`.
   #
-  # @param pnn_string [String] PNN string to validate
-  # @return [Boolean] True if the string is a valid PNN string
+  # @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 intermediate [Boolean] whether the piece has intermediate state
+  # @return [Pnn::Piece] new piece instance
+  # @raise [ArgumentError] if parameters are invalid
   # @example
-  #   Pnn.valid?("k'") # => true
-  #   Pnn.valid?("invalid") # => false
-  def self.valid?(pnn_string)
-    Validator.valid?(pnn_string)
+  #   piece = Pnn.piece("k", enhanced: true)
+  #   piece.to_s  # => "+k"
+  def self.piece(letter, enhanced: false, diminished: false, intermediate: false)
+    Piece.new(
+      letter,
+      enhanced:,
+      diminished:,
+      intermediate:
+    )
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pnn
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -9,10 +9,12 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: A Ruby interface for serialization and deserialization of piece identifiers
-  in PNN format. PNN is a consistent and rule-agnostic format for representing pieces
-  in abstract strategy board games, providing a standardized way to identify pieces
-  independent of any specific game rules or mechanics.
+description: A clean, immutable Ruby interface for working with piece identifiers
+  in PNN format. PNN provides a consistent and rule-agnostic notation for representing
+  pieces in abstract strategy board games like chess, shogi, and xiangqi. Features
+  include state modifiers for enhanced/diminished/intermediate pieces, ownership changes,
+  and comprehensive validation. Perfect for game engines, analysis tools, and educational
+  applications.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -21,9 +23,7 @@ files:
 - LICENSE.md
 - README.md
 - lib/pnn.rb
-- lib/pnn/dumper.rb
-- lib/pnn/parser.rb
-- lib/pnn/validator.rb
+- lib/pnn/piece.rb
 homepage: https://github.com/sashite/pnn.rb
 licenses:
 - MIT
@@ -50,5 +50,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.7
 specification_version: 4
-summary: PNN (Piece Name Notation) support for the Ruby language.
+summary: Modern Ruby implementation of Piece Name Notation (PNN) for abstract strategy
+  games.
 test_files: []

data/lib/pnn/dumper.rb

@@ -1,72 +0,0 @@
-# frozen_string_literal: true
-
-module Pnn
-  # Serializes piece components into PNN strings
-  class Dumper
-    # Valid prefix modifiers
-    VALID_PREFIXES = ["+", "-", nil].freeze
-
-    # Valid suffix modifiers
-    VALID_SUFFIXES = ["'", nil].freeze
-
-    # Letter validation pattern
-    LETTER_PATTERN = /\A[a-zA-Z]\z/
-
-    # Error messages
-    ERROR_INVALID_LETTER = "Letter must be a single ASCII letter (a-z or A-Z): %s"
-    ERROR_INVALID_PREFIX = "Invalid prefix: %s. Must be '+', '-', or nil."
-    ERROR_INVALID_SUFFIX = "Invalid suffix: %s. Must be ''', or nil."
-
-    # Serialize piece components into a PNN string
-    #
-    # @param letter [String] The single ASCII letter identifier
-    # @param prefix [String, nil] Optional prefix modifier
-    # @param suffix [String, nil] Optional suffix modifier
-    # @return [String] PNN notation string
-    # @raise [ArgumentError] If any component is invalid
-    def self.dump(letter:, prefix: nil, suffix: nil)
-      validate_letter(letter)
-      validate_prefix(prefix)
-      validate_suffix(suffix)
-
-      "#{prefix}#{letter}#{suffix}"
-    end
-
-    # Validates that the letter is a single ASCII letter
-    #
-    # @param letter [Object] The letter to validate
-    # @return [void]
-    # @raise [ArgumentError] If the letter is invalid
-    def self.validate_letter(letter)
-      letter_str = String(letter)
-
-      return if letter_str.match?(LETTER_PATTERN)
-
-      raise ArgumentError, format(ERROR_INVALID_LETTER, letter_str)
-    end
-
-    # Validates that the prefix is valid
-    #
-    # @param prefix [String, nil] The prefix to validate
-    # @return [void]
-    # @raise [ArgumentError] If the prefix is invalid
-    def self.validate_prefix(prefix)
-      return if VALID_PREFIXES.include?(prefix)
-
-      raise ArgumentError, format(ERROR_INVALID_PREFIX, prefix)
-    end
-
-    # Validates that the suffix is valid
-    #
-    # @param suffix [String, nil] The suffix to validate
-    # @return [void]
-    # @raise [ArgumentError] If the suffix is invalid
-    def self.validate_suffix(suffix)
-      return if VALID_SUFFIXES.include?(suffix)
-
-      raise ArgumentError, format(ERROR_INVALID_SUFFIX, suffix)
-    end
-
-    private_class_method :validate_letter, :validate_prefix, :validate_suffix
-  end
-end

data/lib/pnn/parser.rb

@@ -1,62 +0,0 @@
-# frozen_string_literal: true
-
-module Pnn
-  # Parses PNN strings into their component parts
-  class Parser
-    # PNN regex capture groups for parsing
-    PATTERN = /\A(?<prefix>[-+])?(?<letter>[a-zA-Z])(?<suffix>['])?\z/
-
-    # Error message for invalid PNN string
-    ERROR_INVALID_PNN = "Invalid PNN string: %s"
-
-    # Component keys for the result hash
-    COMPONENT_KEYS = %i[letter prefix suffix].freeze
-
-    # Parse a PNN string into its components
-    #
-    # @param pnn_string [String] The PNN string to parse
-    # @return [Hash] Hash containing the parsed components
-    # @raise [ArgumentError] If the PNN string is invalid
-    def self.parse(pnn_string)
-      string_value = String(pnn_string)
-      matches = match_pattern(string_value)
-      extract_components(matches)
-    end
-
-    # Safely parse a PNN string without raising exceptions
-    #
-    # @param pnn_string [String] The PNN string to parse
-    # @return [Hash, nil] Hash containing the parsed components or nil if invalid
-    def self.safe_parse(pnn_string)
-      parse(pnn_string)
-    rescue ArgumentError
-      nil
-    end
-
-    # Match the PNN pattern against a string
-    #
-    # @param string [String] The string to match
-    # @return [MatchData] The match data
-    # @raise [ArgumentError] If the string doesn't match the pattern
-    def self.match_pattern(string)
-      matches = PATTERN.match(string)
-
-      return matches if matches
-
-      raise ArgumentError, format(ERROR_INVALID_PNN, string)
-    end
-
-    # Extract components from match data
-    #
-    # @param matches [MatchData] The match data
-    # @return [Hash] Hash containing the parsed components
-    def self.extract_components(matches)
-      COMPONENT_KEYS.each_with_object({}) do |key, result|
-        value = matches[key]
-        result[key] = value if value
-      end
-    end
-
-    private_class_method :match_pattern, :extract_components
-  end
-end

data/lib/pnn/validator.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-module Pnn
-  # Validates PNN strings according to the specification
-  class Validator
-    # PNN validation pattern matching the JSON schema pattern in the spec
-    PATTERN = /\A[-+]?[a-zA-Z][']?\z/
-
-    # Class method to validate PNN strings
-    #
-    # @param pnn_string [Object] The PNN string to validate
-    # @return [Boolean] True if the string is valid according to PNN specification
-    def self.valid?(pnn_string)
-      validate_string(String(pnn_string))
-    end
-
-    # Validates the given string against the PNN pattern
-    #
-    # @param string [String] The string to validate
-    # @return [Boolean] True if the string matches the PNN pattern
-    def self.validate_string(string)
-      string.match?(PATTERN)
-    end
-
-    private_class_method :validate_string
-  end
-end