feen 5.0.0.beta1 → 5.0.0.beta2

data/lib/feen/dumper/piece_placement.rb

@@ -2,84 +2,120 @@
 
 module Feen
   module Dumper
-    # The PiecePlacement class.
-    #
-    # @example Dump an empty board of Xiangqi
-    #   PiecePlacement.new([10, 9]).to_s # => "9/9/9/9/9/9/9/9/9/9"
-    #
-    # @example Dump the Xiangqi starting position board
-    #   PiecePlacement.new(
-    #     [10, 9],
-    #     {
-    #        0 => "車",
-    #        1 => "馬",
-    #        2 => "象",
-    #        3 => "士",
-    #        4 => "將",
-    #        5 => "士",
-    #        6 => "象",
-    #        7 => "馬",
-    #        8 => "車",
-    #       19 => "砲",
-    #       25 => "砲",
-    #       27 => "卒",
-    #       29 => "卒",
-    #       31 => "卒",
-    #       33 => "卒",
-    #       35 => "卒",
-    #       54 => "兵",
-    #       56 => "兵",
-    #       58 => "兵",
-    #       60 => "兵",
-    #       62 => "兵",
-    #       64 => "炮",
-    #       70 => "炮",
-    #       81 => "俥",
-    #       82 => "傌",
-    #       83 => "相",
-    #       84 => "仕",
-    #       85 => "帥",
-    #       86 => "仕",
-    #       87 => "相",
-    #       88 => "傌",
-    #       89 => "俥"
-    #     }
-    #   ).to_s # => "車馬象士將士象馬車/9/1砲5砲1/卒1卒1卒1卒1卒/9/9/兵1兵1兵1兵1兵/1炮5炮1/9/俥傌相仕帥仕相傌俥"
-    class PiecePlacement
-      # @param indexes [Array] The shape of the board.
-      # @param piece_placement [Hash] The index of each piece on the board.
-      def initialize(indexes, piece_placement = {})
-        @indexes = indexes
-        @squares = ::Array.new(length) { |i| piece_placement.fetch(i, nil) }
+    # 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 = ""
+
+      # Dimension separator character
+      DIMENSION_SEPARATOR = "/"
+
+      # Converts the internal piece placement representation to a FEEN string
+      #
+      # @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?
+
+        # Step 1: Calculate the total depth of the structure
+        depth = calculate_depth(piece_placement)
+
+        # Step 2: Convert the structure to a string
+        dump_recursive(piece_placement, depth)
       end
 
-      # @return [String] The string representing the board.
-      def to_s
-        unflatten(@squares, @indexes)
+      # Calculates the maximum depth of the data 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?
+
+        if data.first.is_a?(Array)
+          1 + calculate_depth(data.first)
+        else
+          1
+        end
+      end
+
+      # Recursively converts the structure to FEEN notation
+      #
+      # @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)
+        end
       end
 
-      private
+      # Converts a single rank (row/array of cells) to FEEN notation
+      #
+      # @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?
 
-      def length
-        @indexes.inject(:*)
+        # 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
+          else
+            # Group of pieces -> concatenate FEEN representations
+            chunk.map { |cell| dump_cell(cell) }.join(EMPTY_STRING)
+          end
+        end.join(EMPTY_STRING)
       end
 
-      def unflatten(squares, remaining_indexes)
-        return row(squares) if remaining_indexes.length == 1
+      # Converts a single piece cell to its FEEN representation
+      #
+      # @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?
 
-        squares
-          .each_slice(squares.length / remaining_indexes.fetch(0))
-          .to_a
-          .map { |sub_squares| unflatten(sub_squares, remaining_indexes[1..]) }
-          .join("/" * remaining_indexes.length.pred)
+        # Combine prefix (if any) + piece identifier + suffix (if any)
+        [
+          cell[:prefix],
+          cell[:id],
+          cell[:suffix]
+        ].compact.join(EMPTY_STRING)
       end
 
