github.com/facebookincubator/ttpforge@v1.0.13-0.20240405153150-5ae801628835/docs/foundations/args.md (about)

     1  # Customizing Your TTPs with Command-Line Arguments
     2  
     3  **Note**: to run the examples in this section, make sure you have the `examples`
     4  repository installed with `ttpforge list repos` and if not run:
     5  
     6  ```bash
     7  ttpforge install repo https://github.com/facebookincubator/TTPForge --name examples
     8  ```
     9  
    10  ## Basics of Command-Line Arguments
    11  
    12  TTPForge allows users to control TTP execution through its support for
    13  command-line arguments - check out the TTP below to see how it works:
    14  
    15  https://github.com/facebookincubator/TTPForge/blob/7634dc65879ec43a108a4b2d44d7eb2105a2a4b1/example-ttps/args/basic.yaml#L1-L33
    16  
    17  You can run this TTP and provide values for all relevant arguments as follows:
    18  
    19  ```bash
    20  ttpforge run examples//args/basic.yaml \
    21    --arg str_to_print=hello \
    22    --arg run_second_step=true
    23  ```
    24  
    25  Try out the following exercises to increase your understanding of how arguments
    26  work in TTPForge:
    27  
    28  - Remove `--arg str_to_print="..."` - the TTP will now refuse to run because the
    29    user is required to specify a value for that argument since it has no
    30    `default` value specified.
    31  - Explicitly set `int_arg` with `--arg int_arg=5` - the `default` value will be
    32    overridden.
    33  - Try to pass values with invalid types, such as `--arg int_arg=foo` or
    34    `--arg run_second_step=bar`. TTPForge validates argument types and should
    35    throw an error for both of these cases. Note that `string` type arguments (the
    36    default) will pretty much accept anything.
    37  - Disable the second step by removing the `--arg run_second_step=true` line.
    38  
    39  Focus in particular on the last item above, concerning `run_second_step=true`.
    40  TTPForge TTP files are processed using Golang's
    41  [text/template](https://pkg.go.dev/text/template) package to expand all argument
    42  values prior to execution. We can use advanced templating features, such as the
    43  [if-else-end](https://pkg.go.dev/text/template#hdr-Actions) shown above, to
    44  precisely control execution based on argument values.
    45  
    46  ## Argument Types
    47  
    48  TTPForge supports the following argument types (which you can specify with the
    49  `type:` field as shown in the example above):
    50  
    51  - `string` (this is the default if no `type` is specified)
    52  - `int`
    53  - `bool`
    54  - `path` (a very important one - see below)
    55  
    56  ## The `path` Argument Type
    57  
    58  If your TTP will accept arguments that refer to file paths on disk, you should
    59  **almost always** use `type: path` when declaring those arguments, as shown in
    60  the example below (just focus on the `args:` section for now, though you can
    61  check out the [edit_file documentation](actions/edit_file.md) if you are
    62  curious):
    63  
    64  https://github.com/facebookincubator/TTPForge/blob/7634dc65879ec43a108a4b2d44d7eb2105a2a4b1/example-ttps/actions/edit-file/append-delete.yaml#L1-L35
    65  
    66  You must use `type: path` because when you execute `ttpforge run [ttp]`,
    67  **TTPForge changes its working directory to the folder containing the TTP.**
    68  This means that relative paths such as `foo/bar` won't retain their original
    69  meaning by default - however, when you declare your argument using `type: path`,
    70  TTPForge knows to expand its value to an absolute path prior to changing
    71  directories, ensuring that everything will work as intended.
    72  
    73  ## Predefined Choices for Argument Values
    74  
    75  Sometimes only certain specific values make sense for a given argument. TTPForge
    76  lets you restrict the allowed values for an argument using the `choices:`
    77  keyword, as shown below
    78  
    79  https://github.com/facebookincubator/TTPForge/blob/7634dc65879ec43a108a4b2d44d7eb2105a2a4b1/example-ttps/args/choices.yaml#L1-L29
    80  
    81  You can run the above TTP as follows:
    82  
    83  ```bash
    84  ttpforge run examples//args/choices.yaml \
    85    --arg arg_with_choices=C
    86  ```
    87  
    88  Notice the following key aspects of the `choices` feature:
    89  
    90  - TTPForge will reject your arguments if you specify an invalid choice such as
    91    `arg_with_choices=D`.
    92  - If you use `choices` and `default` together, the `default` value must be one
    93    of the valid choices.
    94  
    95  ## Validating Arguments with Regular Expressions
    96  
    97  In order to require user-provided argument values to match a particular regular
    98  expression (which is useful for ensuring that you don't get strange errors
    99  halfway through a TTP due to user error) you can use the `regexp:` syntax
   100  demonstrated below:
   101  
   102  https://github.com/facebookincubator/TTPForge/blob/7634dc65879ec43a108a4b2d44d7eb2105a2a4b1/example-ttps/args/regexp.yaml#L1-L20
   103  
   104  You can use any regular expression allowed by the Golang regular expression
   105  [syntax](https://pkg.go.dev/regexp), although if you use YAML metacharacters
   106  such as `:` you are advised to put quotes around your regexp to ensure that your
   107  TTP YAML remains valid.
   108  
   109  You can run the above TTP as follows:
   110  
   111  ```bash
   112  ttpforge run examples//args/regexp.yaml \
   113    --arg must_contain_ab=xabyabz \
   114    --arg must_start_with_1_end_with_7=1337
   115  ```