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 [default]. The last 4 directives are only for interactive mode. Directives are used to change the behaviour of the whole application, e.g., imagine you have an application that logs everything to a fiel, then you can add [no-logging] directive to disable logging for a command or whole interactive session.

[debug] aka 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 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 scope to command(s)

If application rans in interactive mode, [>] directive followed by command(s) name(s) would scope to the command(s), allowing to ommit 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 rans 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 rans in interactive mode, [..] directive can be used to reset current scope to default (global scope).

Example:

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

[default] aka execute default or scoped command

Normally if application rans in interactive mode, an empty line does nothing; but [default] will override this behaviour, executing a root (empty) command or scoped command without arguments (parameters and options).