README.md.template

{[name]s}

A pretty logger for Zig, inspired by pretty_env_logger.

The logger works together with the std.log API. It provides a logFn function that can be set to your std.Options.

Quick start example

{[quick]s}

Installation

Update to latest version:

zig fetch --save git+{[repo]s}.git

Add to build.zig:

exe.root_module.addImport("{[name]s}", b.dependency("{[name]s}", .{{}}).module("{[name]s}"));

Important

{[name]s} tracks Zig 0.14.0

Examples

Starting example

Setting up the logger happens in two steps:

1. Call {[module_name]s}.setup(.{{}}) and set the value as your std.Options.
2. Call {[module_name]s}.init(.{{}}) once and as early as possible to initialize the logger.

{[name]s} will read the ZIG_LOG environment variable and parse it as the log level. It logs colored messages to stderr by default.

{[starting]s}

Trace level

Zig does not define a .trace log level in std.log.Level. {[name]s} can still log trace messages at a .trace level.

First enable this in the setup opts. To log a trace message, prefix a debug message with TRACE: (including the colon and space).

{[trace_level]s}

Custom environment variable

By default, the logger will look for the ZIG_LOG environment variable in order to configure the log level. If you want to use a different environment variable, set the name in thefilter option.

{[custom_env]s}

Scoped logging

Scoped loggers other than the .default scope will be included in the log message.

{[scoped_log]s}

Dynamic log level

The log level can also be set programmatically instead of using the environment variable. It can also be changed at runtime.

{[dynamic_log_level]s}

Custom std.Options

In case you want to set other std.Options, you can use the {[module_name]s}.setupWith function. Alternatively, you can use the {[module_name]s}.setupFn function and set the logFn field. This allows you to statically disable certain log levels since the setup function sets the log_level field to .debug.

{[custom_std_options]s}

Only log messages

You can disable the level and logger parts of the log message and only render the message itself.

{[only_messages]s}

Add timestamps

You can also add timestamps to the log messages.

{[add_timestamps]s}

Log to different outputs

By default, the logger logs to stderr, but it can also be configured to log to stdout, append to a file, or write to a writer.

{[log_outputs]s}

Configure colors

By default, the logger will detect if the terminal supports colors and use them. You can disable this by setting the enable_color option to false. Alternatively, you can force the logger to use colors by setting the force_color option to true.

{[colors]s}

Configure allocators

Parsing and constructing the log filter requires allocations. By default, the logger uses the std.heap.page_allocator for this. If you want to use a different allocator, you can set the allocator option to a std.mem.Allocator.

Since the filter is supposed to be kept for the remainder of the program's lifetime, you can set two different allocators, one for all the parsing (e.g. a gpa, like the DebugAllocator), and another one for the final filter allocation (e.g. an arena allocator).

{[allocator]s}

Contributing

Contributions are welcome!

Please open an issue or a pull request if you have any suggestions or improvements.

License

{[name]s} is licensed under the MIT License

---