Updated some signature options for argument creation and such.

Author: softwaresalt

.gitignore

@@ -5,3 +5,4 @@ obj/
 *.suo
 *.sqlite
 /.vs/CmdLineParserCore/DesignTimeBuild/.dtbcache.v2
+/.vs/CmdLineParserCore/v16/TestStore/0

source/Arguments/FlagArgument.cs

@@ -11,7 +11,7 @@ namespace System.CommandLine.Arguments
 	/// Represents a single flag argument of a command line parser. In contrast to named arguments, flag arguments, cannot be explicitly assigned a value, but rather get their value from their presence or absence.
 	/// </summary>
 	/// <typeparam name="T">
-	/// The type of the argument. May only be a boolean, integer, or enumeration type. When the type is boolean, then only the presence or absence of the flag is determined. If the type is an integer type (i.e. byte, sbyte,
+	/// The type of the argument may only be a boolean, integer, or enumeration type. When the type is boolean, then only the presence or absence of the flag is determined. If the type is an integer type (i.e. byte, sbyte,
 	/// short, ushort, int, uint, long, or ulong), then the number of occurrences is determined. But if the type is an enumeration type, then the number of occurrences is interpreted as the enumeration value. For example
 	/// consider the following enumeration type: <c>enum Severity { None = 0, Low = 1, Medium = 2, High = 3 }</c>, which is the type of the flag argument named "severity" with the alias "s", then the following command line
 	/// argument "-sss" would parse to an enumeration value of <c>Severity.High</c>.

source/Arguments/PositionalArgument.cs

