ddn.var.semver¶

Overview¶

The ddn.var.semver module provides a robust, full-featured Semantic Versioning (SemVer) implementation for the D programming language. It enables parsing, comparison, stringification, and manipulation of semantic version numbers, following the official SemVer specification.

Installation¶

To use ddn.var.semver, ensure your project depends on the DDN library. If using DUB, add the following to your dub.sdl or dub.json:

dependency "ddn" version=">=1.0.0"

Then, import the module in your D code:

import ddn.var.semver;

Usage¶

Typical usage involves parsing version strings, comparing versions, and manipulating version components:

import ddn.var.semver;

void main() {
    // Parse a version string
    auto v = SemVer.parse("1.2.3-alpha.1+build.5");

    // Access components
    assert(v.major == 1);
    assert(v.minor == 2);
    assert(v.patch == 3);
    assert(v.prerelease == ["alpha", "1"]);
    assert(v.build == ["build", "5"]);

    // Compare versions
    auto v2 = SemVer.parse("1.2.3");
    assert(v < v2);

    // Bump version
    auto v3 = v.bumpMinor();
    assert(v3.toString() == "1.3.0");
}

API Reference¶

Module¶

module ddn.var.semver;

Struct: `SemVer`¶

Represents a semantic version according to semver.org.

Fields¶

uint major — Major version (non-negative integer)
uint minor — Minor version (non-negative integer)
uint patch — Patch version (non-negative integer)
string[] prerelease — Pre-release identifiers (if any), in order
string[] build — Build metadata identifiers (if any), in order

Constructors¶

this(uint major, uint minor, uint patch, string[] prerelease = [], string[] build = [])
Constructs a SemVer from its components.

Static Methods¶

static SemVer parse(string verstr)
Parses a version string into a SemVer object.
Throws: SemVerParseException if the string is not a valid semantic version.

Methods¶

string toString() const
Converts this SemVer to its canonical string representation.
bool isPrerelease() const
Returns true if this version is a pre-release.
bool hasBuild() const
Returns true if this version has build metadata.
int compare(const SemVer other) const
Compares this SemVer to another according to SemVer precedence rules.
Returns: -1 if this < other, 0 if equal, 1 if this > other.
bool opEquals(const SemVer other) const
Equality operator. Ignores build metadata.
int opCmp(const SemVer other) const
Less-than operator, for sorting. Ignores build metadata.
SemVer bumpMajor() const
Returns a new SemVer with incremented major version, resetting minor and patch to 0, and clearing prerelease/build.
SemVer bumpMinor() const
Returns a new SemVer with incremented minor version, resetting patch to 0, and clearing prerelease/build.
SemVer bumpPatch() const
Returns a new SemVer with incremented patch version, clearing prerelease/build.
SemVer withPrerelease(string[] ids) const
Returns a new SemVer with the given prerelease identifiers.
SemVer withBuild(string[] ids) const
Returns a new SemVer with the given build metadata identifiers.

Examples¶

Parsing and Inspecting Versions¶

auto v = SemVer.parse("2.1.0-beta.2+exp.sha.5114f85");
assert(v.major == 2);
assert(v.minor == 1);
assert(v.patch == 0);
assert(v.prerelease == ["beta", "2"]);
assert(v.build == ["exp", "sha", "5114f85"]);

Comparing Versions¶

auto v1 = SemVer.parse("1.0.0-alpha");
auto v2 = SemVer.parse("1.0.0");
assert(v1 < v2);

Bumping Versions¶

auto v = SemVer.parse("1.2.3-alpha+build.1");
auto major = v.bumpMajor(); // 2.0.0
auto minor = v.bumpMinor(); // 1.3.0
auto patch = v.bumpPatch(); // 1.2.4

Manipulating Prerelease and Build Metadata¶

auto v = SemVer(1, 2, 3);
auto pre = v.withPrerelease(["rc", "1"]); // 1.2.3-rc.1
auto build = v.withBuild(["build", "42"]); // 1.2.3+build.42

Exceptions¶

`SemVerParseException`¶

Thrown when a version string is invalid.

class SemVerParseException : Exception

Example:

try {
    auto v = SemVer.parse("invalid-version");
} catch (SemVerParseException e) {
    // Handle invalid version string
}

License¶

SPDX-License-Identifier: BSD-3-Clause