cheax
Lisp dialect with C API
The cheax C API

API functions to interface with cheax from C/C++. More...

Collaboration diagram for The cheax C API:

Modules

 Type system
 Functions and datastructures to create, examine and manipulate cheax expressions and their types.
 
 Error handling
 Error codes and ways to deal with them.
 
 Setup and configuration
 Functions and datastructures to initialize, clean up and configure a cheax virtual machine instance.
 

Files

file  cheax.h
 The header for the cheax C API.
 

Macros

#define CHX_PURE
 
#define CHX_CONST
 
#define CHX_FORMAT(like, first, args)
 

Typedefs

typedef struct cheax CHEAX
 The type of the cheax virtual machine state, a pointer to wich is needed for most cheax API functions. More...
 

Enumerations

enum  { CHEAX_SYNCED = 0x01 , CHEAX_READONLY = 0x02 , CHEAX_WRITEONLY = 0x04 , CHEAX_EVAL_NODES = 0x08 }
 Options for symbol declaration and value matching. More...
 

Functions

int cheax_list_to_array (CHEAX *c, struct chx_list *list, struct chx_value **array_ptr, size_t *length)
 Converts chx_list to array. More...
 
struct chx_value cheax_array_to_list (CHEAX *c, struct chx_value *array, size_t length)
 Converts array to chx_list. More...
 
void cheax_push_env (CHEAX *c)
 Pushes new empty environment to environment stack. More...
 
void cheax_enter_env (CHEAX *c, struct chx_env *main)
 Pushes new bifurcated environment to environment stack. More...
 
void cheax_pop_env (CHEAX *c)
 Pops environment off environment stack. More...
 
struct chx_symcheax_defsym (CHEAX *c, const char *id, chx_getter get, chx_setter set, chx_finalizer fin, void *user_info)
 Define symbol with custom getter and setter. More...
 
void cheax_def (CHEAX *c, const char *id, struct chx_value value, int flags)
 Creates a new symbol in the cheax environment. More...
 
struct chx_value cheax_get (CHEAX *c, const char *id)
 Obtains the value of the given symbol. More...
 
bool cheax_try_get (CHEAX *c, const char *id, struct chx_value *out)
 
struct chx_value cheax_get_from (CHEAX *c, struct chx_env *env, const char *id)
 Retrieves the value of the given symbol, performing symbol lookup only in the specified environment. More...
 
bool cheax_try_get_from (CHEAX *c, struct chx_env *env, const char *id, struct chx_value *out)
 
void cheax_set (CHEAX *c, const char *id, struct chx_value value)
 Sets the value of a symbol. More...
 
void cheax_defun (CHEAX *c, const char *id, chx_func_ptr perform, void *info)
 Shorthand function to declare an external function the cheax environment. More...
 
void cheax_defsyntax (CHEAX *c, const char *id, chx_tail_func_ptr perform, chx_func_ptr preproc, void *info)
 
void cheax_sync_int (CHEAX *c, const char *name, int *var, int flags)
 Synchronizes a variable from C with a symbol in the cheax environment. More...
 
void cheax_sync_bool (CHEAX *c, const char *name, bool *var, int flags)
 Synchronizes a variable from C with a symbol in the cheax environment. More...
 
void cheax_sync_float (CHEAX *c, const char *name, float *var, int flags)
 Synchronizes a variable from C with a symbol in the cheax environment. More...
 
void cheax_sync_double (CHEAX *c, const char *name, double *var, int flags)
 Synchronizes a variable from C with a symbol in the cheax environment. More...
 
void cheax_sync_nstring (CHEAX *c, const char *name, char *buf, size_t size, int flags)
 Synchronizes a null-terminated string buffer from C with a symbol in the cheax environment. More...
 
bool cheax_match_in (CHEAX *c, struct chx_env *env, struct chx_value pan, struct chx_value match, int flags)
 Matches a cheax expression to a given pattern. More...
 
bool cheax_match (CHEAX *c, struct chx_value pan, struct chx_value match, int flags)
 Matches a cheax expression to a given pattern. More...
 
