gaby

package
v0.2.21 Latest Latest
Warning

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

 Go to latest Published: Aug 14, 2026 License: MIT, MIT Imports: 11 Imported by: 17

README

gaby

This is a fork of https://github.com/Jeffail/gabs/tree/v2.7.0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrOutOfBounds indicates an index was out of bounds.
	ErrOutOfBounds = errors.New("out of bounds")

	// ErrNotObjOrArray is returned when a target is not an object or array type
	// but needs to be for the intended operation.
	ErrNotObjOrArray = errors.New("not an object or array")

	// ErrNotObj is returned when a target is not an object but needs to be for
	// the intended operation.
	ErrNotObj = errors.New("not an object")

	// ErrInvalidQuery is returned when a search query was not valid.
	ErrInvalidQuery = errors.New("invalid search query")

	// ErrNotArray is returned when a target is not an array but needs to be for
	// the intended operation.
	ErrNotArray = errors.New("not an array")

	// ErrPathCollision is returned when creating a path failed because an
	// element collided with an existing value.
	ErrPathCollision = errors.New("encountered value collision whilst building path")

	// ErrInvalidInputObj is returned when the input value was not a
	// map[string]interface{}.
	ErrInvalidInputObj = errors.New("invalid input object")

	// ErrInvalidInputText is returned when the input data could not be parsed.
	ErrInvalidInputText = errors.New("input text could not be parsed")

	// ErrNotFound is returned when a query leaf is not found.
	ErrNotFound = errors.New("field not found")

	// ErrInvalidPath is returned when the filepath was not valid.
	ErrInvalidPath = errors.New("invalid file path")

	// ErrInvalidBuffer is returned when the input buffer contained an invalid
	// YAML string.
	ErrInvalidBuffer = errors.New("input buffer contained invalid YAML")
)

Error variables similar to gabs

View Source 
var EmptyDocument = []byte("null")

Functions

func DotPathToSlice 

func DotPathToSlice(path string) []string

DotPathToSlice returns a slice of path segments parsed out of a dot path.

func GetRoot 

func GetRoot(doc *YamlDoc) *yaml.RNode

func IsCommentKey added in v0.1.25 

func IsCommentKey(key string) bool

IsCommentKey returns true if the key starts with the $comment$ prefix and contains a valid comment type (head, line, or foot) followed by "$". Matches keys like "$comment$head$foo" and "$comment$line$" (empty target).

func JSONPointerToPath 

func JSONPointerToPath(path string) string

func JSONPointerToSlice 

func JSONPointerToSlice(path string) ([]string, error)

