| 1 | ## FileList
|
|---|
| 2 |
|
|---|
| 3 | A FileList is a lazy-evaluated list of files. When given a list
|
|---|
| 4 | of glob patterns for possible files to be included in the file
|
|---|
| 5 | list, instead of searching the file structures to find the files,
|
|---|
| 6 | a FileList holds the pattern for latter use.
|
|---|
| 7 |
|
|---|
| 8 | This allows you to define a FileList to match any number of
|
|---|
| 9 | files, but only search out the actual files when then FileList
|
|---|
| 10 | itself is actually used. The key is that the first time an
|
|---|
| 11 | element of the FileList/Array is requested, the pending patterns
|
|---|
| 12 | are resolved into a real list of file names.
|
|---|
| 13 |
|
|---|
| 14 | ### Usage
|
|---|
| 15 |
|
|---|
| 16 | Add files to the list with the `include` method. You can add glob
|
|---|
| 17 | patterns, individual files, or RegExp objects. When the Array
|
|---|
| 18 | methods are invoked on the FileList, these items are resolved to
|
|---|
| 19 | an actual list of files.
|
|---|
| 20 |
|
|---|
| 21 | ```javascript
|
|---|
| 22 | var fl = new FileList();
|
|---|
| 23 | fl.include('test/*.js');
|
|---|
| 24 | fl.exclude('test/helpers.js');
|
|---|
| 25 | ```
|
|---|
| 26 |
|
|---|
| 27 | Use the `exclude` method to override inclusions. You can use this
|
|---|
| 28 | when your inclusions are too broad.
|
|---|
| 29 |
|
|---|
| 30 | ### Array methods
|
|---|
| 31 |
|
|---|
| 32 | FileList has lazy-evaluated versions of most of the array
|
|---|
| 33 | methods, including the following:
|
|---|
| 34 |
|
|---|
| 35 | * join
|
|---|
| 36 | * pop
|
|---|
| 37 | * push
|
|---|
| 38 | * concat
|
|---|
| 39 | * reverse
|
|---|
| 40 | * shift
|
|---|
| 41 | * unshift
|
|---|
| 42 | * slice
|
|---|
| 43 | * splice
|
|---|
| 44 | * sort
|
|---|
| 45 | * filter
|
|---|
| 46 | * forEach
|
|---|
| 47 | * some
|
|---|
| 48 | * every
|
|---|
| 49 | * map
|
|---|
| 50 | * indexOf
|
|---|
| 51 | * lastIndexOf
|
|---|
| 52 | * reduce
|
|---|
| 53 | * reduceRight
|
|---|
| 54 |
|
|---|
| 55 | When you call one of these methods, the items in the FileList
|
|---|
| 56 | will be resolved to the full list of files, and the method will
|
|---|
| 57 | be invoked on that result.
|
|---|
| 58 |
|
|---|
| 59 | ### Special `length` method
|
|---|
| 60 |
|
|---|
| 61 | `length`: FileList includes a length *method* (instead of a
|
|---|
| 62 | property) which returns the number of actual files in the list
|
|---|
| 63 | once it's been resolved.
|
|---|
| 64 |
|
|---|
| 65 | ### FileList-specific methods
|
|---|
| 66 |
|
|---|
| 67 | `include`: Add a filename/glob/regex to the list
|
|---|
| 68 |
|
|---|
| 69 | `exclude`: Override inclusions by excluding a filename/glob/regex
|
|---|
| 70 |
|
|---|
| 71 | `resolve`: Resolve the items in the FileList to the full list of
|
|---|
| 72 | files. This method is invoked automatically when one of the array
|
|---|
| 73 | methods is called.
|
|---|
| 74 |
|
|---|
| 75 | `toArray`: Immediately resolves the list of items, and returns an
|
|---|
| 76 | actual array of filepaths.
|
|---|
| 77 |
|
|---|
| 78 | `clearInclusions`: Clears any pending items -- must be used
|
|---|
| 79 | before resolving the list.
|
|---|
| 80 |
|
|---|
| 81 | `clearExclusions`: Clears the list of exclusions rules.
|
|---|
| 82 |
|
|---|
| 83 |
|
|---|
| 84 |
|
|---|