bool cheax_eq (CHEAX *c, struct chx_value l, struct chx_value r)
 Tests whether two given cheax expressions are equal. More...
 
bool cheax_equiv (struct chx_value l, struct chx_value r)
 
struct chx_value cheax_cast (CHEAX *c, struct chx_value v, int type)
 Attempts to cast an expression to a given type. More...
 
struct chx_value cheax_read (CHEAX *c, FILE *f)
 Reads value from file. More...
 
struct chx_value cheax_read_at (CHEAX *c, FILE *f, const char *path, int *line, int *pos)
 Reads value from file and reports back line and column information. More...
 
struct chx_value cheax_readstr (CHEAX *c, const char *str)
 Reads value from string. More...
 
struct chx_value cheax_readstr_at (CHEAX *c, const char **str, const char *path, int *line, int *pos)
 Reads value from string, updates the string to reference the byte where it left off reading, and reports back line and column information. More...
 
struct chx_value cheax_macroexpand (CHEAX *c, struct chx_value expr)
 Expand given expression until it is no longer a macro form. More...
 
struct chx_value cheax_macroexpand_once (CHEAX *c, struct chx_value expr)
 Expand expression if it is a macro form. More...
 
struct chx_value cheax_preproc (CHEAX *c, struct chx_value expr)
 
struct chx_value cheax_eval (CHEAX *c, struct chx_value expr)
 Evaluates given cheax expression. More...
 
struct chx_value cheax_apply (CHEAX *c, struct chx_value func, struct chx_list *list)
 Invokes function with given argument list. More...
 
void cheax_print (CHEAX *c, FILE *output, struct chx_value expr)
 Prints given value to file. More...
 
struct chx_value cheax_format (CHEAX *c, struct chx_string *fmt, struct chx_list *args)
 Expresses given cheax values as a chx_string, using given format string. More...
 
void cheax_exec (CHEAX *c, const char *f)
 Reads a file and executes it. More...
 
void * cheax_malloc (CHEAX *c, size_t size)
 
void * cheax_calloc (CHEAX *c, size_t nmemb, size_t size)
 
void * cheax_realloc (CHEAX *c, void *ptr, size_t size)
 
void cheax_free (CHEAX *c, void *ptr)
 
void cheax_gc (CHEAX *c)
 

Detailed Description

API functions to interface with cheax from C/C++.

Macro Definition Documentation

◆ CHX_PURE

#define CHX_PURE

◆ CHX_CONST

#define CHX_CONST

◆ CHX_FORMAT

#define CHX_FORMAT (   like,
  first,
  args 
)

Typedef Documentation

◆ CHEAX

typedef struct cheax CHEAX

The type of the cheax virtual machine state, a pointer to wich is needed for most cheax API functions.

The virtual machine is initialized with cheax_init(), and destroyed with cheax_destroy().

See also
cheax_init(), cheax_destroy(), cheax_load_features(), cheax_load_prelude()

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Options for symbol declaration and value matching.

See also
cheax_def(), cheax_match(), cheax_sync_int(), cheax_sync_bool(), cheax_sync_float(), cheax_sync_double()
Enumerator
CHEAX_SYNCED 

Reserved.

Note
Unused.
CHEAX_READONLY 

Marks a symbol read-only.

CHEAX_WRITEONLY 

Marks a symbol write-only.

CHEAX_EVAL_NODES 

For cheax_match() and cheax_match_in(): evaluate list nodes before matching them.

Function Documentation

◆ cheax_list_to_array()

int cheax_list_to_array ( CHEAX c,
struct chx_list list,
struct chx_value **  array_ptr,
size_t *  length 
)

Converts chx_list to array.

Sets cheax_errno() to CHEAX_EAPI if array_ptr or length is NULL, or to CHEAX_ENOMEM if array allocation failed.

Parameters
listList to convert.
array_ptrOutput parameter, will point to array of cheax_value pointers. Make sure to cheax_free() after use.
lengthOutput parameter, will point to length of output array.
Returns
0 if everything succeeded without errors, -1 if there was an error (most likely CHEAX_ENOMEM).
See also
cheax_array_to_list()

