htmlbind

package
v0.2.8 Latest Latest
Warning

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

Go to latest
Published: Jul 31, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package htmlbind parses typed HTML template sources into an AST.

Index

Constants

View Source
const DefaultActionAttr = "data-tb-action"

DefaultActionAttr is the attribute the lowering writes when GenerateOptions.ServerActionAttr is empty. A framework driving its own client library points it at that library's vocabulary instead.

View Source
const ReservedPageFunc = "Load"

ReservedPageFunc is the Go entry point name a route package gives its own page, which is therefore never a server action.

View Source
const ServerActionAttr = "server-action"

ServerActionAttr is the reserved attribute naming a Go handler instead of a URL. It never reaches the output; the compiler replaces it with the attribute that carries the handler's endpoint.

See decision:server-action-lowering. The value is a static handler name because the symbol has to resolve at generation, and only the caller can resolve it: the URL depends on the route the template serves, which the compiler cannot see. That is why lowering takes two passes, with ActionRefs reporting what a module references and GenerateOptions.ServerActions carrying the answers back.

Variables

This section is empty.

Functions

func Generate

func Generate(filename string, source []byte, options GenerateOptions) ([]byte, error)

Generate parses, validates, and compiles an HTML template module to Go.

Each component becomes an immutable render plan: an instruction list typed by its parameter struct, executed by the shared htmlbind coordinator. Generated code owns no response concerns, so it depends on neither net/http nor any content negotiation.

Types

type ActionRef added in v0.2.3

type ActionRef struct {
	// Component is the declaration the reference appears in.
	Component string
	// Handler is the Go function name the attribute named.
	Handler string
	// Element is the element carrying the attribute, such as form or button.
	Element string
	// Pos is the attribute position, for a diagnostic that can quote the source.
	Pos Position
}

ActionRef is one server-action reference found in a template.

func ActionRefs added in v0.2.3

func ActionRefs(filename string, source []byte) ([]ActionRef, error)

ActionRefs parses and analyzes a template module and returns every server-action reference it makes, in source order.

It is the first of the two passes lowering needs: a caller resolves these names against the Go package beside the template, derives an endpoint URL for each, and passes the result to Generate as GenerateOptions.ServerActions.

Like Signatures it runs the same analysis Generate does, so a module that fails to compile fails here with the same diagnostic rather than yielding a partial answer.

type Annotation added in v0.1.16

type Annotation = syntax.Annotation

type Attribute

type Attribute struct {
	Kind    string          `json:"kind"`
	Pos     Position        `json:"pos"`
	Name    string          `json:"name"`
	Boolean bool            `json:"boolean,omitempty"`
	Value   []AttributePart `json:"value,omitempty"`
}

type AttributePart

type AttributePart struct {
	Kind       string   `json:"kind"`
	Pos        Position `json:"pos"`
	Context    string   `json:"context,omitempty"`
	Text       string   `json:"text,omitempty"`
	Expression Expr     `json:"expression,omitempty"`
}

type AwaitBinding added in v0.1.16

type AwaitBinding = syntax.AwaitBinding

type AwaitNode added in v0.1.16

type AwaitNode = syntax.AwaitNode

type BinaryExpr

type BinaryExpr = syntax.BinaryExpr

type Body

type Body = []Node

Body is the body stored in TemplateDecl.Body.

type CallExpr

type CallExpr = syntax.CallExpr

type CommentNode

type CommentNode struct {
	Kind string   `json:"kind"`
	Pos  Position `json:"pos"`
	Text string   `json:"text"`
}

func (*CommentNode) NodeType

func (n *CommentNode) NodeType() string

type CompileError

type CompileError struct {
	Filename string
	Pos      Position
	Message  string
}

func (*CompileError) Error

func (e *CompileError) Error() string

type ComponentNode

type ComponentNode struct {
	Kind        string      `json:"kind"`
	Pos         Position    `json:"pos"`
	Name        string      `json:"name"`
	Arguments   []Attribute `json:"arguments,omitempty"`
	Children    []Node      `json:"children,omitempty"`
	SelfClosing bool        `json:"selfClosing,omitempty"`
}

func (*ComponentNode) NodeType

func (n *ComponentNode) NodeType() string

type ConditionalExpr

type ConditionalExpr = syntax.ConditionalExpr

type Declaration

type Declaration = syntax.Declaration

type DoctypeNode

type DoctypeNode struct {
	Kind string   `json:"kind"`
	Pos  Position `json:"pos"`
	Text string   `json:"text"`
}

func (*DoctypeNode) NodeType

func (n *DoctypeNode) NodeType() string

type ElementNode

type ElementNode struct {
	Kind        string      `json:"kind"`
	Pos         Position    `json:"pos"`
	Name        string      `json:"name"`
	Attributes  []Attribute `json:"attributes,omitempty"`
	Children    []Node      `json:"children,omitempty"`
	SelfClosing bool        `json:"selfClosing,omitempty"`
}

func (*ElementNode) NodeType

func (n *ElementNode) NodeType() string

type EnumDecl

type EnumDecl = syntax.EnumDecl

type EnumMember

type EnumMember = syntax.EnumMember

type Expr

type Expr = syntax.Expr

type ExpressionNode

type ExpressionNode = syntax.ExpressionNode

type ExternalDecl

type ExternalDecl = syntax.ExternalDecl

type Field

type Field = syntax.Field

type ForNode

type ForNode = syntax.ForNode

type GenerateOptions

