From ea2d4a7ef674b4a0ea0e53ffecbc63320b91f25f Mon Sep 17 00:00:00 2001 From: Jonathan Amsterdam Date: Tue, 21 Mar 2023 19:27:30 -0400 Subject: [PATCH] log/slog: clarify the limits of TextHandler output parseability Give an example illustrating the problem with dots inside groups or keys. Clarify that to fix it in general, you need to do more than escape the keys, since that won't distinguish the group "a.b" from the two groups "a" and "b". Updates #56345. Change-Id: Ide301899c548d50b0a1f18e93e93d6e11ad485cf Reviewed-on: https://go-review.googlesource.com/c/go/+/478199 Reviewed-by: Alan Donovan Run-TryBot: Jonathan Amsterdam TryBot-Result: Gopher Robot --- src/log/slog/text_handler.go | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/src/log/slog/text_handler.go b/src/log/slog/text_handler.go index 307d5c9d75..739c662f85 100644 --- a/src/log/slog/text_handler.go +++ b/src/log/slog/text_handler.go @@ -68,7 +68,7 @@ func (h *TextHandler) WithGroup(name string) Handler { // 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". +// The message's key is "msg". // // To modify these or other attributes, or remove them from the output, use // [HandlerOptions.ReplaceAttr]. @@ -80,9 +80,13 @@ func (h *TextHandler) WithGroup(name string) Handler { // characters, non-printing characters, '"' or '='. // // Keys inside groups consist of components (keys or group names) separated by -// dots. No further escaping is performed. If it is necessary to reconstruct the -// group structure of a key even in the presence of dots inside components, use -// [HandlerOptions.ReplaceAttr] to escape the keys. +// dots. No further escaping is performed. +// Thus there is no way to determine from the key "a.b.c" whether there +// are two groups "a" and "b" and a key "c", or a single group "a.b" and a key "c", +// or single group "a" and a key "b.c". +// If it is necessary to reconstruct the group structure of a key +// even in the presence of dots inside components, use +// [HandlerOptions.ReplaceAttr] to encode that information in the key. // // Each call to Handle results in a single serialized call to // io.Writer.Write. -- 2.51.0