Janet 1.27.0-01aab66 Documentation
(Other Versions:
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
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.