shell-split/README.md

A lighterweight alternative to shell-quote

# shell-split

This is effectively a port of [go-shellquote][] to Node, because if you just want the string-tokenization characteristics of shell syntax, Node's [shell-quote][] has too many frills (such as operator recognition and variable substitution) that can make it harder to write/parse strings that may have unescaped shell-significant characters.

[go-shellquote]: https://github.com/kballard/go-shellquote
[shell-quote]: https://github.com/substack/node-shell-quote

## .split

Aliased as: .unquote, .unescape, .parse, the return of the module itself

Returns an array of strings specified by the input string.

Note that this function follows only basic shell-quoting rules, meaning that advanced features, such as non-literal backslash escapes (like `\n` for a newline) or substituted parameters (like `$HOME`), are **not** recognized (a `\n`, even with double-quotes, will be recognized as a literal 'n').

## .quote

Aliased as: .join, .escape, .stringify

This function backslash-excapes special characters within the string (the same ones from [go-shellquote][quote.go L24] plus closing braces), and surrounds it with double quotes if it contains whitespace or begins with a tilde (or is empty).

[quote.go L24]: https://github.com/kballard/go-shellquote/blob/master/quote.go#L24

If passed an array, this function will escape every item within the array as a shell-quoted string, then join them with single spaces.

Note that this function is mostly included to provide a similar API surface to the modules that inspired it (node-shell-quote and go-shellquote). Depending on your use case, there may well be simpler ways to make your strings shell-clean than this function (such as only escaping a particular problematic character): if such a technique is available, I recommend using that instead.

## Errors

Also attached to the exported module are `UnterminatedSingleQuoteError`, `UnterminatedDoubleQuoteError`, and `UnterminatedEscapeError`, if you wish to check for which error broke a parsing operation using the `instanceof` operator (though I'd recommend checking the `name` property instead).