vuego

package module
v0.0.6 Latest Latest
Warning

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

 Go to latest Published: Dec 6, 2025 License: MIT Imports: 24 Imported by: 0

README

vuego

Go Reference Coverage

Vuego is a Vue.js-inspired template engine for Go. Render HTML templates with familiar Vue syntax - no JavaScript runtime required.

The engine uses golang.org/x/net/html for HTML parsing and rendering.

Features

Vuego supports the following template features:

  • Variable interpolation - {{ variable }} with nested property access
  • Template functions - Pipe-based filter chaining {{ value | upper | trim }}
  • Custom functions - Define custom template functions (FuncMap)
  • Built-in filters - String manipulation, formatting, type conversion
  • Attribute binding - :attr="value" or v-bind:attr="value"
  • Conditional rendering - v-if for showing/hiding elements with function support
  • List rendering - v-for to iterate over arrays with optional index
  • Raw HTML - v-html for unescaped HTML content
  • Component composition - <vuego include> for reusable components
  • Required props - :required attribute for component validation
  • Template wrapping - <template> tag for component boundaries
  • Full documents - Support for complete HTML documents or fragments
  • Automatic escaping - Built-in XSS protection for interpolated values

Playground

Try VueGo in your browser! The interactive playground lets you experiment with templates and see results instantly.

You can run the playground locally, and if you pass a folder as the first parameter, you have a workspace.

# go run github.com/titpetric/vuego/cmd/vuego-playground
2025/11/14 20:07:31 VueGo Playground starting on http://localhost:3000

Documentation

The Template Syntax reference covers four main areas:

  • Values - Variable interpolation, expressions, and filters
  • Directives - Complete reference of all v- directives
  • Components - <vuego> and <template> tags
  • Advanced - Template functions, custom filters, and full documents

Additional resources:

License

MIT

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Component 

type Component interface {
	// Render renders the component template to the given writer.
	Render(ctx context.Context, w io.Writer, filename string, data any) error
}

Component is a renderable .vuego template component.

type ExprEvaluator 

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

ExprEvaluator wraps expr for evaluating boolean and interpolated expressions. It caches compiled programs to avoid recompilation.

func NewExprEvaluator 

func NewExprEvaluator() *ExprEvaluator

NewExprEvaluator creates a new ExprEvaluator with an empty cache.

func (*ExprEvaluator) ClearCache 

func (e *ExprEvaluator) ClearCache()

ClearCache clears the program cache (useful for testing or memory management).

func (*ExprEvaluator) Eval 

func (e *ExprEvaluator) Eval(expression string, env map[string]any) (any, error)

Eval evaluates an expression against the given environment (stack). It returns the result value and any error. The expression can contain:

  • Variable references: item, item.title, items[0]
  • Comparison: ==, !=, <, >, <=, >=
  • Boolean operations: &&, ||, !
  • Function calls: len(items), isActive(v)
  • Literals: 42, "text", true, false

type FuncMap 

type FuncMap map[string]any

FuncMap is a map of function names to functions, similar to text/template's FuncMap. Functions can have any number of parameters and must return 1 or 2 values. If 2 values are returned, the second must be an error.

type LessProcessor 

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

LessProcessor implements vuego.NodeProcessor to compile LESS to CSS in <style type="text/css+less"> tags.

func NewLessProcessor 

func NewLessProcessor(fsys ...fs.FS) *LessProcessor

NewLessProcessor creates a new LESS processor.

func (*LessProcessor) New 

func (lp *LessProcessor) New() NodeProcessor

New creates a new allocation of *LessProcessor.

func (*LessProcessor) PostProcess 

func (lp *LessProcessor) PostProcess(nodes []*html.Node) error

PostProcess walks the DOM tree and compiles LESS in <style type="text/css+less"> tags to CSS.

func (*LessProcessor) PreProcess 

func (lp *LessProcessor) PreProcess(nodes []*html.Node) error

PreProcess.

type LessProcessorError 

type LessProcessorError struct {
	Err    error
	Reason string
}

LessProcessorError wraps processing errors with context.

func (*LessProcessorError) Error 

func (e *LessProcessorError) Error() string

type LoadOption 

type LoadOption func(*Vue)

LoadOption is a functional option for configuring Load()

func WithFS added in v0.0.5 

func WithFS(templateFS fs.FS) LoadOption

WithFS returns a LoadOption that sets the filesystem for template loading.

func WithLessProcessor 

func WithLessProcessor() LoadOption

WithLessProcessor returns a LoadOption that registers a LESS processor

func WithProcessor 

func WithProcessor(processor NodeProcessor) LoadOption

WithProcessor returns a LoadOption that registers a custom node processor

type Loader 

type Loader struct {
	FS fs.FS
}

Loader loads and parses .vuego files from an fs.FS.

func NewLoader 

func NewLoader(fs fs.FS) *Loader

NewLoader creates a Loader backed by fs.

