0
# Text Processing Commands
1

2
Text manipulation and filtering commands for processing file contents, searching patterns, and transforming text data with Unix-style functionality.
3

4
## Capabilities
5

6
### echo - Display Text
7

8
Displays text to stdout with support for backslash escapes and newline control.
9

10
```javascript { .api }
11
/**
12
 * Display text to stdout
13
 * @param options - Command options
14
 * @param text - Text strings to display
15
 * @returns ShellString containing the output text
16
 */
17
function echo(options?: string, ...text: string[]): ShellString;
18
```
19

20
**Options:**
21
- `-e`: Interpret backslash escapes (default behavior)
22
- `-n`: Remove trailing newline from output
23

24
**Usage Examples:**
25

26
```javascript
27
// Simple text output
28
shell.echo('Hello world');
29

30
// Multiple arguments
31
shell.echo('Hello', 'world', '2023');
32

33
// No trailing newline
34
shell.echo('-n', 'No newline at end');
35

36
// Backslash escapes
37
shell.echo('Line 1\\nLine 2\\tTabbed');
38

39
// Capture output
40
const message = shell.echo('Status: OK');
41
```
42

43
### grep - Search Text
44

45
Searches for patterns in files using regular expressions, similar to Unix grep.
46

47
```javascript { .api }
48
/**
49
 * Search for patterns in files using regular expressions
50
 * @param options - Command options
51
 * @param regex - Regular expression or string pattern to search for
52
 * @param files - Files to search in
53
 * @returns ShellString containing matching lines or filenames
54
 */
55
function grep(options: string, regex: RegExp | string, ...files: string[]): ShellString;
56
function grep(regex: RegExp | string, ...files: string[]): ShellString;
57
function grep(options: string, regex: RegExp | string, files: string[]): ShellString;
58
function grep(regex: RegExp | string, files: string[]): ShellString;
59
```
60

61
**Options:**
62
- `-v`: Invert match (show non-matching lines)
63
- `-l`: Show only filenames with matches
64
- `-i`: Case-insensitive matching
65
- `-n`: Print line numbers with matches
66
- `-B <num>`: Show `<num>` lines before each result
67
- `-A <num>`: Show `<num>` lines after each result
68
- `-C <num>`: Show `<num>` lines before and after each result
69

70
**Usage Examples:**
71

72
```javascript
73
// Search for pattern in file
74
const matches = shell.grep('error', 'logfile.txt');
75

76
// Case-insensitive search
77
const caseInsensitive = shell.grep('-i', 'ERROR', 'logfile.txt');
78

79
// Invert match (show lines without pattern)
80
const nonMatches = shell.grep('-v', 'debug', 'logfile.txt');
81

82
// Show only filenames with matches
83
const filesWithMatches = shell.grep('-l', 'TODO', '*.js');
84

85
// Show line numbers
86
const withLineNumbers = shell.grep('-n', 'function', 'script.js');
87

88
// Show context lines (3 before and after)
89
const withContext = shell.grep('-C', 3, 'error', 'log.txt');
90

91
// Show lines before match
92
const beforeContext = shell.grep('-B', 2, 'function', 'script.js');
93

94
// Show lines after match  
95
const afterContext = shell.grep('-A', 5, 'TODO', 'notes.txt');
96

97
// Regular expression search
98
const regexMatches = shell.grep(/\\d{3}-\\d{3}-\\d{4}/, 'contacts.txt');
99

100
// Search multiple files
101
const multiFile = shell.grep('function', 'file1.js', 'file2.js');
102

103
// Chain with other commands
104
const jsErrors = shell.find('.').grep('\\.js$').grep('error');
105
```
106

107
### head - Display First Lines
108

109
Displays the first lines of files, useful for previewing file contents.
110

111
```javascript { .api }
112
/**
113
 * Display first lines of files
114
 * @param options - Options object with line count
115
 * @param files - Files to display
116
 * @returns ShellString containing first lines of files
117
 */
118
function head(options?: { '-n': number }, ...files: string[]): ShellString;
119
function head(...files: string[]): ShellString;
120
function head(options: { '-n': number }, files: string[]): ShellString;
121
function head(files: string[]): ShellString;
122
```
123

