|
libsnobol4 1.0.2
High-performance SNOBOL4-style pattern matching library
|
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"
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. | |
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.
For hot loops (e.g. searchSplit with 1000+ matches), use:
This eliminates per-call malloc/free overhead (~30 ns per match).
Definition in file snobol.h.
| #define SNOBOL_ABI_VERSION 1 |
| #define SNOBOL_API_MAX_VARS 64 |
| #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.
| typedef struct snobol_batch_result 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.
| 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().
| typedef struct snobol_literal_match 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'").
| typedef struct snobol_match_result 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.
| 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.
| typedef struct snobol_pattern_build snobol_pattern_build_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.
| typedef struct snobol_pattern snobol_pattern_t |
Compiled pattern (opaque handle).
Represents a compiled pattern ready for matching. Created via snobol_pattern_compile().
| 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_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.
| 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).
| [in] | ctx | Context to destroy. |
| 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.
| 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.
| 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.
| [in] | pattern | Pattern source string (UTF-8). |
| [in] | pat_len | Byte length of pattern. |
| [in] | subject | Subject string (UTF-8). |
| [in] | sub_len | Byte length of subject. |
| [in] | flags | Bitmask of SNOBOL_FLAG_* constants (0 for default). |
success and error fields. Free with snobol_match_result_free(). | 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().
| void snobol_match_free | ( | snobol_match_t * | match | ) |
Free a match result.
| [in] | match | Match result to free. NULL is safe. |
| size_t snobol_match_get_length | ( | const snobol_match_t * | match | ) |
Get the length of the match in bytes.
| [in] | match | Match result from snobol_pattern_search() or snobol_pattern_search_ex(). |
| 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.
| [in] | match | Match result from snobol_pattern_match(). |
| [out] | len | If non-NULL, set to the byte length of the returned string. |
match, do not free), or NULL if there is no output. | 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.
| [in] | match | Match result from snobol_pattern_search() or snobol_pattern_search_ex(). |
| 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.
| [in] | match | Match result from snobol_pattern_match(). |
| [in] | name | Variable name (NUL-terminated). |
| [out] | len | If non-NULL, set to the byte length of the returned string. |
match, do not free), or NULL if the variable was not set during the match. | 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.
| [in,out] | match | Match result to reset. NULL is safe (no-op). |
| void snobol_match_result_free | ( | snobol_match_result_t * | result | ) |
Free a snobol_match_result_t and all its owned resources.
| [in] | result | Result to free. NULL is safe. |
| bool snobol_match_success | ( | snobol_match_t * | match | ) |
Return whether a match result represents a successful match.
| [in] | match | Match result from snobol_pattern_match(). |
| 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.
| [in,out] | bc | Mutable bytecode buffer, patched in place. |
| [in] | bc_len | Byte length of bc. |
| [in] | names | Table names to bind (NULL or n == 0 clears all table ops back to unbound). |
| [in] | n | Number of entries in names. |
| 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.
| [in] | pattern | Compiled pattern to bind (NULL returns -1). |
| [in] | names | Table names, parallel to tables. |
| [in] | tables | Tables to retain and register, parallel to names. |
| [in] | n | Number of entries in names / tables. |
| ast_node_t * snobol_pattern_build_abort | ( | snobol_pattern_build_t * | build | ) |
Create an ABORT AST node.
| 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_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_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_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_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_breakx | ( | snobol_pattern_build_t * | build, |
| const char * | set, | ||
| size_t | len ) |
Create a BREAKX AST node.
| 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_cap | ( | snobol_pattern_build_t * | build, |
| int | reg, | ||
| ast_node_t * | sub ) |
Create a CAP AST node (capture sub-pattern into register).
| 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.
| [in] | ctx | Context that will own the returned pattern. |
| [in] | root | Root 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] | flags | Bitmask of SNOBOL_FLAG_* constants (unknown bits are ignored). |
| [out] | error | On failure, *error is set to a malloc'd error string that the caller must free. Set to NULL on success. |
ctx, or NULL on compile error. Free with snobol_pattern_free() before destroying the context. | 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_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_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().
| [in] | build | Builder instance (may be NULL for stateless usage). |
| [in] | root | Root AST node to emit (ownership transferred). |
root (non-NULL if input non-NULL). | ast_node_t * snobol_pattern_build_fail | ( | snobol_pattern_build_t * | build | ) |
Create a FAIL 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_goto | ( | snobol_pattern_build_t * | build, |
| const char * | label ) |
Create a GOTO AST node.
| 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_len | ( | snobol_pattern_build_t * | build, |
| int32_t | n ) |
Create a LEN AST node (match exactly N codepoints).
| 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_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.
| 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_pos | ( | snobol_pattern_build_t * | build, |
| int32_t | n ) |
Create a POS 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_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_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_succeed | ( | snobol_pattern_build_t * | build | ) |
Create a SUCCEED AST node.
| ast_node_t * snobol_pattern_build_tab | ( | snobol_pattern_build_t * | build, |
| int32_t | n ) |
Create a TAB AST node.
| 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.
| [in] | ctx | Context that will own the returned pattern. |
| [in] | source | Pattern source text (UTF-8). |
| [in] | len | Byte length of source. |
| [out] | error | On failure, *error is set to a malloc'd error string that the caller must free. Set to NULL on success. |
ctx, or NULL on parse/compile error. Free with snobol_pattern_free() before destroying the context. | 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.
| ctx | Context that owns the returned pattern. |
| source | Pattern source text (UTF-8). |
| len | Byte length of source. |
| flags | Bitmask of SNOBOL_FLAG_* constants (unknown bits are ignored). |
| error | On failure, *error is set to a malloc'd error string. On success, *error is set to NULL. Caller must free on error. |
| void snobol_pattern_free | ( | snobol_pattern_t * | pattern | ) |
Free a compiled pattern.
| [in] | pattern | Pattern to free. NULL is safe. |
| 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.
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().| [in] | bc | Bytecode buffer (ownership transfers as described). |
| [in] | bc_len | Byte length of bc; must be non-zero. |
| [in] | flags | Bitmask of SNOBOL_FLAG_* constants (unknown bits are ignored, matching snobol_pattern_compile_ex()). |
| [out] | error | On failure, *error is set to a malloc'd message the caller must free; set to NULL on success. May be NULL. |
| const uint8_t * snobol_pattern_get_bc | ( | const snobol_pattern_t * | pattern | ) |
Get the bytecode pointer from a compiled pattern.
| [in] | pattern | Compiled pattern. |
| size_t snobol_pattern_get_bc_len | ( | const snobol_pattern_t * | pattern | ) |
Get the bytecode length from a compiled pattern.
| [in] | pattern | 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.
The metadata is computed once at compile time and reused by the search runtime. Exposed read-only for introspection and testing.
| [in] | pattern | 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.
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.
| [in] | pattern | Compiled pattern (NULL returns NULL/0). |
| [out] | count | Number of entries in the returned array (may be NULL). |
| snobol_match_t * snobol_pattern_match | ( | snobol_pattern_t * | pattern, |
| const char * | subject, | ||
| size_t | len ) |
Execute a compiled pattern against a subject string.
| [in] | pattern | Compiled pattern to execute. |
| [in] | subject | Subject string (UTF-8). |
| [in] | len | Byte length of subject. |
| 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.
| [in] | pattern | Compiled pattern to execute. |
| [in] | subject | Subject string (UTF-8). |
| [in] | len | Byte length of subject. |
| 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).
| [in] | pattern | Compiled pattern to execute. |
| [in] | subject | Subject string (UTF-8). |
| [in] | len | Byte length of subject. |
| 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.
| bc | Compiled bytecode buffer (must outlive the call). |
| bc_len | Bytecode length. |
| subject | Subject string (must outlive the call — captures reference offsets into it). |
| len | Subject byte length. |
| meta | Pre-derived search metadata (from snobol_search_derive_meta or snobol_pattern_get_meta()). |
| out | Output struct (caller-allocated, zero-initialised). |
| 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.
| [in,out] | state | Search state created by snobol_pattern_search_state_create(). |
| [in] | subject | Subject string (UTF-8, must outlive the call). |
| [in] | len | Byte length of subject. |
| [out] | out | Output struct (caller-allocated, zero-initialised). |
| 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).
| [in,out] | state | Search state created by snobol_pattern_search_state_create(). The state's internal match result is overwritten on each call. |
| [in] | subject | Subject string (UTF-8). |
| [in] | subject_len | Byte length of subject. |
| [in] | start_offset | Byte offset to start searching from (0 = beginning). |
state, valid until the next call on the same state or state destruction. The caller must NOT free this pointer. | 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().
| [in,out] | state | Search state created by snobol_pattern_search_state_create(). |
| [in] | subject | Subject string (UTF-8). |
| [in] | subject_len | Byte length of subject. |
state, valid until the next call on the same state or state destruction. The caller must NOT free this pointer. | 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).
| [in] | state | Search state created by snobol_pattern_search_state_create(). |
| [in] | subject | Subject string. |
| [in] | subject_len | Byte length of subject. |
| [in] | start_offset | Start searching from this offset. |
| [out] | out_pos | Match start position (absolute in subject). |
| [out] | out_len | Match length (literal length). |
| 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.
| [in] | pattern | Compiled pattern to search. |
| [in] | subject | Subject string (UTF-8). |
| [in] | len | Byte length of subject. |
| [in,out] | match_out | Caller-allocated match object (reusable). |
| 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().
| [in] | bc | Compiled bytecode buffer. Must outlive the state. |
| [in] | bc_len | Byte length of bc. |
| 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.
| 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.
| [in] | state | Search state created by snobol_pattern_search_state_create(). |
| [in] | eval_fn | EVAL callback (NULL to clear). |
| [in] | eval_udata | Opaque pointer passed to eval_fn. |
| 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.
| [in] | state | State created by snobol_pattern_search_state_create(). |
| [in] | pattern | Owning pattern (may be NULL to clear the association). |
| 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.
| [in] | state | Search state created by snobol_pattern_search_state_create(). |
| [in] | tables | Tables to retain and register (NULL with n == 0 to clear). |
| [in] | n | Number of entries in tables. |
| 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).
| [in] | state | Search state created by snobol_pattern_search_state_create(). |
| [in] | trie | Pre-built trie, or NULL to clear. |
| void snobol_version | ( | int * | major, |
| int * | minor, | ||
| int * | patch ) |
Get library version at runtime (three separate integers)
| major | Output parameter for major version (can be NULL) |
| minor | Output parameter for minor version (can be NULL) |
| patch | Output parameter for patch version (can be NULL) |