From 1863156114ef50d0926cbf03a88c045ccbc2f547 Mon Sep 17 00:00:00 2001 From: David Humphrey Date: Wed, 25 Jun 2014 14:28:53 -0400 Subject: [PATCH] Update README.md Include additional things we've done recently but haven't documented (UMD module loading, npm/bower, Buffer rewrite). --- README.md | 90 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 65 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index a4eb4b2..6b74351 100644 --- a/README.md +++ b/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) -* [filer.min.js](https://raw.github.com/js-platform/filer/develop/dist/filer.min.js) +1. npm - `npm install filer` +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). @@ -95,9 +118,9 @@ object can specify a number of optional arguments, including: * `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: - *`'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) - *`'NOMTIME'` to force Filer to not update `mtime` on nodes when data changes (i.e., for better performance) + * `'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) + * `'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). 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. +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 + +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 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) -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) -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) -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 Uint8Array([5, 6, 7, 8]); -fs.writeFile('/myfile', more, function (err) { - if (err) throw err; -}); -fs.appendFile('/myfile', buffer, function (err) { +var data = new Filer.Buffer([1, 2, 3, 4]); +var more = new Filer.Buffer([5, 6, 7, 8]); + +fs.writeFile('/myfile', data, function (err) { if (err) throw err; + + fs.appendFile('/myfile', more, function (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)