state.c File Reference

#include "microlisp_internal.h"
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

Include dependency graph for state.c:

Functions
static void *	default_alloc (size_t size, void *user)
static void	default_free (void *ptr, void *user)
static microlisp_status	validate_allocator (const microlisp_allocator *a)
void	ml_clear_error (ml_state *s)
void	ml_set_error (ml_state *s, size_t line, size_t column, const char *fmt,...)
const char *	microlisp_state_error (const microlisp_state *state)
	Retrieve a human-readable description of the most recent error on state.
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).
static microlisp_status	intern_special_forms (ml_state *s)
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.
void	microlisp_state_destroy (microlisp_state *state)
	Destroy a state, releasing its GC heap and all interned symbols.
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.
void	microlisp_buffer_free (microlisp_state *state, char *bytes)
	Free a buffer previously returned by microlisp_eval via out_bytes .
static int	fputs_or_fail (FILE *out, const char *s)
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.

Function Documentation

default_alloc()

static void * default_alloc ( size_t  size, void *  user  )

static

default_free()

static void default_free ( void *  ptr, void *  user  )

static

fputs_or_fail()

static int fputs_or_fail ( FILE *  out, const char *  s  )

static

intern_special_forms()

static microlisp_status intern_special_forms ( ml_state *  s )

static

microlisp_buffer_free()

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_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_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_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()

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()

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()

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).

ml_clear_error()

void ml_clear_error

(

ml_state *

s

)

ml_set_error()

void ml_set_error	(	ml_state *	s,
		size_t	line,
		size_t	column,
		const char *	fmt,
			...
	)

validate_allocator()

static microlisp_status validate_allocator ( const microlisp_allocator *  a )

static