Defined in header <cparse/Parser.hh>

protected:
bool extractToken( std::string const& token );

Attempts to consume the exact string token from the current cursor position, character by character. On match, returns true with the cursor advanced past the token. On mismatch (or partial match), the cursor is restored to its position at entry and the method returns false.

Uses storeCursor() on entry and restoreCursor() on mismatch — this is the primary form of backtracking in cparse grammars.

Parameters

ParameterDescription
tokenThe literal string to match. Empty tokens are rejected and the method returns false without touching the cursor.

Return value

true if token matched at the current position and the cursor was advanced. false if the cursor was not valid at entry, token was empty, or any character did not match (cursor position unchanged in the mismatch case).

Exceptions

May propagate ios_base::failure if the cursor throws mid-match on an EOF path that the safe helpers do not intercept. In practice, because the match loop uses Cursor::safePeek() to check the next character, EOF during match yields the sentinel '\032' which will not equal any real token character, and the loop exits with matched == false.

Notes

extractToken does not skip whitespace before matching. Grammars that allow whitespace between tokens must call skipWhiteSpaces or skipCommentsBlock explicitly first:

skipCommentsBlock();
if (extractToken("return"))
    parseReturnStatement();
else if (extractToken("if"))
    parseIfStatement();
// ...

Because extractToken handles its own backtracking, the sequence above is safe: an unsuccessful extractToken("return") leaves the cursor exactly where it was and the next extractToken("if") starts from the same position.

Example

bool parseAssignment()
{
    skipCommentsBlock();
    if (!extractToken("let"))
        return false;

    skipCommentsBlock();
    // ... parse identifier ...

    skipCommentsBlock();
    if (!extractCharacter('='))
    {
        recordError(ParseError::Kind::Syntax, "expected '=' after identifier");
        return false;
    }
    // ...
    return true;
}

See also