Context-switch trigger registry

Runtime-registered grammar-mode boundary detection. More...

Macros
#define	MODE_NONE   ((GrammarMode)MODE_SQL)
	Sentinel returned by context_switch_classify_lexeme() when no registered trigger matches the lexeme.

Functions
GrammarMode	context_switch_classify_lexeme (const GrammarContextStack *stack, const char *lexeme)
	Classify a lexeme against the registered triggers.
bool	context_switch_detect_exit (GrammarContextStack *stack, int token_code, const char *lexeme)
	Detect whether the current embedded context should exit.
bool	context_switch_needed (const GrammarContextStack *stack, int token_code, const char *lexeme)
	Fast-path predicate: could the current token trigger a switch?
bool	context_switch_register_trigger (GrammarContextStack *stack, const char *trigger_lexeme, ParserSnapshot *embedded_snap, const char *mode_name)
	Register a runtime trigger that switches into an embedded grammar.

Detailed Description

Runtime-registered grammar-mode boundary detection.

This is the layer above grammar_context_register_mode that handles the boilerplate of building a GrammarModeInfo and assigning a fresh mode id for each runtime-registered embedded grammar.

The earlier (1506723^) version of this module had four hard-coded trigger lexemes (xmlquery, xpath, {:, json) baked into static const strings. Real SQL doesn't say xmlquery(...) and PostgreSQL uses XMLPARSE(DOCUMENT ...), so triggers are now registered at runtime by each host grammar.

Macro Definition Documentation

MODE_NONE

#define MODE_NONE   ((GrammarMode)MODE_SQL)

#include <include/grammar_context.h>

Sentinel returned by context_switch_classify_lexeme() when no registered trigger matches the lexeme.

The sentinel maps to MODE_SQL (== 0); callers should compare against this constant rather than against MODE_SQL directly to keep the "no match" intent explicit at call sites.

Definition at line 360 of file grammar_context.h.

Function Documentation

context_switch_classify_lexeme()

GrammarMode context_switch_classify_lexeme	(	const GrammarContextStack *	stack,
		const char *	lexeme
	)

#include <include/grammar_context.h>

Classify a lexeme against the registered triggers.

Returns the GrammarMode of a matching trigger, or MODE_NONE if no trigger matches. The classification is intentionally a prefix test: a host-grammar lexer that emits multi-character keywords as single lexemes will still be matched against shorter trigger prefixes (for example, json matching against the lexeme json).

Parameters

stack	Context stack with the trigger registry.
lexeme	Lexeme text (may be NULL).

Returns

Mode the lexeme would trigger, or MODE_NONE.

context_switch_detect_exit()

bool context_switch_detect_exit	(	GrammarContextStack *	stack,
		int	token_code,
		const char *	lexeme
	)

#include <include/grammar_context.h>

Detect whether the current embedded context should exit.

The original (1506723^) version of this function looked at the lexeme to spot the EDN :} close marker. The runtime-registered design instead delegates exit detection to either an explicit exit token (registered via GrammarModeInfo.exit_token) or to bracket depth tracking. This function is a thin wrapper for the explicit exit-token case.

Parameters

stack	Context stack with an active embedded context.
token_code	Token code just emitted by the host lexer.
lexeme	Lexeme text (may be NULL; reserved for future lexeme-based exit detection).

Return values

true	Context was popped; previous mode is now active.
false	No exit detected.

context_switch_needed()

bool context_switch_needed	(	const GrammarContextStack *	stack,
		int	token_code,
		const char *	lexeme
	)

#include <include/grammar_context.h>

Fast-path predicate: could the current token trigger a switch?

When no triggers are registered or the lexeme is empty, this returns false in O(1) so the host parser pays a single load + branch on the fast path. When triggers are registered, callers can short-circuit the heavier classify_lexeme / detect_switch path with this check.

Inside an embedded context, this always returns true so callers will still poll for the exit condition via context_switch_detect_exit().

Parameters

stack	Context stack with the trigger registry.
token_code	Token code just emitted by the host lexer.
lexeme	Lexeme text (may be NULL).

Return values

true	A switch or exit may be possible.
false	Definitively no switch needed.

context_switch_register_trigger()

bool context_switch_register_trigger	(	GrammarContextStack *	stack,
		const char *	trigger_lexeme,
		ParserSnapshot *	embedded_snap,
		const char *	mode_name
	)

#include <include/grammar_context.h>

Register a runtime trigger that switches into an embedded grammar.

When the host grammar's lexer sees trigger_lexeme as a prefix of its current lexeme, the parser switches into the embedded grammar identified by embedded_snap. The mode is assigned a fresh GrammarMode id internally; the assignment is returned via the mode field of the GrammarModeInfo registered against stack.

The trigger is bracket-depth-driven: the embedded mode exits when the bracket depth returns to where it was at entry. Callers that need explicit-token exit semantics should use grammar_context_register_mode() directly.

Parameters

stack	Context stack to register with.
trigger_lexeme	Lexeme prefix that triggers the switch (borrowed, must outlive stack).
embedded_snap	Snapshot for the embedded grammar. Stack acquires a reference.
mode_name	Human-readable name (borrowed, must outlive stack); appears in callbacks.

Return values

true	Trigger registered.
false	NULL inputs, registry is full, or duplicate trigger.