DotMake.CommandLine Namespace

This is the root namespace of this library, it includes the CLI attributes and CLI parser/runner.

The main classes in this namespace are:

• CliCommandAttribute is the attribute which specifies a class that represents a command which is a specific action that the command line application performs.
• CliOptionAttribute is the attribute which specifies a class property that represents an option which is a named parameter and a value for that parameter, that is used on the command line.
• CliArgumentAttribute is the attribute which specifies a class property that represents an argument which is a value that can be passed on the command line to a command or an option.
• CliDirectiveAttribute is the attribute which specifies a class property that represents a directive which is a syntactic element, that is used on the command line.
• Cli is the class which provides methods for parsing command line input and running an indicated command.
• CliSettings is the class which represents the settings used by the Cli.
• CliTheme is the class which represents the theme used by the Cli. These color and formatting option are mainly used by the help output.
• CliParser is the class which represents a CLI parser configured for a specific command with grammar and behaviors.
• CliContext is the class which supports command invocation by providing access to parse results and other services.
• CliResult is the class which describes the results of parsing a command line input based on a specific parser configuration and provides methods for binding the result to definition classes.

Classes

Cli	Provides methods for parsing command line input and running an indicated command.
CliArgumentAttribute	Specifies a class property that represents an argument which is a value that can be passed on the command line to a command or an option. [CliArgument] public string SomeCliArgument { get; set; } Note that an argument is required if the decorated property does not have a default value (set via a property initializer), see Required property for details. Arguments: An argument is a value passed to an option or a command. The following examples show an argument for the verbosity option and an argument for the build command. dotnet tool update dotnet-suggest --verbosity quiet --global ^---^ dotnet build myapp.csproj ^----------^ Arguments can have default values that apply if no argument is explicitly provided. For example, many options are implicitly Boolean parameters with a default of true when the option name is in the command line.
CliBindingContext	Context used for binding of commands to definition classes.
CliCommandAsDelegate	Represents a definition class generated by the source generator for a command as delegate.
CliCommandAttribute	Specifies a class that represents a command which is a specific action that the command line application performs. [CliCommand] public class SomeCliCommand The class that this attribute is applied to, will be a root command if the class is not a nested class and other's Children property and self's Parent property is not set. will be a sub command if the class is a nested class or other's Children property or self's Parent property is set. Commands: A command in command-line input is a token that specifies an action or defines a group of related actions. For example: In dotnet run, run is a command that specifies an action. In dotnet tool install, install is a command that specifies an action, and tool is a command that specifies a group of related commands. There are other tool-related commands, such as tool uninstall, tool list, and tool update. Root commands: The root command is the one that specifies the name of the app's executable. For example, the dotnet command specifies the dotnet.exe executable. Subcommands: Most command-line apps support subcommands, also known as verbs. For example, the dotnet command has a run subcommand that you invoke by entering dotnet run. Subcommands can have their own subcommands. In dotnet tool install, install is a subcommand of tool. Inheritance: When you have repeating/common options and arguments for your commands, you can define them once in a base class and then share them by inheriting that base class in other command classes.Interfaces are also supported ! Handler: Add a method with name Run or RunAsync to make it the handler for the CLI command. The method can have one of the following signatures: void Run() int Run() async Task RunAsync() async Task<int> RunAsync() Optionally the method signature can have a CliContext parameter in case you need to access it: Run(CliContext context) RunAsync(CliContext context) We also provide interfaces ICliRun, ICliRunWithReturn, ICliRunWithContext, ICliRunWithContextAndReturn and async versions ICliRunAsync, ICliRunAsyncWithReturn, ICliRunAsyncWithContext, ICliRunAsyncWithContextAndReturn that you can inherit in your command class. Normally you don't need an interface for a handler method as the source generator can detect it automatically, but the interfaces can be used to prevent your IDE complain about unused method in class. The signatures which return int value, sets the ExitCode of the app. If no handler method is provided, then by default it will show help for the command. This can be also controlled manually by extension method ShowHelp(). Other extension methods IsEmptyCommand(), ShowValues() and ShowHierarchy(bool) are also useful.
CliCommandBuilder	Represents a command builder generated by the source generator.
CliContext	Supports command invocation by providing access to parse results and other services.
CliDirectiveAttribute	Specifies a class property that represents a directive which is a syntactic element, that is used on the command line. [CliDirective] public bool SomeCliDirective { get; set; } Currently only bool, string and string[] types are supported for [CliDirective] properties. Directives: System.CommandLine introduces a syntactic element called a directive. The [diagram] directive is an example. When you include [diagram] after the app's name, System.CommandLine displays a diagram of the parse result instead of invoking the command-line app: dotnet [diagram] build --no-restore --output ./build-output/ ^-------^ Output: [ dotnet [ build [ --no-restore <True> ] [ --output <./build-output/> ] ] ] The purpose of directives is to provide cross-cutting functionality that can apply across command-line apps. Because directives are syntactically distinct from the app's own syntax, they can provide functionality that applies across apps. A directive must conform to the following syntax rules: It's a token on the command line that comes after the app's name but before any subcommands or options. It's enclosed in square brackets. It doesn't contain spaces. An unrecognized directive is ignored without causing a parsing error. A directive can include an argument, separated from the directive name by a colon (:): myapp [directive:value] myapp [directive:value1] [directive:value2] The following directives are built in (can be enabled/disabled via CliSettings): [diagram], [suggest], [env]
CliExtensions	Provides extension methods for Cli. These are usually automatically generated by the source generator when current project supports a specific feature through a dependency, e.g. when you add package Microsoft.Extensions.DependencyInjection, dependency injection related extension methods will be available here.
CliHelpBuilder	Formats output to be shown to users to describe how to use a command line tool. HelpBuilder is weirdly designed, i.e. it's hard to derive from that class due to static methods. CliHelpBuilder solves this problem by providing overridable methods, and it also adds color support.
CliHelpBuilder.Default	Provides default formatting for help output.
CliNamer	Provides methods for generating CLI names and aliases while tracking already used ones.
CliOptionAttribute	Specifies a class property that represents an option which is a named parameter and a value for that parameter, that is used on the command line. [CliOption] public string SomeCliOption { get; set; } Note that an option is required if the decorated property does not have a default value (set via a property initializer), see Required property for details. Options: An option is a named parameter that can be passed to a command. The POSIX convention is to prefix the option name with two hyphens (--). The following example shows two options: dotnet tool update dotnet-suggest --verbosity quiet --global ^---------^ ^------^ As this example illustrates, the value of the option may be explicit (quiet for --verbosity) or implicit (nothing follows --global). Options that have no value specified are typically Boolean parameters that default to true if the option is specified on the command line. For some Windows command-line apps, you identify an option by using a leading slash (/) with the option name. For example: msbuild /version ^------^ Both POSIX and Windows prefix conventions are supported. When manually setting a name (overriding decorated property's name), you should specify the option name including the prefix (e.g. `--option`, `-o`, `-option` or `/option`). Bundling of single-character options are supported, also known as stacking. Bundled options are single-character option aliases specified together after a single hyphen prefix. For example if you have options "-a", "-b" and "-c", you can bundle them like "-abc". Only the last option can specify an argument. Note that if you have an explicit option named "-abc" then it will win over bundled options.
CliParser	Represents a CLI parser configured for a specific command with grammar and behaviors.
CliResult	Describes the results of parsing a command line input based on a specific parser configuration and provides methods for binding the result to definition classes.
CliSettings	Represents the settings used by the Cli.
CliStringUtil	Provides CLI related string methods.
CliTheme	Represents the theme used by the Cli. These color and formatting option are mainly used by the help output.
CliValidationExtensions	Provides extension methods related to validation for Argument and Option.

Interfaces

ICliGetCompletions	An interface to get custom completions for options and arguments in a command class.
ICliRun	An interface to add a command handler with void Run() signature to a command class. Normally you don't need an interface for a handler method as the source generator can detect it automatically, but the interface can be used to prevent your IDE complain about unused method in class.
ICliRunAsync	An interface to add an async command handler with Task RunAsync() signature to a command class. Normally you don't need an interface for a handler method as the source generator can detect it automatically, but the interface can be used to prevent your IDE complain about unused method in class.
ICliRunAsyncWithContext	An interface to add an async command handler with Task RunAsync(CliContext) signature to a command class. Normally you don't need an interface for a handler method as the source generator can detect it automatically, but the interface can be used to prevent your IDE complain about unused method in class.
ICliRunAsyncWithContextAndReturn	An interface to add an async command handler with Task<int> RunAsync(CliContext) signature to a command class. Normally you don't need an interface for a handler method as the source generator can detect it automatically, but the interface can be used to prevent your IDE complain about unused method in class.
ICliRunAsyncWithReturn	An interface to add an async command handler with Task<int> RunAsync() signature to a command class. Normally you don't need an interface for a handler method as the source generator can detect it automatically, but the interface can be used to prevent your IDE complain about unused method in class.
ICliRunWithContext	An interface to add a command handler with void Run(CliContext) signature to a command class. Normally you don't need an interface for a handler method as the source generator can detect it automatically, but the interface can be used to prevent your IDE complain about unused method in class.
ICliRunWithContextAndReturn	An interface to add a command handler with int Run(CliContext) signature to a command class. Normally you don't need an interface for a handler method as the source generator can detect it automatically, but the interface can be used to prevent your IDE complain about unused method in class.
ICliRunWithReturn	An interface to add a command handler with int Run() signature to a command class. Normally you don't need an interface for a handler method as the source generator can detect it automatically, but the interface can be used to prevent your IDE complain about unused method in class.

Enums

CliArgumentArity	Defines the arity of an option or argument. The arity refers to the number of values that can be passed on the command line.
CliNameAutoGenerate	Defines the CLI symbol types for auto-generated names or short form aliases.
CliNameCasingConvention	Defines the character casing conventions to use for command, option and argument names.
CliNamePrefixConvention	Defines the prefix conventions to use for option names and aliases.
CliValidationRules	Defines validation rules for a CLI argument and a CLI option's argument.