logging without logger, better public API

build.zig.zon

@@ -1,6 +1,6 @@
 .{
     .name = .faller,
-    .version = "0.1.0",
+    .version = "0.3.1",
     .minimum_zig_version = "0.15.1",
     .paths = .{
         "build.zig",

src/root.zig

@@ -1,22 +1,36 @@
+//! A tag based Logger. Example:
+//!
+//! ```zig
+//! log(.foo, "Anonymous log", .{});
+//!
+//! const module_log = scope(.module);
+//! module_log.log(.debug, "Hello {s}!", .{"World"});
+//!
+//! const sub_module_log = module_log.scope(.bar);
+//! sub_module_log.log(.perf, "Operation took {} ns", .{5});
+//! ```
+//!
+//! Output:
+//! ```
+//! foo: Anonymous log
+//! module|debug: Hello World!
+//! module|bar|perf: Operation took 5 ns
+//! ```
 const std = @import("std");
 const root = @import("root");
+const builtin = @import("builtin");
 
 pub const options: Options = if (@hasDecl(root, "faller_options")) root.faller_options else .{};
 
-/// The base logger to create scopes from. Or just use `Logger` directly.
-pub const logger = Logger(&.{});
-
 pub const Options = struct {
+    /// If more specialised ways to log are required replace this function.
+    /// This could be useful for logging to different things than `stderr` or for specifying whether
+    /// we should log with environment variables or `and`-based queries.
     function: fn (
         comptime []const @Type(.enum_literal),
         comptime []const u8,
         anytype,
     ) void = defaultLogFunction,
-    /// If more specialised ways to determine whether something should be logged are required,
-    /// replace this function.
-    /// This could be useful for instance for specifying it with environment variables or
-    /// `and`-based queries.
-    enabled: fn (comptime []const @Type(.enum_literal)) bool = logEnabled,
     /// If there is at least one tag given this acts like a whitelist. Meaning if **any** of the
     /// tags is present it is logged. May be overwritten by `tags_disabled`.
     tags_enabled: []const @Type(.enum_literal) = &.{},
@@ -24,38 +38,88 @@ pub const Options = struct {
     /// tags is present it **isn't** logged. May overwrite `tags_enabled`.
     tags_disabled: []const @Type(.enum_literal) = &.{},
     buffer_size: u64 = 64,
+    disabled_in_test: bool = false,
 };
 
-pub fn Logger(comptime base_tags: []const @Type(.enum_literal)) type {
-    return struct {
-        /// Creates a new logger with an extended tag prefix.
-        pub fn scope(comptime tag: @Type(.enum_literal)) type {
-            return Logger(base_tags ++ [_]@Type(.enum_literal){tag});
-        }
+/// A Logger with prefixes.
+pub const Logger = struct {
+    base_tags: []const @Type(.enum_literal),
 
-        /// Log with one `tag`. Checks whether the log is enabled.
-        pub fn log(
-            comptime tag: @Type(.enum_literal),
-            comptime format: []const u8,
-            args: anytype,
-        ) void {
-            logTags(&.{tag}, format, args);
-        }
+    /// Creates a new logger with an additional tag prefix.
+    pub fn scope(comptime logger: Logger, comptime tag: @Type(.enum_literal)) Logger {
+        return .{
+            .base_tags = logger.base_tags ++ [_]@Type(.enum_literal){tag},
+        };
+    }
 
-        /// Log with multiple `tags`. Checks whether the log is enabled.
-        pub fn logTags(
-            comptime tags: []const @Type(.enum_literal),
-            comptime format: []const u8,
-            args: anytype,
-        ) void {
-            const all_tags = comptime base_tags ++ tags;
-            if (!options.enabled(all_tags)) return;
+    /// Log with one additional `tag`. Checks whether the log is enabled.
+    pub fn log(
+        comptime logger: Logger,
+        comptime tag: @Type(.enum_literal),
+        comptime format: []const u8,
+        args: anytype,
+    ) void {
+        logger.logTags(&.{tag}, format, args);
+    }
 
-            options.function(all_tags, format, args);
-        }
+    /// Log with multiple `tags`. Checks whether the log is enabled.
+    pub fn logTags(
+        comptime logger: Logger,
+        comptime tags: []const @Type(.enum_literal),
+        comptime format: []const u8,
+        args: anytype,
+    ) void {
+        if (builtin.is_test and options.disabled_in_test) return;
+        const all_tags = logger.base_tags ++ tags;
+        options.function(all_tags, format, args);
+    }
+};
+
+/// Creates a new logger with a tag prefix.
+pub fn scope(comptime tag: @TypeOf(.enum_literal)) Logger {
+    return .{
+        .base_tags = &[_]@Type(.enum_literal){tag},
     };
 }
 
+/// Log with one `tag`. Checks whether the log is enabled.
+pub fn log(
+    comptime tag: @Type(.enum_literal),
+    comptime format: []const u8,
+    args: anytype,
+) void {
+    logTags(&.{tag}, format, args);
+}
+
+/// Log with multiple `tags`. Checks whether the log is enabled.
+pub fn logTags(
+    comptime tags: []const @Type(.enum_literal),
+    comptime format: []const u8,
+    args: anytype,
+) void {
+    if (builtin.is_test and options.disabled_in_test) return;
+    options.function(tags, format, args);
+}
+
+/// Checks whether the log is enabled for a specific combination of `tags`. Depends on the `options`
+/// set.
+pub fn logEnabled(comptime tags: []const @Type(.enum_literal)) bool {
+    // If `tags` has at least one in `options.tags_disabled` then we never log.
+    if (options.tags_disabled.len > 0) {
+        if (intersect(tags, options.tags_disabled)) {
+            return false;
+        }
+    }
+
+    // If `tags` has at least one in `options.tags_enabled` then we should log.
+    if (options.tags_enabled.len > 0) {
+        return intersect(tags, options.tags_enabled);
+    }
+
+    // If neither is set then we just log everything.
+    return true;
+}
+
 /// Return `false` if `as` and `bs` have no common member. Else return `true`.
 fn intersect(comptime as: []const @Type(.enum_literal), comptime bs: []const @Type(.enum_literal)) bool {
     for (as) |a| {
@@ -68,31 +132,13 @@ fn intersect(comptime as: []const @Type(.enum_literal), comptime bs: []const @Ty
     return false;
 }
 
-/// Checks whether the log is enabled for a specific combination of `tags`. Depends on the `options`
-/// set.
-pub fn logEnabled(comptime tags: []const @Type(.enum_literal)) bool {
-    // If `tags` has at least one in `options.tags_disabled` then we never log.
-    if (options.tags_disabled.len > 0) {
-        if (comptime intersect(tags, options.tags_disabled)) {
-            return false;
-        }
-    }
-
-    // If `tags` has at least one in `options.tags_enabled` then we should log.
-    if (options.tags_enabled.len > 0) {
-        return comptime intersect(tags, options.tags_enabled);
-    }
-
-    // If neither is set then we just log everything.
-    return true;
-}
-
 fn defaultLogFunction(
     comptime tags: []const @Type(.enum_literal),
     comptime format: []const u8,
     args: anytype,
 ) void {
     if (tags.len == 0) @compileError("Need at least one tag for logging.");
+    if (comptime !logEnabled(tags)) return;
 
     comptime var prefix: []const u8 = "";
     comptime for (tags) |tag| {
@@ -105,3 +151,13 @@ fn defaultLogFunction(
     defer std.debug.unlockStderrWriter();
     nosuspend stderr.print(prefix ++ ": " ++ format ++ "\n", args) catch return;
 }
+
+test {
+    log(.foo, "Anonymous log", .{});
+
+    const module_log = scope(.module);
+    module_log.log(.debug, "Hello {s}!", .{"World"});
+
+    const sub_module_log = module_log.scope(.bar);
+    sub_module_log.log(.perf, "Operation took {} ns", .{5});
+}