add a throwing initialiser for creating a version from a string

This new initialiser throws a `VersionError` instance when initialisation fails. This gives the user more information and control over error handling. `Version`'s conformance to `LosslessStringConvertible` is preserved by having `init?(_ versionString: String)` call this new initialiser, and return `nil` when an error is thrown.

Author: WowbaggersLiquidLunch

Sources/TSCUtility/Version.swift

@@ -28,7 +28,7 @@ public struct Version {
     /// The build metadata.
     public let buildMetadataIdentifiers: [String]
 
-    /// Create a version object.
+    /// Creates a version object.
     public init(
         _ major: Int,
         _ minor: Int,
@@ -45,6 +45,110 @@ public struct Version {
     }
 }
 
+/// An error that occurs during the creation of a version.
+public enum VersionError: Error, CustomStringConvertible {
+    /// The version string contains non-ASCII characters.
+    case nonASCIIVersionString(_ versionString: String)
+    /// The version core contains an invalid number of Identifiers.
+    case invalidVersionCoreIdentifiersCount(_ identifiers: [String])
+    /// Some or all of the version core identifiers contain non-numerical characters or are empty.
+    case nonNuumericalOrEmptyVersionCoreIdentifiers(_ identifiers: [String])
+    /// Some or all of the pre-release identifiers contain characters other than alpha-numerics and hyphens.
+    case nonAlphaNuumerHyphenalPrereleaseIdentifiers(_ identifiers: [String])
+    /// Some or all of the build metadata identifiers contain characters other than alpha-numerics and hyphens.
+    case nonAlphaNuumerHyphenalBuildMetadataIdentifiers(_ identifiers: [String])
+    
+    public var description: String {
+        switch self {
+        case let .nonASCIIVersionString(versionString):
+            return "non-ASCII characters in version string '\(versionString)'"
+        case let .invalidVersionCoreIdentifiersCount(identifiers):
+            return "\(identifiers.count < 3 ? "fewer" : "more") than 3 identifiers in version core '\(identifiers.joined(separator: "."))'"
+        case let .nonNuumericalOrEmptyVersionCoreIdentifiers(identifiers):
+            if !identifiers.allSatisfy( { !$0.isEmpty } ) {
+                return "empty identifiers in version core '\(identifiers.joined(separator: "."))'"
+            } else {
+                // Not checking for `.isASCII` here because non-ASCII characters should've already been caught before this.
+                let nonNumericalIdentifiers = identifiers.filter { !$0.allSatisfy(\.isNumber) }
+                return "non-numerical characters in version core identifier\(nonNumericalIdentifiers.count > 1 ? "s" : "") \(nonNumericalIdentifiers.map { "'\($0)'" } .joined(separator: ", "))"
+            }
+        case let .nonAlphaNuumerHyphenalPrereleaseIdentifiers(identifiers):
+            // Not checking for `.isASCII` here because non-ASCII characters should've already been caught before this.
+            let nonAlhpaNumericalIdentifiers = identifiers.filter { !$0.allSatisfy { $0.isLetter || $0.isNumber || $0 == "-" } }
+            return "characters other than alpha-numerics and hyphens in pre-release identifier\(nonAlhpaNumericalIdentifiers.count > 1 ? "s" : "") \(nonAlhpaNumericalIdentifiers.map { "'\($0)'" } .joined(separator: ", "))"
+        case let .nonAlphaNuumerHyphenalBuildMetadataIdentifiers(identifiers):
+            // Not checking for `.isASCII` here because non-ASCII characters should've already been caught before this.
+            let nonAlhpaNumericalIdentifiers = identifiers.filter { !$0.allSatisfy { $0.isLetter || $0.isNumber || $0 == "-" } }
+            return "characters other than alpha-numerics and hyphens in build metadata identifier\(nonAlhpaNumericalIdentifiers.count > 1 ? "s" : "") \(nonAlhpaNumericalIdentifiers.map { "'\($0)'" } .joined(separator: ", "))"
+        }
+    }
+}
+
+extension Version {
+    // TODO: Rename this function to `init(string: String) trhows`, after `init?(string: String)` is removed.
+    // TODO: Find a better error-checking order.
+    // Currently, if a version string is "fourty-two", this initializer throws an error that says "fourty" is only 1 version core identifier, which is not enough.
+    // But this is misleading the user to consider "fourty" as a valid version core identifier.
+    // We should find a way to check for (or throw) "wrong characters used" errors first, but without overly-complicating the logic.
+    /// Creates a version from the given string.
+    /// - Parameter versionString: The string to create the version from.
+    /// - Throws: A `VersionError` instance if the `versionString` doesn't follow [SemVer 2.0.0](https://semver.org).
+    public init(versionString: String) throws {
+        // SemVer 2.0.0 allows only ASCII alphanumerical characters and "-" in the version string, except for "." and "+" as delimiters. ("-" is used as a delimiter between the version core and pre-release identifiers, but it's allowed within pre-release and metadata identifiers as well.)
+        // Alphanumerics check will come later, after each identifier is split out (i.e. after the delimiters are removed).
+        guard versionString.allSatisfy(\.isASCII) else {
+            throw VersionError.nonASCIIVersionString(versionString)
+        }
+        
+        let metadataDelimiterIndex = versionString.firstIndex(of: "+")
+        // SemVer 2.0.0 requires that pre-release identifiers come before build metadata identifiers
+        let prereleaseDelimiterIndex = versionString[..<(metadataDelimiterIndex ?? versionString.endIndex)].firstIndex(of: "-")
+        
+        let versionCore = versionString[..<(prereleaseDelimiterIndex ?? metadataDelimiterIndex ?? versionString.endIndex)]
+        let versionCoreIdentifiers = versionCore.split(separator: ".", omittingEmptySubsequences: false)
+
+        guard versionCoreIdentifiers.count == 3 else {
+            throw VersionError.invalidVersionCoreIdentifiersCount(versionCoreIdentifiers.map { String($0) })
+        }
+        
+        guard
+            // Major, minor, and patch versions must be ASCII numbers, according to the semantic versioning standard.
+            // Converting each identifier from a substring to an integer doubles as checking if the identifiers have non-numeric characters.
+            let major = Int(versionCoreIdentifiers[0]),
+            let minor = Int(versionCoreIdentifiers[1]),
+            let patch = Int(versionCoreIdentifiers[2])
+        else {
+            throw VersionError.nonNuumericalOrEmptyVersionCoreIdentifiers(versionCoreIdentifiers.map { String($0) })
+        }
+        
+        self.major = major
+        self.minor = minor
+        self.patch = patch
+        
+        if let prereleaseDelimiterIndex = prereleaseDelimiterIndex {
+            let prereleaseStartIndex = versionString.index(after: prereleaseDelimiterIndex)
+            let prereleaseIdentifiers = versionString[prereleaseStartIndex..<(metadataDelimiterIndex ?? versionString.endIndex)].split(separator: ".", omittingEmptySubsequences: false)
+            guard prereleaseIdentifiers.allSatisfy( { $0.allSatisfy { $0.isLetter || $0.isNumber || $0 == "-" } } ) else {
+                throw VersionError.nonAlphaNuumerHyphenalPrereleaseIdentifiers(prereleaseIdentifiers.map { String($0) })
+            }
+            self.prereleaseIdentifiers = prereleaseIdentifiers.map { String($0) }
+        } else {
+            self.prereleaseIdentifiers = []
+        }
+
+        if let metadataDelimiterIndex = metadataDelimiterIndex {
+            let metadataStartIndex = versionString.index(after: metadataDelimiterIndex)
+            let buildMetadataIdentifiers = versionString[metadataStartIndex...].split(separator: ".", omittingEmptySubsequences: false)
+            guard buildMetadataIdentifiers.allSatisfy( { $0.allSatisfy { $0.isLetter || $0.isNumber || $0 == "-" } } ) else {
+                throw VersionError.nonAlphaNuumerHyphenalBuildMetadataIdentifiers(buildMetadataIdentifiers.map { String($0) })
+            }
+            self.buildMetadataIdentifiers = buildMetadataIdentifiers.map { String($0) }
+        } else {
+            self.buildMetadataIdentifiers = []
+        }
+    }
+}
+
 extension Version: Comparable, Hashable {
 
     func isEqualWithoutPrerelease(_ other: Version) -> Bool {
@@ -122,47 +226,7 @@ extension Version: LosslessStringConvertible {
     /// Initializes a version struct with the provided version string.
     /// - Parameter version: A version string to use for creating a new version struct.
     public init?(_ versionString: String) {
-        // SemVer 2.0.0 allows only ASCII alphanumerical characters and "-" in the version string, except for "." and "+" as delimiters. ("-" is used as a delimiter between the version core and pre-release identifiers, but it's allowed within pre-release and metadata identifiers as well.)
-        // Alphanumerics check will come later, after each identifier is split out (i.e. after the delimiters are removed).
-        guard versionString.allSatisfy(\.isASCII) else { return nil }
-        
-        let metadataDelimiterIndex = versionString.firstIndex(of: "+")
-        // SemVer 2.0.0 requires that pre-release identifiers come before build metadata identifiers
-        let prereleaseDelimiterIndex = versionString[..<(metadataDelimiterIndex ?? versionString.endIndex)].firstIndex(of: "-")
-        
-        let versionCore = versionString[..<(prereleaseDelimiterIndex ?? metadataDelimiterIndex ?? versionString.endIndex)]
-        let versionCoreIdentifiers = versionCore.split(separator: ".", omittingEmptySubsequences: false)
-        
-        guard
-            versionCoreIdentifiers.count == 3,
-            // Major, minor, and patch versions must be ASCII numbers, according to the semantic versioning standard.
-            // Converting each identifier from a substring to an integer doubles as checking if the identifiers have non-numeric characters.
-            let major = Int(versionCoreIdentifiers[0]),
-            let minor = Int(versionCoreIdentifiers[1]),
-            let patch = Int(versionCoreIdentifiers[2])
-        else { return nil }
-        
-        self.major = major
-        self.minor = minor
-        self.patch = patch
-        
-        if let prereleaseDelimiterIndex = prereleaseDelimiterIndex {
-            let prereleaseStartIndex = versionString.index(after: prereleaseDelimiterIndex)
-            let prereleaseIdentifiers = versionString[prereleaseStartIndex..<(metadataDelimiterIndex ?? versionString.endIndex)].split(separator: ".", omittingEmptySubsequences: false)
-            guard prereleaseIdentifiers.allSatisfy( { $0.allSatisfy { $0.isLetter || $0.isNumber || $0 == "-" } } ) else { return nil }
-            self.prereleaseIdentifiers = prereleaseIdentifiers.map { String($0) }
-        } else {
-            self.prereleaseIdentifiers = []
-        }
-        
-        if let metadataDelimiterIndex = metadataDelimiterIndex {
-            let metadataStartIndex = versionString.index(after: metadataDelimiterIndex)
-            let buildMetadataIdentifiers = versionString[metadataStartIndex...].split(separator: ".", omittingEmptySubsequences: false)
-            guard buildMetadataIdentifiers.allSatisfy( { $0.allSatisfy { $0.isLetter || $0.isNumber || $0 == "-" } } ) else { return nil }
-            self.buildMetadataIdentifiers = buildMetadataIdentifiers.map { String($0) }
-        } else {
-            self.buildMetadataIdentifiers = []
-        }
+        try? self.init(versionString: versionString)
     }
 }