Allow custom help providers (#1259)

Allow custom help providers

* Version option will show in help even with a default command

* Reserve `-v` and `--version` as special Spectre.Console command line arguments (nb. breaking change for Spectre.Console users who have a default command with a settings class that uses either of these switches).

* Help writer correctly determines if trailing commands exist and whether to display them as optional or mandatory in the usage statement.

* Ability to control the number of indirect commands to display in the help text when the command itself doesn't have any examples of its own. Defaults to 5 (for backward compatibility) but can be set to any integer or zero to disable completely.

* Significant increase in unit test coverage for the help writer.

* Minor grammatical improvements to website documentation.

src/Spectre.Console.Cli/Internal/Modelling/CommandArgument.cs

@@ -1,6 +1,6 @@
 namespace Spectre.Console.Cli;
 
-internal sealed class CommandArgument : CommandParameter
+internal sealed class CommandArgument : CommandParameter, ICommandArgument
 {
     public string Value { get; }
     public int Position { get; set; }

src/Spectre.Console.Cli/Internal/Modelling/CommandInfo.cs

@@ -1,6 +1,6 @@
 namespace Spectre.Console.Cli;
-
-internal sealed class CommandInfo : ICommandContainer
+
+internal sealed class CommandInfo : ICommandContainer, ICommandInfo
 {
     public string Name { get; }
     public HashSet<string> Aliases { get; }
@@ -20,8 +20,14 @@ internal sealed class CommandInfo : ICommandContainer
 
     // only branches can have a default command
     public CommandInfo? DefaultCommand => IsBranch ? Children.FirstOrDefault(c => c.IsDefaultCommand) : null;
-    public bool IsHidden { get; }
-
+    public bool IsHidden { get; }
+
+    IReadOnlyList<ICommandInfo> Help.ICommandContainer.Commands => Children.Cast<ICommandInfo>().ToList();
+    ICommandInfo? Help.ICommandContainer.DefaultCommand => DefaultCommand;
+    IReadOnlyList<ICommandParameter> ICommandInfo.Parameters => Parameters.Cast<ICommandParameter>().ToList();
+    ICommandInfo? ICommandInfo.Parent => Parent;
+    IReadOnlyList<string[]> Help.ICommandContainer.Examples => (IReadOnlyList<string[]>)Examples;
+
     public CommandInfo(CommandInfo? parent, ConfiguredCommand prototype)
     {
         Parent = parent;
@@ -48,19 +54,5 @@ internal sealed class CommandInfo : ICommandContainer
                 Description = description.Description;
             }
         }
-    }
-
-    public List<CommandInfo> Flatten()
-    {
-        var result = new Stack<CommandInfo>();
-
-        var current = this;
-        while (current != null)
-        {
-            result.Push(current);
-            current = current.Parent;
-        }
-
-        return result.ToList();
-    }
+    }
 }

src/Spectre.Console.Cli/Internal/Modelling/CommandModel.cs

@@ -1,14 +1,18 @@
 namespace Spectre.Console.Cli;
-
-internal sealed class CommandModel : ICommandContainer
+
+internal sealed class CommandModel : ICommandContainer, ICommandModel
 {
     public string? ApplicationName { get; }
     public ParsingMode ParsingMode { get; }
     public IList<CommandInfo> Commands { get; }
     public IList<string[]> Examples { get; }
-    public bool TrimTrailingPeriod { get; }
 
-    public CommandInfo? DefaultCommand => Commands.FirstOrDefault(c => c.IsDefaultCommand);
+    public CommandInfo? DefaultCommand => Commands.FirstOrDefault(c => c.IsDefaultCommand);
+
+    string ICommandModel.ApplicationName => GetApplicationName(ApplicationName);
+    IReadOnlyList<ICommandInfo> Help.ICommandContainer.Commands => Commands.Cast<ICommandInfo>().ToList();
+    ICommandInfo? Help.ICommandContainer.DefaultCommand => DefaultCommand;
+    IReadOnlyList<string[]> Help.ICommandContainer.Examples => (IReadOnlyList<string[]>)Examples;
 
     public CommandModel(
         CommandAppSettings settings,
@@ -17,22 +21,32 @@ internal sealed class CommandModel : ICommandContainer
     {
         ApplicationName = settings.ApplicationName;
         ParsingMode = settings.ParsingMode;
-        TrimTrailingPeriod = settings.TrimTrailingPeriod;
         Commands = new List<CommandInfo>(commands ?? Array.Empty<CommandInfo>());
         Examples = new List<string[]>(examples ?? Array.Empty<string[]>());
-    }
-
-    public string GetApplicationName()
+    }
+
+    /// <summary>
+    /// Gets the name of the application.
+    /// If the provided <paramref name="applicationName"/> is not null or empty,
+    /// it is returned. Otherwise the name of the current application
+    /// is determined based on the executable file's name.
+    /// </summary>
+    /// <param name="applicationName">The optional name of the application.</param>
+    /// <returns>
+    /// The name of the application, or a default value of "?" if no valid application name can be determined.
+    /// </returns>
+    private static string GetApplicationName(string? applicationName)
     {
         return
-            ApplicationName ??
+            applicationName ??
             Path.GetFileName(GetApplicationFile()) ?? // null is propagated by GetFileName
             "?";
     }
 
     private static string? GetApplicationFile()
     {
-        var location = Assembly.GetEntryAssembly()?.Location;
+        var location = Assembly.GetEntryAssembly()?.Location;
+
         if (string.IsNullOrWhiteSpace(location))
         {
             // this is special case for single file executable

src/Spectre.Console.Cli/Internal/Modelling/CommandOption.cs

@@ -1,6 +1,6 @@
 namespace Spectre.Console.Cli;
 
-internal sealed class CommandOption : CommandParameter
+internal sealed class CommandOption : CommandParameter, ICommandOption
 {
     public IReadOnlyList<string> LongNames { get; }
     public IReadOnlyList<string> ShortNames { get; }

src/Spectre.Console.Cli/Internal/Modelling/CommandParameter.cs

@@ -1,6 +1,6 @@
 namespace Spectre.Console.Cli;
-
-internal abstract class CommandParameter : ICommandParameterInfo
+
+internal abstract class CommandParameter : ICommandParameterInfo, ICommandParameter
 {
     public Guid Id { get; }
     public Type ParameterType { get; }
@@ -17,8 +17,10 @@ internal abstract class CommandParameter : ICommandParameterInfo
     public string PropertyName => Property.Name;
 
     public virtual bool WantRawValue => ParameterType.IsPairDeconstructable()
-        && (PairDeconstructor != null || Converter == null);
-
+        && (PairDeconstructor != null || Converter == null);
+
+    public bool IsFlag => ParameterKind == ParameterKind.Flag;
+
     protected CommandParameter(
         Type parameterType, ParameterKind parameterKind, PropertyInfo property,
         string? description, TypeConverterAttribute? converter,