Find READMEs

Find package READMEs.

Usage

var findREADMEs = require( '@stdlib/_tools/pkgs/readmes' );

findREADMEs( [options,] clbk )

Asynchronously search for package READMEs.

findREADMEs( onFiles );

function onFiles( error, files ) {
    if ( error ) {
        throw error;
    }
    console.log( files.join( '\n' ) );
}

The function accepts the following options:

  • dir: root directory from which to search for package READMEs. May be either an absolute path or a path relative to the current working directory. Default: current working directory.
  • pattern: glob pattern used to find packages. Default: '**/package.json' (note: pattern must end with package.json).
  • ignore: list of glob patterns used to exclude matches.

To search from an alternative directory, set the dir option.

var opts = {
    'dir': '/foo/bar/baz'
};

findREADMEs( opts, onFiles );

function onFiles( error, files ) {
    if ( error ) {
        throw error;
    }
    console.log( files.join( '\n' ) );
}

To provide an alternative include filter, set the pattern option.

var opts = {
    'pattern': '**/foo/**/package.json'
};

findREADMEs( opts, onFiles );

function onFiles( error, files ) {
    if ( error ) {
        throw error;
    }
    console.log( files.join( '\n' ) );
}

To exclude matches, set the ignore option.

var opts = {
    'ignore': [
        'node_modules/**',
        'build/**',
        'reports/**'
    ]
};

findREADMEs( opts, onFiles );

function onFiles( error, files ) {
    if ( error ) {
        throw error;
    }
    console.log( files.join( '\n' ) );
}

findREADMEs.sync( [options] )

Synchronously searches for package READMEs.

var files = findREADMEs.sync();
// returns [...]

The function accepts the same options as findREADMEs() above.

Notes

  • The implementation resolves package READMEs by checking for a README.md file in the directory containing a package's package.json file.

Examples

var findREADMEs = require( '@stdlib/_tools/pkgs/readmes' );

findREADMEs( onFiles );

function onFiles( error, files ) {
    if ( error ) {
        throw error;
    }
    console.log( files.join( '\n' ) );
}

CLI

Usage

Usage: find-pkg-readmes [options] [<dir>]

Options:

  -h,    --help                Print this message.
  -V,    --version             Print the package version.
         --pattern pattern     Inclusion glob pattern.
         --ignore pattern      Exclusion glob pattern.

Notes

  • If not provided a dir argument, the current working directory is the search directory.

  • To provide multiple exclusion glob patterns, set multiple --ignore option arguments.

    $ find-pkg-readmes --ignore=node_modules/** --ignore=build/** --ignore=reports/**
    

Examples

$ find-pkg-readmes
<pkg>
<pkg>
...