Parse and quote shell commands.

var quote = require('shell-quote/quote');
var s = quote([ 'a', 'b c d', '$f', '"g"' ]);
console.log(s);

output

a 'b c d' \$f '"g"'

var parse = require('shell-quote/parse');
var xs = parse('a "b c" \\$def \'it\'\\\'\'s great\'');
console.dir(xs);

output

[ 'a', 'b c', '$def', "it's great" ]

var parse = require('shell-quote/parse');
var xs = parse('beep --boop="$PWD"', { PWD: '/home/robot' });
console.dir(xs);

output

[ 'beep', '--boop=/home/robot' ]

var parse = require('shell-quote/parse');
var xs = parse('beep ^--boop="$PWD"', { PWD: '/home/robot' }, { escape: '^' });
console.dir(xs);

output

[ 'beep', '--boop=/home/robot' ]

var parse = require('shell-quote/parse');
var xs = parse('a $T', { T: 'c d' }, { splitUnquoted: true });
console.dir(xs);

output

[ 'a', 'c', 'd' ]

var parse = require('shell-quote/parse');
var xs = parse('beep || boop > /byte');
console.dir(xs);

output:

[ 'beep', { op: '||' }, 'boop', { op: '>' }, '/byte' ]

var parse = require('shell-quote/parse');
var xs = parse('beep > boop # > kaboom');
console.dir(xs);

output:

[ 'beep', { op: '>' }, 'boop', { comment: ' > kaboom' } ]

var quote = require('shell-quote/quote');
var parse = require('shell-quote/parse');

Return a quoted string for the array args suitable for using in shell commands.

Each entry of args may be a string, or one of the object shapes that parse emits: { op } (where op is one of the control operators ||, &&, ;;, |&, <(, <<<, >>, >&, <&, &, ;, (, ), |, <, >), { op: 'glob', pattern }, or { comment }. Any other object shape, an unrecognized op, or a pattern/comment containing line terminators throws a TypeError.

The output is POSIX shell (sh/bash) quoting. It is not valid for Windows cmd.exe or PowerShell, whose rules differ and, for cmd.exe, are not solvable in the general case. On Windows, do not build a shell command string from this output; instead pass an argument array to a non-shell API such as child_process.execFile or spawn (or the cross-spawn package), which does no shell parsing and needs no quoting.

Use the returned string verbatim as shell input. It is already a complete, escaped shell word (or words); do not wrap it in additional quotes or embed it in eval '...'. Re-quoting the output (for example, placing it inside single quotes) turns its backslash escapes into literal characters and corrupts the value.

Return an array of arguments from the quoted string cmd.

Interpolate embedded bash-style $VARNAME and ${VARNAME} variables with the env object which like bash will replace undefined variables with "".

By default an expanded variable is a single token even when unquoted. Pass { splitUnquoted: true } to split an unquoted expansion into multiple tokens the way a shell performs field splitting, using the default IFS (space, tab, newline). Pass a string to use its characters as the IFS instead (for example { splitUnquoted: ':' }). A quoted expansion ("$VAR") is never split.

Only simple $VARNAME and ${VARNAME} interpolation is supported. Bash parameter expansion beyond a plain variable name is not evaluated: forms such as array subscripts (${arr[i]}), length (${#arr[@]}), and modifiers (${var:-default}, ${var/a/b}) are treated as an unknown variable and expand to "", while arithmetic ($((...))) and command substitution ($(...)) are not interpreted. Whitespace inside ${...} throws a Bad substitution error.

env is usually an object but it can also be a function to perform lookups. When env(key) returns a string, its result will be output just like env[key] would. When env(key) returns an object, it will be inserted into the result array like the operator objects.

When a bash operator is encountered, the element in the array with be an object with an "op" key set to the operator string. For example:

'beep || boop > /byte'

parses as:

[ 'beep', { op: '||' }, 'boop', { op: '>' }, '/byte' ]

With npm do:

npm install shell-quote

MIT