feen 5.0.0.beta2 → 5.0.0.beta4

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

@@ -0,0 +1,15 @@
+# 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",
+        sorting_error:  "Pieces in hand must be in ASCII lexicographic order"
+      }.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/piece_count_pattern.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Feen
+  module Parser
+    module PiecesInHand
+      # Regex to extract piece counts from pieces in hand string
+      # Matches either:
+      # - A single piece character with no count (e.g., "P")
+      # - A count followed by a piece character (e.g., "5P")
+      PieceCountPattern = /(?:([2-9]|\d{2,}))?([A-Za-z])/
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Feen
+  module Parser
+    module PiecesInHand
+      # Valid pattern for pieces in hand based on BNF specification.
+      #
+      # The FEEN format specifies these rules for numeric prefixes:
+      # - Cannot start with "0"
+      # - Cannot be exactly "1" (use the letter without prefix instead)
+      # - Can be 2-9 or any number with 2+ digits (10, 11, etc.)
+      #
+      # The pattern matches either:
+      # - A single digit from 2-9
+      # - OR any number with two or more digits (10, 11, 27, 103, etc.)
+      #
+      # @return [Regexp] Regular expression for validating pieces in hand format
+      ValidFormatPattern = /\A
+        (?:
+          -|                                              # No pieces in hand
+          (?:                                             # Or sequence of pieces
+            (?:(?:[2-9]|\d{2,})?[A-Z])*                   # Uppercase pieces (optional)
+            (?:(?:[2-9]|\d{2,})?[a-z])*                   # Lowercase pieces (optional)
+          )
+        )
+      \z/x
+    end
+  end
+end

data/lib/feen/parser/pieces_in_hand.rb

@@ -1,74 +1,119 @@
 # frozen_string_literal: true
 
+require_relative File.join("pieces_in_hand", "errors")
+require_relative File.join("pieces_in_hand", "no_pieces")
+require_relative File.join("pieces_in_hand", "piece_count_pattern")
+require_relative File.join("pieces_in_hand", "valid_format_pattern")
+
 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
-      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
+      # 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), expanded
+      #   based on their counts and 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("BN2Pb")
+      #   # => ["B", "N", "P", "P", "b"]
+      #
+      # @example Parse pieces with counts
+      #   PiecesInHand.parse("N5P2b")
+      #   # => ["N", "P", "P", "P", "P", "P", "b", "b"]
       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
+        # Validate input
+        validate_input_type(pieces_in_hand_str)
+        validate_format(pieces_in_hand_str)
 
-        pieces = []
-        i = 0
+        # Handle the no-pieces case early
+        return [] if pieces_in_hand_str == NoPieces
 
-        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]/)
+        # Extract pieces with their counts and validate the order
+        pieces_with_counts = extract_pieces_with_counts(pieces_in_hand_str)
+        validate_lexicographic_order(pieces_with_counts)
 
-          pieces << { id: pieces_in_hand_str[i] }
-          i += 1
+        # Expand the pieces into an array and maintain lexicographic ordering
+        expand_pieces(pieces_with_counts)
+      end
 
-        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
 
-        # 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)
+      # Validates that the input string matches the expected format according to FEEN specification.
+      #
+      # @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 == NoPieces || str.match?(ValidFormatPattern)
 
-        pieces
+        raise ::ArgumentError, format(Errors[:invalid_format], str)
       end
 
-      # Validates the pieces in hand string for syntax
+      # Extracts pieces with their counts from the FEEN string.
       #
       # @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)
+      # @return [Array<Hash>] Array of hashes with :piece and :count keys
+      private_class_method def self.extract_pieces_with_counts(str)
+        result = []
+        position = 0
+
+        while position < str.length
+          match = str[position..].match(PieceCountPattern)
+          break unless match
 
-        raise ArgumentError, ERRORS[:empty_string] if str.empty?
+          count_str, piece = match.captures
+          count = count_str ? count_str.to_i : 1
 
-        # Check for the special case of no pieces in hand
-        return if str == NO_PIECES
+          # Add to our result with piece type and count
+          result << { piece: piece, count: count }
 
-        # Check for valid characters (only letters)
-        valid_chars = /\A[a-zA-Z]+\z/
-        return if str.match?(valid_chars)
+          # Move position forward
+          position += match[0].length
+        end
 
