libsnobol4 1.0.2
High-performance SNOBOL4-style pattern matching library
Loading...
Searching...
No Matches
snobol.h File Reference

Main API entry point for libsnobol4. More...

#include "snobol/c23_compat.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "snobol/version.h"
#include "snobol/array.h"
#include "snobol/ast.h"
#include "snobol/compiler.h"
#include "snobol/dynamic_pattern.h"
#include "snobol/lexer.h"
#include "snobol/parser.h"
#include "snobol/search.h"
#include "snobol/string_fn.h"
#include "snobol/table.h"
#include "snobol/type_fn.h"
#include "snobol/vm.h"
Include dependency graph for snobol.h:

Go to the source code of this file.

Classes

struct  snobol_batch_result
 Result from snobol_pattern_search_batch(). More...
struct  snobol_match
 Match result object. More...
struct  snobol_literal_match
 Lightweight result from snobol_pattern_match_literal(). More...
struct  snobol_match_result
 Result from the one-shot snobol_match() convenience API. More...

Macros

#define SNOBOL_ABI_VERSION   1
 ABI version number (monotonically increasing).
#define SNOBOL_DEPRECATED
#define SNOBOL_API_MAX_VARS   64
 Maximum named variables returned from a match.
#define SNOBOL_FLAG_CASE_INSENSITIVE   0x0001u

Typedefs

typedef struct snobol_context snobol_context_t
 Pattern matching context (opaque handle).
typedef struct snobol_pattern snobol_pattern_t
 Compiled pattern (opaque handle).
typedef struct snobol_batch_result snobol_batch_result_t
 Result from snobol_pattern_search_batch().
typedef struct snobol_match snobol_match_t
 Match result object.
typedef struct snobol_literal_match snobol_literal_match_t
 Lightweight result from snobol_pattern_match_literal().
typedef struct snobol_pattern_search_state snobol_pattern_search_state_t
 Opaque state for snobol_pattern_search_ex().
typedef struct snobol_match_result snobol_match_result_t
 Result from the one-shot snobol_match() convenience API.
typedef struct snobol_pattern_build snobol_pattern_build_t
 Opaque builder state.

Functions

void snobol_version (int *major, int *minor, int *patch)
uint32_t snobol_get_api_version (void)
uint32_t snobol_get_abi_version (void)
bool snobol_pattern_search_batch (const uint8_t *bc, size_t bc_len, const char *subject, size_t len, const snobol_search_meta_t *meta, snobol_batch_result_t *out)
 Find all non-overlapping matches in a single pass.
void snobol_batch_result_free (snobol_batch_result_t *out)
 Free all arrays owned by a batch result struct. NULL-safe.
snobol_context_t * snobol_context_create (void)
 Create a new pattern matching context.
void snobol_context_destroy (snobol_context_t *ctx)
 Destroy a pattern matching context and free all associated resources.
snobol_pattern_t * snobol_pattern_compile (snobol_context_t *ctx, const char *source, size_t len, char **error)
 Compile a SNOBOL4 pattern string to a compiled pattern object.
snobol_pattern_t * snobol_pattern_compile_ex (snobol_context_t *ctx, const char *source, size_t len, uint32_t flags, char **error)
snobol_pattern_t * snobol_pattern_from_bytecode (uint8_t *bc, size_t bc_len, uint32_t flags, char **error)
 Build a pattern from an existing bytecode buffer.
const uint8_t * snobol_pattern_get_bc (const snobol_pattern_t *pattern)
 Get the bytecode pointer from a compiled pattern.
size_t snobol_pattern_get_bc_len (const snobol_pattern_t *pattern)
 Get the bytecode length from a compiled pattern.
const snobol_search_meta_t * snobol_pattern_get_meta (const snobol_pattern_t *pattern)
 Get the pre-derived search metadata for a compiled pattern.
const snobol_range_meta_t * snobol_pattern_get_range_meta (const snobol_pattern_t *pattern, size_t *count)
 Retrieve cached charclass range metadata from a compiled pattern.
void snobol_pattern_free (snobol_pattern_t *pattern)
 Free a compiled pattern.
int snobol_pattern_bind_tables (snobol_pattern_t *pattern, const char **names, snobol_table_t *const *tables, size_t n)
 Bind host tables to a compiled pattern by name.
int snobol_pattern_bind_bytecode_tables (uint8_t *bc, size_t bc_len, const char **names, size_t n)
 Bind table ids in a compiled pattern bytecode buffer by name.
snobol_match_t * snobol_pattern_match (snobol_pattern_t *pattern, const char *subject, size_t len)
 Execute a compiled pattern against a subject string.
snobol_literal_match_t snobol_pattern_match_literal (snobol_pattern_t *pattern, const char *subject, size_t len)
 Lightweight anchored literal match for literal-only patterns.
snobol_match_t * snobol_pattern_search (snobol_pattern_t *pattern, const char *subject, size_t len)
 Execute a compiled pattern in search (un-anchored) mode.
snobol_pattern_search_state_t * snobol_pattern_search_state_create (const uint8_t *bc, size_t bc_len)
 Create a state object for snobol_pattern_search_ex().
void snobol_pattern_search_state_set_pattern (snobol_pattern_search_state_t *state, snobol_pattern_t *pattern)
 Associate an owning pattern with a search state.
void snobol_pattern_search_state_set_trie_cache (snobol_pattern_search_state_t *state, snobol_auto_trie_t *trie)
void snobol_pattern_search_state_set_eval_fn (snobol_pattern_search_state_t *state, bool(*eval_fn)(int fn_id, const char *s, size_t start, size_t end, void *userdata), void *eval_udata)
 Set the EVAL callback function on a search state's persistent VM.
int snobol_pattern_search_state_set_tables (snobol_pattern_search_state_t *state, snobol_table_t *const *tables, size_t n)
 Set the tables registered into a search state's persistent VM.
void snobol_pattern_search_state_destroy (snobol_pattern_search_state_t *state)
 Destroy a search state object. NULL-safe.