JSONPointerToSlice parses a JSON pointer path (https://tools.ietf.org/html/rfc6901) and returns the path segments as a slice.

Because the characters '~' (%x7E) and '/' (%x2F) have special meanings in gabs paths, '~' needs to be encoded as '~0' and '/' needs to be encoded as '~1' when these characters appear in a reference key.

func NormalizeYAML 

func NormalizeYAML(y string) string

func SetRoot 

func SetRoot(doc *YamlDoc, node *yaml.RNode)

func UnescapeDotsInPathSegment 

func UnescapeDotsInPathSegment(segment string) string

UnescapeDotsInPathSegment unescapes tilde-encoded characters in a path segment. Reverses the encoding done by yamlkit.EscapeDotsInPathSegment: - ~1 becomes . (dot) - ~0 becomes ~ (tilde)

func YAMLPointerToSlice 

func YAMLPointerToSlice(path string) ([]string, error)

YAMLPointerToSlice parses a YAML pointer path and returns the path segments as a slice.

func YamlIsEmpty 

func YamlIsEmpty(y string) bool

Returns true if YAML doc is trivially empty, even no comments

Types

type Container 

type Container []*YamlDoc

func ParseAll 

func ParseAll(y []byte) (Container, error)

func (Container) Bytes 

func (m Container) Bytes() []byte

func (Container) Data 

func (m Container) Data() interface{}

func (Container) Search 

func (m Container) Search(path ...string) Container

func (Container) String 

func (m Container) String() string

type ElementRemover 

type ElementRemover struct {
	Index int
}

func (ElementRemover) Filter 

func (er ElementRemover) Filter(node *yaml.RNode) (*yaml.RNode, error)

type YamlDoc 

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

YamlDoc references a specific element within a YAML structure.

func New 

func New() *YamlDoc

New creates a new gyabs YAML object.

func NewFromData added in v0.1.25 

func NewFromData(data interface{}) (*YamlDoc, error)

NewFromData creates a YamlDoc from arbitrary Go data. Supports map[string]interface{}, *orderedmap.OrderedMap[string, interface{}], []interface{}, and scalar types.

func ParseJSON 

func ParseJSON(y []byte) (*YamlDoc, error)

ParseJSON reads a JSON byte slice and returns a *YamlDoc.

func ParseYAML 

func ParseYAML(y []byte) (*YamlDoc, error)

ParseYAML reads a YAML byte slice and returns a *YamlDoc.

func ParseYAMLBuffer 

func ParseYAMLBuffer(buffer io.Reader) (*YamlDoc, error)

ParseYAMLBuffer reads a buffer and unmarshals the contents into a *YamlDoc.

func ParseYAMLFile 

func ParseYAMLFile(path string) (*YamlDoc, error)

ParseYAMLFile reads a file and unmarshals the contents into a *YamlDoc.

func Wrap 

func Wrap(node *yaml.RNode) *YamlDoc

Wrap wraps an existing *yaml.RNode into a *YamlDoc.

func (*YamlDoc) Array 

func (c *YamlDoc) Array(hierarchy ...string) (*YamlDoc, error)

Array creates a new YAML array at a path. Returns an error if the path contains a collision with a non object type.

func (*YamlDoc) ArrayAppend 

func (c *YamlDoc) ArrayAppend(value interface{}, hierarchy ...string) error

ArrayAppend attempts to append a value onto a YAML array at a path. If the target is not a YAML array then it will be converted into one, with its original contents set to the first element of the array.

func (*YamlDoc) ArrayAppendP 

func (c *YamlDoc) ArrayAppendP(value interface{}, path string) error

ArrayAppendP attempts to append a value onto a YAML array at a path using dot notation. If the target is not a YAML array then it will be converted into one, with its original contents set to the first element of the array.

func (*YamlDoc) ArrayConcat 

func (c *YamlDoc) ArrayConcat(value interface{}, hierarchy ...string) error

ArrayConcat attempts to append a value onto a YAML array at a path. If the target is not a YAML array then it will be converted into one, with its original contents set to the first element of the array.

ArrayConcat differs from ArrayAppend in that it will expand a value of type []interface{} during the append operation, resulting in concatenation of each element, rather than appending as a single element.

func (*YamlDoc) ArrayConcatP 

func (c *YamlDoc) ArrayConcatP(value interface{}, path string) error

ArrayConcatP attempts to append a value onto a YAML array at a path using dot notation. If the target is not a YAML array then it will be converted into one, with its original contents set to the first element of the array.

ArrayConcatP differs from ArrayAppendP in that it will expand a value of type []interface{} during the append operation, resulting in concatenation of each element, rather than appending as a single element.

func (*YamlDoc) ArrayCount 

func (c *YamlDoc) ArrayCount(hierarchy ...string) (int, error)

ArrayCount counts the number of elements in a YAML array at a path.

func (*YamlDoc) ArrayCountP 

func (c *YamlDoc) ArrayCountP(path string) (int, error)

ArrayCountP counts the number of elements in a YAML array at a path using dot notation.

func (*YamlDoc) ArrayElement 

func (c *YamlDoc) ArrayElement(index int, hierarchy ...string) (*YamlDoc, error)

ArrayElement attempts to access an element by an index from a YAML array at a path.

func (*YamlDoc) ArrayElementP 

func (c *YamlDoc) ArrayElementP(index int, path string) (*YamlDoc, error)

ArrayElementP attempts to access an element by an index from a YAML array at a path using dot notation.

func (*YamlDoc) ArrayI 

func (c *YamlDoc) ArrayI(index int) (*YamlDoc, error)

ArrayI creates a new YAML array within an array at an index. Returns an error if the element is not an array or the index is out of bounds.

func (*YamlDoc) ArrayInsert 

func (c *YamlDoc) ArrayInsert(value interface{}, index int, hierarchy ...string) error

ArrayInsert attempts to insert an element at a specified index into a YAML array at a path.

func (*YamlDoc) ArrayInsertP 

func (c *YamlDoc) ArrayInsertP(value interface{}, index int, path string) error

ArrayInsertP attempts to insert an element at a specified index into a YAML array at a path using dot notation.

func (*YamlDoc) ArrayOfSize 

func (c *YamlDoc) ArrayOfSize(size int, hierarchy ...string) (*YamlDoc, error)

ArrayOfSize creates a new YAML array of a particular size at a path. Returns an error if the path contains a collision with a non object type.

func (*YamlDoc) ArrayOfSizeI 

func (c *YamlDoc) ArrayOfSizeI(size, index int) (*YamlDoc, error)

ArrayOfSizeI creates a new YAML array of a particular size within an array at an index. Returns an error if the element is not an array or the index is out of bounds.

func (*YamlDoc) ArrayOfSizeP 

func (c *YamlDoc) ArrayOfSizeP(size int, path string) (*YamlDoc, error)

ArrayOfSizeP creates a new YAML array of a particular size at a path using dot notation. Returns an error if the path contains a collision with a non object type.

func (*YamlDoc) ArrayP 

func (c *YamlDoc) ArrayP(path string) (*YamlDoc, error)

ArrayP creates a new YAML array at a path using dot notation. Returns an error if the path contains a collision with a non object type.

func (*YamlDoc) ArrayRemove 

func (c *YamlDoc) ArrayRemove(index int, hierarchy ...string) error

ArrayRemove attempts to remove an element identified by an index from a YAML array at a path.

func (*YamlDoc) ArrayRemoveP 

func (c *YamlDoc) ArrayRemoveP(index int, path string) error

ArrayRemoveP attempts to remove an element identified by an index from a YAML array at a path using dot notation.

func (*YamlDoc) Bytes 

func (c *YamlDoc) Bytes() []byte

Bytes marshals an element to a YAML []byte blob.

func (*YamlDoc) BytesIndent 

func (c *YamlDoc) BytesIndent(indent int) []byte

BytesIndent marshals an element to a YAML []byte blob formatted with a specified indent. Since YAML inherently supports indentation, this function allows you to set the indentation level.

func (*YamlDoc) BytesWithoutCommentKeys added in v0.1.25 

func (c *YamlDoc) BytesWithoutCommentKeys() []byte

BytesWithoutCommentKeys returns the YAML bytes of this document with all $comment$ keys removed.

func (*YamlDoc) Children 

func (c *YamlDoc) Children() []*YamlDoc

Children returns a slice of all children of an array element. This also works for objects; however, the children returned for an object will be in a random order, and you lose the names of the returned objects this way. If the underlying container value isn't an array or map, nil is returned.

func (*YamlDoc) ChildrenMap 

func (c *YamlDoc) ChildrenMap() map[string]*YamlDoc

ChildrenMap returns a map of all the children of an object element. If the underlying value isn't an object then an empty map is returned.

func (*YamlDoc) Data 

func (c *YamlDoc) Data() interface{}

Data returns the underlying node of the target element in the YAML structure.

func (*YamlDoc) DataOrdered added in v0.1.25 

func (c *YamlDoc) DataOrdered() interface{}

DataOrdered returns the underlying data using *orderedmap.OrderedMap[string, interface{}] for mapping nodes, preserving the key order from the YAML source.

func (*YamlDoc) Delete 

func (c *YamlDoc) Delete(hierarchy ...string) error

Delete an element at a path.

func (*YamlDoc) DeleteCommentKeysForPath added in v0.1.25 

func (c *YamlDoc) DeleteCommentKeysForPath(path string) error

DeleteCommentKeysForPath removes all $comment$ sibling keys associated with the specified data path.

func (*YamlDoc) DeleteP 

func (c *YamlDoc) DeleteP(path string) error

DeleteP deletes an element at a path using dot notation.

func (*YamlDoc) Exists 

func (c *YamlDoc) Exists(hierarchy ...string) bool

Exists checks whether a field exists within the hierarchy.

func (*YamlDoc) ExistsP 

func (c *YamlDoc) ExistsP(path string) bool

ExistsP checks whether a dot notation path exists.

func (*YamlDoc) ExtractCommentsToKeys added in v0.1.25 

func (c *YamlDoc) ExtractCommentsToKeys() error

ExtractCommentsToKeys walks the YAML document tree and converts native HeadComment/LineComment/FootComment on nodes into $comment$ sibling keys in the parent mapping. Clears the original node comments.

func (*YamlDoc) Flatten 

func (c *YamlDoc) Flatten() (map[string]interface{}, error)

Flatten a YAML array or object into an object of key/value pairs for each field, where the key is the full path of the structured field in dot path notation matching the spec for the method Path.

Returns an error if the target is not a YAML object or array.

func (*YamlDoc) FlattenIncludeEmpty 

func (c *YamlDoc) FlattenIncludeEmpty() (map[string]interface{}, error)

FlattenIncludeEmpty a YAML array or object into an object of key/value pairs for each field, just as Flatten, but includes empty arrays and objects, where the key is the full path of the structured field in dot path notation matching the spec for the method Path.

Returns an error if the target is not a YAML object or array.

func (*YamlDoc) GetCommentKeys added in v0.1.25 

func (c *YamlDoc) GetCommentKeys(path string) (head, line, foot string)

GetCommentKeys returns all $comment$ keys and their values from the parent map of the specified path. The path identifies a data key; this method returns any $comment$head$KEY, $comment$line$KEY, $comment$foot$KEY siblings.

func (*YamlDoc) GetComments 

func (c *YamlDoc) GetComments() string

func (*YamlDoc) GetDocComment added in v0.1.25 

func (c *YamlDoc) GetDocComment() (string, bool)

GetDocComment returns the document-level header comment and whether it exists.

func (*YamlDoc) Index 

func (c *YamlDoc) Index(index int) *YamlDoc

Index attempts to find and return an element within a YAML array by an index.

func (*YamlDoc) InjectCommentsFromKeys added in v0.1.25 

func (c *YamlDoc) InjectCommentsFromKeys() error

InjectCommentsFromKeys walks the YAML document and converts $comment$ sibling keys back into HeadComment/LineComment/FootComment on the corresponding data nodes. Removes the $comment$ keys from the document.

func (*YamlDoc) IsArray 

func (c *YamlDoc) IsArray() bool

func (*YamlDoc) IsEmptyDoc 

func (c *YamlDoc) IsEmptyDoc() bool

func (*YamlDoc) JSONPointer 

func (c *YamlDoc) JSONPointer(path string) (*YamlDoc, error)

func (*YamlDoc) MarshalJSON 

func (c *YamlDoc) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of this container.

func (*YamlDoc) MarshalJSONWithoutCommentKeys added in v0.1.25 

func (c *YamlDoc) MarshalJSONWithoutCommentKeys() ([]byte, error)

MarshalJSONWithoutCommentKeys returns the JSON encoding of this document with all $comment$ keys removed.

func (*YamlDoc) MarshalYAML 

func (c *YamlDoc) MarshalYAML() ([]byte, error)

MarshalYAML returns the YAML encoding of this container.

func (*YamlDoc) Merge 

func (c *YamlDoc) Merge(source *YamlDoc) error

Merge merges a source object into an existing destination object. When a collision is found within the merged structures (both a source and destination object contain the same non-object keys), the result will be a sequence containing both values, where values that are already sequences will be expanded into the resulting sequence.

It is possible to merge structures with different collision behaviours with MergeFn.

func (*YamlDoc) MergeDoc 

func (c *YamlDoc) MergeDoc(source *YamlDoc) error

MergeDoc merges a source document into the destination document using kyaml's merge2 strategy. This merge preserves comments and follows Kubernetes strategic merge patch semantics. Unlike Merge, MergeDoc uses kustomize's merge2 implementation which better handles YAML metadata like comments, anchors, and preserves field order where possible.

func (*YamlDoc) MergeDocP 

func (c *YamlDoc) MergeDocP(source *YamlDoc, path string) error

MergeDocP merges a source document into the destination at a specific path using dot notation. The path specifies where in the destination document the merge should occur.

func (*YamlDoc) MergeFn 

func (c *YamlDoc) MergeFn(source *YamlDoc, collisionFn func(destination, source interface{}) interface{}) error

MergeFn merges two objects using a provided function to resolve collisions.

The collision function receives two interface{} arguments, destination (the original object) and source (the object being merged into the destination). Whichever value is returned becomes the new value in the destination object at the location of the collision.

func (*YamlDoc) Object 

func (c *YamlDoc) Object(hierarchy ...string) (*YamlDoc, error)

Object creates a new YAML object at a target path. Returns an error if the path contains a collision with a non object type.

func (*YamlDoc) ObjectI 

func (c *YamlDoc) ObjectI(index int) (*YamlDoc, error)

ObjectI creates a new YAML object at an array index. Returns an error if the object is not an array or the index is out of bounds.

func (*YamlDoc) ObjectP 

func (c *YamlDoc) ObjectP(path string) (*YamlDoc, error)

ObjectP creates a new YAML object at a target path using dot notation. Returns an error if the path contains a collision with a non object type.

func (*YamlDoc) Path 

func (c *YamlDoc) Path(path string) *YamlDoc

Path searches the YAML structure following a path in dot notation, segments of this path are searched according to the same rules as Search.

func (*YamlDoc) S 

func (c *YamlDoc) S(hierarchy ...string) *YamlDoc

S is a shorthand alias for Search.

func (*YamlDoc) Search 

func (c *YamlDoc) Search(hierarchy ...string) *YamlDoc

func (*YamlDoc) Set 

func (c *YamlDoc) Set(value interface{}, hierarchy ...string) (*YamlDoc, error)

Set attempts to set the value of a field located by a hierarchy of field names.

func (*YamlDoc) SetComment 

func (c *YamlDoc) SetComment(comment string)

func (*YamlDoc) SetCommentKey added in v0.1.25 

func (c *YamlDoc) SetCommentKey(path string, commentType string, text string) error

SetCommentKey sets a $comment$ sibling key for the specified data path. commentType should be "head", "line", or "foot".

func (*YamlDoc) SetDocComment added in v0.1.25 

func (c *YamlDoc) SetDocComment(comment string)

SetDocComment sets the document-level header comment key ($comment$head$) on a document.

func (*YamlDoc) SetDocExpandP added in v0.1.25 

func (c *YamlDoc) SetDocExpandP(doc *YamlDoc, path string) (*YamlDoc, error)

SetDocExpandP is like SetDocP but expands arrays on demand.

func (*YamlDoc) SetDocP 

func (c *YamlDoc) SetDocP(doc *YamlDoc, path string) (*YamlDoc, error)

SetDocP sets the value of a field to a YamlDoc at a path using dot notation.

func (*YamlDoc) SetExpand added in v0.1.25 

func (c *YamlDoc) SetExpand(value interface{}, hierarchy ...string) (*YamlDoc, error)

SetExpand is like Set but expands arrays on demand when an index is at or beyond the current length. Missing elements up to the target index are filled with null nodes.

func (*YamlDoc) SetExpandP added in v0.1.25 

func (c *YamlDoc) SetExpandP(value interface{}, path string) (*YamlDoc, error)

SetExpandP is like SetP but expands arrays on demand.

func (*YamlDoc) SetIndex 

func (c *YamlDoc) SetIndex(value interface{}, index int) (*YamlDoc, error)

SetIndex attempts to set a value of an array element based on an index.

func (*YamlDoc) SetP 

func (c *YamlDoc) SetP(value interface{}, path string) (*YamlDoc, error)

SetP sets the value of a field at a path using dot notation.

func (*YamlDoc) SetYAMLPointer 

func (c *YamlDoc) SetYAMLPointer(value interface{}, path string) (*YamlDoc, error)

SetYAMLPointer parses a YAML pointer path and sets the leaf to a value. Returns an error if the pointer could not be resolved due to missing fields.

func (*YamlDoc) String 

func (c *YamlDoc) String() string

String marshals an element to a YAML formatted string.

func (*YamlDoc) StringIndent 

func (c *YamlDoc) StringIndent(indent int) string

StringIndent marshals an element to a YAML string formatted with indents.

func (*YamlDoc) StripCommentKeys added in v0.1.25 

func (c *YamlDoc) StripCommentKeys() *YamlDoc

StripCommentKeys returns a deep copy of this document with all $comment$ keys removed from mapping nodes. Useful before JSON schema validation or other operations that don't understand comment keys.

func (*YamlDoc) YNode 

func (c *YamlDoc) YNode() *yaml.Node

YNode returns yaml's Node to prevent the decoding process.

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.