Add abstract DirectiveSubsystem

The core parser no longer supports the special "directive" syntax,
but this abstract class provides a reusable implementation of
handling directive syntax in a subsystem using preprocessing.

Author: KathleenDollard

src/System.CommandLine.Subsystems.Tests/AlternateSubsystems.cs

@@ -1,7 +1,9 @@
 // Copyright (c) .NET Foundation and contributors. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+using System.CommandLine.Directives;
 using System.CommandLine.Subsystems;
+using System.CommandLine.Subsystems.Annotations;
 
 namespace System.CommandLine.Subsystems.Tests
 {
@@ -65,5 +67,13 @@ protected override CliExit TearDown(CliExit cliExit)
             }
         }
 
+        internal class StringDirectiveSubsystem(IAnnotationProvider? annotationProvider = null)
+            : DirectiveSubsystem("other",SubsystemKind.Other, annotationProvider)
+        { }
+
+        internal class BooleanDirectiveSubsystem(IAnnotationProvider? annotationProvider = null)
+            : DirectiveSubsystem("diagram", SubsystemKind.Other,  annotationProvider)
+        { }
+
     }
 }

src/System.CommandLine.Subsystems.Tests/DirectiveSubsystemTests.cs

@@ -0,0 +1,41 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using FluentAssertions;
+using System.CommandLine.Directives;
+using System.CommandLine.Parsing;
+using Xunit;
+
+namespace System.CommandLine.Subsystems.Tests;
+
+public class DirectiveSubsystemTests
+{
+
+    // For Boolean tests see DiagramSubsystemTests
+
+    [Theory]
+    [ClassData(typeof(TestData.Directive))]
+    // TODO: Not sure why these tests are passing
+    public void String_directive_supplies_string_or_default_and_is_activated_only_when_requested(
+        string input, bool expectedBoolIsActive, bool expectedStringIsActive, string? expectedValue)
+    {
+        CliRootCommand rootCommand = [new CliCommand("x")];
+        var configuration = new CliConfiguration(rootCommand);
+        var stringSubsystem = new AlternateSubsystems.StringDirectiveSubsystem();
+        var boolSubsystem = new AlternateSubsystems.BooleanDirectiveSubsystem();
+        var args = CliParser.SplitCommandLine(input).ToList().AsReadOnly();
+
+        Subsystem.Initialize(stringSubsystem, configuration, args);
+        Subsystem.Initialize(boolSubsystem, configuration, args);
+
+        var parseResult = CliParser.Parse(rootCommand, input, configuration);
+        var stringIsActive = Subsystem.GetIsActivated(stringSubsystem, parseResult);
+        var boolIsActive = Subsystem.GetIsActivated(boolSubsystem, parseResult);
+        var actualValue = stringSubsystem.Value;
+
+        boolIsActive.Should().Be(expectedBoolIsActive);
+        stringIsActive.Should().Be(expectedStringIsActive);
+        actualValue.Should().Be(expectedValue);
+
+    }
+}

src/System.CommandLine.Subsystems.Tests/System.CommandLine.Subsystems.Tests.csproj

@@ -31,6 +31,7 @@
     -->
     <Compile Include="AlternateSubsystems.cs" />
     <Compile Include="Constants.cs" />
+    <Compile Include="DirectiveSubsystemTests.cs" />
     <Compile Include="PipelineTests.cs" />
     <Compile Include="TestData.cs" />
     <Compile Include="VersionFunctionalTests.cs" />

src/System.CommandLine.Subsystems.Tests/TestData.cs

@@ -30,4 +30,29 @@ internal class Version : IEnumerable<object[]>
 
         IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
     }
+
+    internal class Directive : IEnumerable<object[]>
+    {
+        private readonly List<object[]> _data =
+        [
+            ["[diagram]", true, false, null],
+            ["[other:Hello]", false, true, "Hello"],
+            ["[diagram] x", true, false, null],
+            ["[diagram] -o", true, false, null],
+            ["[diagram] -v", true, false, null],
+            ["[diagram] x -v", true, false, null],
+            ["[diagramX]", false, false, null],
+            ["[diagram] [other:Hello]", true, true, "Hello"],
+            ["x", false, false, null],
+            ["-o", false, false, null],
+            ["x -x", false, false, null],
+            [null, false, false, null],
+            ["", false, false, null],
+            //["[diagram] [other Goodbye]", true, true, "Goodbye"],This is a new test that demos new feature, but is also broken
+        ];
+
+        public IEnumerator<object[]> GetEnumerator() => _data.GetEnumerator();
+
+        IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
+    }
 }

src/System.CommandLine.Subsystems/Directives/DirectiveSubsystem.cs

@@ -0,0 +1,60 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using System.CommandLine.Parsing;
+using System.CommandLine.Subsystems;
+
+namespace System.CommandLine.Directives;
+
+public abstract class DirectiveSubsystem : CliSubsystem
+{
+    public string? Value { get; private set; }
+    public bool Found { get; private set; }
+    public string Id { get; }
+    public Location? Location { get; private set; }
+
+    public DirectiveSubsystem(string name, SubsystemKind kind, IAnnotationProvider? annotationProvider = null, string? id = null)
+        : base(name, kind, annotationProvider: annotationProvider)
+    {
+        Id = id ?? name;
+    }
+
+    protected internal override CliConfiguration Initialize(InitializationContext context)
+    {
+        for (int i = 0; i < context.Args.Count; i++)
+        {
+            var arg = context.Args[i];
+            if (arg[0] == '[') // It looks like a directive, see if it is the one we want
+            {
+                var start = arg.IndexOf($"[{Id}");
+                // Protect against matching substrings, such as "diagramX" matching "diagram" - but longer string may be valid for a different directive and we may still find the one we want
+                if (start >= 0)
+                {
+                    var end = arg.IndexOf("]", start) + 1;
+                    var nextChar = arg[start + Id.Length + 1];
+                    if (nextChar is ']' or ':')
+                    {
+                        Found = true;
+                        if (nextChar == ':')
+                        {
+                            Value = arg[(start + Id.Length + 2)..(end - 1)];
+                        }
+                        Location = new Location(arg.Substring(start, end - start), Location.User, i, null, start);
+                        context.Configuration.AddPreprocessedLocation(Location);
+                        break;
+                    }
+                }
+            }
+            else if (i > 0) // First position might be ExeName, but directives are not legal after other tokens appear
+            {
+                break;
+            }
+        }
+
+        return context.Configuration;
+    }
+
+    protected internal override bool GetIsActivated(ParseResult? parseResult)
+        => Found;
+
+}