low

Documentation

Overview

Package low contains a set of low-level models that represent OpenAPI 2 and 3 documents. These low-level models (plumbing) are used to create high-level models, and used when deep knowledge about the original data, positions, comments and the original node structures.

Low-level models are not designed to be easily navigated, every single property is either a NodeReference an KeyReference or a ValueReference. These references hold the raw value and key or value nodes that contain the original yaml.Node trees that make up the object.

Navigating maps that use a KeyReference as a key is tricky, because there is no easy way to provide a lookup. Convenience methods for lookup up properties in a low-level model have therefore been provided.

Index

• func BuildModel(node *yaml.Node, model interface{}) error
• func BuildModelAsync(n *yaml.Node, model interface{}, lwg *sync.WaitGroup, errors *[]error)
• func ExtractExtensions(root *yaml.Node) map[KeyReference[string]]ValueReference[any]
• func ExtractMap[PT Buildable[N], N any](label string, root *yaml.Node, idx *index.SpecIndex) (map[KeyReference[string]]ValueReference[PT], *yaml.Node, *yaml.Node, error)
• func ExtractMapNoLookup[PT Buildable[N], N any](root *yaml.Node, idx *index.SpecIndex) (map[KeyReference[string]]ValueReference[PT], error)
• func ExtractObjectRaw[T Buildable[N], N any](root *yaml.Node, idx *index.SpecIndex) (T, error)
• func GetCircularReferenceResult(node *yaml.Node, idx *index.SpecIndex) *index.CircularReferenceResult
• func IsCircular(node *yaml.Node, idx *index.SpecIndex) bool
• func LocateRefNode(root *yaml.Node, idx *index.SpecIndex) (*yaml.Node, error)
• func SetField(field reflect.Value, valueNode *yaml.Node, keyNode *yaml.Node) error
• type Buildable
• type KeyReference
  • func (n KeyReference[T]) GenerateMapKey() string
  • func (n KeyReference[T]) IsEmpty() bool
• type NodeReference
  • func ExtractExample(expNode, expLabel *yaml.Node) NodeReference[any]
  • func ExtractObject[T Buildable[N], N any](label string, root *yaml.Node, idx *index.SpecIndex) (NodeReference[T], error)
  • func (n NodeReference[T]) GenerateMapKey() string
  • func (n NodeReference[T]) IsEmpty() bool
  • func (n NodeReference[T]) Mutate(value T) NodeReference[T]
• type ValueReference
  • func ExtractArray[T Buildable[N], N any](label string, root *yaml.Node, idx *index.SpecIndex) ([]ValueReference[T], *yaml.Node, *yaml.Node, error)
  • func FindItemInMap[T any](item string, collection map[KeyReference[string]]ValueReference[T]) *ValueReference[T]
  • func (n ValueReference[T]) GenerateMapKey() string
  • func (n ValueReference[T]) IsEmpty() bool
  • func (n ValueReference[T]) Mutate(value T) ValueReference[T]

Functions

func BuildModel

func BuildModel(node *yaml.Node, model interface{}) error

BuildModel accepts a yaml.Node pointer and a model, which can be any struct. Using reflection, the model is analyzed and the names of all the properties are extracted from the model and subsequently looked up from within the yaml.Node.Content value.

BuildModel is non-recursive and will only build out a single layer of the node tree.

func BuildModelAsync

func BuildModelAsync(n *yaml.Node, model interface{}, lwg *sync.WaitGroup, errors *[]error)

BuildModelAsync is a convenience function for calling BuildModel from a goroutine, requires a sync.WaitGroup

func ExtractExtensions

func ExtractExtensions(root *yaml.Node) map[KeyReference[string]]ValueReference[any]

ExtractExtensions will extract any 'x-' prefixed key nodes from a root node into a map. Values have been pre-cast:

Maps

map[string]interface{} for maps

Slices

[]interface{}

int, float, bool, string

int64, float64, bool, string

func ExtractMap

func ExtractMap[PT Buildable[N], N any](
	label string,
	root *yaml.Node,
	idx *index.SpecIndex) (map[KeyReference[string]]ValueReference[PT], *yaml.Node, *yaml.Node, error)

ExtractMap will extract a map of KeyReference and ValueReference from a root yaml.Node. The 'label' is used to locate the node to be extracted from the root node supplied.

The second return value is the yaml.Node found for the 'label' and the third return value is the yaml.Node found for the value extracted from the label node.

func ExtractMapNoLookup

func ExtractMapNoLookup[PT Buildable[N], N any](
	root *yaml.Node,
	idx *index.SpecIndex) (map[KeyReference[string]]ValueReference[PT], error)

ExtractMapNoLookup will extract a map of KeyReference and ValueReference from a root yaml.Node. The 'NoLookup' part refers to the fact that there is no key supplied as part of the extraction, there is no lookup performed and the root yaml.Node pointer is used directly.

This is useful when the node to be extracted, is already known and does not require a search.

func ExtractObjectRaw

func ExtractObjectRaw[T Buildable[N], N any](root *yaml.Node, idx *index.SpecIndex) (T, error)

ExtractObjectRaw will extract a typed Buildable[N] object from a root yaml.Node. The 'raw' aspect is that there is no NodeReference wrapper around the result returned, just the raw object.

func GetCircularReferenceResult

