Recipe 3.22. Parsing Command-Line Parameters Problem You require your applications to accept one or more command-line parameters in a standard format. You need to access and parse the entire command line passed to your application. Solution Use the ParseCmdLine class shown in Example 3-16 to help with parsing command-line parameters. Example 3-16. Parsing command-line parameters using System; using System.Diagnostics; public class ParseCmdLine { // All args are delimited by tab or space. // All double-quotes are removed except when escaped '\"'. // All single-quotes are left untouched. public ParseCmdLine( ) {} public virtual string ParseSwitch(string arg) { arg = arg.TrimStart(new char[2] {'/', '-'}); return (arg); } public virtual void ParseSwitchColonArg(string arg, out string outSwitch, out string outArgument) { outSwitch = ""; outArgument = ""; try { // This is a switch or switch/argument pair. arg = arg.TrimStart(new char[2] {'/', '-'}); if (arg.IndexOf(':') >= 0) { outSwitch = arg.Substring(0, arg.IndexOf(':')); outArgument = arg.Substring(arg.IndexOf(':') + 1); if (outArgument.Trim( ).Length <= 0) { throw (new ArgumentException( "Command-Line parameter error: switch " + arg + " must be followed by one or more arguments.", arg)); } } else { throw (new ArgumentException( "Command-Line parameter error: argument " + arg + " must be in the form of a 'switch:argument}' pair.", arg)); } } catch (ArgumentException ae) { // Re-throw the exception to be handled in the calling method. throw; } catch (Exception e) { // Wrap an ArgumentException around the exception thrown. throw (new ArgumentException("General command-Line parameter error", arg, e)); } } public virtual void ParseSwitchColonArgs(string arg, out string outSwitch, out string[] outArguments) { outSwitch = ""; outArguments = null; try { // This is a switch or switch/argument pair. arg = arg.TrimStart(new char[2] {'/', '-'}); if (arg.IndexOf(':') >= 0) { outSwitch = arg.Substring(0, arg.IndexOf(':')); string Arguments = arg.Substring(arg.IndexOf(':') + 1); if (Arguments.Trim( ).Length <= 0) { throw (new ArgumentException( "Command-Line parameter error: switch " + arg + " must be followed by one or more arguments.", arg)); } outArguments = Arguments.Split(new char[1] {';'}); } else { throw (new ArgumentException( "Command-Line parameter error: argument " + arg + " must be in the form of a 'switch:argument{;argument}' pair.", arg)); } } catch (Exception e) { // Wrap an ArgumentException around the exception thrown. throw ; } } public virtual void DisplayErrorMsg( ) { DisplayErrorMsg(""); } public virtual void DisplayErrorMsg(string msg) { Console.WriteLine ("An error occurred while processing the command-line arguments:"); Console.WriteLine(msg); Console.WriteLine( ); FileVersionInfo version = Process.GetCurrentProcess( ).MainModule.FileVersionInfo; if (Process.GetCurrentProcess( ).ProcessName.Trim( ).Length > 0) { Console.WriteLine(Process.GetCurrentProcess( ).ProcessName); } else { Console.WriteLine("Product Name: " + version.ProductName); } Console.WriteLine("Version " + version.FileVersion); Console.WriteLine("Copyright " + version.LegalCopyright); Console.WriteLine("TradeMarks " + version.LegalTrademarks); DisplayHelp( ); } public virtual void DisplayHelp( ) { Console.WriteLine("See help for command-line usage."); } }
|
Discussion Before command-line parameters can be parsed, a common format must first be decided upon. The format for this recipe follows the command-line format for the Visual C# .NET language compiler. The format used is defined as follows: All command-line arguments are separated by one or more whitespace characters. Each argument may start with either a - or / character, but not both. If it does not, that argument is considered a literal, such as a filename. Each argument that starts with either the - or / character may be divided up into a switch followed by a colon followed by one or more arguments separated with the ; character. The command-line parameter -sw:arg1;arg2;arg3 is divided up into a switch (sw) and three arguments (arg1, arg2, and arg3). Note that there should not be any spaces in the full argument; otherwise, the runtime command-line parser will split up the argument into two or more arguments. Strings delineated with double quotes, such as "c:\test\file.log" will have their double quotes stripped off. This is a function of the operating system interpreting the arguments passed in to your application. Single quotes are not stripped off. To preserve double quotes, precede the double quote character with the \ escape sequence character. The \ character is handled as an escape sequence character only when followed by a double quotein which case, only the double quote is displayed. The ^ character is handled by the runtime command-line parser as a special character.
Fortunately, the runtime command-line parser (for Visual Studio .NET, this would be the CLR) handles most of this before your application receives the individual parsed arguments. The runtime command-line parser passes a string[] containing each parsed argument to the entry point of your application. The entry point can take one of the following forms: public static void Main( ) public static int Main( ) public static void Main(string[] args) public static int Main(string[] args)
The first two accept no arguments, but the last two accept the array of parsed command-line arguments. Note that the static Environment.CommandLine property will also return a string containing the entire command line, and the static Environment.GetCommandLineArgs method will return an array of strings containing the parsed command-line arguments. The individual arguments in this array can then be passed to the various methods of the ParseCmdLine class. Example 3-17 shows how this can be accomplished. Example 3-17. Passing parameters to the command-line parser [STAThread] public static void Main(string[] args) { // The application should be initialized here assuming no command-line // parameters were found. ParseCmdLine parse = new ParseCmdLine( ); try { // Create an array of all possible command-line parameters // and how to parse them. object[,] mySwitches = new object[2, 4] { {"file", "output", "trialmode", "debugoutput"}, {ArgType.Simple, ArgType.Compound, ArgType.SimpleSwitch, ArgType.Complex}}; // Loop through all command-line parameters. for (int counter = 0; counter < args.Length; counter++) { args[counter] = args[counter].TrimStart(new char[2] {'/', '-'}); // Search for the correct ArgType and parse argument according to // this ArgType. for (int index = 0; index <= mySwitches.GetUpperBound(1); index++) { string theSwitch; string theArgument; string[] theArguments; if (args[counter].StartsWith((string)mySwitches[0, index])) { // Parse each argument into switch:arg1;arg2… switch ((ArgType)mySwitches[1, index]) { case ArgType.Simple: theSwitch = args[counter]; break; case ArgType.SimpleSwitch: theSwitch = parse.ParseSwitch(args[counter]); break; case ArgType.Compound: parse.ParseSwitchColonArg(args[counter],out theSwitch, out theArgument); break; case ArgType.Complex: parse.ParseSwitchColonArgs(args[counter],out theSwitch, out theArguments); break; default: throw (new ArgumentException( "Cmd-Line parameter error: ArgType enumeration " + mySwitches[1, index].ToString( ) + " not recognized.")); } // Implement functionality to handle each parsed // command-line parameter. switch ((string)mySwitches[0, index]) { case "file": // Handle this switch here… break; case "output": // Handle this switch here… break; case "trialmode": // Handle this switch and its argument here… break; case "debugoutput": // Handle this switch and its arguments here… break; default: throw (new ArgumentException( "Cmd-Line parameter error: Switch " + mySwitches[0, index].ToString( ) + " not recognized.")); } } } } } catch (ArgumentException ae) { parse.DisplayErrorMsg(ae.ToString( )); return; } catch (Exception e) { // Handle other exceptions here… } }
|
The ArgType enumeration is defined as follows: enum ArgType { Simple = 0, // A simple file name with no preceding '/' or '-' chars SimpleSwitch = 1, // A switch preceded by '/' or '-' chars Compound = 2, // A 'switch:argument' pair preceded by '/' or '-' chars Complex = 3 // A 'switch:argument{;argument}' pair with multiple args // preceded by '/' or '-' chars }
Passing in the following command-line arguments to this application: MyApp c:\input\infile.txt -output:d:\outfile.txt -trialmode /debugoutput:c:\test1.log;\\myserver\history\test2.log
results in the following parsed switches and arguments: Literal: c:\input\infile.txt Switch: output Argument: d:\outfile.txt Switch: trialmode Switch: debugoutput Arguments: c:\test1.log \\myserver\history\test2.log
If you input incorrectly formed command-line parameters, such as forgetting to add arguments to the -output switch, you get the following output: An error has occurred while processing the command-line arguments: System.ArgumentException: Command-Line parameter error: argument output must be in the form of a 'switch:argument{;argument}' pair. Parameter name: output at Chapter_Code.ParseCmdLine.ParseSwitchColonArg(String arg, String& outSwitch, String& outArgument) in c:\book cs cookbook\code\chapter3.cs:line 238 at Chapter_Code.Class1.Main(String[] args) in c:\book cs cookbook\code\main.cs:line 55 CHAPTER_CODE.EXE Version 1.0.1009.12739 Copyright TradeMarks See help for command-line usage.
This may be too much output to show to the user; for example, you might not want the entire exception to be displayed. In addition, the last line in the message indicates that you should see the help files for information on the correct command-line usage. It would be more useful to display the correct command-line arguments and some brief information on their usage. To do this, you can extend the ParseCmdLine class and make your own specialized class to use in your application. The SpecializedParseCmdLine class in Example 3-18 shows how this is accomplished. Example 3-18. Implementing a specialized command-line parser public class SpecializedParseCmdLine : ParseCmdLine { public SpecializedParseCmdLine( ) {} public override string ParseSwitch(string arg) { if (arg.IndexOf(':') >= 0) { throw (new ArgumentException("Command-Line parameter error: switch " + arg + " must not be followed by one or more arguments.", arg)); } return (base.ParseSwitch(arg)); } public virtual void DisplayErrorMsg( ) { DisplayErrorMsg(""); } public virtual void DisplayErrorMsg(string msg) { Console.WriteLine( "An error has occurred while processing the command-line arguments:"); Console.WriteLine( ); FileVersionInfo version = Process.GetCurrentProcess( ).MainModule.FileVersionInfo; if (Process.GetCurrentProcess( ).ProcessName.Trim( ).Length > 0) { Console.WriteLine(Process.GetCurrentProcess( ).ProcessName); } else { Console.WriteLine("Product Name: " + version.ProductName); } Console.WriteLine("Version " + version.FileVersion); Console.WriteLine("Copyright " + version.LegalCopyright); Console.WriteLine("TradeMarks " + version.LegalTrademarks); DisplayHelp( ); } public override void DisplayHelp( ) { // Display correct input args. base.DisplayHelp( ); Console.WriteLine("Chapter_Code [file | /output:projectfile | /trialmode | /debugoutput:file{;file}]"); Console.WriteLine( ); Console.WriteLine("Available command-line switches:"); Console.WriteLine("\tfile : The file to use as input."); Console.WriteLine("\toutput : The file to use as output."); Console.WriteLine("\ttrialmode : Turns on the trial mode, if present."); Console.WriteLine("\tdebugoutput : One or more files in which to dump debug information into."); } }
|
This class overrides four methods of the ParseCmdLine class. The DisplayHelp method is overridden to display the relevant information needed to correctly use the command-line parameters in your application. The overloaded DisplayErrorMsg methods are overridden to prevent the lengthy exception message from being displayed. Finally, the ParseSwitch method is overridden to add some more preventive code that will disallow any arguments from being added to a switch that should not have any arguments. By overriding other methods in the ParseCmdLine class, you can modify this class to handle many other situations specific to your application. See Also See the "Main" and "Command-Line Arguments" topics in the MSDN documentation. |
