|
| 1 | +# complate |
| 2 | + |
| 3 | +`complate` is a general purpose text templating CLI program that supports interactive mode, prompting the user for values via TUI behaviour and headless mode for use in automation such as CI pipelines. |
| 4 | + |
| 5 | +## Installation |
| 6 | + |
| 7 | +* The rusty way:\ |
| 8 | +`cargo install complate --force` |
| 9 | +* The manual way:\ |
| 10 | +Download and install from the GitHub releases |
| 11 | + |
| 12 | + |
| 13 | +## Usage |
| 14 | + |
| 15 | +* `complate render` |
| 16 | +* `complate render -c .complate/alternative.yml` |
| 17 | +* `complate -e render -c <(cat .complate/alternative.yaml) -bui -t0.default` |
| 18 | +* `complate -e render -t three --helpers` |
| 19 | + |
| 20 | +## Configuration |
| 21 | + |
| 22 | +An example: |
| 23 | + |
| 24 | +``` |
| 25 | +version: 0.11 |
| 26 | +templates: |
| 27 | + zero: |
| 28 | + content: |
| 29 | + inline: |- |
| 30 | + {{ a.alpha }} |
| 31 | + values: |
| 32 | + a.alpha: |
| 33 | + static: ALPHA |
| 34 | + one: |
| 35 | + content: |
| 36 | + file: ./.complate/templates/arbitraty-template-file.tpl |
| 37 | + values: |
| 38 | + a.pwd: |
| 39 | + env: "PWD" |
| 40 | + two: |
| 41 | + content: |
| 42 | + inline: |- |
| 43 | + {{ a.alpha }} |
| 44 | + {{ b.bravo }} |
| 45 | + {{ c.charlie }} |
| 46 | + {{ d.delta }} |
| 47 | + {{ e.echo }} |
| 48 | + values: |
| 49 | + a.alpha: |
| 50 | + prompt: "alpha" |
| 51 | + b.bravo: |
| 52 | + shell: "printf bravo" |
| 53 | + c.charlie: |
| 54 | + static: "charlie" |
| 55 | + d.delta: |
| 56 | + select: |
| 57 | + text: Select the version level that shall be incremented |
| 58 | + options: |
| 59 | + alpha: |
| 60 | + display: alpha |
| 61 | + value: |
| 62 | + static: alpha |
| 63 | + bravo: |
| 64 | + display: bravo |
| 65 | + value: |
| 66 | + shell: printf bravo |
| 67 | + e.echo: |
| 68 | + check: |
| 69 | + text: Select the components that are affected |
| 70 | + separator: ", " |
| 71 | + options: |
| 72 | + alpha: |
| 73 | + display: alpha |
| 74 | + value: |
| 75 | + static: alpha |
| 76 | + bravo: |
| 77 | + display: bravo |
| 78 | + value: |
| 79 | + shell: printf bravo |
| 80 | + f.foxtrot: |
| 81 | + env: "FOXTROT" |
| 82 | + three: |
| 83 | + content: |
| 84 | + inline: |- |
| 85 | + {{ _decode "dGVzdA==" }} |
| 86 | + helpers: |
| 87 | + "_decode": |
| 88 | + shell: |- |
| 89 | + printf "$(printf $VALUE | base64 -D)" |
| 90 | + values: {} |
| 91 | +
|
| 92 | +``` |
| 93 | + |
| 94 | +| Key | Behaviour | Input | |
| 95 | +| ------ | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | |
| 96 | +| env | Retrieves value from the specified env var | None | |
| 97 | +| static | Simply replaces the variable with a static value | None | |
| 98 | +| prompt | Asks the user for text input (can be empty) | The prompt | |
| 99 | +| shell | Invokes a shell command to resolve the variable (read from `STDOUT`) | None | |
| 100 | +| select | Asks the user to select one item from a list | `text`: string (context), `options`: list (available options to select from) | |
| 101 | +| check | Asks the user to select `0..n` item(s) from a list (multiselect) | `text`: string (context), `options`: list of options {display: str, value: str} (the available options to select from) | |
| 102 | + |
| 103 | +Since the `shell` value provider is able to run arbitrary shell commands, it is only allowed if and only if the `SHELL_TRUST` argument is explicitly set. See the `render` command reference for possible values for this setting. If *not* set, the provider will throw an unrecoverable error and the program will abort. |
| 104 | + |
| 105 | +## Command reference |
| 106 | + |
| 107 | +### Disclaimer |
| 108 | + |
| 109 | +All features that are marked as `experimental` are _not_ considered a public API and therefore eplicitly not covered by the backwards-compatibility policy inside a major version (see https://semver.org[semver v2]). Use these features on your own risk! |
| 110 | + |
| 111 | +### Application level arguments |
| 112 | + |
| 113 | +| Name | Short | Long | Description | |
| 114 | +| ------------ | ----- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 115 | +| Experimental | -e | --experimental | Activates experimental features that are not stable yet. All features that are marked as experimental are ignored when keeping backwards compatibility inside one major version. | |
| 116 | + |
| 117 | +### Commands |
| 118 | + |
| 119 | +| Command | Description | Status | |
| 120 | +| ------- | -------------------------------------------------------------------------------------- | ------ | |
| 121 | +| help | Prints the help to `STDOUT`. | stable | |
| 122 | +| init | Initializes the default configuration in `./.complate/config.yaml` | stable | |
| 123 | +| render | Prompts for the template, prompts for variable values and renders the data to `STDOUT` | stable | |
| 124 | + |
| 125 | +#### `render` command flags |
| 126 | + |
| 127 | +| Name | Short | Long | Description | Remark | Status | |
| 128 | +| ----------- | ----- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | |
| 129 | +| Config | -c | --config | The path to the configuration file that shall be used. This path can be relative or absolute. The default path is `./complate/config.yaml`. | When setting this argument to pipe (`-`), the config is parsed from the STDIN descriptor to the render command. | stable for file path, experimental for STDIN descriptor. Pipe is only supported for `UI` backend | |
| 130 | +| Shell trust | | --shell-trust | Enables the shell value provider for replacing template placeholders. Due to the potential security risk with this option, it is disabled by default. Possible values for this option are `none` (default) and `ultimate` | | stable | |
| 131 | +| Template | -t | --template | Skip the template selection by defining the used template from the configuration via this argument | | stable | |
| 132 | +| Backend | -b | --backend | Defines the backend for the user interaction. | | `CLI` is stable. `UI` is experimental (feature = "backend+ui"). | |
| 133 | +| Value | -v | --value | Overrides a certain variable with a given string value. Specify the variable and value with an equals sign as separator | Multiple allowed. Example: <br/> `-v"variable=some arbitrary value"` | experimental | |
| 134 | +| Helpers | | --helpers | Enables helper functions. | | experimental | |
| 135 | + |
| 136 | +## Features |
| 137 | + |
| 138 | +| Name | Description | Default | |
| 139 | +| ----------- | -------------------------------------------------------------------- | ------- | |
| 140 | +| backend+cli | The CLI backend which maps to the original dialoguer implementation. | Yes | |
| 141 | +| backend+ui | The UI backend which maps to the new cursive/fui implementation. | No | |
| 142 | + |
| 143 | +### `backend+` |
| 144 | + |
| 145 | +Either one of the `backend+` features (or both) MUST be enabled for `complate` to work (it won't compile otherwise). |
0 commit comments