snobol_match_t * snobol_pattern_search_ex (snobol_pattern_search_state_t *state, const char *subject, size_t subject_len, size_t start_offset)
 Stateful search that reuses VM, output buffer, and match result across calls.
snobol_match_t * snobol_pattern_search_ex_anchored (snobol_pattern_search_state_t *state, const char *subject, size_t subject_len)
 Stateful anchored search that reuses VM, DFA, and range_meta.
bool snobol_pattern_search_next (snobol_pattern_search_state_t *state, const char *subject, size_t subject_len, size_t start_offset, size_t *out_pos, size_t *out_len)
 Lightweight unanchored search for single-literal patterns.
bool snobol_pattern_search_batch_ex (snobol_pattern_search_state_t *state, const char *subject, size_t len, snobol_batch_result_t *out)
 Stateful batch search that reuses VM, range_meta, and (for automaton-eligible patterns) the DFA/trie/SIMD-NFA caches across calls.
size_t snobol_match_get_position (const snobol_match_t *match)
 Get the absolute offset where the match started within the subject.
size_t snobol_match_get_length (const snobol_match_t *match)
 Get the length of the match in bytes.
void snobol_match_free (snobol_match_t *match)
 Free a match result.
snobol_match_t * snobol_match_create (void)
 Create a new match result object.
void snobol_match_reset (snobol_match_t *match)
 Reset a match result for reuse without freeing.
bool snobol_pattern_search_reuse (snobol_pattern_t *pattern, const char *subject, size_t len, snobol_match_t *match_out)
 Search using a caller-allocated, reusable match object.
bool snobol_match_success (snobol_match_t *match)
 Return whether a match result represents a successful match.
const char * snobol_match_get_output (snobol_match_t *match, size_t *len)
 Retrieve the output buffer produced by a successful match.
const char * snobol_match_get_variable (snobol_match_t *match, const char *name, size_t *len)
 Retrieve the value of a named capture variable from a match result.
snobol_match_result_t * snobol_match (const char *pattern, size_t pat_len, const char *subject, size_t sub_len, uint32_t flags)
 One-shot convenience match: compile and run a pattern in one call.
void snobol_match_result_free (snobol_match_result_t *result)
 Free a snobol_match_result_t and all its owned resources.
snobol_pattern_build_t * snobol_pattern_build_create (void)
 Create a new builder.
void snobol_pattern_build_destroy (snobol_pattern_build_t *build)
 Destroy a builder. Does NOT free emitted AST nodes.
ast_node_t * snobol_pattern_build_lit (snobol_pattern_build_t *build, const char *text, size_t len)
 Create a LITERAL AST node.
ast_node_t * snobol_pattern_build_span (snobol_pattern_build_t *build, const char *set, size_t len)
 Create a SPAN AST node (match 1+ chars in set).
ast_node_t * snobol_pattern_build_brk (snobol_pattern_build_t *build, const char *set, size_t len)
 Create a BREAK AST node (consume until char in set).
ast_node_t * snobol_pattern_build_any (snobol_pattern_build_t *build, const char *set, size_t len)
 Create an ANY AST node (match single char in optional set).
ast_node_t * snobol_pattern_build_notany (snobol_pattern_build_t *build, const char *set, size_t len)
 Create a NOTANY AST node (match single char NOT in set).
ast_node_t * snobol_pattern_build_len (snobol_pattern_build_t *build, int32_t n)
 Create a LEN AST node (match exactly N codepoints).
ast_node_t * snobol_pattern_build_arbno (snobol_pattern_build_t *build, ast_node_t *sub)
 Create an ARBNO AST node (zero or more repetitions).
ast_node_t * snobol_pattern_build_cap (snobol_pattern_build_t *build, int reg, ast_node_t *sub)
 Create a CAP AST node (capture sub-pattern into register).
ast_node_t * snobol_pattern_build_name (snobol_pattern_build_t *build, int reg, ast_node_t *sub)
 Create a match-naming node: bind sub-pattern's match to register.
ast_node_t * snobol_pattern_build_assign (snobol_pattern_build_t *build, int var, int reg)
 Create an ASSIGN AST node (assign register to variable).
ast_node_t * snobol_pattern_build_concat (snobol_pattern_build_t *build, ast_node_t **parts, size_t count)
 Create a CONCAT AST node (sequence of parts). Takes ownership of parts array and all child nodes.
ast_node_t * snobol_pattern_build_alt (snobol_pattern_build_t *build, ast_node_t *left, ast_node_t *right)
 Create an ALT AST node (alternation).
ast_node_t * snobol_pattern_build_label (snobol_pattern_build_t *build, const char *name, ast_node_t *target)
 Create a LABEL AST node.
ast_node_t * snobol_pattern_build_goto (snobol_pattern_build_t *build, const char *label)
 Create a GOTO AST node.
ast_node_t * snobol_pattern_build_pos (snobol_pattern_build_t *build, int32_t n)
 Create a POS AST node.
ast_node_t * snobol_pattern_build_tab (snobol_pattern_build_t *build, int32_t n)
 Create a TAB AST node.
ast_node_t * snobol_pattern_build_rpos (snobol_pattern_build_t *build, int32_t n)
 Create a RPOS AST node.
ast_node_t * snobol_pattern_build_rtab (snobol_pattern_build_t *build, int32_t n)
 Create a RTAB AST node.
ast_node_t * snobol_pattern_build_breakx (snobol_pattern_build_t *build, const char *set, size_t len)
 Create a BREAKX AST node.
ast_node_t * snobol_pattern_build_bal (snobol_pattern_build_t *build, uint32_t open_cp, uint32_t close_cp)
 Create a BAL AST node.
ast_node_t * snobol_pattern_build_fence (snobol_pattern_build_t *build)
 Create a FENCE AST node.
ast_node_t * snobol_pattern_build_rem (snobol_pattern_build_t *build)
 Create a REM AST node.
