Conditionals - Cargo Generate Documentation
Description: cargo, make me a project

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# Conditional template settings

Using `cargo-generate.toml`, values and some [`Rhai`] syntax, the template author can make certain conditional decisions before expansion of the template.

`include`, `exclude`, `ignore` and `placeholders` can all be used in sections that are only used based upon the value of one or more values, possibly input by the user using the interactive prompt (if the values in question are defined as placeholders in the non-conditional section).

Using the following example, `cargo-generate` will ask for the `license`, and depending on the `--lib` | `--bin` flags it'll as for the `hypervisor` and `network_enabled` values. It will then continue to expand the template, ignoring the `src/main.rs` file (and thus excluding it from the output) in case `--lib` was specified.

The example is broken up in order to explain each section.

    [template]
    cargo_generate_version = ">=0.10.0"
    # ignore = [ "..." ]
    # include = [ "..." ]
    # exclude = [ "..." ]
    ...

This first part declares that the template requires `cargo-generate` version 0.10 or higher. In this same section the template author may also specify the following 3 lists:

- `ignore` Files/folders on this list will be ignored entirely and are not included in the final output.
- `include` These files will be processed for `Liquid` syntax by the template engine.
- `exclude` These files will not be processed for any `liquid` syntax. The files will be in the final output.

    ...
    [placeholders]
    license = { type = "string", prompt = "What license to use?", choices = ["MIT", "Unrestricted"], default = "MIT" }
    ...

This is the section for the default placeholders. These are variable definitions that `cargo-generate` knows about and will query for if they are not provided e.g. on the commandline (see [Default-values-for-placeholders]).

The section should contain at least all variables used for any conditions (unless it's an automatic variable such as `crate_type`). All variables that are not specific to a condition are recommended to go here as well.

Here we simply define a variable `license` for selecting the desired license type.

    ...
    [conditional.'crate_type == "lib"']
    ignore = [ "src/main.rs" ]
    # include = [ "..." ]
    # exclude = [ "..." ]
    ...

This is a conditional block.

Here it has been chosen that the `src/main.rs` file must be ignored when the `crate_type` variable is equal to the string `"lib"`.

    ...
    [conditional.'crate_type != "lib"'.placeholders]
    hypervisor = { type = "string", prompt = "What hypervisor to use?", choices = ["uhyve", "qemu"], default = "qemu" }
    network_enabled = { type = "bool", prompt = "Want to enable network?", default = true }
    ...

This block uses the same condition as the last, but it defines some extra placeholders - that is, is defines the variables `hypervisor` and `network_enabled`, so that `cargo-generate` may ask for their values.

> ⚠️ `cargo-generate` will ask for values using the placeholders defined in `[placeholders]` before evaluating the conditional sections.

> Placeholder values defined in conditional sections cannot be used to enable/disable further conditional sections, they can however still be used in the actual template!

    ...
    [conditional.'license == "MIT"']
    ignore = [ "LICENSE-UNRESTRICTED.txt" ]
    # include = [ "..." ]
    # exclude = [ "..." ]

    [conditional.'license == "Unrestricted"']
    ignore = [ "LICENSE-MIT.txt" ]
    # include = [ "..." ]
    # exclude = [ "..." ]

This last conditional block is simply to ignore the unneeded license files, based upon the users choice for the `license` variable.

> ⚠️ Note that `include` and `exclude` are still mutually exclusive even if they are in different, but included, conditional sections.