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

   1 # gaze [![Build Status](https://travis-ci.org/shama/gaze.png?branch=master)](https://travis-ci.org/shama/gaze)
   2
   3 A globbing fs.watch wrapper built from the best parts of other fine watch libs.
   4 Compatible with Node.js 0.10/0.8, Windows, OSX and Linux.
   5
   6 ![gaze](http://dontkry.com/images/repos/gaze.png)
   7
   8 ## Usage
   9 Install the module with: `npm install gaze` or place into your `package.json`
  10 and run `npm install`.
  11
  12 ```javascript
  13 var gaze = require('gaze');
  14
  15 // Watch all .js files/dirs in process.cwd()
  16 gaze('**/*.js', function(err, watcher) {
  17   // Files have all started watching
  18   // watcher === this
  19
  20   // Get all watched files
  21   console.log(this.watched());
  22
  23   // On file changed
  24   this.on('changed', function(filepath) {
  25     console.log(filepath + ' was changed');
  26   });
  27
  28   // On file added
  29   this.on('added', function(filepath) {
  30     console.log(filepath + ' was added');
  31   });
  32
  33   // On file deleted
  34   this.on('deleted', function(filepath) {
  35     console.log(filepath + ' was deleted');
  36   });
  37
  38   // On changed/added/deleted
  39   this.on('all', function(event, filepath) {
  40     console.log(filepath + ' was ' + event);
  41   });
  42
  43   // Get watched files with relative paths
  44   console.log(this.relative());
  45 });
  46
  47 // Also accepts an array of patterns
  48 gaze(['stylesheets/*.css', 'images/**/*.png'], function() {
  49   // Add more patterns later to be watched
  50   this.add(['js/*.js']);
  51 });
  52 ```
  53
  54 ### Alternate Interface
  55
  56 ```javascript
  57 var Gaze = require('gaze').Gaze;
  58
  59 var gaze = new Gaze('**/*');
  60
  61 // Files have all started watching
  62 gaze.on('ready', function(watcher) { });
  63
  64 // A file has been added/changed/deleted has occurred
  65 gaze.on('all', function(event, filepath) { });
  66 ```
  67
  68 ### Errors
  69
  70 ```javascript
  71 gaze('**/*', function() {
  72   this.on('error', function(err) {
  73     // Handle error here
  74   });
  75 });
  76 ```
  77
  78 ### Minimatch / Glob
  79
  80 See [isaacs's minimatch](https://github.com/isaacs/minimatch) for more
  81 information on glob patterns.
  82
  83 ## Documentation
  84
  85 ### gaze(patterns, [options], callback)
  86
  87 * `patterns` {String|Array} File patterns to be matched
  88 * `options` {Object}
  89 * `callback` {Function}
  90   * `err` {Error | null}
  91   * `watcher` {Object} Instance of the Gaze watcher
  92
  93 ### Class: gaze.Gaze
  94
  95 Create a Gaze object by instanting the `gaze.Gaze` class.
  96
  97 ```javascript
  98 var Gaze = require('gaze').Gaze;
  99 var gaze = new Gaze(pattern, options, callback);
 100 ```
 101
 102 #### Properties
 103
 104 * `options` The options object passed in.
 105   * `interval` {integer} Interval to pass to fs.watchFile
 106   * `debounceDelay` {integer} Delay for events called in succession for the same
 107     file/event
 108
 109 #### Events
 110
 111 * `ready(watcher)` When files have been globbed and watching has begun.
 112 * `all(event, filepath)` When an `added`, `changed` or `deleted` event occurs.
 113 * `added(filepath)` When a file has been added to a watch directory.
 114 * `changed(filepath)` When a file has been changed.
 115 * `deleted(filepath)` When a file has been deleted.
 116 * `renamed(newPath, oldPath)` When a file has been renamed.
 117 * `end()` When the watcher is closed and watches have been removed.
 118 * `error(err)` When an error occurs.
 119 * `nomatch` When no files have been matched.
 120
 121 #### Methods
 122
 123 * `emit(event, [...])` Wrapper for the EventEmitter.emit.
 124   `added`|`changed`|`deleted` events will also trigger the `all` event.
 125 * `close()` Unwatch all files and reset the watch instance.
 126 * `add(patterns, callback)` Adds file(s) patterns to be watched.
 127 * `remove(filepath)` removes a file or directory from being watched. Does not
 128   recurse directories.
 129 * `watched()` Returns the currently watched files.
 130 * `relative([dir, unixify])` Returns the currently watched files with relative paths.
 131   * `dir` {string} Only return relative files for this directory.
 132   * `unixify` {boolean} Return paths with `/` instead of `\\` if on Windows.
 133
 134 ## FAQs
 135
 136 ### Why Another `fs.watch` Wrapper?
 137 I liked parts of other `fs.watch` wrappers but none had all the features I
 138 needed. This lib combines the features I needed from other fine watch libs:
 139 Speedy data behavior from
 140 [paulmillr's chokidar](https://github.com/paulmillr/chokidar), API interface
 141 from [mikeal's watch](https://github.com/mikeal/watch) and file globbing using
 142 [isaacs's glob](https://github.com/isaacs/node-glob) which is also used by
 143 [cowboy's Grunt](https://github.com/gruntjs/grunt).
 144
 145 ### How do I fix the error `EMFILE: Too many opened files.`?
 146 This is because of your system's max opened file limit. For OSX the default is
 147 very low (256). Increase your limit temporarily with `ulimit -n 10480`, the
 148 number being the new max limit.
 149
 150 ## Contributing
 151 In lieu of a formal styleguide, take care to maintain the existing coding style.
 152 Add unit tests for any new or changed functionality. Lint and test your code
 153 using [grunt](http://gruntjs.com/).
 154
 155 ## Release History
 156 * 0.5.2 - Fix for ENOENT error with non-existent symlinks.
 157 * 0.5.1 - Use setImmediate (process.nextTick for node v0.8) to defer ready/nomatch events (@amasad).
 158 * 0.5.0 - Process is now kept alive while watching files. Emits a nomatch event when no files are matching.
 159 * 0.4.3 - Track file additions in newly created folders (@brett-shwom).
 160 * 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).
 161 * 0.4.1 - Fix watchDir not respecting close in race condition (@chrisirhc).
 162 * 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).
 163 * 0.3.4 - Code clean up. Fix path must be strings errors (@groner). Fix incorrect added events (@groner).
 164 * 0.3.3 - Fix for multiple patterns with negate.
 165 * 0.3.2 - Emit `end` before removeAllListeners.
 166 * 0.3.1 - Fix added events within subfolder patterns.
 167 * 0.3.0 - Handle safewrite events, `forceWatchMethod` option removed, bug fixes and watch optimizations (@rgaskill).
 168 * 0.2.2 - Fix issue where subsequent add calls dont get watched (@samcday). removeAllListeners on close.
 169 * 0.2.1 - Fix issue with invalid `added` events in current working dir.
 170 * 0.2.0 - Support and mark folders with `path.sep`. Add `forceWatchMethod` option. Support `renamed` events.
 171 * 0.1.6 - Recognize the `cwd` option properly
 172 * 0.1.5 - Catch too many open file errors
 173 * 0.1.4 - Really fix the race condition with 2 watches
 174 * 0.1.3 - Fix race condition with 2 watches
 175 * 0.1.2 - Read triggering changed event fix
 176 * 0.1.1 - Minor fixes
 177 * 0.1.0 - Initial release
 178
 179 ## License
 180 Copyright (c) 2013 Kyle Robinson Young
 181 Licensed under the MIT license.