Update README.md

Include additional things we've done recently but haven't documented (UMD module loading, npm/bower, Buffer rewrite).

README.md

@@ -4,12 +4,13 @@
 
 ###Filer
 
-Filer is a POSIX-like file system interface for browser-based JavaScript.
+Filer is a POSIX-like file system interface for node.js and browser-based JavaScript.
 
 ###Compatibility
 
 Filer is known to work in the following browsers/versions, with the specified [Storage Providers](#providers):
 
+* node.js: v0.10.*+
 * IE: 10+ (IndexedDB)
 * Firefox: 26+ (IndexedDB)
 * Chrome: 31+ (IndexedDB, WebSQL)
@@ -25,12 +26,34 @@ See the section on [Storage Providers](#providers).
 
 Want to join the fun? We'd love to have you! See [CONTRIBUTING](https://github.com/js-platform/filer/blob/develop/CONTRIBUTING.md).
 
-###Downloading
+### How to Get It
 
-Pre-built versions of the library are available in the repo:
+Filer can be obtained in a number of ways:
 
-* [filer.js](https://raw.github.com/js-platform/filer/develop/dist/filer.js)
+1. npm - `npm install filer`
-* [filer.min.js](https://raw.github.com/js-platform/filer/develop/dist/filer.min.js)
+2. bower - `bower install filer`
+3. download pre-built versions: [filer.js](https://raw.github.com/js-platform/filer/develop/dist/filer.js), [filer.min.js](https://raw.github.com/js-platform/filer/develop/dist/filer.min.js)
+
+### Loading and Usage
+
+Filer is built as a UMD module and can therefore be loaded as a CommonJS or AMD module, or used via the global.
+
+```javascript
+// Option 1: Filer loaded via require() in node/browserify
+var Filer = require('filer');
+
+// Option 2: Filer loaded via RequireJS
+requirejs.config({
+  baseUrl: '/',
+  paths: {
+    'filer': "filer/dist/filer'
+  }
+});
+requirejs(["filer"], function(Filer) {...}
+
+// Option 3: Filer on global
+var Filer = window.Filer;
+```
 
 ### Getting Started
 
@@ -42,7 +65,7 @@ with the following differences:
 * No support for stream-based operations (e.g., `fs.ReadStream`, `fs.WriteStream`).
 
 Filer has other features lacking in node.js (e.g., swappable backend
-storage providers, support for encryption and compression, extended attributes, etc).
+storage providers, extended attributes, etc).
 
 Like node.js, the API is asynchronous and most methods expect the caller to provide
 a callback function (note: like node.js, Filer will supply one if it's missing).
@@ -161,6 +184,20 @@ if( Filer.FileSystem.providers.WebSQL.isSupported() ) {
 
 You can also write your own provider if you need a different backend. See the code in `src/providers` for details.
 
+A number of other providers have been written, including:
+
+* node.js fs provider: https://github.com/humphd/filer-fs
+* node.js Amazon S3 provider: https://github.com/alicoding/filer-s3
+
+####Filer.Buffer<a name="FilerBuffer"></a>
+
+When reading and writing data, Filer follows node.js and uses [`Buffer`](http://nodejs.org/api/buffer.html).
+When in a node.js environment, native `Buffer`s can be used, or Filer.Buffer, which is a shortcut
+to node's `Buffer`.  In a browser, you can use also use `Filer.Buffer`.
+
+NOTE: a `Filer.Buffer` in a browser is really an augmented `Uint8Array` (i.e., the node `Buffer` api
+methods are added to the instance). See https://github.com/feross/buffer for more details.
+
 ####Filer.Path<a name="FilerPath"></a>
 
 The node.js [path module](http://nodejs.org/api/path.html) is available via the `Filer.Path` object. It is
@@ -298,7 +335,7 @@ Example:
 
 ```javascript
 // Create a file, shrink it, expand it.
-var buffer = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
+var buffer = new Filer.Buffer([1, 2, 3, 4, 5, 6, 7, 8]);
 
 fs.open('/myfile', 'w', function(err, fd) {
   if(err) throw error;
@@ -329,7 +366,7 @@ Example:
 
 ```javascript
 // Create a file, shrink it, expand it.
-var buffer = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
+var buffer = new Filer.Buffer([1, 2, 3, 4, 5, 6, 7, 8]);
 
 fs.open('/myfile', 'w', function(err, fd) {
   if(err) throw error;
@@ -726,7 +763,7 @@ Example:
 
 ```javascript
 // Create a file with the following bytes.
-var buffer = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
+var buffer = new Filer.Buffer([1, 2, 3, 4, 5, 6, 7, 8]);
 
 fs.open('/myfile', 'w', function(err, fd) {
   if(err) throw error;
@@ -755,7 +792,7 @@ fs.open('/myfile', 'w', function(err, fd) {
 
 #### fs.read(fd, buffer, offset, length, position, callback)<a name="read"></a>
 
-Read bytes from the file specified by `fd` into ArrayBufferView `buffer`. Asynchronous [read(2), pread(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/read.html). The `offset` and `length` arguments describe the part of the buffer to be used. The `position` refers to the offset from the beginning of the file where this data should be read. If `position` is `null`, the data will be written at the current position. The callback gets `(error, nbytes)`, where `nbytes` is the number of bytes read.
+Read bytes from the file specified by `fd` into `buffer`. Asynchronous [read(2), pread(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/read.html). The `offset` and `length` arguments describe the part of the buffer to be used. The `position` refers to the offset from the beginning of the file where this data should be read. If `position` is `null`, the data will be written at the current position. The callback gets `(error, nbytes)`, where `nbytes` is the number of bytes read.
 
 NOTE: Filer currently reads into the buffer in a single operation. However, future versions may do it in chunks.
 
@@ -771,7 +808,7 @@ fs.open('/myfile', 'r', function(err, fd) {
 
     // Create a buffer large enough to hold the file's contents
     var nbytes = expected = stats.size;
-    var buffer = new Uint8Array(nbytes);
+    var buffer = new Filer.Buffer(nbytes);
     var read = 0;
 
     function readBytes(offset, position, length) {
@@ -812,13 +849,13 @@ fs.readFile('/myfile.txt', 'utf8', function (err, data) {
 // Read binary file
 fs.readFile('/myfile.txt', function (err, data) {
   if (err) throw err;
-  // data is now the contents of /myfile.txt (i.e., an Uint8Array of bytes)
+  // data is now the contents of /myfile.txt (i.e., a Buffer with the bytes)
 });
 ```
 
 #### fs.writeFile(filename, data, [options], callback)<a name="writeFile"></a>
 
-Writes data to a file. `data` can be a string or an ArrayBufferView, in which case any encoding option is ignored. The `options` argument is optional, and can take the form `"utf8"` (i.e., an encoding) or be an object literal: `{ encoding: "utf8", flag: "w" }`. If no encoding is specified, and `data` is a string, the encoding defaults to `'utf8'`.  The callback gets `(error)`.
+Writes data to a file. `data` can be a string or `Buffer`, in which case any encoding option is ignored. The `options` argument is optional, and can take the form `"utf8"` (i.e., an encoding) or be an object literal: `{ encoding: "utf8", flag: "w" }`. If no encoding is specified, and `data` is a string, the encoding defaults to `'utf8'`.  The callback gets `(error)`.
 
 Examples:
 
@@ -829,7 +866,7 @@ fs.writeFile('/myfile.txt', "...data...", function (err) {
 });
 
 // Write binary file
-var buffer = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]);
+var buffer = new Filer.Buffer([1, 2, 3, 4, 5, 6, 7, 8]);
 fs.writeFile('/myfile', buffer, function (err) {
   if (err) throw err;
 });
@@ -837,7 +874,7 @@ fs.writeFile('/myfile', buffer, function (err) {
 
 #### fs.appendFile(filename, data, [options], callback)<a name="appendFile"></a>
 
-Writes data to the end of a file. `data` can be a string or an ArrayBufferView, in which case any encoding option is ignored. The `options` argument is optional, and can take the form `"utf8"` (i.e., an encoding) or be an object literal: `{ encoding: "utf8", flag: "w" }`. If no encoding is specified, and `data` is a string, the encoding defaults to `'utf8'`.  The callback gets `(error)`.
+Writes data to the end of a file. `data` can be a string or a `Buffer`, in which case any encoding option is ignored. The `options` argument is optional, and can take the form `"utf8"` (i.e., an encoding) or be an object literal: `{ encoding: "utf8", flag: "w" }`. If no encoding is specified, and `data` is a string, the encoding defaults to `'utf8'`.  The callback gets `(error)`.
 
 Examples:
 
@@ -852,15 +889,18 @@ fs.appendFile('/myfile.txt', "Data...", function (err) {
 // '/myfile.txt' would now read out 'More...Data...'
 
 // Append binary file
-var more = new Uint8Array([1, 2, 3, 4]);
+var data = new Filer.Buffer([1, 2, 3, 4]);
-var data = new Uint8Array([5, 6, 7, 8]);
+var more = new Filer.Buffer([5, 6, 7, 8]);
-fs.writeFile('/myfile', more, function (err) {
+
+fs.writeFile('/myfile', data, function (err) {
   if (err) throw err;
-});
+
-fs.appendFile('/myfile', buffer, function (err) {
+  fs.appendFile('/myfile', more, function (err) {
     if (err) throw err;
-});
+    
     // '/myfile' would now contain [1, 2, 3, 4, 5, 6, 7, 8]
+  });
+});
 ```
 
 #### fs.setxattr(path, name, value, [flag], callback)<a name="setxattr"></a>