feen 5.0.0.beta5 → 5.0.0.beta6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28b60c3d60fd3241172fee9e143c53e6dca04082a2efe7f0fa7559b85dc6eac0
-  data.tar.gz: a15999144de7bcd5637b6efca4ed1c4a8ae7d3757d6d583123dfaf44468d6d35
+  metadata.gz: ce89113318c1acf675da8dc7d4af4a9ea135a6485e0e4eb8d522640149f0461a
+  data.tar.gz: e06ae9198a93a896594e1ed9ba0b96a8af1445a20a7f8df8b247a04d84d76e71
 SHA512:
-  metadata.gz: 861669bea6101dba5eefcf6062b9e4e0b37152618e7ffa9c1ba963eb37b2f49cad804f4c1bbee31bd030bf4ddd9602563df7e54cc244384d37e1f45ec748c5ff
-  data.tar.gz: 6f00dcfc09fd378fde0fbe3cd36b078718eab1fa27e208d474637ef89853a7543be4027116d623d0e037c340f0deeae90ce337404db09c953faecba852f56ece
+  metadata.gz: 177f297b196c9a20601eca71865d3ee51389111a72da28d4d1dc08249f3017be07d50636d0a9161759067cf9e8e42dbfdc2dc472f7717130f0e20477634537da
+  data.tar.gz: 5060cd110c9ee95d43f952fbe55c9870e1c98171934f148947a49a6afdbf547007ddd012e24598dd3209e0eab4ea11905f61d52871e9bfa511fdc9bac78af9d6

data/README.md

@@ -14,16 +14,30 @@ FEEN (Forsyth–Edwards Enhanced Notation) is a compact, canonical, and rule-agn
 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)
+- Supporting boards of arbitrary dimensions (2D, 3D, and beyond)
+- Encoding pieces in hand with full PNN (Piece Name Notation) support
 - Facilitating serialization and deserialization of positions
 - Ensuring canonical representation for consistent data handling
 
+## FEEN Format
+
+A FEEN record consists of three space-separated fields:
+
+```
+<PIECE-PLACEMENT> <PIECES-IN-HAND> <GAMES-TURN>
+```
+
+### 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
+3. **Games Turn**: Game identifiers and active player indication
+
 ## Installation
 
 ```ruby
 # In your Gemfile
-gem "feen", ">= 5.0.0.beta5"
+gem "feen", ">= 5.0.0.beta6"
 ```
 
 Or install manually:
@@ -32,14 +46,6 @@ Or install manually:
 gem install feen --pre
 ```
 
-## FEEN Format
-
-A FEEN record consists of three space-separated fields:
-
-```
-<PIECE-PLACEMENT> <PIECES-IN-HAND> <GAMES-TURN>
-```
-
 ## Basic Usage
 
 ### Parsing FEEN Strings
@@ -49,20 +55,20 @@ Convert a FEEN string into a structured Ruby object:
 ```ruby
 require "feen"
 
-feen_string = "r'nbqkbnr'/pppppppp/8/8/8/8/PPPPPPPP/R'NBQKBNR' - CHESS/chess"
+feen_string = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR - CHESS/chess"
 position = Feen.parse(feen_string)
 
 # Result is a hash:
 # {
 #   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"]
@@ -77,7 +83,7 @@ Parse a FEEN string without raising exceptions:
 require "feen"
 
 # Valid FEEN string