124
**Options:**
125
- `{'-n': number}`: Number of lines to display (default: 10)
126

127
**Usage Examples:**
128

129
```javascript
130
// Show first 10 lines (default)
131
const preview = shell.head('largefile.txt');
132

133
// Show first 5 lines
134
const first5 = shell.head({'-n': 5}, 'file.txt');
135

136
// Multiple files
137
const multiHead = shell.head({'-n': 3}, 'file1.txt', 'file2.txt');
138

139
// From array
140
const fromArray = shell.head({'-n': 20}, ['log1.txt', 'log2.txt']);
141
```
142

143
### sed - Stream Editor
144

145
Stream editor for filtering and transforming text using regular expressions and substitutions.
146

147
```javascript { .api }
148
/**
149
 * Stream editor for filtering and transforming text
150
 * @param options - Command options
151
 * @param searchRegex - Pattern to search for (RegExp or string)
152
 * @param replacement - Replacement text
153
 * @param files - Files to process
154
 * @returns ShellString containing processed text
155
 */
156
function sed(options: string, searchRegex: RegExp | string, replacement: string, ...files: string[]): ShellString;
157
function sed(searchRegex: RegExp | string, replacement: string, ...files: string[]): ShellString;
158
function sed(options: string, searchRegex: RegExp | string, replacement: string, files: string[]): ShellString;
159
function sed(searchRegex: RegExp | string, replacement: string, files: string[]): ShellString;
160
```
161

162
**Options:**
163
- `-i`: Edit files in-place (modifies original files)
164

165
**Usage Examples:**
166

167
```javascript
168
// Simple text substitution
169
const replaced = shell.sed('old_text', 'new_text', 'file.txt');
170

171
// Regular expression substitution
172
const regexReplace = shell.sed(/version_\\d+/, 'version_2', 'config.js');
173

174
// Global replacement (replace all occurrences)
175
const globalReplace = shell.sed(/old/g, 'new', 'file.txt');
176

177
// In-place editing
178
shell.sed('-i', 'BUILD_VERSION', 'v1.2.3', 'version.js');
179

180
// Remove lines (replace with empty string)
181
const removeLines = shell.sed(/^.*DEBUG.*$/gm, '', 'app.js');
182

183
// Multiple files
184
shell.sed('-i', /copyright 2022/g, 'copyright 2023', 'file1.js', 'file2.js');
185

186
// Chain with other commands
187
shell.cat('template.txt').sed('{{NAME}}', 'John').to('output.txt');
188
```
189

190
### sort - Sort Lines
191

192
Sorts lines in text files with various sorting options.
193

194
```javascript { .api }
195
/**
196
 * Sort lines in text files
197
 * @param options - Command options
198
 * @param files - Files to sort
199
 * @returns ShellString containing sorted lines
200
 */
201
function sort(options?: string, ...files: string[]): ShellString;
202
function sort(...files: string[]): ShellString;
203
function sort(options: string, files: string[]): ShellString;
204
function sort(files: string[]): ShellString;
205
```
206

207
**Options:**
208
- `-r`: Reverse sort order
209
- `-n`: Numeric sort (compare as numbers, not strings)
210

211
**Usage Examples:**
212

213
```javascript
214
// Basic alphabetical sort
215
const sorted = shell.sort('names.txt');
216

217
// Reverse sort
218
const reversed = shell.sort('-r', 'data.txt');
219

220
// Numeric sort
221
const numericSort = shell.sort('-n', 'numbers.txt');
222

223
// Sort multiple files
224
const multiSort = shell.sort('file1.txt', 'file2.txt');
225

226
// Chain with other commands
227
const sortedList = shell.ls().sort();
228

229
// Numeric reverse sort
230
const numReverse = shell.sort('-rn', 'scores.txt');
231
```
232

233
### tail - Display Last Lines
234

235
Displays the last lines of files, useful for monitoring log files and recent changes.
236

237
```javascript { .api }
238
/**
239
 * Display last lines of files
240
 * @param options - Options object with line count
241
 * @param files - Files to display
242
 * @returns ShellString containing last lines of files
243
 */
244
function tail(options?: { '-n': number }, ...files: string[]): ShellString;
245
function tail(...files: string[]): ShellString;
246
function tail(options: { '-n': number }, files: string[]): ShellString;
247
function tail(files: string[]): ShellString;
248
```
249

