V1 (#23)

* go20 -> go21rc2 * `golang.org/x/exp/slog` -> `log/slog` * doc cleanup * updated go version * updated `go-version` * updated doc --------- Co-authored-by: lmittmann <[email protected]>
lmittmann · Aug 8, 2023 · 8d8bb7d · 8d8bb7d
1 parent 661beec
commit 8d8bb7d
Show file tree

Hide file tree

Showing 6 changed files with 58 additions and 38 deletions.
diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml
@@ -11,7 +11,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-go@v4
         with:
-          go-version: '1.20'
+          go-version: '1.21'
       - name: go fmt
         run: |
           gofmt -s -d . > fmt.out
@@ -27,6 +27,6 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-go@v4
         with:
-          go-version: '1.20'
+          go-version: '1.21'
       - name: go test
         run: TZ="" go test ./... -tags=faketime
diff --git a/README.md b/README.md
@@ -1,63 +1,66 @@
 # `tint`: 🌈 **slog.Handler** that writes tinted logs
 
-[![Go Reference](https://pkg.go.dev/badge/github.com/lmittmann/tint.svg)](https://pkg.go.dev/github.com/lmittmann/tint)
+[![Go Reference](https://pkg.go.dev/badge/github.com/lmittmann/tint.svg)](https://pkg.go.dev/github.com/lmittmann/tint#section-documentation)
 [![Go Report Card](https://goreportcard.com/badge/github.com/lmittmann/tint)](https://goreportcard.com/report/github.com/lmittmann/tint)
 
 <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/3458786/230217128-1ccce237-bf6c-42f5-b026-a86720541584.png">
-    <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/3458786/230217128-1ccce237-bf6c-42f5-b026-a86720541584.png">
-    <img src="https://user-images.githubusercontent.com/3458786/230217128-1ccce237-bf6c-42f5-b026-a86720541584.png">
+    <source media="(prefers-color-scheme: dark)" srcset="https://github.com/lmittmann/tint/assets/3458786/3d42f8d5-8bdf-40db-a16a-1939c88689cb">
+    <source media="(prefers-color-scheme: light)" srcset="https://github.com/lmittmann/tint/assets/3458786/3d42f8d5-8bdf-40db-a16a-1939c88689cb">
+    <img src="https://github.com/lmittmann/tint/assets/3458786/3d42f8d5-8bdf-40db-a16a-1939c88689cb">
 </picture>
 <br>
 <br>
 
-Package `tint` provides a [`slog.Handler`](https://pkg.go.dev/golang.org/x/exp/slog#Handler) that writes tinted (colorized) logs. The output format is inspired by the `zerolog.ConsoleWriter`.
+Package `tint` implements a zero-dependency [`slog.Handler`](https://pkg.go.dev/log/slog#Handler)
+that writes tinted (colorized) logs. Its output format is inspired by the `zerolog.ConsoleWriter` and
+[`slog.TextHandler`](https://pkg.go.dev/log/slog#TextHandler).
 
-The output format can be customized using [`Options`](https://pkg.go.dev/github.com/lmittmann/tint#Options) which is a drop-in replacement for [`slog.HandlerOptions`](https://pkg.go.dev/golang.org/x/exp/slog#HandlerOptions).
+The output format can be customized using [`Options`](https://pkg.go.dev/github.com/lmittmann/tint#Options)
+which is a drop-in replacement for [`slog.HandlerOptions`](https://pkg.go.dev/log/slog#HandlerOptions).
 
 ```
 go get github.com/lmittmann/tint
 ```
 
-> **Note**
->
-> [`slog`](https://pkg.go.dev/golang.org/x/exp/slog) is an experimental structured logging package, that will be added to the **standard library** in **Go 1.21**. See [#56345](https://github.com/golang/go/issues/56345) for tracking the progress.
-
-
 ## Usage
 
 ```go
+w := os.Stderr
+
 // create a new logger
-logger := slog.New(tint.NewHandler(os.Stderr, nil))
+logger := slog.New(tint.NewHandler(w, nil))
 
 // set global logger with custom options
 slog.SetDefault(slog.New(
-    tint.NewHandler(os.Stderr, &tint.Options{
+    tint.NewHandler(w, &tint.Options{
         Level:      slog.LevelDebug,
         TimeFormat: time.Kitchen,
     }),
 ))
 ```
 
-### Customize
+### Customize Attributes
 
 `ReplaceAttr` can be used to alter or drop attributes. If set, it is called on
-each non-group attribute before it is logged. See [`slog.HandlerOptions`](https://pkg.go.dev/golang.org/x/exp/slog#HandlerOptions)
+each non-group attribute before it is logged. See [`slog.HandlerOptions`](https://pkg.go.dev/log/slog#HandlerOptions)
 for details.
 
 ```go
 // create a new logger that doesn't write the time
-logger := slog.New(tint.NewHandler(os.Stderr, &tint.Options{
-    ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
-        if a.Key == slog.TimeKey && len(groups) == 0 {
-            return slog.Attr{}
-        }
-        return a
-    },
-}))
+w := os.Stderr
+logger := slog.New(
+    tint.NewHandler(w, &tint.Options{
+        ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
+            if a.Key == slog.TimeKey && len(groups) == 0 {
+                return slog.Attr{}
+            }
+            return a
+        },
+    }),
+)
 ```
 
-### Automatically Enable/Disable Colors
+### Automatically Enable Colors
 
 Colors are enabled by default and can be disabled using the `Options.NoColor`
 attribute. To automatically enable colors based on the terminal capabilities,

diff --git a/go.mod b/go.mod
@@ -1,5 +1,3 @@
 module github.com/lmittmann/tint
 
-go 1.20
-
-require golang.org/x/exp v0.0.0-20230522175609-2e198f4a06a1
+go 1.21
diff --git a/go.sum b/go.sum
diff --git a/handler.go b/handler.go
@@ -1,10 +1,29 @@
 /*
-Package tint provides a [slog.Handler] that writes tinted logs. The output
-format is inspired by the [zerolog.ConsoleWriter].
+Package tint implements a zero-dependency [slog.Handler] that writes tinted
+(colorized) logs. The output format is inspired by the [zerolog.ConsoleWriter]
+and [slog.TextHandler].
 
 The output format can be customized using [Options], which is a drop-in
 replacement for [slog.HandlerOptions].
 
+# Customize Attributes
+
+Options.ReplaceAttr can be used to alter or drop attributes. If set, it is
+called on each non-group attribute before it is logged.
+See [slog.HandlerOptions] for details.
+
+	w := os.Stderr
+	logger := slog.New(
+		tint.NewHandler(w, &tint.Options{
+			ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
+				if a.Key == slog.TimeKey && len(groups) == 0 {
+					return slog.Attr{}
+				}
+				return a
+			},
+		}),
+	)
+
 # Automatically Enable Colors
 
 Colors are enabled by default and can be disabled using the Options.NoColor
@@ -38,14 +57,13 @@ import (
 	"encoding"
 	"fmt"
 	"io"
+	"log/slog"
 	"path/filepath"
 	"runtime"
 	"strconv"
 	"sync"
 	"time"
 	"unicode"
-
-	"golang.org/x/exp/slog"
 )
 
 // ANSI modes
@@ -78,7 +96,7 @@ type Options struct {
 	Level slog.Leveler
 
 	// ReplaceAttr is called to rewrite each non-group attribute before it is logged.
-	// See https://pkg.go.dev/golang.org/x/exp/slog#HandlerOptions for details.
+	// See https://pkg.go.dev/log/slog#HandlerOptions for details.
 	ReplaceAttr func(groups []string, attr slog.Attr) slog.Attr
 
 	// Time format (Default: time.StampMilli)
@@ -409,7 +427,10 @@ func needsQuoting(s string) bool {
 
 type tintError struct{ error }
 
-// Err returns a tinted slog.Attr.
+// Err returns a tinted (colorized) [slog.Attr] that will be written in red color
+// by the [tint.Handler]. When used with any other [slog.Handler], it behaves as
+//
+//	slog.Any("err", err)
 func Err(err error) slog.Attr {
 	if err != nil {
 		err = tintError{err}

diff --git a/handler_test.go b/handler_test.go
@@ -5,14 +5,14 @@ import (
 	"context"
 	"errors"
 	"io"
+	"log/slog"
 	"os"
 	"strconv"
 	"strings"
 	"testing"
 	"time"
 
 	"github.com/lmittmann/tint"
-	"golang.org/x/exp/slog"
 )
 
 var faketime = time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC)