Documentation
¶
Overview ¶
Package yaml provides YAML parsing, caching, and utility functions for Atmos.
This package contains YAML-specific functionality including:
- Parsing and unmarshaling YAML with custom tag processing
- Content-aware caching for parsed YAML documents
- Position tracking for provenance
- Output formatting and highlighting
The custom tag processing uses the function registry from pkg/function to handle tags like !env, !exec, !terraform.output, etc.
Example usage:
data, err := yaml.UnmarshalYAML[map[string]any](content)
if err != nil {
return err
}
Index ¶
- Constants
- Variables
- func ConvertToYAMLPreservingDelimiters(data any, delimiters []string, opts ...u.YAMLOptions) (string, error)
- func Delete(content []byte, path string) ([]byte, error)
- func DeleteFile(filePath, path string) (bool, error)
- func DelimiterConflictsWithYAMLQuoting(delimiters []string) bool
- func DisplayPath(file string) string
- func DotPathToYqPath(dotPath string) (string, error)
- func EnsureDoubleQuotedForDelimiterSafety(node *goyaml.Node)
- func Eval(content []byte, expr string) ([]byte, error)
- func EvalFile(filePath, expr string) error
- func Format(content []byte) ([]byte, error)
- func FormatFile(filePath string) error
- func Get(content []byte, path string) (string, error)
- func GetFile(filePath, path string) (string, error)
- func GetTyped[T any](content []byte, path string) (T, error)
- func HasPosition(positions PositionMap, path string) bool
- func Query(content []byte, expr string) (string, error)
- func QueryFile(filePath, expr string) (string, error)
- func QuotePathSegment(key string) string
- func Set(content []byte, path, value string) ([]byte, error)
- func SetFile(filePath, path, value string) error
- func SetFileRaw(filePath, path, rhs string) error
- func SetFileWithType(filePath, path, value, valueType string) (bool, error)
- func SetRaw(content []byte, path, rhs string) ([]byte, error)
- func SetWithType(content []byte, path, value, valueType string) ([]byte, error)
- type LongString
- type Options
- type PathEntry
- type Position
- type PositionMap
Constants ¶
const ( TypeString = "string" TypeInt = "int" TypeBool = "bool" TypeFloat = "float" TypeNull = "null" // TypeYAML treats the value as a raw YAML/yq literal (e.g. `[1,2,3]`, // `{a: 1}`, or an unquoted scalar), inserted verbatim. TypeYAML = "yaml" )
Value type names accepted by SetWithType / SetFileWithType. These let CLI callers coerce a string argument into a typed YAML scalar (or a raw YAML literal) instead of always writing a quoted string.
const DefaultIndent = 2
DefaultIndent is the default indentation for YAML output.
Variables ¶
var ( // ErrNilAtmosConfig is returned when atmosConfig is nil. ErrNilAtmosConfig = errors.New("atmosConfig cannot be nil") // ErrIncludeInvalidArguments is returned when !include has invalid arguments. ErrIncludeInvalidArguments = errors.New("invalid number of arguments in the !include function") // ErrIncludeFileNotFound is returned when !include references a non-existent file. ErrIncludeFileNotFound = errors.New("the !include function references a file that does not exist") // ErrIncludeAbsPath is returned when converting to absolute path fails. ErrIncludeAbsPath = errors.New("failed to convert the file path to an absolute path in the !include function") // ErrIncludeProcessFailed is returned when processing stack manifest fails. ErrIncludeProcessFailed = errors.New("failed to process the stack manifest with the !include function") // ErrInvalidYAMLFunction is returned when a YAML function has invalid syntax. ErrInvalidYAMLFunction = errors.New("invalid Atmos YAML function") // ErrInvalidYAMLExpression is returned when a dot-path or yq expression cannot be parsed or evaluated. ErrInvalidYAMLExpression = errors.New("invalid YAML path or expression") // ErrYAMLPathNotFound is returned when a requested path does not exist in the document. ErrYAMLPathNotFound = errors.New("YAML path not found") // ErrYAMLUpdateFailed is returned when an edit operation fails to produce a valid document. ErrYAMLUpdateFailed = errors.New("failed to update YAML") // ErrYAMLAnchorAltered is returned when an edit would alter or expand a YAML anchor or alias, // which the strict editing contract forbids. ErrYAMLAnchorAltered = errors.New("edit would alter or expand a YAML anchor or alias") // ErrYAMLDuplicateAnchor is returned when a document defines the same anchor name more than // once. Aliases before and after the redefinition resolve to different values, so the anchor // guard cannot safely verify an edit; the duplicates must be renamed first. ErrYAMLDuplicateAnchor = errors.New("duplicate YAML anchor definition") // ErrYAMLMultiDocUnsupported is returned when the editor is given a stream containing more // than one YAML document. Edits would silently apply to every document, so multi-document // files are rejected explicitly. ErrYAMLMultiDocUnsupported = errors.New("multi-document YAML streams are not supported by the YAML editor") // ErrParseYAML is returned when YAML content cannot be parsed. ErrParseYAML = errors.New("failed to parse YAML") // ErrReadFile is returned when a file cannot be read. ErrReadFile = errors.New("failed to read file") // ErrWriteFile is returned when a file cannot be written. ErrWriteFile = errors.New("failed to write file") )
Functions ¶
func ConvertToYAMLPreservingDelimiters ¶ added in v1.208.0
func ConvertToYAMLPreservingDelimiters(data any, delimiters []string, opts ...u.YAMLOptions) (string, error)
ConvertToYAMLPreservingDelimiters converts data to YAML while ensuring that custom template delimiter characters are preserved literally in the output. When custom delimiters contain single-quote characters, the default yaml.v3 encoder may use single-quoted style for certain values (like those starting with '!'), which escapes internal single quotes by doubling them. This breaks template processing because the delimiter pattern is altered. This function forces double-quoted YAML style for affected scalar values to preserve delimiters.
func Delete ¶ added in v1.223.0
Delete removes the value at a dot-notation (or raw yq) path via yq's `del`. Deleting from an empty document is a no-op, matching yq's del semantics for a missing path.
func DeleteFile ¶ added in v1.223.0
DeleteFile removes the value at path in a YAML file. It returns whether a value was present and removed, letting callers distinguish an actual deletion from a no-op when the path was already absent.
func DelimiterConflictsWithYAMLQuoting ¶ added in v1.208.0
DelimiterConflictsWithYAMLQuoting checks if any custom delimiter contains a single-quote character that would conflict with YAML's single-quoted string escaping.
func DisplayPath ¶ added in v1.223.0
DisplayPath returns file relative to the current working directory for user-facing display, falling back to the absolute path if the relative form can't be computed (e.g. a different volume on Windows). Callers still read/write the original path passed in; this only affects what's echoed back to the user.
func DotPathToYqPath ¶ added in v1.223.0
DotPathToYqPath converts a user-facing dot-notation path into a yq path expression. Dot-notation is the default addressing syntax for the Atmos config/stack/vendor editors.
Examples:
vars.region -> .vars.region sources[0].version -> .sources[0].version components.terraform.vpc.vars.cidr -> .components.terraform.vpc.vars.cidr metadata."weird.key" -> .metadata.["weird.key"]
Keys that are not simple identifiers are emitted using yq's quoted `.["..."]` form so embedded dots and symbols are preserved literally.
func EnsureDoubleQuotedForDelimiterSafety ¶ added in v1.208.0
EnsureDoubleQuotedForDelimiterSafety recursively walks a yaml.Node tree and forces double-quoted style for scalar nodes whose values contain single-quote characters. This prevents YAML's single-quote escaping (two consecutive single quotes) from interfering with template delimiters that contain single quotes.
func Eval ¶ added in v1.223.0
Eval evaluates an arbitrary yq expression against raw YAML bytes and returns the modified document. It is the escape hatch for power users who want full yq syntax; the strict anchor guard still applies so a raw expression cannot silently rewrite shared anchors.
func EvalFile ¶ added in v1.223.0
EvalFile evaluates a yq expression against a file and writes the result back atomically, applying the strict anchor guard.
func Format ¶ added in v1.223.0
Format normalizes YAML formatting (indentation, spacing) by round-tripping the document through the editor's encoder with an identity expression, while preserving comments and anchors. This powers a `format`/`fmt` capability.
func FormatFile ¶ added in v1.223.0
FormatFile normalizes a YAML file's formatting in place.
func Get ¶ added in v1.223.0
Get reads the value at a dot-notation (or raw yq) path and returns it as a trimmed string. Missing or null paths return ErrYAMLPathNotFound.
func HasPosition ¶
func HasPosition(positions PositionMap, path string) bool
HasPosition checks if a position exists for a specific JSONPath.
func Query ¶ added in v1.223.0
Query evaluates a read-only yq expression (e.g. a select() filter) against raw YAML bytes and returns the trimmed result. Unlike Get, it does not treat the input as a dot-path, so callers can use full yq syntax. A "null" result is reported as ErrYAMLPathNotFound.
func QuotePathSegment ¶ added in v1.223.0
QuotePathSegment renders a literal map key as a dot-path segment, quoting it as "key" when it is not a simple identifier so embedded dots and brackets are parsed literally (e.g. a component named "vpc.prod" or "foo[0]") instead of as nested path syntax. Simple identifiers are returned unchanged.
func Set ¶ added in v1.223.0
Set assigns a string value at a dot-notation (or raw yq) path and returns the modified document, preserving comments/anchors/formatting. The value is written as a YAML string scalar. Use SetRaw for non-string (typed) values.
func SetFile ¶ added in v1.223.0
SetFile sets a string value at path in a YAML file, writing the result back atomically while preserving the original file mode.
func SetFileRaw ¶ added in v1.223.0
SetFileRaw sets a raw (typed) value at path in a YAML file.
func SetFileWithType ¶ added in v1.223.0
SetFileWithType assigns a typed value at path in a YAML file (atomic write). It returns whether the path was newly created (true) as opposed to already existing and being updated (false), letting callers distinguish the two for user-facing messaging.
Types ¶
type LongString ¶
type LongString string
LongString is a string type that encodes as a YAML folded scalar (>). This is used to wrap long strings across multiple lines for better readability.
func (LongString) MarshalYAML ¶
func (s LongString) MarshalYAML() (interface{}, error)
MarshalYAML implements yaml.Marshaler to encode as a folded scalar.
type PathEntry ¶ added in v1.223.0
PathEntry describes an addressable YAML value discovered while flattening a document into Atmos dot-notation paths.
func ListPathEntries ¶ added in v1.223.0
ListPathEntries parses a YAML document and returns all addressable child values as sorted Atmos dot-notation paths. Mapping keys are quoted with the same rules used by the config/stack/vendor editors.
type Position ¶
Position represents a line and column position in a YAML file.
func GetPosition ¶
func GetPosition(positions PositionMap, path string) Position
GetPosition gets the position for a specific JSONPath from the position map. Returns Position{0, 0} if not found.
type PositionMap ¶
PositionMap maps JSONPath-style paths to their positions in a YAML file.
func ExtractPositions ¶
func ExtractPositions(node *goyaml.Node, enabled bool) PositionMap
ExtractPositions extracts line/column positions from a YAML node tree. Returns a map of JSONPath -> Position for all values in the YAML. If enabled is false, returns an empty map immediately (zero overhead).
Source Files
Directories