Dirator
Directory iterator with filters, individual and array callbacks/listeners, and both synchronous and asynchronous execution.
// example: get all js files target: 'some/dir' { return path } { // do something with each file } // must have done callback for async { // check for an error }
Install
npm install dirator --save
Table of Contents
- Usage - Asynchronous via Options
- Usage - Asynchronous via Events
- Usage - Synchronous
- Results
- Modes
- Convenience methods
- Examples
Usage: Asynchronous via Options
You must specify a done
callback to operate asynchronously.
This example uses all other options, however, only specify the options you want and dirator
will do less work.
var dirator = ; ; // OR, to repeatedly use it:var Dirator = Diratorvar dirator = target: 'some/dir' // all the options used above; // then run it.// you can do this repeatedly.dirator;
Usage: Asynchronous via Events
You must specify a done
event listener to operate asynchronously.
This example uses all other options, however, only specify the options you want and dirator
will do less work.
var Dirator = Dirator dirator = target:'some/dir'; // called for each filedirator; // called for each directory with an array// of fspath instances for each filedirator; // called for each accepted dirdirator; // called for each directory with an array// of fspath instances for each// immediate sub-directorydirator; // called for each accepted pathdirator; // called for each directory with an array// of fspath instances for each path (file/directory)dirator; // called when it's all done iterating.dirator; // now start the work.// can be used repeatedly.dirator;
Usage: Synchronous
Without a done
callback/listener dirator
runs synchronously and provides all results at once in returned object.
TODO: It seems appropriate to allow adding event listeners when running synchronously because they are executed synchronously. I may include this feature in a future version. For now, don't use callbacks/listeners without a done
listener/callback.
var Dirator = Dirator dirator = target:'some/dir'; result = dirator; // OR:var result = target: 'some/dir' result = paths: /* array of all paths */ found: paths: // <number> rejected: strings: 0 paths: 0
Results
The result contains different content depending on the mode it runs in. The results are cumulative, so, the more modes you specify the more results you will receive.
The results object always contains these:
A. found - an object containing the number found of each mode (type) specified
// specify all modes to get all countsresults = results = found: // leave out a mode above and this won't contain its count files: /* <number> */ dirs : /* <number> */ paths: /* <number> */
B. rejected - an object containing two numbers:
- strings - the number of paths rejected by the acceptString filter
- paths - the number of paths rejected by the acceptPath filter
The results object only contains these when its corresponding mode is specified:
- result.paths - available when the
paths
mode is specified (the default mode) - result.files - available when the
files
mode is specified (usingdirator.files()
sets this mode) - result.dirs - available when the
dirs
mode is specified (usingdirator.dirs()
sets this mode)
Modes
Dirator performs differently depending on which modes it runs with.
It operates in paths
mode by default.
There are three modes:
A. paths
- only provides paths in results object:
result.paths
- only calls the
path
andpaths
callbacks/listeners. - will iterate through directories to find all paths
B. files
- only provides files in results object:
result.files
- only calls the
file
andfiles
callbacks/listeners. - will iterate through directories to find all files
C. dirs
- only provides dirs in results object:
result.dirs
- only calls the
dir
anddirs
callbacks/listeners. - will iterate through directories to find all directories
The mode can be affected in three ways:
- set the
only
property of options to an array containing one or more of: paths, files, or dirs. - specify callbacks/listeners and their corresponding mode will be added. For example, the
file
andfiles
options/listeners will add thefiles
mode. - specify a single mode by using a direct function for the mode:
dirator.files()
,dirator.dirs()
, and the default does the paths mode:dirator()
.
Note: If you specify both the modes to use and a callback/listener which is not part of those modes, then they will not be called. For example:
var dirator = ; ;
Usage: Convenience methods
For common uses there are three functions on the package's exported object. By default, these will run synchronously in their corresponding mode and return the result with all corresponding types found by recursively iterating from the current working directory down. They also accept options as described above to customize their actions.
files(options)
dirs(options)
paths(options)
var dirator = // get all the files within 'src'var result = dirator // get all the *.js files within 'src'result = dirator
Examples
Get all JS files
Imagine a directory 'some/dir'
with JS files in it and within sub-directories.
var dirator = // Asynchronous: // Synchronous:var result = result = found: paths: 1 // counts how many files/dirs were found rejected: paths: 0 // counts rejects, acceptPath returned false strings: 0 // counts rejects, acceptString returned false paths: // an `fspath` Path instance per file accepted
Get all directories
var dirator = // Asynchronous:dirator // Synchronous:var result = dirator result = found: dirs: 1 // counts how many directories were found rejected: paths: 0 // counts rejects, acceptPath returned false strings: 0 // counts rejects, acceptString returned false dirs: // an `fspath` Path instance per directory accepted // Or, get them in chunks:dirator