Janet 1.0.0-dev Documentation
Janet can be embedded in a host program, usually written in C or C++, in
several ways. The easiest way is to use the Janet's amalgamated build, which
is a single giant C source file that can be copied into the host program's source
tree. This method has many upsides, including simplicity and stability. You can
also link to
libjanet.so to include Janet as shared object.
In the context of embedding Janet in a program, we can call the larger program a client which usually uses the Janet library to run Janet source code. Most Janet clients have a number of things in common, especially some boilerplate required to get Janet code running.
Basic Janet Functions
JANET_API int janet_init(void);
Use this function to initialize global Janet state. This must be called once per thread if using Janet in a multithreaded environment, as all Janet global state is thread local by default.
JANET_API void janet_deinit(void);
Call this function to free all memory and resources managed by Janet.
JanetTable *janet_core_env(JanetTable *replacements);
Use this function to get the core environment for the Janet language. Replacements is an optional table that can be used to override some of the default bindings in the core environment. Usually, set to NULL.
int janet_dobytes(JanetTable *env, const uint8_t *bytes, int32_t len, const char *sourcePath, Janet *out);
Use this function to compile and run some Janet source code from C. If you plan on running the code multiple times, there are more efficient options. However, for code that will only run once, this is a useful function.
int janet_dostring(JanetTable *env, const char *str, const char *sourcePath, Janet *out);
janet_dobytes, runs a null-terminated C string of Janet soruce code.
JanetSignal janet_continue(JanetFiber *fiber, Janet in, Janet *out);
Resumes a new or suspended fiber. Returns a signal that corresponds to the status
of the fiber after execution, and places the return/signal value in out. When
resuming a fiber, the value to resume with should be in the argument in, which
corresponds to the second argument to the Janet
JanetSignal janet_pcall(JanetFunction *fun, int32_t argc, const Janet *argv, Janet *out, JanetFiber **f);
Invoke a function in a protected manner, catching any panics raised. Returns the resulting status
code, as well as placing the return value in
*out. The fiber pointer f is a pointer
to a fiber pointer will contain the fiber used to run the function fun. If f is NULL, a new
fiber will be created. Otherwise, Janet will use the fiber pointed to by f to run fun.
If no panics are raised, will return
JANET_SIGNAL_OK. If an error is raised, will return
JANET_SIGNAL_ERROR. Other signals will be returned as expected.
Janet janet_call(JanetFunction *fun, int32_t argc, const Janet *argv);
Make a simple, re-entrant call back into the Janet interpreter from C. Try to put mostly simple, short running logic here as this suspends the garbage collector for the duration of the call. Functions called this way also must either return or error. Other signals will be coerced into an error.
void janet_stacktrace(JanetFiber *fiber, Janet err);
Print a janet stacktrace for the given fiber to stderr, or whatever is bound
:err dynamic binding on the current fiber. You also must supply the
return value or error message raised, as that is not tracked by the fiber itself.