feen 5.0.0.beta7 → 5.0.0.beta8

data/lib/feen/dumper/games_turn.rb

@@ -4,12 +4,13 @@ module Feen
   module Dumper
     # Handles conversion of games turn data to FEEN notation string
     module GamesTurn
+      # Error messages for validation
       ERRORS = {
-        type:   "%s must be a String, got %s",
-        empty:  "%s cannot be empty",
-        mixed:  "%s has mixed case: %s",
-        casing: "One variant must be uppercase and the other lowercase",
-        chars:  "Variant identifiers must contain only alphabetic characters (a-z, A-Z)"
+        invalid_type:  "%s must be a String, got %s",
+        empty_string:  "%s cannot be empty",
+        invalid_chars: "%s must contain only alphabetic characters (a-z, A-Z)",
+        mixed_case:    "%s has mixed case: %s",
+        same_casing:   "One variant must be uppercase and the other lowercase"
       }.freeze
 
       # Converts the active and inactive variant identifiers to a FEEN-formatted games turn string
@@ -17,6 +18,15 @@ module Feen
       # @param active_variant [String] Identifier for the player to move and their game variant
       # @param inactive_variant [String] Identifier for the opponent and their game variant
       # @return [String] FEEN-formatted games turn string
+      # @raise [ArgumentError] If the variant identifiers are invalid
+      #
+      # @example Valid games turn
+      #   GamesTurn.dump("CHESS", "chess")
+      #   # => "CHESS/chess"
+      #
+      # @example Invalid - same casing
+      #   GamesTurn.dump("CHESS", "SHOGI")
+      #   # => ArgumentError: One variant must be uppercase and the other lowercase
       def self.dump(active_variant, inactive_variant)
         validate_variants(active_variant, inactive_variant)
         "#{active_variant}/#{inactive_variant}"
@@ -29,38 +39,31 @@ module Feen
       # @raise [ArgumentError] If the variant identifiers are invalid
       # @return [void]
       private_class_method def self.validate_variants(active, inactive)
-        # Validate basic type and presence
+        # Validate basic type, presence and format
         [["Active variant", active], ["Inactive variant", inactive]].each do |name, variant|
-          raise ArgumentError, format(ERRORS[:type], name, variant.class) unless variant.is_a?(String)
-          raise ArgumentError, format(ERRORS[:empty], name) if variant.empty?
-          raise ArgumentError, ERRORS[:chars] unless variant.match?(/\A[a-zA-Z]+\z/)
-        end
+          # Type validation
+          raise ArgumentError, format(ERRORS[:invalid_type], name, variant.class) unless variant.is_a?(String)
 
-        # Validate casing (one must be uppercase, one must be lowercase)
-        active_uppercase = active == active.upcase && active != active.downcase
-        inactive_uppercase = inactive == inactive.upcase && inactive != inactive.downcase
+          # Empty validation
+          raise ArgumentError, format(ERRORS[:empty_string], name) if variant.empty?
 
-        # If both have the same casing (both uppercase or both lowercase), raise error
-        raise ArgumentError, ERRORS[:casing] if active_uppercase == inactive_uppercase
+          # Character validation
+          raise ArgumentError, format(ERRORS[:invalid_chars], name) unless variant.match?(/\A[a-zA-Z]+\z/)
 
-        # Check for mixed case (must be all uppercase or all lowercase)
-        if active_uppercase && active != active.upcase
-          raise ArgumentError, format(ERRORS[:mixed], "Active variant", active)
+          # Mixed case validation
+          unless variant == variant.upcase || variant == variant.downcase
+            raise ArgumentError, format(ERRORS[:mixed_case], name, variant)
+          end
         end
 
-        if inactive_uppercase && inactive != inactive.upcase
-          raise ArgumentError, format(ERRORS[:mixed], "Inactive variant", inactive)
-        end
-
-        if !active_uppercase && active != active.downcase
-          raise ArgumentError, format(ERRORS[:mixed], "Active variant", active)
-        end
+        # Casing difference validation
+        active_is_uppercase = active == active.upcase
+        inactive_is_uppercase = inactive == inactive.upcase
 
