Add fs.watch() docs

This commit is contained in:
David Humphrey (:humph) david.humphrey@senecacollege.ca 2014-03-07 15:22:06 -05:00
parent eff4d9b5fc
commit 2f17d82126
1 changed files with 47 additions and 1 deletions

View File

@ -24,7 +24,6 @@ with the following differences:
* No synchronous versions of methods (e.g., `mkdir()` but not `mkdirSync()`). * No synchronous versions of methods (e.g., `mkdir()` but not `mkdirSync()`).
* No permissions (e.g., no `chown()`, `chmod()`, etc.). * No permissions (e.g., no `chown()`, `chmod()`, etc.).
* No support (yet) for `fs.watchFile()`, `fs.unwatchFile()`, `fs.watch()`.
* No support for stream-based operations (e.g., `fs.ReadStream`, `fs.WriteStream`). * No support for stream-based operations (e.g., `fs.ReadStream`, `fs.WriteStream`).
Filer has other features lacking in node.js (e.g., swappable backend Filer has other features lacking in node.js (e.g., swappable backend
@ -246,6 +245,7 @@ var fs = new Filer.FileSystem();
* [fs.fgetxattr(fd, name, callback)](#fgetxattr) * [fs.fgetxattr(fd, name, callback)](#fgetxattr)
* [fs.removexattr(path, name, callback)](#removexattr) * [fs.removexattr(path, name, callback)](#removexattr)
* [fs.fremovexattr(fd, name, callback)](#fremovexattr) * [fs.fremovexattr(fd, name, callback)](#fremovexattr)
* [fs.watch(filename, [options], [listener])](#watch)
#### fs.rename(oldPath, newPath, callback)<a name="rename"></a> #### fs.rename(oldPath, newPath, callback)<a name="rename"></a>
@ -942,6 +942,52 @@ fs.open('/myfile', 'r', function(err, fd) {
}); });
``` ```
#### fs.watch(filename, [options], [listener])<a name="watch"></a>
Watch for changes to a file or directory at `filename`. The object returned is an `FSWatcher`,
which is an [`EventEmitter`](http://nodejs.org/api/events.html) with the following additional method:
* `close()` - stops listening for changes, and removes all listeners from this instance. Use this
to stop watching a file or directory after calling `fs.watch()`.
The only supported option is `recursive`, which if `true` will cause a watch to be placed
on a directory, and all sub-directories and files beneath it.
The `listener` callback gets two arguments (event, filename). `event` is either 'rename' or 'change',
(currenty only `'rename'` is supported) and filename is the name of the file which triggered the event.
Unlike node.js, all watch events return a path. Also, all returned paths are absolute from the root
vs. just a relative filename.
Examples:
```javascript
// Example 1: create a watcher to see when a file is created
var watcher = fs.watch('/myfile', function(event, filename) {
// event will be 'change' and filename will be '/myfile'
// Stop watching for changes
watcher.close();
});
fs.writeFile('/myfile', 'data');
// Example 2: add the listener via watcher.on()
var watcher = fs.watch('/myfile2');
watcher.on('change', function(event, filename) {
// event will be 'change' and filename will be '/myfile2'
// Stop watching for changes
watcher.close();
});
fs.writeFile('/myfile2', 'data2');
// Example 3: recursive watch on /data dir
var watcher = fs.watch('/data', { recursive: true }, function(event, filename) {
// event will be 'change' and filename will be '/data/subdir/file'
// Stop watching for changes
watcher.close();
});
fs.writeFile('/data/subdir/file', 'data');
```
### FileSystemShell<a name="FileSystemShell"></a> ### FileSystemShell<a name="FileSystemShell"></a>
Many common file system shell operations are available by using a `FileSystemShell` object. Many common file system shell operations are available by using a `FileSystemShell` object.