feen 5.0.0.beta9 → 5.0.0.beta10

data/lib/feen/dumper/pieces_in_hand.rb

@@ -1,48 +1,47 @@
 # frozen_string_literal: true
 
+require "pnn"
+
 module Feen
   module Dumper
     # Handles conversion of pieces in hand data to FEEN notation string
     module PiecesInHand
       # Error messages for validation
       ERRORS = {
-        invalid_type:   "Piece at index %d must be a String, got %s",
-        invalid_format: "Piece at index %d must be base form only (single letter): '%s'",
-        has_modifiers:  "Piece at index %d cannot contain modifiers: '%s'. Pieces in hand must be base form only"
+        invalid_type: "Piece at index %d must be a String, got %s",
+        invalid_pnn:  "Piece at index %d must be valid PNN notation: '%s'"
       }.freeze
 
       # Converts an array of piece identifiers to a FEEN-formatted pieces in hand string
       #
-      # @param piece_chars [Array<String>] Array of piece identifiers in base form only (e.g., ["P", "p", "B", "B", "p"])
-      # @return [String] FEEN-formatted pieces in hand string following the format:
+      # @param piece_chars [Array<String>] Array of piece identifiers following PNN notation.
+      #   May include modifiers (per FEEN v1.0.0 specification): prefixes (+, -) and suffixes (')
+      # @return [String] FEEN-formatted pieces in hand string following the canonical sorting:
       #   - Groups pieces by case: uppercase first, then lowercase, separated by "/"
-      #   - Within each group, sorts by quantity (descending), then alphabetically (ascending)
+      #   - Within each group, sorts by quantity (descending), then base letter (ascending),
+      #     then prefix (-, +, none), then suffix (none, ')
       #   - Uses count notation for quantities > 1 (e.g., "3P" instead of "PPP")
-      # @raise [ArgumentError] If any piece identifier is invalid or contains modifiers
+      # @raise [ArgumentError] If any piece identifier is invalid PNN notation
+      #
+      # @example Valid pieces in hand with modifiers
+      #   PiecesInHand.dump("+B", "+B", "B", "B", "B", "B", "B", "K", "-P", "-P", "-P", "-P'", "+P'", "+P'", "+P'", "P", "P", "P", "P", "P", "P", "P", "P", "P", "R", "S", "S", "S'", "b", "p")
+      #   # => "2+B5BK3-P-P'3+P'9PR2SS'/bp"
       #
-      # @example Valid pieces in hand
+      # @example Valid pieces in hand without modifiers
       #   PiecesInHand.dump("P", "P", "P", "B", "B", "p", "p", "p", "p", "p")
       #   # => "3P2B/5p"
       #
-      # @example Valid pieces in hand with mixed order
-      #   PiecesInHand.dump("p", "P", "B")
-      #   # => "BP/p"
-      #
       # @example No pieces in hand
       #   PiecesInHand.dump()
       #   # => "/"
-      #
-      # @example Invalid - modifiers not allowed
-      #   PiecesInHand.dump("+P", "p")
-      #   # => ArgumentError: Piece at index 0 cannot contain modifiers: '+P'
       def self.dump(*piece_chars)
-        # Validate each piece character according to FEEN specification (base form only)
+        # Validate each piece character according to PNN specification
         validated_chars = validate_piece_chars(piece_chars)
 
         # Group pieces by case
         uppercase_pieces, lowercase_pieces = group_pieces_by_case(validated_chars)
 
-        # Format each group according to FEEN specification
+        # Format each group according to FEEN canonical sorting specification
         uppercase_formatted = format_pieces_group(uppercase_pieces)
         lowercase_formatted = format_pieces_group(lowercase_pieces)
 
@@ -50,30 +49,36 @@ module Feen
         "#{uppercase_formatted}/#{lowercase_formatted}"
       end
 
-      # Groups pieces by case (uppercase vs lowercase)
+      # Groups pieces by case (uppercase vs lowercase base letter)
       #
       # @param pieces [Array<String>] Array of validated piece identifiers
       # @return [Array<Array<String>, Array<String>>] Two arrays: [uppercase_pieces, lowercase_pieces]
       private_class_method def self.group_pieces_by_case(pieces)
