shell-quote

shell-quote

Parse and quote shell commands.

example

quote

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"'

parse

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" ]

parse with ANSI-C quoting

var parse = require('shell-quote/parse');
var xs = parse("echo $'it\\'s a \\n test'");
console.dir(xs);

output

[ 'echo', "it's a \n test" ]

parse with an environment variable

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

output

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

parse with custom escape character

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

output

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

parse with unquoted variable splitting

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

output

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

parsing shell operators

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

output:

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

parsing shell comment

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

output:

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

methods

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

quote(args)

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, a pattern/comment containing line terminators, or a string containing line terminators anywhere after a { comment } 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.

parse(cmd, env={})

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.

Bash ANSI-C quoting ($'...') is supported: escape sequences (such as \n, \t, \\, \', \", \xHH, \uHHHH, \UHHHHHHHH, \nnn, and \cx) are decoded, an unrecognized escape keeps its backslash, and the contents are never word-split and never variable-expanded, so ${VAR} inside $'...' stays literal. As in bash, $'...' is not special inside double or single quotes, and a NUL ends the string. Since the result is a JavaScript string, \xHH and \nnn produce the character with that code (U+0000 to U+00FF), not a raw byte.

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' ]

install

With npm do:

npm install shell-quote

license

MIT

Similar packages

Other packages similar to shell-quote

shelljs

ShellJS is a portable (Windows/Linux/OS X) implementation of Unix shell commands on top of the Node.js API. It provides a higher-level API for executing shell commands and includes utilities for file manipulation, which makes it more comprehensive than shell-quote.

execa

Execa is a process execution tool that aims to be a better 'child_process'. It has a promise-based interface and includes features like automatic escaping of arguments, which makes it similar to shell-quote in terms of handling command execution, but with a different API and additional capabilities like returning stdout and stderr.

cross-spawn

Cross-spawn is a cross-platform solution to the issue of spawning child processes (such as shell commands) in Node.js. It automatically handles quoting and escaping of arguments for the target platform's shell, providing similar functionality to shell-quote but focused on child process creation.