vfile-find-down

Find one or more files (exposed as VFiles) by searching the file system downwards.

Installation

npm:

npm install vfile-find-down

Usage

Require dependencies:

var findDown = require('vfile-find-down');

Search for files with a .md extension from the current working directory downwards:

findDown.all('.md', console.log);
/* null [ VFile {
 *     contents: '',
 *     messages: [],
 *     history: [ '/Users/foo/bar/baz/example.md' ],
 *     directory: '/Users/foo/bar/baz',
 *     filename: 'example',
 *     extension: 'md' },
 *   VFile {
 *     contents: '',
 *     messages: [],
 *     directory: '/Users/foo/bar/baz',
 *     filename: 'readme',
 *     extension: 'md' } ]
 */

Search for the first file:

findDown.one('.md', console.log);
/* null VFile {
 *   contents: '',
 *   messages: [],
 *   directory: '/Users/foo/bar/baz',
 *   filename: 'example',
 *   extension: 'md' }
 */

API

findDown.one(test[, paths], callback)

Find a file or a directory downwards.

Example

findDown.one('readme.md', console.log);
/* null VFile {
 *   contents: '',
 *   messages: [],
 *   history: [ '/Users/foo/bar/baz/readme.md' ],
 *   directory: '/Users/foo/bar/baz',
 *   filename: 'readme',
 *   extension: 'md' }
 */

Signatures

• findDown.one(filePath[, paths], callback);
• findDown.one(extension[, paths], callback);
• findDown.one(test[, paths], callback);
• findDown.one(tests[, paths], callback).

Parameters

• filePath (string) — Filename (including extension) to search for;

• extension (string) — File extension to search for (must start with a .);

• test (Function) — Function invoked to check whether a virtual file should be included;

• tests (Array.<Function|filePath|extension>) — List of tests, any of which should match a given file for it to be included.

• paths (Array.<string> or string, optional, default: process.cwd()) — Place(s) to start searching from;

• callback (Function); — Function invoked when a matching file or the top of the volume is reached.

Notes

• Virtual Files are not read (their content is not populated).

function callback(err, file)

Invoked when a matching file or the top of the volume is reached.

Parameters

• err (Error, optional);
• file (VFile, optional).

Notes

• The err parameter is never populated.

findDown.all(test[, paths], callback)

Find files or directories downwards.

Example

findDown.all('.md', console.log);
/* null [ VFile {
 *     contents: '',
 *     messages: [],
 *     directory: '/Users/foo/bar/baz',
 *     filename: 'example',
 *     extension: 'md' },
 *   VFile {
 *     contents: '',
 *     messages: [],
 *     directory: '/Users/foo',
 *     filename: 'readme',
 *     extension: 'md' } ]
 */

Signatures

• findDown.all(filePath[, paths], callback);
• findDown.all(extension[, paths], callback);
• findDown.all(test[, paths], callback);
• findDown.all(tests[, paths], callback).

Parameters

• filePath (string) — Filename (including extension) to search for;

• extension (string) — File extension to search for (must start with a .);

• test (Function) — Function invoked to check whether a virtual file should be included;

• tests (Array.<Function|filePath|extension>) — List of tests, any of which should match a given file for it to be included.

• paths (Array.<string> or string, optional, default: process.cwd()) — Place(s) to start searching from;

• callback (Function); — Function invoked when matching files or the top of the volume is reached.

Notes

• Virtual Files are not read (their content is not populated).

function callback(err, files)

Invoked when files or the top of the volume is reached.

Parameters

• err (Error, optional);
• files (Array.<VFile>, optional).

Notes

• The err parameter is never populated.

function test(file)

Check whether a virtual file should be included.

Parameters

• file (VFile).

Returns: boolean, when truthy, the file is included.

findDown.INCLUDE

Flag used as an alternative to returning true from test, ensuring the tested file is included and passed to callback.

findDown.SKIP

Flag used to skip searching a directory from test.

findDown.EXIT

Flag used to stop searching for files from test.

License

MIT © Titus Wormer