template

package
v0.51.1 Latest Latest
Warning

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

 Go to latest Published: Dec 11, 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 

func (e CompiledTemplateMultiError) Error() string

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 EvaluationCtxDialects 

type EvaluationCtxDialects map[EvaluationCtxDialectName]EvaluationCtxDialect

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 (as NodeAnnotations) Args(name AnnotationName) starlark.Tuple

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 

func (l NoopCompiledTemplateLoader) Load(
	thread *starlark.Thread, module string) (starlark.StringDict, error)

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

Source Files

View all Source files

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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.