Skip to content

Token Transformations#

Token transformations are a way to tranform input arguments before they are mapped to commands.

This feature is used internally to expand clubbed options and support Response Files.

See these implementations as examples:

How to implement#

First, create a function with the signature Func<CommandContext, TokenCollection, TokenCollection>. This function will transform a TokenTransformation into a new TokenTransformation.

Next, register the transformation with 

appRunner.Configure(c => c.UseTokenTransformation(
    name: "my-transformation", 
    order: 1, 
    transformation: MyFunc));
  • name is used for logging and the Parse Directive
  • order is the order the transformation should run in relation to other transformations.

Tokens#

Tokens are initially parsed from the Program.Main args array. Transformations can modify tokens or expand them into additional tokens.

Tokens contains

  • RawValue: Raw value from the user input. This will contain the punctuation used to denote option and argument names or brackets enclosing directives. (eg. --help, [debug])
  • Value: Can be an Option name or an argument value or a directive(eg. help)
  • TokenType: Directive, Option, Value, Separator
  • OptionTokenType: when TokenType is Option

OptionTokenType contains

  • IsLong: is a long name (--help)
  • IsShort: is a short name (-h)
  • IsClubbed: multiple short names in a single string (-hv).
  • HasValue: the option has a value assignment (--verbosity:trace)

TokenCollections#

TokenCollections are an immutable collection of tokens with some convenience members to simplify transformations.

  • Directives: The tokens interpreted as directives. This will always be empty when AppSettings.DisableDirectives = false.
  • Arguments: All arguments after the last directive and before the argument separator --
  • Separated: All arguments included after the argument separator --. If there are multiple separators, the remaining separators will be tokens in this collection.

Tip

Use TokenCollection.Transform method to apply a func to tokens of specific types. This is an alternative to a foreach loop with a switch statement. See the implementations linked above for examples.

Use TokenCollection.ToArgsArray extension method to convert the tokens into a string array that can be passed to another application.

Back to top