kv

README

go-kv

This library provides a key-value field structure kv.Field{} that plays well with the "fmt" package. It gives an easy means of appending key-value fields to log entries, in a manner that also happens to look nice! (it's not far removed from using a map[string]interface{}).

The formatting for these key-value fields is handled by the "fmt" package by default. If you set the kvformat build tag then it will use a custom formatting library found under format/. You can see the benchmarks for both below.

benchmarks:

grufwub @ ~/Projects/main/go-kv
--> go test -run=none -benchmem -bench=.*
goos: linux
goarch: amd64
pkg: codeberg.org/gruf/go-kv
cpu: 11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz
BenchmarkFieldAppendMulti-8       125241              9389 ns/op             849 B/op         98 allocs/op
BenchmarkFieldStringMulti-8       113227             10444 ns/op            3029 B/op        120 allocs/op
BenchmarkFieldFprintfMulti-8      147915              7448 ns/op            1121 B/op        115 allocs/op
BenchmarkFieldsAppend-8           189126              6255 ns/op             849 B/op         98 allocs/op
BenchmarkFieldsString-8           166219              6517 ns/op            3798 B/op        100 allocs/op
PASS
ok      codeberg.org/gruf/go-kv 6.169s

grufwub @ ~/Projects/main/go-kv
--> go test -run=none -benchmem -bench=.* -tags=kvformat                                                                                                                                                                                       
goos: linux
goarch: amd64
pkg: codeberg.org/gruf/go-kv
cpu: 11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz
BenchmarkFieldAppendMulti-8       190161              5709 ns/op             592 B/op         56 allocs/op
BenchmarkFieldStringMulti-8       161763              7930 ns/op            3240 B/op         95 allocs/op
BenchmarkFieldFprintfMulti-8      181557              6207 ns/op            1120 B/op        115 allocs/op
BenchmarkFieldsAppend-8           247052              4580 ns/op             592 B/op         56 allocs/op
BenchmarkFieldsString-8           231235              5103 ns/op            1768 B/op         58 allocs/op
PASS
ok      codeberg.org/gruf/go-kv 6.134s

Documentation

Index

• func AppendQuoteString(buf *byteutil.Buffer, str string)
• func AppendQuoteValue(buf *byteutil.Buffer, str string)
• type Field
  • func (f Field) AppendFormat(buf *byteutil.Buffer, vbose bool)
  • func (f Field) GoString() string
  • func (f Field) Key() string
  • func (f Field) String() string
  • func (f Field) Value(vbose bool) string
• type Fields
  • func (f Fields) AppendFormat(buf *byteutil.Buffer, vbose bool)
  • func (f Fields) Get(key string) (*Field, bool)
  • func (f Fields) GoString() string
  • func (f *Fields) Set(key string, value interface{})
  • func (f Fields) String() string

Functions

func AppendQuoteString

func AppendQuoteString(buf *byteutil.Buffer, str string)

AppendQuoteString will append (and escape/quote where necessary) a field string.

func AppendQuoteValue

func AppendQuoteValue(buf *byteutil.Buffer, str string)

AppendQuoteValue will append (and escape/quote where necessary) a formatted value string.

Types

type Field

type Field struct {
	K string      // Field key
	V interface{} // Field value
}

Field represents an individual key-value field.

func (Field) AppendFormat

func (f Field) AppendFormat(buf *byteutil.Buffer, vbose bool)

AppendFormat will append formatted format of Field to 'buf'. See .String() for details.

func (Field) GoString

func (f Field) GoString() string

GoString performs .String() but with verbose always enabled.

func (Field) Key

func (f Field) Key() string

Key returns the formatted key string of this Field.

func (Field) String

func (f Field) String() string

String will return a string representation of this Field of the form `key=value` where `value` is formatted using fmt package's `%+v` directive. If the .X = true (verbose), then it uses '%#v'. Both key and value are escaped and quoted if necessary to fit on single line.

If the `kvformat` build tag is provided, the formatting will be performed by the `kv/format` package. In this case the value will be formatted using the `{:v}` directive, or `{:?}` if .X = true (verbose).

func (Field) Value

func (f Field) Value(vbose bool) string

Value returns the formatted value string of this Field.

type Fields

type Fields []Field

Fields is a typedef for a []Field slice to provide slightly more performant string formatting for multiples.

func (Fields) AppendFormat

func (f Fields) AppendFormat(buf *byteutil.Buffer, vbose bool)

AppendFormat appends a string representation of receiving Field(s) to 'b'.

func (Fields) Get

func (f Fields) Get(key string) (*Field, bool)

Get will return the field with given 'key'.

func (Fields) GoString

func (f Fields) GoString() string

GoString performs .String() but with type prefix.

func (*Fields) Set

func (f *Fields) Set(key string, value interface{})

Set will set an existing field with 'key' to 'value', or append new.

func (Fields) String

func (f Fields) String() string

String returns a string representation of receiving Field(s).