Module: Feen::Dumper::PiecesInHand

Defined in:
lib/feen/dumper/pieces_in_hand.rb

Overview

Handles conversion of pieces in hand data to FEEN notation string

Constant Summary collapse

ERRORS =

Error messages for validation

{
  invalid_type: "Piece at index %d must be a String, got %s",
  invalid_pnn:  "Piece at index %d must be valid PNN notation: '%s'"
}.freeze

Class Method Summary collapse

Class Method Details

.dump(*piece_chars) ⇒ String

Converts an array of piece identifiers to a FEEN-formatted pieces in hand string

Examples:

Valid pieces in hand with modifiers

PiecesInHand.dump("+B", "+B", "B", "B", "B", "B", "B", "K", "-P", "-P", "-P", "-P'", "+P'", "+P'", "+P'", "P", "P", "P", "P", "P", "P", "P", "P", "P", "R", "S", "S", "S'", "b", "p")
# => "2+B5BK3-P-P'3+P'9PR2SS'/bp"

Valid pieces in hand without modifiers

PiecesInHand.dump("P", "P", "P", "B", "B", "p", "p", "p", "p", "p")
# => "3P2B/5p"

No pieces in hand

PiecesInHand.dump()
# => "/"

Parameters:

  • piece_chars (Array<String>) —

    Array of piece identifiers following PNN notation. May include modifiers (per FEEN v1.0.0 specification): prefixes (+, -) and suffixes (‘)

Returns:

  • (String) —

    FEEN-formatted pieces in hand string following the canonical sorting:

    • Groups pieces by case: uppercase first, then lowercase, separated by “/”

    • Within each group, sorts by quantity (descending), then base letter (ascending), then prefix (-, +, none), then suffix (none, ‘)

    • Uses count notation for quantities > 1 (e.g., “3P” instead of “PPP”)

Raises:

  • (ArgumentError) —

    If any piece identifier is invalid PNN notation



37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/feen/dumper/pieces_in_hand.rb', line 37

def self.dump(*piece_chars)
  # Validate each piece character according to PNN 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 canonical sorting specification
  uppercase_formatted = format_pieces_group(uppercase_pieces)
  lowercase_formatted = format_pieces_group(lowercase_pieces)

  # Combine with separator
  "#{uppercase_formatted}/#{lowercase_formatted}"
end