Support parsing versions with custom prefixes via opt-in option (#79)

Introduce an opt-in mechanism to support parsing version strings with custom prefixes using WithPrefix.

This allows callers to normalize prefixed version strings (e.g. controller-v1.2.3) before parsing, while preserving the original input for display and debugging purposes.

Comparison behavior remains unchanged and operates on normalized versions. Prefix handling is intentionally left to the caller to keep the library behavior predictable and backward compatible.

Documentation and tests have been updated to reflect the new functionality and usage patterns.

--

Signed-off-by: Lasse Gaardsholt <lasse.gaardsholt@bestseller.com>
Co-authored-by: Lasse Gaardsholt <lasse.gaardsholt@bestseller.com>
Co-authored-by: Lasse Gaardsholt <lasse.gaardsholt@gmail.com>
Co-authored-by: Oliver Karstoft <orkarstoft@gmail.com>
Co-authored-by: Sagar Verma <sagar.verma@ibm.com>

Author: 4 people

README.md

@@ -34,6 +34,32 @@ if v1.LessThan(v2) {
 }
 ```
 
+#### Version Parsing and Comparison with Prefixes
+
+The library also supports parsing versions with a custom prefix.
+Using the `WithPrefix` option, you can specify a prefix to strip
+before parsing the version.
+
+Use `WithPrefix` when your input strings carry a known release prefix such as
+`deployment-`, `controller-`, etc.
+
+After parsing, the prefix is not part of the canonical version value. This
+means the regular comparison methods such as `Compare`, `LessThan`, `Equal`,
+and `GreaterThan` compare only the stripped version. If you compare versions
+from different prefixes with these methods, the prefixes are ignored. If you
+need to reject cross-prefix comparisons, inspect the parsed prefixes before
+comparing the versions.
+
+```go
+v1, _ := version.NewVersion("deployment-v1.2.3-beta+metadata", version.WithPrefix("deployment-"))
+v2, _ := version.NewVersion("deployment-v1.2.4", version.WithPrefix("deployment-"))
+
+if v1.LessThan(v2) {
+    fmt.Printf("%s (%s) is less than %s (%s)\n", v1, v1.Original(), v2, v2.Original())
+    // Outputs: 1.2.3-beta+metadata (deployment-v1.2.3-beta+metadata) is less than 1.2.4 (deployment-v1.2.4)
+}
+```
+
 #### Version Constraints
 
 ```go

version.go

@@ -49,19 +49,60 @@ const (
 		`?`
 )
 
+// Optional options for NewVersion function.
+type options struct {
+	// If set, this prefix will be trimmed from the version string before parsing.
+	prefix string
+}
+
+// Option is a functional option for NewVersion.
+type Option func(*options)
+
+// WithPrefix is a functional option that sets a prefix to be removed from the
+// version string before parsing.
+func WithPrefix(prefix string) Option {
+	return func(o *options) {
+		o.prefix = prefix
+	}
+}
+
 // Version represents a single version.
 type Version struct {
 	metadata string
 	pre      string
 	segments []int64
 	si       int
 	original string
+	prefix   string
 }
 
-// NewVersion parses the given version and returns a new
-// Version.
-func NewVersion(v string) (*Version, error) {
-	return newVersion(v, getVersionRegexp())
+// NewVersion parses the given version and returns a new Version.
+//
+// Optional parsing behavior can be enabled with Option values such as
+// WithPrefix, which validates and strips an expected prefix before parsing.
+func NewVersion(v string, opts ...Option) (*Version, error) {
+	options := &options{}
+	for _, opt := range opts {
+		if opt != nil {
+			opt(options)
+		}
+	}
+
+	vToParse := v
+	if options.prefix != "" {
+		if !strings.HasPrefix(v, options.prefix) {
+			return nil, fmt.Errorf("version %q does not have prefix %q", v, options.prefix)
+		}
+		vToParse = strings.TrimPrefix(v, options.prefix)
+	}
+
+	ver, err := newVersion(vToParse, getVersionRegexp())
+	if err != nil {
+		return nil, err
+	}
+	ver.prefix = options.prefix
+	ver.original = v
+	return ver, nil
 }
 
 // NewSemver parses the given version and returns a new
@@ -424,6 +465,11 @@ func (v *Version) Original() string {
 	return v.original
 }
 
+// Prefix returns the explicit prefix used with WithPrefix, if any.
+func (v *Version) Prefix() string {
+	return v.prefix
+}
+
 // UnmarshalText implements encoding.TextUnmarshaler interface.
 func (v *Version) UnmarshalText(b []byte) error {
 	temp, err := NewVersion(string(b))

version_test.go

@@ -39,6 +39,8 @@ func TestNewVersion(t *testing.T) {
 		{"1.7rc2", false},
 		{"v1.7rc2", false},
 		{"1.0-", false},
+		{"controller-v0.40.2", true},
+		{"azure-cli-v1.4.2", true},
 	}
 
 	for _, tc := range cases {
@@ -51,6 +53,33 @@ func TestNewVersion(t *testing.T) {
 	}
 }
 
+func TestNewVersionWithPrefix(t *testing.T) {
+	cases := []struct {
+		version string
+		prefix  string
+		err     bool
+	}{
+		{"", "release-", true},
+		{"rel-1.2.3", "release-", true},
+		{"release_1.2.3", "release-", true},
+		{"release_1.2.0-x.Y.0+metadata", "release_", false},
+		{"release-1.2.0-x.Y.0+metadata-width-hyphen", "release-", false},
+		{"myrelease-1.2.3-rc1-with-hyphen", "myrelease-", false},
+		{"prefix-1.2.3.4", "prefix-", false},
+		{"controller-v0.40.2", "controller-", false},
+		{"azure-cli-v1.4.2", "azure-cli-", false},
+	}
+
+	for _, tc := range cases {
+		_, err := NewVersion(tc.version, WithPrefix(tc.prefix))
+		if tc.err && err == nil {
+			t.Fatalf("expected error for version: %q", tc.version)
+		} else if !tc.err && err != nil {
+			t.Fatalf("error for version %q: %s", tc.version, err)
+		}
+	}
+}
+
 func TestNewSemver(t *testing.T) {
 	cases := []struct {
 		version string
@@ -80,6 +109,8 @@ func TestNewSemver(t *testing.T) {
 		{"1.7rc2", true},
 		{"v1.7rc2", true},
 		{"1.0-", true},
+		{"controller-v0.40.2", true},
+		{"azure-cli-v1.4.2", true},
 	}
 
 	for _, tc := range cases {
@@ -171,6 +202,107 @@ func TestVersionCompare(t *testing.T) {
 	}
 }
 
+func TestVersionCompareWithPrefix(t *testing.T) {
+	cases := []struct {
+		v1       string
+		v1Prefix string
+		v2       string
+		v2Prefix string
+		expected int
+	}{
+		{"controller-v0.40.2", "controller-", "controller-v0.40.3", "controller-", -1},
+		{"0.40.4", "", "controller-v0.40.2", "controller-", 1},
+		{"0.40.4", "", "controller-v0.40.4", "controller-", 0},
+		{"azure-cli-v1.4.2", "azure-cli-", "azure-cli-v1.4.2", "azure-cli-", 0},
+		{"azure-cli-v1.4.1", "azure-cli-", "azure-cli-v1.4.2", "azure-cli-", -1},
+		{"1.4.3", "", "azure-cli-v1.4.2", "azure-cli-", 1},
+		{"v1.4.3", "", "azure-cli-v1.4.2", "azure-cli-", 1},
+		{"controller-v1.4.1", "controller-", "azure-cli-v1.4.2", "azure-cli-", -1},
+	}
+
+	for _, tc := range cases {
+		var v1 *Version
+		var err error
+		if tc.v1Prefix != "" {
+			v1, err = NewVersion(tc.v1, WithPrefix(tc.v1Prefix))
+		} else {
+			v1, err = NewVersion(tc.v1)
+		}
+		if err != nil {
+			t.Fatalf("err: %s", err)
+		}
+
+		var v2 *Version
+		if tc.v2Prefix != "" {
+			v2, err = NewVersion(tc.v2, WithPrefix(tc.v2Prefix))
+		} else {
+			v2, err = NewVersion(tc.v2)
+		}
+		if err != nil {
+			t.Fatalf("err: %s", err)
+		}
+
+		actual := v1.Compare(v2)
+		expected := tc.expected
+		if actual != expected {
+			t.Fatalf(
+				"%s <=> %s\nexpected: %d\nactual: %d",
+				tc.v1, tc.v2,
+				expected, actual)
+		}
+	}
+}
+
+func TestVersionAccessorsWithPrefix(t *testing.T) {
+	v, err := NewVersion("controller-v1.2.0-beta.2+build.5", WithPrefix("controller-"))
+	if err != nil {
+		t.Fatalf("err: %s", err)
+	}
+
+	if got := v.Prefix(); got != "controller-" {
+		t.Fatalf("expected prefix %q, got %q", "controller-", got)
+	}
+
+	if got := v.Original(); got != "controller-v1.2.0-beta.2+build.5" {
+		t.Fatalf("expected original %q, got %q", "controller-v1.2.0-beta.2+build.5", got)
+	}
+
+	if got := v.String(); got != "1.2.0-beta.2+build.5" {
+		t.Fatalf("expected string %q, got %q", "1.2.0-beta.2+build.5", got)
+	}
+
+	if got := v.Metadata(); got != "build.5" {
+		t.Fatalf("expected metadata %q, got %q", "build.5", got)
+	}
+
+	if got := v.Prerelease(); got != "beta.2" {
+		t.Fatalf("expected prerelease %q, got %q", "beta.2", got)
+	}
+
+	expectedSegments := []int{1, 2, 0}
+	if got := v.Segments(); !reflect.DeepEqual(got, expectedSegments) {
+		t.Fatalf("expected segments %#v, got %#v", expectedSegments, got)
+	}
+
+	expectedSegments64 := []int64{1, 2, 0}
+	if got := v.Segments64(); !reflect.DeepEqual(got, expectedSegments64) {
+		t.Fatalf("expected segments64 %#v, got %#v", expectedSegments64, got)
+	}
+}
+
+func TestVersionSegmentsWithPrefix(t *testing.T) {
+	v, err := NewVersion("azure-cli-v1.4.2", WithPrefix("azure-cli-"))
+	if err != nil {
+		t.Fatalf("err: %s", err)
+	}
+
+	expected := []int{1, 4, 2}
+	actual := v.Segments()
+	if !reflect.DeepEqual(actual, expected) {
+		t.Fatalf("expected: %#v\nactual: %#v", expected, actual)
+	}
+}
+
 func TestVersionCompare_versionAndSemver(t *testing.T) {
 	cases := []struct {
 		versionRaw string