configuration

src/System.CommandLine.ApiCompatibility.Tests/ApiCompatibilityApprovalTests.System_CommandLine_api_is_not_changed.approved.txt

@@ -71,7 +71,6 @@ System.CommandLine
     public static CommandLineBuilder AddMiddleware(this CommandLineBuilder builder, System.CommandLine.Invocation.InvocationMiddleware middleware, System.CommandLine.Invocation.MiddlewareOrder order = Default)
     public static CommandLineBuilder AddMiddleware(this CommandLineBuilder builder, System.Action<System.CommandLine.Invocation.InvocationContext> onInvoke, System.CommandLine.Invocation.MiddlewareOrder order = Default)
     public static CommandLineBuilder CancelOnProcessTermination(this CommandLineBuilder builder, System.Nullable<System.TimeSpan> timeout = null)
-    public static CommandLineBuilder EnableDirectives(this CommandLineBuilder builder, System.Boolean value = True)
     public static CommandLineBuilder EnablePosixBundling(this CommandLineBuilder builder, System.Boolean value = True)
     public static CommandLineBuilder RegisterWithDotnetSuggest(this CommandLineBuilder builder)
     public static CommandLineBuilder UseDefaults(this CommandLineBuilder builder)
@@ -90,8 +89,8 @@ System.CommandLine
     public static CommandLineBuilder UseVersionOption(this CommandLineBuilder builder)
     public static CommandLineBuilder UseVersionOption(this CommandLineBuilder builder, System.String[] aliases)
   public class CommandLineConfiguration
-    .ctor(Command command, System.Boolean enablePosixBundling = True, System.Boolean enableDirectives = True, System.Boolean enableTokenReplacement = True, LocalizationResources resources = null, System.Collections.Generic.IReadOnlyList<System.CommandLine.Invocation.InvocationMiddleware> middlewarePipeline = null, System.Func<System.CommandLine.Binding.BindingContext,System.CommandLine.Help.HelpBuilder> helpBuilderFactory = null, System.CommandLine.Parsing.TryReplaceToken tokenReplacer = null)
-    public System.Boolean EnableDirectives { get; }
+    .ctor(Command command, System.Boolean enablePosixBundling = True, System.Boolean enableTokenReplacement = True, LocalizationResources resources = null, System.Collections.Generic.IReadOnlyList<System.CommandLine.Invocation.InvocationMiddleware> middlewarePipeline = null, System.Func<System.CommandLine.Binding.BindingContext,System.CommandLine.Help.HelpBuilder> helpBuilderFactory = null, System.CommandLine.Parsing.TryReplaceToken tokenReplacer = null)
+    public System.Collections.Generic.IReadOnlyList<Directive> Directives { get; }
     public System.Boolean EnablePosixBundling { get; }
     public System.Boolean EnableTokenReplacement { get; }
     public LocalizationResources LocalizationResources { get; }
@@ -107,11 +106,11 @@ System.CommandLine
   public static class ConsoleExtensions
     public static System.Void Write(this IConsole console, System.String value)
     public static System.Void WriteLine(this IConsole console, System.String value)
-  public class DirectiveCollection, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<System.String,System.Collections.Generic.IEnumerable<System.String>>>, System.Collections.IEnumerable
+  public class Directive : Symbol
+    .ctor(System.String name, System.String description = null, System.Action<System.CommandLine.Invocation.InvocationContext> syncHandler = null, System.Func<System.CommandLine.Invocation.InvocationContext,System.Threading.CancellationToken,System.Threading.Tasks.Task> asyncHandler = null)
+    public System.Collections.Generic.IEnumerable<System.CommandLine.Completions.CompletionItem> GetCompletions(System.CommandLine.Completions.CompletionContext context)
+  public class EnvironmentVariablesDirective : Directive
     .ctor()
-    public System.Boolean Contains(System.String name)
-    public System.Collections.Generic.IEnumerator<System.Collections.Generic.KeyValuePair<System.String,System.Collections.Generic.IEnumerable<System.String>>> GetEnumerator()
-    public System.Boolean TryGetValues(System.String name, ref System.Collections.Generic.IReadOnlyList<System.String> values)
   public static class Handler
     public static System.Void SetHandler(this Command command, System.Action<System.CommandLine.Invocation.InvocationContext> handle)
     public static System.Void SetHandler(this Command command, System.Action handle)
@@ -210,6 +209,8 @@ System.CommandLine
     public static Option<System.IO.DirectoryInfo> AcceptExistingOnly(this Option<System.IO.DirectoryInfo> option)
     public static Option<System.IO.FileSystemInfo> AcceptExistingOnly(this Option<System.IO.FileSystemInfo> option)
     public static Option<T> AcceptExistingOnly<T>(this Option<T> option)
