Maintainers
Pricing
Enterprise
More
More
Documentation
Try Live
Rankings
Install
Blog
Docs7
Ask
New
Add Docs
shlex
https://docs.rs/shlex/latest/shlex/
Admin
shlex is a Rust library that parses strings like, and escapes strings for, POSIX shells.
Tokens:
48,122
Snippets:
495
Trust Score:
9.1
Update:
2 weeks ago
Context
Chat
Benchmark
Latest
Show doc for...
Code
Info
Show Results
Tokens:
Raw
Copy
Link
Tokens:
Raw
Copy
Link
### Output of the Rust example showing control character effect Source: https://docs.rs/shlex/latest/shlex/quoting_warning/index.html The output of the previous Rust program, showing that even though the string was quoted, Bash still executed the command 'do_something_evil' and then 'echo '. ```text quoted string is "'\u{1}do_something_evil; '" /tmp comex$ do_something_evil; 'echo ' bash: do_something_evil: command not found bash: echo : command not found ``` -------------------------------- ### Shell behavior of `!` and `^` in interactive contexts Source: https://docs.rs/shlex/latest/shlex/quoting_warning/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E These shell examples illustrate the behavior of the `!` and `^` characters in interactive shells. The first shows that backslash-escaping `!` inside double quotes produces a literal backslash. The second demonstrates that `^` can be partially expanded even inside single quotes due to a Bash bug. ```shell $ echo "\!" \! ``` ```shell $ echo ' > ^a^b > ' !!:s^a^b ``` -------------------------------- ### Overlong command with /bin/echo and Argument list too long Source: https://docs.rs/shlex/latest/shlex/quoting_warning/index.html Shows an overlong command example: assigning a 10-million-character string and passing it to /bin/echo results in 'Argument list too long' error. ```bash x=$(printf '%010000000d' 0); /bin/echo $x bash: /bin/echo: Argument list too long ``` -------------------------------- ### Bash ANSI-C quoting example with hex escape Source: https://docs.rs/shlex/latest/shlex/quoting_warning/index.html Demonstrates Bash's ANSI-C quoting syntax ($'...') which supports C escape sequences like \x41 and \n. This is not portable to all POSIX shells, so the crate avoids it. ```bash $ echo $'\x41\n\x42' A B ``` -------------------------------- ### pub fn new() -> Self Source: https://docs.rs/shlex/latest/shlex/bytes/struct.Quoter.html Creates a new Quoter with default settings. ```APIDOC ## pub fn new() -> Self ### Description Creates a new `Quoter` with default settings. ### Method new ### Signature `pub fn new() -> Self` ### Parameters None ### Returns - `Self` - A new `Quoter` instance with default settings. ``` -------------------------------- ### split Source: https://docs.rs/shlex/latest/shlex/fn.split.html Documentation for the split function from the shlex crate. ```APIDOC ## split ### Description Convenience function that consumes the whole string at once. Returns None if the input was erroneous. ### Function Signature pub fn split(in_str: &str) -> Option<Vec<String>> ### Parameters - **in_str** (&str) - Required - The input string to split. ### Return Value - **Option<Vec<String>>** - Returns Some(Vec<String>) containing the split parts, or None if the input was erroneous. ``` -------------------------------- ### try_join Source: https://docs.rs/shlex/latest/shlex/fn.try_join.html Documentation for the `try_join` function in the shlex crate. ```APIDOC ## try_join ### Description Convenience function that consumes an iterable of words and turns it into a single string, quoting words when necessary. Consecutive words will be separated by a single space. Uses default settings. The only error that can be returned is `QuoteError::Nul`. Equivalent to `Quoter::new().join(words)`. The bytes equivalent is `bytes::try_join`. ### Signature ```rust pub fn try_join<'a, I: IntoIterator<Item = &'a str>>( words: I, ) -> Result<String, QuoteError> ``` ### Parameters - **words** (`I: IntoIterator<Item = &'a str>`) - Required - An iterable of words to join into a single string. ### Return Value - `Result<String, QuoteError>` - On success, returns the joined string. On failure, returns `QuoteError::Nul`. ### Errors - `QuoteError::Nul` - Returned when a word contains a NUL byte. ``` -------------------------------- ### Quoter::new Source: https://docs.rs/shlex/latest/shlex/bytes/struct.Quoter.html?search= Creates a new `Quoter` instance with default settings. ```APIDOC ## Quoter::new ### Description Creates a new `Quoter` with default settings. ### Method new ### Signature pub fn new() -> Self ### Parameters None ### Returns - `Self` - A new `Quoter` instance with default settings. ``` -------------------------------- ### take Source: https://docs.rs/shlex/latest/shlex/bytes/struct.Shlex.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Creates an iterator that yields the first n elements, or fewer if the underlying iterator ends sooner. ```APIDOC ## take ### Description Creates an iterator that yields the first `n` elements, or fewer if the underlying iterator ends sooner. ### Signature ```rust fn take(self, n: usize) -> Take<Self> where Self: Sized, ``` ### Parameters - **n** (usize) - Required - The number of elements to take. ### Returns - **Take<Self>** - An iterator adapter that yields the first `n` elements. ### Notes - Available since Rust 1.0.0 (const: unstable). ``` -------------------------------- ### Quote byte string with try_quote on Unix Source: https://docs.rs/shlex/latest/shlex/bytes/index.html?search= Shows how to use `shlex::bytes::try_quote` to quote a byte string that may contain invalid UTF-8, such as an `OsStr` on Unix. The example asserts that the quoted output is `b"'a\x80b c'"`. This works only on Unix because `OsStr` uses 16-bit wide characters on Windows. ```rust #[cfg(unix)] { use shlex::bytes::try_quote; use std::ffi::OsStr; use std::os::unix::ffi::OsStrExt; // `\x80` is invalid in UTF-8. let os_str = OsStr::from_bytes(b"a\x80b c"); assert_eq!(try_quote(os_str.as_bytes()).unwrap(), &b"'a\x80b c'"[..]); } ``` -------------------------------- ### Rust example: quoting a string with control character and sending to interactive Bash Source: https://docs.rs/shlex/latest/shlex/quoting_warning/index.html Shows that quoting a string containing a control character (\x01) with shlex::try_quote does not prevent Bash from interpreting the control character when in interactive mode. The program spawns Bash with -i and writes the quoted string to its stdin. The output demonstrates that the control character still triggers command execution. ```rust use std::process::{Command, Stdio}; use std::io::Write; let evil_string = "\x01do_something_evil; "; let quoted = shlex::try_quote(evil_string).unwrap(); println!("quoted string is {:?}", quoted); let mut bash = Command::new("bash") .arg("-i") // force interactive mode .stdin(Stdio::piped()) .spawn() .unwrap(); let stdin = bash.stdin.as_mut().unwrap(); write!(stdin, "echo {}\n", quoted).unwrap(); ``` -------------------------------- ### try_join Source: https://docs.rs/shlex/latest/shlex/bytes/fn.try_join.html Documentation for the `shlex::bytes::try_join` function, including its signature, parameters, return type, and error conditions. ```APIDOC ## Function try_join ### Description Convenience function that consumes an iterable of words and turns it into a single byte string, quoting words when necessary. Consecutive words will be separated by a single space. Uses default settings. The only error that can be returned is `QuoteError::Nul`. Equivalent to `Quoter::new().join(words)`. The string equivalent is `shlex::try_join`. ### Signature ```rust pub fn try_join<'a, I: IntoIterator<Item = &'a [u8]>>( words: I, ) -> Result<Vec<u8>, QuoteError> ``` ### Parameters - `words` (I) - Required - An iterable of byte string slices (`&[u8]`) to be joined. ### Returns - `Result<Vec<u8>, QuoteError>` - On success, returns a `Vec<u8>` containing the joined byte string. On failure, returns `QuoteError::Nul` if a null byte is encountered. ### Errors - `QuoteError::Nul` - Returned if any word contains a null byte. ### Example ```rust use shlex::bytes::try_join; let words: Vec<&[u8]> = vec![b"hello", b"world"]; let result = try_join(words); assert_eq!(result, Ok(b"hello world".to_vec())); ``` ``` -------------------------------- ### try_join Source: https://docs.rs/shlex/latest/shlex/bytes/fn.try_join.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Documentation for the `try_join` function in the `shlex::bytes` module. ```APIDOC ## try_join ### Description Convenience function that consumes an iterable of words and turns it into a single byte string, quoting words when necessary. Consecutive words will be separated by a single space. Uses default settings. The only error that can be returned is `QuoteError::Nul`. Equivalent to `Quoter::new().join(words)`. The string equivalent is `shlex::try_join`. ### Function Signature ```rust pub fn try_join<'a, I: IntoIterator<Item = &'a [u8]>>( words: I, ) -> Result<Vec<u8>, QuoteError> ``` ### Parameters - **words** (`I: IntoIterator<Item = &'a [u8]>`) - Required - An iterable of byte string words to join. ### Return Value - `Result<Vec<u8>, QuoteError>` - A byte string with quoted words separated by spaces, or a `QuoteError::Nul` error if a word contains a NUL byte. ### Errors - `QuoteError::Nul` - Returned when a word contains a NUL byte. ### Example ```rust use shlex::bytes::try_join; let words = [b"foo".as_slice(), b"bar baz".as_slice()]; let result = try_join(words); assert_eq!(result, Ok(b"foo \"bar baz\"".to_vec())); ``` ``` -------------------------------- ### split Source: https://docs.rs/shlex/latest/shlex/bytes/fn.split.html?search=std%3A%3Avec Documentation for the `split` function in the `shlex::bytes` module. ```APIDOC ## split ### Description Convenience function that consumes the whole byte string at once. Returns None if the input was erroneous. ### Function Signature ```rust pub fn split(in_bytes: &[u8]) -> Option<Vec<Vec<u8>>> ``` ### Parameters - **in_bytes** (`&[u8]`) - Required - The byte string to split. ### Return Value - `Option<Vec<Vec<u8>>>` - Returns `None` if the input was erroneous; otherwise, a vector of byte vectors representing the split parts. ``` -------------------------------- ### split Source: https://docs.rs/shlex/latest/shlex/bytes/fn.split.html Documentation for the `split` function in the `shlex::bytes` module. ```APIDOC ## split ### Description Convenience function that consumes the whole byte string at once. Returns None if the input was erroneous. ### Function Signature ```rust pub fn split(in_bytes: &[u8]) -> Option<Vec<Vec<u8>>> ``` ### Parameters - **in_bytes** (`&[u8]`) - Required - The byte string to split. ### Return Value - `Option<Vec<Vec<u8>>>` - Returns `None` if the input was erroneous; otherwise, returns a vector of byte vectors representing the split parts. ``` -------------------------------- ### partition Source: https://docs.rs/shlex/latest/shlex/bytes/struct.Shlex.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Consumes an iterator, creating two collections from it. ```APIDOC ## partition ### Description Consumes an iterator, creating two collections from it. ### Signature ```rust fn partition<B, F>(self, f: F) -> (B, B) where Self: Sized, B: Default + Extend<Self::Item>, F: FnMut(&Self::Item) -> bool, ``` ### Parameters - **f** (F) - Required - A closure that determines which collection each item goes into. Returns `true` for the first collection, `false` for the second. ### Returns - **(B, B)** - A tuple of two collections: the first contains items for which `f` returned `true`, the second for which `f` returned `false`. ### Notes - Available since Rust 1.0.0 (const: unstable). ``` -------------------------------- ### Shlex::new Source: https://docs.rs/shlex/latest/shlex/struct.Shlex.html?search=std%3A%3Avec Creates a new Shlex iterator from a string slice. ```APIDOC ## Shlex::new ### Description Creates a new `Shlex` iterator that splits the input string into words using POSIX shell syntax. ### Method `pub fn new(in_str: &'a str) -> Self` ### Parameters - **in_str** (`&'a str`) - Required - The input string to split into words. ### Returns - `Self` - A new `Shlex` iterator. ``` -------------------------------- ### Shlex::new Source: https://docs.rs/shlex/latest/shlex/bytes/struct.Shlex.html?search=std%3A%3Avec Creates a new Shlex iterator from a byte string. The iterator splits the input into words using POSIX shell syntax. ```APIDOC ## Shlex::new ### Description Creates a new `Shlex` iterator that splits the given byte string into words using POSIX shell syntax. ### Method `pub fn new(in_bytes: &'a [u8]) -> Self` ### Parameters - `in_bytes` (`&'a [u8]`) - Required - The input byte string to split. ### Returns A new `Shlex` iterator instance. ### Example ```rust let mut shlex = Shlex::new(b"hello world"); ``` ``` -------------------------------- ### by_ref Source: https://docs.rs/shlex/latest/shlex/bytes/struct.Shlex.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Creates a “by reference” adapter for this instance of Iterator. ```APIDOC ## by_ref ### Description Creates a “by reference” adapter for this instance of `Iterator`. ### Signature ```rust fn by_ref(&mut self) -> &mut Self where Self: Sized, ``` ### Returns - **&mut Self** - A mutable reference to the iterator. ### Notes - Available since Rust 1.0.0 (const: unstable). ``` -------------------------------- ### product Source: https://docs.rs/shlex/latest/shlex/bytes/struct.Shlex.html?search=std%3A%3Avec Iterates over the entire iterator, multiplying all the elements. ```APIDOC ## product ### Description Iterates over the entire iterator, multiplying all the elements. ### Method product ### Signature fn product<P>(self) -> P where Self: Sized, P: Product<Self::Item> ### Returns - **P** - The product of all elements. ``` -------------------------------- ### pub fn quote<'a>(&self, in_bytes: &'a [u8]) -> Result<Cow<'a, [u8]>, QuoteError> Source: https://docs.rs/shlex/latest/shlex/bytes/struct.Quoter.html Given a single word, return a byte string suitable to encode it as a shell argument. If given valid UTF-8, this will never produce invalid UTF-8. ```APIDOC ## pub fn quote<'a>(&self, in_bytes: &'a [u8]) -> Result<Cow<'a, [u8]>, QuoteError> ### Description Given a single word, return a byte string suitable to encode it as a shell argument. If given valid UTF-8, this will never produce invalid UTF-8. This is because it only ever inserts valid ASCII characters before or after existing ASCII characters (or returns two single quotes if the input was an empty string). It will never modify a multibyte UTF-8 character. ### Method quote ### Signature `pub fn quote<'a>(&self, in_bytes: &'a [u8]) -> Result<Cow<'a, [u8]>, QuoteError>` ### Parameters - **in_bytes** (&'a [u8]) - Required - The word to quote. ### Returns - `Result<Cow<'a, [u8]>, QuoteError>` - The quoted byte string, or an error if quoting fails. ``` -------------------------------- ### shlex Functions Source: https://docs.rs/shlex/latest/shlex/all.html Functions for splitting, quoting, and joining shell command strings and byte slices. ```APIDOC ## [FUNCTION] split ### Description Splits a string into a vector of words, respecting shell quoting rules. ### Function Signature `pub fn split(s: &str) -> Vec<String>` ### Parameters - **s** (`&str`) - Required - The input string to split. ### Returns - `Vec<String>` - A vector of words extracted from the input. ``` ```APIDOC ## [FUNCTION] try_quote ### Description Attempts to quote a string for safe shell usage, returning an error if quoting is not possible. ### Function Signature `pub fn try_quote(s: &str) -> Result<Cow<'_, str>, QuoteError>` ### Parameters - **s** (`&str`) - Required - The string to quote. ### Returns - `Result<Cow<'_, str>, QuoteError>` - The quoted string on success, or a `QuoteError` on failure. ``` ```APIDOC ## [FUNCTION] try_join ### Description Joins a list of words into a single shell command string, quoting each word as necessary. ### Function Signature `pub fn try_join<I, S>(words: I) -> Result<String, QuoteError>` ### Parameters - **words** (`I`) - Required - An iterator of words to join. ### Returns - `Result<String, QuoteError>` - The joined command string on success, or a `QuoteError` on failure. ``` ```APIDOC ## [FUNCTION] bytes::split ### Description Splits a byte slice into a vector of byte vectors, respecting shell quoting rules. ### Function Signature `pub fn split(s: &[u8]) -> Vec<Vec<u8>>` ### Parameters - **s** (`&[u8]`) - Required - The input byte slice to split. ### Returns - `Vec<Vec<u8>>` - A vector of byte vectors extracted from the input. ``` ```APIDOC ## [FUNCTION] bytes::try_quote ### Description Attempts to quote a byte slice for safe shell usage, returning an error if quoting is not possible. ### Function Signature `pub fn try_quote(s: &[u8]) -> Result<Cow<'_, [u8]>, QuoteError>` ### Parameters - **s** (`&[u8]`) - Required - The byte slice to quote. ### Returns - `Result<Cow<'_, [u8]>, QuoteError>` - The quoted byte slice on success, or a `QuoteError` on failure. ``` ```APIDOC ## [FUNCTION] bytes::try_join ### Description Joins a list of byte vectors into a single shell command byte string, quoting each word as necessary. ### Function Signature `pub fn try_join<I, S>(words: I) -> Result<Vec<u8>, QuoteError>` ### Parameters - **words** (`I`) - Required - An iterator of byte vectors to join. ### Returns - `Result<Vec<u8>, QuoteError>` - The joined command byte string on success, or a `QuoteError` on failure. ``` -------------------------------- ### split(in_str: &str) -> Option<Vec<String>> Source: https://docs.rs/shlex/latest/shlex/fn.split.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Parses the entire input string as shell-like syntax and returns the resulting arguments. Returns None if the input contains an error. ```APIDOC ## Function split ### Description Convenience function that consumes the whole string at once. Returns None if the input was erroneous. ### Signature ```rust pub fn split(in_str: &str) -> Option<Vec<String>> ``` ### Parameters - **in_str** (`&str`) - The input string to parse. ### Returns - `Option<Vec<String>>` - A vector of parsed arguments, or `None` if the input was erroneous. ``` -------------------------------- ### pub fn try_join<'a, I: IntoIterator<Item = &'a [u8]>>(words: I) -> Result<Vec<u8>, QuoteError> Source: https://docs.rs/shlex/latest/shlex/bytes/fn.try_join.html?search=std%3A%3Avec Joins an iterable of byte string words into a single byte string, quoting words when necessary. Consecutive words are separated by a single space. Uses default settings and returns a QuoteError::Nul error if a NUL byte is encountered. ```APIDOC ## Function: try_join ### Description Convenience function that consumes an iterable of words and turns it into a single byte string, quoting words when necessary. Consecutive words will be separated by a single space. Uses default settings. The only error that can be returned is `QuoteError::Nul`. Equivalent to `Quoter::new().join(words)`. The string equivalent is `shlex::try_join`. ### Signature ```rust pub fn try_join<'a, I: IntoIterator<Item = &'a [u8]>>( words: I, ) -> Result<Vec<u8>, QuoteError> ``` ### Parameters - **words** (`I: IntoIterator<Item = &'a [u8]>`) - Required - An iterable of byte string slices to join. ### Return Value - `Result<Vec<u8>, QuoteError>` - On success, returns a `Vec<u8>` containing the joined byte string. On failure, returns `QuoteError::Nul`. ### Errors - `QuoteError::Nul` - Returned when a NUL byte is encountered in the input words. ### Notes - Uses default settings. - Equivalent to `Quoter::new().join(words)`. - The string equivalent is `shlex::try_join`. ``` -------------------------------- ### Shlex Source: https://docs.rs/shlex/latest/shlex/struct.Shlex.html Documentation for the Shlex struct, including its constructors and iterator trait implementations. ```APIDOC ## Struct Shlex ### Description An iterator that takes an input string and splits it into the words using the same syntax as the POSIX shell. ### Implementations #### `pub fn new(in_str: &'a str) -> Self` Creates a new `Shlex` iterator from a string slice. #### `pub unsafe fn from_bytes(bytes: Shlex<'a>) -> Self` Creates a `Shlex` from a `bytes::Shlex`. The parameter must have been constructed from valid UTF-8. #### `pub unsafe fn as_bytes_mut(&mut self) -> &mut Shlex<'a>` Returns a mutable reference to the underlying `bytes::Shlex`. If the returned reference is reassigned, the new `bytes::Shlex` must have been constructed from valid UTF-8. ### Trait Implementations #### `impl<'a> Deref for Shlex<'a>` - `type Target = Shlex<'a>` - `fn deref(&self) -> &Self::Target` #### `impl Iterator for Shlex<'_>` - `type Item = String` - `fn next(&mut self) -> Option<String>` - `fn size_hint(&self) -> (usize, Option<usize>)` - `fn count(self) -> usize` - `fn last(self) -> Option<Self::Item>` - `fn nth(&mut self, n: usize) -> Option<Self::Item>` - `fn step_by(self, step: usize) -> StepBy<Self>` - `fn chain<U>(self, other: U) -> Chain<Self, <U as IntoIterator>::IntoIter>` - `fn zip<U>(self, other: U) -> Zip<Self, <U as IntoIterator>::IntoIter>` - `fn map<B, F>(self, f: F) -> Map<Self, F>` - `fn for_each<F>(self, f: F)` - `fn filter<P>(self, predicate: P) -> Filter<Self, P>` - `fn filter_map<B, F>(self, f: F) -> FilterMap<Self, F>` - `fn enumerate(self) -> Enumerate<Self>` - `fn peekable(self) -> Peekable<Self>` ``` -------------------------------- ### inspect Source: https://docs.rs/shlex/latest/shlex/bytes/struct.Shlex.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Does something with each element of an iterator, passing the value on. ```APIDOC ## inspect ### Description Does something with each element of an iterator, passing the value on. ### Signature ```rust fn inspect<F>(self, f: F) -> Inspect<Self, F> where Self: Sized, F: FnMut(&Self::Item), ``` ### Parameters - **f** (F) - Required - A closure that is called with a reference to each item. ### Returns - **Inspect<Self, F>** - An iterator adapter that yields the original items after calling `f` on each. ### Notes - Available since Rust 1.0.0 (const: unstable). ``` -------------------------------- ### map_windows Source: https://docs.rs/shlex/latest/shlex/bytes/struct.Shlex.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Calls the given function f for each contiguous window of size N over self and returns an iterator over the outputs of f. Like slice::windows(), the windows during mapping overlap as well. ```APIDOC ## map_windows ### Description Calls the given function `f` for each contiguous window of size `N` over `self` and returns an iterator over the outputs of `f`. Like `slice::windows()`, the windows during mapping overlap as well. ### Signature ```rust fn map_windows<F, R, const N: usize>(self, f: F) -> MapWindows<Self, F, N> where Self: Sized, F: FnMut(&[Self::Item; N]) -> R, ``` ### Parameters - **f** (F) - Required - A closure that takes a reference to an array of `N` items and returns a value `R`. ### Returns - **MapWindows<Self, F, N>** - An iterator adapter that yields the results of `f` for each window. ### Notes - This is a nightly-only experimental API (`iter_map_windows`). ``` -------------------------------- ### pub fn join<'a, I: IntoIterator<Item = &'a [u8]>>(&self, words: I) -> Result<Vec<u8>, QuoteError> Source: https://docs.rs/shlex/latest/shlex/bytes/struct.Quoter.html Convenience function that consumes an iterable of words and turns it into a single byte string, quoting words when necessary. Consecutive words will be separated by a single space. ```APIDOC ## pub fn join<'a, I: IntoIterator<Item = &'a [u8]>>(&self, words: I) -> Result<Vec<u8>, QuoteError> ### Description Convenience function that consumes an iterable of words and turns it into a single byte string, quoting words when necessary. Consecutive words will be separated by a single space. ### Method join ### Signature `pub fn join<'a, I: IntoIterator<Item = &'a [u8]>>(&self, words: I) -> Result<Vec<u8>, QuoteError>` ### Parameters - **words** (I) - Required - An iterable of byte string slices to join. ### Returns - `Result<Vec<u8>, QuoteError>` - The joined byte string, or an error if quoting fails. ``` -------------------------------- ### bytes module structs Source: https://docs.rs/shlex/latest/shlex/bytes/index.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E Structs for splitting and quoting byte strings with configurable behavior. ```APIDOC ## [Struct] Shlex ### Description An iterator that takes an input byte string and splits it into the words using the same syntax as the POSIX shell. ### Constructor `pub fn new(input: &[u8]) -> Shlex` ### Methods - `next(&mut self) -> Option<Vec<u8>>` - Returns the next word, or `None` when the input is exhausted. ### Example ```rust use shlex::bytes::Shlex; let mut it = Shlex::new(b"foo bar"); assert_eq!(it.next(), Some(b"foo".to_vec())); assert_eq!(it.next(), Some(b"bar".to_vec())); assert_eq!(it.next(), None); ``` ``` ```APIDOC ## [Struct] Quoter ### Description A more configurable interface to quote strings. If you only want the default settings you can use the convenience functions `try_quote` and `try_join`. ### Constructor `pub fn new() -> Quoter` ### Methods - `quote(&self, word: &[u8]) -> Cow<[u8]>` - Quotes a word according to the configured settings. - `join(&self, words: &[&[u8]]) -> Vec<u8>` - Joins words with quoting as needed. ### Example ```rust use shlex::bytes::Quoter; let q = Quoter::new(); let quoted = q.quote(b"foo bar"); assert_eq!(quoted, b"'foo bar'"); ``` ``` -------------------------------- ### try_join Source: https://docs.rs/shlex/latest/shlex/all.html?search= Joins a list of words into a single string, quoting as necessary. This function is part of the shlex crate's public API. ```APIDOC ## try_join ### Description Joins a list of words into a single string, quoting as necessary. ### Function `pub fn try_join<'a, I, T>(words: I) -> Result<String, QuoteError>` ### Parameters - **words** (I) - An iterator over word-like items (e.g., `&str` or `String`). ### Returns A `Result` containing the joined string on success, or a `QuoteError` on failure. ``` -------------------------------- ### pub fn split(in_bytes: &[u8]) -> Option<Vec<Vec<u8>>> Source: https://docs.rs/shlex/latest/shlex/bytes/fn.split.html?search= Convenience function that consumes the whole byte string at once. Returns None if the input was erroneous. ```APIDOC ## Function: split ### Description Convenience function that consumes the whole byte string at once. Returns None if the input was erroneous. ### Signature pub fn split(in_bytes: &[u8]) -> Option<Vec<Vec<u8>>> ### Parameters - **in_bytes** (&[u8]) - Required - The byte string to parse. ### Return Value - **Option<Vec<Vec<u8>>>** - Returns Some containing the parsed tokens as a vector of byte vectors, or None if the input was erroneous. ### Example ```rust let result = shlex::bytes::split(b"some input"); ``` ``` -------------------------------- ### split Source: https://docs.rs/shlex/latest/shlex/bytes/index.html Convenience function that consumes the whole byte string at once. Returns None if the input was erroneous. ```APIDOC ## split ### Description Convenience function that consumes the whole byte string at once. Returns None if the input was erroneous. ### Function `split` ### Parameters - **input** (byte string) - Required - The byte string to split into words. ### Returns - `Option<Vec<Vec<u8>>>` - `None` if the input was erroneous, otherwise a vector of words. ### Example ```rust use shlex::bytes::split; let words = split(b"hello world").unwrap(); assert_eq!(words, vec![b"hello".to_vec(), b"world".to_vec()]); ``` ``` -------------------------------- ### Demonstration of `\xa0` as word separator Source: https://docs.rs/shlex/latest/shlex/quoting_warning/index.html Shows that on Bash on macOS with a UTF-8 locale, the byte `\xa0` is treated as a word separator, causing `ls` to see two arguments. ```shell $ echo -e 'ls a\xa0b' | bash ls: a: No such file or directory ls: b: No such file or directory ``` -------------------------------- ### pub fn allow_nul(self, allow: bool) -> Self Source: https://docs.rs/shlex/latest/shlex/bytes/struct.Quoter.html Sets whether to allow nul bytes. By default they are not allowed and will result in an error of `QuoteError::Nul`. ```APIDOC ## pub fn allow_nul(self, allow: bool) -> Self ### Description Sets whether to allow nul bytes. By default they are not allowed and will result in an error of `QuoteError::Nul`. ### Method allow_nul ### Signature `pub fn allow_nul(self, allow: bool) -> Self` ### Parameters - **allow** (bool) - Required - Whether to allow nul bytes. ### Returns - `Self` - The `Quoter` instance with the updated setting. ```
