Shellexpand

https://docs.rs/shellexpand/3.1.2
Admin
Shellexpand is a Rust library that provides functions for performing shell-like expansions in...
Tokens:22,014
Snippets:162
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Environment Expansion Examples

Source: https://docs.rs/shellexpand/3.1.2/src/shellexpand/funcs.rs.html

Demonstrates how to use env_with_context to expand variables, handle defaults, ignore unknown variables, and propagate errors.

```rust
fn context(s: &str) -> Result<Option<&'static str>, &'static str> {
    match s {
        "A" => Ok(Some("a value")),
        "B" => Ok(Some("b value")),
        "E" => Err("something went wrong"),
        _ => Ok(None)
    }
}

// Regular variables are expanded
assert_eq!(
    shellexpand::env_with_context("begin/$A/${B}s/end", context).unwrap(),
    "begin/a value/b values/end"
);

// Expand to a default value if the variable is not defined
assert_eq!(
    shellexpand::env_with_context("begin/${UNSET_ENV:-42}/end", context).unwrap(),
    "begin/42/end"
);

// Unknown variables are left as is
assert_eq!(
    shellexpand::env_with_context("begin/$UNKNOWN/end", context).unwrap(),
    "begin/$UNKNOWN/end"
);

// Errors are propagated
assert_eq!(
    shellexpand::env_with_context("begin${E}end", context),
    Err(shellexpand::LookupError {
        var_name: "E".into(),
        cause: "something went wrong"
    })
);
```

--------------------------------

### Using full_with_context for expansion

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/fn.full_with_context.html

Examples demonstrating tilde and environment variable expansion, error propagation, and allocation avoidance.

```rust
use std::path::{PathBuf, Path};
use std::borrow::Cow;

fn home_dir() -> Option<String> { Some("/home/user".into()) }

fn get_env(name: &str) -> Result<Option<&'static str>, &'static str> {
    match name {
        "A" => Ok(Some("a value")),
        "B" => Ok(Some("b value")),
        "T" => Ok(Some("~")),
        "E" => Err("some error"),
        _ => Ok(None)
    }
}

// Performs both tilde and environment expansions
assert_eq!(
    shellexpand::full_with_context("~/$A/$B", home_dir, get_env).unwrap(),
    "/home/user/a value/b value"
);

// Errors from environment expansion are propagated to the result
assert_eq!(
    shellexpand::full_with_context("~/$E/something", home_dir, get_env),
    Err(shellexpand::LookupError {
        var_name: "E".into(),
        cause: "some error"
    })
);

// Input without starting tilde and without variables does not cause allocations
let s = shellexpand::full_with_context("some/path", home_dir, get_env);
match s {
    Ok(Cow::Borrowed(s)) => assert_eq!(s, "some/path"),
    _ => unreachable!("the above variant is always valid")
}

// Input with a tilde inside a variable in the beginning of the string does not cause tilde
// expansion
assert_eq!(
    shellexpand::full_with_context("$T/$A/$B", home_dir, get_env).unwrap(),
    "~/a value/b value"
);
```

--------------------------------

### Usage examples for full_with_context_no_errors

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/fn.full_with_context_no_errors.html

Demonstrates performing tilde and environment expansions, handling borrowed strings, and managing tilde expansion behavior within variables.

```rust
use std::path::{PathBuf, Path};
use std::borrow::Cow;

fn home_dir() -> Option<String> { Some("/home/user".into()) }

fn get_env(name: &str) -> Option<&'static str> {
    match name {
        "A" => Some("a value"),
        "B" => Some("b value"),
        "T" => Some("~"),
        _ => None
    }
}

// Performs both tilde and environment expansions
assert_eq!(
    shellexpand::full_with_context_no_errors("~/$A/$B", home_dir, get_env),
    "/home/user/a value/b value"
);

// Input without starting tilde and without variables does not cause allocations
let s = shellexpand::full_with_context_no_errors("some/path", home_dir, get_env);
match s {
    Cow::Borrowed(s) => assert_eq!(s, "some/path"),
    _ => unreachable!("the above variant is always valid")
}

// Input with a tilde inside a variable in the beginning of the string does not cause tilde
// expansion
assert_eq!(
    shellexpand::full_with_context_no_errors("$T/$A/$B", home_dir, get_env),
    "~/a value/b value"
);
```

--------------------------------

### Example of tilde_with_context Usage

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/fn.tilde_with_context.html

Demonstrates how to use `tilde_with_context` to expand a tilde path using a custom home directory provider. Ensure the home directory provider returns a `String` or a type that can be converted to `&str`.

```rust
use std::path::{PathBuf, Path};

fn home_dir() -> Option<String> { Some("/home/user".into()) }

assert_eq!(
   shellexpand::tilde_with_context("~/some/dir", home_dir),
   "/home/user/some/dir"
);
```

--------------------------------

### tilde_with_context

