How the Command-Line Parser Works
The sample parser in this article meets these guidelines. It consists of several classes in a CommandLineParse namespace. The CommandLineParser class (see Listing 1
) controls the sequence of actions involved in parsing a command line and serves as a repository for both matched and unmatched parameters and for error messages. To set up the CommandLineParser, you populate its CommandLineEntryCollection (see Listing 2
) with CommandLineEntry objects (see Listing 3
) by calling the parser's CreateEntry
method (see Listing 1
). You must pass a CommandTypeEnum
value to the function that specifies the type of data, and optionally, the value expected for each CommandTypeEntry
a value from the CommandTypeEnum enumeration, shown below:
Public Enum CommandTypeEnum
' a file specification, such as "*.txt"
Filespec = 1
' a short date string, e.g. 08/12/2002
ShortDateString = 2
' a long date string, e.g. 08/12/2002 12:00:01 AM
LongDateString = 3
' any string value
Value = 4
' text validated with a regular expression
RegExpression = 5
' a value treated as an single or
' multiple character option that must
' be preceded by "/" or "-"
Flag = 6
' a file that must already exist
ExistingFile = 7
These seven types serve to make the CommandLineParser both useful and flexible. It's useful because it can recognize and validate common input parameter types, such as files and dates, thus eliminating most common command-line-parsing code. It's flexible because you can use the Value type for any arbitrary value, or the RegExpression type to validate complex entries.
To perform the parse, the CommandLineParser creates a Tokenizer class that splits the command line into its component parts. The Tokenizer returns a Tokens collection containing the individual parameters. The parser then passes the Tokens collection and its CommandLineEntryCollection to a TokenAssigner, which tries to assign each individual token to a matching CommandLineEntry object by looping each object's Value
property through the collection setting.
Setting the Value
property causes the CommandLineEntry object to perform a first-level validation of the tokens by checking the type and settings for that particular CommandLineEntry object against the characteristics of the token. The CommandLineEntry objects reject tokens if they don't match the settings for that particular CommandLineEntry.
The TokenAssigner returns an UnmatchedTokensCollection object that contains all the command line parameters for which the TokenAssigner could not find a matching CommandLineEntry object. The TokenAssigner can return unmatched tokens even after a successful parse (see Figure 1
|Figure 1: Overview of the Parse operation. The calling code creates and populates a CommandLineParser object and then passes it a command line string. The parser uses a Tokenizer class to split the command line into tokens and a TokenAssigner class to match the CommandLineEntry objects in its Entries collection with the tokens. The calling code has access to any unmatched tokens, the Entries collection, and a list of error messages generated during the parse operation.|
|Author's Note: Don't confuse unmatched tokens with unmatched CommandLineEntry items. A successful parse does not necessarily populate every defined CommandLineEntry, because some entries may have their property set to False, and the command line may not contain a matching token for those entries.
If the TokenAssigner completes without errors, the Parser calls a method, which loops through the populated CommandLineEntryCollection performing a second-level validation that enforces the Required, RequiredPosition the MustFollow/, and the MustAppearBefore/MustAppearAfter property settings. The FinalValidation method sets the parser's IsValid property that lets the developer know if the parse was successful.
As implemented in the sample code, the parser ignores extra parameters entered by the user, but you can access them through the UnmatchedEntries property, and treat them appropriately for your application.