Help API adjustments (#1493)

jonsequitur · web-flow · commit fc76f3dfb638 · 2021-12-01T12:14:38.000-08:00
* remove IHelpBuilder

* make HelpBuilder.Layout an instance member

* fix warnings

* make Write virtual
diff --git a/src/System.CommandLine.Generator.Tests/GeneratedCommandHandlerTests.cs b/src/System.CommandLine.Generator.Tests/GeneratedCommandHandlerTests.cs
@@ -136,14 +136,14 @@ public async Task Can_generate_handler_with_well_know_parameters_types()
             InvocationContext? boundInvocationContext = null;
             IConsole? boundConsole = null;
             ParseResult? boundParseResult = null;
-            IHelpBuilder? boundHelpBuilder = null;
+            HelpBuilder? boundHelpBuilder = null;
             BindingContext? boundBindingContext = null;
 
             void Execute(
                 InvocationContext invocationContext,
                 IConsole console,
                 ParseResult parseResult,
-                IHelpBuilder helpBuilder,
+                HelpBuilder helpBuilder,
                 BindingContext bindingContext)
             {
                 boundInvocationContext = invocationContext;
@@ -155,7 +155,7 @@ void Execute(
 
             var command = new Command("command");
 
-            command.SetHandler<Action<InvocationContext, IConsole, ParseResult, IHelpBuilder, BindingContext>>(Execute);
+            command.SetHandler<Action<InvocationContext, IConsole, ParseResult, HelpBuilder, BindingContext>>(Execute);
 
             await command.InvokeAsync("command", _console);
 
diff --git a/src/System.CommandLine.Generator/WellKnownTypes.cs b/src/System.CommandLine.Generator/WellKnownTypes.cs
@@ -21,7 +21,7 @@ public WellKnownTypes(Compilation compilation, IEqualityComparer<ISymbol?> compa
             Console = GetType("System.CommandLine.IConsole");
             ParseResult = GetType("System.CommandLine.Parsing.ParseResult");
             InvocationContext = GetType("System.CommandLine.Invocation.InvocationContext");
-            HelpBuilder = GetType("System.CommandLine.Help.IHelpBuilder");
+            HelpBuilder = GetType("System.CommandLine.Help.HelpBuilder");
             BindingContext = GetType("System.CommandLine.Binding.BindingContext");
 
             INamedTypeSymbol GetType(string typeName)
diff --git a/src/System.CommandLine.Tests/Help/HelpBuilderExtensions.cs b/src/System.CommandLine.Tests/Help/HelpBuilderExtensions.cs
@@ -0,0 +1,17 @@
+// 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.Help;
+using System.IO;
+
+namespace System.CommandLine.Tests.Help
+{
+    public static class HelpBuilderExtensions
+    {
+        public static void Write(
+            this HelpBuilder builder,
+            ICommand command,
+            TextWriter writer) =>
+            builder.Write(new HelpContext(builder, command, writer));
+    }
+}
diff --git a/src/System.CommandLine.Tests/Help/HelpBuilderTests.Customization.cs b/src/System.CommandLine.Tests/Help/HelpBuilderTests.Customization.cs
@@ -205,46 +205,14 @@ public void Command_arguments_can_customize_second_column_text()
                 _console.ToString().Should().Contain(expected);
             }
 
-            [Fact]
-            public void Help_text_can_be_added_after_default_text_by_inheriting_HelpBuilder()
-            {
-                var parser = new CommandLineBuilder()
-                             .UseDefaults()
-                             .UseHelpBuilder(context => new CustomHelpBuilderThatAddsTextAfterDefaultText("The text to add"))
-                             .Build();
-
-                var console = new TestConsole();
-
-                parser.Invoke("-h", console);
-
-                console.Out.ToString().Should().EndWith("The text to add");
-            }
-
             [Fact]
             public void Customize_throws_when_symbol_is_null()
             {
                 Action action = () => new HelpBuilder(LocalizationResources.Instance).Customize(null!, "");
                 action.Should().Throw<ArgumentNullException>();
             }
         }
-
-        private class CustomHelpBuilderThatAddsTextAfterDefaultText : HelpBuilder
-        {
-            private readonly string _theTextToAdd;
-
-            public CustomHelpBuilderThatAddsTextAfterDefaultText(string theTextToAdd)
-                : base(LocalizationResources.Instance)
-            {
-                _theTextToAdd = theTextToAdd;
-            }
-
-            public override void Write(ICommand command, TextWriter writer, ParseResult parseResult)
-            {
-                base.Write(command, writer, parseResult);
-                writer.Write(_theTextToAdd);
-            }
-        }
-
+        
         private class CustomLocalizationResources : LocalizationResources
         {
             public string OverrideHelpDescriptionTitle { get; set; }
diff --git a/src/System.CommandLine.Tests/Help/HelpBuilderTests.cs b/src/System.CommandLine.Tests/Help/HelpBuilderTests.cs
@@ -5,8 +5,6 @@
 using System.Collections.Generic;
 using System.CommandLine.Builder;
 using System.CommandLine.Help;
-using System.CommandLine.IO;
-using System.CommandLine.Parsing;
 using System.IO;
 using System.Linq;
 using Xunit;
diff --git a/src/System.CommandLine.Tests/Invocation/InvocationPipelineTests.cs b/src/System.CommandLine.Tests/Invocation/InvocationPipelineTests.cs
@@ -279,7 +279,7 @@ public async Task When_no_help_builder_is_specified_it_uses_default_implementati
             bool handlerWasCalled = false;
 
             var command = new Command("help-command");
-            command.Handler = CommandHandler.Create((IHelpBuilder helpBuilder) =>
+            command.Handler = CommandHandler.Create((HelpBuilder helpBuilder) =>
             {
                 handlerWasCalled = true;
                 helpBuilder.Should().NotBeNull();
@@ -304,14 +304,14 @@ public async Task When_help_builder_factory_is_specified_it_is_used_to_create_th
 
             HelpBuilder createdHelpBuilder = null;
 
-            Func<BindingContext, IHelpBuilder> helpBuilderFactory = context =>
+            Func<BindingContext, HelpBuilder> helpBuilderFactory = context =>
             {
                 factoryWasCalled = true;
                 return createdHelpBuilder = new HelpBuilder(context.ParseResult.Parser.Configuration.LocalizationResources);
             };
 
             var command = new Command("help-command");
-            command.Handler = CommandHandler.Create((IHelpBuilder helpBuilder) =>
+            command.Handler = CommandHandler.Create((HelpBuilder helpBuilder) =>
             {
                 handlerWasCalled = true;
                 createdHelpBuilder.Should().NotBeNull();
diff --git a/src/System.CommandLine/Binding/BindingContext.cs b/src/System.CommandLine/Binding/BindingContext.cs
@@ -40,7 +40,7 @@ public BindingContext(
 
         internal IConsoleFactory? ConsoleFactory { get; set; }
 
-        internal IHelpBuilder HelpBuilder => (IHelpBuilder)ServiceProvider.GetService(typeof(IHelpBuilder))!;
+        internal HelpBuilder HelpBuilder => (HelpBuilder)ServiceProvider.GetService(typeof(HelpBuilder))!;
 
         /// <summary>
         /// The console to which output should be written during the current invocation.
diff --git a/src/System.CommandLine/Builder/CommandLineBuilder.cs b/src/System.CommandLine/Builder/CommandLineBuilder.cs
@@ -46,7 +46,7 @@ public CommandLineBuilder(Command? rootCommand = null)
         /// </summary>
         public ResponseFileHandling ResponseFileHandling { get; set; }
 
-        internal Func<BindingContext, IHelpBuilder>? HelpBuilderFactory { get; set; }
+        internal Func<BindingContext, HelpBuilder>? HelpBuilderFactory { get; set; }
 
         internal HelpOption? HelpOption { get; set; }
 
diff --git a/src/System.CommandLine/Builder/CommandLineBuilderExtensions.cs b/src/System.CommandLine/Builder/CommandLineBuilderExtensions.cs
@@ -467,13 +467,13 @@ internal static CommandLineBuilder UseHelp(
         }
 
         /// <summary>
-        /// Specifies an <see cref="IHelpBuilder"/> to be used to format help output when help is requested.
+        /// Specifies an <see cref="HelpBuilder"/> to be used to format help output when help is requested.
         /// </summary>
         /// <param name="builder">A command line builder.</param>
-        /// <param name="getHelpBuilder">A delegate that returns an instance of <see cref="IHelpBuilder"/></param>
+        /// <param name="getHelpBuilder">A delegate that returns an instance of <see cref="HelpBuilder"/></param>
         /// <returns>The same instance of <see cref="CommandLineBuilder"/>.</returns>
         public static TBuilder UseHelpBuilder<TBuilder>(this TBuilder builder,
-            Func<BindingContext, IHelpBuilder> getHelpBuilder)
+            Func<BindingContext, HelpBuilder> getHelpBuilder)
             where TBuilder : CommandLineBuilder
         {
             if (builder is null)
diff --git a/src/System.CommandLine/CommandLineConfiguration.cs b/src/System.CommandLine/CommandLineConfiguration.cs
@@ -17,7 +17,7 @@ namespace System.CommandLine
     public class CommandLineConfiguration
     {
         private readonly SymbolSet _symbols = new();
-        private Func<BindingContext, IHelpBuilder>? _helpBuilderFactory;
+        private Func<BindingContext, HelpBuilder>? _helpBuilderFactory;
 
         /// <summary>
         /// Initializes a new instance of the CommandLineConfiguration class.
@@ -38,7 +38,7 @@ public CommandLineConfiguration(
             LocalizationResources? resources = null,
             ResponseFileHandling responseFileHandling = ResponseFileHandling.ParseArgsAsLineSeparated,
             IReadOnlyList<InvocationMiddleware>? middlewarePipeline = null,
-            Func<BindingContext, IHelpBuilder>? helpBuilderFactory = null)
+            Func<BindingContext, HelpBuilder>? helpBuilderFactory = null)
         {
             RootCommand = command ?? throw new ArgumentNullException(nameof(command));
 
@@ -56,7 +56,7 @@ public CommandLineConfiguration(
             _helpBuilderFactory = helpBuilderFactory;
         }
 
-        private static IHelpBuilder DefaultHelpBuilderFactory(BindingContext context)
+        private static HelpBuilder DefaultHelpBuilderFactory(BindingContext context)
         {
             int maxWidth = int.MaxValue;
             if (context.Console is SystemConsole systemConsole)
@@ -115,7 +115,7 @@ private void AddGlobalOptionsToChildren(Command parentCommand)
         /// </summary>
         public LocalizationResources LocalizationResources { get; }
 
-        internal Func<BindingContext, IHelpBuilder> HelpBuilderFactory => _helpBuilderFactory ??= DefaultHelpBuilderFactory;
+        internal Func<BindingContext, HelpBuilder> HelpBuilderFactory => _helpBuilderFactory ??= DefaultHelpBuilderFactory;
 
         internal IReadOnlyList<InvocationMiddleware> Middleware { get; }
 
diff --git a/src/System.CommandLine/Help/HelpBuilder.cs b/src/System.CommandLine/Help/HelpBuilder.cs
@@ -9,13 +9,15 @@
 
 namespace System.CommandLine.Help
 {
-    /// <inheritdoc />
-    public class HelpBuilder : IHelpBuilder
+    /// <summary>
+    /// Formats output to be shown to users to describe how to use a command line tool.
+    /// </summary>
+    public class HelpBuilder 
     {
         private const string Indent = "  ";
 
         private Dictionary<ISymbol, Customization>? _customizationsBySymbol;
-        private static IEnumerable<HelpDelegate>? _layout;
+        private IEnumerable<HelpDelegate>? _layout;
 
         /// <param name="localizationResources">Resources used to localize the help output.</param>
         /// <param name="maxWidth">The maximum width in characters after which help output is wrapped.</param>
@@ -46,41 +48,31 @@ public HelpBuilder(
         public int MaxWidth { get; }
 
         /// <summary>
-        /// Writes help for the specified command.
+        /// Writes help output for the specified command.
         /// </summary>
-        /// <param name="command">The command to write help output for.</param>
-        /// <param name="writer">The writer to write help output to.</param>
-        /// <param name="parseResult">A parse result providing context for help formatting.</param>
-        public virtual void Write(ICommand command, TextWriter writer, ParseResult parseResult)
+        public virtual void Write(HelpContext context)
         {
-            if (command is null)
-            {
-                throw new ArgumentNullException(nameof(command));
-            }
-
-            if (parseResult is null)
+            if (context is null)
             {
-                throw new ArgumentNullException(nameof(parseResult));
+                throw new ArgumentNullException(nameof(context));
             }
 
-            if (command.IsHidden)
+            if (context.Command.IsHidden)
             {
                 return;
             }
 
-            var context = new HelpContext(this, parseResult, command, writer);
-
             foreach (var writeSection in Layout)
             {
                 writeSection(context);
-                writer.WriteLine();
+                context.Output.WriteLine();
             }
         }
 
         /// <summary>
         /// Gets the sections to be written for command line help.
         /// </summary>
-        public static IEnumerable<HelpDelegate> Layout => _layout ??= DefaultLayout();
+        public IEnumerable<HelpDelegate> Layout => _layout ??= DefaultLayout();
 
         /// <summary>
         /// Gets the default sections to be written for command line help.
diff --git a/src/System.CommandLine/Help/HelpBuilderExtensions.cs b/src/System.CommandLine/Help/HelpBuilderExtensions.cs
@@ -40,27 +40,5 @@ public static void Customize(
         {
             builder.Customize(symbol, firstColumnText, secondColumnText, defaultValue);
         }
-
-        /// <summary>
-        /// Writes help output for the specified command.
-        /// </summary>
-        /// <param name="builder">The help builder to write with.</param>
-        /// <param name="command">The command for which to write help output.</param>
-        /// <param name="writer">The writer to write output to.</param>
-        public static void Write(
-            this IHelpBuilder builder,
-            ICommand command,
-            TextWriter writer) =>
-            builder.Write(command, writer, ParseResult.Empty());
-
-        /// <summary>
-        /// Gets help for a command as a string.
-        /// </summary>
-        public static string FormatHelp(this IHelpBuilder helpBuilder, ICommand command, ParseResult parseResult)
-        {
-            using var output = new StringWriter();
-            helpBuilder.Write(command, output, parseResult);
-            return output.ToString();
-        }
     }
 }
diff --git a/src/System.CommandLine/Help/HelpContext.cs b/src/System.CommandLine/Help/HelpContext.cs
@@ -12,15 +12,29 @@ namespace System.CommandLine.Help
     public class HelpContext
     {
         /// <param name="helpBuilder">The current help builder.</param>
-        /// <param name="parseResult">The result of the current parse operation.</param>
         /// <param name="command">The command for which help is being formatted.</param>
         /// <param name="output">A text writer to write output to.</param>
-        public HelpContext(HelpBuilder helpBuilder, ParseResult parseResult, ICommand command, TextWriter output)
+        /// <param name="parseResult">The result of the current parse operation.</param>
+        /// <param name="maxWidth">The maximum width at which to format the text, used for wrapping text within multi-column output.</param>
+        public HelpContext(
+            HelpBuilder helpBuilder,
+            ICommand command,
+            TextWriter output,
+            ParseResult? parseResult = null,
+            int? maxWidth = int.MaxValue)
         {
             HelpBuilder = helpBuilder;
-            ParseResult = parseResult;
+            ParseResult = parseResult ?? ParseResult.Empty();
             Command = command;
             Output = output;
+            if (maxWidth is not null)
+            {
+                MaxWidth = maxWidth.Value;
+            }
+            else
+            {
+                MaxWidth = int.MaxValue;
+            }
         }
 
         /// <summary>
@@ -42,10 +56,10 @@ public HelpContext(HelpBuilder helpBuilder, ParseResult parseResult, ICommand co
         /// A text writer to write output to.
         /// </summary>
         public TextWriter Output { get; }
-    }
 
-    /// <summary>
-    /// Specifies help formatting behavior.
-    /// </summary>
-    public delegate void HelpDelegate(HelpContext context);
+        /// <summary>
+        /// The maximum width at which to format the text, used for wrapping text within multi-column output.
+        /// </summary>
+        public int MaxWidth { get; }
+    }
 }
diff --git a/src/System.CommandLine/Help/HelpDelegate.cs b/src/System.CommandLine/Help/HelpDelegate.cs
@@ -0,0 +1,10 @@
+﻿// 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.
+
+namespace System.CommandLine.Help
+{
+    /// <summary>
+    /// Specifies help formatting behavior for a section of command line help.
+    /// </summary>
+    public delegate void HelpDelegate(HelpContext context);
+}
diff --git a/src/System.CommandLine/Help/HelpResult.cs b/src/System.CommandLine/Help/HelpResult.cs
@@ -11,9 +11,17 @@ internal class HelpResult : IInvocationResult
         /// <inheritdoc />
         public void Apply(InvocationContext context)
         {
+            var output = context.Console.Out.CreateTextWriter();
+
+            var helpContext = new HelpContext(context.BindingContext.HelpBuilder,
+                                              context.ParseResult.CommandResult.Command,
+                                              output,
+                                              context.ParseResult,
+                                              (context.Console as SystemConsole)?.GetWindowWidth());
+
             context.BindingContext
                    .HelpBuilder
-                   .Write(context.ParseResult.CommandResult.Command, StandardStreamWriter.Create(context.Console.Out), context.ParseResult);
+                   .Write(helpContext);
         }
     }
-}
+}
diff --git a/src/System.CommandLine/Help/IHelpBuilder.cs b/src/System.CommandLine/Help/IHelpBuilder.cs
diff --git a/src/System.CommandLine/IO/StandardStreamWriter.cs b/src/System.CommandLine/IO/StandardStreamWriter.cs
diff --git a/src/System.CommandLine/Invocation/InvocationContext.cs b/src/System.CommandLine/Invocation/InvocationContext.cs
diff --git a/src/System.CommandLine/Invocation/ParseErrorResult.cs b/src/System.CommandLine/Invocation/ParseErrorResult.cs
diff --git a/src/System.CommandLine/Invocation/ServiceProvider.cs b/src/System.CommandLine/Invocation/ServiceProvider.cs
