slog: TextHandler

A Handler that writes Records as ordinary text lines.

Also, revise the common handler code. The previous approach required a
stateful appender, which couldn't easily be both zero-alloc and
concurrency-safe.

Change-Id: Ibe2749e2744a560086acec9287a18dd434ba9aa8
Reviewed-on: https://go-review.googlesource.com/c/exp/+/429435
Run-TryBot: Jonathan Amsterdam <[email protected]>
Reviewed-by: Alan Donovan <[email protected]>

Author: jba

slog/handler.go

@@ -88,7 +88,7 @@ type HandlerOptions struct {
 }
 
 type commonHandler struct {
-	appender
+	newAppender       func(*buffer.Buffer) appender
 	opts              HandlerOptions
 	attrs             []Attr
 	preformattedAttrs []byte
@@ -104,7 +104,7 @@ func (h *commonHandler) Enabled(l Level) bool {
 
 func (h *commonHandler) with(as []Attr) *commonHandler {
 	h2 := &commonHandler{
-		appender:          h.appender,
+		newAppender:       h.newAppender,
 		opts:              h.opts,
 		attrs:             concat(h.attrs, as),
 		preformattedAttrs: h.preformattedAttrs,
@@ -117,68 +117,66 @@ func (h *commonHandler) with(as []Attr) *commonHandler {
 	}
 
 	// Pre-format the attributes as an optimization.
-	h2.setBuffer((*buffer.Buffer)(&h2.preformattedAttrs))
+	app := h2.newAppender((*buffer.Buffer)(&h2.preformattedAttrs))
 	for _, p := range h2.attrs[len(h.attrs):] {
-		h2.appendAttr(p)
+		appendAttr(app, p)
 	}
 	return h2
 }
 
 func (h *commonHandler) handle(r Record) error {
 	buf := buffer.New()
 	defer buf.Free()
-	h.setBuffer(buf)
-
+	app := h.newAppender(buf)
 	rep := h.opts.ReplaceAttr
-
 	replace := func(a Attr) {
 		a = rep(a)
 		if a.Key() != "" {
-			h.appendKey(a.Key())
-			h.appendAttrValue(a)
+			app.appendKey(a.Key())
+			app.appendAttrValue(a)
 		}
 	}
 
-	h.appendStart()
+	app.appendStart()
 	if !r.Time().IsZero() {
 		key := "time"
 		val := r.Time().Round(0) // strip monotonic to match Attr behavior
 		if rep == nil {
-			h.appendKey(key)
-			h.appendTime(val)
+			app.appendKey(key)
+			app.appendTime(val)
 		} else {
 			replace(Time(key, val))
 		}
-		h.appendSep()
+		app.appendSep()
 	}
 	if r.Level() != 0 {
 		key := "level"
 		val := r.Level()
 		if rep == nil {
-			h.appendKey(key)
-			h.appendString(val.String())
+			app.appendKey(key)
+			app.appendString(val.String())
 		} else {
 			// Don't use replace: we want to output Levels as strings
 			// to match the above.
 			a := rep(Any(key, val))
 			if a.Key() != "" {
-				h.appendKey(a.Key())
+				app.appendKey(a.Key())
 				if l, ok := a.any.(Level); ok {
-					h.appendString(l.String())
+					app.appendString(l.String())
 				} else {
-					h.appendAttrValue(a)
+					app.appendAttrValue(a)
 				}
 			}
 		}
-		h.appendSep()
+		app.appendSep()
 	}
 	if h.opts.AddSource {
 		file, line := r.SourceLine()
 		if file != "" {
 			key := "source"
 			if rep == nil {
-				h.appendKey(key)
-				h.appendSource(file, line)
+				app.appendKey(key)
+				app.appendSource(file, line)
 			} else {
 				buf := buffer.New()
 				buf.WriteString(file)
@@ -188,14 +186,14 @@ func (h *commonHandler) handle(r Record) error {
 				buf.Free()
 				replace(String(key, s))
 			}
-			h.appendSep()
+			app.appendSep()
 		}
 	}
 	key := "msg"
 	val := r.Message()
 	if rep == nil {
-		h.appendKey(key)
-		h.appendString(val)
+		app.appendKey(key)
+		app.appendString(val)
 	} else {
 		replace(String(key, val))
 	}
@@ -205,9 +203,9 @@ func (h *commonHandler) handle(r Record) error {
 		if rep != nil {
 			a = rep(a)
 		}
-		h.appendAttr(a)
+		appendAttr(app, a)
 	}
-	h.appendEnd()
+	app.appendEnd()
 	buf.WriteByte('\n')
 
 	h.mu.Lock()
@@ -216,20 +214,19 @@ func (h *commonHandler) handle(r Record) error {
 	return err
 }
 
-func (h *commonHandler) appendAttr(a Attr) {
+func appendAttr(app appender, a Attr) {
 	if a.Key() != "" {
-		h.appendSep()
-		h.appendKey(a.Key())
-		if err := h.appendAttrValue(a); err != nil {
-			h.appendString(fmt.Sprintf("!ERROR:%v", err))
+		app.appendSep()
+		app.appendKey(a.Key())
+		if err := app.appendAttrValue(a); err != nil {
+			app.appendString(fmt.Sprintf("!ERROR:%v", err))
 		}
 	}
 }
 
 // An appender appends keys and values to a buffer.
 // TextHandler and JSONHandler both implement it.
 type appender interface {
-	setBuffer(*buffer.Buffer)           // set the buffer to use for output
 	appendStart()                       // start a sequence of Attrs
 	appendEnd()                         // end a sequence of Attrs
 	appendSep()                         // separate one Attr from the next

slog/handler_test.go

@@ -87,7 +87,7 @@ func TestCommonHandle(t *testing.T) {
 		t.Run(test.name, func(t *testing.T) {
 			ma := &memAppender{m: map[string]any{}}
 			test.h.w = &bytes.Buffer{}
-			test.h.appender = ma
+			test.h.newAppender = func(*buffer.Buffer) appender { return ma }
 			if err := test.h.handle(r); err != nil {
 				t.Fatal(err)
 			}
@@ -105,8 +105,6 @@ type memAppender struct {
 
 func (a *memAppender) set(v any) { a.m[a.key] = v }
 
-func (a *memAppender) setBuffer(*buffer.Buffer) {}
-
 func (a *memAppender) appendStart()           {}
 func (a *memAppender) appendSep()             {}
 func (a *memAppender) appendEnd()             {}

slog/text_handler.go

@@ -0,0 +1,142 @@
+// Copyright 2022 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package slog
+
+import (
+	"encoding"
+	"fmt"
+	"io"
+	"strconv"
+	"strings"
+	"time"
+	"unicode"
+
+	"golang.org/x/exp/slog/internal/buffer"
+)
+
+// TextHandler is a Handler that writes Records to an io.Writer as a
+// sequence of key=value pairs separated by spaces and followed by a newline.
+type TextHandler struct {
+	*commonHandler
+}
+
+// NewTextHandler creates a TextHandler that writes to w,
+// using the default options.
+func NewTextHandler(w io.Writer) *TextHandler {
+	return (HandlerOptions{}).NewTextHandler(w)
+}
+
+// NewTextHandler creates a TextHandler with the given options that writes to w.
+func (opts HandlerOptions) NewTextHandler(w io.Writer) *TextHandler {
+	return &TextHandler{
+		&commonHandler{
+			newAppender: func(buf *buffer.Buffer) appender { return (*textAppender)(buf) },
+			w:           w,
+			opts:        opts,
+		},
+	}
+}
+
+// With returns a new TextHandler whose attributes consists
+// of h's attributes followed by attrs.
+func (h *TextHandler) With(attrs []Attr) Handler {
+	return &TextHandler{commonHandler: h.commonHandler.with(attrs)}
+}
+
+// Handle formats its argument Record as a single line of space-separated
+// key=value items.
+//
+// If the Record's time is zero, the time is omitted.
+// Otherwise, the key is "time"
+// and the value is output in RFC3339 format with millisecond precision.
+//
+// If the Record's level is zero, the level is omitted.
+// Otherwise, the key is "level"
+// and the value of [Level.String] is output.
+//
+// If the AddSource option is set and source information is available,
+// the key is "source" and the value is output as FILE:LINE.
+//
+// The message's key "msg".
+//
+// To modify these or other attributes, or remove them from the output, use
+// [HandlerOptions.ReplaceAttr].
+//
+// If a value implements [encoding.TextMarshaler], the result of MarshalText is
+// written. Otherwise, the result of fmt.Sprint is written.
+//
+// Keys and values are quoted if they are long or contain Unicode space
+// characters, '"' or '='.
+//
+// Each call to Handle results in a single serialized call to
+// io.Writer.Write.
+func (h *TextHandler) Handle(r Record) error {
+	return h.commonHandler.handle(r)
+}
+
+type textAppender buffer.Buffer
+
+func (a *textAppender) buf() *buffer.Buffer { return (*buffer.Buffer)(a) }
+
+func (a *textAppender) appendKey(key string) {
+	a.appendString(key)
+	a.buf().WriteByte('=')
+}
+
+func (a *textAppender) appendString(s string) {
+	if needsQuoting(s) {
+		*a.buf() = strconv.AppendQuote(*a.buf(), s)
+	} else {
+		a.buf().WriteString(s)
+	}
+}
+
+func needsQuoting(s string) bool {
+	return len(s) > maxCheckQuoteSize ||
+		strings.IndexFunc(s, func(r rune) bool {
+			return unicode.IsSpace(r) || r == '"' || r == '='
+		}) >= 0
+}
+
+func (a *textAppender) appendStart() {}
+func (a *textAppender) appendEnd()   {}
+func (a *textAppender) appendSep()   { a.buf().WriteByte(' ') }
+
+const maxCheckQuoteSize = 80
+
+func (a *textAppender) appendTime(t time.Time) {
+	*a.buf() = appendTimeRFC3339Millis(*a.buf(), t)
+}
+
+func (a *textAppender) appendSource(file string, line int) {
+	a.appendString(file)
+	a.buf().WriteByte(':')
+	itoa((*[]byte)(a.buf()), line, -1)
+}
+
+func (ap *textAppender) appendAttrValue(a Attr) error {
+	switch a.Kind() {
+	case StringKind:
+		ap.appendString(a.str())
+		return nil
+	case TimeKind:
+		ap.appendTime(a.Time())
+	case AnyKind:
+		if tm, ok := a.any.(encoding.TextMarshaler); ok {
+			data, err := tm.MarshalText()
+			if err != nil {
+				ap.appendString("!ERROR:" + err.Error())
+			} else {
+				// TODO: avoid the conversion to string.
+				ap.appendString(string(data))
+			}
+			return nil
+		}
+		ap.appendString(fmt.Sprint(a.Value()))
+	default:
+		*ap.buf() = a.AppendValue(*ap.buf())
+	}
+	return nil
+}