Add an abstraction for help text generation

Author: natemcmaster

src/CommandLineUtils/CommandLineApplication.cs

@@ -10,6 +10,7 @@
 using System.Linq;
 using System.Text;
 using System.Threading.Tasks;
+using McMaster.Extensions.CommandLineUtils.HelpText;
 
 namespace McMaster.Extensions.CommandLineUtils
 {
@@ -20,6 +21,7 @@ namespace McMaster.Extensions.CommandLineUtils
     public partial class CommandLineApplication
     {
         private IConsole _console;
+        private IHelpTextGenerator _helpTextGenerator;
 
         /// <summary>
         /// Initializes a new instance of <see cref="CommandLineApplication"/>.
@@ -45,6 +47,17 @@ public CommandLineApplication(IConsole console)
         /// <param name="workingDirectory">The current working directory.</param>
         /// <param name="throwOnUnexpectedArg">Initial value for <see cref="ThrowOnUnexpectedArgument"/>.</param>
         public CommandLineApplication(IConsole console, string workingDirectory, bool throwOnUnexpectedArg)
+            : this(DefaultHelpTextGenerator.Singleton, console, workingDirectory, throwOnUnexpectedArg)
+        { }
+
+        /// <summary>
+        /// Initializes a new instance of <see cref="CommandLineApplication"/>.
+        /// </summary>
+        /// <param name="helpTextGenerator">The help text generator to use.</param>
+        /// <param name="console">The console implementation to use.</param>
+        /// <param name="workingDirectory">The current working directory.</param>
+        /// <param name="throwOnUnexpectedArg">Initial value for <see cref="ThrowOnUnexpectedArgument"/>.</param>
+        public CommandLineApplication(IHelpTextGenerator helpTextGenerator, IConsole console, string workingDirectory, bool throwOnUnexpectedArg)
         {
             if (console == null)
             {
@@ -62,13 +75,14 @@ public CommandLineApplication(IConsole console, string workingDirectory, bool th
             Arguments = new List<CommandArgument>();
             Commands = new List<CommandLineApplication>();
             RemainingArguments = new List<string>();
+            HelpTextGenerator = helpTextGenerator;
             Invoke = () => 0;
             ValidationErrorHandler = DefaultValidationErrorHandler;
             SetConsole(console);
         }
 
         private CommandLineApplication(CommandLineApplication parent, string name, bool throwOnUnexpectedArg)
-            : this(parent._console, parent.WorkingDirectory, throwOnUnexpectedArg)
+            : this(parent._helpTextGenerator, parent._console, parent.WorkingDirectory, throwOnUnexpectedArg)
         {
             Name = name;
             Parent = parent;
@@ -81,6 +95,15 @@ private CommandLineApplication(CommandLineApplication parent, string name, bool
         /// </summary>
         public CommandLineApplication Parent { get; set; }
 
+        /// <summary>
+        /// The help text generator to use.
+        /// </summary>
+        public IHelpTextGenerator HelpTextGenerator
+        {
+            get => _helpTextGenerator;
+            set => _helpTextGenerator = value ?? throw new ArgumentNullException(nameof(value));
+        }
+
         /// <summary>
         /// The short name of the command. When this is a subcommand, it is the name of the word used to invoke the subcommand.
         /// </summary>
@@ -449,30 +472,29 @@ public void ShowHint()
         /// <summary>
         /// Show full help.
         /// </summary>
-        /// <param name="commandName">The subcommand for which to show help. Leave null to show for the current command.</param>
-        public void ShowHelp(string commandName = null)
+        public void ShowHelp()
         {
             for (var cmd = this; cmd != null; cmd = cmd.Parent)
             {
                 cmd.IsShowingInformation = true;
             }
 
-            Out.WriteLine(GetHelpText(commandName));
+            _helpTextGenerator.Generate(this, Out);
         }
 
         /// <summary>
-        /// Produces help text describing command usage.
+        /// This method has been marked as obsolete and will be removed in a future version.
+        /// The recommended replacement is <see cref="ShowHelp()" />.
         /// </summary>
-        /// <param name="commandName"></param>
-        /// <returns></returns>
-        public virtual string GetHelpText(string commandName = null)
+        /// <param name="commandName">The subcommand for which to show help. Leave null to show for the current command.</param>
+        [Obsolete("This method has been marked as obsolete and will be removed in a future version." +
+            "The recommended replacement is ShowHelp()")]
+        public void ShowHelp(string commandName = null)
         {
-            var headerBuilder = new StringBuilder("Usage:");
-            for (var cmd = this; cmd != null; cmd = cmd.Parent)
+            if (commandName == null)
             {
-                headerBuilder.Insert(6, string.Format(" {0}", cmd.Name));
+                ShowHelp();
             }
-
             CommandLineApplication target;
 
             if (commandName == null || string.Equals(Name, commandName, StringComparison.OrdinalIgnoreCase))
@@ -483,94 +505,55 @@ public virtual string GetHelpText(string commandName = null)
             {
                 target = Commands.SingleOrDefault(cmd => string.Equals(cmd.Name, commandName, StringComparison.OrdinalIgnoreCase));
 
-                if (target != null)
-                {
-                    headerBuilder.AppendFormat(" {0}", commandName);
-                }
-                else
+                if (target == null)
                 {
                     // The command name is invalid so don't try to show help for something that doesn't exist
                     target = this;
                 }
-
             }
 
-            var optionsBuilder = new StringBuilder();
-            var commandsBuilder = new StringBuilder();
-            var argumentsBuilder = new StringBuilder();
+            target.ShowHelp();
+        }
 
-            var arguments = target.Arguments.Where(a => a.ShowInHelpText).ToList();
-            if (arguments.Any())
-            {
-                headerBuilder.Append(" [arguments]");
+        /// <summary>
+        /// Produces help text describing command usage.
+        /// </summary>
+        /// <returns>The help text.</returns>
+        public virtual string GetHelpText()
+        {
+            var sb = new StringBuilder();
+            _helpTextGenerator.Generate(this, new StringWriter(sb));
+            return sb.ToString();
+        }
 
-                argumentsBuilder.AppendLine();
-                argumentsBuilder.AppendLine("Arguments:");
-                var maxArgLen = arguments.Max(a => a.Name.Length);
-                var outputFormat = string.Format("  {{0, -{0}}}{{1}}", maxArgLen + 2);
-                foreach (var arg in arguments)
-                {
-                    argumentsBuilder.AppendFormat(outputFormat, arg.Name, arg.Description);
-                    argumentsBuilder.AppendLine();
-                }
-            }
+        /// <summary>
+        /// This method has been marked as obsolete and will be removed in a future version.
+        /// The recommended replacement is <see cref="GetHelpText()" />
+        /// </summary>
+        /// <param name="commandName"></param>
+        /// <returns></returns>
+        [Obsolete("This method has been marked as obsolete and will be removed in a future version." +
+            "The recommended replacement is GetHelpText()")]
+        public virtual string GetHelpText(string commandName = null)
+        {
+            CommandLineApplication target;
 
-            var options = target.GetOptions().Where(o => o.ShowInHelpText).ToList();
-            if (options.Any())
+            if (commandName == null || string.Equals(Name, commandName, StringComparison.OrdinalIgnoreCase))
             {
-                headerBuilder.Append(" [options]");
-
-                optionsBuilder.AppendLine();
-                optionsBuilder.AppendLine("Options:");
-                var maxOptLen = options.Max(o => o.Template?.Length ?? 0);
-                var outputFormat = string.Format("  {{0, -{0}}}{{1}}", maxOptLen + 2);
-                foreach (var opt in options)
-                {
-                    optionsBuilder.AppendFormat(outputFormat, opt.Template, opt.Description);
-                    optionsBuilder.AppendLine();
-                }
+                target = this;
             }
-
-            var commands = target.Commands.Where(c => c.ShowInHelpText).ToList();
-            if (commands.Any())
+            else
             {
-                headerBuilder.Append(" [command]");
-
-                commandsBuilder.AppendLine();
-                commandsBuilder.AppendLine("Commands:");
-                var maxCmdLen = commands.Max(c => c.Name?.Length ?? 0);
-                var outputFormat = string.Format("  {{0, -{0}}}{{1}}", maxCmdLen + 2);
-                foreach (var cmd in commands.OrderBy(c => c.Name))
-                {
-                    commandsBuilder.AppendFormat(outputFormat, cmd.Name, cmd.Description);
-                    commandsBuilder.AppendLine();
-                }
+                target = Commands.SingleOrDefault(cmd => string.Equals(cmd.Name, commandName, StringComparison.OrdinalIgnoreCase));
 
-                if (OptionHelp != null)
+                if (target == null)
                 {
-                    commandsBuilder.AppendLine();
-                    commandsBuilder.AppendFormat($"Use \"{target.Name} [command] --{OptionHelp.LongName}\" for more information about a command.");
-                    commandsBuilder.AppendLine();
+                    // The command name is invalid so don't try to show help for something that doesn't exist
+                    target = this;
                 }
             }
 
-            if (target.AllowArgumentSeparator)
-            {
-                headerBuilder.Append(" [[--] <arg>...]");
-            }
-
-            headerBuilder.AppendLine();
-
-            var nameAndVersion = new StringBuilder();
-            nameAndVersion.AppendLine(GetFullNameAndVersion());
-            nameAndVersion.AppendLine();
-
-            return nameAndVersion.ToString()
-                + headerBuilder.ToString()
-                + argumentsBuilder.ToString()
-                + optionsBuilder.ToString()
-                + commandsBuilder.ToString()
-                + target.ExtendedHelpText;
+            return target.GetHelpText();
         }
 
         /// <summary>

src/CommandLineUtils/HelpText/DefaultHelpTextGenerator.cs

@@ -0,0 +1,120 @@
+// Copyright (c) Nate McMaster.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Text;
+
+namespace McMaster.Extensions.CommandLineUtils.HelpText
+{
+    /// <summary>
+    /// A default implementation of help text generation.
+    /// </summary>
+    public class DefaultHelpTextGenerator : IHelpTextGenerator
+    {
+        /// <summary>
+        /// A singleton instance of <see cref="DefaultHelpTextGenerator" />.
+        /// </summary>
+        public static DefaultHelpTextGenerator Singleton { get; } = new DefaultHelpTextGenerator();
+
+        private DefaultHelpTextGenerator() { }
+
+        /// <inheritdoc />
+        public void Generate(CommandLineApplication application, TextWriter output)
+        {
+            var nameAndVersion = application.GetFullNameAndVersion();
+            if (!string.IsNullOrEmpty(nameAndVersion))
+            {
+                output.WriteLine(nameAndVersion);
+                output.WriteLine();
+            }
+
+            output.Write("Usage:");
+            var stack = new Stack<string>();
+            for (var cmd = application; cmd != null; cmd = cmd.Parent)
+            {
+                stack.Push(cmd.Name);
+            }
+
+            while (stack.Count > 0)
+            {
+                output.Write(' ');
+                output.Write(stack.Pop());
+            }
+
+            var arguments = application.Arguments.Where(a => a.ShowInHelpText).ToList();
+            var options = application.GetOptions().Where(o => o.ShowInHelpText).ToList();
+            var commands = application.Commands.Where(c => c.ShowInHelpText).ToList();
+
+            if (arguments.Any())
+            {
+                output.Write(" [arguments]");
+            }
+
+            if (options.Any())
+            {
+                output.Write(" [options]");
+            }
+
+            if (commands.Any())
+            {
+                output.Write(" [command]");
+            }
+
+            if (application.AllowArgumentSeparator)
+            {
+                output.Write(" [[--] <arg>...]");
+            }
+
+            output.WriteLine();
+
+            if (arguments.Any())
+            {
+                output.WriteLine();
+                output.WriteLine("Arguments:");
+                var maxArgLen = arguments.Max(a => a.Name.Length);
+                var outputFormat = string.Format("  {{0, -{0}}}{{1}}", maxArgLen + 2);
+                foreach (var arg in arguments)
+                {
+                    output.Write(outputFormat, arg.Name, arg.Description);
+                    output.WriteLine();
+                }
+            }
+
+            if (options.Any())
+            {
+                output.WriteLine();
+                output.WriteLine("Options:");
+                var maxOptLen = options.Max(o => o.Template?.Length ?? 0);
+                var outputFormat = string.Format("  {{0, -{0}}}{{1}}", maxOptLen + 2);
+                foreach (var opt in options)
+                {
+                    output.Write(outputFormat, opt.Template, opt.Description);
+                    output.WriteLine();
+                }
+            }
+
+            if (commands.Any())
+            {
+                output.WriteLine();
+                output.WriteLine("Commands:");
+                var maxCmdLen = commands.Max(c => c.Name?.Length ?? 0);
+                var outputFormat = string.Format("  {{0, -{0}}}{{1}}", maxCmdLen + 2);
+                foreach (var cmd in commands.OrderBy(c => c.Name))
+                {
+                    output.Write(outputFormat, cmd.Name, cmd.Description);
+                    output.WriteLine();
+                }
+
+                if (application.OptionHelp != null)
+                {
+                    output.WriteLine();
+                    output.WriteLine($"Use \"{application.Name} [command] --{application.OptionHelp.LongName}\" for more information about a command.");
+                }
+            }
+
+            output.Write(application.ExtendedHelpText);
+        }
+    }
+}

src/CommandLineUtils/HelpText/IHelpTextGenerator.cs

@@ -0,0 +1,20 @@
+// Copyright (c) Nate McMaster.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+using System.IO;
+
+namespace McMaster.Extensions.CommandLineUtils.HelpText
+{
+    /// <summary>
+    /// Generates help text for a command line application.
+    /// </summary>
+    public interface IHelpTextGenerator
+    {
+        /// <summary>
+        /// Generate help text for the application.
+        /// </summary>
+        /// <param name="application"></param>
+        /// <param name="output"></param>
+        void Generate(CommandLineApplication application, TextWriter output);
+    }
+}