sashite-pnn 1.0.1 → 2.0.0

data/lib/sashite/pnn/piece.rb

@@ -6,37 +6,75 @@ module Sashite
   module Pnn
     # Represents a piece in PNN (Piece Name Notation) format.
     #
-    # Extends PIN::Piece to add style awareness through derivation markers.
-    # A PNN piece consists of a PIN string with an optional derivation suffix:
-    # - No suffix: native style
-    # - Apostrophe suffix ('): foreign style
+    # A piece consists of a PIN component with an optional derivation marker:
+    # - PIN component: [<state>]<letter> (from PIN specification)
+    # - Derivation marker: "'" (foreign style) or none (native style)
     #
-    # All instances are immutable - style manipulation methods return new instances.
-    class Piece < ::Sashite::Pin::Piece
-      # PNN validation pattern extending PIN
-      PNN_PATTERN = /\A(?<prefix>[-+])?(?<letter>[a-zA-Z])(?<suffix>'?)\z/
-
-      # Derivation marker for foreign style
+    # The case of the letter determines ownership:
+    # - Uppercase (A-Z): first player
+    # - Lowercase (a-z): second player
+    #
+    # Style derivation logic:
+    # - No suffix: piece has the native style of its current side
+    # - Apostrophe suffix: piece has the foreign style (opposite side's native style)
+    #
+    # All instances are immutable - state manipulation methods return new instances.
+    # This extends the Game Protocol's piece model with Style support through derivation.
+    class Piece
+      # Valid derivation suffixes
       FOREIGN_SUFFIX = "'"
+      NATIVE_SUFFIX = ""
+
+      # Derivation constants
+      NATIVE = true
+      FOREIGN = false
+
+      # Valid derivations
+      VALID_DERIVATIONS = [NATIVE, FOREIGN].freeze
 
       # Error messages
       ERROR_INVALID_PNN = "Invalid PNN string: %s"
-      ERROR_INVALID_NATIVE = "Native must be true or false: %s"
+      ERROR_INVALID_DERIVATION = "Derivation must be true (native) or false (foreign), got: %s"
+
+      # @return [Symbol] the piece type (:A to :Z)
+      def type
+        @piece.type
+      end
+
+      # @return [Symbol] the player side (:first or :second)
+      def side
+        @piece.side
+      end
+
+      # @return [Symbol] the piece state (:normal, :enhanced, or :diminished)
+      def state
+        @piece.state
+      end
 
-      # @return [Boolean] whether the piece has native style
+      # @return [Boolean] the style derivation (true for native, false for foreign)
       attr_reader :native
-      alias native? native
 
-      # Create a new piece instance with style information
+      # Create a new piece instance
       #
-      # @param letter [String] single ASCII letter (a-z or A-Z)
-      # @param native [Boolean] whether the piece has native style
+      # @param type [Symbol] piece type (:A to :Z)
+      # @param side [Symbol] player side (:first or :second)
+      # @param state [Symbol] piece state (:normal, :enhanced, or :diminished)
+      # @param native [Boolean] style derivation (true for native, false for foreign)
       # @raise [ArgumentError] if parameters are invalid
-      def initialize(letter, native: true, **)
-        raise ::ArgumentError, format(ERROR_INVALID_NATIVE, native) unless [true, false].include?(native)
-
+      # @example
+      #   Piece.new(:K, :first, :normal, true)
+      #   Piece.new(:P, :second, :enhanced, false)
+      def initialize(type, side, state = Pin::Piece::NORMAL_STATE, native = NATIVE)
+        # Validate using PIN class methods for type, side, and state
+        Pin::Piece.validate_type(type)
+        Pin::Piece.validate_side(side)
+        Pin::Piece.validate_state(state)
+        self.class.validate_derivation(native)
+
+        @piece = Pin::Piece.new(type, side, state)
         @native = native
-        super(letter, **)
+
+        freeze
       end
 
       # Parse a PNN string into a Piece object
@@ -45,190 +83,359 @@ module Sashite
       # @return [Piece] new piece instance
       # @raise [ArgumentError] if the PNN string is invalid
       # @example
-      #   Pnn::Piece.parse("k")     # => #<Pnn::Piece letter="k" native=true>
-      #   Pnn::Piece.parse("k'")    # => #<Pnn::Piece letter="k" native=false>
-      #   Pnn::Piece.parse("+R'")   # => #<Pnn::Piece letter="R" enhanced=true native=false>
+      #   Pnn::Piece.parse("k")     # => #<Pnn::Piece type=:K side=:second state=:normal native=true>
+      #   Pnn::Piece.parse("+R'")   # => #<Pnn::Piece type=:R side=:first state=:enhanced native=false>
+      #   Pnn::Piece.parse("-p")    # => #<Pnn::Piece type=:P side=:second state=:diminished native=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
-        native = matches[:suffix] != FOREIGN_SUFFIX
+        # Check for derivation suffix
+        if string_value.end_with?(FOREIGN_SUFFIX)
+          pin_part = string_value[0...-1] # Remove the apostrophe
+          foreign = true
+        else
+          pin_part = string_value
+          foreign = false
+        end
+
+        # Validate and parse the PIN part using existing PIN logic
+        raise ::ArgumentError, format(ERROR_INVALID_PNN, string_value) unless Pin::Piece.valid?(pin_part)
+
+        pin_piece = Pin::Piece.parse(pin_part)
+        piece_native = !foreign
 
-        new(
-          letter,
-          native:     native,
-          enhanced:   enhanced,
-          diminished: diminished
-        )
+        new(pin_piece.type, pin_piece.side, pin_piece.state, piece_native)
+      end
+
+      # Check if a string is a valid PNN notation
+      #
+      # @param pnn_string [String] The string to validate
+      # @return [Boolean] true if valid PNN, false otherwise
+      #
+      # @example
+      #   Sashite::Pnn::Piece.valid?("K")    # => true
+      #   Sashite::Pnn::Piece.valid?("+R'")  # => true
+      #   Sashite::Pnn::Piece.valid?("-p")   # => true
+      #   Sashite::Pnn::Piece.valid?("KK")   # => false
+      #   Sashite::Pnn::Piece.valid?("++K")  # => false
+      def self.valid?(pnn_string)
+        return false unless pnn_string.is_a?(::String)
+        return false if pnn_string.empty?
+
+        # Check for derivation suffix
+        if pnn_string.end_with?(FOREIGN_SUFFIX)
+          pin_part = pnn_string[0...-1] # Remove the apostrophe
+          return false if pin_part.empty? # Can't have just an apostrophe
+        else
+          pin_part = pnn_string
+        end
+
+        # Validate the PIN part using existing PIN validation
+        Pin::Piece.valid?(pin_part)
       end
 
       # Convert the piece to its PNN string representation
       #
       # @return [String] PNN notation string
       # @example
-      #   piece.to_s  # => "k"
-      #   piece.to_s  # => "k'"
       #   piece.to_s  # => "+R'"
+      #   piece.to_s  # => "-p"
+      #   piece.to_s  # => "K"
       def to_s
-        pin_string = super
-        suffix = native? ? "" : FOREIGN_SUFFIX
-        "#{pin_string}#{suffix}"
+        "#{prefix}#{letter}#{suffix}"
       end
 
-      # Convert the piece to its underlying PIN representation
+      # Get the letter representation (inherited from PIN logic)
       #
-      # @return [String] PIN notation string without style information
-      def to_pin
-        nativize.to_s
+      # @return [String] letter representation combining type and side
+      def letter
+        @piece.letter
       end
 
-      # Check if the piece has foreign style
+      # Get the prefix representation (inherited from PIN logic)
       #
-      # @return [Boolean] true if foreign style
-      def foreign?
-        !native?
+      # @return [String] prefix representing the state
+      def prefix
+        @piece.prefix
+      end
+
+      # Get the suffix representation
+      #
+      # @return [String] suffix representing the derivation
+      def suffix
+        native? ? NATIVE_SUFFIX : FOREIGN_SUFFIX
+      end
+
+      # Create a new piece with enhanced state
+      #
+      # @return [Piece] new piece instance with enhanced state
+      # @example
+      #   piece.enhance  # (:K, :first, :normal, true) => (:K, :first, :enhanced, true)
+      def enhance
+        return self if enhanced?
+
+        self.class.new(type, side, Pin::Piece::ENHANCED_STATE, native)
+      end
+
+      # Create a new piece without enhanced state
+      #
+      # @return [Piece] new piece instance without enhanced state
+      # @example
+      #   piece.unenhance  # (:K, :first, :enhanced, true) => (:K, :first, :normal, true)
+      def unenhance
+        return self unless enhanced?
+
+        self.class.new(type, side, Pin::Piece::NORMAL_STATE, native)
       end
 
-      # Create a new piece with native style
+      # Create a new piece with diminished state
+      #
+      # @return [Piece] new piece instance with diminished state
+      # @example
+      #   piece.diminish  # (:K, :first, :normal, true) => (:K, :first, :diminished, true)
+      def diminish
+        return self if diminished?
+
+        self.class.new(type, side, Pin::Piece::DIMINISHED_STATE, native)
+      end
+
+      # Create a new piece without diminished state
+      #
+      # @return [Piece] new piece instance without diminished state
+      # @example
+      #   piece.undiminish  # (:K, :first, :diminished, true) => (:K, :first, :normal, true)
+      def undiminish
+        return self unless diminished?
+
+        self.class.new(type, side, Pin::Piece::NORMAL_STATE, native)
+      end
+
+      # Create a new piece with normal state (no modifiers)
+      #
+      # @return [Piece] new piece instance with normal state
+      # @example
+      #   piece.normalize  # (:K, :first, :enhanced, true) => (:K, :first, :normal, true)
+      def normalize
+        return self if normal?
+
+        self.class.new(type, side, Pin::Piece::NORMAL_STATE, native)
+      end
+
+      # Create a new piece with opposite side
+      #
+      # @return [Piece] new piece instance with opposite side
+      # @example
+      #   piece.flip  # (:K, :first, :normal, true) => (:K, :second, :normal, true)
+      def flip
+        self.class.new(type, opposite_side, state, native)
+      end
+
+      # Create a new piece with foreign style (derivation marker)
+      #
+      # @return [Piece] new piece instance with foreign style
+      # @example
+      #   piece.derive  # (:K, :first, :normal, true) => (:K, :first, :normal, false)
+      def derive
+        return self if derived?
+
+        self.class.new(type, side, state, FOREIGN)
+      end
+
+      # Create a new piece with native style (no derivation marker)
       #
       # @return [Piece] new piece instance with native style
       # @example
-      #   piece.nativize  # k' => k
-      def nativize
+      #   piece.underive  # (:K, :first, :normal, false) => (:K, :first, :normal, true)
+      def underive
         return self if native?
 
-        self.class.new(
-          letter,
-          native:     true,
-          enhanced:   enhanced?,
-          diminished: diminished?
-        )
+        self.class.new(type, side, state, NATIVE)
       end
 
-      # Create a new piece with foreign style
+      # Create a new piece with a different type (keeping same side, state, and derivation)
       #
-      # @return [Piece] new piece instance with foreign style
+      # @param new_type [Symbol] new type (:A to :Z)
+      # @return [Piece] new piece instance with different type
       # @example
-      #   piece.foreignize  # k => k'
-      def foreignize
-        return self if foreign?
+      #   piece.with_type(:Q)  # (:K, :first, :normal, true) => (:Q, :first, :normal, true)
+      def with_type(new_type)
+        Pin::Piece.validate_type(new_type)
+        return self if type == new_type
 
-        self.class.new(
-          letter,
-          native:     false,
-          enhanced:   enhanced?,
-          diminished: diminished?
-        )
+        self.class.new(new_type, side, state, native)
       end
 
-      # Create a new piece with toggled style
+      # Create a new piece with a different side (keeping same type, state, and derivation)
       #
-      # @return [Piece] new piece instance with opposite style
+      # @param new_side [Symbol] :first or :second
+      # @return [Piece] new piece instance with different side
       # @example
-      #   piece.toggle_style  # k => k', k' => k
-      def toggle_style
-        native? ? foreignize : nativize
+      #   piece.with_side(:second)  # (:K, :first, :normal, true) => (:K, :second, :normal, true)
+      def with_side(new_side)
+        Pin::Piece.validate_side(new_side)
+        return self if side == new_side
+
+        self.class.new(type, new_side, state, native)
       end
 
-      # Override parent methods to maintain PNN type in return values
+      # Create a new piece with a different state (keeping same type, side, and derivation)
+      #
+      # @param new_state [Symbol] :normal, :enhanced, or :diminished
+      # @return [Piece] new piece instance with different state
+      # @example
+      #   piece.with_state(:enhanced)  # (:K, :first, :normal, true) => (:K, :first, :enhanced, true)
+      def with_state(new_state)
+        Pin::Piece.validate_state(new_state)
+        return self if state == new_state
 
-      def enhance
-        return self if enhanced?
+        self.class.new(type, side, new_state, native)
+      end
 
-        self.class.new(
-          letter,
-          native:     native?,
-          enhanced:   true,
-          diminished: false
-        )
+      # Create a new piece with a different derivation (keeping same type, side, and state)
+      #
+      # @param new_native [Boolean] true for native, false for foreign
+      # @return [Piece] new piece instance with different derivation
+      # @example
+      #   piece.with_derivation(false)  # (:K, :first, :normal, true) => (:K, :first, :normal, false)
+      def with_derivation(new_native)
+        self.class.validate_derivation(new_native)
+        return self if native == new_native
+
+        self.class.new(type, side, state, new_native)
       end
 
-      def unenhance
-        return self unless enhanced?
+      # Check if the piece has enhanced state
+      #
+      # @return [Boolean] true if enhanced
+      def enhanced?
+        @piece.enhanced?
+      end
 
-        self.class.new(
-          letter,
-          native:     native?,
-          enhanced:   false,
-          diminished: diminished?
-        )
+      # Check if the piece has diminished state
+      #
+      # @return [Boolean] true if diminished
+      def diminished?
+        @piece.diminished?
       end
 
-      def diminish
-        return self if diminished?
+      # Check if the piece has normal state (no modifiers)
+      #
+      # @return [Boolean] true if no modifiers are present
+      def normal?
+        @piece.normal?
+      end
 
-        self.class.new(
-          letter,
-          native:     native?,
-          enhanced:   false,
-          diminished: true
-        )
+      # Check if the piece belongs to the first player
+      #
+      # @return [Boolean] true if first player
+      def first_player?
+        @piece.first_player?
       end
 
-      def undiminish
-        return self unless diminished?
+      # Check if the piece belongs to the second player
+      #
+      # @return [Boolean] true if second player
+      def second_player?
+        @piece.second_player?
+      end
 
-        self.class.new(
-          letter,
-          native:     native?,
-          enhanced:   enhanced?,
-          diminished: false
-        )
+      # Check if the piece has native style (no derivation marker)
+      #
+      # @return [Boolean] true if native style
+      def native?
+        native == NATIVE
       end
 
-      def normalize
-        return self if normal?
+      # Check if the piece has foreign style (derivation marker)
+      #
+      # @return [Boolean] true if foreign style
+      def derived?
+        native == FOREIGN
+      end
 
-        self.class.new(
-          letter,
-          native: native?
-        )
+      # Alias for derived? to match the specification terminology
+      alias foreign? derived?
+
+      # Check if this piece is the same type as another (ignoring side, state, and derivation)
+      #
+      # @param other [Piece] piece to compare with
+      # @return [Boolean] true if same type
+      # @example
+      #   king1.same_type?(king2)  # (:K, :first, :normal, true) and (:K, :second, :enhanced, false) => true
+      def same_type?(other)
+        return false unless other.is_a?(self.class)
+
+        @piece.same_type?(other.instance_variable_get(:@piece))
       end
 
-      def flip
-        flipped_letter = letter.swapcase
+      # Check if this piece belongs to the same side as another
+      #
+      # @param other [Piece] piece to compare with
+      # @return [Boolean] true if same side
+      def same_side?(other)
+        return false unless other.is_a?(self.class)
+
+        @piece.same_side?(other.instance_variable_get(:@piece))
+      end
+
+      # Check if this piece has the same state as another
+      #
+      # @param other [Piece] piece to compare with
+      # @return [Boolean] true if same state
+      def same_state?(other)
+        return false unless other.is_a?(self.class)
 
-        self.class.new(
-          flipped_letter,
-          native:     native?,
-          enhanced:   enhanced?,
-          diminished: diminished?
-        )
+        @piece.same_state?(other.instance_variable_get(:@piece))
       end
 
-      # Custom equality comparison including style
+      # Check if this piece has the same style derivation as another
+      #
+      # @param other [Piece] piece to compare with
+      # @return [Boolean] true if same style derivation
+      def same_style?(other)
+        return false unless other.is_a?(self.class)
+
+        native == other.native
+      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)
 
