diff --git a/README.md b/README.md index 69e12db..2dde613 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ # c_traceback A colorful, lightweight error-propagation framework for C. +Website (in development): [https://www.alvinng4.github.io/c_traceback/](https://www.alvinng4.github.io/c_traceback/) + This library is in early development. Come back later! diff --git a/website/content/docs/API/call_stack_management.mdx b/website/content/docs/API/call_stack_management.mdx index 6d82aa5..04f88e7 100644 --- a/website/content/docs/API/call_stack_management.mdx +++ b/website/content/docs/API/call_stack_management.mdx @@ -7,13 +7,17 @@ import ParamsTable from "components/params-table.tsx"; # Call Stack Management In order to obtain the traceback in run time, we need to actively manage the call stack. -It is not difficult, but functions or code blocks have to be wrapped with a macro, which -is quite verbose. +Unfortunately, C doesn't provide an easy way to do this. Therefore, we will have to wrap +function calls or code blocks with a macro. While this approach can be quite verbose, it +is what makes our library possible. ## API ### `CTB_WRAP` Wrapper macro for expression to automatically manage call stack frames. +```c +CTB_WRAP(expr) +``` #### Parameters +#### Expands to +```c +do \ +{ \ + ctb_push_call_stack_frame(__FILE__, __func__, __LINE__, #expr); \ + (expr); \ + ctb_pop_call_stack_frame(__FILE__, __func__, __LINE__, #expr); \ +} while (0) +``` + #### Usage ```c int function_a(void) { - CTB_WRAP(function_b()); // Wrap a function call + CTB_WRAP(function_b()); // Wraps a function call } int function_b(void) { int i = 0; - CTB_WRAP(i = 2); // Wrap an assignment + CTB_WRAP(i = 2); // Wraps an assignment } ``` -#### Expands to -```c -do -{ - ctb_push_call_stack_frame(__FILE__, __func__, __LINE__, #expr); - (expr); - ctb_pop_call_stack_frame(__FILE__, __func__, __LINE__, #expr); -} while (0) -``` - ### `CTB_Block` Wrapper macro for a code block to automatically manage call stack frames. +```c +CTB_BLOCK(...) +``` #### Parameters +#### Expands to +```c +do \ +{ \ + ctb_push_call_stack_frame(__FILE__, __func__, __LINE__, #__VA_ARGS__); \ + __VA_ARGS__ \ + ctb_pop_call_stack_frame(__FILE__, __func__, __LINE__, #__VA_ARGS__); \ +} while (0) +``` + #### Usage ```c int function_a(void) { - /* Wrap a code block */ + /* Wraps a code block */ CTB_BLOCK( int i = 0; if (i == 0) @@ -72,14 +89,4 @@ int function_a(void) // Note: i is not accessible here // printf("%d", i); <-- Illegal! } -``` - -#### Expands to -```c -do -{ - ctb_push_call_stack_frame(__FILE__, __func__, __LINE__, #__VA_ARGS__); - __VA_ARGS__ - ctb_pop_call_stack_frame(__FILE__, __func__, __LINE__, #__VA_ARGS__); -} while (0) ``` \ No newline at end of file diff --git a/website/content/docs/API/inline_logging.mdx b/website/content/docs/API/inline_logging.mdx new file mode 100644 index 0000000..c77b55d --- /dev/null +++ b/website/content/docs/API/inline_logging.mdx @@ -0,0 +1,143 @@ +--- +title: Inline Logging +--- + +import ParamsTable from "components/params-table.tsx"; + +# Inline Logging + +Sometimes, we just want to log a simple message without the full traceback. +In this case, we can use the inline logging API. + +## API + +### `CTB_LOG_ERROR_INLINE` +Wrapper for logging an error to stderr without stacktrace. +```c +CTB_LOG_ERROR_INLINE(ctb_error, msg, ...) +``` + +Logging an inline error has no effect on the context / call stack. It only logs an error message. + +#### Parameters + + +#### Expands to +```c +do \ +{ \ + ctb_log_error_inline( \ + __FILE__, __LINE__, __func__, ctb_error, msg, __VA_ARGS__ \ + ); \ +} while (0) +``` + +#### Usage +```c +double division(double x, double y) +{ + if (y == 0) + { + CTB_LOG_ERROR_INLINE( + CTB_ZERO_DIVISION_ERROR, + "y cannot be zero! Received: %lf", + y + ); + return 0.0; + } + return x / y; +} +``` +Output: +```ansi +ZeroDivisionError: File "/home/alvinng/Desktop/c_trackback/examples/example.c", line 19 in division: + y cannot be zero! Received: 0.000000 +``` + +### `CTB_LOG_WARNING_INLINE` +Wrapper for logging a warning to stderr without stacktrace. +```c +CTB_LOG_WARNING_INLINE(ctb_warning, msg, ...) +``` + +#### Parameters + + +#### Expands to +```c +do \ +{ \ + ctb_log_warning_inline( \ + __FILE__, __LINE__, __func__, ctb_warning, msg, __VA_ARGS__ \ + ); \ +} while (0) +``` + +#### Usage +```c +double some_function(void) +{ + CTB_LOG_WARNING_INLINE( + CTB_DEPRECATION_WARNING, + "Function \"%s\" is deprecated. It will be removed in the next version.", + __func__ + ); + + /* Do something */ + + return; +} +``` +Output: +```ansi +DeprecationWarning: File "/home/alvinng/Desktop/c_trackback/examples/example.c", line 17 in some_function: + Function "some_function" is deprecated. It will be removed in the next version. +``` + +### `CTB_LOG_MESSAGE_INLINE` +Wrapper for logging a message to stdout without stacktrace. +```c +CTB_LOG_MESSAGE_INLINE(msg, ...) +``` + +#### Parameters + + +#### Expands to +```c +do \ +{ \ + ctb_log_message_inline(__FILE__, __LINE__, __func__, msg, __VA_ARGS__); \ +} while (0) +``` + +#### Usage +```c +void inline_message(int i) +{ + CTB_LOG_MESSAGE_INLINE("(Test %d) Hello, world! :)", i); +} +``` + +Output: +```ansi +Message: File "/home/alvinng/Desktop/c_trackback/examples/example.c", line 75 in inline_message: + (Test 0) Hello, world! :) +``` \ No newline at end of file