walk

Documentation

Index

• Variables
• func Depth(p string) uint
• func Unescape(path string) string
• type Context
  • func (c *Context) Break()
• type FoundType
• type Path
  • func MustParse(p string) *Path
  • func Parse(p string) (*Path, error)
  • func (p *Path) Clone() *Path
  • func (p *Path) Depth() uint
  • func (p *Path) First(currentElement any) *Context
  • func (p *Path) HasArray() bool
  • func (p *Path) IsWildcard() bool
  • func (p *Path) LastParent() *Path
  • func (p *Path) String() string
  • func (p *Path) Tail() *Path
  • func (p *Path) Truncate(depth uint) *Path
  • func (p *Path) UnescapedString() string
  • func (p *Path) Walk(currentElement any, f func(*Context))
• type PathType

Variables

var (
	// EscapeChars the list of characters that can be escaped using a backslash `\` when
	// parsing a Path. This map is read-only.
	EscapeChars = map[rune]struct{}{
		'*':  {},
		'[':  {},
		']':  {},
		'.':  {},
		'\\': {},
	}
)

Functions

func Depth

func Depth(p string) uint

Depth calculate the path's depth without parsing it.

func Unescape

func Unescape(path string) string

Unescape remove escape characters from a path without parsing it.

Types

type Context

type Context struct {
	Value  any
	Parent any       // Either map[string]any or a slice
	Path   *Path     // Exact Path to the current element
	Name   string    // Name of the current element
	Index  int       // If parent is a slice, the index of the current element in the slice, else -1
	Found  FoundType // True if the path could not be completely explored
	// contains filtered or unexported fields
}

Context information sent to walk function.

func (*Context) Break

func (c *Context) Break()

Break when called, indicates the path walker to stop. This means the current call of the callback function will be the last.

type FoundType

type FoundType int

FoundType adds extra information about not found elements whether what's not found is their parent or themselves.

const (
	// Found indicates the element could be found.
	Found FoundType = iota
	// ParentNotFound indicates one of the parents of the element could no be found.
	ParentNotFound
	// ElementNotFound indicates all parents of the element were found but the element
	// itself could not.
	ElementNotFound
)

type Path

type Path struct {
	Next  *Path
	Index *int
	Name  *string
	Type  PathType
}

Path allows for complex untyped data structure exploration. An instance of this structure represents a step in exploration. Items NOT having `PathTypeElement` as a `Type` are expected to have a non-nil `Next`.

func MustParse

func MustParse(p string) *Path

MustParse is the same as `Parse` but panics if there is an error.

func Parse

func Parse(p string) (*Path, error)

Parse transform given path string representation into usable Path.

The wildcard `*` can be used to match all keys of an object. It is only effective if it is an entire path segment. For example, the `*` in `field*name` won't be considered a wildcard and only the literal field will match.

Special characters defined in the `Escape` map (by default `*`, `[`, `]`, `.` and `\`) can be escaped using a backslack `\`.

Example paths:

name
object.field
object.subobject.field
object.*
object.\*
object.array[]
object.arrayOfObjects[].field
[]
[].field
field*name
object.field\[]
object.field\[text\]
abc\[\]def
path\\to\\element

func (*Path) Clone

func (p *Path) Clone() *Path

Clone returns a deep clone of this Path.

func (*Path) Depth

func (p *Path) Depth() uint

Depth returns the depth of the path. For each step in the path, increments the depth by one.

func (*Path) First

func (p *Path) First(currentElement any) *Context

First returns the first final element matched by the Path. Note that the returned Context may indicate that the value could not be found, so you should always check `Context.Found` before using `Context.Value`.

Bear in mind that map iteration order is not guaranteed. Using paths containing wildcards `*` will not always yield the same result.

func (*Path) HasArray

func (p *Path) HasArray() bool

HasArray returns true if a least one step in the path involves an array.

func (*Path) IsWildcard

func (p *Path) IsWildcard() bool

IsWildcard returns true if the path has unescaped "*" as Name.

func (*Path) LastParent

func (p *Path) LastParent() *Path

LastParent returns the last step in the path that is not a PathTypeElement, excluding the first step in the path, or nil.

func (*Path) String

func (p *Path) String() string

String returns a string representation of the Path. The result contains the escape characters, if any.

func (*Path) Tail

func (p *Path) Tail() *Path

Tail returns the last step in the path.

func (*Path) Truncate

func (p *Path) Truncate(depth uint) *Path

Truncate returns a clone of the n first steps of the path so the returned path's depth equals the given depth.

func (*Path) UnescapedString

func (p *Path) UnescapedString() string

UnescapedString returns a string representation of the Path without the escape characters.

func (*Path) Walk

func (p *Path) Walk(currentElement any, f func(*Context))

Walk this path and execute the given callback for each matching element. Elements are final, meaning they are the deepest explorable element using this path. Only `map[string]any` and n-dimensional slices parents are supported. The given "f" function is executed for each final element matched. If the path cannot be completed because the step's name doesn't exist in the currently explored map, the function will be executed as well, with a the `Context`'s `NotFound` field set to `true`.

type PathType

type PathType int

PathType type of the element being explored.

const (
	// PathTypeElement the explored element is used as a final element (leaf).
	PathTypeElement PathType = iota

	// PathTypeArray the explored element is used as an array and not a final element.
	// All elements in the array will be explored using the next Path.
	PathTypeArray

	// PathTypeObject the explored element is used as an object (`map[string]any`)
	// and not a final element.
	PathTypeObject
)