| 1 |
/* |
| 2 |
Copyright 2015 The Kubernetes Authors. |
| 3 |
|
| 4 |
Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 |
you may not use this file except in compliance with the License. |
| 6 |
You may obtain a copy of the License at |
| 7 |
|
| 8 |
http://www.apache.org/licenses/LICENSE-2.0 |
| 9 |
|
| 10 |
Unless required by applicable law or agreed to in writing, software |
| 11 |
distributed under the License is distributed on an "AS IS" BASIS, |
| 12 |
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 |
See the License for the specific language governing permissions and |
| 14 |
limitations under the License. |
| 15 |
*/ |
| 16 |
|
| 17 |
package generator |
| 18 |
|
| 19 |
import ( |
| 20 |
"fmt" |
| 21 |
"io" |
| 22 |
"runtime" |
| 23 |
"text/template" |
| 24 |
) |
| 25 |
|
| 26 |
// SnippetWriter is an attempt to make the template library usable. |
| 27 |
// Methods are chainable, and you don't have to check Error() until you're all |
| 28 |
// done. |
| 29 |
type SnippetWriter struct { |
| 30 |
w io.Writer |
| 31 |
context *Context |
| 32 |
// Left & right delimiters. text/template defaults to "{{" and "}}" |
| 33 |
// which is totally unusable for go code based templates. |
| 34 |
left, right string |
| 35 |
funcMap template.FuncMap |
| 36 |
err error |
| 37 |
} |
| 38 |
|
| 39 |
// w is the destination; left and right are the delimiters; @ and $ are both |
| 40 |
// reasonable choices. |
| 41 |
// |
| 42 |
// c is used to make a function for every naming system, to which you can pass |
| 43 |
// a type and get the corresponding name. |
| 44 |
func NewSnippetWriter(w io.Writer, c *Context, left, right string) *SnippetWriter { |
| 45 |
sw := &SnippetWriter{ |
| 46 |
w: w, |
| 47 |
context: c, |
| 48 |
left: left, |
| 49 |
right: right, |
| 50 |
funcMap: template.FuncMap{}, |
| 51 |
} |
| 52 |
for name, namer := range c.Namers { |
| 53 |
sw.funcMap[name] = namer.Name |
| 54 |
} |
| 55 |
return sw |
| 56 |
} |
| 57 |
|
| 58 |
// Do parses format and runs args through it. You can have arbitrary logic in |
| 59 |
// the format (see the text/template documentation), but consider running many |
| 60 |
// short templates with ordinary go logic in between--this may be more |
| 61 |
// readable. Do is chainable. Any error causes every other call to do to be |
| 62 |
// ignored, and the error will be returned by Error(). So you can check it just |
| 63 |
// once, at the end of your function. |
| 64 |
// |
| 65 |
// 'args' can be quite literally anything; read the text/template documentation |
| 66 |
// for details. Maps and structs work particularly nicely. Conveniently, the |
| 67 |
// types package is designed to have structs that are easily referencable from |
| 68 |
// the template language. |
| 69 |
// |
| 70 |
// Example: |
| 71 |
// |
| 72 |
// sw := generator.NewSnippetWriter(outBuffer, context, "$", "$") |
| 73 |
// sw.Do(`The public type name is: $.type|public$`, map[string]interface{}{"type": t}) |
| 74 |
// return sw.Error() |
| 75 |
// |
| 76 |
// Where: |
| 77 |
// - "$" starts a template directive |
| 78 |
// - "." references the entire thing passed as args |
| 79 |
// - "type" therefore sees a map and looks up the key "type" |
| 80 |
// - "|" means "pass the thing on the left to the thing on the right" |
| 81 |
// - "public" is the name of a naming system, so the SnippetWriter has given |
| 82 |
// the template a function called "public" that takes a *types.Type and |
| 83 |
// returns the naming system's name. E.g., if the type is "string" this might |
| 84 |
// return "String". |
| 85 |
// - the second "$" ends the template directive. |
| 86 |
// |
| 87 |
// The map is actually not necessary. The below does the same thing: |
| 88 |
// |
| 89 |
// sw.Do(`The public type name is: $.|public$`, t) |
| 90 |
// |
| 91 |
// You may or may not find it more readable to use the map with a descriptive |
| 92 |
// key, but if you want to pass more than one arg, the map or a custom struct |
| 93 |
// becomes a requirement. You can do arbitrary logic inside these templates, |
| 94 |
// but you should consider doing the logic in go and stitching them together |
| 95 |
// for the sake of your readers. |
| 96 |
// |
| 97 |
// TODO: Change Do() to optionally take a list of pairs of parameters (key, value) |
| 98 |
// and have it construct a combined map with that and args. |
| 99 |
func (s *SnippetWriter) Do(format string, args interface{}) *SnippetWriter { |
| 100 |
if s.err != nil { |
| 101 |
return s |
| 102 |
} |
| 103 |
// Name the template by source file:line so it can be found when |
| 104 |
// there's an error. |
| 105 |
_, file, line, _ := runtime.Caller(1) |
| 106 |
tmpl, err := template. |
| 107 |
New(fmt.Sprintf("%s:%d", file, line)). |
| 108 |
Delims(s.left, s.right). |
| 109 |
Funcs(s.funcMap). |
| 110 |
Parse(format) |
| 111 |
if err != nil { |
| 112 |
s.err = err |
| 113 |
return s |
| 114 |
} |
| 115 |
err = tmpl.Execute(s.w, args) |
| 116 |
if err != nil { |
| 117 |
s.err = err |
| 118 |
} |
| 119 |
return s |
| 120 |
} |
| 121 |
|
| 122 |
// Args exists to make it convenient to construct arguments for |
| 123 |
// SnippetWriter.Do. |
| 124 |
type Args map[interface{}]interface{} |
| 125 |
|
| 126 |
// With makes a copy of a and adds the given key, value pair. If key overlaps, |
| 127 |
// the new value wins. |
| 128 |
func (a Args) With(key, value interface{}) Args { |
| 129 |
result := Args{} |
| 130 |
for k, v := range a { |
| 131 |
result[k] = v |
| 132 |
} |
| 133 |
result[key] = value |
| 134 |
return result |
| 135 |
} |
| 136 |
|
| 137 |
// WithArgs makes a copy of a and adds the given arguments. If any keys |
| 138 |
// overlap, the values from rhs win. |
| 139 |
func (a Args) WithArgs(rhs Args) Args { |
| 140 |
result := Args{} |
| 141 |
for k, v := range a { |
| 142 |
result[k] = v |
| 143 |
} |
| 144 |
for k, v := range rhs { |
| 145 |
result[k] = v |
| 146 |
} |
| 147 |
return result |
| 148 |
} |
| 149 |
|
| 150 |
func (s *SnippetWriter) Out() io.Writer { |
| 151 |
return s.w |
| 152 |
} |
| 153 |
|
| 154 |
// Error returns any encountered error. |
| 155 |
func (s *SnippetWriter) Error() error { |
| 156 |
return s.err |
| 157 |
} |
| 158 |
|
| 159 |
// Dup creates an exact duplicate SnippetWriter with a different io.Writer. |
| 160 |
func (s *SnippetWriter) Dup(w io.Writer) *SnippetWriter { |
| 161 |
ret := *s |
| 162 |
ret.w = w |
| 163 |
return &ret |
| 164 |
} |
| 165 |
|
| 166 |
// Append adds the contents of the io.Reader to this SnippetWriter's buffer. |
| 167 |
func (s *SnippetWriter) Append(r io.Reader) error { |
| 168 |
// The behavior of Do() is to ignore all future calls if there's an error, |
| 169 |
// assuming the top-level caller will check Error(). This method is |
| 170 |
// effectively a fancy Do(), so keep the same semantic. |
| 171 |
if s.err != nil { |
| 172 |
return nil |
| 173 |
} |
| 174 |
_, err := io.Copy(s.w, r) |
| 175 |
return err |
| 176 |
} |
| 177 |
|
| 178 |
// Merge adds the contents of the io.Reader to this SnippetWriter's buffer and |
| 179 |
// sets this SnippetWriter's error to the other's, if needed. |
| 180 |
func (s *SnippetWriter) Merge(r io.Reader, other *SnippetWriter) error { |
| 181 |
if s.err != nil { |
| 182 |
return nil |
| 183 |
} |
| 184 |
if other.err != nil { |
| 185 |
s.err = other.err |
| 186 |
} |
| 187 |
return s.Append(r) |
| 188 |
} |