Crate shellexpand [−] [src]

Provides functions for performing shell-like expansions in strings.

In particular, the following expansions are supported:

tilde expansion, when ~ in the beginning of a string, like in "~/some/path", is expanded into the home directory of the current user;
environment expansion, when $A or ${B}, like in "~/$A/${B}something", are expanded into their values in some environment.

The source of external information for these expansions (home directory and environment variables) is called their context. The context is provided to these functions as a closure of the respective type.

This crate provides both customizable functions, which require their context to be provided explicitly, and wrapper functions which use std::env::home_dir() and std::env::var() for obtaining home directory and environment variables, respectively.

Also there is a "full" function which performs both tilde and environment expansion, but does it correctly: for example, if the string starts with a variable whose value starts with a ~, then this tilde won't be expanded.

All functions return Cow<str> because it is possible for their input not to contain anything which triggers the expansion. In that case performing allocations can be avoided.

Please note that by default unknown variables in environment expansion are left as they are and are not, for example, substituted with an empty string:

fn context(_: &str) -> Option<String> { None }

assert_eq!(
    shellexpand::env_with_context_no_errors("$A $B", context),
    "$A $B"
);

Environment expansion context allows for a very fine tweaking of how results should be handled, so it is up to the user to pass a context function which does the necessary thing. For example, env() and full() functions from this library pass all errors returned by std::env::var() through, therefore they will also return an error if some unknown environment variable is used, because std::env::var() returns an error in this case:

use std::env;

// make sure that the variable indeed does not exist
env::remove_var("MOST_LIKELY_NONEXISTING_VAR");

assert_eq!(
    shellexpand::env("$MOST_LIKELY_NONEXISTING_VAR"),
    Err(shellexpand::LookupError {
        name: "MOST_LIKELY_NONEXISTING_VAR".into(),
        cause: env::VarError::NotPresent
    })
);

The author thinks that this approach is more useful than just substituting an empty string (like, for example, does Go with its os.ExpandEnv function), but if you do need os.ExpandEnv-like behavior, it is fairly easy to get one:

use std::env;
use std::borrow::Cow;

fn context(s: &str) -> Result<Option<Cow<'static, str>>, env::VarError> {
    match env::var(s) {
        Ok(value) => Ok(Some(value.into())),
        Err(env::VarError::NotPresent) => Ok(Some("".into())),
        Err(e) => Err(e)
    }
}

// make sure that the variable indeed does not exist
env::remove_var("MOST_LIKELY_NONEXISTING_VAR");

assert_eq!(
    shellexpand::env_with_context("a${MOST_LIKELY_NOEXISTING_VAR}b", context).unwrap(),
    "ab"
);

The above example also demonstrates the flexibility of context function signatures: the context function may return anything which can be AsRefed into a string slice.

Structs

LookupError

Represents a variable lookup error.

Functions

env	Performs the environment expansion using the default system context.
env_with_context	Performs the environment expansion using the provided context.
env_with_context_no_errors	Same as `env_with_context()`, but forbids the variable lookup function to return errors.
full	Performs both tilde and environment expansions in the default system context.
full_with_context	Performs both tilde and environment expansion using the provided contexts.
full_with_context_no_errors	Same as `full_with_context()`, but forbids the variable lookup function to return errors.
tilde	Performs the tilde expansion using the default system context.
tilde_with_context	Performs the tilde expansion using the provided context.