Updated docs and tests

Author: Russ Egan

v2/config_from_env_test.go

@@ -2,10 +2,16 @@ package flume
 
 import (
 	"bytes"
+	"context"
 	"io"
 	"log/slog"
+	"path"
+	"runtime"
+	"strings"
 	"testing"
+	"time"
 
+	"github.com/ansel1/console-slog"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -257,23 +263,60 @@ func TestRegisterHandlerFn(t *testing.T) {
 			}.Run(t)
 		})
 	}
+}
 
+func TestBuiltInHandlers(t *testing.T) {
+	theme := console.NewDefaultTheme()
 	builtIns := map[string]string{
-		TermHandler:      "blue     INF | hi\n",
-		TermColorHandler: "\x1b[1;90mblue    \x1b[0m \x1b[32mINF\x1b[0m \x1b[1;90m|\x1b[0m \x1b[1mhi\x1b[0m\n",
-		TextHandler:      "level=INFO msg=hi logger=blue\n",
-		JSONHandler:      `{"level":"INFO","msg":"hi","logger":"blue"}` + "\n",
-		ConsoleHandler:   "level=INFO msg=hi logger=blue\n",
-		NoopHandler:      "",
+		TermHandler: "blue     |INF| hi\n",
+		TermColorHandler: styled("blue    ", theme.Header) + " " +
+			styled("|", theme.Header) + styled("INF", theme.LevelInfo) + styled("|", theme.Header) + " " +
+			styled("hi", theme.Message) + "\n",
+		TextHandler:    "level=INFO msg=hi logger=blue\n",
+		JSONHandler:    `{"level":"INFO","msg":"hi","logger":"blue"}` + "\n",
+		ConsoleHandler: "level=INFO msg=hi logger=blue\n",
+		NoopHandler:    "",
 	}
 	for name, want := range builtIns {
+		handlerFn := LookupHandlerFn(name)
+
 		t.Run("builtin "+name, func(t *testing.T) {
 			handlerTest{
 				want: want,
 				handlerFn: func(buf *bytes.Buffer) slog.Handler {
-					return LookupHandlerFn(name)("", buf, nil).WithAttrs([]slog.Attr{slog.String(LoggerKey, "blue")})
+					return handlerFn("", buf, nil).WithAttrs([]slog.Attr{slog.String(LoggerKey, "blue")})
 				},
 			}.Run(t)
 		})
+
+		if name == NoopHandler {
+			// noop handler doesn't honor any of the other options
+			continue
+		}
+
+		t.Run("builtin "+name+" with options", func(t *testing.T) {
+			pc, file, _, _ := runtime.Caller(0)
+			file = path.Base(file)
+
+			buf := bytes.NewBuffer(nil)
+			h := handlerFn("", buf, &slog.HandlerOptions{Level: slog.LevelWarn, AddSource: true, ReplaceAttr: replaceKey(LoggerKey, slog.String(LoggerKey, "cerulean"))})
+			h = h.WithAttrs([]slog.Attr{slog.String(LoggerKey, "blue")})
+
+			assert.True(t, h.Enabled(context.Background(), slog.LevelWarn))
+			assert.False(t, h.Enabled(context.Background(), slog.LevelInfo))
+
+			err := h.Handle(context.Background(), slog.NewRecord(time.Now(), slog.LevelWarn, "hi", pc))
+			require.NoError(t, err)
+
+			assert.Contains(t, buf.String(), "cerulean", "ReplaceAttr function should have replaced logger key")
+			assert.Contains(t, buf.String(), file, "AddSource should have been true")
+		})
+	}
+}
+
+func styled(s string, c console.ANSIMod) string {
+	if c == "" {
+		return s
 	}
+	return strings.Join([]string{string(c), s, string(console.ResetMod)}, "")
 }

v2/example_test.go

@@ -48,8 +48,8 @@ func ExampleTermHandler() {
 	l.With(LoggerKey, "server").Info("Request received", "method", "GET", "url", "/users/123")
 
 	// Output:
-	// 20:41:28.515 main     INF | Hello, World!
-	// 20:41:28.515 main     WRN | High temp temp=30
-	// 20:41:28.515 main     ERR | Failed to read file error=file not found
-	// 20:41:28.515 server   INF | Request received method=GET url=/users/123
+	// 20:41:28.515 main     |INF| Hello, World!
+	// 20:41:28.515 main     |WRN| High temp temp=30
+	// 20:41:28.515 main     |ERR| Failed to read file error=file not found
+	// 20:41:28.515 server   |INF| Request received method=GET url=/users/123
 }

v2/handler_options_test.go

