feen 5.0.0.beta3 → 5.0.0.beta4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad6a4426ae68ac5344888465a23eea36cf28b3e0137b50af8483b98288012969
-  data.tar.gz: f9f42840240c5b75629cdb5459f492f966d3fc2706a354c18abc9841a9f17e21
+  metadata.gz: de87bfc9b071e9f1ff14b6f7378ba0a6f9f78cdb9a9bfe32ca00f2494a1be2cd
+  data.tar.gz: fd4d19e8a3b7fb845f081b127a859ff0791c8c11c05e1efb4846152044f67c18
 SHA512:
-  metadata.gz: 31141ae8b866a11ffec6eed44308b475d03e75174ec0bc12b14ff0dc60bfe8b21ad60af3d32e1747d7dce94fe0cff0bbd5add502f26c26aeffac97104fbeeaca
-  data.tar.gz: 82c82de3cf0024e596d9f318e612a8077069a9b519e6b4e753dc808bbee91045f72328489a26307f0877194a4e99ffc8502dd3d3d1610900215ab697fa479ce4
+  metadata.gz: e9fe95297b8577a3bf171a865deca0dc9c2eed91a7d039c04f97077d53d3fa912ca553f28f448f0dd987087926d3ca5225624d7f2d8d08a9275a16a11efe26e0
+  data.tar.gz: b82b7e00f5ece6f5e5859750226be3c74db23e694c8e53def8c8c656fe2fb3ecba7f0f4166cf3d9a4f6c7b4ab7af3cf6544da87a2684e438a389d96e04b3dc75

data/README.md

