template

package
v0.48.0 Latest Latest
Warning

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

Go to latest
Published: Feb 6, 2024 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package template provides the core templating engine for ytt.

At its heart, a template is text (possibly of a specific format like YAML) that is parsed into a set of template.EvaluationNode's which is then compiled into a Starlark program whose objective is to build an output structure that reflects the evaluated expressions that were annotated in the original text.

Index

Constants

This section is empty.

Variables

View Source
var (
	NodeTagRoot = NodeTag{-100}
)

Functions

func NewCompiledTemplateMultiError

func NewCompiledTemplateMultiError(err error, loader CompiledTemplateLoader) error

Types

type Ancestors

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

func NewAncestors

func NewAncestors(nodeNumToParentNum map[NodeTag]NodeTag) Ancestors

func (Ancestors) FindCommonParentTag

func (e Ancestors) FindCommonParentTag(currTag, newTag NodeTag) NodeTag

func (Ancestors) FindParentTag

func (e Ancestors) FindParentTag(tag NodeTag) NodeTag

type Annotation added in v0.48.0

type Annotation struct {
	Name     AnnotationName // eg template/code
	Content  string         // eg if True:
	Position *filepos.Position
}

func NewAnnotationFromComment added in v0.48.0

func NewAnnotationFromComment(data string, position *filepos.Position, opts MetaOpts) (Annotation, error)

NewAnnotationFromComment constructs an Annotation from a string and position from a Comment.

if opts.IgnoreUnknown is true and the annotation is unknown, it is returned as a comment. if opts.IgnoreUnknown is false and the annotation is unknown, returns an error.

type AnnotationName added in v0.48.0

type AnnotationName string
const (
	// AnnotationComment contains user-facing documentation and should be ignored.
	AnnotationComment AnnotationName = "comment"
	// AnnotationCode contains Starlark code that should be inserted, verbatim, into the compiled template.
	AnnotationCode AnnotationName = "template/code"
	// AnnotationValue contains a Starlark expression, the result of which should be set as the value of the annotated node.
	AnnotationValue AnnotationName = "template/value"
)

type AnnotationNs added in v0.48.0

type AnnotationNs string

type CompiledTemplate

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

func NewCompiledTemplate

func NewCompiledTemplate(name string, code []Line,
	instructions *InstructionSet, nodes *Nodes,
	evalDialects EvaluationCtxDialects) *CompiledTemplate

NewCompiledTemplate creates a CompiledTemplate containing the generated code, InstructionSet, and Nodes needed to template the resulting document.

func (*CompiledTemplate) Code

func (e *CompiledTemplate) Code() []Line

func (*CompiledTemplate) CodeAsString

func (e *CompiledTemplate) CodeAsString() string

func (*CompiledTemplate) CodeAtLine

func (e *CompiledTemplate) CodeAtLine(pos *filepos.Position) *Line

func (*CompiledTemplate) DebugCodeAsString

func (e *CompiledTemplate) DebugCodeAsString() string

func (*CompiledTemplate) Eval

func (e *CompiledTemplate) Eval(thread *starlark.Thread, loader CompiledTemplateLoader) (
	starlark.StringDict, interface{}, error)

Eval templates a document by executing the compiled code and instructions from a CompiledTemplate. `instructionBindings` maps the compiled code and instructions to functions defined on a CompiledTemplate.

func (*CompiledTemplate) TplReplaceNode

