shell-quote

What is shell-quote?

The shell-quote npm package is used for quoting and parsing shell commands. It can handle various shell operations such as escaping special characters, joining command-line arguments into a single string, and parsing command-line strings into an array of arguments or a function to be executed.

What are shell-quote's main functionalities?

Quoting arguments

This feature allows you to quote an array of command-line arguments into a single string that can be safely used in a shell command. It handles escaping of special characters and quotes as necessary.

var quote = require('shell-quote').quote;
var args = ['some string', 'another "string"', '$pecial'];
console.log(quote(args));

Parsing command-line strings

This feature is used to parse a command-line string into an array of arguments, taking into account the quoting and escaping rules of a typical Unix shell.

var parse = require('shell-quote').parse;
var cmd = "echo 'hello world'";
console.log(parse(cmd));

Executing parsed commands

This feature allows you to parse a command and then execute it with a given set of environment variables or other options. It can be useful for dynamically constructing and executing shell commands within a Node.js application.

var parse = require('shell-quote').parse;
var op = parse('echo $USER');
op[0]({ USER: 'alice' }); // executes the command with the given environment variable

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.

README

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

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.

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

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

Changelog

v1.8.2 - 2024-11-27

Fixed

• [Fix] quote: preserve empty strings #18

Commits

• [meta] fix changelog tags 0fb9fd8
• [actions] split out node 10-20, and 20+ 819bd84
• [Dev Deps] update @ljharb/eslint-config, auto-changelog, npmignore, tape fc56408
• [actions] update npm for windows tests fdeb0fd
• [Dev Deps] update @ljharb/eslint-config, aud, tape b8a4a3b
• [actions] prevent node 14 on ARM mac from failing 9eecafc
• [meta] exclude more files from the package 4044e7f
• [Tests] replace aud with npm audit 8cfdbd8
• [meta] add missing engines.node 843820e
• [Dev Deps] add missing peer dep 4c3b88d
• [Dev Deps] pin jackspeak since 2.1.2+ depends on npm aliases, which kill the install process in npm < 6 80322ed