Semver: Semantic Versioning

7.7

top ← prev up next →

Semver: Semantic Versioning

package: semver

The semver specification provides a standardized way to represent version information in a semantic way that can be used for smart and effective dependency management. By using a standardized, machine-readable format for parsing versions and specifying version ranges, dependency managers can automatically select patched versions of software without introducing breaking changes.

The original semver specification imposes very strict rules about what version numbers must mean. In practice, this is not always practical, but following the guidelines loosely allows for the most benefit. The ferver specification describes a reinterpretation of the semver rules while still being compatible with semver’s format, so it can still be used with this library.

procedure
(semver-version? version) → Boolean
version : String

Checks to see if a string represents a valid semver version.

A semver version is composed of three numbers separated by dots, the major, minor, and patch version numbers. When comparing version numbers, these values are compared in order, and earlier numbers take precedence.

Additionally, a pre-release label may be appended to the version by adding a hyphen, then including an arbitrary number of dot-delimited groups. The contents of the groups must be limited to ASCII numbers and letters and hypens ([0-9A-Za-z]). The groups are used in version comparisons similarly to the main version numbers. Groups that contain non-numeric characters are compared lexicographically (ASCII ordering), while those that are strictly numeric are compared as integers.

Furthermore, build metadata may be included at the end of the string. Build metadata takes the same form as pre-release labels, but it is indicated using a + instead of a hyphen. However, build metadata is always ignored in all version operations.

The following are all examples of well-formed version strings:

"0.0.0"
"1.2.3"
"11.905.67"
"2.0.3-beta.0"
"2.0.3-pre-alpha.1.2"
"2.0.3+b.1056"
"2.0.3-pre-alpha.1.2+b.1056"

procedure
(semver-comparator? comparator) → Boolean
comparator : String

Checks to see if a string represents a valid semver comparator. A comparator is a single version constraint. It may be composed of an optional operation as well as information about the versions to match. All of the following are valid comparators:

"*"
"1.2.3"
">=1.2.3"
"~1.2.3"
"~1.2"
"^0.2.4"
"<2.0.0"

For information about the semantics of the different comparators, see node-semver.

procedure
(semver-range? range) → Boolean
range : String

Checks to see if a string represents a valid semver range. A range is simply a string containing multiple comparators separated by whitespace. The comparators will be matched against a version using AND. If a group of comparators is separated by ||, then they will be matched using OR.

procedure
(semver-version=? a b) → Boolean
  a : String
  b : String
(semver-version<? a b) → Boolean
  a : String
  b : String
(semver-version>? a b) → Boolean
  a : String
  b : String
(semver-version<=? a b) → Boolean
  a : String
  b : String
(semver-version>=? a b) → Boolean
  a : String
  b : String

Performs various comparisons on semver version strings. Raises an exception if either parameter does not satisfy semver-version?.

procedure
(semver-version-within-range? version
range) → Boolean
version : String
range : String

Determines whether or not a particular version falls within a given range. If version does not satisfy semver-version? or if range does not satisfy semver-range?, then this function raises an exception.

procedure
(semver-maximum-version-within-range versions
range)
→ (Option String)
versions : (Listof String)
range : String

Given a list of versions and a version range, this finds the maximum version that satisfies the given range. If no such version exists, it returns #f.

If any of the versions do not satisfy semver-version? or if range does not satisfy semver-range?, then this function raises an exception.

top ← prev up next →