add HelpBuilder.Write(IOption)

Author: jonsequitur

src/System.CommandLine.Tests/Help/HelpBuilderTests.cs

@@ -10,6 +10,7 @@
 using FluentAssertions;
 using System.Linq;
 using System.Text;
+using FluentAssertions.Execution;
 using Xunit;
 using Xunit.Abstractions;
 using static System.Environment;
@@ -1089,15 +1090,15 @@ public void Options_section_does_not_contain_hidden_argument()
             var command = new Command("the-command", "Does things.");
             var opt1 = new Option("option1")
             {
-                Argument = new Argument<int>()
+                Argument = new Argument<int>
                 {
                     Name = "the-hidden",
                     IsHidden = true
                 }
             };
             var opt2 = new Option("option2")
             {
-                Argument = new Argument<int>()
+                Argument = new Argument<int>
                 {
                     Name = "the-visible",
                     IsHidden = false
@@ -1238,7 +1239,7 @@ public void Option_aliases_are_shown_before_long_names_regardless_of_alphabetica
         }
 
         [Fact]
-        public void Help_describes_default_value_for_option_with_defaultable_argument()
+        public void Help_describes_default_value_for_option_with_argument_having_default_value()
         {
             var argument = new Argument
             {
@@ -1289,6 +1290,28 @@ public void Help_should_not_contain_default_value_for_hidden_argument_defined_fo
             help.Should().NotContain($"[default: the-arg-value]");
         }
 
+        [Fact]
+        public void Option_help_can_be_requested_in_isolation()
+        {
+            var option = new Option(
+                new[] { "-z", "-a", "--zzz", "--aaa" },
+                "from a to z");
+
+            _helpBuilder.Write(option);
+
+            using var _ = new AssertionScope();
+
+            var output = _console.Out.ToString();
+
+            output
+                .Should()
+                .NotContain("Options");
+
+            output
+                .Should()
+                .Be("-a, -z, --aaa, --zzz    from a to z");
+        }
+
         #endregion Options
 
         #region Subcommands

src/System.CommandLine/Help/HelpBuilder.cs

@@ -70,6 +70,18 @@ public virtual void Write(ICommand command)
             AddAdditionalArguments(command);
         }
 
+        public virtual void Write(IOption option)
+        {
+            if (option is null)
+            {
+                throw new ArgumentNullException(nameof(option));
+            }
+
+            var item = GetOptionHelpItems(option).ToList()[0];
+
+            Console.Out.Write($"{item.Invocation}    {item.Description}");
+        }
+
         protected int CurrentIndentation => _indentationLevel * IndentationSize;
 
         /// <summary>
@@ -121,7 +133,6 @@ private void AppendBlankLine()
             Console.Out.WriteLine();
         }
 
-
         /// <summary>
         /// Writes whitespace to the console based on the provided offset,
         /// defaulting to the <see cref="CurrentIndentation"/>
@@ -203,7 +214,9 @@ private void AppendDescription(string description)
         /// Maximum number of characters accross all <see cref="HelpItem">help items</see>
         /// occupied by the invocation text
         /// </param>
-        protected void AppendHelpItem(HelpItem helpItem, int maxInvocationWidth)
+        protected void AppendHelpItem(
+            HelpItem helpItem, 
+            int maxInvocationWidth)
         {
             if (helpItem is null)
             {
@@ -346,11 +359,6 @@ protected virtual string DefaultValueHint(IArgument argument, bool isSingleArgum
                 _ => ""
             };
 
-        /// <summary>
-        /// Formats the help rows for a given option
-        /// </summary>
-        /// <param name="symbol"></param>
-        /// <returns>A new <see cref="HelpItem"/></returns>
         private IEnumerable<HelpItem> GetOptionHelpItems(ISymbol symbol)
         {
             var rawAliases = symbol
@@ -416,7 +424,7 @@ protected virtual void AddSynopsis(ICommand command)
             }
 
             var title = $"{command.Name}:";
-            HelpSection.Write(this, title, command.Description);
+            HelpSection.WriteHeading(this, title, command.Description);
         }
 
         /// <summary>
@@ -477,7 +485,7 @@ protected virtual void AddUsage(ICommand command)
                 usage.Add(Usage.AdditionalArguments);
             }
 
-            HelpSection.Write(this, Usage.Title, string.Join(" ", usage.Where(u => !string.IsNullOrWhiteSpace(u))));
+            HelpSection.WriteHeading(this, Usage.Title, string.Join(" ", usage.Where(u => !string.IsNullOrWhiteSpace(u))));
         }
 
         private string FormatArgumentUsage(IReadOnlyCollection<IArgument> arguments)