func (e *CompiledTemplate) TplReplaceNode(
	thread *starlark.Thread, f *starlark.Builtin,
	args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

type CompiledTemplateError

type CompiledTemplateError struct {
	Positions []CompiledTemplateErrorPosition
	Msg       string
}

type CompiledTemplateErrorPosition

type CompiledTemplateErrorPosition struct {
	Filename     string
	ContextName  string
	TemplateLine *Line

	BeforeTemplateLine *Line
	AfterTemplateLine  *Line
}

type CompiledTemplateLoader

type CompiledTemplateLoader interface {
	FindCompiledTemplate(string) *CompiledTemplate
	Load(*starlark.Thread, string) (starlark.StringDict, error)
}

type CompiledTemplateMultiError

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

func (CompiledTemplateMultiError) Error

type EvaluationCtx

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

func (*EvaluationCtx) RootNode

func (e *EvaluationCtx) RootNode() interface{}

func (*EvaluationCtx) RootNodeAsStarlarkValue

func (e *EvaluationCtx) RootNodeAsStarlarkValue() starlark.Value

func (*EvaluationCtx) TplCollectNodeAnnotation

func (e *EvaluationCtx) TplCollectNodeAnnotation(
	thread *starlark.Thread, f *starlark.Builtin,
	args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

args(args..., kwargs...)

func (*EvaluationCtx) TplReplace

func (e *EvaluationCtx) TplReplace(thread *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

func (*EvaluationCtx) TplSetMapItemKey added in v0.17.0

func (e *EvaluationCtx) TplSetMapItemKey(
	thread *starlark.Thread, _ *starlark.Builtin,
	args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

args(nodeTag, value Value)

func (*EvaluationCtx) TplSetNode

func (e *EvaluationCtx) TplSetNode(thread *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

args(nodeTag, value Value)

func (*EvaluationCtx) TplStartNode

func (e *EvaluationCtx) TplStartNode(
	thread *starlark.Thread, _ *starlark.Builtin,
	args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

args(nodeTag)

func (*EvaluationCtx) TplStartNodeAnnotation

func (e *EvaluationCtx) TplStartNodeAnnotation(
	thread *starlark.Thread, f *starlark.Builtin,
	args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error)

args(nodeTag, name, values)

type EvaluationCtxDialect

type EvaluationCtxDialect interface {
	PrepareNode(parentNode EvaluationNode, val EvaluationNode) error
	SetMapItemKey(node EvaluationNode, val interface{}) error
	Replace(parentNodes []EvaluationNode, val interface{}) error
	ShouldWrapRootValue(val interface{}) bool
	WrapRootValue(val interface{}) interface{}
}

type EvaluationCtxDialectName

type EvaluationCtxDialectName string

type EvaluationNode

type EvaluationNode interface {
	GetValues() []interface{}
	SetValue(interface{}) error
	AddValue(interface{}) error
	ResetValue()
	GetAnnotations() interface{}
	SetAnnotations(interface{})
	DeepCopyAsInterface() interface{} // expects that result implements EvaluationNode
}

type Instruction

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

func (Instruction) AsString

func (i Instruction) AsString() string

func (Instruction) Op

func (i Instruction) Op() InstructionOp

func (Instruction) WithDebug

func (i Instruction) WithDebug(info string) Instruction

type InstructionOp

type InstructionOp struct {
	Name string
}

func (InstructionOp) WithArgs

func (op InstructionOp) WithArgs(args ...string) Instruction

type InstructionSet

type InstructionSet struct {
	SetCtxType            InstructionOp
	StartCtx              InstructionOp
	EndCtx                InstructionOp
	StartNodeAnnotation   InstructionOp
	CollectNodeAnnotation InstructionOp
	StartNode             InstructionOp
	SetNode               InstructionOp
	SetMapItemKey         InstructionOp
	ReplaceNode           InstructionOp
}

func NewInstructionSet

func NewInstructionSet() *InstructionSet

func (*InstructionSet) NewCode

func (is *InstructionSet) NewCode(code string) Instruction

func (*InstructionSet) NewEndCtx

func (is *InstructionSet) NewEndCtx() Instruction

func (*InstructionSet) NewEndCtxNone

func (is *InstructionSet) NewEndCtxNone() Instruction

func (*InstructionSet) NewSetCtxType

func (is *InstructionSet) NewSetCtxType(dialect EvaluationCtxDialectName) Instruction

func (*InstructionSet) NewSetMapItemKey added in v0.17.0

func (is *InstructionSet) NewSetMapItemKey(nodeTag NodeTag, code string) Instruction

func (*InstructionSet) NewSetNode

func (is *InstructionSet) NewSetNode(nodeTag NodeTag) Instruction

func (*InstructionSet) NewSetNodeValue

func (is *InstructionSet) NewSetNodeValue(nodeTag NodeTag, code string) Instruction

func (*InstructionSet) NewStartCtx

func (is *InstructionSet) NewStartCtx(dialect EvaluationCtxDialectName) Instruction

func (*InstructionSet) NewStartNode

func (is *InstructionSet) NewStartNode(nodeTag NodeTag) Instruction

func (*InstructionSet) NewStartNodeAnnotation

func (is *InstructionSet) NewStartNodeAnnotation(nodeTag NodeTag, ann Annotation) Instruction

type Line added in v0.48.0

type Line struct {
	Instruction Instruction
	SourceLine  *SourceLine
}

func NewCodeFromBytes

func NewCodeFromBytes(bs []byte, instructions *InstructionSet) []Line

func NewCodeFromBytesAtPosition

func NewCodeFromBytesAtPosition(bs []byte, pos *filepos.Position, instructions *InstructionSet) []Line

type MetaOpts added in v0.48.0

type MetaOpts struct {
	IgnoreUnknown bool
}

type NodeAnnotation

type NodeAnnotation struct {
	Args     starlark.Tuple
	Kwargs   []starlark.Tuple
	Position *filepos.Position
}

type NodeAnnotations

type NodeAnnotations map[AnnotationName]NodeAnnotation

func NewAnnotations

func NewAnnotations(node EvaluationNode) NodeAnnotations

func (NodeAnnotations) Args

func (NodeAnnotations) DeepCopy

func (as NodeAnnotations) DeepCopy() NodeAnnotations

func (NodeAnnotations) DeepCopyAsInterface

func (as NodeAnnotations) DeepCopyAsInterface() interface{}

func (NodeAnnotations) DeleteNs

func (as NodeAnnotations) DeleteNs(ns AnnotationNs)

func (NodeAnnotations) Has

func (as NodeAnnotations) Has(name AnnotationName) bool

func (NodeAnnotations) Kwargs

func (as NodeAnnotations) Kwargs(name AnnotationName) []starlark.Tuple

type NodeTag

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

func NewNodeTag

func NewNodeTag(id int) NodeTag

func NewNodeTagFromStarlarkValue

func NewNodeTagFromStarlarkValue(val starlark.Value) (NodeTag, error)

func (NodeTag) AsString

func (t NodeTag) AsString() string

func (NodeTag) Equals

func (t NodeTag) Equals(other NodeTag) bool

func (NodeTag) String

func (t NodeTag) String() string

type Nodes

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

Nodes contain source information that is used when building and compiling a template.

Nodes track a source's structure by:

  • assigning a unique integer id, NodeTag, for each 'Node'.
  • storing breadcrumbs to find a Node's Parent.
  • keeping track each Node's non-template comments via annotations.

func NewNodes

func NewNodes() *Nodes

NewNodes initializes Nodes with empty maps to store info about the source template.

func (*Nodes) AddAnnotation added in v0.48.0

func (n *Nodes) AddAnnotation(tag NodeTag, ann Annotation)

AddAnnotation creates an entry in the annotations map of Nodes. The entry is NodeAnnotation with only the annotation's position, indexed by NodeTag and AnnotationName.

func (*Nodes) AddNode

func (n *Nodes) AddNode(node EvaluationNode, parentTag NodeTag) NodeTag

AddNode creates a new unique NodeTag to keep track of the EvaluationNode and its parent.

func (*Nodes) AddRootNode

func (n *Nodes) AddRootNode(node EvaluationNode) NodeTag

AddRootNode creates a new unique NodeTag to keep track of an EvaluationNode that has no parent.

func (*Nodes) Ancestors

func (n *Nodes) Ancestors() Ancestors

func (*Nodes) FindAnnotation added in v0.48.0

func (n *Nodes) FindAnnotation(tag NodeTag, annName AnnotationName) (NodeAnnotation, bool)

FindAnnotation uses a NodeTag, and an AnnotationName to retrieve a NodeAnnotation from the annotations map in Nodes.

func (*Nodes) FindNode

func (n *Nodes) FindNode(tag NodeTag) (EvaluationNode, bool)

FindNode uses a NodeTag to retrieve an EvaluationNode from the annotations map in Nodes.

type NoopCompiledTemplateLoader

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

func NewNoopCompiledTemplateLoader added in v0.48.0

func NewNoopCompiledTemplateLoader(tpl *CompiledTemplate) NoopCompiledTemplateLoader

func (NoopCompiledTemplateLoader) FindCompiledTemplate

func (l NoopCompiledTemplateLoader) FindCompiledTemplate(_ string) *CompiledTemplate

FindCompiledTemplate returns the CompiledTemplate this CompiledTemplateLoader was constructed with.

func (NoopCompiledTemplateLoader) Load

type ProgramAST

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

func NewProgramAST

func NewProgramAST(f *syntax.File, instructions *InstructionSet) *ProgramAST

func (*ProgramAST) InsertTplCtxs

func (r *ProgramAST) InsertTplCtxs()

type SourceLine

type SourceLine struct {
	Position  *filepos.Position
	Content   string
	Selection *SourceLine
}

func NewSourceLine added in v0.17.0

func NewSourceLine(pos *filepos.Position, content string) *SourceLine

Directories

Path Synopsis
Package core provides facilities for low-level integration with Starlark.
Package core provides facilities for low-level integration with Starlark.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL