structured

package
v0.57.10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 14, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	InvalidNodeType = 0
	// ScalarNodeType is a NodeType for scalar values.
	// The scalar type currently supported is nil,bool,string,int,float and time.Time.
	ScalarNodeType = 1
	// SequenceNdoeType is a NodeType for sequence(array, slices) values.
	SequenceNodeType = 2
	// MapNodeType is a NodeType for map(dictionary) values. It needs to retain the order of keys.
	MapNodeType = 3
)

Variables

View Source 
var ErrAliasNodeNotSupported = errors.New("alias node is not supported in a yaml. FromYAML does not support alias node")
View Source 
var ErrFieldNotFound = errors.New("field not found")

ErrFieldNotFound is returned when a requested field is not found in the node structure.

View Source 
var ErrInvalidJSON = errors.New("invalid json format")

ErrInvalidJSON indicates that invalid JSON syntax was encountered during scanning.

View Source 
var ErrMultipleDocumentNodeFound = errors.New("multiple document node found in a yaml. FromYAML only supports a single document node")
View Source 
var ErrNonScalarNode = errors.New("this is not a scalar node but called NodeScalarValue method")
View Source 
var ErrUnknownYAMLNodeKind = errors.New("unknown yaml node kind")

Functions

func ReadReflect 

func ReadReflect[T any](r *NodeReader, fieldPath string, target T) error

ReadReflect unmarshals the structured data into a given type after the given fieldPath. TODO: ReadReflect currently marshals and unmarshals the strtucred data into the target. 

There should be room to improve this behavior regarding the performance.

func ReadReflectK8sRuntimeObject 

func ReadReflectK8sRuntimeObject[T runtime.Object](r *NodeReader, fieldPath string, target T) error

ReadReflectK8sRuntimeObject unmarshal the structured data into a type implementing runtime.Object.

Types

type AlphabeticalGoMapKeyOrderProvider 

type AlphabeticalGoMapKeyOrderProvider struct {
}

AlphabeticalGoMapKeyOrderProvider implements GoMapKeyOrderProvider with sorting map keys by alphabetical order.

func (*AlphabeticalGoMapKeyOrderProvider) GetOrderedKeys 

func (a *AlphabeticalGoMapKeyOrderProvider) GetOrderedKeys(sourcePath []string, sourceMap map[string]any) ([]string, error)

type DefaultMergeMapOrderStrategy 

type DefaultMergeMapOrderStrategy struct {
}

func (*DefaultMergeMapOrderStrategy) GetMergedKeyOrder 

func (d *DefaultMergeMapOrderStrategy) GetMergedKeyOrder(prevKeys []string, patchKeys []string, directiveKeys []string) ([]string, error)

GetMergedKeyOrder implements MergeMapOrderStrategy.

type GoMapKeyOrderProvider 

type GoMapKeyOrderProvider interface {
	// GetOrderedKeys returns the keys of map in the order to store keys. This interface is necessary because the order of map keys are not stable in Go.
	GetOrderedKeys(fieldPath []string, mapToDecideOrder map[string]any) ([]string, error)
}

GoMapKeyOrderProvider decides the order of keys from the given map.

type JSONNodeSerializer 

type JSONNodeSerializer struct{}

func (*JSONNodeSerializer) Serialize 

func (j *JSONNodeSerializer) Serialize(node Node) ([]byte, error)

Serialize implements NodeSerializer.

type LazyJSONNode added in v0.57.10 

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

LazyJSONNode represents structured data as an immutable JSON byte buffer and an offset index. Child nodes reuse the underlying byte buffer without allocating sub-slices, adjusting only the offset index.

func (*LazyJSONNode) Children added in v0.57.10 

func (n *LazyJSONNode) Children() NodeChildrenIterator

Children returns an iterator function over the children of this node.

func (*LazyJSONNode) Len added in v0.57.10 

func (n *LazyJSONNode) Len() int

Len returns the count of items in a map or sequence, or 0 for scalars.

func (*LazyJSONNode) NodeScalarValue added in v0.57.10 

func (n *LazyJSONNode) NodeScalarValue() (any, error)

NodeScalarValue returns the scalar value of this node.

func (*LazyJSONNode) Type added in v0.57.10 

func (n *LazyJSONNode) Type() NodeType

Type returns the NodeType of this node.

type MergeArrayStrategy 

type MergeArrayStrategy string
const MergeStrategyMerge MergeArrayStrategy = "merge"
const MergeStrategyReplace MergeArrayStrategy = "replace"