+  public class ParseDirective : Directive
+    .ctor(System.Int32 errorExitCode = 1)
   public class ParseResult
     public System.CommandLine.Parsing.CommandResult CommandResult { get; }
     public System.Collections.Generic.IReadOnlyDictionary<System.String,System.Collections.Generic.IReadOnlyList<System.String>> Directives { get; }
@@ -221,6 +222,7 @@ System.CommandLine
     public System.CommandLine.Parsing.ArgumentResult FindResultFor(Argument argument)
     public System.CommandLine.Parsing.CommandResult FindResultFor(Command command)
     public System.CommandLine.Parsing.OptionResult FindResultFor(Option option)
+    public System.CommandLine.Parsing.DirectiveResult FindResultFor(Directive directive)
     public System.CommandLine.Parsing.SymbolResult FindResultFor(Symbol symbol)
     public System.CommandLine.Completions.CompletionContext GetCompletionContext()
     public System.Collections.Generic.IEnumerable<System.CommandLine.Completions.CompletionItem> GetCompletions(System.Nullable<System.Int32> position = null)
@@ -231,6 +233,8 @@ System.CommandLine
     public static System.String ExecutableName { get; }
     public static System.String ExecutablePath { get; }
     .ctor(System.String description = )
+  public class SuggestDirective : Directive
+    .ctor()
   public abstract class Symbol
     public System.String Description { get; set; }
     public System.Boolean IsHidden { get; set; }
@@ -393,6 +397,10 @@ System.CommandLine.Parsing
     public System.Collections.Generic.IEnumerable<SymbolResult> Children { get; }
     public System.CommandLine.Command Command { get; }
     public Token Token { get; }
+  public class DirectiveResult : SymbolResult
+    public System.CommandLine.Directive Directive { get; }
+    public Token Token { get; }
+    public System.String Value { get; }
   public class OptionResult : SymbolResult
     public System.Boolean IsImplicit { get; }
     public System.CommandLine.Option Option { get; }
@@ -427,6 +435,7 @@ System.CommandLine.Parsing
     public ArgumentResult FindResultFor(System.CommandLine.Argument argument)
     public CommandResult FindResultFor(System.CommandLine.Command command)
     public OptionResult FindResultFor(System.CommandLine.Option option)
+    public DirectiveResult FindResultFor(System.CommandLine.Directive directive)
     public T GetValue<T>(Argument<T> argument)
     public T GetValue<T>(Option<T> option)
     public System.String ToString()

src/System.CommandLine.Tests/DirectiveTests.cs

@@ -146,8 +146,7 @@ public void Directives_can_be_disabled()
                     new RootCommand
                     {
                         new Argument<List<string>>()
-                    },
-                    enableDirectives: false));
+                    }));
 
             var result = parser.Parse("[hello]");
 

src/System.CommandLine/Builder/CommandLineBuilder.cs

@@ -23,18 +23,6 @@ public class CommandLineBuilder
         /// <inheritdoc cref="CommandLineConfiguration.ParseErrorReportingExitCode"/>
         internal int? ParseErrorReportingExitCode;
 
-        /// <inheritdoc cref="CommandLineConfiguration.EnableDirectives"/>
-        internal bool EnableDirectives = true;
-
-        /// <inheritdoc cref="CommandLineConfiguration.EnableEnvironmentVariableDirective"/>
-        internal bool EnableEnvironmentVariableDirective;
-
-        /// <inheritdoc cref="CommandLineConfiguration.ParseDirectiveExitCode"/>
-        internal int? ParseDirectiveExitCode;
-
-        /// <inheritdoc cref="CommandLineConfiguration.EnableSuggestDirective"/>
-        internal bool EnableSuggestDirective;
-
         /// <inheritdoc cref="CommandLineConfiguration.MaxLevenshteinDistance"/>
         internal int MaxLevenshteinDistance;
 
@@ -98,19 +86,18 @@ internal LocalizationResources LocalizationResources
 
         internal TryReplaceToken? TokenReplacer;
 