-        super && native? == other.native?
+        @piece == other.instance_variable_get(:@piece) && native == other.native
       end
 
-      # Custom hash implementation including style
+      # Alias for == to ensure Set functionality works correctly
+      alias eql? ==
+
+      # Custom hash implementation for use in collections
       #
       # @return [Integer] hash value
       def hash
-        [super, @native].hash
+        [self.class, @piece, native].hash
       end
 
-      # Match PNN pattern against string
+      # Validate that the derivation is a valid boolean
       #
-      # @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
+      # @param derivation [Boolean] the derivation to validate
+      # @raise [ArgumentError] if invalid
+      def self.validate_derivation(derivation)
+        return if VALID_DERIVATIONS.include?(derivation)
 
-        raise ::ArgumentError, format(ERROR_INVALID_PNN, string)
+        raise ::ArgumentError, format(ERROR_INVALID_DERIVATION, derivation.inspect)
       end
 
-      private_class_method :match_pattern
+      private
+
+      # Get the opposite side of the current piece
+      #
+      # @return [Symbol] :first if current side is :second, :second if current side is :first
+      def opposite_side
+        @piece.send(:opposite_side)
+      end
     end
   end
 end

data/lib/sashite/pnn.rb

@@ -5,43 +5,36 @@ require_relative "pnn/piece"
 module Sashite
   # PNN (Piece Name Notation) implementation for Ruby
   #
