Header lexy/action/trace.hpp

Visualize the parsing process.

Action lexy::trace and lexy::trace_to

lexy/action/trace.hpp
namespace lexy
{
    template <production Production, typename TokenKind = void,
              std::output_iterator<char> OutputIt>
    OutputIt trace_to(OutputIt out, const auto input& input,
                      visualization_options opts = {});

    template <production Production, typename TokenKind = void>
    void trace(std::FILE* file, const auto input& input,
               visualization_options opts = {});
}

An action that traces the events of parsing Production on input and visualizes them.

The first overload writes the events to out; the second one to file. Like lexy::visualize_to, the output is meant to be human-readable only. It is not documented exactly and subject to change.

The events it reports are:

  • Whenever parsing of a production starts or is finished.

  • Whenever parsing of a production starts in a branch condition and is then canceled as the branch couldn’t be taken.

  • Whenever a token is parsed.

  • Whenever parsing needs to backtrack to an earlier position.

  • Whenever an error is encountered.

  • Whenever non-trivial error recovery starts, finishes or fails, e.g. by a lexy::dsl::try_ rule.

  • Whenever a lexy::dsl::debug rule is matched.

For each event, the line and column information in the input is given. Events are structured in a hierarchy like lexy::parse_tree.

Example 1. Trace parsing of a grammar
struct name
{
    static constexpr auto rule = dsl::identifier(dsl::ascii::alpha);
};

struct alphabet
{
    static constexpr auto rule
        // Just something stupid, so we can see a backtrack.
        = dsl::peek(LEXY_LIT("abc")) >> LEXY_LIT("abcdefg");
};

struct number
{
    static constexpr auto rule = dsl::identifier(dsl::ascii::digit);
};

struct object
{
    struct unexpected
    {
        static constexpr auto name = "unexpected";
    };

    static constexpr auto rule
        = dsl::p<alphabet> | dsl::p<name> | dsl::p<number>
         // Issue an error, but recover.
         | dsl::try_(dsl::error<unexpected>);
};

struct production
{
    static constexpr auto whitespace = dsl::ascii::space;

    static constexpr auto rule = [] {
        auto greeting = LEXY_LIT("Hello");
        return greeting + LEXY_DEBUG("finished greeting") //
               + dsl::p<object> + dsl::exclamation_mark;
    }();
};

Rule lexy::dsl::debug

lexy/action/trace.hpp
namespace lexy::dsl
{
    template <auto Str>
    constexpr rule auto debug;
}

#define LEXY_DEBUG(Str) lexy::dsl::debug<Str>

Creates a debug event for lexy::trace.

Parsing

Always succeeds without consuming anything.

Errors

None.

Values

None.

It generates a debug event at the current input position with the associated message Str. This is only meaningful for lexy::trace and is ignored otherwise. See an example there.

The macro LEXY_DEBUG(Str) is equivalent to debug<Str>, except that it also works on older compilers that do not support C++20’s extended NTTPs. Use this instead of debug<Str> if you need to support them.

See also