Defined in header <cparse/Parser.hh>

protected:
void pushCursor( std::string const&                    sourceName,
                 std::shared_ptr<Cursor::stream_type>  stream );

Saves the current cursor's position, pushes it onto the internal return-point stack, and installs a new Cursor constructed around sourceName and stream. Use this to switch input mid-parse — parsing an embedded snippet, expanding a macro, reading from a preloaded in-memory buffer.

The return stack unwinds automatically when the pushed cursor reaches EOF and the grammar returns from whatever construct triggered the push. There is no manual popCursor().

Parameters

Parameter	Description
sourceName	Diagnostic label for the new stream. Appears in ParseError::filename records for errors emitted while this cursor is active.
stream	Shared pointer to the input stream. Any std::istream derivative — std::istringstream is the common choice for in-memory sources.

Return value

(none)

Exceptions

Does not throw directly. The new Cursor constructor may throw if stream is malformed — the parser's exception mask on the new stream is set to throw on failbit | eofbit | badbit.

Notes

The pushed cursor participates in the same parse() exception-translation lifecycle. When it reaches EOF, the ios_base::failure propagates out of start() (or whichever helper is reading it), and parse()'s Phase 6 pops the return stack and restores the outer cursor.

Do not try to unwind the return stack manually — the automatic unwind in parse() Phase 6 is the only supported path.

Errors recorded while the pushed cursor is active carry its sourceName in ParseError::filename, so callers can distinguish diagnostics from the outer file vs. the embedded snippet.

Example

Parsing a macro-expanded snippet in place:

void expandAndParseMacro(std::string const& body)
{
    auto ss = std::make_shared<std::istringstream>(body);
    pushCursor("<macro-expansion>", ss);
    // continue calling normal grammar helpers; they act on the pushed cursor
    parseMacroBody();
    // when the pushed cursor hits EOF, parse() restores the outer cursor
}

See also

• Cursor::Cursor — the stream-taking constructor used internally.
• Parser::parse — nested parses and the return stack unwind.
• Parser::getCursor — access the currently active cursor (which changes after pushCursor).