@@ -1,8 +1,8 @@
 namespace System.CommandLine.Arguments
 {
 	/// <summary>
-	/// Represents a single positional argument of a command line parser. A positional argument, in contrast to a named or flag argument, is an argument, which is only comprised of a value. They are not optional and must
-	/// be at the beginning of the command line arguments in exactly the same order as they were declared.
+	/// Represents a single positional argument of a command line parser. A positional argument, in contrast to a named or flag argument, is an argument, which is only comprised of a value.
+	/// They are not optional and must be at the beginning of the command line arguments in exactly the same order as they were declared.
 	/// </summary>
 	/// <typeparam name="T">The type of the positional argument.</param>
 	public class PositionalArgument<T> : Argument
@@ -18,7 +18,19 @@ public class PositionalArgument<T> : Argument
 		/// </param>
 		/// <param name="help">A descriptive help text for the argument, which is used in the help string.</param>
 		/// <exception cref="ArgumentNullException">If either the name or the destination are <c>null</c>, empty, or only consist of white spaces then an <see cref="ArgumentNullException"/> is thrown.</exception>
-		public PositionalArgument(string name, string destination, string help)
+		public PositionalArgument(string name, string destination, string help) : this(name, name, destination, help) { }
+
+		/// <summary>
+		/// Initializes a new <see cref="PositionalArgument"/> instance.
+		/// </summary>
+		/// <param name="name">The name of the positional argument, which is used in the help string.</param>
+		/// <param name="alias">The alias name of the argument.</param>
+		/// <param name="destination">
+		/// The name that the positional argument will have in the result dictionary after parsing. This should adhere to normal C# naming standards. If it does not, it is automatically converted.
+		/// </param>
+		/// <param name="help">A descriptive help text for the argument, which is used in the help string.</param>
+		/// <exception cref="ArgumentNullException">If either the name or the destination are <c>null</c>, empty, or only consist of white spaces then an <see cref="ArgumentNullException"/> is thrown.</exception>
+		public PositionalArgument(string name, string alias, string destination, string help)
 		{
 			// Validates the arguments
 			if (string.IsNullOrWhiteSpace(name))
@@ -28,7 +40,7 @@ public PositionalArgument(string name, string destination, string help)
 
 			// Stores the arguments for later use
 			this.Name = name;
-			this.Alias = name;
+			this.Alias = alias;
 			this.Destination = destination;
 			this.Help = help;
 			this.Type = typeof(T);

source/Parser.cs

@@ -414,17 +414,19 @@ private ParsingResults Parse(Queue<string> tokenQueue)
 		/// Adds a positional argument to the command line parser.
 		/// </summary>
 		/// <param name="name">The name of the positional argument, which is used in the help string.</param>
+		/// <param name="alias">The alias name of the argument.</param>
 		/// <param name="help">A descriptive help text for the argument, which is used in the help string.</param>
 		/// <typeparam name="T">The type of the positional argument.</typeparam>
 		/// <exception cref="ArgumentNullException">If the name is <c>null</c>, empty, or only consists of white spaces, then an <see cref="ArgumentNullException"/> is thrown.</exception>
 		/// <exception cref="InvalidOperationException">If there already is an argument with the same name, then an <see cref="InvalidOperationException"/> is thrown.</exception>
 		/// <returns>Returns this command line parser so that method invocations can be chained.</returns>
-		public Parser AddPositionalArgument<T>(string name, string help) => this.AddPositionalArgument<T>(name, name, help);
+		public Parser AddPositionalArgument<T>(string name, string alias, string help) => this.AddPositionalArgument<T>(name, alias, name, help);
 
 		/// <summary>
 		/// Adds a positional argument to the command line parser.
 		/// </summary>
 		/// <param name="name">The name of the positional argument, which is used in the help string.</param>
+		/// <param name="alias">The alias name of the argument.</param>
 		/// <param name="destination">
 		/// The name that the positional argument will have in the result dictionary after parsing. This should adhere to normal C# naming standards. If it does not, it is automatically converted.
 		/// </param>
@@ -433,7 +435,7 @@ private ParsingResults Parse(Queue<string> tokenQueue)
 		/// <exception cref="InvalidOperationException">If there already is an argument with the same name, then an <see cref="InvalidOperationException"/> is thrown.</exception>
 		/// <typeparam name="T">The type of the positional argument.</typeparam>
 		/// <returns>Returns this command line parser so that method invocations can be chained.</returns>
-		public Parser AddPositionalArgument<T>(string name, string destination, string help)
+		public Parser AddPositionalArgument<T>(string name, string alias, string destination, string help)
 		{
 			// Validates the arguments
 			if (string.IsNullOrWhiteSpace(name))
@@ -442,7 +444,7 @@ public Parser AddPositionalArgument<T>(string name, string destination, string h
 				throw new ArgumentNullException(nameof(destination));
 
 			// Checks if there is already an argument with the same name
-			PositionalArgument<T> newPositionalArgument = new PositionalArgument<T>(name, destination, help);
+			PositionalArgument<T> newPositionalArgument = new PositionalArgument<T>(name, alias, destination, help);
 			this.AssertArgumentIsValidAndUnique(newPositionalArgument);
 
 			// Adds the positional argument to the parser
@@ -533,10 +535,21 @@ public Parser AddNamedArgument<T>(string name, string alias, string destination,
 			if (string.IsNullOrWhiteSpace(destination))
 				throw new ArgumentNullException(nameof(destination));
 
+			// Returns this parser, so that method invocations can be chained
+			return AddNamedArgument<T>(new NamedArgument<T>(name, alias, destination, help, defaultValue, duplicateResolutionPolicy));
+		}
+
+		/// <summary>
+		/// Adds a named argument to the command line parser.
+		/// </summary>
+		/// <param name="newNamedArgument">An instance of a new named argument.</param>
+		/// <exception cref="InvalidOperationException">If there already is an argument with the same name or the same alias, then an <see cref="InvalidOperationException"/> is thrown.</exception>
+		/// <typeparam name="T">The type of the argument.</typeparam>
+		/// <returns>Returns this command line parser so that method invocations can be chained.</returns>
+		public Parser AddNamedArgument<T>(NamedArgument<T> newNamedArgument)
+		{
 			// Checks if there is already an argument with the same name or alias
-			NamedArgument<T> newNamedArgument = new NamedArgument<T>(name, alias, destination, help, defaultValue, duplicateResolutionPolicy);
 			this.AssertArgumentIsValidAndUnique(newNamedArgument);
-
 			// Adds the argument to the parser
 			(this.NamedArguments as List<Argument>).Add(newNamedArgument);
 
@@ -550,7 +563,7 @@ public Parser AddNamedArgument<T>(string name, string alias, string destination,
 		/// <param name="name">The name of the argument, which is used for parsing and in the help string.</param>
 		/// <exception cref="ArgumentNullException">If the name is <c>null</c>, empty, or only consists of white spaces, then an <see cref="ArgumentNullException"/> is thrown.</exception>
 		/// <exception cref="InvalidOperationException">If there already is an argument with the same name, then an <see cref="InvalidOperationException"/> is thrown.</exception>
-		/// <typeparam name="T">The type of the argument.</typeparam>
+		/// <typeparam name="T">The type of the argument; see FlagArgument class for allowed types.</typeparam>
 		/// <returns>Returns this command line parser so that method invocations can be chained.</returns>
 		public Parser AddFlagArgument<T>(string name) => this.AddFlagArgument<T>(name, null, name, null);
 
@@ -561,7 +574,7 @@ public Parser AddNamedArgument<T>(string name, string alias, string destination,
 		/// <param name="alias">The alias name of the argument.</param>
 		/// <exception cref="ArgumentNullException">If the name is <c>null</c>, empty, or only consists of white spaces, then an <see cref="ArgumentNullException"/> is thrown.</exception>
 		/// <exception cref="InvalidOperationException">If there already is an argument with the same name or the same alias, then an <see cref="InvalidOperationException"/> is thrown.</exception>
-		/// <typeparam name="T">The type of the argument.</typeparam>
+		/// <typeparam name="T">The type of the argument; see FlagArgument class for allowed types.</typeparam>
 		/// <returns>Returns this command line parser so that method invocations can be chained.</returns>
 		public Parser AddFlagArgument<T>(string name, string alias) => this.AddFlagArgument<T>(name, alias, name, null);
 
@@ -573,7 +586,7 @@ public Parser AddNamedArgument<T>(string name, string alias, string destination,
 		/// <param name="help">A descriptive help text for the argument, which is used in the help string.</param>
 		/// <exception cref="ArgumentNullException">If the name is <c>null</c>, empty, or only consists of white spaces, then an <see cref="ArgumentNullException"/> is thrown.</exception>
 		/// <exception cref="InvalidOperationException">If there already is an argument with the same name or the same alias, then an <see cref="InvalidOperationException"/> is thrown.</exception>
-		/// <typeparam name="T">The type of the argument.</typeparam>
+		/// <typeparam name="T">The type of the argument; see FlagArgument class for allowed types.</typeparam>
 		/// <returns>Returns this command line parser so that method invocations can be chained.</returns>
 		public Parser AddFlagArgument<T>(string name, string alias, string help) => this.AddFlagArgument<T>(name, alias, name, help);
 
@@ -586,7 +599,7 @@ public Parser AddNamedArgument<T>(string name, string alias, string destination,
 		/// <param name="help">A descriptive help text for the argument, which is used in the help string.</param>
 		/// <exception cref="ArgumentNullException">If either the name or the destination are <c>null</c>, empty, or only consist of white spaces, then an <see cref="ArgumentNullException"/> is thrown.</exception>
 		/// <exception cref="InvalidOperationException">If there already is an argument with the same name or the same alias, then an <see cref="InvalidOperationException"/> is thrown.</exception>
-		/// <typeparam name="T">The type of the argument.</typeparam>
+		/// <typeparam name="T">The type of the argument; see FlagArgument class for allowed types.</typeparam>
 		/// <returns>Returns this command line parser so that method invocations can be chained.</returns>
 		public Parser AddFlagArgument<T>(string name, string alias, string destination, string help)
 		{
@@ -596,8 +609,20 @@ public Parser AddFlagArgument<T>(string name, string alias, string destination,
 			if (string.IsNullOrWhiteSpace(destination))
 				throw new ArgumentNullException(nameof(destination));
 
+			// Returns this parser, so that method invocations can be chained
+			return AddFlagArgument<T>(new FlagArgument<T>(name, alias, destination, help));
+		}
+
+		/// <summary>
+		/// Adds a flag argument to the command line parser.
+		/// </summary>
+		/// <param name="newFlagArgument">An instance of a FlagArgument.</param>
+		/// <exception cref="InvalidOperationException">If there already is an argument with the same name or the same alias, then an <see cref="InvalidOperationException"/> is thrown.</exception>
+		/// <typeparam name="T">The type of the argument; see FlagArgument class for allowed types.</typeparam>
+		/// <returns>Returns this command line parser so that method invocations can be chained.</returns>
+		public Parser AddFlagArgument<T>(FlagArgument<T> newFlagArgument)
+		{
 			// Checks if there is already an argument with the same name or alias
-			FlagArgument<T> newFlagArgument = new FlagArgument<T>(name, alias, destination, help);
 			this.AssertArgumentIsValidAndUnique(newFlagArgument);
 
 			// Adds the argument to the parser
@@ -761,7 +786,14 @@ public Parser AddCommand(Command command)
 		/// </summary>
 		/// <param name="commandLineArguments">The command line arguments that were retrieved by the application.</param>
 		/// <returns>Returns the parsing results, which is a bag of arguments.</returns>
-		public ParsingResults Parse(string[] commandLineArguments)
+		public ParsingResults Parse(string[] commandLineArguments) => this.Parse(commandLineArguments.ToList());
+
+		/// <summary>
+		/// Parses the command line arguments by matching them to the declared arguments and commands.
+		/// </summary>
+		/// <param name="commandLineArguments">The command line arguments that were retrieved by the application.</param>
+		/// <returns>Returns the parsing results, which is a bag of arguments.</returns>
+		public ParsingResults Parse(List<string> commandLineArguments)
 		{
 			// Copies the command line arguments into a queue so that they are easier to parse without having to do fancy indexing, the first token is dequeued right away, because it is the file name of the executable
 			Queue<string> tokenQueue = new Queue<string>(commandLineArguments);

test/ParserTests.cs

@@ -781,32 +781,32 @@ public void TestComplexScenario()
 
 			// Creates the parser for the add command
 			Parser addCommandParser = parser.AddCommand("add", "Add a new package or reference to a .NET project.");
-			addCommandParser.AddPositionalArgument<string>("project", "The project file to operate on.");
+			addCommandParser.AddPositionalArgument<string>("project", "The project file to operate on.", null);
 			addCommandParser.AddFlagArgument<bool>("help", "h", "Show command line help.");
 
 			// Creates the parser for the add package command
 			Parser addPackageCommandParser = addCommandParser.AddCommand("package", "Add a NuGet package reference to the project.");
-			addPackageCommandParser.AddPositionalArgument<string>("package-name", "The package reference to add.");
+			addPackageCommandParser.AddPositionalArgument<string>("package-name", "The package reference to add.", null);
 			addPackageCommandParser.AddFlagArgument<bool>("help", "h", "Show command line help.");
 			addPackageCommandParser.AddNamedArgument<string>("version", "v", "The version of the package to add.");
 			addPackageCommandParser.AddFlagArgument<bool>("interactive", null, "Show command line help.");
 
 			// Creates the parser for the add reference command
 			Parser addReferenceCommandParser = addCommandParser.AddCommand("reference", "Add a project-to-project reference to the project.");
-			addReferenceCommandParser.AddPositionalArgument<string>("project-path", "The paths to the projects to add as references.");
+			addReferenceCommandParser.AddPositionalArgument<string>("project-path", "The paths to the projects to add as references.", null);
 			addReferenceCommandParser.AddFlagArgument<bool>("help", "h", "Show command line help.");
 			addReferenceCommandParser.AddNamedArgument<string>("framework", "f", "Add the reference only when targeting a specific framework.");
 
 			// Creates the parser for the build command
 			Parser buildCommandParser = parser.AddCommand("build", "Add a new package or reference to a .NET project.");
-			buildCommandParser.AddPositionalArgument<string>("project", "The project file to operate on.");
+			buildCommandParser.AddPositionalArgument<string>("project", "The project file to operate on.", null);
 			buildCommandParser.AddFlagArgument<bool>("help", "h", "Show command line help.");
 			buildCommandParser.AddNamedArgument<VerbosityLevel>("verbosity", "v", "Set the MSBuild verbosity level. Allowed values are quiet, minimal, normal, detailed, and diagnostic.");
 			buildCommandParser.AddNamedArgument<string>("framework", "f", "The target framework to build for. The target framework must also be specified in the project file.");
 
 			// Creates the parser for the new command
 			Parser newCommandParser = parser.AddCommand("new", "Create a new .NET project or file.");
-			newCommandParser.AddPositionalArgument<string>("template", "The project template to use.");
+			newCommandParser.AddPositionalArgument<string>("template", "The project template to use.", null);
 			newCommandParser.AddFlagArgument<bool>("help", "h", "Show command line help.");
 			newCommandParser.AddNamedArgument<string>("name", "n", "The name for the output being created. If no name is specified, the name of the current directory is used.");
 			newCommandParser.AddNamedArgument<string>("output", "o", "Location to place the generated output.");