ast_node_t * snobol_pattern_build_abort (snobol_pattern_build_t *build)
 Create an ABORT AST node.
ast_node_t * snobol_pattern_build_fail (snobol_pattern_build_t *build)
 Create a FAIL AST node.
ast_node_t * snobol_pattern_build_succeed (snobol_pattern_build_t *build)
 Create a SUCCEED AST node.
ast_node_t * snobol_pattern_build_emit (snobol_pattern_build_t *build, ast_node_t *root)
 Finalize and emit an AST tree built with the builder.
snobol_pattern_t * snobol_pattern_build_compile (snobol_context_t *ctx, ast_node_t *root, uint32_t flags, char **error)
 Compile a built AST root into a compiled pattern object.

Detailed Description

Main API entry point for libsnobol4.

libsnobol4 is a high-performance C library implementing SNOBOL4-style pattern matching. This header provides the main API entry point, re-exporting common types and functions for convenient single-include usage.

Reusable Match API

For hot loops (e.g. searchSplit with 1000+ matches), use:

This eliminates per-call malloc/free overhead (~30 ns per match).

Version
0.13.0

Definition in file snobol.h.

Macro Definition Documentation

◆ SNOBOL_ABI_VERSION

#define SNOBOL_ABI_VERSION   1

ABI version number (monotonically increasing).

Incremented on any breaking ABI change. The initial value is 1. Bindings can check this at load time to detect incompatibility.

Definition at line 49 of file snobol.h.

◆ SNOBOL_API_MAX_VARS

#define SNOBOL_API_MAX_VARS   64

Maximum named variables returned from a match.

Definition at line 134 of file snobol.h.

◆ SNOBOL_DEPRECATED

#define SNOBOL_DEPRECATED

Definition at line 65 of file snobol.h.

◆ SNOBOL_FLAG_CASE_INSENSITIVE

#define SNOBOL_FLAG_CASE_INSENSITIVE   0x0001u

Make literal and character-class matching case-insensitive for ASCII and Latin-1 Supplement (U+0041–U+005A / U+0061–U+007A; U+00C0–U+00FF pairs). Captured text preserves the original subject case.

Pass to snobol_pattern_compile_ex() via the flags bitmask.

Definition at line 292 of file snobol.h.

Typedef Documentation

◆ snobol_batch_result_t

Result from snobol_pattern_search_batch().

Contains all non-overlapping matches found in a single pass, stored as flat C arrays. All array memory is allocated with snobol_malloc; the caller must free via snobol_batch_result_free().

When no captures are present, var_count is 0 and captures is NULL. outputs is NULL when no match produced EMIT output. Each output segment is NUL-terminated; the final segment is followed by an empty-string sentinel so callers can iterate outputs without needing output_lens.

eligible distinguishes "no matches but the pattern was batch-eligible" (true, zero matches) from "the pattern was not batch-eligible" (false). Callers must check eligible: a false return with eligible == true means the search completed with zero matches (DONE) — do NOT re-run the search. A false return with eligible == false means the pattern must fall back to the per-call loop. eligible is set true for every batch-eligible pattern regardless of match count, and false (the safe default) for early-outs.

◆ snobol_context_t

typedef struct snobol_context snobol_context_t

Pattern matching context (opaque handle).

The context owns all compiled patterns and associated resources. Create with snobol_context_create(), destroy with snobol_context_destroy().

Definition at line 121 of file snobol.h.

◆ snobol_literal_match_t

Lightweight result from snobol_pattern_match_literal().

Zero heap allocations — returned by value. Only valid for patterns whose bytecode is a single anchored literal (e.g. "'abc'").

◆ snobol_match_result_t

Result from the one-shot snobol_match() convenience API.

Unlike the opaque snobol_match_t (which is used by the multi-step API), this struct is non-opaque so callers can directly read the fields.

◆ snobol_match_t

typedef struct snobol_match snobol_match_t

Match result object.

Contains the result of a successful pattern match, including captured variables and output buffer. Use snobol_match_create() to allocate, snobol_match_free() to release.

◆ snobol_pattern_build_t

typedef struct snobol_pattern_build snobol_pattern_build_t

Opaque builder state.

Definition at line 909 of file snobol.h.

◆ snobol_pattern_search_state_t

typedef struct snobol_pattern_search_state snobol_pattern_search_state_t

Opaque state for snobol_pattern_search_ex().

Holds the cached search metadata, a reusable VM, an output buffer, and a reusable match result. Created once per pattern, reused across all matches in a search loop (e.g. PHP Pattern::searchSplit) to avoid per-call allocation churn.

Pointer ownership: created by snobol_pattern_search_state_create(), destroyed by snobol_pattern_search_state_destroy(). The state holds a reference to the pattern but does not own it; the caller must keep the pattern alive until the state is destroyed.

Definition at line 530 of file snobol.h.

◆ snobol_pattern_t

typedef struct snobol_pattern snobol_pattern_t

Compiled pattern (opaque handle).

Represents a compiled pattern ready for matching. Created via snobol_pattern_compile().

Definition at line 129 of file snobol.h.

Function Documentation

◆ snobol_batch_result_free()

void snobol_batch_result_free ( snobol_batch_result_t * out)

Free all arrays owned by a batch result struct. NULL-safe.

Releases positions, lengths, captures, outputs, and output_lens arrays. Does NOT free the struct itself (caller-allocated).

◆ snobol_context_create()

snobol_context_t * snobol_context_create ( void )

Create a new pattern matching context.

The context owns all compiled patterns and associated resources. Must be destroyed with snobol_context_destroy() when no longer needed.

Returns
New context, or NULL on allocation failure.

◆ snobol_context_destroy()

void snobol_context_destroy ( snobol_context_t * ctx)

Destroy a pattern matching context and free all associated resources.

All patterns compiled under this context are invalidated. Passing NULL is safe (no-op).

Parameters
[in]ctxContext to destroy.

◆ snobol_get_abi_version()