type GenerateOptions struct {
	// Package overrides the template package/module declaration.
	Package string
	// ContextExternals names the external functions whose Go implementation
	// takes a leading context.Context. Those calls receive the boundary's
	// context; every other external is called as an ordinary function.
	//
	// The caller discovers this by reading the package's Go sources, so the
	// template declaration stays the same either way and the choice belongs to
	// whoever writes the implementation.
	ContextExternals map[string]bool
	// PreserveWhitespace turns off requirement:static-whitespace-normalization,
	// so static output keeps the authoring indentation and newlines byte for
	// byte. It exists for a project comparing generated markup against
	// pre-existing golden files.
	PreserveWhitespace bool
	// ServerActions maps each handler name a template reaches through
	// ServerActionAttr to the endpoint URL the lowering writes. The caller
	// resolves it, because the URL depends on the route the template serves and
	// the compiler cannot see that; [ActionRefs] reports what needs resolving.
	//
	// A reference with no entry here is a compile error, so a template naming a
	// handler nobody resolved never silently emits a dead element.
	ServerActions map[string]string
	// ServerActionResolver answers a name ServerActions does not hold. It is what
	// lets a framework address a handler from its own route table, for a template
	// that sits outside the tree route discovery walks.
	//
	// The map wins, so configuring a resolver cannot retarget an action a
	// discovered package already declares.
	ServerActionResolver func(name string) (url string, ok bool)
	// ServerActionAttr is the attribute the lowering writes. Empty uses
	// [DefaultActionAttr]. A framework driving an existing client library points
	// it at that library's vocabulary, such as hx-post.
	ServerActionAttr string
}

GenerateOptions controls the generated Go file.

type HeadNode added in v0.1.15

type HeadNode struct {
	Kind     string   `json:"kind"`
	Pos      Position `json:"pos"`
	Children []Node   `json:"children,omitempty"`
}

HeadNode is a head element declared outside the document shell. Its children are hoisted into the merged document head instead of being emitted in place.

func (*HeadNode) NodeType added in v0.1.15

func (n *HeadNode) NodeType() string

type IdentifierExpr

type IdentifierExpr = syntax.IdentifierExpr

type IfNode

type IfNode = syntax.IfNode

type ImportDecl

type ImportDecl = syntax.ImportDecl

type IndexExpr

type IndexExpr = syntax.IndexExpr

type LiteralExpr

type LiteralExpr = syntax.LiteralExpr

type MemberExpr

type MemberExpr = syntax.MemberExpr

type Module

type Module = syntax.Module

func Parse

func Parse(filename string, source []byte) (*Module, error)

Parse parses one template source using the shared declarations and the HTML component root declaration.

type Node

type Node = syntax.Node

type PackageDecl

type PackageDecl = syntax.PackageDecl

type Parameter

type Parameter = syntax.Parameter

type ParseError

type ParseError = syntax.ParseError

type Position

type Position = syntax.Position

type Signature added in v0.2.0

type Signature struct {
	// Name is the declaration name as written in the template.
	Name string
	// Exported reports the export modifier.
	Exported bool
	// Parameters are in declaration order.
	Parameters []SignatureParam
}

Signature is one declaration's contract stated in Go terms.

It exists so a caller that generates code around a template, such as a filesystem router, can read what a component takes without reimplementing the template type system. The Go types here are exactly the ones the generated parameter struct declares.

func Lookup added in v0.2.0

func Lookup(signatures []Signature, name string) (Signature, bool)

Lookup returns the signature with the given name.

func Signatures added in v0.2.0

func Signatures(filename string, source []byte) ([]Signature, error)

Signatures parses and analyzes a template module and returns the Go-typed signature of every component it declares, in declaration order.

It runs the same analysis Generate does, so a module that fails to compile fails here with the same diagnostic rather than yielding a partial answer.

type SignatureParam added in v0.2.0

type SignatureParam struct {
	// Name is the parameter name as written in the template.
	Name string
	// GoType is the Go type of the generated parameter struct field. An async
	// parameter is already wrapped, so it reads htmlbind.Pending[T].
	GoType string
	// TemplateType is the type as written in the template, kept for diagnostics
	// that should quote the source rather than its lowering.
	TemplateType string
	// Async marks a parameter the caller settles through htmlbind.Pending.
	Async bool
	// Slot marks an html parameter, which a wrapper fills rather than a caller
	// passing data.
	Slot bool
}

SignatureParam is one declared parameter of a Signature.

type SlotNode added in v0.1.15

type SlotNode struct {
	Kind     string   `json:"kind"`
	Pos      Position `json:"pos"`
	Name     string   `json:"name,omitempty"`
	Required bool     `json:"required,omitempty"`
	Default  []Node   `json:"default,omitempty"`
}

SlotNode marks where a bound html parameter is inserted. Name is empty for the reserved children parameter. Default holds the content rendered when the bound argument is absent.

func (*SlotNode) NodeType added in v0.1.15

func (n *SlotNode) NodeType() string

func (*SlotNode) Parameter added in v0.1.15

func (n *SlotNode) Parameter() string

Parameter reports the component parameter this slot binds to.

type TemplateDecl

type TemplateDecl = syntax.TemplateDecl

type TextNode

type TextNode struct {
	Kind string   `json:"kind"`
	Pos  Position `json:"pos"`
	Text string   `json:"text"`
}

func (*TextNode) NodeType

func (n *TextNode) NodeType() string

type TypeDecl

type TypeDecl = syntax.TypeDecl

type TypeRef

type TypeRef = syntax.TypeRef

type UnaryExpr

type UnaryExpr = syntax.UnaryExpr

Jump to

Keyboard shortcuts

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