OptionParser.OptionParser

Overview

OptionParser is the glue between Option classes and the command line as supplied via the Run event's args() parameter in a ConsoleApplication or via a call to System.CommandLine in a Desktop or Web application. It handles actually parsing the command line, populating the associated Options and validating it as a whole.

How to supply command line parameters

OptionParser is versitle on it's use of command line options.

  • Options can appear anywhere on the command line
  • Extra can be at the start, middle or end of the command line
  • Short options can be combined
  • Long options with assignment utilize the equal sign (=)
  • Short options can optionally use the = sign
  • File and Directory options can be a full or relative path
  • Anything after a -- is considered an extra even if it looks like a parameter
  • Boolean options can be prefixed with no, --recursive or --no-recursive, it'll just do the right thing.

Here are some example uses at the command line:

# Options for a fictitious copy program
#
# -r/--recursive
# -v/--verbose
# -l/--log FILE

# copy the $HOME/Desktop/Folder to /tmp recursively with verbose turned on

$ cp -rv ~/Desktop/Folder /tmp

# same thing

$ cp ~/Desktop/Folder -r /tmp -v

# enable logging to a file

$ cp -rv --log=file.txt ~/Desktop/Folder /tmp

# enable logging to a file using combined short options 

$ cp -rvl=file.txt ~/Desktop/Folder /tmp

# disable verbose and copy a file named "-r" to "tmp.txt"

$ cp --no-verbose -- -r tmp.txt

Properties

AdditionalHelpNotes As String

Displayed after the help message generated by OptionParser when the help screen is shown.

This can be used to provide further usage notes and to expand on options when a single line description is not sufficient.

AppDescription As String

Typically a single line description of the application that is displayed before the application help.

AppName As String

Name of the application. If empty, OptionParser will assign the AppName variable to the name of the executable filename. This is displayed when user help is shown.

Extra() As String

Any non-option parameters given to the application will be appended to this array. For example:

$ my-app --verbose -o ./docs file.txt file2.txt file3.txt

In the above case, the Extras array will contain three strings:

0 = "file.txt"
1 = "file2.txt"
2 = "file3.txt"

ExtrasRequired As Integer = 0

Specify the minimum number of extra items required. For example, say you are writing a copy program. One might set this value to 2.

$ copy extra1 extra2

See Extra for more information.

HelpRequested As Boolean

True when the user supplies either -h or --help on the command line.

Methods

AddOption(o As Option)

Add an option to the parser.

Parameters

  • o - Option to add

Exceptions

OptionParserException can be thrown if one attempts to add an option with the same short or long key as an existing option. Validation

Arguments() As String()

Get the original arguments passed to the OptionParser as a String array.

BooleanValue(key As Variant, defaultValue As Boolean = False) As Boolean

Retrieve the contents of an option as a Boolean value.

Parameters

  • key - Key of the option to retrieve. This can be the short or long key. Convention is to use the long key if available as it produces more readable code.
  • defaultValue - Value to return if the user did not supply this option.

Notes

The option type must be that of OptionType.Boolean.

Constructor(appName As String = "", appDescription As String = "")

Construct a new OptionParser

Parameters

  • appName - Name of the application to display when showing help.
  • appDescription - Description of the application to display when showing help.

For more inforation on the parameters, see the two properties AppName and AppDescription.

Notes

When creating a new OptionParser the "Help" option is added automatically. The "Help" option uses the short key h and the long key help, thus they can not be used by the application.

DateValue(key As Variant, defaultValue As Date = Nil) As Date

Retrieve the contents of an option as a Date value.

Parameters

  • key - Key of the option to retrieve. This can be the short or long key. Convention is to use the long key if available as it produces more readable code.
  • defaultValue - Value to return if the user did not supply this option.

Notes

The option type must be that of OptionType.Date.

WARNING: If the Option.IsValidDateRequired is set to True then the value supplied must pass the test of ParseDate(). If, however, Option.IsValidDateRequired is set to False and ParseDate() can not handle the date properly, the value is recorded as a String not a Date.

This behavior is likely to change in the future. If one requests the type be a valid date, then the value will have to pass as a valid date or a OptionInvalidKeyValueException will be raised to indicate that an invalid option value has been supplied.

