stoiridh/version

A module that contains types and functions to work with Semantic Versioning.

Semantic Versioning (see https://semver.org/) is a specification that proposes a simple set of rules and requirements that dictate how version numbers are assigned and incremented.

NOTE: This module follows the Semantic Versioning specification 2.0.

Import

To import the types and functions of this module, add the following import statement in your gleam files:

import stoiridh/version

Example

This brief example gives an overview on how to use this module:

import gleam/io
import gleam/result
import stoiridh/version

pub fn main() {
  use v1 <- result.map(
    version.new(5, 12, 4)
    |> version.with_prerelease("alpha.20")
    |> version.with_build_metadata("49ae79"),
  )

  use v2 <- result.map(
    version.new(8, 0, 0)
    |> version.with_build_metadata("dev"),
  )

  v1
  |> version.to_string
  |> io.println

  v2
  |> version.to_string
  |> io.println

  v1
  |> version.compare(v2)
  |> io.debug
}

5.12.4-alpha.20+49ae79
8.0.0+dev
Lt

Types

Version

opaque </>

A Version type.

The Version type holds the values for constructing a semantic version.

pub opaque type Version

VersionError

</>

A type that holds errors when interacting with Semantic Versioning.

pub type VersionError {
  InvalidVersion
  InvalidMajorVersion
  InvalidMinorVersion
  InvalidPatchVersion
  InvalidPrerelease
  InvalidBuildMetadata
  NegativeValue(String)
}

Constructors

```
InvalidVersion
```
The version isn’t valid.

An invalid version may be the result of an empty string or the failure of parsing a character as a digit for any major, minor, or patch version numbers.
```
InvalidMajorVersion
```
The major version number isn’t valid.

This error raises when the parse function failed to parse the major version number.
```
InvalidMinorVersion
```
The minor version number isn’t valid.

This error raises when the parse function failed to parse the minor version number.
```
InvalidPatchVersion
```
The patch version number isn’t valid.

This error raises when the parse function failed to parse the patch version number.
```
InvalidPrerelease
```
The pre-release version isn’t valid.

A valid pre-release version is a series of dot separated identifiers. Identifiers must comprise only ASCII alphanumerics and hyphens [A-Za-z0-9-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes.
```
InvalidBuildMetadata
```
The build metadata isn’t valid.

A valid build metadata is a series of dot separated identifiers. Identifiers must comprise only ASCII alphanumerics and hyphens [A-Za-z0-9-]. Identifiers MUST NOT be empty.
```
NegativeValue(String)
```
Constructs a negative value error.

This error is emitted when the version contains any negative value.

Functions

build_metadata

</>

pub fn build_metadata(version: Version) -> Option(String)

Returns the build metadata of the version.

Example

use v <- result.map(
  version.new(1, 0, 18)
  |> version.with_build_metadata("ae93d74"),
)

v
|> version.build_metadata

Some("ae93d74")

compare

</>

pub fn compare(a: Version, b: Version) -> Order

Compares two versions.

The comparison of two versions a and b is carried out in two logical steps.

The first step consists of comparing numerically the fields major, minor, and patch to find a difference. If the comparison results in equality, then we will proceed to the second step if and only if there is a presence of a pre-release label in either one or both versions.

The second step consists of comparing each dot separated identifier of the pre-release label from both versions a and b until a difference is found. If a version has’nt a pre-release label, then it will have a higher precedence than the other.

Example: 1.2.3-alpha.1 < 1.2.3.

Example

use v1 <- result.map(version.new(1, 15, 0))
use v2 <- result.map(version.new(0, 30, 5))

v1
|> version.compare(v2)

order.Gt

Precedence

Precedence for two pre-release versions with the same major, minor and patch field consists of comparing each dot separated identifier from left to right until a difference is found.

Identifiers consisting of only digits are compared numerically.
Identifiers with letters or hyphens are compared lexically in ASCII sort order.
Numeric identifiers always have a lower precedence than non-numeric identifiers.
A larget set of identifiers will always have a higher precedence than a smaller set if and only if all of the preceding identifiers are equal.

If there is no precedence and both versions are exactly the same, then the function will return order.Eq.

use v <- result.map(
  version.new(1, 0, 0)
  |> version.with_prerelease("alpha.1.beta.2.gamma.3.---"),
)

v
|> version.compare(v)

order.Eq

Precedence and Build Metadata

According to the specification, the build-metadata label is ignored during the comparison.

use v1 <- result.map(
  version.new(1, 15, 0)
  |> version.with_prerelease("alpha.1")
  |> version.with_build_metadata("aef1678"),
)

use v2 <- result.map(
  version.new(1, 15, 0)
  |> version.with_prerelease("alpha.1"),
)

v1
|> version.compare(v2)
|> should.equal(order.Eq)

order.Eq

major

</>

pub fn major(version: Version) -> Int

Returns the major version.

Example

use v <- result.map(version.new(1, 0, 18))

v
|> version.major

minor

</>

pub fn minor(version: Version) -> Int

Returns the minor version.

Example

use v <- result.map(version.new(1, 0, 18))

v
|> version.minor

new

</>

pub fn new(
  major: Int,
  minor: Int,
  patch: Int,
) -> Result(Version, VersionError)

Creates a new semantic version.

Any negative values on major, minor, or patch will result as an error.

parse

</>

pub fn parse(from input: String) -> Result(Version, VersionError)

Creates a new semantic version from a String representation.

Add or Override Pre-release and Build Metadata Labels.

You can also use with_prerelease and with_build_metadata after parsing a version successfully to whether add or override the pre-release and build metadata labels, respectively.

Example

use v <- result.map(
  version.parse("1.0.0-alpha.1")
  |> version.with_prerelease("beta.2")
  |> version.with_build_metadata("dev")
)

v
|> version.to_string
|> io.println

1.0.0-beta.2+dev

patch

</>

pub fn patch(version: Version) -> Int

Returns the patch version.

Example

use v <- result.map(version.new(1, 0, 18))

v
|> version.patch

prerelease

</>

pub fn prerelease(version: Version) -> Option(String)

Returns the pre-release version.

Example

use v <- result.map(
  version.new(1, 0, 18)
  |> version.with_prerelease("alpha.1"),
)

v
|> version.prerelease

Some("alpha.1")

to_string

</>

pub fn to_string(version: Version) -> String

Converts a Version to a String.

Example

use v <- result.map(
  version.new(1, 0, 18)
  |> version.with_prerelease("beta.8")
  |> version.with_build_metadata("dff999"),
)

v
|> version.to_string
|> io.println

1.0.1-beta.8+dff999

with_build_metadata

</>

pub fn with_build_metadata(
  version: Result(Version, VersionError),
  build_metadata: String,
) -> Result(Version, VersionError)

Appends a build metadata to version.

Build metadata are additional information that are ignored during version precedence. Examples: 1.0.0+a10234ff, 1.0.0+a10234ff.001, 1.0.0-alpha.1+bc632df.

Error

If build_metadata is not valid, the InvalidBuildMetadata error will return.

Example

use v <- result.map(
  version.new(1, 0, 18)
  |> version.with_build_metadata("ae93d74"),
)

with_prerelease

</>

pub fn with_prerelease(
  version: Result(Version, VersionError),
  prerelease: String,
) -> Result(Version, VersionError)

Appends a pre-release to version.

A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--.

Error

If prerelease is not valid, then the InvalidPrerelease error will return.

Example

use v <- result.map(
  version.new(1, 0, 18)
  |> version.with_prerelease("alpha.1"),
)