NAME

libstu provides the core routines for working with the stu interpreter.

SYNOPSIS

Include the following header accordingly:

#include <libstu/stu.h>

And the relevant build flags, which may be obtained via pkg-config; e.g.

$ pkg-config --cflags --libs libstu

DESCRIPTION

The interpreter Stu object encapsulates all interpreter state information; more than one instance may be used in the same program.

All returned StuVal objects are automatically exempt from garbage collection. Once a StuVal object is no longer required, it must be explicitly released via Stu_release_val.

STRUCTURES

The libstu routines all operate on the following structures.

StuVal

The main structure encapsulating the atomic lisp object. The contents of this structure are intentionally opaque.

StuEnv

The structure which tracks the head of the environment binding list.

Stu

The main stu interpreter structure.

NIL

The singleton NIL object. This object is initialized in the first call to Stu_new; any subsequent calls will make use of the same instance.

FUNCTIONS

The following functions comprise the public libstu interface.

Stu *Stu_new(void)

Create and initialize an interpreter instance.

void Stu_destroy(Stu **stu)

Destroy an interpreter instance created with Stu_new.

StuVal *Stu_eval_file(Stu *stu, const char *file)

Eval a NUL-terminated file path and return the result as a StuVal. The returned StuVal object is exempt from garbage collection, thus when the result is no longer required it must be released via a call to the Stu_release_val function.

StuVal *Stu_eval_buf(Stu *stu, const char *buf)

Same as Stu_eval_file, but parse the NUL-terminated buffer instead.

StuVal *Stu_eval_buf_in_env(Stu *stu, const char *buf, StuEnv *base, StuEnv **updated)

Same as Stu_eval_buf, but pass in an explicit environment base and return the updated environment head in updated.

void Stu_update_main_env(Stu *stu, StuEnv *env)

Update the interpreter's main environment HEAD pointer.

StuEnv *Stu_main_env(Stu *stu)

Fetch the interpreter's current main environment HEAD pointer.

int Stu_is_valid_form(Stu *stu, const char *buf)

Scan the supplied buf and report on it's validity by returning:

• 1 if the form contained in buf is syntactically valid

• 0 if the form is invalid

• -1 if the form is valid so far, but incomplete

void Stu_release_val(Stu *stu, StuVal *val)

Release the specified val back to the mercy of the garbage collector, to be cleaned up at some unspecified time in the future.

void Stu_dump_val(Stu *stu, StuVal *val, FILE *out)

Dump the string representation of val to out in the context of the stu interpreter instance.

void Stu_add_include_path(Stu *stu, const char *path)

Append an include path to the interpreter's list of search locations for imported module files.

void Stu_dump_stats(Stu *stu, FILE *out)

Dump assorted interpreter stats to out.

AUTHOR

stu is written by Mikey Austin, Dmitry Petrov and Raphael Santos.

SEE ALSO

stu - cli

COPYRIGHT AND LICENSE

See the COPYING file in the distribution for the details.