diff --git a/doc/pages/math.md b/doc/pages/math.md new file mode 100644 index 0000000..dc028c0 --- /dev/null +++ b/doc/pages/math.md @@ -0,0 +1,3 @@ +@page math Math Library + +Archeus' math library as of now is a work in progress. There are basic shapes such as ::ARC_Rect and ::ARC_Circle but this library as of now has not been focused on. Will be revamped at a later date diff --git a/doc/pages/standard.md b/doc/pages/standard.md new file mode 100644 index 0000000..2b4bbc9 --- /dev/null +++ b/doc/pages/standard.md @@ -0,0 +1,17 @@ +@page standard Standard Library + +Archeus' standard library is a collection of basic datatypes that does not depend on any backends and is build by default as it is the core of the project. Each file is listed below with a brief description of what they do. Inside the file linked will be examples of each and a more in-depth explanation of what is happening. + +- @subpage standard-array "ARC_Array" +- @subpage standard-bool "ARC_Bool" +- @subpage standard-chemical "ARC_Chemical" +- @subpage standard-errno "ARC_Errno" +- @subpage standard-hashtable "ARC_Hashtable" +- @subpage standard-io "ARC_IO" +- @subpage standard-lexer "ARC_Lexer" +- @subpage standard-parser "ARC_Parser" +- @subpage standard-queue "ARC_Queue" +- @subpage standard-stack "ARC_Stack" +- @subpage standard-string "ARC_String" +- @subpage standard-time "ARC_Time" +- @subpage standard-vector "ARC_Vector" diff --git a/doc/pages/standard/array.md b/doc/pages/standard/array.md new file mode 100644 index 0000000..92bea6c --- /dev/null +++ b/doc/pages/standard/array.md @@ -0,0 +1,20 @@ +\page standard-array ARC_Array + +The ARC_Array is a simple type, all it does is have a `void *` to store the array data in and a `uint32_t` to store the size in. This type is mostly a helper type to cut down on the number of parameters needed within Archeus' functions + +Example: +```c +#include +#include + +//initing the array (as it is a basic type there is no ARC_Array_Create or ARC_Array_Destroy) +ARC_Array exampleArray; +exampleArray.size = 4; +exampleArray.data = malloc(sizeof(uint32_t) * exampleArray.size); + +//example function using an ARC_Array +ARC_Example_RunArray(&exampleArray); + +//cleanup +free(exampleArray.data); +``` diff --git a/doc/pages/standard/bool.md b/doc/pages/standard/bool.md new file mode 100644 index 0000000..2a013bf --- /dev/null +++ b/doc/pages/standard/bool.md @@ -0,0 +1,34 @@ +\page standard-bool ARC_Bool + +The ::ARC_Bool type simple sets ::ARC_Bool to the `stdbool.h` `bool` type, ::ARC_True to true, and ::ARC_False to false. This type exists so that it can be overriden if a different boolean type should be used (like with opengl) + +Basic Example: +```c +#include + +ARC_Bool example = ARC_True; + +//this example is very pedantic, saying `== ARC_True` isn't required, just recommended +if(example == ARC_True){ + //this will be executed +} +``` + +Override Example: +```c +#include + +//this should be called at the start of the program +#define ARC_BOOL_OVERRIDE +#define ARC_Bool uint8_t +#define ARC_True 1 +#define ARC_False 0 + +#include + +ARC_Bool example = ARC_False; + +if(example != ARC_True){ + //this will be executed +} +``` diff --git a/doc/pages/standard/chemical.md b/doc/pages/standard/chemical.md new file mode 100644 index 0000000..81b2316 --- /dev/null +++ b/doc/pages/standard/chemical.md @@ -0,0 +1,3 @@ +\page standard-chemical ARC_Chemical + +This type is being actively worked on. It will be a config type to read in .chemical files. The name was chosen from the four ethers that Archeus can be broken down into (Chemical, Life, Light, and Reflective) diff --git a/doc/pages/standard/errno.md b/doc/pages/standard/errno.md new file mode 100644 index 0000000..33a25b7 --- /dev/null +++ b/doc/pages/standard/errno.md @@ -0,0 +1,63 @@ +\page standard-errno ARC_Errno + +*Note: this file is being actively worked on and might change during minor updates* + +## About + +arc/std/errno.h is used for handling errors as well as printing to debug. It defines a global `uint32_t` ::arc_errno, as well as a global `FILE` ::arc_errno_log_file. For now it just has printing errors, but in the future it is planned to have warnings and general logs added. For error logs to be printed, `ARC_DEBUG` needs to be defined when compiled. + +## Basic Error Handling + +When throwing errors, ::arc_errno should usually be set to an ARC_ERRNO_ define describing the error. After setting ::arc_errno it is strongly recommended to log that the error happened (this really helps when debugging). + +Basic Example: +```c +#include + +void ARC_Example_ThrowNullError(){ + uint32_t *exampleNumber = NULL; + + if(exampleNumber == NULL){ + //set arc_errno to the most applicable error + arc_errno = ARC_ERRNO_NULL; + + //log where the error happened + ARC_DEBUG_LOG_ERROR("ARC_Example_ThrowNullError(), exampleNumber was NULL"); + } +} +``` + +## Error Handling With More Information + +Sometimes the error will have data that could be helpful when debugging, so there is also a log macro that can log the error with variables added. The formatting is the same as printf. + +Example With Variables: +```c +#include +#include + +void ARC_Example_ThrowPathError(ARC_String *path){ + ARC_String *data; + /* .. try loading data from path here .. */ + + if(data == NULL){ + //set arc_errno to the most applicable error + arc_errno = ARC_ERRNO_DATA; + + //log where the error happened + ARC_DEBUG_LOG_ERROR_WITH_VARIABLES("ARC_Example_ThrowPathError(path), path was %s", path->data); + } +} +``` + +## Overriding Output File + +By default the logs will output to stdout, however this can has an override by defining ARC_DEBUG_LOG_STREAM_OVERRIDE + +Example of Overriding Log Stream: +```c +//when compiling, ARC_DEBUG_LOG_STREAM_OVERRIDE needs to be set, then just add + +//this sets the output to a example_out.txt file that has write permissions +arc_errno_log_file = fopen("example_out.txt", "w"); +``` diff --git a/doc/pages/standard/hashtable.md b/doc/pages/standard/hashtable.md new file mode 100644 index 0000000..e89e774 --- /dev/null +++ b/doc/pages/standard/hashtable.md @@ -0,0 +1,3 @@ +\page standard-hashtable ARC_Hashtable + +*This page will be written after refactoring the ::ARC_Hashtable type* diff --git a/doc/pages/standard/io.md b/doc/pages/standard/io.md new file mode 100644 index 0000000..f3aa9e5 --- /dev/null +++ b/doc/pages/standard/io.md @@ -0,0 +1,3 @@ +\page standard-io ARC_IO + +*This page will be written after refactoring the arc/std/io.h header* diff --git a/doc/pages/standard/lexer.md b/doc/pages/standard/lexer.md new file mode 100644 index 0000000..8fc6d13 --- /dev/null +++ b/doc/pages/standard/lexer.md @@ -0,0 +1 @@ +\page standard-lexer ARC_Lexer diff --git a/doc/pages/standard/parser.md b/doc/pages/standard/parser.md new file mode 100644 index 0000000..9e52d44 --- /dev/null +++ b/doc/pages/standard/parser.md @@ -0,0 +1 @@ +\page standard-parser ARC_Parser diff --git a/doc/pages/standard/queue.md b/doc/pages/standard/queue.md new file mode 100644 index 0000000..9ccfdd1 --- /dev/null +++ b/doc/pages/standard/queue.md @@ -0,0 +1 @@ +\page standard-queue ARC_Queue diff --git a/doc/pages/standard/stack.md b/doc/pages/standard/stack.md new file mode 100644 index 0000000..2788b5d --- /dev/null +++ b/doc/pages/standard/stack.md @@ -0,0 +1 @@ +\page standard-stack ARC_Stack diff --git a/doc/pages/standard/string.md b/doc/pages/standard/string.md new file mode 100644 index 0000000..25fd25c --- /dev/null +++ b/doc/pages/standard/string.md @@ -0,0 +1 @@ +\page standard-string ARC_String diff --git a/doc/pages/standard/time.md b/doc/pages/standard/time.md new file mode 100644 index 0000000..a4af705 --- /dev/null +++ b/doc/pages/standard/time.md @@ -0,0 +1 @@ +\page standard-time ARC_Time diff --git a/doc/pages/standard/vector.md b/doc/pages/standard/vector.md new file mode 100644 index 0000000..73b0d52 --- /dev/null +++ b/doc/pages/standard/vector.md @@ -0,0 +1 @@ +\page standard-vector ARC_Vector