|
| 1 | +// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers |
| 2 | +// SPDX-License-Identifier: Apache-2.0 |
| 3 | + |
| 4 | +package parsers |
| 5 | + |
| 6 | +import ( |
| 7 | + "strings" |
| 8 | + "unicode" |
| 9 | + "unicode/utf8" |
| 10 | +) |
| 11 | + |
| 12 | +// Scanning one comment line for an annotation. |
| 13 | +// |
| 14 | +// These are string searches for what were regular expressions until this file replaced them. The |
| 15 | +// rules they enforce are unchanged and are stated on each function; the reason for spelling them |
| 16 | +// out is that they are rules about where a keyword sits on a line, and reading them off a |
| 17 | +// character walk is easier than reading them off a pattern. |
| 18 | + |
| 19 | +// annotationKeyword prefixes every annotation. |
| 20 | +const annotationKeyword = "swagger:" |
| 21 | + |
| 22 | +// isCommentNoise reports whether r may precede an annotation as leading noise: a Unicode space |
| 23 | +// separator, a tab, or one of the comment / list decorations `/`, `*`, `-`. |
| 24 | +func isCommentNoise(r rune) bool { |
| 25 | + switch r { |
| 26 | + case '\t', '/', '*', '-': |
| 27 | + return true |
| 28 | + default: |
| 29 | + return unicode.Is(unicode.Zs, r) |
| 30 | + } |
| 31 | +} |
| 32 | + |
| 33 | +// isSpaceSeparator reports whether r is a Unicode space separator (which a tab is not). |
| 34 | +func isSpaceSeparator(r rune) bool { return unicode.Is(unicode.Zs, r) } |
| 35 | + |
| 36 | +// isNameRune reports whether r may appear in an annotation keyword or in an override name after |
| 37 | +// its first character: a letter, a digit, a dash or a connector (`_`). |
| 38 | +func isNameRune(r rune) bool { |
| 39 | + return unicode.IsLetter(r) || unicode.IsNumber(r) || |
| 40 | + unicode.Is(unicode.Pd, r) || unicode.Is(unicode.Pc, r) |
| 41 | +} |
| 42 | + |
| 43 | +// isASCIISpace reports whether r is one of the characters a regexp `\S` excludes. |
| 44 | +// |
| 45 | +// Deliberately not unicode.IsSpace: the argument matchers below reject a line whose argument starts |
| 46 | +// with one of exactly these, and widening that would classify lines the previous rule did not. |
| 47 | +func isASCIISpace(r rune) bool { |
| 48 | + switch r { |
| 49 | + case '\t', '\n', '\f', '\r', ' ': |
| 50 | + return true |
| 51 | + default: |
| 52 | + return false |
| 53 | + } |
| 54 | +} |
| 55 | + |
| 56 | +// afterCommentNoise returns the offset at which an annotation would have to start on line. |
| 57 | +// |
| 58 | +// It skips the leading run of comment noise, then AT MOST ONE markdown table pipe, then a further |
| 59 | +// run of space separators. |
| 60 | +// |
| 61 | +// Annotations must START the comment line: any prose before the keyword disqualifies the line, so |
| 62 | +// an annotation mentioned mid-sentence is not classified as one. The sole exception is |
| 63 | +// `swagger:route`, which may follow a single godoc identifier — that allowance lives in the path |
| 64 | +// annotation matchers (see rxRoutePrefix), not here. |
| 65 | +func afterCommentNoise(line string) int { |
| 66 | + i := skipRunes(line, 0, isCommentNoise) |
| 67 | + if i < len(line) && line[i] == '|' { |
| 68 | + i = skipRunes(line, i+1, isSpaceSeparator) |
| 69 | + } |
| 70 | + |
| 71 | + return i |
| 72 | +} |
| 73 | + |
| 74 | +// skipRunes returns the offset of the first rune at or after i that keep rejects. |
| 75 | +func skipRunes(s string, i int, keep func(rune) bool) int { |
| 76 | + for i < len(s) { |
| 77 | + r, size := utf8.DecodeRuneInString(s[i:]) |
| 78 | + if !keep(r) { |
| 79 | + return i |
| 80 | + } |
| 81 | + i += size |
| 82 | + } |
| 83 | + |
| 84 | + return i |
| 85 | +} |
| 86 | + |
| 87 | +// annotationTail returns what follows `swagger:<keyword>` when line starts with that annotation, |
| 88 | +// leading comment noise aside. |
| 89 | +func annotationTail(line, keyword string) (string, bool) { |
| 90 | + rest := line[afterCommentNoise(line):] |
| 91 | + marker := annotationKeyword + keyword |
| 92 | + if !strings.HasPrefix(rest, marker) { |
| 93 | + return "", false |
| 94 | + } |
| 95 | + |
| 96 | + return rest[len(marker):], true |
| 97 | +} |
| 98 | + |
| 99 | +// overrideName reads the OPTIONAL name argument of a single-name struct marker on line. |
| 100 | +// |
| 101 | +// The shape is: the marker starting the line, space separators, an optional name, an optional |
| 102 | +// trailing period (a marker written as the last word of a godoc sentence), and nothing else. A |
| 103 | +// name is a letter followed by at least one further name character — a single letter is not a |
| 104 | +// name, and neither is anything package-qualified, which is what makes MalformedModelName / |
| 105 | +// MalformedResponseName able to report it instead of the marker being dropped in silence. |
| 106 | +// |
| 107 | +// wildcard admits `*` as a name, the shared-namespace synonym for the bare form that |
| 108 | +// `swagger:response` accepts. |
| 109 | +// |
| 110 | +// Returns ("", true) for a bare marker, so callers can tell "no marker" from "marker, no argument". |
| 111 | +func overrideName(line, keyword string, wildcard bool) (string, bool) { |
| 112 | + tail, ok := annotationTail(line, keyword) |
| 113 | + if !ok { |
| 114 | + return "", false |
| 115 | + } |
| 116 | + |
| 117 | + arg := strings.TrimSuffix(strings.TrimLeftFunc(tail, isSpaceSeparator), ".") |
| 118 | + switch { |
| 119 | + case arg == "": |
| 120 | + return "", true // bare marker |
| 121 | + case wildcard && arg == "*": |
| 122 | + return arg, true |
| 123 | + case isOverrideName(arg): |
| 124 | + return arg, true |
| 125 | + default: |
| 126 | + return "", false |
| 127 | + } |
| 128 | +} |
| 129 | + |
| 130 | +// isOverrideName reports whether s is a plain identifier-shaped name: a letter, then at least one |
| 131 | +// further name character. |
| 132 | +func isOverrideName(s string) bool { |
| 133 | + first, size := utf8.DecodeRuneInString(s) |
| 134 | + if !unicode.IsLetter(first) { |
| 135 | + return false |
| 136 | + } |
| 137 | + rest := s[size:] |
| 138 | + if rest == "" { |
| 139 | + return false |
| 140 | + } |
| 141 | + |
| 142 | + return skipRunes(rest, 0, isNameRune) == len(rest) |
| 143 | +} |
| 144 | + |
| 145 | +// annotationArgument reads the raw, unvalidated argument of a marker on line. |
| 146 | +// |
| 147 | +// The shape is: the marker starting the line, AT LEAST ONE space separator, then a non-empty |
| 148 | +// argument that does not itself begin with a whitespace character, with trailing space separators |
| 149 | +// dropped. The argument's content is not inspected — `swagger:parameters` hands it to the grammar, |
| 150 | +// which diagnoses a malformed one rather than skipping it here, and the malformed-name detectors |
| 151 | +// compare it against what overrideName accepts. |
| 152 | +// |
| 153 | +// One case reads differently from the expression this replaced, deliberately: that pattern could |
| 154 | +// start the argument ON a space separator. Its `\S` excludes the ASCII whitespace characters and |
| 155 | +// nothing else, so a non-breaking space passed it, and when what followed the separator run was a |
| 156 | +// tab (or nothing at all) the pattern gave a separator back and began the argument there. The |
| 157 | +// argument here begins where the separators end, or there is none. Nothing an author would write |
| 158 | +// reaches the difference. |
| 159 | +func annotationArgument(line, keyword string) (string, bool) { |
| 160 | + tail, ok := annotationTail(line, keyword) |
| 161 | + if !ok { |
| 162 | + return "", false |
| 163 | + } |
| 164 | + |
| 165 | + arg := strings.TrimLeftFunc(tail, isSpaceSeparator) |
| 166 | + if len(arg) == len(tail) { |
| 167 | + return "", false // no separator between the marker and its argument |
| 168 | + } |
| 169 | + |
| 170 | + arg = strings.TrimRightFunc(arg, isSpaceSeparator) |
| 171 | + if arg == "" { |
| 172 | + return "", false |
| 173 | + } |
| 174 | + if first, _ := utf8.DecodeRuneInString(arg); isASCIISpace(first) { |
| 175 | + return "", false |
| 176 | + } |
| 177 | + |
| 178 | + return arg, true |
| 179 | +} |
| 180 | + |
| 181 | +// annotationName returns the keyword of the first `swagger:<name>` marker on line. |
| 182 | +// |
| 183 | +// Deliberately loose — this is the classification search, not a gate: the marker may sit anywhere |
| 184 | +// on the line provided it follows start-of-line, whitespace or a `/`. Do NOT use it as a block |
| 185 | +// terminator; it fires on mid-prose mentions and would truncate descriptions. |
| 186 | +func annotationName(line string) (string, bool) { |
| 187 | + for from := 0; from < len(line); { |
| 188 | + at := strings.Index(line[from:], annotationKeyword) |
| 189 | + if at < 0 { |
| 190 | + return "", false |
| 191 | + } |
| 192 | + at += from |
| 193 | + |
| 194 | + if at == 0 || isLooseBoundary(line[at-1]) { |
| 195 | + tail := line[at+len(annotationKeyword):] |
| 196 | + if end := skipRunes(tail, 0, isNameRune); end > 0 { |
| 197 | + return tail[:end], true |
| 198 | + } |
| 199 | + } |
| 200 | + from = at + 1 |
| 201 | + } |
| 202 | + |
| 203 | + return "", false |
| 204 | +} |
| 205 | + |
| 206 | +// isLooseBoundary reports whether b may precede the keyword in the classification search. |
| 207 | +// |
| 208 | +// Byte-wise rather than rune-wise on purpose: every character it admits is ASCII, and a UTF-8 |
| 209 | +// continuation byte can never be one of them. |
| 210 | +func isLooseBoundary(b byte) bool { |
| 211 | + switch b { |
| 212 | + case '\t', '\n', '\f', '\r', ' ', '/': |
| 213 | + return true |
| 214 | + default: |
| 215 | + return false |
| 216 | + } |
| 217 | +} |
0 commit comments