diff --git a/src/Ubiquity.NET.Versioning/AlphaNumericOrdering.cs b/src/Ubiquity.NET.Versioning/AlphaNumericOrdering.cs index 1f91b78..87e8523 100644 --- a/src/Ubiquity.NET.Versioning/AlphaNumericOrdering.cs +++ b/src/Ubiquity.NET.Versioning/AlphaNumericOrdering.cs @@ -9,7 +9,7 @@ namespace Ubiquity.NET.Versioning /// Identifies the sort ordering expected for a given version public enum AlphaNumericOrdering { - /// Indicates no sort ordering + /// Indicates an invalid sort ordering /// /// This value is the default for this type and is ALWAYS invalid. /// diff --git a/src/Ubiquity.NET.Versioning/AppContextSwitches.cs b/src/Ubiquity.NET.Versioning/AppContextSwitches.cs index db215fa..67b6bb4 100644 --- a/src/Ubiquity.NET.Versioning/AppContextSwitches.cs +++ b/src/Ubiquity.NET.Versioning/AppContextSwitches.cs @@ -62,6 +62,7 @@ public static bool CSemVerCIOnlySupportsBuildMetaOnZeroTimedVersions set => AppContext.SetSwitch(CSemVerCIOnlySupportsBuildMetaOnZeroTimedVersionsName, value); } + // internal utility to read a switch and default to false if not found. private static bool GetSwitchValue(string name) { bool found = AppContext.TryGetSwitch(name, out bool currentVal); diff --git a/src/Ubiquity.NET.Versioning/CSemVer.cs b/src/Ubiquity.NET.Versioning/CSemVer.cs index 7cbf391..19f6e21 100644 --- a/src/Ubiquity.NET.Versioning/CSemVer.cs +++ b/src/Ubiquity.NET.Versioning/CSemVer.cs @@ -262,6 +262,7 @@ public static CSemVer From( ParsedBuildVersionXml parsedBuildVersionXml, Immutab /// public static new CSemVer Parse( string s, IFormatProvider? provider ) { + // Throw if provider isn't one that is ignorable. provider.ThrowIfCaseSensitive(); return TryParse( s, out CSemVer? retVal, out Exception? ex ) ? retVal : throw ex; } @@ -272,6 +273,7 @@ public static CSemVer From( ParsedBuildVersionXml parsedBuildVersionXml, Immutab /// public static bool TryParse( [NotNullWhen( true )] string? s, IFormatProvider? provider, [MaybeNullWhen( false )] out CSemVer result ) { + // Throw if provider isn't one that is ignorable. provider.ThrowIfCaseSensitive(); return TryParse( s, out result, out _ ); } diff --git a/src/Ubiquity.NET.Versioning/CSemVerCI.cs b/src/Ubiquity.NET.Versioning/CSemVerCI.cs index 9d2b3e0..ee58a4b 100644 --- a/src/Ubiquity.NET.Versioning/CSemVerCI.cs +++ b/src/Ubiquity.NET.Versioning/CSemVerCI.cs @@ -214,6 +214,7 @@ public static bool TryFrom( /// public static new CSemVerCI Parse( string s, IFormatProvider? provider ) { + // Throw if provider isn't one that is ignorable. provider.ThrowIfCaseSensitive(); return TryParse( s, out CSemVerCI? retVal, out Exception? ex ) ? retVal : throw ex; } @@ -221,6 +222,7 @@ public static bool TryFrom( /// public static bool TryParse( [NotNullWhen( true )] string? s, IFormatProvider? provider, [MaybeNullWhen( false )] out CSemVerCI result ) { + // Throw if provider isn't one that is ignorable. provider.ThrowIfCaseSensitive(); return TryParse( s, out result, out _ ); } diff --git a/src/Ubiquity.NET.Versioning/FormatProviderExtensions.cs b/src/Ubiquity.NET.Versioning/FormatProviderExtensions.cs index e831615..722fbe1 100644 --- a/src/Ubiquity.NET.Versioning/FormatProviderExtensions.cs +++ b/src/Ubiquity.NET.Versioning/FormatProviderExtensions.cs @@ -25,5 +25,12 @@ public static void ThrowIfCaseSensitive(this IFormatProvider? provider, [CallerA throw new ArgumentException("Format provider must be or provide a CaseInsensitive comparison", exp); } } + + public static AlphaNumericOrdering GetOrdering(this IFormatProvider provider) + { + ArgumentNullException.ThrowIfNull(provider); + + return (AlphaNumericOrdering?)provider.GetFormat(typeof(AlphaNumericOrdering)) ?? AlphaNumericOrdering.None; + } } } diff --git a/src/Ubiquity.NET.Versioning/PackageReadMe.md b/src/Ubiquity.NET.Versioning/PackageReadMe.md index f1a3f92..6384d48 100644 --- a/src/Ubiquity.NET.Versioning/PackageReadMe.md +++ b/src/Ubiquity.NET.Versioning/PackageReadMe.md @@ -43,15 +43,18 @@ sort ordering of the versions according to the rules of SemVer (Which, CSemVer a follow with the exception of explicit case insensitivity for AphaNumeric IDs) >[!WARNING] -> The formal 'spec' for [CSemVer](https://csemver.org) remains mostly silent on the point of -> the short format. See this [known issue](https://github.com/CK-Build/csemver.org/issues/2). +> The formal 'spec' for [CSemVer](https://csemver.org) remains mostly silent on the point +> of the short format. See this [known issue](https://github.com/CK-Build/csemver.org/issues/2). > Since, the existence of that form was to support NuGet V2, which is now obsolete, this > library does not support the short form at all. (This choice keeps documentation clarity > [NOT SUPPORTED] and implementation simplicity) ------ -1 `SemVer` contains constructors accepting an -`AlhpanumericOrdering` enumeration to identify the ordering expected for a given instance. -Unfortunately, major repositories using SemVer have chosen to use different comparisons. Thus, -a consumer is required to specify if the version is compared insensitive or not. - +1Unfortunately, major repositories using SemVer have +chosen to use different comparisons. Thus, a consumer is required to know a-priori if the +version is compared insensitive or not. Thus all constructors accept an enum indicating +the sort ordering to use. Additional, parsing accepts an IFormatProvider, which should +provide an `AlphaNumeirvOrdering` value to specify the ordering. If none is provided, the +default is used. (SemVer uses CaseSensitive comparisons, CSemVer and CSemVerCI ALWAYS use +case insensitive) `IComparer` instances are available for cases where the versions +are from mixed sources and the application wishes to order the versions. diff --git a/src/Ubiquity.NET.Versioning/SemVer.cs b/src/Ubiquity.NET.Versioning/SemVer.cs index 3650230..0b9109e 100644 --- a/src/Ubiquity.NET.Versioning/SemVer.cs +++ b/src/Ubiquity.NET.Versioning/SemVer.cs @@ -278,7 +278,7 @@ internal static bool TryParse( ArgumentNullException.ThrowIfNull( s ); provider ??= SemVerFormatProvider.CaseSensitive; - IResult parseResult = SemVerGrammar.SemanticVersion(GetOrdering(provider)).TryParse(s); + IResult parseResult = SemVerGrammar.SemanticVersion(provider.GetOrdering()).TryParse(s); if(parseResult.Failed(out ex)) { result = default; @@ -364,10 +364,5 @@ private static ImmutableArray ValidateElementsWithParser( return value.Value; } - - private static AlphaNumericOrdering GetOrdering(IFormatProvider? provider) - { - return (AlphaNumericOrdering?)provider?.GetFormat(typeof(AlphaNumericOrdering)) ?? AlphaNumericOrdering.None; - } } }