Skip to content

Commit 9237f66

Browse files
nfischernfischer
authored
docs: clarify which methods return ShellStrings (shelljs#934)
No change to logic, only docs. In v0.7.0, we introduced ShellStrings and changed most methods to return them. Docs weren't appropriately updated, so this PR cross-links these methods to the ShellString docs. This also expands on the ShellString docs themselves, since there was room to make this clearer. Fixes shelljs#933
1 parent a877512 commit 9237f66

26 files changed

Lines changed: 129 additions & 73 deletions

‎README.md‎

Lines changed: 64 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -151,15 +151,16 @@ var str = cat('file1', 'file2');
151151
var str = cat(['file1', 'file2']); // same as above
152152
```
153153

154-
Returns a string containing the given file, or a concatenated string
155-
containing the files if more than one file is given (a new line character is
156-
introduced between each file).
154+
Returns a [ShellString](#shellstringstr) containing the given file, or a
155+
concatenated string containing the files if more than one file is given (a
156+
new line character is introduced between each file).
157157

158158

159159
### cd([dir])
160160

161161
Changes to directory `dir` for the duration of the script. Changes to home
162-
directory if no argument is supplied.
162+
directory if no argument is supplied. Returns a
163+
[ShellString](#shellstringstr) to indicate success or failure.
163164

164165

165166
### chmod([options,] octal_mode || octal_string, file)
@@ -189,6 +190,8 @@ Notable exceptions:
189190
given to the `umask`.
190191
+ There is no "quiet" option, since default behavior is to run silent.
191192

193+
Returns a [ShellString](#shellstringstr) indicating success or failure.
194+
192195

193196
### cp([options,] source [, source ...], dest)
194197
### cp([options,] source_array, dest)
@@ -211,7 +214,8 @@ cp('-Rf', '/tmp/*', '/usr/local/*', '/home/tmp');
211214
cp('-Rf', ['/tmp/*', '/usr/local/*'], '/home/tmp'); // same as above
212215
```
213216

214-
Copies files.
217+
Copies files. Returns a [ShellString](#shellstringstr) indicating success
218+
or failure.
215219

216220

217221
### pushd([options,] [dir | '-N' | '+N'])
@@ -295,8 +299,7 @@ var str = echo('hello world');
295299
echo('-n', 'no newline at end');
296300
```
297301

298-
Prints `string` to stdout, and returns string with additional utility methods
299-
like `.to()`.
302+
Prints `string` to stdout, and returns a [ShellString](#shellstringstr).
300303

301304

302305
### exec(command [, options] [, callback])
@@ -328,10 +331,10 @@ exec('some_long_running_process', function(code, stdout, stderr) {
328331
});
329332
```
330333

331-
Executes the given `command` _synchronously_, unless otherwise specified. When in synchronous
332-
mode, this returns a `ShellString` (compatible with ShellJS v0.6.x, which returns an object
333-
of the form `{ code:..., stdout:... , stderr:... }`). Otherwise, this returns the child process
334-
object, and the `callback` receives the arguments `(code, stdout, stderr)`.
334+
Executes the given `command` _synchronously_, unless otherwise specified.
335+
When in synchronous mode, this returns a [ShellString](#shellstringstr).
336+
Otherwise, this returns the child process object, and the `callback`
337+
receives the arguments `(code, stdout, stderr)`.
335338

336339
Not seeing the behavior you want? `exec()` runs everything through `sh`
337340
by default (or `cmd.exe` on Windows), which differs from `bash`. If you
@@ -349,7 +352,8 @@ find(['src', 'lib']); // same as above
349352
find('.').filter(function(file) { return file.match(/\.js$/); });
350353
```
351354

352-
Returns array of all files (however deep) in the given paths.
355+
Returns a [ShellString](#shellstringstr) (with array-like properties) of all
356+
files (however deep) in the given paths.
353357

354358
The main difference from `ls('-R', path)` is that the resulting file names
355359
include the base directories (e.g., `lib/resources/file1` instead of just `file1`).
@@ -371,8 +375,9 @@ grep('-v', 'GLOBAL_VARIABLE', '*.js');
371375
grep('GLOBAL_VARIABLE', '*.js');
372376
```
373377

374-
Reads input string from given files and returns a string containing all lines of the
375-
file that match the given `regex_filter`.
378+
Reads input string from given files and returns a
379+
[ShellString](#shellstringstr) containing all lines of the @ file that match
380+
the given `regex_filter`.
376381

377382

378383
### head([{'-n': \<num\>},] file [, file ...])
@@ -390,7 +395,7 @@ var str = head('file1', 'file2');
390395
var str = head(['file1', 'file2']); // same as above
391396
```
392397

393-
Read the start of a file.
398+
Read the start of a `file`. Returns a [ShellString](#shellstringstr).
394399

395400

396401
### ln([options,] source, dest)
@@ -407,7 +412,9 @@ ln('file', 'newlink');
407412
ln('-sf', 'file', 'existing');
408413
```
409414

410-
Links `source` to `dest`. Use `-f` to force the link, should `dest` already exist.
415+
Links `source` to `dest`. Use `-f` to force the link, should `dest` already
416+
exist. Returns a [ShellString](#shellstringstr) indicating success or
417+
failure.
411418

412419

413420
### ls([options,] [path, ...])
@@ -433,8 +440,9 @@ ls('-R', ['/users/me', '/tmp']); // same as above
433440
ls('-l', 'file.txt'); // { name: 'file.txt', mode: 33188, nlink: 1, ...}
434441
```
435442

436-
Returns array of files in the given `path`, or files in
437-
the current directory if no `path` is provided.
443+
Returns a [ShellString](#shellstringstr) (with array-like properties) of all
444+
the files in the given `path`, or files in the current directory if no
445+
`path` is provided.
438446

439447

440448
### mkdir([options,] dir [, dir ...])
@@ -451,7 +459,8 @@ mkdir('-p', '/tmp/a/b/c/d', '/tmp/e/f/g');
451459
mkdir('-p', ['/tmp/a/b/c/d', '/tmp/e/f/g']); // same as above
452460
```
453461

454-
Creates directories.
462+
Creates directories. Returns a [ShellString](#shellstringstr) indicating
463+
success or failure.
455464

456465

457466
### mv([options ,] source [, source ...], dest')
@@ -470,12 +479,13 @@ mv('file1', 'file2', 'dir/');
470479
mv(['file1', 'file2'], 'dir/'); // same as above
471480
```
472481

473-
Moves `source` file(s) to `dest`.
482+
Moves `source` file(s) to `dest`. Returns a [ShellString](#shellstringstr)
483+
indicating success or failure.
474484

475485

476486
### pwd()
477487

478-
Returns the current directory.
488+
Returns the current directory as a [ShellString](#shellstringstr).
479489

480490

481491
### rm([options,] file [, file ...])
@@ -494,7 +504,8 @@ rm('some_file.txt', 'another_file.txt');
494504
rm(['some_file.txt', 'another_file.txt']); // same as above
495505
```
496506

497-
Removes files.
507+
Removes files. Returns a [ShellString](#shellstringstr) indicating success
508+
or failure.
498509

499510

500511
### sed([options,] search_regex, replacement, file [, file ...])
@@ -511,8 +522,9 @@ sed('-i', 'PROGRAM_VERSION', 'v0.1.3', 'source.js');
511522
sed(/.*DELETE_THIS_LINE.*\n/, '', 'source.js');
512523
```
513524

514-
Reads an input string from `file`s, and performs a JavaScript `replace()` on the input
515-
using the given `search_regex` and `replacement` string or function. Returns the new string after replacement.
525+
Reads an input string from `file`s, and performs a JavaScript `replace()` on
526+
the input using the given `search_regex` and `replacement` string or
527+
function. Returns the new [ShellString](#shellstringstr) after replacement.
516528

517529
Note:
518530

@@ -557,8 +569,9 @@ sort('foo.txt', 'bar.txt');
557569
sort('-r', 'foo.txt');
558570
```
559571

560-
Return the contents of the `file`s, sorted line-by-line. Sorting multiple
561-
files mixes their content (just as unix `sort` does).
572+
Return the contents of the `file`s, sorted line-by-line as a
573+
[ShellString](#shellstringstr). Sorting multiple files mixes their content
574+
(just as unix `sort` does).
562575

563576

564577
### tail([{'-n': \<num\>},] file [, file ...])
@@ -576,7 +589,7 @@ var str = tail('file1', 'file2');
576589
var str = tail(['file1', 'file2']); // same as above
577590
```
578591

579-
Read the end of a `file`.
592+
Read the end of a `file`. Returns a [ShellString](#shellstringstr).
580593

581594

582595
### tempdir()
@@ -611,7 +624,8 @@ if (test('-d', path)) { /* do something with dir */ };
611624
if (!test('-f', path)) continue; // skip if it's a regular file
612625
```
613626

614-
Evaluates `expression` using the available primaries and returns corresponding value.
627+
Evaluates `expression` using the available primaries and returns
628+
corresponding boolean value.
615629

616630

617631
### ShellString.prototype.to(file)
@@ -624,7 +638,8 @@ cat('input.txt').to('output.txt');
624638

625639
Analogous to the redirection operator `>` in Unix, but works with
626640
`ShellStrings` (such as those returned by `cat`, `grep`, etc.). _Like Unix
627-
redirections, `to()` will overwrite any existing file!_
641+
redirections, `to()` will overwrite any existing file!_ Returns the same
642+
[ShellString](#shellstringstr) this operated on, to support chaining.
628643

629644

630645
### ShellString.prototype.toEnd(file)
@@ -636,7 +651,8 @@ cat('input.txt').toEnd('output.txt');
636651
```
637652

638653
Analogous to the redirect-and-append operator `>>` in Unix, but works with
639-
`ShellStrings` (such as those returned by `cat`, `grep`, etc.).
654+
`ShellStrings` (such as those returned by `cat`, `grep`, etc.). Returns the
655+
same [ShellString](#shellstringstr) this operated on, to support chaining.
640656

641657

642658
### touch([options,] file [, file ...])
@@ -663,7 +679,9 @@ touch({ date: new Date('December 17, 1995 03:24:00') }, 'path/to/file.js');
663679

664680
Update the access and modification times of each file to the current time.
665681
A file argument that does not exist is created empty, unless `-c` is supplied.
666-
This is a partial implementation of [`touch(1)`](http://linux.die.net/man/1/touch).
682+
This is a partial implementation of
683+
[`touch(1)`](http://linux.die.net/man/1/touch). Returns a
684+
[ShellString](#shellstringstr) indicating success or failure.
667685

668686

669687
### uniq([options,] [input, [output]])
@@ -682,7 +700,8 @@ uniq('-i', 'foo.txt');
682700
uniq('-cd', 'foo.txt', 'bar.txt');
683701
```
684702

685-
Filter adjacent matching lines from `input`.
703+
Filter adjacent matching lines from `input`. Returns a
704+
[ShellString](#shellstringstr).
686705

687706

688707
### which(command)
@@ -695,7 +714,8 @@ var nodeExec = which('node');
695714

696715
Searches for `command` in the system's `PATH`. On Windows, this uses the
697716
`PATHEXT` variable to append the extension if it's not already executable.
698-
Returns string containing the absolute path to `command`.
717+
Returns a [ShellString](#shellstringstr) containing the absolute path to
718+
`command`.
699719

700720

701721
### exit(code)
@@ -717,11 +737,19 @@ the `.stderr` attribute from the last command's return value instead.
717737
Examples:
718738

719739
```javascript
720-
var foo = ShellString('hello world');
740+
var foo = new ShellString('hello world');
721741
```
722742

723-
Turns a regular string into a string-like object similar to what each
724-
command returns. This has special methods, like `.to()` and `.toEnd()`.
743+
This is a dedicated type returned by most ShellJS methods, which wraps a
744+
string (or array) value. This has all the string (or array) methods, but
745+
also exposes extra methods: [`.to()`](#shellstringprototypetofile),
746+
[`.toEnd()`](#shellstringprototypetoendfile), and all the pipe-able methods
747+
(ex. `.cat()`, `.grep()`, etc.). This can be easily converted into a string
748+
by calling `.toString()`.
749+
750+
This type also exposes the corresponding command's stdout, stderr, and
751+
return status code via the `.stdout` (string), `.stderr` (string), and
752+
`.code` (number) properties respectively.
725753

726754

727755
### env['VAR_NAME']

‎src/cat.js‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,9 @@ common.register('cat', _cat, {
2424
//@ var str = cat(['file1', 'file2']); // same as above
2525
//@ ```
2626
//@
27-
//@ Returns a string containing the given file, or a concatenated string
28-
//@ containing the files if more than one file is given (a new line character is
29-
//@ introduced between each file).
27+
//@ Returns a [ShellString](#shellstringstr) containing the given file, or a
28+
//@ concatenated string containing the files if more than one file is given (a
29+
//@ new line character is introduced between each file).
3030
function _cat(options, files) {
3131
var cat = common.readFromPipe();
3232

‎src/cd.js‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@ common.register('cd', _cd, {});
77
//@ ### cd([dir])
88
//@
99
//@ Changes to directory `dir` for the duration of the script. Changes to home
10-
//@ directory if no argument is supplied.
10+
//@ directory if no argument is supplied. Returns a
11+
//@ [ShellString](#shellstringstr) to indicate success or failure.
1112
function _cd(options, dir) {
1213
if (!dir) dir = os.homedir();
1314

‎src/chmod.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,8 @@ common.register('chmod', _chmod, {
5959
//@ + In symbolic modes, `a-r` and `-r` are identical. No consideration is
6060
//@ given to the `umask`.
6161
//@ + There is no "quiet" option, since default behavior is to run silent.
62+
//@
63+
//@ Returns a [ShellString](#shellstringstr) indicating success or failure.
6264
function _chmod(options, mode, filePattern) {
6365
if (!filePattern) {
6466
if (options.length > 0 && options.charAt(0) === '-') {

‎src/common.js‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -131,11 +131,19 @@ exports.error = error;
131131
//@ Examples:
132132
//@
133133
//@ ```javascript
134-
//@ var foo = ShellString('hello world');
134+
//@ var foo = new ShellString('hello world');
135135
//@ ```
136136
//@
137-
//@ Turns a regular string into a string-like object similar to what each
138-
//@ command returns. This has special methods, like `.to()` and `.toEnd()`.
137+
//@ This is a dedicated type returned by most ShellJS methods, which wraps a
138+
//@ string (or array) value. This has all the string (or array) methods, but
139+
//@ also exposes extra methods: [`.to()`](#shellstringprototypetofile),
140+
//@ [`.toEnd()`](#shellstringprototypetoendfile), and all the pipe-able methods
141+
//@ (ex. `.cat()`, `.grep()`, etc.). This can be easily converted into a string
142+
//@ by calling `.toString()`.
143+
//@
144+
//@ This type also exposes the corresponding command's stdout, stderr, and
145+
//@ return status code via the `.stdout` (string), `.stderr` (string), and
146+
//@ `.code` (number) properties respectively.
139147
function ShellString(stdout, stderr, code) {
140148
var that;
141149
if (stdout instanceof Array) {

‎src/cp.js‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -209,7 +209,8 @@ function cpcheckcycle(sourceDir, srcFile) {
209209
//@ cp('-Rf', ['/tmp/*', '/usr/local/*'], '/home/tmp'); // same as above
210210
//@ ```
211211
//@
212-
//@ Copies files.
212+
//@ Copies files. Returns a [ShellString](#shellstringstr) indicating success
213+
//@ or failure.
213214
function _cp(options, sources, dest) {
214215
// If we're missing -R, it actually implies -L (unless -P is explicit)
215216
if (options.followsymlink) {

‎src/echo.js‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,7 @@ common.register('echo', _echo, {
2222
//@ echo('-n', 'no newline at end');
2323
//@ ```
2424
//@
25-
//@ Prints `string` to stdout, and returns string with additional utility methods
26-
//@ like `.to()`.
25+
//@ Prints `string` to stdout, and returns a [ShellString](#shellstringstr).
2726
function _echo(opts) {
2827
// allow strings starting with '-', see issue #20
2928
var messages = [].slice.call(arguments, opts ? 0 : 1);

‎src/exec.js‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -169,10 +169,10 @@ function execAsync(cmd, opts, pipe, callback) {
169169
//@ });
170170
//@ ```
171171
//@
172-
//@ Executes the given `command` _synchronously_, unless otherwise specified. When in synchronous
173-
//@ mode, this returns a `ShellString` (compatible with ShellJS v0.6.x, which returns an object
174-
//@ of the form `{ code:..., stdout:... , stderr:... }`). Otherwise, this returns the child process
175-
//@ object, and the `callback` receives the arguments `(code, stdout, stderr)`.
172+
//@ Executes the given `command` _synchronously_, unless otherwise specified.
173+
//@ When in synchronous mode, this returns a [ShellString](#shellstringstr).
174+
//@ Otherwise, this returns the child process object, and the `callback`
175+
//@ receives the arguments `(code, stdout, stderr)`.
176176
//@
177177
//@ Not seeing the behavior you want? `exec()` runs everything through `sh`
178178
//@ by default (or `cmd.exe` on Windows), which differs from `bash`. If you

‎src/find.js‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,8 @@ common.register('find', _find, {});
1616
//@ find('.').filter(function(file) { return file.match(/\.js$/); });
1717
//@ ```
1818
//@
19-
//@ Returns array of all files (however deep) in the given paths.
19+
//@ Returns a [ShellString](#shellstringstr) (with array-like properties) of all
20+
//@ files (however deep) in the given paths.
2021
//@
2122
//@ The main difference from `ls('-R', path)` is that the resulting file names
2223
//@ include the base directories (e.g., `lib/resources/file1` instead of just `file1`).

‎src/grep.js‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,9 @@ common.register('grep', _grep, {
2828
//@ grep('GLOBAL_VARIABLE', '*.js');
2929
//@ ```
3030
//@
31-
//@ Reads input string from given files and returns a string containing all lines of the
32-
//@ file that match the given `regex_filter`.
31+
//@ Reads input string from given files and returns a
32+
//@ [ShellString](#shellstringstr) containing all lines of the @ file that match
33+
//@ the given `regex_filter`.
3334
function _grep(options, regex, files) {
3435
// Check if this is coming from a pipe
3536
var pipe = common.readFromPipe();

0 commit comments

Comments
 (0)