177 lines
3.8 KiB
Markdown
177 lines
3.8 KiB
Markdown
[](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.
|
|
|