-  # Extends PIN to provide style-aware piece representation in abstract strategy board games.
-  # PNN adds a derivation marker that distinguishes pieces by their style origin, enabling
-  # cross-style game scenarios and piece origin tracking.
+  # Provides style-aware ASCII-based format for representing pieces in abstract strategy board games.
+  # PNN extends PIN by adding derivation markers that distinguish pieces by their style origin,
+  # enabling cross-style game scenarios and piece origin tracking.
   #
-  # Format: <pin>[<suffix>]
-  # - PIN component: [<state>]<letter> (state modifier + letter)
-  # - Suffix: "'" for foreign style, none for native style
+  # Format: [<state>]<letter>[<derivation>]
+  # - State modifier: "+" (enhanced), "-" (diminished), or none (normal)
+  # - Letter: A-Z (first player), a-z (second player)
+  # - Derivation marker: "'" (foreign style), or none (native style)
   #
   # Examples:
-  #   "K"   - First player king (native style)
-  #   "K'"  - First player king (foreign style)
-  #   "+R"  - First player rook, enhanced state (native style)
-  #   "+R'" - First player rook, enhanced state (foreign style)
-  #   "-p'" - Second player pawn, diminished state (foreign style)
+  #   "K"   - First player king (native style, normal state)
+  #   "k'"  - Second player king (foreign style, normal state)
+  #   "+R'" - First player rook (foreign style, enhanced state)
+  #   "-p"  - Second player pawn (native style, diminished state)
   #
   # See: https://sashite.dev/specs/pnn/1.0.0/
   module Pnn
