Janet 1.38.0-73334f3 Documentation
(Other Versions: 1.37.1 1.36.0 1.35.0 1.34.0 1.31.0 1.29.1 1.28.0 1.27.0 1.26.0 1.25.1 1.24.0 1.23.0 1.22.0 1.21.0 1.20.0 1.19.0 1.18.1 1.17.1 1.16.1 1.15.0 1.13.1 1.12.2 1.11.1 1.10.1 1.9.1 1.8.1 1.7.0 1.6.0 1.5.1 1.5.0 1.4.0 1.3.1 )

Wrapping Types

The Janet C API Embedding

Janet has several built-in fundamental data types. These data types are the bread and butter of the Janet C API, and most functions and macros in the API expect at least some of their arguments to be of these types. However, as Janet is a dynamically typed language, Janet internally uses a boxed representation of these types, simply called Janet.

Functions that are specific to a particular type expect the unboxed or unwrapped type, while operations that are generic to Janet values will typically expect a Janet. It is important to be able to convert between these two representations in order to interact with Janet from C.

Wrapping Functions

These functions convert a C type into a generic Janet value. 

Janet janet_wrap_nil(void);
Janet janet_wrap_number(double x);
Janet janet_wrap_true(void);
Janet janet_wrap_false(void);
Janet janet_wrap_boolean(int x);
Janet janet_wrap_string(const uint8_t *x);
Janet janet_wrap_symbol(const uint8_t *x);
Janet janet_wrap_keyword(const uint8_t *x);
Janet janet_wrap_array(JanetArray *x);
Janet janet_wrap_tuple(const Janet *x);
Janet janet_wrap_struct(const JanetKV *x);
Janet janet_wrap_fiber(JanetFiber *x);
Janet janet_wrap_buffer(JanetBuffer *x);
Janet janet_wrap_function(JanetFunction *x);
Janet janet_wrap_cfunction(JanetCFunction x);
Janet janet_wrap_table(JanetTable *x);
Janet janet_wrap_abstract(void *x);
Janet janet_wrap_pointer(void *x);
Janet janet_wrap_integer(int32_t x);

Unwrapping Functions

These function convert from a Janet to a more specific C type. If the Janet being unwrapped is not actually the returned type, the behavior is undefined. 

const JanetKV *janet_unwrap_struct(Janet x);
const Janet *janet_unwrap_tuple(Janet x);
JanetFiber *janet_unwrap_fiber(Janet x);
JanetArray *janet_unwrap_array(Janet x);
JanetTable *janet_unwrap_table(Janet x);
JanetBuffer *janet_unwrap_buffer(Janet x);
const uint8_t *janet_unwrap_string(Janet x);
const uint8_t *janet_unwrap_symbol(Janet x);
const uint8_t *janet_unwrap_keyword(Janet x);
void *janet_unwrap_abstract(Janet x);
void *janet_unwrap_pointer(Janet x);
JanetFunction *janet_unwrap_function(Janet x);
JanetCFunction janet_unwrap_cfunction(Janet x);
int janet_unwrap_boolean(Janet x);
double janet_unwrap_number(Janet x);
int32_t janet_unwrap_integer(Janet x);

Janet Types

Before unwrapping a Janet value, one should check the value is of the correct Janet type. Janet provides two macros for checking this, janet_checktype and janet_checktypes. These macros may be more efficient than the more obvious way of checking types via janet_type(x) == JANET_ARRAY, and so are preferred.

The enum JanetType represents the base type of a Janet value. There are are exactly 16 basic types. 

typedef enum JanetType {
    JANET_NUMBER,
    JANET_NIL,
    JANET_BOOLEAN,
    JANET_FIBER,
    JANET_STRING,
    JANET_SYMBOL,
    JANET_KEYWORD,
    JANET_ARRAY,
    JANET_TUPLE,
    JANET_TABLE,
    JANET_STRUCT,
    JANET_BUFFER,
    JANET_FUNCTION,
    JANET_CFUNCTION,
    JANET_ABSTRACT,
    JANET_POINTER
} JanetType;
/* macro */
int janet_checktype(Janet x, JanetType type);

