CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-shlex

Node.js port of Python's shlex shell-like lexer for quoting and parsing shell commands

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

shlex

shlex is a Node.js port of Python's shlex shell-like lexer that provides utilities for safely quoting, parsing, and splitting shell command strings. It handles quotation marks, escape characters, and whitespace following POSIX shell conventions, with support for ANSI C-style quotes ($'...') and locale-specific translation strings ($"...").

Package Information

  • Package Name: shlex
  • Package Type: npm
  • Language: JavaScript (ESM)
  • Installation: npm install shlex

Core Imports

import { split, quote, join } from "shlex";

For older Node.js versions or mixed environments:

import * as shlex from "shlex";
// Usage: shlex.split(), shlex.quote(), shlex.join()

Basic Usage

import { split, quote, join } from "shlex";

// Split shell command string into array
const args = split('rm -f "/path with spaces/file.txt"');
// Result: ['rm', '-f', '/path with spaces/file.txt']

// Quote individual arguments safely
const safeArg = quote("can't touch this");
// Result: 'can'"'"'t touch this'

// Join array of arguments into shell command
const command = join(['ls', '-al', '/Volumes/My Drive']);
// Result: 'ls -al \'/Volumes/My Drive\''

Architecture

shlex operates in POSIX mode and consists of:

  • Lexer Engine: Internal Shlexer class that tokenizes shell strings with configurable quote, escape, and whitespace characters
  • ANSI C Quote Support: Handles $'...' strings with escape sequences (\n, \t, \x, \u, etc.)
  • Locale Quote Support: Processes $"..." locale-specific translation strings (treated as literal in C/POSIX locale)
  • Escape Processing: Supports various escape patterns including octal, hexadecimal, Unicode, and control characters

Capabilities

String Splitting

Parses shell command strings into arrays of individual arguments, properly handling quotes and escape sequences.

/**
 * Splits a given string using shell-like syntax. This function is the inverse
 * of shlex.join().
 * @param s - String to split using shell-like syntax
 * @returns Array of strings representing parsed tokens
 * @throws Error when encountering unclosed quoted strings or incomplete escape sequences
 */
function split(s: string): string[];

Usage Examples:

import { split } from "shlex";

// Basic splitting
split('ls -al /');
// Result: ['ls', '-al', '/']

// Quoted arguments
split('rm -f "/Volumes/Macintosh HD"');
// Result: ['rm', '-f', '/Volumes/Macintosh HD']

// Mixed quotes
split(`echo 'single quotes' "double quotes"`);
// Result: ['echo', 'single quotes', 'double quotes']

// ANSI C quotes with escape sequences
split(`echo $'line1\\nline2\\t\\x41'`);
// Result: ['echo', 'line1\nline2\tA']

// ANSI C quotes with control characters and Unicode
split(`echo $'\\ca\\u2603\\x7f'`);
// Result: ['echo', '\x01☃\x7f']

// Locale translation quotes
split(`echo $"localized string"`);
// Result: ['echo', 'localized string']

// Escaped characters
split('echo hello\\ world');
// Result: ['echo', 'hello world']

String Quoting

Escapes potentially unsafe strings by wrapping them in quotes, ensuring they can be safely used in shell commands.

/**
 * Escapes a potentially shell-unsafe string using quotes.
 * @param s - String to quote/escape for shell safety
 * @returns Shell-escaped string safe for use in shell commands
 */
function quote(s: string): string;

Usage Examples:

import { quote } from "shlex";

// Safe strings remain unquoted
quote("simple");
// Result: 'simple'

// Unsafe characters get quoted
quote("hello world");
// Result: "'hello world'"

// Empty strings
quote("");
// Result: "''"

// Strings with single quotes
quote("can't");
// Result: 'can'"'"'t'

// Complex unsafe strings
quote('file with "quotes" and spaces');
// Result: '\'file with "quotes" and spaces\''

Array Joining

Combines an array of arguments into a properly quoted shell command string, ensuring each argument is safely escaped.

/**
 * Concatenate the tokens of the list args and return a string. This function
 * is the inverse of shlex.split().
 * The returned value is shell-escaped to protect against injection vulnerabilities.
 * @param args - Array of strings to join into a shell command
 * @returns Shell-escaped string with arguments properly quoted and joined with spaces
 * @throws TypeError when args is not an array
 */
function join(args: readonly string[]): string;

Usage Examples:

import { join } from "shlex";

// Simple arguments
join(['ls', '-al', '/']);
// Result: 'ls -al /'

// Arguments requiring quotes
join(['rm', '-f', '/Volumes/Macintosh HD']);
// Result: "rm -f '/Volumes/Macintosh HD'"

// Mixed safe and unsafe arguments
join(['echo', 'hello', 'world with spaces']);
// Result: "echo hello 'world with spaces'"

// Error handling - parameter validation
join("not an array");
// Throws: TypeError: args should be an array

join(null);
// Throws: TypeError: args should be an array

join(undefined);
// Throws: TypeError: args should be an array

Error Handling

  • split(): Throws Error for unclosed quoted strings or incomplete escape sequences at end of input
  • quote(): Never throws exceptions, handles all string inputs including empty strings and special characters
  • join(): Throws TypeError if the args parameter is not an array

Advanced Features

ANSI C Quote Support

shlex supports ANSI C-style quoting ($'...') with comprehensive escape sequence handling:

  • Literal characters: \\, \', \", \?
  • Non-printable ASCII: \a (bell), \b (backspace), \e/\E (escape), \f (form feed), \n (newline), \r (carriage return), \t (tab), \v (vertical tab)
  • Octal bytes: \nnn (1-3 octal digits, e.g., \007 → bell, \101 → 'A')
  • Hexadecimal bytes: \xnn (1-2 hex digits, e.g., \x41 → 'A', \xff → ÿ)
  • Unicode code units: \unnnn (1-4 hex digits), \Unnnnnnnn (1-8 hex digits, e.g., \u2603 → ☃)
  • Control characters: \cx (control-x sequences, e.g., \ca → control-A, \c? → DEL)

Locale Translation Support

Locale-specific translation strings ($"...") are supported but treated literally (as if locale is C/POSIX), meaning no actual translation occurs.

Compatibility

  • Node.js: Requires ES6 module support (package type is "module") - Node.js v12.20.0+ or v14.14.0+
  • TypeScript: Full type definitions included in shlex.d.ts
  • Shell Compatibility: Follows POSIX shell quoting conventions
  • Performance: Optimized for typical command-line parsing workloads with linear time complexity

docs

index.md

tile.json