Skip to content
Semantic versioning in Swift
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Common
CommonTests
SemverKit-OSX
SemverKit-OSXTests
SemverKit.xcodeproj
SemverKit
SemverKitTests
.gitignore
Cartfile
Cartfile.resolved
LICENSE
README.md

README.md

SemverKit — Semantic Versioning in Swift

SemverKit is a pure Swift implementation of the Semantic Versioning 2.0 specification. It includes a parser for version strings, as well as comparison and equality operators. As an extension, it also includes semantics for incrementing versions, with special support for alpha and beta pre-release versions.

SemverKit exists for both iOS and OS X, with the OS X version having an eye towards being useful for the creation of scripts and command-line tools. The OS X framework therefore includes additional functionality, such as consistent parsing of options.

Basic Usage

The first point of contact with the API is likely going to be the parser.

let result1 = parseVersion("2.0.1-alpha.2") // { Success 2.0.1-alpha.2 }
let result2 = parseVersion("a.0.2-alpha.3") // { Failure String "a.0.2" could not be
                                            //   parsed as a number in normal version: "a.0.2" }

The parser returns a Result type, an enum that is either a Success or a Failure, depending on whether or not the parsing was successful. Upon failure, a message describes the source of the error. A successful parse contains the core type of the library: a Version.

Version is Equatable and Comparable, fully implementing the semantics of the spec:

 2.0.1 < 2.0.2 < 2.1.0 < 2.2.0 < 3.0.0 < 3.1.0-alpha.0 < 3.1.0-alpha.3 < 3.1.0-beta < 3.1.0-beta.0 < 3.1.0-beta.1 < 3.1.0-lexically-larger < 3.1.0

Of course, version metadata is fully supported, but ignored during equality and comparison operations.

Extensions

In addition to supporting basic comparison of versions, SemverKit also includes support for incrementing versions in a consistent manner. A number of methods are defined to support:

  • Incrementing normal versions (patch, minor, major)
  • Incrementing pre-release versions (to pre-release alpha and beta versions and to normal versions)
  • Stabilizing a version

All these methods are prefixed with next*, and their return values are uniquely defined. For instance, nextMajorAlphaVersion defines what it returns as:

The next major alpha version of version v1 is defined as the smallest version v2 > v1 with:

  • A patch number of 0
  • A minor number of 0
  • A pre-release of alpha.X, where X is an integer

This allows for precise semantics, which makes SemverKit suitable for automated versioning.

Installation

Minimum system requirements:

  • Xcode 6.3 β4
  • OS X Mavericks 10.10

Steps:

  1. Clone this github repository, and build the project.
  2. Run the tests, just for sanity. They should all pass.
  3. Copy SemverKit.framework from the DerivedData directoy to /Library/Frameworks (this will require sudo access)

SemverKit should now be available for use from a command line script. The shebang needs to read:

#!/usr/bin/env xcrun swift -F /Library/Frameworks

This is because the Swift compiler, unlike Clang, doesn't automatically pick up frameworks in /Library/Frameworks.

Including SemverKit in Other Libraries

Use Carthage. SemverKit, of course, uses semantic versioning, so the corresponding Cartfile line should be:

github "nomothetis/SemverKit" == 0.2.0
You can’t perform that action at this time.