Shell Escape

https://docs.rs/shell-escape/0.1.5
Admin
Shell Escape is a Rust crate that provides functionality to escape characters that may have special...
Tokens:3,058
Snippets:47
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### escape

Source: https://docs.rs/shell-escape/0.1.5/shell_escape/windows/fn.escape.html

Escapes a string for the windows cmd.exe shell. See here for more information.

```APIDOC
## escape

### Description
Escapes a string for the windows cmd.exe shell.

### Signature
```rust
pub fn escape(s: Cow<'_, str>) -> Cow<'_, str>
```
```

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

### windows::escape

Source: https://docs.rs/shell-escape/0.1.5/shell_escape/all.html

Escapes a string for safe use in a Windows shell command.

```APIDOC
## windows::escape

### Description
Escapes a string for safe use in a Windows shell command.

### Function Signature
`pub fn escape<S: AsRef<str>>(s: S) -> String`

### Parameters
* `s` - The string to escape.

### Returns
A string that is safe to use in a Windows shell command.
```

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

### Escape for Windows cmd.exe

Source: https://docs.rs/shell-escape/0.1.5/shell_escape/windows/fn.escape.html

Use this function to escape strings intended for the Windows cmd.exe shell. Refer to the provided link for detailed information on the escaping rules.

```rust
pub fn escape(s: Cow<'_, str>) -> Cow<'_, str>
```

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

### escape

Source: https://docs.rs/shell-escape/0.1.5/shell_escape/all.html

Escapes a string for safe use in a shell command.

```APIDOC
## escape

### Description
Escapes a string for safe use in a shell command.

### Function Signature
`pub fn escape<S: AsRef<str>>(s: S) -> String`

### Parameters
* `s` - The string to escape.

### Returns
A string that is safe to use in a shell command.
```

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

### Platform-Agnostic Shell String Escaping

Source: https://docs.rs/shell-escape/0.1.5/src/shell_escape/lib.rs.html

Escapes a string for safe use in a shell command. It automatically selects the appropriate escaping mechanism (Unix or Windows) based on the target platform or environment variables.

```rust
use std::borrow::Cow;
use std::env;

pub fn escape(s: Cow<str>) -> Cow<str> {
    if cfg!(unix) || env::var("MSYSTEM").is_ok() {
        unix::escape(s)
    } else {
        windows::escape(s)
    }
}
```

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

### unix::escape

Source: https://docs.rs/shell-escape/0.1.5/shell_escape/all.html

Escapes a string for safe use in a Unix-like shell command.

```APIDOC
## unix::escape

### Description
Escapes a string for safe use in a Unix-like shell command.

### Function Signature
`pub fn escape<S: AsRef<str>>(s: S) -> String`

### Parameters
* `s` - The string to escape.

### Returns
A string that is safe to use in a Unix-like shell command.
```

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

### escape

Source: https://docs.rs/shell-escape/0.1.5/src/shell_escape/lib.rs.html

Escapes characters that may have special meaning in a shell. It automatically detects the operating system and uses the appropriate escaping mechanism (Unix or Windows).

```APIDOC
## escape

### Description
Escapes characters that may have special meaning in a shell. It automatically detects the operating system and uses the appropriate escaping mechanism (Unix or Windows).

### Function Signature
`pub fn escape(s: Cow<str>) -> Cow<str>`

### Parameters
- **s** (`Cow<str>`) - The string to escape.

### Returns
- (`Cow<str>`) - The escaped string.
```

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

### Windows cmd.exe Shell String Escaping

Source: https://docs.rs/shell-escape/0.1.5/src/shell_escape/lib.rs.html

Escapes a string for the Windows cmd.exe shell. Strings containing spaces, tabs, newlines, or double quotes are enclosed in double quotes, with internal double quotes and backslashes escaped appropriately.

```rust
use std::borrow::Cow;
use std::iter::repeat;

pub fn escape(s: Cow<str>) -> Cow<str> {
    let mut needs_escape = s.is_empty();
    for ch in s.chars() {
        match ch {
            '"' | '\t' | '\n' | ' ' => needs_escape = true,
            _ => {}
        }
    }
    if !needs_escape {
        return s
    }
    let mut es = String::with_capacity(s.len());
    es.push('"');
    let mut chars = s.chars().peekable();
    loop {
        let mut nslashes = 0;
        while let Some(&'\') = chars.peek() {
            chars.next();
            nslashes += 1;
        }

        match chars.next() {
            Some('"') => {
                es.extend(repeat('\').take(nslashes * 2 + 1));
                es.push('"');
            }
            Some(c) => {
                es.extend(repeat('\').take(nslashes));
                es.push(c);
            }
            None => {
                es.extend(repeat('\').take(nslashes * 2));
                break;
            }
        }

    }
    es.push('"');
    es.into()
}
```

```rust
assert_eq!(escape("--aaa=bbb-ccc".into()), "--aaa=bbb-ccc");
assert_eq!(escape("linker=gcc -L/foo -Wl,bar".into()),
r#""linker=gcc -L/foo -Wl,bar""#);
assert_eq!(escape(r#"--features=\"default\""#.into()),
r#""--features=\"default\"""#);
assert_eq!(escape(r#"\path\to\my documents\""#.into()),
r#""\path\to\my documents\\""#);
assert_eq!(escape("".into()), r#"""#);
```

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

### escape

Source: https://docs.rs/shell-escape/0.1.5/shell_escape/unix/fn.escape.html

Escapes characters that may have special meaning in a shell, including spaces.

```APIDOC
## escape

### Description
Escape characters that may have special meaning in a shell, including spaces.

### Signature
```rust
pub fn escape(s: Cow<'_, str>) -> Cow<'_, str>
```
```

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

### escape Function

Source: https://docs.rs/shell-escape/0.1.5/shell_escape

The `escape` function is the primary interface for escaping shell metacharacters. It handles the necessary logic to ensure strings are safe for shell interpretation.

```APIDOC
## Function: escape

### Description
Escape characters that may have special meaning in a shell.

### Signature
```rust
pub fn escape<S: AsRef<str>>(s: S) -> String
```

### Parameters
* `s` - A string slice or type that can be referenced as a string slice, to be escaped.

### Returns
A `String` containing the escaped version of the input string.
```

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

### escape Function

Source: https://docs.rs/shell-escape/0.1.5/shell_escape/index.html

Escapes characters that may have special meaning in a shell. This is a general-purpose function for shell escaping.

```APIDOC
## Function: escape

### Description
Escape characters that may have special meaning in a shell.

### Signature
```rust
pub fn escape<S: AsRef<str>>(input: S) -> String
```

### Parameters
* `input` - A string slice or type that can be referenced as a string slice, which will be escaped.

### Returns
A `String` containing the escaped version of the input.
```

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

### escape

Source: https://docs.rs/shell-escape/0.1.5/shell_escape/fn.escape.html

Escapes characters that may have special meaning in a shell.

```APIDOC
## escape

### Description
Escape characters that may have special meaning in a shell.

### Signature
```rust
pub fn escape(s: Cow<'_, str>) -> Cow<'_, str>
```
```

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

### escape Function

Source: https://docs.rs/shell-escape/0.1.5/index.html

Escapes characters that may have special meaning in a shell.

```APIDOC
## Function: escape

### Description
Escape characters that may have special meaning in a shell.

### Parameters

This function does not explicitly list parameters in the provided documentation.
```

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

### Unix Shell String Escaping

Source: https://docs.rs/shell-escape/0.1.5/src/shell_escape/lib.rs.html

Escapes a string for Unix-like shells. Strings containing characters not in the whitelisted set (alphanumeric, -, _, =, /, ,, ., +) are enclosed in single quotes. Single quotes and exclamation marks within the string are escaped.

```rust
use std::borrow::Cow;

fn non_whitelisted(ch: char) -> bool {
    match ch {
        'a'...'z' | 'A'...'Z' | '0'...'9' | '-' | '_' | '=' | '/' | ',' | '.' | '+' => false,
        _ => true,
    }
}

pub fn escape(s: Cow<str>) -> Cow<str> {
    if !s.is_empty() && !s.contains(non_whitelisted) {
        return s;
    }

    let mut es = String::with_capacity(s.len() + 2);
    es.push('\'');
    for ch in s.chars() {
        match ch {
            '\' | '!' => {
                es.push_str("'\\'");
                es.push(ch);
                es.push('\'');
            }
            _ => es.push(ch),
        }
    }
    es.push('\'');
    es.into()
}
```

```rust
assert_eq!(
    escape("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_=/,.+".into()),
    "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_=/,.+"
);
assert_eq!(escape("--aaa=bbb-ccc".into()), "--aaa=bbb-ccc");
assert_eq!(escape("linker=gcc -L/foo -Wl,bar".into()), r"'linker=gcc -L/foo -Wl,bar'");
assert_eq!(escape(r"--features=\"default\"".into()), r"'--features=\"default\"'");
assert_eq!(escape(r"'!,`\\\n ".into()), r"''\'!'\$`\\\n '");
assert_eq!(escape("".into()), r"''");
```

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

### unix::escape

Source: https://docs.rs/shell-escape/0.1.5/src/shell_escape/lib.rs.html

Escapes characters that may have special meaning in a Unix-like shell, including spaces. It uses single quotes to enclose the string and escapes single quotes and exclamation marks within the string.

```APIDOC
## unix::escape

### Description
Escapes characters that may have special meaning in a Unix-like shell, including spaces. It uses single quotes to enclose the string and escapes single quotes and exclamation marks within the string.

### Function Signature
`pub fn escape(s: Cow<str>) -> Cow<str>`

### Parameters
- **s** (`Cow<str>`) - The string to escape for Unix shells.

### Returns
- (`Cow<str>`) - The escaped string suitable for Unix shells.

### Example
```rust
use shell_escape::unix;

let escaped = unix::escape("linker=gcc -L/foo -Wl,bar".into());
assert_eq!(escaped, "'linker=gcc -L/foo -Wl,bar'");
```
```
Tokens:
Raw