C#/.NET Command Line Argument Parser Reloaded






4.86/5 (30 votes)
Easy to use yet powerful command line argument parser which also creates usage and parameter information for the user.
Introduction
Many programs use command line arguments. Each time parsing has to be done in the same way. There are other projects which facilitate the parsing process. For example, C#/.NET Command Line Arguments Parser does a great job, however it lacks verification of the passed and parsed arguments. C# command-line option parser can do that, however using it is quite complicated. CLAParser
is a compromise of both: It is easy to use and uses regular expressions for parsing and validating which makes it quite powerful. Further more, it supports i18n and it creates information for correct command line usage for the user.
Naming Conventions
- Arguments: Everything passed on argument line to program separated by spaces, or grouped by quotes, e.g.
program.exe argument1 /argument2 --argument3 .!§$argument4´ß2! "argument5 with spaces"
- Parameter: All arguments that start with / or -, e.g.
program.exe /parameter1 -parameter2
- Values: Every argument that is not a parameter, e.g.
program.exe value1 value2 /my_param 'v a l u e 3'
In the last example, value1
and value2
are values without parameters, whereas v a l u e 3
belongs to parameter my_param
. (Note that the single quotes which hold 'v a l u e 3'
together are removed by CLAParser
.)
Using the Code
- Copy
CLAParser
files to your project folder and include them in C# project (CmdLineArgumentParser.cs, CmdLineArgumentParserRes.resx, and optionally further resx-files). - Create a
CLAParser
instance by calling the constructor.CLAParser.CLAParser CmdLine = new CLAParser.CLAParser("CLAParserTest");
The argument must be the default namespace. (This is necessary so thatCLAParser
can find its resx-files.) - Use
CmdLine.Parameter()
function to define known parameters.CmdLine.Parameter(CLAParser.CLAParser.ParamAllowType.Optional, "", CLAParser.CLAParser.ValueType.String, "Path to file that is to be loaded on starting the program."); CmdLine.Parameter(CLAParser.CLAParser.ParamAllowType.Optional, "output", CLAParser.CLAParser.ValueType.OptionalString, "Write output to file, if no file specified default file output.txt is used."); CmdLine.Parameter(CLAParser.CLAParser.ParamAllowType.Required, "add", CLAParser.CLAParser.ValueType.MultipleInts, "Do a mathematical addition of number given integers.");
- Start parsing by calling function
CmdLine.Parse()
. Raised exceptions can be passed directly to the user. They indicate the reason for the problem. Further, show user correct syntax and information about the parameters usingCmdLine.GetUsage()
andCmdLine.GetParameterInfo()
.try { CmdLine.Parse(); } catch (CLAParser.CLAParser.CmdLineArgumentException Ex) { Console.WriteLine(Ex.Message); Console.WriteLine(CmdLine.GetUsage()); Console.WriteLine(CmdLine.GetParameterInfo()); }
- If arguments are correct and all required arguments are defined, no exception is raised and values of all parameters can be accessed by the dictionary interface. Optional parameters which are not defined by the user are indicated by
null
values. A value without parameter can be accessed by the empty string ("").if(CmdLine[""] != null) { value = CmdLine[""]; ... } if(CmdLine["parameter"] != null) { value = CmdLine["parameter"]; ... }
Points of Interest
- Update: Using the obsolete function
Parse(string[] Arguments)
with args as parameter quotes (") must be escaped (\") to be recognized correctly. It is recommended to use functionParse()
instead! - Function
FindMismatchReasonInRegex()
helps in analyzing why a searchstring
does not match a regular expression and indicates where the problem probably is located. CLAParser
is internationalized, i.e. new languages can easily be defined by creating new resx-files (localization).- Using the enumerator, all arguments can be traversed, e.g.:
IEnumerator e = CmdLine.GetEnumerator(); while (e.MoveNext()) { DictionaryEntry arg = (DictionaryEntry)e.Current; Console.WriteLine(arg.Key + "=" + arg.Value); }
- For a complete overview of
CLAParser
's capabilities, have a look at the attached code files.
History
- 2010-02-24
- Initial release
- 2010-04-05
- CmdLineArgumentParser.cs:574 -> from "
...Parameters == false)
" to "...Parameters == true)
"
- CmdLineArgumentParser.cs:574 -> from "
- 2011-01-06
- Corrected error in regular expression which made it impossible to use more than one quoted value
- Added internal function
GetRawCommandlineArgs()
proposed by vermis0. Together with it comes functionParse()
which makes functionParse(string[] Arguments)
obsolete. Now the quotes of quoted values (e.g. "value with spaces") do not need to be escaped anymore!
- 2011-01-07
- Corrected error in regular expression which made it impossible to use a value without parameter containing minus (-) or slash (/).
- Made behaviour with (first) value without parameter more consistent. Instead of setting
AllowValuesWithoutParameter
, use functionParameter()
withParameterName==""
. - Fixed error with case sensitivity of parameter. Now everything is case insensitive.
- 2011-09-09
- Corrected problem reported by Hautzendorfer concerning single parameters not being processed correctly
- 2014-07-09
- Corrected problem reported by Gray John concerning multiple boolean parameters not being processed correctly
- 2015-11-07
- Corrected problem detecting values without parameters
- Added tests
- 2017-08-24
- Enhance formatting if help text for parameter contains line break (\n)
- Added
GetAdditionalParameters()
for nested usage ofCLAParser
- 2020-09-29
- Fix typos
- Fix compiler and code rule warnings
- Allow negative integers to be passed without quotes