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