podman

1
// Copyright 2018 The Go Authors. All rights reserved.
2
// Use of this source code is governed by a BSD-style
3
// license that can be found in the LICENSE file.
4

5
// Package semver implements comparison of semantic version strings.
6
// In this package, semantic version strings must begin with a leading "v",
7
// as in "v1.0.0".
8
//
9
// The general form of a semantic version string accepted by this package is
10
//
11
//	vMAJOR[.MINOR[.PATCH[-PRERELEASE][+BUILD]]]
12
//
13
// where square brackets indicate optional parts of the syntax;
14
// MAJOR, MINOR, and PATCH are decimal integers without extra leading zeros;
15
// PRERELEASE and BUILD are each a series of non-empty dot-separated identifiers
16
// using only alphanumeric characters and hyphens; and
17
// all-numeric PRERELEASE identifiers must not have leading zeros.
18
//
19
// This package follows Semantic Versioning 2.0.0 (see semver.org)
20
// with two exceptions. First, it requires the "v" prefix. Second, it recognizes
21
// vMAJOR and vMAJOR.MINOR (with no prerelease or build suffixes)
22
// as shorthands for vMAJOR.0.0 and vMAJOR.MINOR.0.
23
package semver
24

25
import "sort"
26

27
// parsed returns the parsed form of a semantic version string.
28
type parsed struct {
29
	major      string
30
	minor      string
31
	patch      string
32
	short      string
33
	prerelease string
34
	build      string
35
}
36

37
// IsValid reports whether v is a valid semantic version string.
38
func IsValid(v string) bool {
39
	_, ok := parse(v)
40
	return ok
41
}
42

43
// Canonical returns the canonical formatting of the semantic version v.
44
// It fills in any missing .MINOR or .PATCH and discards build metadata.
45
// Two semantic versions compare equal only if their canonical formattings
46
// are identical strings.
47
// The canonical invalid semantic version is the empty string.
48
func Canonical(v string) string {
49
	p, ok := parse(v)
50
	if !ok {
51
		return ""
52
	}
53
	if p.build != "" {
54
		return v[:len(v)-len(p.build)]
55
	}
56
	if p.short != "" {
57
		return v + p.short
58
	}
59
	return v
60
}
61

62
// Major returns the major version prefix of the semantic version v.
63
// For example, Major("v2.1.0") == "v2".
64
// If v is an invalid semantic version string, Major returns the empty string.
65
func Major(v string) string {
66
	pv, ok := parse(v)
67
	if !ok {
68
		return ""
69
	}
70
	return v[:1+len(pv.major)]
71
}
72

73
// MajorMinor returns the major.minor version prefix of the semantic version v.
74
// For example, MajorMinor("v2.1.0") == "v2.1".
75
// If v is an invalid semantic version string, MajorMinor returns the empty string.
76
func MajorMinor(v string) string {
77
	pv, ok := parse(v)
78
	if !ok {
79
		return ""
80
	}
81
	i := 1 + len(pv.major)
82
	if j := i + 1 + len(pv.minor); j <= len(v) && v[i] == '.' && v[i+1:j] == pv.minor {
83
		return v[:j]
84
	}
85
	return v[:i] + "." + pv.minor
86
}
87

88
// Prerelease returns the prerelease suffix of the semantic version v.
89
// For example, Prerelease("v2.1.0-pre+meta") == "-pre".
90
// If v is an invalid semantic version string, Prerelease returns the empty string.
91
func Prerelease(v string) string {
92
	pv, ok := parse(v)
93
	if !ok {
94
		return ""
95
	}
96
	return pv.prerelease
97
}
98

99
// Build returns the build suffix of the semantic version v.
100
// For example, Build("v2.1.0+meta") == "+meta".
101
// If v is an invalid semantic version string, Build returns the empty string.
102
func Build(v string) string {
103
	pv, ok := parse(v)
104
	if !ok {
105
		return ""
106
	}
107
	return pv.build
108
}
109