-        if !inactive_uppercase && inactive != inactive.downcase
-          raise ArgumentError, format(ERRORS[:mixed], "Inactive variant", inactive)
-        end
+        # Both variants must have different casing
+        return unless active_is_uppercase == inactive_is_uppercase
 
-        true
+        raise ArgumentError, ERRORS[:same_casing]
       end
     end
   end

data/lib/feen/dumper/piece_placement.rb

@@ -2,69 +2,91 @@
 
 module Feen
   module Dumper
+    # Handles conversion of piece placement data to FEEN notation string
     module PiecePlacement
+      # Error messages
+      ERRORS = {
+        invalid_type:       "Piece placement must be an Array, got %s",
+        inconsistent_shape: "Inconsistent dimension structure detected",
+        invalid_cell:       "Invalid cell content: %s (must be String)"
+      }.freeze
+
       # Converts a piece placement structure to a FEEN-compliant string
       #
       # @param piece_placement [Array] Hierarchical array representing the board where:
       #   - Empty squares are represented by empty strings ("")
-      #   - Pieces are represented by strings (e.g., "r", "R'", "+P")
+      #   - Pieces are represented by strings (e.g., "r", "R", "+P", "K'")
       #   - Dimensions are represented by nested arrays
       # @return [String] FEEN piece placement string
       # @raise [ArgumentError] If the piece placement structure is invalid
+      #
+      # @example 2D chess board
+      #   PiecePlacement.dump([
+      #     ["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"]
+      #   ])
+      #   # => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR"
+      #
+      # @example 3D board
+      #   PiecePlacement.dump([
+      #     [["r", "n"], ["p", "p"]],
+      #     [["", ""], ["P", "P"]],
+      #     [["R", "N"], ["", ""]]
+      #   ])
+      #   # => "rn/pp//2/PP//RN/2"
       def self.dump(piece_placement)
-        # Détecter la forme du tableau directement à partir de la structure
-        detect_shape(piece_placement)
-
-        # Formater directement la structure en chaîne FEEN
+        validate_input(piece_placement)
         format_placement(piece_placement)
       end
 
-      # Detects the shape of the board based on the piece_placement structure
+      # Validates the input piece placement structure
       #
-      # @param piece_placement [Array] Hierarchical array structure representing the board
-      # @return [Array<Integer>] Array of dimension sizes
-      # @raise [ArgumentError] If the piece_placement structure is invalid
-      def self.detect_shape(piece_placement)
-        return [] if piece_placement.empty?
-
-        dimensions = []
-        current = piece_placement
+      # @param piece_placement [Object] Structure to validate
+      # @raise [ArgumentError] If the structure is invalid
+      # @return [void]
+      private_class_method def self.validate_input(piece_placement)
+        raise ArgumentError, format(ERRORS[:invalid_type], piece_placement.class) unless piece_placement.is_a?(Array)
 
-        # Traverse the structure to determine shape
-        while current.is_a?(Array) && !current.empty?
-          dimensions << current.size
-
-          # Check if all elements at this level have the same structure
-          validate_dimension_uniformity(current)
-
-          # Check if we've reached the leaf level (array of strings)
-          break if current.first.is_a?(String) ||
-                   (current.first.is_a?(Array) && current.first.empty?)
-
-          current = current.first
-        end
-
-        dimensions
+        validate_structure_consistency(piece_placement)
       end
 
-      # Validates that all elements in a dimension have the same structure
+      # Validates that the structure is consistent (all dimensions have same size)
       #
-      # @param dimension [Array] Array of elements at a particular dimension level
-      # @raise [ArgumentError] If elements have inconsistent structure
-      def self.validate_dimension_uniformity(dimension)
-        return if dimension.empty?
+      # @param structure [Array] Structure to validate
+      # @raise [ArgumentError] If structure is inconsistent
+      # @return [void]
+      private_class_method def self.validate_structure_consistency(structure)
+        return if structure.empty?
+
+        # Check if this is a rank (array of strings) or multi-dimensional
+        if structure.all?(String)
+          # This is a rank - validate each cell
+          structure.each_with_index do |cell, _index|
+            raise ArgumentError, format(ERRORS[:invalid_cell], cell.inspect) unless cell.is_a?(String)
+          end
+        elsif structure.all?(Array)
+          # This is multi-dimensional - check consistency and validate recursively
+          structure.each do |element|
+            # Recursively validate sub-structures
+            validate_structure_consistency(element)
+          end
+        else
+          # Mixed types - check for non-string elements in what should be a rank
+          non_string_elements = structure.reject { |element| element.is_a?(String) }
+          raise ArgumentError, ERRORS[:inconsistent_shape] unless non_string_elements.any?
 
