feen 5.0.0.beta0 → 5.0.0.beta2

data/lib/feen/parser/piece_placement.rb

@@ -2,59 +2,219 @@
 
 module Feen
   module Parser
-    # The PiecePlacement class.
-    #
-    # @example Parse a Shogi problem board and return an array
-    #   PiecePlacement.new("3,s,k,s,3/9/4,+P,4/9/7,+B,1/9/9/9/9").to_a
-    #   # => [
-    #   #      nil, nil, nil, "s", "k", "s", nil, nil, nil,
-    #   #      nil, nil, nil, nil, nil, nil, nil, nil, nil,
-    #   #      nil, nil, nil, nil, "+P", nil, nil, nil, nil,
-    #   #      nil, nil, nil, nil, nil, nil, nil, nil, nil,
-    #   #      nil, nil, nil, nil, nil, nil, nil, "+B", nil,
-    #   #      nil, nil, nil, nil, nil, nil, nil, nil, nil,
-    #   #      nil, nil, nil, nil, nil, nil, nil, nil, nil,
-    #   #      nil, nil, nil, nil, nil, nil, nil, nil, nil,
-    #   #      nil, nil, nil, nil, nil, nil, nil, nil, nil
-    #   #    ]
-    #
-    # @example Parse a Shogi problem board and return a hash
-    #   PiecePlacement.new("3,s,k,s,3/9/4,+P,4/9/7,+B,1/9/9/9/9").to_h
-    #   # => {
-    #   #       3 => "s",
-    #   #       4 => "k",
-    #   #       5 => "s",
-    #   #      22 => "+P",
-    #   #      43 => "+B"
-    #   #    }
-    class PiecePlacement
-      # @param piece_placement_str [String] The placement of pieces on the board.
-      def initialize(piece_placement_str)
-        @piece_placement_str = piece_placement_str
+    # 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
 
-      # @return [Array] The list of pieces on the board.
-      def to_a
-        @piece_placement_str
-          .split(%r{[/,]+})
-          .flat_map { |str| row(str) }
+      # 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
 
-      # @return [Hash] The index of each piece on the board.
-      def to_h
-        to_a
-          .each_with_index
-          .inject({}) do |h, (v, i)|
-            next h if v.nil?
+      # 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
 
-            h.merge(i => v)
+        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
 
-      private
+      # 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
 
-      def row(string)
-        string.match?(/[0-9]+/) ? ::Array.new(Integer(string)) : string
+        cells
       end
     end
   end

data/lib/feen/parser/pieces_in_hand.rb

@@ -2,32 +2,73 @@
 
 module Feen
   module Parser
-    # The pieces in hand module.
+    # Handles parsing of the pieces in hand section of a FEEN string
     module PiecesInHand
-      # The list of pieces in hand grouped by players.
-      #
-      # @param pieces_in_hand [String, nil] The serialized list of pieces in hand.
+      NO_PIECES = "-"
+      ERRORS = {
+        invalid_type:       "Pieces in hand must be a string, got %s",
+        empty_string:       "Pieces in hand string cannot be empty",
+        invalid_chars:      "Invalid characters in pieces in hand: %s",
+        invalid_identifier: "Invalid piece identifier at position %d"
+      }.freeze
+
+      # Parses the pieces in hand section of a FEEN string
       #
-      # @example Parse a list of serialized pieces in hand
-      #   parse("S,b,g*4,n*4,p*17,r*2,s")
-      #   # => ["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"]
+      # @param pieces_in_hand_str [String] FEEN pieces in hand string
+      # @return [Array<Hash>] Array of pieces in hand
+      # @raise [ArgumentError] If the input string is invalid
+      def self.parse(pieces_in_hand_str)
+        validate_pieces_in_hand_string(pieces_in_hand_str)
+
+        # Handle the special case of no pieces in hand
+        return [] if pieces_in_hand_str == NO_PIECES
+
+        pieces = []
+        i = 0
+
+        while i < pieces_in_hand_str.length
+          # Vérifier que le caractère est une lettre
+          raise ArgumentError, format(ERRORS[:invalid_identifier], i) unless pieces_in_hand_str[i].match?(/[a-zA-Z]/)
+
+          pieces << { id: pieces_in_hand_str[i] }
+          i += 1
+
+        end
+
+        # Vérifier que les pièces sont triées par ordre lexicographique
+        raise ArgumentError, "Pieces in hand must be in ASCII lexicographic order" unless pieces_sorted?(pieces)
+
+        pieces
+      end
+
+      # Validates the pieces in hand string for syntax
       #
