tree

Documentation

Overview

Package tree provides an in-memory configuration tree used as the central data structure by go-config.

Key Types

• Node — a tree node that can be a leaf (holding a scalar Value) or a branch (with ordered children via omap.OrderedMap). Each node tracks its Source, Revision, and Range (source position). Nodes can represent YAML maps or arrays.
• Value (type alias for any) — the raw value stored in leaf nodes.
• Range / Position — source position tracking for nodes (line/column).

Constructors and Converters

• NewValue — creates a value.Value from a tree node, implementing type conversion (Get) and metadata (Meta).
• ToAny — converts a Node tree to a generic Go value (map[string]any, []any, or primitive).

Node Operations

The tree supports operations such as Child, SetChild, ChildrenKeys, DeepCopy, Merge, Walk, IsLeaf, MarkArray, and more.

Index

• Variables
• func NewValue(node *Node, keyPath keypath.KeyPath) value.Value
• func ToAny(node *Node) any
• type Node
  • func New() *Node
  • func (n *Node) Child(key string) *Node
  • func (n *Node) Children() []*Node
  • func (n *Node) ChildrenKeys() []string
  • func (n *Node) ClearChildren()
  • func (n *Node) DeleteChild(key string) bool
  • func (n *Node) Get(path keypath.KeyPath) *Node
  • func (n *Node) GetValue(path keypath.KeyPath) Value
  • func (n *Node) HasChild(key string) bool
  • func (n *Node) IsArray() bool
  • func (n *Node) IsLeaf() bool
  • func (n *Node) MarkArray()
  • func (n *Node) OrderSet() bool
  • func (n *Node) ReorderChildren(keys []string) error
  • func (n *Node) Set(path keypath.KeyPath, value Value)
  • func (n *Node) SetChild(key string, child *Node)
  • func (n *Node) SetOrderSet(v bool)
• type Position
• type Range
  • func NewRange(startLine, startCol, endLine, endCol int) Range
  • func NewZeroRange() Range
• type Value

Variables

var (
	// ErrDestinationMustBePointer is returned when destination is not a non-nil pointer.
	ErrDestinationMustBePointer = errors.New("destination must be a non-nil pointer")
	// ErrUnsupportedDestinationType is returned when destination type is unsupported.
	ErrUnsupportedDestinationType = errors.New("unsupported destination type")
	// ErrParseDuration is returned when a duration string cannot be parsed.
	ErrParseDuration = errors.New("cannot parse duration from string")
	// ErrConvertToDuration is returned when a value cannot be converted to time.Duration.
	ErrConvertToDuration = errors.New("cannot convert to time.Duration")
	// ErrConvertToBool is returned when a value cannot be converted to bool.
	ErrConvertToBool = errors.New("cannot convert to bool")
	// ErrConvertToInt is returned when a value cannot be converted to int.
	ErrConvertToInt = errors.New("cannot convert to int")
	// ErrOverflow is returned when a value overflows the destination type.
	ErrOverflow = errors.New("overflow")
	// ErrNegativeToUnsigned is returned when a negative value cannot be converted to unsigned.
	ErrNegativeToUnsigned = errors.New("cannot convert negative value to unsigned")
	// ErrConvertToUint is returned when a value cannot be converted to uint.
	ErrConvertToUint = errors.New("cannot convert to uint")
	// ErrConvertToFloat is returned when a value cannot be converted to float.
	ErrConvertToFloat = errors.New("cannot convert to float")
	// ErrSourceNotSliceOrArray is returned when source is not a slice or array.
	ErrSourceNotSliceOrArray = errors.New("source is not a slice or array")
	// ErrSourceNotMap is returned when source is not a map.
	ErrSourceNotMap = errors.New("source is not a map")
	// ErrDestinationMapStringKeys is returned when destination map does not have string keys.
	ErrDestinationMapStringKeys = errors.New("destination map must have string keys")
	// ErrSourceMapKeyNotString is returned when source map key is not string.
	ErrSourceMapKeyNotString = errors.New("source map key is not string")
	// ErrSourceForStructMustBeMap is returned when source for struct is not a map.
	ErrSourceForStructMustBeMap = errors.New("source for struct must be a map")
	// ErrSourceMapMustHaveStringKeys is returned when source map does not have string keys.
	ErrSourceMapMustHaveStringKeys = errors.New("source map must have string keys")
)

