template

package module
v0.0.1 Latest Latest
Warning

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

 Go to latest Published: Oct 25, 2023 License: MIT Imports: 14 Imported by: 0

README

template

a fast and full-featured template generator for go

Documentation

Overview

This package is drop-in replacement for text/template, implementing additional template engines.

More information on templates can be found on https://git.dresden.micronet24.de/toolkit/template/wiki, existing text/template or html/template templates should work as is.

The API covers most of text/template API.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func HTMLEscape 

func HTMLEscape(w io.Writer, b []byte)

HTMLEscape writes to w the escaped HTML equivalent of the plain text data b.

func HTMLEscapeString 

func HTMLEscapeString(s string) string

HTMLEscapeString returns the escaped HTML equivalent of the plain text data s.

func HTMLEscaper 

func HTMLEscaper(args ...any) string

HTMLEscaper returns the escaped HTML equivalent of the textual representation of its arguments.

func IsTrue 

func IsTrue(val any) (truth, ok bool)

IsTrue reports whether the value is 'true', in the sense of not the zero of its type, and whether the value has a meaningful truth value. This is the definition of truth used by if and other such actions.

func JSEscape 

func JSEscape(w io.Writer, b []byte)

JSEscape writes to w the escaped JavaScript equivalent of the plain text data b.

func JSEscapeString 

func JSEscapeString(s string) string

JSEscapeString returns the escaped JavaScript equivalent of the plain text data s.

func JSEscaper 

func JSEscaper(args ...any) string

JSEscaper returns the escaped JavaScript equivalent of the textual representation of its arguments.

func SelectOnMissingNoVal 

func SelectOnMissingNoVal(name string, e error) (reflect.Value, error)

func URLQueryEscaper 

func URLQueryEscaper(args ...any) string

URLQueryEscaper returns the escaped value of the textual representation of its arguments in a form suitable for embedding in a URL query.

Types

type FuncMap 

type FuncMap map[string]any

FuncMap is the type of the map defining the mapping from names to functions. Each function must have either a single return value, or two return values of which the second has type error. In that case, if the second (error) return value evaluates to non-nil during execution, execution terminates and Execute returns that error.

When template execution invokes a function with an argument list, that list must be assignable to the function's parameter types. Functions meant to apply to arguments of arbitrary type can use parameters of type interface{} or of type reflect.Value. Similarly, functions meant to return a result of arbitrary type can return interface{} or reflect.Value.

type OptionCompat 

type OptionCompat struct {
	Behaviour string
}

OptionCompat can be used as a convenience helper to adjust the template-behaviuor to a well-known reference. This can be * text/template * html/template

func (*OptionCompat) GetOption 

func (o *OptionCompat) GetOption(t *Template)

func (*OptionCompat) SetOption 

func (o *OptionCompat) SetOption(t *Template) error

type OptionDefaultFunc 

type OptionDefaultFunc struct {
	Enable bool
}

OptionDefaultFunc can be used to disable the default functions, or check wether they are enabled

func (*OptionDefaultFunc) GetOption 

func (o *OptionDefaultFunc) GetOption(t *Template)

func (*OptionDefaultFunc) SetOption 

func (o *OptionDefaultFunc) SetOption(t *Template)

type OptionDelimiter 

type OptionDelimiter struct {
	Engine, Start, End string
	// contains filtered or unexported fields
}

OptionDelimiter can be used to set or retrive the action delimiter (the strings marking the Start and the End of a template action) for a certain template Engine.

If an invalid Engine is specified, the SetOption/GetOption calls will panic()

func (*OptionDelimiter) GetOption 

func (o *OptionDelimiter) GetOption(t *Template)

GetOption retrieves the currently set delimiters.

If Engine is set, the Start/End delimiters of that engine will be stored in o. If Engine is empty, the name and delimiters of the first engine will be returned by the first call to GetOption, of the next engine for subsequent calls with the same o. If all engines have been returned, Engine, Start and End will be set to the empty string.

func (*OptionDelimiter) SetOption 

func (o *OptionDelimiter) SetOption(t *Template)

SetOption sets the action delimiter for a certain Engine. If no Engine is given, the first Engine available, usually `text/template` will be used. If Start or End are Empty, the delimiter will not be changed.

type OptionFunction 

type OptionFunction struct {
	Name     string
	Type     itemcontrol.FuncType
	Function any
}

OptionFunc is used to add or retrieve user-defined functions towards the template

func (*OptionFunction) GetOption 

func (o *OptionFunction) GetOption(t *Template)

func (*OptionFunction) SetOption 

func (o *OptionFunction) SetOption(t *Template)

type OptionFunctionMap 

type OptionFunctionMap struct {
	Type        itemcontrol.FuncType
	FunctionMap map[string]any
}

OptionfuncMap is used to add or retrieve multiple user-defined functions with the same type towards the template.

Retrieving functions can be filtered by Type and by Name (or both) - for name filtering the FunctionMap must have the keys with the names of interest defined (the value can be nil)

func (*OptionFunctionMap) GetOption 

func (o *OptionFunctionMap) GetOption(t *Template)

func (*OptionFunctionMap) SetOption 

func (o *OptionFunctionMap) SetOption(t *Template)

type OptionMissingKey 

type OptionMissingKey struct {
	OnMissing itemcontrol.SelectOnMissingHdl
}

OptionMissingKey can be used to adjust the behaviour when a template references a non-existing element

By default (using itemcontrol.SelectOnMissingIgnore) The item will be ignored and nothing is send to the output. Using itemcontrol.SelectOnMissingError will create an error on those instances. Alternatively a Custom function can be used, which will output an user-defined element.

func (*OptionMissingKey) GetOption 

func (o *OptionMissingKey) GetOption(t *Template)

func (*OptionMissingKey) SetOption 

func (o *OptionMissingKey) SetOption(t *Template)

type OptionOnError 

type OptionOnError struct {
	Hdl itemcontrol.OnErrorHdl
}

OptionOnError can be used to set an arbitrary error handler while executing a template

See also OptionSuppressError and OptionMissingKey

func (*OptionOnError) GetOption 

func (o *OptionOnError) GetOption(t *Template)

func (*OptionOnError) SetOption 

func (o *OptionOnError) SetOption(t *Template)

type OptionSuppressError 

type OptionSuppressError struct {
	Suppress bool
}

OptionSuppressError can be used to define, wether errors in the template (such as incomatible conversions on map/array indices) are returned or silently ignored.

By default, all errors are ignored.

See also OptionMissingKey (which can generate errors, which might get suppressed, or can ignore keys on its own) and OptionOnError for a fine-grained control

func (*OptionSuppressError) GetOption 

func (o *OptionSuppressError) GetOption(t *Template)

func (*OptionSuppressError) SetOption 

func (o *OptionSuppressError) SetOption(t *Template)

type Template 

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

Template is the representation of a parsed template.

func Create 

func Create() *Template

Create a new (empty) Template Group

func Must 

func Must(t *Template, err error) *Template

Must is a helper that wraps a call to a function returning (*Template, error) and panics if the error is non-nil. It is intended for use in variable initializations such as 

var t = template.Must(template.New("name").Parse("text"))

func New 

func New(name string) *Template

New allocates a new, undefined template with the given name.

func ParseFS 

func ParseFS(fsys fs.FS, patterns ...string) (*Template, error)

ParseFS is like ParseFiles or ParseGlob but reads from the file system fsys instead of the host operating system's file system. It accepts a list of glob patterns. (Note that most file names serve as glob patterns matching only themselves.)

func ParseFiles 

func ParseFiles(filenames ...string) (*Template, error)

ParseFiles creates a new Template and parses the template definitions from the named files. The returned template's name will have the base name and parsed contents of the first file. There must be at least one file. If an error occurs, parsing stops and the returned *Template is nil.