Source: https://docs.rs/shellexpand/3.1.2/src/shellexpand/funcs.rs.html

Performs the tilde expansion using the provided context function to get the home directory.

```APIDOC
## tilde_with_context

### Description
Performs the tilde expansion using the provided context function to get the home directory. If the input string does not contain a tilde at the beginning, or if it is not followed by a slash or the end of the string, it is left as is. Expansions like `~anotheruser/directory` are not supported.

### Method
`pub fn tilde_with_context<SI: ?Sized, CO, C>(input: &SI, home_dir: C) -> Cow<'_, Xstr>`

### Endpoint
N/A (Function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
fn get_home() -> Option<&'static str> {
    Some("/home/user")
}

assert_eq!(shellexpand::tilde_with_context("~/Documents", get_home), "/home/user/Documents");
assert_eq!(shellexpand::tilde_with_context("Documents", get_home), "Documents");
```

### Response
#### Success Response (200)
`Cow<'_, Xstr>`: The string with tilde expanded.

#### Response Example
```json
{
  "example": "/home/user/Documents"
}
```
```

--------------------------------

### Custom Context Function Example

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/fn.env_with_context.html

Defines a sample context function for `env_with_context`. This function maps specific variable names to values or errors, and returns `Ok(None)` for undefined variables.

```rust
fn context(s: &str) -> Result<Option<&'static str>, &'static str> {
    match s {
        "A" => Ok(Some("a value")),
        "B" => Ok(Some("b value")),
        "E" => Err("something went wrong"),
        _ => Ok(None)
    }
}

```

--------------------------------

### CharsExt: Get Approximate Character Length

Source: https://docs.rs/shellexpand/3.1.2/src/shellexpand/wtraits.rs.html

Provides a method to get the length of the character iterator from `Wstr.chars_approx()`. This length is suitable for slicing calculations.

```rust
pub(crate) trait CharsExt {
    fn wstr_len(&self) -> usize;
}
```

--------------------------------

### Full Expansion

Source: https://docs.rs/shellexpand/3.1.2/index.html

Performs both tilde and environment expansions, handling interactions between them correctly.

```APIDOC
## Full Expansion API

### Description
Performs both tilde and environment expansions in the default system context.

### Method
GET (conceptual)

### Endpoint
N/A (function within the crate)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use std::env;

env::set_var("MY_DIR", "/tmp");

let expanded_string = shellexpand::full("~/user/$MY_DIR/file.txt");
```

### Response
#### Success Response (Cow<str>)
- **expanded_string** (Cow<str>) - The string with both tilde and environment variables expanded.

#### Response Example
```json
{
  "expanded_string": "/home/user/tmp/file.txt"
}
```
```

```APIDOC
## Full Expansion with Custom Context API

### Description
Performs both tilde and environment expansion using provided contexts.

### Method
GET (conceptual)

### Endpoint
N/A (function within the crate)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use shellexpand;
use std::borrow::Cow;
use std::env;

fn custom_home_dir(_: &str) -> Option<Cow<'static, str>> {
    Some(Cow::from("/custom/home"))
}

fn custom_env_context(var_name: &str) -> Result<Option<Cow<'static, str>>, env::VarError> {
    match var_name {
        "CUSTOM_VAR" => Ok(Some(Cow::from("custom_value"))),
        _ => Ok(None)
    }
}

let expanded_string = shellexpand::full_with_context("~/user/$CUSTOM_VAR", custom_home_dir, custom_env_context);
```

### Response
#### Success Response (Result<Cow<str>, LookupError>)
- **expanded_string** (Result<Cow<str>, LookupError>) - The string with both expansions performed using custom contexts.

#### Response Example
```json
{
  "expanded_string": "/custom/home/user/custom_value"
}
```
```

```APIDOC
## Full Expansion with No Errors API

### Description
Performs both tilde and environment expansion, similar to `full_with_context`, but the variable lookup function is forbidden from returning errors. Unknown variables are left as is.

### Method
GET (conceptual)

### Endpoint
N/A (function within the crate)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use shellexpand;
use std::env;

// Ensure the variable does not exist to test the 'no errors' behavior
env::remove_var("NONEXISTENT_VAR");

let expanded_string = shellexpand::full_with_context_no_errors("~/user/$NONEXISTENT_VAR", |s| Some(Cow::from(s)), |s| Ok(std::env::var(s).ok().map(Cow::from)));
```

### Response
#### Success Response (Cow<str>)
- **expanded_string** (Cow<str>) - The string with both expansions performed. Unknown variables are not replaced.

#### Response Example
```json
{
  "expanded_string": "/home/user/$NONEXISTENT_VAR"
}
```
```

--------------------------------

### Function: full

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/fn.full.html

Performs both tilde and environment expansions in the default system context using dirs::home_dir() and std::env::var().