DoubleValue(key As Variant, defaultValue As Double = 0.0) As Double

Retrieve the contents of an option as a Double value.

Parameters

  • key - Key of the option to retrieve. This can be the short or long key. Convention is to use the long key if available as it produces more readable code.
  • defaultValue - Value to return if the user did not supply this option.

Notes

The option type must be that of OptionType.Double.

FileValue(key As Variant, defaultValue As FolderItem = Nil) As FolderItem

Retrieve the contents of an option as a FolderItem value.

Parameters

  • key - Key of the option to retrieve. This can be the short or long key. Convention is to use the long key if available as it produces more readable code.
  • defaultValue - Value to return if the user did not supply this option.

Notes

The option type must be that of OptionType.File or OptionType.Folder.

WARNING: This will likely be renamed to FolderItemValue in the future.

IntegerValue(key As Variant, defaultValue As Integer = 0) As Integer

Retrieve the contents of an option as a Integer value.

Parameters

  • key - Key of the option to retrieve. This can be the short or long key. Convention is to use the long key if available as it produces more readable code.
  • defaultValue - Value to return if the user did not supply this option.

Notes

The option type must be that of OptionType.Integer.

OptionValue(key As String) As Option

Retrieve the actual Option object associated with the key.

Parameters

  • key - Key of the option to retrieve. This can be the short or long key. Convention is to use the long key if available as it produces more readable code.

Notes

Once Parse has been called, changing parameters in the Option object will have no bearing or change.

One can use this to check the WasSet property of the Option class.

Parse(args() As String)

Parse the arguments

Parameters

  • args() - Command line arguments already split into an array. Generally this will be used with a ConsoleApplication since it's Run event passes in command line parameters this way.

Exceptions

  • OptionUnrecognizedKeyException can be raised in the event an invalid argument is supplied. For example, the user types myprog --coun=12 when it should have been --count=12.
  • OptionInvalidKeyValueException can be raised in the event a valid argument is supplied with an invalid value. For example --count=John where count was suppose to be an Integer.
  • OptionParserException can be raised in the event that the application expects at least X extra items but the user did not supply at least X extra items.

Parse(value As String)

Parse the arguments into a String array of parameters, then pass the contents of that array to the 'real' Parse(args() As String) method.

Parameters

  • value - Command line arguments contained in a single line string. This is most often used in a Desktop or Web application via a call to System.CommandLine as a Desktop and Web application has no direct access to the args() parameter that a ConsoleApplication does.

Notes

See Parse(args() As String) for more detailed information

ShowHelp(sectionTitle As String = "Help")

Display a nicely formatted help message including various pieces of meta data such as AppName, AppDescription and AdditionalHelpNotes. Mixed in there are of course all of the possible options with their short and long keys, value types (if any) and description

Parameters

  • sectionTitle - One can overide the section title in case they have multiple help screen outputs or have utilized more than one OptionParser for some advanced techniques.

Notes

Right now there is not a nice GUI for displaying the command line help for a GUI application or a Web application.

  • For a console application, the output is Print to the screen.
  • For a GUI application, the output is given to MsgBox
  • For a Web application, help is not currently displayed.

WARNING: It is likely that for console applications the call to Print will changes to StdErr.Write instead.

StringValue(key As Variant, defaultValue As String = "") As String

Retrieve the contents of an option as a String value.

Parameters

  • key - Key of the option to retrieve. This can be the short or long key. Convention is to use the long key if available as it produces more readable code.
  • defaultValue - Value to return if the user did not supply this option.

Notes

The option type must be that of OptionType.String.

ArrayValue(key As Variant) As Variant()

Retrieve the contents of an option as a Variant array. The contents of the array are of course a Variant however the actual value assigned to the Variant is that of the options OptionType. For example, if this option is of the OptionType.Integer value, then the resulting array will be an array containing parsed Integer values from the command line. The same is true for any of the OptionType values.

Parameters

  • key - Key of the option to retrieve. This can be the short or long key. Convention is to use the long key if available as it produces more readable code.

Notes

The option needs to have the IsArray property set to True to utilize this method.