-    # Regular expression for PNN validation
-    # Matches: optional state modifier, letter, optional derivation marker
-    PNN_REGEX = /\A[-+]?[A-Za-z]'?\z/
-
     # Check if a string is a valid PNN notation
     #
-    # @param pnn [String] The string to validate
+    # @param pnn_string [String] The string to validate
     # @return [Boolean] true if valid PNN, false otherwise
     #
     # @example
-    #   Sashite::Pnn.valid?("K")    # => true
-    #   Sashite::Pnn.valid?("K'")   # => true
-    #   Sashite::Pnn.valid?("+R'")  # => true
-    #   Sashite::Pnn.valid?("-p'")  # => true
-    #   Sashite::Pnn.valid?("K''")  # => false
-    #   Sashite::Pnn.valid?("++K'") # => false
-    def self.valid?(pnn)
-      return false unless pnn.is_a?(::String)
-
-      pnn.match?(PNN_REGEX)
+    #   Sashite::Pnn.valid?("K")     # => true
+    #   Sashite::Pnn.valid?("+R'")   # => true
+    #   Sashite::Pnn.valid?("-p")    # => true
+    #   Sashite::Pnn.valid?("KK")    # => false
+    #   Sashite::Pnn.valid?("++K")   # => false
+    def self.valid?(pnn_string)
+      Piece.valid?(pnn_string)
     end
 
     # Parse a PNN string into a Piece object
