ytbx

README

ytbx

Golang package with convenience functions to load and process YAML files

Documentation

Index

• Variables
• func Delete(node *yamlv3.Node, pathString string) (*yamlv3.Node, error)
• func GetIdentifierFromNamedList(sequenceNode *yamlv3.Node) string
• func GetType(value interface{}) string
• func Grab(node *yamlv3.Node, pathString string) (*yamlv3.Node, error)
• func HumanReadableLocation(location string) string
• func HumanReadableLocationInformation(inputFile InputFile) string
• func IsPathInTree(tree *yamlv3.Node, pathString string) (bool, error)
• func IsStdin(location string) bool
• func ListStringKeys(mappingNode *yamlv3.Node) ([]string, error)
• func LoadDocuments(input []byte) ([]*yamlv3.Node, error)
• func LoadFiles(locationA string, locationB string) (InputFile, InputFile, error)
• func LoadJSONDocuments(input []byte) ([]*yamlv3.Node, error)
• func LoadTOMLDocuments(input []byte) ([]*yamlv3.Node, error)
• func LoadYAMLDocuments(input []byte) ([]*yamlv3.Node, error)
• func RestructureObject(node *yamlv3.Node)
• type DecoderProxy
  • func NewDecoderProxy(keepOrder bool, r io.Reader) *DecoderProxy
  • func (d *DecoderProxy) Decode(v interface{}) error
• type InputFile
  • func LoadDirectory(location string) (InputFile, error)
  • func LoadFile(location string) (InputFile, error)
• type InvalidPathString
  • func NewInvalidPathError(style PathStyle, pathString string, format string, a ...interface{}) *InvalidPathString
  • func (e *InvalidPathString) Error() string
• type KeyNotFoundInMapError
  • func (e *KeyNotFoundInMapError) Error() string
• type NoNamedEntryListError
  • func (e *NoNamedEntryListError) Error() string
• type Path
  • func ComparePaths(fromLocation string, toLocation string, compareByValue bool) ([]Path, error)
  • func ComparePathsByValue(fromLocation string, toLocation string, duplicatePaths []Path) ([]Path, error)
  • func ListPaths(location string) ([]Path, error)
  • func NewPathWithIndexedListElement(path Path, idx int) Path
  • func NewPathWithNamedElement(path Path, name interface{}) Path
  • func NewPathWithNamedListElement(path Path, identifier interface{}, name interface{}) Path
  • func NewPathWithPathElement(path Path, pathElement PathElement) Path
  • func ParseDotStylePathString(path string, node *yamlv3.Node) (Path, error)
  • func ParseDotStylePathStringUnsafe(path string) (Path, error)
  • func ParseGoPatchStylePathString(path string) (Path, error)
  • func ParsePathString(pathString string, node *yamlv3.Node) (Path, error)
  • func ParsePathStringUnsafe(pathString string) (Path, error)
  • func (path *Path) RootDescription() string
  • func (path Path) String() string
  • func (path *Path) ToDotStyle() string
  • func (path *Path) ToGoPatchStyle() string
• type PathElement
• type PathStyle

Variables

var DisableRemainingKeySort = false

DisableRemainingKeySort disables that during restructuring of map keys, all unknown keys are also sorted in such a way that it improves the readability.

var PreserveKeyOrderInJSON = false

PreserveKeyOrderInJSON specifies whether a special library is used to decode JSON input to preserve the order of keys in maps even though that is not part of the JSON specification.

Functions

func Delete

func Delete(node *yamlv3.Node, pathString string) (*yamlv3.Node, error)

Delete removes the section identified by the path from the YAML structure

func GetIdentifierFromNamedList

func GetIdentifierFromNamedList(sequenceNode *yamlv3.Node) string

GetIdentifierFromNamedList returns the identifier key used in the provided list, or an empty string if there is none. The identifier key is either 'name', 'key', or 'id'.

func GetType

func GetType(value interface{}) string

GetType returns the type of the input value with a YAML specific view

func Grab

func Grab(node *yamlv3.Node, pathString string) (*yamlv3.Node, error)

Grab gets the value from the provided YAML tree using a path to traverse through the tree structure

func HumanReadableLocation

func HumanReadableLocation(location string) string

