feen 5.0.0.beta0 → 5.0.0.beta2

data/lib/feen/dumper/games_turn.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Feen
+  module Dumper
+    # Handles conversion of games turn data structure to FEEN notation string
+    module GamesTurn
+      ERRORS = {
+        missing_key:        "Missing required key in games_turn: %s",
+        invalid_type:       "Invalid type for games_turn[%s]: expected String, got %s",
+        empty_string:       "Empty string for games_turn[%s]",
+        casing_requirement: "One game must be uppercase and the other lowercase",
+        invalid_chars:      "Game identifiers must contain only alphabetic characters (a-z, A-Z)"
+      }.freeze
+
+      REQUIRED_KEYS = %i[active_player inactive_player].freeze
+
+      # Converts the internal games turn representation to a FEEN string
+      #
+      # @param games_turn [Hash] Hash containing game turn information
+      # @return [String] FEEN-formatted games turn string
+      def self.dump(games_turn)
+        validate_games_turn(games_turn)
+
+        # Format is <active_player>/<inactive_player>
+        "#{games_turn[:active_player]}/#{games_turn[:inactive_player]}"
+      end
+
+      # Validates the games turn data structure
+      #
+      # @param games_turn [Hash] The games turn data to validate
+      # @raise [ArgumentError] If the games turn data is invalid
+      # @return [Boolean] true if the validation passes
+      def self.validate_games_turn(games_turn)
+        validate_structure(games_turn)
+        validate_casing(games_turn)
+        validate_character_set(games_turn)
+
+        true
+      end
+
+      # Validates the basic structure of games_turn
+      #
+      # @param games_turn [Hash] The games turn data to validate
+      # @raise [ArgumentError] If the structure is invalid
+      # @return [void]
+      private_class_method def self.validate_structure(games_turn)
+        REQUIRED_KEYS.each do |key|
+          raise ArgumentError, format(ERRORS[:missing_key], key) unless games_turn.key?(key)
+
+          unless games_turn[key].is_a?(String)
+            raise ArgumentError, format(ERRORS[:invalid_type], key, games_turn[key].class)
+          end
+
+          raise ArgumentError, format(ERRORS[:empty_string], key) if games_turn[key].empty?
+        end
+      end
+
+      # Validates the casing requirement (one uppercase, one lowercase)
+      #
+      # @param games_turn [Hash] The games turn data to validate
+      # @raise [ArgumentError] If the casing requirement is not met
+      # @return [void]
+      private_class_method def self.validate_casing(games_turn)
+        active_has_uppercase = games_turn[:active_player].match?(/[A-Z]/)
+        inactive_has_uppercase = games_turn[:inactive_player].match?(/[A-Z]/)
+
+        # Ensure exactly one has uppercase
+        raise ArgumentError, ERRORS[:casing_requirement] if active_has_uppercase == inactive_has_uppercase
+
+        # Check that uppercase game is all caps and lowercase game has no caps
+        if active_has_uppercase && games_turn[:active_player].match?(/[a-z]/)
+          raise ArgumentError, "Active game has mixed case: #{games_turn[:active_player]}"
+        end
+
+        return unless inactive_has_uppercase && games_turn[:inactive_player].match?(/[a-z]/)
+
+        raise ArgumentError, "Inactive game has mixed case: #{games_turn[:inactive_player]}"
+      end
+
+      # Validates that identifiers only contain allowed characters
+      #
+      # @param games_turn [Hash] The games turn data to validate
+      # @raise [ArgumentError] If invalid characters are present
+      # @return [void]
+      private_class_method def self.validate_character_set(games_turn)
+        REQUIRED_KEYS.each do |key|
+          raise ArgumentError, ERRORS[:invalid_chars] unless games_turn[key].match?(/\A[a-zA-Z]+\z/)
+        end
+      end
+    end
+  end
+end

data/lib/feen/dumper/piece_placement.rb

@@ -2,83 +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 }
+      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

@@ -2,26 +2,54 @@
 
 module Feen
   module Dumper
-    # A module that serializes pieces in hand lists into a string.
+    # Handles conversion of pieces in hand data structure to FEEN notation string
     module PiecesInHand
-      # Serialize pieces in hand lists into a string.
-      #
-      # @param piece_names [Array] A list of pieces in hand.
-      #
-      # @example Dump a list of pieces in hand
-      #   dump(["S", "b", "g", "g", "g", "g", "n", "n", "n", "n", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "r", "r", "s"])
-      #   # => "S,b,g*4,n*4,p*17,r*2,s"
+      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
       #
-      # @example Dump an empty list of pieces in hand
-      #   dump([])
-      #   # => nil
+      # @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
       #
-      # @return [String, nil] A serialized list of pieces in hand.
-      def self.dump(piece_names)
-        return if piece_names.empty?
+      # @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?
 
-        hash = piece_names.group_by(&:itself).transform_values(&:count)
-        hash.map { |k, v| v > 1 ? "#{k}*#{v}" : k }.sort.join(",")
+          raise ArgumentError, format(ERRORS[:suffix_not_allowed], index) if piece.key?(:suffix) && !piece[:suffix].nil?
+        end
       end
     end
   end

data/lib/feen/dumper.rb

@@ -1,42 +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 side_to_move [String] Identify the active side.
-    # @param pieces_in_hand [Array, nil] The list of pieces in hand.
-    # @param board_shape [Array] The shape of the board.
-    # @param piece_placement [Hash] The index of each piece on the board.
-    #
-    # @example Dump a classic Tsume Shogi problem
-    #   call(
-    #     "side_to_move": "s",
-    #     "pieces_in_hand": %w[S r r b g g g g s n n n n p p p p p p p p p p p p p p p p p],
-    #     "board_shape": [9, 9],
-    #     "piece_placement": {
-    #        3 => "s",
-    #        4 => "k",
-    #        5 => "s",
-    #       22 => "+P",
-    #       43 => "+B"
-    #     }
-    #   )
-    #   # => "3,s,k,s,3/9/4,+P,4/9/7,+B,1/9/9/9/9 s S,b,g*4,n*4,p*17,r*2,s"
+    # @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.dump(position[:piece_placement]),
+        GamesTurn.dump(position[:games_turn]),
+        PiecesInHand.dump(position[:pieces_in_hand])
+      ].join(" ")
+    end
+
+    # Validates the position data structure
     #
-    # @return [String] The FEEN string representing the position.
-    def self.call(board_shape:, side_to_move:, piece_placement:, pieces_in_hand: nil)
-      array = [
-        PiecePlacement.new(board_shape, piece_placement).to_s,
-        side_to_move
-      ]
-
-      array << PiecesInHand.dump(pieces_in_hand) if Array(pieces_in_hand).any?
-      array.join(" ")
+    # @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