From a6f8b6fa3903d846cdc2fbe715ca951d83af3107 Mon Sep 17 00:00:00 2001
From: Rob Mensching <rob@firegiant.com>
Date: Thu, 11 Aug 2022 17:40:06 -0700
Subject: Redesign command-line help to meet the needs of WiX v4

---
 .../BaseCommandLineCommand.cs                      | 40 +++++++++++++++++
 .../BaseExtensionCommandLine.cs                    |  9 ++--
 .../Data/CommandLineHelp.cs                        | 52 ++++++++++++++++++++++
 .../Data/CommandLineHelpCommand.cs                 | 31 +++++++++++++
 .../Data/CommandLineHelpSwitch.cs                  | 47 +++++++++++++++++++
 .../Data/ExtensionCommandLineSwitch.cs             | 20 ---------
 .../Data/ICommandLineCommand.cs                    | 12 ++---
 .../IExtensionCommandLine.cs                       |  6 +--
 8 files changed, 183 insertions(+), 34 deletions(-)
 create mode 100644 src/api/wix/WixToolset.Extensibility/BaseCommandLineCommand.cs
 create mode 100644 src/api/wix/WixToolset.Extensibility/Data/CommandLineHelp.cs
 create mode 100644 src/api/wix/WixToolset.Extensibility/Data/CommandLineHelpCommand.cs
 create mode 100644 src/api/wix/WixToolset.Extensibility/Data/CommandLineHelpSwitch.cs
 delete mode 100644 src/api/wix/WixToolset.Extensibility/Data/ExtensionCommandLineSwitch.cs

(limited to 'src/api')