@@ -553,7 +561,10 @@ protected virtual void AddArguments(ICommand command)
                 commands.Add(command);
             }
 
-            HelpSection.Write(this, Arguments.Title, commands, GetArgumentHelpItems);
+            HelpSection.WriteItems(
+                this,
+                Arguments.Title,
+                commands.SelectMany(GetArgumentHelpItems).Distinct().ToArray());
         }
 
         /// <summary>
@@ -564,12 +575,15 @@ protected virtual void AddArguments(ICommand command)
         protected virtual void AddOptions(ICommand command)
         {
             var options = command
-                .Children
-                .OfType<IOption>()
-                .Where(ShouldShowHelp)
-                .ToArray();
-
-            HelpSection.Write(this, Options.Title, options, GetOptionHelpItems);
+                          .Children
+                          .OfType<IOption>()
+                          .Where(ShouldShowHelp)
+                          .ToArray();
+
+            HelpSection.WriteItems(
+                this,
+                Options.Title,
+                options.SelectMany(GetOptionHelpItems).Distinct().ToArray());
         }
 
         /// <summary>
@@ -580,12 +594,14 @@ protected virtual void AddOptions(ICommand command)
         protected virtual void AddSubcommands(ICommand command)
         {
             var subcommands = command
-                .Children
-                .OfType<ICommand>()
-                .Where(ShouldShowHelp)
-                .ToArray();
-
-            HelpSection.Write(this, Commands.Title, subcommands, GetOptionHelpItems);
+                              .Children
+                              .OfType<ICommand>()
+                              .Where(ShouldShowHelp)
+                              .ToArray();
+
+            HelpSection.WriteItems(this, 
+                              Commands.Title,
+                              subcommands.SelectMany(GetOptionHelpItems).ToArray());
         }
 
         protected virtual void AddAdditionalArguments(ICommand command)
@@ -595,7 +611,7 @@ protected virtual void AddAdditionalArguments(ICommand command)
                 return;
             }
 
-            HelpSection.Write(this, AdditionalArguments.Title, AdditionalArguments.Description);
+            HelpSection.WriteHeading(this, AdditionalArguments.Title, AdditionalArguments.Description);
         }
 
         private bool ShouldDisplayArgumentHelp(ICommand? command)
@@ -650,12 +666,12 @@ protected bool Equals(HelpItem other) =>
 
         private static class HelpSection
         {
-            public static void Write(
+            public static void WriteHeading(
                 HelpBuilder builder,
                 string title,
                 string? description = null)
             {
-                if (!ShouldWrite(description, null))
+                if (!ShouldWrite(description, Array.Empty<ISymbol>()))
                 {
                     return;
                 }
@@ -667,34 +683,35 @@ public static void Write(
                 builder.AppendBlankLine();
             }
 
-            public static void Write(
+            public static void WriteItems(
                 HelpBuilder builder,
                 string title,
-                IReadOnlyCollection<ISymbol>? usageItems = null,
-                Func<ISymbol, IEnumerable<HelpItem>>? formatter = null,
+                IReadOnlyCollection<HelpItem> usageItems,
                 string? description = null)
             {
-                if (!ShouldWrite(description, usageItems))
+                if (usageItems.Count == 0)
                 {
                     return;
                 }
 
                 AppendHeading(builder, title);
                 builder.Indent();
+
                 AddDescription(builder, description);
-                AddInvocation(builder, usageItems, formatter);
+                AddInvocation(builder, usageItems);
+
                 builder.Outdent();
                 builder.AppendBlankLine();
             }
 
-            private static bool ShouldWrite(string? description, IReadOnlyCollection<ISymbol>? usageItems)
+            private static bool ShouldWrite(string? description, IReadOnlyCollection<ISymbol> usageItems)
             {
                 if (!string.IsNullOrWhiteSpace(description))
                 {
                     return true;
                 }
 
-                return usageItems?.Any() == true;
+                return usageItems.Count > 0;
             }
 
             private static void AppendHeading(HelpBuilder builder, string? title = null)
@@ -719,14 +736,8 @@ private static void AddDescription(HelpBuilder builder, string? description = nu
 
             private static void AddInvocation(
                 HelpBuilder builder,
-                IReadOnlyCollection<ISymbol>? symbols,
-                Func<ISymbol, IEnumerable<HelpItem>>? formatter)
+                IReadOnlyCollection<HelpItem> helpItems)
             {
-                var helpItems = symbols
-                    .SelectMany(formatter)
-                    .Distinct()
-                    .ToList();
-
                 var maxWidth = helpItems
                     .Select(line => line.Invocation.Length)
                     .OrderByDescending(textLength => textLength)