```APIDOC
## Function: full

### Description
Performs both tilde and environment expansions in the default system context. This function delegates to `full_with_context()`, using the default system sources for both home directory and environment. Note that variable lookup of unknown variables will fail with an error.

### Signature
`pub fn full<SI>(input: &SI) -> Result<Cow<'_, str>, LookupError<VarError>> where SI: AsRef<str> + ?Sized`

### Parameters
- **input** (&SI) - Required - The input string to expand, which may contain tilde (~) or environment variables (e.g., $VAR or ${VAR}).

### Response
- **Result<Cow<'_, str>, LookupError<VarError>>** - Returns the expanded string on success, or a `LookupError` if an environment variable is not found.

### Example
```rust
use std::env;

env::set_var("A", "a value");
env::set_var("B", "b value");

let home_dir = dirs::home_dir()
    .map(|p| p.display().to_string())
    .unwrap_or_else(|| "~".to_owned());

// Performs both tilde and environment expansions
assert_eq!(
    shellexpand::full("~/$A/${B}s").unwrap(),
    format!("{}/a value/b values", home_dir)
);
```
```

--------------------------------

### full_with_context

Source: https://docs.rs/shellexpand/3.1.2/src/shellexpand/funcs.rs.html

Performs both tilde and environment expansion using the provided contexts. It handles ownership carefully to avoid unnecessary allocations and correctly manages cases where environment variables might contain tildes.

```APIDOC
## POST /api/users

### Description
This endpoint allows for the creation of new user accounts.

### Method
POST

### Endpoint
/api/users

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **username** (string) - Required - The desired username for the new account.
- **email** (string) - Required - The email address for the new account.
- **password** (string) - Required - The password for the new account.

### Request Example
```json
{
  "username": "johndoe",
  "email": "john.doe@example.com",
  "password": "securepassword123"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier for the newly created user.
- **username** (string) - The username of the created user.
- **email** (string) - The email address of the created user.

#### Response Example
```json
{
  "id": "user-12345",
  "username": "johndoe",
  "email": "john.doe@example.com"
}
```
```

--------------------------------

### env

Source: https://docs.rs/shellexpand/3.1.2/src/shellexpand/funcs.rs.html

Performs the environment expansion using the default system context (std::env::var). Unknown variables result in an error.

```APIDOC
## env

### Description
Performs the environment expansion using the default system context (std::env::var). Unknown variables result in an error.

### Method
`pub fn env<SI: ?Sized>(input: &SI) -> Result<Cow<'_, Xstr>, LookupError<VarError>>`

### Endpoint
N/A (Function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use std::env;

// make sure that some environment variables are set
env::set_var("X", "x value");
env::set_var("Y", "y value");

// Known variables are expanded
assert_eq!(
    shellexpand::env("begin/$X/${Y}s/end").unwrap(),
    "begin/x value/y values/end"
);

// Unknown variables result in an error
assert_eq!(
    shellexpand::env("begin/$Z/end"),
    Err(shellexpand::LookupError {
        var_name: "Z".into(),
        cause: env::VarError::NotPresent
    })
);
```

### Response
#### Success Response (200)
`Result<Cow<'_, Xstr>, LookupError<VarError>>`: Ok with the expanded string on success, Err with a LookupError on failure.

#### Response Example
```json
{
  "example": "begin/x value/y values/end"
}
```
```

--------------------------------

### Tilde Expansion with Default System Context

Source: https://docs.rs/shellexpand/3.1.2/src/shellexpand/funcs.rs.html

Performs tilde expansion using the default system context for the home directory. This function is a convenience wrapper around `tilde_with_context`, utilizing the `dirs::home_dir()` function to resolve the user's home directory.

```APIDOC
## POST /tilde

### Description
Performs tilde expansion using the default system context for the home directory.

### Method
POST

### Endpoint
/tilde

### Parameters
#### Query Parameters
- **input** (string) - Required - The input string potentially starting with a tilde.

### Request Body
```json
{
  "input": "~/some/dir"
}
```

### Response
#### Success Response (200)
- **expanded_string** (string) - The string with the tilde expanded using the system's home directory.

#### Response Example
```json
{
  "expanded_string": "/home/user/some/dir"
}
```
```

--------------------------------

### Full Expansion Functions

Source: https://docs.rs/shellexpand/3.1.2/shellexpand

Functions that perform both tilde and environment expansion in a single pass.

```APIDOC
## full(value: &str)

### Description
Performs both tilde and environment expansions using default system contexts.

### Parameters
- **value** (str) - Required - The string to expand.

### Response
- **Result<Cow<str>, LookupError>** - The fully expanded string.
```

--------------------------------

### Implement Go-like os.ExpandEnv behavior

Source: https://docs.rs/shellexpand/3.1.2/src/shellexpand/lib.rs.html

Provides a custom context function that substitutes missing environment variables with an empty string instead of returning an error.

```rust
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"
);
```

--------------------------------

### Function: full_with_context_no_errors

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/fn.full_with_context_no_errors.html

Performs full shell-like expansion on an input string using a provided home directory function and a context lookup function for environment variables.

```APIDOC
## Function: full_with_context_no_errors