When parsing multiple files with the same name in different directories, the last one mentioned will be the one that results. For instance, ParseFiles("a/foo", "b/foo") stores "b/foo" as the template named "foo", while "a/foo" is unavailable.

func ParseGlob 

func ParseGlob(pattern string) (*Template, error)

ParseGlob creates a new Template and parses the template definitions from the files identified by the pattern. The files are matched according to the semantics of filepath.Match, and the pattern must match at least one file. The returned template will have the (base) name and (parsed) contents of the first file matched by the pattern. ParseGlob is equivalent to calling ParseFiles with the list of files matched by the pattern.

When parsing multiple files with the same name in different directories, the last one mentioned will be the one that results.

func (*Template) Clone 

func (t *Template) Clone() (*Template, error)

Clone duplicates the current template group. The new template group will have all the currently known templates as well, but new templates are only added either to the clone or the instance t of the template group.

Clone can be used to prepare a common template group and add distinct templates for different representations afterwards.

func (*Template) Create 

func (t *Template) Create() *Template

Create a new common part of the template, if not existing

func (*Template) DefinedTemplates 

func (t *Template) DefinedTemplates() string

DefinedTemplates is provided as compatibility function for text/template and html/template. It returns the list of known templates in a single string used for error messages.

Deprecated. Use t.TemplateNames() instead.

func (*Template) Delims 

func (t *Template) Delims(left, right string) *Template

Delims is a compatibility function for "text/template" for changing the template action delimiters. Those will be used by all feature calls to one of the Parse* functions in the template group. If any of left or right is empty, the defaults `{{` resp. `}}` are used.

This call is deprecated, use `t.SetOption(&OptionDelimiter{"text/template", left, right})` instead.

To allow chained calls, the template itself is returned

func (*Template) Execute 

func (t *Template) Execute(out io.Writer, data interface{}) (err error)

Execute applies a parsed template to the specified data object, and writes the output to wr. If an error occurs executing the template or writing its output, execution stops, but partial results may already have been written to the output writer. A template may be executed safely in parallel, although if parallel executions share a Writer the output may be interleaved.

If data is a reflect.Value, the template applies to the concrete value that the reflect.Value holds, as in fmt.Print.

func (*Template) ExecuteTemplate 

func (t *Template) ExecuteTemplate(wr io.Writer, name string, data any) error

ExecuteTemplate will use a previously parsed template of the template group by the given name and fill in the active parts using the data supplied. The generated output will be written to wr. Unless wr is the same for different calls to ExecuteTemplate(), the templates can be processed in parallel.

func (*Template) Funcs 

func (t *Template) Funcs(funcMap FuncMap) *Template

Funcs adds the elements of the argument map to the template's function map. It must be called before the template is parsed. It panics if a value in the map is not a function with appropriate return type or if the name cannot be used syntactically as a function in a template. It is legal to overwrite elements of the map. The return value is the template, so calls can be chained.

func (*Template) GetOption 

func (t *Template) GetOption(o ...TemplateOption) *Template

GetOption can be used to retrieve the current setting of a certain Option. The current setting will be set within the TemplateOption passed as argument. It is allowed to pass multiple TemplateOptions to retrieve multiple settings at once. The template itself will be returned to allow chained calls.

func (*Template) Lookup 

func (t *Template) Lookup(name string) *Template

Lookup retrieves a previously Parse()d template in the current template group.

Nil is returned, if the template hasn't been created yet.

func (*Template) Name 

func (t *Template) Name() string

Name returns the name of the template.

func (*Template) New 

func (t *Template) New(name string) *Template

New allocates a new, undefined template associated with the given one and with the same delimiters. The association, which is transitive, allows one template to invoke another with a {{template}} action.

Because associated templates share underlying data, template construction cannot be done safely in parallel. Once the templates are constructed, they can be executed in parallel.