func (*Loader) Load 

func (l *Loader) Load(filename string) ([]*html.Node, error)

Load parses a full HTML document from the given filename.

func (*Loader) LoadFragment 

func (l *Loader) LoadFragment(filename string) ([]*html.Node, error)

LoadFragment parses a template fragment; if the file is a full document, it falls back to Load. Front-matter is extracted and discarded; use loadFragmentInternal to access it.

func (*Loader) Stat 

func (l *Loader) Stat(filename string) error

Stat checks that filename exists in the loader filesystem.

type NodeProcessor 

type NodeProcessor interface {
	// New ensures that we can have render-scoped allocations.
	New() NodeProcessor

	// PreProcess receives the nodes as they are decoded.
	PreProcess(nodes []*html.Node) error

	// PostProcess receives the rendered nodes and may modify them in place.
	// It should return an error if processing fails.
	PostProcess(nodes []*html.Node) error
}

NodeProcessor is an interface for post-processing []*html.Node after template evaluation. Implementations can inspect and modify HTML nodes to implement custom tags and attributes. NodeProcessor receives the complete rendered DOM and can transform it in place.

Processors are called after all Vue directives and interpolations have been evaluated. Multiple processors can be registered and are applied in order of registration.

See docs/nodeprocessor.md for examples and best practices.

type Renderer 

type Renderer interface {
	// Render renders HTML nodes to the given writer.
	Render(ctx context.Context, w io.Writer, nodes []*html.Node) error
}

Renderer renders parsed HTML nodes to output.

func NewRenderer 

func NewRenderer() Renderer

NewRenderer creates a new Renderer.

type Stack 

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

Stack provides stack-based variable lookup and convenient typed accessors.

func NewStack 

func NewStack(root map[string]any) *Stack

NewStack constructs a Stack with an optional initial root map (nil allowed). The originalData parameter is the original value passed to Render (for struct field fallback).

func NewStackWithData 

func NewStackWithData(root map[string]any, originalData any) *Stack

NewStackWithData constructs a Stack with both map data and original root data for struct field fallback.

func (*Stack) Copy added in v0.0.6 

func (s *Stack) Copy() *Stack

Copy returns a copy of the stack that can be discarded. The root data is retained as is, the envmap is a copy.

func (*Stack) EnvMap 

func (s *Stack) EnvMap() map[string]any

EnvMap converts the Stack to a map[string]any for expr evaluation. Includes all accessible values from stack and struct fields.

func (*Stack) ForEach 

func (s *Stack) ForEach(expr string, fn func(index int, value any) error) error

ForEach iterates over a collection at the given expr and calls fn(index,value). Supports slices/arrays and map[string]any (iteration order for maps is unspecified). If fn returns an error iteration is stopped and the error passed through.

func (*Stack) GetInt 

func (s *Stack) GetInt(expr string) (int, bool)

GetInt resolves and tries to return an int (best-effort).

func (*Stack) GetMap 

func (s *Stack) GetMap(expr string) (map[string]any, bool)

GetMap returns map[string]any or converts map[string]string to map[string]any. Avoids reflection for other map types.

func (*Stack) GetSlice 

func (s *Stack) GetSlice(expr string) ([]any, bool)

GetSlice returns a []any for supported slice kinds. Avoids reflection by only converting known types.

func (*Stack) GetString 

func (s *Stack) GetString(expr string) (string, bool)

GetString resolves and tries to return a string.

func (*Stack) Lookup 

func (s *Stack) Lookup(name string) (any, bool)

Lookup searches stack from top to bottom for a plain identifier (no dots). If not found in the stack maps, it checks the root data struct (if any). Returns (value, true) if found.

func (*Stack) Pop 

func (s *Stack) Pop()

Pop the top-most Stack. If only root remains it still pops to empty slice safely. Returns pooled maps to reduce GC pressure.

func (*Stack) Push 

func (s *Stack) Push(m map[string]any)

Push a new map as a top-most Stack. If m is nil, an empty map is obtained from the pool.

func (*Stack) Resolve 

func (s *Stack) Resolve(expr string) (any, bool)

Resolve resolves dotted/bracketed expression paths like: 

"user.name", "items[0].title", "mapKey.sub"

It returns (value, true) if resolution succeeded.

func (*Stack) Set 

func (s *Stack) Set(key string, val any)

Set sets a key in the top-most Stack.

type Template 

