feen 5.0.0.beta6 → 5.0.0.beta7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce89113318c1acf675da8dc7d4af4a9ea135a6485e0e4eb8d522640149f0461a
-  data.tar.gz: e06ae9198a93a896594e1ed9ba0b96a8af1445a20a7f8df8b247a04d84d76e71
+  metadata.gz: 0f302aa1f4504f94ed909dcb5f6759c52a8895c85e4bd4cc0c0cbff42ef6fdd4
+  data.tar.gz: eb77d9e6e1d1bae1c13cc0b4997e1b509e06b631001fbc8c60027da234f50494
 SHA512:
-  metadata.gz: 177f297b196c9a20601eca71865d3ee51389111a72da28d4d1dc08249f3017be07d50636d0a9161759067cf9e8e42dbfdc2dc472f7717130f0e20477634537da
-  data.tar.gz: 5060cd110c9ee95d43f952fbe55c9870e1c98171934f148947a49a6afdbf547007ddd012e24598dd3209e0eab4ea11905f61d52871e9bfa511fdc9bac78af9d6
+  metadata.gz: 331d90ea031b33aa88292680f98b5c847c467827ad2cd64f39e261c8d052a3cfefdf1f4fe734befc51ffffe7667fbe3b713a08d6952adc86869f3401726f12c5
+  data.tar.gz: 574801b36461caf3e971540430962344442a43027e100d76527df73345374ab624a6a2d7bd80fa9cb3917a85a2e16d4ececbca67325776c134a33d7d400ee5c7

data/README.md

