feen 5.0.0.beta8 → 5.0.0.beta9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e4b55ca0d1584708dbb732475262b5c22ce42fc8c77b6822a51a19832fde6ca
-  data.tar.gz: 9662571dc247824251d1d256783dac5236e5f54acbdb5fb9041d4c2471733f0a
+  metadata.gz: bac9b628685776db7be71e57f80638a6479f03175da5b182154254f6aa0573e2
+  data.tar.gz: 77f99b0ee0ce4d0a4846f5a134ab85cc35ae0919df5f75b18eb9bc688c1d1530
 SHA512:
-  metadata.gz: 5d8c6e55a5d6ec7809af8df89ee212503dccc67590384ec9c6e403a4dab5a8b54bcc2c4dd93a6fef0060e23f327e592a8263779bc1060ab74738306b0ce7a117
-  data.tar.gz: 68cc013cef6eac0309a2241c697133459f242fa472325e2dd0e8a97ec2c7d134c372883e16f1532ba7ba8a3ca8bb793ed93e1f2a670427bc6698a9a2601cb95b
+  metadata.gz: a195a54e16d82c53e60e9001e4111800d6d6af6a04c68517599f04b4478b84b4a96ef6a0ead6034458aafc3c7aefe80a7c55cf6d9e780a0aa933cf2b8d566f16
+  data.tar.gz: 864de377e1c97fa20f5d723865e8115468bd139b406889b44a956f55beec20f18d1e7a93fc97e033f873a0ab12c9d96f8cb82bb1ab32da48f643da0e07c6f49f

data/README.md

@@ -24,7 +24,7 @@ FEEN is like taking a snapshot of any board game position and turning it into a
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "feen", ">= 5.0.0.beta8"
+gem "feen", ">= 5.0.0.beta9"
 ```
 
 Or install it directly:
@@ -45,8 +45,8 @@ board = [["r", "k", "r"]]
 
 feen_string = Feen.dump(
   piece_placement: board,
-  pieces_in_hand:  [],           # No captured pieces
-  games_turn:      ["GAME", "game"]  # GAME player's turn
+  pieces_in_hand:  [],              # No captured pieces
+  games_turn:      ["GAME", "game"] # GAME player's turn
 )
 
 feen_string # => "rkr / GAME/game"
@@ -87,11 +87,11 @@ The board shows where pieces are placed:
 **Examples:**
 
 ```ruby
-"K"           # Single piece on 1x1 board
-"3"           # Three empty squares
-"Kqr"         # Three pieces: K, q, r
-"K2r"         # K, two empty squares, then r
-"Kqr/3/R2k"   # 3x3 board with multiple ranks
+"K"         # Single piece on 1x1 board
+"3"         # Three empty squares
+"Kqr"       # Three pieces: K, q, r
+"K2r"       # K, two empty squares, then r
+"Kqr/3/R2k" # 3x3 board with multiple ranks
 ```
 
 ### Part 2: Captured Pieces (Pieces in Hand)
@@ -106,10 +106,10 @@ Shows pieces that have been captured and can potentially be used again:
 **Examples:**
 
 ```ruby
-"/"          # No pieces captured
-"P/"         # First player has one P piece
-"/p"         # Second player has one p piece
-"2PK/3p"     # First player: 2 P's + 1 K, Second player: 3 p's
+"/"         # No pieces captured
+"P/"        # First player has one P piece
+"/p"        # Second player has one p piece
+"2PK/3p"    # First player: 2 P's + 1 K, Second player: 3 p's
 ```
 
 ### Part 3: Turn Information
@@ -123,9 +123,9 @@ Shows whose turn it is and identifies the game types:
 **Examples:**
 
 ```ruby
