parse_context.h

/*
** Parse context - manages parser state for a single parse session
**
** The parse context pins a snapshot for the duration of parsing,
** ensuring grammar stability even if extensions are modified.
*/
#ifndef PARSE_CONTEXT_H
#define PARSE_CONTEXT_H
 
#include "snapshot.h"
#include <stdbool.h>
 
/* Forward declaration (full definition in parser.h) */
typedef struct ParseContext ParseContext;
 
struct ParseContext {
    ParserSnapshot *snapshot;  
    void *engine;              
    struct GrammarContextStack *context_stack;
 
    bool borrowed_snapshot;
 
    LimeHostReduceFn host_reduce;
    void *host_reduce_user;
 
    void *result_value;
};
 
/*
** Create a parse context with the given snapshot.
** Acquires a reference to the snapshot.
*/
ParseContext *parse_context_create(ParserSnapshot *snap);
 
/*
** Borrowed-snapshot variant: same as parse_context_create except
** snap->refcount is NOT touched.  Caller guarantees snap outlives
** the returned ParseContext.  See parse_begin_borrowed() in the
** parser.h-style API section below.
*/
ParseContext *parse_context_create_borrowed(ParserSnapshot *snap);
 
/*
** Destroy a parse context, releasing the snapshot.
*/
void parse_context_destroy(ParseContext *ctx);
 
/*
** Drop the calling thread's pooled ParseContext (if any).
**
** Lime maintains a thread-local single-slot pool of recycled
** ParseContexts so that parse_begin / parse_end can avoid
** malloc/free + stack alloc/destroy on every parse.  The pool
** memory is reclaimed at process exit by default; this function
** is for callers who want to drop the cached context explicitly
** before joining a parser thread (test harnesses, leak hunters).
**
** Safe to call from a thread that has never called parse_begin
** (no-op).  Not thread-safe across threads -- each thread drains
** its own slot.
*/
void parse_context_pool_drain(void);
 
/* ------------------------------------------------------------------ */
/*  parser.h wrappers                                                  */
/* ------------------------------------------------------------------ */
 
ParseContext *parse_begin(ParserSnapshot *snap);
void parse_end(ParseContext *ctx);
ParserSnapshot *parse_get_snapshot(ParseContext *ctx);
 
ParseContext *parse_begin_borrowed(ParserSnapshot *snap);
 
/*
** Feed a token to the push parser.
**
**   ctx         Active parse context.
**   token_code  Token code (0 for end-of-input).
**   token_value Semantic value (may be NULL).
**   location    Byte offset of the token in the source, or
**               LIME_LOC_UNKNOWN if the grammar does not declare
**               %locations or the caller does not track positions.
**
** Returns 0 on success, non-zero on parse error.
*/
int parse_token(ParseContext *ctx, int token_code, void *token_value, int location);
 
/* ------------------------------------------------------------------ */
/*  Host-reduce binding (Letter 30)                                    */
/* ------------------------------------------------------------------ */
 
/*
** Bind a host-reduce hook on this parse session, overriding any
** hook carried by the snapshot.  When set, the push parser calls
** `fn` on every base-grammar reduce to run the action and produce
** the LHS value (see LimeHostReduceFn in snapshot.h).  Pass fn==NULL
** to clear the session override and fall back to the snapshot's
** host_reduce (which may itself be NULL = recognition-only).
**
** This keeps the snapshot immutable/shareable: a composed snapshot
** can be driven by different reduce dispatches per session.  Has no
** effect on the shift hot path; the hook is consulted only inside a
** reduce.
*/
void parse_set_host_reduce(ParseContext *ctx, LimeHostReduceFn fn, void *user);
 
/*
** Return the semantic value the start-rule reduce produced once the
** parse has accepted, or NULL if the parse has not accepted, ran no
** host-reduce, or the start action produced NULL.  The pointer's
** lifetime is the host's responsibility (Lime never frees it).
*/
void *parse_result(const ParseContext *ctx);
 
/*
** Sentinel value for `location` callers who do not track positions
** (or who cannot attribute a position to a given token, e.g. an
** injected end-of-input marker).  Guaranteed to be -1 so that
** existing code that passed an integer offset happens to be
** forward-compatible when offsets are always >= 0.
*/
#define LIME_LOC_UNKNOWN (-1)
 
/* ------------------------------------------------------------------ */
/*  Grammar-context binding (optional)                                 */
/* ------------------------------------------------------------------ */
 
/* Forward declaration; full type lives in include/grammar_context.h. */
typedef struct GrammarContextStack GrammarContextStack;
 
void parse_attach_context_stack(ParseContext *ctx, GrammarContextStack *stack);
 
int parse_token_lex(ParseContext *ctx, int token_code, void *token_value, const char *lexeme,
                    int location);
 
/* ------------------------------------------------------------------ */
/*  Snapshot action table lookup helpers                               */
/* ------------------------------------------------------------------ */
 
uint16_t snap_find_shift_action(const ParserSnapshot *snap, uint16_t stateno, uint16_t iLookAhead);
uint16_t snap_find_reduce_action(const ParserSnapshot *snap, uint16_t stateno, uint16_t iLookAhead);
 
