feen 5.0.0.beta2 → 5.0.0.beta3

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Feen
+  module Parser
+    module PiecesInHand
+      # Error messages for validation
+      Errors = {
+        invalid_type:   "Pieces in hand must be a string, got %s",
+        empty_string:   "Pieces in hand string cannot be empty",
+        invalid_format: "Invalid pieces in hand format: %s"
+      }.freeze
+    end
+  end
+end

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

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

data/lib/feen/parser/pieces_in_hand/valid_format_pattern.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Feen
+  module Parser
+    module PiecesInHand
+      # Valid pattern for pieces in hand based on BNF:
+      # <pieces-in-hand> ::= "-" | <A-part> <B-part> ... <Z-part> <a-part> <b-part> ... <z-part>
+      # where each part can be empty or contain repetitions of the same letter
+      ValidFormatPattern = /\A(?:-|
+        A*B*C*D*E*F*G*H*I*J*K*L*M*N*O*P*Q*R*S*T*U*V*W*X*Y*Z*
+        a*b*c*d*e*f*g*h*i*j*k*l*m*n*o*p*q*r*s*t*u*v*w*x*y*z*
+      )\z/x
+    end
+  end
+end

data/lib/feen/parser/pieces_in_hand.rb

@@ -2,73 +2,82 @@
 
 module Feen
   module Parser
-    # Handles parsing of the pieces in hand section of a FEEN string
+    # Handles parsing of the pieces in hand section of a FEEN string.
+    # Pieces in hand represent pieces available for dropping onto the board.
     module PiecesInHand
+      # Character used to represent no pieces in hand
       NO_PIECES = "-"
+
+      # Error messages for validation
       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"
+        invalid_type:   "Pieces in hand must be a string, got %s",
+        empty_string:   "Pieces in hand string cannot be empty",
+        invalid_format: "Invalid pieces in hand format: %s",
+        sorting_error:  "Pieces in hand must be in ASCII lexicographic order"
       }.freeze
 
-      # Parses the pieces in hand section of a FEEN string
+      # Valid pattern for pieces in hand based on BNF:
+      # <pieces-in-hand> ::= "-" | <piece> <pieces-in-hand>
+      # <piece> ::= [a-zA-Z]
+      VALID_FORMAT_PATTERN = /\A(?:-|[a-zA-Z]+)\z/
+
+      # Parses the pieces in hand section of a FEEN string.
       #
       # @param pieces_in_hand_str [String] FEEN pieces in hand string
-      # @return [Array<Hash>] Array of pieces in hand
+      # @return [Array<String>] Array of single-character piece identifiers in the
+      #   format specified in the FEEN string (no prefixes or suffixes), sorted in ASCII
+      #   lexicographic order. Empty array if no pieces are in hand.
       # @raise [ArgumentError] If the input string is invalid
+      #
+      # @example Parse no pieces in hand
+      #   PiecesInHand.parse("-")
+      #   # => []
+      #
+      # @example Parse multiple pieces in hand
+      #   PiecesInHand.parse("BNPPb")
+      #   # => ["B", "N", "P", "P", "b"]
       def self.parse(pieces_in_hand_str)
