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.
6 Data-driven templates for generating textual output such as
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
17 Data items may be values or pointers; the interface hides the
20 In the following, 'field' is one of several things, according to the data.
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())
27 Major constructs ({} are metacharacters; [] marks optional elements):
33 {.section field} XXX [ {.or} YYY ] {.end}
35 Set @ to the value of the field. It may be an explicit @
36 to stay at the same point in the data. If the field is nil
37 or empty, execute YYY; otherwise execute XXX.
39 {.repeated section field} XXX [ {.alternates with} ZZZ ] [ {.or} YYY ] {.end}
41 Like .section, but field must be an array or slice. XXX
42 is executed for each element. If the array is nil or empty,
43 YYY is executed instead. If the {.alternates with} marker
44 is present, ZZZ is executed between iterations of XXX.
49 Insert the value of the field into the output. Field is
50 first looked for in the cursor, as in .section and .repeated.
51 If it is not found, the search continues in outer sections
52 until the top level is reached.
54 If a formatter is specified, it must be named in the formatter
55 map passed to the template set up routines or in the default
56 set ("html","str","") and is used to process the data for
57 output. The formatter function has signature
58 func(wr io.Writer, data interface{}, formatter string)
59 where wr is the destination for output, data is the field
60 value, and formatter is its name at the invocation site.
74 // Errors returned during parsing and execution. Users may extract the information and reformat
81 func (e *Error) String() string { return fmt.Sprintf("line %d: %s", e.Line, e.Msg) }
83 // Most of the literals are aces.
84 var lbrace = []byte{'{'}
85 var rbrace = []byte{'}'}
86 var space = []byte{' '}
87 var tab = []byte{'\t'}
89 // The various types of "tokens", which are plain text or (usually) brace-delimited descriptors
102 // FormatterMap is the type describing the mapping from formatter
103 // names to the functions that implement them.
104 type FormatterMap map[string]func(io.Writer, interface{}, string)
106 // Built-in formatters.
107 var builtins = FormatterMap{
108 "html": HTMLFormatter,
109 "str": StringFormatter,
113 // The parsed state of a template is a vector of xxxElement structs.
114 // Sections have line numbers so errors can be reported better during execution.
117 type textElement struct {
121 // A literal such as .meta-left or .meta-right
122 type literalElement struct {
126 // A variable to be evaluated
127 type variableElement struct {
130 formatter string // TODO(r): implement pipelines
133 // A .section block, possibly with a .or
134 type sectionElement struct {
135 linenum int // of .section itself
136 field string // cursor field for this block
137 start int // first element
138 or int // first element of .or block
139 end int // one beyond last element
142 // A .repeated block, possibly with a .or and a .alternates
143 type repeatedElement struct {
144 sectionElement // It has the same structure...
145 altstart int // ... except for alternates
149 // Template is the type that represents a template definition.
150 // It is unchanged after parsing.
151 type Template struct {
152 fmap FormatterMap // formatters for variables
153 // Used during parsing:
154 ldelim, rdelim []byte // delimiters; default {}
155 buf []byte // input text to process
156 p int // position in buf
157 linenum int // position in input
162 // Internal state for executing a Template. As we evaluate the struct,
163 // the data item descends into the fields associated with sections, etc.
164 // Parent is used to walk upwards to find variables higher in the tree.
166 parent *state // parent in hierarchy
167 data reflect.Value // the driver data for this section etc.
168 wr io.Writer // where to send output
171 func (parent *state) clone(data reflect.Value) *state {
172 return &state{parent, data, parent.wr}
175 // New creates a new template with the specified formatter map (which
176 // may be nil) to define auxiliary functions for formatting variables.
177 func New(fmap FormatterMap) *Template {
182 t.elems = new(vector.Vector)
186 // Report error and stop executing. The line number must be provided explicitly.
187 func (t *Template) execError(st *state, line int, err string, args ...interface{}) {
188 panic(&Error{line, fmt.Sprintf(err, args...)})
191 // Report error, panic to terminate parsing.
192 // The line number comes from the template state.
193 func (t *Template) parseError(err string, args ...interface{}) {
194 panic(&Error{t.linenum, fmt.Sprintf(err, args...)})
197 // -- Lexical analysis
199 // Is c a white space character?
200 func white(c uint8) bool { return c == ' ' || c == '\t' || c == '\r' || c == '\n' }
202 // Safely, does s[n:n+len(t)] == t?
203 func equal(s []byte, n int, t []byte) bool {
205 if len(t) > len(b) { // not enough space left for a match.
208 for i, c := range t {
216 // nextItem returns the next item from the input buffer. If the returned
217 // item is empty, we are at EOF. The item will be either a
218 // delimited string or a non-empty string between delimited
219 // strings. Tokens stop at (but include, if plain text) a newline.
220 // Action tokens on a line by themselves drop any space on
221 // either side, up to and including the newline.
222 func (t *Template) nextItem() []byte {
223 startOfLine := t.p == 0 || t.buf[t.p-1] == '\n'
230 // Leading white space up to but not including newline
231 for i = start; i < len(t.buf); i++ {
232 if t.buf[i] == '\n' || !white(t.buf[i]) {
236 leadingSpace := i > start
237 // What's left is nothing, newline, delimited string, or plain text
240 case i == len(t.buf):
241 // EOF; nothing to do
242 case t.buf[i] == '\n':
244 case equal(t.buf, i, t.ldelim):
245 left := i // Start of left delimiter.
246 right := -1 // Will be (immediately after) right delimiter.
247 haveText := false // Delimiters contain text.
249 // Find the end of the action.
250 for ; i < len(t.buf); i++ {
251 if t.buf[i] == '\n' {
254 if equal(t.buf, i, t.rdelim) {
262 t.parseError("unmatched opening delimiter")
265 // Is this a special action (starts with '.' or '#') and the only thing on the line?
266 if startOfLine && haveText {
267 firstChar := t.buf[left+len(t.ldelim)]
268 if firstChar == '.' || firstChar == '#' {
269 // It's special and the first thing on the line. Is it the last?
270 for j := right; j < len(t.buf) && white(t.buf[j]); j++ {
271 if t.buf[j] == '\n' {
272 // Yes it is. Drop the surrounding space and return the {.foo}
275 return t.buf[left:right]
280 // No it's not. If there's leading space, return that.
282 // not trimming space: return leading white space if there is some.
284 return t.buf[start:left]
286 // Return the word, leave the trailing space.
290 for ; i < len(t.buf); i++ {
291 if t.buf[i] == '\n' {
295 if equal(t.buf, i, t.ldelim) {
300 item := t.buf[start:i]
305 // Turn a byte array into a white-space-split array of strings.
306 func words(buf []byte) []string {
307 s := make([]string, 0, 5)
308 p := 0 // position in buf
312 for ; p < len(buf) && white(buf[p]); p++ {
316 for ; p < len(buf) && !white(buf[p]); p++ {
318 if start == p { // no text left
321 s = append(s, string(buf[start:p]))
326 // Analyze an item and return its token type and, if it's an action item, an array of
327 // its constituent words.
328 func (t *Template) analyze(item []byte) (tok int, w []string) {
329 // item is known to be non-empty
330 if !equal(item, 0, t.ldelim) { // doesn't start with left delimiter
334 if !equal(item, len(item)-len(t.rdelim), t.rdelim) { // doesn't end with right delimiter
335 t.parseError("internal error: unmatched opening delimiter") // lexing should prevent this
338 if len(item) <= len(t.ldelim)+len(t.rdelim) { // no contents
339 t.parseError("empty directive")
343 if item[len(t.ldelim)] == '#' {
348 w = words(item[len(t.ldelim) : len(item)-len(t.rdelim)]) // drop final delimiter
350 t.parseError("empty directive")
353 if len(w) == 1 && w[0][0] != '.' {
358 case ".meta-left", ".meta-right", ".space", ".tab":
369 t.parseError("incorrect fields for .section: %s", item)
375 if len(w) != 3 || w[1] != "section" {
376 t.parseError("incorrect fields for .repeated: %s", item)
382 if len(w) != 2 || w[1] != "with" {
383 t.parseError("incorrect fields for .alternates: %s", item)
389 t.parseError("bad directive: %s", item)
395 // Allocate a new variable-evaluation element.
396 func (t *Template) newVariable(name_formatter string) (v *variableElement) {
397 name := name_formatter
399 bar := strings.Index(name_formatter, "|")
401 name = name_formatter[0:bar]
402 formatter = name_formatter[bar+1:]
404 // Probably ok, so let's build it.
405 v = &variableElement{t.linenum, name, formatter}
407 // We could remember the function address here and avoid the lookup later,
408 // but it's more dynamic to let the user change the map contents underfoot.
409 // We do require the name to be present, though.
411 // Is it in user-supplied map?
413 if _, ok := t.fmap[formatter]; ok {
417 // Is it in builtin map?
418 if _, ok := builtins[formatter]; ok {
421 t.parseError("unknown formatter: %s", formatter)
425 // Grab the next item. If it's simple, just append it to the template.
426 // Otherwise return its details.
427 func (t *Template) parseSimple(item []byte) (done bool, tok int, w []string) {
428 tok, w = t.analyze(item)
429 done = true // assume for simplicity
434 t.elems.Push(&textElement{item})
439 t.elems.Push(&literalElement{t.ldelim})
441 t.elems.Push(&literalElement{t.rdelim})
443 t.elems.Push(&literalElement{space})
445 t.elems.Push(&literalElement{tab})
447 t.parseError("internal error: unknown literal: %s", w[0])
451 t.elems.Push(t.newVariable(w[0]))
457 // parseRepeated and parseSection are mutually recursive
459 func (t *Template) parseRepeated(words []string) *repeatedElement {
460 r := new(repeatedElement)
462 r.linenum = t.linenum
464 // Scan section, collecting true and false (.or) blocks.
465 r.start = t.elems.Len()
473 t.parseError("missing .end for .repeated section")
476 done, tok, w := t.parseSimple(item)
485 t.parseError("extra .or in .repeated section")
488 r.altend = t.elems.Len()
496 t.parseError("extra .alternates in .repeated section")
500 t.parseError(".alternates inside .or block in .repeated section")
503 r.altstart = t.elems.Len()
505 t.parseError("internal error: unknown repeated section item: %s", item)
510 r.altend = t.elems.Len()
512 r.end = t.elems.Len()
516 func (t *Template) parseSection(words []string) *sectionElement {
517 s := new(sectionElement)
519 s.linenum = t.linenum
521 // Scan section, collecting true and false (.or) blocks.
522 s.start = t.elems.Len()
528 t.parseError("missing .end for .section")
531 done, tok, w := t.parseSimple(item)
540 t.parseError("extra .or in .section")
549 t.parseError(".alternates not in .repeated")
551 t.parseError("internal error: unknown section item: %s", item)
554 s.end = t.elems.Len()
558 func (t *Template) parse() {
564 done, tok, w := t.parseSimple(item)
569 case tokOr, tokEnd, tokAlternates:
570 t.parseError("unexpected %s", w[0])
576 t.parseError("internal error: bad directive in parse: %s", item)
583 // Evaluate interfaces and pointers looking for a value that can look up the name, via a
584 // struct field, method, or map key, and return the result of the lookup.
585 func lookup(v reflect.Value, name string) reflect.Value {
588 if n := v.Type().NumMethod(); n > 0 {
589 for i := 0; i < n; i++ {
592 if m.Name == name && mtyp.NumIn() == 1 && mtyp.NumOut() == 1 {
593 return v.Method(i).Call(nil)[0]
597 switch av := v.(type) {
598 case *reflect.PtrValue:
600 case *reflect.InterfaceValue:
602 case *reflect.StructValue:
603 return av.FieldByName(name)
604 case *reflect.MapValue:
605 return av.Elem(reflect.NewValue(name))
613 // Walk v through pointers and interfaces, extracting the elements within.
614 func indirect(v reflect.Value) reflect.Value {
617 switch av := v.(type) {
618 case *reflect.PtrValue:
620 case *reflect.InterfaceValue:
629 // If the data for this template is a struct, find the named variable.
630 // Names of the form a.b.c are walked down the data tree.
631 // The special name "@" (the "cursor") denotes the current data.
632 // The value coming in (st.data) might need indirecting to reach
633 // a struct while the return value is not indirected - that is,
634 // it represents the actual named field.
635 func (st *state) findVar(s string) reflect.Value {
640 for _, elem := range strings.Split(s, ".", -1) {
641 // Look up field; data must be a struct or map.
642 data = lookup(data, elem)
650 // Is there no data to look at?
651 func empty(v reflect.Value) bool {
656 switch v := v.(type) {
657 case *reflect.BoolValue:
658 return v.Get() == false
659 case *reflect.StringValue:
661 case *reflect.StructValue:
663 case *reflect.MapValue:
665 case *reflect.ArrayValue:
667 case *reflect.SliceValue:
673 // Look up a variable or method, up through the parent if necessary.
674 func (t *Template) varValue(name string, st *state) reflect.Value {
675 field := st.findVar(name)
677 if st.parent == nil {
678 t.execError(st, t.linenum, "name not found: %s in type %s", name, st.data.Type())
680 return t.varValue(name, st.parent)
685 // Evaluate a variable, looking up through the parent if necessary.
686 // If it has a formatter attached ({var|formatter}) run that too.
687 func (t *Template) writeVariable(v *variableElement, st *state) {
688 formatter := v.formatter
689 val := t.varValue(v.name, st).Interface()
690 // is it in user-supplied map?
692 if fn, ok := t.fmap[formatter]; ok {
693 fn(st.wr, val, formatter)
697 // is it in builtin map?
698 if fn, ok := builtins[formatter]; ok {
699 fn(st.wr, val, formatter)
702 t.execError(st, v.linenum, "missing formatter %s for variable %s", formatter, v.name)
705 // Execute element i. Return next index to execute.
706 func (t *Template) executeElement(i int, st *state) int {
707 switch elem := t.elems.At(i).(type) {
709 st.wr.Write(elem.text)
711 case *literalElement:
712 st.wr.Write(elem.text)
714 case *variableElement:
715 t.writeVariable(elem, st)
717 case *sectionElement:
718 t.executeSection(elem, st)
720 case *repeatedElement:
721 t.executeRepeated(elem, st)
725 t.execError(st, 0, "internal error: bad directive in execute: %v %T\n", reflect.NewValue(e).Interface(), e)
729 // Execute the template.
730 func (t *Template) execute(start, end int, st *state) {
731 for i := start; i < end; {
732 i = t.executeElement(i, st)
736 // Execute a .section
737 func (t *Template) executeSection(s *sectionElement, st *state) {
738 // Find driver data for this section. It must be in the current struct.
739 field := t.varValue(s.field, st)
741 t.execError(st, s.linenum, ".section: cannot find field %s in %s", s.field, st.data.Type())
744 start, end := s.start, s.or
746 // Execute the normal block.
751 // Execute the .or block. If it's missing, do nothing.
752 start, end = s.or, s.end
757 for i := start; i < end; {
758 i = t.executeElement(i, st)
762 // Return the result of calling the Iter method on v, or nil.
763 func iter(v reflect.Value) *reflect.ChanValue {
764 for j := 0; j < v.Type().NumMethod(); j++ {
765 mth := v.Type().Method(j)
767 ft := fv.Type().(*reflect.FuncType)
768 // TODO(rsc): NumIn() should return 0 here, because ft is from a curried FuncValue.
769 if mth.Name != "Iter" || ft.NumIn() != 1 || ft.NumOut() != 1 {
772 ct, ok := ft.Out(0).(*reflect.ChanType)
773 if !ok || ct.Dir()&reflect.RecvDir == 0 {
776 return fv.Call(nil)[0].(*reflect.ChanValue)
781 // Execute a .repeated section
782 func (t *Template) executeRepeated(r *repeatedElement, st *state) {
783 // Find driver data for this section. It must be in the current struct.
784 field := t.varValue(r.field, st)
786 t.execError(st, r.linenum, ".repeated: cannot find field %s in %s", r.field, st.data.Type())
788 field = indirect(field)
790 start, end := r.start, r.or
799 // Code common to all the loops.
800 loopBody := func(newst *state) {
801 // .alternates between elements
802 if !first && r.altstart >= 0 {
803 for i := r.altstart; i < r.altend; {
804 i = t.executeElement(i, newst)
808 for i := start; i < end; {
809 i = t.executeElement(i, newst)
813 if array, ok := field.(reflect.ArrayOrSliceValue); ok {
814 for j := 0; j < array.Len(); j++ {
815 loopBody(st.clone(array.Elem(j)))
817 } else if m, ok := field.(*reflect.MapValue); ok {
818 for _, key := range m.Keys() {
819 loopBody(st.clone(m.Elem(key)))
821 } else if ch := iter(field); ch != nil {
827 loopBody(st.clone(e))
830 t.execError(st, r.linenum, ".repeated: cannot repeat %s (type %s)",
831 r.field, field.Type())
835 // Empty. Execute the .or block, once. If it's missing, do nothing.
836 start, end := r.or, r.end
838 newst := st.clone(field)
839 for i := start; i < end; {
840 i = t.executeElement(i, newst)
847 // A valid delimiter must contain no white space and be non-empty.
848 func validDelim(d []byte) bool {
852 for _, c := range d {
860 // checkError is a deferred function to turn a panic with type *Error into a plain error return.
861 // Other panics are unexpected and so are re-enabled.
862 func checkError(error *os.Error) {
863 if v := recover(); v != nil {
864 if e, ok := v.(*Error); ok {
867 // runtime errors should crash
873 // -- Public interface
875 // Parse initializes a Template by parsing its definition. The string
876 // s contains the template text. If any errors occur, Parse returns
878 func (t *Template) Parse(s string) (err os.Error) {
880 return &Error{1, "template not allocated with New"}
882 if !validDelim(t.ldelim) || !validDelim(t.rdelim) {
883 return &Error{1, fmt.Sprintf("bad delimiter strings %q %q", t.ldelim, t.rdelim)}
885 defer checkError(&err)
893 // ParseFile is like Parse but reads the template definition from the
895 func (t *Template) ParseFile(filename string) (err os.Error) {
896 b, err := ioutil.ReadFile(filename)
900 return t.Parse(string(b))
903 // Execute applies a parsed template to the specified data object,
904 // generating output to wr.
905 func (t *Template) Execute(data interface{}, wr io.Writer) (err os.Error) {
906 // Extract the driver data.
907 val := reflect.NewValue(data)
908 defer checkError(&err)
910 t.execute(0, t.elems.Len(), &state{nil, val, wr})
914 // SetDelims sets the left and right delimiters for operations in the
915 // template. They are validated during parsing. They could be
916 // validated here but it's better to keep the routine simple. The
917 // delimiters are very rarely invalid and Parse has the necessary
918 // error-handling interface already.
919 func (t *Template) SetDelims(left, right string) {
920 t.ldelim = []byte(left)
921 t.rdelim = []byte(right)
924 // Parse creates a Template with default parameters (such as {} for
925 // metacharacters). The string s contains the template text while
926 // the formatter map fmap, which may be nil, defines auxiliary functions
927 // for formatting variables. The template is returned. If any errors
928 // occur, err will be non-nil.
929 func Parse(s string, fmap FormatterMap) (t *Template, err os.Error) {
938 // ParseFile is a wrapper function that creates a Template with default
939 // parameters (such as {} for metacharacters). The filename identifies
940 // a file containing the template text, while the formatter map fmap, which
941 // may be nil, defines auxiliary functions for formatting variables.
942 // The template is returned. If any errors occur, err will be non-nil.
943 func ParseFile(filename string, fmap FormatterMap) (t *Template, err os.Error) {
944 b, err := ioutil.ReadFile(filename)
948 return Parse(string(b), fmap)
951 // MustParse is like Parse but panics if the template cannot be parsed.
952 func MustParse(s string, fmap FormatterMap) *Template {
953 t, err := Parse(s, fmap)
955 panic("template.MustParse error: " + err.String())
960 // MustParseFile is like ParseFile but panics if the file cannot be read
961 // or the template cannot be parsed.
962 func MustParseFile(filename string, fmap FormatterMap) *Template {
963 b, err := ioutil.ReadFile(filename)
965 panic("template.MustParseFile error: " + err.String())
967 return MustParse(string(b), fmap)