/* ------------------------------------------------------------------ */
/*  Context-sensitive token admissibility (multi-grammar composition)  */
/* ------------------------------------------------------------------ */
 
/* Sentinel returned by parse_context_current_state() when no parse is
** in progress (no state to constrain a token).  Equal to UINT16_MAX. */
#define LIME_NO_STATE ((uint16_t)0xFFFFu)
 
/* Classification of a token's action in a given LR state.  Derived
** from the snapshot's self-describing action-code ranges (see
** snapshot.h: yy_max_shift / yy_min_shiftreduce / yy_min_reduce /
** yy_error_action / yy_accept_action).  Result type of
** lime_token_admissible_in_state().
**
** "Admissible" = anything other than LIME_TOK_NONE: the parser would
** make progress (shift, shift-reduce, reduce, or accept) on the token
** in that state.  Scanner glue resolving a lexeme that collides
** between a base grammar and a loaded extension uses this to decide
** which token code to emit: prefer the code admissible in the current
** parser state.  When BOTH a base and an extension code are
** admissible, the collision is genuinely ambiguous and must be
** resolved by the disambiguation strategy (fork-resolve), not here. */
typedef enum LimeTokenAdmissibility {
    LIME_TOK_NONE = 0,    
    LIME_TOK_SHIFT,       
    LIME_TOK_SHIFTREDUCE, 
    LIME_TOK_REDUCE,      
    LIME_TOK_ACCEPT       
} LimeTokenAdmissibility;
 
/* Current LR state at the top of ctx's parse stack, or LIME_NO_STATE
** when no parse is in progress.  Raw introspection value: between
** tokens it may be a pending shift-reduce encoding, not a settled
** state.  For an admissibility decision use
** parse_context_token_admissible() instead (lookahead-correct). */
uint16_t parse_context_current_state(const ParseContext *ctx);
 
/* Lookahead-correct admissibility oracle: would the parser bound to
** `ctx`, in its current state, make progress on `external_token_code`
** (shift / shift-reduce / reduce / accept) rather than syntax-error?
** This is the primary entry point for context-sensitive keyword
** disambiguation -- it replays the engine's shift/reduce/goto loop
** read-only (resolving pending reduces and lookahead-gated default
** reduces) without mutating the live parse or running user actions.
** Returns LIME_TOK_SHIFT (treat-as-admissible) before the first
** token and on any internal limit, so it never wrongly vetoes.
** See src/parse_engine.c and docs/MULTI_GRAMMAR.md. */
LimeTokenAdmissibility parse_context_token_admissible(
    const ParseContext *ctx, int external_token_code);
 
/* Lower-level variant: classify `external_token_code` against an
** explicit, already-settled LR state of `snap` (no pending-reduce
** resolution -- the caller must pass a real state).  Most callers
** want parse_context_token_admissible() instead, which handles the
** pending-reduce / default-reduce resolution for them.
**
** `external_token_code` is the EXTERNAL token code (the value an
** extension or the grammar's .h #define uses).  The %first_token
** offset is applied internally; EOF (0) is preserved.  Out-of-range
** codes classify as LIME_TOK_NONE.  When `stateno` is LIME_NO_STATE
** the result is LIME_TOK_SHIFT (treat-as-admissible).
**
** Pure function over read-only snapshot tables; O(1) -- one action-
** table probe.  Single-grammar parsers never call this. */
LimeTokenAdmissibility lime_token_admissible_in_state(
    const ParserSnapshot *snap, uint16_t stateno, int external_token_code);
 
/* ------------------------------------------------------------------ */
/*  Tier 1: full-statement fork simulation                             */
/* ------------------------------------------------------------------ */
 
/* Outcome of simulating a fresh parse of a snapshot over a fixed token
** buffer (lime_simulate_parse).  Used to rank candidate grammars when
** a collision is admissible in more than one: feed each candidate the
** real upcoming token stream and see how far it gets. */
typedef struct LimeForkTrial {
    uint32_t tokens_consumed; /* external tokens shifted before stopping */
    bool     reached_accept;  /* true if the parse reached an accept state */
    uint32_t error_count;     /* unrecoverable errors encountered (0 or 1) */
} LimeForkTrial;
 
/* Read-only, action-free simulation of parsing `tokens[0..ntokens)`
** (plus an implicit trailing EOF) with `snap`'s automaton, starting
** from the LR start state.  Mutates nothing and runs no user/host
** reduce actions; it replays the engine's shift/reduce/goto loop on a
** private state stack purely to measure how far the grammar gets.
**
** This is the Tier 1 primitive behind multi-grammar fork-resolve: on a
** collision where two loaded dialects both admit the colliding token,
** simulate each over the real lookahead and prefer the one that
** reaches accept (or gets furthest with fewest errors).  Resolves
** structural overlap that DIVERGES within the statement; two truly-
** identical productions trial identically (rank by Tier 2 / Tier 3).
**
** Cost: invoked only on a registered-extension collision; never on the
** single-grammar / no-collision hot path.  No allocation for parses
** that stay within the inline scratch depth. */
LimeForkTrial lime_simulate_parse(const ParserSnapshot *snap,
                                  const int *tokens, uint32_t ntokens);
 
#endif /* PARSE_CONTEXT_H */