feen 5.0.0.beta8 → 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/piece_placement.rb

@@ -3,6 +3,14 @@
 module Feen
   module Parser
     # Handles parsing of the piece placement section of a FEEN string
+    #
+    # This module is responsible for converting the first field of a FEEN string
+    # (piece placement) into a hierarchical array structure representing the board.
+    # It supports arbitrary dimensions and handles both pieces (with optional PNN modifiers)
+    # and empty squares (represented by numbers).
+    #
+    # @see https://sashite.dev/documents/feen/1.0.0/ FEEN Specification
+    # @see https://sashite.dev/documents/pnn/1.0.0/ PNN Specification
     module PiecePlacement
       # Simplified error messages
       ERRORS = {
@@ -16,11 +24,78 @@ module Feen
 
       # Parses the piece placement section of a FEEN string
       #
+      # Converts a FEEN piece placement string into a hierarchical array structure
+      # representing the board where empty squares are represented by empty strings
+      # and pieces are represented by strings containing their PNN identifier and
+      # optional modifiers.
+      #
       # @param piece_placement_str [String] FEEN piece placement string
       # @return [Array] Hierarchical array structure representing the board where:
       #   - Empty squares are represented by empty strings ("")
       #   - Pieces are represented by strings containing their identifier and optional modifiers
       # @raise [ArgumentError] If the input string is invalid
+      #
+      # @example Parse a simple 2D chess position (initial position)
+      #   PiecePlacement.parse("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR")
+      #   # => [
+      #   #      ["r", "n", "b", "q", "k", "b", "n", "r"],
+      #   #      ["p", "p", "p", "p", "p", "p", "p", "p"],
+      #   #      ["", "", "", "", "", "", "", ""],
+      #   #      ["", "", "", "", "", "", "", ""],
+      #   #      ["", "", "", "", "", "", "", ""],
+      #   #      ["", "", "", "", "", "", "", ""],
+      #   #      ["P", "P", "P", "P", "P", "P", "P", "P"],
+      #   #      ["R", "N", "B", "Q", "K", "B", "N", "R"]
+      #   #    ]
+      #
+      # @example Parse a single rank with mixed pieces and empty squares
+      #   PiecePlacement.parse("r2k1r")
+      #   # => ["r", "", "", "k", "", "r"]
+      #
+      # @example Parse pieces with PNN modifiers (promoted pieces in Shogi)
+      #   PiecePlacement.parse("+P+Bk")
+      #   # => ["+P", "+B", "k"]
+      #
+      # @example Parse a 3D board structure (2 planes of 2x2)
+      #   PiecePlacement.parse("rn/pp//RN/PP")
+      #   # => [
+      #   #      [["r", "n"], ["p", "p"]],
+      #   #      [["R", "N"], ["P", "P"]]
+      #   #    ]
+      #
+      # @example Parse complex Shogi position with promoted pieces
+      #   PiecePlacement.parse("9/9/9/9/4+P4/9/5+B3/9/9")
+      #   # => [
+      #   #      ["", "", "", "", "", "", "", "", ""],
+      #   #      ["", "", "", "", "", "", "", "", ""],
+      #   #      ["", "", "", "", "", "", "", "", ""],
+      #   #      ["", "", "", "", "", "", "", "", ""],
+      #   #      ["", "", "", "", "+P", "", "", "", ""],
+      #   #      ["", "", "", "", "", "", "", "", ""],
+      #   #      ["", "", "", "", "", "+B", "", "", ""],
+      #   #      ["", "", "", "", "", "", "", "", ""],
+      #   #      ["", "", "", "", "", "", "", "", ""]
+      #   #    ]
+      #
+      # @example Parse irregular board shapes (different rank sizes)
+      #   PiecePlacement.parse("rnbqkbnr/ppppppp/8")
+      #   # => [
+      #   #      ["r", "n", "b", "q", "k", "b", "n", "r"],  # 8 cells
+      #   #      ["p", "p", "p", "p", "p", "p", "p"],       # 7 cells
+      #   #      ["", "", "", "", "", "", "", ""]           # 8 cells
+      #   #    ]
+      #
+      # @example Parse large numbers of empty squares
+      #   PiecePlacement.parse("15")
+      #   # => ["", "", "", "", "", "", "", "", "", "", "", "", "", "", ""]
+      #
+      # @example Parse pieces with all PNN modifier types
+      #   PiecePlacement.parse("+P'-R'k")
+      #   # => ["+P'", "-R'", "k"]
+      #   # Where:
+      #   # - "+P'" = enhanced state with intermediate suffix
+      #   # - "-R'" = diminished state with intermediate suffix
+      #   # - "k"   = base piece without modifiers
       def self.parse(piece_placement_str)
         validate_input(piece_placement_str)
         parse_structure(piece_placement_str)
@@ -28,9 +103,24 @@ module Feen
 
       # Validates the input string for basic requirements
       #
+      # Ensures the input is a non-empty string containing only valid FEEN characters.
+      # Valid characters include: letters (a-z, A-Z), digits (0-9), and modifiers (+, -, ').
+      #
       # @param str [String] Input string to validate
       # @raise [ArgumentError] If the string is invalid
       # @return [void]
+      #
+      # @example Valid input
+      #   validate_input("rnbqkbnr/pppppppp/8/8")
+      #   # => (no error)
+      #
+      # @example Invalid input (empty string)
+      #   validate_input("")
+      #   # => ArgumentError: Piece placement string cannot be empty
+      #
+      # @example Invalid input (wrong type)
+      #   validate_input(123)
+      #   # => ArgumentError: Piece placement must be a string, got Integer
       def self.validate_input(str)
         raise ArgumentError, format(ERRORS[:invalid_type], str.class) unless str.is_a?(String)
         raise ArgumentError, ERRORS[:empty_string] if str.empty?
@@ -43,9 +133,25 @@ module Feen
 
       # Parses the structure recursively
       #
+      # Determines the dimensionality of the board by analyzing separator patterns
+      # and recursively parses nested structures. Uses the longest separator sequence
+      # to determine the highest dimension level.
+      #
       # @param str [String] FEEN piece placement string
-      # @return [Array] Parsed structure
-      def self.parse_structure(str)
+      # @return [Array] Parsed structure (1D array for ranks, nested arrays for higher dimensions)
+      #
+      # @example 1D structure (single rank)
+      #   parse_structure("rnbq")
+      #   # => ["r", "n", "b", "q"]
+      #
+      # @example 2D structure (multiple ranks)
+      #   parse_structure("rn/pq")
+      #   # => [["r", "n"], ["p", "q"]]
+      #
+      # @example 3D structure (multiple planes)
+      #   parse_structure("r/p//R/P")
+      #   # => [[["r"], ["p"]], [["R"], ["P"]]]
+      private_class_method def self.parse_structure(str)
         # Handle trailing separators
         raise ArgumentError, ERRORS[:invalid_format] if str.end_with?(DIMENSION_SEPARATOR)
 
@@ -64,10 +170,22 @@ module Feen
 
       # Splits string by separator while preserving shorter separators
       #
+      # Intelligently splits a string by a specific separator pattern while
+      # ensuring that shorter separator patterns within the string are preserved
+      # for recursive parsing of nested dimensions.
+      #
       # @param str [String] String to split
-      # @param separator [String] Separator to split by
-      # @return [Array<String>] Split parts
-      def self.smart_split(str, separator)
+      # @param separator [String] Separator to split by (e.g., "/", "//", "///")
+      # @return [Array<String>] Split parts, with empty parts removed
+      #
+      # @example Split by single separator
+      #   smart_split("a/b/c", "/")
+      #   # => ["a", "b", "c"]
+      #
+      # @example Split by double separator, preserving single separators
+      #   smart_split("a/b//c/d", "//")
+      #   # => ["a/b", "c/d"]
+      private_class_method def self.smart_split(str, separator)
         return [str] unless str.include?(separator)
 
         parts = str.split(separator)
@@ -76,9 +194,29 @@ module Feen
 
       # Parses a rank (sequence of cells)
       #
+      # Processes a 1D sequence of cells, expanding numeric values to empty squares
+      # and extracting pieces with their PNN modifiers. Numbers represent consecutive
+      # empty squares, while letters (with optional modifiers) represent pieces.
+      #
       # @param str [String] FEEN rank string
-      # @return [Array] Array of cells
-      def self.parse_rank(str)
+      # @return [Array<String>] Array of cells (empty strings for empty squares, piece strings for pieces)
+      #
+      # @example Simple pieces
+      #   parse_rank("rnbq")
+      #   # => ["r", "n", "b", "q"]
+      #
+      # @example Mixed pieces and empty squares
+      #   parse_rank("r2k1r")
+      #   # => ["r", "", "", "k", "", "r"]
+      #
+      # @example All empty squares
+      #   parse_rank("8")
+      #   # => ["", "", "", "", "", "", "", ""]
+      #
+      # @example Pieces with modifiers
+      #   parse_rank("+P-R'")
+      #   # => ["+P", "-R'"]
+      private_class_method def self.parse_rank(str)
         return [] if str.empty?
 
         cells = []
@@ -114,10 +252,32 @@ module Feen
 
       # Extracts a piece starting at given position
       #
+      # Parses a piece identifier with optional PNN modifiers starting at the specified
+      # position in the string. Handles prefix modifiers (+, -), the required letter,
+      # and suffix modifiers (').
+      #
       # @param str [String] String to parse
-      # @param start_index [Integer] Starting position
+      # @param start_index [Integer] Starting position in the string
       # @return [Hash] Hash with :piece and :next_index keys
-      def self.extract_piece(str, start_index)
+      #   - :piece [String] The complete piece identifier with modifiers
+      #   - :next_index [Integer] Position after the piece in the string
+      #
+      # @example Extract simple piece
+      #   extract_piece("Kqr", 0)
+      #   # => { piece: "K", next_index: 1 }
+      #
+      # @example Extract piece with prefix modifier
+      #   extract_piece("+Pqr", 0)
+      #   # => { piece: "+P", next_index: 2 }
+      #
+      # @example Extract piece with suffix modifier
+      #   extract_piece("K'qr", 0)
+      #   # => { piece: "K'", next_index: 2 }
+      #
+      # @example Extract piece with both prefix and suffix modifiers
+      #   extract_piece("+P'qr", 0)
+      #   # => { piece: "+P'", next_index: 3 }
+      private_class_method def self.extract_piece(str, start_index)
         piece = ""
         i = start_index