### Description
Performs full shell-like expansion (tilde and environment variables) on the input string. This variant forbids the variable lookup function from returning errors, returning a Cow<str> directly.

### Parameters
- **input** (&SI) - Required - The input string to expand.
- **home_dir** (HD) - Required - A function that returns the home directory path.
- **context** (C) - Required - A function that maps environment variable names to their values.

### Request Example
```rust
use std::borrow::Cow;
fn home_dir() -> Option<String> { Some("/home/user".into()) }
fn get_env(name: &str) -> Option<&'static str> { Some("value") }

shellexpand::full_with_context_no_errors("~/$VAR", home_dir, get_env);
```

### Response
- **Return Value** (Cow<'_, str>) - The expanded string, either borrowed from the input or owned if expansion occurred.
```

--------------------------------

### Tilde Expansion

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/index.html

Performs tilde expansion (`~`) at the beginning of a string, expanding it to the current user's home directory.

```APIDOC
## Tilde Expansion API

### Description
Performs the tilde expansion using the default system context.

### Method
GET (conceptual, as this is a function call)

### Endpoint
N/A (function within a library)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use shellexpand;

let expanded_path = shellexpand::tilde("~/some/path");
```

### Response
#### Success Response (Cow<str>)
- **expanded_path** (Cow<str>) - The string with tilde expanded.

#### Response Example
```
"/home/user/some/path"
```
```

```APIDOC
## Tilde Expansion with Custom Context API

### Description
Performs the tilde expansion using a provided context.

### Method
GET (conceptual)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use shellexpand;

fn custom_home_dir() -> Option<String> {
    Some("/custom/home".to_string())
}

let expanded_path = shellexpand::tilde_with_context("~/some/path", custom_home_dir);
```

### Response
#### Success Response (Cow<str>)
- **expanded_path** (Cow<str>) - The string with tilde expanded using the custom context.

#### Response Example
```
"/custom/home/some/path"
```
```

--------------------------------

### Handle unknown environment variables with custom context

Source: https://docs.rs/shellexpand/3.1.2/src/shellexpand/lib.rs.html

Demonstrates using a custom context function to leave unknown variables unchanged during expansion.

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

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

--------------------------------

### full_with_context_no_errors

Source: https://docs.rs/shellexpand/3.1.2/src/shellexpand/funcs.rs.html

Expands environment variables and tildes using a provided context lookup function that returns Option<CO> instead of Result<Option<CO>, E>. This function returns Cow<str> directly, without a Result.

```APIDOC
## POST /api/users

### Description
This endpoint allows for the creation of new user resources.

### Method
POST

### Endpoint
/api/users

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **username** (string) - Required - The desired username for the new user.
- **email** (string) - Required - The email address of the new user.
- **password** (string) - Required - The password for the new user.

### Request Example
```json
{
  "username": "johndoe",
  "email": "john.doe@example.com",
  "password": "securepassword123"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier for the newly created user.
- **username** (string) - The username of the created user.
- **email** (string) - The email address of the created user.

#### Response Example
```json
{
  "id": "user-12345",
  "username": "johndoe",
  "email": "john.doe@example.com"
}
```
```

--------------------------------

### Tilde Expansion

Source: https://docs.rs/shellexpand/3.1.2/index.html

Performs tilde expansion, expanding '~' at the beginning of a string to the current user's home directory.

```APIDOC
## Tilde Expansion API

### Description
Performs the tilde expansion using the default system context.

### Method
GET (conceptual, as this is a function call)

### Endpoint
N/A (function within the crate)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use shellexpand;

let expanded_path = shellexpand::tilde("~/some/path");
```

### Response
#### Success Response (Cow<str>)
- **expanded_path** (Cow<str>) - The string with tilde expanded.

#### Response Example
```json
{
  "expanded_path": "/home/user/some/path"
}
```
```

```APIDOC
## Tilde Expansion with Custom Context API

### Description
Performs the tilde expansion using a provided context.

### Method
GET (conceptual)

### Endpoint
N/A (function within the crate)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use shellexpand;
use std::borrow::Cow;

fn custom_home_dir(_: &str) -> Option<Cow<'static, str>> {
    Some(Cow::from("/custom/home"))
}

let expanded_path = shellexpand::tilde_with_context("~/some/path", custom_home_dir);
```

### Response
#### Success Response (Cow<str>)
- **expanded_path** (Cow<str>) - The string with tilde expanded using the custom context.

#### Response Example
```json
{
  "expanded_path": "/custom/home/some/path"
}
```
```

--------------------------------

### Function tilde_with_context

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/fn.tilde_with_context.html

Performs tilde expansion using a provided context function to determine the home directory. It handles cases where the tilde is at the beginning of the string and followed by a slash or the end of the string. If the context function returns None, no expansion occurs.

