More ANTLR Utils and refactoring (#32)

* * Renamed MsgLevel =< MessageLevel
    - Avoids en-us acronym and clarifies intent better fitting with other names.

* Moved types out of command line into general core and runtime.
General refactoring of code to unify and eliminate redundancy of abstractions. There was a LOT of duplication of abstraction between command line and runtime that is now moved to the Extensions library.

* Argument validation now moved to runtime independent "Requires" static class.
    - This contains the implementation which depending on targeted framework may be polyFilled.
    - This keeps intent clearer AND supports multi-targetting without pre-processor conditionals on all targets or compilations that support C#14 'extension' keyword.
* Added SourceLocation to contain both the URI of the source text AND the range for the location.
* Added more ANTLR common support
* Removed shared source library
    - All of that functionality is now in Ubiquity.NET.Extensions

>[!IMPORTANT]
> The existing tests were updated to the refactoring and all
> pass. The new functionality does NOT have testing yet.

* * Updated demo app to account for refactoring

* Updated docs and behavior of `Requires.NotDisposed` to avoid negative logic and provide clarity of intent.
* new semantics allow use as a drop-in replacement for `ObjectDisposedException.ThrowIf`

Author: smaillet

Directory.Packages.props

@@ -30,12 +30,7 @@
     <PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic" Version="5.0.0" />
     <PackageVersion Include="Microsoft.CodeAnalysis.Analyzers" Version="4.14.0" />
     <PackageVersion Include="Microsoft.CodeAnalysis.VisualBasic.Features" Version="4.14.0" />
-    <PackageVersion Include="Basic.Reference.Assemblies" Version="1.8.4" />
 
-    <!-- Until https://github.com/jaredpar/basic-reference-assemblies/issues/78 is resolved these are a specific version ref -->
-    <PackageVersion Include="Basic.Reference.Assemblies.Net80" Version="1.8.3" />
-    <PackageVersion Include="Basic.Reference.Assemblies.Net90" Version="1.8.4" />
-    <PackageVersion Include="Basic.Reference.Assemblies.Net100" Version="1.8.4" />
     <PackageVersion Include="PolySharp" Version="1.15.0" />
     <PackageVersion Include="System.Buffers" Version="4.6.1" />
     <PackageVersion Include="System.Collections.Immutable" Version="9.0.0" />

IgnoredWords.dic

@@ -103,6 +103,7 @@ invocable
 jit
 len
 Lexer
+lhs
 LibLLVM
 Licensor
 Llilum
@@ -158,6 +159,7 @@ referenceable
 Relocations
 repl
 repo
+rhs
 RMW
 runtimes
 RValue

docfx/ReadMe.md

@@ -87,8 +87,15 @@ possible.
 
 ### Lists
 The largest intrusion of the XML into the source is that of lists. The XML doc comments
-official support is to use the `<list>` tag. However, that is VERY intrusive and doesn't
-easily support sub-lists. Consider:
+official support is to use the `<list>` tag. For an example of how intrusive and ugly these
+can become see this [Blog Article](https://documentation.contiem.com/HelpAuthoringTools/UseListsAndTablesInXmlComments.html)
+>[!NOTE]
+> The output shown in that article is using a theoretcial rendering. It is ***NOT*** how the
+> IDE Will present the text. Usually the IDE is not as "pretty".
+
+#### Bulleted lists
+Unfortunately, the XML doc comments for a bulleted list (and any other form really) is VERY
+intrusive and doesn't easily support sub-lists. Consider:
 
 ``` C#
 /// Additional steps might include:
@@ -122,7 +129,7 @@ Which one would ***YOU*** rather encounter in code? Which one is easier to under
 reading the source? This repo chooses the latter. (If you favor the former, perhaps you
 should reconsider... :grinning:)
 
-#### How to handle lists
+##### How to handle bulleted lists
 There is little that can be done to alter the rendering of any editor support, at most an
 editor might allow specification of a CSS file, but that is the lowest priority of doc
 comments. Readability by maintainers of the docs AND the rendering for final docs used by
@@ -151,3 +158,24 @@ render properly in final docs.
             1) Turning this off can greatly reduce the noise AND reduce the problems of
                different rendering as lists are generally not used in the other elements.
 
+#### Tables
+There's sadly no simple rendering of these. Many user requests for a simpler markdown tag
+have gone unresolved. The docfx tool will render tables from the XML comment form though
+so a pattern of implementing them is possible
+
+#### Guidance for tables
+1) Avoid using them if at all possible.
+    - This is the simplest advice to give for these, they are ugly and intrusive so avoid
+      them whenever possible.
+2) If they are unavoidable or alternate representations leads to even uglier forms then use
+   the following guidance.
+
+``` C#
+/// <list type="table">
+/// <listheader><term>{Header 1}</term><term>{Header 2}</term></listheader>
+/// <item><term>{Row 1, Col 1}</term><term>{Row 1, Col 2}</term></item>
+/// <item><term>{Row 2, Col 2}</term><term>{Row 2, Col 2}</term></item>
+/// </list>
+```
+If a table needs more than 3 columns this gets ugly, fast, don't do that. Re-think the docs,
+use an additional markdown file that includes a simpler form of the table, anything else...

src/DemoCommandLineSrcGen/Program.cs

@@ -9,6 +9,7 @@
 using System.Threading.Tasks;
 
 using Ubiquity.NET.CommandLine;
+using Ubiquity.NET.Extensions;
 
 namespace TestNamespace
 {
@@ -25,7 +26,7 @@ public static async Task<int> Main( string[] args )
             };
 
             // start with information level for parsing; parsed options might specify different level
-            var reporter = new ColoredConsoleReporter( MsgLevel.Information );
+            var reporter = new ColoredConsoleReporter( MessageLevel.Information );
 
             return await TestOptions.BuildRootCommand( ( options, ct ) => AppMainAsync( options, reporter, ct ) )
                                     .ParseAndInvokeResultAsync( reporter, cts.Token, args );

src/DemoCommandLineSrcGen/TestOptions.cs

@@ -6,15 +6,11 @@
 using System.IO;
 using System.Linq;
 
-using Ubiquity.NET.CommandLine;
 using Ubiquity.NET.CommandLine.GeneratorAttributes;
+using Ubiquity.NET.Extensions;
 
 namespace TestNamespace
 {
-    // It is important to understand how "required" is handled in the underlying command line handler
-    // in System.CommandLine. The semantics are:
-    //     When the command is invoked, the value may not be null.
-    // That is, it is NOT evaluated during parse, ONLY during invocation.
     [RootCommand( Description = "Root command for tests" )]
     internal partial class TestOptions
     {
@@ -23,7 +19,7 @@ internal partial class TestOptions
         public required DirectoryInfo SomePath { get; init; }
 
         [Option( "-v", Description = "Verbosity Level" )]
-        public MsgLevel Verbosity { get; init; } = MsgLevel.Information;
+        public MessageLevel Verbosity { get; init; } = MessageLevel.Information;
 
         [Option( "-b", Description = "Test Some existing Path", Required = true )]
         [FolderValidation( FolderValidation.ExistingOnly )]

src/Ubiquity.NET.ANTLR.Utils/AntlrErrorListenerAdapter.cs

@@ -0,0 +1,85 @@
+// Copyright (c) Ubiquity.NET Contributors. All rights reserved.
+// Licensed under the Apache-2.0 WITH LLVM-exception license. See the LICENSE.md file in the project root for full license information.
+
+namespace Ubiquity.NET.ANTLR.Utils
+{
+    /// <summary>Adapter to translate ANTLR error listeners to an <see cref="IDiagnosticReporter"/></summary>
+    /// <remarks>
+    /// <para>This intentionally ignores the <see cref="TextWriter"/> provided by ANTLR and uses the <see cref="IDiagnosticReporter"/>
+    /// provided in the constructor. This allows a much greater level of flexibility in reporting of diagnostics from
+    /// a parser. Especially in abstracting the underlying parse technology from the diagnostic reporting</para>
+    /// <para>
+    /// The <see cref="SeverityMap"/> is used to allow for future adaptation of the parser to map errors from a
+    /// recognizer state, which is not stable if the grammar changes. This ensures that the ID values remain unique
+    /// even if the underlying grammar changes.
+    /// </para>
+    /// <para>The <see cref="DiagnosticMessage.Subcategory"/> for messages reported by this type are always null. If
+    /// an application desires specific sub categories then it can use it's own implementation of this type</para>
+    /// </remarks>
+    public class AntlrErrorListenerAdapter
+        : IAntlrErrorListener<int>
+        , IAntlrErrorListener<IToken>
+    {
+        /// <summary>Initializes a new instance of the <see cref="AntlrErrorListenerAdapter"/> class</summary>
+        /// <param name="sourceName">Source name for all errors</param>
+        /// <param name="severityMap">Severity map to use when transforming errors</param>
+        /// <param name="formatter">Formatter to use to form a string version of the error code</param>
+        /// <param name="diagnosticReporter">Diagnostic reporter to adapt ANTL errors to</param>
+        /// <exception cref="ArgumentException"><paramref name="sourceName"/> is null or whitespace</exception>
+        public AntlrErrorListenerAdapter(
+            string sourceName,
+            IMessageLevelMap severityMap,
+            IDiagnosticIdFormatter formatter,
+            IDiagnosticReporter diagnosticReporter
+        )
+        {
+            Requires.NotNullOrWhiteSpace( sourceName );
+
+            SeverityMap = severityMap;
+            IdFormatter = formatter;
+            Reporter = diagnosticReporter;
+        }
+
+        /// <summary>Gets the severity mapping used when forming a diagnostic</summary>
+        public IMessageLevelMap SeverityMap { get; init; }
+
+        /// <summary>Gets the error ID mapping used when forming a diagnostic</summary>
+        public IDiagnosticIdFormatter IdFormatter { get; init; }
+
+        /// <summary>Gets the reporter this instance adapts to</summary>
+        public IDiagnosticReporter Reporter { get; init; }
+
+        /// <inheritdoc/>
+        public void SyntaxError( TextWriter output // ignored
+                               , IRecognizer recognizer
+                               , int offendingSymbol
+                               , int line
+                               , int charPositionInLine
+                               , string msg
+                               , RecognitionException? e
+                               )
+        {
+            var loc = new SourceLocation(recognizer.InputStream.SourceName, new SourcePosition(line, charPositionInLine, recognizer.InputStream.Index));
+            var code = new ScopedDiagnosticId(ParseSource.Lexical, recognizer.State );
+            var diagnostic = code.AsDiagnostic(SeverityMap, IdFormatter, msg, loc, subcategory: null);
+            Reporter.Report( diagnostic );
+        }
+
+        /// <inheritdoc/>
+        public void SyntaxError( TextWriter output // ignored
+                               , IRecognizer recognizer
+                               , IToken? offendingSymbol
+                               , int line
+                               , int charPositionInLine
+                               , string msg
+                               , RecognitionException? e
+                               )
+        {
+            var loc = new SourceLocation(recognizer.InputStream.SourceName, new SourcePosition(line, charPositionInLine, recognizer.InputStream.Index));
+            int id = e is ParseException pe ? pe.ErrorId : recognizer.State;
+            var code = new ScopedDiagnosticId(ParseSource.Syntactic, id );
+            var diagnostic = code.AsDiagnostic(SeverityMap, IdFormatter, msg, loc, subcategory: null);
+            Reporter.Report( diagnostic );
+        }
+    }
+}

src/Ubiquity.NET.ANTLR.Utils/AntlrParseErrorListenerAdapter.cs

@@ -0,0 +1,49 @@
+// Copyright (c) Ubiquity.NET Contributors. All rights reserved.
+// Licensed under the Apache-2.0 WITH LLVM-exception license. See the LICENSE.md file in the project root for full license information.
+
+using System.Threading;
+
+namespace Ubiquity.NET.ANTLR.Utils
+{
+    /// <summary>IParseTreeListener that provides support for cancellation</summary>
+    /// <remarks>
+    /// This class will throw an OperationCanceled from any method when the provided
+    /// <see cref="CancellationToken"/> has requested cancellation of the parse. Cancellable
+    /// </remarks>
+    public class CancellableParseTreeListener
+        : IParseTreeListener
+    {
+        /// <summary>Initializes a new instance of the <see cref="CancellableParseTreeListener"/> class.</summary>
+        /// <param name="ct">Token to use for detection of cancellation</param>
+        public CancellableParseTreeListener( CancellationToken ct )
+        {
+            CancelToken = ct;
+        }
+
+        /// <inheritdoc/>
+        public void EnterEveryRule( ParserRuleContext ctx )
+        {
+            CancelToken.ThrowIfCancellationRequested();
+        }
+
+        /// <inheritdoc/>
+        public void ExitEveryRule( ParserRuleContext ctx )
+        {
+            CancelToken.ThrowIfCancellationRequested();
+        }
+
+        /// <inheritdoc/>
+        public void VisitErrorNode( IErrorNode node )
+        {
+            CancelToken.ThrowIfCancellationRequested();
+        }
+
+        /// <inheritdoc/>
+        public void VisitTerminal( ITerminalNode node )
+        {
+            CancelToken.ThrowIfCancellationRequested();
+        }
+
+        private readonly CancellationToken CancelToken;
+    }
+}