@@ -209,6 +209,7 @@ func TestLevels_UnmarshalText(t *testing.T) {
 }
 
 func TestHandlerOptions_UnmarshalJSON(t *testing.T) {
+	theme := console.NewDefaultTheme()
 	tests := []struct {
 		name     string
 		confJSON string
@@ -234,8 +235,9 @@ func TestHandlerOptions_UnmarshalJSON(t *testing.T) {
 		{
 			name:     "dev defaults",
 			confJSON: `{"development":true}`,
-			expected: DevDefaults(),
-			want:     "         \x1b[32mINF\x1b[0m \x1b[1;90m|\x1b[0m \x1b[1mhi\x1b[0m\n",
+			expected: *DevDefaults(),
+			want: styled("|", theme.Header) + styled("INF", theme.LevelInfo) + styled("|", theme.Header) + " " +
+				styled("hi", theme.Message) + "\n",
 		},
 		{
 			name:     "int level",

v2/middleware.go

@@ -56,6 +56,27 @@ import (
 // 	return err, ok
 // }
 
+// AbbreviateLevel is a ReplaceAttr function that abbreviates log level names.
+//
+// It modifies the attribute if it's a log level (slog.Level) and changes the level name to its abbreviation.
+// The abbreviations are:
+//
+//   - "DEBUG" becomes "DBG"
+//   - "INFO" becomes "INF"
+//   - "WARN" becomes "WRN"
+//   - "ERROR" becomes "ERR"
+//
+// If the attribute's value is not a slog.Level, it is returned unchanged.
+//
+// Example:
+//
+//	// Create a logger with the ReplaceAttr function.
+//	logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
+//		ReplaceAttr: AbbreviateLevel,
+//	}))
+//
+//	// Log a message.
+//	logger.Debug("This is a debug message.") // Output will be: level=DBG msg="This is a debug message."
 func AbbreviateLevel(_ []string, attr slog.Attr) slog.Attr {
 	if attr.Value.Kind() != slog.KindAny {
 		return attr
@@ -79,6 +100,46 @@ func AbbreviateLevel(_ []string, attr slog.Attr) slog.Attr {
 	return attr
 }
 
+// FormatTimes returns a ReplaceAttr function that formats time values according to the specified format.
+//
+// It modifies an attribute if its value is a time.Time. The time is formatted using the provided format string,
+// and the attribute's value is updated to the formatted time string.
+//
+// If the attribute's value is not a time.Time, it is returned unchanged.
+//
+// Args:
+//
+//	format string: The format string to use for formatting time values (e.g., time.DateTime, "2006-01-02", "15:04:05").
+//
+// Returns:
+//
+//	func([]string, slog.Attr) slog.Attr: A ReplaceAttr function that formats time values.
+//
+// Example:
+//
+//		// Create a ReplaceAttr function that formats times using a custom format.
+//		customTimeFormat := FormatTimes("2006-01-02 15:04:05")
+//
+//		// Create a logger with the ReplaceAttr function.
+//		logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
+//		    ReplaceAttr: customTimeFormat,
+//		}))
+//
+//		// Log a message with a time attribute.
+//		logger.Info("Time example", slog.Time("now", time.Now()))
+//		// Output might be: level=INFO msg="Time example" now="2023-10-27 10:30:00"
+//
+//	 // Create a ReplaceAttr function that formats times using a predefined format.
+//	 dateTimeFormat := FormatTimes(time.DateTime)
+//
+//	 // Create a logger with the ReplaceAttr function.
+//	 logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
+//	     ReplaceAttr: dateTimeFormat,
+//	 }))
+//
+//	 // Log a message with a time attribute.
+//	 logger.Info("Time example", slog.Time("now", time.Now()))
+//	 // Output might be: level=INFO msg="Time example" now="2023-10-27 10:30:00.000"
 func FormatTimes(format string) func([]string, slog.Attr) slog.Attr {
 	return func(_ []string, a slog.Attr) slog.Attr {
 		if a.Value.Kind() == slog.KindTime {
@@ -88,6 +149,20 @@ func FormatTimes(format string) func([]string, slog.Attr) slog.Attr {
 	}
 }
 
+// SimpleTime returns a ReplaceAttr function that formats time values to a simple time format: "15:04:05.000".
+//
+// It's a convenience function that uses FormatTimes internally with a predefined format.
+//
+// Example:
+//
+//	// Create a logger with the ReplaceAttr function.
+//	logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
+//	    ReplaceAttr: SimpleTime(),
+//	}))
+//
+//	// Log a message with a time attribute.
+//	logger.Info("Time example", slog.Time("now", time.Now()))
+//	// Output might be: level=INFO msg="Time example" now="10:30:00.000"
 func SimpleTime() func([]string, slog.Attr) slog.Attr {
 	return FormatTimes("15:04:05.000")
 }