template

Documentation

Overview

Data-driven templates for generating textual output such as HTML. See

http://code.google.com/p/json-template/wiki/Reference

for full documentation of the template language. A summary:

Templates are executed by applying them to a data structure. Annotations in the template refer to elements of the data structure (typically a field of a struct or a key in a map) to control execution and derive values to be displayed. The template walks the structure as it executes and the "cursor" @ represents the value at the current location in the structure.

Data items may be values or pointers; the interface hides the indirection.

In the following, 'field' is one of several things, according to the data.

• the name of a field of a struct (result = data.field)
• the value stored in a map under that key (result = data[field])
• the result of invoking a niladic single-valued method with that name (result = data.field())

Major constructs ({} are metacharacters; [] marks optional elements):

{# comment }

A one-line comment.

{.section field} XXX [ {.or} YYY ] {.end}

Set @ to the value of the field. It may be an explicit @ to stay at the same point in the data. If the field is nil or empty, execute YYY; otherwise execute XXX.

{.repeated section field} XXX [ {.alternates with} ZZZ ] [ {.or} YYY ] {.end}

Like .section, but field must be an array or slice. XXX is executed for each element. If the array is nil or empty, YYY is executed instead. If the {.alternates with} marker is present, ZZZ is executed between iterations of XXX.

{field}
{field|formatter}

Insert the value of the field into the output. Field is first looked for in the cursor, as in .section and .repeated. If it is not found, the search continues in outer sections until the top level is reached.

If a formatter is specified, it must be named in the formatter map passed to the template set up routines or in the default set ("html","str","") and is used to process the data for output. The formatter function has signature

func(wr io.Write, data interface{}, formatter string)

where wr is the destination for output, data is the field value, and formatter is its name at the invocation site.

Index

• func HTMLEscape(w io.Writer, s []byte)
• func HTMLFormatter(w io.Writer, value interface{}, format string)
• func StringFormatter(w io.Writer, value interface{}, format string)
• type Error
  • func (e *Error) String() string
• type FormatterMap
• type Template
  • func MustParse(s string, fmap FormatterMap) *Template
  • func MustParseFile(filename string, fmap FormatterMap) *Template
  • func New(fmap FormatterMap) *Template
  • func Parse(s string, fmap FormatterMap) (t *Template, err os.Error)
  • func ParseFile(filename string, fmap FormatterMap) (t *Template, err os.Error)
  • func (t *Template) Execute(data interface{}, wr io.Writer) os.Error
  • func (t *Template) Parse(s string) os.Error
  • func (t *Template) SetDelims(left, right string)

Functions

func HTMLEscape

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

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

func HTMLFormatter

func HTMLFormatter(w io.Writer, value interface{}, format string)

HTMLFormatter formats arbitrary values for HTML

func StringFormatter

func StringFormatter(w io.Writer, value interface{}, format string)

StringFormatter formats into the default string representation. It is stored under the name "str" and is the default formatter. You can override the default formatter by storing your default under the name "" in your custom formatter map.

Types

type Error

type Error struct {
	Line int
	Msg  string
}

Errors returned during parsing and execution. Users may extract the information and reformat if they desire.

func (*Error) String

func (e *Error) String() string

type FormatterMap

type FormatterMap map[string]func(io.Writer, interface{}, string)

FormatterMap is the type describing the mapping from formatter names to the functions that implement them.

type Template

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

Template is the type that represents a template definition. It is unchanged after parsing.

func MustParse

func MustParse(s string, fmap FormatterMap) *Template

MustParse is like Parse but panics if the template cannot be parsed.

func MustParseFile

func MustParseFile(filename string, fmap FormatterMap) *Template

MustParseFile is like ParseFile but panics if the file cannot be read or the template cannot be parsed.

func New

func New(fmap FormatterMap) *Template

New creates a new template with the specified formatter map (which may be nil) to define auxiliary functions for formatting variables.

func Parse

func Parse(s string, fmap FormatterMap) (t *Template, err os.Error)

Parse creates a Template with default parameters (such as {} for metacharacters). The string s contains the template text while the formatter map fmap, which may be nil, defines auxiliary functions for formatting variables. The template is returned. If any errors occur, err will be non-nil.

func ParseFile

func ParseFile(filename string, fmap FormatterMap) (t *Template, err os.Error)

ParseFile is a wrapper function that creates a Template with default parameters (such as {} for // metacharacters). The filename identfies a file containing the template text, while the formatter map fmap, which may be nil, defines auxiliary functions for formatting variables. The template is returned. If any errors occur, err will be non-nil.

func (*Template) Execute

func (t *Template) Execute(data interface{}, wr io.Writer) os.Error

Execute applies a parsed template to the specified data object, generating output to wr.

func (*Template) Parse

func (t *Template) Parse(s string) os.Error

Parse initializes a Template by parsing its definition. The string s contains the template text. If any errors occur, Parse returns the error.

func (*Template) SetDelims

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

SetDelims sets the left and right delimiters for operations in the template. They are validated during parsing. They could be validated here but it's better to keep the routine simple. The delimiters are very rarely invalid and Parse has the necessary error-handling interface already.