uint32_t snobol_get_abi_version ( void )

Get the ABI version of the library.

Returns a monotonically-increasing integer that is bumped whenever a breaking change is made to the public ABI. Bindings and dynamic loaders can call this at initialisation to verify compatibility.

The initial v0.11.0 value is 1.

Returns
ABI version integer.

◆ snobol_get_api_version()

uint32_t snobol_get_api_version ( void )

Get library API version as a single encoded integer.

Encoding: (MAJOR << 16) | (MINOR << 8) | PATCH

Bindings should compare snobol_get_api_version() >> 16 against their compile-time SNOBOL_VERSION_MAJOR to detect incompatible library upgrades.

Returns
Encoded API version uint32_t. For v0.11.0 this returns 0x00000B00u.

◆ snobol_match()

snobol_match_result_t * snobol_match ( const char * pattern,
size_t pat_len,
const char * subject,
size_t sub_len,
uint32_t flags )

One-shot convenience match: compile and run a pattern in one call.

Bundles the full pipeline: lexer → parser → compiler → VM execution. All intermediate objects are freed internally.

Parameters
[in]patternPattern source string (UTF-8).
[in]pat_lenByte length of pattern.
[in]subjectSubject string (UTF-8).
[in]sub_lenByte length of subject.
[in]flagsBitmask of SNOBOL_FLAG_* constants (0 for default).
Returns
Newly allocated snobol_match_result_t. Always valid; check the success and error fields. Free with snobol_match_result_free().

◆ snobol_match_create()

snobol_match_t * snobol_match_create ( void )

Create a new match result object.

Allocates and zero-initializes a snobol_match_t. The caller owns the returned pointer and must free it with snobol_match_free() or reuse it with snobol_pattern_search_reuse().

Returns
Newly allocated match object, or NULL on allocation failure.

◆ snobol_match_free()

void snobol_match_free ( snobol_match_t * match)

Free a match result.

Parameters
[in]matchMatch result to free. NULL is safe.

◆ snobol_match_get_length()

size_t snobol_match_get_length ( const snobol_match_t * match)

Get the length of the match in bytes.

Parameters
[in]matchMatch result from snobol_pattern_search() or snobol_pattern_search_ex().
Returns
Number of bytes in the match. Returns 0 on failure or NULL.

◆ snobol_match_get_output()

const char * snobol_match_get_output ( snobol_match_t * match,
size_t * len )

Retrieve the output buffer produced by a successful match.

The output contains any text emitted by OP_EMIT_LITERAL / OP_EMIT_CAPTURE instructions during the match.

Parameters
[in]matchMatch result from snobol_pattern_match().
[out]lenIf non-NULL, set to the byte length of the returned string.
Returns
Pointer to the output string (owned by match, do not free), or NULL if there is no output.

◆ snobol_match_get_position()

size_t snobol_match_get_position ( const snobol_match_t * match)

Get the absolute offset where the match started within the subject.

Returns the position of the first byte of the match in the subject string (not the position within the search window). Returns 0 on failure or if match is NULL.

Parameters
[in]matchMatch result from snobol_pattern_search() or snobol_pattern_search_ex().
Returns
Byte offset of the match start in the original subject.

◆ snobol_match_get_variable()

const char * snobol_match_get_variable ( snobol_match_t * match,
const char * name,
size_t * len )

Retrieve the value of a named capture variable from a match result.

Parameters
[in]matchMatch result from snobol_pattern_match().
[in]nameVariable name (NUL-terminated).
[out]lenIf non-NULL, set to the byte length of the returned string.
Returns
Pointer to the variable value (owned by match, do not free), or NULL if the variable was not set during the match.

◆ snobol_match_reset()

void snobol_match_reset ( snobol_match_t * match)

Reset a match result for reuse without freeing.

Clears all fields and frees any allocated capture strings. The match object remains allocated and ready for reuse. Safe to call on a zeroed or freshly allocated match object.

Parameters
[in,out]matchMatch result to reset. NULL is safe (no-op).

◆ snobol_match_result_free()

void snobol_match_result_free ( snobol_match_result_t * result)

Free a snobol_match_result_t and all its owned resources.

Parameters
[in]resultResult to free. NULL is safe.

◆ snobol_match_success()

bool snobol_match_success ( snobol_match_t * match)

Return whether a match result represents a successful match.

Parameters
[in]matchMatch result from snobol_pattern_match().
Returns
true if the pattern matched; false otherwise.

◆ snobol_pattern_bind_bytecode_tables()

int snobol_pattern_bind_bytecode_tables ( uint8_t * bc,
size_t bc_len,
const char ** names,
size_t n )

Bind table ids in a compiled pattern bytecode buffer by name.

Low-level companion to snobol_pattern_bind_tables() for callers that own pattern bytecode directly (bindings that compile bytecode without a core pattern object). Patches every OP_TABLE_GET / OP_TABLE_SET instruction in place: an instruction whose embedded name matches names[k] is patched to id k; every other instruction is reset to SNBL_TABLE_ID_UNBOUND so the op fails at match time. Registering the tables into the execution VM is the caller's responsibility (see snobol_pattern_search_state_set_tables()); the registration order must be the same as the name order passed here.

Parameters
[in,out]bcMutable bytecode buffer, patched in place.
[in]bc_lenByte length of bc.
[in]namesTable names to bind (NULL or n == 0 clears all table ops back to unbound).
[in]nNumber of entries in names.
Returns
0 on success, -1 on invalid arguments.

◆ snobol_pattern_bind_tables()

int snobol_pattern_bind_tables ( snobol_pattern_t * pattern,
const char ** names,
snobol_table_t *const * tables,
size_t n )

Bind host tables to a compiled pattern by name.

Resolves the embedded table names of every unbound OP_TABLE_GET / OP_TABLE_SET instruction in the pattern's bytecode: an instruction whose name matches names[k] is patched to the sequential id k, and the tables are retained on the pattern so every match/search call registers them into its execution VM (reads resolve, writes land in the table).