◆ cheax_array_to_list()

struct chx_value cheax_array_to_list ( CHEAX c,
struct chx_value array,
size_t  length 
)

Converts array to chx_list.

Throws CHEAX_EAPI if array is NULL.

Parameters
arrayArray of chx_value.
lengthLength of array.
See also
cheax_list_to_array()

◆ cheax_push_env()

void cheax_push_env ( CHEAX c)

Pushes new empty environment to environment stack.

◆ cheax_enter_env()

void cheax_enter_env ( CHEAX c,
struct chx_env *  main 
)

Pushes new bifurcated environment to environment stack.

Lookups will first look in main, then look further down the stack. New symbols are declared only in main.

Parameters
mainMain branch of bifurcated environment.

◆ cheax_pop_env()

void cheax_pop_env ( CHEAX c)

Pops environment off environment stack.

Sets cheax_errno() to CHEAX_EAPI if environment stack is empty.

◆ cheax_defsym()

struct chx_sym* cheax_defsym ( CHEAX c,
const char *  id,
chx_getter  get,
chx_setter  set,
chx_finalizer  fin,
void *  user_info 
)

Define symbol with custom getter and setter.

Throws

  • CHEAX_EAPI if id is NULL, or get and set are both NULL; or
  • CHEAX_EEXIST if a symbol with name id already exists.
Parameters
idIdentifier for new symbol.
getGetter for symbol.
setSetter for symbol.
finFinalizer for symbol.
user_infoUser data to be passed to getter, setter and finalizer.
Returns
The newly created symbol, or NULL if unsuccessful.
See also
chx_sym, cheax_def()

◆ cheax_def()

void cheax_def ( CHEAX c,
const char *  id,
struct chx_value  value,
int  flags 
)

Creates a new symbol in the cheax environment.

Sets cheax_errno() to CHEAX_EAPI if id is NULL, or to CHEAX_EEXIST if a symbol with name id already exists.

Parameters
idVariable identifier.
valueInitial value or the symbol. May be NULL.
flagsVariable flags. Use 0 if there are no special needs.
See also
cheax_get(), cheax_set()

◆ cheax_get()

struct chx_value cheax_get ( CHEAX c,
const char *  id 
)

Obtains the value of the given symbol.

Sets cheax_errno() to CHEAX_EAPI if id is NULL, or to CHEAX_ENOSYM if no symbol with name id could be found.

Note
This function may call cheax_gc(). Make sure to cheax_ref() your values properly.
Parameters
idIdentifier to look up.
Returns
The value of the given symbol. Always NULL in case of an error.
See also
cheax_get_from(), cheax_set()

◆ cheax_try_get()

bool cheax_try_get ( CHEAX c,
const char *  id,
struct chx_value out 
)

Attempts to get the value of a given symbol.

Like cheax_get(), but does not throw CHEAX_ENOSYM if no symbol was found.

Note
This function may call cheax_gc(). Make sure to cheax_ref() your values properly.
Parameters
idIdentifier to look up.
outOutput value. Not written to if no symbol was found.
Returns
true if symbol was found, false otherwise.
See also
cheax_get()

◆ cheax_get_from()

struct chx_value cheax_get_from ( CHEAX c,
struct chx_env *  env,
const char *  id 
)

Retrieves the value of the given symbol, performing symbol lookup only in the specified environment.

Sets cheax_errno() to CHEAX_EAPI if id is NULL, or to CHEAX_ENOSYM if no symbol with name id could be found.

Note
This function may call cheax_gc(). Make sure to cheax_ref() your values properly.
Parameters
envEnvironment to look up identifier in.
idIdentifier to look up.
Returns
The value of the given symbol. Always NULL in case of an error.
See also
cheax_get(), cheax_try_get_from()

◆ cheax_try_get_from()

bool cheax_try_get_from ( CHEAX c,
struct chx_env *  env,
const char *  id,
struct chx_value out 
)