Functions

func NewValue

func NewValue(node *Node, keyPath keypath.KeyPath) value.Value

NewValue creates a new value.Value from a tree node and its key path. The source information and revision are extracted from the node.

func ToAny

func ToAny(node *Node) any

ToAny converts a Node tree to a generic Go value suitable for JSON validation. Returns:

• primitive value for leaf nodes
• []any for array nodes (nodes marked with MarkArray)
• map[string]any for object nodes

Types

type Node

type Node struct {
	// Value holds the node's value if it's a leaf node.
	Value Value

	// Source indicates where this node's value came from (e.g., file, env, flag).
	Source string

	// Revision is a version identifier for the node (e.g., commit hash, timestamp).
	Revision string

	// Range indicates the position in source file where this node was defined.
	Range Range
	// contains filtered or unexported fields
}

Node represents a node in the configuration tree.

func New

func New() *Node

New creates a new empty node.

func (*Node) Child

func (n *Node) Child(key string) *Node

Child returns the child node for the given key, or nil if not found.

func (*Node) Children

func (n *Node) Children() []*Node

Children returns the child nodes in insertion order.

func (*Node) ChildrenKeys

func (n *Node) ChildrenKeys() []string

ChildrenKeys returns the keys of child nodes in insertion order.

func (*Node) ClearChildren

func (n *Node) ClearChildren()

ClearChildren removes all child nodes and resets the orderSet flag.

func (*Node) DeleteChild

func (n *Node) DeleteChild(key string) bool

DeleteChild removes a child node by key. It also removes the key from the insertion order.

func (*Node) Get

func (n *Node) Get(path keypath.KeyPath) *Node

Get returns the node at the given path, or nil if not found.

func (*Node) GetValue

func (n *Node) GetValue(path keypath.KeyPath) Value

GetValue returns the value at the given path, or nil if not found or node is not a leaf.

func (*Node) HasChild

func (n *Node) HasChild(key string) bool

HasChild returns true if the node has a child with the given key.

func (*Node) IsArray

func (n *Node) IsArray() bool

IsArray returns true if this node represents a sequence (array).

func (*Node) IsLeaf

func (n *Node) IsLeaf() bool

IsLeaf returns true if the node has no children.

func (*Node) MarkArray

func (n *Node) MarkArray()

MarkArray marks this node as representing a sequence (array).

func (*Node) OrderSet

func (n *Node) OrderSet() bool

OrderSet returns true if the order of children has been set by a higher-priority ordered collector.

func (*Node) ReorderChildren

func (n *Node) ReorderChildren(keys []string) error

ReorderChildren reorders the node's children according to the provided keys. Only keys present in the keys slice are reordered; other keys keep their relative positions. Keys that are not present in the node's children are ignored. If the node has no children or keys is empty, nothing happens.

func (*Node) Set

func (n *Node) Set(path keypath.KeyPath, value Value)

Set sets the value at the given path, creating intermediate nodes as needed.

func (*Node) SetChild

func (n *Node) SetChild(key string, child *Node)

SetChild sets or replaces a child node under the given key. If a child with this key already exists, it is replaced and the insertion order is preserved. If the child is new, it is appended to the end of the order.

func (*Node) SetOrderSet

func (n *Node) SetOrderSet(v bool)

SetOrderSet sets the orderSet flag.

type Position

type Position struct {
	Line   int // Line number (1-based), 0 if unknown.
	Column int // Column number (1-based), 0 if unknown.
}

Position describes a position in source file.

type Range

type Range struct {
	Start Position
	End   Position
}

Range describes a range in source file for highlighting.

func NewRange

func NewRange(startLine, startCol, endLine, endCol int) Range

NewRange creates a Range with given start and end positions.

func NewZeroRange

func NewZeroRange() Range

NewZeroRange creates a zero Range (unknown position).

type Value

type Value any

Value represents a configuration value.