feen 5.0.0.beta1 → 5.0.0.beta3

data/lib/feen/dumper.rb

@@ -1,36 +1,86 @@
 # 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.
+  # This implements the serialization part of the FEEN (Format for Encounter & Entertainment Notation) format.
   module Dumper
-    # Dump position params into 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.
+    # 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 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"
-    #     }
+    # @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"]
     #   )
-    #   # => "3sks3/9/4+P4/9/7+B1/9/9/9/9 s"
+    #   # => "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess"
     #
-    # @return [String] The FEEN string representing the position.
-    def self.call(board_shape:, side_to_move:, piece_placement:)
+    # @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.new(board_shape, piece_placement).to_s,
-        side_to_move
-      ].join(" ")
+        PiecePlacement.dump(piece_placement),
+        PiecesInHand.dump(*pieces_in_hand),
+        GamesTurn.dump(*games_turn)
+      ].join(FIELD_SEPARATOR)
+    end
+
+    # Validates the input parameters for type and structure
+    #
+    # @param piece_placement [Object] Piece placement parameter to validate
+    # @param games_turn [Object] Games turn parameter to validate
+    # @param pieces_in_hand [Object] Pieces in hand parameter to validate
+    # @raise [ArgumentError] If any parameter is invalid
+    # @return [void]
+    private_class_method def self.validate_inputs(piece_placement, games_turn, pieces_in_hand)
+      # Validate piece_placement is an Array
+      unless piece_placement.is_a?(Array)
+        raise ArgumentError, format(ERRORS[:invalid_piece_placement_type], piece_placement.class)
+      end
+
+      # Validate games_turn is an Array with exactly 2 elements
+      unless games_turn.is_a?(Array) && games_turn.size == 2
+        raise ArgumentError, format(ERRORS[:invalid_games_turn_type], games_turn.inspect)
+      end
+
+      # Validate pieces_in_hand is an Array
+      return if pieces_in_hand.is_a?(Array)
+
+      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

data/lib/feen/parser/games_turn.rb

@@ -0,0 +1,58 @@
+# 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
+      # Parses the games turn section of a FEEN string
+      #
+      # @param games_turn_str [String] FEEN games turn string
+      # @return [Array<String>] Array containing [active_player, inactive_player]
+      # @raise [ArgumentError] If the input string is invalid
+      #
+      # @example Valid games turn string with uppercase first
+      #   GamesTurn.parse("CHESS/shogi")
+      #   # => ["CHESS", "shogi"]
+      #
+      # @example Valid games turn string with lowercase first
+      #   GamesTurn.parse("chess/SHOGI")
+      #   # => ["chess", "SHOGI"]
+      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
+
+        extract_game_identifiers(**match.named_captures.transform_keys(&:to_sym))
+      end
+
+      # Validates that the input is a non-empty string
+      #
+      # @param str [String] Input string to validate
+      # @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?
+      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
+      # @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]
+        else
+          [lowercase_first, uppercase_second]
+        end
+      end
+    end
+  end
+end