stoiridh_version - v0.2.0

stoiridh/version/constraint

A module that contains types and functions to work with version constraints.

Import

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

import stoiridh/version/constraint

Example

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

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

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

  use vc <- result.map(
    constraint.new("^5")
  )

  v1
  |> version.to_string
  |> io.println

  vc
  |> constraint.check(v1)
  |> io.debug
}

5.12.4-alpha.20+49ae79
True

Types

Constraint

opaque </>

A version Constraint type.

The version Constraint type holds all version constraints that will next apply during a check on a version number to verify if it satisfies the version constraint.

pub opaque type Constraint

ConstraintError

</> 
pub type ConstraintError {
  InvalidConstraint
}

Constructors 

  • InvalidConstraint

    The given version constraint does not respect the constraint definition.

Functions

check

</> 
pub fn check(
  this constraint: Constraint,
  with_this version: Version,
) -> Bool

Checks the acceptability of a version against this version constraint.

Example

import gleam/io
import gleam/result

import stoiridh/version
import stoiridh/version/constraint

pub fn main() {
  use vc <- result.map(constraint.new("=1.0.0"))
  use v1 <- result.map(version.parse("1.4.0"))
  use v2 <- result.map(version.parse("2.0.0"))

  vc
  |> constraint.check(v1)
  |> io.debug

  vc
  |> constraint.check(v2)
  |> io.debug
}

False
False

new

</> 
pub fn new(
  constraints: String,
) -> Result(Constraint, ConstraintError)

Creates a new version constraint.

A version constraint contains one or more conditions to check the acceptability of a version.

Operators

When you create a new version constraint, you should specify an operator that will determine, during a check, if a version satisfies the version constraint. If omitted, the version number within the version constraint will implicitly consider as the = operator.

In the table below, the accepted operators that supports the function:

OperatorDescription
=The equal operator will check if a version matches exactly the version constraint.
<The less than operator will check if a version is less than the version constraint.
<=The less than or equal to operator will check if a version is less than or equal to the version constraint.
>The greater than operator will check if a version is greater than the version constraint.
>=The greater than or equal to operator will check if a version is greater than or equal to the version constraint.
^The caret operator will check for compatible updates to a specified version.
~The tilde operator will check for patch updates to a specified version.

The = operator

As you may expect, the equal operator should strictly check the equivalence of a version compared to a version constraint. But it did not. Indeed, when a version constraint is partial or have a wildcard, some logical rules are applied to make sure you match a range of potential versions:

Version ConstraintEquivalent ToRule
=1 or =1.x>=1.0.0 <2.0.0>=I.0.0 <(I+1).0.0
=1.1 or =1.1.x>=1.1.0 <1.2.0>=I.J.0 <I.(J+1).0
=1.1.1=1.1.1=I.J.K

Special Case: Wildcard in Major Version Number Constraint

Putting a wildcard in a major version number part is prohibited whatever the operators. However, this function only accepts a wildcard for the = operator as it make sense to want the latest version available for a package, as an example, whatever the reason behind.

Version ConstraintEquivalent To
*>=0.0.0
=*>=0.0.0

The ^ operator

The caret operator allows finding compatible updates to a specified version:

Version ConstraintEquivalent ToRule
^0 or ^0.x>=0.0.0 <1.0.0>=I.0.0 <(I+1).0.0
^1 or ^1.x>=1.0.0 <2.0.0>=I.0.0 <(I+1).0.0
^0.5 or ^0.5.x>=0.5.0 <0.6.0>=0.J.0 <0.(J+1).0
^1.1 or ^1.1.x>=1.1.0 <2.0.0>=I.J.0 <(I+1).0.0
^0.0.7=0.0.7=0.0.K
^1.1.0>=1.1.0 <2.0.0>=I.J.0 <(I+1).0.0

The ~ operator

The tilde operator allows finding patch updates to a specified version:

Version ConstraintEquivalent ToRule
~0 or ~0.x>=0.0.0 <1.0.0>=0.0.0 <(I+1).0.0
~1 or ~1.x>=1.0.0 <2.0.0>=I.0.0 <(I+1).0.0
~0.5 or ~0.5.x>=0.5.0 <0.6.0>=0.J.0 <0.(J+1).0
~1.1 or ~1.1.x>=1.1.0 <1.2.0>=I.J.0 <I.(J+1).0
~0.0.7>=0.0.7 <0.1.0>=0.0.K <0.(J+1).0
~1.1.0>=1.1.0 <1.2.0>=I.J.0 <I.(J+1).0

Wildcard and Partial Version Number within Version Constraints

Unlike version.new, a version constraint may contain wildcards or be partial.

Wildcard

This function supports three kinds of wildcards: *, x, and X. A wildcard allows you to not specify the part of a version number.

However, keep in mind it is strictly prohibited from putting a wildcard into a major version part. Except if and only if the definition of the version constraint is "*" or "=*".

Example

import gleam/io
import gleam/result

import stoiridh/version
import stoiridh/version/constraint

pub fn main() {
  use vc <- result.map(constraint.new("=1.*"))
  use v1 <- result.map(version.parse("1.4.0"))
  use v2 <- result.map(version.parse("2.0.0"))

  vc
  |> constraint.check(v1)
  |> io.debug

  vc
  |> constraint.check(v2)
  |> io.debug
}

True
False
✨ Search Document