Shell Quote

https://docs.rs/shell-quote/latest/shell_quote/
Admin
Shell Quote is a Rust crate that escapes strings so they can be safely inserted into shell scripts...
Tokens:4,736
Snippets:59
Trust Score:9.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Configuring dependencies in Cargo.toml

Source: https://docs.rs/shell-quote/latest/shell_quote/index.html

Example of how to limit shell support by disabling default features in Cargo.toml.

```toml
[dependencies]
shell-quote = { version = "*", default-features = false, features = ["bash"] }
```

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

### Fish shell quoting example

Source: https://docs.rs/shell-quote/latest/shell_quote/struct.Fish.html

Demonstrates how to correctly place escape sequences outside of quotes in the fish shell.

```bash
echo 'foo'\t'bar'
```

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

### Define Zsh struct

Source: https://docs.rs/shell-quote/latest/shell_quote/type.Zsh.html

The Zsh struct definition.

```rust
pub struct Zsh;
```

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

### Directly quoting strings with shell-specific structs

Source: https://docs.rs/shell-quote/latest/shell_quote/index.html

Use shell-specific structs like Bash, Dash, or Fish to quote strings directly. Note that Dash is an alias for Sh and Zsh is an alias for Bash.

```rust
use shell_quote::{Bash, Dash, Fish, Sh, Zsh};
// No quoting is necessary for simple strings.
assert_eq!(Sh::quote_vec("foobar"), b"foobar");
assert_eq!(Dash::quote_vec("foobar"), b"foobar");  // `Dash` is an alias for `Sh`
assert_eq!(Bash::quote_vec("foobar"), b"foobar");
assert_eq!(Zsh::quote_vec("foobar"), b"foobar");   // `Zsh` is an alias for `Bash`
assert_eq!(Fish::quote_vec("foobar"), b"foobar");
// In all shells, quoting is necessary for strings with spaces.
assert_eq!(Sh::quote_vec("foo bar"), b"foo' bar'");
assert_eq!(Dash::quote_vec("foo bar"), b"foo' bar'");
assert_eq!(Bash::quote_vec("foo bar"), b"$'foo bar'$");
assert_eq!(Zsh::quote_vec("foo bar"), b"$'foo bar'$");
assert_eq!(Fish::quote_vec("foo bar"), b"foo' bar'");
```

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

### Bash Struct Definition

Source: https://docs.rs/shell-quote/latest/shell_quote/struct.Bash.html

The definition of the Bash struct.

```rust
pub struct Bash;
```

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

### Pushing quoted strings into a buffer with QuoteExt

Source: https://docs.rs/shell-quote/latest/shell_quote/index.html

Use the QuoteExt trait to append quoted strings directly into an existing buffer.

```rust
use shell_quote::{Bash, QuoteExt};
let mut script: bstr::BString = "echo ".into();
script.push_quoted(Bash, "foo bar");
script.extend(b" > ");
script.push_quoted(Bash, "/path/(to)/[output]");
assert_eq!(script, "echo $'foo bar' > $'/path/(to)/[output]'");
```

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

### Zsh::quote_into_vec

Source: https://docs.rs/shell-quote/latest/shell_quote/type.Zsh.html

Quotes a string of bytes into an existing Vec<u8> buffer.

```APIDOC
## pub fn quote_into_vec<'a, S: Into<Quotable<'a>>>(s: S, sout: &mut Vec<u8>)

### Description
Quote a string of bytes into an existing `Vec<u8>`. This is useful for appending quoted strings to an existing buffer without extra allocations.

### Parameters
- **s** (Into<Quotable<'a>>) - Required - The input string to be quoted.
- **sout** (&mut Vec<u8>) - Required - The mutable reference to the destination buffer.
```

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

### Define Fish struct

Source: https://docs.rs/shell-quote/latest/shell_quote/struct.Fish.html

The basic definition of the Fish struct.

```rust
pub struct Fish;
```

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

### Bash::quote_into_vec

Source: https://docs.rs/shell-quote/latest/shell_quote/struct.Bash.html

Quotes a string of bytes into an existing Vec<u8> buffer.

```APIDOC
## pub fn quote_into_vec<'a, S: Into<Quotable<'a>>>(s: S, sout: &mut Vec<u8>)

### Description
Quote a string of bytes into an existing `Vec<u8>`. This method appends the quoted result to the provided buffer.

### Parameters
- **s** (S: Into<Quotable<'a>>) - Required - The input string or byte sequence to be quoted.
- **sout** (&mut Vec<u8>) - Required - The existing buffer to append the quoted result into.
```

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