```APIDOC
## Function tilde_with_context

### Description
Performs the tilde expansion using the provided context. This function expands the tilde (`~`) character at the beginning of the input string into the contents of the path returned by the `home_dir` function. If the input string does not contain a tilde, or if it is not followed by a slash (`/`) or the end of the string, it is left as is. Expansions like `~anotheruser/directory` are not supported. The context function may also return `None`, in which case the tilde won't be replaced.

### Signature
```rust
pub fn tilde_with_context<SI, P, HD>(input: &SI, home_dir: HD) -> Cow<'_, str>
where
    SI: AsRef<str> + ?Sized,
    P: AsRef<str>,
    HD: FnOnce() -> Option<P>,
```

### Parameters

- `input` (SI): The input string slice to perform tilde expansion on. Must implement `AsRef<str>`.
- `home_dir` (HD): A closure that returns an `Option<P>`, where `P` is a type that can be referenced as a string slice (`AsRef<str>`). This closure provides the home directory path.

### Return Value

- `Cow<'_, str>`: A `Cow` (Clone-on-Write) string slice containing the result of the tilde expansion. It will be borrowed if no expansion occurred, or owned if an expansion took place.

### Examples

```rust
use std::path::{PathBuf, Path};

fn home_dir() -> Option<String> { Some("/home/user".into()) }

assert_eq!(
   shellexpand::tilde_with_context("~/some/dir", home_dir),
   "/home/user/some/dir"
);

fn no_home_dir() -> Option<String> { None }

assert_eq!(
   shellexpand::tilde_with_context("~/some/dir", no_home_dir),
   "~/some/dir"
);

assert_eq!(
   shellexpand::tilde_with_context("no_tilde", home_dir),
   "no_tilde"
);
```
```

--------------------------------

### Function tilde

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/fn.tilde.html

Performs the tilde expansion using the default system context. This function delegates to `tilde_with_context()`, using the default system source of home directory path, namely `dirs::home_dir()` function.

```APIDOC
## Function tilde

### Description
Performs the tilde expansion using the default system context. This function delegates to `tilde_with_context()`, using the default system source of home directory path, namely `dirs::home_dir()` function.

### Signature
```rust
pub fn tilde<SI>(input: &SI) -> Cow<'_, str>
where
    SI: AsRef<str> + ?Sized,
```

### Examples
```rust
let hds = dirs::home_dir()
    .map(|p| p.display().to_string())
    .unwrap_or_else(|| "~".to_owned());

assert_eq!(
    shellexpand::tilde("~/some/dir"),
    format!("{}/some/dir", hds)
);
```
```

--------------------------------

### Expand tilde and environment variables

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/fn.full.html

Use `shellexpand::full` to expand tilde and environment variables. Ensure necessary environment variables are set before calling. Unknown variables will result in a `LookupError`.

```rust
use std::env;

env::set_var("A", "a value");
env::set_var("B", "b value");

let home_dir = dirs::home_dir()
    .map(|p| p.display().to_string())
    .unwrap_or_else(|| "~".to_owned());

// Performs both tilde and environment expansions using the system contexts
assert_eq!(
    shellexpand::full("~/$A/${B}s").unwrap(),
    format!("{}/a value/b values", home_dir)
);

// Unknown variables cause expansion errors
assert_eq!(
    shellexpand::full("~/$UNKNOWN/$B"),
    Err(shellexpand::LookupError {
        var_name: "UNKNOWN".into(),
        cause: env::VarError::NotPresent
    })
);
```

--------------------------------

### Function: full_with_context

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/fn.full_with_context.html

Performs both tilde and environment expansion using the provided contexts. It is designed to minimize allocations by returning a Cow<str> and handles edge cases where variables might contain tilde characters.

```APIDOC
## Function: full_with_context

### Description
Performs both tilde and environment expansion using the provided contexts. It tracks ownership to avoid unnecessary allocations and prevents incorrect tilde expansion when variables contain tilde characters.

### Parameters
- **input** (&SI) - Required - The input string to expand.
- **home_dir** (HD) - Required - A function that returns the home directory path.
- **context** (C) - Required - A function that resolves environment variable names to their values.

### Response
- **Result<Cow<'_, str>, LookupError<E>>** - Returns the expanded string as a Cow or a LookupError if the environment lookup fails.
```

--------------------------------

### Tilde Expansion with Custom Context

Source: https://docs.rs/shellexpand/3.1.2/src/shellexpand/funcs.rs.html

Expands the tilde character (~) at the beginning of a string to a provided home directory context. This function allows for custom logic to determine the home directory, which is useful for testing or environments where the default home directory is not applicable.

```APIDOC
## POST /tilde_with_context

### Description
Expands the tilde character (~) at the beginning of a string to a provided home directory context.

### Method
POST

### Endpoint
/tilde_with_context

