Snapshot API

Create, share, and release parser snapshots. More...

Functions
ParserSnapshot *	lime_compile_grammar_text (const char *grammar_text, size_t len, char **error)
	Build a base snapshot from in-memory grammar text.
ParserSnapshot *	lime_snapshot_acquire (ParserSnapshot *snap)
	Acquire a reference to a snapshot.
ParserSnapshot *	lime_snapshot_create (const char *grammar_file, char **error)
	Create a base snapshot by parsing a grammar file.
uint16_t	lime_snapshot_first_token (const ParserSnapshot *snap)
	The first_token offset baked into a snapshot.
void	lime_snapshot_release (ParserSnapshot *snap)
	Release a snapshot reference.
int	lime_snapshot_token_code (const ParserSnapshot *snap, const char *name)
	Map a token name to its external code in a snapshot.

Detailed Description

Create, share, and release parser snapshots.

Function Documentation

lime_compile_grammar_text()

ParserSnapshot * lime_compile_grammar_text	(	const char *	grammar_text,
		size_t	len,
		char **	error
	)

#include <include/parser.h>

Build a base snapshot from in-memory grammar text.

Same pipeline as lime_snapshot_create() but takes the grammar source as a buffer rather than a file path. Internally writes the buffer to a temp file and runs lime + cc on it. Used by lime_snapshot_extend() and by callers that hold the grammar text in memory (e.g. embedded in a config blob).

Parameters

	grammar_text	Pointer to the grammar source bytes.
	len	Byte length (NOT including any NUL).
[out]	error	On failure, malloc'd message; NULL on success.

Returns

New snapshot with refcount 1, or NULL on failure.

lime_snapshot_acquire()

ParserSnapshot * lime_snapshot_acquire

(

ParserSnapshot *

snap

)

#include <include/parser.h>

Acquire a reference to a snapshot.

The caller must eventually call lime_snapshot_release() to avoid leaking memory.

Parameters

snap	Snapshot to acquire. Passing NULL is safe and returns NULL.

Returns

Same pointer as snap, for convenience.

See also

lime_snapshot_release()

lime_snapshot_create()

ParserSnapshot * lime_snapshot_create	(	const char *	grammar_file,
		char **	error
	)

#include <include/parser.h>

Create a base snapshot by parsing a grammar file.

Runs the Lime parser generator on grammar_file and produces a snapshot containing the compiled action tables.

Parameters

	grammar_file	Path to the grammar file.
[out]	error	On failure, set to a malloc'd message the caller must free. Set to NULL on success.

Returns

New snapshot with refcount 1, or NULL on failure.

lime_snapshot_first_token()

uint16_t lime_snapshot_first_token

(

const ParserSnapshot *

snap

)

#include <include/parser.h>

The first_token offset baked into a snapshot.

External token codes are internal_index + first_token; parse_token() subtracts this offset. Returns 0 when the grammar declared no first_token (external codes equal internal indices).

Use this to verify, after composing/recompiling a grammar at runtime, that the offset survived – and, with lime_token_admissible_in_state(snap, 0, external_code), that each base terminal keeps the same external code across the rebuild. Passing NULL returns 0.

lime_snapshot_release()

void lime_snapshot_release

(

ParserSnapshot *

snap

)

#include <include/parser.h>

Release a snapshot reference.

When the last reference is released the snapshot and all memory it owns are freed.

Parameters

snap	Snapshot to release. Passing NULL is safe.

lime_snapshot_token_code()

int lime_snapshot_token_code	(	const ParserSnapshot *	snap,
		const char *	name
	)

#include <include/parser.h>

Map a token name to its external code in a snapshot.

Returns the external token code (the value parse_token() expects and a scanner emits: internal_index + first_token) for the terminal or nonterminal named name, or -1 when the name is unknown or the snapshot carries no name table.

This is the lookup a scanner needs to make an extension keyword resolve to its token in a runtime-composed snapshot: extension token codes are assigned by the recompile, so they cannot be hard-coded. Resolve each keyword once at scanner setup (the lookup is a linear scan over the symbol table, not meant for the per-token hot path).

Parameters

snap	Snapshot to query (may be NULL -> -1).
name	Token name, e.g. "DELETE" (may be NULL -> -1).

Returns

External token code, or -1 if not found.