C API reference

Distribution

syntaqlite's C API is available in two forms:

Both are attached to each GitHub release. See Using syntaqlite from C for compilation instructions.

Parser

Types

// Opaque parser handle.
typedef struct SyntaqliteParser SyntaqliteParser;

// Allocator override. Pass NULL for system malloc/free.
typedef struct SyntaqliteMemMethods {
  void* (*xMalloc)(size_t);
  void* (*xRealloc)(void*, size_t);
  void (*xFree)(void*);
} SyntaqliteMemMethods;

// Source span (byte offset + length).
typedef struct { uint32_t offset; uint32_t length; } SyntaqliteSpan;

// Comment descriptor.
typedef struct {
  SyntaqliteSpan span;
  uint32_t is_block;  // 0 = line comment, 1 = block comment
} SyntaqliteComment;

// Token from the token side-table.
typedef struct {
  uint32_t token_type;
  SyntaqliteSpan span;
} SyntaqliteParserToken;

Functions

Result access

Arena access

Configuration

Tokenizer

Functions

Formatter

Types

// Opaque formatter handle.
typedef struct SyntaqliteFormatter SyntaqliteFormatter;

// Keyword casing options.
typedef enum {
  SYNTAQLITE_KEYWORD_UPPER = 0,
  SYNTAQLITE_KEYWORD_LOWER = 1,
} SyntaqliteKeywordCase;

// Formatter configuration.
typedef struct {
  uint32_t line_width;                // Max line width before breaking (default: 80)
  uint32_t indent_width;              // Spaces per indent level (default: 2)
  SyntaqliteKeywordCase keyword_case; // Keyword casing (default: UPPER)
  uint32_t semicolons;                // Append semicolons (0 = no, nonzero = yes, default: 1)
} SyntaqliteFormatConfig;

Return codes from syntaqlite_formatter_format():

Functions

Validator

Types

// Opaque validator handle.
typedef struct SyntaqliteValidator SyntaqliteValidator;

// Diagnostic severity levels.
typedef enum {
  SYNTAQLITE_SEVERITY_ERROR   = 0,
  SYNTAQLITE_SEVERITY_WARNING = 1,
  SYNTAQLITE_SEVERITY_INFO    = 2,
  SYNTAQLITE_SEVERITY_HINT    = 3,
} SyntaqliteSeverity;

// A single diagnostic from validation.
typedef struct {
  SyntaqliteSeverity severity;
  const char* message;       // NUL-terminated, borrowed
  uint32_t start_offset;     // byte offset in source
  uint32_t end_offset;       // byte offset in source
} SyntaqliteDiagnostic;

// Relation definition for batch catalog registration (tables and views).
typedef struct {
  const char* name;              // NUL-terminated table name
  const char* const* columns;    // NULL = columns unknown (accepts any ref)
  uint32_t column_count;         // ignored when columns is NULL
} SyntaqliteRelationDef;

// Analysis mode.
typedef enum {
  SYNTAQLITE_MODE_DOCUMENT = 0,  // DDL resets between analyze() calls
  SYNTAQLITE_MODE_EXECUTE  = 1,  // DDL accumulates across calls
} SyntaqliteAnalysisMode;

// Relation kind.
typedef enum {
  SYNTAQLITE_RELATION_TABLE = 0,
  SYNTAQLITE_RELATION_VIEW  = 1,
} SyntaqliteRelationKind;

// Origin of a result column (NULL when origin unknown).
typedef struct {
  const char* table;
  const char* column;
} SyntaqliteColumnOrigin;

// Lineage for a single result column.
typedef struct {
  const char* name;               // output column name
  uint32_t index;                 // zero-based position
  SyntaqliteColumnOrigin origin;  // NULL fields when no single-column origin
} SyntaqliteColumnLineage;

// A catalog relation referenced in FROM.
typedef struct {
  const char* name;
  SyntaqliteRelationKind kind;
} SyntaqliteRelationAccess;

// A physical table accessed by the query.
typedef struct {
  const char* name;
} SyntaqliteTableAccess;

Functions

Utility

Analysis modes

Memory model

• Parser, formatter, and validator handles are reusable: create once, call repeatedly.
• Output strings from syntaqlite_formatter_output(), syntaqlite_validator_diagnostics(), and lineage accessors (syntaqlite_validator_column_lineage(), syntaqlite_validator_relations(), syntaqlite_validator_tables()) are borrowed, valid until the next call to analyze or destroy.
• Strings from syntaqlite_validator_render_diagnostics() are borrowed, valid until the next analyze(), render_diagnostics(), or destroy() call.
• Strings from syntaqlite_dump_node() are owned; caller must free().
• Passing NULL to any destroy function is a safe no-op.