Documentation
¶
Overview ¶
Package engine renders a template's parts in one language with Go templates: text/template for text parts, html/template for html parts (contextual escaping), a closed function set with language-aware helpers, strict about missing data, and bounded so a template cannot exhaust the process. Shared pieces are other templates (named "_x") whose part of the same name a part includes with {{template "_x" .}}.
Index ¶
Constants ¶
const ( KindText = "text" KindHTML = "html" )
Kinds of a part.
const ( MaxPartBytes = 256 << 10 MaxParts = 16 MaxDataBytes = 1 << 20 MaxOutputBytes = 1 << 20 // RenderTimeout bounds one render of every part. RenderTimeout = 2 * time.Second )
Limits of what the engine accepts.
const ( MaxRangeDepth = 2 MaxDataItems = 10000 )
What a template may do. A Go template cannot be interrupted, so the engine refuses up front what could loop without bound:
- {{range}} iterates only over data: a field (.items, $.a.b, $e.x), a variable holding data, never a number (Go 1.22 ranges over ints) nor a function's result; JSON numbers decode as float64, which range refuses, so data cannot smuggle an int in;
- ranges nest at most MaxRangeDepth deep, counted through included shared pieces, and data holds at most MaxDataItems elements, so the iterations of one render stay under MaxDataItems^MaxRangeDepth;
- parts and shared pieces define no templates of their own and shared pieces include each other without cycles, so nothing recurses.
Output (MaxOutputBytes), time (RenderTimeout) and concurrent renders (slots) are bounded at render.
Variables ¶
var ( ErrNoParts = errors.New("template: no parts") ErrPartName = errors.New("template: part name must be [a-z][a-z0-9_]* and unique") ErrPartKind = errors.New("template: part kind must be text or html") ErrPartTooBig = errors.New("template: part exceeds 256 KiB") ErrTooMany = errors.New("template: too many parts") ErrParse = errors.New("template: parse") ErrRender = errors.New("template: render") ErrDataTooBig = errors.New("template: data exceeds 1 MiB") ErrTooLong = errors.New("output exceeds 1 MiB") ErrTooSlow = errors.New("template: render exceeded 2s") ErrLanguage = errors.New("template: not a language tag") // ErrBusy: renders that ran past their time still hold every slot; // retrying later can succeed. ErrBusy = errors.New("template: too many renders running") )
Errors of Compile and Render; every one is final but ErrBusy.
var ( ErrRangeSource = errors.New("range iterates only over data: a field or a variable holding one") ErrRangeDepth = errors.New("ranges nest at most 2 deep") ErrDefine = errors.New("define and block are not allowed: use a shared piece") ErrCycle = errors.New("shared pieces include each other in a cycle") ErrDataItems = errors.New("template: data holds more than 10000 elements") )
Errors of the checks.
Functions ¶
func DecodeData ¶
DecodeData parses the JSON object data of a render and bounds what a template can iterate over (see safety.go).
func ParseLanguage ¶ added in v0.2.0
ParseLanguage is the canonical BCP 47 form of a tag ("ru", "pt-BR").
Types ¶
type Compiled ¶
type Compiled struct {
// contains filtered or unexported fields
}
Compiled is a template ready to render in one language.
type Part ¶
type Part struct {
Name string `json:"name"`
Kind string `json:"kind"`
Source string `json:"source,omitempty"`
}
Part is one output of a template in one language: its name, how it is escaped and its source.
type Partial ¶
Partial is a shared piece in the language being compiled: a template whose parts other templates include by the template's name.
type ProblemError ¶
ProblemError is what a part is wrong about: for the console's editor.
func Problems ¶
func Problems(err error) []ProblemError
Problems lists the problems an error carries (parse or render), in part order.
func (ProblemError) Error ¶
func (p ProblemError) Error() string