A name with no matching entry — and any pattern that was never bound — keeps today's behaviour: the table op fails and backtracks. Re-binding with a different (e.g. reordered) list re-patches every instruction against the new list, so a name absent from it fails again; binding with n equal to 0 releases the retained tables and clears the binding.

Mutating the pattern's bytecode is one-shot: bind before sharing the pattern across threads.

Parameters
[in]patternCompiled pattern to bind (NULL returns -1).
[in]namesTable names, parallel to tables.
[in]tablesTables to retain and register, parallel to names.
[in]nNumber of entries in names / tables.
Returns
0 on success, -1 on invalid arguments or allocation failure.

◆ snobol_pattern_build_abort()

ast_node_t * snobol_pattern_build_abort ( snobol_pattern_build_t * build)

Create an ABORT AST node.

◆ snobol_pattern_build_alt()

ast_node_t * snobol_pattern_build_alt ( snobol_pattern_build_t * build,
ast_node_t * left,
ast_node_t * right )

Create an ALT AST node (alternation).

◆ snobol_pattern_build_any()

ast_node_t * snobol_pattern_build_any ( snobol_pattern_build_t * build,
const char * set,
size_t len )

Create an ANY AST node (match single char in optional set).

◆ snobol_pattern_build_arbno()

ast_node_t * snobol_pattern_build_arbno ( snobol_pattern_build_t * build,
ast_node_t * sub )

Create an ARBNO AST node (zero or more repetitions).

◆ snobol_pattern_build_assign()

ast_node_t * snobol_pattern_build_assign ( snobol_pattern_build_t * build,
int var,
int reg )

Create an ASSIGN AST node (assign register to variable).

◆ snobol_pattern_build_bal()

ast_node_t * snobol_pattern_build_bal ( snobol_pattern_build_t * build,
uint32_t open_cp,
uint32_t close_cp )

Create a BAL AST node.

◆ snobol_pattern_build_breakx()

ast_node_t * snobol_pattern_build_breakx ( snobol_pattern_build_t * build,
const char * set,
size_t len )

Create a BREAKX AST node.

◆ snobol_pattern_build_brk()

ast_node_t * snobol_pattern_build_brk ( snobol_pattern_build_t * build,
const char * set,
size_t len )

Create a BREAK AST node (consume until char in set).

◆ snobol_pattern_build_cap()

ast_node_t * snobol_pattern_build_cap ( snobol_pattern_build_t * build,
int reg,
ast_node_t * sub )

Create a CAP AST node (capture sub-pattern into register).

◆ snobol_pattern_build_compile()

snobol_pattern_t * snobol_pattern_build_compile ( snobol_context_t * ctx,
ast_node_t * root,
uint32_t flags,
char ** error )

Compile a built AST root into a compiled pattern object.

Runs the same post-AST pipeline as snobol_pattern_compile_ex() — bytecode generation, search metadata derivation, and range metadata construction — so builder-composed patterns are fully initialized and match identically to their source-compiled equivalents. No internal struct fields are exposed or hand-populated by the caller.

Parameters
[in]ctxContext that will own the returned pattern.
[in]rootRoot AST node from snobol_pattern_build_emit(). Ownership is transferred: the tree is freed by this call on both success and failure, and must NOT be freed by the caller afterwards.
[in]flagsBitmask of SNOBOL_FLAG_* constants (unknown bits are ignored).
[out]errorOn failure, *error is set to a malloc'd error string that the caller must free. Set to NULL on success.
Returns
Compiled pattern owned by ctx, or NULL on compile error. Free with snobol_pattern_free() before destroying the context.

◆ snobol_pattern_build_concat()

ast_node_t * snobol_pattern_build_concat ( snobol_pattern_build_t * build,
ast_node_t ** parts,
size_t count )

Create a CONCAT AST node (sequence of parts). Takes ownership of parts array and all child nodes.

◆ snobol_pattern_build_create()

snobol_pattern_build_t * snobol_pattern_build_create ( void )

Create a new builder.

◆ snobol_pattern_build_destroy()

void snobol_pattern_build_destroy ( snobol_pattern_build_t * build)

Destroy a builder. Does NOT free emitted AST nodes.

◆ snobol_pattern_build_emit()

ast_node_t * snobol_pattern_build_emit ( snobol_pattern_build_t * build,
ast_node_t * root )

Finalize and emit an AST tree built with the builder.

Takes ownership of root and returns it. After this call the builder may be reused to build a new tree, or destroyed. The returned node must eventually be freed via snobol_ast_free().

Parameters
[in]buildBuilder instance (may be NULL for stateless usage).
[in]rootRoot AST node to emit (ownership transferred).
Returns
root (non-NULL if input non-NULL).

◆ snobol_pattern_build_fail()

ast_node_t * snobol_pattern_build_fail ( snobol_pattern_build_t * build)

Create a FAIL AST node.

◆ snobol_pattern_build_fence()

ast_node_t * snobol_pattern_build_fence ( snobol_pattern_build_t * build)

Create a FENCE AST node.

◆ snobol_pattern_build_goto()

ast_node_t * snobol_pattern_build_goto ( snobol_pattern_build_t * build,
const char * label )

Create a GOTO AST node.

◆ snobol_pattern_build_label()

ast_node_t * snobol_pattern_build_label ( snobol_pattern_build_t * build,
const char * name,
ast_node_t * target )

Create a LABEL AST node.

◆ snobol_pattern_build_len()

ast_node_t * snobol_pattern_build_len ( snobol_pattern_build_t * build,
int32_t n )

Create a LEN AST node (match exactly N codepoints).

◆ snobol_pattern_build_lit()

ast_node_t * snobol_pattern_build_lit ( snobol_pattern_build_t * build,
const char * text,
size_t len )

Create a LITERAL AST node.

◆ snobol_pattern_build_name()

ast_node_t * snobol_pattern_build_name ( snobol_pattern_build_t * build,
int reg,
ast_node_t * sub )

