Recipe 3.23 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 following class to help with 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 spaces and/or tabs.
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 runtime 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 only as an escape sequence character 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 devenv.exe ) 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. The following code shows how this can be accomplished:

 [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 we input incorrectly formed command-line parameters, such as forgetting to add arguments to the -output switch, we get the following output:

 An error has occured 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, we can extend the ParseCmdLine class and make our own specialized class to use in our application. The following class shows how this is accomplished:

 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 our 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 preventative 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.

Recipe 3.23 Parsing Command-Line Parameters

Problem

Solution

Discussion

See Also