Semver.3sh.mdoc

.Dd Jun 06, 2018
.Dt SEMVER 3
.Os
.Sh NAME
.Nm Semver
.Nd semantic versioning functions
.Sh SYNOPSIS
.Nm Semver::validate
.Ar version
.Op Ar variable
.Nm Semver::compare
.Ar version
.Ar version
.Nm Semver::is_prerelease
.Ar version
.Nm Semver::increment_major
.Ar version
.Nm Semver::increment_minor
.Ar version
.Nm Semver::increment_patch
.Ar version
.Nm Semver::set_pre
.Ar version
.Ar pre-release
.Nm Semver::set_build
.Ar version
.Ar build metadata
.Nm Semver::pretty
.Ar major
.Ar minor
.Ar patch
.Op Ar pre-release
.Op Ar build_metadata
.Sh DESCRIPTION
.Nm Semver::validate
validates a semantic version string and optionally returns the parsed output.
It prints its input
.Ar version ,
erroring with a description of what's wrong if it's invalid.
If
.Ar variable
is also provided, a snippet for array assignment of the parsed parts to
.Ar variable
is instead printed, allowing for an easy
.Nm eval
afterwards.
(You probably want to run
.Ql declare -a my_var
beforehand so static analysis tools like
.Xr shellcheck 1
can work properly.)
.Pp
.Nm Semver::compare
compares two semvers and returns the result.
The result is one of
.Ql -1 ,
meaning less than,
.Ql 0 ,
meaning equals, or
.Ql 1 ,
meaning greater than.
This allows for natural use with
.Nm [[
or
.Xr test 1 ,
such as
.Ql [[ $(Semver::compare a b) -ge 0 ]]
testing whether
.Ar a
is greater than or equal to 
.Ar b .
.Pp
.Nm Semver::is_prerelease
checks whether a semver is a pre-release.
The result is either
.Ql yes
or
.Ql no .
.Pp
.Nm Semver::increment_major ,
.Nm Semver::increment_minor ,
and
.Nm Semver::increment_patch
return a new semver with the relevant part incremented.
This does not modify
.Ar version .
When incrementing, the pre-release and build metadata parts are dropped.
.Pp
.Nm Semver::set_pre
and
.Nm Semver::set_build
return a new semver with the relevant part replaced.
This does not modify
.Ar version .
Validation is performed on
.Ar part .
A
.Ar part
of the empty string removes the part.
Setting the pre-release does not drop the build metadata.
.Pp
.Nm Semver::pretty
takes separate parts and formats them into a semver.
Note that no validation is performed on the returned version.
.Sh VENDORING
If you wish to copy and paste these functions into your own script to vendor
them,
.Nm Semver::validate
&
.Nm Semver::pretty
have no dependencies.
All other functions depend on
.Nm Semver::validate .
Please remember to provide proper attribution and license information.
.Sh ERRORS
All errors start with the name of their associated function, like so:
.Dl Semver::validate: ...
.Pp
.Bl -tag
.It Nm Semver::validate
.Bl -bullet
.It
.Ql invalid major: $major
|
.Ql inavlid minor: $minor
|
.Ql invalid patch: $patch
.Pp
The part is not an integer.
.It
.Ql invalid pre-release: $pre_release
|
.Ql invalid build metadata: $build_metadata
.Pp
The part is not a series of non-empty identifiers
.Pq Ql [0-9A-Za-z-]
separated by
dots
.Pq Ql "." .
.El
.It Nm Semver::compare
.Bl -bullet
.It
All
.Nm Semver::validate
errors.
.El
.It Nm Semver::increment_major | Nm Semver::increment_minor | Nm \
Semver::increment_patch
.Bl -bullet
.It
All
.Nm Semver::validate
errors.
.El
.It Nm Semver::set_pre | Nm Semver::set_build
.Bl -bullet
.It
All
.Nm Semver::validate
errors.
.It 
.Nm Semver::set_pre :
.Ql invalid pre-release: $pre_release
|
.Nm Semver::set_build :
.Ql invalid build metadata: $build_metadata
.Pp
The part is not a series of non-empty identifiers
.Pq Ql [0-9A-Za-z-]
separated by dots
.Pq Ql "." .
.El
.El
.Sh EXAMPLE
The following script is designed to be placed next to a copy of
.Nm Semver.sh .
.Pp
.Bd -literal
#!/bin/bash
# example.sh
. ./semver.sh

ver_a='1.2.11-alpha+001'
ver_b='1.4.0'
ver_invalid='1.5.'

Semver::validate "$ver_invalid" 2>/dev/null \\
  && echo "$ver_invalid should be an invalid semver" \\
  || echo "$ver_invalid is an invalid semver"

echo

declare -a v
eval "$(Semver::validate "$ver_a" v)"
echo "Parts of \\$ver_a:"
echo "major=${v[0]}, minor=${v[1]}, patch=${v[2]},"
echo "pre-release=${v[3]}, build metadata=${v[4]}"

echo

compare_vers() {
  echo -n "Comparsion between $ver_a & $ver_b: "
  Semver::compare $ver_a $ver_b
}
compare_vers
ver_a=$(Semver::increment_minor "$ver_a")
ver_a=$(Semver::increment_minor "$ver_a")
compare_vers
ver_a=$(Semver::increment_patch "$ver_a")
compare_vers
ver_b=$(Semver::increment_patch "$ver_b")
ver_a=$(Semver::set_pre "$ver_a" 'alpha')
ver_b=$(Semver::set_pre "$ver_b" 'alpha')
ver_a=$(Semver::set_build "$ver_a" 'musl')
ver_b=$(Semver::set_build "$ver_b" 'glibc')
compare_vers
ver_b=$(Semver::set_pre "$ver_b" 'beta')
ver_b=$(Semver::set_build "$ver_b" '')
compare_vers
ver_a=$(Semver::set_pre "$ver_a" '')
ver_a=$(Semver::set_build "$ver_a" '')
compare_vers

echo

echo -n "Is $ver_b a pre-release? "
Semver::is_prerelease "$ver_b"
echo -n "What about $ver_a? "
Semver::is_prerelease "$ver_a"
.Ed
.Pp
We can then run
.Ql bash example.sh
for the following output:
.Pp
.Bd -literal
1.5. is an invalid semver

Parts of $ver_a:
major=1, minor=2, patch=11,
pre-release=alpha, build metadata=001

Comparsion between 1.2.11-alpha+001 & 1.4.10: -1
Comparsion between 1.4.0 & 1.4.0: 0
Comparsion between 1.4.1 & 1.4.0: 1
Comparsion between 1.4.1-alpha+musl & 1.4.1-alpha+glibc: 0
Comparsion between 1.4.1-alpha+musl & 1.4.1-beta: -1
Comparsion between 1.4.1 & 1.4.1-beta: 1

Is 1.4.1-beta a pre-release? yes
What about 1.4.1? no
.Ed
.Sh BUGS
Hopefully not, but if you do find some, let me know on GitHub or email me.
.Sh SEE ALSO
.Lk https://semver.org/ "Semantic Versioning specification" ,
.Xr bash 1
.Sh AUTHORS
.An bb010g Aq Mt me@bb010g.com

The latest sources, full contributor list, and more can be found at
.Lk https://github.com/bb010g/semver.sh .