infra

README

Infrastructure

This package contains infrastructure shared by various packages. The main packages sharing this code are verify and bench. The definitions in this package are publicly visible and may in some cases be usable elsewhere.

Attributes

A few useful items relating to slog.Attr:

• AttrFn defines a type useful when working with HandlerOptions.ReplaceAttr functionality.
• The EmptyAttr function returns a new empty slog.Attr object.

Creator

A Creator object is a factory used to generate slog.Logger objects for testing. A number of predefined Creator objects can be found in the creator package. The simplest of these returns loggers for the slog.NewJSONHandler handler.

Creation of a new infra.Creator object is fairly simple. The infra.NewCreator function takes the name of the handler package and one or two functions as appropriate:

• A CreateHandlerFn creates a new slog.Handler.
• A CreateLoggerFn creates a new slog.Logger.

At least one of the two is required, though the CreateHandlerFn is preferred, as in the following example:

package creator

import (
	"io"
	"log/slog"

	"github.com/madkins23/go-slog/infra"
)

// Slog returns a Creator object for the log/slog.JSONHandler.
func Slog() infra.Creator {
	return infra.NewCreator("log/slog.JSONHandler", SlogHandlerFn, nil)
}

func SlogHandlerFn(w io.Writer, options *slog.HandlerOptions) slog.Handler {
	return slog.NewJSONHandler(w, options)
}

Creator factories can generate both slog.Handler and slog.Logger objects. Most tests use the latter, but a few tests require the former.

• If only a CreateLoggerFn is provided the Creator.NewHandler method returns nil and the Creator.CanMakeHandler method returns false. Tests requiring handler creation use the latter method to skip the test.
• If only a CreateHandlerFn is provided the Creator.NewHandler method uses that function to return a new handler and the Creator.NewLogger method also uses that function, then wraps the handler in slog.New.
• If both functions are provided, they will each be used for the appropriate method. This has yet to be required.

The reason for two functions is the possibility that an slog.Logger is available but a slog.Handler is not. This handler is implemented directly as a slog.Logger, without defining a slog.Handler interface.[^1]

Options

The options package provides some predefined slog.HandlerOptions objects. These are used in testing and benchmarks and may have some utility elsewhere.

---

[^1]: This may or may not be a desirable thing. On the one hand, there is a lot of useful code in the slog package outside the handler. On the other hand, replacing that code might provide some advantage.

Documentation

Overview

Package infra contains functionality shared between test and benchmark managers.

• Convenient definitions for:
• AttrFn defines the slog.HandlerOptions.ReplaceAttr function template.
• EmptyAttr() returns an empty attribute.
• Creator struct and instances thereof for specific slog.Handlers.
• Functions to return slog.HandlerOptions of general utility.

Index

• func EmptyAttr() slog.Attr
• func LevelOptions(level slog.Leveler) *slog.HandlerOptions
• func ReplaceAttrOptions(fn AttrFn) *slog.HandlerOptions
• func SimpleOptions() *slog.HandlerOptions
• func SourceOptions() *slog.HandlerOptions
• type AttrFn
• type CreateHandlerFn
• type CreateLoggerFn
• type Creator
  • func NewCreator(name string, handlerFn CreateHandlerFn, loggerFn CreateLoggerFn) Creator
  • func (c *Creator) CanMakeHandler() bool
  • func (c *Creator) Name() string
  • func (c *Creator) NewHandler(w io.Writer, options *slog.HandlerOptions) slog.Handler
  • func (c *Creator) NewLogger(w io.Writer, options *slog.HandlerOptions) *slog.Logger

Functions

func EmptyAttr

func EmptyAttr() slog.Attr

EmptyAttr returns an empty attribute object as a convenience.

func LevelOptions

func LevelOptions(level slog.Leveler) *slog.HandlerOptions

LevelOptions returns a slog.HandlerOptions with the specified level.

func ReplaceAttrOptions

func ReplaceAttrOptions(fn AttrFn) *slog.HandlerOptions

ReplaceAttrOptions returns a slog.HandlerOptions with the specified ReplaceAttr function.

func SimpleOptions

func SimpleOptions() *slog.HandlerOptions

SimpleOptions returns a default, simple, slog.HandlerOptions.

func SourceOptions

func SourceOptions() *slog.HandlerOptions

SourceOptions returns a slog.HandlerOptions with the specified level and the AddSource field set to true.

Types

type AttrFn

type AttrFn func(groups []string, a slog.Attr) slog.Attr

AttrFn defines a type for ReplaceAttr functions. The slog.HandlersOptions struct defines this inline without defining a type.

type CreateHandlerFn

type CreateHandlerFn func(w io.Writer, options *slog.HandlerOptions) slog.Handler

CreateHandlerFn is a function that can create new slog.Handler objects.

type CreateLoggerFn

type CreateLoggerFn func(w io.Writer, options *slog.HandlerOptions) *slog.Logger

CreateLoggerFn is a function that can create new slog.Logger objects.

type Creator

type Creator struct {
	// contains filtered or unexported fields
}

A Creator object encapsulates the creation of new slog.Handler objects. This includes both the name of the handler and a CreateLoggerFn.

func NewCreator

func NewCreator(name string, handlerFn CreateHandlerFn, loggerFn CreateLoggerFn) Creator

NewCreator returns a new Creator object for the specified name and CreateLoggerFn.

func (*Creator) CanMakeHandler

func (c *Creator) CanMakeHandler() bool

func (*Creator) Name

func (c *Creator) Name() string

Name returns the name of the slog package.

func (*Creator) NewHandler

func (c *Creator) NewHandler(w io.Writer, options *slog.HandlerOptions) slog.Handler

NewHandler returns a new slog.Handler object. The actual creation is done by invoking the embedded CreateHandlerFn.

func (*Creator) NewLogger

func (c *Creator) NewLogger(w io.Writer, options *slog.HandlerOptions) *slog.Logger

NewLogger returns a new slog.Logger object. The actual creation is done by invoking the embedded CreateLoggerFn, if it is non-nil, or the embedded CreateHandlerFn.