StauffConsulting.Essentials.

CmdLineParser

C#:  
public class CmdLineParser :
    object

VB:  
Public Class CmdLineParser
    Inherits Object

Type Ancestry:  Object
+---CmdLineParser

Parses command lines that are passed to a console program.

This class allows you to define the syntax for the command-line arguments that are passed to a console program when it is launched, and made available through the argument to the Main method. This class recognizes three fundamental kinds of tokens:

The command-line syntax recognized by this class is as follows:

command_line := [element [whitespace element]...]
element := non_switch | (switch [arg_list])
arg_list := (whitespace switch_arg)...
switch_arg := token
switch := "-" token
non_switch := token
token := any sequence of non-space characters, not beginning with "-"
| any sequence of characters enclosed in double-quotes
whitespace := space | tab
Each defined switch may appear at most once in a command line; including the same switch twice will result in a run-time exception being thrown. The following kinds of switches are currently supported:
Boolean Switch
This kind of switch has no arguments; each switch is either present or not present.
String Switch
This switch expects a single string argument to follow it.
Integer Switch
This switch expects a single integer argument to follow it.
String List Switch
This switch expects one or more string arguments to follow it, up to (but not including) the next switch, or the end of the command line.
Integer List Switch
This switch expects one or more integer arguments to follow it, up to (but not including) the next non-integer argument, or the end of the command line.
The parser recognizes any non-ambiguous prefix for a switch. That is, if you define a switch named "foobar" , the parser will recognize "-foo" as matching that switch, as long as there are no other switches beginning with "-foo" . Switches are not case-sensitive.

How to Use It

  1. Instantiate a CmdLineParser object.
  2. Instantiate whatever subclasses of the Switch class you need to define your switches. Pass to the constructors whatever default values you want to use if the corresponding switch doesn't appear in the command line.
  3. Add your switch objects to the CmdLineParser object using the AddSwitch method.
  4. Call the Parse method to parse the command line arguments. If any errors are encountered, Parse will throw a SyntaxError .

Summary Info

Constructor Summary

CmdLineParser Constructs a command line parser.

Field Summary

Property Summary

Method Summary

AddSwitch Adds a switch to the command parser.
AddSwitches Adds a collection of switches to the command parser.
DefineHelp Defines a help overview message.
DefineNonSwitch Defines where to put non-switch arguments.
DefineNonSwitch
Parse Parses the command line arguments, and places any switch values in the appropriate Switch objects.
WordWrap Word-wraps a string to fit in the given number of columns.
WriteHelp Displays help.

Miscellany Summary

Constructor Details

CmdLineParser

C#:  
CmdLineParser ()

VB:  
Sub New()

Constructs a command line parser.

Method Details

AddSwitch

C#:  
Void AddSwitch(StauffConsulting.Essentials.Switch s)

VB:  
Function AddSwitch(ByVal s As StauffConsulting.Essentials.Switch) As Void

Adds a switch to the command parser.

Parameters

s  

AddSwitches

C#:  
Void AddSwitches(System.Collections.ICollection c)

VB:  
Function AddSwitches(ByVal c As System.Collections.ICollection) As Void

Adds a collection of switches to the command parser.

Parameters

c  

DefineHelp

C#:  
Void DefineHelp(string help)

VB:  
Function DefineHelp(ByVal help As String) As Void

Defines a help overview message. This string will be printed when help is requested, before the help for the individual switches. It is intended to provide an overall description of what the program does. It need not contain any newlines; help output is automatically word-wrapped.

Parameters

help   the help string.

DefineNonSwitch

C#:  
Void DefineNonSwitch(string[] values,
    string help)

VB:  
Function DefineNonSwitch(ByVal values() As String, ByVal help As String) As Void

Defines where to put non-switch arguments. If you call this method, then the parser will accept arguments that are neither switches nor switch arguments, and place them in the specified array. If you do not call this method, then when the parser encounters an argument that is neither a switch nor a switch argument, it throws a SyntaxError. This method may be called at most once during the lifetime of each CmdLineParser object. If it is called more than once, an assertion will fail.

Parameters

values   this array will receive the values of the non- switch arguments when the command line is parsed. If the user provides more non-switch arguments than will fit in this array, the parser will throw a SyntaxError.
help   a help string describing the expected arguments. This will be printed when help is requested. It should not contain any newlines; help output is automatically word-wrapped.

DefineNonSwitch

C#:  
Void DefineNonSwitch(System.Collections.Generic.List values,
    string help)

VB:  
Function DefineNonSwitch(ByVal values As System.Collections.Generic.List(Of String), ByVal help As String) As Void

Parameters

values  
help  

Parse

C#:  
Void Parse(string[] cmdLineArgs)

VB:  
Function Parse(ByVal cmdLineArgs() As String) As Void

Parses the command line arguments, and places any switch values in the appropriate Switch objects. If any syntax errors are encountered it throws a SyntaxError. This method may be called at most once during the lifetime of each CmdLineParser object. If it is called more than once, an assertion will fail.

Parameters

cmdLineArgs   the command line arguments that were passed to Main().

WordWrap

C#:  
static String WordWrap(string input,
    int maxColumns,
    string prefix)

VB:  
Shared Function WordWrap(ByVal input As String, ByVal maxColumns As Integer, ByVal prefix As String) As [String]

Word-wraps a string to fit in the given number of columns.

Parameters

input   the string to be word-wrapped.
maxColumns   the maximum number of columns; i.e. the maximum number of characters per line.
prefix   a string to prepend to the beginning of each line, or null.
RETURNS   the word-wrappped string

WriteHelp

C#:  
Void WriteHelp(System.IO.TextWriter tw,
    int helpWidth)

VB:  
Function WriteHelp(ByVal tw As System.IO.TextWriter, ByVal helpWidth As Integer) As Void

Displays help.

Parameters

tw   where to write it
helpWidth   width in characters for wrapping text; 0 = no wrap

generated by DocGenDotNet on 18 Nov 2008 6:35:01 PM