vnfmarket/src/main/webapp/vnfmarket/node_modules/readdirp/README.md

   1 # readdirp [![Build Status](https://secure.travis-ci.org/thlorenz/readdirp.png)](http://travis-ci.org/thlorenz/readdirp)
   2
   3 [![NPM](https://nodei.co/npm/readdirp.png?downloads=true&stars=true)](https://nodei.co/npm/readdirp/)
   4
   5 Recursive version of [fs.readdir](http://nodejs.org/docs/latest/api/fs.html#fs_fs_readdir_path_callback). Exposes a **stream api**.
   6
   7 ```javascript
   8 var readdirp = require('readdirp')
   9   , path = require('path')
  10   , es = require('event-stream');
  11
  12 // print out all JavaScript files along with their size
  13
  14 var stream = readdirp({ root: path.join(__dirname), fileFilter: '*.js' });
  15 stream
  16   .on('warn', function (err) {
  17     console.error('non-fatal error', err);
  18     // optionally call stream.destroy() here in order to abort and cause 'close' to be emitted
  19   })
  20   .on('error', function (err) { console.error('fatal error', err); })
  21   .pipe(es.mapSync(function (entry) {
  22     return { path: entry.path, size: entry.stat.size };
  23   }))
  24   .pipe(es.stringify())
  25   .pipe(process.stdout);
  26 ```
  27
  28 Meant to be one of the recursive versions of [fs](http://nodejs.org/docs/latest/api/fs.html) functions, e.g., like [mkdirp](https://github.com/substack/node-mkdirp).
  29
  30 **Table of Contents**  *generated with [DocToc](http://doctoc.herokuapp.com/)*
  31
  32 - [Installation](#installation)
  33 - [API](#api)
  34         - [entry stream](#entry-stream)
  35         - [options](#options)
  36         - [entry info](#entry-info)
  37         - [Filters](#filters)
  38         - [Callback API](#callback-api)
  39                 - [allProcessed ](#allprocessed)
  40                 - [fileProcessed](#fileprocessed)
  41 - [More Examples](#more-examples)
  42         - [stream api](#stream-api)
  43         - [stream api pipe](#stream-api-pipe)
  44         - [grep](#grep)
  45         - [using callback api](#using-callback-api)
  46         - [tests](#tests)
  47
  48
  49 # Installation
  50
  51     npm install readdirp
  52
  53 # API
  54
  55 ***var entryStream = readdirp (options)***
  56
  57 Reads given root recursively and returns a `stream` of [entry info](#entry-info)s.
  58
  59 ## entry stream
  60
  61 Behaves as follows:
  62
  63 - `emit('data')` passes an [entry info](#entry-info) whenever one is found
  64 - `emit('warn')` passes a non-fatal `Error` that prevents a file/directory from being processed (i.e., if it is
  65   inaccessible to the user)
  66 - `emit('error')` passes a fatal `Error` which also ends the stream (i.e., when illegal options where passed)
  67 - `emit('end')` called when all entries were found and no more will be emitted (i.e., we are done)
  68 - `emit('close')` called when the stream is destroyed via `stream.destroy()` (which could be useful if you want to
  69   manually abort even on a non fatal error) - at that point the stream is no longer `readable` and no more entries,
  70   warning or errors are emitted
  71 - to learn more about streams, consult the very detailed
  72   [nodejs streams documentation](http://nodejs.org/api/stream.html) or the
  73   [stream-handbook](https://github.com/substack/stream-handbook)
  74
  75
  76 ## options
  77
  78 - **root**: path in which to start reading and recursing into subdirectories
  79
  80 - **fileFilter**: filter to include/exclude files found (see [Filters](#filters) for more)
  81
  82 - **directoryFilter**: filter to include/exclude directories found and to recurse into (see [Filters](#filters) for more)
  83
  84 - **depth**: depth at which to stop recursing even if more subdirectories are found
  85
  86 - **entryType**: determines if data events on the stream should be emitted for `'files'`, `'directories'`, `'both'`, or `'all'`. Setting to `'all'` will also include entries for other types of file descriptors like character devices, unix sockets and named pipes. Defaults to `'files'`.
  87
  88 - **lstat**: if `true`, readdirp uses `fs.lstat` instead of `fs.stat` in order to stat files and includes symlink entries in the stream along with files.
  89
  90 ## entry info
  91
  92 Has the following properties:
  93
  94 - **parentDir**     :  directory in which entry was found (relative to given root)
  95 - **fullParentDir** :  full path to parent directory
  96 - **name**          :  name of the file/directory
  97 - **path**          :  path to the file/directory (relative to given root)
  98 - **fullPath**      :  full path to the file/directory found
  99 - **stat**          :  built in [stat object](http://nodejs.org/docs/v0.4.9/api/fs.html#fs.Stats)
 100 - **Example**: (assuming root was `/User/dev/readdirp`)
 101
 102         parentDir     :  'test/bed/root_dir1',
 103         fullParentDir :  '/User/dev/readdirp/test/bed/root_dir1',
 104         name          :  'root_dir1_subdir1',
 105         path          :  'test/bed/root_dir1/root_dir1_subdir1',
 106         fullPath      :  '/User/dev/readdirp/test/bed/root_dir1/root_dir1_subdir1',
 107         stat          :  [ ... ]
 108
 109 ## Filters
 110
 111 There are three different ways to specify filters for files and directories respectively.
 112
 113 - **function**: a function that takes an entry info as a parameter and returns true to include or false to exclude the entry
 114
 115 - **glob string**: a string (e.g., `*.js`) which is matched using [minimatch](https://github.com/isaacs/minimatch), so go there for more
 116     information.
 117
 118     Globstars (`**`) are not supported since specifiying a recursive pattern for an already recursive function doesn't make sense.
 119
 120     Negated globs (as explained in the minimatch documentation) are allowed, e.g., `!*.txt` matches everything but text files.
 121
 122 - **array of glob strings**: either need to be all inclusive or all exclusive (negated) patterns otherwise an error is thrown.
 123
 124     `[ '*.json', '*.js' ]` includes all JavaScript and Json files.
 125
 126
 127     `[ '!.git', '!node_modules' ]` includes all directories except the '.git' and 'node_modules'.
 128
 129 Directories that do not pass a filter will not be recursed into.
 130
 131 ## Callback API
 132
 133 Although the stream api is recommended, readdirp also exposes a callback based api.
 134
 135 ***readdirp (options, callback1 [, callback2])***
 136
 137 If callback2 is given, callback1 functions as the **fileProcessed** callback, and callback2 as the **allProcessed** callback.
 138
 139 If only callback1 is given, it functions as the **allProcessed** callback.
 140
 141 ### allProcessed
 142
 143 - function with err and res parameters, e.g., `function (err, res) { ... }`
 144 - **err**: array of errors that occurred during the operation, **res may still be present, even if errors occurred**
 145 - **res**: collection of file/directory [entry infos](#entry-info)
 146
 147 ### fileProcessed
 148
 149 - function with [entry info](#entry-info) parameter e.g., `function (entryInfo) { ... }`
 150
 151
 152 # More Examples
 153
 154 `on('error', ..)`, `on('warn', ..)` and `on('end', ..)` handling omitted for brevity
 155
 156 ```javascript
 157 var readdirp = require('readdirp');
 158
 159 // Glob file filter
 160 readdirp({ root: './test/bed', fileFilter: '*.js' })
 161   .on('data', function (entry) {
 162     // do something with each JavaScript file entry
 163   });
 164
 165 // Combined glob file filters
 166 readdirp({ root: './test/bed', fileFilter: [ '*.js', '*.json' ] })
 167   .on('data', function (entry) {
 168     // do something with each JavaScript and Json file entry
 169   });
 170
 171 // Combined negated directory filters
 172 readdirp({ root: './test/bed', directoryFilter: [ '!.git', '!*modules' ] })
 173   .on('data', function (entry) {
 174     // do something with each file entry found outside '.git' or any modules directory
 175   });
 176
 177 // Function directory filter
 178 readdirp({ root: './test/bed', directoryFilter: function (di) { return di.name.length === 9; } })
 179   .on('data', function (entry) {
 180     // do something with each file entry found inside directories whose name has length 9
 181   });
 182
 183 // Limiting depth
 184 readdirp({ root: './test/bed', depth: 1 })
 185   .on('data', function (entry) {
 186     // do something with each file entry found up to 1 subdirectory deep
 187   });
 188
 189 // callback api
 190 readdirp(
 191     { root: '.' }
 192   , function(fileInfo) {
 193       // do something with file entry here
 194     }
 195   , function (err, res) {
 196       // all done, move on or do final step for all file entries here
 197     }
 198 );
 199 ```
 200
 201 Try more examples by following [instructions](https://github.com/thlorenz/readdirp/blob/master/examples/Readme.md)
 202 on how to get going.
 203
 204 ## stream api
 205
 206 [stream-api.js](https://github.com/thlorenz/readdirp/blob/master/examples/stream-api.js)
 207
 208 Demonstrates error and data handling by listening to events emitted from the readdirp stream.
 209
 210 ## stream api pipe
 211
 212 [stream-api-pipe.js](https://github.com/thlorenz/readdirp/blob/master/examples/stream-api-pipe.js)
 213
 214 Demonstrates error handling by listening to events emitted from the readdirp stream and how to pipe the data stream into
 215 another destination stream.
 216
 217 ## grep
 218
 219 [grep.js](https://github.com/thlorenz/readdirp/blob/master/examples/grep.js)
 220
 221 Very naive implementation of grep, for demonstration purposes only.
 222
 223 ## using callback api
 224
 225 [callback-api.js](https://github.com/thlorenz/readdirp/blob/master/examples/callback-api.js)
 226
 227 Shows how to pass callbacks in order to handle errors and/or data.
 228
 229 ## tests
 230
 231 The [readdirp tests](https://github.com/thlorenz/readdirp/blob/master/test/readdirp.js) also will give you a good idea on
 232 how things work.
 233