110
// Compare returns an integer comparing two versions according to
111
// semantic version precedence.
112
// The result will be 0 if v == w, -1 if v < w, or +1 if v > w.
113
//
114
// An invalid semantic version string is considered less than a valid one.
115
// All invalid semantic version strings compare equal to each other.
116
func Compare(v, w string) int {
117
	pv, ok1 := parse(v)
118
	pw, ok2 := parse(w)
119
	if !ok1 && !ok2 {
120
		return 0
121
	}
122
	if !ok1 {
123
		return -1
124
	}
125
	if !ok2 {
126
		return +1
127
	}
128
	if c := compareInt(pv.major, pw.major); c != 0 {
129
		return c
130
	}
131
	if c := compareInt(pv.minor, pw.minor); c != 0 {
132
		return c
133
	}
134
	if c := compareInt(pv.patch, pw.patch); c != 0 {
135
		return c
136
	}
137
	return comparePrerelease(pv.prerelease, pw.prerelease)
138
}
139

140
// Max canonicalizes its arguments and then returns the version string
141
// that compares greater.
142
//
143
// Deprecated: use [Compare] instead. In most cases, returning a canonicalized
144
// version is not expected or desired.
145
func Max(v, w string) string {
146
	v = Canonical(v)
147
	w = Canonical(w)
148
	if Compare(v, w) > 0 {
149
		return v
150
	}
151
	return w
152
}
153

154
// ByVersion implements [sort.Interface] for sorting semantic version strings.
155
type ByVersion []string
156

157
func (vs ByVersion) Len() int      { return len(vs) }
158
func (vs ByVersion) Swap(i, j int) { vs[i], vs[j] = vs[j], vs[i] }
159
func (vs ByVersion) Less(i, j int) bool {
160
	cmp := Compare(vs[i], vs[j])
161
	if cmp != 0 {
162
		return cmp < 0
163
	}
164
	return vs[i] < vs[j]
165
}
166

167
// Sort sorts a list of semantic version strings using [ByVersion].
168
func Sort(list []string) {
169
	sort.Sort(ByVersion(list))
170
}
171

172
func parse(v string) (p parsed, ok bool) {
173
	if v == "" || v[0] != 'v' {
174
		return
175
	}
176
	p.major, v, ok = parseInt(v[1:])
177
	if !ok {
178
		return
179
	}
180
	if v == "" {
181
		p.minor = "0"
182
		p.patch = "0"
183
		p.short = ".0.0"
184
		return
185
	}
186
	if v[0] != '.' {
187
		ok = false
188
		return
189
	}
190
	p.minor, v, ok = parseInt(v[1:])
191
	if !ok {
192
		return
193
	}
194
	if v == "" {
195
		p.patch = "0"
196
		p.short = ".0"
197
		return
198
	}
199
	if v[0] != '.' {
200
		ok = false
201
		return
202
	}
203
	p.patch, v, ok = parseInt(v[1:])
204
	if !ok {
205
		return
206
	}
207
	if len(v) > 0 && v[0] == '-' {
208
		p.prerelease, v, ok = parsePrerelease(v)
209
		if !ok {
210
			return
211
		}
212
	}
213
	if len(v) > 0 && v[0] == '+' {
214
		p.build, v, ok = parseBuild(v)
215
		if !ok {
216
			return
217
		}
218
	}
219
	if v != "" {
220
		ok = false
221
		return
222
	}
223
	ok = true
224
	return
225
}
226

227
func parseInt(v string) (t, rest string, ok bool) {
228
	if v == "" {
229
		return
230
	}
231
	if v[0] < '0' || '9' < v[0] {
232
		return
233
	}
234
	i := 1
235
	for i < len(v) && '0' <= v[i] && v[i] <= '9' {
236
		i++
237
	}
238
	if v[0] == '0' && i != 1 {
239
		return
240
	}
241
	return v[:i], v[i:], true
242
}
243

