Update CHANGELOG, release notes, and polish a few API for the 2.3.0-alpha release

* Get rid of ClusterOptions on CommandAttribute: still need to noodle on this one and ParserSettings
* Get rid of APIs named "alias". Just use "names" instead for consistency with options.

Author: natemcmaster

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## [Unreleased]
+## [2.3.0-alpha]
 
 Enhancements:
 
@@ -10,8 +10,8 @@ Enhancements:
 * New type: `Pager`. Provides a simple interaction model for displaying console output in a pager.
 * Display help text using the `less` pager on macOS/Linux.
 * Make suggestions when invalid options or commands are used, but there is a valid one that is similar.
-  (Thanks to [@MadbHatter][@MadbHatter] for doing the inital work on this.)
-* Add support for subcommand aliases.
+  (Thanks to [@MadbHatter][@MadbHatter] for doing the initial work on this.)
+* Add support for subcommand aliases. Commands can be given multiple names.
 
   ```c#
   [Command("organization", "org", "o")]
@@ -25,6 +25,7 @@ Enhancements:
 
   public class AddCommand { } // subcommand name = "add"
   ```
+* [@lvermeulen]: Sort subcommands by name in help text. This can be disabled with `DefaultHelpTextGenerator.SortCommandsByName`.
 
 Bugs fixed:
 
@@ -39,8 +40,8 @@ Details:
 
 * **Clustering options:** I've added this behavior as the new default, but only if I think it won't interfere with existing apps.
   If it causes issues or you don't like clustering, you can disable this by setting 
-  `CommandLineApplication.ParserSettings.ClusterOptions = false`, or adding `[Command(ClusterOptions = false)]`.
-  To preserve compatibilty with existing apps, this behavior is off if you have configured options with short names with 
+  `CommandLineApplication.ParserSettings.ClusterOptions = false`.
+  To preserve compatibility with existing apps, this behavior is off if you have configured options with short names with 
   multiple characters. In a future version, this will cause an error unless you set `ClusterOptions = false`.
 
 * **Pager:** this is the new default for showing help text. The pager should have graceful fallback to regular stdout 
