core

package
v0.7.9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 16, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package core provides shared value types used by both the root clog package and subpackages like fx/. It lives under internal/ to prevent external consumers from depending on it directly.

Index

Constants

View Source 
const ErrorKey = "error"

ErrorKey is the default field key used by Err methods.

View Source 
const Nil = "<nil>"

Nil is the string representation used for nil values.

Variables

This section is empty.

Functions

func Clamp01 

func Clamp01(val float64) float64

Clamp01 restricts val to the 0–1 range.

func ClampPercent 

func ClampPercent(val, r float64) float64

ClampPercent restricts val to the [0, r] range. NaN and negative infinity clamp to 0; positive infinity clamps to r.

func ErrSliceToStrings 

func ErrSliceToStrings(errs []error) []string

ErrSliceToStrings converts a slice of errors to a slice of strings. Nil errors are rendered as Nil ("<nil>").

func IsNilStringer 

func IsNilStringer(val fmt.Stringer) bool

IsNilStringer reports whether val is nil, either as an untyped nil interface or as a typed nil whose underlying kind supports IsNil.

Types

type ElapsedField 

type ElapsedField time.Duration

ElapsedField wraps a time.Duration so formatValue can identify it for elapsed-time styling.

type Field 

type Field struct {
	Key   string `json:"key"`
	Value any    `json:"value"`
}

Field is a typed key-value pair attached to a log entry.

func MergeFields 

func MergeFields(base, overrides []Field) []Field

MergeFields merges base fields with overrides, replacing existing keys. Keys in overrides replace matching keys in base while preserving order.

type FieldBuilder 

type FieldBuilder[T any] struct {
	Fields []Field
	Self   *T
}

FieldBuilder provides common field-appending methods for fluent builders. Embed it and call InitSelf in the constructor to enable method chaining.

func (*FieldBuilder[T]) AnErr added in v0.7.0 

func (fb *FieldBuilder[T]) AnErr(key string, err error) *T

AnErr adds an error as a keyed field. No-op if err is nil.

func (*FieldBuilder[T]) Any 

func (fb *FieldBuilder[T]) Any(key string, val any) *T

Any adds a field with an arbitrary value.

func (*FieldBuilder[T]) Anys 

func (fb *FieldBuilder[T]) Anys(key string, vals []any) *T

Anys adds a slice of arbitrary values.

func (*FieldBuilder[T]) Base64 

func (fb *FieldBuilder[T]) Base64(key string, val []byte) *T

Base64 adds a []byte field encoded as a base64 string.

func (*FieldBuilder[T]) Bool 

func (fb *FieldBuilder[T]) Bool(key string, val bool) *T

Bool adds a bool field.

func (*FieldBuilder[T]) Bools 

func (fb *FieldBuilder[T]) Bools(key string, vals []bool) *T

Bools adds a bool slice field.

func (*FieldBuilder[T]) Bytes 

func (fb *FieldBuilder[T]) Bytes(key string, val []byte) *T

Bytes adds a []byte field. If val is valid JSON it is stored as RawJSON with syntax highlighting; otherwise it is stored as a plain string.

func (*FieldBuilder[T]) Duration 

func (fb *FieldBuilder[T]) Duration(key string, val time.Duration) *T

Duration adds a time.Duration field.

func (*FieldBuilder[T]) Durations 

func (fb *FieldBuilder[T]) Durations(key string, vals []time.Duration) *T

Durations adds a time.Duration slice field.

func (*FieldBuilder[T]) Err 

func (fb *FieldBuilder[T]) Err(err error) *T

Err adds an error field with key "error". No-op if err is nil.

func (*FieldBuilder[T]) Errs 

func (fb *FieldBuilder[T]) Errs(key string, vals []error) *T

Errs adds an error slice field. Each error is converted to its message string; nil errors are rendered as Nil ("<nil>").

func (*FieldBuilder[T]) Float32 added in v0.7.0 

func (fb *FieldBuilder[T]) Float32(key string, val float32) *T

Float32 adds a float32 field.

func (*FieldBuilder[T]) Float64 

func (fb *FieldBuilder[T]) Float64(key string, val float64) *T

Float64 adds a float64 field.

func (*FieldBuilder[T]) Floats32 added in v0.7.0 

func (fb *FieldBuilder[T]) Floats32(key string, vals []float32) *T

Floats32 adds a float32 slice field.

func (*FieldBuilder[T]) Floats64 

func (fb *FieldBuilder[T]) Floats64(key string, vals []float64) *T

Floats64 adds a float64 slice field.