+        internal List<Directive>? Directives;
+
         /// <summary>
         /// Creates a parser based on the configuration of the command line builder.
         /// </summary>
         public Parser Build() =>
             new(
                 new CommandLineConfiguration(
                     Command,
+                    Directives,
                     enablePosixBundling: EnablePosixBundling,
-                    enableDirectives: EnableDirectives,
                     enableTokenReplacement: EnableTokenReplacement,
-                    enableEnvironmentVariableDirective: EnableEnvironmentVariableDirective,
-                    parseDirectiveExitCode: ParseDirectiveExitCode,
-                    enableSuggestDirective: EnableSuggestDirective,
                     parseErrorReportingExitCode: ParseErrorReportingExitCode,
                     maxLevenshteinDistance: MaxLevenshteinDistance,
                     exceptionHandler: ExceptionHandler,

src/System.CommandLine/Builder/CommandLineBuilderExtensions.cs

@@ -9,8 +9,6 @@
 using System.CommandLine.Parsing;
 using System.IO;
 using System.Threading;
-using System.Threading.Tasks;
-using static System.Environment;
 using Process = System.CommandLine.Invocation.Process;
 
 namespace System.CommandLine
@@ -40,22 +38,6 @@ public static CommandLineBuilder CancelOnProcessTermination(
             return builder;
         }
 
-        /// <summary>
-        /// Enables the parser to recognize command line directives.
-        /// </summary>
-        /// <param name="builder">A command line builder.</param>
-        /// <param name="value"><see langword="true" /> to enable directives. <see langword="false" /> to parse directive-like tokens in the same way as any other token.</param>
-        /// <returns>The same instance of <see cref="CommandLineBuilder"/>.</returns>
-        /// <seealso href="/dotnet/standard/commandline/syntax#directives">Command-line directives</seealso> 
-        /// <seealso cref="DirectiveCollection"/>
-        public static CommandLineBuilder EnableDirectives(
-            this CommandLineBuilder builder,
-            bool value = true)
-        {
-            builder.EnableDirectives = value;
-            return builder;
-        }
-
         /// <summary>
         /// Enables the parser to recognize and expand POSIX-style bundled options.
         /// </summary>
@@ -141,15 +123,13 @@ await feature.EnsureRegistered(async () =>
             return builder;
         }
 
-        /// <summary>
-        /// Enables the use of the <c>[env:key=value]</c> directive, allowing environment variables to be set from the command line during invocation.
-        /// </summary>
+        /// <inheritdoc cref="EnvironmentVariablesDirective"/>
         /// <param name="builder">A command line builder.</param>
         /// <returns>The same instance of <see cref="CommandLineBuilder"/>.</returns>
         public static CommandLineBuilder UseEnvironmentVariableDirective(
             this CommandLineBuilder builder)
         {
-            builder.EnableEnvironmentVariableDirective = true;
+            (builder.Directives ??= new()).Add(new EnvironmentVariablesDirective());
 
             return builder;
         }
@@ -348,17 +328,16 @@ public static CommandLineBuilder AddMiddleware(
             return builder;
         }
 
-        /// <summary>
-        /// Enables the use of the <c>[parse]</c> directive, which when specified on the command line will short circuit normal command handling and display a diagram explaining the parse result for the command line input.
-        /// </summary>
+
+        /// <inheritdoc cref="ParseDirective"/>
         /// <param name="builder">A command line builder.</param>
         /// <param name="errorExitCode">If the parse result contains errors, this exit code will be used when the process exits.</param>
         /// <returns>The same instance of <see cref="CommandLineBuilder"/>.</returns>
         public static CommandLineBuilder UseParseDirective(
             this CommandLineBuilder builder,
             int errorExitCode = 1)
         {
-            builder.ParseDirectiveExitCode = errorExitCode;
+            (builder.Directives ??= new()).Add(new ParseDirective(errorExitCode));
 
             return builder;
         }
@@ -378,16 +357,13 @@ public static CommandLineBuilder UseParseErrorReporting(
             return builder;
         }
 
-        /// <summary>
-        /// Enables the use of the <c>[suggest]</c> directive which when specified in command line input short circuits normal command handling and writes a newline-delimited list of suggestions suitable for use by most shells to provide command line completions.
-        /// </summary>
-        /// <remarks>The <c>dotnet-suggest</c> tool requires the suggest directive to be enabled for an application to provide completions.</remarks>
+        /// <inheritdoc cref="SuggestDirective"/>
         /// <param name="builder">A command line builder.</param>
         /// <returns>The same instance of <see cref="CommandLineBuilder"/>.</returns>
         public static CommandLineBuilder UseSuggestDirective(
             this CommandLineBuilder builder)
         {
-            builder.EnableSuggestDirective = true;
+            (builder.Directives ??= new()).Add(new SuggestDirective());
 
             return builder;
         }

src/System.CommandLine/CommandLineConfiguration.cs

@@ -21,22 +21,6 @@ public class CommandLineConfiguration
         /// </summary>
         internal readonly Action<Exception, InvocationContext>? ExceptionHandler;
 
-        /// <summary>
-        /// Enables the use of the <c>[env:key=value]</c> directive, allowing environment variables to be set from the command line during invocation.
-        /// </summary>
-        internal readonly bool EnableEnvironmentVariableDirective;
-
-        /// <summary>
-        /// If the parse result contains errors, this exit code will be used when the process exits.
-        /// </summary>
-        internal readonly int? ParseDirectiveExitCode;
-
-        /// <summary>
-        /// Enables the use of the <c>[suggest]</c> directive which when specified in command line input short circuits normal command handling and writes a newline-delimited list of suggestions suitable for use by most shells to provide command line completions.
-        /// </summary>
-        /// <remarks>The <c>dotnet-suggest</c> tool requires the suggest directive to be enabled for an application to provide completions.</remarks>
-        internal readonly bool EnableSuggestDirective;
-
         /// <summary>
         /// The exit code to use when parser errors occur.
         /// </summary>
@@ -51,8 +35,6 @@ public class CommandLineConfiguration
 
         internal readonly IReadOnlyList<InvocationMiddleware> Middleware;
 
-        internal readonly IReadOnlyList<Directive>? Directives;
-
         private Func<BindingContext, HelpBuilder>? _helpBuilderFactory;
         private TryReplaceToken? _tokenReplacer;
 
@@ -61,7 +43,6 @@ public class CommandLineConfiguration
         /// </summary>
         /// <param name="command">The root command for the parser.</param>
         /// <param name="enablePosixBundling"><see langword="true"/> to enable POSIX bundling; otherwise, <see langword="false"/>.</param>
-        /// <param name="enableDirectives"><see langword="true"/> to enable directive parsing; otherwise, <see langword="false"/>.</param>
         /// <param name="enableTokenReplacement"><see langword="true"/> to enable token replacement; otherwise, <see langword="false"/>.</param>
         /// <param name="resources">Provide custom validation messages.</param>
         /// <param name="middlewarePipeline">Provide a custom middleware pipeline.</param>
@@ -70,25 +51,32 @@ public class CommandLineConfiguration
         public CommandLineConfiguration(
             Command command,
             bool enablePosixBundling = true,
-            bool enableDirectives = true,
             bool enableTokenReplacement = true,
             LocalizationResources? resources = null,
             IReadOnlyList<InvocationMiddleware>? middlewarePipeline = null,
             Func<BindingContext, HelpBuilder>? helpBuilderFactory = null,
             TryReplaceToken? tokenReplacer = null)
-            : this(command, enablePosixBundling, enableDirectives, enableTokenReplacement, false, null, false, null, 0, null,
-                  resources, middlewarePipeline, helpBuilderFactory, tokenReplacer, null)
+            : this(
+                  command,
+                  directives: null,
+                  enablePosixBundling: enablePosixBundling,
+                  enableTokenReplacement: enableTokenReplacement,
+                  parseErrorReportingExitCode: null,
+                  maxLevenshteinDistance: 0,
+                  processTerminationTimeout: null,
+                  resources: resources,
+                  middlewarePipeline: middlewarePipeline,
+                  helpBuilderFactory: helpBuilderFactory,
+                  tokenReplacer: tokenReplacer,
+                  exceptionHandler: null)
         {
         }
 
         internal CommandLineConfiguration(
             Command command,
+            List<Directive>? directives,
             bool enablePosixBundling,
-            bool enableDirectives,
             bool enableTokenReplacement,
-            bool enableEnvironmentVariableDirective,
-            int? parseDirectiveExitCode,
-            bool enableSuggestDirective,
             int? parseErrorReportingExitCode,
             int maxLevenshteinDistance,
             TimeSpan? processTerminationTimeout,
@@ -99,12 +87,9 @@ internal CommandLineConfiguration(
             Action<Exception, InvocationContext>? exceptionHandler)
         {
             RootCommand = command ?? throw new ArgumentNullException(nameof(command));
+            Directives = directives is not null ? directives : Array.Empty<Directive>();
             EnableTokenReplacement = enableTokenReplacement;
             EnablePosixBundling = enablePosixBundling;
-            EnableDirectives = enableDirectives || enableEnvironmentVariableDirective || parseDirectiveExitCode.HasValue || enableSuggestDirective;
-            EnableEnvironmentVariableDirective = enableEnvironmentVariableDirective;
-            ParseDirectiveExitCode = parseDirectiveExitCode;
-            EnableSuggestDirective = enableSuggestDirective;
             ParseErrorReportingExitCode = parseErrorReportingExitCode;
             MaxLevenshteinDistance = maxLevenshteinDistance;
             ProcessTerminationTimeout = processTerminationTimeout;
@@ -128,9 +113,9 @@ internal static HelpBuilder DefaultHelpBuilderFactory(BindingContext context, in
         }
 
         /// <summary>
-        /// Gets whether directives are enabled.
+        /// Gets the enabled directives.
         /// </summary>
-        public bool EnableDirectives { get; }
+        public IReadOnlyList<Directive> Directives { get; }
 
         /// <summary>
         /// Gets a value indicating whether POSIX bundling is enabled.