meta

Documentation

Index

• Constants
• Variables
• func StringToBestType(s string) any
• type Object
  • func ObjectFromRaw(in any, at ...string) (obj Object)
  • func ObjectFromRawWithOrigin(in any, where []Origin, at ...string) (obj Object)
  • func (obj Object) AdaptToRaw(adapter func(from, to reflect.Value) (any, error)) (Object, error)
  • func (obj Object) Add(keyDelimiter, key string, val any, origin ...Origin) (Object, error)
  • func (obj Object) AlterKeyCase(to func(string) string) Object
  • func (obj Object) Clone() Object
  • func (obj Object) ConvertMapsToArrays() Object
  • func (obj Object) ErrOnNonSerializable() error
  • func (obj Object) Fetch(asks []string, separater string) (Object, error)
  • func (obj Object) FilterNonSerializable() Object
  • func (o Object) IsEmpty() bool
  • func (o Object) Kind() int
  • func (obj Object) Merge(next Object) (Object, error)
  • func (obj Object) OriginString() string
  • func (obj Object) ResolveCommands() (Object, error)
  • func (obj Object) ToExpanded(max int, origin, start, end string, expander func(string) (string, bool)) (Object, error)
  • func (obj Object) ToRaw() any
  • func (obj Object) ToRedacted() Object
• type Origin
  • func (o Origin) String() string

Constants

const (
	Array = iota + 1
	Map
	Value
)

Variables

var (
	ErrConflict         = errors.New("a conflict has been detected")
	ErrInvalidCommand   = errors.New("invalid command")
	ErrNotFound         = errors.New("not found")
	ErrArrayOutOfBounds = errors.New("array index is out of bounds")
	ErrInvalidIndex     = errors.New("invalid index")
	ErrRecursionTooDeep = errors.New("recursion too deep")
	ErrNonSerializable  = errors.New("non-serializeable objects encountered")
)

Functions

func StringToBestType

func StringToBestType(s string) any

StringToBestType does a reasonable effort to determine if there is a better type being presented. Either an int64, float64, bool or the original string is returned with preference for the type also in that order.

Types

type Object

type Object struct {
	Origins []Origin          // The list of origins that influenced this Object.
	Array   []Object          // The array of Objects (if a map).
	Map     map[string]Object // The map of Objects (if a map).
	Value   any               // The value of the configuration parameter (if a value).
	// contains filtered or unexported fields
}

Object represents either a map, of objects, and array of objects or a specific configuration value and the origins of how this Object came into existence.

To build an Object tree, either add to the Array, Map or Value fields. Don't add to them all, as only one will be used. The order is Array > Map > Value. So for example, if you add to the Array field and the Value field, the Value field will always be ignored.

func ObjectFromRaw

func ObjectFromRaw(in any, at ...string) (obj Object)

ObjectFromRaw converts a native go tree into the equivalent Object tree structure.

func ObjectFromRawWithOrigin

func ObjectFromRawWithOrigin(in any, where []Origin, at ...string) (obj Object)

ObjectFromRawWithOrigin converts a native go tree into the equivalent Object tree structure with the specified origin applied across the tree.

func (Object) AdaptToRaw

func (obj Object) AdaptToRaw(adapter func(from, to reflect.Value) (any, error)) (Object, error)

AdaptToRaw uses the provided converter function against each parameter and builds a new tree based on the output. This allows for user provided adapters to translate from string to a time.Time{} for example. If multiple adapters are needed provide a single adapter with the logic of applying the list.

# Note The adapter must return the original object, and an error of nil if no transformation took place.

func (Object) Add

func (obj Object) Add(keyDelimiter, key string, val any, origin ...Origin) (Object, error)

Add adds an object to the tree assuming the key needs to be split and the tree may need to be created or added to depending on what is existing. The returned object is the new tree.

Note that Add will not create arrays, but only maps and values. It will update arrays (either replacing an item, or extending the array by exactly 1 if the index is 1 larger than the array). It is suggested to use Add() to build an object tree and then use the ConvertMapsToArrays() method to do the conversion. This helps eliminate problems due to sparcely populated arrays not being allowed.

func (Object) AlterKeyCase

func (obj Object) AlterKeyCase(to func(string) string) Object

AlterKeyCase builds a copy of the tree where the keys for all Objects have been converted using the specified conversion function. If the to function returns the value "-" then the key and it's subtree is dropped entirely.

func (Object) Clone

func (obj Object) Clone() Object

Clone builds a copy of the tree where secrets are redacted. Secret maps or arrays will now show up as values containing the value 'REDACTED'.

func (Object) ConvertMapsToArrays

func (obj Object) ConvertMapsToArrays() Object

ConvertMapsToArrays walks the object tree and looks for any maps that contain only sequential numbers starting with 0. If one is found, then it assumed to be an array and restructured accordingly.

func (Object) ErrOnNonSerializable

func (obj Object) ErrOnNonSerializable() error

ErrOnNonSerializable returns if the types are excluded from the values.

func (Object) Fetch

func (obj Object) Fetch(asks []string, separater string) (Object, error)

Fetch looks up the specific asks in the tree (map keys or array indexes) and returns the found object or provides a contextual error. The separater is used to provide error context.

func (Object) FilterNonSerializable

func (obj Object) FilterNonSerializable() Object

FilterNonSerializable builds a copy of the tree where any non-serializeable types are excluded from the values.

func (Object) IsEmpty

func (o Object) IsEmpty() bool

IsEmpty returns if the object is an empty node. Metadata about the node like the origin or secret are ignored in this determination.

func (Object) Kind

func (o Object) Kind() int

Kind provides the specific kind of Object this is. Array, Map or Value. If it unclear exactly which, Value will be returned.

func (Object) Merge

func (obj Object) Merge(next Object) (Object, error)

Merge performs a merge of the new Object tree onto the existing Object tree using the default semantics and merge rules found in the key commands.

func (Object) OriginString

func (obj Object) OriginString() string

OriginString provides the string for all origins for this Object.

func (Object) ResolveCommands

func (obj Object) ResolveCommands() (Object, error)

ResolveCommands builds a copy of the tree where the commands have been resolved from the keys.

func (Object) ToExpanded

func (obj Object) ToExpanded(max int, origin, start, end string, expander func(string) (string, bool)) (Object, error)

ToExpanded builds a copy of the tree where any matching variables are expanded to the final instance. The max value is used to prevent recursive substitutions from never returning. Instead the process is stopped and an error is returned. The resulting tree is returned.

func (Object) ToRaw

func (obj Object) ToRaw() any

ToRaw converts an Object tree into a native go tree (with no secret or origin history.

func (Object) ToRedacted

func (obj Object) ToRedacted() Object

ToRedacted builds a copy of the tree where secrets are redacted. Secret maps or arrays will now show up as values containing the value 'REDACTED'.

type Origin

type Origin struct {
	File string // Filename where the value originated.
	Line int    // Line number where the value originated.
	Col  int    // Column where the value originated.
}

Origin provides details about an origin of a parameter.

func (Origin) String

func (o Origin) String() string

String returns a useful representation for the origin.