Create a match-naming node: bind sub-pattern's match to register.

Source-equivalent of P . @vN / P $ vN: compiles to the same CAP_START/CAP_END bytecode as snobol_pattern_build_cap.

◆ snobol_pattern_build_notany()

ast_node_t * snobol_pattern_build_notany ( snobol_pattern_build_t * build,
const char * set,
size_t len )

Create a NOTANY AST node (match single char NOT in set).

◆ snobol_pattern_build_pos()

ast_node_t * snobol_pattern_build_pos ( snobol_pattern_build_t * build,
int32_t n )

Create a POS AST node.

◆ snobol_pattern_build_rem()

ast_node_t * snobol_pattern_build_rem ( snobol_pattern_build_t * build)

Create a REM AST node.

◆ snobol_pattern_build_rpos()

ast_node_t * snobol_pattern_build_rpos ( snobol_pattern_build_t * build,
int32_t n )

Create a RPOS AST node.

◆ snobol_pattern_build_rtab()

ast_node_t * snobol_pattern_build_rtab ( snobol_pattern_build_t * build,
int32_t n )

Create a RTAB AST node.

◆ snobol_pattern_build_span()

ast_node_t * snobol_pattern_build_span ( snobol_pattern_build_t * build,
const char * set,
size_t len )

Create a SPAN AST node (match 1+ chars in set).

◆ snobol_pattern_build_succeed()

ast_node_t * snobol_pattern_build_succeed ( snobol_pattern_build_t * build)

Create a SUCCEED AST node.

◆ snobol_pattern_build_tab()

ast_node_t * snobol_pattern_build_tab ( snobol_pattern_build_t * build,
int32_t n )

Create a TAB AST node.

◆ snobol_pattern_compile()

snobol_pattern_t * snobol_pattern_compile ( snobol_context_t * ctx,
const char * source,
size_t len,
char ** error )

Compile a SNOBOL4 pattern string to a compiled pattern object.

Equivalent to snobol_pattern_compile_ex() with flags = 0.

Parameters
[in]ctxContext that will own the returned pattern.
[in]sourcePattern source text (UTF-8).
[in]lenByte length of source.
[out]errorOn failure, *error is set to a malloc'd error string that the caller must free. Set to NULL on success.
Returns
Compiled pattern owned by ctx, or NULL on parse/compile error. Free with snobol_pattern_free() before destroying the context.

◆ snobol_pattern_compile_ex()

snobol_pattern_t * snobol_pattern_compile_ex ( snobol_context_t * ctx,
const char * source,
size_t len,
uint32_t flags,
char ** error )

Compile a pattern with option flags.

Parameters
ctxContext that owns the returned pattern.
sourcePattern source text (UTF-8).
lenByte length of source.
flagsBitmask of SNOBOL_FLAG_* constants (unknown bits are ignored).
errorOn failure, *error is set to a malloc'd error string. On success, *error is set to NULL. Caller must free on error.
Returns
Compiled pattern owned by ctx, or NULL on parse/compile error. Free with snobol_pattern_free() before destroying the context.

◆ snobol_pattern_free()

void snobol_pattern_free ( snobol_pattern_t * pattern)

Free a compiled pattern.

Parameters
[in]patternPattern to free. NULL is safe.

◆ snobol_pattern_from_bytecode()

snobol_pattern_t * snobol_pattern_from_bytecode ( uint8_t * bc,
size_t bc_len,
uint32_t flags,
char ** error )

Build a pattern from an existing bytecode buffer.

The buffer is finalized exactly like compiler output: search metadata and range metadata are derived through the same path, so the pattern matches, searches and reports its tier exactly like the equivalent compiled pattern.

Note
Ownership of bc transfers when the function is called. On success the pattern owns the buffer and releases it in snobol_pattern_free(). On failure (invalid arguments or out of memory) this function releases the buffer itself. The caller must not free or reuse bc afterwards. bc must come from the compiler API or snobol_malloc().
Parameters
[in]bcBytecode buffer (ownership transfers as described).
[in]bc_lenByte length of bc; must be non-zero.
[in]flagsBitmask of SNOBOL_FLAG_* constants (unknown bits are ignored, matching snobol_pattern_compile_ex()).
[out]errorOn failure, *error is set to a malloc'd message the caller must free; set to NULL on success. May be NULL.
Returns
New pattern, or NULL for a null buffer, zero length or out of memory. Free with snobol_pattern_free().

◆ snobol_pattern_get_bc()

const uint8_t * snobol_pattern_get_bc ( const snobol_pattern_t * pattern)

Get the bytecode pointer from a compiled pattern.

Parameters
[in]patternCompiled pattern.
Returns
Read-only pointer to the bytecode, or NULL if pattern is NULL.

◆ snobol_pattern_get_bc_len()

size_t snobol_pattern_get_bc_len ( const snobol_pattern_t * pattern)

Get the bytecode length from a compiled pattern.

Parameters
[in]patternCompiled pattern.
Returns
Byte length, or 0 if pattern is NULL.

◆ snobol_pattern_get_meta()

const snobol_search_meta_t * snobol_pattern_get_meta ( const snobol_pattern_t * pattern)

Get the pre-derived search metadata for a compiled pattern.

The metadata is computed once at compile time and reused by the search runtime. Exposed read-only for introspection and testing.

Parameters
[in]patternCompiled pattern.
Returns
Read-only pointer to the search metadata, or NULL if pattern is NULL.

◆ snobol_pattern_get_range_meta()

const snobol_range_meta_t * snobol_pattern_get_range_meta ( const snobol_pattern_t * pattern,
size_t * count )

Retrieve cached charclass range metadata from a compiled pattern.

The range metadata is built once at compile time and used by SPAN/BREAK/BREAKX opcodes to resolve character-class set IDs. Callers that invoke snobol_search_exec() directly (bypassing snobol_pattern_search()) must copy this into the VM's range_meta / range_meta_count fields.

