Update README.md

Include additional things we've done recently but haven't documented (UMD module loading, npm/bower, Buffer rewrite).
This commit is contained in:
David Humphrey 2014-06-25 14:28:53 -04:00
parent 1abc0d4f86
commit 1863156114
1 changed files with 65 additions and 25 deletions

View File

@ -4,12 +4,13 @@
###Filer ###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 ###Compatibility
Filer is known to work in the following browsers/versions, with the specified [Storage Providers](#providers): Filer is known to work in the following browsers/versions, with the specified [Storage Providers](#providers):
* node.js: v0.10.*+
* IE: 10+ (IndexedDB) * IE: 10+ (IndexedDB)
* Firefox: 26+ (IndexedDB) * Firefox: 26+ (IndexedDB)
* Chrome: 31+ (IndexedDB, WebSQL) * 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). 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 ### Getting Started
@ -42,7 +65,7 @@ with the following differences:
* 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
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 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). 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. 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> ####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 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 ```javascript
// Create a file, shrink it, expand it. // 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) { fs.open('/myfile', 'w', function(err, fd) {
if(err) throw error; if(err) throw error;
@ -329,7 +366,7 @@ Example:
```javascript ```javascript
// Create a file, shrink it, expand it. // 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) { fs.open('/myfile', 'w', function(err, fd) {
if(err) throw error; if(err) throw error;
@ -726,7 +763,7 @@ Example:
```javascript ```javascript
// Create a file with the following bytes. // 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) { fs.open('/myfile', 'w', function(err, fd) {
if(err) throw error; 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> #### 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. 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 // Create a buffer large enough to hold the file's contents
var nbytes = expected = stats.size; var nbytes = expected = stats.size;
var buffer = new Uint8Array(nbytes); var buffer = new Filer.Buffer(nbytes);
var read = 0; var read = 0;
function readBytes(offset, position, length) { function readBytes(offset, position, length) {
@ -812,13 +849,13 @@ fs.readFile('/myfile.txt', 'utf8', function (err, data) {
// Read binary file // Read binary file
fs.readFile('/myfile.txt', function (err, data) { fs.readFile('/myfile.txt', function (err, data) {
if (err) throw err; 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> #### 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: Examples:
@ -829,7 +866,7 @@ fs.writeFile('/myfile.txt', "...data...", function (err) {
}); });
// Write binary file // 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) { fs.writeFile('/myfile', buffer, function (err) {
if (err) throw 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> #### 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: Examples:
@ -852,15 +889,18 @@ fs.appendFile('/myfile.txt', "Data...", function (err) {
// '/myfile.txt' would now read out 'More...Data...' // '/myfile.txt' would now read out 'More...Data...'
// Append binary file // 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; if (err) throw err;
});
fs.appendFile('/myfile', buffer, function (err) { fs.appendFile('/myfile', more, function (err) {
if (err) throw err; if (err) throw err;
});
// '/myfile' would now contain [1, 2, 3, 4, 5, 6, 7, 8] // '/myfile' would now contain [1, 2, 3, 4, 5, 6, 7, 8]
});
});
``` ```
#### fs.setxattr(path, name, value, [flag], callback)<a name="setxattr"></a> #### fs.setxattr(path, name, value, [flag], callback)<a name="setxattr"></a>