Checks the type x, and returns a non zero value if x is the correct type, and 0 otherwise. Usually, you will want to use this function before unwrapping a value. 

/* macro */
int janet_checktypes(Janet x, int typeflags);

Similar to janet_checktype, but allows the programmer to check multiple types at once, in an efficient manner. typeflags should be a bit set of all of the types to check membership for. For example, to check if x is one of nil or a number, you would call 

janet_checktypes(x, (1 << JANET_NIL) | (1 << JANET_NUMBER))

There are also several aliases so you don't need to do the shift yourself. 

#define JANET_TFLAG_NIL (1 << JANET_NIL)
#define JANET_TFLAG_BOOLEAN (1 << JANET_BOOLEAN)
#define JANET_TFLAG_FIBER (1 << JANET_FIBER)
#define JANET_TFLAG_NUMBER (1 << JANET_NUMBER)
#define JANET_TFLAG_STRING (1 << JANET_STRING)
#define JANET_TFLAG_SYMBOL (1 << JANET_SYMBOL)
#define JANET_TFLAG_KEYWORD (1 << JANET_KEYWORD)
#define JANET_TFLAG_ARRAY (1 << JANET_ARRAY)
#define JANET_TFLAG_TUPLE (1 << JANET_TUPLE)
#define JANET_TFLAG_TABLE (1 << JANET_TABLE)
#define JANET_TFLAG_STRUCT (1 << JANET_STRUCT)
#define JANET_TFLAG_BUFFER (1 << JANET_BUFFER)
#define JANET_TFLAG_FUNCTION (1 << JANET_FUNCTION)
#define JANET_TFLAG_CFUNCTION (1 << JANET_CFUNCTION)
#define JANET_TFLAG_ABSTRACT (1 << JANET_ABSTRACT)
#define JANET_TFLAG_POINTER (1 << JANET_POINTER)

/* Some abstractions */
#define JANET_TFLAG_BYTES (JANET_TFLAG_STRING | JANET_TFLAG_SYMBOL | JANET_TFLAG_BUFFER | JANET_TFLAG_KEYWORD)
#define JANET_TFLAG_INDEXED (JANET_TFLAG_ARRAY | JANET_TFLAG_TUPLE)
#define JANET_TFLAG_DICTIONARY (JANET_TFLAG_TABLE | JANET_TFLAG_STRUCT)
#define JANET_TFLAG_LENGTHABLE (JANET_TFLAG_BYTES | JANET_TFLAG_INDEXED | JANET_TFLAG_DICTIONARY)
#define JANET_TFLAG_CALLABLE (JANET_TFLAG_FUNCTION | JANET_TFLAG_CFUNCTION | \
        JANET_TFLAG_LENGTHABLE | JANET_TFLAG_ABSTRACT)

The resulting call would look like: 

janet_checktypes(x, JANET_TFLAG_NIL | JANET_TFLAG_NUMBER)
JANET_API JanetType janet_type(Janet x);

Returns the type of Janet value.

Strings

Janet provides several utilities for dealing with C-style, NULL terminated strings. It can be tempting to use the janet_wrap_* functions for passing C-style strings as Janet strings, keywords, and symbols, but this is incorrect and will cause segfaults and other problems.

Instead, use janet_cstring to convert any NULL terminated string to a Janet string. This may allocated memory and do an extra copy, but will always result in a string that can be safely used by Janet. There are similar utilities for creating symbols and keywords.

Some of these interfaces are defined as macros, but this may change in future versions. From janet.h, the following 6 functions and macros are commonly used for converting string-like types. 


/* Wrapping C-Style strings */

/* Convert const char * ---->>>> JanetString, JanetKeyword, JanetSymbol */
JANET_API JanetString janet_cstring(const char *cstring);
JANET_API JanetSymbol janet_csymbol(const char *str);
#define janet_ckeyword janet_csymbol

/* Convert const char * ---->>>> Janet */
#define janet_cstringv(cstr) janet_wrap_string(janet_cstring(cstr))
#define janet_csymbolv(cstr) janet_wrap_symbol(janet_csymbol(cstr))
#define janet_ckeywordv(cstr) janet_wrap_keyword(janet_ckeyword(cstr))
The Janet C API Embedding