OptionParser is a library that deals with option parsing and option handling for command-line (CLI) programs.
Options are defined in a class that derives from OptionParser
, where each option is declared as a property and has a type that derives from Option
. Meta-information about the options (such as its name) are defined using attributes. The library comes with multiple pre-defined option types, which will enable you to get started quickly. See below for a complete list of option types.
Below we will describe the few necessary steps to get the option parser to run in your application.
The first step in using OptionParser is to create a class that derives from OptionParser
that defines the different switches of your application. Below is a small example:
public class ExampleOptionParser : OptionParser
{
public override string Name => "Option parser example";
public override string Description => "This application provides a basic example of the OptionParser library";
[Option(Description = "Specifies the input size in number of bytes", Name = "--input-size", ShortName = "-i")]
public IntOption InputSize { get; set; }
[Option(Description = "Specifies whether or not binary mode should be used", Name = "--binary-mode", ShortName = "-b")]
public BoolOption BinaryMode { get; set; }
[Option(Description = "Specifies the source location", Name = "--source-location", ShortName = "-s")]
public StringOption SourceLocation { get; set; }
}
This class defines an option parser with a specific name and description. It specifies three options. There is an IntOption
to specify the input size, a BoolOption
to specify binary mode, and there is a StrngOption
to specify the source location. The attributes for each option specify meta data. In this example, the description of each option and its syntax (as long name and short name).
To use this option parser you instantiate the class and use its Parse
method as follows:
public static void Main(string[] args)
{
var options = new ExampleOptionParser();
options.Parse(args);
}
This example shows how the array of command line parameters args
is passed to the Parse
method. For testing purposes, you could also pass your own set of switches to the parser. E.g.:
options.Parse("-i", "10", "--binary-mode");
The meta information defined in your parser class also serves to build default usage instructions. If you run your application with the --help
or /?
switch, the parser writes usage instructions of your application to standard error.
Option parser example -- This application provides a basic example of the
OptionParser library
Usage:
--binary-mode (-b) Specifies whether or not binary mode should be used
--input-size (-i) Specifies the input size in number of bytes
--source-location (-s) Specifies the source location
--help (/?) Shows this usage information. (default: false).
After parsing, the different properties of ExampleOptionParser
are instantiated according to the command line arguments that are passed to the parser.
For instance, to get the input size use:
int input_size = options.InputSize.Value;
If this switch wasn't used by the user, options.InputSize.IsDefined
is false. This is because options are optional by default. To make an option mandatory, specify IsRequired = true
for the option:
[Option(Description = "Specifies the input size in number of bytes", Name = "--input-size", ShortName = "-i", IsRequired = true)]
public IntOption InputSize { get; set; }
If the user does not specify the switch an exception is which you need to handle in your program.
The library supports more advanced option handling than the getting-started example shows. For instance, it supports enum types,file options, as well as sub commands. The source code of OptionParser
contain unit tests for each feature, demonstrating their usage.
The class OptionParser
forms the base class of every option parser. It has two constructors:
protected OptionParser(IEnumerable<string> args)
protected OptionParser()
The first constructor automatically parses the list of arguments args
. The second constructor only performs required initialization, while the parsing has to be done explicitly by calling the Parse
methods.
The class defines the following abstract properties that must be defined in a base class:
Name
Specifies the name of the application. This is used in the generated usage instructions.Description
Provides a short description about the program. This information is used in the generated usage instructions.
The following option can optionally be defined in a base class:
Copyright
Provides copyright information about the program. This information is used in the generated usage instruction.
Explicit parsing is done by choosing one of the following parse methods:
public void Parse(params string[] args
Parse(IEnumerable<string> args)
The first is typically used for unit testing where you can pass a sequence of command line arguments to the parse method. The second method is typically used to parse the array of command line argument from your Main
method.
To display usage information you can choose between two variants:
public void DisplayUsage(TextWriter writer)
public void DisplayUsage(TextWriter writer, int width)
The first uses a default line width based on the console window width, for the second variant you specify the width explicitly.
There are three properties available to further inspect the parser and the parse result:
public List<Option> Options
Returns the collection of switched defined in your option parser.public List<Option> ProcessedOptions
Returns the collection of all the options that have successfully been processed.public List<string> Arguments
Returns the collection of remaining (unparsed) command line arguments after parsing.
Metadata of options is specified using the OptionAttribute
. It has the following properties:
DefaultValue
Specifies a default value for the option.Description
Specifies a description for the option.EnumValue
For enumeration-based options (e.g., SwitchOption and CommandOption) this attribute specifies the enum value to which this option corresponds.Index
Specifies the index in the help overview where this option should appear.IsRequired
Indicates whether an option is mandatory or not.Name
Specifies the name of the option (e.g., '--input-size').ShortName
Specifies the abbreviated name of the option (e.g., '-i').
Below is the list of predefined option types.
BoolOption
Defines a boolean switch. It accepts a value of true or false,but specifying this value is required. The evaluated value is accessible through theValue
property.CommandOption
This is an advanced feature ofOptionParser
which enables the definition of commands with different sets of switches. Please look at the unit tests for further information.EnumOption
This option type serves to define a fixed set of accepted values.FileOption
ExtendsStringOption
with aFileName
property.InputFileOption
ExtendsFileOption
with aReader
property of typeTextReader
which allows to easily access the file that was specified on the command line.IntOption
Defines an integer switch. The evaluated value is accessible through theValue
property.OutputFileOption
ExtendsFileOption
with aWriter
property of typeTextWriter
which allows to easily access the file that was specified on the command line. The propertyEncoding
allows you to write a file in the correct encoding.PathOption
ExtendsStringOption
with aPath
property.StringOption
Defines a string switch. The evaluated value is accessible through theValue
property.SwitchOption
This is an advanced feature ofOptionParser
that serves to define a group of command line switch one of which may be used at a time. Please look at the unit tests for examples of using this feature.
Source code of OptionParser
is available at GitHub. Nuget packages are available at Nuget.org.
OptionParser
is distributed under the Apache 2.0 License.