mxcl/version

semver (Semantic Version) Swift µFramework.

Version

A µ-framework for representing, comparing, encoding and utilizing semantic versions, eg. 1.2.3 or 2.0.0-beta.

This is Version.swift from the Swift Package Manager, with some minor adjustments:

1. More compact Codable implementation †
2. Implements LosslessStringConvertible ‡
3. Not a massive-single-source-file (MSSF)
4. Online documentation
5. Extensions for Bundle and ProcessInfo
6. Removal of the potentially fatal ExpressibleByStringLiteral conformance
7. A “tolerant” initializer for user input like 10.0 or v3
8. Idiomatic implementations for Range<Version>
9. Initialization from StringProtocol, not just String

We have automatic monitoring for changes at Apple’s repo to alert us if we should need merge any fixes.

† Semantic versions can be losslessly expressed as strings; thus we do so.

‡ Like Int we can losslessly store a semantic version from a valid string, so we conform to the same protocol.

Support mxcl

Hey there, I’m Max Howell. I’m a prolific producer of open source software and probably you already use some of it (for example, I created brew). I work full-time on open source and it’s hard; currently I earn less than minimum wage. Please help me continue my work, I appreciate it 🙏🏻

Other ways to say thanks.

Usage

import Version

// these two initializers are the same, use whichever suits the code context
let v1 = Version(1,0,0)
let v2 = Version(major: 1, minor: 0, patch: 0)

let v3 = Version("1.2.3")           // =>  1.2.3: Version?
let v4 = Version(tolerant: "10.1")  // => 10.1.0: Version?
let v5 = Version(tolerant: "10")    // => 10.0.0: Version?

// a real Version object from your app’s Info.plist
let v6 = Bundle.main.version

let range = Version(1,2,3)..<Version(2,0,0)

let null: Version = .null  // => Version(0,0,0)

let foo = Version(1,2,3) < Version(2,0,0)  // => true

Installation

SwiftPM:

package.append(.package(url: "https://github.com/mxcl/Version.git", from: "2.0.0"))

Carthage:

Waiting on: @Carthage#1945.

Ranges

Ranges work as you expect, but there are caveats for prerelease identifiers, here are the rules:

1.0.0..<2.0.0 does not include eg. 2.0.0-alpha

This is probably what you expected. However:

1.0.0..<2.0.0 also does not include eg. 1.5.0-alpha

However:

1.0.0..<2.0.0-beta does include eg. 2.0.0-alpha

This is how the majority of Semantic Version libraries work.

Comparable, Equatable & Hashable

Both comparable and equatable ignore build metadata as per the specification. Thus:

Version("1.2.3+14") == Version("1.2.3+15")  // => true
Version("1.2.3+14") <= Version("1.2.3+15")  // => true
Version("1.2.3+14") <  Version("1.2.3+15")  // => false

This also means that Hashable must mirror this behavior, thus:

dict[Version("1.2.3+14")] = 1
dict[Version("1.2.3+15")] = 2
dict.count  // => 1
dict        // => ["1.2.3+15": 2]

Be aware of this as it may catch you out, naturally this will also effect structures that depend on Hashable, eg. Set.

version's Issues

Version listening idea

Not sire if there is value here, but I've created a SemanticVersion framework that is focused on listening for changes and then updating the various places where you may have used the Semantic Version. The intent is for libraries where you have to list our your version in multiple places but only want to update it once.

https://gitlab.com/thecb4/SemVerSwift

Thoughts?

Check Bundle Version matches expected release version before finalizing

add an initializer using Float or Decimal

some version is float-pointing like 12.2, not "12.2". can you support it?

Build metadata should be ignored when determining version precedence

I think I've found an issue with metadata:
Based on https://semver.org/#spec-item-10 when you compare two version the metadata should be ignored.

Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.

So I think the following code should work:

if let v1 = Version("1.0.0+build1"), let v2 = Version("1.0.0+build2") {
    assert(v1 == v2)
}

multiple targets named 'Tests' in: CryptoSwift, Version

The actual Tests target is too generic, causing dependency name collisions that SPM can not handle. In this case, I found a collision between this package and https://github.com/krzyzanowskim/CryptoSwift.

After running swift package generate-xcodeproj the console shows the following error:

error: multiple targets named 'Tests' in: CryptoSwift, Version

The solution is to rename the target.