-      # @example Parse an empty list of serialized pieces in hand
-      #   parse("-")
-      #   # => []
+      # @param str [String] FEEN pieces in hand string
+      # @raise [ArgumentError] If the string is invalid
+      # @return [void]
+      def self.validate_pieces_in_hand_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 the special case of no pieces in hand
+        return if str == NO_PIECES
+
+        # Check for valid characters (only letters)
+        valid_chars = /\A[a-zA-Z]+\z/
+        return if str.match?(valid_chars)
+
+        invalid_chars = str.scan(/[^a-zA-Z]/).uniq.join(", ")
+        raise ArgumentError, format(ERRORS[:invalid_chars], invalid_chars)
+      end
+
+      # Checks if pieces are sorted in ASCII lexicographic order
       #
-      # @return [Array] The list of pieces in hand grouped by players.
-      def self.parse(pieces_in_hand)
-        return if pieces_in_hand.nil?
-
-        pieces_in_hand.split(",").flat_map do |piece|
-          if piece.include?("*")
-            letter, count = piece.split("*")
-            [letter] * count.to_i
-          else
-            piece
-          end
-        end.sort
+      # @param pieces [Array<Hash>] Array of piece hashes
+      # @return [Boolean] True if pieces are sorted
+      def self.pieces_sorted?(pieces)
+        piece_ids = pieces.map { |piece| piece[:id] }
+        piece_ids == piece_ids.sort
       end
     end
   end

data/lib/feen/parser.rb

@@ -1,40 +1,52 @@
 # frozen_string_literal: true
 
-require_relative File.join("parser", "board_shape")
-require_relative File.join("parser", "pieces_in_hand")
+require_relative File.join("parser", "games_turn")
 require_relative File.join("parser", "piece_placement")
+require_relative File.join("parser", "pieces_in_hand")
 
 module Feen
-  # The parser module.
+  # Module responsible for parsing FEEN notation strings into internal data structures
   module Parser
-    # Parse a FEEN string into position params.
-    #
-    # @param feen [String] The FEEN string representing a position.
-    #
-    # @example Parse a classic Tsume Shogi problem
-    #   call("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")
-    #   # => {
-    #   #      "side_to_move": "s",
-    #   #      "pieces_in_hand": ["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"],
-    #   #      "board_shape": [9, 9],
-    #   #      "piece_placement": {
-    #   #         3 => "s",
-    #   #         4 => "k",
-    #   #         5 => "s",
-    #   #        22 => "+P",
-    #   #        43 => "+B"
-    #   #      }
+    # Parses a complete FEEN string into a structured representation
     #
-    # @return [Hash] The position params representing the position.
-    def self.call(feen)
-      piece_placement, side_to_move, pieces_in_hand = feen.split
+    # @param feen_string [String] Complete FEEN notation string
+    # @return [Hash] Hash containing the parsed position data
+    # @raise [ArgumentError] If the FEEN string is invalid
+    def self.parse(feen_string)
+      validate_feen_string(feen_string)
+
+      # Split the FEEN string into its three fields
+      fields = feen_string.strip.split(/\s+/)
+
+      raise ArgumentError, "Invalid FEEN format: expected 3 fields, got #{fields.size}" unless fields.size == 3
+
+      # Parse each field using the appropriate submodule
+      piece_placement = PiecePlacement.parse(fields[0])
+      games_turn = GamesTurn.parse(fields[1])
+      pieces_in_hand = PiecesInHand.parse(fields[2])
 
+      # Return a structured representation of the position
       {
-        board_shape:     BoardShape.new(piece_placement).to_a,
-        pieces_in_hand:  PiecesInHand.parse(pieces_in_hand),
-        piece_placement: PiecePlacement.new(piece_placement).to_h,
-        side_to_move:
+        piece_placement: piece_placement,
+        games_turn:      games_turn,
+        pieces_in_hand:  pieces_in_hand
       }
     end
+
+    # Validates the FEEN string for basic format
+    #
+    # @param feen_string [String] FEEN string to validate
+    # @raise [ArgumentError] If the FEEN string is fundamentally invalid
+    # @return [void]
+    def self.validate_feen_string(feen_string)
+      raise ArgumentError, "FEEN must be a string, got #{feen_string.class}" unless feen_string.is_a?(String)
+
+      raise ArgumentError, "FEEN string cannot be empty" if feen_string.empty?
+
+      # Check for at least two spaces (three fields)
+      return unless feen_string.count(" ") < 2
+
+      raise ArgumentError, "Invalid FEEN format: must contain at least two spaces separating three fields"
+    end
   end
 end

