Add a help option by default as long as it doesn't conflict with existing options.

natemcmaster · natemcmaster · commit 902cd965e767 · 2018-04-21T13:41:48.000-07:00
This removes the requirement for users to specify [HelpOption] in order to get generated help text.

Add [SuppressDefaultHelpOption] to the type or assembly if you wish to opt-out of this behavior change.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,7 +4,8 @@
 
 Minor improvement:
 
- - Automatically add conventions from attributes that implement IConvention and IMemberConvention
+ - Add conventions from attributes that implement IConvention and IMemberConvention
+ - Add a help option by default as long as it doesn't conflict with existing options
 
 ## [v2.2.1]
 
diff --git a/Directory.Build.props b/Directory.Build.props
@@ -18,7 +18,7 @@
     <IsPackable>false</IsPackable>
     <NoPackageAnalysis>true</NoPackageAnalysis>
     <LangVersion>7.2</LangVersion>
-    <AssemblyOriginatorKeyFile>$(MSBuildThisFileDirectory)build\StrongName.snk</AssemblyOriginatorKeyFile>
+    <AssemblyOriginatorKeyFile>$(MSBuildThisFileDirectory)src\StrongName.snk</AssemblyOriginatorKeyFile>
     <SignAssembly>true</SignAssembly>
     <PublicSign Condition="'$(OS)' != 'Windows_NT'">true</PublicSign>
 
diff --git a/README.md b/README.md
@@ -53,7 +53,6 @@ See [samples/](./samples/) for more examples, such as:
 using System;
 using McMaster.Extensions.CommandLineUtils;
 