### fn quote_into<'q, S: Into<Quotable<'q>>>(s: S, out: &mut OUT)

Source: https://docs.rs/shell-quote/latest/shell_quote/trait.QuoteInto.html

Quotes or escapes a string of bytes into an existing container.

```APIDOC
## fn quote_into<'q, S: Into<Quotable<'q>>>(s: S, out: &mut OUT)

### Description
Quotes or escapes a string of bytes into an existing container. This method is used to transform input into a shell-safe format.

### Parameters
- **s** (S: Into<Quotable<'q>>) - Required - The input string of bytes to be quoted.
- **out** (&mut OUT) - Required - The mutable container where the quoted output will be stored.
```

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

### Quote string into a new Vec<u8>

Source: https://docs.rs/shell-quote/latest/shell_quote/struct.Bash.html

Returns a new vector containing the quoted byte string. If no escaping is required, the original string is returned as-is.

```rust
assert_eq!(Bash::quote_vec("foobar"), b"foobar");
assert_eq!(Bash::quote_vec("foo bar"), b"$'foo bar'");
```

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

### Sh::quote_into_vec

Source: https://docs.rs/shell-quote/latest/shell_quote/struct.Sh.html

Quotes a string of bytes into an existing Vec<u8> buffer, allowing for efficient memory usage by appending to an existing allocation.

```APIDOC
## pub fn quote_into_vec<'a, S: Into<Quotable<'a>>>(s: S, sout: &mut Vec<u8>)

### Description
Quotes a string of bytes into an existing `Vec<u8>`. This is useful for building command strings incrementally.

### Parameters
- **s** (Into<Quotable<'a>>) - Required - The input string or byte sequence to be quoted.
- **sout** (&mut Vec<u8>) - Required - A mutable reference to the destination vector where the quoted bytes will be appended.
```

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

### Quote strings into an existing Vec

Source: https://docs.rs/shell-quote/latest/shell_quote/type.Zsh.html

Use quote_into_vec to append a quoted string to an existing buffer.

```rust
let mut buf = Vec::with_capacity(128);
Bash::quote_into_vec("foobar", &mut buf);
buf.push(b' ');  // Add a space.
Bash::quote_into_vec("foo bar", &mut buf);
assert_eq!(buf, b"foobar $'foo bar'$");
```

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

### Fish::quote_into_vec

Source: https://docs.rs/shell-quote/latest/shell_quote/struct.Fish.html

Quotes a string of bytes into an existing Vec<u8> buffer, allowing for efficient memory usage by appending to an existing allocation.

```APIDOC
## pub fn quote_into_vec<'a, S: Into<Quotable<'a>>>(s: S, sout: &mut Vec<u8>)

### Description
Quote a string of bytes into an existing `Vec<u8>`. This is useful for avoiding new allocations when building command strings.

### Parameters
- **s** (S: Into<Quotable<'a>>) - Required - The input string or byte sequence to be quoted.
- **sout** (&mut Vec<u8>) - Required - The mutable reference to the buffer where the quoted bytes will be appended.

### Example
```rust
let mut buf = Vec::with_capacity(128);
Fish::quote_into_vec("foobar", &mut buf);
buf.push(b' ');
Fish::quote_into_vec("foo 'bar", &mut buf);
assert_eq!(buf, b"foobar foo' \'bar'");
```
```

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

### QuoteInto Trait Definition

Source: https://docs.rs/shell-quote/latest/shell_quote/trait.QuoteInto.html

The core trait definition for quoting strings into a mutable output container.

```rust
pub trait QuoteInto<OUT: ?Sized> {
    // Required method
    fn quote_into<'q, S: Into<Quotable<'q>>>(s: S, out: &mut OUT);
}
```

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

### Bash ANSI C Escape Sequences

Source: https://docs.rs/shell-quote/latest/shell_quote/struct.Bash.html

List of backslash escape sequences decoded by Bash as specified by the ANSI C standard.

```text
\a     alert (bell)
\b     backspace
\e     an escape character
\f     form feed
\n     new line
\r     carriage return
\t     horizontal tab
\v     vertical tab
\\     backslash
\'     single quote
\nnn   the eight-bit character whose value is the
       octal value nnn (one to three digits)
\xHH   the eight-bit character whose value is the
       hexadecimal value HH (one or two hex digits)
\cx    a control-x character
```

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

