nextver

A library for parsing and incrementing arbitrarily-formatted versions.

Instead of conforming to a specific versioning scheme, this library allows you to define your own version format, parse version strings against it, and increment versions according to semantic and/or calendar rules.

Also comes with a CLI.

This an abridged version of the documentation. For the full documentation, see docs.rs.

Example

Below, the text in < and > brackets is a specifier. See what they mean here.

Quickly get a next version:

use nextver::prelude::*;

let next = Sem::next_version_string(
  "<MAJOR>.<MINOR>.<PATCH>",  // format string
  "1.2.3",                    // current version string
  SemLevel::Minor             // the specifier to increment
)?;
assert_eq!(next, "1.3.0");

API Overview

nextver is built around three main concepts: Schemes, formats, and versions.

• Schemes dictate the kinds of values allowed in versions and the rules for incrementing them. (See the table below.) They are modeled by the [Scheme] trait and implemented by the the following structs:

  • [Sem]: A semantic versioning scheme. It is similar to SemVer.
  • [CalSem]: A calendar-semantic versioning scheme. It is similar to CalVer, but with an explicitly-required semantic part(s).
  • [Cal]: A calendar versioning scheme. Its like [CalSem] but without semantic specifiers. (This scheme is less useful in practice because there is no way to increment a version twice within the same period of its least significant specifier.)

• Formats define the structure of a version string. They are modeled by the [Format] struct. They contains a sequence of specifier and literal text tokens. For example, <MAJOR>.<MINOR>.<PATCH> is a format string that can be turned into a [Format] object.

• Versions are like Formats, but with actual values instead of specifiers. They represent a a point in a project's development. These are modeled by the [Version] struct. They can be incremented to new versions and compared amongst each other.

Format String Syntax

Use any sequence of specifiers (listed below) and literal text in a format string. Specifiers are bracketed with < and >.

Table

In the "Example" column below, we reference a major of 1, minor of 2, patch of 3 and a date of 2001-02-03 (which is in the 4th week).

Specifier	Example	Sem	CalSem	Cal	Parse Width	Format Width	Description
<MAJOR>	1	✅	❌	❌	>=1	None	The major part of a version
<MINOR>	2	✅	✅	❌	>=1	None	The minor part of a version
<PATCH>	3	✅	✅	❌	>=1	None	The patch part of a version
<YYYY>	2001	❌	✅	✅	>=1	None	Full year, years less than 1 BCE are unsupported (0 refers to 1 BCE)
<YY>	1	❌	✅	✅	>=1	None	Year minus 2000. For now, has same effect as year % 100, but the year 2100 will be 100, and so on
<0Y>	01	❌	✅	✅	>=2	2	Same as YY but zero-padded
<MM>	1	❌	✅	✅	1 or 2	None	Month of year (1–12)
<0M>	01	❌	✅	✅	2	2	Same as MM but zero-padded
<WW>	4	❌	✅	✅	1 or 2	None	Week of the year (0–53), week 1 starts with the first Sunday in that year.
<0W>	04	❌	✅	✅	2	2	Same as WW but zero-padded
<DD>	3	❌	✅	✅	1 or 2	None	Day of the month (1–31)
<0D>	03	❌	✅	✅	2	2	Same as DD but zero-padded

Specifiers are case-sensitive. For example, <major> is not a valid specifier.

CLI

This crate provides a CLI that can be used to do some API functions straight from the command line.

Installation

cargo install nextver

Usage

nextver --help

DevOps

To:

• create and push a new git tag,
• create a new GitHub release with binaries attached, and
• publish a new version to https://crates.io (and update docs on https://docs.rs)

simply push a commit to the master branch with an updated version number in Cargo.toml. The workflow file at .github/workflows/release+build+publish.yml will take care of the rest. Make sure to pull afterwards.