Module: Feen::Parser

Defined in:
lib/feen/parser.rb,
lib/feen/parser/style_turn.rb,
lib/feen/parser/pieces_in_hand.rb,
lib/feen/parser/piece_placement.rb

Overview

Module responsible for parsing FEEN notation strings into internal data structures. FEEN (Forsyth–Edwards Enhanced Notation) is a compact, canonical, and rule-agnostic textual format for representing static board positions in two-player piece-placement games.

Defined Under Namespace

Modules: PiecePlacement, PiecesInHand, StyleTurn

Constant Summary collapse

FEEN_PATTERN =

Regular expression pattern for matching a valid FEEN string structure Captures exactly three non-space components separated by single spaces

/\A([^\s]+)\s([^\s]+)\s([^\s]+)\z/
INVALID_FORMAT_ERROR =

Error message for invalid FEEN format

"Invalid FEEN format: expected exactly 3 fields separated by single spaces"

Class Method Summary collapse

Class Method Details

.parse(feen_string) ⇒ Hash

Parses a complete FEEN string into a structured representation

Examples:

Parsing a standard chess initial position

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"],
#        ["p", "p", "p", "p", "p", "p", "p", "p"],
#        ["", "", "", "", "", "", "", ""],
#        ["", "", "", "", "", "", "", ""],
#        ["", "", "", "", "", "", "", ""],
#        ["", "", "", "", "", "", "", ""],
#        ["P", "P", "P", "P", "P", "P", "P", "P"],
#        ["R", "N", "B", "Q", "K", "B", "N", "R"]
#      ],
#      pieces_in_hand: [],
#      style_turn: ["CHESS", "chess"]
#    }

Parameters:

  • feen_string (String) —

    Complete FEEN notation string

Returns:

  • (Hash) —

    Hash containing the parsed position data with the following keys:

    • :piece_placement [Array] - Hierarchical array structure representing the board

    • :pieces_in_hand [Array<String>] - Pieces available for dropping onto the board (may include modifiers)

    • :style_turn [Array<String>] - A two-element array with [active_style, inactive_style]

Raises:

  • (ArgumentError) —

    If the FEEN string is invalid



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/feen/parser.rb', line 45

def self.parse(feen_string)
  feen_string = String(feen_string)

  # Match the FEEN string against the expected pattern
  match = FEEN_PATTERN.match(feen_string)

  # Raise an error if the format doesn't match the expected pattern
  raise ::ArgumentError, INVALID_FORMAT_ERROR unless match

  # Capture the three distinct parts
  piece_placement_string, pieces_in_hand_string, style_turn_string = match.captures

  # Parse each field using the appropriate submodule
  piece_placement = PiecePlacement.parse(piece_placement_string)
  pieces_in_hand = PiecesInHand.parse(pieces_in_hand_string)
  style_turn = StyleTurn.parse(style_turn_string)

  # Create a structured representation of the position
  {
    piece_placement:,
    pieces_in_hand:,
    style_turn:
  }
end

.safe_parse(feen_string) ⇒ Hash?

Safely parses a complete FEEN string into a structured representation without raising exceptions

This method works like ‘parse` but returns nil instead of raising an exception if the FEEN string is invalid.

Examples:

Parsing a valid FEEN string

feen = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR / CHESS/chess"
result = Feen::Parser.safe_parse(feen)
# => {piece_placement: [...], pieces_in_hand: [...], style_turn: [...]}

Parsing an invalid FEEN string

feen = "invalid feen string"
result = Feen::Parser.safe_parse(feen)
# => nil

Parameters:

  • feen_string (String) —

    Complete FEEN notation string

Returns:

  • (Hash, nil) —

    Hash containing the parsed position data or nil if parsing fails



87
88
89
90
91
 
# File 'lib/feen/parser.rb', line 87

def self.safe_parse(feen_string)
  parse(feen_string)
rescue ::ArgumentError
  nil
end