Crate subst

Shell-like variable substitution for strings and byte strings.

Features

• Perform substitution in &str or in &[u8].
• Provide a custom map of variables or use environment variables.
  • Support for indexmap (requires the indexmap feature).
• Short format: "Hello $name!"
• Long format: "Hello ${name}!"
• Default values: "Hello ${name:person}!"
• Recursive substitution in default values: "${XDG_CONFIG_HOME:$HOME/.config}/my-app/config.toml"
• Perform substitution on all string values in TOML, JSON or YAML data (optional, requires the toml, json or yaml feature).

Variable names can consist of alphanumeric characters and underscores. They are allowed to start with numbers.

If you want to quickly perform substitution on a string, use substitute() or substitute_bytes().

It is also possible to use one of the template types. The templates parse the source string or bytes once, and can be expanded as many times as you want. There are four different template types to choose from:

• Template: borrows the source string.
• TemplateBuf: owns the source string.
• ByteTemplate: borrows the source bytes.
• ByteTemplateBuf: owns the source bytes.

Examples

The substitute() function can be used to perform substitution on a &str. The variables can either be a HashMap or a BTreeMap.

let mut variables = HashMap::new();
variables.insert("name", "world");
assert_eq!(subst::substitute("Hello $name!", &variables)?, "Hello world!");

The variables can also be taken directly from the environment with the Env map.

assert_eq!(
  subst::substitute("$XDG_CONFIG_HOME/my-app/config.toml", &subst::Env)?,
  "/home/user/.config/my-app/config.toml",
);

Substitution can also be done on byte strings using the substitute_bytes() function.

let mut variables = HashMap::new();
variables.insert("name", b"world");
assert_eq!(subst::substitute_bytes(b"Hello $name!", &variables)?, b"Hello world!");

You can also parse a template once and expand it multiple times:

let template = subst::Template::from_str("Welcome to our hair salon, $name!")?;
for name in ["Scrappy", "Coco"] {
  let variables: HashMap<_, _> = [("name", name)].into_iter().collect();
  let message = template.expand(&variables)?;
  println!("{}", message);
}

Re-exports

pub use error::Error;

Modules

error

Module containing error details.

jsonjson

Support for variable substitution in JSON data.

tomltoml

Support for variable substitution in TOML data.

yamlyaml

Support for variable substitution in YAML data.

Structs

ByteTemplate

A parsed byte template that borrows the source slice.

ByteTemplateBuf

A parsed byte template that owns the source vector.

Env

A map that gives strings from the environment.

EnvBytes

A map that gives byte strings from the environment.

NoSubstitution

A “map” that never returns any values.

Template

A parsed string template that borrows the source string.

TemplateBuf

A parsed string template that owns the source string.

Enums

NeverValue

Value returned by the NoSubstitution map.

Traits

VariableMap

Trait for types that can be used as a variable map.

Functions

substitute

Substitute variables in a string.

substitute_bytes

Substitute variables in a byte string.