-        first_type = dimension.first.class
-        first_size = dimension.first.is_a?(Array) ? dimension.first.size : nil
+          # If we have non-string elements, report the first one as invalid cell content
+          first_invalid = non_string_elements.first
+          raise ArgumentError, format(ERRORS[:invalid_cell], first_invalid.inspect)
 
-        dimension.each do |element|
-          unless element.class == first_type
-            raise ArgumentError, "Inconsistent element types in dimension: #{first_type} vs #{element.class}"
-          end
+          # This shouldn't happen, but keep the original error as fallback
 
-          if element.is_a?(Array) && element.size != first_size
-            raise ArgumentError, "Inconsistent dimension sizes: expected #{first_size}, got #{element.size}"
-          end
         end
       end
 
@@ -72,28 +94,26 @@ module Feen
       #
       # @param placement [Array] Piece placement structure
       # @return [String] FEEN piece placement string
-      def self.format_placement(placement)
-        # For 1D arrays (ranks), format directly
-        if !placement.is_a?(Array) ||
-           (placement.is_a?(Array) && (placement.empty? || !placement.first.is_a?(Array)))
-          return format_rank(placement)
-        end
+      private_class_method def self.format_placement(placement)
+        return "" if placement.empty?
+
+        # Check if this is a rank (1D array of strings)
+        return format_rank(placement) if placement.all?(String)
 
-        # For 2D+ arrays, format each sub-element and join with appropriate separator
+        # This is multi-dimensional - determine separator depth
         depth = calculate_depth(placement) - 1
         separator = "/" * depth
 
-        # Important: Ne pas inverser le tableau - nous voulons maintenir l'ordre original
-        elements = placement
-        elements.map { |element| format_placement(element) }.join(separator)
+        # Format each sub-element and join
+        placement.map { |element| format_placement(element) }.join(separator)
       end
 
-      # Formats a rank (1D array of cells)
+      # Formats a rank (1D array of cells) into FEEN notation
       #
-      # @param rank [Array] 1D array of cells
+      # @param rank [Array<String>] 1D array of cells
       # @return [String] FEEN rank string
-      def self.format_rank(rank)
-        return "" if !rank.is_a?(Array) || rank.empty?
+      private_class_method def self.format_rank(rank)
+        return "" if rank.empty?
 
         result = ""
         empty_count = 0
@@ -102,9 +122,11 @@ module Feen
           if cell.empty?
             empty_count += 1
           else
-            # Add accumulated empty squares
-            result += empty_count.to_s if empty_count > 0
-            empty_count = 0
+            # Add accumulated empty squares count
+            if empty_count.positive?
+              result += empty_count.to_s
+              empty_count = 0
+            end
 
             # Add the piece
             result += cell
@@ -112,16 +134,16 @@ module Feen
         end
 
         # Add any trailing empty squares
-        result += empty_count.to_s if empty_count > 0
+        result += empty_count.to_s if empty_count.positive?
 
         result
       end
 
-      # Calculates the depth of a nested structure
+      # Calculates the depth of a nested array structure
       #
       # @param structure [Array] Structure to analyze
       # @return [Integer] Depth of the structure
-      def self.calculate_depth(structure)
+      private_class_method def self.calculate_depth(structure)
         return 0 unless structure.is_a?(Array) && !structure.empty?
 
         if structure.first.is_a?(Array)

data/lib/feen/dumper/pieces_in_hand.rb

@@ -1,30 +1,42 @@
 # frozen_string_literal: true
 
-require_relative File.join("pieces_in_hand", "errors")
-
 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"