### Parameters
#### Query Parameters
- **input** (string) - Required - The input string potentially starting with a tilde.
- **home_dir_context** (function) - Required - A function that returns an Option<String> representing the home directory.

### Request Body
```json
{
  "input": "~/some/dir",
  "home_dir_context": "() -> Option<String> { Some(\"/home/user\".to_string()) }"
}
```

### Response
#### Success Response (200)
- **expanded_string** (string) - The string with the tilde expanded.

#### Response Example
```json
{
  "expanded_string": "/home/user/some/dir"
}
```
```

--------------------------------

### Handle Unknown Environment Variables with Custom Context

Source: https://docs.rs/shellexpand/3.1.2/shellexpand

Demonstrates how to use `env_with_context_no_errors` to ensure that unknown environment variables are left as they are, rather than causing errors. This is useful when you want to process strings without failing due to missing variables.

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

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

--------------------------------

### Function: env_with_context_no_errors

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/fn.env_with_context_no_errors.html

Performs environment expansion on a string using a context lookup function that is guaranteed not to fail.

```APIDOC
## Function: env_with_context_no_errors

### Description
Performs environment variable expansion on the input string. It uses a provided context function to resolve variables. Unlike `env_with_context`, this function requires a context function that returns `Option<CO>` instead of a `Result`, simplifying usage when lookups cannot fail.

### Signature
`pub fn env_with_context_no_errors<SI, CO, C>(input: &SI, context: C) -> Cow<'_, str>`

### Parameters
- **input** (&SI) - The input string to expand.
- **context** (C) - A closure or function `FnMut(&str) -> Option<CO>` used to resolve variable names.

### Returns
- **Cow<'_, str>** - The expanded string. If a variable is not found (context returns `None`), the variable reference remains unexpanded in the output.

### Example
```rust
fn context(s: &str) -> Option<&'static str> {
    match s {
        "A" => Some("a value"),
        "B" => Some("b value"),
        _ => None
    }
}

// Known variables are expanded
assert_eq!(
    shellexpand::env_with_context_no_errors("begin/$A/${B}s/end", context),
    "begin/a value/b values/end"
);

// Unknown variables are left as is
assert_eq!(
    shellexpand::env_with_context_no_errors("begin/$U/end", context),
    "begin/$U/end"
);
```
```

--------------------------------

### shellexpand/strings.rs - Core Type Definitions and Implementations

Source: https://docs.rs/shellexpand/3.1.2/src/shellexpand/strings.rs.html

This snippet details the type aliases and trait implementations for string handling within the shellexpand crate. It includes definitions for Xstr, WInput, Wstr, and OString, along with implementations of extension traits like XstrRequirements, AsRefXstrExt, WstrExt, WstrRefExt, CharsExt, OStringExt, and PathBufExt.

```APIDOC
## Type Aliases and Extension Traits

### Description
This section details the type aliases and trait implementations for string handling within the shellexpand crate. It includes definitions for `Xstr`, `WInput`, `Wstr`, and `OString`, along with implementations of extension traits like `XstrRequirements`, `AsRefXstrExt`, `WstrExt`, `WstrRefExt`, `CharsExt`, `OStringExt`, and `PathBufExt`.

### Type Aliases

- **Xstr**: Alias for `str`.
- **WInput<'x>**: Alias for `&'x str`, representing a string slice input.
- **Wstr**: Alias for `str`.
- **OString**: Alias for `String`.

### Trait Implementations

- **`impl XstrRequirements for str`**: Implements requirements for `Xstr`.
- **`impl<S: AsRef<str> + ?Sized> AsRefXstrExt for S`**: Provides methods to convert string types into `WInput` and `Cow<'_, str>`.
  - `into_winput(&self) -> &str`: Converts the string slice to `&str`.
  - `into_ocow(&self) -> Cow<'_, str>`: Converts the string slice to `Cow<'_, str>`.
- **`impl WstrExt for str`**: Provides methods for `Wstr` (string slices).
  - `wstr_as_str(&self) -> Option<&str>`: Returns the string slice itself.
  - `wstr_len(&self) -> usize`: Returns the length of the string slice.
  - `wstr_to_ostring(&self) -> String`: Converts the string slice to an owned `String`.
  - `wstr_strip_prefix(&self, c: char) -> Option<&Self>`: Strips a prefix character from the string slice.
- **`impl<'s> WstrRefExt for &'s str`**: Provides methods for string slice references.
  - `wstr_chars_approx(self) -> Chars<'s>`: Returns an iterator over the characters of the string slice.
- **`impl CharsExt for Chars<'_>`**: Provides methods for character iterators.
  - `wstr_len(&self) -> usize`: Returns the length of the string slice represented by the character iterator.