@@ -50,11 +43,27 @@ module Sashite
     # @return [Pnn::Piece] new piece instance
     # @raise [ArgumentError] if the PNN string is invalid
     # @example
-    #   Sashite::Pnn.parse("K")     # => #<Pnn::Piece letter="K" native=true>
-    #   Sashite::Pnn.parse("K'")    # => #<Pnn::Piece letter="K" native=false>
-    #   Sashite::Pnn.parse("+R'")   # => #<Pnn::Piece letter="R" enhanced=true native=false>
+    #   Sashite::Pnn.parse("K")     # => #<Pnn::Piece type=:K side=:first state=:normal native=true>
+    #   Sashite::Pnn.parse("+R'")   # => #<Pnn::Piece type=:R side=:first state=:enhanced native=false>
+    #   Sashite::Pnn.parse("-p")    # => #<Pnn::Piece type=:P side=:second state=:diminished native=true>
     def self.parse(pnn_string)
       Piece.parse(pnn_string)
     end
+
+    # Create a new piece instance
+    #
+    # @param type [Symbol] piece type (:A to :Z)
+    # @param side [Symbol] player side (:first or :second)
+    # @param state [Symbol] piece state (:normal, :enhanced, or :diminished)
+    # @param native [Boolean] style derivation (true for native, false for foreign)
+    # @return [Pnn::Piece] new piece instance
+    # @raise [ArgumentError] if parameters are invalid
+    # @example
+    #   Sashite::Pnn.piece(:K, :first, :normal, true)      # => #<Pnn::Piece type=:K side=:first state=:normal native=true>
+    #   Sashite::Pnn.piece(:R, :first, :enhanced, false)   # => #<Pnn::Piece type=:R side=:first state=:enhanced native=false>
+    #   Sashite::Pnn.piece(:P, :second, :diminished, true) # => #<Pnn::Piece type=:P side=:second state=:diminished native=true>
+    def self.piece(type, side, state = Sashite::Pin::Piece::NORMAL_STATE, native = Piece::NATIVE)
+      Piece.new(type, side, state, native)
+    end
   end
 end