@@ -209,6 +209,19 @@ tar.t({
209
209
})
210
210
```
211
211
212
+ For example, to just get the list of filenames from an archive:
213
+
214
+ ``` js
215
+ const getEntryFilenames = async tarballFilename => {
216
+ const filenames = []
217
+ await tar .t ({
218
+ file: tarballFilename,
219
+ onentry : entry => filenames .push (entry .path ),
220
+ })
221
+ return filenames
222
+ }
223
+ ```
224
+
212
225
To replicate ` cat my-tarball.tgz | tar t ` do:
213
226
214
227
``` js
@@ -223,6 +236,18 @@ When the function returns, it's already done. Sync methods without a
223
236
file argument return a sync stream, which flushes immediately. But,
224
237
of course, it still won't be done until you ` .end() ` it.
225
238
239
+ ``` js
240
+ const getEntryFilenamesSync = tarballFilename => {
241
+ const filenames = []
242
+ tar .t ({
243
+ file: tarballFilename,
244
+ onentry : entry => filenames .push (entry .path ),
245
+ sync: true ,
246
+ })
247
+ return filenames
248
+ }
249
+ ```
250
+
226
251
To filter entries, add ` filter: <function> ` to the options.
227
252
Tar-creating methods call the filter with ` filter(path, stat) ` .
228
253
Tar-reading methods (including extraction) call the filter with
@@ -429,15 +454,18 @@ no paths are provided, then all the entries are listed.
429
454
430
455
If the archive is gzipped, then tar will detect this and unzip it.
431
456
432
- Returns an event emitter that emits ` entry ` events with
433
- ` tar.ReadEntry ` objects. However, they don't emit ` 'data' ` or ` 'end' `
434
- events. (If you want to get actual readable entries, use the
435
- ` tar.Parse ` class instead.)
457
+ If the ` file ` option is _ not_ provided, then returns an event emitter that
458
+ emits ` entry ` events with ` tar.ReadEntry ` objects. However, they don't
459
+ emit ` 'data' ` or ` 'end' ` events. (If you want to get actual readable
460
+ entries, use the ` tar.Parse ` class instead.)
461
+
462
+ If a ` file ` option _ is_ provided, then the return value will be a promise
463
+ that resolves when the file has been fully traversed in async mode, or
464
+ ` undefined ` if ` sync: true ` is set. Thus, you _ must_ specify an ` onentry `
465
+ method in order to do anything useful with the data it parses.
436
466
437
467
The following options are supported:
438
468
439
- - ` cwd ` Extract files relative to the specified directory. Defaults
440
- to ` process.cwd() ` . [ Alias: ` C ` ]
441
469
- ` file ` The archive file to list. If not specified, then a
442
470
Writable stream is returned where the archive data should be
443
471
written. [ Alias: ` f ` ]
@@ -449,8 +477,8 @@ The following options are supported:
449
477
entry being listed. Return ` true ` to emit the entry from the
450
478
archive, or ` false ` to skip it.
451
479
- ` onentry ` A function that gets called with ` (entry) ` for each entry
452
- that passes the filter. This is important for when both ` file ` and
453
- ` sync ` are set, because it will be called synchronously .
480
+ that passes the filter. This is important for when ` file ` is set,
481
+ because there is no other way to do anything useful with this method .
454
482
- ` maxReadSize ` The maximum buffer size for ` fs.read() ` operations.
455
483
Defaults to 16 MB.
456
484
- ` noResume ` By default, ` entry ` streams are resumed immediately after
0 commit comments