mirrors/zig
1
0
Fork 0
mirror of https://codeberg.org/ziglang/zig.git synced 2025-12-06 13:54:21 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

std.log: update documentation and example for scoped logging

Browse source
This commit is contained in:
heidezomp 2020-08-13 17:12:16 +02:00
parent a8e0f667c6
commit 2439f67061
2 changed files with 25 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
doc/langref.html.in
View file

@ -325,7 +325,7 @@ pub fn main() !void {
represents writing data to a file. When the disk is full, a write to the file will fail. represents writing data to a file. When the disk is full, a write to the file will fail.
However, we typically do not expect writing text to the standard output to fail. To avoid having However, we typically do not expect writing text to the standard output to fail. To avoid having
to handle the failure case of printing to standard output, you can use alternate functions: the to handle the failure case of printing to standard output, you can use alternate functions: the
<code>std.log</code> function for proper logging or the <code>std.debug.print</code> function. functions in <code>std.log</code> for proper logging or the <code>std.debug.print</code> function.
This documentation will use the latter option to print to standard error (stderr) and silently return This documentation will use the latter option to print to standard error (stderr) and silently return
on failure. The next code sample, <code>hello_again.zig</code> demonstrates the use of on failure. The next code sample, <code>hello_again.zig</code> demonstrates the use of
<code>std.debug.print</code>. <code>std.debug.print</code>.

46
lib/std/log.zig
View file

@ -6,12 +6,16 @@ const root = @import("root");
//! of programs and libraries using this interface to be formatted and filtered //! of programs and libraries using this interface to be formatted and filtered
//! by the implementer of the root.log function. //! by the implementer of the root.log function.
//! //!
//! The scope parameter should be used to give context to the logging. For //! Each log message has an associated scope enum, which can be used to give
//! example, a library called 'libfoo' might use .libfoo as its scope. //! context to the logging. The logging functions in std.log implicitly use a
//! This parameter can either be passed explicitly to the logging functions //! scope of .default.
//! provided here, or a scoped logging namespace can be created //!
//! using the `log.scoped` function. If logging scopes are not relevant for //! A logging namespace using a custom scope can be created using the
//! your use case, the `log.default` scope namespace can be used. //! std.log.scoped function, passing the scope as an argument; the logging
//! functions in the resulting struct use the provided scope parameter.
//! For example, a library called 'libfoo' might use
//! `const log = std.log.scoped(.libfoo);` to use .libfoo as the scope of its
//! log messages.
//! //!
//! An example root.log might look something like this: //! An example root.log might look something like this:
//! //!
@ -29,9 +33,9 @@ const root = @import("root");
//! args: anytype, //! args: anytype,
//! ) void { //! ) void {
//! // Ignore all non-critical logging from sources other than //! // Ignore all non-critical logging from sources other than
//! // .my_project and .nice_library //! // .my_project, .nice_library and .default
//! const scope_prefix = "(" ++ switch (scope) { //! const scope_prefix = "(" ++ switch (scope) {
//! .my_project, .nice_library => @tagName(scope), //! .my_project, .nice_library, .default => @tagName(scope),
//! else => if (@enumToInt(level) <= @enumToInt(std.log.Level.crit)) //! else => if (@enumToInt(level) <= @enumToInt(std.log.Level.crit))
//! @tagName(scope) //! @tagName(scope)
//! else //! else
@ -48,26 +52,24 @@ const root = @import("root");
//! } //! }
//! //!
//! pub fn main() void { //! pub fn main() void {
//! // Using explicit scopes: //! // Using the default scope:
//! // Won't be printed as log_level is .warn //! std.log.info("Just a simple informational log message", .{}); // Won't be printed as log_level is .warn
//! std.log.info(.my_project, "Starting up.", .{}); //! std.log.warn("Flux capacitor is starting to overheat", .{});
//! std.log.err(.nice_library, "Something went very wrong, sorry.", .{});
//! // Won't be printed as it gets filtered out by our log function
//! std.log.err(.lib_that_logs_too_much, "Added 1 + 1", .{});
//! //!
//! // Using a scoped logging namespace: //! // Using scoped logging:
//! const scoped_log = std.log.scoped(.my_project); //! const my_project_log = std.log.scoped(.my_project);
//! scoped_log.alert("The scope for this message is implicitly .my_project", .{}); //! const nice_library_log = std.log.scoped(.nice_library);
//! const verbose_lib_log = std.log.scoped(.verbose_lib);
//! //!
//! // Using the default namespace: //! my_project_log.info("Starting up", .{}); // Won't be printed as log_level is .warn
//! // Won't be printed as log_level is .warn //! nice_library_log.err("Something went very wrong, sorry", .{});
//! std.log.default.info("I don't care about my namespace", .{}); //! verbose_lib_log.err("Added 1 + 1: {}", .{1 + 1}); // Won't be printed as it gets filtered out by our log function
//! } //! }
//! ``` //! ```
//! Which produces the following output: //! Which produces the following output:
//! ``` //! ```
//! [err] (nice_library): Something went very wrong, sorry. //! [warn] (default): Flux capacitor is starting to overheat
//! [alert] (my_project): The scope for this message is implicitly .my_project //! [err] (nice_library): Something went very wrong, sorry
//! ``` //! ```
pub const Level = enum { pub const Level = enum {