| ... | @@ -6,12 +6,16 @@ const root = @import("root"); | ... | @@ -6,12 +6,16 @@ const root = @import("root"); |
| 6 | //! of programs and libraries using this interface to be formatted and filtered | 6 | //! of programs and libraries using this interface to be formatted and filtered |
| 7 | //! by the implementer of the root.log function. | 7 | //! by the implementer of the root.log function. |
| 8 | //! | 8 | //! |
| 9 | //! The scope parameter should be used to give context to the logging. For | 9 | //! Each log message has an associated scope enum, which can be used to give |
| 10 | //! example, a library called 'libfoo' might use .libfoo as its scope. | 10 | //! context to the logging. The logging functions in std.log implicitly use a |
| 11 | //! This parameter can either be passed explicitly to the logging functions | 11 | //! scope of .default. |
| 12 | //! provided here, or a scoped logging namespace can be created | 12 | //! |
| 13 | //! using the `log.scoped` function. If logging scopes are not relevant for | 13 | //! A logging namespace using a custom scope can be created using the |
| 14 | //! your use case, the `log.default` scope namespace can be used. | 14 | //! std.log.scoped function, passing the scope as an argument; the logging |
| | 15 | //! functions in the resulting struct use the provided scope parameter. |
| | 16 | //! For example, a library called 'libfoo' might use |
| | 17 | //! `const log = std.log.scoped(.libfoo);` to use .libfoo as the scope of its |
| | 18 | //! log messages. |
| 15 | //! | 19 | //! |
| 16 | //! An example root.log might look something like this: | 20 | //! An example root.log might look something like this: |
| 17 | //! | 21 | //! |
| ... | @@ -29,9 +33,9 @@ const root = @import("root"); | ... | @@ -29,9 +33,9 @@ const root = @import("root"); |
| 29 | //! args: anytype, | 33 | //! args: anytype, |
| 30 | //! ) void { | 34 | //! ) void { |
| 31 | //! // Ignore all non-critical logging from sources other than | 35 | //! // Ignore all non-critical logging from sources other than |
| 32 | //! // .my_project and .nice_library | 36 | //! // .my_project, .nice_library and .default |
| 33 | //! const scope_prefix = "(" ++ switch (scope) { | 37 | //! const scope_prefix = "(" ++ switch (scope) { |
| 34 | //! .my_project, .nice_library => @tagName(scope), | 38 | //! .my_project, .nice_library, .default => @tagName(scope), |
| 35 | //! else => if (@enumToInt(level) <= @enumToInt(std.log.Level.crit)) | 39 | //! else => if (@enumToInt(level) <= @enumToInt(std.log.Level.crit)) |
| 36 | //! @tagName(scope) | 40 | //! @tagName(scope) |
| 37 | //! else | 41 | //! else |
| ... | @@ -48,26 +52,24 @@ const root = @import("root"); | ... | @@ -48,26 +52,24 @@ const root = @import("root"); |
| 48 | //! } | 52 | //! } |
| 49 | //! | 53 | //! |
| 50 | //! pub fn main() void { | 54 | //! pub fn main() void { |
| 51 | //! // Using explicit scopes: | 55 | //! // Using the default scope: |
| 52 | //! // Won't be printed as log_level is .warn | 56 | //! std.log.info("Just a simple informational log message", .{}); // Won't be printed as log_level is .warn |
| 53 | //! std.log.info(.my_project, "Starting up.", .{}); | 57 | //! std.log.warn("Flux capacitor is starting to overheat", .{}); |
| 54 | //! std.log.err(.nice_library, "Something went very wrong, sorry.", .{}); | | |
| 55 | //! // Won't be printed as it gets filtered out by our log function | | |
| 56 | //! std.log.err(.lib_that_logs_too_much, "Added 1 + 1", .{}); | | |
| 57 | //! | 58 | //! |
| 58 | //! // Using a scoped logging namespace: | 59 | //! // Using scoped logging: |
| 59 | //! const scoped_log = std.log.scoped(.my_project); | 60 | //! const my_project_log = std.log.scoped(.my_project); |
| 60 | //! scoped_log.alert("The scope for this message is implicitly .my_project", .{}); | 61 | //! const nice_library_log = std.log.scoped(.nice_library); |
| | 62 | //! const verbose_lib_log = std.log.scoped(.verbose_lib); |
| 61 | //! | 63 | //! |
| 62 | //! // Using the default namespace: | 64 | //! my_project_log.info("Starting up", .{}); // Won't be printed as log_level is .warn |
| 63 | //! // Won't be printed as log_level is .warn | 65 | //! nice_library_log.err("Something went very wrong, sorry", .{}); |
| 64 | //! std.log.default.info("I don't care about my namespace", .{}); | 66 | //! verbose_lib_log.err("Added 1 + 1: {}", .{1 + 1}); // Won't be printed as it gets filtered out by our log function |
| 65 | //! } | 67 | //! } |
| 66 | //! ``` | 68 | //! ``` |
| 67 | //! Which produces the following output: | 69 | //! Which produces the following output: |
| 68 | //! ``` | 70 | //! ``` |
| 69 | //! [err] (nice_library): Something went very wrong, sorry. | 71 | //! [warn] (default): Flux capacitor is starting to overheat |
| 70 | //! [alert] (my_project): The scope for this message is implicitly .my_project | 72 | //! [err] (nice_library): Something went very wrong, sorry |
| 71 | //! ``` | 73 | //! ``` |
| 72 | | 74 | |
| 73 | pub const Level = enum { | 75 | pub const Level = enum { |
heidezomp <heidezomp@protonmail.com> 2020-08-13 17:12:16+02:00