-        invalid_chars = str.scan(/[^a-zA-Z]/).uniq.join(", ")
-        raise ArgumentError, format(ERRORS[:invalid_chars], invalid_chars)
+        result
       end
 
-      # Checks if pieces are sorted in ASCII lexicographic order
+      # Validates that pieces are in lexicographic ASCII 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_with_counts [Array<Hash>] Array of pieces with their counts
+      # @raise [ArgumentError] If pieces are not in lexicographic order
+      # @return [void]
+      private_class_method def self.validate_lexicographic_order(pieces_with_counts)
+        pieces = pieces_with_counts.map { |item| item[:piece] }
+
+        # Verify the array is sorted lexicographically
+        return if pieces == pieces.sort
+
+        raise ::ArgumentError, Errors[:sorting_error]
+      end
+
+      # Expands the pieces based on their counts into an array.
+      #
+      # @param pieces_with_counts [Array<Hash>] Array of pieces with their counts
+      # @return [Array<String>] Array of expanded pieces
+      private_class_method def self.expand_pieces(pieces_with_counts)
+        pieces_with_counts.flat_map do |item|
+          Array.new(item[:count], item[:piece])
+        end
       end
     end
   end

data/lib/feen/parser.rb

@@ -5,48 +5,89 @@ 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 (Forsyth–Edwards Enhanced 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
+    # @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
+    #
+    # @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"]
+    #   #    }
     def self.parse(feen_string)
-      validate_feen_string(feen_string)
+      feen_string = String(feen_string)
 
-      # Split the FEEN string into its three fields
-      fields = feen_string.strip.split(/\s+/)
+      # Match the FEEN string against the expected pattern
+      match = FEEN_PATTERN.match(feen_string)
 
-      raise ArgumentError, "Invalid FEEN format: expected 3 fields, got #{fields.size}" unless fields.size == 3
+      # Raise an error if the format doesn't match the expected pattern
+      raise ::ArgumentError, INVALID_FORMAT_ERROR unless match
+
+      # 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
+    # Safely parses a complete FEEN string into a structured representation without raising exceptions
     #
-    # @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"
+    # This method works like `parse` but returns nil instead of raising an exception
+    # if the FEEN string is invalid.
+    #
+    # @param feen_string [String] Complete FEEN notation string
+    # @return [Hash, nil] Hash containing the parsed position data or nil if parsing fails
+    #
+    # @example Parsing a valid FEEN string
+    #   feen = "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess"
+    #   result = Feen::Parser.safe_parse(feen)
+    #   # => {piece_placement: [...], pieces_in_hand: [...], games_turn: [...]}
+    #
+    # @example Parsing an invalid FEEN string
+    #   feen = "invalid feen string"
+    #   result = Feen::Parser.safe_parse(feen)
+    #   # => nil
+    def self.safe_parse(feen_string)
+      parse(feen_string)
+    rescue ::ArgumentError
+      nil
     end
   end
 end

data/lib/feen.rb

@@ -1,110 +1,129 @@
 # frozen_string_literal: true
 
-require_relative File.join("feen", "converter")
 require_relative File.join("feen", "dumper")
 require_relative File.join("feen", "parser")
 
 # This module provides a Ruby interface for data serialization and
 # deserialization in FEEN format.
 #
+# FEEN (Forsyth–Edwards Enhanced Notation) is a compact, canonical, and
+# rule-agnostic textual format for representing static board positions
+# in two-player piece-placement games.
+#
 # @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
+  # @param piece_placement [Array] Board position data structure representing the spatial
+  #                               distribution of pieces across the board
+  # @param pieces_in_hand [Array<String>] Pieces available for dropping onto the board
+  # @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] 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(piece_placement:, pieces_in_hand:, games_turn:)
+    Dumper.dump(piece_placement:, pieces_in_hand:, games_turn:)
   end
 
-  # Parses a FEEN string into position params.
+  # Parses a FEEN string into position components.
   #
-  # @param feen_string [String] FEEN notation string
-  # @return [Hash] Hash containing the parsed position data
+  # @param feen_string [String] Complete FEEN notation string
+  # @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
   # @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)
   end
 
-  # Validates if the given string is a valid FEEN string
+  # Safely parses a FEEN string into position components without raising exceptions.
   #
-  # @param feen_string [String] FEEN string to validate
-  # @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?("invalid feen string") # => false
-  def self.valid?(feen_string)
-    parse(feen_string)
-    true
-  rescue ::ArgumentError
-    false
-  end
-
-  # Converts a FEN string to a FEEN string for chess positions
+  # This method works like `parse` but returns nil instead of raising an exception
+  # if the FEEN string is invalid.
   #
-  # @param fen_string [String] Standard FEN notation string for chess
-  # @return [String] Equivalent FEEN notation string
-  # @raise [ArgumentError] If the FEN string is invalid
+  # @param feen_string [String] Complete FEEN notation string
+  # @return [Hash, nil] Hash containing the parsed position data or nil if parsing fails
   # @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)
+  #   # Valid FEEN string
+  #   Feen.safe_parse("rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess")
+  #   # => {piece_placement: [...], pieces_in_hand: [...], games_turn: [...]}
+  #
+  #   # Invalid FEEN string
+  #   Feen.safe_parse("invalid feen string")
+  #   # => nil
+  def self.safe_parse(feen_string)
+    Parser.safe_parse(feen_string)
   end
 
-  # Converts a FEEN string to a FEN string for chess positions
+  # Validates if the given string is a valid and canonical FEEN string
   #
-  # @param feen_string [String] FEEN notation string
-  # @return [String] Equivalent FEN notation string
-  # @raise [ArgumentError] If the FEEN string is invalid
+  # This method performs a complete validation in two steps:
+  # 1. Syntax check: Verifies the string can be parsed as FEEN
+  # 2. Canonicity check: Ensures the string is in canonical form by comparing
+  #    it with a freshly generated FEEN string created from its parsed components
+  #
+  # This approach guarantees that the string not only follows FEEN syntax
+  # but is also in its most compact, canonical representation.
+  #
+  # @param feen_string [String] FEEN string to validate
+  # @return [Boolean] True if the string is a valid and canonical FEEN string
   # @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)
+  #   # Canonical form
+  #   Feen.valid?("lnsgk3l/5g3/p1ppB2pp/9/8B/2P6/P2PPPPPP/3K3R1/5rSNL N5P2gln2s SHOGI/shogi") # => true
+  #
+  #   # Invalid syntax
+  #   Feen.valid?("invalid feen string") # => false
+  #
+  #   # Valid syntax but non-canonical form (pieces in hand not in lexicographic order)
+  #   Feen.valid?("lnsgk3l/5g3/p1ppB2pp/9/8B/2P6/P2PPPPPP/3K3R1/5rSNL N5P2gn2sl SHOGI/shogi") # => false
+  def self.valid?(feen_string)
+    # First check: Basic syntax validation
+    begin
+      parsed_data = parse(feen_string)
+    rescue ::ArgumentError
+      return false
+    end
+
+    # Second check: Canonicity validation through round-trip conversion
+    # Generate a fresh FEEN string from the parsed data
+    canonical_feen = dump(**parsed_data)
+
+    # Compare the original string with the canonical form
+    feen_string == canonical_feen
   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.beta4
 platform: ruby
 authors:
 - Cyril Kato
@@ -10,6 +10,9 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: A Ruby interface for data serialization and deserialization in FEEN format.
+  FEEN is a compact, canonical, and rule-agnostic textual format for representing
+  static board positions in two-player piece-placement games like Chess, Shogi, Xiangqi,
+  and others.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -18,23 +21,34 @@ 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/piece_count_pattern.rb
+- lib/feen/parser/pieces_in_hand/valid_format_pattern.rb
 homepage: https://github.com/sashite/feen.rb
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/sashite/feen.rb/issues
+  documentation_uri: https://rubydoc.info/github/sashite/feen.rb/main
+  homepage_uri: https://github.com/sashite/feen.rb
+  source_code_uri: https://github.com/sashite/feen.rb
+  specification_uri: https://sashite.dev/documents/feen/1.0.0/
+  funding_uri: https://github.com/sponsors/cyril
   rubygems_mfa_required: 'true'
+  article_uri: https://blog.cyril.email/posts/2025-05-01/introducing-feen-notation.html
 rdoc_options: []
 require_paths:
 - lib
@@ -42,7 +56,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:
   - - ">="
@@ -51,5 +65,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.7
 specification_version: 4
-summary: FEEN support for the Ruby language.
+summary: FEEN (Forsyth–Edwards Enhanced Notation) support for the Ruby language.
 test_files: []