parse_engine_line_cpp: Parse a line of UCI chess engine output

In dryguy/rbitr: Arbiter: One who ensures adherence to the rules and laws of chess

Parse a line of UCI chess engine output

Description

Parse a line of UCI chess engine output

Usage

parse_engine_line_cpp(engine_line, tag_names)

Arguments

engine_line	A single-element character vector of the engine line to be parsed.
tag_names	A character vector of tag names to extract from the engine line.

Details

The parse_engine_line_cpp() function is optimized for speed for large data sets. Input validation should therefore be handled by a parent function. The function is written in C++ via the Rcpp package.

The parse_engine_line_cpp() function takes two arguments: a character vector of length one representing a single line of UCI engine output, and a character vector containing the tag names to extract from the engine line. It will return a character vector of tag values corresponding to the input tag names. Anywhere a tag is not present, it will return NA.

The UCI protocol lists a number of tags that may appear in engine output. Most tags have values that are either numeric, or that are a series of chess moves in long algebraic notation (LAN):
    Numeric tags: depth, seldepth, multipv, time, nodes, currmovenumber, hashfull, nps, tbhits, sbhits, cpuload
    Move tags: bestmove, ponder, pv, currmove, refutation
    Special tags: score, string, currline

In the case of move tags, parse_engine_line_cpp() will check for the next move until it reaches the end of the series, and return the moves as a string separated by spaces.

The tags score, string, and currline differ from the rest.

The score tag has 4 different types of value (⁠<x>⁠ indicates numeric):
    cp: A score (centipawns), 'cp ⁠<x>⁠'
    mate: Moves until mate, 'mate ⁠<x>⁠'
    lowerbound: A lower bound for the score (centipawns), '⁠<x>⁠ lowerbound'
    upperbound: An upper bound for the score (centipawns), '⁠<x>⁠ upperbound'

The string tag can have any value, and it runs to the end of the line.

The currline tag has a slightly different format than the other move tags. The moves may be preceded by a number indicating which CPU generated the moves. In the case of only 1 CPU, the number may be omitted.

Some engines may use tags not listed in the UCI protocol. The parse_engine_line_cpp() function may be able to deal with such tags if they conform to the general format of other UCI tags.

Value

A character vector of tag values corresponding to the input tag names.

dryguy/rbitr documentation built on Oct. 15, 2024, 6:18 a.m.