- **`impl OStringExt for String`**: Provides methods for owned `String` types.
  - `push_str(&mut self, x: &str)`: Appends a string slice to the `String`.
  - `push_wstr(&mut self, x: &str)`: Appends a string slice to the `String`.
  - `push_xstr(&mut self, x: &str)`: Appends a string slice to the `String`.
  - `into_ocow(self) -> Cow<'static, str>`: Converts the `String` to `Cow<'static, str>`.
  - `display_possibly_lossy(&self, f: &mut fmt::Formatter) -> fmt::Result`: Formats the `String` for display.
- **`impl PathBufExt for PathBuf`**: Provides methods for `PathBuf`.
  - `try_into_xstring(self) -> Option<String>`: Attempts to convert a `PathBuf` into an owned `String`.
```

--------------------------------

### Tilde Expansion Functions

Source: https://docs.rs/shellexpand/3.1.2/shellexpand

Functions for expanding the tilde (~) character to the user's home directory.

```APIDOC
## tilde(value: &str)

### Description
Performs tilde expansion using the default system context (dirs::home_dir).

### Parameters
- **value** (str) - Required - The string starting with ~ to expand.

### Response
- **Cow<str>** - The expanded string.
```

--------------------------------

### Expand to Default Value for Unset Variables

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/fn.env_with_context.html

Shows how to use the `:-` syntax to provide a default value when an environment variable is not defined in the context. This ensures a fallback value is used.

```rust
assert_eq!(
    shellexpand::env_with_context("begin/${UNSET_ENV:-42}/end", context).unwrap(),
    "begin/42/end"
);

```

--------------------------------

### Environment Expansion Functions

Source: https://docs.rs/shellexpand/3.1.2/shellexpand

Functions for performing environment variable expansion, supporting default values and custom context providers.

```APIDOC
## env(value: &str)

### Description
Performs environment expansion using the default system context (std::env::var).

### Parameters
- **value** (str) - Required - The string containing environment variables to expand.

### Response
- **Result<Cow<str>, LookupError>** - The expanded string or a lookup error if a variable is missing or inaccessible.
```

```APIDOC
## env_with_context(value: &str, context: F)

### Description
Performs environment expansion using a provided custom context function.

### Parameters
- **value** (str) - Required - The string to expand.
- **context** (Fn) - Required - A closure that resolves variable names to values.
```

--------------------------------

### shellexpand Functions

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/all.html

Overview of the primary functions available in the shellexpand crate for string expansion.

```APIDOC
## Functions

### env
Expands environment variables in a string.

### env_with_context
Expands environment variables using a provided context.

### env_with_context_no_errors
Expands environment variables using a provided context, suppressing errors.

### full
Performs full shell-style expansion (tilde and environment variables).

### full_with_context
Performs full shell-style expansion using a provided context.

### full_with_context_no_errors
Performs full shell-style expansion using a provided context, suppressing errors.

### tilde
Expands tilde (~) to the user's home directory.

### tilde_with_context
Expands tilde (~) using a provided context.
```

--------------------------------

### Function: env

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/fn.env.html

Performs environment variable expansion using the default system context (std::env::var).

```APIDOC
## Function: env

### Description
Performs environment variable expansion using the default system context. This function delegates to `env_with_context()` using `std::env::var()`. Note that lookup of unknown variables results in a `LookupError`.

### Signature
`pub fn env<SI>(input: &SI) -> Result<Cow<'_, str>, LookupError<VarError>> where SI: AsRef<str> + ?Sized`

### Parameters
- **input** (&SI) - Required - The input string containing variables to expand (e.g., $VAR or ${VAR}).

