LumeWeb
/
filer
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update docs for shell changes

This commit is contained in:
David Humphrey (:humph) david.humphrey@senecacollege.ca 2014-02-19 15:22:12 -05:00
parent 21f5d15f51
commit dd87117ff8
2 changed files with 272 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

274
README.md
View File

@ -36,7 +36,7 @@ Errors are passed to callbacks through the first parameter. As with node.js,
there is no guarantee that file system operations will be executed in the order
they are invoked. Ensure proper ordering by chaining operations in callbacks.
### Example
### Overview
To create a new file system or open an existing one, create a new `FileSystem`
instance. By default, a new [IndexedDB](https://developer.mozilla.org/en/docs/IndexedDB)
@ -58,6 +58,15 @@ fs.open('/myfile', 'w+', function(err, fd) {
});
```
For a complete list of `FileSystem` methods and examples, see the [FileSystem Instance Methods](#FileSystemMethods)
section below.
Filer also supports node's Path module. See the [Filer.Path](#FilerPath) section below.
In addition, common shell operations (e.g., rm, touch, cat, etc.) are supported via the
`FileSystemShell` object, which can be used with a `FileSystem`. See the[Filer.FileSystemShell](#FileSystemShell)
section below.
### API Reference
Like node.js, callbacks for methods that accept them are optional but suggested (i.e., if
@ -162,7 +171,7 @@ var fs = new FileSystem({ provider: compressionAdapter });
You can also write your own adapter if you need to add new capabilities to the providers. Adapters share the same
interface as providers. See the code in `src/providers` and `src/adapters` for many examples.
####Filer.Path
####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
identical to the node.js version with the following differences:
@ -195,7 +204,7 @@ For more info see the docs in the [path module](http://nodejs.org/api/path.html)
* `path.sep`
* `path.delimiter`
###FileSystem Instance Methods
###FileSystem Instance Methods<a name="FileSystemMethods"></a>
Once a `FileSystem` is created, it has the following methods. NOTE: code examples below assume
a `FileSystem` instance named `fs` has been created like so:
@ -911,3 +920,262 @@ fs.open('/myfile', 'r', function(err, fd) {
fs.close(fd);
});
```
### Filer.FileSystemShell<a name="FileSystemShell"></a>
Many common file system shell operations are available by using a `FileSystemShell` object.
The `FileSystemShell` is used in conjuction with a `FileSystem`, and provides augmented
features. Many separate `FileSystemShell` objects can exist per `FileSystem`, but each
`FileSystemShell` is bound to a single instance of a `FileSystem` for its lifetime.
There are two ways to create a `FileSystemShell` object:
```javascript
// Method 1: obtain a shell from an existing fs
var fs = new Filer.FileSystem();
var sh = fs.Shell(options);
// Method 2: create a shell, passing in an existing fs
var fs = new Filer.FileSystem();
var sh = new Filer.FileSystemShell(fs, options);
```
The `FileSystemShell` can take an optional `options` object. The `options` object
can include `env`, which is a set of environment variables. Currently support variables
include `TMP` (the path to the temporary directory), and `PATH` (the list of known paths):
```javascript
var fs = new Filer.FileSystem();
var sh = fs.Shell({
env: {
TMP: '/tempdir',
PATH: '/one:/two'
}
});
```
NOTE: unless otherwise stated, all `FileSystemShell` methods can take relative or absolute
paths. Relative paths are resolved relative to the shell's current working directory (`sh.cwd`).
This is different from the `FileSystem`, which requires absolute paths, and has no notion
of a current working directory.
#### FileSystemShell Properties
A `FileSystemShell` has a number of properties, including:
* `fs` - (readonly) a reference to the bound `FileSystem`
* `cwd` - (readonly) the current working directory (changed with `cd()`)
* `env` - (readonly) the shell's environment. At runtime it will have an
added `PWD` property, which is the same as `cwd`.
Example:
```javascript
var fs = new Filer.FileSystem();
var sh = fs.Shell();
// Store the current location
var before = sh.env.PWD;
var after;
sh.cd('/newdir', function(err) {
if(err) throw err;
// Get the new location
after = sh.env.PWD;
});
```
#### FileSystemShell Instance Methods
Once a `FileSystemShell` object is created, it has the following methods. NOTE: code
examples below assume a `FileSystemShell` instance named `sh` has been created like so:
```javascript
var fs = new Filer.FileSystem();
var sh = fs.Shell();
```
* [sh.cd(path, callback)](#cd)
* [sh.ls(dir, [options], callback)](#ls)
* [sh.exec(path, [options], callback)][#exec)
* [sh.touch(path, [options], callback)[#touch)
* [sh.cat(files, callback)](#cat)
* [sh.rm(path, [options], callback)](#rm)
* [sh.tempDir(callback)](#tempDir)
#### sh.cd(path, callback)<a name="cd"></a>
Changes the current working directory to directory at `path`. The callback returns
an error if `path` does not exist, or is not a directory. Once the callback occurs
the shell's `cwd` property is updated to the new path (as well as `sh.env.PWD`).
Example:
```javascript
sh.cd('/dir1', function(err) {
if(err) throw err;
// sh.cwd is now '/dir1'
});
#### sh.ls(dir, [options], callback)<a name="ls"></a>
Get the listing of a directory, returning an array of directory entries
in the following form:
```
{
path: <String> the basename of the directory entry
links: <Number> the number of links to the entry
size: <Number> the size in bytes of the entry
modified: <Number> the last modified date/time
type: <String> the type of the entry
contents: <Array> an optional array of child entries, if this entry is itself a directory
}
```
By default `sh.ls()` gives a shallow listing. If you want to follow
directories as they are encountered, use the `recursive=true` option. NOTE:
you should not count on the order of the returned entries always being the same.
Example:
```javascript
/**
* Given a dir structure of:
*
* /dir
* file1
* file2
* dir2/
* file3
*/
// Shallow listing
sh.ls('/dir', function(err, entries) {
if(err) throw err;
// entries is now an array of 3 file/dir entries under /dir
});
// Deep listing
sh.ls('/dir', { recursive: true }, function(err, entries) {
if(err) throw err;
// entries is now an array of 3 file/dir entries under /dir.
// The entry object for '/dir2' also includes a `contents` property,
// which is an array of 1 entry element for `file3`.
});
```
#### sh.exec(path, [options], callback)<a name="exec"></a>
Attempts to Execute the .js command located at `path`. Such commands
should be written so as to assume the existence of 3 global variables,
which will be defined at runtime:
* `options` - <Object> an object containing any arguments, data, etc.
* `fs` - <FileSystem> the `FileSystem` object bound to this shell.
* `callback` - <Function> a callback function(error, result) to call when done.
The .js command's contents should be the body of a function that
looks like this:
```javascript
function(fs, options, callback) {
//-------------------------commmand code here---------
// ...
//----------------------------------------------------
}
```
Example:
```javascript
// Simple command to delete a file.
var cmd = "fs.unlink(options.path, callback);"
// Write the file to the filesystem
fs.writeFile('/cmd.js', cmd, callback(err) {
if(err) throw err;
// Execute the command
sh.exec('/cmd.js', { path: '/file' }, function(err, result) {
if(err) throw err;
});
});
#### sh.touch(path, [options], callback)<a name="touch"></a>
Create a file if it does not exist, or update the access and modified
times if it does. Valid options include:
* updateOnly - <Boolean> whether to create the file if it is missing (defaults to `false`)
* date - <Date> a date to use instead of the current date and time when updating
access and modified dates.
Example:
```javascript
sh.touch('/newfile', function(err) {
if(err) throw err;
fs.exists('/newfile', function(exists) {
// exists is now true.
}
});
```
#### sh.cat(files, callback)<a name="cat"></a>
Concatenates multiple files into a single string, with each file
separated by a newline character. The `files` argument should be
a String (i.e., path to a single file) or an Array of Strings (i.e.,
multiple paths for multiple files).
Example:
```javascript
sh.cat([ './file1', '../file2' ], function(err, data) {
if(err) throw err;
// data is now the contents of file1 and file2 joined
});
```
#### sh.rm(path, [options], callback)<a name="rm"></a>
Removes (deletes) the file or directory at `path`. If `path` is a file, it will
be removed. If `path` is a directory, it will be removed if it is empty, otherwise
the callback will receive an error. In order to remove non-empty directories,
use the `recursive=true` option.
Example:
```javascript
sh.rm('./file', function(err) {
if(err) throw err;
// ./file is now removed
});
sh.rm('/dir', { recursive: true }, function(err) {
if(err) throw err;
// /dir and all its children are now removed
});
```
#### sh.tempDir(callback)<a name="tempDir"></a>
Gets the path to the shell's temporary directory, creating it if it
does not already exist. The temp directory to use is specified in the
`env.TMP` environment variable. The callback receives an error
and the `tempDir` path. NOTE: it is safe to call this many times (i.e.,
the temp dir will only be created once). No effort is made to clean-up
the temp dir, and it is up to the caller to destroy it if desired.
Example:
```javascript
// Default /tmp dir
sh.tempDir(function(err, tmp) {
if(err) throw err;
// tmp is now '/tmp' by default, and /tmp exists
});
// Specify a tmp dir path
sh.env.TMP = '/temporary'
sh.tempDir(function(err, tmp) {
if(err) throw err;
// tmp is now '/temporary', and /temporary exists
});
```

1
src/shell.js
View File

@ -72,6 +72,7 @@ define(function(require) {
* should assume the existence of 3 arguments, which will be
* defined at runtime:
*
* * fs - the current shell's bound filesystem object
* * options - an object containing any arguments, data, etc.
* * callback - a callback function(error, result) to call when done.
*