semver: Basics

John D Harrison

2017-01-02

The goal of this vignette is to describe the basic functionality of the semver package.

Introduction

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 semantiv versioning operates is given a version number MAJOR.MINOR.PATCH, increment the:

  1. MAJOR version when you make incompatible API changes,
  2. MINOR version when you add functionality in a backwards-compatible manner, and
  3. PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

semver package

The 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).

All the functions

parse_version

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
## [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.10
str(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"

render_version

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)])
## [[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 ""

Comparing versions

The parse_version function returns a list of svptr objects. These svptr objects represent the semantic versions. We can do comparisons like:

svptr Ops

sem_versions[[1]] <= sem_versions[[5]]
## [1] TRUE
sem_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] TRUE

Summary of svlist objects

You can get the min, max and range of the versions

min(sem_versions)
## Maj: 1 Min: 0 Pat: 0 Pre: alpha
max(sem_versions)
## Maj: 2 Min: 1 Pat: 3
range(sem_versions)
## [1] Maj: 1 Min: 0 Pat: 0 Pre: alpha
## 
## [2] Maj: 2 Min: 1 Pat: 3

Sort, Order and rank an svlist

You 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: 3
order(sem_versions)
## [1] 3 4 1 6 5 2
rank(sem_versions)
## [1] 3.0 6.0 1.5 1.5 5.0 4.0

Ops on svlist

You 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  TRUE

Compare to character strings

Sometimes 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  TRUE
sem_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.10