-      def row(squares)
-        squares
-          .map { |square| square.nil? ? 1 : square }
-          .join(",")
-          .gsub(/1,[1,]*1/) { |str| str.split(",").length }
-          .delete(",")
+      def self.dump_dimension_group(group)
+        max_depth = calculate_depth(group)
+        dump_recursive(group, max_depth)
       end
     end
   end

data/lib/feen/dumper/pieces_in_hand.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Feen
+  module Dumper
+    # Handles conversion of pieces in hand data structure 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
+      #
+      # @param pieces_in_hand [Array<Hash>] Array of piece hashes
+      # @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
+      end
+
+      # Validates the structure of each piece in the array
+      #
+      # @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?
+        end
+      end
+    end
+  end
+end

data/lib/feen/dumper.rb

@@ -1,36 +1,55 @@
 # frozen_string_literal: true
 
+require_relative File.join("dumper", "games_turn")
 require_relative File.join("dumper", "piece_placement")
+require_relative File.join("dumper", "pieces_in_hand")
 
 module Feen
-  # The dumper module.
+  # Module responsible for converting internal data structures to FEEN notation strings
   module Dumper
-    # Dump position params into a FEEN string.
+    # Converts a complete position data structure to a FEEN string
     #
-    # @param board_shape [Array] The shape of the board.
-    # @param side_to_move [String] Identify the active side.
-    # @param piece_placement [Hash] The index of each piece on the board.
-    #
-    # @example Dump a classic Tsume Shogi problem
-    #   call(
-    #     "board_shape": [9, 9],
-    #     "side_to_move": "s",
-    #     "piece_placement": {
-    #        3 => "s",
-    #        4 => "k",
-    #        5 => "s",
-    #       22 => "+P",
-    #       43 => "+B"
-    #     }
-    #   )
-    #   # => "3sks3/9/4+P4/9/7+B1/9/9/9/9 s"
-    #
-    # @return [String] The FEEN string representing the position.
-    def self.call(board_shape:, side_to_move:, piece_placement:)
+    # @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)
+
       [
-        PiecePlacement.new(board_shape, piece_placement).to_s,
-        side_to_move
+        PiecePlacement.dump(position[:piece_placement]),
+        GamesTurn.dump(position[:games_turn]),
+        PiecesInHand.dump(position[:pieces_in_hand])
       ].join(" ")
     end
+
+    # Validates the position data structure
+    #
+    # @param position [Hash] Position data to validate
+    # @raise [ArgumentError] If the position data 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}"
+      end
+
+      unless position[:games_turn].is_a?(Hash)
+        raise ArgumentError, "games_turn must be a Hash, got #{position[:games_turn].class}"
+      end
+
+      return if position[:pieces_in_hand].is_a?(Array)
+
+      raise ArgumentError, "pieces_in_hand must be an Array, got #{position[:pieces_in_hand].class}"
+    end
   end
 end

