Documentation
¶
Overview ¶
Package tree is the format-neutral document a Compose file is read into: mappings (ordered, unique keys), sequences and scalars, each carrying the file, line and column it came from. The YAML, JSON and HCL2 readers all produce it, so interpolation, merging and decoding are written once.
Every reader is bounded (Limits): a Compose file is untrusted input.
Index ¶
- Variables
- func Errorf(p Pos, format string, a ...any) error
- func Walk(n *Node, fn func(*Node) bool)
- type Entry
- type Error
- type HCLOptions
- type Kind
- type Limits
- type Node
- func NewMap(p Pos) *Node
- func NewSeq(p Pos, items ...*Node) *Node
- func NewString(s string, p Pos) *Node
- func Number(f float64, p Pos) *Node
- func ParseHCL(file string, data []byte, lim Limits, opt HCLOptions) (*Node, error)
- func ParseJSON(file string, data []byte, lim Limits) (*Node, error)
- func ParseYAML(file string, data []byte, lim Limits) (*Node, error)
- func (n *Node) AsBool() (bool, error)
- func (n *Node) AsInt() (int64, error)
- func (n *Node) AsString() (string, error)
- func (n *Node) Clone() *Node
- func (n *Node) Delete(key string)
- func (n *Node) Get(key string) *Node
- func (n *Node) Has(key string) bool
- func (n *Node) Index(key string) int
- func (n *Node) IsScalar() bool
- func (n *Node) Scalar() (string, error)
- func (n *Node) Set(key string, v *Node)
- type Pos
- type Tag
Constants ¶
This section is empty.
Variables ¶
var DefaultLimits = Limits{MaxBytes: 4 << 20, MaxDepth: 64, MaxNodes: 1 << 18, MaxString: 1 << 20}
DefaultLimits are the bounds used when a field is zero.
Functions ¶
Types ¶
type HCLOptions ¶
type HCLOptions struct {
// Variables are the values of var.NAME: the project's environment
// (the explicit environment, then .env). A `variable "NAME"` block's
// default applies when NAME is not among them.
Variables map[string]string
}
HCLOptions are what an HCL2 Compose file may refer to.
type Limits ¶
type Limits struct {
// MaxBytes is the largest file (default 4 MiB).
MaxBytes int
// MaxDepth is the deepest nesting of mappings and sequences (64).
MaxDepth int
// MaxNodes is the most nodes a file may expand to, aliases counted
// at every use (262144): what stops a YAML "billion laughs".
MaxNodes int
// MaxString is the longest scalar, also after interpolation (1 MiB).
MaxString int
}
Limits bound what a reader accepts.
func (Limits) WithDefaults ¶
WithDefaults fills the zero fields.
type Node ¶
type Node struct {
Kind Kind
Pos Pos
Tag Tag
// Text is a scalar's value: the string itself, a number's literal
// (base 10 after reading), "true" or "false".
Text string
Entries []Entry // Map
Items []*Node // Seq
}
Node is a value of a Compose document.
func Number ¶
Number makes a float node, or an integer one when the value is whole: HCL2 has one number type, so 1.0 and 1 must be the same value in all three formats.
func ParseHCL ¶
ParseHCL reads an HCL2 native-syntax Compose file into a tree.
Expressions are evaluated in a static context: the only variable is `var` (HCLOptions.Variables), there are no functions, and `for` expressions and directives are refused (they multiply sizes). A quoted string is a template: a literal "${" is written "$${". Values are final: Compose's own `${VAR}` interpolation does not apply to HCL files.
func ParseJSON ¶
ParseJSON reads a JSON document (RFC 8259) into a tree, keeping key order and positions, refusing duplicate keys and trailing content.
func ParseYAML ¶
ParseYAML reads one YAML 1.2 document into a tree.
Anchors and aliases are resolved here (Compose Specification, fragments: before interpolation), with every use of an alias counted against Limits.MaxNodes. Merge keys (`<<`, the YAML 1.1 merge type that Compose files rely on) take a mapping or a sequence of mappings; keys of the mapping itself win, then earlier sources over later ones. Keys must be unique (YAML 1.2 §3.2.1.3). The tags `!reset` and `!override` are kept for the merge; any other non-standard tag is refused.
func (*Node) AsBool ¶
AsBool reads a boolean field: a boolean, or a string spelling one (the value of an interpolated variable).
func (*Node) AsString ¶
AsString reads a string field: a string, or a number or boolean written where a string is expected (as YAML users do: `version: 3`).
Source Files