README.md
1## FileList
2
3A FileList is a lazy-evaluated list of files. When given a list
4of glob patterns for possible files to be included in the file
5list, instead of searching the file structures to find the files,
6a FileList holds the pattern for latter use.
7
8This allows you to define a FileList to match any number of
9files, but only search out the actual files when then FileList
10itself is actually used. The key is that the first time an
11element of the FileList/Array is requested, the pending patterns
12are resolved into a real list of file names.
13
14### Usage
15
16Add files to the list with the `include` method. You can add glob
17patterns, individual files, or RegExp objects. When the Array
18methods are invoked on the FileList, these items are resolved to
19an actual list of files.
20
21```javascript
22var fl = new FileList();
23fl.include('test/*.js');
24fl.exclude('test/helpers.js');
25```
26
27Use the `exclude` method to override inclusions. You can use this
28when your inclusions are too broad.
29
30### Array methods
31
32FileList has lazy-evaluated versions of most of the array
33methods, 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
55When you call one of these methods, the items in the FileList
56will be resolved to the full list of files, and the method will
57be invoked on that result.
58
59### Special `length` method
60
61`length`: FileList includes a length *method* (instead of a
62property) which returns the number of actual files in the list
63once 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
72files. This method is invoked automatically when one of the array
73methods is called.
74
75`toArray`: Immediately resolves the list of items, and returns an
76actual array of filepaths.
77
78`clearInclusions`: Clears any pending items -- must be used
79before resolving the list.
80
81`clearExclusions`: Clears the list of exclusions rules.
82
83
84
85