@@ -5,23 +5,24 @@
 ![Ruby](https://github.com/sashite/feen.rb/actions/workflows/main.yml/badge.svg?branch=main)
 [![License](https://img.shields.io/github/license/sashite/feen.rb?label=License&logo=github)](https://github.com/sashite/feen.rb/raw/main/LICENSE.md)
 
-> **FEEN** (Format for Encounter & Entertainment Notation) support for the Ruby language.
+> **FEEN** (Forsyth–Edwards Enhanced Notation) support for the Ruby language.
 
 ## What is FEEN?
 
-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.
+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.
 
 This gem implements the [FEEN Specification v1.0.0](https://sashite.dev/documents/feen/1.0.0/), providing a Ruby interface for:
 - Representing positions from various games without knowledge of specific rules
 - Supporting boards of arbitrary dimensions
 - Encoding pieces in hand (as used in Shogi)
 - Facilitating serialization and deserialization of positions
+- Ensuring canonical representation for consistent data handling
 
 ## Installation
 
 ```ruby
 # In your Gemfile
-gem "feen", ">= 5.0.0.beta3"
+gem "feen", ">= 5.0.0.beta4"
 ```
 
 Or install manually:
@@ -52,7 +53,7 @@ position = Feen.parse(feen_string)
 
 # Result is a hash:
 # {
-#   "piece_placement" => [
+#   piece_placement: [
 #     ["r", "n", "b", "q", "k=", "b", "n", "r"],
 #     ["p", "p", "p", "p", "p", "p", "p", "p"],
 #     ["", "", "", "", "", "", "", ""],
@@ -62,11 +63,27 @@ position = Feen.parse(feen_string)
 #     ["P", "P", "P", "P", "P", "P", "P", "P"],
 #     ["R", "N", "B", "Q", "K=", "B", "N", "R"]
 #   ],
-#   "games_turn" => ["CHESS", "chess"],
-#   "pieces_in_hand" => []
+#   pieces_in_hand: [],
+#   games_turn: ["CHESS", "chess"]
 # }
 ```
 
+### Safe Parsing
+
+Parse a FEEN string without raising exceptions:
+
+```ruby
+require "feen"
+
+# Valid FEEN string
+result = 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
+result = Feen.safe_parse("invalid feen string")
+# => nil
+```
+
 ### Creating FEEN Strings
 
 Convert position components to a FEEN string using named arguments:
@@ -96,18 +113,28 @@ result = Feen.dump(
 
 ### Validation
 
-Check if a string is valid FEEN notation:
+Check if a string is valid FEEN notation and in canonical form:
 
 ```ruby
 require "feen"
 
-Feen.valid?("rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess")
+# 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
 ```
 
+The `valid?` method performs two levels of validation:
+1. **Syntax check**: Verifies the string can be parsed as FEEN
+2. **Canonicity check**: Ensures the string is in its canonical form through round-trip conversion
+
 ## Game Examples
 
 As FEEN is rule-agnostic, it can represent positions from various board games. Here are some examples:
@@ -125,14 +152,14 @@ In this initial chess position:
 ### Shogi (Japanese Chess)
 
 ```ruby
-feen_string = "lnsgk3l/5g3/p1ppB2pp/9/8B/2P6/P2PPPPPP/3K3R1/5rSNL N5P2g2snl SHOGI/shogi"
+feen_string = "lnsgk3l/5g3/p1ppB2pp/9/8B/2P6/P2PPPPPP/3K3R1/5rSNL N5P2gln2s SHOGI/shogi"
 ```
 
 In this shogi position:
 - The format supports promotions with the `+` prefix (e.g., `+P` for a promoted pawn)
 - The notation allows for pieces in hand, indicated in the second field
 - `SHOGI/shogi` indicates it's Sente's (Black's, uppercase) turn to move
-- `N5P2g2snl` shows the pieces in hand: Sente has a Knight (N) and 5 Pawns (P), while Gote has 2 Golds (g), 2 Silvers (s), a Knight (n), and a Lance (l)
+- `N5P2gln2s` shows the pieces in hand: Sente has a Knight (N) and 5 Pawns (5P), while Gote has 2 Golds (2g), a Lance (l), a Knight (n), and 2 Silvers (2s), all properly sorted in ASCII lexicographic order
 
 ### Makruk (Thai Chess)
 

data/lib/feen/dumper.rb

@@ -6,7 +6,7 @@ require_relative File.join("dumper", "pieces_in_hand")
 
 module Feen
   # 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.
+  # This implements the serialization part of the FEEN (Forsyth–Edwards Enhanced Notation) format.
   module Dumper
     # Field separator used between the three main components of FEEN notation
     FIELD_SEPARATOR = " "

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

@@ -7,7 +7,8 @@ module Feen
       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"
+        invalid_format: "Invalid pieces in hand format: %s",
+        sorting_error:  "Pieces in hand must be in ASCII lexicographic order"
       }.freeze
     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

@@ -3,13 +3,27 @@
 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
+      # 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,32 +1,22 @@
 # 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.
     # 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_format: "Invalid pieces in hand format: %s",
-        sorting_error:  "Pieces in hand must be in ASCII lexicographic order"
-      }.freeze
-
-      # 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<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.
+      #   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
@@ -34,18 +24,26 @@ module Feen
       #   # => []
       #
       # @example Parse multiple pieces in hand
-      #   PiecesInHand.parse("BNPPb")
+      #   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 input
         validate_input_type(pieces_in_hand_str)
         validate_format(pieces_in_hand_str)
 
-        return [] if pieces_in_hand_str == NO_PIECES
+        # Handle the no-pieces case early
+        return [] if pieces_in_hand_str == NoPieces
 
-        pieces = pieces_in_hand_str.chars
-        validate_pieces_order(pieces)
+        # 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
+        # Expand the pieces into an array and maintain lexicographic ordering
+        expand_pieces(pieces_with_counts)
       end
 
       # Validates that the input is a non-empty string.
@@ -54,30 +52,68 @@ module Feen
       # @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?
+        raise ::ArgumentError, format(Errors[:invalid_type], str.class) unless str.is_a?(::String)
+        raise ::ArgumentError, Errors[:empty_string] if str.empty?
       end
 
-      # Validates that the input string matches the expected format.
+      # 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.match?(VALID_FORMAT_PATTERN)
+        return if str == NoPieces || str.match?(ValidFormatPattern)
 
-        raise ::ArgumentError, format(ERRORS[:invalid_format], str)
+        raise ::ArgumentError, format(Errors[:invalid_format], str)
       end
 
-      # Validates that pieces are sorted in ASCII lexicographic order.
+      # Extracts pieces with their counts from the FEEN string.
       #
-      # @param pieces [Array<String>] Array of piece identifiers
-      # @raise [ArgumentError] If pieces are not sorted
+      # @param str [String] FEEN pieces in hand 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
+
+          count_str, piece = match.captures
+          count = count_str ? count_str.to_i : 1
+
+          # Add to our result with piece type and count
+          result << { piece: piece, count: count }
+
+          # Move position forward
+          position += match[0].length
+        end
+
+        result
+      end
+
+      # Validates that pieces are in lexicographic ASCII order.
+      #
+      # @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_pieces_order(pieces)
+      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]
+        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

@@ -6,7 +6,7 @@ require_relative File.join("parser", "pieces_in_hand")
 
 module Feen
   # Module responsible for parsing FEEN notation strings into internal data structures.
-  # FEEN (Format for Encounter & Entertainment Notation) is a compact, canonical, and rule-agnostic
+  # 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
@@ -23,7 +23,7 @@ module Feen
     #   - :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
+    # @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"
@@ -42,25 +42,6 @@ module Feen
     #   #      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)
       feen_string = String(feen_string)
 
@@ -85,5 +66,28 @@ module Feen
         games_turn:
       }
     end
+
+    # Safely parses a complete FEEN string into a structured representation without raising exceptions
+    #
+    # 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

@@ -6,11 +6,19 @@ 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 components into a FEEN string.
   #
-  # @see Feen::Dumper.dump for the detailed parameters documentation
+  # @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 any parameter is invalid
   # @example
@@ -30,14 +38,17 @@ module Feen
   #     games_turn: ["CHESS", "chess"]
   #   )
   #   # => "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess"
-  def self.dump(...)
-    Dumper.dump(...)
+  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 components.
   #
-  # @see Feen::Parser.parse for the detailed parameters and return value documentation
-  # @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"
@@ -56,21 +67,63 @@ module Feen
   #   #      pieces_in_hand: [],
   #   #      games_turn: ["CHESS", "chess"]
   #   #    }
-  def self.parse(...)
-    Parser.parse(...)
+  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.
+  #
+  # This method works like `parse` but returns nil instead of raising an exception
+  # if the FEEN string is invalid.
   #
-  # @see Feen.parse for parameter details
-  # @return [Boolean] True if the string is a valid FEEN string, false otherwise
+  # @param feen_string [String] Complete FEEN notation string
+  # @return [Hash, nil] Hash containing the parsed position data or nil if parsing fails
   # @example
-  #   Feen.valid?("rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess") # => true
+  #   # 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
+
+  # Validates if the given string is a valid and canonical FEEN string
+  #
+  # 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
+  #   # 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
-  def self.valid?(...)
-    parse(...)
-    true
-  rescue ::ArgumentError
-    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.beta3
+  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: []
@@ -32,12 +35,20 @@ files:
 - lib/feen/parser/pieces_in_hand.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
@@ -54,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: []