move slogr into main package

This is necessary to give the context handling functions access to the slogr
functionality. Functions get renamed to match names in the main package
where needed.

The slogr package is now deprecated, but continues to be supported as part of
the logr v1 API by keeping all exported items as wrappers or aliases for the
main package.

Author: pohly

README.md

@@ -94,8 +94,8 @@ logr design but also left out some parts and changed others:
 
 The high-level slog API is explicitly meant to be one of many different APIs
 that can be layered on top of a shared `slog.Handler`. logr is one such
-alternative API, with [interoperability](#slog-interoperability) provided by the [`slogr`](slogr)
-package.
+alternative API, with [interoperability](#slog-interoperability) provided by
+some conversion functions.
 
 ### Inspiration
 
@@ -145,24 +145,24 @@ There are implementations for the following logging libraries:
 ## slog interoperability
 
 Interoperability goes both ways, using the `logr.Logger` API with a `slog.Handler`
-and using the `slog.Logger` API with a `logr.LogSink`. [slogr](./slogr) provides `NewLogr` and
-`NewSlogHandler` API calls to convert between a `logr.Logger` and a `slog.Handler`.
+and using the `slog.Logger` API with a `logr.LogSink`. `FromSlogHandler` and
+`ToSlogHandler` convert between a `logr.Logger` and a `slog.Handler`.
 As usual, `slog.New` can be used to wrap such a `slog.Handler` in the high-level
-slog API. `slogr` itself leaves that to the caller.
+slog API.
 
-## Using a `logr.Sink` as backend for slog
+### Using a `logr.LogSink` as backend for slog
 
 Ideally, a logr sink implementation should support both logr and slog by
-implementing both the normal logr interface(s) and `slogr.SlogSink`.  Because
+implementing both the normal logr interface(s) and `SlogSink`.  Because
 of a conflict in the parameters of the common `Enabled` method, it is [not
 possible to implement both slog.Handler and logr.Sink in the same
 type](https://github.com/golang/go/issues/59110).
 
 If both are supported, log calls can go from the high-level APIs to the backend
-without the need to convert parameters. `NewLogr` and `NewSlogHandler` can
+without the need to convert parameters. `FromSlogHandler` and `ToSlogHandler` can
 convert back and forth without adding additional wrappers, with one exception:
 when `Logger.V` was used to adjust the verbosity for a `slog.Handler`, then
-`NewSlogHandler` has to use a wrapper which adjusts the verbosity for future
+`ToSlogHandler` has to use a wrapper which adjusts the verbosity for future
 log calls.
 
 Such an implementation should also support values that implement specific
@@ -187,13 +187,13 @@ Not supporting slog has several drawbacks:
 These drawbacks are severe enough that applications using a mixture of slog and
 logr should switch to a different backend.
 
-## Using a `slog.Handler` as backend for logr
+### Using a `slog.Handler` as backend for logr
 
 Using a plain `slog.Handler` without support for logr works better than the
 other direction:
 - All logr verbosity levels can be mapped 1:1 to their corresponding slog level
   by negating them.
-- Stack unwinding is done by the `slogr.SlogSink` and the resulting program
+- Stack unwinding is done by the `SlogSink` and the resulting program
   counter is passed to the `slog.Handler`.
 - Names added via `Logger.WithName` are gathered and recorded in an additional
   attribute with `logger` as key and the names separated by slash as value.
@@ -205,7 +205,7 @@ ideally support both `logr.Marshaler` and `slog.Valuer`. If compatibility
 with logr implementations without slog support is not important, then
 `slog.Valuer` is sufficient.
 
-## Context support for slog
+### Context support for slog
 
 Storing a logger in a `context.Context` is not supported by
 slog. `logr.NewContext` and `logr.FromContext` can be used with slog like this
@@ -214,13 +214,13 @@ to fill this gap:
     func HandlerFromContext(ctx context.Context) slog.Handler {
         logger, err := logr.FromContext(ctx)
         if err == nil {
-            return slogr.NewSlogHandler(logger)
+            return ToSlogHandler(logger)
         }
         return slog.Default().Handler()
     }
 
     func ContextWithHandler(ctx context.Context, handler slog.Handler) context.Context {
-        return logr.NewContext(ctx, slogr.NewLogr(handler))
+        return logr.NewContext(ctx, FromSlogHandler(handler))
     }
 
 The downside is that storing and retrieving a `slog.Handler` needs more

slogr/example/main.go renamed to examples/slog/main.go

@@ -28,7 +28,6 @@ import (
 
 	"github.com/go-logr/logr"
 	"github.com/go-logr/logr/funcr"
-	"github.com/go-logr/logr/slogr"
 )
 
 type e struct {
@@ -62,7 +61,7 @@ func main() {
 		Level:     slog.Level(-1),
 	}
 	handler := slog.NewJSONHandler(os.Stderr, &opts)
-	logrLogger := slogr.NewLogr(handler)
+	logrLogger := logr.FromSlogHandler(handler)
 	logrExample(logrLogger)
 
 	logrLogger = funcr.NewJSON(
@@ -72,7 +71,7 @@ func main() {
 			LogTimestamp: true,
 			Verbosity:    1,
 		})
-	slogLogger := slog.New(slogr.NewSlogHandler(logrLogger))
+	slogLogger := slog.New(logr.ToSlogHandler(logrLogger))
 	slogExample(slogLogger)
 }
 
@@ -91,7 +90,7 @@ func logrExample(log logr.Logger) {
 
 func slogExample(log *slog.Logger) {
 	// There's no guarantee that this logs the right source code location.
-	// It works for Go 1.21.0 by compensating in slogr.NewSlogHandler
+	// It works for Go 1.21.0 by compensating in logr.ToSlogHandler
 	// for the additional callers, but those might change.
 	log = log.With("saved", "value")
 	log.Info("1) hello", "val1", 1, "val2", map[string]int{"k": 1})

slogr/sloghandler.go renamed to sloghandler.go

@@ -17,18 +17,16 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-package slogr
+package logr
 
 import (
 	"context"
 	"log/slog"
-
-	"github.com/go-logr/logr"
 )
 
 type slogHandler struct {
 	// May be nil, in which case all logs get discarded.
-	sink logr.LogSink
+	sink LogSink
 	// Non-nil if sink is non-nil and implements SlogSink.
 	slogSink SlogSink
 
@@ -90,15 +88,15 @@ func (l *slogHandler) Handle(ctx context.Context, record slog.Record) error {
 // are called by Handle, code in slog gets skipped.
 //
 // This offset currently (Go 1.21.0) works for calls through
-// slog.New(NewSlogHandler(...)).  There's no guarantee that the call
+// slog.New(ToSlogHandler(...)).  There's no guarantee that the call
 // chain won't change. Wrapping the handler will also break unwinding. It's
 // still better than not adjusting at all....
 //
-// This cannot be done when constructing the handler because NewLogr needs
+// This cannot be done when constructing the handler because FromSlogHandler needs
 // access to the original sink without this adjustment. A second copy would
 // work, but then WithAttrs would have to be called for both of them.
-func (l *slogHandler) sinkWithCallDepth() logr.LogSink {
-	if sink, ok := l.sink.(logr.CallDepthLogSink); ok {
+func (l *slogHandler) sinkWithCallDepth() LogSink {
+	if sink, ok := l.sink.(CallDepthLogSink); ok {
 		return sink.WithCallDepth(2)
 	}
 	return l.sink
@@ -148,21 +146,22 @@ func (l *slogHandler) addGroupPrefix(name string) string {
 
 // levelFromSlog adjusts the level by the logger's verbosity and negates it.
 // It ensures that the result is >= 0. This is necessary because the result is
-// passed to a logr.LogSink and that API did not historically document whether
+// passed to a LogSink and that API did not historically document whether
 // levels could be negative or what that meant.
 //
 // Some example usage:
-//     logrV0 := getMyLogger()
-//     logrV2 := logrV0.V(2)
-//     slogV2 := slog.New(slogr.NewSlogHandler(logrV2))
-//     slogV2.Debug("msg") // =~ logrV2.V(4) =~ logrV0.V(6)
-//     slogV2.Info("msg")  // =~  logrV2.V(0) =~ logrV0.V(2)
-//     slogv2.Warn("msg")  // =~ logrV2.V(-4) =~ logrV0.V(0)
+//
+//	logrV0 := getMyLogger()
+//	logrV2 := logrV0.V(2)
+//	slogV2 := slog.New(logr.ToSlogHandler(logrV2))
+//	slogV2.Debug("msg") // =~ logrV2.V(4) =~ logrV0.V(6)
+//	slogV2.Info("msg")  // =~  logrV2.V(0) =~ logrV0.V(2)
+//	slogv2.Warn("msg")  // =~ logrV2.V(-4) =~ logrV0.V(0)
 func (l *slogHandler) levelFromSlog(level slog.Level) int {
 	result := -level
-	result += l.levelBias // in case the original logr.Logger had a V level
+	result += l.levelBias // in case the original Logger had a V level
 	if result < 0 {
-		result = 0 // because logr.LogSink doesn't expect negative V levels
+		result = 0 // because LogSink doesn't expect negative V levels
 	}
 	return int(result)
 }

slogr.go

@@ -0,0 +1,100 @@
+//go:build go1.21
+// +build go1.21
+
+/*
+Copyright 2023 The logr Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package logr
+
+import (
+	"context"
+	"log/slog"
+)
+
+// FromSlogHandler returns a Logger which writes to the slog.Handler.
+//
+// The logr verbosity level is mapped to slog levels such that V(0) becomes
+// slog.LevelInfo and V(4) becomes slog.LevelDebug.
+func FromSlogHandler(handler slog.Handler) Logger {
+	if handler, ok := handler.(*slogHandler); ok {
+		if handler.sink == nil {
+			return Discard()
+		}
+		return New(handler.sink).V(int(handler.levelBias))
+	}
+	return New(&slogSink{handler: handler})
+}
+
+// ToSlogHandler returns a slog.Handler which writes to the same sink as the Logger.
+//
+// The returned logger writes all records with level >= slog.LevelError as
+// error log entries with LogSink.Error, regardless of the verbosity level of
+// the Logger:
+//
+//	logger := <some Logger with 0 as verbosity level>
+//	slog.New(ToSlogHandler(logger.V(10))).Error(...) -> logSink.Error(...)
+//
+// The level of all other records gets reduced by the verbosity
+// level of the Logger and the result is negated. If it happens
+// to be negative, then it gets replaced by zero because a LogSink
+// is not expected to handled negative levels:
+//
+//	slog.New(ToSlogHandler(logger)).Debug(...) -> logger.GetSink().Info(level=4, ...)
+//	slog.New(ToSlogHandler(logger)).Warning(...) -> logger.GetSink().Info(level=0, ...)
+//	slog.New(ToSlogHandler(logger)).Info(...) -> logger.GetSink().Info(level=0, ...)
+//	slog.New(ToSlogHandler(logger.V(4))).Info(...) -> logger.GetSink().Info(level=4, ...)
+func ToSlogHandler(logger Logger) slog.Handler {
+	if sink, ok := logger.GetSink().(*slogSink); ok && logger.GetV() == 0 {
+		return sink.handler
+	}
+
+	handler := &slogHandler{sink: logger.GetSink(), levelBias: slog.Level(logger.GetV())}
+	if slogSink, ok := handler.sink.(SlogSink); ok {
+		handler.slogSink = slogSink
+	}
+	return handler
+}
+
+// SlogSink is an optional interface that a LogSink can implement to support
+// logging through the slog.Logger or slog.Handler APIs better. It then should
+// also support special slog values like slog.Group. When used as a
+// slog.Handler, the advantages are:
+//
+//   - stack unwinding gets avoided in favor of logging the pre-recorded PC,
+//     as intended by slog
+//   - proper grouping of key/value pairs via WithGroup
+//   - verbosity levels > slog.LevelInfo can be recorded
+//   - less overhead
+//
+// Both APIs (Logger and slog.Logger/Handler) then are supported equally
+// well. Developers can pick whatever API suits them better and/or mix
+// packages which use either API in the same binary with a common logging
+// implementation.
+//
+// This interface is necessary because the type implementing the LogSink
+// interface cannot also implement the slog.Handler interface due to the
+// different prototype of the common Enabled method.
+//
+// An implementation could support both interfaces in two different types, but then
+// additional interfaces would be needed to convert between those types in FromSlogHandler
+// and ToSlogHandler.
+type SlogSink interface {
+	LogSink
+
+	Handle(ctx context.Context, record slog.Record) error
+	WithAttrs(attrs []slog.Attr) SlogSink
+	WithGroup(name string) SlogSink
+}

slogr/slogr.go

@@ -23,86 +23,32 @@ limitations under the License.
 //
 // See the README in the top-level [./logr] package for a discussion of
 // interoperability.
+//
+// Deprecated: use the main logr package instead.
 package slogr
 
 import (
-	"context"
 	"log/slog"
 
 	"github.com/go-logr/logr"
 )
 
 // NewLogr returns a logr.Logger which writes to the slog.Handler.
 //
-// The logr verbosity level is mapped to slog levels such that V(0) becomes
-// slog.LevelInfo and V(4) becomes slog.LevelDebug.
+// Deprecated: use [logr.FromSlogHandler] instead.
 func NewLogr(handler slog.Handler) logr.Logger {
-	if handler, ok := handler.(*slogHandler); ok {
-		if handler.sink == nil {
-			return logr.Discard()
-		}
-		return logr.New(handler.sink).V(int(handler.levelBias))
-	}
-	return logr.New(&slogSink{handler: handler})
+	return logr.FromSlogHandler(handler)
 }
 
-// NewSlogHandler returns a slog.Handler which writes to the same sink as the logr.Logger.
-//
-// The returned logger writes all records with level >= slog.LevelError as
-// error log entries with LogSink.Error, regardless of the verbosity level of
-// the logr.Logger:
-//
-//	logger := <some logr.Logger with 0 as verbosity level>
-//	slog.New(NewSlogHandler(logger.V(10))).Error(...) -> logSink.Error(...)
+// ToSlogHandler returns a slog.Handler which writes to the same sink as the logr.Logger.
 //
-// The level of all other records gets reduced by the verbosity
-// level of the logr.Logger and the result is negated. If it happens
-// to be negative, then it gets replaced by zero because a LogSink
-// is not expected to handled negative levels:
-//
-//	slog.New(NewSlogHandler(logger)).Debug(...) -> logger.GetSink().Info(level=4, ...)
-//	slog.New(NewSlogHandler(logger)).Warning(...) -> logger.GetSink().Info(level=0, ...)
-//	slog.New(NewSlogHandler(logger)).Info(...) -> logger.GetSink().Info(level=0, ...)
-//	slog.New(NewSlogHandler(logger.V(4))).Info(...) -> logger.GetSink().Info(level=4, ...)
-func NewSlogHandler(logger logr.Logger) slog.Handler {
-	if sink, ok := logger.GetSink().(*slogSink); ok && logger.GetV() == 0 {
-		return sink.handler
-	}
-
-	handler := &slogHandler{sink: logger.GetSink(), levelBias: slog.Level(logger.GetV())}
-	if slogSink, ok := handler.sink.(SlogSink); ok {
-		handler.slogSink = slogSink
-	}
-	return handler
+// Deprecated: use [logr.ToSlogHandler] instead.
+func ToSlogHandler(logger logr.Logger) slog.Handler {
+	return logr.ToSlogHandler(logger)
 }
 
 // SlogSink is an optional interface that a LogSink can implement to support
-// logging through the slog.Logger or slog.Handler APIs better. It then should
-// also support special slog values like slog.Group. When used as a
-// slog.Handler, the advantages are:
+// logging through the slog.Logger or slog.Handler APIs better.
 //
-//   - stack unwinding gets avoided in favor of logging the pre-recorded PC,
-//     as intended by slog
-//   - proper grouping of key/value pairs via WithGroup
-//   - verbosity levels > slog.LevelInfo can be recorded
-//   - less overhead
-//
-// Both APIs (logr.Logger and slog.Logger/Handler) then are supported equally
-// well. Developers can pick whatever API suits them better and/or mix
-// packages which use either API in the same binary with a common logging
-// implementation.
-//
-// This interface is necessary because the type implementing the LogSink
-// interface cannot also implement the slog.Handler interface due to the
-// different prototype of the common Enabled method.
-//
-// An implementation could support both interfaces in two different types, but then
-// additional interfaces would be needed to convert between those types in NewLogr
-// and NewSlogHandler.
-type SlogSink interface {
-	logr.LogSink
-
-	Handle(ctx context.Context, record slog.Record) error
-	WithAttrs(attrs []slog.Attr) SlogSink
-	WithGroup(name string) SlogSink
-}
+// Deprecated: use [logr.SlogSink] instead.
+type SlogSink = logr.SlogSink