The goal of this vignette is to describe the basic functionality of the
semver
package.
The semver
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 at http://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
packageThe semver
package provides a wrapper for the C++14 semantic versioning parser
written by Marko Živanović. The project is currently hosted on
github. The Rcpp 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).
The parse_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 str(sem_versions)
The render_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)]) render_version(sem_versions[[5]]) str(render_version(sem_versions[[5]]))
The parse_version
function returns a list of svptr
objects. These svptr
objects represent the semantic versions. We can do comparisons like:
sem_versions[[1]] <= sem_versions[[5]] sem_versions[[1]] > sem_versions[[5]] # compare example 5, 6 (pre-release ordering matters) sem_versions[[5]] > sem_versions[[6]] # compare example 3, 4 (build order does not matter) sem_versions[[3]] == sem_versions[[4]]
You can get the min, max and range of the versions
min(sem_versions) max(sem_versions) range(sem_versions)
You can sort, order and rank the versions:
sort(sem_versions) order(sem_versions) rank(sem_versions)
You can also compare "svlist" objects. If the lengths of the two lists are unequal recycling occurs:
sem_versions > sem_versions[1]
Sometimes it can be useful to compare a parsed vector of semantic versions to a character string:
sem_versions > "1.1.0-beta" sem_versions[sem_versions > "1.1.0-beta"]
If 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.
The set_version
method operates on svptr
and svlist
classes. It
simply changes the indicated field to the value given. Other fields in the
version are unaffected.
For the svptr
class the set_version
method takes a character string
argument field
which indicates which field (major, minor etc.) to change.
The value
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) set_version(sem_versions[[1]], "minor", 1L) set_version(sem_versions[[1]], "patch", 1L) set_version(sem_versions[[4]], "prerelease", "beta") set_version(sem_versions[[4]], "build", "bld1a")
Note that changing a field with the set_version method does not change any other field.
As syntactic sugar for assigning using set_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]] # Syntactic sugar sem_versions[[1]]$minor <- 2L sem_versions[[1]]
For svlist
classes the set_version
method expects a character vector
for the field
argument. The value
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 the svlist
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 argument set_version(sem_versions, "major", list(2L, 4L, 6L)) # recycling on the value argument set_version(sem_versions, c("major", "minor", "patch"), list(7L)) # assigning integer and character values set_version(sem_versions, c("prerelease", "minor", "build"), list("alpha", 3L, "build1.12"))
The reset_version
method operates on svptr
and svlist
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 ("")
The reset_version
method for svptr
classes operates similarly to the
set_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) reset_version(sem_versions[[1]], "minor", 3L) reset_version(sem_versions[[1]], "patch", 4L) reset_version(sem_versions[[1]], "prerelease", "gamma") reset_version(sem_versions[[1]], "build", "superbuild")
The reset_version
method for svlist
classes operates similarly to the
set_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 the svlist
:
examples <- c("1.8.2-beta.1.10+somebuild", "2.4.6-8") sem_versions <- parse_version(examples) # recycling on both arguments reset_version(sem_versions, "major", list(3L)) # recycling on field argument reset_version(sem_versions, "minor", list(3L, 4L)) # recycling on value argument reset_version(sem_versions, c("major", "patch"), list(4L)) # assigning integer and character fields reset_version(sem_versions, c("prerelease", "minor"), list("zeta", 7L))
The increment_version
method operates on svptr
and svlist
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
The increment_version
method for svptr
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 versions increment_version(sem_versions[[1]], "major", 1L) increment_version(sem_versions[[1]], "minor", 2L) increment_version(sem_versions[[1]], "patch", 3L) # decrementing versions increment_version(sem_versions[[1]], "major", -1L) increment_version(sem_versions[[1]], "minor", -2L) increment_version(sem_versions[[1]], "patch", -2L)
The increment_version
method for svlist
classes takes a character vector
as argument field
and an integer vector as argument value
. Recycling occurs
as for set_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 arguments increment_version(sem_versions, "major", 3L) # recycling on field argument increment_version(sem_versions, "minor", c(3L, 4L)) # recycling on value argument increment_version(sem_versions, c("major", "patch"), 4L) ## Decrementing # recycling on both arguments increment_version(sem_versions, "major", -1L) # recycling on field argument increment_version(sem_versions, "minor", c(-3L, -4L)) # recycling on value argument increment_version(sem_versions, c("minor"), -4L)
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.