### Comparing UTF-8 string and byte-based quoting

Source: https://docs.rs/shell-quote/latest/shell_quote/index.html

UTF-8 strings are preserved verbatim, whereas byte slices are hex-escaped when using Bash quoting.

```rust
let data: &str = "café";
let data_utf8_quoted_from_string_type: Vec<u8> = data.quoted(Bash);
assert_eq!(&data_utf8_quoted_from_string_type, b"$'caf\xC3\xA9'$"); // UTF-8, verbatim.
let data_utf8_quoted_from_bytes: Vec<u8> = data.as_bytes().quoted(Bash);
assert_eq!(&data_utf8_quoted_from_bytes, b"$'caf\\xC3\\xA9'$"); // Now hex escaped!
```

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

### Quote string into an existing Vec<u8>

Source: https://docs.rs/shell-quote/latest/shell_quote/struct.Bash.html

Appends a quoted byte string to an existing vector, useful for minimizing allocations.

```rust
let mut buf = Vec::with_capacity(128);
Bash::quote_into_vec("foobar", &mut buf);
buf.push(b' ');  // Add a space.
Bash::quote_into_vec("foo bar", &mut buf);
assert_eq!(buf, b"foobar $'foo bar'");
```

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

### Quoting non-UTF-8 encoded data

Source: https://docs.rs/shell-quote/latest/shell_quote/index.html

Non-UTF-8 data must be encoded before passing to the crate's functions to ensure correct hex escaping.

```rust
let data = "café";
let data_utf8_quoted: Vec<u8> = data.quoted(Bash);
assert_eq!(&data_utf8_quoted, b"$'caf\xC3\xA9'$"); // UTF-8: 2 bytes for é.
let data_iso_8859_1: &[u8] = encode_iso_8859_1(data);
let data_iso_8859_1_quoted: Vec<u8> = data_iso_8859_1.quoted(Bash);
assert_eq!(&data_iso_8859_1_quoted, b"$'caf\\xE9'$"); // ISO-8859-1: 1 byte, hex escaped.
```

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

### Quote strings into a new Vec

Source: https://docs.rs/shell-quote/latest/shell_quote/type.Zsh.html

Use quote_vec to return a new Vec<u8> containing the quoted string.

```rust
assert_eq!(Bash::quote_vec("foobar"), b"foobar");
assert_eq!(Bash::quote_vec("foo bar"), b"$'foo bar'$");
```

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

### Bash::quote_vec

Source: https://docs.rs/shell-quote/latest/shell_quote/struct.Bash.html

Quotes a string of bytes into a new Vec<u8>. It returns the string as-is if no escaping is necessary, or an ANSI-C escaped string.

```APIDOC
## pub fn quote_vec<'a, S: Into<Quotable<'a>>>(s: S) -> Vec<u8>

### Description
Quote a string of bytes into a new `Vec<u8>`. This will return the string as-is if no escaping is necessary, or an ANSI-C escaped string.

### Parameters
- **s** (S: Into<Quotable<'a>>) - Required - The input string or byte sequence to be quoted.

### Returns
- **Vec<u8>** - The quoted byte sequence.
```

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

### Quoting strings using the QuoteRefExt trait

Source: https://docs.rs/shell-quote/latest/shell_quote/index.html

The QuoteRefExt trait provides a convenient quoted function to convert strings into quoted formats.

```rust
use shell_quote::{Bash, Sh, Fish, QuoteRefExt};
let quoted: String = "foo bar".quoted(Bash);
assert_eq!(quoted, "$'foo bar'$");
let quoted: Vec<u8> = "foo bar".quoted(Sh);
assert_eq!(quoted, b"foo' bar'");
let quoted: String = "foo bar".quoted(Fish);
assert_eq!(quoted, "foo' bar'");
```

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

### Define Zsh type alias

Source: https://docs.rs/shell-quote/latest/shell_quote/type.Zsh.html

The Zsh type is defined as an alias for the Bash type.

```rust
pub type Zsh = Bash;
```

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

### Aliased Type Definition

Source: https://docs.rs/shell-quote/latest/shell_quote/type.Dash.html

The underlying structure for the Dash type.

```rust
pub struct Dash;
```

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

