libabacus/include/libabacus.h

301 lines
10 KiB
C

#ifndef LIBABACUS_H
#define LIBABACUS_H
#include "custom.h"
#include "ht.h"
#include "impl.h"
#include "interpreter.h"
#include "lexer.h"
#include "parser.h"
#include "result.h"
#include "table.h"
#include "gc.h"
/**
* The main struct of libabacus,
* which essentially holds all the informatiom
* for the library's state and operation.
*/
struct libab_s {
/**
* The lexer used to convert a string
* to tokens.
*/
libab_lexer lexer;
/**
* The parser used to convert
* tokens to a tree.
*/
libab_parser parser;
/**
* The interpreter used
* to run a tree.
*/
libab_interpreter intr;
/**
* The table used to store top-level
* things like functions and operators.
*/
libab_ref table;
/**
* The allocator used to construct number instances.
*/
libab_impl impl;
/**
* The number type instance.
*/
libab_ref type_num;
/**
* The boolean type instance.
*/
libab_ref type_bool;
/**
* The function list type instance.
*/
libab_ref type_function_list;
/**
* The unit type instance.
*/
libab_ref type_unit;
/**
* List of containers references
* that should be tracked by the
* garbage collector for cycles.
*/
libab_gc_list containers;
/**
* Internal; the number basetype. This cannot be a static
* variable like other built-in types because it has a free function
* specified by the user.
*/
libab_basetype basetype_num;
};
typedef struct libab_s libab;
/**
* Initializes the libabacus struct as well
* as all its internal structures such as the lexer.
* @param ab the libabacus instance used to keep state.
* @param parse_function function used to parse a number.
* @param free_function function used to free the parsed number.
* @return the result of the initialization.
*/
libab_result libab_init(libab* ab, void* (*parse_function)(const char*),
void (*free_function)(void*));
/**
* Registers an operator with libabacus.
* @param ab the libabacus instance to reigster the operator with.
* @param op the operator string to register.
* @param precedence the precedence of the operator.
* @param associativity the associativity of the operator.
* @param function the function this operator calls.
* @return the result of the initialization.
*/
libab_result libab_register_operator_infix(libab* ab, const char* op,
int precedence, int associativity,
const char* function);
/**
* Registers an operation with libabacus that appears
* before its operand.
* @param ab the libabacus instance to register the operator with.
* @param op the operator string to register.
* @param function the function this operator calls.
* @return the result of the registration.
*/
libab_result libab_register_operator_prefix(libab* ab, const char* op,
const char* function);
/**
* Registers an operation with libabacus that appears
* after its operand.
* @param ab the libabacus instance to register the operator with.
* @param op the operator string to register.
* @param function the function this operator calls.
* @return the result of the registration.
*/
libab_result libab_register_operator_postfix(libab* ab, const char* op,
const char* function);
/**
* Registers a function with libabacus.
* @param ab the libabacus instance used to keep state.
* @param name the name of the function.
* @param type the type of this operator.
* @param func the function that describes the functionality of the function.
* @return the result of the registration.
*/
libab_result libab_register_function(libab* ab, const char* name,
libab_ref* type, libab_function_ptr func);
/**
* Registers a base type with abacus.
* @param ab the libabacus instance used to keep state.
* @param name the name to register the basetype under.
* @param basetype the basetype to register.
* @return the result of the registration.
*/
libab_result libab_register_basetype(libab* ab, const char* name,
libab_basetype* basetype);
/**
* Constructs and resolves a parse type, similarly to how it's done in the
* parser.
* @param ab the libab instance to use for constructing the type.
* @param into the reference to populate with the given type.
* @param type the type to parse.
* @return the result of the operation.
*/
libab_result libab_create_type(libab* ab, libab_ref* into, const char* type);
/**
* Finds and returns the built-in libabacus number type.
* @param ab the ab instance for which to return a type.
* @return the num basetype.
*/
libab_basetype* libab_get_basetype_num(libab* ab);
/**
* Finds and returns the built-in libabacus boolean type.
* @param ab the ab instance for which to return a type.
* @return the boolean basetype.
*/
libab_basetype* libab_get_basetype_bool(libab* ab);
/**
* Finds and returns the built-in libabacus function type.
* @param ab the ab instance for which to return a type.
* @return the function basetype.
*/
libab_basetype* libab_get_basetype_function(libab* ab);
/**
* Finds and returns the built-in libabacus function list type.
* @param ab the ab instance for which to return a type.
* @return the function list basetype.
*/
libab_basetype* libab_get_basetype_function_list(libab* ab);
/**
* Finds and returns the built-in libabacus unit type.
* @param ab the ab instance for which to return a type.
* @return the unit basetype.
*/
libab_basetype* libab_get_basetype_unit(libab* ab);
/**
* Get the type of a number in this libabacus instance.
* @param ab the instance to get the type for.
* @param into the reference to store the type into.
*/
void libab_get_type_num(libab* ab, libab_ref* into);
/**
* Get the type of a boolean in this libabacus instance.
* @param ab the instance to get the type for.
* @param into the reference to store the type into.
*/
void libab_get_type_bool(libab* ab, libab_ref* into);
/**
* Get the type of the function list in this libabacus instance.
* @param ab the instance to get the type for.
* @param into the ference to store the type into.
*/
void libab_get_type_function_list(libab* ab, libab_ref* into);
/**
* Get the type of the unit in this libabacus instance.
* @param ab the instance to get the type for.
* @param into the reference to store the type into.
*/
void libab_get_type_unit(libab* ab, libab_ref* into);
/**
* Gets the unit value form this libab instance.
* @param ab the instance to get the unit value from.
* @param into the reference into which to store the unit value.
*/
void libab_get_unit_value(libab* ab, libab_ref* into);
/**
* Gets the true value form this libab instance.
* @param ab the instance to get the true value from.
* @param into the reference into which to store the true value.
*/
void libab_get_true_value(libab* ab, libab_ref* into);
/**
* Gets the false value form this libab instance.
* @param ab the instance to get the false value from.
* @param into the reference into which to store the false value.
*/
void libab_get_false_value(libab* ab, libab_ref* into);
/**
* Get the boolean value corresponding to val from this
* libab instance.
* @param ab the instance to get the value from.
* @param val the true or false value to represent.
* @param into the reference into which to store the value.
*/
void libab_get_bool_value(libab* ab, int val, libab_ref* into);
/**
* Executes the given string of code.
* @param ab the libabacus instance to use for executing code.
* @param string the string to execute.
* @param value the reference into which to store the result.
* @return the result of the computation.
*/
libab_result libab_run(libab* ab, const char* string, libab_ref* value);
/**
* Runs an already-compiled tree.
* @param ab the libabacus instance to use for executing code.
* @param tree the tree the run.
* @param value the reference into which to store the output.
* @return the result of the computation.
*/
libab_result libab_run_tree(libab* ab, libab_tree* tree, libab_ref* value);
/**
* Calls a function with the given name and parameters.
* @param ab the libabacus instance to use to call the function.
* @param function the name of the function to call.
* @param into the reference into which to store the result.
* @param param_count the number of parameters given to this function.
* @return the result of the call.
*/
libab_result libab_run_function(libab* ab, const char* function,
libab_ref* into,
size_t param_count, ...);
/**
* Calls a string in a given surrounding scope.
* @param ab the libabacus instance to use to call the function.
* @param strign the string to run.
* @param scope the scope to use for calling the string.
* @param value the reference into which to store the output of the computation.
* @return the result of the computation.
*/
libab_result libab_run_scoped(libab* ab, const char* string, libab_ref* scope, libab_ref* value);
/**
* Calls a tree in a given scope.
* @param ab the libabacus instance to use to call the tree.
* @param tree the tree to call.
* @param scope the scope to use for the call.
* @param value the reference into which to store the output.
* @return the result of the call.
*/
libab_result libab_run_tree_scoped(libab* ab, libab_tree* tree, libab_ref* scope, libab_ref* value);
/**
* Calls a function with the given name and parameters using a given scope.
* @param ab the libabacus instance to use to call the function.
* @param function the name of the function to call.
* @param scope the scope in which to perform the call.
* @param into the reference into which to store the result.
* @param param_count the number of parameters given to this function.
* @return the result of the call.
*/
libab_result libab_run_function_scoped(libab* ab, const char* function, libab_ref* scope,
libab_ref* into,
size_t param_count, ...);
/**
* Releases all the resources allocated by libabacus.
* @param ab the libabacus instance to release.
* @return the result of the initialization.
*/
libab_result libab_free(libab* ab);
#endif