Parameters
[in]patternCompiled pattern (NULL returns NULL/0).
[out]countNumber of entries in the returned array (may be NULL).
Returns
Read-only pointer to range metadata array, or NULL.

◆ snobol_pattern_match()

snobol_match_t * snobol_pattern_match ( snobol_pattern_t * pattern,
const char * subject,
size_t len )

Execute a compiled pattern against a subject string.

Parameters
[in]patternCompiled pattern to execute.
[in]subjectSubject string (UTF-8).
[in]lenByte length of subject.
Returns
New match result that the caller must free with snobol_match_free(). Always returns a valid pointer; call snobol_match_success() to determine whether the match succeeded.

◆ snobol_pattern_match_literal()

snobol_literal_match_t snobol_pattern_match_literal ( snobol_pattern_t * pattern,
const char * subject,
size_t len )

Lightweight anchored literal match for literal-only patterns.

If the compiled pattern's bytecode is a single anchored literal (e.g. "'abc'"), this function performs a memcmp at position 0 with zero heap allocations. No VM setup, emit buffer, or capture tracking is performed — the result is returned by value.

For non-literal patterns or when the subject does not start with the pattern literal, success is set to false.

Parameters
[in]patternCompiled pattern to execute.
[in]subjectSubject string (UTF-8).
[in]lenByte length of subject.
Returns
Lightweight result struct (zero heap allocations).

◆ snobol_pattern_search()

snobol_match_t * snobol_pattern_search ( snobol_pattern_t * pattern,
const char * subject,
size_t len )

Execute a compiled pattern in search (un-anchored) mode.

