shellwords

What is shellwords?

The shellwords package is designed to manipulate strings according to the word parsing rules of the UNIX Bourne shell. It provides functionality for splitting a string into an array of tokens in the same way the shell would and for escaping and joining words into a single string that can be safely used in a shell command.

What are shellwords's main functionalities?

Splitting a string into an array of tokens

This feature allows you to split a command line string into an array of tokens, similar to how a UNIX shell would. It's useful for parsing command line arguments or processing shell commands within a Node.js application.

"const shellwords = require('shellwords');
const cmd = 'ls -la /some/path with spaces';
const tokens = shellwords.split(cmd);
console.log(tokens);"

Escaping and joining words into a shell command

This feature enables you to take an array of command line arguments and join them into a single string that is safe to use in a shell command. It automatically escapes any characters that have special meaning in the shell, making it easier to construct shell commands programmatically.

"const shellwords = require('shellwords');
const args = ['ls', '-la', '/some/path with spaces'];
const cmd = shellwords.join(args);
console.log(cmd);"

Other packages similar to shellwords

shell-quote

Similar to shellwords, shell-quote provides functionality for quoting and parsing shell commands. It differs in its approach to handling special characters and offers more customization options for parsing, making it a versatile alternative for complex shell command manipulations.

shlex

Shlex is a port of Python's shlex module for Node.js. It offers similar functionality to shellwords, focusing on splitting shell commands into tokens. Shlex might be preferred in environments where developers are more familiar with Python's way of handling shell strings.

README

Shellwords

Shellwords provides functions to manipulate strings according to the word parsing rules of the UNIX Bourne shell. It is based on the Ruby module of the same name.

Installation

With npm:

npm install shellwords

With pnpm:

pnpm add shellwords

With Yarn:

yarn add shellwords

API

Shellwords exports the following functions, shown here in the TypeScript declaration file format.

/**
 * Splits a string into an array of tokens in the same way the UNIX Bourne shell does.
 *
 * @param line A string to split.
 * @returns An array of the split tokens.
 */
export declare const split: (line?: string) => string[];

/**
 * Escapes a string so that it can be safely used in a Bourne shell command line.
 *
 * @param str A string to escape.
 * @returns The escaped string.
 */
export declare const escape: (str?: string) => string;

/**
 * Builds a command line string from an argument list.
 *
 * @param array An array of string arguments.
 * @returns The command line string.
 */
export const join = (array: string[]) => string;

Example

import { escape, split, join } from "shellwords";

split("foo 'bar baz'");
// ["foo", "bar baz"]

escape("What's up, yo?");
// 'What\\\'s\\ up,\\ yo\\?'

join(["What's", "up,", "gang?");
// 'What\\\'s up, gang\\?'

Legal

shellwords is released under the MIT license. See LICENSE.