pub struct Xpanda { /* private fields */ }
Expand description
Xpanda
substitutes the values of variables in strings similar to envsubst
and
Bash parameter expansion
.
Implementations
sourceimpl Xpanda
impl Xpanda
pub fn builder() -> Builder
sourcepub fn expand(&self, input: &str) -> Result<String, Error>
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")));