func (*FieldBuilder[T]) Hex 

func (fb *FieldBuilder[T]) Hex(key string, val []byte) *T

Hex adds a []byte field encoded as a hex string.

func (*FieldBuilder[T]) InitSelf 

func (fb *FieldBuilder[T]) InitSelf(s *T)

InitSelf sets the self-pointer for method chaining.

func (*FieldBuilder[T]) Int 

func (fb *FieldBuilder[T]) Int(key string, val int) *T

Int adds an int field.

func (*FieldBuilder[T]) Int8 added in v0.7.0 

func (fb *FieldBuilder[T]) Int8(key string, val int8) *T

Int8 adds an int8 field.

func (*FieldBuilder[T]) Int16 added in v0.7.0 

func (fb *FieldBuilder[T]) Int16(key string, val int16) *T

Int16 adds an int16 field.

func (*FieldBuilder[T]) Int32 added in v0.7.0 

func (fb *FieldBuilder[T]) Int32(key string, val int32) *T

Int32 adds an int32 field.

func (*FieldBuilder[T]) Int64 

func (fb *FieldBuilder[T]) Int64(key string, val int64) *T

Int64 adds an int64 field.

func (*FieldBuilder[T]) Ints 

func (fb *FieldBuilder[T]) Ints(key string, vals []int) *T

Ints adds an int slice field.

func (*FieldBuilder[T]) Ints8 added in v0.7.0 

func (fb *FieldBuilder[T]) Ints8(key string, vals []int8) *T

Ints8 adds an int8 slice field.

func (*FieldBuilder[T]) Ints16 added in v0.7.0 

func (fb *FieldBuilder[T]) Ints16(key string, vals []int16) *T

Ints16 adds an int16 slice field.

func (*FieldBuilder[T]) Ints32 added in v0.7.0 

func (fb *FieldBuilder[T]) Ints32(key string, vals []int32) *T

Ints32 adds an int32 slice field.

func (*FieldBuilder[T]) Ints64 

func (fb *FieldBuilder[T]) Ints64(key string, vals []int64) *T

Ints64 adds an int64 slice field.

func (*FieldBuilder[T]) JSON 

func (fb *FieldBuilder[T]) JSON(key string, val any) *T

JSON marshals val to JSON and adds it as a highlighted field. On marshal error the field value is the error string.

func (*FieldBuilder[T]) Percent 

func (fb *FieldBuilder[T]) Percent(key string, val float64, opts ...func(*Percent)) *T

Percent adds a percentage field with gradient color styling. The value is stored as-is; use [Event.Percent] for clamped input.

func (*FieldBuilder[T]) Quantities 

func (fb *FieldBuilder[T]) Quantities(key string, vals []string) *T

Quantities adds a quantity string slice field.

func (*FieldBuilder[T]) Quantity 

func (fb *FieldBuilder[T]) Quantity(key, val string) *T

Quantity adds a quantity string field where numeric and unit segments are styled independently (e.g. "5m", "5.1km", "100MB").

func (*FieldBuilder[T]) RawJSON 

func (fb *FieldBuilder[T]) RawJSON(key string, val []byte) *T

RawJSON adds a field with pre-serialized JSON bytes, emitted verbatim without quoting or escaping.

func (*FieldBuilder[T]) Str 

func (fb *FieldBuilder[T]) Str(key, val string) *T

Str adds a string field.

func (*FieldBuilder[T]) Stringer 

func (fb *FieldBuilder[T]) Stringer(key string, val fmt.Stringer) *T

Stringer adds a field by calling the value's String method. No-op if val is nil.

func (*FieldBuilder[T]) Stringers 

func (fb *FieldBuilder[T]) Stringers(key string, vals []fmt.Stringer) *T

Stringers adds a field with a slice of fmt.Stringer values.

func (*FieldBuilder[T]) Strs 

func (fb *FieldBuilder[T]) Strs(key string, vals []string) *T

Strs adds a string slice field.

func (*FieldBuilder[T]) Time 

func (fb *FieldBuilder[T]) Time(key string, val time.Time) *T

Time adds a time.Time field.

func (*FieldBuilder[T]) TimeDiff added in v0.7.0 

func (fb *FieldBuilder[T]) TimeDiff(key string, t, start time.Time) *T

TimeDiff adds the field key with the duration between t and start. If t is not after start, the duration is zero.

func (*FieldBuilder[T]) Times 

func (fb *FieldBuilder[T]) Times(key string, vals []time.Time) *T

Times adds a time.Time slice field.

func (*FieldBuilder[T]) Uint 