-        uppercase_pieces = pieces.grep(/[A-Z]/)
-        lowercase_pieces = pieces.grep(/[a-z]/)
+        uppercase_pieces = pieces.select { |piece| extract_base_letter(piece).match?(/[A-Z]/) }
+        lowercase_pieces = pieces.select { |piece| extract_base_letter(piece).match?(/[a-z]/) }
 
         [uppercase_pieces, lowercase_pieces]
       end
 
-      # Formats a group of pieces according to FEEN specification
+      # Formats a group of pieces according to FEEN canonical sorting specification
+      #
+      # Sorting algorithm (FEEN v1.0.0):
+      # 1. By quantity (descending)
+      # 2. By base letter (ascending)
+      # 3. By prefix (-, +, none)
+      # 4. By suffix (none, ')
       #
       # @param pieces [Array<String>] Array of pieces from the same case group
-      # @return [String] Formatted string for this group (e.g., "3P2B", "5pq")
+      # @return [String] Formatted string for this group (e.g., "2+B5BK3-P-P'3+P'9PR2SS'")
       private_class_method def self.format_pieces_group(pieces)
         return "" if pieces.empty?
 
-        # Count occurrences of each piece type
-        piece_counts = pieces.each_with_object(Hash.new(0)) do |piece, counts|
+        # Count occurrences of each unique piece (including modifiers)
+        piece_counts = pieces.each_with_object(::Hash.new(0)) do |piece, counts|
           counts[piece] += 1
         end
 
-        # Sort by count (descending) then alphabetically (ascending)
+        # Sort according to FEEN canonical sorting algorithm
         sorted_pieces = piece_counts.sort do |a, b|
           piece_a, count_a = a
           piece_b, count_b = b
@@ -82,8 +87,22 @@ module Feen
           count_comparison = count_b <=> count_a
           next count_comparison unless count_comparison.zero?
 
-          # Secondary sort: by piece name (ascending)
-          piece_a <=> piece_b
+          # Secondary sort: by base letter (ascending)
+          base_a = extract_base_letter(piece_a)
+          base_b = extract_base_letter(piece_b)
+          base_comparison = base_a <=> base_b
+          next base_comparison unless base_comparison.zero?
+
+          # Tertiary sort: by prefix (-, +, none)
+          prefix_a = extract_prefix(piece_a)
+          prefix_b = extract_prefix(piece_b)
+          prefix_comparison = compare_prefixes(prefix_a, prefix_b)
+          next prefix_comparison unless prefix_comparison.zero?
+
+          # Quaternary sort: by suffix (none, ')
+          suffix_a = extract_suffix(piece_a)
+          suffix_b = extract_suffix(piece_b)
+          compare_suffixes(suffix_a, suffix_b)
         end
 
         # Format each piece with its count
@@ -96,34 +115,76 @@ module Feen
         end.join
       end
 
-      # Validates all piece characters according to FEEN specification (base form only)
+      # Extracts the base letter from a PNN piece identifier
+      #
+      # @param piece [String] PNN piece identifier (e.g., "+P'", "-R", "K")
+      # @return [String] Base letter (e.g., "P", "R", "K")
+      private_class_method def self.extract_base_letter(piece)
+        piece.match(/[a-zA-Z]/)[0]
+      end
+
+      # Extracts the prefix from a PNN piece identifier
+      #
+      # @param piece [String] PNN piece identifier
+      # @return [String, nil] Prefix ("+" or "-") or nil if no prefix
+      private_class_method def self.extract_prefix(piece)
+        match = piece.match(/\A([+-])/)
+        match ? match[1] : nil
+      end
+
+      # Extracts the suffix from a PNN piece identifier
+      #
+      # @param piece [String] PNN piece identifier
+      # @return [String, nil] Suffix ("'") or nil if no suffix
+      private_class_method def self.extract_suffix(piece)
+        piece.end_with?("'") ? "'" : nil
+      end
+
+      # Compares prefixes according to FEEN sorting order: -, +, none
+      #
+      # @param prefix_a [String, nil] First prefix
+      # @param prefix_b [String, nil] Second prefix
+      # @return [Integer] Comparison result (-1, 0, 1)
+      private_class_method def self.compare_prefixes(prefix_a, prefix_b)
+        prefix_order = { "-" => 0, "+" => 1, nil => 2 }
+        prefix_order[prefix_a] <=> prefix_order[prefix_b]
+      end
+
+      # Compares suffixes according to FEEN sorting order: none, '
+      #
+      # @param suffix_a [String, nil] First suffix
+      # @param suffix_b [String, nil] Second suffix
+      # @return [Integer] Comparison result (-1, 0, 1)
+      private_class_method def self.compare_suffixes(suffix_a, suffix_b)
+        suffix_order = { nil => 0, "'" => 1 }
+        suffix_order[suffix_a] <=> suffix_order[suffix_b]
+      end
+
+      # Validates all piece characters according to PNN specification
       #
       # @param piece_chars [Array<Object>] Array of piece character candidates
       # @return [Array<String>] Array of validated piece characters