244
func parsePrerelease(v string) (t, rest string, ok bool) {
245
	// "A pre-release version MAY be denoted by appending a hyphen and
246
	// a series of dot separated identifiers immediately following the patch version.
247
	// Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-].
248
	// Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes."
249
	if v == "" || v[0] != '-' {
250
		return
251
	}
252
	i := 1
253
	start := 1
254
	for i < len(v) && v[i] != '+' {
255
		if !isIdentChar(v[i]) && v[i] != '.' {
256
			return
257
		}
258
		if v[i] == '.' {
259
			if start == i || isBadNum(v[start:i]) {
260
				return
261
			}
262
			start = i + 1
263
		}
264
		i++
265
	}
266
	if start == i || isBadNum(v[start:i]) {
267
		return
268
	}
269
	return v[:i], v[i:], true
270
}
271

272
func parseBuild(v string) (t, rest string, ok bool) {
273
	if v == "" || v[0] != '+' {
274
		return
275
	}
276
	i := 1
277
	start := 1
278
	for i < len(v) {
279
		if !isIdentChar(v[i]) && v[i] != '.' {
280
			return
281
		}
282
		if v[i] == '.' {
283
			if start == i {
284
				return
285
			}
286
			start = i + 1
287
		}
288
		i++
289
	}
290
	if start == i {
291
		return
292
	}
293
	return v[:i], v[i:], true
294
}
295

296
func isIdentChar(c byte) bool {
297
	return 'A' <= c && c <= 'Z' || 'a' <= c && c <= 'z' || '0' <= c && c <= '9' || c == '-'
298
}
299

300
func isBadNum(v string) bool {
301
	i := 0
302
	for i < len(v) && '0' <= v[i] && v[i] <= '9' {
303
		i++
304
	}
305
	return i == len(v) && i > 1 && v[0] == '0'
306
}
307

308
func isNum(v string) bool {
309
	i := 0
310
	for i < len(v) && '0' <= v[i] && v[i] <= '9' {
311
		i++
312
	}
313
	return i == len(v)
314
}
315

316
func compareInt(x, y string) int {
317
	if x == y {
318
		return 0
319
	}
320
	if len(x) < len(y) {
321
		return -1
322
	}
323
	if len(x) > len(y) {
324
		return +1
325
	}
326
	if x < y {
327
		return -1
328
	} else {
329
		return +1
330
	}
331
}
332

333
func comparePrerelease(x, y string) int {
334
	// "When major, minor, and patch are equal, a pre-release version has
335
	// lower precedence than a normal version.
336
	// Example: 1.0.0-alpha < 1.0.0.
337
	// Precedence for two pre-release versions with the same major, minor,
338
	// and patch version MUST be determined by comparing each dot separated
339
	// identifier from left to right until a difference is found as follows:
340
	// identifiers consisting of only digits are compared numerically and
341
	// identifiers with letters or hyphens are compared lexically in ASCII
342
	// sort order. Numeric identifiers always have lower precedence than
343
	// non-numeric identifiers. A larger set of pre-release fields has a
344
	// higher precedence than a smaller set, if all of the preceding
345
	// identifiers are equal.
346
	// Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta <
347
	// 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0."
348
	if x == y {
349
		return 0
350
	}
351
	if x == "" {
352
		return +1
353
	}
354
	if y == "" {
355
		return -1
356
	}
357
	for x != "" && y != "" {
358
		x = x[1:] // skip - or .
359
		y = y[1:] // skip - or .
360
		var dx, dy string
361
		dx, x = nextIdent(x)
362
		dy, y = nextIdent(y)
363
		if dx != dy {
364
			ix := isNum(dx)
365
			iy := isNum(dy)
366
			if ix != iy {
367
				if ix {
368
					return -1
369
				} else {
370
					return +1
371
				}
372
			}
373
			if ix {
374
				if len(dx) < len(dy) {
375
					return -1
376
				}
377
				if len(dx) > len(dy) {
378
					return +1
379
				}
380
			}
381
			if dx < dy {
382
				return -1
383
			} else {
384
				return +1
385
			}
386
		}
387
	}
388
	if x == "" {
389
		return -1
390
	} else {
391
		return +1
392
	}
393
}
394

395
func nextIdent(x string) (dx, rest string) {
396
	i := 0
397
	for i < len(x) && x[i] != '.' {
398
		i++
399
	}
400
	return x[:i], x[i:]
401
}
402