feen 5.0.0.beta2 → 5.0.0.beta3

data/lib/feen/dumper/piece_placement.rb

@@ -2,120 +2,133 @@
 
 module Feen
   module Dumper
-    # Handles conversion of piece placement data structure to FEEN notation string
     module PiecePlacement
-      # Error messages
-      ERRORS = {
-        empty_input: "Piece placement cannot be empty"
-      }.freeze
-
-      # Empty string for initialization
-      EMPTY_STRING = ""
+      # 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", "K=", "+P")
+      #   - Dimensions are represented by nested arrays
+      # @return [String] FEEN piece placement string
+      # @raise [ArgumentError] If the piece placement structure is invalid
+      def self.dump(piece_placement)
+        # Détecter la forme du tableau directement à partir de la structure
+        detect_shape(piece_placement)
 
-      # Dimension separator character
-      DIMENSION_SEPARATOR = "/"
+        # Formater directement la structure en chaîne FEEN
+        format_placement(piece_placement)
+      end
 
-      # Converts the internal piece placement representation to a FEEN string
+      # Detects the shape of the board based on the piece_placement structure
       #
       # @param piece_placement [Array] Hierarchical array structure representing the board
-      # @return [String] FEEN-formatted piece placement string
-      # @example
-      #   piece_placement = [[{id: 'r'}, {id: 'n'}, nil, nil]]
-      #   PiecePlacement.dump(piece_placement)
-      #   # => "rn2"
-      def self.dump(piece_placement)
-        return EMPTY_STRING if piece_placement.nil? || piece_placement.empty?
+      # @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
+
+        # 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)
 
-        # Step 1: Calculate the total depth of the structure
-        depth = calculate_depth(piece_placement)
+          # 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?)
 
-        # Step 2: Convert the structure to a string
-        dump_recursive(piece_placement, depth)
+          current = current.first
+        end
+
+        dimensions
       end
 
-      # Calculates the maximum depth of the data structure
+      # Validates that all elements in a dimension have the same structure
       #
-      # @param data [Array] Data structure to evaluate
-      # @return [Integer] Maximum depth
-      def self.calculate_depth(data)
-        return 0 unless data.is_a?(Array) && !data.empty?
+      # @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?
 
-        if data.first.is_a?(Array)
-          1 + calculate_depth(data.first)
-        else
-          1
+        first_type = dimension.first.class
+        first_size = dimension.first.is_a?(Array) ? dimension.first.size : nil
+
+        dimension.each do |element|
+          unless element.class == first_type
+            raise ArgumentError, "Inconsistent element types in dimension: #{first_type} vs #{element.class}"
+          end
+
+          if element.is_a?(Array) && element.size != first_size
+            raise ArgumentError, "Inconsistent dimension sizes: expected #{first_size}, got #{element.size}"
+          end
         end
       end
 
-      # Recursively converts the structure to FEEN notation
+      # Formats the piece placement structure into a FEEN string
       #
-      # @param data [Array] Data to convert
-      # @param max_depth [Integer] Maximum depth of the structure
-      # @param current_depth [Integer] Current recursion depth
-      # @return [String] FEEN representation
-      def self.dump_recursive(data, max_depth, current_depth = 1)
-        return EMPTY_STRING if data.nil? || data.empty?
-
-        if data.first.is_a?(Array)
-          parts = data.map { |subdata| dump_recursive(subdata, max_depth, current_depth + 1) }
-
-          # The number of separators depends on the current depth
-          # The lowest level uses a single '/', then increases progressively
-          separator_count = max_depth - current_depth
-          separator = DIMENSION_SEPARATOR * separator_count
-
-          parts.join(separator)
-        else
-          # This is a simple row (rank)
-          dump_rank(data)
+      # @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
+
+        # For 2D+ arrays, format each sub-element and join with appropriate separator
+        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)
       end
 
-      # Converts a single rank (row/array of cells) to FEEN notation
+      # Formats a rank (1D array of cells)
       #
