complate

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.

Installation

The rusty way:
cargo install complate --force
The manual way:
Download and install from the GitHub releases

Configuration

An example:

version: 0.12
templates:
  zero:
    content:
      inline: |-
        {{ a.alpha }}
    values:
      a.alpha:
        static: ALPHA
  one:
    content:
      file: ./.complate/templates/arbitraty-template-file.tpl
    values:
      a.pwd:
        env: "PWD"
  two:
    content:
      inline: |-
        {{ a.alpha }}
        {{ b.bravo }}
        {{ c.charlie }}
        {{ d.delta }}
        {{ e.echo }}
    values:
      a.alpha:
        prompt: "alpha"
      b.bravo:
        shell: "printf bravo"
      c.charlie:
        static: "charlie"
      d.delta:
        select:
          text: Select the version level that shall be incremented
          options:
            alpha:
              display: alpha
              value:
                static: alpha
            bravo:
              display: bravo
              value:
                shell: printf bravo
      e.echo:
        check:
          text: Select the components that are affected
          separator: ", "
          options:
            alpha:
              display: alpha
              value:
                static: alpha
            bravo:
              display: bravo
              value:
                shell: printf bravo
      f.foxtrot:
        env: "FOXTROT"
  three:
    content:
      inline: |-
        {{ _decode "dGVzdA==" }}
    helpers:
      "_decode":
        shell: |-
          printf "$(printf $VALUE | base64 -D)"
    values: {}

Key	Behaviour	Input
env	Retrieves value from the specified env var	None
static	Simply replaces the variable with a static value	None
prompt	Asks the user for text input (can be empty)	The prompt
shell	Invokes a shell command to resolve the variable (read from `STDOUT`)	None
select	Asks the user to select one item from a list	`text`: string (context), `options`: list (available options to select from)
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)

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.

Command reference

Disclaimer

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!

Command-Line Help for `complate`

This document contains the help content for the complate command-line program.

Command Overview:

`complate`

A rusty text templating application for CLIs.

Usage: complate [OPTIONS] <COMMAND>

Subcommands:

man — Renders the manual.
autocomplete — Renders shell completion scripts.
init — Initializes a dummy default configuration in "./.complate/config.yaml".
render — Renders a template by replacing values as specified by the configuration.

Options:

-e, --experimental <EXPERIMENTAL> — enables experimental features

`complate man`

Renders the manual.

Usage: complate man --out <out> --format <format>

Options:

-o, --out <OUT>
-f, --format <FORMAT>

Possible values: manpages, markdown

`complate autocomplete`

Renders shell completion scripts.

Usage: complate autocomplete --out <out> --shell <shell>

Options:

-o, --out <OUT>
-s, --shell <SHELL>

Possible values: bash, zsh, fish, elvish, powershell

`complate init`

Initializes a dummy default configuration in "./.complate/config.yaml".

Usage: complate init

`complate render`

Renders a template by replacing values as specified by the configuration.

Usage: complate render [OPTIONS]

Options:

-c, --config <CONFIG> — The configuration file to use.

Default value: ./.complate/config.yaml
-t, --template <TEMPLATE> — Specify the template to use from the config and skip it's selection.
--trust — Enables the shell command execution. This is potentially insecure and should only be done for trustworthy sources.
-l, --loose — Defines that the templating is done in non-strict mode (allow missing value for variable).
-b, --backend <BACKEND> — The execution backend (cli=native-terminal, ui=ui emulator in terminal).

Default value: headless

Possible values: headless, cli
-v, --value <VALUE> — Overrides a certain value definition with a string.

This document was generated automatically by clap-markdown.

Adrs

1: Usage of ADRs

This project uses ADRs. ADRs are documented in this repository and format. In doubt, the documents in this repository and documentation are to be considered as the single source of truth.

2: Usage of keywords

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document and in all documents in it's subtree as well as all documents that are directly related to this document are to be interpreted as described in https://tools.ietf.org/html/bcp14[BCP 14], https://tools.ietf.org/html/rfc2119[RFC2119] and https://tools.ietf.org/html/rfc8174[RFC8174] when, and only when, they appear in all capitals, as shown here.

3: Versioning

This project makes use of https://semver.org[the semver v2 versioning scheme] for all parts of the official public API. The public stable API is a subset of all available features (see link:/complate/docs/adrs/4-experimental-flag[this page]).

4: Experimental flag

There is a application level argument (flag) experimental (-e | --experimental) that indicates that experimental features can now be accessed. This flag explicitly marks features that are NOT part of the official public API and therefore NOT considered when applying the versioning scheme (see link:/complate/docs/adrs/3-versioning[ADR 3]). + This flag is designed to be used with and therefore CAN be used with link:/complate/docs/adrs/5-feature-flags[feature Flags as specified in ADR 5].

5: Feature flags

This project makes use of cargo feature flags. Feature flags count as part of the public API and are therefore to be considered when applying the version rules IF NOT marked as experimental (see link:/complate/docs/adrs/4-experimental-flag[ADR 4]). + All feature flags MUST be documented in an appropriate manner in the documentation.