using System; using System.Text.RegularExpressions; using StardewModdingAPI.Toolkit.Framework; namespace StardewModdingAPI.Toolkit { /// A semantic version with an optional release tag. /// /// The implementation is defined by Semantic Version 2.0 (https://semver.org/), with a few deviations: /// - short-form "x.y" versions are supported (equivalent to "x.y.0"); /// - hyphens are synonymous with dots in prerelease tags and build metadata (like "-unofficial.3-pathoschild"); /// - and "-unofficial" in prerelease tags is always lower-precedence (e.g. "1.0-beta" is newer than "1.0-unofficial"). /// /// This optionally also supports four-part versions, a non-standard extension used by Stardew Valley on ported platforms to represent platform-specific patches to a ported version, represented as a fourth number in the version string. /// public class SemanticVersion : ISemanticVersion { /********* ** Fields *********/ /// A regex pattern matching a valid prerelease or build metadata tag. private const string TagPattern = @"(?>[a-z0-9]+[\-\.]?)+"; /********* ** Accessors *********/ /// public int MajorVersion { get; } /// public int MinorVersion { get; } /// public int PatchVersion { get; } /// The platform release. This is a non-standard semver extension used by Stardew Valley on ported platforms to represent platform-specific patches to a ported version, represented as a fourth number in the version string. public int PlatformRelease { get; } /// public string PrereleaseTag { get; } /// public string BuildMetadata { get; } /********* ** Public methods *********/ /// Construct an instance. /// The major version incremented for major API changes. /// The minor version incremented for backwards-compatible changes. /// The patch version for backwards-compatible fixes. /// The platform-specific version (if applicable). /// An optional prerelease tag. /// Optional build metadata. This is ignored when determining version precedence. public SemanticVersion(int major, int minor, int patch, int platformRelease = 0, string prereleaseTag = null, string buildMetadata = null) { this.MajorVersion = major; this.MinorVersion = minor; this.PatchVersion = patch; this.PlatformRelease = platformRelease; this.PrereleaseTag = this.GetNormalizedTag(prereleaseTag); this.BuildMetadata = this.GetNormalizedTag(buildMetadata); this.AssertValid(); } /// Construct an instance. /// The assembly version. /// The is null. public SemanticVersion(Version version) { if (version == null) throw new ArgumentNullException(nameof(version), "The input version can't be null."); this.MajorVersion = version.Major; this.MinorVersion = version.Minor; this.PatchVersion = version.Build; this.AssertValid(); } /// Construct an instance. /// The semantic version string. /// Whether to recognize non-standard semver extensions. /// The is null. /// The is not a valid semantic version. public SemanticVersion(string version, bool allowNonStandard = false) { if (version == null) throw new ArgumentNullException(nameof(version), "The input version string can't be null."); if (!SemanticVersionReader.TryParse(version, allowNonStandard, out int major, out int minor, out int patch, out int platformRelease, out string prereleaseTag, out string buildMetadata) || (!allowNonStandard && platformRelease != 0)) throw new FormatException($"The input '{version}' isn't a valid semantic version."); this.MajorVersion = major; this.MinorVersion = minor; this.PatchVersion = patch; this.PlatformRelease = platformRelease; this.PrereleaseTag = prereleaseTag; this.BuildMetadata = buildMetadata; this.AssertValid(); } /// public int CompareTo(ISemanticVersion other) { if (other == null) throw new ArgumentNullException(nameof(other)); return this.CompareTo(other.MajorVersion, other.MinorVersion, other.PatchVersion, (other as SemanticVersion)?.PlatformRelease ?? 0, other.PrereleaseTag); } /// public bool Equals(ISemanticVersion other) { return other != null && this.CompareTo(other) == 0; } /// public bool IsPrerelease() { return !string.IsNullOrWhiteSpace(this.PrereleaseTag); } /// public bool IsOlderThan(ISemanticVersion other) { return this.CompareTo(other) < 0; } /// public bool IsOlderThan(string other) { return this.IsOlderThan(new SemanticVersion(other, allowNonStandard: true)); } /// public bool IsNewerThan(ISemanticVersion other) { return this.CompareTo(other) > 0; } /// public bool IsNewerThan(string other) { return this.IsNewerThan(new SemanticVersion(other, allowNonStandard: true)); } /// public bool IsBetween(ISemanticVersion min, ISemanticVersion max) { return this.CompareTo(min) >= 0 && this.CompareTo(max) <= 0; } /// public bool IsBetween(string min, string max) { return this.IsBetween(new SemanticVersion(min, allowNonStandard: true), new SemanticVersion(max, allowNonStandard: true)); } /// public override string ToString() { string version = $"{this.MajorVersion}.{this.MinorVersion}.{this.PatchVersion}"; if (this.PlatformRelease != 0) version += $".{this.PlatformRelease}"; if (this.PrereleaseTag != null) version += $"-{this.PrereleaseTag}"; if (this.BuildMetadata != null) version += $"+{this.BuildMetadata}"; return version; } /// public bool IsNonStandard() { return this.PlatformRelease != 0; } /// Parse a version string without throwing an exception if it fails. /// The version string. /// The parsed representation. /// Returns whether parsing the version succeeded. public static bool TryParse(string version, out ISemanticVersion parsed) { return SemanticVersion.TryParse(version, allowNonStandard: false, out parsed); } /// Parse a version string without throwing an exception if it fails. /// The version string. /// Whether to allow non-standard extensions to semantic versioning. /// The parsed representation. /// Returns whether parsing the version succeeded. public static bool TryParse(string version, bool allowNonStandard, out ISemanticVersion parsed) { try { parsed = new SemanticVersion(version, allowNonStandard); return true; } catch { parsed = null; return false; } } /********* ** Private methods *********/ /// Get a normalized prerelease or build tag. /// The tag to normalize. private string GetNormalizedTag(string tag) { tag = tag?.Trim(); return !string.IsNullOrWhiteSpace(tag) ? tag : null; } /// Get an integer indicating whether this version precedes (less than 0), supersedes (more than 0), or is equivalent to (0) the specified version. /// The major version to compare with this instance. /// The minor version to compare with this instance. /// The patch version to compare with this instance. /// The non-standard platform release to compare with this instance. /// The prerelease tag to compare with this instance. private int CompareTo(int otherMajor, int otherMinor, int otherPatch, int otherPlatformRelease, string otherTag) { const int same = 0; const int curNewer = 1; const int curOlder = -1; int CompareToRaw() { // compare stable versions if (this.MajorVersion != otherMajor) return this.MajorVersion.CompareTo(otherMajor); if (this.MinorVersion != otherMinor) return this.MinorVersion.CompareTo(otherMinor); if (this.PatchVersion != otherPatch) return this.PatchVersion.CompareTo(otherPatch); if (this.PlatformRelease != otherPlatformRelease) return this.PlatformRelease.CompareTo(otherPlatformRelease); if (this.PrereleaseTag == otherTag) return same; // stable supersedes prerelease bool curIsStable = string.IsNullOrWhiteSpace(this.PrereleaseTag); bool otherIsStable = string.IsNullOrWhiteSpace(otherTag); if (curIsStable) return curNewer; if (otherIsStable) return curOlder; // compare two prerelease tag values string[] curParts = this.PrereleaseTag.Split('.', '-'); string[] otherParts = otherTag.Split('.', '-'); int length = Math.Max(curParts.Length, otherParts.Length); for (int i = 0; i < length; i++) { // longer prerelease tag supersedes if otherwise equal if (curParts.Length <= i) return curOlder; if (otherParts.Length <= i) return curNewer; // skip if same value, unless we've reached the end if (curParts[i] == otherParts[i]) { if (i == length - 1) return same; continue; } // unofficial is always lower-precedence if (otherParts[i].Equals("unofficial", StringComparison.OrdinalIgnoreCase)) return curNewer; if (curParts[i].Equals("unofficial", StringComparison.OrdinalIgnoreCase)) return curOlder; // compare numerically if possible { if (int.TryParse(curParts[i], out int curNum) && int.TryParse(otherParts[i], out int otherNum)) return curNum.CompareTo(otherNum); } // else compare lexically return string.Compare(curParts[i], otherParts[i], StringComparison.OrdinalIgnoreCase); } // fallback (this should never happen) return string.Compare(this.ToString(), new SemanticVersion(otherMajor, otherMinor, otherPatch, otherPlatformRelease, otherTag).ToString(), StringComparison.OrdinalIgnoreCase); } int result = CompareToRaw(); if (result < 0) return curOlder; if (result > 0) return curNewer; return same; } /// Assert that the current version is valid. private void AssertValid() { if (this.MajorVersion < 0 || this.MinorVersion < 0 || this.PatchVersion < 0) throw new FormatException($"{this} isn't a valid semantic version. The major, minor, and patch numbers can't be negative."); if (this.MajorVersion == 0 && this.MinorVersion == 0 && this.PatchVersion == 0) throw new FormatException($"{this} isn't a valid semantic version. At least one of the major, minor, and patch numbers must be more than zero."); if (this.PrereleaseTag != null) { if (this.PrereleaseTag.Trim() == "") throw new FormatException($"{this} isn't a valid semantic version. The prerelease tag cannot be a blank string (but may be omitted)."); if (!Regex.IsMatch(this.PrereleaseTag, $"^{SemanticVersion.TagPattern}$", RegexOptions.IgnoreCase)) throw new FormatException($"{this} isn't a valid semantic version. The prerelease tag is invalid."); } if (this.BuildMetadata != null) { if (this.BuildMetadata.Trim() == "") throw new FormatException($"{this} isn't a valid semantic version. The build metadata cannot be a blank string (but may be omitted)."); if (!Regex.IsMatch(this.BuildMetadata, $"^{SemanticVersion.TagPattern}$", RegexOptions.IgnoreCase)) throw new FormatException($"{this} isn't a valid semantic version. The build metadata is invalid."); } } } }