data/lib/feen/sanitizer.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Feen
+  # Provides methods for sanitizing and validating chess-related notation strings
+  module Sanitizer
+    # Cleans a FEN (Forsyth-Edwards Notation) string by removing invalid castling rights
+    # and en passant targets based on the current position.
+    #
+    # The method performs the following validations:
+    # - Verifies that kings and rooks are in correct positions for castling rights
+    # - Verifies that en passant captures are actually possible
+    #
+    # @param fen_string [String] The FEN string to clean
+    # @return [String] A sanitized FEN string with invalid castling rights and en passant targets removed
+    # @raise [ArgumentError] If the FEN string is malformed (less than 4 parts)
+    #
+    # @example Clean a valid FEN string (unchanged)
+    #   fen = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
+    #   Feen::Sanitizer.clean_fen(fen) # => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
+    #
+    # @example Remove invalid castling rights when king has moved
+    #   fen = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQ1BNR w KQkq - 0 1"
+    #   Feen::Sanitizer.clean_fen(fen) # => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQ1BNR w kq - 0 1"
+    #
+    # @example Remove invalid castling rights when rook has moved
+    #   fen = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/1NBQKBNR w KQkq - 0 1"
+    #   Feen::Sanitizer.clean_fen(fen) # => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/1NBQKBNR w Kkq - 0 1"
+    #
+    # @example Remove invalid en passant target when no capturing pawn exists
+    #   fen = "rnbqkbnr/pppp1ppp/8/4p3/8/8/PPPPPPPP/RNBQKBNR w KQkq e6 0 2"
+    #   Feen::Sanitizer.clean_fen(fen) # => "rnbqkbnr/pppp1ppp/8/4p3/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 2"
+    #
+    # @example Keep valid en passant target when capturing is possible
+    #   fen = "rnbqkbnr/pppp1ppp/8/3Pp3/8/8/PPP1PPPP/RNBQKBNR w KQkq e6 0 2"
+    #   Feen::Sanitizer.clean_fen(fen) # => "rnbqkbnr/pppp1ppp/8/3Pp3/8/8/PPP1PPPP/RNBQKBNR w KQkq e6 0 2"
+    def self.clean_fen(fen_string)
+      parts = fen_string.strip.split
+      return fen_string unless parts.size >= 4
+
+      board, active_color, castling, en_passant, *rest = parts
+
+      # Parse board into a 2D array for easier access
+      board_matrix = []
+      board.split("/").each do |row|
+        current_row = []
+        row.each_char do |c|
+          if /[1-8]/.match?(c)
+            c.to_i.times { current_row << nil }
+          else
+            current_row << c
+          end
+        end
+        board_matrix << current_row
+      end
+
+      # Clean castling rights
+      new_castling = castling.dup
+      new_castling = clean_castling_rights(new_castling, board_matrix)
+
+      # Clean en passant target
+      new_en_passant = clean_en_passant_target(en_passant, board_matrix, active_color)
+
+      ([board, active_color, new_castling, new_en_passant] + rest).join(" ")
+    end
+
+    # Validates and cleans castling rights based on the position of kings and rooks
+    #
+    # @param castling [String] The castling rights string from FEN
+    # @param board [Array<Array<String, nil>>] 2D array representing the board
+    # @return [String] Cleaned castling rights or "-" if none are valid
+    # @api private
+    private_class_method def self.clean_castling_rights(castling, board)
+      return "-" if castling == "-"
+
+      new_castling = castling.dup
+
+      # White castling rights
+      new_castling.gsub!(/[KQ]/, "") unless board[7][4] == "K"
+      new_castling.delete!("K") unless board[7][7] == "R"
+      new_castling.delete!("Q") unless board[7][0] == "R"
+
+      # Black castling rights
+      new_castling.gsub!(/[kq]/, "") unless board[0][4] == "k"
+      new_castling.delete!("k") unless board[0][7] == "r"
+      new_castling.delete!("q") unless board[0][0] == "r"
+
+      new_castling.empty? ? "-" : new_castling
+    end
+
+    # Validates and cleans en passant target based on the position of pawns
+    #
+    # @param en_passant [String] The en passant target square from FEN
+    # @param board [Array<Array<String, nil>>] 2D array representing the board
+    # @param active_color [String] The active color ("w" or "b")
+    # @return [String] Cleaned en passant target or "-" if invalid
+    # @api private
+    private_class_method def self.clean_en_passant_target(en_passant, board, active_color)
+      return "-" if en_passant == "-"
+
+      file = en_passant[0].ord - "a".ord
+      rank = en_passant[1].to_i
+
+      # Validate en passant square coordinates
+      return "-" unless file.between?(0, 7) && [3, 6].include?(rank)
+
+      # For white's move (after black pawn double advance)
+      if active_color == "w" && rank == 6
+        # Check for white pawns on the 5th rank (index 3) that can capture
+        return en_passant if [file - 1, file + 1].any? { |f| f.between?(0, 7) && board[3][f] == "P" }
+      # For black's move (after white pawn double advance)
+      elsif active_color == "b" && rank == 3
+        # Check for black pawns on the 4th rank (index 4) that can capture
+        return en_passant if [file - 1, file + 1].any? { |f| f.between?(0, 7) && board[4][f] == "p" }
+      end
+
+      "-" # Invalid en passant square
+    end
+  end
+end