type MergeConfigResolver 

type MergeConfigResolver struct {
	Parent          *MergeConfigResolver
	MergeStrategies map[string]MergeArrayStrategy
	MergeKeys       map[string]string
}

func (*MergeConfigResolver) GetMergeArrayStrategy 

func (r *MergeConfigResolver) GetMergeArrayStrategy(fieldPath string) MergeArrayStrategy

func (*MergeConfigResolver) GetMergeKey 

func (r *MergeConfigResolver) GetMergeKey(fieldPath string) (string, error)

type MergeConfiguration 

type MergeConfiguration struct {
	// MergeMapOrderStrategy decides the order of map keys generated by the merge.
	MergeMapOrderStrategy MergeMapOrderStrategy
	// ArrayMergeConfigResolver resolves array merge strategy of a sequence node at a specific node.
	// Arrays defined in kubernetes manifest can be replaced or merged with using keys. These are different by the field path of the manifest.
	ArrayMergeConfigResolver *MergeConfigResolver
	// contains filtered or unexported fields
}

MergeConfiguration contains configurations of merging a previous node and patch node. This configuration is modified throughout walking every nodes during the merging.

func (*MergeConfiguration) GetArrayMergeStrategyAndKey 

func (c *MergeConfiguration) GetArrayMergeStrategyAndKey(fieldPath []string) (strategy MergeArrayStrategy, mergeKey string, err error)

GetArrayMergeStrategyAndKey returns the strategy of merging a sequence of maps and the key field name used for merging.

type MergeMapOrderStrategy 

type MergeMapOrderStrategy interface {
	// GetMergedKeyOrder returns the order of keys after merging.
	// prevKeys is the keys of previous map.
	// patchKeys is the keys of patch map.
	// directiveKeys is the keys only found in the strategic patch merge directives. These fields are missing in prev and patch, but the existence is inferred from the directives.
	GetMergedKeyOrder(prevKeys []string, patchKeys []string, directiveKeys []string) ([]string, error)
}

type Node 

type Node interface {
	Type() NodeType
	NodeScalarValue() (any, error)
	Children() NodeChildrenIterator
	Len() int
}

Node interfce is a recursive data structure representing structured data.

func FromGoValue 

func FromGoValue(source any, mapKeyOrderProvider GoMapKeyOrderProvider) (Node, error)

FromGoValue instantiate the Node interface from given Go map, slice or scalars.

func FromYAML 

func FromYAML(yamlStr string) (Node, error)

func MergeNode 

func MergeNode(prev Node, patch Node, config MergeConfiguration) (Node, error)

MergeNode merge a previous node with patch node and generates a new Node. This patch supports strategic-merge patch https://github.com/kubernetes/community/blob/master/contributors/devel/sig-api-machinery/strategic-merge-patch.md Refer the following mermaid graph to understand call hierarchy. ```mermaid flowchart TD 

MergeNode --> mergeNode
mergeNode -->|when the node is scalar| mergeScalarNode
mergeNode -->|when the node is sequence| mergeSequenceNode
mergeNode -->|when the node is map| mergeMapNode
mergeSequenceNode -->|when the sequence items are scalar| mergeScalarSequenceNode
mergeSequenceNode -->|when the sequence items are sequence| mergeSequenceSequenceNode
mergeSequenceNode -->|when the sequence items are map| mergeMapSequenceNode
mergeMapSequenceNode -->|when the patch policy is replace| mergeMapSequenceNodeWithReplaceStrategy
mergeMapSequenceNode -->|when the patch policy is merge| mergeMapSequenceNodeWithMergeStrategy

mergeMapNode o-..->|for each items| mergeNode
mergeSequenceSequenceNode o-..->|for each sequences| mergeNode
mergeMapSequenceNodeWithReplaceStrategy o-..->|for each maps| mergeNode
mergeMapSequenceNodeWithMergeStrategy o-.->|for each maps| mergeNode