func (*Template) Option 

func (t *Template) Option(opt ...string) *Template

Option sets options for the template. Options are described by strings, either a simple string or "key=value". There can be at most one equals sign in an option string. If the option string is unrecognized or otherwise invalid, Option panics.

Known options:

missingkey: Control the behavior during execution if a map is indexed with a key that is not present in the map. 

"missingkey=default" or "missingkey=invalid"
	The default behavior: Do nothing and continue execution.
	If printed, the result of the index operation is the string
	"<no value>".
"missingkey=zero"
	The operation returns the zero value for the map type's element.
"missingkey=error"
	Execution stops immediately with an error.

func (*Template) Parse 

func (t *Template) Parse(text string) (*Template, error)

Parse parses text as a template body for t. Named template definitions ({{define ...}} or {{block ...}} statements) in text define additional templates associated with t and are removed from the definition of t itself.

Templates can be redefined in successive calls to Parse. A template definition with a body containing only white space and comments is considered empty and will not replace an existing template's body. This allows using Parse to add new named template definitions without overwriting the main template body.

func (*Template) ParseFS 

func (t *Template) ParseFS(fsys fs.FS, patterns ...string) (*Template, error)

ParseFS is like ParseFiles or ParseGlob but reads from the file system fsys instead of the host operating system's file system. It accepts a list of glob patterns. (Note that most file names serve as glob patterns matching only themselves.)

func (*Template) ParseFiles 

func (t *Template) ParseFiles(filenames ...string) (*Template, error)

ParseFiles parses the named files and associates the resulting templates with t. If an error occurs, parsing stops and the returned template is nil; otherwise it is t. There must be at least one file. Since the templates created by ParseFiles are named by the base names of the argument files, t should usually have the name of one of the (base) names of the files. If it does not, depending on t's contents before calling ParseFiles, t.Execute may fail. In that case use t.ExecuteTemplate to execute a valid template.

When parsing multiple files with the same name in different directories, the last one mentioned will be the one that results.

func (*Template) ParseGlob 

func (t *Template) ParseGlob(pattern string) (*Template, error)

ParseGlob parses the template definitions in the files identified by the pattern and associates the resulting templates with t. The files are matched according to the semantics of filepath.Match, and the pattern must match at least one file. ParseGlob is equivalent to calling t.ParseFiles with the list of files matched by the pattern.

When parsing multiple files with the same name in different directories, the last one mentioned will be the one that results.

func (*Template) ParseReader 

func (t *Template) ParseReader(input io.Reader) (ot *Template, err error)

ParseReader parses input as template body for t. See Parse()

func (*Template) SetOption 

func (t *Template) SetOption(o ...TemplateOption) *Template

SetOption can be used to set one or more options affecting the parsing or execution of a template group

The option to set and the corresponding parameters are set in the TemplateOption. Multiple options can be set at once. The template itself will be returned to allow chaining.

func (*Template) TemplateNames 

func (t *Template) TemplateNames() []string

TemplateNamess returns the names of all defined templates within t's template group

func (*Template) Templates 

func (t *Template) Templates() []*Template

Templates returns all defined templates within t's template group

type TemplateOption 

type TemplateOption interface {
	SetOption(t *Template)
	GetOption(t *Template)
}

TemplateOption is an interface for setting and retrieving options and parameters of a template group

Source Files

View all Source files

Directories

Path Synopsis
Package itemcontrol implements the logic needed for the different parsed tokens on a certain template.
 Package itemcontrol implements the logic needed for the different parsed tokens on a certain template.
Package text implements the inner lexer and parser for text/template like templates
 Package text implements the inner lexer and parser for text/template like templates
testhelper
Package tmpl is responsible for parsing the combined templates for git.dresden.micronet24.de/toolkit/template
 Package tmpl is responsible for parsing the combined templates for git.dresden.micronet24.de/toolkit/template

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.