gundy/semver4j

Semantic Versioning for Java

Download

Step 1. Add the JitPack repository to your build file

Add it in your root settings.gradle at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url 'https://jitpack.io' }
		}
	}

Add it in your settings.gradle.kts at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url = uri("https://jitpack.io") }
		}
	}

Add to pom.xml

	<repositories>
		<repository>
		    <id>jitpack.io</id>
		    <url>https://jitpack.io</url>
		</repository>
	</repositories>

Add it in your build.sbt at the end of resolvers:

 
    resolvers += "jitpack" at "https://jitpack.io"

Add it in your project.clj at the end of repositories:

 
    :repositories [["jitpack" "https://jitpack.io"]]

Step 2. Add the dependency

	dependencies {
		implementation 'com.github.gundy:semver4j:0.16.4'
	}

	dependencies {
		implementation("com.github.gundy:semver4j:0.16.4")
	}

	<dependency>
	    <groupId>com.github.gundy</groupId>
	    <artifactId>semver4j</artifactId>
	    <version>0.16.4</version>
	</dependency>


                            
    libraryDependencies += "com.github.gundy" % "semver4j" % "0.16.4"


                            
    :dependencies [[com.github.gundy/semver4j "0.16.4"]]

Readme

SemVer4J -- Evaluate node SemVer expressions in Java

Build status

SemVer

SemVer stands for "Semantic Versioning". The SemVer specification defines a set of rules for versioning software, such that the kind of things that can change between version numbers are well defined, and easily understood.

SemVer4J supports validation of, and comparison between between validated SemVer versions, according to the rules given in the SemVer specification.

Usage

SemVer.valid("1.2.3") // true
SemVer.valid("a.b.c") // false

Version versionA = Version.fromString("1.2.3");
Version versionB = Version.fromString("1.2.1-alpha.1+build");
versionA.compareTo(versionB) // 1  (A>B)

SemVer4J and npm range expressions

SemVer4J supports the same range expression language that is used in node's SemVer library. This is the library npm uses to determine which dependencies to download based on the range expressions given in package.json.

Usage

SemVer.satisfies("1.2.3", "1.x || >=2.5.0 || 5.0.0 - 7.2.3") // true

SemVer.maxSatisfying(Arrays.asList("1.2.5", "0.3.5", "1.2.3", "1.1.4"), ">1.0") // "1.2.5"

Please refer to the link above for full details about the syntax and constructs that the language supports.

Dependencies

SemVer4J uses the ANTLR parser generator and runtime for parsing SemVer versions, and for parsing the expression language used for ranges.

If you find that you have conflicts, or if you simply want to prevent additional downstream dependencies for your software, SemVer4J provides a nodeps package that bundles (and relocated) the ANTLR dependencies using the maven shade plugin.

Strict vs Loose semantics

No attempt has been made to differentiate between node's strict and loose parsing rules. All parsing is done with what might be considered "loose" semantics in node's library. The reason for this is to attempt to make SemVer4J as tolerant as possible of various parse-related issues.

For example, the following are equivalent, and will result in version having the same value:

version = Version.fromString("1.2.3-beta")
version = Version.fromString("1.2.3beta")
version = Version.fromString("v1.2.3-beta")
version = Version.fromString("=v1.2.3-beta")
version = Version.fromString("=1.2.3-beta")
version = Version.fromString("=1.2.3beta")
// etc

Calling version.toString() on any of the above will result in the canonical form:

version.toString(); // "1.2.3-beta"

Technical details

The ANTLR grammars in src/main/antlr4 may provide some useful hints at the specific grammar and implementation that SemVer4J uses.

Range expressions are parsed using ANTLR4's visitor pattern, in the SemVerRangeExpressionVisitor class. Visit methods are provided for each of the important classifying / leaf nodes of the parse tree, and for operators such as logical OR (||) and AND (no specific operator), which combine the output from their child nodes.

Hopefully the code should be straightforward enough to follow at a high level, although the specific requirements from node's range specification do make certain things quite complex.

The positive and negative test cases used have been borrowed from Node's own SemVer library (linked above). This doesn't guarantee any sort of equivalence, but should at least help to ensure that SemVer4J is reasonably compatible with node's implementation.