func GetCircularReferenceResult(node *yaml.Node, idx *index.SpecIndex) *index.CircularReferenceResult

GetCircularReferenceResult will check if a node is part of a circular reference chain and then return that index.CircularReferenceResult it was located in. Returns nil if not found.

func IsCircular

func IsCircular(node *yaml.Node, idx *index.SpecIndex) bool

IsCircular will determine if the node in question, is part of a circular reference chain discovered by the index.

func LocateRefNode

func LocateRefNode(root *yaml.Node, idx *index.SpecIndex) (*yaml.Node, error)

LocateRefNode will perform a complete lookup for a $ref node. This function searches the entire index for the reference being supplied. If there is a match found, the reference *yaml.Node is returned.

func SetField

func SetField(field reflect.Value, valueNode *yaml.Node, keyNode *yaml.Node) error

SetField accepts a field reflection value, a yaml.Node valueNode and a yaml.Node keyNode. Using reflection, the function will attempt to set the value of the field based on the key and value nodes. This method is only useful for low-level models, it has no value to high-level ones.

Types

type Buildable

type Buildable[T any] interface {
	Build(node *yaml.Node, idx *index.SpecIndex) error
	*T
}

Buildable is an interface for any struct that can be 'built out'. This means that a struct can accept a root node and a reference to the index that carries data about any references used.

Used by generic functions when automatically building out structs based on yaml.Node inputs.

type KeyReference

type KeyReference[T any] struct {

	// The value being referenced.
	Value T

	// The yaml.Node that holds this referenced key
	KeyNode *yaml.Node
}

KeyReference is a low-level container for key nodes holding a Value of type T. A KeyNode is a pointer to the yaml.Node that holds a key to a value.

func (KeyReference[T]) GenerateMapKey

func (n KeyReference[T]) GenerateMapKey() string

GenerateMapKey will return a string based on the line and column number of the node, e.g. 33:56 for line 33, col 56.

func (KeyReference[T]) IsEmpty

func (n KeyReference[T]) IsEmpty() bool

IsEmpty will return true if this reference has no key or value nodes assigned (it's been ignored)

type NodeReference

type NodeReference[T any] struct {

	// The value being referenced
	Value T

	// The yaml.Node that holds the value
	ValueNode *yaml.Node

	// The yaml.Node that is the key, that contains the value.
	KeyNode *yaml.Node
}

NodeReference is a low-level container for holding a Value of type T, as well as references to a key yaml.Node that points to the key node that contains the value node, and the value node that contains the actual value.

func ExtractExample

func ExtractExample(expNode, expLabel *yaml.Node) NodeReference[any]

ExtractExample will extract a value supplied as an example into a NodeReference. Value can be anything. the node value is untyped, so casting will be required when trying to use it.

func ExtractObject

func ExtractObject[T Buildable[N], N any](label string, root *yaml.Node, idx *index.SpecIndex) (NodeReference[T], error)

ExtractObject will extract a typed Buildable[N] object from a root yaml.Node. The result is wrapped in a NodeReference[T] that contains the key node found and value node found when looking up the reference.

func (NodeReference[T]) GenerateMapKey

func (n NodeReference[T]) GenerateMapKey() string

GenerateMapKey will return a string based on the line and column number of the node, e.g. 33:56 for line 33, col 56.

func (NodeReference[T]) IsEmpty

func (n NodeReference[T]) IsEmpty() bool

IsEmpty will return true if this reference has no key or value nodes assigned (it's been ignored)

func (NodeReference[T]) Mutate

func (n NodeReference[T]) Mutate(value T) NodeReference[T]

Mutate will set the reference value to what is supplied. This happens to both the Value and ValueNode, which means the root document is permanently mutated and changes will be reflected in any serialization of the root document.

type ValueReference

type ValueReference[T any] struct {

	// The value being referenced.
	Value T

	// The yaml.Node that holds the referenced value
	ValueNode *yaml.Node
}

ValueReference is a low-level container for value nodes that hold a Value of type T. A ValueNode is a pointer to the yaml.Node that holds the value.

func ExtractArray

func ExtractArray[T Buildable[N], N any](label string, root *yaml.Node, idx *index.SpecIndex) ([]ValueReference[T],
	*yaml.Node, *yaml.Node, error)

ExtractArray will extract a slice of []ValueReference[T] from a root yaml.Node that is defined as a sequence. Used when the value being extracted is an array.

func FindItemInMap

func FindItemInMap[T any](item string, collection map[KeyReference[string]]ValueReference[T]) *ValueReference[T]

FindItemInMap accepts a string key and a collection of KeyReference[string] and ValueReference[T]. Every KeyReference will have its value checked against the string key and if there is a match, it will be returned.

func (ValueReference[T]) GenerateMapKey

func (n ValueReference[T]) GenerateMapKey() string

GenerateMapKey will return a string based on the line and column number of the node, e.g. 33:56 for line 33, col 56.

func (ValueReference[T]) IsEmpty

func (n ValueReference[T]) IsEmpty() bool

IsEmpty will return true if this reference has no key or value nodes assigned (it's been ignored)

func (ValueReference[T]) Mutate

func (n ValueReference[T]) Mutate(value T) ValueReference[T]

Mutate will set the reference value to what is supplied. This happens to both the Value and ValueNode, which means the root document is permanently mutated and changes will be reflected in any serialization of the root document.