www.aleph1.co.uk Git - yaffs-website/blob - node_modules/grunt-contrib-watch/node_modules/gaze/README.md

   1 # gaze [![Build Status](http://img.shields.io/travis/shama/gaze.svg)](https://travis-ci.org/shama/gaze) [![Build status](https://ci.appveyor.com/api/projects/status/vtx65w9eg511tgo4)](https://ci.appveyor.com/project/shama/gaze)
   2
   3 A globbing fs.watch wrapper built from the best parts of other fine watch libs.
   4 Compatible with Node.js 4.x/0.12/0.10, Windows, OSX and Linux.
   5
   6 ![gaze](http://dontkry.com/images/repos/gaze.png)
   7
   8 [![NPM](https://nodei.co/npm/gaze.png?downloads=true)](https://nodei.co/npm/gaze/)
   9
  10 ## Usage
  11 Install the module with: `npm install gaze` or place into your `package.json`
  12 and run `npm install`.
  13
  14 ```javascript
  15 var gaze = require('gaze');
  16
  17 // Watch all .js files/dirs in process.cwd()
  18 gaze('**/*.js', function(err, watcher) {
  19   // Files have all started watching
  20   // watcher === this
  21
  22   // Get all watched files
  23   var watched = this.watched();
  24
  25   // On file changed
  26   this.on('changed', function(filepath) {
  27     console.log(filepath + ' was changed');
  28   });
  29
  30   // On file added
  31   this.on('added', function(filepath) {
  32     console.log(filepath + ' was added');
  33   });
  34
  35   // On file deleted
  36   this.on('deleted', function(filepath) {
  37     console.log(filepath + ' was deleted');
  38   });
  39
  40   // On changed/added/deleted
  41   this.on('all', function(event, filepath) {
  42     console.log(filepath + ' was ' + event);
  43   });
  44
  45   // Get watched files with relative paths
  46   var files = this.relative();
  47 });
  48
  49 // Also accepts an array of patterns
  50 gaze(['stylesheets/*.css', 'images/**/*.png'], function() {
  51   // Add more patterns later to be watched
  52   this.add(['js/*.js']);
  53 });
  54 ```
  55
  56 ### Alternate Interface
  57
  58 ```javascript
  59 var Gaze = require('gaze').Gaze;
  60
  61 var gaze = new Gaze('**/*');
  62
  63 // Files have all started watching
  64 gaze.on('ready', function(watcher) { });
  65
  66 // A file has been added/changed/deleted has occurred
  67 gaze.on('all', function(event, filepath) { });
  68 ```
  69
  70 ### Errors
  71
  72 ```javascript
  73 gaze('**/*', function(error, watcher) {
  74   if (error) {
  75     // Handle error if it occurred while starting up
  76   }
  77 });
  78
  79 // Or with the alternative interface
  80 var gaze = new Gaze();
  81 gaze.on('error', function(error) {
  82   // Handle error here
  83 });
  84 gaze.add('**/*');
  85 ```
  86
  87 ### Minimatch / Glob
  88
  89 See [isaacs's minimatch](https://github.com/isaacs/minimatch) for more
  90 information on glob patterns.
  91
  92 ## Documentation
  93
  94 ### gaze([patterns, options, callback])
  95
  96 * `patterns` {String|Array} File patterns to be matched
  97 * `options` {Object}
  98 * `callback` {Function}
  99   * `err` {Error | null}
 100   * `watcher` {Object} Instance of the Gaze watcher
 101
 102 ### Class: gaze.Gaze
 103
 104 Create a Gaze object by instancing the `gaze.Gaze` class.
 105
 106 ```javascript
 107 var Gaze = require('gaze').Gaze;
 108 var gaze = new Gaze(pattern, options, callback);
 109 ```
 110
 111 #### Properties
 112
 113 * `options` The options object passed in.
 114   * `interval` {integer} Interval to pass to fs.watchFile
 115   * `debounceDelay` {integer} Delay for events called in succession for the same
 116     file/event in milliseconds
 117   * `mode` {string} Force the watch mode. Either `'auto'` (default), `'watch'` (force native events), or `'poll'` (force stat polling).
 118   * `cwd` {string} The current working directory to base file patterns from. Default is `process.cwd()`.
 119
 120 #### Events
 121
 122 * `ready(watcher)` When files have been globbed and watching has begun.
 123 * `all(event, filepath)` When an `added`, `changed` or `deleted` event occurs.
 124 * `added(filepath)` When a file has been added to a watch directory.
 125 * `changed(filepath)` When a file has been changed.
 126 * `deleted(filepath)` When a file has been deleted.
 127 * `renamed(newPath, oldPath)` When a file has been renamed.
 128 * `end()` When the watcher is closed and watches have been removed.
 129 * `error(err)` When an error occurs.
 130 * `nomatch` When no files have been matched.
 131
 132 #### Methods
 133
 134 * `emit(event, [...])` Wrapper for the EventEmitter.emit.
 135   `added`|`changed`|`deleted` events will also trigger the `all` event.
 136 * `close()` Unwatch all files and reset the watch instance.
 137 * `add(patterns, callback)` Adds file(s) patterns to be watched.
 138 * `remove(filepath)` removes a file or directory from being watched. Does not
 139   recurse directories.
 140 * `watched()` Returns the currently watched files.
 141 * `relative([dir, unixify])` Returns the currently watched files with relative paths.
 142   * `dir` {string} Only return relative files for this directory.
 143   * `unixify` {boolean} Return paths with `/` instead of `\\` if on Windows.
 144
 145 ## Similar Projects
 146
 147 Other great watch libraries to try are:
 148
 149 * [paulmillr's chokidar](https://github.com/paulmillr/chokidar)
 150 * [amasad's sane](https://github.com/amasad/sane)
 151 * [mikeal's watch](https://github.com/mikeal/watch)
 152 * [github's pathwatcher](https://github.com/atom/node-pathwatcher)
 153 * [bevry's watchr](https://github.com/bevry/watchr)
 154
 155 ## Contributing
 156 In lieu of a formal styleguide, take care to maintain the existing coding style.
 157 Add unit tests for any new or changed functionality. Lint and test your code
 158 using [grunt](http://gruntjs.com/).
 159
 160 ## Release History
 161 * 1.1.2 - Prevent more ENOENT errors from escaping (@alexgorbatchev).
 162 * 1.1.1 - Prevent fs.watch errors from escaping error handler (@rosen-vladimirov). Fix _addToWatched without path.sep (@wyicwx).
 163 * 1.1.0 - Update to `globule@1.0.0` with `minimatch >= 3.0.0`.
 164 * 1.0.0 - Revert back to 0.5.2. Drop support for Node.js v0.8. Fix for `maxListeners`. Update globule to `0.2.0`.
 165 * 0.6.4 - Catch and emit error from readdir (@oconnore). Fix for 0 maxListeners. Use graceful-fs to avoid EMFILE errors in other places fs is used. Better method to determine if pathwatcher was built. Fix keeping process alive too much, only init pathwatcher if a file is being watched. Set min required to Windows Vista when building on Windows (@pvolok).
 166 * 0.6.3 - Add support for node v0.11
 167 * 0.6.2 - Fix argument error with watched(). Fix for erroneous added events on folders. Ignore msvs build error 4244.
 168 * 0.6.1 - Fix for absolute paths.
 169 * 0.6.0 - Uses native OS events (fork of pathwatcher) but can fall back to stat polling. Everything is async to avoid blocking, including `relative()` and `watched()`. Better error handling. Update to globule@0.2.0. No longer watches `cwd` by default. Added `mode` option. Better `EMFILE` message. Avoids `ENOENT` errors with symlinks. All constructor arguments are optional.
 170 * 0.5.2 - Fix for ENOENT error with non-existent symlinks [BACKPORTED].
 171 * 0.5.1 - Use setImmediate (process.nextTick for node v0.8) to defer ready/nomatch events (@amasad).
 172 * 0.5.0 - Process is now kept alive while watching files. Emits a nomatch event when no files are matching.
 173 * 0.4.3 - Track file additions in newly created folders (@brett-shwom).
 174 * 0.4.2 - Fix .remove() method to remove a single file in a directory (@kaelzhang). Fixing Cannot call method 'call' of undefined (@krasimir). Track new file additions within folders (@brett-shwom).
 175 * 0.4.1 - Fix watchDir not respecting close in race condition (@chrisirhc).
 176 * 0.4.0 - Drop support for node v0.6. Use globule for file matching. Avoid node v0.10 path.resolve/join errors. Register new files when added to non-existent folder. Multiple instances can now poll the same files (@jpommerening).
 177 * 0.3.4 - Code clean up. Fix path must be strings errors (@groner). Fix incorrect added events (@groner).
 178 * 0.3.3 - Fix for multiple patterns with negate.
 179 * 0.3.2 - Emit `end` before removeAllListeners.
 180 * 0.3.1 - Fix added events within subfolder patterns.
 181 * 0.3.0 - Handle safewrite events, `forceWatchMethod` option removed, bug fixes and watch optimizations (@rgaskill).
 182 * 0.2.2 - Fix issue where subsequent add calls dont get watched (@samcday). removeAllListeners on close.
 183 * 0.2.1 - Fix issue with invalid `added` events in current working dir.
 184 * 0.2.0 - Support and mark folders with `path.sep`. Add `forceWatchMethod` option. Support `renamed` events.
 185 * 0.1.6 - Recognize the `cwd` option properly
 186 * 0.1.5 - Catch too many open file errors
 187 * 0.1.4 - Really fix the race condition with 2 watches
 188 * 0.1.3 - Fix race condition with 2 watches
 189 * 0.1.2 - Read triggering changed event fix
 190 * 0.1.1 - Minor fixes
 191 * 0.1.0 - Initial release
 192
 193 ## License
 194 Copyright (c) 2015 Kyle Robinson Young
 195 Licensed under the MIT license.