-[HelpOption]
 public class Program
 {
     public static int Main(string[] args)
diff --git a/docfx_project/docs/concepts/help-text.md b/docfx_project/docs/concepts/help-text.md
@@ -1,61 +1,97 @@
 # Help Text
 
 CommandLineUtils provides API to automatically generate help text for a command line application.
-By default, the help text will only be shown if you indicate that a help option should exit.
 
-## Adding a help option
+## Configure the help option
+
+### Attribute API
+By default, three options will exist on the command line app that will show help: `-?`, `-h`, and `--help`.
+When users specify one of these, generated help text will display on the command line.
+
+```
+> MyApp.exe --help
+
+Usage: MyApp.exe [options]
+
+Options:
+  -?|-h|--help   Show help output
+```
+
+To customize the flags that can show help text, add an instance of [HelpOptionAttribute](xref:McMaster.Extensions.CommandLineUtils.HelpOptionAttribute) to your model type.
+
+```csharp
+[HelpOption("--my-custom-help-option")]
+public class Program
+```
+
+```
+> MyApp.exe --help
+Unrecognized option '--help'
+
+> MyApp.exe --my-custom-help-option
+
+Usage: MyApp.exe [options]
+
+Options:
+  --my-custom-help-option   Show help output
+```
+
+#### Disabling the default
+
+To disable the help option by default, add `[SuppressDefaultHelpOption]` to your program type or the containing assembly.
+
+```csharp
+// suppress the help option on all types define in this project
+[assembly: SuppressDefaultHelpOption]
+
+// disable help option on a specific command
+[SuppressDefaultHelpOption]
+public class MySecretProgram
+```
+
+### Builder API
+By default, the help text will only be shown if you define a help option on the command.
 
 Using the **builder API**, call [`.HelpOption()`](xref:McMaster.Extensions.CommandLineUtils.CommandLineApplicationExtensions.HelpOption(McMaster.Extensions.CommandLineUtils.CommandLineApplication)).
-```c#
+
+```csharp
 var app = new CommandLineApplication();
 app.HelpOption();
 ```
 
 This adds three flags to the command line app that will show help, `-?`, `-h`, and `--help`.
 You can change these flags by calling [`.HelpOption(string template)`](xref:McMaster.Extensions.CommandLineUtils.CommandLineApplication.HelpOption(System.String)) with a template string.
 
-```c#
+```csharp
 app.HelpOption("-m|--my-help");
 ```
 
-When using the **attribute API**, add an instance of [HelpOptionAttribute](xref:McMaster.Extensions.CommandLineUtils.HelpOptionAttribute) to your model type.
-
-```c#
-[HelpOption]
-public class Program
-```
-
-## Add a help option to all subcommands
+#### Add a help option to all subcommands
 
 If you have subcommands on your application, you can make a help option available on all subcommands without
 needing to explicitly add a HelpOption to each subcommand type or object. To do this, set `inherited` to true
 when adding the help option.
 
-```c#
+```csharp
 app.HelpOption(inherited: true);
 ```
 
-```c#
-[HelpOption(Inherited = true)]
-public class Program
-```
-
 ## Extending help text
 
 By default, the help text only includes information about arguments, options, and commands.
 If you would like to provide additional information, you can use the
 [ExtendedHelpText](xref:McMaster.Extensions.CommandLineUtils.CommandLineApplication.ExtendedHelpText)
 property to add additional information to help output.
 
-```c#
+```csharp
 var app = new CommandLineApplication();
 app.ExtendedHelpText = @"
 Remarks:
   This command should only be used on Tuesdays.
 ";
 ```
 
-```c#
+```csharp
 [Command(
     ExtendedHelpText = @"
 Remarks:
@@ -72,7 +108,7 @@ Help text generation can be completely customized by implementing the
 [IHelpTextGenerator](xref:McMaster.Extensions.CommandLineUtils.HelpText.IHelpTextGenerator)
 interface.
 
-```c#
+```csharp
 class MyHelpTextGenerator : IHelpTextGenerator
 {
     public void void Generate(CommandLineApplication application, TextWriter output)
diff --git a/docfx_project/docs/intro.md b/docfx_project/docs/intro.md
@@ -36,7 +36,6 @@
 using System;
 using McMaster.Extensions.CommandLineUtils;
 
-[HelpOption]
 public class Program
 {
     public static int Main(string[] args)
diff --git a/docfx_project/index.md b/docfx_project/index.md
@@ -40,7 +40,6 @@ See [samples](https://github.com/natemcmaster/CommandLineUtils/tree/master/sampl
 using System;
 using McMaster.Extensions.CommandLineUtils;
 
-[HelpOption]
 public class Program
 {
     public static int Main(string[] args)
diff --git a/samples/HelloWorld/Attributes.cs b/samples/HelloWorld/Attributes.cs
@@ -4,7 +4,6 @@
 using System;
 using McMaster.Extensions.CommandLineUtils;
 
-[HelpOption]
 public class Attributes
 {
     public static int Main(string[] args)
diff --git a/samples/HelloWorld/Program.cs b/samples/HelloWorld/Program.cs
@@ -1,9 +1,7 @@
 // Copyright (c) Nate McMaster.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
-using System.ComponentModel.DataAnnotations;
 using System.Threading.Tasks;
-using McMaster.Extensions.CommandLineUtils;
 
 public class Program
 {
diff --git a/samples/Subcommands/BuilderApi.cs b/samples/Subcommands/BuilderApi.cs
@@ -2,7 +2,6 @@
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
-using System.Collections.Generic;
 using McMaster.Extensions.CommandLineUtils;
 
 namespace SubcommandSample
diff --git a/samples/Subcommands/NestedTypes.cs b/samples/Subcommands/NestedTypes.cs
@@ -12,7 +12,6 @@ namespace SubcommandSample
     /// This isn't required. See the <see cref="Git"/> example for a sample on how to use inheritance.
     /// </summary>
     [Command(Name ="fake-docker", Description = "A self-sufficient runtime for containers"),
-        HelpOption,
         Subcommand("container", typeof(Containers)),
         Subcommand("image", typeof(Images))]
     class Docker
@@ -30,7 +29,6 @@ private int OnExecute(CommandLineApplication app, IConsole console)
         /// once so that all subcommand types automatically support '--help'.
         /// </summary>
         [Command(Description = "Manage containers"),
-            HelpOption,
             Subcommand("ls", typeof(List)),
             Subcommand("run", typeof(Run))]
         private class Containers
@@ -59,8 +57,7 @@ private void OnExecute(IConsole console)
 
             [Command(Description = "Run a command in a new container",
                 AllowArgumentSeparator = true,
-                ThrowOnUnexpectedArgument = false),
-                HelpOption]
+                ThrowOnUnexpectedArgument = false)]
             private class Run
             {
                 [Required(ErrorMessage = "You must specify the image name")]
@@ -84,7 +81,6 @@ private void OnExecute(IConsole console)
         }
 
         [Command(Description = "Manage images"),
-            HelpOption,
             Subcommand("ls", typeof(List))]
         private class Images
         {
@@ -96,8 +92,7 @@ private int OnExecute(IConsole console)
 
 
             [Command(Description = "List images",
-                ThrowOnUnexpectedArgument = false),
-                HelpOption]
+                ThrowOnUnexpectedArgument = false)]
             private class List
             {
                 [Option(Description = "Show all containers (default shows just running)")]
diff --git a/src/CommandLineUtils/Abstractions/IValueParser{T}.cs b/src/CommandLineUtils/Abstractions/IValueParser{T}.cs
@@ -1,7 +1,6 @@
 // Copyright (c) Nate McMaster.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
-using System;
 using System.Globalization;
 
 namespace McMaster.Extensions.CommandLineUtils.Abstractions
diff --git a/src/CommandLineUtils/Attributes/SuppressDefaultHelpOptionAttribute.cs b/src/CommandLineUtils/Attributes/SuppressDefaultHelpOptionAttribute.cs
@@ -0,0 +1,16 @@
+﻿// Copyright (c) Nate McMaster.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+using System;
+using McMaster.Extensions.CommandLineUtils.Conventions;
+
+namespace McMaster.Extensions.CommandLineUtils
+{
+    /// <summary>
+    /// Suppress <see cref="DefaultHelpOptionConvention"/>.
+    /// </summary>
+    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Assembly, Inherited = true)]
+    public sealed class SuppressDefaultHelpOptionAttribute : Attribute
+    {
+    }
+}
diff --git a/src/CommandLineUtils/CommandArgument{T}.cs b/src/CommandLineUtils/CommandArgument{T}.cs
@@ -7,7 +7,6 @@
 using System.Globalization;
 using System.Linq;
 using McMaster.Extensions.CommandLineUtils.Abstractions;
-using McMaster.Extensions.CommandLineUtils.Validation;
 
 namespace McMaster.Extensions.CommandLineUtils
 {
diff --git a/src/CommandLineUtils/Conventions/ConventionBuilderExtensions.cs b/src/CommandLineUtils/Conventions/ConventionBuilderExtensions.cs
@@ -32,7 +32,24 @@ public static IConventionBuilder UseDefaultConventions(this IConventionBuilder b
                 .UseOnExecuteMethodFromModel()
                 .UseOnValidateMethodFromModel()
                 .UseOnValidationErrorMethodFromModel()
-                .UseConstructorInjection();
+                .UseConstructorInjection()
+                .UseDefaultHelpOption();
+        }
+
+        /// <summary>
+        /// Adds --help option, if there isn't already a help flag set.
+        /// </summary>
+        /// <param name="builder">The builder.</param>
+        /// <param name="template">The help template. Defaults to <c>--help</c>.</param>
+        /// <returns>The builder.</returns>
+        public static IConventionBuilder UseDefaultHelpOption(this IConventionBuilder builder, string template = DefaultHelpOptionConvention.DefaultHelpTemplate)
+        {
+            if (builder == null)
+            {
+                throw new ArgumentNullException(nameof(builder));
+            }
+
+            return builder.AddConvention(new DefaultHelpOptionConvention(template));
         }
 
         /// <summary>
diff --git a/src/CommandLineUtils/Conventions/DefaultHelpOptionConvention.cs b/src/CommandLineUtils/Conventions/DefaultHelpOptionConvention.cs
@@ -0,0 +1,80 @@
+﻿// Copyright (c) Nate McMaster.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+using System.Reflection;
+
+namespace McMaster.Extensions.CommandLineUtils.Conventions
+{
+    /// <summary>
+    /// Adds a help option of --help if no other help option is specified.
+    /// </summary>
+    public class DefaultHelpOptionConvention : IConvention
+    {
+        /// <summary>
+        /// The default help template.
+        /// </summary>
+        public const string DefaultHelpTemplate = Strings.DefaultHelpTemplate;
+        private readonly string _template;
+
+        /// <summary>
+        /// Initializes an instance of <see cref="DefaultHelpOptionConvention"/>.
+        /// </summary>
+        /// <param name="template"></param>
+        public DefaultHelpOptionConvention(string template)
+        {
+            _template = template;
+        }
+
+        /// <inheritdoc />
+        public void Apply(ConventionContext context)
+        {
+            if (context.Application.OptionHelp != null)
+            {
+                return;
+            }
+
+            if (context.ModelType != null)
+            {
+                var typeInfo = context.ModelType.GetTypeInfo();
+                if (typeInfo.GetCustomAttribute<SuppressDefaultHelpOptionAttribute>() != null
+                    || typeInfo.Assembly.GetCustomAttribute<SuppressDefaultHelpOptionAttribute>() != null)
+                {
+                    return;
+                }
+            }
+
+            var help = new CommandOption(_template, CommandOptionType.NoValue)
+            {
+                Description = Strings.DefaultHelpOptionDescription,
+
+                // the convention will run on each subcommand automatically.
+                // it is better to run the command on each to check for overlap
+                // or already set options to avoid conflict
+                Inherited = false,
+            };
+
+            foreach (var opt in context.Application.GetOptions())
+            {
+                if (string.Equals(help.LongName, opt.LongName))
+                {
+                    help.LongName = null;
+                }
+                if (string.Equals(help.ShortName, opt.ShortName))
+                {
+                    help.ShortName = null;
+                }
+
+                if (string.Equals(help.SymbolName, opt.SymbolName))
+                {
+                    help.SymbolName = null;
+                }
+            }
+
+            if (help.LongName != null || help.ShortName != null || help.SymbolName != null)
+            {
+                context.Application.OptionHelp = help;
+                context.Application.Options.Add(help);
+            }
+        }
+    }
+}
diff --git a/src/CommandLineUtils/Validation/ValidationBuilder{T}.cs b/src/CommandLineUtils/Validation/ValidationBuilder{T}.cs
@@ -1,7 +1,6 @@
 ﻿// Copyright (c) Nate McMaster.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
-using System;
 
 namespace McMaster.Extensions.CommandLineUtils.Validation
 {
diff --git a/src/StrongName.snk b/src/StrongName.snk
diff --git a/test/CommandLineUtils.Tests/ArgumentAttributeTests.cs b/test/CommandLineUtils.Tests/ArgumentAttributeTests.cs
@@ -2,7 +2,6 @@
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
-using System.Reflection;
 using Xunit;
 using Xunit.Abstractions;
 
diff --git a/test/CommandLineUtils.Tests/ConstructorInjectionConventionTests.cs b/test/CommandLineUtils.Tests/ConstructorInjectionConventionTests.cs
diff --git a/test/CommandLineUtils.Tests/CustomValidationAttributeTest.cs b/test/CommandLineUtils.Tests/CustomValidationAttributeTest.cs
diff --git a/test/CommandLineUtils.Tests/DefaultHelpOptionTests.cs b/test/CommandLineUtils.Tests/DefaultHelpOptionTests.cs
diff --git a/test/CommandLineUtils.Tests/HelpOptionAttributeTests.cs b/test/CommandLineUtils.Tests/HelpOptionAttributeTests.cs
diff --git a/test/CommandLineUtils.Tests/Utilities/ConventionTestBase.cs b/test/CommandLineUtils.Tests/Utilities/ConventionTestBase.cs
diff --git a/test/CommandLineUtils.Tests/ValueParserProviderTests.cs b/test/CommandLineUtils.Tests/ValueParserProviderTests.cs
diff --git a/test/CommandLineUtils.Tests/VersionOptionAttributeTests.cs b/test/CommandLineUtils.Tests/VersionOptionAttributeTests.cs

Original file line number	Diff line number	Diff line change
`@@ -53,7 +53,6 @@ See [samples/](./samples/) for more examples, such as:`
`53`	`53`	`using System;`
`54`	`54`	`using McMaster.Extensions.CommandLineUtils;`
`55`	`55`
`56`		`-[HelpOption]`
`57`	`56`	`public class Program`
`58`	`57`	`{`
`59`	`58`	`public static int Main(string[] args)`
Original file line number	Diff line number	Diff line change
`@@ -36,7 +36,6 @@`
`36`	`36`	`using System;`
`37`	`37`	`using McMaster.Extensions.CommandLineUtils;`
`38`	`38`
`39`		`-[HelpOption]`
`40`	`39`	`public class Program`
`41`	`40`	`{`
`42`	`41`	`public static int Main(string[] args)`
Original file line number	Diff line number	Diff line change
`@@ -40,7 +40,6 @@ See [samples](https://github.com/natemcmaster/CommandLineUtils/tree/master/sampl`
`40`	`40`	`using System;`
`41`	`41`	`using McMaster.Extensions.CommandLineUtils;`
`42`	`42`
`43`		`-[HelpOption]`
`44`	`43`	`public class Program`
`45`	`44`	`{`
`46`	`45`	`public static int Main(string[] args)`
Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,6 @@`
`4`	`4`	`using System;`
`5`	`5`	`using McMaster.Extensions.CommandLineUtils;`
`6`	`6`
`7`		`-[HelpOption]`
`8`	`7`	`public class Attributes`
`9`	`8`	`{`
`10`	`9`	`public static int Main(string[] args)`
Original file line number	Diff line number	Diff line change
`@@ -1,9 +1,7 @@`
`1`	`1`	`// Copyright (c) Nate McMaster.`
`2`	`2`	`// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.`
`3`	`3`
`4`		`-using System.ComponentModel.DataAnnotations;`
`5`	`4`	`using System.Threading.Tasks;`
`6`		`-using McMaster.Extensions.CommandLineUtils;`
`7`	`5`
`8`	`6`	`public class Program`
`9`	`7`	`{`