semver_parser

Pub Documentation Build Status codecov License: MIT

A Dart library that provides an API to parse strings to Semantic Versions along with Semantic Version comparison logic. The library's semver parsing and comparison logic follows the Semantic Version 2.0.0 spec.

A note about the pub_semver package

This package (semver_parser) is NOT the official dartlang semver parsing package. This project is not endorsed, associated with or supported by the dartlang team. The pub_semver package is the official semver parsing library provided by the dartlang team and is used in many of the dart and pub tools (such as the version resolution done in a pub get command).

The pub_semver package follows a modified Semantic Version 2.0.0 spec to provide more logical version resolution, so if you want to use the same rules pub does, use the official pub_semver package. This package (semver_parser) is intending to implement the exact Semantic Version 2.0.0 spec, so this package's logic will differ from pub_semver's logic.

  • In the standard 2.0.0 spec, the version range '<2.0.0' would allow using the version '2.0.0-beta' which could lead to broken builds due to breaking changes in the '2.0.0-beta' branch.
  • In the pub modified spec, '<2.0.0' would not allow any '2.0.0-blah' versions to be used. '1.Last.Last' would be the last supported version.

It is also worth nothing the pub_semver is an officially supported package backed by a team of professional, dedicated, developers. This package (semver_parser) is a hobby project, and while I strive to deliver high quality, accurate code and address any bugs found, I cannot provide the same level of support as the official dartlang team can.

Semantic Version Parsing

This library can take an arbitrary string value and attempt to parse it into a single Semantic Version, represented by the Semver object. For a string to parse to a Semantic Version it must contain one, and only one, valid Semantic Version. Additional "noise" in the string will not affect the parse and will be dropped.

E.X.

  • '1.2.3' = Major: 1 Minor: 2 Patch: 3
  • 'react-16.3.2' = Major: 16 Minor: 3 Patch 2 ('react-' is ignored as it does not affect the Semantic Version)
  • 'California' = No Semantic Version, exception would be thrown.
  • '2.1.5 and 5.12.6' = Two potential Semantic Versions, exception would be thrown.
Note: Pre-Release information is not parsed currently, issue #17 will add support for parsing this information.
Note: Built metadata information is not parsed currently, issue #18 will add support for parsing this information.

Semantic Version Comparison Logic

Two Semver objects can be compared using the standard comparison operators such as ==, !=, <, <=, > or >=.

E.X.

  • '1.2.3' == '1.2.3' (true)
  • '4.3.1' != '4.3.1' (false)
  • '2.4.5' > '2.3.0' (true)
  • '2.4.5' >= '2.4.5' (true)
  • '1.12.43' < '1.12.42' (false)
  • '1.12.43' <= '1.12.43' (true)

Example Parsing

var versionOne = parseSemverString('some-12.5.3%thing');
var versionTwo = parseSemverString('11.5.12');

print(versionOne); // 12.5.3
print(versionTwo); // 11.5.12

print(versionOne == versionTwo); // true
print(versionOne < versionTwo); // false

Example Parsing App

An example app to test or demo semver string parsing is included under 'example/'. This app can be run using dart example/semver_parser.dart or pub run example/semver_parser.dart. The example app takes input from stdin and parses that input. Run the example to see more details about all its functions.

Releases/Roadmap

The 0.1.0 release has been made. Breaking changes are possible until a '1.x.y' release is made, please read all changelog notes to be safe. Additional pre-1.0.0 releases will increment the minor version (unless the change is non-functional in which case the patch version will be changed).

Release '1.0.0' will likely be made after support for parsing all Semantic Version information and comparison logic work is complete.

Contributing

Feel free to submit issues for any bugs, feature requests or questions in generally. Please provide as much information as possible so I can best help you out.

If you'd like to contribute, feel free to open pulls for changes. I'd suggest you read the contributing guide as well.

Libraries

semver_parser
A library which provides the utilities to parse Semantic Versions from strings.