Class CommandLine

Namespace: Pixie.Options

Assembly: Pixie.dll

Defines the options accepted by a command-line program and parses argument lists into an OptionParseResult. Use this type when you want one place to describe your options, positional arguments, and common built-in behaviors such as --help and --version.

public sealed class CommandLine

Inheritance: object

CommandLine

Inherited Members: object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Constructors

CommandLine(params Option[])

Creates a command line that accepts only named options.

public CommandLine(params Option[] options)

Parameters

options Option[]: The options accepted by the command line.

CommandLine(IReadOnlyList<Option>, Option)

Creates a command line with one option that also consumes positional arguments.

public CommandLine(IReadOnlyList<Option> options, Option positionalOption)

Parameters

options IReadOnlyList<Option>: The options accepted by the command line.
positionalOption Option: The option that should consume bare arguments such as file names.

CommandLine(IReadOnlyList<Option>, Option, OptionForm)

Creates a command line with one option that also consumes positional arguments, using a specific option form when Pixie needs to describe that positional usage.

public CommandLine(IReadOnlyList<Option> options, Option positionalOption, OptionForm positionalForm)

Parameters

options IReadOnlyList<Option>: The options accepted by the command line.
positionalOption Option: The option that should consume bare arguments such as file names.
positionalForm OptionForm: The preferred form for the positional option in help and usage text.

CommandLine(IReadOnlyList<Option>, IReadOnlyList<KeyValuePair<Option, OptionForm>>)

Creates a command line with explicitly configured positional bindings.

public CommandLine(IReadOnlyList<Option> options, IReadOnlyList<KeyValuePair<Option, OptionForm>> positionalOptions)

Parameters

options IReadOnlyList<Option>: The options accepted by the command line.
positionalOptions IReadOnlyList<KeyValuePair<Option, OptionForm>>: The options that should consume bare arguments, in the order they should be considered.

Properties

HelpOption

Gets the generated help option, if any.

public Option HelpOption { get; }

Property Value

Option: The help option.

Options

Gets the options accepted by this command line.

public IReadOnlyList<Option> Options { get; }

Property Value

IReadOnlyList<Option>: The accepted options.

PositionalOptions

Gets the positional option bindings for this command line.

public IReadOnlyList<KeyValuePair<Option, OptionForm>> PositionalOptions { get; }

Property Value

IReadOnlyList<KeyValuePair<Option, OptionForm>>: The positional option bindings.

Summary

Gets the summary used for generated help output.

public Block Summary { get; }

Property Value

Block: The summary.

Usage

Gets the usage text used for generated help output.

public Inline Usage { get; }

Property Value

Inline: The usage text.

Version

Gets the version text emitted by the generated version option.

public Block Version { get; }

Property Value

Block: The version text.

VersionOption

Gets the generated version option, if any.

public Option VersionOption { get; }

Property Value

Option: The version option.

Methods

Parse(IReadOnlyList<string>)

Parses a list of command-line arguments and returns both the parsed values and any diagnostics Pixie produced while parsing. Diagnostics are captured in the result and not forwarded anywhere.

public OptionParseResult Parse(IReadOnlyList<string> arguments)

Parameters

arguments IReadOnlyList<string>: The command-line arguments to parse.

Returns

OptionParseResult: A parse result.

Parse(IReadOnlyList<string>, ILog)

Parses a list of command-line arguments, forwarding any diagnostics to the supplied log while also capturing them in the result. This is the usual entry point for real commands because it lets Pixie print parse errors, generated help, or version information immediately while still giving the caller structured access to the outcome.

public OptionParseResult Parse(IReadOnlyList<string> arguments, ILog log)

Parameters

arguments IReadOnlyList<string>: The command-line arguments to parse.
log ILog: The log to forward diagnostics to.

Returns

OptionParseResult: A parse result.

WithHelp(Block, Inline, params string[])

Creates a copy of this command line that also supports a generated help option, typically -h and --help.

public CommandLine WithHelp(Block summary, Inline usage, params string[] forms)

Parameters

summary Block: The summary shown in generated help output.
usage Inline: The usage text shown in generated help output.
forms string[]: The forms accepted by the help option. If omitted, Pixie uses -h and --help.

Returns

CommandLine: A new command line.

WithHelp(string, string, params string[])

Creates a copy of this command line that also supports a generated help option, typically -h and --help.

public CommandLine WithHelp(string summary, string usage, params string[] forms)

Parameters

summary string: The summary shown in generated help output.
usage string: The usage text shown in generated help output.
forms string[]: The forms accepted by the help option. If omitted, Pixie uses -h and --help.

Returns

CommandLine: A new command line.

WithVersion(Block, params string[])

Creates a copy of this command line that also supports a generated version option, typically --version.

public CommandLine WithVersion(Block version, params string[] forms)

Parameters

version Block: The version text to emit.
forms string[]: The forms accepted by the version option. If omitted, Pixie uses --version.

Returns

CommandLine: A new command line.

WithVersion(string, params string[])

Creates a copy of this command line that also supports a generated version option, typically --version.

public CommandLine WithVersion(string version, params string[] forms)

Parameters

version string: The version text to emit.
forms string[]: The forms accepted by the version option. If omitted, Pixie uses --version.

Returns

CommandLine: A new command line.