0
# Shellwords
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: shellwords
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install shellwords`
10

11
## Core Imports
12

13
```typescript
14
import { split, escape, join } from "shellwords";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { split, escape, join } = require("shellwords");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { split, escape, join } from "shellwords";
27

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

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

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

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

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

51
## Architecture
52

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

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

59
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.
60

61
## Capabilities
62

63
### String Tokenization
64

65
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.
66

67
```typescript { .api }
68
/**
69
 * Splits a string into an array of tokens in the same way the UNIX Bourne shell does.
70
 * @param line - A string to split (defaults to empty string)
71
 * @returns An array of the split tokens
72
 * @throws Error with message "Unmatched quote: {line}" when quotes are unmatched
73
 */
74
function split(line?: string): string[];
75
```
76

77
**Usage Examples:**
78

79
```typescript
80
// Basic word splitting
81
split("foo bar baz");
82
// Result: ["foo", "bar", "baz"]
83

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

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

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

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

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

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

107
// Empty and edge case handling
108
split(""); // Result: []
109
split("   "); // Result: []
110
split("''"); // Result: [""]
111
```
112

113
### String Escaping
114

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

117
```typescript { .api }
118
/**
119
 * Escapes a string so that it can be safely used in a Bourne shell command line.
120
 * @param str - A string to escape (defaults to empty string)
121
 * @returns The escaped string
122
 */
123
function escape(str?: string): string;
124
```
125

126
**Usage Examples:**
127

128
```typescript
129
// Basic escaping
130
escape("What's up, yo?");
131
// Result: "What\\'s\\ up,\\ yo\\?"
132

133
// Special characters
134
escape("foo '\"' bar");
135
// Result: "foo\\ \\'\\\"\\'\\ bar"
136

137
// Multibyte characters
138
escape("あい");
139
// Result: "\\あ\\い"
140

141
// Newlines converted to quoted form
142
escape("line1\nline2");
143
// Result: "line1'\n'line2"
144
```
145

146
### Command Building
147

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

150
```typescript { .api }
151
/**
152
 * Builds a command line string from an argument list.
153
 * @param array - An array of string arguments
154
 * @returns The command line string
155
 */
156
function join(array: string[]): string;
157
```
158

159
**Usage Examples:**
160

161
```typescript
162
// Basic command building
163
join(["git", "commit", "-m", "Fix bug"]);
164
// Result: "git commit -m Fix\\ bug"
165

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

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