Attempts to get the value of a given symbol, performing symbol lookup only in the specified environment.

Like cheax_get_from(), but does not throw CHEAX_ENOSYM if no symbol was found.

Note
This function may call cheax_gc(). Make sure to cheax_ref() your values properly.
Parameters
envEnvironment to look up identifier in.
idIdentifier to look up.
outOutput value. Not written to if no symbol was found.
Returns
true if symbol was found, false otherwise.
See also
cheax_get_from()

◆ cheax_set()

void cheax_set ( CHEAX c,
const char *  id,
struct chx_value  value 
)

Sets the value of a symbol.

Sets cheax_errno() to

cheax_set() cannot be used to declare a new symbol, use cheax_def() instead.

Note
This function may call cheax_gc(). Make sure to cheax_ref() your values properly.
Parameters
idIdentifier of the symbol to look up and set.
valueNew value for the symbol with the given identifier.
See also
cheax_get(), cheax_def()

◆ cheax_defun()

void cheax_defun ( CHEAX c,
const char *  id,
chx_func_ptr  perform,
void *  info 
)

Shorthand function to declare an external function the cheax environment.

Shorthand for:

cheax_def(c, id, &cheax_ext_func(c, id, perform, info)->base, CHEAX_READONLY);
void cheax_def(CHEAX *c, const char *id, struct chx_value value, int flags)
Creates a new symbol in the cheax environment.
@ CHEAX_READONLY
Definition: cheax.h:953
struct chx_value cheax_ext_func(CHEAX *c, const char *name, chx_func_ptr perform, void *info)
Creates a cheax external/user function expression.
Parameters
idIdentifier for the external functions.
performCallback for the new external functions.
infoCallback info for the new external functions.
See also
chx_ext_func, cheax_ext_func(), cheax_def(), cheax_defsyntax()

◆ cheax_defsyntax()

void cheax_defsyntax ( CHEAX c,
const char *  id,
chx_tail_func_ptr  perform,
chx_func_ptr  preproc,
void *  info 
)

◆ cheax_sync_int()

void cheax_sync_int ( CHEAX c,
const char *  name,
int *  var,
int  flags 
)

Synchronizes a variable from C with a symbol in the cheax environment.

Parameters
nameIdentifier for the symbol in the cheax environment.
varReference to the C variable to synchronize.
flagsSymbol flags. Use 0 if there are no special needs.

◆ cheax_sync_bool()

void cheax_sync_bool ( CHEAX c,
const char *  name,
bool *  var,
int  flags 
)

Synchronizes a variable from C with a symbol in the cheax environment.

Parameters
nameIdentifier for the symbol in the cheax environment.
varReference to the C variable to synchronize.
flagsSymbol flags. Use 0 if there are no special needs.

◆ cheax_sync_float()

void cheax_sync_float ( CHEAX c,
const char *  name,
float *  var,
int  flags 
)

Synchronizes a variable from C with a symbol in the cheax environment.

Parameters
nameIdentifier for the symbol in the cheax environment.
varReference to the C variable to synchronize.
flagsSymbol flags. Use 0 if there are no special needs.

◆ cheax_sync_double()

void cheax_sync_double ( CHEAX c,
const char *  name,
double *  var,
int  flags 
)

Synchronizes a variable from C with a symbol in the cheax environment.

Parameters
nameIdentifier for the symbol in the cheax environment.
varReference to the C variable to synchronize.
flagsSymbol flags. Use 0 if there are no special needs.

◆ cheax_sync_nstring()

void cheax_sync_nstring ( CHEAX c,
const char *  name,
char *  buf,
size_t  size,
int  flags 
)

Synchronizes a null-terminated string buffer from C with a symbol in the cheax environment.

Parameters
nameIdentifier for the symbol in the cheax environment.
varString buffer to synchronize.
sizeCapacity of buffer, including null byte.
flagsSymbol flags. Use 0 if there are no special needs.

◆ cheax_match_in()

