Debian Codegraph @

v2/generator/snippet_writer.go

raw
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 }