Documentation
¶
Overview ¶
Package log provides a slog.Handler for structured, human-readable CLI output.
CLIHandler formats time, level, source, label, and message as built-in output components, followed by ordinary attributes with dot-separated group names. Style controls their appearance; AttrReplacer applies only to ordinary attributes. Configured colors are enabled for terminal files and omitted for other writers.
Pass the result of NewCLIHandler to slog.New to create a logger.
Index ¶
- Constants
- func NewCLIHandler(w io.Writer, opts ...CLIHandlerOption) slog.Handler
- type AffixStyle
- type AttrReplacer
- type AttrStyle
- type CLIHandler
- type CLIHandlerOption
- func WithAttrReplacer(replacer AttrReplacer) CLIHandlerOption
- func WithLabel(label string) CLIHandlerOption
- func WithLevel(level slog.Leveler) CLIHandlerOption
- func WithSourceFunction() CLIHandlerOption
- func WithSourcePath() CLIHandlerOption
- func WithStyle(s *Style) CLIHandlerOption
- func WithTime() CLIHandlerOption
- func WithTimeLayout(layout string) CLIHandlerOption
- type Color
- type LabelStyle
- type LevelStyle
- type MessageStyle
- type SourceStyle
- type Style
- type StyleOption
- func WithAttrStyle(value AttrStyle) StyleOption
- func WithLabelStyle(value LabelStyle) StyleOption
- func WithLevelStyle(value map[slog.Level]LevelStyle) StyleOption
- func WithMessageStyle(value MessageStyle) StyleOption
- func WithSourceStyle(value SourceStyle) StyleOption
- func WithTimeStyle(value TimeStyle) StyleOption
- type TimeStyle
Constants ¶
const ( CodeReset = 0 CodeBold = 1 CodeFaint = 2 CodeItalic = 3 CodeUnderline = 4 CodeBlinkSlow = 5 CodeBlinkRapid = 6 CodeReverseVideo = 7 CodeConcealed = 8 CodeCrossedOut = 9 CodeFgBlack = 30 CodeFgRed = 31 CodeFgGreen = 32 CodeFgYellow = 33 CodeFgBlue = 34 CodeFgMagenta = 35 CodeFgCyan = 36 CodeFgWhite = 37 CodeFgHiBlack = 90 CodeFgHiRed = 91 CodeFgHiGreen = 92 CodeFgHiYellow = 93 CodeFgHiBlue = 94 CodeFgHiMagenta = 95 CodeFgHiCyan = 96 CodeFgHiWhite = 97 CodeBgBlack = 40 CodeBgRed = 41 CodeBgGreen = 42 CodeBgYellow = 43 CodeBgBlue = 44 CodeBgMagenta = 45 CodeBgCyan = 46 CodeBgWhite = 47 CodeBgHiBlack = 100 CodeBgHiRed = 101 CodeBgHiGreen = 102 CodeBgHiYellow = 103 CodeBgHiBlue = 104 CodeBgHiMagenta = 105 CodeBgHiCyan = 106 CodeBgHiWhite = 107 )
SGR (Select Graphic Rendition) codes accepted by NewColor. Fg and Bg select foreground and background colors; Hi selects bright colors.
const Version = "0.0.1"
Version is the version of this package.
Variables ¶
This section is empty.
Functions ¶
func NewCLIHandler ¶
func NewCLIHandler(w io.Writer, opts ...CLIHandlerOption) slog.Handler
NewCLIHandler returns a handler that writes to w using opts. A nil w discards output. Zero-valued options are ignored.
By default, the handler uses DefaultStyle and a minimum level of slog.LevelInfo, with time, source, and label output disabled. Terminal detection requires an *os.File; terminal output is adapted for Windows when needed.
Types ¶
type AffixStyle ¶
AffixStyle decorates a literal prefix or suffix. Text is written verbatim, and Color applies only to Text. Empty Text produces no output; a nil Color adds no color.
type AttrReplacer ¶
AttrReplacer replaces each non-group ordinary attribute before formatting. It does not receive the built-in time, level, source, label, or message. Ordinary attributes with those names are still passed to the replacer.
slog.LogValuer values are resolved before and after the call. Returning a zero slog.Attr removes the attribute. If the result is a group, its children are traversed and each non-group child is passed to the replacer.
The groups slice contains the original enclosing group names, outermost first. The replacer must not modify or retain this slice. Empty group names are omitted. Calls may run concurrently, so the replacer must protect any shared mutable state.
type AttrStyle ¶
AttrStyle decorates ordinary attributes without affecting built-in output. KeyColor also applies to the group path and separator. Separator is written verbatim; an empty value adds nothing.
type CLIHandler ¶
type CLIHandler struct {
// contains filtered or unexported fields
}
CLIHandler implements slog.Handler for human-readable CLI output. Create a handler with NewCLIHandler; the zero value is not ready for use.
Its methods are safe for concurrent use. CLIHandler.WithAttrs and CLIHandler.WithGroup preserve the original attributes and groups while sharing the output lock and source cache. Separately constructed handlers use separate locks.
func (*CLIHandler) Enabled ¶
Enabled reports whether level meets the configured minimum. It reads the level threshold on each call and ignores the context.
func (*CLIHandler) Handle ¶
Handle formats record and writes the result, followed by a newline. It returns any write error, including io.ErrShortWrite for a partial write. It ignores the context and does not check the minimum level.
type CLIHandlerOption ¶
type CLIHandlerOption struct {
// contains filtered or unexported fields
}
CLIHandlerOption configures a CLIHandler. Its zero value has no effect.
func WithAttrReplacer ¶
func WithAttrReplacer(replacer AttrReplacer) CLIHandlerOption
WithAttrReplacer sets the replacer for ordinary attributes. By default, attributes are not replaced. A nil replacer leaves the current setting unchanged. See AttrReplacer for its scope and concurrency requirements.
func WithLabel ¶
func WithLabel(label string) CLIHandlerOption
WithLabel sets the label displayed before the message. An empty label, the default, omits the label and its decoration. The label is written verbatim and should contain only trusted text.
func WithLevel ¶
func WithLevel(level slog.Leveler) CLIHandlerOption
WithLevel sets the minimum level accepted by the handler. The default is slog.LevelInfo. A nil level leaves the current setting unchanged. Level is read on each enabled check, allowing updates through slog.LevelVar. Custom implementations must support concurrent Level calls.
func WithSourceFunction ¶
func WithSourceFunction() CLIHandlerOption
WithSourceFunction enables the source function name and line number. Source output is disabled by default and omitted when a record has no location. The name is used as reported by the runtime, without shortening, and escaped when necessary. If multiple source options are specified, the last one wins.
func WithSourcePath ¶
func WithSourcePath() CLIHandlerOption
WithSourcePath enables the source file path and line number. Source output is disabled by default and omitted when a record has no location. The path is used as reported by the runtime, without shortening, and escaped when necessary. If multiple source options are specified, the last one wins.
func WithStyle ¶
func WithStyle(s *Style) CLIHandlerOption
WithStyle sets the output style, replacing DefaultStyle. A nil s leaves the current setting unchanged.
func WithTime ¶
func WithTime() CLIHandlerOption
WithTime enables the built-in timestamp, which is disabled by default. A record with a zero Time still omits the timestamp and its decoration.
func WithTimeLayout ¶
func WithTimeLayout(layout string) CLIHandlerOption
WithTimeLayout sets the layout for built-in time and ordinary time attributes. It applies to ordinary attributes even without WithTime. The default and the fallback for an empty layout are time.RFC3339. The built-in timestamp is written verbatim; ordinary time attributes are escaped when necessary. The layout should therefore contain only trusted text.
type Color ¶
type Color struct {
// contains filtered or unexported fields
}
Color holds immutable SGR sequences for text styling. A nil *Color or a zero-valued Color adds no color.
type LabelStyle ¶
type LabelStyle struct {
Prefix AffixStyle
Suffix AffixStyle
Color *Color
Width int
}
LabelStyle decorates the text set by WithLabel. An empty label omits all decoration. Color applies to the label and padding. Width sets the minimum label width, excluding affixes, without truncation. Padding is centered with any extra column on the right; non-positive Width adds none.
type LevelStyle ¶
type LevelStyle struct {
Prefix AffixStyle
Suffix AffixStyle
Text string
Color *Color
Width int
}
LevelStyle decorates a built-in log level. Empty Text uses slog.Level.String. Color applies to the text and padding. Width sets the minimum text width, excluding affixes, without truncation. Padding is centered with any extra column on the right; non-positive Width adds none.
type MessageStyle ¶
type MessageStyle struct {
Prefix AffixStyle
Suffix AffixStyle
Color *Color
}
MessageStyle decorates the log message. Prefix and Suffix surround the message; Color applies to the message itself. A nil Color adds no color.
type SourceStyle ¶
type SourceStyle struct {
Prefix AffixStyle
Suffix AffixStyle
Color *Color
}
SourceStyle decorates the built-in source location. Prefix and Suffix surround the location; Color applies to the location itself. A nil Color adds no color. Source selection is controlled by WithSourcePath and WithSourceFunction.
type Style ¶
type Style struct {
// contains filtered or unexported fields
}
Style holds immutable decoration settings for log output. Use NewStyle or DefaultStyle for the default appearance, and Style.With to derive a style without modifying the original.
The zero value adds no decoration and uses an empty attribute separator. Style does not enable or disable built-in output. Literal style text is written verbatim and should contain only trusted text.
func DefaultStyle ¶
func DefaultStyle() *Style
DefaultStyle returns a new style with DBG, INF, WRN, and ERR level labels, angle brackets around source locations, and "=" between attribute keys and values. Its colors are used only for terminal output.
func NewStyle ¶
func NewStyle(opts ...StyleOption) *Style
NewStyle returns DefaultStyle with opts applied in order. Zero-valued options are ignored.
func (*Style) With ¶
func (o *Style) With(opts ...StyleOption) *Style
With returns an independent copy of the style with opts applied in order. It also works on a zero-valued Style. Zero-valued options are ignored.
type StyleOption ¶
type StyleOption struct {
// contains filtered or unexported fields
}
StyleOption configures a Style. Its zero value has no effect.
func WithAttrStyle ¶
func WithAttrStyle(value AttrStyle) StyleOption
WithAttrStyle replaces the colors and key-value separator for ordinary attributes.
func WithLabelStyle ¶
func WithLabelStyle(value LabelStyle) StyleOption
WithLabelStyle replaces the label's decoration and alignment. It does not set the label text.
func WithLevelStyle ¶
func WithLevelStyle(value map[slog.Level]LevelStyle) StyleOption
WithLevelStyle merges value into the style's level styles, including custom levels. Entries with matching levels are replaced; other entries are preserved. The entries are copied when the option is applied. A nil or empty map has no effect.
func WithMessageStyle ¶
func WithMessageStyle(value MessageStyle) StyleOption
WithMessageStyle replaces the message's decoration.
func WithSourceStyle ¶
func WithSourceStyle(value SourceStyle) StyleOption
WithSourceStyle replaces the built-in source's decoration. It does not enable source output or select between file and function names.
func WithTimeStyle ¶
func WithTimeStyle(value TimeStyle) StyleOption
WithTimeStyle replaces the built-in timestamp's decoration. It does not enable time output or change the time layout.
type TimeStyle ¶
type TimeStyle struct {
Prefix AffixStyle
Suffix AffixStyle
Color *Color
}
TimeStyle decorates the built-in timestamp. Prefix and Suffix surround the timestamp; Color applies to the timestamp itself. A nil Color adds no color. The layout is set by WithTimeLayout.

