fields

package
v1.6.1 Latest Latest
Warning

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

 Go to latest Published: Aug 15, 2024 License: MIT Imports: 5 Imported by: 10

Documentation

Overview

Fields represents a collection of key value pairs.

Key and Values

The keys are always of type string and should be only printable characters which can be printed in any context. Recommended are everything that matches: 

^[a-zA-Z0-9._-]+$

The values could be everything including nils.

Immutability

Fields are defined as immutable. Calling the methods With, Withf, Without and WithAll always results in a new instance of Fields that could be either brand new, a copy of the source one or do inherit some stuff of the original called one; but it never modifies the called instance.

Example 
f := With("foo", "1").
	With("bar", 2).
	Withf("message", "something happened in module %s", module)

err := f.ForEach(func(k string, v interface{}) error {
	fmt.Printf("%s=%+v\n", k, v)
	return nil
})

if err != nil {
	panic(err)
}

Output:

Index

Examples

Constants

This section is empty.

Variables

View Source 
var Exclude = struct{}{}

Exclude marks values of fields which might be present in the list of fields but should not be printed somewhere.

Cause: `nil` values are always printed. This value is an exception.

Functions

func AreEqual added in v0.7.1 

func AreEqual(left, right Fields) (bool, error)

AreEqual is comparing two given Fields using DefaultEquality.

func AsMap added in v0.1.5 

func AsMap(f ForEachEnabled) (map[string]interface{}, error)

AsMap converts a given object which contains is ForEachEnabled and converts it to a map[string]interface{}

func SortedForEach added in v0.7.0 

func SortedForEach(input ForEachEnabled, sorter KeySorter, consumer func(key string, value interface{}) error) error

SortedForEach is calling the consumer for all entries of ForEachEnabled but in the order ensured by KeySorter. If KeySorter is nil DefaultKeySorter is used.

Types

type Equality added in v0.7.1 

type Equality interface {
	// AreFieldsEqual compares the two given Fields for their equality.
	AreFieldsEqual(left, right Fields) (bool, error)
}

Equality is comparing two Fields with each other and check if both are equal. 

var DefaultEquality Equality = &privateEqualityImpl{&EqualityImpl{
	ValueEquality: NewValueEqualityFacade(func() ValueEquality {
		return DefaultValueEquality
	}),
}}

DefaultEquality is the default instance of an Equality. The initial initialization of this global variable should be able to deal with the majority of the cases. There is also a shortcut function: AreEqual(left,right)

func NewEqualityFacade added in v0.7.1 

func NewEqualityFacade(provider func() Equality) Equality

NewEqualityFacade creates a re-implementation of Equality which uses the given provider to retrieve the actual instance of Equality at the moment when it is used. This is useful especially in cases where you want to deal with concurrency while creation of objects that need to hold a reference to an Equality.

type EqualityFunc added in v0.7.1 

type EqualityFunc func(left, right Fields) (bool, error)

EqualityFunc is wrapping a given func into Equality.

func (EqualityFunc) AreFieldsEqual added in v0.7.1 

func (instance EqualityFunc) AreFieldsEqual(left, right Fields) (bool, error)

AreFieldsEqual implements Equality.AreFieldsEqual().

type EqualityImpl added in v0.7.1 

type EqualityImpl struct {
	// ValueEquality is used to compare the values of the given fields. If nil
	// DefaultValueEquality is used. If this is nil too, there is always false
	// returned.
	ValueEquality ValueEquality
}

EqualityImpl is a default implementation of Equality which compares all its values using the configured ValueEquality.

func (*EqualityImpl) AreFieldsEqual added in v0.7.1 

func (instance *EqualityImpl) AreFieldsEqual(left, right Fields) (bool, error)

AreFieldsEqual implements Equality.AreFieldsEqual().

type Fields 

type Fields interface {
	// ForEach will call the provided consumer for each field which is provided
	// by this Fields instance.
	ForEach(consumer func(key string, value interface{}) error) error

	// Get will return for the given key the corresponding value if exists.
	// The value itself can be nil but it cal still exist.
	Get(key string) (value interface{}, exists bool)

	// Len returns the len of this Fields instance.
	Len() int

	// With returns a variant of this Fields with the given key
	// value pair contained inside. If the given key already exists in the
	// current instance this means it will be overwritten.
	With(key string, value interface{}) Fields

	// Withf is similar to With, but it adds classic fmt.Printf functions to it.
	// It is defined that the format itself will not be executed before the
	// consumption of the value. (See ForEach() and Get())
	Withf(key string, format string, args ...interface{}) Fields

	// WithAll is similar to With, but it can consume more than one field at
	// once. Be aware: There is neither a guarantee that this instance will be
	// copied or not.
	WithAll(map[string]interface{}) Fields

	// Without returns a variant of this Fields without the given
	// key contained inside. In other words: If someone afterwards tries to
	// call either ForEach() or Get() nothing with this key(s) will be returned.
	Without(keys ...string) Fields
}
Example (ForEach) 
err := someFields.ForEach(func(k string, v interface{}) error {
	fmt.Printf("%s=%+v\n", k, v)
	return nil
})

