microlisp.h File Reference

#include "microlisp/export.h"
#include "microlisp/version.h"
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>

Include dependency graph for microlisp.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	microlisp_allocator
	Caller-supplied allocator. More...
struct	microlisp_options
	Options controlling a state. More...

Macros
#define	MICROLISP_DEFAULT_MAX_READ_DEPTH   256
	Default value for microlisp_options::max_read_depth.
#define	MICROLISP_DEFAULT_MAX_EVAL_DEPTH   1024
	Default value for microlisp_options::max_eval_depth.
#define	MICROLISP_DEFAULT_MAX_PRINT_DEPTH   1024
	Default value for microlisp_options::max_print_depth.
#define	MICROLISP_DEFAULT_MAX_EQUAL_DEPTH   1024
	Default value for microlisp_options::max_equal_depth.

Typedefs
typedef enum microlisp_status	microlisp_status
	Error and status codes returned by every fallible API entry point.
typedef struct microlisp_state	microlisp_state
	Opaque interpreter state.
typedef struct microlisp_allocator	microlisp_allocator
	Caller-supplied allocator.
typedef struct microlisp_options	microlisp_options
	Options controlling a state.

Enumerations
enum	microlisp_status {   MICROLISP_OK = 0 , MICROLISP_ERR_INVALID_ARG = 1 , MICROLISP_ERR_NOMEM = 2 , MICROLISP_ERR_READ_SYNTAX = 3 ,   MICROLISP_ERR_READ_TRUNCATED = 4 , MICROLISP_ERR_READ_DEPTH = 5 , MICROLISP_ERR_UNBOUND = 6 , MICROLISP_ERR_TYPE = 7 ,   MICROLISP_ERR_ARITY = 8 , MICROLISP_ERR_DIV_ZERO = 9 , MICROLISP_ERR_OVERFLOW = 10 , MICROLISP_ERR_USER = 11 ,   MICROLISP_ERR_IO = 12 , MICROLISP_ERR_SYNTAX = 13 , MICROLISP_ERR_EVAL_DEPTH = 14 , MICROLISP_ERR_PRINT_DEPTH = 15 ,   MICROLISP_ERR_EQUAL_DEPTH = 16 }
	Error and status codes returned by every fallible API entry point. More...

Functions
MICROLISP_API MICROLISP_NODISCARD microlisp_status	microlisp_state_create (const microlisp_options *opts, microlisp_state **out_state)
	Create a fresh interpreter state with the built-in primitive bindings loaded in the top-level environment.
MICROLISP_API void	microlisp_state_destroy (microlisp_state *state)
	Destroy a state, releasing its GC heap and all interned symbols.
MICROLISP_API MICROLISP_NODISCARD microlisp_status	microlisp_eval (microlisp_state *state, const char *source, size_t source_len, char **out_bytes, size_t *out_len)
	Evaluate a source buffer of Scheme code as a sequence of top-level forms.
MICROLISP_API MICROLISP_NODISCARD microlisp_status	microlisp_repl (microlisp_state *state, FILE *in_file, FILE *out_file, const char *prompt)
	Run an interactive Read-Eval-Print Loop reading from in_file and writing prompts and results to out_file.
MICROLISP_API void	microlisp_buffer_free (microlisp_state *state, char *bytes)
	Free a buffer previously returned by microlisp_eval via out_bytes .
MICROLISP_API const char *	microlisp_state_error (const microlisp_state *state)
	Retrieve a human-readable description of the most recent error on state.
MICROLISP_API void	microlisp_state_error_position (const microlisp_state *state, size_t *out_line, size_t *out_column)
	Source position of the most recent error, as line and column (both 1-based).
