pnn 1.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c243c47d75b03455ad8fa85bebd13cf90b6e3abb2c37f93cf425a1a51f14b16
-  data.tar.gz: 89a3d75180c92c5627e6dfb9c301f0ba3637e59c923448b7e5c9cde175805144
+  metadata.gz: '0584c1ee7a42c3f556efe5e27e106c07b7e12c37148ba345238ef9fb02622c76'
+  data.tar.gz: b31fcbfb3442f0b130662a0cbd7e644c127b3c8a9247f3380f85056aa0be6ea1
 SHA512:
-  metadata.gz: 688721867ee73331f8b2b49606caefafe3239efccc7756d122b1cb76453c472d9a71dba2de13224388a6ea110651abb5386d87039a3c110e0366a03c00cfd4f0
-  data.tar.gz: 82e0e2c1d4f058a8d09c107ad1f6beef50a0a2c826b9467504fca411281ce766d8cac9468cca105760ba16db1a014d5d0db1c92b6a4fdd268f24c07c273274e6
+  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,121 +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 (`=`, `<`, or `>`)
+- `<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"
+piece = Pnn::Piece.parse("k")
+piece.to_s
+# => "k"
+
+enhanced_piece = Pnn::Piece.parse("+k'")
+enhanced_piece.to_s
+# => "+k'"
+```
+
+### State Manipulation
+
+Create new piece instances with different states:
+
+```ruby
+piece = Pnn::Piece.parse("k")
+
+# Enhanced state (+ prefix)
+enhanced = piece.enhance
+enhanced.to_s # => "+k"
+
+# Diminished state (- prefix)
+diminished = piece.diminish
+diminished.to_s # => "-k"
+
+# Intermediate state (' suffix)
+intermediate = piece.intermediate
+intermediate.to_s # => "k'"
 
-# Valid PNN string
-result = Pnn.safe_parse("+k=")
-# => { letter: "k", prefix: "+", suffix: "=" }
+# Remove states
+restored = enhanced.unenhance
+restored.to_s # => "k"
 
-# Invalid PNN string
-result = Pnn.safe_parse("invalid pnn string")
-# => nil
+# Combine states
+complex = piece.enhance.intermediate
+complex.to_s # => "+k'"
 ```
 
-### Creating PNN Strings
+### Ownership Changes
 
-Convert piece components into a PNN string:
+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'"
+```
 
-# Basic letter
-Pnn.dump(letter: "k")
-# => "k"
+### Clean State
+
+Get a piece without any modifiers:
+
+```ruby
+complex_piece = Pnn::Piece.parse("+k'")
+clean_piece = complex_piece.bare
+clean_piece.to_s # => "k"
+```
+
+## 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:
+
+- **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
+
+- **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
+
+- **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
 
-# With prefix
-Pnn.dump(letter: "p", prefix: "+")
-# => "+p"
+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.
 
-# With suffix
-Pnn.dump(letter: "k", suffix: "=")
-# => "k="
+## Examples of PNN in Common Games
 
-# With both prefix and suffix
-Pnn.dump(letter: "p", prefix: "+", suffix: ">")
-# => "+p>"
+### Chess Examples
+
+```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
+
+# 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
+
+```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)
+```
+
+## 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"
 ```
 
 ### Validation
 
-Check if a string is valid PNN notation:
+All parsing automatically validates input according to the PNN specification:
 
 ```ruby
-require "pnn"
+# 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
+```
 
-Pnn.valid?("k")      # => true
-Pnn.valid?("+p")     # => true
-Pnn.valid?("k=")     # => true
-Pnn.valid?("+p>")    # => true
+### Inspection and Debugging
 
-Pnn.valid?("")       # => false
-Pnn.valid?("kp")     # => false
-Pnn.valid?("++k")    # => false
-Pnn.valid?("k==")    # => false
+```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
 ```
 
-### Piece Modifiers
+## API Reference
+
+### Module Methods
 
-PNN supports prefixes and suffixes for pieces to denote various states or capabilities:
+- `Pnn.valid?(pnn_string)` - Check if a string is valid PNN notation
+- `Pnn.piece(letter, **options)` - Convenience method to create pieces
 
-- **Prefix `+`**: Alternative or enhanced state
-  - Example in shogi: `+p` may represent a promoted pawn
+### Pnn::Piece Class Methods
 
-- **Prefix `-`**: Diminished or restricted state
-  - Example: `-k` may represent a king with restricted movement
+- `Pnn::Piece.parse(pnn_string)` - Parse a PNN string into a piece object
+- `Pnn::Piece.new(letter, **options)` - Create a new piece instance
 
-- **Suffix `=`**: Bidirectional or dual-option state
-  - Example in chess: `k=` may represent a king eligible for both kingside and queenside castling
+### Instance Methods
 
-- **Suffix `<`**: Left-side constraint or condition
-  - Example in chess: `k<` may represent a king eligible for queenside castling only
-  - Example in chess: `p<` may represent a pawn that may be captured _en passant_ from the left
+#### 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
 
-- **Suffix `>`**: Right-side constraint or condition
-  - Example in chess: `k>` may represent a king eligible for kingside castling only
-  - Example in chess: `p>` may represent a pawn that may be captured en passant from the right
+#### 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)
 
-These modifiers have no defined semantics in the PNN specification itself but provide a flexible framework for representing piece-specific conditions while maintaining PNN's rule-agnostic nature.
+#### 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
 
@@ -173,4 +354,4 @@ The [gem](https://rubygems.org/gems/pnn) is available as open source under the t
 
 ## About Sashité
 
-This project is maintained by [Sashité](https://sashite.com/) - a project dedicated to promoting chess variants and sharing the beauty of Chinese, Japanese, and Western chess cultures.
+This project is maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of Chinese, Japanese, and Western chess cultures.

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 prefix [String, nil] Optional modifier preceding the letter ('+' or '-')
-  # @param letter [String] A single ASCII letter ('a-z' or 'A-Z')
-  # @param suffix [String, nil] Optional modifier following the letter ('=', '<', or '>')
-  # @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.0.1
+  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,35 +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
-
-    # 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)
-      letter = String(letter)
-
-      unless letter.match?(/^[a-zA-Z]$/)
-        raise ArgumentError, "Letter must be a single ASCII letter (a-z or A-Z): #{letter}"
-      end
-
-      raise ArgumentError, "Invalid prefix: #{prefix}. Must be '+', '-', or nil." unless VALID_PREFIXES.include?(prefix)
-
-      unless VALID_SUFFIXES.include?(suffix)
-        raise ArgumentError, "Invalid suffix: #{suffix}. Must be '=', '<', '>', or nil."
-      end
-
-      "#{prefix}#{letter}#{suffix}"
-    end
-  end
-end

data/lib/pnn/parser.rb

@@ -1,38 +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/
-
-    # 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)
-      pnn_string = String(pnn_string)
-
-      matches = PATTERN.match(pnn_string)
-
-      raise ArgumentError, "Invalid PNN string: #{pnn_string}" if matches.nil?
-
-      {
-        letter: matches[:letter],
-        prefix: matches[:prefix],
-        suffix: matches[:suffix]
-      }.compact
-    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
-  end
-end

data/lib/pnn/validator.rb

@@ -1,17 +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 [String] The PNN string to validate
-    # @return [Boolean] True if the string is valid according to PNN specification
-    def self.valid?(pnn_string)
-      String(pnn_string).match?(PATTERN)
-    end
-  end
-end