Add a FormatLogger logger sink.

Author: fredrikekre

README.md

@@ -23,7 +23,7 @@ Loggers can be broken down into 4 types:
  - *Demux*: There is only one possible Demux Logger. and it is central to log routing. It acts as a hub that recieves 1 log message, and then sends copies of it to all its child loggers. Like iin the diagram above, it can be composed with Filters to control what goes where.
 
 This is a basically full taxonomy of all compositional loggers.
-Other than `Sinks`, this package implements the full set. So you shouldn't need to build your own routing components, just configure the ones included in this package.
+This package implements the full set. So you shouldn't need to build your own routing components, just configure the ones included in this package.
 
 It is worth understanding the idea of logging purity.
 The loggers defined in this package are all pure.
@@ -81,9 +81,10 @@ logger = global_logger()
 
 
 # Loggers introduced by this package:
-This package introduces 7 new loggers.
-The `TeeLogger`, the `TransformerLogger`, 3 types of filtered logger, and the `FileLogger`.
-All of them just wrap existing loggers.
+This package introduces 8 new loggers.
+The `TeeLogger`, the `TransformerLogger`, 3 types of filtered logger, the `FileLogger`,
+the `DatetimeRotatingFileLogger` and the `FormatLogger`.
+All of them, except `FormatLogger`, just wrap existing loggers.
  - The `TeeLogger` sends the logs to multiple different loggers.
  - The `TransformerLogger` applies a function to modify log messages before passing them on.
  - The 3 filter loggers are used to control if a message is written or not
@@ -92,6 +93,7 @@ All of them just wrap existing loggers.
      - The `ActiveFilteredLogger` lets you filter based on the full content
  - The `FileLogger` is a simple logger sink that writes to file.
  - The `DatetimeRotatingFileLogger` is a logger sink that writes to file, rotating logs based upon a user-provided `DateFormat`.
+ - The `FormatLogger` is a logger sink that simply formats the message and writes to the logger stream.
 
 By combining `TeeLogger` with filter loggers you can arbitrarily route log messages, wherever you want.
 
@@ -315,6 +317,25 @@ julia> filter(f -> endswith(f, ".log"), readdir(pwd()))
 
 The user implicitly controls when the files will be rolled over based on the `DateFormat` given.
 
+## `FormatLogger`
+The `FormatLogger` is a sink that formats the message and prints to a wrapped IO.
+Formatting is done by providing a function `f(io::IO, log_args::NamedTuple)`.
+
+```julia
+julia> using Logging, LoggingExtras
+
+julia> logger = FormatLogger() do io, args
+           println(io, args._module, " | ", "[", args.level, "] ", args.message)
+       end;
+
+julia> with_logger(logger) do
+           @info "This is an informational message."
+           @warn "This is a warning, should take a look."
+       end
+Main | [Info] This is an informational message.
+Main | [Warn] This is a warning, should take a look.
+```
+
 # More Examples
 
 ## Filter out any overly long messages

src/LoggingExtras.jl

@@ -10,7 +10,7 @@ import Base.CoreLogging:
 
 export TeeLogger, TransformerLogger, FileLogger,
     ActiveFilteredLogger, EarlyFilteredLogger, MinLevelLogger,
-    DatetimeRotatingFileLogger
+    DatetimeRotatingFileLogger, FormatLogger
 
 
 ######
@@ -39,6 +39,7 @@ include("earlyfiltered.jl")
 include("minlevelfiltered.jl")
 include("filelogger.jl")
 include("datetime_rotation.jl")
+include("formatlogger.jl")
 include("deprecated.jl")
 
 end # module

src/formatlogger.jl

@@ -0,0 +1,50 @@
+
+struct FormatLogger <: AbstractLogger
+    f::Function
+    io::IO
+    always_flush::Bool
+end
+
+"""
+    FormatLogger(f::Function, io::IO=stderr; always_flush=true)
+
+Logger sink that formats the message and finally writes to `io`.
+The formatting function should be of the form `f(io::IOContext, log_args::NamedTuple)`
+where `log_args` has the following fields:
+`(level, message, _module, group, id, file, line, kwargs)`.
+See `?LoggingExtra.handle_message_args` for more information on what field is.
+
+# Examples
+```julia-repl
+julia> using Logging, LoggingExtras
+
+julia> logger = FormatLogger() do io, args
+           println(io, args._module, " | ", "[", args.level, "] ", args.message)
+       end;
+
+julia> with_logger(logger) do
+           @info "This is an informational message."
+           @warn "This is a warning, should take a look."
+       end
+Main | [Info] This is an informational message.
+Main | [Warn] This is a warning, should take a look.
+```
+"""
+function FormatLogger(f::Function, io::IO=stderr; always_flush=true)
+    return FormatLogger(f, io, always_flush)
+end
+
+function handle_message(logger::FormatLogger, args...; kwargs...)
+    log_args = handle_message_args(args...; kwargs...)
+    # We help the user by passing an IOBuffer to the formatting function
+    # to make sure that everything writes to the logger io in one go.
+    iob = IOBuffer()
+    ioc = IOContext(iob, logger.io)
+    logger.f(ioc, log_args)
+    write(logger.io, take!(iob))
+    logger.always_flush && flush(logger.io)
+    return nothing
+end
+shouldlog(logger::FormatLogger, arg...) = true
+min_enabled_level(logger::FormatLogger) = BelowMinLevel
+catch_exceptions(logger::FormatLogger) = true # Or false? SimpleLogger doesn't, ConsoleLogger does.

test/runtests.jl

@@ -159,6 +159,36 @@ end
     end
 end
 
+@testset "FormatLogger" begin
+    io = IOBuffer()
+    logger = FormatLogger(io) do io, args
+        # Put in some bogus sleep calls just to test that
+        # log records writes in one go
+        print(io, args.level)
+        sleep(rand())
+        print(io, ": ")
+        sleep(rand())
+        println(io, args.message)
+    end
+    with_logger(logger) do
+        @sync begin
+            @async @debug "debug message"
+            @async @info "info message"
+            @async @warn "warning message"
+            @async @error "error message"
+        end
+    end
+    str = String(take!(io))
+    @test occursin(r"^Debug: debug message$"m, str)
+    @test occursin(r"^Info: info message$"m, str)
+    @test occursin(r"^Warn: warning message$"m, str)
+    @test occursin(r"^Error: error message$"m, str)
+    @test logger.always_flush
+    # Test constructor with default io and kwarg
+    logger = FormatLogger(x -> x; always_flush=false)
+    @test logger.io === stderr
+    @test !logger.always_flush
+end
 
 @testset "Deprecations" begin
     testlogger = TestLogger(min_level=BelowMinLevel)