-      # @param cells [Array] Array of cell values (nil for empty, hash for piece)
-      # @return [String] FEEN representation of this rank
-      # @example
-      #   cells = [{id: 'r'}, {id: 'n'}, nil, nil]
-      #   PiecePlacement.dump_rank(cells)
-      #   # => "rn2"
-      def self.dump_rank(cells)
-        return EMPTY_STRING if cells.nil? || cells.empty?
-
-        # Use chunk_while to group consecutive empty/non-empty cells
-        cells.chunk_while { |a, b| a.nil? == b.nil? }.map do |chunk|
-          if chunk.first.nil?
-            # Group of empty cells -> count
-            chunk.size.to_s
+      # @param rank [Array] 1D array of cells
+      # @return [String] FEEN rank string
+      def self.format_rank(rank)
+        return "" if !rank.is_a?(Array) || rank.empty?
+
+        result = ""
+        empty_count = 0
+
+        rank.each do |cell|
+          if cell.empty?
+            empty_count += 1
           else
-            # Group of pieces -> concatenate FEEN representations
-            chunk.map { |cell| dump_cell(cell) }.join(EMPTY_STRING)
+            # Add accumulated empty squares
+            result += empty_count.to_s if empty_count > 0
+            empty_count = 0
+
+            # Add the piece
+            result += cell
           end
-        end.join(EMPTY_STRING)
+        end
+
+        # Add any trailing empty squares
+        result += empty_count.to_s if empty_count > 0
+
+        result
       end
 
-      # Converts a single piece cell to its FEEN representation
+      # Calculates the depth of a nested structure
       #
-      # @param cell [Hash] Hash with :id and optional :prefix and :suffix
-      # @return [String] FEEN representation of this piece
-      # @example
-      #   cell = {id: 'P', suffix: '='}
-      #   PiecePlacement.dump_cell(cell)
-      #   # => "P="
-      def self.dump_cell(cell)
-        return EMPTY_STRING if cell.nil?
-
-        # Combine prefix (if any) + piece identifier + suffix (if any)
-        [
-          cell[:prefix],
-          cell[:id],
-          cell[:suffix]
-        ].compact.join(EMPTY_STRING)
-      end
+      # @param structure [Array] Structure to analyze
+      # @return [Integer] Depth of the structure
+      def self.calculate_depth(structure)
+        return 0 unless structure.is_a?(Array) && !structure.empty?
 
-      def self.dump_dimension_group(group)
-        max_depth = calculate_depth(group)
-        dump_recursive(group, max_depth)
+        if structure.first.is_a?(Array)
+          1 + calculate_depth(structure.first)
+        else
+          1
+        end
       end
     end
   end

data/lib/feen/dumper/pieces_in_hand/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Feen
+  module Dumper
+    module PiecesInHand
+      Errors = {
+        invalid_type:   "Piece at index: %<index>s must be a String, got type: %<type>s",
+        invalid_format: "Piece at index: %<index>s has an invalid format: '%<value>s'"
+      }.freeze
+    end
+  end
+end

data/lib/feen/dumper/pieces_in_hand/no_pieces.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Feen
+  module Dumper
+    module PiecesInHand
+      # Character used to represent no pieces in hand
+      NoPieces = "-"
+    end
+  end
+end

data/lib/feen/dumper/pieces_in_hand.rb

@@ -1,56 +1,72 @@
 # frozen_string_literal: true
 
+require_relative File.join("pieces_in_hand", "no_pieces")
+require_relative File.join("pieces_in_hand", "errors")
+
 module Feen
   module Dumper
-    # Handles conversion of pieces in hand data structure to FEEN notation string
+    # Handles conversion of pieces in hand data to FEEN notation string
     module PiecesInHand
