Crate `shlex`

Parse strings like, and escape strings for, POSIX shells.

Same idea as (but implementation not directly based on) the Python shlex module.

Disabling the std feature (which is enabled by default) will allow the crate to work in no_std environments, where the alloc crate, and a global allocator, are available.

Warning

The try_quote/try_join family of APIs does not quote control characters (because they cannot be quoted portably).

This is fully safe in noninteractive contexts, like shell scripts and sh -c arguments (or even scripts sourced from interactive shells).

But if you are quoting for human consumption, you should keep in mind that ugly inputs produce ugly outputs (which may not be copy-pastable).

And if by chance you are piping the output of try_quote/try_join directly to the stdin of an interactive shell, you should stop, because control characters can lead to arbitrary command injection.

For more information, and for information about more minor issues, please see [quoting_warning].

Compatibility

This crate's quoting functionality tries to be compatible with any POSIX-compatible shell; it's tested against bash, zsh, dash, Busybox ash, and mksh, plus fish (which is not POSIX-compatible but close enough).

It also aims to be compatible with Python shlex and C wordexp.

Modules

bytes Shlex and friends for byte strings.
quoting_warning A more detailed version of the warning at the top level about the quote/join family of APIs.

Structs

Quoter 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.
Shlex An iterator that takes an input string and splits it into the words using the same syntax as the POSIX shell.

Enums

QuoteError Errors from Quoter::quote, Quoter::join, etc. (and their bytes counterparts).

Functions

join 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.
quote Given a single word, return a string suitable to encode it as a shell argument.
split Convenience function that consumes the whole string at once. Returns None if the input was erroneous.
try_join 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.
try_quote Given a single word, return a string suitable to encode it as a shell argument.