HumanReadableLocation returns a human readable location with proper coloring

func HumanReadableLocationInformation

func HumanReadableLocationInformation(inputFile InputFile) string

HumanReadableLocationInformation create a nicely decorated information about the provided input location. It will output the absolute path of the file rather than the possibly relative location, or it will show the URL in the usual look-and-feel of URIs.

func IsPathInTree

func IsPathInTree(tree *yamlv3.Node, pathString string) (bool, error)

IsPathInTree returns whether the provided path is in the given YAML structure

func IsStdin

func IsStdin(location string) bool

IsStdin checks whether the provided input location refers to the dash character which usually serves as the replacement to point to STDIN rather than a file.

func ListStringKeys

func ListStringKeys(mappingNode *yamlv3.Node) ([]string, error)

ListStringKeys lists the keys in a MappingNode

func LoadDocuments

func LoadDocuments(input []byte) ([]*yamlv3.Node, error)

LoadDocuments reads the provided input data slice as a YAML, JSON, or TOML file with potential multiple documents. It only acts as a dispatcher and depending on the input will either use `LoadTOMLDocuments`, `LoadJSONDocuments`, or `LoadYAMLDocuments`.

func LoadFiles

func LoadFiles(locationA string, locationB string) (InputFile, InputFile, error)

LoadFiles concurrently loads two files from the provided locations

func LoadJSONDocuments

func LoadJSONDocuments(input []byte) ([]*yamlv3.Node, error)

LoadJSONDocuments reads the provided input data slice as a JSON file with potential multiple documents. Each document in the JSON stream results in an entry of the result slice.

func LoadTOMLDocuments

func LoadTOMLDocuments(input []byte) ([]*yamlv3.Node, error)

LoadTOMLDocuments reads the provided input data slice as a TOML file, which can only have one document. For the sake of having similar sounding functions and the same signatures, the function uses the plural in its name and returns a list of results even though it will only contain one entry. All map entries inside the result document are converted into Go-YAMLv3 Node types to make it compatible with the rest of the package.

func LoadYAMLDocuments

func LoadYAMLDocuments(input []byte) ([]*yamlv3.Node, error)

LoadYAMLDocuments reads the provided input data slice as a YAML file with potential multiple documents. Each document in the YAML stream results in an entry of the result slice.

func RestructureObject

func RestructureObject(node *yamlv3.Node)

RestructureObject takes an object and traverses down any sub elements such as list entries or map values to recursively call restructure itself. On YAML MappingNodes, it will use a look-up mechanism to decide if the order of key in that map need to be rearranged to meet some known established human order.

Types

type DecoderProxy

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

DecoderProxy can either be used with the standard JSON Decoder, or the specialised JSON library fork that supports preserving key order

func NewDecoderProxy

func NewDecoderProxy(keepOrder bool, r io.Reader) *DecoderProxy

NewDecoderProxy creates a new decoder proxy which either works in ordered mode or standard mode.

func (*DecoderProxy) Decode

func (d *DecoderProxy) Decode(v interface{}) error

Decode is a delegate function that calls JSON Decoder `Decode`

type InputFile

type InputFile struct {
	Location  string
	Note      string
	Documents []*yamlv3.Node
	Names     []string
}

InputFile represents the actual input file (local, or fetched remotely) that needs to be processed. It can contain multiple documents, where a document is a map or a list of things.

func LoadDirectory

func LoadDirectory(location string) (InputFile, error)

LoadDirectory reads the provided location as a directory and processes all files in the directory as documents

func LoadFile

func LoadFile(location string) (InputFile, error)

LoadFile processes the provided input location to load it as one of the supported document formats, or plain text if nothing else works.

type InvalidPathString

type InvalidPathString struct {
	Style       PathStyle
	PathString  string
	Explanation string
}

InvalidPathString represents the error that a path string is not a valid Dot-style or GoPatch path syntax and does not match a provided document.

func NewInvalidPathError

func NewInvalidPathError(style PathStyle, pathString string, format string, a ...interface{}) *InvalidPathString

NewInvalidPathError creates a new InvalidPathString

func (*InvalidPathString) Error

func (e *InvalidPathString) Error() string

type KeyNotFoundInMapError

type KeyNotFoundInMapError struct {
	MissingKey    string
	AvailableKeys []string
}