-      EMPTY_RESULT = "-"
-      ERRORS = {
-        invalid_piece:      "Invalid piece at index %d: must be a Hash with an :id key",
-        invalid_id:         "Invalid piece ID at index %d: must be a single alphabetic character",
-        prefix_not_allowed: "Prefix is not allowed for pieces in hand at index %d",
-        suffix_not_allowed: "Suffix is not allowed for pieces in hand at index %d"
-      }.freeze
-
-      # Converts the internal pieces in hand representation to a FEEN string
+      # Converts an array of piece identifiers to a FEEN-formatted pieces in hand string
       #
-      # @param pieces_in_hand [Array<Hash>] Array of piece hashes
+      # @param piece_chars [Array<String>] Array of single-character piece identifiers
       # @return [String] FEEN-formatted pieces in hand string
-      def self.dump(pieces_in_hand)
-        # If no pieces in hand, return a single hyphen
-        return EMPTY_RESULT if pieces_in_hand.nil? || pieces_in_hand.empty?
-
-        # Validate all pieces have the required structure
-        validate_pieces(pieces_in_hand)
-
-        # Sort pieces in ASCII lexicographic order by their ID
-        pieces_in_hand
-          .sort_by { |piece| piece[:id] }
-          .map { |piece| piece[:id] }
-          .join
+      # @raise [ArgumentError] If any piece identifier is invalid
+      # @example
+      #   PiecesInHand.dump("P", "p", "B")
+      #   # => "BPp"
+      #
+      #   PiecesInHand.dump
+      #   # => "-"
+      def self.dump(*piece_chars)
+        # If no pieces in hand, return the standardized empty indicator
+        return NoPieces if piece_chars.empty?
+
+        # Validate each piece character according to the FEEN specification
+        validated_chars = validate_piece_chars(piece_chars)
+
+        # Sort pieces in ASCII lexicographic order and join them
+        validated_chars.sort.join
       end
 
-      # Validates the structure of each piece in the array
+      # Validates all piece characters according to FEEN specification
       #
-      # @param pieces [Array<Hash>] Array of piece hashes to validate
-      # @raise [ArgumentError] If any piece has an invalid structure
-      # @return [void]
-      def self.validate_pieces(pieces)
-        pieces.each_with_index do |piece, index|
-          # Check basic piece structure
-          raise ArgumentError, format(ERRORS[:invalid_piece], index) unless piece.is_a?(Hash) && piece.key?(:id)
-
-          # Validate piece ID
-          unless piece[:id].is_a?(String) && piece[:id].match?(/\A[a-zA-Z]\z/)
-            raise ArgumentError, format(ERRORS[:invalid_id], index)
-          end
-
-          # Ensure no prefix or suffix is present
-          raise ArgumentError, format(ERRORS[:prefix_not_allowed], index) if piece.key?(:prefix) && !piece[:prefix].nil?
-
-          raise ArgumentError, format(ERRORS[:suffix_not_allowed], index) if piece.key?(:suffix) && !piece[:suffix].nil?
+      # @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
+      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
+      #
+      # @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
+      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
+
+        # Validate format (single alphabetic character)
+        unless char.match?(/\A[a-zA-Z]\z/)
+          raise ::ArgumentError, format(
+            Errors[:invalid_format],
+            index: index,
+            value: char
+          )
+        end
+
+        char
+      end
     end
   end
 end

data/lib/feen/dumper.rb

@@ -5,51 +5,82 @@ require_relative File.join("dumper", "piece_placement")
 require_relative File.join("dumper", "pieces_in_hand")
 
 module Feen
-  # Module responsible for converting internal data structures to FEEN notation strings
+  # Module responsible for converting internal data structures to FEEN notation strings.
+  # This implements the serialization part of the FEEN (Format for Encounter & Entertainment Notation) format.
   module Dumper