bool cheax_match_in ( CHEAX c,
struct chx_env *  env,
struct chx_value  pan,
struct chx_value  match,
int  flags 
)

Matches a cheax expression to a given pattern.

May declare some symbols in currently active environment, regardless of return value, and does not set cheax_errno() to CHEAX_EMATCH if the expression did not match the pattern. If flags contains CHEAX_EVAL_NODES, evaluation of node values occurs in environment env.

Parameters
envEnvironment to evaluate nodes in.
panPattern to match against.
matchExpression to match against pan.
flagsVariable flags for newly defined matched symbols. Use 0 if there are no special needs, although you should probably use CHEAX_READONLY.
Returns
Whether match matched the pattern pan.

◆ cheax_match()

bool cheax_match ( CHEAX c,
struct chx_value  pan,
struct chx_value  match,
int  flags 
)

Matches a cheax expression to a given pattern.

May declare some symbols in currently active environment, regardless of return value, and does not set cheax_errno() to CHEAX_EMATCH if the expression did not match the pattern.

Parameters
panPattern to match against.
matchExpression to match against pan.
flagsVariable flags for newly defined matched symbols. Use 0 if there are no special needs, although you should probably use CHEAX_READONLY.
Returns
Whether match matched the pattern pan.

◆ cheax_eq()

bool cheax_eq ( CHEAX c,
struct chx_value  l,
struct chx_value  r 
)

Tests whether two given cheax expressions are equal.

Parameters
lLeft.
rRight.
Returns
Whether the given cheax expressions are equal in value.

◆ cheax_equiv()

bool cheax_equiv ( struct chx_value  l,
struct chx_value  r 
)

◆ cheax_cast()

struct chx_value cheax_cast ( CHEAX c,
struct chx_value  v,
int  type 
)

Attempts to cast an expression to a given type.

Sets cheax_errno() to CHEAX_ETYPE if casting is not possible.

Parameters
vExpression to cast.
typeCode of the type to cast to.
Returns
The cast expression. Always NULL if unsuccessful.

◆ cheax_read()

struct chx_value cheax_read ( CHEAX c,
FILE *  f 
)

Reads value from file.

Core element of the read, eval, print loop.

Throws

Parameters
fFile handle to read from.
Returns
The value that was read from the file. If no value was read and end-of-file was reached, the function will return nil and no error will be thrown. Check feof(f) to test for this condition.
See also
cheax_read_at(), cheax_readstr(), cheax_eval(), cheax_print()

◆ cheax_read_at()

struct chx_value cheax_read_at ( CHEAX c,
FILE *  f,
const char *  path,
int *  line,
int *  pos 
)

Reads value from file and reports back line and column information.

Like cheax_read(), but with additional parameters used for error reporting and diagnostics.

Parameters
fFile handle to read from.
pathPath of input file. Used for error reporting and debug info generation.
linePointer to current line number. Will be updated as newlines are read. Will be ignored if NULL.
posPointer to current column number. Will be updated as input is read. Will be ignored if NULL.
See also
cheax_read(), cheax_readstr_at()

◆ cheax_readstr()

struct chx_value cheax_readstr ( CHEAX c,
const char *  str 
)

Reads value from string.

Like cheax_read(), but reading directly from a string, rather than from a file.

Throws

Parameters
strNull-terminated string to read from.
Returns
The value that was read from the string. If no value was read and the null terminator was reached, the function will return nil and no error will be thrown. Unlike with cheax_read() and cheax_readstr_at(), the API does not distinguishes this condition from a successful reading of the value nil from the string.
See also
cheax_read_at(), cheax_readstr(), cheax_eval(), cheax_print()

◆ cheax_readstr_at()

struct chx_value cheax_readstr_at ( CHEAX c,
const char **  str,
const char *  path,
int *  line,
int *  pos 
)

Reads value from string, updates the string to reference the byte where it left off reading, and reports back line and column information.

Like cheax_readstr(), but with additional parameters used for error reporting and diagnostics. Additionally, the string pointer is updated, allowing one to call the function multiple times in succession to read multiple values.