type Template interface {
	// Fill sets all variables from the map at once.
	Fill(vars any) Template

	// Assign sets a single variable.
	Assign(key string, value any) Template

	// GetVar retrieves a variable value.
	GetVar(key string) any

	// GetString retrieves a variable value as a string.
	// Returns an empty string if the value is not a string.
	GetString(key string) string

	// Funcs sets custom template functions, overwriting default keys. Returns the Template for chaining.
	Funcs(funcMap FuncMap) Template

	// Render processes the template file and writes output to w.
	// If an error occurs, w is unmodified (uses internal buffering).
	// The context can be used to cancel the rendering operation.
	Render(ctx context.Context, w io.Writer, filename string) error

	// RenderString processes a template string and writes output to w.
	// If an error occurs, w is unmodified (uses internal buffering).
	// The context can be used to cancel the rendering operation.
	RenderString(ctx context.Context, w io.Writer, templateStr string) error

	// RenderByte processes template bytes and writes output to w.
	// If an error occurs, w is unmodified (uses internal buffering).
	// The context can be used to cancel the rendering operation.
	RenderByte(ctx context.Context, w io.Writer, templateData []byte) error

	// RenderReader processes template data from a reader and writes output to w.
	// If an error occurs, w is unmodified (uses internal buffering).
	// The context can be used to cancel the rendering operation.
	RenderReader(ctx context.Context, w io.Writer, r io.Reader) error
}

Template represents a prepared vuego template. It allows variable assignment and rendering with internal buffering.

func Load 

func Load(templateFS fs.FS, opts ...LoadOption) Template

Load creates a new Template with access to the given filesystem and optional configurations. The returned Template can be used to render files, strings, or bytes with variable assignment.

func New added in v0.0.5 

func New(opts ...LoadOption) Template

New creates a new Template for rendering strings, bytes, or readers without a filesystem. Use this when templates are provided as strings/bytes rather than loaded from files. To render from files, use Load(fs) or New(WithFS(fs)) instead. The returned Template can be used for variable assignment and rendering.

type Vue 

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

Vue is the main template renderer for .vuego templates. After initialization, Vue is safe for concurrent use by multiple goroutines.

func NewVue 

func NewVue(templateFS fs.FS) *Vue

NewVue creates a new Vue backed by the given filesystem. The returned Vue is safe for concurrent use by multiple goroutines.

func (*Vue) DefaultFuncMap 

func (v *Vue) DefaultFuncMap() FuncMap

DefaultFuncMap returns a FuncMap with built-in utility functions

func (*Vue) Funcs 

func (v *Vue) Funcs(funcMap FuncMap) *Vue

Funcs sets custom template functions. Returns the Vue instance for chaining.

func (*Vue) RegisterNodeProcessor 

func (v *Vue) RegisterNodeProcessor(processor NodeProcessor) *Vue

RegisterNodeProcessor adds a custom node processor to the Vue instance. Processors are applied in order after template evaluation completes.

func (*Vue) Render 

func (v *Vue) Render(w io.Writer, filename string, data any) error

Render processes a full-page template file and writes the output to w. Front-matter data in the template is authoritative and overrides passed data. Render is safe to call concurrently from multiple goroutines.

func (*Vue) RenderFragment 

func (v *Vue) RenderFragment(w io.Writer, filename string, data any) error

RenderFragment processes a template fragment file and writes the output to w. Front-matter data in the template is authoritative and overrides passed data. RenderFragment is safe to call concurrently from multiple goroutines.

type VueContext 

type VueContext struct {

	// Template inclusion chain context
	BaseDir       string
	CurrentDir    string
	FromFilename  string
	TemplateStack []string

	// HTML rendering state
	TagStack []string

	Processors []NodeProcessor
	// contains filtered or unexported fields
}

VueContext carries template inclusion context and request-scoped state used during evaluation. Each render operation gets its own VueContext, making concurrent rendering safe.

func NewVueContext 

func NewVueContext(fromFilename string, options *VueContextOptions) VueContext

NewVueContext returns a VueContext initialized for the given template filename with initial data.

func (VueContext) CurrentTag 

func (ctx VueContext) CurrentTag() string

CurrentTag returns the current parent tag, or empty string if no tag is on the stack.

func (VueContext) FormatTemplateChain 

func (ctx VueContext) FormatTemplateChain() string

FormatTemplateChain returns the template inclusion chain formatted for error messages.

func (*VueContext) PopTag 

func (ctx *VueContext) PopTag()

PopTag removes the current tag from the tag stack.

func (*VueContext) PushTag 

func (ctx *VueContext) PushTag(tag string)

PushTag adds a tag to the tag stack.

func (VueContext) WithTemplate 

func (ctx VueContext) WithTemplate(filename string) VueContext

WithTemplate returns a copy of the context extended with filename in the inclusion chain.

type VueContextOptions 

type VueContextOptions struct {
	Stack      *Stack
	Processors []NodeProcessor
}

VueContextOptions holds configurable options for a new VueContext.

Source Files

View all Source files

Directories

Path Synopsis
cmd
vuego command
vuego-playground command
internal
helpers
Package helpers provides HTML node manipulation utilities for vuego.
 Package helpers provides HTML node manipulation utilities for vuego.
reflect
Package reflect provides utilities for traversing struct fields and values during template evaluation, supporting both field names and JSON tags.
 Package reflect provides utilities for traversing struct fields and values during template evaluation, supporting both field names and JSON tags.
ulid

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.