-    # Converts a complete position data structure to a FEEN string
+    # Field separator used between the three main components of FEEN notation
+    FIELD_SEPARATOR = " "
+
+    # 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_pieces_in_hand_type:  "Pieces in hand must be an Array, got %s"
+    }.freeze
+
+    # Converts position components to a complete FEEN string.
+    #
+    # @example Creating a FEEN string for chess initial position
+    #   Feen::Dumper.dump(
+    #     piece_placement: [
+    #       ["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"]
+    #     ],
+    #     pieces_in_hand: [],
+    #     games_turn: ["CHESS", "chess"]
+    #   )
+    #   # => "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess"
     #
-    # @param position [Hash] Hash containing the complete position data
-    # @option position [Array] :piece_placement Board position data
-    # @option position [Hash] :games_turn Games and turn data
-    # @option position [Array<Hash>] :pieces_in_hand Pieces in hand data
-    # @return [String] Complete FEEN string representation
-    def self.dump(position)
-      validate_position(position)
+    # @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
+    # @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
+    # @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:)
+      # Validate input types
+      validate_inputs(piece_placement, games_turn, pieces_in_hand)
 
+      # Process each component with appropriate submodule and combine into final FEEN string
       [
-        PiecePlacement.dump(position[:piece_placement]),
-        GamesTurn.dump(position[:games_turn]),
-        PiecesInHand.dump(position[:pieces_in_hand])
-      ].join(" ")
+        PiecePlacement.dump(piece_placement),
+        PiecesInHand.dump(*pieces_in_hand),
+        GamesTurn.dump(*games_turn)
+      ].join(FIELD_SEPARATOR)
     end
 
-    # Validates the position data structure
+    # Validates the input parameters for type and structure
     #
-    # @param position [Hash] Position data to validate
-    # @raise [ArgumentError] If the position data is invalid
+    # @param piece_placement [Object] Piece placement parameter to validate
+    # @param games_turn [Object] Games turn parameter to validate
+    # @param pieces_in_hand [Object] Pieces in hand parameter to validate
+    # @raise [ArgumentError] If any parameter is invalid
     # @return [void]
-    def self.validate_position(position)
-      raise ArgumentError, "Position must be a Hash, got #{position.class}" unless position.is_a?(Hash)
-
-      # Check for required keys
-      required_keys = %i[piece_placement games_turn pieces_in_hand]
-      missing_keys = required_keys - position.keys
-
-      raise ArgumentError, "Missing required keys in position: #{missing_keys.join(', ')}" unless missing_keys.empty?
-
-      # Validate types of values
-      unless position[:piece_placement].is_a?(Array)
-        raise ArgumentError, "piece_placement must be an Array, got #{position[:piece_placement].class}"
+    private_class_method def self.validate_inputs(piece_placement, games_turn, pieces_in_hand)
+      # Validate piece_placement is an Array
+      unless piece_placement.is_a?(Array)
+        raise ArgumentError, format(ERRORS[:invalid_piece_placement_type], piece_placement.class)
       end
 
-      unless position[:games_turn].is_a?(Hash)
-        raise ArgumentError, "games_turn must be a Hash, got #{position[:games_turn].class}"
+      # 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)
       end
 
-      return if position[:pieces_in_hand].is_a?(Array)
+      # Validate pieces_in_hand is an Array
+      return if pieces_in_hand.is_a?(Array)
 
-      raise ArgumentError, "pieces_in_hand must be an Array, got #{position[:pieces_in_hand].class}"
+      raise ArgumentError, format(ERRORS[:invalid_pieces_in_hand_type], pieces_in_hand.class)
     end
   end
 end

data/lib/feen/parser/games_turn/errors.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Feen
+  module Parser
+    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
+    end
+  end
+end

data/lib/feen/parser/games_turn/valid_games_turn_pattern.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Feen
+  module Parser
+    module GamesTurn
+      # Complete pattern matching the BNF specification with named groups
+      # <games-turn> ::= <game-id-uppercase> "/" <game-id-lowercase>
+      #                | <game-id-lowercase> "/" <game-id-uppercase>
+      ValidGamesTurnPattern = %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
+    end
+  end
+end