### QuoteExt Trait Definition

Source: https://docs.rs/shell-quote/latest/shell_quote/trait.QuoteExt.html

The definition of the QuoteExt trait, requiring the push_quoted method for shell-quoted data insertion.

```rust
pub trait QuoteExt {
    // Required method
    fn push_quoted<'q, Q, S>(&mut self, _q: Q, s: S)
       where Q: QuoteInto<Self>,
             S: Into<Quotable<'q>>;
}
```

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

### Sh::quote_vec

Source: https://docs.rs/shell-quote/latest/shell_quote/struct.Sh.html

Quotes a string of bytes into a new Vec<u8>. It returns the string as-is if no quoting is necessary, or a string containing single-quoted sections.

```APIDOC
## pub fn quote_vec<'a, S: Into<Quotable<'a>>>(s: S) -> Vec<u8>

### Description
Quotes a string of bytes into a new `Vec<u8>`. This method handles the necessary quoting logic for `/bin/sh` compatibility.

### Parameters
- **s** (Into<Quotable<'a>>) - Required - The input string or byte sequence to be quoted.

### Returns
- **Vec<u8>** - A new vector containing the quoted byte sequence.
```

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

### Fish::quote_vec

Source: https://docs.rs/shell-quote/latest/shell_quote/struct.Fish.html

Quotes a string of bytes into a new Vec<u8>. It returns the string as-is if no escaping is required, or an escaped version if necessary.

```APIDOC
## pub fn quote_vec<'a, S: Into<Quotable<'a>>>(s: S) -> Vec<u8>

### Description
Quote a string of bytes into a new `Vec<u8>`. This method handles the necessary escaping for the fish shell.

### Parameters
- **s** (S: Into<Quotable<'a>>) - Required - The input string or byte sequence to be quoted.

### Returns
- **Vec<u8>** - The quoted byte sequence.

### Example
```rust
assert_eq!(Fish::quote_vec("foobar"), b"foobar");
assert_eq!(Fish::quote_vec("foo 'bar"), b"foo' \'bar'");
```
```

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

### Quote trait definition

Source: https://docs.rs/shell-quote/latest/shell_quote/trait.Quote.html

The definition of the Quote trait, which requires the QuoteInto trait.

```rust
pub trait Quote<OUT: Default>: QuoteInto<OUT> {
    // Provided method
    fn quote<'q, S: Into<Quotable<'q>>>(s: S) -> OUT { ... }
}
```

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

### Zsh::quote_vec

Source: https://docs.rs/shell-quote/latest/shell_quote/type.Zsh.html

Quotes a string of bytes into a new Vec<u8>. Returns the string as-is if no escaping is necessary, or an ANSI-C escaped string.

```APIDOC
## pub fn quote_vec<'a, S: Into<Quotable<'a>>>(s: S) -> Vec<u8>

### Description
Quote a string of bytes into a new `Vec<u8>`. This will return the string as-is if no escaping is necessary, or an ANSI-C escaped string (e.g., `$'foo\nbar'`).

### Parameters
- **s** (Into<Quotable<'a>>) - Required - The input string to be quoted.

### Returns
- **Vec<u8>** - The quoted string as a vector of bytes.
```

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

### QuoteRefExt Trait Definition

Source: https://docs.rs/shell-quote/latest/shell_quote/trait.QuoteRefExt.html

The core trait definition for QuoteRefExt, requiring an Output type that implements Default and a quoted method.

```rust
pub trait QuoteRefExt<Output: Default> {
    // Required method
    fn quoted<Q: Quote<Output>>(self, q: Q) -> Output;
}
```

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

### Bourne Shell double quote escape characters

Source: https://docs.rs/shell-quote/latest/shell_quote/struct.Sh.html

Characters that require backslash escaping within double quotes in the Bourne shell.

```text
$ ` " \ <newline>.
```

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

### Quotable Enum Definition

Source: https://docs.rs/shell-quote/latest/shell_quote/enum.Quotable.html

The core enum structure used to represent either raw bytes or text for quoting.

```rust
pub enum Quotable<'a> {
    Bytes(&'a [u8]),
    Text(&'a str),
}
```

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

### Dash Type Definition

Source: https://docs.rs/shell-quote/latest/shell_quote/type.Dash.html

The Dash type is defined as an alias for the Sh struct.

```rust
pub type Dash = Sh;
```
Tokens:
Raw