-        validate_pieces_in_hand_string(pieces_in_hand_str)
+        validate_input_type(pieces_in_hand_str)
+        validate_format(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 = pieces_in_hand_str.chars
+        validate_pieces_order(pieces)
 
         pieces
       end
 
-      # Validates the pieces in hand string for syntax
+      # Validates that the input is a non-empty string.
       #
-      # @param str [String] FEEN pieces in hand string
-      # @raise [ArgumentError] If the string is invalid
+      # @param str [String] Input string to validate
+      # @raise [ArgumentError] If input is not a string or is empty
       # @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
+      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
 
-        # Check for valid characters (only letters)
-        valid_chars = /\A[a-zA-Z]+\z/
-        return if str.match?(valid_chars)
+      # Validates that the input string matches the expected format.
+      #
+      # @param str [String] Input string to validate
+      # @raise [ArgumentError] If format is invalid
+      # @return [void]
+      private_class_method def self.validate_format(str)
+        return if str.match?(VALID_FORMAT_PATTERN)
 
-        invalid_chars = str.scan(/[^a-zA-Z]/).uniq.join(", ")
-        raise ArgumentError, format(ERRORS[:invalid_chars], invalid_chars)
+        raise ::ArgumentError, format(ERRORS[:invalid_format], str)
       end
 
-      # Checks if pieces are sorted in ASCII lexicographic order
+      # Validates that pieces are sorted in ASCII lexicographic order.
       #
-      # @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
+      # @param pieces [Array<String>] Array of piece identifiers
+      # @raise [ArgumentError] If pieces are not sorted
+      # @return [void]
+      private_class_method def self.validate_pieces_order(pieces)
+        return if pieces == pieces.sort
+
+        raise ::ArgumentError, ERRORS[:sorting_error]
       end
     end
   end

data/lib/feen/parser.rb

@@ -5,48 +5,85 @@ require_relative File.join("parser", "piece_placement")
 require_relative File.join("parser", "pieces_in_hand")
 
 module Feen
-  # Module responsible for parsing FEEN notation strings into internal data structures
+  # Module responsible for parsing FEEN notation strings into internal data structures.
+  # FEEN (Format for Encounter & Entertainment Notation) is a compact, canonical, and rule-agnostic
+  # textual format for representing static board positions in two-player piece-placement games.
   module Parser
+    # Regular expression pattern for matching a valid FEEN string structure
+    # Captures exactly three non-space components separated by single spaces
+    FEEN_PATTERN = /\A([^\s]+)\s([^\s]+)\s([^\s]+)\z/
+
+    # Error message for invalid FEEN format
+    INVALID_FORMAT_ERROR = "Invalid FEEN format: expected exactly 3 fields separated by single spaces"
+
     # Parses a complete FEEN string into a structured representation
     #
     # @param feen_string [String] Complete FEEN notation string
-    # @return [Hash] Hash containing the parsed position data
-    # @raise [ArgumentError] If the FEEN string is invalid
+    # @return [Hash] Hash containing the parsed position data with the following keys:
+    #   - :piece_placement [Array] - Hierarchical array structure representing the board
+    #   - :pieces_in_hand [Array<String>] - Pieces available for dropping onto the board
+    #   - :games_turn [Array<String>] - A two-element array with [active_variant, inactive_variant]
+    # @raise [ArgumentError] If the FEEN string is invalid or any component cannot be parsed
+    #
+    # @example Parsing a standard chess initial position
+    #   feen = "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess"
+    #   result = Feen::Parser.parse(feen)
+    #   # => {
+    #   #      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"]
+    #   #    }
+    #
+    # @example Parsing a shogi position (from a Tempo Loss Bishop Exchange opening) with pieces in hand
+    #   feen = "lnsgk2nl/1r4gs1/p1pppp1pp/1p4p2/7P1/2P6/PP1PPPP1P/1SG4R1/LN2KGSNL Bb SHOGI/shogi"
+    #   result = Feen::Parser.parse(feen)
+    #   # => {
+    #   #      piece_placement: [
+    #   #        ["l", "n", "s", "g", "k", "", "", "n", "l"],
+    #   #        ["", "r", "", "", "", "", "g", "s", ""],
+    #   #        ["p", "", "p", "p", "p", "p", "", "p", "p"],
+    #   #        ["", "p", "", "", "", "", "p", "", ""],
+    #   #        ["", "", "", "", "", "", "", "P", ""],
+    #   #        ["", "", "P", "", "", "", "", "", ""],
+    #   #        ["P", "P", "", "P", "P", "P", "P", "", "P"],
+    #   #        ["", "S", "G", "", "", "", "", "R", ""],
+    #   #        ["L", "N", "", "", "K", "G", "S", "N", "L"]
+    #   #      ],
+    #   #      pieces_in_hand: ["B", "b"],
+    #   #      games_turn: ["SHOGI", "shogi"]
+    #   #    }
     def self.parse(feen_string)
-      validate_feen_string(feen_string)
+      feen_string = String(feen_string)
+
+      # Match the FEEN string against the expected pattern
+      match = FEEN_PATTERN.match(feen_string)
 
-      # Split the FEEN string into its three fields
-      fields = feen_string.strip.split(/\s+/)
+      # Raise an error if the format doesn't match the expected pattern
+      raise ::ArgumentError, INVALID_FORMAT_ERROR unless match
 
-      raise ArgumentError, "Invalid FEEN format: expected 3 fields, got #{fields.size}" unless fields.size == 3
+      # Capture the three distinct parts
+      piece_placement_string, pieces_in_hand_string, games_turn_string = match.captures
 
       # 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])
+      piece_placement = PiecePlacement.parse(piece_placement_string)
+      pieces_in_hand = PiecesInHand.parse(pieces_in_hand_string)
+      games_turn = GamesTurn.parse(games_turn_string)
 
-      # Return a structured representation of the position
+      # Create a structured representation of the position
       {
-        piece_placement: piece_placement,
-        games_turn:      games_turn,
-        pieces_in_hand:  pieces_in_hand
+        piece_placement:,
+        pieces_in_hand:,
+        games_turn:
       }
     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.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require_relative File.join("feen", "converter")
 require_relative File.join("feen", "dumper")
 require_relative File.join("feen", "parser")
 
@@ -9,102 +8,69 @@ require_relative File.join("feen", "parser")
 #
 # @see https://sashite.dev/documents/feen/1.0.0/
 module Feen
-  # Dumps position params into a FEEN string.
+  # Dumps position components into a FEEN string.
   #
-  # @param position [Hash] Hash containing the 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
+  # @see Feen::Dumper.dump for the detailed parameters documentation
   # @return [String] FEEN notation string
-  # @raise [ArgumentError] If the position data is invalid
+  # @raise [ArgumentError] If any parameter is invalid
   # @example
-  #   position = {
-  #     piece_placement: [[{id: 'r'}, {id: 'n'}, {id: 'b'}, {id: 'q'}, {id: 'k'}, {id: 'b'}, {id: 'n'}, {id: 'r'}],
-  #                       [{id: 'p'}, {id: 'p'}, {id: 'p'}, {id: 'p'}, {id: 'p'}, {id: 'p'}, {id: 'p'}, {id: 'p'}],
-  #                       [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],
-  #                       [{id: 'P'}, {id: 'P'}, {id: 'P'}, {id: 'P'}, {id: 'P'}, {id: 'P'}, {id: 'P'}, {id: 'P'}],
-  #                       [{id: 'R'}, {id: 'N'}, {id: 'B'}, {id: 'Q'}, {id: 'K'}, {id: 'B'}, {id: 'N'}, {id: 'R'}]],
-  #     games_turn: {
-  #       active_player: 'CHESS',
-  #       inactive_player: 'chess',
-  #       uppercase_game: 'CHESS',
-  #       lowercase_game: 'chess'
-  #     },
-  #     pieces_in_hand: []
-  #   }
-  #   Feen.dump(position) # => "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR CHESS/chess -"
-  def self.dump(position)
-    Dumper.dump(position)
+  #   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"]
+  #   ]
+  #   Feen.dump(
+  #     piece_placement: piece_placement,
+  #     pieces_in_hand: [],
+  #     games_turn: ["CHESS", "chess"]
+  #   )
+  #   # => "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess"
+  def self.dump(...)
+    Dumper.dump(...)
   end
 
-  # Parses a FEEN string into position params.
+  # Parses a FEEN string into position components.
   #
-  # @param feen_string [String] FEEN notation string
+  # @see Feen::Parser.parse for the detailed parameters and return value documentation
   # @return [Hash] Hash containing the parsed position data
   # @raise [ArgumentError] If the FEEN string is invalid
   # @example
-  #   feen_string = "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR CHESS/chess -"
+  #   feen_string = "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess"
   #   Feen.parse(feen_string)
   #   # => {
-  #   #      piece_placement: [[{id: 'r'}, {id: 'n'}, {id: 'b'}, {id: 'q'}, {id: 'k', suffix: '='}, {id: 'b'}, {id: 'n'}, {id: 'r'}],
-  #   #                        [{id: 'p'}, {id: 'p'}, {id: 'p'}, {id: 'p'}, {id: 'p'}, {id: 'p'}, {id: 'p'}, {id: 'p'}],
-  #   #                        [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],
-  #   #                        [{id: 'P'}, {id: 'P'}, {id: 'P'}, {id: 'P'}, {id: 'P'}, {id: 'P'}, {id: 'P'}, {id: 'P'}],
-  #   #                        [{id: 'R'}, {id: 'N'}, {id: 'B'}, {id: 'Q'}, {id: 'K', suffix: '='}, {id: 'B'}, {id: 'N'}, {id: 'R'}]],
-  #   #      games_turn: {
-  #   #        active_player: 'CHESS',
-  #   #        inactive_player: 'chess',
-  #   #        uppercase_game: 'CHESS',
-  #   #        lowercase_game: 'chess',
-  #   #        active_player_casing: :uppercase
-  #   #      },
-  #   #      pieces_in_hand: []
+  #   #      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"]
   #   #    }
-  def self.parse(feen_string)
-    Parser.parse(feen_string)
+  def self.parse(...)
+    Parser.parse(...)
   end
 
   # Validates if the given string is a valid FEEN string
   #
-  # @param feen_string [String] FEEN string to validate
+  # @see Feen.parse for parameter details
   # @return [Boolean] True if the string is a valid FEEN string, false otherwise
   # @example
-  #   Feen.valid?("rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR CHESS/chess -") # => true
+  #   Feen.valid?("rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess") # => true
   #   Feen.valid?("invalid feen string") # => false
-  def self.valid?(feen_string)
-    parse(feen_string)
+  def self.valid?(...)
+    parse(...)
     true
   rescue ::ArgumentError
     false
   end
-
-  # Converts a FEN string to a FEEN string for chess positions
-  #
-  # @param fen_string [String] Standard FEN notation string for chess
-  # @return [String] Equivalent FEEN notation string
-  # @raise [ArgumentError] If the FEN string is invalid
-  # @example
-  #   Feen.from_fen("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1")
-  #   # => "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR CHESS/chess -"
-  def self.from_fen(fen_string)
-    Converter.from_fen(fen_string)
-  end
-
-  # Converts a FEEN string to a FEN string for chess positions
-  #
-  # @param feen_string [String] FEEN notation string
-  # @return [String] Equivalent FEN notation string
-  # @raise [ArgumentError] If the FEEN string is invalid
-  # @example
-  #   Feen.to_fen("rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR CHESS/chess -")
-  #   # => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
-  def self.to_fen(feen_string)
-    Converter.to_fen(feen_string)
-  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: feen
 version: !ruby/object:Gem::Version
-  version: 5.0.0.beta2
+  version: 5.0.0.beta3
 platform: ruby
 authors:
 - Cyril Kato
@@ -18,18 +18,21 @@ files:
 - LICENSE.md
 - README.md
 - lib/feen.rb
-- lib/feen/converter.rb
-- lib/feen/converter/from_fen.rb
-- lib/feen/converter/to_fen.rb
 - lib/feen/dumper.rb
 - lib/feen/dumper/games_turn.rb
 - lib/feen/dumper/piece_placement.rb
 - lib/feen/dumper/pieces_in_hand.rb
+- lib/feen/dumper/pieces_in_hand/errors.rb
+- lib/feen/dumper/pieces_in_hand/no_pieces.rb
 - lib/feen/parser.rb
 - lib/feen/parser/games_turn.rb
+- lib/feen/parser/games_turn/errors.rb
+- lib/feen/parser/games_turn/valid_games_turn_pattern.rb
 - lib/feen/parser/piece_placement.rb
 - lib/feen/parser/pieces_in_hand.rb
-- lib/feen/sanitizer.rb
+- lib/feen/parser/pieces_in_hand/errors.rb
+- lib/feen/parser/pieces_in_hand/no_pieces.rb
+- lib/feen/parser/pieces_in_hand/valid_format_pattern.rb
 homepage: https://github.com/sashite/feen.rb
 licenses:
 - MIT
@@ -42,7 +45,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.4.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="