func (fb *FieldBuilder[T]) Uint(key string, val uint) *T

Uint adds a uint field.

func (*FieldBuilder[T]) Uint8 added in v0.7.0 

func (fb *FieldBuilder[T]) Uint8(key string, val uint8) *T

Uint8 adds a uint8 field.

func (*FieldBuilder[T]) Uint16 added in v0.7.0 

func (fb *FieldBuilder[T]) Uint16(key string, val uint16) *T

Uint16 adds a uint16 field.

func (*FieldBuilder[T]) Uint32 added in v0.7.0 

func (fb *FieldBuilder[T]) Uint32(key string, val uint32) *T

Uint32 adds a uint32 field.

func (*FieldBuilder[T]) Uint64 

func (fb *FieldBuilder[T]) Uint64(key string, val uint64) *T

Uint64 adds a uint64 field.

func (*FieldBuilder[T]) Uints 

func (fb *FieldBuilder[T]) Uints(key string, vals []uint) *T

Uints adds a uint slice field.

func (*FieldBuilder[T]) Uints8 added in v0.7.0 

func (fb *FieldBuilder[T]) Uints8(key string, vals []uint8) *T

Uints8 adds a uint8 slice field.

func (*FieldBuilder[T]) Uints16 added in v0.7.0 

func (fb *FieldBuilder[T]) Uints16(key string, vals []uint16) *T

Uints16 adds a uint16 slice field.

func (*FieldBuilder[T]) Uints32 added in v0.7.0 

func (fb *FieldBuilder[T]) Uints32(key string, vals []uint32) *T

Uints32 adds a uint32 slice field.

func (*FieldBuilder[T]) Uints64 

func (fb *FieldBuilder[T]) Uints64(key string, vals []uint64) *T

Uints64 adds a uint64 slice field.

func (*FieldBuilder[T]) When 

func (fb *FieldBuilder[T]) When(condition bool, fn func(*T)) *T

When calls fn with the builder if condition is true.

type Level 

type Level = level.Level

Level represents a log level.

type Part 

type Part int

Part identifies a component of a formatted log line. 

const (
	// PartTimestamp is the timestamp component.
	PartTimestamp Part = iota
	// PartLevel is the level label component.
	PartLevel
	// PartSymbol is the emoji symbol component.
	PartSymbol
	// PartMessage is the log message component.
	PartMessage
	// PartFields is the structured fields component.
	PartFields
)

type Percent 

type Percent struct {
	Value   float64
	Reverse bool
	Maximum *float64
}

Percent holds a percentage value (0–100) with an optional reverse gradient flag. When Reverse is true, the gradient is flipped relative to the logger's default direction. Maximum overrides the global maximum for this field when non-nil.

type QuantityField 

type QuantityField string

QuantityField wraps a string value with numeric and unit segments (e.g. "5m", "5.1km", "100MB") so formatValue can identify it for quantity styling.

type QuoteMode 

type QuoteMode int

QuoteMode controls how field values are quoted in log output. 

const (
	// QuoteAuto quotes values only when they contain spaces, unprintable
	// characters, or embedded quotes. This is the default.
	QuoteAuto QuoteMode = iota
	// QuoteAlways quotes all string, error, and default-kind values.
	QuoteAlways
	// QuoteNever disables quoting entirely.
	QuoteNever
)

type RawJSON 

type RawJSON []byte

RawJSON wraps pre-serialized JSON bytes so formatValue can emit them verbatim without quoting or escaping.

type Sort 

type Sort int

Sort controls how fields are sorted in output. 

const (
	// SortNone preserves the insertion order of fields (default).
	SortNone Sort = iota
	// SortAscending sorts fields by key A→Z.
	SortAscending
	// SortDescending sorts fields by key Z→A.
	SortDescending
)

type TreeChars 

type TreeChars struct {
	First    string // connector for TreeFirst  (default "├── ")
	Middle   string // connector for TreeMiddle (default "├── ")
	Last     string // connector for TreeLast   (default "└── ")
	Continue string // ancestor line when parent is First/Middle (default "│   ")
	Blank    string // ancestor line when parent is Last         (default "    ")
}

TreeChars defines the box-drawing characters used by tree indentation.

type TreePos 

type TreePos int

TreePos identifies a node's position among its siblings in a tree. 

const (
	// TreeFirst marks the first sibling.
	TreeFirst TreePos = iota
	// TreeMiddle marks a middle sibling (more siblings follow).
	TreeMiddle
	// TreeLast marks the last sibling (no more siblings follow).
	TreeLast
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.