### Response
- **Result** (Cow<'_, str>) - Returns the expanded string on success, or a `LookupError` if a variable is missing.

### Example
```rust
use std::env;

env::set_var("X", "x value");
assert_eq!(shellexpand::env("begin/$X/end").unwrap(), "begin/x value/end");
```
```

--------------------------------

### Expand Environment Variables with Default Context

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/fn.env.html

Use this function to perform environment expansion using the default system context. It relies on `std::env::var()` for variable lookups. Unknown variables will result in an error, which is the default behavior for robustness. For alternative error handling, consider `env_with_context()` or `env_with_context_no_errors()`.

```rust
use std::env;

// make sure that some environment variables are set
env::set_var("X", "x value");
env::set_var("Y", "y value");

// Known variables are expanded
assert_eq!(
    shellexpand::env("begin/$X/${Y}s/end").unwrap(),
    "begin/x value/y values/end"
);

// Unknown variables result in an error
assert_eq!(
    shellexpand::env("begin/$Z/end"),
    Err(shellexpand::LookupError {
        var_name: "Z".into(),
        cause: env::VarError::NotPresent
    })
);
```

--------------------------------

### Expand Regular Variables with Context

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/fn.env_with_context.html

Demonstrates expanding standard shell variables like `$A` and `${B}` using a custom context function. This is useful for dynamic string construction.

```rust
assert_eq!(
    shellexpand::env_with_context("begin/$A/${B}s/end", context).unwrap(),
    "begin/a value/b values/end"
);

```

--------------------------------

### OStringExt: Append String Data

Source: https://docs.rs/shellexpand/3.1.2/src/shellexpand/wtraits.rs.html

Provides methods to append different string types to an `OString`. Use `push_str` for literal strings, `push_wstr` for `Wstr` slices, and `push_xstr` for `Xstr` slices. These are useful for accumulating output strings, especially in error reporting.

```rust
pub(crate) trait OStringExt {
    /// Append a plain `str` (used for literal text)
    #[allow(unused)] // false positive, depending on Rust version &/ cargo features
    fn push_str(&mut self, x: &str);

    /// Append a `Wstr` (used for copying through pieces of the input)
    fn push_wstr(&mut self, x: &Wstr);

    /// Append an `Xstr` (used for copying through variable lookup results)
    fn push_xstr(&mut self, x: &Xstr);

    /// Convert an output string we have been accumulating into the public output type
    fn into_ocow(self) -> Cow<'static, Xstr>;

    /// Write this input string in a possibly-lossy way, for use in error messages
    fn display_possibly_lossy(&self, f: &mut fmt::Formatter) -> fmt::Result;
}
```

--------------------------------

### env_with_context_no_errors

Source: https://docs.rs/shellexpand/3.1.2/src/shellexpand/funcs.rs.html

Performs environment expansion using a custom context function that returns Option<CO>. This function forbids the variable lookup function to return errors and simplifies the API when context lookups are known not to fail.

```APIDOC
## env_with_context_no_errors

### Description
Performs environment expansion using a custom context function that returns Option<CO>. This function forbids the variable lookup function to return errors and simplifies the API when context lookups are known not to fail.

### Method
`pub fn env_with_context_no_errors<SI: ?Sized, CO, C>(input: &SI, mut context: C) -> Cow<'_, Xstr>`

### Endpoint
N/A (Function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
fn context(s: &str) -> Option<&'static str> {
    match s {
        "A" => Some("a value"),
        "B" => Some("b value"),
        _ => None
    }
}

// Known variables are expanded
assert_eq!(
    shellexpand::env_with_context_no_errors("begin/$A/${B}s/end", context),
    "begin/a value/b values/end"
);

// Unknown variables are left as is
assert_eq!(
    shellexpand::env_with_context_no_errors("begin/$U/end", context),
    "begin/$U/end"
);
```

### Response
#### Success Response (200)
`Cow<'_, Xstr>`: The expanded string.

#### Response Example
```json
{
  "example": "begin/a value/b values/end"
}
```
```

--------------------------------

### Function signature for full_with_context

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/fn.full_with_context.html

The signature for the full_with_context function, showing the required trait bounds for input, home directory, and context closure.

```rust
pub fn full_with_context<SI, CO, C, E, P, HD>(
    input: &SI,
    home_dir: HD,
    context: C,
) -> Result<Cow<'_, str>, LookupError<E>>
where
    SI: AsRef<str> + ?Sized,
    CO: AsRef<str>,
    C: FnMut(&str) -> Result<Option<CO>, E>,
    P: AsRef<str>,
    HD: FnOnce() -> Option<P>,
```

--------------------------------

### PathBuf Conversion to String

Source: https://docs.rs/shellexpand/3.1.2/src/shellexpand/strings.rs.html

Provides a method to attempt conversion of a `PathBuf` into a `String`. This is useful when a shell-like string representation is needed from a path.

```rust
impl PathBufExt for PathBuf {
    fn try_into_xstring(self) -> Option<String> {
        self.into_os_string().into_string().ok()
    }
}
```

--------------------------------

### Perform tilde expansion with shellexpand::tilde

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/fn.tilde.html

Expands the tilde character in a path string using the system's default home directory.

```rust
let hds = dirs::home_dir()
    .map(|p| p.display().to_string())
    .unwrap_or_else(|| "~".to_owned());

assert_eq!(
    shellexpand::tilde("~/some/dir"),
    format!("{}/some/dir", hds)
);
```

--------------------------------

### Handle missing environment variables with error reporting

Source: https://docs.rs/shellexpand/3.1.2/src/shellexpand/lib.rs.html

Shows how the default env() function returns a LookupError when an environment variable is not present.

```rust
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 {
        var_name: "MOST_LIKELY_NONEXISTING_VAR".into(),
        cause: env::VarError::NotPresent
    })
);
```

--------------------------------

### Function Signature: env_with_context

Source: https://docs.rs/shellexpand/3.1.2/shellexpand/fn.env_with_context.html

Defines the signature for `env_with_context`, which performs environment expansion using a provided context. It handles potential lookup errors.

```rust
pub fn env_with_context<SI, CO, C, E>(
    input: &SI,
    context: C,
) -> Result<Cow<'_, str>, LookupError<E>>
where
    SI: AsRef<str> + ?Sized,
    CO: AsRef<str>,
    C: FnMut(&str) -> Result<Option<CO>, E>,

```
Tokens:
Raw