mapstr

Documentation

Index

• Constants
• Variables
• func AddTags(ms M, tags []string) error
• func AddTagsWithKey(ms M, key string, tags []string) error
• func MergeFields(target, from M, underRoot bool) error
• func MergeFieldsDeep(target, from M, underRoot bool) error
• type AlterFunc
• type EventMetadata
• type M
  • func Union(dict1 M, dict2 M) M
  • func (m M) AlterPath(path string, mode TraversalMode, alterFunc AlterFunc) (err error)
  • func (m M) Clone() M
  • func (m M) CopyFieldsTo(to M, key string) error
  • func (m M) DeepUpdate(d M)
  • func (m M) DeepUpdateNoOverwrite(d M)
  • func (m M) Delete(key string) error
  • func (m M) FindFold(path string) (matchedKey string, value interface{}, err error)
  • func (m M) Flatten() M
  • func (m M) FlattenKeys() *[]string
  • func (m M) Format(f fmt.State, c rune)
  • func (m M) GetValue(key string) (interface{}, error)
  • func (m M) HasKey(key string) (bool, error)
  • func (m M) MarshalLogObject(enc zapcore.ObjectEncoder) error
  • func (m M) Put(key string, value interface{}) (interface{}, error)
  • func (m M) String() string
  • func (m M) StringToPrint() string
  • func (m M) Traverse(path string, mode TraversalMode, visitor TraversalVisitor) (err error)
  • func (m M) Update(d M)
• type Pointer
  • func NewPointer(m M) Pointer
  • func (m Pointer) Get() M
  • func (m *Pointer) Set(p M)
• type TraversalMode
• type TraversalVisitor

Constants

const (
	FieldsKey = "fields"
	TagsKey   = "tags"
)

Event metadata constants. These keys are used within libbeat to identify metadata stored in an event.

const (
	// The key match is strictly case-sensitive
	CaseSensitiveMode = iota
	// The key match is performed with `strings.EqualFold`
	CaseInsensitiveMode = iota
)

Variables

var (
	// ErrKeyNotFound indicates that the specified key was not found.
	ErrKeyNotFound = errors.New("key not found")
	// ErrKeyCollision indicates that during the case-insensitive search multiple keys matched
	ErrKeyCollision = errors.New("key collision")
	// ErrNotMapType indicates that the given value is not map type
	ErrNotMapType = errors.New("value is not a map")
)

Functions

func AddTags

func AddTags(ms M, tags []string) error

AddTags appends a tag to the tags field of ms. If the tags field does not exist then it will be created. If the tags field exists and is not a []string then an error will be returned. It does not deduplicate the list of tags.

func AddTagsWithKey

func AddTagsWithKey(ms M, key string, tags []string) error

AddTagsWithKey appends a tag to the key field of ms. If the field does not exist then it will be created. If the field exists and is not a []string then an error will be returned. It does not deduplicate the list.

func MergeFields

func MergeFields(target, from M, underRoot bool) error

MergeFields merges the top-level keys and values in each source map (it does not perform a deep merge). If the same key exists in both, the value in fields takes precedence. If underRoot is true then the contents of the fields M is merged with the value of the 'fields' key in target.

An error is returned if underRoot is true and the value of ms.fields is not a M.

func MergeFieldsDeep

func MergeFieldsDeep(target, from M, underRoot bool) error

MergeFieldsDeep recursively merges the keys and values from `from` into `target`, either into ms itself (if underRoot == true) or into ms["fields"] (if underRoot == false). If the same key exists in `from` and the destination map, the value in fields takes precedence.

An error is returned if underRoot is true and the value of ms["fields"] is not a M.

Types

type AlterFunc

type AlterFunc func(string) (string, error)

type EventMetadata

type EventMetadata struct {
	Fields          M
	FieldsUnderRoot bool `config:"fields_under_root"`
	Tags            []string
}

EventMetadata contains fields and tags that can be added to an event via configuration.

type M

type M map[string]interface{}

M is a map[string]interface{} wrapper with utility methods for common map operations like converting to JSON.

func Union

func Union(dict1 M, dict2 M) M

Union creates a new M containing the union of the key-value pairs of the two maps. If the same key is present in both, the key-value pairs from dict2 overwrite the ones from dict1.

func (M) AlterPath

func (m M) AlterPath(path string, mode TraversalMode, alterFunc AlterFunc) (err error)

AlterPath walks the given `path` and replaces matching keys using the value returned by `alterFunc`. `mode` sets the behavior how the given path is matched throughout the levels. Returns `ErrKeyCollision` if multiple keys match the same request (when `mode` is `CaseInsensitiveMode`). Returns `ErrNotMapType` when one of the values on the path is not a map and cannot be traversed. Returns `ErrKeyNotFound` when the path does not exist

