"prerelease" keyword supported in bump and get (issue #51) (#69)

The "diff" subcommand returns the keyword "prerelease" when it is the pre-release part that differs. This keyword--different from "prerel"--means using the output of "diff" is awkward to use as input to "bump" or "get". This change creates a synonym for "prerel", namely "prerelease" in the bump and get subcommands, fixing the output/input awkwardness without breaking backwards compatibility. The implementation is simple: normalize the part keyword to a canonical string ("prerel"). This is completely transparent to the external API. The README and usage string have been updated accordingly. The README and usage string now list each subcommand on a separate line for readability: the previous list of subcommand choices being too long. The order of the subcommands listed has been changed: the two "complex" subcommands ("bump" and "get") appear ahead of the others. The changes pass all the existing unit tests: no regression or backward compatibility issues. Two new test cases added to cover use of this alternative keyword. When released, these changes require bumping semver's minor version. As a placeholder, the version string has been set to 3.4.0.
fsaintjacques · Oct 12, 2022 · 837ad91 · 837ad91
1 parent cac039e
commit 837ad91
Show file tree

Hide file tree

Showing 4 changed files with 80 additions and 30 deletions.
diff --git a/README.md b/README.md
@@ -5,8 +5,8 @@ semver is a little tool to manipulate version bumping in a project that
 follows the [semver 2.x][semver] specification. Its uses are:
 
   - bump version
-  - compare versions
   - extract specific version part
+  - compare versions
   - identify most significant difference between two versions
   - validate version syntax
 
@@ -47,10 +47,20 @@ usage
 
 ```
 Usage:
-  semver bump (major|minor|patch|release|prerel [<prerel>]|build <build>) <version>
+  semver bump major <version>
+  semver bump minor <version>
+  semver bump patch <version>
+  semver bump prerel|prerelease [<prerel>] <version>
+  semver bump build <build> <version>
+  semver bump release <version>
+  semver get major <version>
+  semver get minor <version>
+  semver get patch <version>
+  semver get prerel|prerelease <version>
+  semver get build <version>
+  semver get release <version>
   semver compare <version> <other_version>
   semver diff <version> <other_version>
-  semver get (major|minor|patch|release|prerel|build) <version>
   semver validate <version>
   semver --help
   semver --version
@@ -71,7 +81,7 @@ Arguments:
   <other_version>  See <version> definition.
 
   <prerel>  A string as defined by PRERELEASE above. Or, it can be a PRERELEASE
-            prototype string (or empty) followed by a dot.
+            prototype string followed by a dot.
 
   <build>   A string as defined by BUILD above.
 
@@ -81,14 +91,17 @@ Options:
 
 Commands:
   bump      Bump by one of major, minor, patch; zeroing or removing
-            subsequent parts. "bump prerel" sets the PRERELEASE part and
-            removes any BUILD part. A trailing dot in the <prerel> argument
-            introduces an incrementing numeric field which is added or
-            bumped. If no <prerel> argument is provided, an incrementing numeric
-            field is introduced/bumped. "bump build" sets the BUILD part.
-            "bump release" removes any PRERELEASE or BUILD parts.
+            subsequent parts. "bump prerel" (or its synonym "bump prerelease")
+            sets the PRERELEASE part and removes any BUILD part. A trailing dot
+            in the <prerel> argument introduces an incrementing numeric field
+            which is added or bumped. If no <prerel> argument is provided, an
+            incrementing numeric field is introduced/bumped. "bump build" sets
+            the BUILD part.  "bump release" removes any PRERELEASE or BUILD parts.
             The bumped version is written to stdout.
 
+  get       Extract given part of <version>, where part is one of major, minor,
+            patch, prerel (alternatively: prerelease), build, or release.
+
   compare   Compare <version> with <other_version>, output to stdout the
             following values: -1 if <other_version> is newer, 0 if equal, 1 if
             older. The BUILD part is not used in comparisons.
@@ -97,9 +110,6 @@ Commands:
             difference between two versions by the release type (MAJOR, MINOR,
             PATCH, PRERELEASE, BUILD).
 
-  get       Extract given part of <version>, where part is one of major, minor,
-            patch, prerel, build, or release.
-
   validate  Validate if <version> follows the SEMVER pattern (see <version>
             definition). Print 'valid' to stdout if the version is valid, otherwise
             print 'invalid'.
@@ -125,6 +135,8 @@ Basic bumping operations
     1.0.1
     $ semver bump prerel rc.1 1.0.1
     1.0.1-rc.1
+    $ semver bump prerelease rc.1 1.0.1
+    1.0.1-rc.1
     $ semver bump prerel rc.. 1.2.0-beta2
     1.2.0-rc.1
     $ semver bump prerel 1.0.1-rc.1+build4423
@@ -170,6 +182,8 @@ Extract version part
     1
     $ semver get prerel 1.2.3-rc.4
     rc.4
+    $ semver get prerelease 1.2.3-rc.4
+    rc.4
     $ semver get prerel 1.2.3-alpha.4.5
     alpha.4.5
     $ semver get build 1.2.3-rc.4+build.567

diff --git a/src/semver b/src/semver
@@ -14,14 +14,24 @@ SEMVER_REGEX="\
 (\\+${FIELD}(\\.${FIELD})*)?$"
 
 PROG=semver
-PROG_VERSION="3.3.0"
+PROG_VERSION="3.4.0"
 
 USAGE="\
 Usage:
-  $PROG bump (major|minor|patch|release|prerel [<prerel>]|build <build>) <version>
+  $PROG bump major <version>
+  $PROG bump minor <version>
+  $PROG bump patch <version>
+  $PROG bump prerel|prerelease [<prerel>] <version>
+  $PROG bump build <build> <version>
+  $PROG bump release <version>
+  $PROG get major <version>
+  $PROG get minor <version>
+  $PROG get patch <version>
+  $PROG get prerel|prerelease <version>
+  $PROG get build <version>
+  $PROG get release <version>
   $PROG compare <version> <other_version>
   $PROG diff <version> <other_version>
-  $PROG get (major|minor|patch|release|prerel|build) <version>
   $PROG validate <version>
   $PROG --help
   $PROG --version
@@ -42,7 +52,7 @@ Arguments:
   <other_version>  See <version> definition.
 
   <prerel>  A string as defined by PRERELEASE above. Or, it can be a PRERELEASE
-            prototype string (or empty) followed by a dot.
+            prototype string followed by a dot.
 
   <build>   A string as defined by BUILD above.
 
@@ -52,14 +62,17 @@ Options:
 
 Commands:
   bump      Bump by one of major, minor, patch; zeroing or removing
-            subsequent parts. \"bump prerel\" sets the PRERELEASE part and
-            removes any BUILD part. A trailing dot in the <prerel> argument
-            introduces an incrementing numeric field which is added or
-            bumped. If no <prerel> argument is provided, an incrementing numeric
-            field is introduced/bumped. \"bump build\" sets the BUILD part.
-            \"bump release\" removes any PRERELEASE or BUILD parts.
+            subsequent parts. \"bump prerel\" (or its synonym \"bump prerelease\")
+            sets the PRERELEASE part and removes any BUILD part. A trailing dot
+            in the <prerel> argument introduces an incrementing numeric field
+            which is added or bumped. If no <prerel> argument is provided, an
+            incrementing numeric field is introduced/bumped. \"bump build\" sets
+            the BUILD part.  \"bump release\" removes any PRERELEASE or BUILD parts.
             The bumped version is written to stdout.
 
+  get       Extract given part of <version>, where part is one of major, minor,
+            patch, prerel (alternatively: prerelease), build, or release.
+
   compare   Compare <version> with <other_version>, output to stdout the
             following values: -1 if <other_version> is newer, 0 if equal, 1 if
             older. The BUILD part is not used in comparisons.
@@ -68,9 +81,6 @@ Commands:
             difference between two versions by the release type (MAJOR, MINOR,
             PATCH, PRERELEASE, BUILD).
 
-  get       Extract given part of <version>, where part is one of major, minor,
-            patch, prerel, build, or release.
-
   validate  Validate if <version> follows the SEMVER pattern (see <version>
             definition). Print 'valid' to stdout if the version is valid, otherwise
             print 'invalid'.
@@ -92,6 +102,18 @@ function usage_version {
   exit 0
 }
 
+# normalize the "part" keywords to a canonical string.  At present,
+# only "prerelease" is normalized to "prerel".
+
+function normalize_part {
+    if [ "$1" == "prerelease" ]
+    then
+	echo "prerel"
+    else
+	echo "$1"
+    fi
+}
+
 function validate_version {
   local version=$1
   if [[ "$version" =~ $SEMVER_REGEX ]]; then
@@ -284,13 +306,15 @@ function bump_prerel {
 function command_bump {
   local new; local version; local sub_version; local command;
 
+  command="$(normalize_part "$1")"
+
   case $# in
-    2) case $1 in
-        major|minor|patch|prerel|release) command=$1; sub_version="+."; version=$2;;
+    2) case "$command" in
+        major|minor|patch|prerel|release) sub_version="+."; version=$2;;
         *) usage_help;;
        esac ;;
-    3) case $1 in
-        prerel|build) command=$1; sub_version=$2 version=$3 ;;
+    3) case "$command" in
+        prerel|build) sub_version=$2 version=$3 ;;
         *) usage_help;;
        esac ;;
     *) usage_help;;
@@ -381,6 +405,8 @@ function command_get {
     local build="${parts[4]:1}"
     local release="${major}.${minor}.${patch}"
 
+    part="$(normalize_part "$part")"
+
     case "$part" in
         major|minor|patch|release|prerel|build) echo "${!part}" ;;
         *) usage_help ;;

diff --git a/test/bump.bats b/test/bump.bats
@@ -51,6 +51,11 @@ SEMVER="src/semver"
 	[ "$result" = "0.2.1-rc.1" ]
 }
 
+@test "bump prerelease" {
+	result="$($SEMVER bump prerelease rc.1 0.2.1)"
+	[ "$result" = "0.2.1-rc.1" ]
+}
+
 @test "bump prerel (replace and strip build metadata)" {
 	result="$($SEMVER bump prerel rc.1 0.2.1-0.2+b13)"
 	[ "$result" = "0.2.1-rc.1" ]

diff --git a/test/get.bats b/test/get.bats
@@ -24,6 +24,11 @@ SEMVER="src/semver"
 	[ "$result" = "rc1.-0" ]
 }
 
+@test "get prerelease" {
+	result="$($SEMVER get prerelease 0.2.1-rc1.-0+build-1234)"
+	[ "$result" = "rc1.-0" ]
+}
+
 @test "get build" {
 	result="$($SEMVER get build 0.2.1-rc1.0+build-0234)"
 	[ "$result" = "build-0234" ]