yaml

README

YAML

Fully backward-compatible YAML parser built from scratch in Golang Yaml 1.2 syntax is specified in the official specification release at https://yaml.org/spec

Backward Compatibility

This parser will start out to be fully compliant with YAML 1.2 specification (revision 2021) https://yaml.org/spec/1.2.2/
Compatibility with specifications 1.1.x will come in future releases.

Key Features

• Supports all YAML data types: scalars, sequences, and mappings.
• Handles block style and flow style YAML formats.
• Supports advanced YAML features like anchors, aliases, and tags.
• Full support for multi-line and folded strings.
• Proper error handling for invalid YAML syntax, including indentation errors and invalid characters.

Components

• Tokenizer: Breaks the input stream into YAML tokens such as scalars, mappings, sequences, comments, and indentation tokens.
• Parser: Constructs an Abstract Syntax Tree (AST) based on tokenized input.
• Emitter: Converts the parsed structure back into human-readable YAML if needed.

Use cases

Ideal for configuration management, data serialization, and parsing of structured data in YAML format.

Data structures used

• Trie
• Singly-LinkedList
• Stack
• Abstract Syntax tree

Documentation

Index

• type DocumentNode
  • func NewDocumentNode() *DocumentNode
  • func (n *DocumentNode) AddChild(child Node)
  • func (n *DocumentNode) Children() []Node
  • func (n *DocumentNode) Key() string
  • func (n *DocumentNode) SetValue(_ interface{})
  • func (n *DocumentNode) Type() NodeType
  • func (n *DocumentNode) Value() any
• type Node
• type NodeBuilder
• type NodeType
  • func (nt NodeType) IsNestable() bool
• type ScalarNode
  • func NewScalarNodeBuilder() *ScalarNode
  • func (n *ScalarNode) AddChild(_ Node)
  • func (n *ScalarNode) Children() any
  • func (n *ScalarNode) CurrentPosition() token.Location
  • func (n *ScalarNode) Key() string
  • func (n *ScalarNode) SetCurrentPosition(position token.Location)
  • func (n *ScalarNode) SetKey(key string)
  • func (n *ScalarNode) SetValue(v any)
  • func (n *ScalarNode) ToNode() Node
  • func (n *ScalarNode) Type() NodeType
  • func (n *ScalarNode) Value() any

Types

type DocumentNode

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

DocumentNode is usually the root of an AbstractSyntaxTree

func NewDocumentNode

func NewDocumentNode() *DocumentNode

func (*DocumentNode) AddChild

func (n *DocumentNode) AddChild(child Node)

func (*DocumentNode) Children

func (n *DocumentNode) Children() []Node

func (*DocumentNode) Key

func (n *DocumentNode) Key() string

func (*DocumentNode) SetValue

func (n *DocumentNode) SetValue(_ interface{})

func (*DocumentNode) Type

func (n *DocumentNode) Type() NodeType

func (*DocumentNode) Value

func (n *DocumentNode) Value() any

type Node

type Node interface {
	Key() string
	Type() NodeType
	Value() interface{}
	Children() any
}

type NodeBuilder

type NodeBuilder interface {
	AddChild(Node)
	SetValue(any)
	ToNode() Node
	SetKey(key string)
	CurrentPosition() token.Location
	SetCurrentPosition(position token.Location)
}

type NodeType

type NodeType int8

const (
	NodeTypeUnknown NodeType = iota // Node type is unknown and used as a placeholder for uninitialized or invalid nodes.

	// NodeTypeScalar represents a single value node, such as a string, integer, or boolean.
	// Example:
	//   key: "Hello, World"
	NodeTypeScalar

	// NodeTypeDocument is the root of a YAML document. It represents the whole document structure and may contain sequences or mappings.
	// Example:
	//   ---
	//   title: "YAML Example"
	//   ---
	NodeTypeDocument

	// NodeTypeMultilineString represents a multi-line string, often using the `|` symbol to preserve line breaks.
	// Example:
	//   description: |
	//     This is a multi-line
	//     string in YAML.
	NodeTypeMultilineString

	// NodeTypeFoldedString is a multi-line text node that uses the `>` symbol to fold lines. Line breaks within folded text are converted to spaces.
	// Example:
	//   note: >
	//     This text will be folded
	//     into a single line when parsed.
	NodeTypeFoldedString

	// NodeTypeAnchor represents an anchor node, allowing values to be reused or referenced elsewhere in the document.
	// Example:
	//   base: &baseAnchor "Base Value"
	NodeTypeAnchor

	// NodeTypeSequenceFlowStyle represents a sequence in flow style, denoted by square brackets `[]`. This style is non-nestable.
	// Example:
	//   items: [1, 2, 3]
	NodeTypeSequenceFlowStyle

	// NodeTypeSequenceBlockStyle represents a sequence in block style, using `-` to denote each item. This style can contain nested elements.
	// Example:
	//   items:
	//     - name: "Item 1"
	//     - name: "Item 2"
	NodeTypeSequenceBlockStyle

	// NodeTypeMappingFlowStyle represents a mapping in flow style, using curly braces `{}`. This style is non-nestable.
	// Example:
	//   info: { key1: "value1", key2: "value2" }
	NodeTypeMappingFlowStyle

	// NodeTypeMappingBlockStyle represents a mapping in block style, where each key-value pair is on a new line.
	// This style can contain nested mappings, sequences, or scalars.
	// Example:
	//   user:
	//     name: "Alice"
	//     age: 30
	NodeTypeMappingBlockStyle

	// NodeTypeAlias represents a reference to an anchor node, allowing the reuse of values defined by an anchor.
	// Example:
	//   base: &baseAnchor "Base Value"
	//   alias: *baseAnchor
	NodeTypeAlias
)

func (NodeType) IsNestable

func (nt NodeType) IsNestable() bool

IsNestable checks if NodeType can serve as a parent node to other child nodes. In the context of YAML, only certain node types can nest other nodes. Specifically, NodeTypeSequenceBlockStyle and NodeTypeMappingBlockStyle are nestable, while other types such as scalars, flow styles, and aliases are not.

type ScalarNode

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

func NewScalarNodeBuilder

func NewScalarNodeBuilder() *ScalarNode

func (*ScalarNode) AddChild

func (n *ScalarNode) AddChild(_ Node)

func (*ScalarNode) Children

func (n *ScalarNode) Children() any

func (*ScalarNode) CurrentPosition

func (n *ScalarNode) CurrentPosition() token.Location

func (*ScalarNode) Key

func (n *ScalarNode) Key() string

func (*ScalarNode) SetCurrentPosition

func (n *ScalarNode) SetCurrentPosition(position token.Location)

func (*ScalarNode) SetKey

func (n *ScalarNode) SetKey(key string)

func (*ScalarNode) SetValue

func (n *ScalarNode) SetValue(v any)

func (*ScalarNode) ToNode

func (n *ScalarNode) ToNode() Node

func (*ScalarNode) Type

func (n *ScalarNode) Type() NodeType

func (*ScalarNode) Value

func (n *ScalarNode) Value() any