Subversion Repositories openrisc

// Copyright 2009 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

/*
        Package template implements data-driven templates for generating textual
        output such as HTML.

        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"]), or
                - The result of invoking a niladic single-valued method with that name
                  (result = data.Field())

        If Field is a struct field or method name, it must be an exported
        (capitalized) name.

        Major constructs ({} are the default delimiters for template actions;
        [] are the notation in this comment for 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}
                {field1 field2 ...}
                {field|formatter}
                {field1 field2...|formatter}
                {field|formatter1|formatter2}

        Insert the value of the fields into the output. Each 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 the field value is a pointer, leading asterisks indicate
        that the value to be inserted should be evaluated through the
        pointer.  For example, if x.p is of type *int, {x.p} will
        insert the value of the pointer but {*x.p} will insert the
        value of the underlying integer.  If the value is nil or not a
        pointer, asterisks have no effect.

        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.Writer, formatter string, data ...interface{})
        where wr is the destination for output, data holds the field
        values at the instantiation, and formatter is its name at
        the invocation site.  The default formatter just concatenates
        the string representations of the fields.

        Multiple formatters separated by the pipeline character | are
        executed sequentially, with each formatter receiving the bytes
        emitted by the one to its left.

        As well as field names, one may use literals with Go syntax.
        Integer, floating-point, and string literals are supported.
        Raw strings may not span newlines.

        The delimiter strings get their default value, "{" and "}", from
        JSON-template.  They may be set to any non-empty, space-free
        string using the SetDelims method.  Their value can be printed
        in the output using {.meta-left} and {.meta-right}.
*/
package template