250
**Options:**
251
- `{'-n': number}`: Number of lines to display (default: 10)
252

253
**Usage Examples:**
254

255
```javascript
256
// Show last 10 lines (default)
257
const lastLines = shell.tail('logfile.txt');
258

259
// Show last 5 lines
260
const last5 = shell.tail({'-n': 5}, 'file.txt');
261

262
// Multiple files
263
const multiTail = shell.tail({'-n': 3}, 'log1.txt', 'log2.txt');
264

265
// Monitor recent log entries
266
const recentErrors = shell.tail({'-n': 50}, 'error.log');
267

268
// From array
269
const fromArray = shell.tail({'-n': 20}, ['access.log', 'error.log']);
270
```
271

272
### uniq - Remove Duplicate Lines
273

274
Removes duplicate consecutive lines from sorted input, with options for counting and filtering.
275

276
```javascript { .api }
277
/**
278
 * Remove duplicate consecutive lines from sorted input
279
 * @param options - Command options
280
 * @param input - Input file (optional, reads from stdin if not provided)
281
 * @param output - Output file (optional, writes to stdout if not provided)
282
 * @returns ShellString containing unique lines
283
 */
284
function uniq(options?: string, input?: string, output?: string): ShellString;
285
```
286

287
**Options:**
288
- `-i`: Case-insensitive comparison
289
- `-c`: Prefix lines with occurrence count
290
- `-d`: Only output duplicate lines
291
- `-u`: Only output unique lines (non-duplicated)
292

293
**Usage Examples:**
294

295
```javascript
296
// Remove duplicates from file
297
const unique = shell.uniq('sorted_data.txt');
298

299
// Case-insensitive duplicate removal
300
const caseUnique = shell.uniq('-i', 'names.txt');
301

302
// Count occurrences
303
const counted = shell.uniq('-c', 'log_entries.txt');
304

305
// Show only duplicated lines
306
const duplicates = shell.uniq('-d', 'data.txt');
307

308
// Show only unique lines
309
const onlyUnique = shell.uniq('-u', 'data.txt');
310

311
// Process and save to file
312
shell.uniq('-c', 'input.txt', 'output.txt');
313

314
// Chain with sort for full deduplication
315
const fullyUnique = shell.sort('unsorted.txt').uniq();
316

317
// Case-insensitive count
318
const caseCount = shell.uniq('-ic', 'mixed_case.txt');
319
```
320

321
## Text Processing Patterns
322

323
### Common Text Processing Workflows
324

325
```javascript
326
// Log analysis workflow
327
const errorCount = shell.cat('application.log')
328
  .grep('ERROR')
329
  .uniq('-c')
330
  .sort('-rn');
331

332
// File content transformation
333
shell.cat('template.html')
334
  .sed('{{TITLE}}', 'My Page')
335
  .sed('{{DATE}}', new Date().toDateString())
336
  .to('index.html');
337

338
// Data extraction and cleaning
339
const cleanData = shell.grep('^[A-Z]', 'raw_data.txt')
340
  .sort()
341
  .uniq()
342
  .head({'-n': 100});
343

344
// Search and replace across multiple files
345
shell.find('.')
346
  .grep('\\.js$')
347
  .forEach(file => {
348
    shell.sed('-i', 'oldAPI', 'newAPI', file);
349
  });
350
```
351

352
### Piping and Chaining
353

354
Text processing commands support method chaining and can be combined with file system operations:
355

356
```javascript
357
// Chain text operations
358
const result = shell.cat('data.txt')
359
  .grep('important')
360
  .sort()
361
  .uniq()
362
  .head({'-n': 10});
363

364
// Output to file
365
shell.echo('Processing complete')
366
  .toEnd('process.log');
367

368
// Complex pipeline
369
const report = shell.find('logs/')
370
  .grep('\\.log$')  // Find log files
371
  .map(file => shell.grep('ERROR', file))  // Search each for errors
372
  .filter(result => result.length > 0)  // Keep only files with errors
373
  .sort();
374
```