diff --git a/src/api/wix/WixToolset.Extensibility/BaseCommandLineCommand.cs b/src/api/wix/WixToolset.Extensibility/BaseCommandLineCommand.cs
new file mode 100644
index 00000000..69a4f49f
--- /dev/null
+++ b/src/api/wix/WixToolset.Extensibility/BaseCommandLineCommand.cs
@@ -0,0 +1,40 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved. Licensed under the Microsoft Reciprocal License. See LICENSE.TXT file in the project root for full license information.
+
+namespace WixToolset.Extensibility
+{
+    using System.Threading;
+    using System.Threading.Tasks;
+    using WixToolset.Extensibility.Data;
+    using WixToolset.Extensibility.Services;
+
+    /// <summary>
+    /// Base class for a command-line command.
+    /// </summary>
+    public abstract class BaseCommandLineCommand : ICommandLineCommand
+    {
+        /// <summary>
+        /// See <see cref="ICommandLineCommand.ShowLogo" />
+        /// </summary>
+        public virtual bool ShowLogo => false;
+
+        /// <summary>
+        /// See <see cref="ICommandLineCommand.StopParsing" />
+        /// </summary>
+        public bool StopParsing { get; protected set; }
+
+        /// <summary>
+        /// See <see cref="ICommandLineCommand.ExecuteAsync" />
+        /// </summary>
+        public abstract Task<int> ExecuteAsync(CancellationToken cancellationToken);
+
+        /// <summary>
+        /// See <see cref="ICommandLineCommand.GetCommandLineHelp" />
+        /// </summary>
+        public abstract CommandLineHelp GetCommandLineHelp();
+
+        /// <summary>
+        /// See <see cref="ICommandLineCommand.TryParseArgument" />
+        /// </summary>
+        public abstract bool TryParseArgument(ICommandLineParser parser, string argument);
+    }
+}
diff --git a/src/api/wix/WixToolset.Extensibility/BaseExtensionCommandLine.cs b/src/api/wix/WixToolset.Extensibility/BaseExtensionCommandLine.cs
index c716ac7e..2690788b 100644
--- a/src/api/wix/WixToolset.Extensibility/BaseExtensionCommandLine.cs
+++ b/src/api/wix/WixToolset.Extensibility/BaseExtensionCommandLine.cs
@@ -2,8 +2,6 @@
 
 namespace WixToolset.Extensibility
 {
-    using System;
-    using System.Collections.Generic;
     using WixToolset.Extensibility.Data;
     using WixToolset.Extensibility.Services;
 
@@ -13,9 +11,12 @@ namespace WixToolset.Extensibility
     public abstract class BaseExtensionCommandLine : IExtensionCommandLine
     {
         /// <summary>
-        /// See <see cref="IExtensionCommandLine.CommandLineSwitches" />
+        /// See <see cref="IExtensionCommandLine.GetCommandLineHelp" />
         /// </summary>
-        public virtual IReadOnlyCollection<ExtensionCommandLineSwitch> CommandLineSwitches => Array.Empty<ExtensionCommandLineSwitch>();
+        public virtual CommandLineHelp GetCommandLineHelp()
+        {
+            return null;
+        }
 
         /// <summary>
         /// See <see cref="IExtensionCommandLine.PostParse" />
diff --git a/src/api/wix/WixToolset.Extensibility/Data/CommandLineHelp.cs b/src/api/wix/WixToolset.Extensibility/Data/CommandLineHelp.cs
new file mode 100644
index 00000000..52291947
--- /dev/null
+++ b/src/api/wix/WixToolset.Extensibility/Data/CommandLineHelp.cs
@@ -0,0 +1,52 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved. Licensed under the Microsoft Reciprocal License. See LICENSE.TXT file in the project root for full license information.
+
+namespace WixToolset.Extensibility.Data
+{
+    using System.Collections.Generic;
+
+    /// <summary>
+    /// A command line option (switch or command) description.
+    /// </summary>
+    public class CommandLineHelp
+    {
+        /// <summary>
+        /// Creates command line help.
+        /// </summary>
+        /// <param name="description">Description for the command line option.</param>
+        /// <param name="usage">Optional usage for the command line option.</param>
+        /// <param name="switches">Optional list of switches.</param>
+        /// <param name="commands">Optional list of commands.</param>
+        public CommandLineHelp(string description, string usage = null, IReadOnlyCollection<CommandLineHelpSwitch> switches = null, IReadOnlyCollection<CommandLineHelpCommand> commands = null)
+        {
+            this.Description = description;
+            this.Usage = usage;
+            this.Switches = switches;
+            this.Commands = commands;
+        }
+
+        /// <summary>
+        /// Description for the command line option.
+        /// </summary>
+        public string Description { get; set; }
+
+        /// <summary>
+        /// Usage for the command line option.
+        /// </summary>
+        public string Usage { get; set; }
+
+        /// <summary>
+        /// Optional additional notes for the command line option.
+        /// </summary>
+        public string Notes { get; set; }
+
+        /// <summary>
+        /// Optional list of command line switches.
+        /// </summary>
+        public IReadOnlyCollection<CommandLineHelpSwitch> Switches { get; set; }
+
+        /// <summary>
+        /// Optional list of command line commands.
+        /// </summary>
+        public IReadOnlyCollection<CommandLineHelpCommand> Commands { get; set; }
+    }
+}
diff --git a/src/api/wix/WixToolset.Extensibility/Data/CommandLineHelpCommand.cs b/src/api/wix/WixToolset.Extensibility/Data/CommandLineHelpCommand.cs
new file mode 100644
index 00000000..a9fc70f9
--- /dev/null
+++ b/src/api/wix/WixToolset.Extensibility/Data/CommandLineHelpCommand.cs
@@ -0,0 +1,31 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved. Licensed under the Microsoft Reciprocal License. See LICENSE.TXT file in the project root for full license information.
+
+namespace WixToolset.Extensibility.Data
+{
+    /// <summary>
+    /// A command line command description.
+    /// </summary>
+    public class CommandLineHelpCommand
+    {
+        /// <summary>
+        /// Creates help for command line command.
+        /// </summary>
+        /// <param name="name">Name of command.</param>
+        /// <param name="description">Description for command.</param>
+        public CommandLineHelpCommand(string name, string description)
+        {
+            Name = name;
+            Description = description;
+        }
+
+        /// <summary>
+        /// Name of command.
+        /// </summary>
+        public string Name { get; set; }
+
+        /// <summary>
+        /// Description of the command.
+        /// </summary>
+        public string Description { get; set; }
+    }
+}
diff --git a/src/api/wix/WixToolset.Extensibility/Data/CommandLineHelpSwitch.cs b/src/api/wix/WixToolset.Extensibility/Data/CommandLineHelpSwitch.cs
new file mode 100644
index 00000000..19c014ad
--- /dev/null
+++ b/src/api/wix/WixToolset.Extensibility/Data/CommandLineHelpSwitch.cs
@@ -0,0 +1,47 @@
+// Copyright (c) .NET Foundation and contributors. All rights reserved. Licensed under the Microsoft Reciprocal License. See LICENSE.TXT file in the project root for full license information.
+
+namespace WixToolset.Extensibility.Data
+{
+    /// <summary>
+    /// A command line switch description.
+    /// </summary>
+    public class CommandLineHelpSwitch
+    {
+        /// <summary>
+        /// Creates help for command line switch.
+        /// </summary>
+        /// <param name="name">Name of switch.</param>
+        /// <param name="description">Description for switch.</param>
+        public CommandLineHelpSwitch(string name, string description) : this(name, null, description)
+        {
+        }
+
+        /// <summary>
+        /// Creates help for command line switch.
+        /// </summary>
+        /// <param name="name">Name of switch.</param>
+        /// <param name="shortName">Optional short name of switch.</param>
+        /// <param name="description">Description for switch.</param>
+        public CommandLineHelpSwitch(string name, string shortName, string description)
+        {
+            Name = name;
+            ShortName = shortName;
+            Description = description;
+        }
+
+        /// <summary>
+        /// Name for switch.
+        /// </summary>
+        public string Name { get; set; }
+
+        /// <summary>
+        /// Optional short name for switch.
+        /// </summary>
+        public string ShortName { get; set; }
+
+        /// <summary>
+        /// Description of the switch.
+        /// </summary>
+        public string Description { get; set; }
+    }
+}
diff --git a/src/api/wix/WixToolset.Extensibility/Data/ExtensionCommandLineSwitch.cs b/src/api/wix/WixToolset.Extensibility/Data/ExtensionCommandLineSwitch.cs
deleted file mode 100644
index 14b5dabb..00000000
--- a/src/api/wix/WixToolset.Extensibility/Data/ExtensionCommandLineSwitch.cs
+++ /dev/null
@@ -1,20 +0,0 @@
-// Copyright (c) .NET Foundation and contributors. All rights reserved. Licensed under the Microsoft Reciprocal License. See LICENSE.TXT file in the project root for full license information.
-
-namespace WixToolset.Extensibility.Data
-{
-    /// <summary>
-    /// A command line option.
-    /// </summary>
-    public struct ExtensionCommandLineSwitch
-    {
-        /// <summary>
-        /// 
-        /// </summary>
-        public string Switch { get; set; }
-
-        /// <summary>
-        /// 
-        /// </summary>
-        public string Description { get; set; }
-    }
-}
diff --git a/src/api/wix/WixToolset.Extensibility/Data/ICommandLineCommand.cs b/src/api/wix/WixToolset.Extensibility/Data/ICommandLineCommand.cs
index b6c9ef3e..1f58bfb5 100644
--- a/src/api/wix/WixToolset.Extensibility/Data/ICommandLineCommand.cs
+++ b/src/api/wix/WixToolset.Extensibility/Data/ICommandLineCommand.cs
@@ -12,19 +12,19 @@ namespace WixToolset.Extensibility.Data
     public interface ICommandLineCommand
     {
         /// <summary>
-        /// Indicates the command-line should show help for the command.
+        /// Indicates the command-line should show the logo.
         /// </summary>
-        bool ShowHelp { get; set; }
+        bool ShowLogo { get; }
 
         /// <summary>
-        /// Indicates the command-line should show the command-line logo.
+        /// Indicates the command-line parsing can stop.
         /// </summary>
-        bool ShowLogo { get; set; }
+        bool StopParsing { get; }
 
         /// <summary>
-        /// Indicates the command-line parsing can stop.
+        /// Gets the help for this command.
         /// </summary>
-        bool StopParsing { get; }
+        CommandLineHelp GetCommandLineHelp();
 
         /// <summary>
         /// Executes the command.
diff --git a/src/api/wix/WixToolset.Extensibility/IExtensionCommandLine.cs b/src/api/wix/WixToolset.Extensibility/IExtensionCommandLine.cs
index f7b19955..304c30bb 100644
--- a/src/api/wix/WixToolset.Extensibility/IExtensionCommandLine.cs
+++ b/src/api/wix/WixToolset.Extensibility/IExtensionCommandLine.cs
@@ -2,7 +2,6 @@
 
 namespace WixToolset.Extensibility
 {
-    using System.Collections.Generic;
     using WixToolset.Extensibility.Data;
     using WixToolset.Extensibility.Services;
 
@@ -12,10 +11,9 @@ namespace WixToolset.Extensibility
     public interface IExtensionCommandLine
     {
         /// <summary>
-        /// Gets the supported command line types for this extension.
+        /// Gets the help for this extension.
         /// </summary>
-        /// <value>The supported command line types for this extension.</value>
-        IReadOnlyCollection<ExtensionCommandLineSwitch> CommandLineSwitches { get; }
+        CommandLineHelp GetCommandLineHelp();
 
         /// <summary>
         /// Called before the command-line is parsed.
-- 
cgit v1.2.3-55-g6feb