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:
parent
1abc0d4f86
commit
1863156114
88
README.md
88
README.md
|
@ -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).
|
||||||
|
@ -95,9 +118,9 @@ object can specify a number of optional arguments, including:
|
||||||
|
|
||||||
* `name`: the name of the file system, defaults to `'"local'`
|
* `name`: the name of the file system, defaults to `'"local'`
|
||||||
* `flags`: an Array of one or more flags to use when creating/opening the file system:
|
* `flags`: an Array of one or more flags to use when creating/opening the file system:
|
||||||
*`'FORMAT'` to force Filer to format (i.e., erase) the file system
|
* `'FORMAT'` to force Filer to format (i.e., erase) the file system
|
||||||
*`'NOCTIME'` to force Filer to not update `ctime` on nodes when metadata changes (i.e., for better performance)
|
* `'NOCTIME'` to force Filer to not update `ctime` on nodes when metadata changes (i.e., for better performance)
|
||||||
*`'NOMTIME'` to force Filer to not update `mtime` on nodes when data changes (i.e., for better performance)
|
* `'NOMTIME'` to force Filer to not update `mtime` on nodes when data changes (i.e., for better performance)
|
||||||
* `provider`: an explicit storage provider to use for the file system's database context provider. See the section on [Storage Providers](#providers).
|
* `provider`: an explicit storage provider to use for the file system's database context provider. See the section on [Storage Providers](#providers).
|
||||||
|
|
||||||
The `callback` function indicates when the file system is ready for use. Depending on the storage provider used, this might
|
The `callback` function indicates when the file system is ready for use. Depending on the storage provider used, this might
|
||||||
|
@ -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>
|
||||||
|
|
Loading…
Reference in New Issue