if err != nil {
	panic(fmt.Errorf("doh!: %w", err))
}

Output:
Example (Get) 
v, _ := someFields.Get("foo")

fmt.Printf("foo=%+v\n", v)

Output:

func AsFields added in v0.10.0 

func AsFields(f ForEachEnabled) (Fields, error)

AsFields converts a given object which contains is ForEachEnabled and converts it to a Fields instance.

func Empty 

func Empty() Fields

Empty returns an empty instance of Fields.

func With 

func With(key string, value interface{}) Fields

With creates an instance of Fields for the given key value pair.

func WithAll added in v0.5.5 

func WithAll(of map[string]interface{}) Fields

WithAll wraps a map into Fields with all its functions. This can be better in case of performance because it could safe several Fields.With() calls.

WARNING! This type is potentially dangerous. On the one hand anybody can cast to this type and can directly modify the contents. This applies to the initial creator of this mapped instance, too. Both cases might result in breaking the basic contracts of Fields: Be immutable. So it is only recommend to use this when it really makes sense out of readability or performance.

func Withf added in v0.1.3 

func Withf(key string, format string, args ...interface{}) Fields

With creates an instance of Fields for the given key and a Lazy fmt.Sprintf value from the given format and args.

type FilterContext added in v1.1.0 

type FilterContext interface {
	// GetLevel provides the current level.Level of this context.
	GetLevel() level.Level

	// Get provides access to other fields within this context.
	Get(key string) (value interface{}, exists bool)
}

FilterContext provides information about the context where a field exists within.

type Filtered added in v1.1.0 

type Filtered interface {
	// Filter is the method which will be called at the moment where the value
	// should be consumed.
	//
	// Only if shouldBeRespected is true it will be respected by the consumers.
	Filter(FilterContext) (value interface{}, shouldBeRespected bool)

	// Get will return the original value (unfiltered).
	Get() interface{}
}

Filtered is a value which will be executed on usage to retrieve the actual value or exclude it.

This is useful in context where fields should be only respected based on a specific log level, another field has a specific value, ...

func IgnoreLevels added in v1.2.0 

func IgnoreLevels(fromLevel, toLevel level.Level, value interface{}) Filtered

IgnoreLevels represents a filtered value which will only be consumed if the level.Level of the current context (for example logging events) is smaller than fromLevel or equal/bigger than toLevel (fromLevel:inclusive, toLevel:exclusive).

func IgnoreLevelsLazy added in v1.2.0 

func IgnoreLevelsLazy(fromLevel, toLevel level.Level, value Lazy) Filtered

IgnoreLevelsLazy represents a filtered Lazy value which will only be consumed if the level.Level of the current context (for example logging events) is smaller than fromLevel or equal/bigger than toLevel (fromLevel:inclusive, toLevel:exclusive).

func RequireMaximalLevel added in v1.1.0 

func RequireMaximalLevel(maximalLevel level.Level, value interface{}) Filtered

RequireMaximalLevel represents a filtered value which will only be consumed if the level.Level of the current context (for example logging events) is not bigger than the requested maximalLevel.

Example 
filteredValue := RequireMaximalLevel(level.Debug, veryComplexValue)

// Will be <nil>, <false>
fmt.Println(filteredValue.Filter(filterContextWithLeveInfo))

// Will be <veryComplexValue>, <true>
fmt.Println(filteredValue.Filter(filterContextWithLeveDebug))

Output:

func RequireMaximalLevelLazy added in v1.1.0 

func RequireMaximalLevelLazy(minimalLevel level.Level, value Lazy) Filtered

RequireMaximalLevelLazy represents a filtered Lazy value which will only be consumed if the level.Level of the current context (for example logging events) is not bigger than requested maximalLevel.

type ForEachEnabled added in v0.7.0 

type ForEachEnabled interface {
	ForEach(consumer func(key string, value interface{}) error) error
}

ForEachEnabled defines a type that handles iterates over all its key value pairs and providing it to the the given consumer.

type ForEachFunc added in v0.7.0 

type ForEachFunc func(consumer func(key string, value interface{}) error) error

ForEachFunc is a utility type to wrapping simple functions into ForEachEnabled.

func (ForEachFunc) ForEach added in v0.7.0 

func (instance ForEachFunc) ForEach(consumer func(key string, value interface{}) error) error

type KeySorter added in v0.1.5 

type KeySorter func(keys []string)

KeySorter is used to sort all keys. See Sort() for more details. 

var DefaultKeySorter KeySorter = func(what []string) {
	sort.Strings(what)
}

DefaultKeySorter is the default instance of an KeySorter. By default this is sorting in increasing order.

func NoopKeySorter added in v0.9.0 

func NoopKeySorter() KeySorter

NoopKeySorter provides a noop implementation of KeySorter.

type KeysSpec added in v0.1.5 