-      # @raise [ArgumentError] If any piece character is invalid or contains modifiers
+      # @raise [ArgumentError] If any piece character is invalid PNN notation
       private_class_method def self.validate_piece_chars(piece_chars)
         piece_chars.each_with_index.map do |char, index|
           validate_piece_char(char, index)
         end
       end
 
-      # Validates a single piece character according to FEEN specification
-      # For pieces in hand, only base form is allowed: single letter (a-z or A-Z)
-      # NO modifiers (+, -, ') are allowed in pieces in hand
+      # Validates a single piece character according to PNN specification
+      # Per FEEN v1.0.0: pieces in hand may include PNN modifiers (prefixes and suffixes)
       #
       # @param char [Object] Piece character candidate
       # @param index [Integer] Index of the character in the original array
       # @return [String] Validated piece character
-      # @raise [ArgumentError] If the piece character is invalid or contains modifiers
+      # @raise [ArgumentError] If the piece character is invalid PNN notation
       private_class_method def self.validate_piece_char(char, index)
         # Validate type
-        raise ArgumentError, format(ERRORS[:invalid_type], index, char.class) unless char.is_a?(String)
-
-        # Check for forbidden modifiers first (clearer error message)
-        raise ArgumentError, format(ERRORS[:has_modifiers], index, char) if char.match?(/[+\-']/)
+        raise ::ArgumentError, format(ERRORS[:invalid_type], index, char.class) unless char.is_a?(::String)
 
-        # Validate format: must be exactly one letter (base form only)
-        raise ArgumentError, format(ERRORS[:invalid_format], index, char) unless char.match?(/\A[a-zA-Z]\z/)
+        # Validate PNN format using the PNN gem
+        # @see https://rubygems.org/gems/pnn
+        raise ::ArgumentError, format(ERRORS[:invalid_pnn], index, char) unless ::Pnn.valid?(char)
 
         char
       end

data/lib/feen/dumper/style_turn.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "sashite-snn"
+
+module Feen
+  module Dumper
+    # Handles conversion of style turn data to FEEN notation string
+    module StyleTurn
+      # Error messages for validation
+      ERRORS = {
+        invalid_type: "%s must be a String, got %s",
+        empty_string: "%s cannot be empty",
+        invalid_snn:  "%s must be valid SNN notation: %s",
+        same_casing:  "One style must be uppercase and the other lowercase"
+      }.freeze
+
+      # Converts the active and inactive style identifiers to a FEEN-formatted style turn string
+      #
+      # @param active_style [String] Identifier for the player to move and their style
+      # @param inactive_style [String] Identifier for the opponent and their style
+      # @return [String] FEEN-formatted style turn string
+      # @raise [ArgumentError] If the style identifiers are invalid
+      #
+      # @example Valid style turn
+      #   StyleTurn.dump("CHESS", "chess")
+      #   # => "CHESS/chess"
+      #
+      # @example Valid style turn with variants
+      #   StyleTurn.dump("CHESS960", "makruk")
+      #   # => "CHESS960/makruk"
+      #
+      # @example Invalid - same casing
+      #   StyleTurn.dump("CHESS", "MAKRUK")
+      #   # => ArgumentError: One style must be uppercase and the other lowercase
+      def self.dump(active_style, inactive_style)
+        validate_styles(active_style, inactive_style)
+        "#{active_style}/#{inactive_style}"
+      end
+
+      # Validates the style identifiers according to SNN specification
+      #
+      # @param active [String] The active player's style identifier
+      # @param inactive [String] The inactive player's style identifier
+      # @raise [ArgumentError] If the style identifiers are invalid
+      # @return [void]
+      private_class_method def self.validate_styles(active, inactive)
+        # Validate basic type and SNN format
+        [["Active style", active], ["Inactive style", inactive]].each do |name, style|
+          # Type validation
+          raise ArgumentError, format(ERRORS[:invalid_type], name, style.class) unless style.is_a?(::String)
+
+          # Empty validation
+          raise ArgumentError, format(ERRORS[:empty_string], name) if style.empty?
+
+          # SNN format validation using the sashite-snn gem
+          # @see https://rubygems.org/gems/sashite-snn
+          raise ArgumentError, format(ERRORS[:invalid_snn], name, style) unless ::Sashite::Snn.valid?(style)
+        end
+
+        # Casing difference validation
+        active_is_uppercase = active == active.upcase
+        inactive_is_uppercase = inactive == inactive.upcase
+
+        # Both styles must have different casing
+        return unless active_is_uppercase == inactive_is_uppercase
+
+        raise ArgumentError, ERRORS[:same_casing]
+      end
+    end
+  end
+end

data/lib/feen/dumper.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative File.join("dumper", "games_turn")
+require_relative File.join("dumper", "style_turn")
 require_relative File.join("dumper", "piece_placement")
 require_relative File.join("dumper", "pieces_in_hand")
 
@@ -14,7 +14,7 @@ module Feen
     # Error messages for validation
     ERRORS = {
       invalid_piece_placement_type: "Piece placement must be an Array, got %s",
-      invalid_games_turn_type:      "Games turn must be an Array with exactly two elements, got %s",
+      invalid_style_turn_type:      "Style turn must be an Array with exactly two elements, got %s",
       invalid_pieces_in_hand_type:  "Pieces in hand must be an Array, got %s"
     }.freeze
 
@@ -33,52 +33,52 @@ module Feen
     #       ["R", "N", "B", "Q", "K", "B", "N", "R"]
     #     ],
     #     pieces_in_hand: [],
-    #     games_turn: ["CHESS", "chess"]
+    #     style_turn: ["CHESS", "chess"]
     #   )
     #   # => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR / CHESS/chess"
     #
     # @param piece_placement [Array] Board position data structure representing the spatial
     #                                distribution of pieces across the board, where each cell
     #                                is represented by a String (or empty string for empty cells)
-    # @param pieces_in_hand [Array<String>] Pieces available for dropping onto the board,
-    #                                    each represented as a single character string (base form only)
-    # @param games_turn [Array<String>] A two-element array where the first element is the
-    #                                  active player's variant and the second is the inactive player's variant
+    # @param pieces_in_hand [Array<String>] Pieces available for dropping onto the board.
+    #                                    May include PNN modifiers (per FEEN v1.0.0 specification)
+    # @param style_turn [Array<String>] A two-element array where the first element is the
+    #                                  active player's style and the second is the inactive player's style
     # @return [String] Complete FEEN string representation compliant with the specification
     # @raise [ArgumentError] If any input parameter is invalid
     # @see https://sashite.dev/documents/feen/1.0.0/ FEEN Specification v1.0.0
-    def self.dump(piece_placement:, pieces_in_hand:, games_turn:)
+    def self.dump(piece_placement:, pieces_in_hand:, style_turn:)
       # Validate input types
-      validate_inputs(piece_placement, games_turn, pieces_in_hand)
+      validate_inputs(piece_placement, style_turn, pieces_in_hand)
 
       # Process each component with appropriate submodule and combine into final FEEN string
       [
         PiecePlacement.dump(piece_placement),
         PiecesInHand.dump(*pieces_in_hand),
-        GamesTurn.dump(*games_turn)
+        StyleTurn.dump(*style_turn)
       ].join(FIELD_SEPARATOR)
     end
 
     # Validates the input parameters for type and structure
     #
     # @param piece_placement [Object] Piece placement parameter to validate
-    # @param games_turn [Object] Games turn parameter to validate
+    # @param style_turn [Object] Style turn parameter to validate
     # @param pieces_in_hand [Object] Pieces in hand parameter to validate
     # @raise [ArgumentError] If any parameter is invalid
     # @return [void]
-    private_class_method def self.validate_inputs(piece_placement, games_turn, pieces_in_hand)
+    private_class_method def self.validate_inputs(piece_placement, style_turn, pieces_in_hand)
       # Validate piece_placement is an Array
-      unless piece_placement.is_a?(Array)
+      unless piece_placement.is_a?(::Array)
         raise ArgumentError, format(ERRORS[:invalid_piece_placement_type], piece_placement.class)
       end
 
-      # Validate games_turn is an Array with exactly 2 elements
-      unless games_turn.is_a?(Array) && games_turn.size == 2
-        raise ArgumentError, format(ERRORS[:invalid_games_turn_type], games_turn.inspect)
+      # Validate style_turn is an Array with exactly 2 elements
+      unless style_turn.is_a?(::Array) && style_turn.size == 2
+        raise ArgumentError, format(ERRORS[:invalid_style_turn_type], style_turn.inspect)
       end
 
       # Validate pieces_in_hand is an Array
-      return if pieces_in_hand.is_a?(Array)
+      return if pieces_in_hand.is_a?(::Array)
 
       raise ArgumentError, format(ERRORS[:invalid_pieces_in_hand_type], pieces_in_hand.class)
     end

data/lib/feen/parser/pieces_in_hand.rb

@@ -1,31 +1,31 @@
 # frozen_string_literal: true
 
+require "pnn"
+
 module Feen
   module Parser
     # Handles parsing of the pieces in hand section of a FEEN string.
     # Pieces in hand represent pieces available for dropping onto the board.
-    # According to FEEN specification, pieces in hand MUST be in base form only (no modifiers).
+    # According to FEEN v1.0.0 specification, pieces in hand MAY include PNN modifiers.
     # Format: "UPPERCASE_PIECES/LOWERCASE_PIECES"
     module PiecesInHand
       # Error messages for validation
-      Errors = {
-        invalid_type:          "Pieces in hand must be a string, got %s",
-        empty_string:          "Pieces in hand string cannot be empty",
-        invalid_format:        "Invalid pieces in hand format: %s",
-        missing_separator:     "Pieces in hand format must contain exactly one '/' separator. Got: %s",
-        modifiers_not_allowed: 'Pieces in hand cannot contain modifiers: "%s"'
+      ERRORS = {
+        invalid_type:      "Pieces in hand must be a string, got %s",
+        empty_string:      "Pieces in hand string cannot be empty",
+        invalid_format:    "Invalid pieces in hand format: %s",
+        missing_separator: "Pieces in hand format must contain exactly one '/' separator. Got: %s",
+        invalid_pnn:       "Invalid PNN piece notation: '%s'",
+        invalid_count:     "Invalid count format: '%s'. Count cannot be '0' or '1'"
       }.freeze
 
-      # Base piece pattern: single letter only (no modifiers allowed in hand)
-      BASE_PIECE_PATTERN = /\A[a-zA-Z]\z/
-
       # Valid count pattern: 2-9 or any number with 2+ digits (no 0, 1, or leading zeros)
       VALID_COUNT_PATTERN = /\A(?:[2-9]|[1-9]\d+)\z/
 
-      # Pattern for piece with optional count in pieces in hand
+      # Pattern for piece with optional count in pieces in hand (with full PNN support)
       PIECE_WITH_COUNT_PATTERN = /(?:([2-9]|[1-9]\d+))?([-+]?[a-zA-Z]'?)/
 
-      # Complete validation pattern for pieces in hand string
+      # Complete validation pattern for pieces in hand string (with PNN modifier support)
       VALID_FORMAT_PATTERN = %r{\A
         (?:                                     # Uppercase section (optional)
           (?:(?:[2-9]|[1-9]\d+)?[-+]?[A-Z]'?)*  # Zero or more uppercase pieces with optional counts and modifiers
@@ -39,10 +39,10 @@ module Feen
       # Parses the pieces in hand section of a FEEN string.
       #
       # @param pieces_in_hand_str [String] FEEN pieces in hand string in format "UPPERCASE/lowercase"
-      # @return [Array<String>] Array of piece identifiers in base form only,
-      #   expanded based on their counts and sorted alphabetically.
-      #   Empty array if no pieces are in hand.
-      # @raise [ArgumentError] If the input string is invalid or contains modifiers
+      # @return [Array<String>] Array of piece identifiers (may include PNN modifiers),
+      #   expanded based on their counts. Pieces are returned in the order they appear
+      #   in the canonical FEEN string (not sorted alphabetically).
+      # @raise [ArgumentError] If the input string is invalid
       #
       # @example Parse no pieces in hand
       #   PiecesInHand.parse("/")
@@ -50,11 +50,11 @@ module Feen
       #
       # @example Parse pieces with case separation
       #   PiecesInHand.parse("3P2B/p")
-      #   # => ["B", "B", "P", "P", "P", "p"]
+      #   # => ["P", "P", "P", "B", "B", "p"]
       #
-      # @example Invalid - modifiers not allowed in hand
-      #   PiecesInHand.parse("+P/p")
-      #   # => ArgumentError: Pieces in hand cannot contain modifiers: '+P'
+      # @example Parse pieces with PNN modifiers
+      #   PiecesInHand.parse("2+B5BK3-P-P'3+P'9PR2SS'/bp")
+      #   # => ["+B", "+B", "B", "B", "B", "B", "B", "K", "-P", "-P", "-P", "-P'", "+P'", "+P'", "+P'", "P", "P", "P", "P", "P", "P", "P", "P", "P", "R", "S", "S", "S'", "b", "p"]
       def self.parse(pieces_in_hand_str)
         validate_input_type(pieces_in_hand_str)
         validate_format(pieces_in_hand_str)
@@ -65,13 +65,13 @@ module Feen
         # Split by the separator to get uppercase and lowercase sections
         uppercase_section, lowercase_section = pieces_in_hand_str.split("/", 2)
 
-        # Parse each section separately and validate no modifiers
+        # Parse each section separately
         uppercase_pieces = parse_pieces_section(uppercase_section || "", :uppercase)
         lowercase_pieces = parse_pieces_section(lowercase_section || "", :lowercase)
 
-        # Combine all pieces and sort them alphabetically
-        all_pieces = uppercase_pieces + lowercase_pieces
-        all_pieces.sort
+        # Combine all pieces in order (uppercase first, then lowercase)
+        # Do NOT sort - preserve the canonical order from the FEEN string
+        uppercase_pieces + lowercase_pieces
       end
 
       # Validates that the input is a non-empty string.
@@ -80,41 +80,23 @@ module Feen
       # @raise [ArgumentError] If input is not a string or is empty
       # @return [void]
       private_class_method def self.validate_input_type(str)
-        raise ::ArgumentError, format(Errors[:invalid_type], str.class) unless str.is_a?(::String)
-        raise ::ArgumentError, Errors[:empty_string] if str.empty?
+        raise ArgumentError, format(ERRORS[:invalid_type], str.class) unless str.is_a?(::String)
+        raise ArgumentError, ERRORS[:empty_string] if str.empty?
       end
 
       # Validates that the input string matches the expected format according to FEEN specification.
-      # Format must be: "UPPERCASE_PIECES/LOWERCASE_PIECES" with base pieces only (no modifiers).
+      # Format must be: "UPPERCASE_PIECES/LOWERCASE_PIECES" with optional PNN modifiers.
       #
       # @param str [String] Input string to validate
-      # @raise [ArgumentError] If format is invalid or contains modifiers
+      # @raise [ArgumentError] If format is invalid
       # @return [void]
       private_class_method def self.validate_format(str)
         # Must contain exactly one "/" separator
         parts_count = str.count("/")
-        raise ::ArgumentError, format(Errors[:missing_separator], parts_count) unless parts_count == 1
-
-        # Must match the overall pattern (including potential modifiers for detection)
-        raise ::ArgumentError, format(Errors[:invalid_format], str) unless str.match?(VALID_FORMAT_PATTERN)
+        raise ArgumentError, format(ERRORS[:missing_separator], parts_count) unless parts_count == 1
 
-        # Additional validation: check for any modifiers (forbidden in hand)
-        validate_no_modifiers(str)
-      end
-
-      # Validates that no modifiers are present in the pieces in hand string
-      #
-      # @param str [String] Input string to validate
-      # @raise [ArgumentError] If modifiers are found
-      # @return [void]
-      private_class_method def self.validate_no_modifiers(str)
-        # Check for any modifier characters that are forbidden in pieces in hand
-        return unless str.match?(/[+\-']/)
-
-        # Find the specific invalid piece to provide a better error message
-        invalid_pieces = str.scan(/(?:[2-9]|[1-9]\d+)?[-+]?[a-zA-Z]'?/).grep(/[+\-']/)
-
-        raise ::ArgumentError, format(Errors[:modifiers_not_allowed], invalid_pieces.first)
+        # Must match the overall pattern
+        raise ArgumentError, format(ERRORS[:invalid_format], str) unless str.match?(VALID_FORMAT_PATTERN)
       end
 
       # Parses a specific section (uppercase or lowercase) and returns expanded pieces
@@ -137,7 +119,7 @@ module Feen
       # @param section [String] FEEN pieces section string
       # @param case_type [Symbol] Either :uppercase or :lowercase
       # @return [Array<Hash>] Array of hashes with :piece and :count keys
-      # @raise [ArgumentError] If pieces don't match the expected case or contain modifiers
+      # @raise [ArgumentError] If pieces contain invalid PNN notation
       private_class_method def self.extract_pieces_with_counts_from_section(section, case_type)
         result = []
         position = 0
@@ -149,28 +131,27 @@ module Feen
           count_str, piece_with_modifiers = match.captures
           count = count_str ? count_str.to_i : 1
 
-          # Extract just the base piece (remove any modifiers)
-          base_piece = extract_base_piece(piece_with_modifiers)
-
-          # Validate piece is base form only (single letter)
-          unless base_piece.match?(BASE_PIECE_PATTERN)
-            raise ::ArgumentError, "Pieces in hand must be base form only: '#{base_piece}'"
+          # Validate PNN format using the PNN gem
+          # @see https://rubygems.org/gems/pnn
+          unless ::Pnn.valid?(piece_with_modifiers)
+            raise ::ArgumentError, format(ERRORS[:invalid_pnn], piece_with_modifiers)
           end
 
           # Validate count format
           if count_str && !count_str.match?(VALID_COUNT_PATTERN)
-            raise ::ArgumentError, "Invalid count format: '#{count_str}'. Count cannot be '0' or '1', use the piece without count instead"
+            raise ::ArgumentError, format(ERRORS[:invalid_count], count_str)
           end
 
-          # Validate that the piece matches the expected case
-          piece_case = base_piece.match?(/[A-Z]/) ? :uppercase : :lowercase
+          # Validate that the piece matches the expected case (based on base letter)
+          base_letter = extract_base_letter(piece_with_modifiers)
+          piece_case = base_letter.match?(/[A-Z]/) ? :uppercase : :lowercase
           unless piece_case == case_type
             case_name = case_type == :uppercase ? "uppercase" : "lowercase"
-            raise ::ArgumentError, "Piece '#{base_piece}' has wrong case for #{case_name} section"
+            raise ::ArgumentError, "Piece '#{piece_with_modifiers}' has wrong case for #{case_name} section"
           end
 
           # Add to our result with piece type and count
-          result << { piece: base_piece, count: count }
+          result << { piece: piece_with_modifiers, count: count }
 
           # Move position forward
           position += match[0].length
@@ -179,25 +160,21 @@ module Feen
         result
       end
 
-      # Extracts the base piece from a piece string that may contain modifiers
+      # Extracts the base letter from a PNN piece identifier
       #
-      # @param piece_str [String] Piece string potentially with modifiers
-      # @return [String] Base piece without modifiers
-      private_class_method def self.extract_base_piece(piece_str)
-        # Remove prefix modifiers (+ or -)
-        without_prefix = piece_str.gsub(/^[-+]/, "")
-
-        # Remove suffix modifiers (')
-        without_prefix.gsub(/'$/, "")
+      # @param piece [String] PNN piece identifier (e.g., "+P'", "-R", "K")
+      # @return [String] Base letter (e.g., "P", "R", "K")
+      private_class_method def self.extract_base_letter(piece)
+        piece.match(/[a-zA-Z]/)[0]
       end
 
       # Expands the pieces based on their counts into an array.
       #
       # @param pieces_with_counts [Array<Hash>] Array of pieces with their counts
-      # @return [Array<String>] Array of expanded pieces
+      # @return [Array<String>] Array of expanded pieces preserving order
       private_class_method def self.expand_pieces(pieces_with_counts)
         pieces_with_counts.flat_map do |item|
-          Array.new(item[:count], item[:piece])
+          ::Array.new(item[:count], item[:piece])
         end
       end
     end