package log

Import Path
	github.com/gotd/log (on go.dev)

Dependency Relation
	imports 5 packages, and imported by 8 packages

Involved Source Files

	    attr.go
	    helper.go
	  d log.go
		Package log defines a minimal, dependency-free logging port for gotd
		libraries.
		
		A library writes structured records to a [Logger] and never logs through a
		global or imports a concrete logging framework. The consumer chooses the
		backend by passing an adapter: see the logslog and logzap subpackages for
		log/slog and go.uber.org/zap. When no logger is supplied, [Nop] discards
		every record.
		
		The attribute model ([Attr], [Value]) stores scalar values without boxing
		them into an interface, and the [Logger.Enabled] gate lets callers skip
		building attributes on hot paths when a level is disabled.

	    with.go
Package-Level Type Names (total 10, in which 8 are exported)

	/* sort exporteds by: alphabet | popularity */
	 type Attr (struct)
		Attr is a key-value pair attached to a log record.

		Fields (total 2, both are exported)
			Key string
			Value Value
		As Outputs Of (at least 16, all are exported)
			func Any(key string, value any) Attr
			func Bool(key string, value bool) Attr
			func Duration(key string, value time.Duration) Attr
			func Error(err error) Attr
			func Float64(key string, value float64) Attr
			func Group(key string, attrs ...Attr) Attr
			func Int(key string, value int) Attr
			func Int32(key string, value int32) Attr
			func Int64(key string, value int64) Attr
			func NamedError(key string, err error) Attr
			func String(key, value string) Attr
			func Stringer(key string, value fmt.Stringer) Attr
			func Time(key string, value time.Time) Attr
			func Uint64(key string, value uint64) Attr
			func Value.Group() []Attr
			func github.com/gotd/td/crypto.AuthKey.LogAttr() Attr
		As Inputs Of (at least 9, all are exported)
			func Group(key string, attrs ...Attr) Attr
			func With(l Logger, attrs ...Attr) Logger
			func Helper.Debug(ctx context.Context, msg string, attrs ...Attr)
			func Helper.Error(ctx context.Context, msg string, attrs ...Attr)
			func Helper.Info(ctx context.Context, msg string, attrs ...Attr)
			func Helper.Warn(ctx context.Context, msg string, attrs ...Attr)
			func Helper.With(attrs ...Attr) Helper
			func Logger.Log(ctx context.Context, level Level, msg string, attrs ...Attr)
			func Wither.With(attrs ...Attr) Logger

	 type Helper (struct)
		Helper wraps a Logger with leveled convenience methods for call sites. It is a
		thin value type; adapters implement Logger, not Helper.
		
		Build one with For; the zero Helper logs to Nop.

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			l Logger
		Methods (total 9, in which 8 are exported)
			( Helper) Debug(ctx context.Context, msg string, attrs ...Attr)
				Debug logs at LevelDebug.

			( Helper) Enabled(ctx context.Context, level Level) bool
				Enabled reports whether a record at level would be recorded.

			( Helper) Error(ctx context.Context, msg string, attrs ...Attr)
				Error logs at LevelError.

			( Helper) Info(ctx context.Context, msg string, attrs ...Attr)
				Info logs at LevelInfo.

			( Helper) Logger() Logger
				Logger returns the underlying Logger, never nil.

			( Helper) Named(name string) Helper
				Named returns a Helper whose logger is tagged with name. See Named.

			( Helper) Warn(ctx context.Context, msg string, attrs ...Attr)
				Warn logs at LevelWarn.

			( Helper) With(attrs ...Attr) Helper
				With returns a Helper whose logger attaches attrs to every record. See With.

			/* one unexported ... *//* one unexported: */
			( Helper) logger() Logger
		As Outputs Of (at least 6, in which 3 are exported)
			func For(l Logger) Helper
			func Helper.Named(name string) Helper
			func Helper.With(attrs ...Attr) Helper
			/* 3+ unexporteds ... *//* 3+ unexporteds: */
			func github.com/gotd/td/mtproto.(*Conn).logWithBuffer(b *bin.Buffer) Helper
			func github.com/gotd/td/mtproto.(*Conn).logWithType(b *bin.Buffer) Helper
			func github.com/gotd/td/mtproto.(*Conn).logWithTypeID(id uint32) Helper

	 type Kind uint8 (basic type)
		Kind enumerates the dynamic type stored in a [Value].

		As Outputs Of (at least one exported)
			func Value.Kind() Kind
		As Types Of (total 10, all are exported)
			const KindAny
			const KindBool
			const KindDuration
			const KindError
			const KindFloat64
			const KindGroup
			const KindInt64
			const KindString
			const KindTime
			const KindUint64

	 type Level int (basic type)
		Level is the severity of a log record.
		
		Values match log/slog (Debug=-4, Info=0, Warn=4, Error=8) so adapters convert
		by casting; this is an interop convenience, the values are defined here.

		Methods (only one, which is exported)
			( Level) String() string
				String returns the canonical name of the level.

		Implements (at least 3, in which 1 is exported)
			 Level : fmt.Stringer
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			 Level : context.stringer
			 Level : runtime.stringer
		As Inputs Of (at least 3, all are exported)
			func Helper.Enabled(ctx context.Context, level Level) bool
			func Logger.Enabled(ctx context.Context, level Level) bool
			func Logger.Log(ctx context.Context, level Level, msg string, attrs ...Attr)
		As Types Of (total 4, all are exported)
			const LevelDebug
			const LevelError
			const LevelInfo
			const LevelWarn

	 type Logger (interface)
		Logger is the logging port a library writes structured records to.
		
		Implementations must be safe for concurrent use by multiple goroutines.

		Methods (total 2, both are exported)
			( Logger) Enabled(ctx context.Context, level Level) bool
				Enabled reports whether a record at level would be recorded. Callers use
				it to avoid building attributes on hot paths when logging is off.

			( Logger) Log(ctx context.Context, level Level, msg string, attrs ...Attr)
				Log records one structured message. The attrs slice and its contents must
				not be retained after Log returns.

		Implemented By (at least 2, neither is exported)
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			 nop
			*withLogger
		As Outputs Of (at least 7, in which 6 are exported)
			func Named(l Logger, name string) Logger
			func OrNop(l Logger) Logger
			func With(l Logger, attrs ...Attr) Logger
			func Helper.Logger() Logger
			func Namer.Named(name string) Logger
			func Wither.With(attrs ...Attr) Logger
			/* at least one unexported ... *//* at least one unexported: */
			func Helper.logger() Logger
		As Inputs Of (at least 7, in which 6 are exported)
			func For(l Logger) Helper
			func Named(l Logger, name string) Logger
			func OrNop(l Logger) Logger
			func With(l Logger, attrs ...Attr) Logger
			func github.com/gotd/td/exchange.Exchanger.WithLogger(logger Logger) exchange.Exchanger
			func github.com/gotd/td/tdsync.NewLogGroup(parent context.Context, logger Logger) *tdsync.LogGroup
			/* at least one unexported ... *//* at least one unexported: */
			func github.com/gotd/td/telegram.retry(ctx context.Context, logger Logger, cb func(ctx context.Context) error) error
		As Types Of (only one, which is exported)
			  var Nop

	 type Namer (interface)
		Namer is an optional Logger capability: returning a child Logger tagged with a
		name. Adapters implement it to map onto a native mechanism (e.g.
		zap.Logger.Named); Named is a no-op for loggers that do not, since the name is
		advisory.

		Methods (only one, which is exported)
			( Namer) Named(name string) Logger

	 type Value (struct)
		Value holds an attribute value without boxing scalar kinds into an interface.
		
		num carries int64/uint64/float64/bool/duration bits; s carries strings; a
		carries the boxed value for KindAny, KindTime and KindError. It is modeled on
		slog.Value but kept deliberately small and explicit.

		Fields (total 4, none are exported)
			/* 4 unexporteds ... *//* 4 unexporteds: */
			a any
			kind Kind
			num uint64
			s string
		Methods (total 11, all are exported)
			( Value) Any() any
				Any returns the value boxed into an interface, regardless of kind.

			( Value) Bool() bool
				Bool returns the value as bool. Valid for KindBool.

			( Value) Duration() time.Duration
				Duration returns the value as time.Duration. Valid for KindDuration.

			( Value) Error() error
				Error returns the value as error, or nil. Valid for KindError.

			( Value) Float64() float64
				Float64 returns the value as float64. Valid for KindFloat64.

			( Value) Group() []Attr
				Group returns the value's child attributes, or nil. Valid for KindGroup.

			( Value) Int64() int64
				Int64 returns the value as int64. Valid for KindInt64 and KindDuration.

			( Value) Kind() Kind
				Kind returns the value's kind.

			( Value) String() string
				String renders the value to a string. For KindString it returns the string
				unchanged, so Value also satisfies fmt.Stringer.

			( Value) Time() time.Time
				Time returns the value as time.Time, or the zero time. Valid for KindTime.

			( Value) Uint64() uint64
				Uint64 returns the value as uint64. Valid for KindUint64.

		Implements (at least 4, in which 2 are exported)
			 Value : fmt.Stringer
			 Value : math/rand/v2.Source
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			 Value : context.stringer
			 Value : runtime.stringer

	 type Wither (interface)
		Wither is an optional Logger capability: returning a child Logger with attrs
		permanently attached to every record. Adapters implement it to map onto a
		native mechanism (e.g. zap.Logger.With); With falls back to a wrapper for
		loggers that do not.

		Methods (only one, which is exported)
			( Wither) With(attrs ...Attr) Logger
		Implemented By (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			*withLogger

	/* 2 unexporteds ... *//* 2 unexporteds: */
	 type nop (struct)

		Methods (total 2, both are exported)
			( nop) Enabled(context.Context, Level) bool
			( nop) Log(context.Context, Level, string, ...Attr)
		Implements (at least one exported)
			 nop : Logger

	 type withLogger (struct)

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			attrs []Attr
			l Logger
		Methods (total 3, all are exported)
			(*withLogger) Enabled(ctx context.Context, level Level) bool
			(*withLogger) Log(ctx context.Context, level Level, msg string, attrs ...Attr)
			(*withLogger) With(attrs ...Attr) Logger
				With implements Wither so chained With calls accumulate without re-wrapping.

		Implements (at least 2, both are exported)
			*withLogger : Logger
			*withLogger : Wither


Package-Level Functions (total 18, all are exported)

	 func Any(key string, value any) Attr
		Any returns an Attr holding an arbitrary value. Prefer the typed constructors
		for scalars: Any boxes the value into an interface.

	 func Bool(key string, value bool) Attr
		Bool returns a bool Attr.

	 func Duration(key string, value time.Duration) Attr
		Duration returns a time.Duration Attr.

	 func Error(err error) Attr
		Error returns an Attr with the conventional key "error". A nil err is kept as
		a nil-valued error Attr.

	 func Float64(key string, value float64) Attr
		Float64 returns a float64 Attr.

	 func For(l Logger) Helper
		For returns a Helper writing to l, or to Nop if l is nil.

	 func Group(key string, attrs ...Attr) Attr
		Group returns an Attr whose value is the given child attributes. Adapters
		render it as a nested object. As a special case, an empty key inlines the
		children into the parent (like log/slog), matching zap's Inline.

	 func Int(key string, value int) Attr
		Int returns an int Attr, stored as int64.

	 func Int32(key string, value int32) Attr
		Int32 returns an int32 Attr, stored as int64.

	 func Int64(key string, value int64) Attr
		Int64 returns an int64 Attr.

	 func Named(l Logger, name string) Logger
		Named returns a child Logger tagged with name. It uses the logger's native
		Named when it implements Namer, otherwise it returns l unchanged (the name is
		advisory for backends without a naming concept). With an empty name it returns
		l unchanged.

	 func NamedError(key string, err error) Attr
		NamedError returns an error Attr under an explicit key. Unlike Error, which
		uses the conventional "error" key, this lets callers name the field.

	 func OrNop(l Logger) Logger
		OrNop returns l, or Nop if l is nil. Callers store the result so no log site
		needs a nil check.

	 func String(key, value string) Attr
		String returns a string Attr.

	 func Stringer(key string, value fmt.Stringer) Attr
		Stringer returns an Attr holding value.String(). A nil Stringer yields the
		string "<nil>".

	 func Time(key string, value time.Time) Attr
		Time returns a time.Time Attr.

	 func Uint64(key string, value uint64) Attr
		Uint64 returns a uint64 Attr.

	 func With(l Logger, attrs ...Attr) Logger
		With returns a child Logger that attaches attrs to every record. It uses the
		logger's native With when it implements Wither, otherwise it wraps l. With no
		attrs it returns l unchanged.


Package-Level Variables (only one, which is exported)

	  var Nop Logger
		Nop is a Logger that discards every record. Its Enabled always returns false.


Package-Level Constants (total 14, all are exported)

	const KindAny Kind = 0
		Value kinds.

	const KindBool Kind = 5
		Value kinds.

	const KindDuration Kind = 6
		Value kinds.

	const KindError Kind = 8
		Value kinds.

	const KindFloat64 Kind = 4
		Value kinds.

	const KindGroup Kind = 9
		Value kinds.

	const KindInt64 Kind = 2
		Value kinds.

	const KindString Kind = 1
		Value kinds.

	const KindTime Kind = 7
		Value kinds.

	const KindUint64 Kind = 3
		Value kinds.

	const LevelDebug Level = -4
		Severity levels.

	const LevelError Level = 8
		Severity levels.

	const LevelInfo Level = 0
		Severity levels.

	const LevelWarn Level = 4
		Severity levels.

The pages are generated with Golds v0.8.4. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.