data/lib/feen/parser/games_turn.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Feen
+  module Parser
+    # Handles parsing of the games turn section of a FEEN string
+    module GamesTurn
+      ERRORS = {
+        invalid_type:       "Games turn must be a string, got %s",
+        empty_string:       "Games turn string cannot be empty",
+        separator:          "Games turn must contain exactly one '/' separator",
+        mixed_casing:       "%s game has mixed case: %s",
+        casing_requirement: "One game must use uppercase letters and the other lowercase letters",
+        invalid_chars:      "Invalid characters in %s game identifier: %s",
+        empty_identifier:   "%s game identifier cannot be empty"
+      }.freeze
+
+      # Parses the games turn section of a FEEN string
+      #
+      # @param games_turn_str [String] FEEN games turn string
+      # @return [Hash] Hash containing game turn information
+      # @raise [ArgumentError] If the input string is invalid
+      def self.parse(games_turn_str)
+        validate_games_turn_string(games_turn_str)
+
+        # Split by the forward slash
+        parts = games_turn_str.split("/")
+        active_player = parts[0]
+        inactive_player = parts[1]
+
+        # Determine casing
+        active_uppercase = contains_uppercase?(active_player)
+
+        # Build result hash
+        {
+          active_player:        active_player,
+          inactive_player:      inactive_player,
+          uppercase_game:       active_uppercase ? active_player : inactive_player,
+          lowercase_game:       active_uppercase ? inactive_player : active_player,
+          active_player_casing: active_uppercase ? :uppercase : :lowercase
+        }
+      end
+
+      # Validates the games turn string for syntax and semantics
+      #
+      # @param str [String] FEEN games turn string
+      # @raise [ArgumentError] If the string is invalid
+      # @return [void]
+      def self.validate_games_turn_string(str)
+        validate_basic_structure(str)
+
+        parts = str.split("/")
+        validate_game_identifiers(parts)
+        validate_casing_requirements(parts)
+      end
+
+      # Validates the basic structure of the games turn string
+      #
+      # @param str [String] FEEN games turn string
+      # @raise [ArgumentError] If the structure is invalid
+      # @return [void]
+      private_class_method def self.validate_basic_structure(str)
+        raise ArgumentError, format(ERRORS[:invalid_type], str.class) unless str.is_a?(String)
+
+        raise ArgumentError, ERRORS[:empty_string] if str.empty?
+
+        # Check for exactly one separator '/'
+        return if str.count("/") == 1
+
+        raise ArgumentError, ERRORS[:separator]
+      end
+
+      # Validates the individual game identifiers
+      #
+      # @param parts [Array<String>] Split game identifiers
+      # @raise [ArgumentError] If any identifier is invalid
+      # @return [void]
+      private_class_method def self.validate_game_identifiers(parts)
+        parts.each_with_index do |game_id, idx|
+          position = idx == 0 ? "active" : "inactive"
+
+          raise ArgumentError, format(ERRORS[:empty_identifier], position.capitalize) if game_id.nil? || game_id.empty?
+
+          unless game_id.match?(/\A[a-zA-Z]+\z/)
+            invalid_chars = game_id.scan(/[^a-zA-Z]/).uniq.join(", ")
+            raise ArgumentError, format(ERRORS[:invalid_chars], position, invalid_chars)
+          end
+        end
+      end
+
+      # Validates the casing requirements (one uppercase, one lowercase)
+      #
+      # @param parts [Array<String>] Split game identifiers
+      # @raise [ArgumentError] If casing requirements aren't met
+      # @return [void]
+      private_class_method def self.validate_casing_requirements(parts)
+        active_uppercase = contains_uppercase?(parts[0])
+        inactive_uppercase = contains_uppercase?(parts[1])
+
+        raise ArgumentError, ERRORS[:casing_requirement] if active_uppercase == inactive_uppercase
+
+        # Verify consistent casing in each identifier
+        if active_uppercase && contains_lowercase?(parts[0])
+          raise ArgumentError, format(ERRORS[:mixed_casing], "Active", parts[0])
+        end
+
+        if inactive_uppercase && contains_lowercase?(parts[1])
+          raise ArgumentError, format(ERRORS[:mixed_casing], "Inactive", parts[1])
+        end
+
+        if !active_uppercase && contains_uppercase?(parts[0])
+          raise ArgumentError, format(ERRORS[:mixed_casing], "Active", parts[0])
+        end
+
+        return unless !inactive_uppercase && contains_uppercase?(parts[1])
+
+        raise ArgumentError, format(ERRORS[:mixed_casing], "Inactive", parts[1])
+      end
+
+      # Checks if a string contains any uppercase letters
+      #
+      # @param str [String] String to check
+      # @return [Boolean] True if the string contains uppercase letters
+      def self.contains_uppercase?(str)
+        str.match?(/[A-Z]/)
+      end
+
+      # Checks if a string contains any lowercase letters
+      #
+      # @param str [String] String to check
+      # @return [Boolean] True if the string contains lowercase letters
+      def self.contains_lowercase?(str)
+        str.match?(/[a-z]/)
+      end
+    end
+  end
+end

