feen 5.0.0.beta3 → 5.0.0.beta5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad6a4426ae68ac5344888465a23eea36cf28b3e0137b50af8483b98288012969
-  data.tar.gz: f9f42840240c5b75629cdb5459f492f966d3fc2706a354c18abc9841a9f17e21
+  metadata.gz: 28b60c3d60fd3241172fee9e143c53e6dca04082a2efe7f0fa7559b85dc6eac0
+  data.tar.gz: a15999144de7bcd5637b6efca4ed1c4a8ae7d3757d6d583123dfaf44468d6d35
 SHA512:
-  metadata.gz: 31141ae8b866a11ffec6eed44308b475d03e75174ec0bc12b14ff0dc60bfe8b21ad60af3d32e1747d7dce94fe0cff0bbd5add502f26c26aeffac97104fbeeaca
-  data.tar.gz: 82c82de3cf0024e596d9f318e612a8077069a9b519e6b4e753dc808bbee91045f72328489a26307f0877194a4e99ffc8502dd3d3d1610900215ab697fa479ce4
+  metadata.gz: 861669bea6101dba5eefcf6062b9e4e0b37152618e7ffa9c1ba963eb37b2f49cad804f4c1bbee31bd030bf4ddd9602563df7e54cc244384d37e1f45ec748c5ff
+  data.tar.gz: 6f00dcfc09fd378fde0fbe3cd36b078718eab1fa27e208d474637ef89853a7543be4027116d623d0e037c340f0deeae90ce337404db09c953faecba852f56ece

data/README.md

