Version Primitives

This library provides version primitives in the form of constraints; currently supported:

• The composition constraints VersionRange and VersionUnion
• A generic Version representation
• A specific SemverVersion to represent semver versions

License

This project is licensed under AGPL-3.0-or-later. For more information see the LICENSE file, or alternative online under https://www.gnu.org/licenses/.

Usage

This library provides means to work with versions through version constraints; in particular, it is ment for package managers and similar software to represent versions of an package.

Because not every system is similar, this library reflects this by choosing to NOT implement an strict version scheme the user needs to follow; instead it opts to define an contract, based on a abstract base class (Version), which users can implement to represent their versioning scheme and semantics. One such example is provided in this library, in the form of the SemverVersion class.

The Version contract

The contract each version implementation must fullfill is quite simple:

• be compareable with other constraints (Compareable<VersionConstraint>), primarily for comparing against itself and an VersionRange<?>.

• can be checked for equality (overriding Object#equals(Object)),

• a custom toString() method so enduser can know what they are dealing with.

For examples, you can look at how SemverVersion implements this contract.

Composites

This library supports 2 additional implementations of VersionConstraint apart from the strict Version:

• VersionRange<?> implements an range of versions with an minimum and maximum, both in the form of inclusive or exclusive.

• VersionUnion<?> a set of VersionRange<?> which are OR'ed together. This allows for more complex constraints, such as a range with a hole inside (represented via two ranges for the two ranges around the hole).

Parsing of versions

Parsing of versions can be tricky sometimes, and other times be outright impossible to unify. Because of this, this library chooses to not implement any generic parsing, but instead encourages users to implement parsing on their own.

That being said, the default concrete versioning schemes included, have all some parsing capability included and ready to go. The convention in this library (and to some extend encouraged to be also used by users) is the following:

• #parse(String) parses the version itself completly; in the case of semver, this would be 1.0.0. If no complete version can be parsed from the string, null is returned instead.

• #match(AtomicReference<String>) parses a version, if possible, from the start of the given string reference. If done so successfully, it updates the given reference with the remainder of the string. Else, returns null.

Special thanks / inspirations

• the pub_semver dart library for inspiration for modeling version constraints.