KeyNotFoundInMapError represents an error when a key in a map was expected, but could not be found.

func (*KeyNotFoundInMapError) Error

func (e *KeyNotFoundInMapError) Error() string

type NoNamedEntryListError

type NoNamedEntryListError struct {
}

NoNamedEntryListError represents the situation where a list was expected to be a named-entry list, but one or more entries were not maps.

func (*NoNamedEntryListError) Error

func (e *NoNamedEntryListError) Error() string

type Path

type Path struct {
	Root         *InputFile
	DocumentIdx  int
	PathElements []PathElement
}

Path points to a section in a data structure by using names to identify the location. Example:

---
sizing:
  api:
    count: 2

For example, `sizing.api.count` points to the key `sizing` of the root element and in there to the key `api` and so on and so forth.

func ComparePaths

func ComparePaths(fromLocation string, toLocation string, compareByValue bool) ([]Path, error)

ComparePaths returns all duplicate Path structures between two documents.

func ComparePathsByValue

func ComparePathsByValue(fromLocation string, toLocation string, duplicatePaths []Path) ([]Path, error)

ComparePathsByValue returns all Path structure that have the same path value

func ListPaths

func ListPaths(location string) ([]Path, error)

ListPaths returns all paths in the documents using the provided choice of path style.

func NewPathWithIndexedListElement

func NewPathWithIndexedListElement(path Path, idx int) Path

NewPathWithIndexedListElement returns a new path based on a given path adding a new of type list entry using the index.

func NewPathWithNamedElement

func NewPathWithNamedElement(path Path, name interface{}) Path

NewPathWithNamedElement returns a new path based on a given path adding a new of type entry in map using the name.

func NewPathWithNamedListElement

func NewPathWithNamedListElement(path Path, identifier interface{}, name interface{}) Path

NewPathWithNamedListElement returns a new path based on a given path adding a new of type entry in a named-entry list by using key and name.

func NewPathWithPathElement

func NewPathWithPathElement(path Path, pathElement PathElement) Path

NewPathWithPathElement returns a new path based on a given path adding a new path element.

func ParseDotStylePathString

func ParseDotStylePathString(path string, node *yamlv3.Node) (Path, error)

ParseDotStylePathString returns a path by parsing a string representation which is assumed to be a Dot-Style path.

func ParseDotStylePathStringUnsafe

func ParseDotStylePathStringUnsafe(path string) (Path, error)

ParseDotStylePathStringUnsafe returns a path by parsing a string representation, which is assumed to be a Dot-Style path, but *without* checking it against a YAML Node

func ParseGoPatchStylePathString

func ParseGoPatchStylePathString(path string) (Path, error)

ParseGoPatchStylePathString returns a path by parsing a string representation which is assumed to be a GoPatch style path.

func ParsePathString

func ParsePathString(pathString string, node *yamlv3.Node) (Path, error)

ParsePathString returns a path by parsing a string representation of a path, which can be one of the supported types.

func ParsePathStringUnsafe

func ParsePathStringUnsafe(pathString string) (Path, error)

ParsePathStringUnsafe returns a path by parsing a string representation of a path, which can either be GoPatch or DotStyle, but will not check the path elements against a given YAML document to verify the types (unsafe)

func (*Path) RootDescription

func (path *Path) RootDescription() string

RootDescription returns a description of the root level of this path, which could be the number of the respective document inside a YAML or if available the name of the document

func (Path) String

func (path Path) String() string

func (*Path) ToDotStyle

func (path *Path) ToDotStyle() string

ToDotStyle returns the path as a Dot-Style string.

func (*Path) ToGoPatchStyle

func (path *Path) ToGoPatchStyle() string

ToGoPatchStyle returns the path as a GoPatch style string.

type PathElement

type PathElement struct {
	Idx  int
	Key  string
	Name string
}

PathElement represents one part of a path, which can either address an entry in a map (by name), a named-entry list entry (key and name), or an entry in a list (by index).

type PathStyle

type PathStyle int

PathStyle is a custom type for supported path styles

const (
	DotStyle PathStyle = iota
	GoPatchStyle
)

Supported styles are the Dot-Style (used by Spruce for example) and GoPatch Style which is used by BOSH