|
1 | | -josh.js 0.1 |
2 | | -=========== |
3 | | - |
4 | | -***Javascript Online SHell*** provides a toolkit for building bash-like command line consoles for web pages. It consists of the following components: |
5 | | - |
6 | | -* `readline.js` - full readline support for ctrl sequences, tab, history, etc. |
7 | | -* `shell.js` - visual presentation of the shell and command handling |
8 | | -* `pathhandler.js` - provide cd, ls, pwd and path completion toolikit |
9 | | -* `history.js` - localStorage backed command history |
10 | | - |
11 | | -## License |
12 | | -josh.js is licensed under the Apache 2.0 License |
13 | | - |
14 | | -## Status |
15 | | - |
16 | | -* code is ready for experimental use |
17 | | - * Only confirmed to work on chrome so far. |
18 | | - * API is not yet stable |
19 | | -* needs minified versions of complete toolkit and just readline.js |
20 | | -* needs code documentation and documenation site |
21 | | - |
22 | | -## Usage |
23 | | - |
24 | | -Until documentation is written, refer to `index.html` and `example.js` for a sample implementation of a shell with path completion. |
25 | | - |
26 | | -## Components |
27 | | -***josh*** is built from 4 components and can be used in part or in full. |
28 | | - |
29 | | -### readline.js |
30 | | - |
31 | | -`readline.js` has no dependencies on any outside libraries, although it requires either `history.js` or an object implementing the same calls. |
32 | | - |
33 | | -It implements key trapping to bring [GNU Readline](http://cnswww.cns.cwru.edu/php/chet/readline/readline.html) like line editing to the browser. It can be used by itself to bring readline support to custom data entry fields or in conjunction with `shell.js` to create a full console. |
34 | | - |
35 | | -### shell.js |
36 | | -`shell.js` has external dependencies of [jQuery](http://jquery.com/), [Underscore](http://underscorejs.org/) and internal dependencies of `readline.js` and `history.js`. |
37 | | - |
38 | | -It provides a simple console UI, using a *panel* for the console viewport and an auto-scrolling *view* inside the panel. It uses Underscore templates for generating the view html, although any template generator can be substituted as long as it can be expressed in the form of a function that takes a JSON object of arguments and returns an html string. |
39 | | - |
40 | | -It also implements command handling so that new commands can be added by name with execution and completion handlers. Out of the box, `shell.js` provides the following commands: |
41 | | -* help - list all known commands (including user added) |
42 | | -* clear - clear the "screen" i.e. viewport |
43 | | -* history - show the command history captured by `readline.js` in `history.js` |
44 | | - |
45 | | -### pathhandler.js |
46 | | -`pathhandler.js` is a mix in to easily add the `cd`, `ls` and `pwd` commands as well as path completion. It has the same external dependencies of [jQuery](http://jquery.com/), [Underscore](http://underscorejs.org/) as `shell.js` and also uses Underscore templating. |
47 | | - |
48 | | -By implementing the functions `getNode` and `getChildNodes`, this library adds path traversal, discovery and completion just like a bash shell. |
49 | | - |
50 | | -### history.js |
51 | | -`history.js` implements a localStorage back command history storage that persists over page changes and reloads. It is used by the `shell.js` history command to list all executed commands, and by `readline.js` for up/down arrow and reverse search capabilities. |
| 1 | +josh.js 0.2 |
| 2 | +=========== |
| 3 | + |
| 4 | +***Javascript Online SHell*** provides a toolkit for building bash-like command line consoles for web pages. It consists of the following components: |
| 5 | + |
| 6 | +* `readline.js` - full readline support for ctrl sequences, tab, history, etc. |
| 7 | +* `shell.js` - visual presentation of the shell and command handling |
| 8 | +* `pathhandler.js` - provide cd, ls, pwd and path completion toolikit |
| 9 | +* `history.js` - localStorage backed command history |
| 10 | + |
| 11 | +## License |
| 12 | +josh.js is licensed under the Apache 2.0 License |
| 13 | + |
| 14 | +## Status |
| 15 | + |
| 16 | +* code is ready for experimental use |
| 17 | + * Tested under Chrome, Firefox, Safari and IE9 |
| 18 | + * API may not yet be stable |
| 19 | +* needs minified versions of complete toolkit and just readline.js |
| 20 | +* needs code documentation and documenation site |
| 21 | +* would like to add AMD support |
| 22 | + |
| 23 | +## Usage |
| 24 | + |
| 25 | +Until documentation is written, refer to `index.html` and `example.js` for a sample implementation of a shell with path completion. |
| 26 | + |
| 27 | +## Components |
| 28 | +***josh*** is built from 4 components and can be used in part or in full. |
| 29 | + |
| 30 | +### readline.js |
| 31 | + |
| 32 | +`readline.js` has no dependencies on any outside libraries, although it requires either `history.js` or an object implementing the same calls. |
| 33 | + |
| 34 | +It implements key trapping to bring [GNU Readline](http://cnswww.cns.cwru.edu/php/chet/readline/readline.html) like line editing to the browser. It can be used by itself to bring readline support to custom data entry fields or in conjunction with `shell.js` to create a full console. |
| 35 | + |
| 36 | +### shell.js |
| 37 | +`shell.js` has external dependencies of [jQuery](http://jquery.com/), [Underscore](http://underscorejs.org/) and internal dependencies of `readline.js` and `history.js`. |
| 38 | + |
| 39 | +It provides a simple console UI, using a *panel* for the console viewport and an auto-scrolling *view* inside the panel. It uses Underscore templates for generating the view html, although any template generator can be substituted as long as it can be expressed in the form of a function that takes a JSON object of arguments and returns an html string. |
| 40 | + |
| 41 | +It also implements command handling so that new commands can be added by name with execution and completion handlers. Out of the box, `shell.js` provides the following commands: |
| 42 | +* help - list all known commands (including user added) |
| 43 | +* clear - clear the "screen" i.e. viewport |
| 44 | +* history - show the command history captured by `readline.js` in `history.js` |
| 45 | + |
| 46 | +### pathhandler.js |
| 47 | +`pathhandler.js` is a mix in to easily add the `cd`, `ls` and `pwd` commands as well as path completion. It has the same external dependencies of [jQuery](http://jquery.com/), [Underscore](http://underscorejs.org/) as `shell.js` and also uses Underscore templating. |
| 48 | + |
| 49 | +By implementing the functions `getNode` and `getChildNodes`, this library adds path traversal, discovery and completion just like a bash shell. |
| 50 | + |
| 51 | +### history.js |
| 52 | +`history.js` implements a localStorage back command history storage that persists over page changes and reloads. It is used by the `shell.js` history command to list all executed commands, and by `readline.js` for up/down arrow and reverse search capabilities. |
| 53 | + |
| 54 | +## Changelog |
| 55 | + |
| 56 | +**0.2** -- 2013/01/07 |
| 57 | +* console wrapper to allow debug logging to be turned on and off |
| 58 | +* refactored how pathhandler attaches to shell because it needs to keep a reference to the shell |
| 59 | +* refactored how prompts are set. now uses dedicated callback rather than returning the prompt in the `onEnter` callback |
| 60 | +* tested and made fixes to ensure compatibility with major modern browsers |
| 61 | + |
| 62 | +**0.1** -- 2013/01/04 |
| 63 | +* Initial code-complete release |
0 commit comments