-"CHESS/chess"    # CHESS player (uppercase pieces) to move
-"shogi/SHOGI"    # shogi player (lowercase pieces) to move
-"GAME1/game2"    # Mixed game types
+"CHESS/chess" # CHESS player (uppercase pieces) to move
+"shogi/SHOGI" # shogi player (lowercase pieces) to move
+"GAME1/game2" # GAME1 player (uppercase pieces) to move (mixed game types)
 ```
 
 ## Complete API Reference
@@ -147,9 +147,9 @@ Converts position components into a FEEN string.
 
 ```ruby
 board = [
-  ["r", "n", "k", "n", "r"],   # Back rank
-  ["", "", "", "", ""],        # Empty rank
-  ["P", "P", "P", "P", "P"]    # Front rank
+  ["r", "n", "k", "n", "r"],  # Back rank
+  ["", "", "", "", ""],       # Empty rank
+  ["P", "P", "P", "P", "P"]   # Front rank
 ]
 
 feen = Feen.dump(
@@ -214,9 +214,9 @@ Checks if a string is valid, canonical FEEN notation.
 **Example:**
 
 ```ruby
-Feen.valid?("k/K / GAME/game")        # => true
-Feen.valid?("invalid")                # => false
-Feen.valid?("k/K P3K/ GAME/game")     # => false (wrong piece order)
+Feen.valid?("k/K / GAME/game")    # => true
+Feen.valid?("invalid")            # => false
+Feen.valid?("k/K P3K/ GAME/game") # => false (wrong piece order)
 ```
 
 ## Working with Different Board Sizes
@@ -313,8 +313,8 @@ For games that need special piece states, use modifiers **only on the board**:
 
 ```ruby
 board = [
-  ["+P", "K", "-R"],    # Enhanced pawn, King, diminished rook
-  ["N'", "", "B"]       # Knight with special state, empty, Bishop
+  ["+P", "K", "-R"],  # Enhanced pawn, King, diminished rook
+  ["N'", "", "B"]     # Knight with special state, empty, Bishop
 ]
 
 # Note: Modifiers (+, -, ') are ONLY allowed on the board
@@ -335,9 +335,9 @@ FEEN can represent positions mixing different game systems:
 ```ruby
 # FOO pieces vs bar pieces
 mixed_feen = Feen.dump(
-  piece_placement: ["K", "G", "k", "r"],    # Mixed piece types
-  pieces_in_hand:  ["P", "g"],              # Captured from both sides
-  games_turn:      ["bar", "FOO"]           # Different game systems
+  piece_placement: ["K", "G", "k", "r"],  # Mixed piece types
+  pieces_in_hand:  ["P", "g"],            # Captured from both sides
+  games_turn:      ["bar", "FOO"]         # Different game systems
 )
 
 mixed_feen # => "KGkr P/g bar/FOO"
@@ -350,16 +350,16 @@ mixed_feen # => "KGkr P/g bar/FOO"
 ```ruby
 # ERROR: Wrong argument types
 Feen.dump(
-  piece_placement: "not an array",    # Must be Array
-  pieces_in_hand:  "not an array",   # Must be Array
-  games_turn:      "not an array"    # Must be Array[2]
+  piece_placement: "not an array",  # Must be Array
+  pieces_in_hand:  "not an array",  # Must be Array
+  games_turn:      "not an array"   # Must be Array[2]
 )
 # => ArgumentError
 
 # ERROR: Modifiers in captured pieces
 Feen.dump(
   piece_placement: [["K"]],
-  pieces_in_hand:  ["+P"],           # Invalid: no modifiers allowed
+  pieces_in_hand:  ["+P"],          # Invalid: no modifiers allowed
   games_turn:      ["GAME", "game"]
 )
 # => ArgumentError
@@ -368,7 +368,7 @@ Feen.dump(
 Feen.dump(
   piece_placement: [["K"]],
   pieces_in_hand:  [],
-  games_turn:      ["GAME", "ALSO"]  # Must be different cases
+  games_turn:      ["GAME", "ALSO"] # Must be different cases
 )
 # => ArgumentError
 ```
@@ -450,7 +450,7 @@ end
 db = PositionDatabase.new
 db.store_position("start", [["r", "k", "r"]], [], ["GAME", "game"])
 position = db.retrieve_position("start")
-# => {piece_placement: [["r", "k", "r"]], pieces_in_hand: [], games_turn: ["GAME", "game"]}
+# => { piece_placement: [["r", "k", "r"]], pieces_in_hand: [], games_turn: ["GAME", "game"] }
 ```
 
 ## Best Practices

data/lib/feen/dumper/games_turn.rb

@@ -25,7 +25,7 @@ module Feen
       #   # => "CHESS/chess"
       #
       # @example Invalid - same casing
-      #   GamesTurn.dump("CHESS", "SHOGI")
+      #   GamesTurn.dump("CHESS", "MAKRUK")
       #   # => ArgumentError: One variant must be uppercase and the other lowercase
       def self.dump(active_variant, inactive_variant)
         validate_variants(active_variant, inactive_variant)

data/lib/feen/parser/games_turn.rb

@@ -15,8 +15,8 @@ module Feen
       # <games-turn> ::= <game-id-uppercase> "/" <game-id-lowercase>
       #                | <game-id-lowercase> "/" <game-id-uppercase>
       VALID_GAMES_TURN_PATTERN = %r{
-        \A                    # Start of string
-        (?:                   # Non-capturing group for alternatives
+        \A                            # Start of string
+        (?:                           # Non-capturing group for alternatives
           (?<uppercase_first>[A-Z]+)  # Named group: uppercase identifier first
           /                           # Separator
           (?<lowercase_second>[a-z]+) # Named group: lowercase identifier second
@@ -25,7 +25,7 @@ module Feen
           /                           # Separator
           (?<uppercase_second>[A-Z]+) # Named group: uppercase identifier second
         )
-        \z                    # End of string
+        \z                            # End of string
       }x
 
       # Parses the games turn section of a FEEN string
@@ -35,12 +35,12 @@ module Feen
       # @raise [ArgumentError] If the input string is invalid
       #
       # @example Valid games turn string with uppercase first
-      #   GamesTurn.parse("CHESS/shogi")
-      #   # => ["CHESS", "shogi"]
+      #   GamesTurn.parse("CHESS/ogi")
+      #   # => ["CHESS", "ogi"]
       #
       # @example Valid games turn string with lowercase first
-      #   GamesTurn.parse("chess/SHOGI")
-      #   # => ["chess", "SHOGI"]
+      #   GamesTurn.parse("chess/OGI")
+      #   # => ["chess", "OGI"]
       def self.parse(games_turn_str)
         validate_input_type(games_turn_str)
 

data/lib/feen/parser/piece_placement.rb

@@ -3,6 +3,14 @@
 module Feen
   module Parser
     # Handles parsing of the piece placement section of a FEEN string
+    #
+    # This module is responsible for converting the first field of a FEEN string
+    # (piece placement) into a hierarchical array structure representing the board.
+    # It supports arbitrary dimensions and handles both pieces (with optional PNN modifiers)
+    # and empty squares (represented by numbers).
+    #
+    # @see https://sashite.dev/documents/feen/1.0.0/ FEEN Specification
+    # @see https://sashite.dev/documents/pnn/1.0.0/ PNN Specification
     module PiecePlacement
       # Simplified error messages
       ERRORS = {
@@ -16,11 +24,78 @@ module Feen
 
       # Parses the piece placement section of a FEEN string
       #
+      # Converts a FEEN piece placement string into a hierarchical array structure
+      # representing the board where empty squares are represented by empty strings
+      # and pieces are represented by strings containing their PNN identifier and
+      # optional modifiers.
+      #
       # @param piece_placement_str [String] FEEN piece placement string
       # @return [Array] Hierarchical array structure representing the board where:
       #   - Empty squares are represented by empty strings ("")
       #   - Pieces are represented by strings containing their identifier and optional modifiers
       # @raise [ArgumentError] If the input string is invalid
+      #
+      # @example Parse a simple 2D chess position (initial position)
+      #   PiecePlacement.parse("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR")
+      #   # => [
+      #   #      ["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"]
+      #   #    ]
+      #
+      # @example Parse a single rank with mixed pieces and empty squares
+      #   PiecePlacement.parse("r2k1r")
+      #   # => ["r", "", "", "k", "", "r"]
+      #
+      # @example Parse pieces with PNN modifiers (promoted pieces in Shogi)
+      #   PiecePlacement.parse("+P+Bk")
+      #   # => ["+P", "+B", "k"]
+      #
+      # @example Parse a 3D board structure (2 planes of 2x2)
+      #   PiecePlacement.parse("rn/pp//RN/PP")
+      #   # => [
+      #   #      [["r", "n"], ["p", "p"]],
+      #   #      [["R", "N"], ["P", "P"]]
+      #   #    ]
+      #
+      # @example Parse complex Shogi position with promoted pieces
+      #   PiecePlacement.parse("9/9/9/9/4+P4/9/5+B3/9/9")
+      #   # => [
+      #   #      ["", "", "", "", "", "", "", "", ""],
+      #   #      ["", "", "", "", "", "", "", "", ""],
+      #   #      ["", "", "", "", "", "", "", "", ""],
+      #   #      ["", "", "", "", "", "", "", "", ""],
+      #   #      ["", "", "", "", "+P", "", "", "", ""],
+      #   #      ["", "", "", "", "", "", "", "", ""],
+      #   #      ["", "", "", "", "", "+B", "", "", ""],
+      #   #      ["", "", "", "", "", "", "", "", ""],
+      #   #      ["", "", "", "", "", "", "", "", ""]
+      #   #    ]
+      #
+      # @example Parse irregular board shapes (different rank sizes)
+      #   PiecePlacement.parse("rnbqkbnr/ppppppp/8")
+      #   # => [
+      #   #      ["r", "n", "b", "q", "k", "b", "n", "r"],  # 8 cells
+      #   #      ["p", "p", "p", "p", "p", "p", "p"],       # 7 cells
+      #   #      ["", "", "", "", "", "", "", ""]           # 8 cells
+      #   #    ]
+      #
+      # @example Parse large numbers of empty squares
+      #   PiecePlacement.parse("15")
+      #   # => ["", "", "", "", "", "", "", "", "", "", "", "", "", "", ""]
+      #
+      # @example Parse pieces with all PNN modifier types
+      #   PiecePlacement.parse("+P'-R'k")
+      #   # => ["+P'", "-R'", "k"]
+      #   # Where:
+      #   # - "+P'" = enhanced state with intermediate suffix
+      #   # - "-R'" = diminished state with intermediate suffix
+      #   # - "k"   = base piece without modifiers
       def self.parse(piece_placement_str)
         validate_input(piece_placement_str)
         parse_structure(piece_placement_str)
@@ -28,9 +103,24 @@ module Feen
 
       # Validates the input string for basic requirements
       #
+      # Ensures the input is a non-empty string containing only valid FEEN characters.
+      # Valid characters include: letters (a-z, A-Z), digits (0-9), and modifiers (+, -, ').
+      #
       # @param str [String] Input string to validate
       # @raise [ArgumentError] If the string is invalid
       # @return [void]
+      #
+      # @example Valid input
+      #   validate_input("rnbqkbnr/pppppppp/8/8")
+      #   # => (no error)
+      #
+      # @example Invalid input (empty string)
+      #   validate_input("")
+      #   # => ArgumentError: Piece placement string cannot be empty
+      #
+      # @example Invalid input (wrong type)
+      #   validate_input(123)
+      #   # => ArgumentError: Piece placement must be a string, got Integer
       def self.validate_input(str)
         raise ArgumentError, format(ERRORS[:invalid_type], str.class) unless str.is_a?(String)
         raise ArgumentError, ERRORS[:empty_string] if str.empty?
@@ -43,9 +133,25 @@ module Feen
 
       # Parses the structure recursively
       #
+      # Determines the dimensionality of the board by analyzing separator patterns
+      # and recursively parses nested structures. Uses the longest separator sequence
+      # to determine the highest dimension level.
+      #
       # @param str [String] FEEN piece placement string
-      # @return [Array] Parsed structure
-      def self.parse_structure(str)
+      # @return [Array] Parsed structure (1D array for ranks, nested arrays for higher dimensions)
+      #
+      # @example 1D structure (single rank)
+      #   parse_structure("rnbq")
+      #   # => ["r", "n", "b", "q"]
+      #
+      # @example 2D structure (multiple ranks)
+      #   parse_structure("rn/pq")
+      #   # => [["r", "n"], ["p", "q"]]
+      #
+      # @example 3D structure (multiple planes)
+      #   parse_structure("r/p//R/P")
+      #   # => [[["r"], ["p"]], [["R"], ["P"]]]
+      private_class_method def self.parse_structure(str)
         # Handle trailing separators
         raise ArgumentError, ERRORS[:invalid_format] if str.end_with?(DIMENSION_SEPARATOR)
 
@@ -64,10 +170,22 @@ module Feen
 
       # Splits string by separator while preserving shorter separators
       #
+      # Intelligently splits a string by a specific separator pattern while
+      # ensuring that shorter separator patterns within the string are preserved
+      # for recursive parsing of nested dimensions.
+      #
       # @param str [String] String to split
-      # @param separator [String] Separator to split by
-      # @return [Array<String>] Split parts
-      def self.smart_split(str, separator)
+      # @param separator [String] Separator to split by (e.g., "/", "//", "///")
+      # @return [Array<String>] Split parts, with empty parts removed
+      #
+      # @example Split by single separator
+      #   smart_split("a/b/c", "/")
+      #   # => ["a", "b", "c"]
+      #
+      # @example Split by double separator, preserving single separators
+      #   smart_split("a/b//c/d", "//")
+      #   # => ["a/b", "c/d"]
+      private_class_method def self.smart_split(str, separator)
         return [str] unless str.include?(separator)
 
         parts = str.split(separator)
@@ -76,9 +194,29 @@ module Feen
 
       # Parses a rank (sequence of cells)
       #
+      # Processes a 1D sequence of cells, expanding numeric values to empty squares
+      # and extracting pieces with their PNN modifiers. Numbers represent consecutive
+      # empty squares, while letters (with optional modifiers) represent pieces.
+      #
       # @param str [String] FEEN rank string
-      # @return [Array] Array of cells
-      def self.parse_rank(str)
+      # @return [Array<String>] Array of cells (empty strings for empty squares, piece strings for pieces)
+      #
+      # @example Simple pieces
+      #   parse_rank("rnbq")
+      #   # => ["r", "n", "b", "q"]
+      #
+      # @example Mixed pieces and empty squares
+      #   parse_rank("r2k1r")
+      #   # => ["r", "", "", "k", "", "r"]
+      #
+      # @example All empty squares
+      #   parse_rank("8")
+      #   # => ["", "", "", "", "", "", "", ""]
+      #
+      # @example Pieces with modifiers
+      #   parse_rank("+P-R'")
+      #   # => ["+P", "-R'"]
+      private_class_method def self.parse_rank(str)
         return [] if str.empty?
 
         cells = []
@@ -114,10 +252,32 @@ module Feen
 
       # Extracts a piece starting at given position
       #
+      # Parses a piece identifier with optional PNN modifiers starting at the specified
+      # position in the string. Handles prefix modifiers (+, -), the required letter,
+      # and suffix modifiers (').
+      #
       # @param str [String] String to parse
-      # @param start_index [Integer] Starting position
+      # @param start_index [Integer] Starting position in the string
       # @return [Hash] Hash with :piece and :next_index keys
-      def self.extract_piece(str, start_index)
+      #   - :piece [String] The complete piece identifier with modifiers
+      #   - :next_index [Integer] Position after the piece in the string
+      #
+      # @example Extract simple piece
+      #   extract_piece("Kqr", 0)
+      #   # => { piece: "K", next_index: 1 }
+      #
+      # @example Extract piece with prefix modifier
+      #   extract_piece("+Pqr", 0)
+      #   # => { piece: "+P", next_index: 2 }
+      #
+      # @example Extract piece with suffix modifier
+      #   extract_piece("K'qr", 0)
+      #   # => { piece: "K'", next_index: 2 }
+      #
+      # @example Extract piece with both prefix and suffix modifiers
+      #   extract_piece("+P'qr", 0)
+      #   # => { piece: "+P'", next_index: 3 }
+      private_class_method def self.extract_piece(str, start_index)
         piece = ""
         i = start_index
 

data/lib/feen/parser/pieces_in_hand.rb

@@ -9,10 +9,11 @@ module Feen
     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",
-        missing_separator: "Pieces in hand format must contain exactly one '/' separator. Got: %s"
+        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",
+        missing_separator:     "Pieces in hand format must contain exactly one '/' separator. Got: %s",
+        modifiers_not_allowed: 'Pieces in hand cannot contain modifiers: "%s"'
       }.freeze
 
       # Base piece pattern: single letter only (no modifiers allowed in hand)
@@ -22,16 +23,16 @@ module Feen
       VALID_COUNT_PATTERN = /\A(?:[2-9]|[1-9]\d+)\z/
 
       # Pattern for piece with optional count in pieces in hand
-      PIECE_WITH_COUNT_PATTERN = /(?:([2-9]|[1-9]\d+))?([a-zA-Z])/
+      PIECE_WITH_COUNT_PATTERN = /(?:([2-9]|[1-9]\d+))?([-+]?[a-zA-Z]'?)/
 
       # Complete validation pattern for pieces in hand string
       VALID_FORMAT_PATTERN = %r{\A
-        (?:                                               # Uppercase section (optional)
-          (?:(?:[2-9]|[1-9]\d+)?[A-Z])*                  # Zero or more uppercase pieces with optional counts
+        (?:                                     # Uppercase section (optional)
+          (?:(?:[2-9]|[1-9]\d+)?[-+]?[A-Z]'?)*  # Zero or more uppercase pieces with optional counts and modifiers
         )
-        /                                                 # Mandatory separator
-        (?:                                               # Lowercase section (optional)
-          (?:(?:[2-9]|[1-9]\d+)?[a-z])*                  # Zero or more lowercase pieces with optional counts
+        /                                       # Mandatory separator
+        (?:                                     # Lowercase section (optional)
+          (?:(?:[2-9]|[1-9]\d+)?[-+]?[a-z]'?)*  # Zero or more lowercase pieces with optional counts and modifiers
         )
       \z}x
 
@@ -94,7 +95,7 @@ module Feen
         parts_count = str.count("/")
         raise ::ArgumentError, format(Errors[:missing_separator], parts_count) unless parts_count == 1
 
-        # Must match the overall pattern
+        # Must match the overall pattern (including potential modifiers for detection)
         raise ::ArgumentError, format(Errors[:invalid_format], str) unless str.match?(VALID_FORMAT_PATTERN)
 
         # Additional validation: check for any modifiers (forbidden in hand)
@@ -111,9 +112,9 @@ module Feen
         return unless str.match?(/[+\-']/)
 
         # Find the specific invalid piece to provide a better error message
-        invalid_pieces = str.scan(/(?:[2-9]|[1-9]\d+)?[+\-']?[a-zA-Z]'?/).grep(/[+\-']/)
+        invalid_pieces = str.scan(/(?:[2-9]|[1-9]\d+)?[-+]?[a-zA-Z]'?/).grep(/[+\-']/)
 
-        raise ::ArgumentError, "Pieces in hand cannot contain modifiers: '#{invalid_pieces.first}'"
+        raise ::ArgumentError, format(Errors[:modifiers_not_allowed], invalid_pieces.first)
       end
 
       # Parses a specific section (uppercase or lowercase) and returns expanded pieces
@@ -145,12 +146,15 @@ module Feen
           match = section[position..].match(PIECE_WITH_COUNT_PATTERN)
           break unless match
 
-          count_str, piece = match.captures
+          count_str, piece_with_modifiers = match.captures
           count = count_str ? count_str.to_i : 1
 
+          # Extract just the base piece (remove any modifiers)
+          base_piece = extract_base_piece(piece_with_modifiers)
+
           # Validate piece is base form only (single letter)
-          unless piece.match?(BASE_PIECE_PATTERN)
-            raise ::ArgumentError, "Pieces in hand must be base form only: '#{piece}'"
+          unless base_piece.match?(BASE_PIECE_PATTERN)
+            raise ::ArgumentError, "Pieces in hand must be base form only: '#{base_piece}'"
           end
 
           # Validate count format
@@ -159,14 +163,14 @@ module Feen
           end
 
           # Validate that the piece matches the expected case
-          piece_case = piece.match?(/[A-Z]/) ? :uppercase : :lowercase
+          piece_case = base_piece.match?(/[A-Z]/) ? :uppercase : :lowercase
           unless piece_case == case_type
             case_name = case_type == :uppercase ? "uppercase" : "lowercase"
-            raise ::ArgumentError, "Piece '#{piece}' has wrong case for #{case_name} section"
+            raise ::ArgumentError, "Piece '#{base_piece}' has wrong case for #{case_name} section"
           end
 
           # Add to our result with piece type and count
-          result << { piece: piece, count: count }
+          result << { piece: base_piece, count: count }
 
           # Move position forward
           position += match[0].length
@@ -175,6 +179,18 @@ module Feen
         result
       end
 
+      # Extracts the base piece from a piece string that may contain modifiers
+      #
+      # @param piece_str [String] Piece string potentially with modifiers
+      # @return [String] Base piece without modifiers
+      private_class_method def self.extract_base_piece(piece_str)
+        # Remove prefix modifiers (+ or -)
+        without_prefix = piece_str.gsub(/^[-+]/, "")
+
+        # Remove suffix modifiers (')
+        without_prefix.gsub(/'$/, "")
+      end
+
       # Expands the pieces based on their counts into an array.
       #
       # @param pieces_with_counts [Array<Hash>] Array of pieces with their counts

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: feen
 version: !ruby/object:Gem::Version
-  version: 5.0.0.beta8
+  version: 5.0.0.beta9
 platform: ruby
 authors:
 - Cyril Kato
@@ -39,6 +39,8 @@ metadata:
   source_code_uri: https://github.com/sashite/feen.rb
   specification_uri: https://sashite.dev/documents/feen/1.0.0/
   rubygems_mfa_required: 'true'
+  keywords: board, board-games, chess, deserialization, feen, fen, game, makruk, notation,
+    serialization, shogi, xiangqi"
 rdoc_options: []
 require_paths:
 - lib