+      }.freeze
+
       # Converts an array of piece identifiers to a FEEN-formatted pieces in hand string
       #
-      # @param piece_chars [Array<String>] Array of piece identifiers (e.g., ["P", "p", "B", "B", "p", "+P"])
+      # @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:
       #   - Groups pieces by case: uppercase first, then lowercase, separated by "/"
       #   - Within each group, sorts by quantity (descending), then alphabetically (ascending)
       #   - Uses count notation for quantities > 1 (e.g., "3P" instead of "PPP")
-      # @raise [ArgumentError] If any piece identifier is invalid
-      # @example
+      # @raise [ArgumentError] If any piece identifier is invalid or contains modifiers
+      #
+      # @example Valid pieces in hand
       #   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"
       #
-      #   PiecesInHand.dump
+      # @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 the FEEN specification
+        # Validate each piece character according to FEEN specification (base form only)
         validated_chars = validate_piece_chars(piece_chars)
 
         # Group pieces by case
@@ -43,34 +55,12 @@ module Feen
       # @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.select { |piece| piece_is_uppercase?(piece) }
-        lowercase_pieces = pieces.select { |piece| piece_is_lowercase?(piece) }
+        uppercase_pieces = pieces.grep(/[A-Z]/)
+        lowercase_pieces = pieces.grep(/[a-z]/)
 
         [uppercase_pieces, lowercase_pieces]
       end
 
