The Parser interface

After generating a parser it would be useful to use it.

There are a few functions made available. The parser is a type function, that depends on the wanted parser configuration.

The name of the function is per default the name of the grammar used to generate the parser (it can be set to a static name at generation time with the --name option).

Options

importing the parser works as follows:

const Parser = @import("parser.zig").Parser(.{}); // default options

Per default the configuration can be left empty.
The Configuration struct:

pub const ParseOptions = struct {
    /// make use of memoization (defaults to true)
    use_memo: bool = true,

    /// set the limit to the parsing stack
    /// per default it is unlimited
    stack_limit: ?usize = null,

    /// the number of chunks used in the memoization table
    /// (based on https://bford.info/pub/lang/thesis.pdf)
    /// per default calculated depending on the amount of rules
    chunks: ?usize = null,
};

is used to configure the parser at compile time.

Parsing

Parsing is done with the parsing method parse(chars: [:0]const u8) !ParseReturn which takes in a null terminated string (the reason for which null is not allowed to be matched in grammars).

The Result type of the parsing is:

const ParseReturn = union(enum) {
    pass: ResultType,             // the return type of the root rule
    parse_fail: ParsingError,     // if the chars did not match the grammar
    infer_fail: InferError,       // if some action failed
};

const ParsingError = struct {
    last_found: []const u8,       // the last matched string (points to the parsed chars)
    expected: []const u8,         // the exepected nonterminal
};

const InferError = struct {
    err: ?anyerror,               // the error    
    msg: []const u8,              // the error message
};

The parse function can also return errors, either InputTooLarge for inputs exeeding parser_namespace.MaxInputSize or an allocator error from std.mem.Allocator.Error.

Other Functions

To initialize the parser there is an init(allocator: Allocator) !void function.
To deinitialize there is the corresponding deinit() method.

To get Additional information from the parsing there is the stats() method which can be called on the parser to get informations about divers memory consumption of the parser.