-result = Feen.safe_parse("r'nbqkbnr'/pppppppp/8/8/8/8/PPPPPPPP/R'NBQKBNR' - 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
@@ -94,14 +100,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(
@@ -109,7 +115,7 @@ result = Feen.dump(
   games_turn:      %w[CHESS chess],
   pieces_in_hand:  []
 )
-# => "r'nbqkbnr'/pppppppp/8/8/8/8/PPPPPPPP/R'NBQKBNR' - CHESS/chess"
+# => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR - CHESS/chess"
 ```
 
 ### Validation
@@ -120,16 +126,16 @@ Check if a string is valid FEEN notation and in canonical form:
 require "feen"
 
 # Canonical form
-Feen.valid?("lnsgk3l/5g3/p1ppB2pp/9/8B/2P6/P2PPPPPP/3K3R1/5rSNL N5P2gln2s SHOGI/shogi")
+Feen.valid?("lnsgkgsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL - 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
+# 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)
 ```
 
 The `valid?` method performs two levels of validation:
@@ -144,47 +150,100 @@ As FEEN is rule-agnostic, it can represent positions from various board games. H
 ### International Chess
 
 ```ruby
-feen_string = "r'nbqkbnr'/pppppppp/8/8/8/8/PPPPPPPP/R'NBQKBNR' - CHESS/chess"
+feen_string = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR - CHESS/chess"
 ```
 
-In this initial chess position:
-
-- 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
+In this initial chess position, 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 N5P2gln2s SHOGI/shogi"
+feen_string = "lnsgkgsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL - SHOGI/shogi"
 ```
 
-In this shogi position:
+**With pieces in hand and promotions:**
+
+```ruby
+feen_string = "lnsgk3l/5g3/p1ppB2pp/9/8B/2P6/P2PPPPPP/3K3R1/5rSNL 5P2g2sln 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
+- `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)
 - `SHOGI/shogi` indicates it's Sente's (Black's, uppercase) turn to move
-- `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)
 
 ```ruby
-feen_string = "rnbqkbnr/8/pppppppp/8/8/PPPPPPPP/8/RNBQKBNR - MAKRUK/makruk"
+feen_string = "rnbqkbnr/8/pppppppp/8/8/PPPPPPPP/8/RNBKQBNR - MAKRUK/makruk"
 ```
 
-This initial Makruk position is easily represented in FEEN without needing to know the specific rules of the game.
-
 ### Xiangqi (Chinese Chess)
 
 ```ruby
 feen_string = "rheagaehr/9/1c5c1/s1s1s1s1s/9/9/S1S1S1S1S/1C5C1/9/RHEAGAEHR - XIANGQI/xiangqi"
 ```
 
-In this Xiangqi position:
+## Advanced Features
 
-- The representation uses single letters for the different pieces
-- The format naturally adapts to the presence of a "river" (empty space in the middle)
+### Piece Name Notation (PNN) Support
 
-## Advanced Features
+FEEN supports the complete [PNN specification](https://sashite.dev/documents/pnn/1.0.0/) for representing pieces with state modifiers:
+
+#### PNN Modifiers
+
+- **Prefix `+`**: Enhanced state (e.g., promoted pieces in shogi)
+- **Prefix `-`**: Diminished state (e.g., restricted movement)
+- **Suffix `'`**: Intermediate state (e.g., castling rights, en passant eligibility)
+
+#### Examples with PNN
+
+```ruby
+# Shogi position with promoted pieces on board
+piece_placement = [
+  ["", "", "", "", "+P", "", "", "", ""] # Promoted pawn on board
+  # ... other ranks
+]
+
+# Pieces in hand with PNN modifiers
+pieces_in_hand = ["+P", "+P", "+P", "B'", "B'", "-p", "P"]
+
+result = Feen.dump(
+  piece_placement: piece_placement,
+  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"
+```
+
+### Canonical Pieces in Hand Sorting
+
+FEEN enforces canonical ordering of pieces in hand according to the specification:
+
+1. **By quantity (descending)**
+2. **By complete PNN representation (alphabetically ascending)**
+
+```ruby
+# Input pieces in any order
+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)
+```
+
+#### Complex Example from FEEN Specification
+
+```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)
+```
 
 ### Multi-dimensional Boards
 
@@ -193,7 +252,7 @@ FEEN supports arbitrary-dimensional board configurations:
 ```ruby
 require "feen"
 
-# 3D board
+# 3D board (2×2×3 configuration)
 piece_placement = [
   [
     %w[r n b],
@@ -213,26 +272,85 @@ result = Feen.dump(
 # => "rnb/qkp//PR1/1KQ - FOO/bar"
 ```
 
-### Piece Modifiers
+### Hybrid Games
+
+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"
+```
+
+This represents a position where:
+- The board uses chess-style pieces
+- Pieces in hand use shogi-style promotion (`+P`) and intermediate states (`B'`, `-p`)
+- Chess player to move, against shogi player
+
+## 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"
+parsed = Feen.parse(original)
+dumped = Feen.dump(**parsed)
+
+original == dumped # => true (guaranteed canonical form)
+```
+
+## Error Handling
+
+### Validation Errors
+
+```ruby
+# Invalid PNN format
+Feen::Dumper::PiecesInHand.dump("++P")
+# => ArgumentError: Invalid PNN format: '++P'
+
+# Invalid games turn
+Feen.dump(
+  piece_placement: [["P"]],
+  pieces_in_hand:  [],
+  games_turn:      %w[BOTH_UPPERCASE ALSO_UPPERCASE] # Both same case
+)
+# => ArgumentError: One variant must be uppercase and the other lowercase
+```
+
+### Safe Operations
+
+```ruby
+# Use safe_parse for user input
+user_input = gets.chomp
+position = Feen.safe_parse(user_input)
+
+if position
+  puts "Valid FEEN position!"
+else
+  puts "Invalid FEEN format"
+end
+```
 
-FEEN supports prefixes and suffixes for pieces to denote various states or capabilities:
+## Performance Considerations
 
-- **Prefix `+`**: Enhanced state
-  - Example in shogi: `+P` may represent a promoted pawn
+- **Parsing**: Optimized recursive descent parser with O(n) complexity
+- **Validation**: Round-trip validation ensures canonical form
+- **Memory**: Efficient array-based representation for large boards
+- **Sorting**: In-place canonical sorting for pieces in hand
 
-- **Prefix `-`**: Diminished state
-  - Could represent a piece with limited movement or other restrictions
+## Compatibility
 
-- **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_
+- **Ruby version**: >= 3.2.0
+- **FEEN specification**: v1.0.0 compliant
+- **PNN specification**: v1.0.0 compliant
+- **Thread safety**: All operations are thread-safe (no shared mutable state)
 
-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.
+## Related Specifications
 
-## Documentation
+FEEN is part of a family of specifications for abstract strategy games:
 
-- [Official FEEN Specification](https://sashite.dev/documents/feen/1.0.0/)
-- [API Documentation](https://rubydoc.info/github/sashite/feen.rb/main)
+- [FEEN Specification v1.0.0](https://sashite.dev/documents/feen/1.0.0/) - Board position notation
+- [PNN Specification v1.0.0](https://sashite.dev/documents/pnn/1.0.0/) - Piece name notation
+- [GAN Specification v1.0.0](https://sashite.dev/documents/gan/1.0.0/) - Game-qualified piece identifiers
 
 ## License
 

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

@@ -5,7 +5,7 @@ module Feen
     module PiecesInHand
       Errors = {
         invalid_type:   "Piece at index: %<index>s must be a String, got type: %<type>s",
-        invalid_format: "Piece at index: %<index>s has an invalid format: '%<value>s'"
+        invalid_format: "Piece at index: %<index>s has an invalid PNN format: '%<value>s'. Expected format: [prefix]letter[suffix] where prefix is + or -, suffix is ', and letter is a-z or A-Z"
       }.freeze
     end
   end

data/lib/feen/dumper/pieces_in_hand.rb

@@ -9,12 +9,14 @@ 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 single-character piece identifiers
-      # @return [String] 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)
       # @raise [ArgumentError] If any piece identifier is invalid
       # @example
-      #   PiecesInHand.dump("P", "p", "B")
-      #   # => "BPp"
+      #   PiecesInHand.dump("P", "P", "P", "B", "B", "+P")
+      #   # => "3P2B+P"
       #
       #   PiecesInHand.dump
       #   # => "-"
@@ -22,14 +24,25 @@ module Feen
         # 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
+        # Validate each piece character according to the FEEN specification (full PNN support)
         validated_chars = validate_piece_chars(piece_chars)
 
-        # Sort pieces in ASCII lexicographic order and join them
-        validated_chars.sort.join
+        # Count occurrences of each piece type
+        piece_counts = validated_chars.tally
+
+        # Sort according to FEEN specification:
+        # 1. By quantity (descending)
+        # 2. By complete PNN representation (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
+        end
+
+        # Format the pieces sequence with proper count prefixes
+        format_pieces_sequence(sorted_pieces)
       end
 
-      # Validates all piece characters according to FEEN specification
+      # Validates all piece characters according to FEEN specification with full PNN support
       #
       # @param piece_chars [Array<Object>] Array of piece character candidates
       # @return [Array<String>] Array of validated piece characters
@@ -40,7 +53,7 @@ module Feen
         end
       end
 
-      # Validates a single piece character according to FEEN specification
+      # Validates a single piece character according to FEEN specification with full PNN support
       #
       # @param char [Object] Piece character candidate
       # @param index [Integer] Index of the character in the original array
@@ -56,8 +69,12 @@ module Feen
           )
         end
 
-        # Validate format (single alphabetic character)
-        unless char.match?(/\A[a-zA-Z]\z/)
+        # 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/)
           raise ::ArgumentError, format(
             Errors[:invalid_format],
             index: index,
@@ -67,6 +84,20 @@ 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/dumper.rb

@@ -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"]
     #   )
-    #   # => "r'nbqkbnr'/pppppppp/8/8/8/8/PPPPPPPP/R'NBQKBNR' - CHESS/chess"
+    #   # => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR - 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/pieces_in_hand/canonical_sorter.rb

@@ -0,0 +1,70 @@
+# 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/errors.rb

@@ -5,10 +5,12 @@ 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",
-        sorting_error:  "Pieces in hand must be in ASCII lexicographic order"
+        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_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'"
       }.freeze
     end
   end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Feen
+  module Parser
+    module PiecesInHand
+      # Patterns for PNN (Piece Name Notation) validation and parsing
+      module PnnPatterns
+        # Basic PNN piece pattern following the specification:
+        # <piece> ::= <letter> | <prefix> <letter> | <letter> <suffix> | <prefix> <letter> <suffix>
+        # <prefix> ::= "+" | "-"
+        # <suffix> ::= "'"
+        # <letter> ::= [a-zA-Z]
+        PNN_PIECE_PATTERN = /\A[-+]?[a-zA-Z]'?\z/
+
+        # Pattern for valid count prefixes according to FEEN specification:
+        # - Cannot be "0" or "1" (use piece without prefix instead)
+        # - Can be 2-9 or any number with 2+ digits
+        VALID_COUNT_PATTERN = /\A(?:[2-9]|\d{2,})\z/
+
+        # Pattern to extract piece with optional count from pieces in hand string
+        # Matches: optional count followed by complete PNN piece
+        # Groups: (count_str, piece_str)
+        # 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
+        # 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
+          (?:
+            -|                                                    # 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
+          )
+        \z/x
+
+        # Pattern for extracting all pieces globally (used for comprehensive validation)
+        GLOBAL_PIECE_EXTRACTION_PATTERN = /(?:([2-9]|\d{2,}))?([-+]?[a-zA-Z]'?)/
+      end
+    end
+  end
+end

data/lib/feen/parser/pieces_in_hand.rb

@@ -2,20 +2,22 @@
 
 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")
+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.
     module PiecesInHand
       # 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), expanded
-      #   based on their counts and sorted in ASCII lexicographic order.
+      # @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)
       #   Empty array if no pieces are in hand.
       # @raise [ArgumentError] If the input string is invalid
       #
@@ -23,13 +25,17 @@ module Feen
       #   PiecesInHand.parse("-")
       #   # => []
       #
-      # @example Parse multiple pieces in hand
-      #   PiecesInHand.parse("BN2Pb")
-      #   # => ["B", "N", "P", "P", "b"]
+      # @example Parse pieces with modifiers
+      #   PiecesInHand.parse("3+P2B'Pn")
+      #   # => ["+P", "+P", "+P", "B'", "B'", "P", "n"]
       #
-      # @example Parse pieces with counts
-      #   PiecesInHand.parse("N5P2b")
-      #   # => ["N", "P", "P", "P", "P", "P", "b", "b"]
+      # @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"]
       def self.parse(pieces_in_hand_str)
         # Validate input
         validate_input_type(pieces_in_hand_str)
@@ -38,11 +44,13 @@ module Feen
         # Handle the no-pieces case early
         return [] if pieces_in_hand_str == NoPieces
 
-        # Extract pieces with their counts and validate the order
+        # Extract pieces with their counts and validate the format
         pieces_with_counts = extract_pieces_with_counts(pieces_in_hand_str)
-        validate_lexicographic_order(pieces_with_counts)
 
-        # Expand the pieces into an array and maintain lexicographic ordering
+        # Validate canonical ordering according to FEEN specification
+        validate_canonical_order(pieces_with_counts)
+
+        # Expand the pieces into an array maintaining the canonical order
         expand_pieces(pieces_with_counts)
       end
 
@@ -57,17 +65,112 @@ 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.
       #
       # @param str [String] Input string to validate
       # @raise [ArgumentError] If format is invalid
       # @return [void]
       private_class_method def self.validate_format(str)
-        return if str == NoPieces || str.match?(ValidFormatPattern)
+        return if str == NoPieces
+
+        # First, validate overall structure using the updated pattern
+        raise ::ArgumentError, format(Errors[:invalid_format], str) unless str.match?(PnnPatterns::VALID_FORMAT_PATTERN)
+
+        # Additional validation: ensure each piece component is valid PNN
+        # This catches cases like "++P" that might pass the overall pattern
+        validate_individual_pieces(str)
+      end
+
+      # Validates each individual piece in the string for PNN compliance
+      #
+      # @param str [String] FEEN pieces in hand string
+      # @raise [ArgumentError] If any piece is invalid PNN format
+      # @return [void]
+      private_class_method def self.validate_individual_pieces(str)
+        original_string = str
+        position = 0
+
+        while position < str.length
+          match = str[position..].match(PnnPatterns::PIECE_WITH_COUNT_PATTERN)
+
+          unless match
+            # Find the problematic part
+            remaining = str[position..]
+            raise ::ArgumentError, format(Errors[:invalid_format], remaining)
+          end
+
+          count_str, piece = match.captures
 
-        raise ::ArgumentError, format(Errors[:invalid_format], str)
+          # Skip empty matches (shouldn't happen with our pattern, but safety check)
+          if piece.nil? || piece.empty?
+            position += 1
+            next
+          end
+
+          # Validate the piece follows PNN specification
+          unless piece.match?(PnnPatterns::PNN_PIECE_PATTERN)
+            raise ::ArgumentError, format(Errors[:invalid_pnn_piece], piece)
+          end
+
+          # Validate count format (no "0" or "1" prefixes allowed)
+          if count_str && !count_str.match?(PnnPatterns::VALID_COUNT_PATTERN)
+            raise ::ArgumentError, format(Errors[:invalid_count], count_str)
+          end
+
+          position += match[0].length
+        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)
+        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)
+      end
+
+      # Finds the problematic piece in the original string by comparing with reconstruction
+      #
+      # @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
+
+        # 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]
       end
 
       # Extracts pieces with their counts from the FEEN string.
+      # Supports full PNN notation including prefixes and suffixes.
       #
       # @param str [String] FEEN pieces in hand string
       # @return [Array<Hash>] Array of hashes with :piece and :count keys
@@ -76,7 +179,7 @@ module Feen
         position = 0
 
         while position < str.length
-          match = str[position..].match(PieceCountPattern)
+          match = str[position..].match(PnnPatterns::PIECE_WITH_COUNT_PATTERN)
           break unless match
 
           count_str, piece = match.captures
@@ -92,24 +195,24 @@ module Feen
         result
       end
 
-      # Validates that pieces are in lexicographic ASCII order.
+      # 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 lexicographic order
+      # @raise [ArgumentError] If pieces are not in canonical order
       # @return [void]
-      private_class_method def self.validate_lexicographic_order(pieces_with_counts)
-        pieces = pieces_with_counts.map { |item| item[:piece] }
-
-        # Verify the array is sorted lexicographically
-        return if pieces == pieces.sort
+      private_class_method def self.validate_canonical_order(pieces_with_counts)
+        return if pieces_with_counts.size <= 1
 
-        raise ::ArgumentError, Errors[:sorting_error]
+        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
+      # @return [Array<String>] Array of expanded pieces in canonical order
       private_class_method def self.expand_pieces(pieces_with_counts)
         pieces_with_counts.flat_map do |item|
           Array.new(item[:count], item[:piece])

data/lib/feen/parser.rb

@@ -26,18 +26,18 @@ module Feen
     # @raise [ArgumentError] If the FEEN string is invalid
     #
     # @example Parsing a standard chess initial position
-    #   feen = "r'nbqkbnr'/pppppppp/8/8/8/8/PPPPPPPP/R'NBQKBNR' - CHESS/chess"
+    #   feen = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR - 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"]
@@ -76,7 +76,7 @@ module Feen
     # @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"
+    #   feen = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR - CHESS/chess"
     #   result = Feen::Parser.safe_parse(feen)
     #   # => {piece_placement: [...], pieces_in_hand: [...], games_turn: [...]}
     #

data/lib/feen.rb

@@ -23,21 +23,21 @@ module Feen
   # @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"]
   #   )
-  #   # => "r'nbqkbnr'/pppppppp/8/8/8/8/PPPPPPPP/R'NBQKBNR' - CHESS/chess"
+  #   # => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR - CHESS/chess"
   def self.dump(piece_placement:, pieces_in_hand:, games_turn:)
     Dumper.dump(piece_placement:, pieces_in_hand:, games_turn:)
   end
@@ -51,18 +51,18 @@ module Feen
   #   - :games_turn [Array<String>] - A two-element array with [active_variant, inactive_variant]
   # @raise [ArgumentError] If the FEEN string is invalid
   # @example
-  #   feen_string = "r'nbqkbnr'/pppppppp/8/8/8/8/PPPPPPPP/R'NBQKBNR' - CHESS/chess"
+  #   feen_string = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR - 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"]
@@ -80,7 +80,7 @@ module Feen
   # @return [Hash, nil] Hash containing the parsed position data or nil if parsing fails
   # @example
   #   # Valid FEEN string
-  #   Feen.safe_parse("r'nbqkbnr'/pppppppp/8/8/8/8/PPPPPPPP/R'NBQKBNR' - CHESS/chess")
+  #   Feen.safe_parse("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR - CHESS/chess")
   #   # => {piece_placement: [...], pieces_in_hand: [...], games_turn: [...]}
   #
   #   # Invalid FEEN string
@@ -104,7 +104,7 @@ module Feen
   # @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
+  #   Feen.valid?("lnsgk3l/5g3/p1ppB2pp/9/8B/2P6/P2PPPPPP/3K3R1/5rSNL 2g2s5PNln SHOGI/shogi") # => true
   #
   #   # Invalid syntax
   #   Feen.valid?("invalid feen string") # => false

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: feen
 version: !ruby/object:Gem::Version
-  version: 5.0.0.beta5
+  version: 5.0.0.beta6
 platform: ruby
 authors:
 - Cyril Kato
@@ -33,9 +33,11 @@ files:
 - 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:
@@ -61,7 +63,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: FEEN (Forsyth–Edwards Enhanced Notation) support for the Ruby language.
 test_files: []