Struct Xpanda

pub struct Xpanda { /* private fields */ }

Xpanda substitutes the values of variables in strings similar to envsubst and Bash parameter expansion.

Implementations

impl Xpanda

pub fn builder() -> Builder

pub fn expand(&self, input: &str) -> Result<String, Error>

Expands the given text by substituting the values of the variables inside it.

Variables can appear in any of the following forms:

Pattern	Description
$VAR	substituted with the corresponding value for 'VAR' if set, otherwise "".
${VAR}	substituted with the corresponding value for 'VAR' if set, otherwise "".
${VAR-default}	substituted with the corresponding value for 'VAR' if set, otherwise "default".
${VAR:-default}	substituted with the corresponding value for 'VAR' if set and non-empty, otherwise "default".
${VAR+alternative}	substituted with "alternative" if the corresponding value for 'VAR' is set, otherwise "".
${VAR:+alternative}	substituted with "alternative" if the corresponding value for 'VAR' is set and non-empty, otherwise "".
${VAR?}	substituted with the corresponding value for 'VAR' if set, otherwise yields an error.
${VAR?error}	substituted with the corresponding value for 'VAR' if set, otherwise yields an error with the given message (in this case "error").
${VAR?error}	substituted with the corresponding value for 'VAR' if set and non-empty, otherwise yields an error with the given message (in this case "error").
${#VAR}	substituted with the length of the corresponding value for 'VAR' if set, otherwise "0".

VAR above is a named variable. Named variables can be provided using the builder:

use std::collections::HashMap;
use xpanda::Xpanda;

let named_vars = HashMap::new();
let xpanda = Xpanda::builder()
    .with_named_vars(named_vars)
    .build();

Positional variables are also supported and can be provided in the same way:

use xpanda::Xpanda;

let xpanda = Xpanda::builder()
    .with_positional_vars(Vec::new())
    .build();

Positional variables can be referenced using their index (starting at 1), for example, $1 references the first positional variable, $2 the second and so on. $0 is a space concatenated string of all positional variables.

Here are some examples and their output:

Pattern	VAR unset	VAR=""	VAR="example"
$VAR			"example"
${VAR}			"example"
${VAR-default}	"default"		"example"
${VAR:-default}	"default"	"default"	"example"
${VAR+alternative}		"alternative"	"alternative"
${VAR:+alternative}			"alternative"
${VAR?message}	error: "message"		"example"
${VAR:?message}	error: "message"	error: "message"	"example"
${#VAR}	"0"	"0"	"7"
${!VAR}			$example

Special rules take precedence when Builder::no_unset is true:

Pattern	VAR unset
$VAR	error
${VAR}	error
${#VAR}	error
${!VAR}	error

Default/Alternative values can also be variables:

Pattern	VAR unset	VAR=""	VAR="example"
`${VAR:-$DEF}`	`$DEF`		"example"
`${VAR+${ALT:-alternative}}`		`${ALT:-alternative}`	${ALT:-alternative}

The $ character is assumed to be the start of a variable. If the variable does not match any of the forms listed above, an error is returned. Variables can be escaped by prefixing them by an additional ‘$’, for example: $$VAR which yields $VAR and ${VAR-$$text} which yields $text if VAR is unset.

Errors

Returns Err if the given string is badly formatted and cannot be parsed.

Examples

use xpanda::Xpanda;

let xpanda = Xpanda::default();
assert_eq!(xpanda.expand("${1:-default}"), Ok(String::from("default")));

Trait Implementations

impl Default for Xpanda

fn default() -> Xpanda

Returns the “default value” for a type.