Documentation
¶
Overview ¶
Package htmlbind parses typed HTML template sources into an AST.
Index ¶
- Constants
- func Generate(filename string, source []byte, options GenerateOptions) ([]byte, error)
- type ActionRef
- type Annotation
- type Attribute
- type AttributePart
- type AwaitBinding
- type AwaitNode
- type BinaryExpr
- type Body
- type CallExpr
- type CommentNode
- type CompileError
- type ComponentNode
- type ConditionalExpr
- type Declaration
- type DoctypeNode
- type ElementNode
- type EnumDecl
- type EnumMember
- type Expr
- type ExpressionNode
- type ExternalDecl
- type Field
- type ForNode
- type GenerateOptions
- type HeadNode
- type IdentifierExpr
- type IfNode
- type ImportDecl
- type IndexExpr
- type LiteralExpr
- type MemberExpr
- type Module
- type Node
- type PackageDecl
- type Parameter
- type ParseError
- type Position
- type Signature
- type SignatureParam
- type SlotNode
- type TemplateDecl
- type TextNode
- type TypeDecl
- type TypeRef
- type UnaryExpr
Constants ¶
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.
const ReservedPageFunc = "Load"
ReservedPageFunc is the Go entry point name a route package gives its own page, which is therefore never a server action.
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
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 AwaitBinding ¶ added in v0.1.16
type AwaitBinding = syntax.AwaitBinding
type BinaryExpr ¶
type BinaryExpr = syntax.BinaryExpr
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 ¶
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 EnumMember ¶
type EnumMember = syntax.EnumMember
type ExpressionNode ¶
type ExpressionNode = syntax.ExpressionNode
type ExternalDecl ¶
type ExternalDecl = syntax.ExternalDecl
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.
type IdentifierExpr ¶
type IdentifierExpr = syntax.IdentifierExpr
type ImportDecl ¶
type ImportDecl = syntax.ImportDecl
type LiteralExpr ¶
type LiteralExpr = syntax.LiteralExpr
type MemberExpr ¶
type MemberExpr = syntax.MemberExpr
type PackageDecl ¶
type PackageDecl = syntax.PackageDecl
type ParseError ¶
type ParseError = syntax.ParseError
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 Signatures ¶ added in v0.2.0
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.
type TemplateDecl ¶
type TemplateDecl = syntax.TemplateDecl