microlisp.h

Go to the documentation of this file.

/*
 * SPDX-License-Identifier: MIT
 * Copyright (c) 2026 microlisp contributors
 *
 * Public API for microlisp: a small Scheme-subset interpreter.
 *
 * The language is a strict R5RS-flavored Scheme subset:
 *
 *     Types       int64, boolean (#t/#f), symbol, string, pair, '(),
 *                 procedure (closure or built-in primitive)
 *     Forms       quote, if, define, lambda, set!, let, let*, letrec,
 *                 begin, and, or, cond
 *     Built-ins   arithmetic (+ - * / quotient remainder modulo)
 *                 comparison (= < > <= >=)
 *                 list ops   (cons car cdr list pair? null? length)
 *                 predicates (eq? eqv? equal? number? symbol?
 *                             string? procedure? boolean?)
 *                 I/O        (display newline write error)
 *
 * Out of scope for v0.1: floats, chars, vectors, macros, continuations,
 * exceptions (callers handle errors as status codes).
 *
 * The implementation uses tagged pointers (low-3-bit tag on uintptr_t)
 * for the value representation and a mark-and-sweep garbage collector
 * for heap-allocated objects. Proper tail-call optimization is provided
 * by a trampolined evaluator -- tail-recursive Scheme programs run in
 * O(1) C-stack space.
 *
 * @par Thread safety:
 *      Each ::microlisp_state owns its own GC heap, symbol table, and
 *      global environment. A given state is **MT-Unsafe**: all calls on
 *      the same state must be serialized by the caller. Different
 *      states may be used concurrently from different threads (every
 *      function is MT-Safe-per-instance).
 *
 * @par Memory:
 *      Allocation goes through an optional ::microlisp_allocator; pass
 *      NULL to use platform @c malloc / @c free. The allocator is used
 *      for both bookkeeping and GC-managed heap objects.
 *
 * @par Embedding model:
 *      The v0.1 API is intentionally minimal: callers supply Scheme
 *      source as a byte buffer, get back a printed result and a status
 *      code. A value-level C API (build values from C, call Scheme
 *      procedures with C-constructed arguments) is deferred to a
 *      future minor release once the internal representation is
 *      stable.
 */
#ifndef MICROLISP_MICROLISP_H
#define MICROLISP_MICROLISP_H
 
#include "microlisp/export.h"
#include "microlisp/version.h"
 
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* -- Types ------------------------------------------------------------------ */
 
typedef 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
} microlisp_status;
 
typedef struct microlisp_state microlisp_state;
 
typedef struct microlisp_allocator {
    void *(*alloc)(size_t size, void *user);
    void (*free)(void *ptr, void *user);
    void *user;
} microlisp_allocator;
 
#define MICROLISP_DEFAULT_MAX_READ_DEPTH 256
 
#define MICROLISP_DEFAULT_MAX_EVAL_DEPTH 1024
 
#define MICROLISP_DEFAULT_MAX_PRINT_DEPTH 1024
 
#define MICROLISP_DEFAULT_MAX_EQUAL_DEPTH 1024
 
typedef struct microlisp_options {
    const microlisp_allocator *allocator;
 
    size_t max_read_depth;
 
    size_t max_eval_depth;
 
    size_t max_print_depth;
 
    size_t max_equal_depth;
 
    size_t gc_initial_threshold;
} microlisp_options;
 
/* -- State lifecycle -------------------------------------------------------- */
 
MICROLISP_API MICROLISP_NODISCARD microlisp_status
microlisp_state_create(const microlisp_options *opts, microlisp_state **out_state);
 
MICROLISP_API void microlisp_state_destroy(microlisp_state *state);
 
/* -- Evaluation ------------------------------------------------------------- */
 
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);
 
MICROLISP_API MICROLISP_NODISCARD microlisp_status microlisp_repl(microlisp_state *state,
                                                                  FILE *in_file, FILE *out_file,
                                                                  const char *prompt);
 
MICROLISP_API void microlisp_buffer_free(microlisp_state *state, char *bytes);
 
/* -- Diagnostics ------------------------------------------------------------ */
 
MICROLISP_API const char *microlisp_state_error(const microlisp_state *state);
 
MICROLISP_API void microlisp_state_error_position(const microlisp_state *state, size_t *out_line,
                                                  size_t *out_column);
 
/* -- Misc ------------------------------------------------------------------- */
 
MICROLISP_API const char *microlisp_version(void);
 
MICROLISP_API const char *microlisp_status_string(microlisp_status status);
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
#endif /* MICROLISP_MICROLISP_H */