@@ -5,23 +5,25 @@
 ![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.beta5"
 ```
 
 Or install manually:
@@ -47,26 +49,42 @@ Convert a FEEN string into a structured Ruby object:
 ```ruby
 require "feen"
 
-feen_string = "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess"
+feen_string = "r'nbqkbnr'/pppppppp/8/8/8/8/PPPPPPPP/R'NBQKBNR' - CHESS/chess"
 position = Feen.parse(feen_string)
 
 # Result is a hash:
 # {
-#   "piece_placement" => [
-#     ["r", "n", "b", "q", "k=", "b", "n", "r"],
+#   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"]
+#     ["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("r'nbqkbnr'/pppppppp/8/8/8/8/PPPPPPPP/R'NBQKBNR' - 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:
@@ -76,14 +94,14 @@ require "feen"
 
 # Representation of a chess board in initial position
 piece_placement = [
-  ["r", "n", "b", "q", "k=", "b", "n", "r"],
+  ["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"]
+  ["R'", "N", "B", "Q", "K", "B", "N", "R'"]
 ]
 
 result = Feen.dump(
@@ -91,23 +109,34 @@ result = Feen.dump(
   games_turn:      %w[CHESS chess],
   pieces_in_hand:  []
 )
-# => "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess"
+# => "r'nbqkbnr'/pppppppp/8/8/8/8/PPPPPPPP/R'NBQKBNR' - CHESS/chess"
 ```
 
 ### 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:
@@ -115,24 +144,26 @@ As FEEN is rule-agnostic, it can represent positions from various board games. H
 ### International Chess
 
 ```ruby
-feen_string = "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess"
+feen_string = "r'nbqkbnr'/pppppppp/8/8/8/8/PPPPPPPP/R'NBQKBNR' - CHESS/chess"
 ```
 
 In this initial chess position:
-- The `=` suffixes on kings indicate castling rights on both sides (though FEEN doesn't define this semantics)
+
+- The `'` suffixes on rooks indicate an intermediate state (which might represent castling rights in chess, though FEEN doesn't define this semantics)
 - The third field `CHESS/chess` indicates it's the player with uppercase pieces' turn to move
 
 ### 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)
 
@@ -149,6 +180,7 @@ feen_string = "rheagaehr/9/1c5c1/s1s1s1s1s/9/9/S1S1S1S1S/1C5C1/9/RHEAGAEHR - XIA
 ```
 
 In this Xiangqi position:
+
 - The representation uses single letters for the different pieces
 - The format naturally adapts to the presence of a "river" (empty space in the middle)
 
@@ -185,19 +217,15 @@ result = Feen.dump(
 
 FEEN supports prefixes and suffixes for pieces to denote various states or capabilities:
 
-- **Prefix `+`**: May indicate promotion or special state
+- **Prefix `+`**: Enhanced state
   - Example in shogi: `+P` may represent a promoted pawn
 
-- **Suffix `=`**: May indicate dual-option status
-  - Example in chess: `K=` may represent a king eligible for both kingside and queenside castling
-
-- **Suffix `<`**: May indicate left-side constraint
-  - Example in chess: `K<` may represent a king eligible for queenside castling only
-  - Example in chess: `P<` may represent a pawn that may be captured _en passant_ from the left
+- **Prefix `-`**: Diminished state
+  - Could represent a piece with limited movement or other restrictions
 
-- **Suffix `>`**: May indicate right-side constraint
-  - Example in chess: `K>` may represent a king eligible for kingside castling only
-  - Example in chess: `P>` may represent a pawn that may be captured en passant from the right
+- **Suffix `'`**: Intermediate state
+  - Example in chess: `R'` may represent a rook that has intermediate status (such as castling eligibility)
+  - Example in chess: `P'` may represent a pawn that may be captured _en passant_
 
 These modifiers have no defined semantics in the FEEN specification itself but provide a flexible framework for representing piece-specific conditions while maintaining FEEN's rule-agnostic nature.
 
@@ -212,4 +240,4 @@ The [gem](https://rubygems.org/gems/feen) is available as open source under the
 
 ## About Sashité
 
-This project is maintained by [Sashité](https://sashite.com/) - a project dedicated to promoting chess variants and sharing the beauty of Chinese, Japanese, and Western chess cultures.
+This project is maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of Chinese, Japanese, and Western chess cultures.

data/lib/feen/dumper/piece_placement.rb

@@ -7,7 +7,7 @@ module Feen
       #
       # @param piece_placement [Array] Hierarchical array representing the board where:
       #   - Empty squares are represented by empty strings ("")
-      #   - Pieces are represented by strings (e.g., "r", "K=", "+P")
+      #   - Pieces are represented by strings (e.g., "r", "R'", "+P")
       #   - Dimensions are represented by nested arrays
       # @return [String] FEEN piece placement string
       # @raise [ArgumentError] If the piece placement structure is invalid

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 = " "
@@ -23,19 +23,19 @@ module Feen
     # @example Creating a FEEN string for chess initial position
     #   Feen::Dumper.dump(
     #     piece_placement: [
-    #       ["r", "n", "b", "q", "k=", "b", "n", "r"],
+    #       ["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"]
+    #       ["R'", "N", "B", "Q", "K", "B", "N", "R'"]
     #     ],
     #     pieces_in_hand: [],
     #     games_turn: ["CHESS", "chess"]
     #   )
-    #   # => "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess"
+    #   # => "r'nbqkbnr'/pppppppp/8/8/8/8/PPPPPPPP/R'NBQKBNR' - CHESS/chess"
     #
     # @param piece_placement [Array] Board position data structure representing the spatial
     #                                distribution of pieces across the board, where each cell

data/lib/feen/parser/piece_placement.rb

@@ -30,10 +30,8 @@ module Feen
       VALID_PREFIXES = [PREFIX_PROMOTION, PREFIX_DIMINISHED].freeze
 
       # Valid piece suffixes
-      SUFFIX_EQUALS = "="
-      SUFFIX_LEFT = "<"
-      SUFFIX_RIGHT = ">"
-      VALID_SUFFIXES = [SUFFIX_EQUALS, SUFFIX_LEFT, SUFFIX_RIGHT].freeze
+      SUFFIX_INTERMEDIATE = "'"
+      VALID_SUFFIXES = [SUFFIX_INTERMEDIATE].freeze
 
       # Build validation pattern step by step to match BNF
       # <letter> ::= <letter-lowercase> | <letter-uppercase>
@@ -42,8 +40,8 @@ module Feen
       # <prefix> ::= "+" | "-"
       PREFIX = "[+-]"
 
-      # <suffix> ::= "=" | "<" | ">"
-      SUFFIX = "[=<>]"
+      # <suffix> ::= "'"
+      SUFFIX = "[']"
 
       # <piece> ::= <letter> | <prefix> <letter> | <letter> <suffix> | <prefix> <letter> <suffix>
       PIECE = "(?:#{PREFIX}?#{LETTER}#{SUFFIX}?)"

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,44 +23,25 @@ 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"
+    #   feen = "r'nbqkbnr'/pppppppp/8/8/8/8/PPPPPPPP/R'NBQKBNR' - CHESS/chess"
     #   result = Feen::Parser.parse(feen)
     #   # => {
     #   #      piece_placement: [
-    #   #        ["r", "n", "b", "q", "k=", "b", "n", "r"],
+    #   #        ["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"]
+    #   #        ["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)
       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 = "r'nbqkbnr'/pppppppp/8/8/8/8/PPPPPPPP/R'NBQKBNR' - 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,71 +6,124 @@ 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
   #   piece_placement = [
-  #     ["r", "n", "b", "q", "k=", "b", "n", "r"],
+  #     ["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"]
+  #     ["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(...)
+  #   # => "r'nbqkbnr'/pppppppp/8/8/8/8/PPPPPPPP/R'NBQKBNR' - 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 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"
+  #   feen_string = "r'nbqkbnr'/pppppppp/8/8/8/8/PPPPPPPP/R'NBQKBNR' - CHESS/chess"
   #   Feen.parse(feen_string)
   #   # => {
   #   #      piece_placement: [
-  #   #        ["r", "n", "b", "q", "k=", "b", "n", "r"],
+  #   #        ["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"]
+  #   #        ["R'", "N", "B", "Q", "K", "B", "N", "R'"]
   #   #      ],
   #   #      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("r'nbqkbnr'/pppppppp/8/8/8/8/PPPPPPPP/R'NBQKBNR' - 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.beta5
 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,11 +35,17 @@ 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/
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -54,5 +63,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: []