@@ -30,14 +30,14 @@ A FEEN record consists of three space-separated fields:
 ### Field Details
 
 1. **Piece Placement**: Spatial distribution of pieces on the board using [PNN notation](https://sashite.dev/documents/pnn/1.0.0/)
-2. **Pieces in Hand**: Off-board pieces available for placement, sorted canonically
+2. **Pieces in Hand**: Off-board pieces available for placement, formatted as `"UPPERCASE/lowercase"` and sorted canonically within each section
 3. **Games Turn**: Game identifiers and active player indication
 
 ## Installation
 
 ```ruby
 # In your Gemfile
-gem "feen", ">= 5.0.0.beta6"
+gem "feen", ">= 5.0.0.beta7"
 ```
 
 Or install manually:
@@ -55,7 +55,7 @@ Convert a FEEN string into a structured Ruby object:
 ```ruby
 require "feen"
 
-feen_string = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR - CHESS/chess"
+feen_string = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR / CHESS/chess"
 position = Feen.parse(feen_string)
 
 # Result is a hash:
@@ -83,7 +83,7 @@ Parse a FEEN string without raising exceptions:
 require "feen"
 
 # Valid FEEN string
-result = Feen.safe_parse("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR - CHESS/chess")
+result = Feen.safe_parse("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR / CHESS/chess")
 # => {piece_placement: [...], pieces_in_hand: [...], games_turn: [...]}
 
 # Invalid FEEN string
@@ -115,7 +115,7 @@ result = Feen.dump(
   games_turn:      %w[CHESS chess],
   pieces_in_hand:  []
 )
-# => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR - CHESS/chess"
+# => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR / CHESS/chess"
 ```
 
 ### Validation
@@ -126,7 +126,7 @@ Check if a string is valid FEEN notation and in canonical form:
 require "feen"
 
 # Canonical form
-Feen.valid?("lnsgkgsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL - SHOGI/shogi")
+Feen.valid?("lnsgkgsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL / SHOGI/shogi")
 # => true
 
 # Invalid syntax
@@ -134,8 +134,8 @@ Feen.valid?("invalid feen string")
 # => false
 
 # Valid syntax but non-canonical form (pieces in hand not in canonical order)
-Feen.valid?("8/8/8/8/8/8/8/8 P3K CHESS/chess")
-# => false (wrong quantity sorting)
+Feen.valid?("8/8/8/8/8/8/8/8 P3K/ CHESS/chess")
+# => false (wrong quantity sorting in uppercase section)
 ```
 
 The `valid?` method performs two levels of validation:
@@ -150,7 +150,7 @@ As FEEN is rule-agnostic, it can represent positions from various board games. H
 ### International Chess
 
 ```ruby
-feen_string = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR - CHESS/chess"
+feen_string = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR / CHESS/chess"
 ```
 
 In this initial chess position, the third field `CHESS/chess` indicates it's the player with uppercase pieces' turn to move.
@@ -158,36 +158,58 @@ In this initial chess position, the third field `CHESS/chess` indicates it's the
 ### Shogi (Japanese Chess)
 
 ```ruby
-feen_string = "lnsgkgsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL - SHOGI/shogi"
+feen_string = "lnsgkgsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL / SHOGI/shogi"
 ```
 
 **With pieces in hand and promotions:**
 
 ```ruby
-feen_string = "lnsgk3l/5g3/p1ppB2pp/9/8B/2P6/P2PPPPPP/3K3R1/5rSNL 5P2g2sln SHOGI/shogi"
+feen_string = "lnsgk3l/5g3/p1ppB2pp/9/8B/2P6/P2PPPPPP/3K3R1/5rSNL 5P2G2L/2gln2s SHOGI/shogi"
 ```
 
 In this shogi position:
+
 - The format supports promotions with the `+` prefix (e.g., `+P` for a promoted pawn)
-- `5P2g2sln` shows pieces in hand in canonical FEEN order:
-  - **Quantity descending**: 5 Pawns (5P), then 2 Golds (2g)
-  - **Alphabetically**: then Lance (l), Knight (n), Silver (s)
+- Pieces in hand are separated by case: `5P2G2L/2gln2s`
+  - **Uppercase section** (Sente): 5 Pawns, 2 Golds, 2 Lances
+  - **Lowercase section** (Gote): 2 golds, lance, knight, 2 silvers
+- Each section is sorted by quantity (descending) then alphabetically
 - `SHOGI/shogi` indicates it's Sente's (Black's, uppercase) turn to move
 
 ### Makruk (Thai Chess)
 
 ```ruby
-feen_string = "rnbqkbnr/8/pppppppp/8/8/PPPPPPPP/8/RNBKQBNR - MAKRUK/makruk"
+feen_string = "rnbqkbnr/8/pppppppp/8/8/PPPPPPPP/8/RNBKQBNR / MAKRUK/makruk"
 ```
 
 ### Xiangqi (Chinese Chess)
 
 ```ruby
-feen_string = "rheagaehr/9/1c5c1/s1s1s1s1s/9/9/S1S1S1S1S/1C5C1/9/RHEAGAEHR - XIANGQI/xiangqi"
+feen_string = "rheagaehr/9/1c5c1/s1s1s1s1s/9/9/S1S1S1S1S/1C5C1/9/RHEAGAEHR / XIANGQI/xiangqi"
 ```
 
 ## Advanced Features
 
+### Pieces in Hand with Case Separation
+
+FEEN uses case separation for pieces in hand to distinguish between players using the format `"UPPERCASE_PIECES/LOWERCASE_PIECES"`:
+
+```ruby
+require "feen"
+
+# Parse pieces in hand with case separation
+pieces_in_hand = Feen.parse("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR 3P2B/2pn CHESS/chess")[:pieces_in_hand]
+# => ["B", "B", "P", "P", "P", "n", "p", "p"]  # Sorted alphabetically
+
+# Create FEEN with pieces in hand
+result = Feen.dump(
+  piece_placement: [["k"], ["K"]],
+  pieces_in_hand: ["P", "P", "B", "p", "n"],
+  games_turn: ["TEST", "test"]
+)
+# => "k/K 2BP/np TEST/test"
+```
+
 ### Piece Name Notation (PNN) Support
 
 FEEN supports the complete [PNN specification](https://sashite.dev/documents/pnn/1.0.0/) for representing pieces with state modifiers:
@@ -207,7 +229,7 @@ piece_placement = [
   # ... other ranks
 ]
 
-# Pieces in hand with PNN modifiers
+# Pieces in hand with PNN modifiers - case separated
 pieces_in_hand = ["+P", "+P", "+P", "B'", "B'", "-p", "P"]
 
 result = Feen.dump(
@@ -215,34 +237,38 @@ result = Feen.dump(
   pieces_in_hand:  pieces_in_hand,
   games_turn:      %w[SHOGI shogi]
 )
-# => "8/8/8/8/4+P4/8/8/8/8 3+P2B'-pP SHOGI/shogi"
+# => "8/8/8/8/4+P4/8/8/8/8 3+P2B'P/-p SHOGI/shogi"
 ```
 
 ### Canonical Pieces in Hand Sorting
 
-FEEN enforces canonical ordering of pieces in hand according to the specification:
+FEEN enforces canonical ordering of pieces in hand within each case section according to the specification:
 
 1. **By quantity (descending)**
 2. **By complete PNN representation (alphabetically ascending)**
 
+The dumper organizes pieces by case first, then applies canonical sorting within each section:
+
 ```ruby
 # Input pieces in any order
-pieces = ["P", "B", "P", "+P", "B", "P", "+P", "+P"]
+pieces = ["P", "b", "P", "+P", "B", "p", "+P", "+P"]
 
-result = Feen::Dumper::PiecesInHand.dump(*pieces)
-# => "3+P3P2B"
-# Breakdown: 3×+P (most frequent), 3×P, 2×B (alphabetical within same quantity)
+result = Feen.dump(
+  piece_placement: [["k"], ["K"]],
+  pieces_in_hand: pieces,
+  games_turn: %w[GAME game]
+)
+# => "k/K 3+P2PB/bp GAME/game"
+# Breakdown:
+# - Uppercase: 3×+P (most frequent), 2×P, 1×B (alphabetical within same quantity)
+# - Lowercase: 1×b, 1×p (alphabetical)
 ```
 
-#### Complex Example from FEEN Specification
+The parser returns pieces in simple alphabetical order for easy handling:
 
 ```ruby
-# From FEEN spec v1.0.0 example
-pieces = (["P"] * 10) + (["K"] * 5) + (["B"] * 3) + (["p'"] * 2) + ["+P", "-p", "R", "b", "q"]
-
-result = Feen::Dumper::PiecesInHand.dump(*pieces)
-# => "10P5K3B2p'+P-pRbq"
-# Sorted by: quantity desc (10,5,3,2,1...), then alphabetical (+P,-p,R,b,q)
+pieces_in_hand = Feen.parse("k/K 3+P2PB/bp GAME/game")[:pieces_in_hand]
+# => ["+P", "+P", "+P", "B", "P", "P", "b", "p"]  # Alphabetically sorted
 ```
 
 ### Multi-dimensional Boards
@@ -269,7 +295,7 @@ result = Feen.dump(
   games_turn:      %w[FOO bar],
   pieces_in_hand:  []
 )
-# => "rnb/qkp//PR1/1KQ - FOO/bar"
+# => "rnb/qkp//PR1/1KQ / FOO/bar"
 ```
 
 ### Hybrid Games
@@ -278,20 +304,22 @@ FEEN supports hybrid games mixing different piece sets:
 
 ```ruby
 # Chess-Shogi hybrid position
-feen_string = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR 3+P2B'-pP CHESS/shogi"
+feen_string = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR 3+P2B'/p CHESS/shogi"
 ```
 
 This represents a position where:
+
 - The board uses chess-style pieces
-- Pieces in hand use shogi-style promotion (`+P`) and intermediate states (`B'`, `-p`)
+- Pieces in hand use shogi-style promotion (`+P`) and intermediate states (`B'`)
 - Chess player to move, against shogi player
+- Case separation shows which player has which pieces
 
 ## Round-trip Consistency
 
 FEEN.rb guarantees round-trip consistency - parsing and dumping produces identical canonical strings:
 
 ```ruby
-original = "lnsgk3l/5g3/p1ppB2pp/9/8B/2P6/P2PPPPPP/3K3R1/5rSNL 5P2g2sln SHOGI/shogi"
+original = "lnsgk3l/5g3/p1ppB2pp/9/8B/2P6/P2PPPPPP/3K3R1/5rSNL 5P2G2L/2gln2s SHOGI/shogi"
 parsed = Feen.parse(original)
 dumped = Feen.dump(**parsed)
 
@@ -304,8 +332,12 @@ original == dumped # => true (guaranteed canonical form)
 
 ```ruby
 # Invalid PNN format
-Feen::Dumper::PiecesInHand.dump("++P")
-# => ArgumentError: Invalid PNN format: '++P'
+Feen.dump(
+  piece_placement: [["k"]],
+  pieces_in_hand: ["++P"],  # Invalid: double prefix
+  games_turn: %w[GAME game]
+)
+# => ArgumentError: Invalid format at index: 0, value: '++P'
 
 # Invalid games turn
 Feen.dump(
@@ -314,6 +346,10 @@ Feen.dump(
   games_turn:      %w[BOTH_UPPERCASE ALSO_UPPERCASE] # Both same case
 )
 # => ArgumentError: One variant must be uppercase and the other lowercase
+
+# Invalid pieces in hand format (parsing)
+Feen.parse("8/8/8/8/8/8/8/8 NoSeparator CHESS/chess")
+# => ArgumentError: Invalid pieces in hand format: NoSeparator
 ```
 
 ### Safe Operations
@@ -325,6 +361,7 @@ position = Feen.safe_parse(user_input)
 
 if position
   puts "Valid FEEN position!"
+  puts "Pieces in hand: #{position[:pieces_in_hand]}"
 else
   puts "Invalid FEEN format"
 end
@@ -333,6 +370,7 @@ end
 ## Performance Considerations
 
 - **Parsing**: Optimized recursive descent parser with O(n) complexity
+- **Case separation**: Efficient single-pass processing for pieces in hand
 - **Validation**: Round-trip validation ensures canonical form
 - **Memory**: Efficient array-based representation for large boards
 - **Sorting**: In-place canonical sorting for pieces in hand

data/lib/feen/dumper/pieces_in_hand.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require_relative File.join("pieces_in_hand", "no_pieces")
 require_relative File.join("pieces_in_hand", "errors")
 
 module Feen
@@ -9,40 +8,105 @@ module Feen
     module PiecesInHand
       # Converts an array of piece identifiers to a FEEN-formatted pieces in hand string
       #
-      # @param piece_chars [Array<String>] Array of piece identifiers in full PNN format
-      # @return [String] FEEN-formatted pieces in hand string sorted according to FEEN specification:
-      #   1. By quantity (descending)
-      #   2. By complete PNN representation (alphabetically ascending)
+      # @param piece_chars [Array<String>] Array of piece identifiers (e.g., ["P", "p", "B", "B", "p", "+P"])
+      # @return [String] FEEN-formatted pieces in hand string following the format:
+      #   - Groups pieces by case: uppercase first, then lowercase, separated by "/"
+      #   - Within each group, sorts by quantity (descending), then alphabetically (ascending)
+      #   - Uses count notation for quantities > 1 (e.g., "3P" instead of "PPP")
       # @raise [ArgumentError] If any piece identifier is invalid
       # @example
-      #   PiecesInHand.dump("P", "P", "P", "B", "B", "+P")
-      #   # => "3P2B+P"
+      #   PiecesInHand.dump("P", "P", "P", "B", "B", "p", "p", "p", "p", "p")
+      #   # => "3P2B/5p"
+      #
+      #   PiecesInHand.dump("p", "P", "B")
+      #   # => "BP/p"
       #
       #   PiecesInHand.dump
-      #   # => "-"
+      #   # => "/"
       def self.dump(*piece_chars)
-        # If no pieces in hand, return the standardized empty indicator
-        return NoPieces if piece_chars.empty?
-
-        # Validate each piece character according to the FEEN specification (full PNN support)
+        # Validate each piece character according to the FEEN specification
         validated_chars = validate_piece_chars(piece_chars)
 
+        # Group pieces by case
+        uppercase_pieces, lowercase_pieces = group_pieces_by_case(validated_chars)
+
+        # Format each group according to FEEN specification
+        uppercase_formatted = format_pieces_group(uppercase_pieces)
+        lowercase_formatted = format_pieces_group(lowercase_pieces)
+
+        # Combine with separator
+        "#{uppercase_formatted}/#{lowercase_formatted}"
+      end
+
+      # Groups pieces by case (uppercase vs lowercase)
+      #
+      # @param pieces [Array<String>] Array of validated piece identifiers
+      # @return [Array<Array<String>, Array<String>>] Two arrays: [uppercase_pieces, lowercase_pieces]
+      private_class_method def self.group_pieces_by_case(pieces)
+        uppercase_pieces = pieces.select { |piece| piece_is_uppercase?(piece) }
+        lowercase_pieces = pieces.select { |piece| piece_is_lowercase?(piece) }
+
+        [uppercase_pieces, lowercase_pieces]
+      end
+
+      # Determines if a piece belongs to the uppercase group
+      # A piece is considered uppercase if its main letter is uppercase (ignoring prefixes/suffixes)
+      #
+      # @param piece [String] Piece identifier (e.g., "P", "+P", "P'", "+P'")
+      # @return [Boolean] True if the piece's main letter is uppercase
+      private_class_method def self.piece_is_uppercase?(piece)
+        # Extract the main letter (skip prefixes like + or -)
+        main_letter = piece.gsub(/\A[+-]/, "").gsub(/'\z/, "")
+        main_letter.match?(/[A-Z]/)
+      end
+
+      # Determines if a piece belongs to the lowercase group
+      # A piece is considered lowercase if its main letter is lowercase (ignoring prefixes/suffixes)
+      #
+      # @param piece [String] Piece identifier (e.g., "p", "+p", "p'", "+p'")
+      # @return [Boolean] True if the piece's main letter is lowercase
+      private_class_method def self.piece_is_lowercase?(piece)
+        # Extract the main letter (skip prefixes like + or -)
+        main_letter = piece.gsub(/\A[+-]/, "").gsub(/'\z/, "")
+        main_letter.match?(/[a-z]/)
+      end
+
+      # Formats a group of pieces according to FEEN specification
+      #
+      # @param pieces [Array<String>] Array of pieces from the same case group
+      # @return [String] Formatted string for this group (e.g., "3P2B", "5pq")
+      private_class_method def self.format_pieces_group(pieces)
+        return "" if pieces.empty?
+
         # Count occurrences of each piece type
-        piece_counts = validated_chars.tally
+        piece_counts = pieces.each_with_object(Hash.new(0)) do |piece, counts|
+          counts[piece] += 1
+        end
 
-        # Sort according to FEEN specification:
-        # 1. By quantity (descending)
-        # 2. By complete PNN representation (alphabetically ascending)
+        # Sort by count (descending) then alphabetically (ascending)
         sorted_pieces = piece_counts.sort do |a, b|
-          count_comparison = b[1] <=> a[1] # quantity descending
-          count_comparison.zero? ? a[0] <=> b[0] : count_comparison # then alphabetical
+          piece_a, count_a = a
+          piece_b, count_b = b
+
+          # Primary sort: by count (descending)
+          count_comparison = count_b <=> count_a
+          next count_comparison unless count_comparison.zero?
+
+          # Secondary sort: by piece name (ascending)
+          piece_a <=> piece_b
         end
 
-        # Format the pieces sequence with proper count prefixes
-        format_pieces_sequence(sorted_pieces)
+        # Format each piece with its count
+        sorted_pieces.map do |piece, count|
+          if count == 1
+            piece
+          else
+            "#{count}#{piece}"
+          end
+        end.join
       end
 
-      # Validates all piece characters according to FEEN specification with full PNN support
+      # Validates all piece characters according to FEEN specification
       #
       # @param piece_chars [Array<Object>] Array of piece character candidates
       # @return [Array<String>] Array of validated piece characters
@@ -53,7 +117,11 @@ module Feen
         end
       end
 
-      # Validates a single piece character according to FEEN specification with full PNN support
+      # Validates a single piece character according to FEEN specification
+      # Supports full PNN notation: [prefix]letter[suffix] where:
+      # - prefix can be "+" or "-"
+      # - letter must be a-z or A-Z
+      # - suffix can be "'"
       #
       # @param char [Object] Piece character candidate
       # @param index [Integer] Index of the character in the original array
@@ -69,12 +137,9 @@ module Feen
           )
         end
 
-        # Validate format (full PNN notation: [prefix]letter[suffix])
-        # <piece> ::= <letter> | <prefix> <letter> | <letter> <suffix> | <prefix> <letter> <suffix>
-        # <prefix> ::= "+" | "-"
-        # <suffix> ::= "'"
-        # <letter> ::= [a-zA-Z]
-        unless char.match?(/\A[-+]?[a-zA-Z]'?\z/)
+        # Validate format using PNN pattern: [prefix]letter[suffix]
+        # where prefix is +/-, letter is a-zA-Z, suffix is '
+        unless char.match?(/\A[+-]?[a-zA-Z]'?\z/)
           raise ::ArgumentError, format(
             Errors[:invalid_format],
             index: index,
@@ -84,20 +149,6 @@ module Feen
 
         char
       end
-
-      # Formats the pieces sequence with proper count prefixes according to FEEN specification
-      #
-      # @param sorted_pieces [Array<Array>] Array of [piece, count] pairs sorted according to FEEN rules
-      # @return [String] Formatted pieces sequence
-      private_class_method def self.format_pieces_sequence(sorted_pieces)
-        sorted_pieces.map do |piece, count|
-          if count == 1
-            piece
-          else
-            "#{count}#{piece}"
-          end
-        end.join
-      end
     end
   end
 end

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

@@ -10,7 +10,10 @@ module Feen
         invalid_format:            "Invalid pieces in hand format: %s",
         invalid_pnn_piece:         "Invalid PNN piece format: '%s'. Expected format: [prefix]letter[suffix] where prefix is + or -, suffix is ', and letter is a-z or A-Z",
         invalid_count:             "Invalid count format: '%s'. Count cannot be '0' or '1', use the piece without count instead",
-        canonical_order_violation: "Pieces in hand must be in canonical order (by quantity descending, then alphabetically). Got: '%<actual>s', expected: '%<expected>s'"
+        canonical_order_violation: "Pieces in hand must be in canonical order (by quantity descending, then alphabetically). Got: '%<actual>s', expected: '%<expected>s'",
+        missing_separator:         "Pieces in hand format must contain exactly one '/' separator. Got: %s",
+        wrong_case_in_section:     "Piece '%<piece>s' has wrong case for %<section>s section",
+        invalid_section_format:    "Invalid format in %<section>s section: %<content>s"
       }.freeze
     end
   end

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

@@ -23,24 +23,66 @@ module Feen
         # Note: We need to handle the full PNN piece including modifiers
         PIECE_WITH_COUNT_PATTERN = /(?:([2-9]|\d{2,}))?([-+]?[a-zA-Z]'?)/
 
-        # Complete validation pattern for pieces in hand string
+        # Pattern for uppercase pieces only (used for uppercase section validation)
+        UPPERCASE_PIECE_PATTERN = /[-+]?[A-Z]'?/
+
+        # Pattern for lowercase pieces only (used for lowercase section validation)
+        LOWERCASE_PIECE_PATTERN = /[-+]?[a-z]'?/
+
+        # Pattern for uppercase section: sequence of uppercase pieces with optional counts
+        # Format: [count]piece[count]piece... where pieces are uppercase
+        UPPERCASE_SECTION_PATTERN = /\A
+          (?:
+            (?:[2-9]|\d{2,})?                                 # Optional count (2-9 or 10+)
+            [-+]?                                             # Optional single prefix (+ or -)
+            [A-Z]                                             # Required uppercase letter
+            '?                                                # Optional single suffix (')
+          )+                                                  # One or more uppercase pieces
+        \z/x
+
+        # Pattern for lowercase section: sequence of lowercase pieces with optional counts
+        # Format: [count]piece[count]piece... where pieces are lowercase
+        LOWERCASE_SECTION_PATTERN = /\A
+          (?:
+            (?:[2-9]|\d{2,})?                                 # Optional count (2-9 or 10+)
+            [-+]?                                             # Optional single prefix (+ or -)
+            [a-z]                                             # Required lowercase letter
+            '?                                                # Optional single suffix (')
+          )+                                                  # One or more lowercase pieces
+        \z/x
+
+        # Complete validation pattern for pieces in hand string with case separation
         # Based on the FEEN BNF specification with PNN support
-        # This pattern allows any sequence of pieces (uppercase/lowercase mixed) in canonical order
-        # It should reject invalid formats like "++P"
-        VALID_FORMAT_PATTERN = /\A
+        # Format: "UPPERCASE_PIECES/LOWERCASE_PIECES"
+        # Either section can be empty, but the "/" separator is mandatory
+        VALID_FORMAT_PATTERN = %r{\A
           (?:
-            -|                                                    # No pieces in hand
-            (?:
-              (?:[2-9]|\d{2,})?                                   # Optional count (2-9 or 10+)
-              [-+]?                                               # Optional single prefix (+ or -)
-              [a-zA-Z]                                            # Required letter
-              '?                                                  # Optional single suffix (')
-            )+                                                    # One or more pieces
+            (?:                                               # Uppercase section (optional)
+              (?:[2-9]|\d{2,})?                               # Optional count (2-9 or 10+)
+              [-+]?                                           # Optional single prefix (+ or -)
+              [A-Z]                                           # Required uppercase letter
+              '?                                              # Optional single suffix (')
+            )*                                                # Zero or more uppercase pieces
           )
-        \z/x
+          /                                                  # Mandatory separator
+          (?:
+            (?:                                               # Lowercase section (optional)
+              (?:[2-9]|\d{2,})?                               # Optional count (2-9 or 10+)
+              [-+]?                                           # Optional single prefix (+ or -)
+              [a-z]                                           # Required lowercase letter
+              '?                                              # Optional single suffix (')
+            )*                                                # Zero or more lowercase pieces
+          )
+        \z}x
 
         # Pattern for extracting all pieces globally (used for comprehensive validation)
         GLOBAL_PIECE_EXTRACTION_PATTERN = /(?:([2-9]|\d{2,}))?([-+]?[a-zA-Z]'?)/
+
+        # Pattern specifically for uppercase pieces with counts (for section parsing)
+        UPPERCASE_PIECE_WITH_COUNT_PATTERN = /(?:([2-9]|\d{2,}))?([-+]?[A-Z]'?)/
+
+        # Pattern specifically for lowercase pieces with counts (for section parsing)
+        LOWERCASE_PIECE_WITH_COUNT_PATTERN = /(?:([2-9]|\d{2,}))?([-+]?[a-z]'?)/
       end
     end
   end

data/lib/feen/parser/pieces_in_hand.rb

@@ -1,57 +1,54 @@
 # 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", "pnn_patterns")
-require_relative File.join("pieces_in_hand", "canonical_sorter")
 
 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.
     # This implementation supports full PNN notation including prefixes and suffixes.
+    # Format: "UPPERCASE_PIECES/LOWERCASE_PIECES"
     module PiecesInHand
       # Parses the pieces in hand section of a FEEN string.
       #
-      # @param pieces_in_hand_str [String] FEEN pieces in hand string
+      # @param pieces_in_hand_str [String] FEEN pieces in hand string in format "UPPERCASE/lowercase"
       # @return [Array<String>] Array of piece identifiers in full PNN format,
-      #   expanded based on their counts and sorted according to FEEN specification:
-      #   1. By quantity (descending)
-      #   2. By complete PNN representation (alphabetically ascending)
+      #   expanded based on their counts and sorted alphabetically.
       #   Empty array if no pieces are in hand.
       # @raise [ArgumentError] If the input string is invalid
       #
       # @example Parse no pieces in hand
-      #   PiecesInHand.parse("-")
+      #   PiecesInHand.parse("/")
       #   # => []
       #
-      # @example Parse pieces with modifiers
-      #   PiecesInHand.parse("3+P2B'Pn")
-      #   # => ["+P", "+P", "+P", "B'", "B'", "P", "n"]
+      # @example Parse pieces with case separation
+      #   PiecesInHand.parse("3P2B/p")
+      #   # => ["B", "B", "P", "P", "P", "p"]
       #
       # @example Parse complex pieces with counts and modifiers
-      #   PiecesInHand.parse("10P5K3B2p'+P-pBRbq")
-      #   # => ["P", "P", "P", "P", "P", "P", "P", "P", "P", "P",
-      #   #     "K", "K", "K", "K", "K",
-      #   #     "B", "B", "B",
-      #   #     "p'", "p'",
-      #   #     "+P", "-p", "B", "R", "b", "q"]
+      #   PiecesInHand.parse("10P5K3B/2p'+p-pbq")
+      #   # => ["+p", "-p", "B", "B", "B", "K", "K", "K", "K", "K",
+      #   #     "P", "P", "P", "P", "P", "P", "P", "P", "P", "P",
+      #   #     "b", "p'", "p'", "q"]
       def self.parse(pieces_in_hand_str)
         # Validate input
         validate_input_type(pieces_in_hand_str)
         validate_format(pieces_in_hand_str)
 
         # Handle the no-pieces case early
-        return [] if pieces_in_hand_str == NoPieces
+        return [] if pieces_in_hand_str == "/"
 
-        # Extract pieces with their counts and validate the format
-        pieces_with_counts = extract_pieces_with_counts(pieces_in_hand_str)
+        # Split by the separator to get uppercase and lowercase sections
+        uppercase_section, lowercase_section = pieces_in_hand_str.split("/", 2)
 
-        # Validate canonical ordering according to FEEN specification
-        validate_canonical_order(pieces_with_counts)
+        # Parse each section separately
+        uppercase_pieces = parse_pieces_section(uppercase_section || "", :uppercase)
+        lowercase_pieces = parse_pieces_section(lowercase_section || "", :lowercase)
 
-        # Expand the pieces into an array maintaining the canonical order
-        expand_pieces(pieces_with_counts)
+        # Combine all pieces and sort them alphabetically
+        all_pieces = uppercase_pieces + lowercase_pieces
+        all_pieces.sort
       end
 
       # Validates that the input is a non-empty string.
@@ -65,37 +62,63 @@ module Feen
       end
 
       # Validates that the input string matches the expected format according to FEEN specification.
-      # This includes validation of individual PNN pieces and overall structure.
+      # Format must be: "UPPERCASE_PIECES/LOWERCASE_PIECES"
       #
       # @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
+        # Must contain exactly one "/" separator
+        parts_count = str.count("/")
+        raise ::ArgumentError, format(Errors[:invalid_format], str) unless parts_count == 1
+
+        uppercase_section, lowercase_section = str.split("/", 2)
 
-        # First, validate overall structure using the updated pattern
-        raise ::ArgumentError, format(Errors[:invalid_format], str) unless str.match?(PnnPatterns::VALID_FORMAT_PATTERN)
+        # Each section can be empty, but if not empty, must follow PNN patterns
+        validate_section_format(uppercase_section, :uppercase) unless uppercase_section.empty?
+        validate_section_format(lowercase_section, :lowercase) unless lowercase_section.empty?
+      end
 
-        # Additional validation: ensure each piece component is valid PNN
-        # This catches cases like "++P" that might pass the overall pattern
-        validate_individual_pieces(str)
+      # Validates the format of a specific section (uppercase or lowercase)
+      #
+      # @param section [String] The section to validate
+      # @param case_type [Symbol] Either :uppercase or :lowercase
+      # @raise [ArgumentError] If the section format is invalid
+      # @return [void]
+      private_class_method def self.validate_section_format(section, case_type)
+        return if section.empty?
+
+        # Build the appropriate pattern based on case type
+        case_pattern = case case_type
+                       when :uppercase
+                         PnnPatterns::UPPERCASE_SECTION_PATTERN
+                       when :lowercase
+                         PnnPatterns::LOWERCASE_SECTION_PATTERN
+                       else
+                         raise ArgumentError, "Invalid case type: #{case_type}"
+                       end
+
+        # Validate overall section pattern
+        raise ::ArgumentError, format(Errors[:invalid_format], section) unless section.match?(case_pattern)
+
+        # Validate individual pieces in the section
+        validate_individual_pieces_in_section(section, case_type)
       end
 
-      # Validates each individual piece in the string for PNN compliance
+      # Validates each individual piece in a section for PNN compliance
       #
-      # @param str [String] FEEN pieces in hand string
+      # @param section [String] FEEN pieces section string
+      # @param case_type [Symbol] Either :uppercase or :lowercase
       # @raise [ArgumentError] If any piece is invalid PNN format
       # @return [void]
-      private_class_method def self.validate_individual_pieces(str)
-        original_string = str
+      private_class_method def self.validate_individual_pieces_in_section(section, case_type)
         position = 0
 
-        while position < str.length
-          match = str[position..].match(PnnPatterns::PIECE_WITH_COUNT_PATTERN)
+        while position < section.length
+          match = section[position..].match(PnnPatterns::PIECE_WITH_COUNT_PATTERN)
 
           unless match
-            # Find the problematic part
-            remaining = str[position..]
+            remaining = section[position..]
             raise ::ArgumentError, format(Errors[:invalid_format], remaining)
           end
 
@@ -117,69 +140,52 @@ module Feen
             raise ::ArgumentError, format(Errors[:invalid_count], count_str)
           end
 
-          position += match[0].length
-        end
+          # Validate that the piece matches the expected case
+          piece_case = piece_is_uppercase?(piece) ? :uppercase : :lowercase
+          unless piece_case == case_type
+            case_name = case_type == :uppercase ? "uppercase" : "lowercase"
+            raise ::ArgumentError, "#{case_name.capitalize} section contains #{piece_case} piece: '#{piece}'"
+          end
 
-        # Final check: verify that we can reconstruct the string correctly
-        # by re-extracting all pieces and comparing with original
-        reconstructed_pieces = extract_pieces_with_counts(original_string)
-        reconstructed = reconstructed_pieces.map do |item|
-          count = item[:count]
-          piece = item[:piece]
-          count == 1 ? piece : "#{count}#{piece}"
-        end.join
-
-        # If reconstruction doesn't match original, there's an invalid format
-        return if reconstructed == original_string
-        # Find the first discrepancy to provide better error message
-        # This will catch cases like "++P" where we extract "+P" but original has extra "+"
-        unless original_string.length > reconstructed.length
-          raise ::ArgumentError, format(Errors[:invalid_format], original_string)
+          position += match[0].length
         end
+      end
 
-        # There are extra characters - find what's invalid
-        original_string.sub(reconstructed, "")
-        # Try to identify the problematic piece
-        problematic_part = find_problematic_piece(original_string, reconstructed)
-        raise ::ArgumentError, format(Errors[:invalid_pnn_piece], problematic_part)
+      # Determines if a piece belongs to the uppercase group
+      #
+      # @param piece [String] Piece identifier (e.g., "P", "+P", "P'", "+P'")
+      # @return [Boolean] True if the piece's main letter is uppercase
+      private_class_method def self.piece_is_uppercase?(piece)
+        # Extract the main letter (skip prefixes like + or -)
+        main_letter = piece.gsub(/\A[+-]/, "").gsub(/'\z/, "")
+        main_letter.match?(/[A-Z]/)
       end
 
-      # Finds the problematic piece in the original string by comparing with reconstruction
+      # Parses a specific section (uppercase or lowercase) and returns expanded pieces
       #
-      # @param original [String] Original input string
-      # @param reconstructed [String] Reconstructed string from extracted pieces
-      # @return [String] The problematic piece or sequence
-      private_class_method def self.find_problematic_piece(original, reconstructed)
-        # Simple heuristic: find the first part that doesn't match
-        min_length = [original.length, reconstructed.length].min
-
-        # Find first difference
-        diff_pos = 0
-        diff_pos += 1 while diff_pos < min_length && original[diff_pos] == reconstructed[diff_pos]
-
-        # If difference is at start, likely extra prefix
-        # Look for a sequence that starts with invalid pattern like "++"
-        if (diff_pos == 0) && original.match?(/\A\+\+/)
-          return "++P" # Common case
-        end
+      # @param section [String] The section string to parse
+      # @param case_type [Symbol] Either :uppercase or :lowercase (for validation)
+      # @return [Array<String>] Array of expanded pieces from this section
+      private_class_method def self.parse_pieces_section(section, _case_type)
+        return [] if section.empty?
+
+        # Extract pieces with their counts
+        pieces_with_counts = extract_pieces_with_counts_from_section(section)
 
-        # Extract a reasonable chunk around the problematic area
-        start_pos = [0, diff_pos - 2].max
-        end_pos = [original.length, diff_pos + 4].min
-        original[start_pos...end_pos]
+        # Expand the pieces into an array (no canonical order validation needed)
+        expand_pieces(pieces_with_counts)
       end
 
-      # Extracts pieces with their counts from the FEEN string.
-      # Supports full PNN notation including prefixes and suffixes.
+      # Extracts pieces with their counts from a section string.
       #
-      # @param str [String] FEEN pieces in hand string
+      # @param section [String] FEEN pieces section string
       # @return [Array<Hash>] Array of hashes with :piece and :count keys
-      private_class_method def self.extract_pieces_with_counts(str)
+      private_class_method def self.extract_pieces_with_counts_from_section(section)
         result = []
         position = 0
 
-        while position < str.length
-          match = str[position..].match(PnnPatterns::PIECE_WITH_COUNT_PATTERN)
+        while position < section.length
+          match = section[position..].match(PnnPatterns::PIECE_WITH_COUNT_PATTERN)
           break unless match
 
           count_str, piece = match.captures
@@ -195,24 +201,10 @@ module Feen
         result
       end
 
-      # Validates that pieces are in canonical order according to FEEN specification:
-      # 1. By quantity (descending)
-      # 2. By complete PNN representation (alphabetically ascending)
-      #
-      # @param pieces_with_counts [Array<Hash>] Array of pieces with their counts
-      # @raise [ArgumentError] If pieces are not in canonical order
-      # @return [void]
-      private_class_method def self.validate_canonical_order(pieces_with_counts)
-        return if pieces_with_counts.size <= 1
-
-        CanonicalSorter.validate_order(pieces_with_counts)
-      end
-
       # Expands the pieces based on their counts into an array.
-      # Maintains the canonical ordering from the input.
       #
       # @param pieces_with_counts [Array<Hash>] Array of pieces with their counts
-      # @return [Array<String>] Array of expanded pieces in canonical order
+      # @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])

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: feen
 version: !ruby/object:Gem::Version
-  version: 5.0.0.beta6
+  version: 5.0.0.beta7
 platform: ruby
 authors:
 - Cyril Kato
@@ -26,19 +26,14 @@ files:
 - 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/parser/pieces_in_hand/canonical_sorter.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/pnn_patterns.rb
-- lib/feen/parser/pieces_in_hand/valid_format_pattern.rb
 homepage: https://github.com/sashite/feen.rb
 licenses:
 - MIT

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

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

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

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-module Feen
-  module Parser
-    module PiecesInHand
-      # Handles canonical ordering validation for pieces in hand according to FEEN specification
-      module CanonicalSorter
-        # Validates that pieces are in canonical order according to FEEN specification:
-        # 1. By quantity (descending)
-        # 2. By complete PNN representation (alphabetically ascending)
-        #
-        # @param pieces_with_counts [Array<Hash>] Array of pieces with their counts
-        # @raise [ArgumentError] If pieces are not in canonical order
-        # @return [void]
-        def self.validate_order(pieces_with_counts)
-          return if pieces_with_counts.size <= 1
-
-          # Create the expected canonical order
-          canonical_order = sort_canonically(pieces_with_counts)
-
-          # Compare with actual order
-          pieces_with_counts.each_with_index do |piece_data, index|
-            canonical_piece = canonical_order[index]
-
-            next if piece_data[:piece] == canonical_piece[:piece] &&
-                    piece_data[:count] == canonical_piece[:count]
-
-            raise ::ArgumentError, format(
-              Errors[:canonical_order_violation],
-              actual:   format_pieces_sequence(pieces_with_counts),
-              expected: format_pieces_sequence(canonical_order)
-            )
-          end
-        end
-
-        # Sorts pieces according to canonical FEEN order
-        #
-        # @param pieces_with_counts [Array<Hash>] Array of pieces with their counts
-        # @return [Array<Hash>] Canonically sorted array
-        def self.sort_canonically(pieces_with_counts)
-          pieces_with_counts.sort do |a, b|
-            # Primary sort: by quantity (descending)
-            count_comparison = b[:count] <=> a[:count]
-            next count_comparison unless count_comparison.zero?
-
-            # Secondary sort: by complete PNN representation (alphabetically ascending)
-            a[:piece] <=> b[:piece]
-          end
-        end
-
-        # Formats a pieces sequence for error messages
-        #
-        # @param pieces_with_counts [Array<Hash>] Array of pieces with their counts
-        # @return [String] Formatted string representation
-        private_class_method def self.format_pieces_sequence(pieces_with_counts)
-          pieces_with_counts.map do |item|
-            count = item[:count]
-            piece = item[:piece]
-
-            if count == 1
-              piece
-            else
-              "#{count}#{piece}"
-            end
-          end.join
-        end
-      end
-    end
-  end
-end

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

@@ -1,10 +0,0 @@
-# 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

@@ -1,13 +0,0 @@
-# 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

@@ -1,29 +0,0 @@
-# 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