libsnobol4 1.0.2
High-performance SNOBOL4-style pattern matching library
Loading...
Searching...
No Matches
snobol.h
Go to the documentation of this file.
1#pragma once
2
3#include "snobol/c23_compat.h"
4
5#ifdef __cplusplus
6extern "C" {
7#endif
8
9
30
31#include <stdbool.h>
32#include <stddef.h>
33#include <stdint.h>
34
35/* -----------------------------------------------------------------------
36 * Version macros
37 *
38 * SNOBOL_VERSION_* and SNOBOL_VERSION_STRING are generated by CMake into
39 * `snobol/version.h` from the single source of truth in the top-level
40 * `project(libsnobol4 VERSION X.Y.Z)` declaration. They are NOT hard-coded
41 * here; to bump the version, edit CMakeLists.txt and reconfigure.
42 * ----------------------------------------------------------------------- */
43#include "snobol/version.h"
44
49#define SNOBOL_ABI_VERSION 1
50
51/* -----------------------------------------------------------------------
52 * Deprecation macros
53 *
54 * Use SNOBOL_DEPRECATED to mark public API functions that are deprecated
55 * but kept for one minor version cycle before removal. Deprecated
56 * functions produce a compiler warning.
57 *
58 * SNOBOL_DEPRECATED void snobol_old_func(void);
59 * ----------------------------------------------------------------------- */
60#if defined(__GNUC__) || defined(__clang__)
61#define SNOBOL_DEPRECATED __attribute__((deprecated))
62#elif defined(_MSC_VER)
63#define SNOBOL_DEPRECATED __declspec(deprecated)
64#else
65#define SNOBOL_DEPRECATED
66#endif
67
74void snobol_version(int *major, int *minor, int *patch);
75
88
101
102/* Include common headers */
103#include "snobol/array.h"
104#include "snobol/ast.h"
105#include "snobol/compiler.h"
107#include "snobol/lexer.h"
108#include "snobol/parser.h"
109#include "snobol/search.h"
110#include "snobol/string_fn.h"
111#include "snobol/table.h"
112#include "snobol/type_fn.h"
113#include "snobol/vm.h"
114
121typedef struct snobol_context snobol_context_t;
122
129typedef struct snobol_pattern snobol_pattern_t;
130
134#define SNOBOL_API_MAX_VARS 64
135
169
201bool snobol_pattern_search_batch(const uint8_t *bc, size_t bc_len,
202 const char *subject, size_t len,
203 const snobol_search_meta_t *meta,
205
213
221typedef struct snobol_match {
223
224 /* Output buffer (from OP_EMIT_* instructions) */
225 char *output;
227
228 /* Named capture variables.
229 *
230 * Captures are stored register-style as (offset, length) pairs relative to
231 * `var_subject` (var_off[i], var_len[i]). The NUL-terminated byte copy in
232 * var_values[i] is materialized lazily on the first snobol_match_get_variable
233 * call and cached there; a NULL var_values[i] with var_len[i] > 0 means the
234 * capture is present but not yet copied. This avoids a per-match malloc +
235 * memcpy for every variable when the caller only reads a subset (or none).
236 *
237 * Variable names are decimal strings "1", "2", …, "64".
238 * Index 0 corresponds to variable name "1" (1-based). */
239 const char *var_subject;
245
246 /* Match position within the subject. */
247 size_t position;
248 size_t length;
250
256typedef struct snobol_table snobol_table_t;
257
258typedef struct snobol_array snobol_array_t;
259
260/* Context lifecycle */
270
280
281/* -----------------------------------------------------------------------
282 * Pattern compilation flags
283 * ----------------------------------------------------------------------- */
284
292#define SNOBOL_FLAG_CASE_INSENSITIVE 0x0001u
293
294/* Pattern compilation */
309 const char *source, size_t len,
310 char **error);
311
325 const char *source, size_t len,
326 uint32_t flags, char **error);
327
352 uint32_t flags, char **error);
353
359const uint8_t *snobol_pattern_get_bc(const snobol_pattern_t *pattern);
360
367
378 const snobol_pattern_t *pattern);
379
393 const snobol_pattern_t *pattern, size_t *count);
394
401
402/* Pattern table binding */
427int snobol_pattern_bind_tables(snobol_pattern_t *pattern, const char **names,
428 snobol_table_t *const *tables, size_t n);
429
450int snobol_pattern_bind_bytecode_tables(uint8_t *bc, size_t bc_len,
451 const char **names, size_t n);
452
453/* Pattern matching */
465 const char *subject, size_t len);
466
478
496 const char *subject,
497 size_t len);
498
515 const char *subject, size_t len);
516
530typedef struct snobol_pattern_search_state snobol_pattern_search_state_t;
531
541 const uint8_t *bc, size_t bc_len);
542
556
570
584 bool (*eval_fn)(int fn_id, const char *s, size_t start, size_t end,
585 void *userdata),
586 void *eval_udata);
587
610 snobol_table_t *const *tables,
611 size_t n);
612
621
644 const char *subject,
645 size_t subject_len,
646 size_t start_offset);
647
664 snobol_pattern_search_state_t *state, const char *subject,
665 size_t subject_len);
666
690 const char *subject, size_t subject_len,
691 size_t start_offset, size_t *out_pos,
692 size_t *out_len);
693
717 const char *subject, size_t len,
719
732
741
748
759
770
789bool snobol_pattern_search_reuse(snobol_pattern_t *pattern, const char *subject,
790 size_t len, snobol_match_t *match_out);
791
792/* Match result access */
800
812const char *snobol_match_get_output(snobol_match_t *match, size_t *len);
813
823const char *snobol_match_get_variable(snobol_match_t *match, const char *name,
824 size_t *len);
825
826/* -----------------------------------------------------------------------
827 * One-shot convenience match API
828 *
829 * snobol_match() bundles lex→parse→compile→VM execution into a single
830 * call, freeing all intermediate resources internally. Use this for
831 * simple one-off matches; for repeated matching of the same pattern use
832 * snobol_pattern_compile() + snobol_pattern_match() instead.
833 * ----------------------------------------------------------------------- */
834
856
872snobol_match_result_t *snobol_match(const char *pattern, size_t pat_len,
873 const char *subject, size_t sub_len,
874 uint32_t flags);
875
881
882/* -----------------------------------------------------------------------
883 * Builder API — programmatic AST construction
884 *
885 * Each snobol_pattern_build_*() function creates a single AST node of the
886 * corresponding type. Compound functions (concat, alt, cap, etc.) accept
887 * child AST nodes and take ownership of them. Use snobol_pattern_build_emit()
888 * to finalize the root node, then snobol_pattern_build_compile() to turn it
889 * into a ready-to-use pattern.
890 *
891 * Example (create → build → emit → compile → match):
892 * snobol_context_t *ctx = snobol_context_create();
893 * snobol_pattern_build_t *b = snobol_pattern_build_create();
894 * ast_node_t *lit = snobol_pattern_build_lit(b, "hello", 5);
895 * ast_node_t *root = snobol_pattern_build_emit(b, lit);
896 * char *err = NULL;
897 * snobol_pattern_t *pat = snobol_pattern_build_compile(ctx, root, 0, &err);
898 * // root is consumed by compile; b can be destroyed or reused.
899 * snobol_pattern_build_destroy(b);
900 * // pat is a fully initialized pattern: match, search, free.
901 * snobol_match_t *m = snobol_pattern_search(pat, "hello world", 11);
902 * snobol_pattern_free(pat);
903 * snobol_context_destroy(ctx);
904 * ----------------------------------------------------------------------- */
905
909typedef struct snobol_pattern_build snobol_pattern_build_t;
910
913
916
917/* --- Primitive nodes ---------------------------------------------------- */
918
921 const char *text, size_t len);
922
925 const char *set, size_t len);
926
929 const char *set, size_t len);
930
933 const char *set, size_t len);
934
937 const char *set, size_t len);
938
941
944 ast_node_t *sub);
945
946/* --- Capture / assignment ---------------------------------------------- */
947
950 ast_node_t *sub);
951
957 ast_node_t *sub);
958
961 int reg);
962
963/* --- Compound nodes ---------------------------------------------------- */
964
968 ast_node_t **parts, size_t count);
969
972 ast_node_t *left, ast_node_t *right);
973
974/* --- Control flow ------------------------------------------------------ */
975
978 const char *name, ast_node_t *target);
979
982 const char *label);
983
984/* --- Position primitives ----------------------------------------------- */
985
988
991
994
997
1000 const char *set, size_t len);
1001
1004 uint32_t open_cp, uint32_t close_cp);
1005
1008
1011
1014
1017
1020
1033 ast_node_t *root);
1034
1057 ast_node_t *root, uint32_t flags,
1058 char **error);
1059
1060#ifdef __cplusplus
1061}
1062#endif
Runtime-owned sparse array objects for SNOBOL4.
struct snobol_array snobol_array_t
Sparse array state.
Abstract Syntax Tree representation for SNOBOL patterns.
struct ast_node ast_node_t
Definition ast.h:129
Compiler for SNOBOL pattern AST to bytecode.
Dynamic pattern objects and canonical cache keys.
struct snobol_table snobol_table_t
Associative table (opaque handle).
Lexer for SNOBOL pattern syntax.
Recursive descent parser for SNOBOL pattern syntax.
Core search runtime API for libsnobol4.
struct snobol_auto_trie_t snobol_auto_trie_t
Opaque pre-allocated trie used by the Tier-5 alternation matcher.
Definition search.h:164
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_abort(snobol_pattern_build_t *build)
Create an ABORT AST node.
uint32_t snobol_get_api_version(void)
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_fail(snobol_pattern_build_t *build)
Create a FAIL AST node.
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_build_destroy(snobol_pattern_build_t *build)
Destroy a builder. Does NOT free emitted AST nodes.
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_rpos(snobol_pattern_build_t *build, int32_t n)
Create a RPOS AST node.
snobol_match_t * snobol_pattern_match(snobol_pattern_t *pattern, const char *subject, size_t len)
Execute a compiled pattern against a subject string.
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.
snobol_pattern_t * snobol_pattern_compile_ex(snobol_context_t *ctx, const char *source, size_t len, uint32_t flags, char **error)
void snobol_match_free(snobol_match_t *match)
Free a match result.
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/...
snobol_pattern_build_t * snobol_pattern_build_create(void)
Create a new builder.
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_assign(snobol_pattern_build_t *build, int var, int reg)
Create an ASSIGN AST node (assign register to 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.
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).
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.
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).
void snobol_match_reset(snobol_match_t *match)
Reset a match result for reuse without freeing.
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.
ast_node_t * snobol_pattern_build_fence(snobol_pattern_build_t *build)
Create a FENCE AST node.
#define SNOBOL_API_MAX_VARS
Maximum named variables returned from a match.
Definition snobol.h:134
void snobol_batch_result_free(snobol_batch_result_t *out)
Free all arrays owned by a batch result struct. NULL-safe.
struct snobol_match snobol_match_t
Match result object.
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_alt(snobol_pattern_build_t *build, ast_node_t *left, ast_node_t *right)
Create an ALT AST node (alternation).
struct snobol_pattern_build snobol_pattern_build_t
Opaque builder state.
Definition snobol.h:909
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.
void snobol_context_destroy(snobol_context_t *ctx)
Destroy a pattern matching context and free all associated resources.
void snobol_pattern_free(snobol_pattern_t *pattern)
Free a compiled 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.
void snobol_version(int *major, int *minor, int *patch)
struct snobol_context snobol_context_t
Pattern matching context (opaque handle).
Definition snobol.h:121
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_lit(snobol_pattern_build_t *build, const char *text, size_t len)
Create a LITERAL AST node.
ast_node_t * snobol_pattern_build_rem(snobol_pattern_build_t *build)
Create a REM AST node.
struct snobol_pattern_search_state snobol_pattern_search_state_t
Opaque state for snobol_pattern_search_ex().
Definition snobol.h:530
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_emit(snobol_pattern_build_t *build, ast_node_t *root)
Finalize and emit an AST tree built with the builder.
const char * snobol_match_get_output(snobol_match_t *match, size_t *len)
Retrieve the output buffer produced by a successful match.
snobol_match_t * snobol_match_create(void)
Create a new match result object.
struct snobol_literal_match snobol_literal_match_t
Lightweight result from snobol_pattern_match_literal().
void snobol_pattern_search_state_destroy(snobol_pattern_search_state_t *state)
Destroy a search state object. NULL-safe.
struct snobol_pattern snobol_pattern_t
Compiled pattern (opaque handle).
Definition snobol.h:129
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.
const uint8_t * snobol_pattern_get_bc(const snobol_pattern_t *pattern)
Get the bytecode pointer from a compiled pattern.
struct snobol_batch_result snobol_batch_result_t
Result from snobol_pattern_search_batch().
ast_node_t * snobol_pattern_build_succeed(snobol_pattern_build_t *build)
Create a SUCCEED 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.
uint32_t snobol_get_abi_version(void)
const snobol_search_meta_t * snobol_pattern_get_meta(const snobol_pattern_t *pattern)
Get the pre-derived search metadata for a compiled pattern.
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.
size_t snobol_match_get_length(const snobol_match_t *match)
Get the length of the match in bytes.
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.
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.
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_cap(snobol_pattern_build_t *build, int reg, ast_node_t *sub)
Create a CAP AST node (capture sub-pattern into register).
struct snobol_match_result snobol_match_result_t
Result from the one-shot snobol_match() convenience API.
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().
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_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.
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.
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_brk(snobol_pattern_build_t *build, const char *set, size_t len)
Create a BREAK AST node (consume until char in set).
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_search_state_set_trie_cache(snobol_pattern_search_state_t *state, snobol_auto_trie_t *trie)
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.
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_name(snobol_pattern_build_t *build, int reg, ast_node_t *sub)
Create a match-naming node: bind sub-pattern's match to register.
snobol_context_t * snobol_context_create(void)
Create a new pattern matching context.
size_t snobol_match_get_position(const snobol_match_t *match)
Get the absolute offset where the match started within the subject.
void snobol_match_result_free(snobol_match_result_t *result)
Free a snobol_match_result_t and all its owned resources.
bool snobol_match_success(snobol_match_t *match)
Return whether a match result represents a successful match.
ast_node_t * snobol_pattern_build_len(snobol_pattern_build_t *build, int32_t n)
Create a LEN AST node (match exactly N codepoints).
size_t snobol_pattern_get_bc_len(const snobol_pattern_t *pattern)
Get the bytecode length from a compiled pattern.
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.
SNOBOL4 built-in string transformation functions.
Sparse array state.
Definition array.h:46
Result from snobol_pattern_search_batch().
Definition snobol.h:156
size_t * lengths
Definition snobol.h:159
size_t * output_lens
Definition snobol.h:165
size_t * positions
Definition snobol.h:158
size_t ** captures
Definition snobol.h:161
Lightweight result from snobol_pattern_match_literal().
Definition snobol.h:473
Result from the one-shot snobol_match() convenience API.
Definition snobol.h:841
size_t * capture_lens
Definition snobol.h:853
Match result object.
Definition snobol.h:221
size_t position
Definition snobol.h:247
size_t var_lens[SNOBOL_API_MAX_VARS]
Definition snobol.h:243
size_t var_off[SNOBOL_API_MAX_VARS]
Definition snobol.h:240
bool success
Definition snobol.h:222
size_t length
Definition snobol.h:248
char * var_values[SNOBOL_API_MAX_VARS]
Definition snobol.h:242
char * output
Definition snobol.h:225
size_t var_len[SNOBOL_API_MAX_VARS]
Definition snobol.h:241
const char * var_subject
Definition snobol.h:239
int var_count
Definition snobol.h:244
size_t output_len
Definition snobol.h:226
Cached range metadata for a single charclass set.
Definition vm.h:60
Runtime-owned associative table objects for SNOBOL4.
SNOBOL4 built-in comparison and type-checking functions.
Virtual machine types, opcodes, and execution API for libsnobol4.