@@ -94,7 +95,7 @@ Bug fixes:
  - Don't assign option and argument options if no value was provided, preserving the default CLR value unless there is user-input.
  - Fix ShowHint() to use ShortName or SymbolName if OptionHelp.LongName is not set
  - Fix [#85](https://github.com/natemcmaster/CommandLineUtils/issues/85) - lower priority of resolving AdditionalServices after most built-in services
- - Fix [#79](https://github.com/natemcmaster/CommandLineUtils/issues/79) - OnValidate callbacks invoked before property valueswere assigned
+ - Fix [#79](https://github.com/natemcmaster/CommandLineUtils/issues/79) - OnValidate callbacks invoked before property values were assigned
 
 Minor improvements:
 
@@ -105,7 +106,7 @@ Minor improvements:
 **March 30, 2018**
 
  - Added support for command validators using `CommandLineApplication.Validators` and added a new OnValidate convention
- - Fix minor bug in ArgumentEscaper where some strings were not properly escaped
+ - Fix minor bug in `ArgumentEscaper` where some strings were not properly escaped
  - Update to System.ComponentModel.Annotations 4.4.1 (netstandard2.0 only)
  - [@atruskie]: Ensure ValueParsers are inherited in subcommands
 
@@ -227,12 +228,14 @@ Other:
 [@jerriep]: https://github.com/jerriep
 [@kant2002]: https://github.com/kant2002
 [@liamdawson]: https://github.com/liamdawson
+[@lvermeulen]: https://github.com/lvermeulen
 [@MadbHatter]: https://github.com/MadbHatter
 [@rmcc13]: https://github.com/rmcc13
 [@SeanFeldman]: https://github.com/SeanFeldman
 [@sebastienros]: https://github.com/sebastienros
 
 [Unreleased]: https://github.com/natemcmaster/CommandLineUtils/compare/v2.2.5...HEAD
+[v2.3.0-alpha]: https://github.com/natemcmaster/CommandLineUtils/compare/v2.2.5...v2.3.0-alpha
 [v2.2.5]: https://github.com/natemcmaster/CommandLineUtils/compare/v2.2.4...v2.2.5
 [v2.2.4]: https://github.com/natemcmaster/CommandLineUtils/compare/v2.2.3...v2.2.4
 [v2.2.3]: https://github.com/natemcmaster/CommandLineUtils/compare/v2.2.3...v2.2.3

releasenotes.props

@@ -1,5 +1,53 @@
 <Project>
   <PropertyGroup>
+    <PackageReleaseNotes Condition="'$(VersionPrefix)' == '2.3.0'">
+      <![CDATA[
+
+Enhancements:
+
+* Support the POSIX convention for cluster multiple options. For example, `-ixd` is treated the same as `-i -x -d`.
+
+* @bjorg: support SingleOrNoValue notation. `--option[:value]`
+
+* New type: `Pager`. Provides a simple interaction model for displaying console output in a pager.
+
+* Display help text using the `less` pager on macOS/Linux.
+
+* Make suggestions when invalid options or commands are used, but there is a valid one that is similar.
+  (Thanks to @MadbHatter for doing the initial work on this.)
+
+* Add support for subcommand aliases. Commands can be given multiple names.
+  ```c#
+  [Command("organization", "org", "o")]
+  public class OrgCommand { }
+  ```
+
+* Obsolete the constructor of `[Subcommand]` which takes a string.
+
+* Infer subcommand names from the type name
+  ```c#
+  [Subcommand(typeof(AddCommand))]
+  public class Git { }
+
+  public class AddCommand { } // subcommand name = "add"
+  ```
+
+* @lvermeulen: Sort subcommands by name in help text. This can be disabled with `DefaultHelpTextGenerator.SortCommandsByName`.
+
+Bugs fixed:
+
+* Duplicate subcommand names used to cause undefined behavior. Now, attempting to add a duplicate subcommand name or aliases will
+  cause the library to throw before the app can execute.
+
+* Fix bug in subcommand name inference. When not specified, the subcommand always matched the entry assembly name.
+  In this update, this convention only applies to the parent command.
+
+* Add generic overloads of `.IsRequired()` for `CommandOption<T>` and `CommandArgument<T>`.
+
+
+See more details here: https://github.com/natemcmaster/CommandLineUtils/blob/master/CHANGELOG.md#v$(VersionPrefix.Replace('.',''))
+]]>
+    </PackageReleaseNotes>
     <PackageReleaseNotes Condition="'$(VersionPrefix)' == '2.2.5'">
 <![CDATA[
 Bug fixes:

src/CommandLineUtils/Attributes/CommandAttribute.cs

@@ -14,7 +14,6 @@ namespace McMaster.Extensions.CommandLineUtils
     [AttributeUsage(AttributeTargets.Class)]
     public sealed class CommandAttribute : Attribute
     {
-        private bool? _clusterOptions;
         private string[] _names = Util.EmptyArray<string>();
 
         /// <summary>
@@ -35,11 +34,10 @@ public CommandAttribute(string name)
         /// <summary>
         /// Initializes a new <see cref="CommandAttribute"/>.
         /// </summary>
-        /// <param name="name">The primary name of the command.</param>
-        /// <param name="aliases">The names of the command.</param>
-        public CommandAttribute(string name, params string[] aliases)
+        /// <param name="names">The names of the command. The first name given is the primary name</param>
+        public CommandAttribute(params string[] names)
         {
-            _names = new[] { name }.Concat(aliases).ToArray();
+            _names = names;
         }
 
         /// <summary>
@@ -102,31 +100,14 @@ public string Name
         /// </summary>
         public CultureInfo ParseCulture { get; set; } = CultureInfo.CurrentCulture;
 
-        /// <summary>
-        /// <para>
-        /// One or more options of <see cref="CommandOptionType.NoValue"/>, followed by at most one option that takes values, should be accepted when grouped behind one '-' delimiter.
-        /// </para>
-        /// <para>
-        /// This defaults to true unless an option with a short name of two or more characters is added.
-        /// </para>
-        /// <para>
-        /// See <see cref="ParserSettings.ClusterOptions"/> for more details.
-        /// </para>
-        /// </summary>
-        public bool ClusterOptions
-        {
-            get => _clusterOptions ?? true;
-            set => _clusterOptions = value;
-        }
-
         internal void Configure(CommandLineApplication app)
         {
             // this might have been set from SubcommandAttribute
             app.Name = Name ?? app.Name;
 
-            foreach (var alias in Names.Skip(1))
+            foreach (var name in Names.Skip(1))
             {
-                app.AddAlias(alias);
+                app.AddName(name);
             }
 
             app.AllowArgumentSeparator = AllowArgumentSeparator;
@@ -138,12 +119,6 @@ internal void Configure(CommandLineApplication app)
             app.ThrowOnUnexpectedArgument = ThrowOnUnexpectedArgument;
             app.OptionsComparison = OptionsComparison;
             app.ValueParsers.ParseCulture = ParseCulture;
-
-            // detect if this is explicitly set. Otherwise, we try to infer if clustering options is okay.
-            if (_clusterOptions.HasValue)
-            {
-                app.ParserSettings.ClusterOptions = ClusterOptions;
-            }
         }
     }
 }

src/CommandLineUtils/CommandLineApplication.cs

@@ -26,7 +26,7 @@ public partial class CommandLineApplication : IServiceProvider
         private List<Action<ParseResult>> _onParsingComplete;
         internal readonly Dictionary<string, PropertyInfo> _shortOptions = new Dictionary<string, PropertyInfo>();
         internal readonly Dictionary<string, PropertyInfo> _longOptions = new Dictionary<string, PropertyInfo>();
-        private readonly HashSet<string> _aliases = new HashSet<string>(StringComparer.Ordinal);
+        private readonly HashSet<string> _names = new HashSet<string>(StringComparer.Ordinal);
 
 
         private const int HelpExitCode = 0;
@@ -171,7 +171,7 @@ public string Name
         public List<CommandOption> Options { get; private set; }
 
         /// <summary>
-        /// All names by which the command can be referenced. This includes <see cref="Name"/> and an aliases added in <see cref="AddAlias"/>.
+        /// All names by which the command can be referenced. This includes <see cref="Name"/> and an aliases added in <see cref="AddName"/>.
         /// </summary>
         public IEnumerable<string> Names
         {
@@ -182,9 +182,9 @@ public IEnumerable<string> Names
                     yield return Name;
                 }
 
-                foreach (var alias in _aliases)
+                foreach (var names in _names)
                 {
-                    yield return alias;
+                    yield return names;
                 }
             }
         }
@@ -332,22 +332,22 @@ public IEnumerable<CommandOption> GetOptions()
         }
 
         /// <summary>
-        /// Add an alias for the command.
+        /// Add another name for the command.
         /// <para>
-        /// An alias is a shorter name by which a command may be referenced.
+        /// Additional names can be shorter, longer, or alternative names by which a command may be invoked on the command line.
         /// </para>
         /// </summary>
-        /// <param name="alias">The alias. Must not be null or empty.</param>
-        public void AddAlias(string alias)
+        /// <param name="name">The name. Must not be null or empty.</param>
+        public void AddName(string name)
         {
-            if (string.IsNullOrEmpty(alias))
+            if (string.IsNullOrEmpty(name))
             {
-                throw new ArgumentException("Value cannot be null or empty.", nameof(alias));
+                throw new ArgumentException("Value cannot be null or empty.", nameof(name));
             }
 
-            Parent?.AssertCommandNameIsUnique(alias, this);
+            Parent?.AssertCommandNameIsUnique(name, this);
 
-            _aliases.Add(alias);
+            _names.Add(name);
         }
 
         /// <summary>
@@ -965,7 +965,7 @@ internal bool MatchesName(string name)
                 return true;
             }
 