type KeysSpec interface {
	// GetTimestamp returns the key where the timestamp is stored inside, if
	// available.
	GetTimestamp() string

	// GetMessage returns the key where the message is stored inside, if
	// available.
	GetMessage() string

	// GetError returns the key where an error is stored inside, if
	// available.
	GetError() string

	// GetLogger returns the key where the Logger is stored inside, which is
	// managed a Fields instance. (if available)
	GetLogger() string
}

KeysSpec defines the keys for common usages inside a Fields instance.

func NewKeysSpecFacade added in v0.9.0 

func NewKeysSpecFacade(provider func() KeysSpec) KeysSpec

NewKeysSpecFacade creates a facade of KeysSpec using the given provider.

type KeysSpecImpl added in v0.7.1 

type KeysSpecImpl struct {
	// Timestamp defines the used key of a timestamp.
	// If empty "timestamp" will be used instead.
	Timestamp string

	// Message defines the used key of a message.
	// If empty "message" will be used instead.
	Message string

	// Logger defines the used key of a logger.
	// If empty "logger" will be used instead.
	Logger string

	// Error defines the used key of an error.
	// If empty "error" will be used instead.
	Error string
}

KeysSpecImpl is a default implementation of KeysSpec.

func (KeysSpecImpl) GetError added in v0.7.1 

func (instance KeysSpecImpl) GetError() string

GetError implements KeysSpec#GetError()

func (KeysSpecImpl) GetLogger added in v0.7.1 

func (instance KeysSpecImpl) GetLogger() string

GetLogger implements KeysSpec#GetLogger()

func (KeysSpecImpl) GetMessage added in v0.7.1 

func (instance KeysSpecImpl) GetMessage() string

GetMessage implements KeysSpec#GetMessage()

func (KeysSpecImpl) GetTimestamp added in v0.7.1 

func (instance KeysSpecImpl) GetTimestamp() string

GetTimestamp implements KeysSpec#GetTimestamp()

type Lazy added in v0.2.0 

type Lazy interface {
	// Get is the method which will be called at the moment where the value
	// should be consumed.
	Get() interface{}
}

Lazy is a value which CAN be initialized on usage.

This is very useful in the context of Fields where sometimes the evaluating of values could be cost intensive, but maybe you either might log stuff on a level which might not be always enabled or the operation might be happening on an extra routine/thread.

func LazyFormat added in v0.4.0 

func LazyFormat(format string, args ...interface{}) Lazy

LazyFormat returns a value which will be executed the fmt.Sprintf action at the moment when it will be consumed or in other words: Lazy.Get() is called.

Example 
lazy := LazyFormat("Hello, %s!", "world")

fmt.Println(lazy.Get())

Output:

func LazyFunc added in v0.2.0 

func LazyFunc(provider func() interface{}) Lazy

LazyFunc wraps Lazy into a single function pointer.

Example 
lazy := LazyFunc(func() interface{} {
	return someVariable.someResourceIntensiveMethod()
})

fmt.Println(lazy.Get())

Output:

type ValueEquality added in v0.7.1 

type ValueEquality interface {
	// AreValuesEqual compares the two given values for their equality for
	// the given key.
	AreValuesEqual(key string, left, right interface{}) (bool, error)
}

ValueEquality is comparing two values (of the same key) with each other and check if both are equal. 

var DefaultValueEquality ValueEquality = ValueEqualityFunc(func(key string, leftValue, rightValue interface{}) (bool, error) {
	if v, ok := leftValue.(Lazy); ok {
		leftValue = v.Get()
	}
	if v, ok := rightValue.(Lazy); ok {
		rightValue = v.Get()
	}

	if isFunction(leftValue) {
		lV, rV := reflect.ValueOf(leftValue), reflect.ValueOf(rightValue)
		if lV.Kind() == reflect.Func {
			return rV.Kind() == reflect.Func && lV.Pointer() == rV.Pointer(), nil
		}
	}

	return reflect.DeepEqual(leftValue, rightValue), nil
})

DefaultValueEquality is the default instance of a ValueEquality. The initial initialization of this global variable should be able to deal with the majority of the cases.

func NewValueEqualityFacade added in v0.7.1 

func NewValueEqualityFacade(provider func() ValueEquality) ValueEquality

NewValueEqualityFacade creates a re-implementation of ValueEquality which uses the given provider to retrieve the actual instance of ValueEquality at the moment when it is used. This is useful especially in cases where you want to deal with concurrency while creation of objects that need to hold a reference to an ValueEquality.

type ValueEqualityFunc added in v0.7.1 

type ValueEqualityFunc func(key string, left, right interface{}) (bool, error)

ValueEqualityFunc is wrapping a given func into ValueEquality.

func (ValueEqualityFunc) AreValuesEqual added in v0.7.1 

func (instance ValueEqualityFunc) AreValuesEqual(key string, left, right interface{}) (bool, error)

AreValuesEqual implements ValueEquality.AreValuesEqual().

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.