API Reference
Welcome to the API Reference of Chaos language!
In this page we will describe the accessible macros and functions via Chaos.h header that can be useful while developing C extensions for the language.
Macros
__KAOS_LANGUAGE_NAME__ "Chaos"
: Language's name
__KAOS_VERSION_MAJOR__ 0
: Language's major version
__KAOS_VERSION_MINOR__ 2
: Language's minor version
__KAOS_VERSION_PATCHLEVEL__ 0
: Language's patch version
__KAOS_LANGUAGE_FILE_EXTENSION__ "kaos"
: Default program file extension
__KAOS_LANGUAGE_MOTTO__ "Turn chaos into magic!"
: Language's motto
__KAOS_LANGUAGE_KEYWORD_COUNT__ 31
: Number of reserved keywords
__KAOS_INTERACTIVE_MODULE_NAME__ "__interactive__.kaos"
: Interactive shell's module name
__KAOS_MSG_LINE_LENGTH__ 1000
: A buffer constant being used while printing error messages
__KAOS_BYE_BYE__ "Bye bye!"
: Farewell message appears on exit from interactive shell
__KAOS_SYNTAX_ERROR__ "Syntax error"
: Syntax error message title.
__KAOS_INDENT_LENGTH__ 4
: Indentation length.
__KAOS_SPELLS__ "spells"
: Default package directory name
__KAOS_DYNAMIC_LIBRARY_EXTENSION__
: Dynamic library extension. On Linux: "so"
, on macOS: "dylib"
, on Windows: "dll"
__KAOS_EXTENSION_REGISTER_FUNCTION__ "KaosRegister"
: The function name purposed to be called to register the Chaos C extensions.
__KAOS_EXTENSION_FUNCTION_PREFIX__ "Kaos_"
: Prefix for the exported functions inside the Chaos C extensions.
__KAOS_SHELL_INDICATOR__
: Interactive shell indicator/prompt. "kaos> "
on Windows, "\001\033[0;90m\002kaos>\001\033[0m\002 "
on other platforms. (colored)
__KAOS_SHELL_INDICATOR_BLOCK__
: Interactive shell indicator/prompt in code block mode. ".... "
on Windows, "\001\033[0;90m\002....\001\033[0m\002 "
on other platforms. (colored)
__KAOS_BUILD_DIRECTORY__ "build"
: Compiler's output directory name.
__KAOS_WINDOWS_EXE_EXT__ ".exe"
: Compiled binaries' file extension on Windows.
__KAOS_PLATFORM_NAME__
: Gives you the current platform's name. See platform.h for more details.
__KAOS_PATH_SEPARATOR__
: Path separator string. "\\"
on Windows, "/"
on other platforms.
__KAOS_PATH_SEPARATOR_ASCII__
: Path separator character. '\\'
on Windows, '/'
on other platforms.
Enums
Phase
enum Phase { INIT_PREPARSE, PREPARSE, INIT_PROGRAM, PROGRAM, INIT_JSON_PARSE, JSON_PARSE };
Phase
enumerator symbolizes the states of the runtime. A global variable named phase
holds the state of the runtime.
The Chaos language parses a program file, builds an Abstract Syntax Tree (AST)
and traverses that AST in the phases.
The first phase is named PREPARSE
and it registers the functions and does some look ahead checks.
The second phase is named PROGRAM
and it simply executes the program.
To switch a phase, you do set phase
global variable neither to PREPARSE
nor to PROGRAM
but rather set to INIT_PREPARSE
or INIT_PROGRAM
to initiate the switch. It might seem weird but that's how the phase transition
is implemented in our lexer.
INIT_JSON_PARSE
and JSON_PARSE
are only there to harness the JSON parsing capabilities of the Chaos language and provide jsonParse() function.
Type
enum Type { K_BOOL, K_NUMBER, K_STRING, K_ANY, K_LIST, K_DICT, K_VOID };
Type
enumerator is quite simple. It symbolizes the types of variables that the Chaos language can understand.
K_BOOL
means Boolean,
K_NUMBER
means Number,
K_STRING
means String,
K_ANY
means Any,
K_LIST
means List,
K_DICT
means Dictionary,
and K_VOID
means Void data type.
K_
prefix can remind you Kaos.
ValueType
enum ValueType { V_BOOL, V_INT, V_FLOAT, V_STRING, V_VOID };
ValueType
enumerator is also quite simple. It symbolizes the types of variables in terms of C language that the Chaos language can store.
V_BOOL
means bool
V_INT
means long long
V_FLOAT
means long double
V_STRING
means char*
and V_VOID
has a special meaning. It means a List or a Dictionary can store any of the other four data types.
V_
prefix can remind you Value.
KaosValue
typedef struct KaosValue {
bool b;
long long i;
char *s;
long double f;
} KaosValue;
KaosValue
is the representation of how the Chaos variables hold their value. It's tightly related to ValueType
. You use the KaosValue
to store the value if the value
needs to be hard-coded into the extension and assign to correct C data type according to ValueType
of variable and its equivalent shown above.
Role
enum Role { DEFAULT, PARAM, CALL_PARAM };
Role
enumerator symbolizes the role of a variable that used by the runtime.
DEFAULT
means it's an ordinary variable
PARAM
means it's a function parameter
and CALL_PARAM
means it's a function call parameter.
Functions
int defineFunction()
int defineFunction(
char *name,
enum Type type,
enum Type secondary_type,
char *params_name[],
unsigned params_type[],
unsigned params_secondary_type[],
unsigned short params_length,
KaosValue optional_params[],
unsigned short optional_params_length
);
This is the function to register a function from your Chaos C extension to the runtime and it's meant to put inside the KaosRegister
function.
It takes 8 parameters. Here is a complete example for the usages of defineFunction
:
char *add_params_name[] = {
"x",
"y"
};
unsigned add_params_type[] = {
K_NUMBER,
K_NUMBER
};
unsigned add_params_secondary_type[] = {
K_ANY,
K_ANY
};
unsigned short add_params_length = (unsigned short) sizeof(add_params_type) / sizeof(unsigned);
int EXPORT Kaos_add()
{
long long x = kaos.getVariableInt(add_params_name[0]);
long long y = kaos.getVariableInt(add_params_name[1]);
long long z = x + y;
kaos.returnVariableInt(z);
return 0;
}
int EXPORT KaosRegister(struct Kaos _kaos)
{
kaos = _kaos;
kaos.defineFunction("add", K_NUMBER, K_ANY, add_params_name, add_params_type, add_params_secondary_type, add_params_length, NULL, 0);
return 0;
}
char *name : The function's name. If your function is int EXPORT Kaos_add()
then the name is add
.
enum Type type : The function's return data type. If your function will not return anything it's K_VOID
, otherwise it's one of these { K_BOOL, K_NUMBER, K_STRING, K_ANY, K_LIST, K_DICT }
enum Type secondary_type : This parameter is only meaningful if enum Type type
is K_LIST
or K_DICT
. It indicates the type of typed list or typed dictionary. So for example, if you want to return num list
then set the parameters as ... K_LIST, K_NUM ...
Otherwise set it to K_ANY
char *params_name[] : The parameter names list. If your param list is char *add_params_name[] = { "x", "y" };
variables named x
and y
will be available to use inside your function.
unsigned params_type[] : The variable types of the parameters. If your param type list is unsigned add_params_type[] = { K_NUMBER, K_NUMBER };
there will be two variables with data type Number available to use inside your function.
unsigned params_secondary_type[] : The variable types of the elements of list or dictionary parameters. If your params are, for example; num list
and bool dict
then secondary type list is unsigned blabla_params_secondary_type[] = { K_NUMBER, K_BOOL };
. If the parameter is not a typed list or dictionary or a primitive data type then it's a good practice to use K_ANY
type.
unsigned short params_length : The length of the parameter list. So the length of char *params_name[]
and unsigned params_type[]
must be equal and you have to supply the length value with unsigned short params_length
. So it's 2
in this example.
KaosValue optional_params[] : Optional parameters list which is an array KaosValue
that holds the default values of optional parameters. Assign NULL
if the function does not have any optional parameters.
unsigned short optional_params_length : Number of optional parameters. Indicates that how many of the last N parameters are optional function parameters. Assign 0
if the function does not have any optional parameters.
Optional Function Parameter Example:
You can turn the implementation of num add(num x, num y)
function to num add(num x, num y = 5)
like this:
int EXPORT KaosRegister(struct Kaos _kaos)
{
kaos = _kaos;
struct KaosValue add_optional_y;
add_optional_y.i = 5;
add_optional_y.f = 5.0;
struct KaosValue add_optional_params[] = {
add_optional_y
};
kaos.defineFunction("add", K_NUMBER, K_ANY, add_params_name, add_params_type, add_params_length, add_optional_params, 1);
return 0;
}
bool getVariableBool()
bool getVariableBool(char *name);
Get a V_BOOL
value type variable. Example:
bool x = kaos.getVariableBool(my_params_name[0]);
long long getVariableInt()
long long getVariableInt(char *name);
Get a variable with V_INT
value type. Example:
long long x = kaos.getVariableInt(my_params_name[0]);
long double getVariableFloat()
long double getVariableFloat(char *name);
Get a variable with V_FLOAT
value type. Example:
long double x = kaos.getVariableFloat(my_params_name[0]);
char* getVariableString()
char* getVariableString(char *name);
Get a variable with V_STRING
value type. Example:
char* x = kaos.getVariableString(my_params_name[0]);
bool getVariableBoolByTypeCasting()
bool getVariableBoolByTypeCasting(char *name);
Get a variable by casting its value type V_BOOL
no matter what value type it has. Example:
bool x = kaos.getVariableBoolByTypeCasting(my_params_name[0]);
long long getVariableIntByTypeCasting()
long long getVariableIntByTypeCasting(char *name);
Get a variable by casting its value type V_INT
no matter what value type it has. Example:
long long x = kaos.getVariableIntByTypeCasting(my_params_name[0]);
long double getVariableFloatByTypeCasting()
long double getVariableFloatByTypeCasting(char *name);
Get a variable by casting its value type V_FLOAT
no matter what value type it has. Example:
long double x = kaos.getVariableFloatByTypeCasting(my_params_name[0]);
char* getVariableStringByTypeCasting()
char* getVariableStringByTypeCasting(char *name);
Get a variable by casting its value type V_STRING
no matter what value type it has. Example:
char* x = kaos.getVariableStringByTypeCasting(my_params_name[0]);
unsigned long getListLength()
unsigned long getListLength(char *name);
Get the length of the list. Example:
unsigned long length = kaos.getListLength(my_params_name[0]);
bool getListElementBool()
bool getListElementBool(char *name, long long i);
Get a list element with V_BOOL
value type. Example:
long long i : is the index of the element.
bool x = kaos.getListElementBool(my_params_name[0], 0);
long long getListElementInt()
long long getListElementInt(char *name, long long i);
Get a list element with V_INT
value type. Example:
long long i : is the index of the element.
long long x = kaos.getListElementInt(my_params_name[0], 0);
long double getListElementFloat()
long double getListElementFloat(char *name, long long i);
Get a list element with V_FLOAT
value type. Example:
long long i : is the index of the element.
long double x = kaos.getListElementFloat(my_params_name[0], 0);
char* getListElementString()
char* getListElementBool(char *name, long long i);
Get a list element with V_STRING
value type. Example:
long long i : is the index of the element.
char* x = kaos.getListElementString(my_params_name[0], 0);
bool getListElementBoolByTypeCasting()
bool getListElementBoolByTypeCasting(char *name, long long i);
Get a list element by casting its value type V_BOOL
no matter what value type it has. Example:
bool x = kaos.getListElementBoolByTypeCasting(my_params_name[0], 0);
long long getListElementIntByTypeCasting()
long long getListElementIntByTypeCasting(char *name, long long i);
Get a list element by casting its value type V_INT
no matter what value type it has. Example:
long long x = kaos.getListElementIntByTypeCasting(my_params_name[0], 0);
long double getListElementFloatByTypeCasting()
long double getListElementFloatByTypeCasting(char *name, long long i);
Get a list element by casting its value type V_FLOAT
no matter what value type it has. Example:
long double x = kaos.getListElementFloatByTypeCasting(my_params_name[0], 0);
char* getListElementStringByTypeCasting()
char* getListElementStringByTypeCasting(char *name, long long i);
Get a list element by casting its value type V_STRING
no matter what value type it has. Example:
char* x = kaos.getListElementStringByTypeCasting(my_params_name[0], 0);
void copyListElement()
void copyListElement(char *name, long long i);
Copy the list element seamlessly while building a new list with startBuildingList(). Example:
kaos.copyListElement(my_params_name[0], 0);
enum Type getListElementType()
enum Type getListElementType(char *name, long long i);
Learn the type of specific list element. Example:
enum Type type = kaos.getListElementType(my_params_name[0], 0);
enum ValueType getListElementValueType()
enum ValueType getListElementValueType(char *name, long long i);
Learn the value type of specific list element. Example:
enum ValueType value_type = kaos.getListElementValueType(my_params_name[0], 0);
unsigned long getDictLength()
unsigned long getDictLength(char *name);
Get the length of the dictionary. Example:
unsigned long length = kaos.getDictLength(my_params_name[0]);
char* getDictKeyByIndex()
char* getDictKeyByIndex(char *name, long long i);
Get the key of a dictionary on index i
.
long long i : is the index of the element.
char* x = kaos.getDictKeyByIndex(my_params_name[0], 0);
bool getDictElementBool()
bool getDictElementBool(char *name, char *key);
Get a dictionary element with V_BOOL
value type. Example:
char *key : is the key of the element.
bool x = kaos.getDictElementBool(my_params_name[0], "a");
long long getDictElementInt()
long long getDictElementInt(char *name, char *key);
Get a dictionary element with V_INT
value type. Example:
char *key : is the key of the element.
long long x = kaos.getDictElementInt(my_params_name[0], "a");
long double getDictElementFloat()
long double getDictElementFloat(char *name, char *key);
Get a dictionary element with V_FLOAT
value type. Example:
char *key : is the key of the element.
long double x = kaos.getDictElementFloat(my_params_name[0], "a");
char* getDictElementString()
char* getDictElementString(char *name, char *key);
Get a dictionary element with V_STRING
value type. Example:
char *key : is the key of the element.
char* x = kaos.getDictElementString(my_params_name[0], "a");
bool getDictElementBoolByTypeCasting()
bool getDictElementBoolByTypeCasting(char *name, char *key);
Get a dictionary element by casting its value type V_BOOL
no matter what value type it has. Example:
bool x = kaos.getDictElementBoolByTypeCasting(my_params_name[0], "a");
long long getDictElementIntByTypeCasting()
long long getDictElementIntByTypeCasting(char *name, char *key);
Get a dictionary element by casting its value type V_INT
no matter what value type it has. Example:
long long x = kaos.getDictElementIntByTypeCasting(my_params_name[0], "a");
long double getDictElementFloatByTypeCasting()
long double getDictElementFloatByTypeCasting(char *name, char *key);
Get a dictionary element by casting its value type V_FLOAT
no matter what value type it has. Example:
long double x = kaos.getDictElementFloatByTypeCasting(my_params_name[0], "a");
char* getDictElementStringByTypeCasting()
char* getDictElementStringByTypeCasting(char *name, char *key);
Get a dictionary element by casting its value type V_STRING
no matter what value type it has. Example:
char* x = kaos.getDictElementStringByTypeCasting(my_params_name[0], "a");
void copyDictElement()
void copyDictElement(char *name, char *key);
Copy the dictionary element seamlessly while building a new dictionary with startBuildingDict(). Example:
kaos.copyDictElement(my_params_name[0], "a");
enum Type getDictElementType()
enum Type getDictElementType(char *name, char *key);
Learn the type of specific dictionary element. Example:
enum Type type = kaos.getDictElementType(my_params_name[0], "a");
enum ValueType getDictElementValueType()
enum ValueType getDictElementValueType(char *name, char *key);
Learn the value type of specific dictionary element. Example:
enum ValueType value_type = kaos.getDictElementValueType(my_params_name[0], "a");
char* dumpVariableToString()
char* dumpVariableToString(char *name, bool pretty, bool escaped, bool double_quotes);
Dumps a variable into a string as if you're printing that variable. Example:
char* dump = kaos.dumpVariableToString(my_params_name[0], false, true, true);
void returnVariableBool()
void returnVariableBool(bool b);
Return a variable with K_BOOL
type and V_BOOL
value type. Example:
kaos.returnVariableBool(true);
void returnVariableInt()
void returnVariableInt(long long i);
Return a variable with K_NUMBER
type and V_INT
value type. Example:
kaos.returnVariableInt(365);
void returnVariableFloat()
void returnVariableFloat(long double f);
Return a variable with K_NUMBER
type and V_FLOAT
value type. Example:
kaos.returnVariableFloat(3.14);
void returnVariableString()
void returnVariableString(char *s);
Return a variable with K_STRING
type and V_STRING
value type. Example:
kaos.returnVariableString("foo");
void createVariableBool()
void createVariableBool(char *name, bool b);
Create a variable with K_BOOL
type and V_BOOL
value type. Example:
It's meant to be used after startBuildingList() or startBuildingDict()
char *name : is the key if it's a dictionary element.
kaos.createVariableBool("b", true);
void createVariableInt()
void createVariableInt(char *name, long long i);
Create a variable with K_NUMBER
type and V_INT
value type. Example:
It's meant to be used after startBuildingList() or startBuildingDict()
char *name : is the key if it's a dictionary element.
kaos.createVariableInt("i", 1);
void createVariableFloat()
void createVariableFloat(char *name, long double f);
Create a variable with K_NUMBER
type and V_FLOAT
value type. Example:
It's meant to be used after startBuildingList() or startBuildingDict()
char *name : is the key if it's a dictionary element.
kaos.createVariableFloat("f", 3.14);
void createVariableString()
void createVariableString(char *name, char *s);
Create a variable with K_STRING
type and V_STRING
value type. Example:
It's meant to be used after startBuildingList() or startBuildingDict()
char *name : is the key if it's a dictionary element.
kaos.createVariableString("s", "bar");
void startBuildingList()
void startBuildingList();
Start building a list for the return. Example:
kaos.startBuildingList();
kaos.createVariableInt(NULL, 1);
kaos.createVariableInt(NULL, 2);
kaos.createVariableInt(NULL, 3);
kaos.returnList(K_NUMBER);
void returnList()
void returnList(enum Type type);
Return the list. If enum Type type
is one of these { K_BOOL, K_NUMBER, K_STRING }
then that means it will be a typed list. Example:
kaos.startBuildingList();
kaos.createVariableInt(NULL, 1);
kaos.createVariableInt(NULL, 2);
kaos.createVariableInt(NULL, 3);
kaos.returnList(K_NUMBER);
void startBuildingDict()
void startBuildingDict();
Start building a dictionary for the return. Example:
kaos.startBuildingDict();
kaos.createVariableBool("b", true);
kaos.createVariableInt("i", 1);
kaos.createVariableFloat("f", 3.14);
kaos.createVariableString("s", "bar");
kaos.returnDict(K_ANY);
void returnDict()
void returnDict(enum Type type);
Return the dictionary. If enum Type type
is one of these { K_BOOL, K_NUMBER, K_STRING }
then that means it will be a typed dictionary. Example:
kaos.startBuildingDict();
kaos.createVariableBool("b", true);
kaos.createVariableInt("i", 1);
kaos.createVariableFloat("f", 3.14);
kaos.createVariableString("s", "bar");
kaos.returnDict(K_ANY);
void returnComplex()
void returnComplex(enum Type type);
This function can be used instead of returnList() or returnDict().
void finishList()
void finishList(enum Type type);
Finish building a list that you started with startBuildingList(). You can think this function as returnList() minus return
void finishDict()
void finishDict(enum Type type);
Finish building a dictionary that you started with startBuildingDict(). You can think this function as returnDict() minus return
void finishComplex()
void finishComplex(enum Type type);
This function can be used instead of finishList() or finishDict().
enum Type getListType()
enum Type getListType(char *name);
Learn the type of a typed list. Example:
enum Type type = kaos.getListType(my_params_name[0]);
enum Type getDictType()
enum Type getDictType(char *name);
Learn the type of a typed dictionary. Example:
enum Type type = kaos.getDictType(my_params_name[0]);
enum ValueType getValueType()
enum ValueType getValueType(char *name);
Learn the value type of a specific variable. Example:
enum ValueType value_type = kaos.getValueType(my_params_name[0]);
enum Role getRole()
enum Role getRole(char *name);
Learn the role of a specific variable. Example:
enum Role role = kaos.getRole(my_params_name[0]);
void raiseError()
void raiseError(char *msg);
Throw an error. Example:
kaos.raiseError("Something bad happened!")
void parseJson()
void parseJson(char *json);
Parse a JSON string and return it as a dictionary.