cheax
Lisp dialect with C API
|
API functions to interface with cheax from C/C++. More...
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_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. 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) |
API functions to interface with cheax from C/C++.
#define CHX_PURE |
#define CHX_CONST |
#define CHX_FORMAT | ( | like, | |
first, | |||
args | |||
) |
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().
anonymous enum |
Options for symbol declaration and value matching.
Enumerator | |
---|---|
CHEAX_SYNCED | Reserved.
|
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. |
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.
list | List to convert. |
array_ptr | Output parameter, will point to array of cheax_value pointers. Make sure to cheax_free() after use. |
length | Output parameter, will point to length of output array. |
Converts array to chx_list.
Throws CHEAX_EAPI if array is NULL
.
array | Array of chx_value. |
length | Length of array. |
void cheax_push_env | ( | CHEAX * | c | ) |
Pushes new empty environment to environment stack.
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.
main | Main branch of bifurcated environment. |
void cheax_pop_env | ( | CHEAX * | c | ) |
Pops environment off environment stack.
Sets cheax_errno() to CHEAX_EAPI if environment stack is empty.
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
NULL
, or get and set are both NULL
; or id | Identifier for new symbol. |
get | Getter for symbol. |
set | Setter for symbol. |
fin | Finalizer for symbol. |
user_info | User data to be passed to getter, setter and finalizer. |
NULL
if unsuccessful.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.
id | Variable identifier. |
value | Initial value or the symbol. May be NULL . |
flags | Variable flags. Use 0 if there are no special needs. |
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.
id | Identifier to look up. |
NULL
in case of an error.Attempts to get the value of a given symbol.
Like cheax_get(), but does not throw CHEAX_ENOSYM if no symbol was found.
id | Identifier to look up. |
out | Output value. Not written to if no symbol was found. |
true
if symbol was found, false
otherwise.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.
env | Environment to look up identifier in. |
id | Identifier to look up. |
NULL
in case of an error.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.
env | Environment to look up identifier in. |
id | Identifier to look up. |
out | Output value. Not written to if no symbol was found. |
true
if symbol was found, false
otherwise.Sets the value of a symbol.
Sets cheax_errno() to
NULL
; cheax_set() cannot be used to declare a new symbol, use cheax_def() instead.
id | Identifier of the symbol to look up and set. |
value | New value for the symbol with the given identifier. |
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:
id | Identifier for the external functions. |
perform | Callback for the new external functions. |
info | Callback info for the new external functions. |
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.
name | Identifier for the symbol in the cheax environment. |
var | Reference to the C variable to synchronize. |
flags | Symbol flags. Use 0 if there are no special needs. |
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.
name | Identifier for the symbol in the cheax environment. |
var | Reference to the C variable to synchronize. |
flags | Symbol flags. Use 0 if there are no special needs. |
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.
name | Identifier for the symbol in the cheax environment. |
var | Reference to the C variable to synchronize. |
flags | Symbol flags. Use 0 if there are no special needs. |
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.
name | Identifier for the symbol in the cheax environment. |
var | Reference to the C variable to synchronize. |
flags | Symbol flags. Use 0 if there are no special needs. |
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.
name | Identifier for the symbol in the cheax environment. |
var | String buffer to synchronize. |
size | Capacity of buffer, including null byte. |
flags | Symbol flags. Use 0 if there are no special needs. |
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.
env | Environment to evaluate nodes in. |
pan | Pattern to match against. |
match | Expression to match against pan. |
flags | Variable flags for newly defined matched symbols. Use 0 if there are no special needs, although you should probably use CHEAX_READONLY. |
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.
pan | Pattern to match against. |
match | Expression to match against pan. |
flags | Variable flags for newly defined matched symbols. Use 0 if there are no special needs, although you should probably use CHEAX_READONLY. |
Tests whether two given cheax expressions are equal.
l | Left. |
r | Right. |
Attempts to cast an expression to a given type.
Sets cheax_errno() to CHEAX_ETYPE if casting is not possible.
v | Expression to cast. |
type | Code of the type to cast to. |
NULL
if unsuccessful. Reads value from file.
Core element of the read, eval, print loop.
Throws
NULL
; f | File handle to read from. |
nil
and no error will be thrown. Check feof(f)
to test for this condition.Reads value from file and reports back line and column information.
Like cheax_read(), but with additional parameters used for error reporting and diagnostics.
f | File handle to read from. |
path | Path of input file. Used for error reporting and debug info generation. |
line | Pointer to current line number. Will be updated as newlines are read. Will be ignored if NULL . |
pos | Pointer to current column number. Will be updated as input is read. Will be ignored if NULL . |
Reads value from string.
Like cheax_read(), but reading directly from a string, rather than from a file.
Throws
NULL
; str | Null-terminated string to read from. |
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.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
.
str | Pointer 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. |
line | Pointer to current line number. Will be updated as newlines are read. Will be ignored if NULL . |
pos | Pointer to current column number. Will be updated as input is read. Will be ignored if NULL . |
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.
expr | Expression in which to expand macro forms. |
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.
expr | Expression to expand. |
Evaluates given cheax expression.
Core element of the read, eval, print loop.
expr | Cheax expression to evaluate. |
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.
func | Function to invoke. |
list | Argument list to pass to func. |
Prints given value to file.
Core element of the read, eval, print loop.
output | Output file handle. |
expr | Value to print. |
Expresses given cheax values as a chx_string, using given format string.
Sets cheax_errno() to
fmt | Python-esque format string. |
args | List of arguments to format into the output string. |
void cheax_exec | ( | CHEAX * | c, |
const char * | f | ||
) |
Reads a file and executes it.
f | Input file path. |
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 | ) |