This repository was archived by the owner on Nov 13, 2026. It is now read-only.
Repository navigation
Expand file tree
/
Copy pathparse.go
More file actions
399 lines (363 loc) · 14.4 KB
/
Copy pathparse.go
File metadata and controls
399 lines (363 loc) · 14.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
package dotenv
import (
"regexp"
"strings"
)
// ds:def id=keyclass-46et9zsb owner=@maintainers stability=stable
// keyClass is the set of characters a variable name may contain — Docker
// Compose's charset (compose-go accepts letters, digits, '_', '.', '-', '[',
// ']'), which is a superset of Node dotenv's and godotenv's `[\w.-]`. Matching
// the widest mainstream implementation means a file any of those tools reads
// loses no keys here: dotted keys (`spring.datasource.url`), hyphenated keys
// (`MY-SERVICE-TOKEN`), digit-first keys (`2FA_SECRET`), and bracketed keys
// (`SERVICES[0]`) are all real pairs, not unrecognised lines.
//
// Deliberately NOT the interpolation-name charset: what `${VAR}` may reference
// is a separate, narrower grammar owned by expand.go. Widening one must not
// widen the other.
//
// A key containing anything OUTSIDE this class (`HAS KEY=v`, `K!=v`) is not an
// error here, unlike compose-go which refuses the whole file: the line becomes
// KindOther and survives verbatim. See KindOther for why an editor must prefer
// preservation over rejection.
const keyClass = `[A-Za-z0-9_.\-\[\]]`
// ds:def id=pairre-v3u356bt owner=@maintainers stability=stable
// pairRe matches the head of a KEY=value (or Compose/Node-style KEY: value)
// line.
//
// The whole prefix — optional `export`, spacing, key, spacing, and the
// delimiter — is captured as one group so a value edit can put it back exactly
// as the author wrote it, colon and all. Reconstructing it from parts would
// normalise somebody's chosen spacing (or delimiter) into a diff they did not
// ask for.
//
// Both `=` and `:` are accepted because both are in the Compose env-file
// grammar and in Node dotenv's LINE regex; a file written for either tool must
// parse to the same set of keys here. No whitespace is required after the
// colon — Compose requires none, and following Node's stricter `: ` form
// instead would make this package and Compose disagree about the same bytes.
//
// Known consequence, shared with compose-go: a bare URL line
// (`http://example.com`) parses as key `http`, value `//example.com`. That
// looks surprising but is Compose's own reading, and the line still
// round-trips verbatim — do NOT special-case it. Pinned by
// TestColonDelimiter. The same line inside a comment is prose, not a disabled
// pair: see colonProse.
var pairRe = regexp.MustCompile(`^((?:export[ \t]+)?[ \t]*(` + keyClass + `+)[ \t]*[=:])(.*)$`)
// inheritedRe matches a name-only line: `HOME`, or `export HOME` — no
// delimiter, no value. In the Compose env-file grammar this declares the
// variable as INHERITED from the process environment rather than defined by
// the file.
//
// This package recognises the declaration (KindInherited) but never resolves
// it — reading os.Environ is exactly what this package promises not to do.
// See KindInherited for the contract.
var inheritedRe = regexp.MustCompile(`^[ \t]*(?:export[ \t]+)?(` + keyClass + `+)[ \t]*$`)
// ds:def id=inlinecommentre-5km4985g owner=@maintainers stability=stable
// inlineCommentRe finds where an unquoted value ends: at whitespace followed by
// a #. Requiring the whitespace is deliberate — a # inside a value such as
// PASSWORD=a#b is part of the password, not the start of a comment.
var inlineCommentRe = regexp.MustCompile(`[ \t]#`)
// parse ingests whole-file content. Separate from Load so parsing is testable
// without a filesystem, and so Parse can reuse it.
func (f *File) parse(content string) {
// crlf records the DOMINANT style, used only for lines this package writes
// later. Existing lines keep their own terminator verbatim: a file with
// mixed endings must round-trip as mixed, not be silently normalised to one
// style — that would be a whole-file diff nobody asked for.
f.crlf = strings.Contains(content, "\r\n")
f.trailingNewline = strings.HasSuffix(content, "\n") || content == ""
lines := strings.Split(content, "\n")
if f.trailingNewline && len(lines) > 0 {
// Split leaves an empty tail element after a final terminator; keeping
// it would invent a blank line that was never in the file.
lines = lines[:len(lines)-1]
}
// observe fires EntryObserver for one finished entry. Hoisted so every
// append site reports, rather than three of them remembering to.
//
// Each observer gets its own copy of the entry, never the parsed one: an
// observer handed the live *Entry could rewrite Raw or Value and so change
// what Render and Save produce, or keep the pointer and do it later. The
// copy is only made when observers are installed, so a parse without them
// pays nothing.
observe := func(e *Entry) {
for _, o := range f.opts.entryObs {
o.ObserveEntry(e.clone())
}
}
for i := 0; i < len(lines); i++ {
// raw keeps any trailing \r so Render reproduces the exact bytes;
// everything downstream parses the trimmed form.
raw := lines[i]
line := strings.TrimSuffix(raw, "\r")
trimmed := strings.TrimSpace(line)
switch {
case trimmed == "":
e := &Entry{Kind: KindBlank, Raw: []string{raw}, attached: true}
f.entries = append(f.entries, e)
observe(e)
case strings.HasPrefix(trimmed, "#"):
e := f.parseComment(line, raw)
f.entries = append(f.entries, e)
observe(e)
default:
m := pairRe.FindStringSubmatch(line)
if m == nil {
// Not a pair. A bare name is a Compose "inherited" declaration
// (see KindInherited); anything else is unrecognised and kept
// verbatim.
if im := inheritedRe.FindStringSubmatch(line); im != nil {
inh := &Entry{Kind: KindInherited, Key: im[1], Raw: []string{raw}, attached: true}
f.entries = append(f.entries, inh)
observe(inh)
continue
}
other := &Entry{Kind: KindOther, Raw: []string{raw}, attached: true}
f.entries = append(f.entries, other)
observe(other)
continue
}
e := &Entry{Kind: KindPair, Key: m[2], prefix: m[1], Raw: []string{raw}, attached: true}
// A quoted value may run past this physical line; whatever it
// consumes joins this entry's Raw so the block edits as one unit.
// The lookahead is passed UNTRIMMED and each line is trimmed only
// if a multi-line value actually consumes it. Pre-trimming copied
// the whole remaining file for every pair, which made parsing
// quadratic: a 5 MB file took 23 seconds.
consumed := parseValue(m[3], lines[i+1:], e, f.opts)
for range consumed {
i++
e.Raw = append(e.Raw, lines[i])
}
f.entries = append(f.entries, e)
observe(e)
}
}
}
// parseComment classifies a comment line, recognising a commented-out setting as
// a KindDisabledPair rather than prose.
//
// Without this, "# DB_USER=admin" would mean something different depending on
// who commented it: Unset records the key, a human editor does not. Same text,
// same intent, so they must parse the same way.
func (f *File) parseComment(line, raw string) *Entry {
marker := strings.Index(line, "#")
body := line[marker+1:]
// The recorded prefix starts AT the marker, not at the start of the line:
// Restore must remove the comment marker and the spaces that follow it,
// while leaving any indentation the line already had. Stripping from column
// zero would silently re-align an indented setting.
spaces := len(body) - len(strings.TrimLeft(body, " \t"))
prefix := line[marker : marker+1+spaces]
body = body[spaces:]
m := pairRe.FindStringSubmatch(body)
if m == nil || !valueEndsOnThisLine(m[3]) || colonProse(m[1], m[3]) {
return &Entry{Kind: KindComment, Raw: []string{raw}, attached: true}
}
e := &Entry{
Kind: KindDisabledPair,
Key: m[2],
prefix: m[1],
commentPrefix: prefix,
Raw: []string{raw},
attached: true,
}
parseValue(m[3], nil, e, f.opts)
return e
}
// ds:def id=colonprose-cthvdumn owner=@maintainers stability=stable
// colonProse reports whether a commented `KEY: value` line is prose rather than
// a disabled setting. head is pairRe's prefix group (ending in the delimiter)
// and rhs is everything after the delimiter.
//
// Only the `:` form is judged, and only inside a comment. An active line keeps
// Compose's reading whatever it says, and the `=` form is left alone: a colon
// is ordinary punctuation in prose ("# Note: rotate monthly") and in URLs
// ("# http://example.com"), where `=` rarely is, so treating every commented
// colon line as a setting made Restore able to activate a sentence.
//
// The rule: a commented colon assignment is a disabled pair only when its
// value is one token — quoted, or unquoted with no space or tab before an
// inline comment — and does not begin with `//`, the tail of a URL scheme.
// That keeps Unset round-tripping through a reload for every colon pair whose
// value is quoted or a single word, which is what Unset produces for nearly
// every real setting. The trade-off, pinned by TestCommentColon_TradeOff: an
// unquoted colon value WITH a space ("KEY: two words") cannot be told apart
// from prose, so after Unset, Save and a reload it is a plain comment. A
// single-word heading ("# Owner: alice") still reads as a disabled pair, for
// the same reason in reverse.
func colonProse(head, rhs string) bool {
if !strings.HasSuffix(head, ":") {
return false
}
if strings.HasPrefix(rhs, "//") {
return true
}
v := strings.TrimLeft(rhs, " \t")
if v == "" || strings.ContainsAny(v[:1], "\"'`") {
// Empty, or quoted: valueEndsOnThisLine has already required the quote
// to close, so the value is one token however many spaces it holds.
return false
}
if loc := inlineCommentRe.FindStringIndex(v); loc != nil {
v = v[:loc[0]]
}
return strings.ContainsAny(strings.TrimRight(v, " \t"), " \t")
}
// valueEndsOnThisLine reports whether a quoted value closes on the line it opens.
//
// A commented-out multi-line block cannot be reassembled — each of its lines is
// a separate comment entry — so only a self-contained assignment is treated as a
// disabled pair. Otherwise "# KEY=\"one" would become a pair whose value is an
// unterminated quote.
func valueEndsOnThisLine(rhs string) bool {
v := strings.TrimLeft(rhs, " \t")
switch {
case strings.HasPrefix(v, `"`):
_, _, closed := scanDoubleQuoted(v[1:], EscapeCompose)
return closed
case strings.HasPrefix(v, "'"):
return strings.IndexByte(v[1:], '\'') >= 0
case strings.HasPrefix(v, "`"):
return strings.IndexByte(v[1:], '`') >= 0
default:
return true
}
}
// trimEOL strips a CRLF terminator from one lookahead line, so a multi-line
// value's decoded content never carries a stray \r.
func trimEOL(line string) string {
return strings.TrimSuffix(line, "\r")
}
// parseValue decodes the right-hand side of a pair into e.Value and
// e.inlineComment.
//
// rest holds the FOLLOWING physical lines; the return value is how many of them
// a multi-line quoted value consumed.
func parseValue(rhs string, rest []string, e *Entry, opts options) int {
s := strings.TrimLeft(rhs, " \t")
switch {
case strings.HasPrefix(s, `"`):
e.quote = quoteDouble
return parseDoubleQuoted(s[1:], rest, e, opts)
case strings.HasPrefix(s, `'`):
e.quote = quoteSingle
return parseLiteralQuoted(s[1:], rest, e, '\'')
case strings.HasPrefix(s, "`"):
e.quote = quoteBacktick
return parseLiteralQuoted(s[1:], rest, e, '`')
default:
e.quote = quoteNone
return parseBare(s, e)
}
}
// parseDoubleQuoted handles a value opening with a double quote, spanning lines
// until the quote closes.
func parseDoubleQuoted(s string, rest []string, e *Entry, opts options) int {
value, remainder, closed := scanDoubleQuoted(s, opts.escapes)
if closed {
e.Value = value
e.inlineComment = remainder
return 0
}
parts := []string{value}
for n, raw := range rest {
line := trimEOL(raw)
v, rem, ok := scanDoubleQuoted(line, opts.escapes)
parts = append(parts, v)
if ok {
e.Value = strings.Join(parts, "\n")
e.inlineComment = rem
return n + 1
}
}
// Unterminated at EOF. Everything consumed becomes the value; preservation
// still holds because Raw is verbatim, so rendering an untouched file is
// unaffected by the malformed quote.
e.Value = strings.Join(parts, "\n")
return len(rest)
}
// parseLiteralQuoted handles a fully literal value delimited by quote — single
// quotes or backticks. No escape processing at all, so the closing delimiter is
// simply the next occurrence of it, and the value may span lines.
func parseLiteralQuoted(s string, rest []string, e *Entry, quote byte) int {
if idx := strings.IndexByte(s, quote); idx >= 0 {
e.Value = s[:idx]
e.inlineComment = s[idx+1:]
return 0
}
parts := []string{s}
for n, raw := range rest {
line := trimEOL(raw)
if idx := strings.IndexByte(line, quote); idx >= 0 {
parts = append(parts, line[:idx])
e.Value = strings.Join(parts, "\n")
e.inlineComment = line[idx+1:]
return n + 1
}
parts = append(parts, line)
}
e.Value = strings.Join(parts, "\n")
return len(rest)
}
// parseBare handles an unquoted value, which ends at an inline comment or at
// end of line, with trailing whitespace trimmed.
func parseBare(s string, e *Entry) int {
if loc := inlineCommentRe.FindStringIndex(s); loc != nil {
e.Value = strings.TrimRight(s[:loc[0]], " \t")
e.inlineComment = s[loc[0]:]
return 0
}
e.Value = strings.TrimRight(s, " \t")
return 0
}
// scanDoubleQuoted scans s — the content AFTER an opening double quote — for the
// closing unescaped quote.
//
// Returns the decoded value, whatever followed the closing quote, and whether
// the quote closed within s. Which backslash sequences are decoded depends on
// mode; see EscapeMode. An unrecognised sequence is always kept literally,
// backslash included, so a Windows path or a regex survives without the author
// doubling every separator.
func scanDoubleQuoted(s string, mode EscapeMode) (value, remainder string, closed bool) {
var b strings.Builder
for i := 0; i < len(s); i++ {
c := s[i]
if c == '\\' && i+1 < len(s) {
if decoded, ok := decodeEscape(s[i+1], mode); ok {
b.WriteString(decoded)
i++
continue
}
}
if c == '"' {
return b.String(), s[i+1:], true
}
b.WriteByte(c)
}
return b.String(), "", false
}
// ds:def id=decodeescape-w7neknhj owner=@maintainers stability=stable
// decodeEscape maps the character following a backslash to its replacement,
// reporting whether the sequence is recognised in this mode.
func decodeEscape(c byte, mode EscapeMode) (string, bool) {
switch c {
case '"':
return `"`, true
case '\\':
return `\`, true
}
if mode != EscapeExtended {
return "", false
}
switch c {
case 'n':
return "\n", true
case 'r':
return "\r", true
case 't':
return "\t", true
}
return "", false
}