Uses the search tier dispatch (memchr/memmem/bitmap fast paths) before falling back to the interpreter VM when no tier matches. Finds the first occurrence of the pattern anywhere in the subject string (like SNOBOL4's ? or POS(0) match).

Parameters
[in]patternCompiled pattern to execute.
[in]subjectSubject string (UTF-8).
[in]lenByte length of subject.
Returns
New match result that the caller must free with snobol_match_free(). Always returns a valid pointer; call snobol_match_success() to determine whether the match succeeded.

◆ snobol_pattern_search_batch()

bool snobol_pattern_search_batch ( const uint8_t * bc,
size_t bc_len,
const char * subject,
size_t len,
const snobol_search_meta_t * meta,
snobol_batch_result_t * out )

Find all non-overlapping matches in a single pass.

Runs the search engine's main loop once, collecting every match's position, length, captures, and EMIT output into flat arrays in a single result struct. The caller must free the result arrays with snobol_batch_result_free().

Patterns with side-effect ops (EVAL, ASSIGN, DYNAMIC) are not supported and return false immediately (out->eligible == false; caller falls back to the per-call loop).

For batch-eligible patterns the search runs once and out->eligible is set true. When zero matches are found the function returns false but out->eligible stays true — the caller must treat that as DONE (no fallback), not as a request to re-run the search via the per-call loop.

Parameters
bcCompiled bytecode buffer (must outlive the call).
bc_lenBytecode length.
subjectSubject string (must outlive the call — captures reference offsets into it).
lenSubject byte length.
metaPre-derived search metadata (from snobol_search_derive_meta or snobol_pattern_get_meta()).
outOutput struct (caller-allocated, zero-initialised).
Returns
true when at least one match was found; false otherwise. On false, out->match_count is 0 and all arrays are NULL (or empty for ineligible patterns). Check out->eligible to tell zero-match (eligible == true, DONE) from ineligible (eligible == false, fall back to per-call loop).

◆ snobol_pattern_search_batch_ex()

bool snobol_pattern_search_batch_ex ( snobol_pattern_search_state_t * state,
const char * subject,
size_t len,
snobol_batch_result_t * out )

Stateful batch search that reuses VM, range_meta, and (for automaton-eligible patterns) the DFA/trie/SIMD-NFA caches across calls.

Behaves identically to snobol_pattern_search_batch() but reuses the caches already built on state, building them lazily on first use and reusing them on every subsequent call. This avoids re-deriving metadata and rebuilding the DFA per call. The stateless snobol_pattern_search_batch() delegates to a temporary state internally, so both share one implementation.

Parameters
[in,out]stateSearch state created by snobol_pattern_search_state_create().
[in]subjectSubject string (UTF-8, must outlive the call).
[in]lenByte length of subject.
[out]outOutput struct (caller-allocated, zero-initialised).
Returns
Same tri-state contract as snobol_pattern_search_batch(): true when at least one match was found; false otherwise. On false, check out->eligible to tell zero-match (eligible == true, DONE) from ineligible (eligible == false, fall back to per-call loop).

◆ snobol_pattern_search_ex()

snobol_match_t * snobol_pattern_search_ex ( snobol_pattern_search_state_t * state,
const char * subject,
size_t subject_len,
size_t start_offset )

Stateful search that reuses VM, output buffer, and match result across calls.

Functionally equivalent to repeated calls to snobol_pattern_search() but amortises the per-call allocation cost. Intended for hot loops (e.g. PHP Pattern::searchSplit, which performs 1000+ matches per call).

Parameters
[in,out]stateSearch state created by snobol_pattern_search_state_create(). The state's internal match result is overwritten on each call.
[in]subjectSubject string (UTF-8).
[in]subject_lenByte length of subject.
[in]start_offsetByte offset to start searching from (0 = beginning).
Returns
Pointer to the internal match result owned by state, valid until the next call on the same state or state destruction. The caller must NOT free this pointer.

◆ snobol_pattern_search_ex_anchored()

snobol_match_t * snobol_pattern_search_ex_anchored ( snobol_pattern_search_state_t * state,
const char * subject,
size_t subject_len )

Stateful anchored search that reuses VM, DFA, and range_meta.

Identical to snobol_pattern_search_ex() but calls snobol_search_exec_anchored() internally so the match MUST start at offset 0 (SNOBOL-style anchored match). Intended for Pattern::match().

Parameters
[in,out]stateSearch state created by snobol_pattern_search_state_create().
[in]subjectSubject string (UTF-8).
[in]subject_lenByte length of subject.
Returns
Pointer to the internal match result owned by state, valid until the next call on the same state or state destruction. The caller must NOT free this pointer.

◆ snobol_pattern_search_next()

bool snobol_pattern_search_next ( snobol_pattern_search_state_t * state,
const char * subject,
size_t subject_len,
size_t start_offset,
size_t * out_pos,
size_t * out_len )

Lightweight unanchored search for single-literal patterns.

Returns the position and length of the next occurrence of the pattern's literal at or after start_offset, without the overhead of snobol_pattern_search_ex() (no match struct, no capture arrays, no output buffer). Returns false for non-literal patterns — the caller must fall back to snobol_pattern_search_ex().

Per-call cost is ~15 ns (vs ~91 ns for snobol_pattern_search_ex with the short-circuit, or ~158 ns for the full tier-dispatch path).

Parameters
[in]stateSearch state created by snobol_pattern_search_state_create().
[in]subjectSubject string.
[in]subject_lenByte length of subject.
[in]start_offsetStart searching from this offset.
[out]out_posMatch start position (absolute in subject).
[out]out_lenMatch length (literal length).
Returns
true if a match was found, false otherwise (including when the pattern is not a single literal).

◆ snobol_pattern_search_reuse()

bool snobol_pattern_search_reuse ( snobol_pattern_t * pattern,
const char * subject,
size_t len,
snobol_match_t * match_out )

Search using a caller-allocated, reusable match object.

Functionally equivalent to snobol_pattern_search() but uses a caller-provided match object instead of allocating one per call. Eliminates per-call malloc/free overhead (~30 ns).

The caller owns the match object and must call snobol_match_reset() or snobol_match_free() when done. The match object is overwritten on each call.

Parameters
[in]patternCompiled pattern to search.
[in]subjectSubject string (UTF-8).
[in]lenByte length of subject.
[in,out]match_outCaller-allocated match object (reusable).
Returns
true if match succeeded, false otherwise. Results are written to *match_out.

◆ snobol_pattern_search_state_create()

snobol_pattern_search_state_t * snobol_pattern_search_state_create ( const uint8_t * bc,
size_t bc_len )

Create a state object for snobol_pattern_search_ex().

Parameters
[in]bcCompiled bytecode buffer. Must outlive the state.
[in]bc_lenByte length of bc.
Returns
Newly allocated state, or NULL on allocation failure. Free with snobol_pattern_search_state_destroy().

◆ snobol_pattern_search_state_destroy()

void snobol_pattern_search_state_destroy ( snobol_pattern_search_state_t * state)

Destroy a search state object. NULL-safe.

Releases the cached VM, output buffer, match result, and the reference to the pattern's bytecode. Does NOT free the pattern itself.

◆ snobol_pattern_search_state_set_eval_fn()

void snobol_pattern_search_state_set_eval_fn ( snobol_pattern_search_state_t * state,
bool(* eval_fn )(int fn_id, const char *s, size_t start, size_t end, void *userdata),
void * eval_udata )

Set the EVAL callback function on a search state's persistent VM.

Once set, the callback persists for the lifetime of the state, avoiding per-call allocation. Pass NULL (the default) to clear.

Parameters
[in]stateSearch state created by snobol_pattern_search_state_create().
[in]eval_fnEVAL callback (NULL to clear).
[in]eval_udataOpaque pointer passed to eval_fn.

◆ snobol_pattern_search_state_set_pattern()

void snobol_pattern_search_state_set_pattern ( snobol_pattern_search_state_t * state,
snobol_pattern_t * pattern )

Associate an owning pattern with a search state.

When set, repeated calls to snobol_pattern_search_ex() on the state reuse the pattern's cached Tier-5 alternation trie instead of rebuilding it each call. The pattern must outlive the state. Optional — callers that build a state directly from bytecode (without a pattern object) need not call this.

Parameters
[in]stateState created by snobol_pattern_search_state_create().
[in]patternOwning pattern (may be NULL to clear the association).

◆ snobol_pattern_search_state_set_tables()

int snobol_pattern_search_state_set_tables ( snobol_pattern_search_state_t * state,
snobol_table_t *const * tables,
size_t n )

Set the tables registered into a search state's persistent VM.

For bytecode-only callers (bindings that compile bytecode without a core pattern object): the tables are retained on the state, and the state's VM registry is rebuilt from them before each search, so OP_TABLE_GET / OP_TABLE_SET ids patched by snobol_pattern_bind_bytecode_tables() resolve. The list order must match the name order passed to the bytecode binding (ids are positions in it).

When no state-level tables are set, a pattern associated via snobol_pattern_search_state_set_pattern() supplies the binding instead; state-level tables take precedence over the pattern's. Replacing or clearing the list (with n equal to 0) takes effect on the next search.

Parameters
[in]stateSearch state created by snobol_pattern_search_state_create().
[in]tablesTables to retain and register (NULL with n == 0 to clear).
[in]nNumber of entries in tables.
Returns
0 on success, -1 on invalid arguments or allocation failure.

◆ snobol_pattern_search_state_set_trie_cache()

void snobol_pattern_search_state_set_trie_cache ( snobol_pattern_search_state_t * state,
snobol_auto_trie_t * trie )

Set a pre-built alt-literals trie on the search state's VM.

The trie is used by the Tier 5 alt-literals dispatch instead of rebuilding it on every search call. The caller owns the trie and must keep it alive until the state is destroyed (the state does not take ownership).

Parameters
[in]stateSearch state created by snobol_pattern_search_state_create().
[in]triePre-built trie, or NULL to clear.

◆ snobol_version()

void snobol_version ( int * major,
int * minor,
int * patch )

Get library version at runtime (three separate integers)

Parameters
majorOutput parameter for major version (can be NULL)
minorOutput parameter for minor version (can be NULL)
patchOutput parameter for patch version (can be NULL)