-            return _aliases.Contains(name);
+            return _names.Contains(name);
         }
 
         private sealed class Builder : IConventionBuilder

src/CommandLineUtils/Properties/Strings.cs

@@ -42,7 +42,7 @@ public static string OptionNameIsAmbiguous(string optionName, PropertyInfo first
             => $"Ambiguous option name. Both {first.DeclaringType.FullName}.{first.Name} and {second.DeclaringType.FullName}.{second.Name} produce a CommandOption with the name '{optionName}'";
 
         public static string DuplicateSubcommandName(string commandName)
-            => $"The subcommand name '{commandName}' has already been been specified. Subcommand names and aliases must be unique.";
+            => $"The subcommand name '{commandName}' has already been been specified. Subcommand names must be unique.";
 
         public static string BothOptionAndArgumentAttributesCannotBeSpecified(PropertyInfo prop)
             => $"Cannot specify both {nameof(OptionAttribute)} and {nameof(ArgumentAttribute)} on property {prop.DeclaringType.Name}.{prop.Name}.";

test/CommandLineUtils.Tests/CommandLineApplicationTests.cs

@@ -88,7 +88,7 @@ public void ItThrowsIfAnotherSubcommandHasNameName()
 
             app.Command("sub1", c =>
             {
-                c.AddAlias("s");
+                c.AddName("s");
             });
 
             var ex = Assert.Throws<InvalidOperationException>(() => app.Command("sub1", null));
@@ -105,10 +105,10 @@ public void ItThrowsIfAnotherSubCommandHasTheSameAlias()
 
             app.Command("sub1", c =>
             {
-                c.AddAlias("s");
+                c.AddName("s");
             });
 
-            var ex = Assert.Throws<InvalidOperationException>(() => app.Command("sub2", c => c.AddAlias("s")));
+            var ex = Assert.Throws<InvalidOperationException>(() => app.Command("sub2", c => c.AddName("s")));
             Assert.Equal(Strings.DuplicateSubcommandName("s"), ex.Message);
         }
 

test/CommandLineUtils.Tests/CommandLineProcessorTests.cs

@@ -262,7 +262,7 @@ public void ItFindsSubcommandsByAliases()
             var app = new CommandLineApplication();
             var cmd = app.Command("sub1", c =>
             {
-                c.AddAlias("s");
+                c.AddName("s");
             });
 
             var result = app.Parse("s");

version.props

@@ -1,7 +1,7 @@
 <Project>
   <PropertyGroup>
     <VersionPrefix>2.3.0</VersionPrefix>
-    <VersionSuffix>alpha1</VersionSuffix>
+    <VersionSuffix>alpha</VersionSuffix>
     <PackageVersion Condition="'$(APPVEYOR_REPO_TAG)' == 'true' AND '$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix)</PackageVersion>
     <PackageVersion Condition="'$(APPVEYOR_REPO_TAG)' == 'true' AND '$(VersionSuffix)' == 'rtm'">$(VersionPrefix)</PackageVersion>