diff options
Diffstat (limited to 'node_modules/walkdir/readme.md')
| -rw-r--r-- | node_modules/walkdir/readme.md | 176 |
1 files changed, 176 insertions, 0 deletions
diff --git a/node_modules/walkdir/readme.md b/node_modules/walkdir/readme.md new file mode 100644 index 000000000..df3f9d571 --- /dev/null +++ b/node_modules/walkdir/readme.md @@ -0,0 +1,176 @@ +[](http://travis-ci.org/soldair/node-walkdir) + +## walkdir + +Find files. Walks a directory tree emitting events based on what it finds. Presents a familliar callback/emitter/sync interface. Walk a tree of any depth. This is a performant option any pull requests to make it more so will be taken into consderation.. + +## Example + +```js + +var walk = require('walkdir'); + +//async with path callback + +walk('../',function(path,stat){ + console.log('found: ',path); +}); + +//use async emitter to capture more events + +var emitter = walk('../'); + +emitter.on('file',function(filename,stat){ + console.log('file from emitter: ', filename); +}); + + +//sync with callback + +walk.sync('../',function(path,stat){ + console.log('found sync:',path); +}); + +//sync just need paths + +var paths = walk.sync('../'); +console.log('found paths sync: ',paths); + +``` + + +## install + + npm install walkdir + +## arguments + +walkdir(path, [options], [callback]) +walkdir.sync(path, [options], [callback]); + +- path + - the starting point of your directory walk + +- options. supported options are + - general + + ```js + { + "follow_symlinks":false, // default is off + "no_recurse":false, // only recurse one level deep + "max_depth":undefined // only recurse down to max_depth. if you need more than no_recurse + } + ``` + + - sync only + + ```js + { + "return_object":false, // if true the sync return will be in {path:stat} format instead of [path,path,...] + "no_return":false, // if true null will be returned and no array or object will be created with found paths. useful for large listings + } + ``` + +- callback + - this is bound to the path event of the emitter. its optional in all cases. + + ```js + callback(path,stat) + ``` + +## events + +non error type events are emitted with (path,stat). stat is an instanceof fs.Stats + +###path +fired for everything + +###file +fired only for regular files + +###directory +fired only for directories + +###link +fired when a symbolic link is found + +###end +fired when the entire tree has been read and emitted. + +###socket +fired when a socket descriptor is found + +###fifo +fired when a fifo is found + +###characterdevice +fired when a character device is found + +###blockdevice +fired when a block device is found + +###targetdirectory +fired for the stat of the path you provided as the first argument. is is only fired if it is a directory. + +###empty +fired for empty directory + +## error events +error type events are emitted with (path,error). error being the error object returned from an fs call or other opperation. + +###error +if the target path cannot be read an error event is emitted. this is the only failure case. + +###fail +when stat or read fails on a path somewhere in the walk and it is not your target path you get a fail event instead of error. +This is handy if you want to find places you dont have access too. + +## notes +the async emitter returned supports 3 methods + +###end + stop a walk in progress + +###pause + pause the walk. no more events will be emitted until resume + +###resume + resume the walk + +### ignore(path or array of paths) + will not traverse these directories. may be called in the path event handler to ignore dynamically. + ```js + var walk = require('walkdir'); + var p = require('path'); + walk('/',function(path,stat){ + // ignore all .git directories. + if(p.basename(path) === '.git') { + this.ignore(path) + } + }) + ``` + +### cancel a walk in progress + ```js + //cancel a walk in progress within callback. + + var walk = require('walkdir'); + walk('../',function(path,stat){ + this.end(); + }); + + //cancel a walk in progress with emitter handle + var walk = require('walkdir'); + var emitter = walk('../'); + + doSomethingAsync(function(){ + emitter.end(); + }) + ``` + +## thanks +thanks to substack. the interface for this module is based off of node-findit + +## contributing +see `CONTRIBUTING.md` for guidelines. this is an open opensource project. + |