josh.js 0.2

Javascript Online SHell provides a toolkit for building bash-like command line consoles for web pages. It consists of the following components:

• readline.js - full readline support for ctrl sequences, tab, history, etc.
• shell.js - visual presentation of the shell and command handling
• pathhandler.js - provide cd, ls, pwd and path completion toolkit
• history.js - localStorage backed command history
• killring.js - killring for kill & yank handling in readline

Live Demo

Annotated source of demo

Tutorials

• Hello world - put a console on a web page and add a new custom command with completion
• Quake Console - Create a quake-style console with ls, cd, pwd and bash filename tab-completion
• GitHub Console - Extend the Quake Console to talk to GitHub's REST API to navigate repositories, their branches and file system

Articles

• CLI all the things: Introducing Josh.js -- Article about the origins of Josh.js with an example console for wordpress sites.
• Using Josh for form data -- Article about changes to Josh.js to allow binding to an element and new helper Josh.Input for binding to input elements.

License

josh.js is licensed under the Apache 2.0 License

Status

• code is ready for experimental use
  • Tested under Chrome, Firefox, Safari and IE9
  • API may not yet be stable
• needs minified versions of complete toolkit and just readline.js
• needs code documentation and documentation site
• would like to add AMD support
• implement NCurses for better UI control
• Readline has not been tested with non-ascii.

Usage

Until documentation is written, refer to index.html and the annotated version of example.js for a sample implementation of a shell with path completion.

Components

josh is built from 5 components and can be used in part or in full.

readline.js

readline.js has no dependencies on any outside libraries, although it requires either history.js and killring.js or objects implementing the same calls.

It implements key trapping to bring GNU Readline 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.

Line Editing

In the below C-x refers to the Ctrl-x keystroke, while M-x refers to the Meta-x keystroke which is mapped to Alt, ⌘ and Left Windows.

Movement

C-b or Left Arrow

Move back one character

M-b or Right Arrow

Move back one word

C-f

Move forward one character

M-f

Move forward one word

C-a or Home

Move to the beginning of the line

C-e or End

Move to the end of the line

Edit/Kill

Backspace

Delete one character back

C-d or Delete

Delete character under cursor

C-k

Kill (i.e. put in kill ring) text to the end of the line

M-Backspace

Kill one word back

M-d

Kill word under cursor

C-y

Yank (i.e. pull from kill ring) the most recently killed text

M-y

Rotate to the next item in killring and yank it. Must be preceded by yank

History

C-r

Reverse search through history

C-p or Up Arrow

Previous entry in history

C-n or Down Arrow

Next entry in history

Page Up

Top of history

Page Down

Bottom of history

Misc

C-l

refresh line (clear screen in shell)

Tab

Invoke completion handler for text under cursor

Esc in reverse search

Cancel search

C-c

call onCancel handler

C-d on empty line

call onCancel handler

More readline.js docs

shell.js

shell.js has external dependencies of jQuery, Underscore and internal dependencies of readline.js and history.js.

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.

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:

• help - list all known commands (including user added)
• clear - clear the "screen" i.e. viewport
• history - show the command history captured by readline.js in history.js

More shell.js docs

pathhandler.js

pathhandler.js is a mix in to easily add the cd, ls and pwd commands as well as path completion. It has Underscore as its dependency for templating, however since all templates it uses are exposed, they could easily be replaced with a different function that accepts an argument object returns html.

By implementing the functions getNode and getChildNodes, this library adds path traversal, discovery and completion just like a bash shell.

More pathhandler.js docs

history.js

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.

killring.js

killing.js implements the kill and yank behavior as well as state tracking, i.e. multiple consecutive kills are combined as a single kill and killring rotation tracks the previous yank, so that the readline.js can remove the previous yank and replace it with the rotated text.