-      # Determines if a piece belongs to the uppercase group
-      # A piece is considered uppercase if its main letter is uppercase (ignoring prefixes/suffixes)
-      #
-      # @param piece [String] Piece identifier (e.g., "P", "+P", "P'", "+P'")
-      # @return [Boolean] True if the piece's main letter is uppercase
-      private_class_method def self.piece_is_uppercase?(piece)
-        # Extract the main letter (skip prefixes like + or -)
-        main_letter = piece.gsub(/\A[+-]/, "").gsub(/'\z/, "")
-        main_letter.match?(/[A-Z]/)
-      end
-
-      # Determines if a piece belongs to the lowercase group
-      # A piece is considered lowercase if its main letter is lowercase (ignoring prefixes/suffixes)
-      #
-      # @param piece [String] Piece identifier (e.g., "p", "+p", "p'", "+p'")
-      # @return [Boolean] True if the piece's main letter is lowercase
-      private_class_method def self.piece_is_lowercase?(piece)
-        # Extract the main letter (skip prefixes like + or -)
-        main_letter = piece.gsub(/\A[+-]/, "").gsub(/'\z/, "")
-        main_letter.match?(/[a-z]/)
-      end
-
       # Formats a group of pieces according to FEEN specification
       #
       # @param pieces [Array<String>] Array of pieces from the same case group
@@ -106,11 +96,11 @@ module Feen
         end.join
       end
 
-      # Validates all piece characters according to FEEN specification
+      # Validates all piece characters according to FEEN specification (base form only)
       #
       # @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
+      # @raise [ArgumentError] If any piece character is invalid or contains modifiers
       private_class_method def self.validate_piece_chars(piece_chars)
         piece_chars.each_with_index.map do |char, index|
           validate_piece_char(char, index)
@@ -118,34 +108,22 @@ module Feen
       end
 
       # Validates a single piece character according to FEEN specification
-      # Supports full PNN notation: [prefix]letter[suffix] where:
-      # - prefix can be "+" or "-"
-      # - letter must be a-z or A-Z
-      # - suffix can be "'"
+      # For pieces in hand, only base form is allowed: single letter (a-z or A-Z)
+      # NO modifiers (+, -, ') are allowed in pieces in hand
       #
       # @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
+      # @raise [ArgumentError] If the piece character is invalid or contains modifiers
       private_class_method def self.validate_piece_char(char, index)
         # Validate type
-        unless char.is_a?(::String)
-          raise ::ArgumentError, format(
-            Errors[:invalid_type],
-            index: index,
-            type:  char.class
-          )
-        end
+        raise ArgumentError, format(ERRORS[:invalid_type], index, char.class) unless char.is_a?(String)
 
-        # Validate format using PNN pattern: [prefix]letter[suffix]
-        # where prefix is +/-, letter is a-zA-Z, suffix is '
-        unless char.match?(/\A[+-]?[a-zA-Z]'?\z/)
-          raise ::ArgumentError, format(
-            Errors[:invalid_format],
-            index: index,
-            value: char
-          )
-        end
+        # Check for forbidden modifiers first (clearer error message)
+        raise ArgumentError, format(ERRORS[:has_modifiers], index, char) if char.match?(/[+\-']/)
+
+        # 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/)
 
         char
       end

data/lib/feen/dumper.rb

@@ -35,13 +35,13 @@ module Feen
     #     pieces_in_hand: [],
     #     games_turn: ["CHESS", "chess"]
     #   )
-    #   # => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR - 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
+    #                                    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
     # @return [String] Complete FEEN string representation compliant with the specification

data/lib/feen/parser/games_turn.rb

@@ -1,12 +1,33 @@
 # frozen_string_literal: true
 
-require_relative File.join("games_turn", "valid_games_turn_pattern")
-require_relative File.join("games_turn", "errors")
-
 module Feen
   module Parser
     # Handles parsing of the games turn section of a FEEN string
     module GamesTurn
+      # Error messages for games turn parsing
+      ERRORS = {
+        invalid_type:   "Games turn must be a string, got %s",
+        empty_string:   "Games turn string cannot be empty",
+        invalid_format: "Invalid games turn format. Expected format: UPPERCASE/lowercase or lowercase/UPPERCASE"
+      }.freeze
+
+      # Pattern matching the FEEN specification for games turn
+      # <games-turn> ::= <game-id-uppercase> "/" <game-id-lowercase>
+      #                | <game-id-lowercase> "/" <game-id-uppercase>
+      VALID_GAMES_TURN_PATTERN = %r{
+        \A                    # Start of string
+        (?:                   # Non-capturing group for alternatives
+          (?<uppercase_first>[A-Z]+)  # Named group: uppercase identifier first
+          /                           # Separator
+          (?<lowercase_second>[a-z]+) # Named group: lowercase identifier second
+          |                           # OR
+          (?<lowercase_first>[a-z]+)  # Named group: lowercase identifier first
+          /                           # Separator
+          (?<uppercase_second>[A-Z]+) # Named group: uppercase identifier second
+        )
+        \z                    # End of string
+      }x
+
       # Parses the games turn section of a FEEN string
       #
       # @param games_turn_str [String] FEEN games turn string
@@ -23,10 +44,10 @@ module Feen
       def self.parse(games_turn_str)
         validate_input_type(games_turn_str)
 
-        match = ValidGamesTurnPattern.match(games_turn_str)
-        raise ::ArgumentError, Errors[:invalid_format] unless match
+        match = VALID_GAMES_TURN_PATTERN.match(games_turn_str)
+        raise ::ArgumentError, ERRORS[:invalid_format] unless match
 
-        extract_game_identifiers(**match.named_captures.transform_keys(&:to_sym))
+        extract_game_identifiers(match)
       end
 
       # Validates that the input is a non-empty string
@@ -35,22 +56,21 @@ 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
 
       # Extracts game identifiers from regexp match captures
       #
-      # @param uppercase_first [String, nil] Uppercase identifier if it comes first
-      # @param lowercase_second [String, nil] Lowercase identifier if it comes second
-      # @param lowercase_first [String, nil] Lowercase identifier if it comes first
-      # @param uppercase_second [String, nil] Uppercase identifier if it comes second
+      # @param match [MatchData] Regexp match data with named captures
       # @return [Array<String>] Array containing [active_player, inactive_player]
-      private_class_method def self.extract_game_identifiers(uppercase_first: nil, lowercase_second: nil, lowercase_first: nil, uppercase_second: nil)
-        if uppercase_first
-          [uppercase_first, lowercase_second]
+      private_class_method def self.extract_game_identifiers(match)
+        captures = match.named_captures
+
+        if captures["uppercase_first"]
+          [captures["uppercase_first"], captures["lowercase_second"]]
         else
-          [lowercase_first, uppercase_second]
+          [captures["lowercase_first"], captures["uppercase_second"]]
         end
       end
     end