data/lib/feen/parser/piece_placement.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Feen
+  module Parser
+    # Handles parsing of the piece placement section of a FEEN string
+    module PiecePlacement
+      # Error messages
+      ERRORS = {
+        invalid_type:       "Piece placement must be a string, got %s",
+        empty_string:       "Piece placement string cannot be empty",
+        invalid_chars:      "Invalid characters in piece placement: %s",
+        invalid_prefix:     "Expected piece identifier after '+' prefix",
+        invalid_piece:      "Invalid piece identifier at position %d: %s",
+        trailing_separator: "Unexpected separator at the end of string or dimension group"
+      }.freeze
+
+      # Valid characters for validation
+      VALID_CHARS_PATTERN = %r{\A[a-zA-Z0-9/+<=>\s]+\z}
+
+      # Empty string for initialization
+      EMPTY_STRING = ""
+
+      # Dimension separator character
+      DIMENSION_SEPARATOR = "/"
+
+      # Piece promotion prefix
+      PREFIX_PROMOTION = "+"
+
+      # Valid piece suffixes
+      SUFFIX_EQUALS = "="
+      SUFFIX_LEFT = "<"
+      SUFFIX_RIGHT = ">"
+      VALID_SUFFIXES = [SUFFIX_EQUALS, SUFFIX_LEFT, SUFFIX_RIGHT].freeze
+
+      # Parses the piece placement section of a FEEN string
+      #
+      # @param piece_placement_str [String] FEEN piece placement string
+      # @return [Array] Hierarchical array structure representing the board
+      # @raise [ArgumentError] If the input string is invalid
+      def self.parse(piece_placement_str)
+        validate_piece_placement_string(piece_placement_str)
+
+        # Check for trailing separators that don't contribute to dimension structure
+        raise ArgumentError, ERRORS[:trailing_separator] if piece_placement_str.end_with?(DIMENSION_SEPARATOR)
+
+        parse_dimension_group(piece_placement_str)
+      end
+
+      # Validates the piece placement string for basic syntax
+      #
+      # @param str [String] FEEN piece placement string
+      # @raise [ArgumentError] If the string is invalid
+      # @return [void]
+      def self.validate_piece_placement_string(str)
+        raise ArgumentError, format(ERRORS[:invalid_type], str.class) unless str.is_a?(String)
+
+        raise ArgumentError, ERRORS[:empty_string] if str.empty?
+
+        # Check for valid characters
+        return if str.match?(VALID_CHARS_PATTERN)
+
+        invalid_chars = str.scan(%r{[^a-zA-Z0-9/+<=>]}).uniq.join(", ")
+        raise ArgumentError, format(ERRORS[:invalid_chars], invalid_chars)
+      end
+
+      # Finds all separator types present in the string (e.g., /, //, ///)
+      #
+      # @param str [String] FEEN dimension group string
+      # @return [Array<Integer>] Sorted array of separator depths (1 for /, 2 for //, etc.)
+      def self.find_separator_types(str)
+        # Find all consecutive sequences of '/'
+        separators = str.scan(%r{/+})
+        return [] if separators.empty?
+
+        # Return a unique sorted array of separator lengths
+        separators.map(&:length).uniq.sort
+      end
+
+      # Finds the minimum dimension depth in the string
+      #
+      # @param str [String] FEEN dimension group string
+      # @return [Integer] Minimum dimension depth (defaults to 1)
+      def self.find_min_dimension_depth(str)
+        separator_types = find_separator_types(str)
+        separator_types.empty? ? 1 : separator_types.first
+      end
+
+      # Recursively parses a dimension group
+      #
+      # @param str [String] FEEN dimension group string
+      # @return [Array] Hierarchical array structure representing the dimension group
+      def self.parse_dimension_group(str)
+        # Check for trailing separators at each level
+        raise ArgumentError, ERRORS[:trailing_separator] if str.end_with?(DIMENSION_SEPARATOR)
+
+        # Find all separator types present in the string
+        separator_types = find_separator_types(str)
+        return parse_rank(str) if separator_types.empty?
+
+        # Start with the deepest separator (largest number of consecutive /)
+        max_depth = separator_types.last
+        separator = DIMENSION_SEPARATOR * max_depth
+
+        # Split the string by this separator depth
+        parts = split_by_separator(str, separator)
+
+        # Create the hierarchical structure
+        parts.map do |part|
+          # Check each part for trailing separators of lower depths
+          raise ArgumentError, ERRORS[:trailing_separator] if part.end_with?(DIMENSION_SEPARATOR)
+
+          if max_depth == 1
+            # If this is the lowest level separator, parse as ranks
+            parse_rank(part)
+          else
+            # Otherwise, continue recursively with lower level separators
+            parse_dimension_group(part)
+          end
+        end
+      end
+
+      # Splits a string by a given separator, preserving separators of different depths
+      #
+      # @param str [String] String to split
+      # @param separator [String] Separator to split by (e.g., "/", "//")
+      # @return [Array<String>] Array of split parts
+      def self.split_by_separator(str, separator)
+        return [str] unless str.include?(separator)
+
+        parts = []
+        current_part = ""
+        i = 0
+
+        while i < str.length
+          # Si nous trouvons le début d'un séparateur potentiel
+          if str[i] == DIMENSION_SEPARATOR[0]
+            # Vérifier si c'est notre séparateur exact
+            if i <= str.length - separator.length && str[i, separator.length] == separator
+              # C'est notre séparateur, ajouter la partie actuelle à la liste
+              parts << current_part unless current_part.empty?
+              current_part = ""
+              i += separator.length
+            else
+              # Ce n'est pas notre séparateur exact, compter combien de '/' consécutifs
+              start = i
+              i += 1 while i < str.length && str[i] == DIMENSION_SEPARATOR[0]
+              # Ajouter ces '/' à la partie actuelle
+              current_part += str[start...i]
+            end
+          else
+            # Caractère normal, l'ajouter à la partie actuelle
+            current_part += str[i]
+            i += 1
+          end
+        end
+
+        # Ajouter la dernière partie si elle n'est pas vide
+        parts << current_part unless current_part.empty?
+
+        parts
+      end
+
+      # Parses a rank (sequence of cells)
+      #
+      # @param str [String] FEEN rank string
+      # @return [Array] Array of cells (nil for empty, hash for piece)
+      def self.parse_rank(str)
+        return [] if str.nil? || str.empty?
+
+        cells = []
+        i = 0
+
+        while i < str.length
+          char = str[i]
+
+          if char.match?(/[1-9]/)
+            # Handle empty cells (digits represent consecutive empty squares)
+            empty_count = EMPTY_STRING
+            while i < str.length && str[i].match?(/[0-9]/)
+              empty_count += str[i]
+              i += 1
+            end
+
+            empty_count.to_i.times { cells << nil }
+          else
+            # Handle pieces
+            piece = {}
+
+            # Check for prefix
+            if char == PREFIX_PROMOTION
+              piece[:prefix] = PREFIX_PROMOTION
+              i += 1
+
+              # Ensure there's a piece identifier after the prefix
+              raise ArgumentError, ERRORS[:invalid_prefix] if i >= str.length || !str[i].match?(/[a-zA-Z]/)
+
+              char = str[i]
+            end
+
+            # Get the piece identifier
+            raise ArgumentError, format(ERRORS[:invalid_piece], i, char) unless char.match?(/[a-zA-Z]/)
+
+            piece[:id] = char
+            i += 1
+
+            # Check for suffix
+            if i < str.length && VALID_SUFFIXES.include?(str[i])
+              piece[:suffix] = str[i]
+              i += 1
+            end
+
+            cells << piece
+
+          end
+        end
+
+        cells
+      end
+    end
+  end
+end