From b1c4a6d4589f15f90849908d13595861d5071b7a Mon Sep 17 00:00:00 2001 From: Abdelrahman Date: Fri, 26 Jun 2026 15:13:35 +0100 Subject: [PATCH] Update wiki --- Home.md | 4 ++ Packages.md | 1 + _Sidebar.md | 1 + log/Home.md | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++ os/Home.md | 14 +++++++ uuid/Home.md | 4 +- 6 files changed, 138 insertions(+), 2 deletions(-) create mode 100644 log/Home.md diff --git a/Home.md b/Home.md index 6548b1e..eedfd60 100644 --- a/Home.md +++ b/Home.md @@ -133,6 +133,7 @@ The library source lives inside the `src` directory. src/ ├── base ├── common +├── log ├── os ├── prng ├── testing @@ -166,6 +167,9 @@ src/ ├── uuid │ ├── wapp_uuid.c │ └── wapp_uuid.h +├── log +│ ├── wapp_log.c +│ └── wapp_log.h ├── testing │ ├── wapp_testing.c │ └── wapp_testing.h diff --git a/Packages.md b/Packages.md index 12e74d7..68bd437 100644 --- a/Packages.md +++ b/Packages.md @@ -6,4 +6,5 @@ The library contains the following packages: - [os](os/Home.md) - [prng](prng/Home.md) - [uuid](uuid/Home.md) +- [log](log/Home.md) - [testing](testing/Home.md) diff --git a/_Sidebar.md b/_Sidebar.md index b224471..8a9eb6a 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -5,4 +5,5 @@ - [os](os/Home.md) - [prng](prng/Home.md) - [uuid](uuid/Home.md) + - [log](log/Home.md) - [testing](testing/Home.md) diff --git a/log/Home.md b/log/Home.md new file mode 100644 index 0000000..b06cc9b --- /dev/null +++ b/log/Home.md @@ -0,0 +1,116 @@ +# log + +The `log` package provides a lightweight, structured logging framework with configurable log levels, named loggers, and automatic timestamping. + +```c +#include "wapp_log.h" +``` + +**Dependencies:** common, base, os + +--- + +## 📋 Log Levels + +Six severity levels are available, ordered from most to least severe: + +| Level | Description | +|-------|-------------| +| `WAPP_LOG_FATAL` | Fatal error — unrecoverable | +| `WAPP_LOG_CRITICAL` | Critical condition | +| `WAPP_LOG_ERROR` | Error condition | +| `WAPP_LOG_WARNING` | Warning condition | +| `WAPP_LOG_INFO` | Informational message | +| `WAPP_LOG_DEBUG` | Debug message | + +Messages below the configured log level are silently discarded. + +--- + +## ⚙️ Configuration + +### Global Log Level + +```c +void wapp_log_set_level(LogLevel level); +``` + +Sets the minimum log level. Messages below this threshold are ignored. + +### Output Streams + +```c +void wapp_log_configure(WFile *outlog, WFile *errlog, LogLevel level); +``` + +Configures output streams for informational and error output, and sets the log level in one call. + +- `outlog` — destination for `debug`, `info`, and `warning` messages (defaults to `stdout`) +- `errlog` — destination for `error`, `critical`, and `fatal` messages (defaults to `stderr`) +- `level` — minimum log level + +--- + +## 🏷️ Logger + +A named logger identifies the source of each log message. + +```c +typedef struct { + Str8 name; +} Logger; + +Logger wapp_log_make_logger(Str8 name); +``` + +The logger name appears in every log line, making it easy to filter messages by component. + +--- + +## 📝 Logging Functions + +Each severity level has a corresponding function: + +```c +void wapp_log_fatal(const Logger *logger, Str8 msg); +void wapp_log_critical(const Logger *logger, Str8 msg); +void wapp_log_error(const Logger *logger, Str8 msg); +void wapp_log_warning(const Logger *logger, Str8 msg); +void wapp_log_info(const Logger *logger, Str8 msg); +void wapp_log_debug(const Logger *logger, Str8 msg); +``` + +All functions accept a `Logger` pointer and a `Str8` message. + +--- + +## 📄 Log Format + +Each log line follows this format: + +``` +2024-01-15T10:30:00Z [debug ] message text [logger_name] +``` + +- ISO 8601 UTC timestamp +- Log level in brackets (padded to 10 characters) +- Message text (padded to a minimum width) +- Logger name in brackets + +### Example + +```c +Allocator arena = wapp_mem_arena_allocator_init(KiB(16)); + +Logger main_logger = wapp_log_make_logger(wapp_str8_lit("main")); + +wapp_log_info(&main_logger, wapp_str8_lit("Application started")); +wapp_log_debug(&main_logger, wapp_str8_lit("Initialising subsystems...")); + +// Output: +// 2024-01-15T10:30:00Z [info ] Application started [main] +// 2024-01-15T10:30:00Z [debug ] Initialising subsystems... [main] + +wapp_log_set_level(WAPP_LOG_ERROR); +wapp_log_debug(&main_logger, wapp_str8_lit("This will not be printed")); +``` diff --git a/os/Home.md b/os/Home.md index ad0b56a..c9db2b7 100644 --- a/os/Home.md +++ b/os/Home.md @@ -152,6 +152,18 @@ Cross-platform file operations with array-level read/write support. | `WAPP_SEEK_CURRENT` | Current position | | `WAPP_SEEK_END` | End of file | +### Standard Streams + +Convenience accessors for the process's standard I/O streams. + +| Function | Description | +|----------|-------------| +| `wapp_file_stdin()` | Returns a `WFile*` for standard input | +| `wapp_file_stdout()` | Returns a `WFile*` for standard output | +| `wapp_file_stderr()` | Returns a `WFile*` for standard error | + +> Return values should not be cached as they are not guaranteed to remain the same across calls. Always call the function to get the current stream. + ### Functions | Function | Description | @@ -160,6 +172,8 @@ Cross-platform file operations with array-level read/write support. | `wapp_file_close(file)` | Closes a file | | `wapp_file_read(buf, file, byte_count)` | Reads raw bytes. Returns bytes read. | | `wapp_file_write(buf, file, byte_count)` | Writes raw bytes. Returns count or negative on error. | +| `wapp_file_read_str8(str, file)` | Reads into a `Str8` buffer (fills up to `str->size` bytes) | +| `wapp_file_write_str8(str, file)` | Writes a `Str8RO` to a file | | `wapp_file_read_array(dst_array, file, item_count)` | Reads array elements from file | | `wapp_file_write_array(src_array, file, item_count)` | Writes array elements to file | | `wapp_file_seek(file, offset, origin)` | Seeks to position. Returns new position or negative. | diff --git a/uuid/Home.md b/uuid/Home.md index cea90ef..0124d87 100644 --- a/uuid/Home.md +++ b/uuid/Home.md @@ -42,13 +42,13 @@ printf(WAPP_UUID_SPEC "\n", wapp_uuid_varg(u)); WUUID u = wapp_uuid_gen_uuid4(); ``` -Creates a buffer and returns a fully initialised `WUUID` in a single expression. +Creates a buffer and returns a fully initialised `WUUID` in a single expression. Works in both C and C++. ### Low-Level API | Function / Macro | Description | |------------------|-------------| -| `wapp_uuid_create()` | Creates an empty `WUUID` with a zeroed buffer | +| `wapp_uuid_create()` | Creates an empty `WUUID` with a zeroed buffer. Uses `WUUID{...}` in C++ and compound literals in C. | | `wapp_uuid_init_uuid4(uuid)` | Fills a `WUUID` with a randomly generated UUID v4. Returns the same pointer. | ### Example