Directives

As described in Argument syntax arguments consist of four parts, first of which is for directives:

{directives} {command name} {parameters} {options}

Directives are used to modify the behavior of the whole applications. There are few build-in directives, but it's also possible to define custom.

Built-in directives

By default Typin provides 6 directives, i.e., [debug], [preview], [!], [>], [.], and [..]. The last 3 directives are only for interactive mode.

In help screen interactive mode only directives and commands are indicated using @.

Directives are used to change the behavior of the whole application, e.g., imagine you have an application that logs everything to a file, then you can add [no-logging] directive to disable logging for a command or whole interactive session.

[debug] aka run debug mode

When troubleshooting issues, you may find it useful to run your app in debug mode. If your application is ran in debug mode (using the [debug] directive), it will wait for debugger to be attached before proceeding. This is useful for debugging apps that were ran outside of the IDE.

> myapp.exe [debug] cmd -o

Attach debugger to PID 3148 to continue.

By default this directive is disallowed. To add a support of this directive, use AddDirective method in the CliApplicationBuilder:

builder.AddDirective<DebugDirective>();

[preview] aka run preview mode

When troubleshooting issues, you may find it useful to run your app in preview mode. If preview mode is specified (using the [preview] directive), the app will short-circuit by printing consumed command line arguments as they were parsed. This is useful when troubleshooting issues related to command routing and argument binding.

> myapp.exe [preview] cmd arg1 arg2 -o foo --option bar1 bar2

Parser preview:
cmd <arg1> <arg2> [-o foo] [--option bar1 bar2]

By default this directive is disallowed. To add a support of this directive, use AddDirective method in the CliApplicationBuilder:

builder.AddDirective<PreviewDirective>();

[!] aka execute default or scoped command

Normally when application runs in interactive mode, an empty line does nothing; but [!] will override this behavior, executing a root or scoped command. This directive will also force default command execution when input contains default command parameter values equal to command/subcommand name.

[>] aka scope to command(s)

If application runs in interactive mode, [>] directive followed by command(s) name(s) would scope to the command(s), allowing to omit specified command name(s).

For example, commands:

            > [>] cmd1 sub
    cmd1 sub> list
    cmd1 sub> get
            > [>] cmd1
        cmd1> test
        cmd1> -h

are an equivalent to:

            > cmd1 sub list
            > cmd1 sub get
            > cmd1 test
            > cmd1 -h

[.] aka scope-up

If application runs in interactive mode, [.] directive can be used to remove one command from the scope.

Example:

            > [>] cmd1 sub
    cmd1 sub> list
    cmd1 sub> [.]
        cmd1>

[..] aka scope-reset

If application runs in interactive mode, [..] directive can be used to reset current scope to default (global scope).

Example:

            > [>] cmd1 sub
    cmd1 sub> list
    cmd1 sub> [..]
            >