Semantic Versioning (#14)

Author: bbengfort

README.md

@@ -24,6 +24,7 @@ This is single repository that stores many, independent small subpackages. This
 - [randstr](https://go.rtnl.ai/x/randstr): generate random strings using the crypto/rand package as efficiently as possible
 - [api](https://go.rtnl.ai/x/api): common utilities and responses for our JSON/REST APIs that our services run.
 - [dsn](https://go.rtnl.ai/x/dsn): parses data source names in order to connect to both server and embedded databases easily.
+- [semver](https://go.rtnl.ai/x/semver): allows parsing and comparison of semantic versioning numbers.
 
 ## About
 

assert/assert.go

@@ -101,6 +101,20 @@ func Regexp(tb testing.TB, rx *regexp.Regexp, str string, msgAndArgs ...interfac
 	Assert(tb, rx.MatchString(str), msg)
 }
 
+// Nil asserts that the specified object is nil.
+func Nil(tb testing.TB, object interface{}, msgAndArgs ...interface{}) {
+	tb.Helper()
+	msg := makeMessage("expected nil, but got non-nil", msgAndArgs...)
+	Assert(tb, object == nil || reflect.ValueOf(object).IsNil(), msg)
+}
+
+// NotNil asserts that the specified object is not nil.
+func NotNil(tb testing.TB, object interface{}, msgAndArgs ...interface{}) {
+	tb.Helper()
+	msg := makeMessage("expected non-nil, but got nil", msgAndArgs...)
+	Assert(tb, object != nil && !reflect.ValueOf(object).IsNil(), msg)
+}
+
 func makeMessage(msg string, msgAndArgs ...interface{}) string {
 	switch len(msgAndArgs) {
 	case 0:

semver/README.md

@@ -0,0 +1,71 @@
+# Semantic Versioning
+
+Utilities for identifying, parsing, and comparing semantic version strings as
+specified by [Semantic Versioning 2.0.0](https://semver.org/).
+
+To test if a string is a valid semantic version:
+
+```go
+semver.Valid("1.3.1")
+// true
+
+semver.Valid("1.foo")
+// false
+```
+
+To parse a string into its semantic version components:
+
+```go
+vers, err := semver.Parse("1.3.1-alpha")
+```
+
+To compare the precedence of two versions:
+
+```go
+semver.Compare(a, b)
+// or
+a.Compare(b)
+```
+
+[Precedence](https://semver.org/#spec-item-11) defines how versions are compared to each other when ordered (e.g. which is the later version number). The output of compare is:
+
+- `-1`: a < b or b has the higher precedence
+- `0`: a == b or a and b have the same precedence (but not necessarily equal strings)
+- `1`: a > b or a has the higher precedence
+
+A `Range` is a a specification of semantic version boundaries, and are used to check if a semantic version is part of a range or not. For example:
+
+```go
+spec := semver.Range(">=1.3.1")
+spec("1.4.8")
+// true
+spec("1.2.9")
+// false
+```
+
+Alternatively, you can check to see if a version satisifies a range:
+
+```go
+v := semver.MustParse("1.3.0")
+v.Satisfies(spec)
+// false
+```
+
+> **NOTE**: The range functionality described below is currently only partially implemented.
+
+Ranges are denoted by an operator:
+
+| Operator | Definition | Example | Notes |
+|---|---|---|---|
+| = | Match exact version | =1.2.3 | No operator is interpreted as = |
+| > | Match higher precedence versions | >1.2.3 |  |
+| < | Match lower precedence versions | <1.2.3 |  |
+| >= | Match exact or higher precedence versions | >=1.2.3 |  |
+| <=  | Match exact or lower precedence versions | <=1.2.3 |  |
+| ~ | Match "reasonably close to" | ~1.2.3 | is >=1.2.3 && <1.3.0 |
+| ^ | Match "compatible with" | ^1.2.3 | is >=1.2.3 && <2.0.0 |
+| x or X | Any version | 1.x.x | is >=1.0.0 && <2.0.0 |
+| * | Any version | 1.2.* | is >=1.2.0 && <1.3.0 |
+| - | Hyphenated range | 1.2.3 - 2.3.4 | is >=1.2.3 && <=2.3.4 |
+
+Ranges can be combined with `&&` (AND) and `||` (OR) operators for more complex range definitions.

semver/errors.go

@@ -0,0 +1,9 @@
+package semver
+
+import "errors"
+
+var (
+	ErrInvalidSemVer = errors.New("invalid semantic version")
+	ErrInvalidRange  = errors.New("invalid semantic range")
+	ErrScanValue     = errors.New("could not scan source value")
+)

semver/range.go

@@ -0,0 +1,218 @@
+package semver
+
+import (
+	"fmt"
+	"strings"
+	"unicode"
+)
+
+func Range(s string) (_ Specification, err error) {
+	var fn Specifies
+	if fn, err = parseRange(s); err != nil {
+		return nil, err
+	}
+
+	return func(t any) bool {
+		switch v := t.(type) {
+		case string:
+			ver, err := Parse(v)
+			if err != nil {
+				return false
+			}
+			return fn(ver)
+		case Version:
+			return fn(v)
+		case *Version:
+			return fn(*v)
+		default:
+			return false
+		}
+	}, nil
+}
+
+type Specification func(any) bool
+
+type Specifies func(Version) bool
+
+func (s Specifies) Or(o Specifies) Specifies {
+	return func(v Version) bool {
+		return s(v) || o(v)
+	}
+}
+
+func (s Specifies) And(o Specifies) Specifies {
+	return func(v Version) bool {
+		return s(v) && o(v)
+	}
+}
+
+//===========================================================================
+// Comparison Operators
+//===========================================================================
+
+type operator rune
+
+const (
+	EQ  operator = '='
+	GT  operator = '>'
+	GTE operator = '≥'
+	LT  operator = '<'
+	LTE operator = '≤'
+)
+
+func compare(v Version, op operator) Specifies {
+	switch op {
+	case EQ:
+		return func(o Version) bool {
+			return Compare(o, v) == 0
+		}
+	case GT:
+		return func(o Version) bool {
+			return Compare(o, v) > 0
+		}
+	case GTE:
+		return func(o Version) bool {
+			return Compare(o, v) >= 0
+		}
+	case LT:
+		return func(o Version) bool {
+			return Compare(o, v) < 0
+		}
+	case LTE:
+		return func(o Version) bool {
+			return Compare(o, v) <= 0
+		}
+	default:
+		panic(fmt.Errorf("unknown operator %q", op))
+	}
+}
+
+//===========================================================================
+// Parsing
+//===========================================================================
+
+func parseRange(s string) (_ Specifies, err error) {
+	parts := split(s)
+	orParts, err := splitOR(parts)
+	if err != nil {
+		return nil, err
+	}
+
+	// TODO: expand wildcards
+
+	var orFn Specifies
+	for _, part := range orParts {
+		var andFn Specifies
+		for _, and := range part {
+			op, vers, err := parseComparitor(and)
+			if err != nil {
+				return nil, err
+			}
+
+			// TODO: build range functions
+
+			// Set function
+			if andFn == nil {
+				andFn = compare(vers, op)
+			} else {
+				andFn = andFn.And(compare(vers, op))
+			}
+		}
+
+		if orFn == nil {
+			orFn = andFn
+		} else {
+			orFn = orFn.Or(andFn)
+		}
+	}
+
+	return orFn, nil
+}
+
+func parseComparitor(s string) (op operator, v Version, err error) {
+	i := strings.IndexFunc(s, unicode.IsDigit)
+	if i == -1 {
+		return 0, Version{}, ErrInvalidRange
+	}
+
+	// Split the operator from the version
+	ops, vers := s[0:i], s[i:]
+
+	// Parse the version number
+	if v, err = Parse(vers); err != nil {
+		return 0, Version{}, err
+	}
+
+	// Parse the operator
+	switch ops {
+	case "=", "==":
+		return EQ, v, nil
+	case ">":
+		return GT, v, nil
+	case ">=":
+		return GTE, v, nil
+	case "<":
+		return LT, v, nil
+	case "<=":
+		return LTE, v, nil
+	default:
+		return 0, Version{}, ErrInvalidRange
+	}
+}
+
+func split(s string) (result []string) {
+	last := 0
+	var lastChar byte
+	exclude := []byte{'>', '<', '='}
+
+	for i := 0; i < len(s); i++ {
+		if s[i] == ' ' && !inArray(lastChar, exclude) {
+			if last < i-1 {
+				result = append(result, s[last:i])
+			}
+			last = i + 1
+		} else if s[i] != ' ' {
+			lastChar = s[i]
+		}
+	}
+
+	if last < len(s)-1 {
+		result = append(result, s[last:])
+	}
+
+	for i, v := range result {
+		result[i] = strings.Replace(v, " ", "", -1)
+	}
+
+	return result
+}
+
+func splitOR(parts []string) (result [][]string, err error) {
+	last := 0
+	for i, part := range parts {
+		if part == "||" {
+			if i == 0 {
+				return nil, ErrInvalidRange
+			}
+
+			result = append(result, parts[last:i])
+			last = i + 1
+		}
+	}
+
+	if last == len(parts) {
+		return nil, ErrInvalidRange
+	}
+
+	result = append(result, parts[last:])
+	return result, nil
+}
+
+func inArray(s byte, list []byte) bool {
+	for _, el := range list {
+		if el == s {
+			return true
+		}
+	}
+	return false
+}