src/dma/vendor/github.com/valyala/fasttemplate/README.md

   1 fasttemplate
   2 ============
   3
   4 Simple and fast template engine for Go.
   5
   6 Fasttemplate peforms only a single task - it substitutes template placeholders
   7 with user-defined values. At high speed :)
   8
   9 Take a look at [quicktemplate](https://github.com/valyala/quicktemplate) if you  need fast yet powerful html template engine.
  10
  11 *Please note that fasttemplate doesn't do any escaping on template values
  12 unlike [html/template](http://golang.org/pkg/html/template/) do. So values
  13 must be properly escaped before passing them to fasttemplate.*
  14
  15 Fasttemplate is faster than [text/template](http://golang.org/pkg/text/template/),
  16 [strings.Replace](http://golang.org/pkg/strings/#Replace),
  17 [strings.Replacer](http://golang.org/pkg/strings/#Replacer)
  18 and [fmt.Fprintf](https://golang.org/pkg/fmt/#Fprintf) on placeholders' substitution.
  19
  20 Below are benchmark results comparing fasttemplate performance to text/template,
  21 strings.Replace, strings.Replacer and fmt.Fprintf:
  22
  23 ```
  24 $ go test -bench=. -benchmem
  25 PASS
  26 BenchmarkFmtFprintf-4                            2000000               790 ns/op               0 B/op          0 allocs/op
  27 BenchmarkStringsReplace-4                         500000              3474 ns/op            2112 B/op         14 allocs/op
  28 BenchmarkStringsReplacer-4                        500000              2657 ns/op            2256 B/op         23 allocs/op
  29 BenchmarkTextTemplate-4                           500000              3333 ns/op             336 B/op         19 allocs/op
  30 BenchmarkFastTemplateExecuteFunc-4               5000000               349 ns/op               0 B/op          0 allocs/op
  31 BenchmarkFastTemplateExecute-4                   3000000               383 ns/op               0 B/op          0 allocs/op
  32 BenchmarkFastTemplateExecuteFuncString-4         3000000               549 ns/op             144 B/op          1 allocs/op
  33 BenchmarkFastTemplateExecuteString-4             3000000               572 ns/op             144 B/op          1 allocs/op
  34 BenchmarkFastTemplateExecuteTagFunc-4            2000000               743 ns/op             144 B/op          3 allocs/op
  35 ```
  36
  37
  38 Docs
  39 ====
  40
  41 See http://godoc.org/github.com/valyala/fasttemplate .
  42
  43
  44 Usage
  45 =====
  46
  47 ```go
  48         template := "http://{{host}}/?q={{query}}&foo={{bar}}{{bar}}"
  49         t := fasttemplate.New(template, "{{", "}}")
  50         s := t.ExecuteString(map[string]interface{}{
  51                 "host":  "google.com",
  52                 "query": url.QueryEscape("hello=world"),
  53                 "bar":   "foobar",
  54         })
  55         fmt.Printf("%s", s)
  56
  57         // Output:
  58         // http://google.com/?q=hello%3Dworld&foo=foobarfoobar
  59 ```
  60
  61
  62 Advanced usage
  63 ==============
  64
  65 ```go
  66         template := "Hello, [user]! You won [prize]!!! [foobar]"
  67         t, err := fasttemplate.NewTemplate(template, "[", "]")
  68         if err != nil {
  69                 log.Fatalf("unexpected error when parsing template: %s", err)
  70         }
  71         s := t.ExecuteFuncString(func(w io.Writer, tag string) (int, error) {
  72                 switch tag {
  73                 case "user":
  74                         return w.Write([]byte("John"))
  75                 case "prize":
  76                         return w.Write([]byte("$100500"))
  77                 default:
  78                         return w.Write([]byte(fmt.Sprintf("[unknown tag %q]", tag)))
  79                 }
  80         })
  81         fmt.Printf("%s", s)
  82
  83         // Output:
  84         // Hello, John! You won $100500!!! [unknown tag "foobar"]
  85 ```