Throws CHEAX_EREAD and CHEAX_EEOF as would cheax_readstr(), and throws CHEAX_EAPI if str points to, or is itself, NULL.

Parameters
strPointer to string to read from. Will, if no errors were thrown, point to the first byte in the string not examined by the parser.
path"Path" of input string. Used for error reporting and debug info generation.
linePointer to current line number. Will be updated as newlines are read. Will be ignored if NULL.
posPointer to current column number. Will be updated as input is read. Will be ignored if NULL.
See also
cheax_readstr(), cheax_read_at()

◆ cheax_macroexpand()

struct chx_value cheax_macroexpand ( CHEAX c,
struct chx_value  expr 
)

Expand given expression until it is no longer a macro form.

Macros are defined using the (defmacro) built-in. Throws CHEAX_ESTATIC in case of an internal error.

Note
This function may call cheax_gc(). Make sure to cheax_ref() your values properly.
Parameters
exprExpression in which to expand macro forms.
See also
cheax_macroexpand_once()

◆ cheax_macroexpand_once()

struct chx_value cheax_macroexpand_once ( CHEAX c,
struct chx_value  expr 
)

Expand expression if it is a macro form.

Macros are defined using the (defmacro) built-in. Throws CHEAX_ESTATIC in case of an internal error.

Note
This function may call cheax_gc(). Make sure to cheax_ref() your values properly.
Parameters
exprExpression to expand.
See also
cheax_macroexpand()

◆ cheax_preproc()

struct chx_value cheax_preproc ( CHEAX c,
struct chx_value  expr 
)

◆ cheax_eval()

struct chx_value cheax_eval ( CHEAX c,
struct chx_value  expr 
)

Evaluates given cheax expression.

Core element of the read, eval, print loop.

Note
This function may call cheax_gc(). Make sure to cheax_ref() your values properly.
Parameters
exprCheax expression to evaluate.
Returns
The evaluated expression.
See also
cheax_read(), cheax_print()

◆ cheax_apply()

struct chx_value cheax_apply ( CHEAX c,
struct chx_value  func,
struct chx_list list 
)

Invokes function with given argument list.

Argument list will be passed to the function as-is. I.e. the individual list nodes will not be evaluated.

Throws CHEAX_ETYPE is func is not CHEAX_FUNC or CHEAX_EXT_FUNC.

Parameters
funcFunction to invoke.
listArgument list to pass to func.
Returns
Function return value.

◆ cheax_print()

void cheax_print ( CHEAX c,
FILE *  output,
struct chx_value  expr 
)

Prints given value to file.

Core element of the read, eval, print loop.

Parameters
outputOutput file handle.
exprValue to print.
See also
cheax_format(), cheax_read(), cheax_eval()

◆ cheax_format()

struct chx_value cheax_format ( CHEAX c,
struct chx_string *  fmt,
struct chx_list args 
)

Expresses given cheax values as a chx_string, using given format string.

Sets cheax_errno() to

  • CHEAX_EAPI if fmt is NULL;
  • CHEAX_EVALUE if format string is otherwise invalid; or
  • CHEAX_EINDEX if an index occurs in the format string (either implicitly or explicitly) that is out of bounds for args.
Parameters
fmtPython-esque format string.
argsList of arguments to format into the output string.
Returns
A chx_string representing the formatted result, or NULL if an error occurred.
See also
cheax_print()

◆ cheax_exec()

void cheax_exec ( CHEAX c,
const char *  f 
)

Reads a file and executes it.

Parameters
fInput file path.

◆ cheax_malloc()

void* cheax_malloc ( CHEAX c,
size_t  size 
)

◆ cheax_calloc()

void* cheax_calloc ( CHEAX c,
size_t  nmemb,
size_t  size 
)

◆ cheax_realloc()

void* cheax_realloc ( CHEAX c,
void *  ptr,
size_t  size 
)

◆ cheax_free()

void cheax_free ( CHEAX c,
void *  ptr 
)

◆ cheax_gc()

void cheax_gc ( CHEAX c)