|
Banjo API 1.1.0-alpha
Low-level C99 game development API
|
Macros | |
| #define | BJ_MAXIMUM_LOG_LEN 120u |
| #define | bj_log_msg(LEVEL, ...) |
| #define | bj_trace(...) |
| #define | bj_debug(...) |
| #define | bj_info(...) |
| #define | bj_warn(...) |
| #define | bj_err(...) |
| #define | bj_fatal(...) |
Typedefs | |
| typedef enum bj_log_level | bj_log_level |
Enumerations | |
| enum | bj_log_level { BJ_LOG_TRACE , BJ_LOG_DEBUG , BJ_LOG_INFO , BJ_LOG_WARN , BJ_LOG_ERROR , BJ_LOG_FATAL } |
Functions | |
| const char * | bj_log_level_name (int level) |
| const char * | bj_get_log_level_string (int level) |
| void | bj_set_log_level (int level) |
| int | bj_get_log_level (void) |
| size_t | bj_log_message (int level, const char *file, int line, const char *format,...) |
Severity-filtered structured logging.
Banjo applications and the library itself log through one shared channel. Six severity levels are defined in bj_log_level (TRACE, DEBUG, INFO, WARN, ERROR, FATAL). At runtime only messages at or above the threshold set by bj_set_log_level are emitted; everything below is dropped at the call site, so leaving trace logs in shipped code costs nothing when the threshold is higher.
Use the per-level macros (bj_trace, bj_debug, bj_info, bj_warn, bj_err, bj_fatal) over the generic bj_log_msg / bj_log_message. They take printf-style arguments:
In debug builds, the macros also pass the source file and line to bj_log_message, which does not print them. In release builds they pass neither.
A log line is the name of the level, a space and the message, written to the standard output with a newline: WARN Warning level message. It holds at most BJ_MAXIMUM_LOG_LEN characters. A longer message is truncated, and the level is left out when it no longer fits beside the message.
Configure with the CMake option BANJO_CONFIG_LOG_COLOR, which defines BJ_CONFIG_LOG_COLOR, to wrap level names in ANSI colour codes. They are written whether or not the output is a terminal.
logging.c for a runnable demo. | #define bj_debug | ( | ... | ) |
Log a message using the BJ_LOG_DEBUG level.
The function effectively calls bj_log_message, forwarding arguments to format the input string.
This function is preferred over calling bj_log_msg or bj_log_message directly for clarity.
| ... | The string formatting, forwarded to the last arguments of bj_log_message. |
| #define bj_err | ( | ... | ) |
Log a message using the BJ_LOG_ERROR level.
The function effectively calls bj_log_message, forwarding arguments to format the input string.
This function is preferred over calling bj_log_msg or bj_log_message directly for clarity.
| ... | The string formatting, forwarded to the last arguments of bj_log_message. |
Definition at line 169 of file log.h.
Referenced by main(), main(), setup(), and write_text().
| #define bj_fatal | ( | ... | ) |
Log a message using the BJ_LOG_FATAL level.
The function effectively calls bj_log_message, forwarding arguments to format the input string.
This function is preferred over calling bj_log_msg or bj_log_message directly for clarity.
| ... | The string formatting, forwarded to the last arguments of bj_log_message. |
| #define bj_info | ( | ... | ) |
Log a message using the BJ_LOG_INFO level.
The function effectively calls bj_log_message, forwarding arguments to format the input string.
This function is preferred over calling bj_log_msg or bj_log_message directly for clarity.
| ... | The string formatting, forwarded to the last arguments of bj_log_message. |
Definition at line 141 of file log.h.
Referenced by button_callback(), cursor_callback(), demonstrate_error_copy(), demonstrate_error_matching(), demonstrate_zero_cost(), display_value(), enter_callback(), initialize_server(), key_callback(), main(), main(), print_report(), resize_callback(), resize_callback(), step(), step(), teardown(), and teardown().
| #define bj_log_msg | ( | LEVEL, | |
| ... ) |
Log a message using the given level LEVEL.
LEVEL is the name of a level without its BJ_LOG_ prefix, which the macro pastes back on: TRACE, DEBUG, INFO, WARN, ERROR or FATAL. Call bj_log_message for a level held in a variable.
A message is reported only if LEVEL is at least the threshold set with bj_set_log_level.
The function effectively calls bj_log_message, forwarding arguments to format the input string.
| LEVEL | The name of the level to report the message in, without its BJ_LOG_ prefix. |
| ... | Arguments forwarded to bj_log_message. |
Definition at line 96 of file log.h.
Referenced by main().
| #define BJ_MAXIMUM_LOG_LEN 120u |
Maximum length of log messages.
Log lines, the level and its colour codes included, cannot have a size in bytes larger than BJ_MAXIMUM_LOG_LEN, excluding the newline. In case a message is longer than this limit, the content is truncated in order of priority as described in bj_log_message.
| #define bj_trace | ( | ... | ) |
Log a message using the BJ_LOG_TRACE level.
The function effectively calls bj_log_message, forwarding arguments to format the input string.
This function is preferred over calling bj_log_msg or bj_log_message directly for clarity.
| ... | The string formatting, forwarded to the last arguments of bj_log_message. |
Definition at line 113 of file log.h.
Referenced by main().
| #define bj_warn | ( | ... | ) |
Log a message using the BJ_LOG_WARN level.
The function effectively calls bj_log_message, forwarding arguments to format the input string.
This function is preferred over calling bj_log_msg or bj_log_message directly for clarity.
| ... | The string formatting, forwarded to the last arguments of bj_log_message. |
Definition at line 155 of file log.h.
Referenced by main().
| typedef enum bj_log_level bj_log_level |
| enum bj_log_level |
Log Levels.
Level values are ordered from 0.
| int bj_get_log_level | ( | void | ) |
Gets the current log level set by bj_set_log_level.
Referenced by main().
| const char * bj_get_log_level_string | ( | int | level | ) |
| const char * bj_log_level_name | ( | int | level | ) |
Return the name of the given log level ("TRACE", "WARN", ...).
A level outside bj_log_level gives "UNKNOWN".
| level | The log level to name. |
| size_t bj_log_message | ( | int | level, |
| const char * | file, | ||
| int | line, | ||
| const char * | format, | ||
| ... ) |
Generic message reporting function.
Sends a message using the given level. Message will only be reported if level is at least the value set as a parameter to bj_set_log_level (or BJ_LOG_TRACE if never called).
The more convenient functions bj_log_msg, bj_trace, ... should be used for simplicity.
The string formatting follows standard printf signature and behaviour.
| level | The log level the message is reported in. A level outside bj_log_level is named UNKNOWN and is never coloured. |
| file | The file the message is reported from, or NULL. It is not printed. |
| line | The line the message is reported from. It is not printed. |
| format,... | The formatted string to report. A NULL format logs nothing and returns 0. |
The line written to the standard output is LEVEL MESSAGE and a newline, where:
For example: WARN Warning level message
The line holds at most BJ_MAXIMUM_LOG_LEN characters, the newline excluded. To keep to it, the function gives things up in this order:
| void bj_set_log_level | ( | int | level | ) |
Sets the default log level.
Once set, any call to bj_log_message, bj_log_msg and helper macros will only report a message if its level is at least level.
| level | The level to set. |
If not set, default is BJ_LOG_TRACE.
Referenced by main().