Debian Codegraph @

v2/comments.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 gengo
18
19 import (
20 "bytes"
21 "fmt"
22 "strings"
23 "unicode"
24 )
25
26 // ExtractCommentTags parses comments for lines of the form:
27 //
28 // 'marker' + "key=value".
29 //
30 // Values are optional; "" is the default. A tag can be specified more than
31 // one time and all values are returned. If the resulting map has an entry for
32 // a key, the value (a slice) is guaranteed to have at least 1 element.
33 //
34 // Example: if you pass "+" for 'marker', and the following lines are in
35 // the comments:
36 //
37 // +foo=value1
38 // +bar
39 // +foo=value2
40 // +baz="qux"
41 //
42 // Then this function will return:
43 //
44 // map[string][]string{"foo":{"value1, "value2"}, "bar": {""}, "baz": {`"qux"`}}
45 //
46 // Deprecated: Use ExtractFunctionStyleCommentTags.
47 func ExtractCommentTags(marker string, lines []string) map[string][]string {
48 out := map[string][]string{}
49 for _, line := range lines {
50 line = strings.Trim(line, " ")
51 if len(line) == 0 {
52 continue
53 }
54 if !strings.HasPrefix(line, marker) {
55 continue
56 }
57 kv := strings.SplitN(line[len(marker):], "=", 2)
58 if len(kv) == 2 {
59 out[kv[0]] = append(out[kv[0]], kv[1])
60 } else if len(kv) == 1 {
61 out[kv[0]] = append(out[kv[0]], "")
62 }
63 }
64 return out
65 }
66
67 // ExtractSingleBoolCommentTag parses comments for lines of the form:
68 //
69 // 'marker' + "key=value1"
70 //
71 // If the tag is not found, the default value is returned. Values are asserted
72 // to be boolean ("true" or "false"), and any other value will cause an error
73 // to be returned. If the key has multiple values, the first one will be used.
74 func ExtractSingleBoolCommentTag(marker string, key string, defaultVal bool, lines []string) (bool, error) {
75 tags, err := ExtractFunctionStyleCommentTags(marker, []string{key}, lines)
76 if err != nil {
77 return false, err
78 }
79 values := tags[key]
80 if values == nil {
81 return defaultVal, nil
82 }
83 if values[0].Value == "true" {
84 return true, nil
85 }
86 if values[0].Value == "false" {
87 return false, nil
88 }
89 return false, fmt.Errorf("tag value for %q is not boolean: %q", key, values[0])
90 }
91
92 // ExtractFunctionStyleCommentTags parses comments for special metadata tags. The
93 // marker argument should be unique enough to identify the tags needed, and
94 // should not be a marker for tags you don't want, or else the caller takes
95 // responsibility for making that distinction.
96 //
97 // The tagNames argument is a list of specific tags being extracted. If this is
98 // nil or empty, all lines which match the marker are considered. If this is
99 // specified, only lines with begin with marker + one of the tags will be
100 // considered. This is useful when a common marker is used which may match
101 // lines which fail this syntax (e.g. which predate this definition).
102 //
103 // This function looks for input lines of the following forms:
104 // - 'marker' + "key=value"
105 // - 'marker' + "key()=value"
106 // - 'marker' + "key(arg)=value"
107 //
108 // The arg is optional. If not specified (either as "key=value" or as
109 // "key()=value"), the resulting Tag will have an empty Args list.
110 //
111 // The value is optional. If not specified, the resulting Tag will have "" as
112 // the value.
113 //
114 // Tag comment-lines may have a trailing end-of-line comment.
115 //
116 // The map returned here is keyed by the Tag's name without args.
117 //
118 // A tag can be specified more than one time and all values are returned. If
119 // the resulting map has an entry for a key, the value (a slice) is guaranteed
120 // to have at least 1 element.
121 //
122 // Example: if you pass "+" as the marker, and the following lines are in
123 // the comments:
124 //
125 // +foo=val1 // foo
126 // +bar
127 // +foo=val2 // also foo
128 // +baz="qux"
129 // +foo(arg) // still foo
130 //
131 // Then this function will return:
132 //
133 // map[string][]Tag{
134 // "foo": []Tag{{
135 // Name: "foo",
136 // Args: nil,
137 // Value: "val1",
138 // }, {
139 // Name: "foo",
140 // Args: nil,
141 // Value: "val2",
142 // }, {
143 // Name: "foo",
144 // Args: []string{"arg"},
145 // Value: "",
146 // }, {
147 // Name: "bar",
148 // Args: nil,
149 // Value: ""
150 // }, {
151 // Name: "baz",
152 // Args: nil,
153 // Value: "\"qux\""
154 // }}
155 //
156 // This function should be preferred instead of ExtractCommentTags.
157 func ExtractFunctionStyleCommentTags(marker string, tagNames []string, lines []string) (map[string][]Tag, error) {
158 stripTrailingComment := func(in string) string {
159 parts := strings.SplitN(in, "//", 2)
160 return strings.TrimSpace(parts[0])
161 }
162
163 out := map[string][]Tag{}
164 for _, line := range lines {
165 line = strings.TrimSpace(line)
166 if len(line) == 0 {
167 continue
168 }
169 if !strings.HasPrefix(line, marker) {
170 continue
171 }
172 line = stripTrailingComment(line)
173 kv := strings.SplitN(line[len(marker):], "=", 2)
174 key := kv[0]
175 val := ""
176 if len(kv) == 2 {
177 val = kv[1]
178 }
179
180 tag := Tag{}
181 if name, args, err := parseTagKey(key, tagNames); err != nil {
182 return nil, err
183 } else if name != "" {
184 tag.Name, tag.Args = name, args
185 tag.Value = val
186 out[tag.Name] = append(out[tag.Name], tag)
187 }
188 }
189 return out, nil
190 }
191
192 // Tag represents a single comment tag.
193 type Tag struct {
194 // Name is the name of the tag with no arguments.
195 Name string
196 // Args is a list of optional arguments to the tag.
197 Args []string
198 // Value is the value of the tag.
199 Value string
200 }
201
202 func (t Tag) String() string {
203 buf := bytes.Buffer{}
204 buf.WriteString(t.Name)
205 if len(t.Args) > 0 {
206 buf.WriteString("(")
207 for i, a := range t.Args {
208 if i > 0 {
209 buf.WriteString(", ")
210 }
211 buf.WriteString(a)
212 }
213 buf.WriteString(")")
214 }
215 return buf.String()
216 }
217
218 // parseTagKey parses the key part of an extended comment tag, including
219 // optional arguments. The input is assumed to be the entire text of the
220 // original input after the marker, up to the '=' or end-of-line.
221 //
222 // The tags argument is an optional list of tag names to match. If it is nil or
223 // empty, all tags match.
224 //
225 // At the moment, arguments are very strictly formatted (see parseTagArgs) and
226 // whitespace is not allowed.
227 //
228 // This function returns the key name and arguments, unless tagNames was
229 // specified and the input did not match, in which case it returns "".
230 func parseTagKey(input string, tagNames []string) (string, []string, error) {
231 parts := strings.SplitN(input, "(", 2)
232 key := parts[0]
233
234 if len(tagNames) > 0 {
235 found := false
236 for _, tn := range tagNames {
237 if key == tn {
238 found = true
239 break
240 }
241 }
242 if !found {
243 return "", nil, nil
244 }
245 }
246
247 var args []string
248 if len(parts) == 2 {
249 if ret, err := parseTagArgs(parts[1]); err != nil {
250 return key, nil, fmt.Errorf("failed to parse tag args: %v", err)
251 } else {
252 args = ret
253 }
254 }
255 return key, args, nil
256 }
257
258 // parseTagArgs parses the arguments part of an extended comment tag. The input
259 // is assumed to be the entire text of the original input after the opening
260 // '(', including the trailing ')'.
261 //
262 // At the moment this assumes that the entire string between the opening '('
263 // and the trailing ')' is a single Go-style identifier token, but in the
264 // future could be extended to have multiple arguments with actual syntax. The
265 // single token may consist only of letters and digits. Whitespace is not
266 // allowed.
267 func parseTagArgs(input string) ([]string, error) {
268 // This is really dumb, but should be extendable to a "real" parser if
269 // needed.
270 runes := []rune(input)
271 for i, r := range runes {
272 if unicode.IsLetter(r) || unicode.IsDigit(r) {
273 continue
274 }
275 if r == ',' {
276 return nil, fmt.Errorf("multiple arguments are not supported: %q", input)
277 }
278 if r == ')' {
279 if i != len(runes)-1 {
280 return nil, fmt.Errorf("unexpected characters after ')': %q", string(runes[i:]))
281 }
282 if i == 0 {
283 return nil, nil
284 }
285 return []string{string(runes[:i])}, nil
286 }
287 return nil, fmt.Errorf("unsupported character: %q", string(r))
288 }
289 return nil, fmt.Errorf("no closing ')' found: %q", input)
290 }