MICROLISP_API const char *	microlisp_version (void)
	Library version (e.g.
MICROLISP_API const char *	microlisp_status_string (microlisp_status status)
	Human-readable name of a status code.

Macro Definition Documentation

MICROLISP_DEFAULT_MAX_EQUAL_DEPTH

#define MICROLISP_DEFAULT_MAX_EQUAL_DEPTH   1024

Default value for microlisp_options::max_equal_depth.

MICROLISP_DEFAULT_MAX_EVAL_DEPTH

#define MICROLISP_DEFAULT_MAX_EVAL_DEPTH   1024

Default value for microlisp_options::max_eval_depth.

MICROLISP_DEFAULT_MAX_PRINT_DEPTH

#define MICROLISP_DEFAULT_MAX_PRINT_DEPTH   1024

Default value for microlisp_options::max_print_depth.

MICROLISP_DEFAULT_MAX_READ_DEPTH

#define MICROLISP_DEFAULT_MAX_READ_DEPTH   256

Default value for microlisp_options::max_read_depth.

Typedef Documentation

microlisp_allocator

typedef struct microlisp_allocator microlisp_allocator

Caller-supplied allocator.

Pass NULL to microlisp_state_create to use the platform malloc / free.

The implementation only calls alloc and free; it does not call realloc, calloc, or memalign.

Thread safety: the caller's alloc / free functions must

themselves be MT-Safe if the microlisp_allocator is shared across threads (i.e. used to construct multiple states that run concurrently).

microlisp_options

typedef struct microlisp_options microlisp_options

Options controlling a state.

Zero-initialize to use defaults; pass NULL to microlisp_state_create for "all defaults."

microlisp_state

typedef struct microlisp_state microlisp_state

Opaque interpreter state.

Construct with microlisp_state_create and destroy with microlisp_state_destroy.

microlisp_status

typedef enum microlisp_status microlisp_status

Error and status codes returned by every fallible API entry point.

Callers that switch on this enum should include a default: arm to handle codes added in future minor releases without breaking.

Enumeration Type Documentation

microlisp_status

enum microlisp_status

Error and status codes returned by every fallible API entry point.

Callers that switch on this enum should include a default: arm to handle codes added in future minor releases without breaking.

Enumerator
MICROLISP_OK	Success.
MICROLISP_ERR_INVALID_ARG	A required argument was NULL or otherwise structurally invalid.
MICROLISP_ERR_NOMEM	Allocator (or platform malloc) returned NULL.
MICROLISP_ERR_READ_SYNTAX	Reader encountered a syntax error – bad token, unmatched paren, malformed string escape, etc.
MICROLISP_ERR_READ_TRUNCATED	Reader reached end-of-input mid-form (e.g. (a b with no closing paren).
MICROLISP_ERR_READ_DEPTH	Reader nesting depth exceeded the configured limit (DoS guard against pathologically deep inputs).
MICROLISP_ERR_UNBOUND	Evaluator looked up a symbol that has no binding in any frame of the active environment.
MICROLISP_ERR_TYPE	Evaluator received a value of the wrong type – e.g. car of a non-pair, or + on a non-number.
MICROLISP_ERR_ARITY	Procedure called with the wrong number of arguments.
MICROLISP_ERR_DIV_ZERO	Division by zero in / , quotient , remainder , or modulo .
MICROLISP_ERR_OVERFLOW	Integer operation would overflow the int64_t range.
MICROLISP_ERR_USER	A Scheme program invoked the error built-in. The argument message is available via microlisp_state_error.
MICROLISP_ERR_IO	An output stream reported a write error during display , write , or newline , or while writing the result.
MICROLISP_ERR_SYNTAX	Malformed special form – e.g. (lambda) with no body or (define) with no name.
MICROLISP_ERR_EVAL_DEPTH	Evaluator recursion depth exceeded the configured limit. Caused by deep non-tail-recursive Scheme code; tail-recursive code runs in constant C-stack space regardless of depth. Limits blast radius from untrusted input.
MICROLISP_ERR_PRINT_DEPTH	Printer recursion depth exceeded the configured limit. Caused by deeply-nested-list output (e.g. an accumulator chain like (nest n acc) -> (nest (- n 1) (list acc)) produces a list of depth N in the car direction). The printer walks pair-car chains recursively; this guard keeps the host C stack bounded. v0.2 will replace the recursive walker with an iterative one and lift the limit.
MICROLISP_ERR_EQUAL_DEPTH	Structural-equality (eqv?, equal?) recursion depth exceeded the configured limit. The v0.1.x comparison walker is recursive on the pair-car axis; this guard prevents a stack overflow when two deeply-nested structures are compared. v0.2 lifts the limit alongside the printer's iterative rewrite.

Function Documentation

microlisp_buffer_free()

MICROLISP_API void microlisp_buffer_free	(	microlisp_state *	state,
		char *	bytes
	)

Free a buffer previously returned by microlisp_eval via out_bytes .

NULL is a no-op.

Lifetime:

The buffer is allocated by state's allocator and must be released before the state is destroyed. Calling microlisp_buffer_free with a state that has already been passed to microlisp_state_destroy is undefined behavior; the allocator's free is no longer reachable through the freed state. The conventional pattern is: eval, consume the result, buffer_free, then destroy the state once you're done with all its outputs.

Parameters

state	The state that produced the buffer; the same allocator must be used to free it.
bytes	Buffer pointer.

microlisp_eval()

MICROLISP_API MICROLISP_NODISCARD microlisp_status microlisp_eval	(	microlisp_state *	state,
		const char *	source,
		size_t	source_len,
		char **	out_bytes,
		size_t *	out_len
	)

Evaluate a source buffer of Scheme code as a sequence of top-level forms.

Each top-level form is read and evaluated in order; the result of the last form is the result of the call. Side effects of earlier forms (defines, set!, displays) persist in state.

Parameters

	state	Interpreter state. Must not be NULL.
	source	Scheme source bytes. May be NULL iff source_len is 0 (in which case the call is a no-op returning MICROLISP_OK with out_bytes set to NULL and out_len set to 0).
	source_len	Length of source in bytes.
[out]	out_bytes	If non-NULL, receives a pointer to a freshly allocated, NUL-terminated string containing the printed result of the last form (in write style: strings quoted, symbols bare). The buffer is allocated with the state's allocator and must be released with microlisp_buffer_free, passing the same state. May be NULL if the caller doesn't need the result text.
[out]	out_len	If non-NULL, receives the length of *out_bytes excluding the trailing NUL. May be NULL.

Returns

MICROLISP_OK on success, or a specific error code.

On any non-OK return, *out_bytes is set to NULL and *out_len to 0; the human-readable error message is retrievable via microlisp_state_error.

Thread safety: MT-Unsafe. The caller must serialize all calls

on the same state.

microlisp_repl()

MICROLISP_API MICROLISP_NODISCARD microlisp_status microlisp_repl	(	microlisp_state *	state,
		FILE *	in_file,
		FILE *	out_file,
		const char *	prompt
	)

Run an interactive Read-Eval-Print Loop reading from in_file and writing prompts and results to out_file.

Errors at any form abort that form's evaluation and print a diagnostic to out_file, then the loop continues with the next prompt. The function returns MICROLISP_OK when in_file reaches end-of-file cleanly, or MICROLISP_ERR_IO if a write to out_file fails.

Parameters

state	Interpreter state. Must not be NULL.
in_file	Input stream. NULL means stdin.
out_file	Output stream for prompts, results, and diagnostics. NULL means stdout.
prompt	Prompt string printed before each input line. NULL means no prompt (suitable for piped input).

Thread safety: MT-Unsafe (per state).

microlisp_state_create()

MICROLISP_API MICROLISP_NODISCARD microlisp_status microlisp_state_create	(	const microlisp_options *	opts,
		microlisp_state **	out_state
	)

Create a fresh interpreter state with the built-in primitive bindings loaded in the top-level environment.

Parameters

	opts	Options. NULL means "all defaults."
[out]	out_state	Receives the new state on success. Set to NULL on error. Caller owns it and must release with microlisp_state_destroy.

Returns

MICROLISP_OK on success, MICROLISP_ERR_NOMEM if any setup allocation failed, MICROLISP_ERR_INVALID_ARG if out_state is NULL or opts has a partial allocator table.

Thread safety: MT-Safe.

microlisp_state_destroy()

MICROLISP_API void microlisp_state_destroy

(

microlisp_state *

state

)

Destroy a state, releasing its GC heap and all interned symbols.

NULL is a no-op.

microlisp_state_error()

MICROLISP_API const char * microlisp_state_error

(

const microlisp_state *

state

)

Retrieve a human-readable description of the most recent error on state.

The pointer remains valid until the next call into microlisp_eval on the same state, or until microlisp_state_destroy.

For MICROLISP_OK the result is the empty string. Never returns NULL.

Thread safety: MT-Unsafe (per state).

microlisp_state_error_position()

MICROLISP_API void microlisp_state_error_position	(	const microlisp_state *	state,
		size_t *	out_line,
		size_t *	out_column
	)

Source position of the most recent error, as line and column (both 1-based).

Reports 0, 0 if the error has no associated position (e.g. MICROLISP_ERR_NOMEM) or if state is NULL.

Thread safety: MT-Unsafe (per state).

microlisp_status_string()

MICROLISP_API const char * microlisp_status_string

(

microlisp_status

status

)

Human-readable name of a status code.

Never NULL, even for unknown codes. Returns short tokens like "MICROLISP_OK", "MICROLISP_ERR_UNBOUND". For a fuller, error-specific message use microlisp_state_error.

microlisp_version()

MICROLISP_API const char * microlisp_version

(

void

)

Library version (e.g.

"0.1.0"). Never NULL.