Validate, compare, sort, parse, and serialize Semantic Versioning (SemVer) 2.0.0 version strings, using XQuery.
SemVer rules are applied strictly, raising errors when version strings do not conform to the spec.
- Requirements: Java 8, Apache Maven 3.3+, Git.
If you want to create an EXPath Package for the app, you can run:
$ mvn packageThere will be a .xar file in the target/ sub-folder.
This project is configured to use the Maven Release Plugin to make creating and subsequently publishing a release easy.
The release plugin will take care of:
- Testing the project (all tests must pass)
- Verifying all rules, e.g. license declarations present, etc.
- Creating a Git Tag and pushing the Tag to GitHub
- Building and signing the artifacts (e.g. EXPath Pkg
.xarfile).
Before performing the release, in addition to the Build requirements you need an installed and functioning copy of GPG or GnuPG with your private key setup correctly for signing.
To perform the release, from within your local Git cloned repository run:
mvn release:prepare && mvn release:performYou will be prompted for the answers to a few questions along the way. The default response will be provided for you, and you can simply press "Enter" (or "Return") to accept it. Alternatively you may enter your own value and press "Enter" (or "Return").
What is the release version for "semver.xq"? (org.exist-db.xquery:semver-xq) 2.3.1: : 2.4.0
What is SCM release tag or label for "semver.xq"? (org.exist-db.xquery:semver-xq) 2.4.0: :
What is the new development version for "semver.xq"? (org.exist-db.xquery:semver-xq) 2.4.1-SNAPSHOT: :- For the
release version, please sensibly consider using the next appropriate SemVer 2.0.0 version number. - For the
SCM release tag, please use the same value as therelease version. - For the
new development version, the default value should always suffice.
Once the release process completes, there will be a .xar file in the target/ sub-folder. This file may be published to:
- GitHub Releases - https://github.com/eXist-db/semver.xq/releases
- The eXist-db Public EXPath Repository - https://exist-db.org/exist/apps/public-repo/admin
Simply run: mvn -Pdev docker:start to start a Docker environment of eXist-db on port 9090
with the semver.xq package already deployed.
As the Docker environment binds the files from the host filesystem, changes to the source code are reflected immediately in the running eXist-db environment.
You can override the Docker host port for eXist-db from port 9090 to a port of your choosing by
specifying -Ddev.port=9191, e.g.: mvn -Pdev -Ddev.port=9191 docker:start.
If you also want the Dashboard and eXide to be available from the Docker environment of eXist-db
you can invoke the target public-xar-repo:resolve before you call docker:start,
e.g. mvn -Pdev public-xar-repo:resolve docker:start.
To stop the Docker environment run: mvn -Pdev docker:stop.
- Variables: $semver:regex, $semver:coerce-regex, $semver:expath-package-semver-template-regex
- Functions: semver:validate#1, semver:validate-expath-package-semver-template#1, semver:parse#1, semver:parse#2, semver:coerce#1, semver:resolve-expath-package-semver-template-min#1, semver:resolve-expath-package-semver-template-max#1, semver:resolve-expath-package-semver-template#2, semver:satisfies-expath-package-dependency-versioning-attributes#5, semver:serialize#5, semver:serialize#1, semver:serialize-parsed#1, semver:compare#2, semver:compare#3, semver:compare-parsed#2, semver:lt#2, semver:lt#3, semver:lt-parsed#2, semver:le#2, semver:le#3, semver:le-parsed#2, semver:gt#2, semver:gt#3, semver:gt-parsed#2, semver:ge#2, semver:ge#3, semver:ge-parsed#2, semver:eq#2, semver:eq#3, semver:eq-parsed#2, semver:ne#2, semver:ne#3, semver:ne-parsed#2, semver:sort#1, semver:sort#2, semver:sort#3, semver:sort-parsed#1
$semver:regex asA regular expression for validating SemVer strings and parsing valid SemVer strings
$semver:coerce-regex asA forgiving regular expression for capturing groups needed to coerce a non-SemVer string into SemVer components
$semver:expath-package-semver-template-regex asA regular expression for validating SemVer templates as defined in the EXPath Package spec
semver:validate($version as xs:string) as xs:booleanValidate whether a SemVer string conforms to the spec
Params
$version as xs:string— A version string
Returns xs:boolean: True if the version is valid, false if not
semver:validate-expath-package-semver-template($version as xs:string) as xs:booleanValidate whether a version string conforms to the rules for SemVer templates as defined in the EXPath Package spec
Params
$version as xs:string— A version string
Returns xs:boolean: True if the version is a SemVer template, false if not
semver:parse($version as xs:string) as map(*)Parse a SemVer string (strictly)
Params
$version as xs:string— A version string
Returns map(*): A map containing analysis of the parsed version, with entries for each identifier ("major", "minor", "patch", "pre-release", and "build-metadata"), and an "identifiers" entry with all identifiers in an array.
Errors regex-error, identifier-error
semver:parse($version as xs:string, $coerce as xs:boolean) as map(*)Parse a SemVer string (with an option to coerce invalid SemVer strings)
Params
$version as xs:string— A version string$coerce as xs:boolean— An option for coercing non-SemVer version strings into parsable form
Returns map(*): A map containing analysis of the parsed SemVer versions, with entries for each identifier ("major", "minor", "patch", "pre-release", and "build-metadata"), and an "identifiers" entry with all identifiers in an array.
Errors regex-error, identifier-error
semver:coerce($version as xs:string) as map(*)Coerce a non-SemVer version string into a SemVer string and parse it as such
Params
$version as xs:string— A version string which will be coerced into a parsed SemVer version
Returns map(*): A map containing analysis of the coerced version, with entries for each identifier ("major", "minor", "patch", "pre-release", and "build-metadata"), and an "identifiers" entry with all identifiers in an array. Fallback for invalid version strings: 0.0.0.
semver:resolve-expath-package-semver-template-min($version as xs:string) as map(*)Resolve an EXPath Package SemVer Template as minimum (floor)
Params
$version as xs:string— An EXPath SemVer Template
Returns map(*): A map containing the resolved version, with entries for each identifier ("major", "minor", "patch", "pre-release", and "build-metadata"), and an "identifiers" entry with all identifiers in an array.
semver:resolve-expath-package-semver-template-max($version as xs:string) as map(*)Resolve an EXPath Package SemVer Template as maximum (ceiling)
Params
$version as xs:string— An EXPath SemVer Template
Returns map(*): A map containing the resolved version, with entries for each identifier ("major", "minor", "patch", "pre-release", and "build-metadata"), and an "identifiers" entry with all identifiers in an array.
semver:resolve-expath-package-semver-template($version as xs:string, $mode as xs:string)Resolve an EXPath SemVer Package Template
Params
$version as xs:string— An EXPath Package SemVer Template$mode as xs:string— Mode for resolving the template: "min" (floor) or "max" (ceiling)
semver:satisfies-expath-package-dependency-versioning-attributes(
$version as xs:string,
$versions as xs:string?,
$semver as xs:string?,
$semver-min as xs:string?,
$semver-max as xs:string?
) as xs:booleanCheck if a version satisfies EXPath Package dependency versioning attributes.
Params
$version as xs:string— A version string$versions as xs:string?— An EXPath Package "versions" versioning attribute$semver as xs:string?— An EXPath Package "semver" versioning attribute$semver-min as xs:string?— An EXPath Package "semver-min" versioning attribute$semver-max as xs:string?— An EXPath Package "semver-max" versioning attribute
Returns xs:boolean: True if the version satisfies the attributes, or false if not
semver:serialize(
$major as xs:integer,
$minor as xs:integer,
$patch as xs:integer,
$pre-release as xs:anyAtomicType*,
$build-metadata as xs:anyAtomicType*
)Serialize a SemVer string
Params
$major as xs:integer— The major version$minor as xs:integer— The minor version$patch as xs:integer— The patch version$pre-release as xs:anyAtomicType*— Pre-release identifiers$build-metadata as xs:anyAtomicType*— Build identifiers
semver:serialize($parsed-version as map(*))Serialize a parsed SemVer version (deprecated as of 2.4.0; use semver:serialize-parsed#1)
Params
$parsed-version as map(*)— A map containing the components of the SemVer string
semver:serialize-parsed($parsed-version as map(*))Serialize a parsed SemVer version
Params
$parsed-version as map(*)— A map containing the components of the SemVer string
semver:compare($v1 as xs:string, $v2 as xs:string) as xs:integerCompare two SemVer strings (strictly)
Params
$v1 as xs:string— A version string$v2 as xs:string— A second version string
Returns xs:integer
semver:compare($v1 as xs:string, $v2 as xs:string, $coerce as xs:boolean) as xs:integerCompare two SemVer strings (with an option to coerce invalid SemVer strings)
Params
$v1 as xs:string— A version string$v2 as xs:string— A second version string$coerce as xs:boolean— An option for coercing non-SemVer version strings into parsable form
Returns xs:integer
semver:compare-parsed($parsed-v1 as map(*), $parsed-v2 as map(*)) as xs:integerCompare two parsed SemVer versions
Params
$parsed-v1 as map(*)— A parsed SemVer version$parsed-v2 as map(*)— A second parsed SemVer version
Returns xs:integer
semver:lt($v1 as xs:string, $v2 as xs:string) as xs:booleanTest if v1 is a lower version than v2 (strictly)
Params
$v1 as xs:string— A version string$v2 as xs:string— A second version string
Returns xs:boolean: true if v1 is less than v2
semver:lt($v1 as xs:string, $v2 as xs:string, $coerce as xs:boolean) as xs:booleanTest if v1 is a lower version than v2 (with an option to coerce invalid SemVer strings)
Params
$v1 as xs:string— A version string$v2 as xs:string— A second version string$coerce as xs:boolean— An option for coercing non-SemVer version strings into parsable form
Returns xs:boolean: true if v1 is less than v2
semver:lt-parsed($parsed-v1 as map(*), $parsed-v2 as map(*)) as xs:booleanTest if a parsed v1 is a lower version than a parsed v2
Params
$parsed-v1 as map(*)— A parsed SemVer version$parsed-v2 as map(*)— A second parsed SemVer version
Returns xs:boolean: true if v1 is less than v2
semver:le($v1 as xs:string, $v2 as xs:string) as xs:booleanTest if v1 is a lower version or the same version as v2 (strictly)
Params
$v1 as xs:string— A version string$v2 as xs:string— A second version string
Returns xs:boolean: true if v1 is less than or equal to v2
semver:le($v1 as xs:string, $v2 as xs:string, $coerce as xs:boolean) as xs:booleanTest if v1 is a lower version or the same version as v2 (with an option to coerce invalid SemVer strings)
Params
$v1 as xs:string— A version string$v2 as xs:string— A second version string$coerce as xs:boolean— An option for coercing non-SemVer version strings into parsable form
Returns xs:boolean: true if v1 is less than or equal to v2
semver:le-parsed($parsed-v1 as map(*), $parsed-v2 as map(*)) as xs:booleanTest if a parsed v1 is a lower version or the same version as a parsed v2
Params
$parsed-v1 as map(*)— A parsed SemVer version$parsed-v2 as map(*)— A second parsed SemVer version
Returns xs:boolean: true if v1 is less than or equal to v2
semver:gt($v1 as xs:string, $v2 as xs:string) as xs:booleanTest if v1 is a higher version than v2 (strictly)
Params
$v1 as xs:string— A version string$v2 as xs:string— A second version string
Returns xs:boolean: true if v1 is greater than v2
semver:gt($v1 as xs:string, $v2 as xs:string, $coerce as xs:boolean) as xs:booleanTest if v1 is a higher version than v2 (with an option to coerce invalid SemVer strings)
Params
$v1 as xs:string— A version string$v2 as xs:string— A second version string$coerce as xs:boolean— An option for coercing non-SemVer version strings into parsable form
Returns xs:boolean: true if v1 is greater than v2
semver:gt-parsed($parsed-v1 as map(*), $parsed-v2 as map(*)) as xs:booleanTest if a parsed v1 is a higher version than a parsed v2
Params
$parsed-v1 as map(*)— A parsed SemVer version$parsed-v2 as map(*)— A second parsed SemVer version
Returns xs:boolean: true if v1 is greater than v2
semver:ge($v1 as xs:string, $v2 as xs:string) as xs:booleanTest if v1 is the same or higher version than v2 (strictly)
Params
$v1 as xs:string— A version string$v2 as xs:string— A second version string
Returns xs:boolean: true if v1 is greater than or equal to v2
semver:ge($v1 as xs:string, $v2 as xs:string, $coerce as xs:boolean) as xs:booleanTest if v1 is the same or higher version than v2 (with an option to coerce invalid SemVer strings)
Params
$v1 as xs:string— A version string$v2 as xs:string— A second version string$coerce as xs:boolean— An option for coercing non-SemVer version strings into parsable form
Returns xs:boolean: true if v1 is greater than or equal to v2
semver:ge-parsed($parsed-v1 as map(*), $parsed-v2 as map(*)) as xs:booleanTest if a parsed v1 is the same or higher version than a parsed v2
Params
$parsed-v1 as map(*)— A parsed SemVer version$parsed-v2 as map(*)— A second parsed SemVer version
Returns xs:boolean: true if v1 is greater than or equal to v2
semver:eq($v1 as xs:string, $v2 as xs:string) as xs:booleanTest if v1 is equal to v2 (strictly)
Params
$v1 as xs:string— A version string$v2 as xs:string— A second version string
Returns xs:boolean: true if v1 is equal to v2
semver:eq($v1 as xs:string, $v2 as xs:string, $coerce as xs:boolean) as xs:booleanTest if v1 is equal to v2 (with an option to coerce invalid SemVer strings)
Params
$v1 as xs:string— A version string$v2 as xs:string— A second version string$coerce as xs:boolean— An option for coercing non-SemVer version strings into parsable form
Returns xs:boolean: true if v1 is equal to v2
semver:eq-parsed($parsed-v1 as map(*), $parsed-v2 as map(*)) as xs:booleanTest if a parsed v1 is equal to a parsed v2
Params
$parsed-v1 as map(*)— A parsed SemVer version$parsed-v2 as map(*)— A second parsed SemVer version
Returns xs:boolean: true if v1 is equal to v2
semver:ne($v1 as xs:string, $v2 as xs:string) as xs:booleanTest if v1 is not equal to v2 (strictly)
Params
$v1 as xs:string— A version string$v2 as xs:string— A second version string
Returns xs:boolean: true if v1 is not equal to v2
semver:ne($v1 as xs:string, $v2 as xs:string, $coerce as xs:boolean) as xs:booleanTest if v1 is not equal to v2 (with an option to coerce invalid SemVer strings)
Params
$v1 as xs:string— A version string$v2 as xs:string— A second version string$coerce as xs:boolean— An option for coercing non-SemVer version strings into parsable form
Returns xs:boolean: true if v1 is not equal to v2
semver:ne-parsed($parsed-v1 as map(*), $parsed-v2 as map(*)) as xs:booleanTest if a parsed v1 is not equal to a parsed v2
Params
$parsed-v1 as map(*)— A parsed SemVer version$parsed-v2 as map(*)— A second parsed SemVer version
Returns xs:boolean: true if v1 is not equal to v2
semver:sort($versions as xs:string+) as xs:string+Sort SemVer strings (strictly)
Params
$versions as xs:string+— A sequence of version strings
Returns xs:string+: A sequence of sorted version strings
semver:sort($versions as xs:string*, $coerce as xs:boolean) as xs:string*Sort SemVer strings (with an option to coerce invalid SemVer strings)
Params
$versions as xs:string*— A sequence of version strings$coerce as xs:boolean— An option for coercing non-SemVer version strings into parsable form
Returns xs:string*: A sequence of sorted version strings
semver:sort($items as item()*, $function as function(*), $coerce as xs:boolean) as item()*Sort arbitrary items by their SemVer strings (with an option to coerce invalid SemVer strings)
Params
$items as item()*— A sequence of items to sort$function as function(*)— A function taking a single parameter used to derive a SemVer string from the item$coerce as xs:boolean— An option for coercing non-SemVer version strings into parsable form
Returns item()*: The sequence of items in SemVer order
semver:sort-parsed($parsed-versions as map(*)*) as map(*)*Sort SemVer maps
Params
$parsed-versions as map(*)*— A sequence of SemVer maps, containing entries for each identifier ("major", "minor", "patch", "pre-release", and "build-metadata"), and an "identifiers" entry with all identifiers in an array
Returns map(*)*: A sorted sequence of SemVer maps
Generated by xquerydoc