func (M) Clone

func (m M) Clone() M

Clone returns a copy of the M. It recursively makes copies of inner maps.

func (M) CopyFieldsTo

func (m M) CopyFieldsTo(to M, key string) error

CopyFieldsTo copies the field specified by key to the given map. It will overwrite the key if it exists. An error is returned if the key does not exist in the source map.

func (M) DeepUpdate

func (m M) DeepUpdate(d M)

DeepUpdate recursively copies the key-value pairs from d to this map. If the key is present and a map as well, the sub-map will be updated recursively via DeepUpdate. DeepUpdateNoOverwrite is a version of this function that does not overwrite existing values.

func (M) DeepUpdateNoOverwrite

func (m M) DeepUpdateNoOverwrite(d M)

DeepUpdateNoOverwrite recursively copies the key-value pairs from d to this map. If a key is already present it will not be overwritten. DeepUpdate is a version of this function that overwrites existing values.

func (M) Delete

func (m M) Delete(key string) error

Delete deletes the given key from the map.

func (M) FindFold

func (m M) FindFold(path string) (matchedKey string, value interface{}, err error)

FindFold accepts a key and traverses the map trying to match every key segment using `strings.FindFold` (case-insensitive match) and returns the actual key of the map that matched the given key and the value stored under this key. Returns `ErrKeyCollision` if multiple keys match the same request. Returns `ErrNotMapType` when one of the values on the path is not a map and cannot be traversed. Returns `ErrKeyNotFound` when the path does not exist

func (M) Flatten

func (m M) Flatten() M

Flatten flattens the given M and returns a flat M.

Example:

"hello": M{"world": "test" }

This is converted to:

"hello.world": "test"

This can be useful for testing or logging.

func (M) FlattenKeys

func (m M) FlattenKeys() *[]string

FlattenKeys flattens given MapStr keys and returns a containing array pointer

Example:

"hello": MapStr{"world": "test" }

This is converted to:

["hello.world"]

func (M) Format

func (m M) Format(f fmt.State, c rune)

Format implements fmt.Formatter

func (M) GetValue

func (m M) GetValue(key string) (interface{}, error)

GetValue gets a value from the map. If the key does not exist then an error is returned.

func (M) HasKey

func (m M) HasKey(key string) (bool, error)

HasKey returns true if the key exist. If an error occurs then false is returned with a non-nil error.

func (M) MarshalLogObject

func (m M) MarshalLogObject(enc zapcore.ObjectEncoder) error

MarshalLogObject implements the zapcore.ObjectMarshaler interface and allows for more efficient marshaling of mapstr.M in structured logging.

func (M) Put

func (m M) Put(key string, value interface{}) (interface{}, error)

Put associates the specified value with the specified key. If the map previously contained a mapping for the key, the old value is replaced and returned. The key can be expressed in dot-notation (e.g. x.y) to put a value into a nested map.

If you need insert keys containing dots then you must use bracket notation to insert values (e.g. m[key] = value).

func (M) String

func (m M) String() string

String returns the M as JSON.

func (M) StringToPrint

func (m M) StringToPrint() string

StringToPrint returns the M as pretty JSON.

func (M) Traverse

func (m M) Traverse(path string, mode TraversalMode, visitor TraversalVisitor) (err error)

Traverse walks the given nested `path` in the map and invokes the `visitor` function on each level passing the current-level map and the current key. `mode` sets the behavior how the given path is matched throughout the levels. The `visitor` function is allowed to make changes in the level or collect data. Returns `ErrKeyCollision` if multiple keys match the same request (when `mode` is `CaseInsensitiveMode`). Returns `ErrNotMapType` when one of the values on the path is not a map and cannot be traversed. Returns `ErrKeyNotFound` when the path does not exist

func (M) Update

func (m M) Update(d M)

Update copies all the key-value pairs from d to this map. If the key already exists then it is overwritten. This method does not merge nested maps.

type Pointer

type Pointer struct {
	// contains filtered or unexported fields
}

Pointer stores a pointer to atomically get/set a mapstr.M object This should give faster access for use cases with lots of reads and a few changes. It's important to note that modifying the map is not thread safe, only fully replacing it.

func NewPointer

func NewPointer(m M) Pointer

NewMPointer initializes and returns a pointer to the given M

func (Pointer) Get

func (m Pointer) Get() M

Get returns the M stored under this pointer

func (*Pointer) Set

func (m *Pointer) Set(p M)

Set stores a pointer the given M, replacing any previous one

type TraversalMode

type TraversalMode int

TraversalMode used for traversing the map through multiple levels.

type TraversalVisitor

type TraversalVisitor func(M, string) error