0
# shlex
1

2
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 (`$"..."`).
3

4
## Package Information
5

6
- **Package Name**: shlex
7
- **Package Type**: npm
8
- **Language**: JavaScript (ESM)
9
- **Installation**: `npm install shlex`
10

11
## Core Imports
12

13
```javascript
14
import { split, quote, join } from "shlex";
15
```
16

17
For older Node.js versions or mixed environments:
18

19
```javascript
20
import * as shlex from "shlex";
21
// Usage: shlex.split(), shlex.quote(), shlex.join()
22
```
23

24
## Basic Usage
25

26
```javascript
27
import { split, quote, join } from "shlex";
28

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

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

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

42
## Architecture
43

44
shlex operates in POSIX mode and consists of:
45

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

51
## Capabilities
52

53
### String Splitting
54

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

57
```javascript { .api }
58
/**
59
 * Splits a given string using shell-like syntax. This function is the inverse
60
 * of shlex.join().
61
 * @param s - String to split using shell-like syntax
62
 * @returns Array of strings representing parsed tokens
63
 * @throws Error when encountering unclosed quoted strings or incomplete escape sequences
64
 */
65
function split(s: string): string[];
66
```
67

68
**Usage Examples:**
69

70
```javascript
71
import { split } from "shlex";
72

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

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

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

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

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

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

97
// Escaped characters
98
split('echo hello\\ world');
99
// Result: ['echo', 'hello world']
100
```
101

102
### String Quoting
103

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

106
```javascript { .api }
107
/**
108
 * Escapes a potentially shell-unsafe string using quotes.
109
 * @param s - String to quote/escape for shell safety
110
 * @returns Shell-escaped string safe for use in shell commands
111
 */
112
function quote(s: string): string;
113
```
114

115
**Usage Examples:**
116

117
```javascript
118
import { quote } from "shlex";
119

120
// Safe strings remain unquoted
121
quote("simple");
122
// Result: 'simple'
123

124
// Unsafe characters get quoted
125
quote("hello world");
126
// Result: "'hello world'"
127

128
// Empty strings
129
quote("");
130
// Result: "''"
131

132
// Strings with single quotes
133
quote("can't");
134
// Result: 'can'"'"'t'
135

136
// Complex unsafe strings
137
quote('file with "quotes" and spaces');
138
// Result: '\'file with "quotes" and spaces\''
139
```
140

141
### Array Joining
142

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

145
```javascript { .api }
146
/**
147
 * Concatenate the tokens of the list args and return a string. This function
148
 * is the inverse of shlex.split().
149
 * The returned value is shell-escaped to protect against injection vulnerabilities.
150
 * @param args - Array of strings to join into a shell command
151
 * @returns Shell-escaped string with arguments properly quoted and joined with spaces
152
 * @throws TypeError when args is not an array
153
 */
154
function join(args: readonly string[]): string;
155
```
156

157
**Usage Examples:**
158

159
```javascript
160
import { join } from "shlex";
161

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

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

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

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

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

181
join(undefined);
182
// Throws: TypeError: args should be an array
183
```
184

185
## Error Handling
186

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

191
## Advanced Features
192

193
### ANSI C Quote Support
194

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

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

204
### Locale Translation Support
205

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

208
### Compatibility
209

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