The goal of this vignette is to describe the basic functionality of thesemver package.
Thesemver package provides tools and functions for parsing, rendering and operating on semantic version strings. Semantic versioning is a simple set of rules and requirements that dictate how version numbers are assigned and incremented as outlined athttp://semver.org.
A basic summary of how semantic versioning operates is given a version number MAJOR.MINOR.PATCH, increment the:
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
semver packageThesemver package provides a wrapper for the C++14 semantic versioning parser written by Marko Živanović. The project is currently hosted ongithub. TheRcpp package was used to provide R bindings. Some changes were made on the C++ side as currently CRAN does not accept packages compiling under C++14 (R version 3.4.0 should allow this in future).
Theparse_version function parses a character vector containing valid semantic versioning strings returning an “svlist” object.
library(semver)examples <-c("1.0.0","2.1.3","1.0.0-alpha","1.0.0-alpha+1.2","1.8.2-beta.1.13","1.8.2-beta.1.10")sem_versions <-parse_version(examples)sem_versions## [1] Maj: 1 Min: 0 Pat: 0## ## [2] Maj: 2 Min: 1 Pat: 3## ## [3] Maj: 1 Min: 0 Pat: 0 Pre: alpha## ## [4] Maj: 1 Min: 0 Pat: 0 Pre: alpha Bld: 1.2## ## [5] Maj: 1 Min: 8 Pat: 2 Pre: beta.1.13## ## [6] Maj: 1 Min: 8 Pat: 2 Pre: beta.1.10str(sem_versions)## List of 6## $ :Class 'svptr' <externalptr> ## $ :Class 'svptr' <externalptr> ## $ :Class 'svptr' <externalptr> ## $ :Class 'svptr' <externalptr> ## $ :Class 'svptr' <externalptr> ## $ :Class 'svptr' <externalptr> ## - attr(*, "class")= chr "svlist"Therender_version function acts on an “svptr”/“svlist” object. It returns an R list/(list of lists) giving the major, minor and patch version as an integer and the prerelease and build version as a charcter
render_version(sem_versions[c(1,4)])## [[1]]## [[1]]$major## [1] 1## ## [[1]]$minor## [1] 0## ## [[1]]$patch## [1] 0## ## [[1]]$prerelease## [1] ""## ## [[1]]$build## [1] ""## ## ## [[2]]## [[2]]$major## [1] 1## ## [[2]]$minor## [1] 0## ## [[2]]$patch## [1] 0## ## [[2]]$prerelease## [1] "alpha"## ## [[2]]$build## [1] "1.2"render_version(sem_versions[[5]])## $major## [1] 1## ## $minor## [1] 8## ## $patch## [1] 2## ## $prerelease## [1] "beta.1.13"## ## $build## [1] ""str(render_version(sem_versions[[5]]))## List of 5## $ major : int 1## $ minor : int 8## $ patch : int 2## $ prerelease: chr "beta.1.13"## $ build : chr ""Theparse_version function returns a list ofsvptr objects. Thesesvptr objects represent the semantic versions. We can do comparisons like:
sem_versions[[1]] <=sem_versions[[5]]## [1] TRUEsem_versions[[1]] >sem_versions[[5]]## [1] FALSE# compare example 5, 6 (pre-release ordering matters)sem_versions[[5]] >sem_versions[[6]]## [1] TRUE# compare example 3, 4 (build order does not matter)sem_versions[[3]] ==sem_versions[[4]]## [1] TRUEYou can get the min, max and range of the versions
min(sem_versions)## Maj: 1 Min: 0 Pat: 0 Pre: alphamax(sem_versions)## Maj: 2 Min: 1 Pat: 3range(sem_versions)## [1] Maj: 1 Min: 0 Pat: 0 Pre: alpha## ## [2] Maj: 2 Min: 1 Pat: 3You can sort, order and rank the versions:
sort(sem_versions)## [1] Maj: 1 Min: 0 Pat: 0 Pre: alpha## ## [2] Maj: 1 Min: 0 Pat: 0 Pre: alpha Bld: 1.2## ## [3] Maj: 1 Min: 0 Pat: 0## ## [4] Maj: 1 Min: 8 Pat: 2 Pre: beta.1.10## ## [5] Maj: 1 Min: 8 Pat: 2 Pre: beta.1.13## ## [6] Maj: 2 Min: 1 Pat: 3order(sem_versions)## [1] 3 4 1 6 5 2rank(sem_versions)## [1] 3.0 6.0 1.5 1.5 5.0 4.0You can also compare “svlist” objects. If the lengths of the two lists are unequal recycling occurs:
sem_versions >sem_versions[1]## [1] FALSE TRUE FALSE FALSE TRUE TRUESometimes it can be useful to compare a parsed vector of semantic versions to a character string:
sem_versions > "1.1.0-beta"## [1] FALSE TRUE FALSE FALSE TRUE TRUEsem_versions[sem_versions > "1.1.0-beta"]## [1] Maj: 2 Min: 1 Pat: 3## ## [2] Maj: 1 Min: 8 Pat: 2 Pre: beta.1.13## ## [3] Maj: 1 Min: 8 Pat: 2 Pre: beta.1.10If you want to change or ammend the major, minor, patch, prerelease or build fields the semver package provides a number of methods to achieve this.
Theset_version method operates onsvptr andsvlist classes. It simply changes the indicated field to the value given. Other fields in the version are unaffected.
For thesvptr class theset_version method takes a character string argumentfield which indicates which field (major, minor etc.) to change. Thevalue argument is an integer scalar when field is major, minor or patch and a character string when prerelease or build.
library(semver)examples <-c("1.0.0","2.1.3","1.0.0-alpha","1.0.0-alpha+1.2","1.8.2-beta.1.13","1.8.2-beta.1.10")sem_versions <-parse_version(examples)set_version(sem_versions[[1]],"major", 2L)## Maj: 2 Min: 0 Pat: 0set_version(sem_versions[[1]],"minor", 1L)## Maj: 1 Min: 1 Pat: 0set_version(sem_versions[[1]],"patch", 1L)## Maj: 1 Min: 0 Pat: 1set_version(sem_versions[[4]],"prerelease","beta")## Maj: 1 Min: 0 Pat: 0 Pre: beta Bld: 1.2set_version(sem_versions[[4]],"build","bld1a")## Maj: 1 Min: 0 Pat: 0 Pre: alpha Bld: bld1aNote that changing a field with the set_version method does not change any other field.
As syntactic sugar for assigning usingset_version there is a dollar assignment method for svptr classes so the following are equivalent waysto assign fields:
sem_versions[[1]] <-set_version(sem_versions[[1]],"major", 3L)sem_versions[[1]]## Maj: 3 Min: 0 Pat: 0# Syntactic sugarsem_versions[[1]]$minor <-2Lsem_versions[[1]]## Maj: 3 Min: 2 Pat: 0Forsvlist classes theset_version method expects a character vector for thefield argument. Thevalue argument is expected to be a list with integer and character elements assigning to (major, minor, patch)/(prerelease, build) fields respectively. If either the length of the field or values argeument is shorter than the number of elements in thesvlist then recycling occurs.
examples <-c("1.0.0","1.8.2-beta.1.10","2.4.6-8")sem_versions <-parse_version(examples)# recycling on the field argumentset_version(sem_versions,"major",list(2L, 4L, 6L))## [1] Maj: 2 Min: 0 Pat: 0## ## [2] Maj: 4 Min: 8 Pat: 2 Pre: beta.1.10## ## [3] Maj: 6 Min: 4 Pat: 6 Pre: 8# recycling on the value argumentset_version(sem_versions,c("major","minor","patch"),list(7L))## [1] Maj: 7 Min: 0 Pat: 0## ## [2] Maj: 1 Min: 7 Pat: 2 Pre: beta.1.10## ## [3] Maj: 2 Min: 4 Pat: 7 Pre: 8# assigning integer and character valuesset_version(sem_versions,c("prerelease","minor","build"),list("alpha", 3L,"build1.12"))## [1] Maj: 1 Min: 0 Pat: 0 Pre: alpha## ## [2] Maj: 1 Min: 3 Pat: 2 Pre: beta.1.10## ## [3] Maj: 2 Min: 4 Pat: 6 Pre: 8 Bld: build1.12Thereset_version method operates onsvptr andsvlist classes. It changes the indicated field to the value given. Fields with lower precedence are set to default values:
MAJOR(0L) > MINOR (0L) > PATCH (0L) > PRERELEASE ("") > BUILD ("")Thereset_version method forsvptr classes operates similarly to theset_version method with fields of lower precedence being set to default values:
examples <-c("1.8.2-beta.1.10+somebuild","2.4.6-8")sem_versions <-parse_version(examples)reset_version(sem_versions[[1]],"major", 2L)## Maj: 2 Min: 0 Pat: 0reset_version(sem_versions[[1]],"minor", 3L)## Maj: 1 Min: 3 Pat: 0reset_version(sem_versions[[1]],"patch", 4L)## Maj: 1 Min: 8 Pat: 4reset_version(sem_versions[[1]],"prerelease","gamma")## Maj: 1 Min: 8 Pat: 2 Pre: gammareset_version(sem_versions[[1]],"build","superbuild")## Maj: 1 Min: 8 Pat: 2 Pre: beta.1.10 Bld: superbuildThereset_version method forsvlist classes operates similarly to theset_version method with fields of lower precedence being set to default values. Again recycling of elements occur if the length of the field/value argument is shorter than the number of elements in thesvlist:
examples <-c("1.8.2-beta.1.10+somebuild","2.4.6-8")sem_versions <-parse_version(examples)# recycling on both argumentsreset_version(sem_versions,"major",list(3L))## [1] Maj: 3 Min: 0 Pat: 0## ## [2] Maj: 3 Min: 0 Pat: 0# recycling on field argumentreset_version(sem_versions,"minor",list(3L, 4L))## [1] Maj: 1 Min: 3 Pat: 0## ## [2] Maj: 2 Min: 4 Pat: 0# recycling on value argumentreset_version(sem_versions,c("major","patch"),list(4L))## [1] Maj: 4 Min: 0 Pat: 0## ## [2] Maj: 2 Min: 4 Pat: 4# assigning integer and character fieldsreset_version(sem_versions,c("prerelease","minor"),list("zeta", 7L))## [1] Maj: 1 Min: 8 Pat: 2 Pre: zeta## ## [2] Maj: 2 Min: 7 Pat: 0Theincrement_version method operates onsvptr andsvlist classes. It increments the given field with the provided value. Fields of lower precedence are set to default value.
Only major, minor and patch field can be incremented
To decrement a field provide a negative integer as the value argument
Theincrement_version method forsvptr classes increments the chosen field with the given value with fields of lower precedence being set to default values:
examples <-c("1.8.2-beta.1.10+somebuild","2.4.6-8")sem_versions <-parse_version(examples)# incrementing versionsincrement_version(sem_versions[[1]],"major", 1L)## Maj: 2 Min: 0 Pat: 0increment_version(sem_versions[[1]],"minor", 2L)## Maj: 1 Min: 10 Pat: 0increment_version(sem_versions[[1]],"patch", 3L)## Maj: 1 Min: 8 Pat: 5# decrementing versionsincrement_version(sem_versions[[1]],"major", -1L)## Maj: 0 Min: 0 Pat: 0increment_version(sem_versions[[1]],"minor", -2L)## Maj: 1 Min: 6 Pat: 0increment_version(sem_versions[[1]],"patch", -2L)## Maj: 1 Min: 8 Pat: 0Theincrement_version method forsvlist classes takes a character vector as argumentfield and an integer vector as argumentvalue. Recycling occurs as forset_version/reset_version methods:
examples <-c("1.8.2-beta.1.10+somebuild","2.4.6-8")sem_versions <-parse_version(examples)## Incrementing# recycling on both argumentsincrement_version(sem_versions,"major", 3L)## [1] Maj: 4 Min: 0 Pat: 0## ## [2] Maj: 5 Min: 0 Pat: 0# recycling on field argumentincrement_version(sem_versions,"minor",c(3L, 4L))## [1] Maj: 1 Min: 11 Pat: 0## ## [2] Maj: 2 Min: 8 Pat: 0# recycling on value argumentincrement_version(sem_versions,c("major","patch"), 4L)## [1] Maj: 5 Min: 0 Pat: 0## ## [2] Maj: 2 Min: 4 Pat: 10## Decrementing# recycling on both argumentsincrement_version(sem_versions,"major", -1L)## [1] Maj: 0 Min: 0 Pat: 0## ## [2] Maj: 1 Min: 0 Pat: 0# recycling on field argumentincrement_version(sem_versions,"minor",c(-3L, -4L))## [1] Maj: 1 Min: 5 Pat: 0## ## [2] Maj: 2 Min: 0 Pat: 0# recycling on value argumentincrement_version(sem_versions,c("minor"), -4L)## [1] Maj: 1 Min: 4 Pat: 0## ## [2] Maj: 2 Min: 0 Pat: 0