diff --git a/lib/std/log.zig b/lib/std/log.zig index d8bcba38cc..9a0dcecc05 100644 --- a/lib/std/log.zig +++ b/lib/std/log.zig @@ -2,12 +2,16 @@ const std = @import("std.zig"); const builtin = std.builtin; const root = @import("root"); -//! std.log is standardized interface for logging which allows for the logging +//! std.log is a standardized interface for logging which allows for the logging //! of programs and libraries using this interface to be formatted and filtered //! by the implementer of the root.log function. //! //! The scope parameter should be used to give context to the logging. For //! example, a library called 'libfoo' might use .libfoo as its scope. +//! This parameter can either be passed explicitly to the logging functions +//! provided here, or a scoped logging namespace can be created +//! using the `log.scoped` function. If logging scopes are not relevant for +//! your use case, the `log.default` scope namespace can be used. //! //! An example root.log might look something like this: //! @@ -44,16 +48,26 @@ const root = @import("root"); //! } //! //! pub fn main() void { +//! // Using explicit scopes: //! // Won't be printed as log_level is .warn //! std.log.info(.my_project, "Starting up.", .{}); //! 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: +//! const scoped_log = std.log.scoped(.my_project); +//! scoped_log.alert("The scope for this message is implicitly .my_project", .{}); +//! +//! // Using the default namespace: +//! // Won't be printed as log_level is .warn +//! std.log.default.info("I don't care about my namespace", .{}); //! } //! ``` //! Which produces the following output: //! ``` //! [err] (nice_library): Something went very wrong, sorry. +//! [alert] (my_project): The scope for this message is implicitly .my_project //! ``` pub const Level = enum { @@ -115,7 +129,7 @@ fn log( } } -/// Log an emergency message to stderr. This log level is intended to be used +/// Log an emergency message. This log level is intended to be used /// for conditions that cannot be handled and is usually followed by a panic. pub fn emerg( comptime scope: @Type(.EnumLiteral), @@ -126,7 +140,7 @@ pub fn emerg( log(.emerg, scope, format, args); } -/// Log an alert message to stderr. This log level is intended to be used for +/// Log an alert message. This log level is intended to be used for /// conditions that should be corrected immediately (e.g. database corruption). pub fn alert( comptime scope: @Type(.EnumLiteral), @@ -137,7 +151,7 @@ pub fn alert( log(.alert, scope, format, args); } -/// Log a critical message to stderr. This log level is intended to be used +/// Log a critical message. This log level is intended to be used /// when a bug has been detected or something has gone wrong and it will have /// an effect on the operation of the program. pub fn crit( @@ -149,7 +163,7 @@ pub fn crit( log(.crit, scope, format, args); } -/// Log an error message to stderr. This log level is intended to be used when +/// Log an error message. This log level is intended to be used when /// a bug has been detected or something has gone wrong but it is recoverable. pub fn err( comptime scope: @Type(.EnumLiteral), @@ -160,7 +174,7 @@ pub fn err( log(.err, scope, format, args); } -/// Log a warning message to stderr. This log level is intended to be used if +/// Log a warning message. This log level is intended to be used if /// it is uncertain whether something has gone wrong or not, but the /// circumstances would be worth investigating. pub fn warn( @@ -171,7 +185,7 @@ pub fn warn( log(.warn, scope, format, args); } -/// Log a notice message to stderr. This log level is intended to be used for +/// Log a notice message. This log level is intended to be used for /// non-error but significant conditions. pub fn notice( comptime scope: @Type(.EnumLiteral), @@ -181,7 +195,7 @@ pub fn notice( log(.notice, scope, format, args); } -/// Log an info message to stderr. This log level is intended to be used for +/// Log an info message. This log level is intended to be used for /// general messages about the state of the program. pub fn info( comptime scope: @Type(.EnumLiteral), @@ -191,7 +205,7 @@ pub fn info( log(.info, scope, format, args); } -/// Log a debug message to stderr. This log level is intended to be used for +/// Log a debug message. This log level is intended to be used for /// messages which are only useful for debugging. pub fn debug( comptime scope: @Type(.EnumLiteral), @@ -200,3 +214,90 @@ pub fn debug( ) void { log(.debug, scope, format, args); } + +/// Returns a scoped logging namespace that logs all messages using the scope +/// provided here. +pub fn scoped(comptime scope: @Type(.EnumLiteral)) type { + return struct { + /// Log an emergency message. This log level is intended to be used + /// for conditions that cannot be handled and is usually followed by a panic. + pub fn emerg( + comptime format: []const u8, + args: anytype, + ) void { + @setCold(true); + log(.emerg, scope, format, args); + } + + /// Log an alert message. This log level is intended to be used for + /// conditions that should be corrected immediately (e.g. database corruption). + pub fn alert( + comptime format: []const u8, + args: anytype, + ) void { + @setCold(true); + log(.alert, scope, format, args); + } + + /// Log a critical message. This log level is intended to be used + /// when a bug has been detected or something has gone wrong and it will have + /// an effect on the operation of the program. + pub fn crit( + comptime format: []const u8, + args: anytype, + ) void { + @setCold(true); + log(.crit, scope, format, args); + } + + /// Log an error message. This log level is intended to be used when + /// a bug has been detected or something has gone wrong but it is recoverable. + pub fn err( + comptime format: []const u8, + args: anytype, + ) void { + @setCold(true); + log(.err, scope, format, args); + } + + /// Log a warning message. This log level is intended to be used if + /// it is uncertain whether something has gone wrong or not, but the + /// circumstances would be worth investigating. + pub fn warn( + comptime format: []const u8, + args: anytype, + ) void { + log(.warn, scope, format, args); + } + + /// Log a notice message. This log level is intended to be used for + /// non-error but significant conditions. + pub fn notice( + comptime format: []const u8, + args: anytype, + ) void { + log(.notice, scope, format, args); + } + + /// Log an info message. This log level is intended to be used for + /// general messages about the state of the program. + pub fn info( + comptime format: []const u8, + args: anytype, + ) void { + log(.info, scope, format, args); + } + + /// Log a debug message. This log level is intended to be used for + /// messages which are only useful for debugging. + pub fn debug( + comptime format: []const u8, + args: anytype, + ) void { + log(.debug, scope, format, args); + } + }; +} + +/// The default scoped logging namespace. +pub const default = scoped(.default);