github.com/llvm-mirror/llgo@v0.0.0-20190322182713-bf6f0a60fce1/third_party/gofrontend/libgo/go/old/template/doc.go (about)

     1  // Copyright 2009 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  /*
     6  	Package template implements data-driven templates for generating textual
     7  	output such as HTML.
     8  
     9  	Templates are executed by applying them to a data structure.
    10  	Annotations in the template refer to elements of the data
    11  	structure (typically a field of a struct or a key in a map)
    12  	to control execution and derive values to be displayed.
    13  	The template walks the structure as it executes and the
    14  	"cursor" @ represents the value at the current location
    15  	in the structure.
    16  
    17  	Data items may be values or pointers; the interface hides the
    18  	indirection.
    19  
    20  	In the following, 'Field' is one of several things, according to the data.
    21  
    22  		- The name of a field of a struct (result = data.Field),
    23  		- The value stored in a map under that key (result = data["Field"]), or
    24  		- The result of invoking a niladic single-valued method with that name
    25  		  (result = data.Field())
    26  
    27  	If Field is a struct field or method name, it must be an exported
    28  	(capitalized) name.
    29  
    30  	Major constructs ({} are the default delimiters for template actions;
    31  	[] are the notation in this comment for optional elements):
    32  
    33  		{# comment }
    34  
    35  	A one-line comment.
    36  
    37  		{.section field} XXX [ {.or} YYY ] {.end}
    38  
    39  	Set @ to the value of the field.  It may be an explicit @
    40  	to stay at the same point in the data. If the field is nil
    41  	or empty, execute YYY; otherwise execute XXX.
    42  
    43  		{.repeated section field} XXX [ {.alternates with} ZZZ ] [ {.or} YYY ] {.end}
    44  
    45  	Like .section, but field must be an array or slice.  XXX
    46  	is executed for each element.  If the array is nil or empty,
    47  	YYY is executed instead.  If the {.alternates with} marker
    48  	is present, ZZZ is executed between iterations of XXX.
    49  
    50  		{field}
    51  		{field1 field2 ...}
    52  		{field|formatter}
    53  		{field1 field2...|formatter}
    54  		{field|formatter1|formatter2}
    55  
    56  	Insert the value of the fields into the output. Each field is
    57  	first looked for in the cursor, as in .section and .repeated.
    58  	If it is not found, the search continues in outer sections
    59  	until the top level is reached.
    60  
    61  	If the field value is a pointer, leading asterisks indicate
    62  	that the value to be inserted should be evaluated through the
    63  	pointer.  For example, if x.p is of type *int, {x.p} will
    64  	insert the value of the pointer but {*x.p} will insert the
    65  	value of the underlying integer.  If the value is nil or not a
    66  	pointer, asterisks have no effect.
    67  
    68  	If a formatter is specified, it must be named in the formatter
    69  	map passed to the template set up routines or in the default
    70  	set ("html","str","") and is used to process the data for
    71  	output.  The formatter function has signature
    72  		func(wr io.Writer, formatter string, data ...interface{})
    73  	where wr is the destination for output, data holds the field
    74  	values at the instantiation, and formatter is its name at
    75  	the invocation site.  The default formatter just concatenates
    76  	the string representations of the fields.
    77  
    78  	Multiple formatters separated by the pipeline character | are
    79  	executed sequentially, with each formatter receiving the bytes
    80  	emitted by the one to its left.
    81  
    82  	As well as field names, one may use literals with Go syntax.
    83  	Integer, floating-point, and string literals are supported.
    84  	Raw strings may not span newlines.
    85  
    86  	The delimiter strings get their default value, "{" and "}", from
    87  	JSON-template.  They may be set to any non-empty, space-free
    88  	string using the SetDelims method.  Their value can be printed
    89  	in the output using {.meta-left} and {.meta-right}.
    90  */
    91  package template