readme.md
1# Dragonfail
2Dragonfail is a simple library providing basic error handling functionnalities.
3It was designed to be as lightweight as possible, and can be completely disabled
4with only one `#define` (more on that later).
5
6Dragonfail was designed to be fast and uses inline functions exclusively. These
7calls modify a global context which is not directly accessible by the programmer.
8
9All the error codes must be written in an enum in **your** `dragonfail_error.h` file.
10Because of this rather unusual architecture, the file must be found by the compiler
11when it is processing `dragonfail.c` (in addition to your own source code of course).
12
13## Testing
14Run `make` to compile an example, and `make run` to execute it.
15
16## Defines
17This header can also contain some `#define` to modify dragonfail's behaviour:
18 - `DRAGONFAIL_SKIP` completely disables the whole library, making it completely
19 disappear from the binary (unless your compiler is a massive douche).
20 - `DRAGONFAIL_BASIC_LOG` enables the `dgn_basic_log()` function calls
21 - `DRAGONFAIL_THROW_BASIC_LOG` makes `dgn_throw()` call `dgn_basic_log()` automatically
22 - `DRAGONFAIL_ABORT` makes `dgn_throw()` call `abort()`
23
24Again, these `#define` must be placed in **your** `dragonfail_error.h` file.
25
26## Using
27### TL;DR
28see the `example` folder :)
29
30### Documentation
31```
32char** dgn_init();
33```
34This intializes the context to `DGN_OK` (no error) and returns the array of strings
35you can fill with log messages corresponding to the errors you added in the enum.
36
37```
38void dgn_reset();
39```
40This resets the context to `DGN_OK`.
41
42```
43void dgn_basic_log();
44```
45This prints the message corresponding to the current error to stderr.
46
47```
48void dgn_throw(enum dgn_error new_code);
49```
50This sets the error to the given code.
51
52```
53char dgn_catch();
54```
55This returns true if the context currently holds an error
56
57## Why is the architecture so strange?
58The dragonfail context is global (extern) but really *implemented* in `dragonfail.c`.
59Its type depends on the size of the enum so it is *declared* in `dragonfail_private.h`:
60this way we can include the user's `dragonfail_error.h` and get `DGN_SIZE`.
61
62The inline functions need to access this context and **we want it private**, so we can't
63*implement* them directly in the header as a lot of people seem to appreciate. Instead,
64we will *declare* them here, and put the *implementations* in `dragonfail.c`: this way
65we can access the global context without including its declaration, because it is
66implemented here as well.
67
68When you include `dragonfail.h`, you get access to the inline functions declarations
69and thanks to this design any compiler will do the rest of the job automatically. Yes,
70this whole thing is useless and over-engineered. And yes, I had fun doing it...
71
72## Greetings
73Jinjer for the cool music \m/
74Haiku developers for indirectly giving me the idea
75