```

func NewEmptyMapNode 

func NewEmptyMapNode() Node

NewEmptyMapNode returns an empty map node.

func NewFieldFilterNode added in v0.56.0 

func NewFieldFilterNode(original Node, keys []string) Node

NewFieldFilterNode returns a filtered Node that wraps the original Node. It filters out any map children whose keys are present in the ignored keys list.

func NewLazyJSONNode added in v0.57.10 

func NewLazyJSONNode(node Node) (Node, error)

NewLazyJSONNode serializes a given Node to JSON and wraps it in a LazyJSONNode.

func NewLazyJSONNodeFromBytes added in v0.57.10 

func NewLazyJSONNodeFromBytes(data []byte) Node

NewLazyJSONNodeFromBytes creates a LazyJSONNode from a JSON byte slice.

func NewStandardMap 

func NewStandardMap(keys []string, values []Node) Node

NewStandardMap returns a map node from given key and values with keeping the order of map keys.

func NewStandardSequenceNode added in v0.56.0 

func NewStandardSequenceNode(values []Node) Node

NewStandardSequenceNode returns a sequence node from given values.

func WithKeyOrder added in v0.57.10 

func WithKeyOrder(node Node, priorityKeys ...string) Node

WithKeyOrder wraps a map Node to customize its Children() iteration order. It yields children with keys matching priorityKeys in the specified order first, followed by any remaining children in their original order. If the node is not a MapNodeType or priorityKeys is empty, it returns the original node.

func WithScalarField 

func WithScalarField[T comparable](node Node, fieldPath []string, value T) (Node, error)

WithScalarField add a new scalar value node at the specified field path.

type NodeChildrenIterator 

type NodeChildrenIterator = func(func(key NodeChildrenKey, value Node) bool)

NodeChildrenIterator is a type to represent the iterator returned from the Children method of Node interface.

type NodeChildrenKey 

type NodeChildrenKey struct {
	// Index is the index of the children
	Index int
	// Key is the key of the children in the map.
	// This value is empty when the Node is a sequence and not a map.
	Key string
}

NodeChildrenElement represents an item of Chidlren of a Node.

type NodeReader 

type NodeReader struct {
	Node
}

NodeReader provides a convenient way to read values from a node structure. It offers type-safe accessor methods and path navigation capabilities.

func NewNodeReader 

func NewNodeReader(node Node) *NodeReader

NewNodeReader creates a new NodeReader instance from a given Node.

func (*NodeReader) Children 

func (n *NodeReader) Children() NodeReaderChildrenIterator

Children returns an iterator for navigating through readers of the children of this node.

func (*NodeReader) GetReader 

func (n *NodeReader) GetReader(fieldPath string) (*NodeReader, error)

GetReader obtains the NodeReader from the specified field path.

func (*NodeReader) Has 

func (n *NodeReader) Has(fieldPath string) bool

Has checks if a field exists at the specified path in the node structure. Returns true if the field exists, false otherwise.

func (*NodeReader) ReadBool 

func (n *NodeReader) ReadBool(fieldPath string) (bool, error)

ReadBool retrieves a boolean value from the specified field path. Returns an error if the field doesn't exist or cannot be cast to a boolean.

func (*NodeReader) ReadBoolOrDefault 

func (n *NodeReader) ReadBoolOrDefault(fieldPath string, defaultValue bool) bool

ReadBoolOrDefault retrieves a boolean value from the specified field path. Returns the provided default value if the field doesn't exist or an error occurs.

func (*NodeReader) ReadFloat 

func (n *NodeReader) ReadFloat(fieldPath string) (float64, error)

ReadFloat retrieves a floating-point value from the specified field path. Returns an error if the field doesn't exist or cannot be cast to a float64.

func (*NodeReader) ReadFloatOrDefault 

func (n *NodeReader) ReadFloatOrDefault(fieldPath string, defaultValue float64) float64

ReadFloatOrDefault retrieves a floating-point value from the specified field path. Returns the provided default value if the field doesn't exist or an error occurs.

func (*NodeReader) ReadInt 

func (n *NodeReader) ReadInt(fieldPath string) (int, error)

ReadInt retrieves an integer value from the specified field path. Returns an error if the field doesn't exist or cannot be cast to an integer.

func (*NodeReader) ReadIntOrDefault 

func (n *NodeReader) ReadIntOrDefault(fieldPath string, defaultValue int) int

ReadIntOrDefault retrieves an integer value from the specified field path. Returns the provided default value if the field doesn't exist or an error occurs.

func (*NodeReader) ReadString 

func (n *NodeReader) ReadString(fieldPath string) (string, error)

ReadString retrieves a string value from the specified field path. Returns an error if the field doesn't exist or cannot be cast to a string.

func (*NodeReader) ReadStringOrDefault 

func (n *NodeReader) ReadStringOrDefault(fieldPath string, defaultValue string) string

ReadStringOrDefault retrieves a string value from the specified field path. Returns the provided default value if the field doesn't exist or an error occurs.

func (*NodeReader) ReadTimestamp 

func (n *NodeReader) ReadTimestamp(fieldPath string) (time.Time, error)

ReadTimestamp retrieves a timestamp value from the specified field path. Returns an error if the field doesn't exist or cannot be cast to a time.Time.

func (*NodeReader) ReadTimestampOrDefault 

func (n *NodeReader) ReadTimestampOrDefault(fieldPath string, defaultValue time.Time) time.Time

ReadTimestampOrDefault retrieves a timestamp value from the specified field path. Returns the provided default value if the field doesn't exist or an error occurs.

func (*NodeReader) Serialize 

func (n *NodeReader) Serialize(fieldPath string, serializer NodeSerializer) ([]byte, error)

Serialize serializes the structured data with the given NodeSerializer.

func (*NodeReader) WithKeyOrder added in v0.57.10 

func (n *NodeReader) WithKeyOrder(priorityKeys ...string) *NodeReader

WithKeyOrder returns a new NodeReader wrapping the node with the specified key order.

type NodeReaderChildrenIterator 

type NodeReaderChildrenIterator = func(func(key NodeChildrenKey, value NodeReader) bool)

NodeReaderChildrenIterator is a type that represents an iterator function for navigating

type NodeSerializer 

type NodeSerializer interface {
	Serialize(node Node) ([]byte, error)
}

type NodeType 

type NodeType int

type StandardMapNode 

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

StandardMapNode is a map field of structured data implementing Node interface. This type retain the order of keys.

func (*StandardMapNode) Children 

func (n *StandardMapNode) Children() NodeChildrenIterator

func (*StandardMapNode) Len 

func (n *StandardMapNode) Len() int

func (*StandardMapNode) MarshalJSON 

func (n *StandardMapNode) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*StandardMapNode) MarshalYAML 

func (n *StandardMapNode) MarshalYAML() (interface{}, error)

MarshalYAML implements yaml.Marshaler.

func (*StandardMapNode) NodeScalarValue 

func (n *StandardMapNode) NodeScalarValue() (any, error)

func (*StandardMapNode) Type 

func (n *StandardMapNode) Type() NodeType

type StandardScalarNode 

type StandardScalarNode[T comparable] struct {
	// contains filtered or unexported fields
}

StandardScalarNode is a leaf of structured data implementing Node interface.

func NewStandardScalarNode 

func NewStandardScalarNode[T comparable](value T) *StandardScalarNode[T]

NewStandardScalarNode instantiates the value of StandardScalarNode from the given value.

func (*StandardScalarNode[T]) Children 

func (n *StandardScalarNode[T]) Children() NodeChildrenIterator

func (*StandardScalarNode[T]) Len 

func (n *StandardScalarNode[T]) Len() int

func (*StandardScalarNode[T]) MarshalJSON 

func (n *StandardScalarNode[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*StandardScalarNode[T]) MarshalYAML 

func (n *StandardScalarNode[T]) MarshalYAML() (interface{}, error)

MarshalYAML implements yaml.Marshaler.

func (*StandardScalarNode[T]) NodeScalarValue 

func (n *StandardScalarNode[T]) NodeScalarValue() (any, error)

func (*StandardScalarNode[T]) Type 

func (n *StandardScalarNode[T]) Type() NodeType

type StandardSequenceNode 

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

StandardScalarNode is a sequence field of a structured data implementing Node interface.

func (*StandardSequenceNode) Children 

func (n *StandardSequenceNode) Children() NodeChildrenIterator

func (*StandardSequenceNode) Len 

func (n *StandardSequenceNode) Len() int

func (*StandardSequenceNode) MarshalJSON 

func (n *StandardSequenceNode) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*StandardSequenceNode) MarshalYAML 

func (n *StandardSequenceNode) MarshalYAML() (interface{}, error)

MarshalYAML implements yaml.Marshaler.

func (*StandardSequenceNode) NodeScalarValue 

func (n *StandardSequenceNode) NodeScalarValue() (any, error)

func (*StandardSequenceNode) Type 

func (n *StandardSequenceNode) Type() NodeType

type YAMLNodeSerializer 

type YAMLNodeSerializer struct{}

func (*YAMLNodeSerializer) Serialize 

func (y *YAMLNodeSerializer) Serialize(node Node) ([]byte, error)

Serialize implements NodeSerializer.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.