or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-shellwords

Manipulate strings according to the word parsing rules of the UNIX Bourne shell

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/shellwords@1.1.x

To install, run

npx @tessl/cli install tessl/npm-shellwords@1.1.0

index.mddocs/

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 and offers three core functions for shell-compatible string parsing, escaping, and command building.

Package Information

  • Package Name: shellwords
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install shellwords

Core Imports

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

For CommonJS:

const { split, escape, join } = require("shellwords");

Basic Usage

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

// Split shell command string into tokens
const tokens = split("foo 'bar baz' --verbose");
// Result: ["foo", "bar baz", "--verbose"]

// Escape string for safe shell usage
const escaped = escape("What's up, yo?");
// Result: "What\\'s\\ up,\\ yo\\?"

// Build command string from argument array
const command = join(["git", "commit", "-m", "Fix bug"]);
// Result: "git commit -m Fix\\ bug"

// Complex workflow example
const userInput = "file with spaces.txt";
const safeCommand = join(["ls", "-la", userInput]);
// Result: "ls -la file\\ with\\ spaces.txt"

// Parsing complex shell commands
const complexCmd = `git commit -m "Initial commit" --author="John Doe <john@example.com>"`;
const parsed = split(complexCmd);
// Result: ["git", "commit", "-m", "Initial commit", "--author=John Doe <john@example.com>"]

Architecture

Shellwords is designed around three core functional operations that work together to provide complete shell string manipulation:

  • Tokenization (split): Parses shell-formatted strings into individual arguments using a regex-based state machine that handles quotes, escapes, and whitespace
  • Escaping (escape): Converts arbitrary strings into shell-safe format by escaping special characters and wrapping newlines in quotes
  • Command Building (join): Combines individual arguments into a properly escaped shell command string

The library follows UNIX Bourne shell parsing rules exactly, making it compatible with bash, sh, and other POSIX-compliant shells. All functions are pure (no side effects) and handle edge cases like empty strings, unmatched quotes, and multibyte characters.

Capabilities

String Tokenization

Splits a string into an array of tokens in the same way the UNIX Bourne shell does. Handles single quotes, double quotes, and escape sequences.

/**
 * Splits a string into an array of tokens in the same way the UNIX Bourne shell does.
 * @param line - A string to split (defaults to empty string)
 * @returns An array of the split tokens
 * @throws Error with message "Unmatched quote: {line}" when quotes are unmatched
 */
function split(line?: string): string[];

Usage Examples:

// Basic word splitting
split("foo bar baz");
// Result: ["foo", "bar", "baz"]

// Single quoted phrases
split("foo 'bar baz'");
// Result: ["foo", "bar baz"]

// Double quoted phrases
split('"foo bar" baz');
// Result: ["foo bar", "baz"]

// Escaped characters
split("foo\\ bar baz");
// Result: ["foo bar", "baz"]

// Escaped quotes within quotes
split('foo "bar\\" baz"');
// Result: ["foo", 'bar" baz']

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

// Error on unmatched quotes
split("foo 'bar baz"); // Throws Error: Unmatched quote: foo 'bar baz
split('foo "bar baz'); // Throws Error: Unmatched quote: foo "bar baz

// Empty and edge case handling
split(""); // Result: []
split("   "); // Result: []
split("''"); // Result: [""]

String Escaping

Escapes a string so that it can be safely used in a Bourne shell command line. Protects special characters and handles multibyte characters.

/**
 * Escapes a string so that it can be safely used in a Bourne shell command line.
 * @param str - A string to escape (defaults to empty string)
 * @returns The escaped string
 */
function escape(str?: string): string;

Usage Examples:

// Basic escaping
escape("What's up, yo?");
// Result: "What\\'s\\ up,\\ yo\\?"

// Special characters
escape("foo '\"' bar");
// Result: "foo\\ \\'\\\"\\'\\ bar"

// Multibyte characters
escape("あい");
// Result: "\\あ\\い"

// Newlines converted to quoted form
escape("line1\nline2");
// Result: "line1'\n'line2"

Command Building

Builds a command line string from an argument list by escaping each element and joining with spaces.

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

Usage Examples:

// Basic command building
join(["git", "commit", "-m", "Fix bug"]);
// Result: "git commit -m Fix\\ bug"

// Arguments with special characters
join(["foo", "'\"'", "bar"]);
// Result: "foo \\'\\\"\\' bar"

// Complex arguments
join(["echo", "Hello World!", ">", "output.txt"]);
// Result: "echo Hello\\ World\\! \\> output.txt"