josh.js 0.2

http://sdether.github.io/josh.js/

Javascript Online SHell provides a toolkit for building bash-like command line consoles for web pages. JOSH enables the visitor who prefers the bash-like command to maneuver through web content using a console rather than clicking with a mouse. This toolkit is most useful for people who like to use command line because it is faster and more effective than using a mouse. It is easier and convienent to access hierarchical information using JOSH command history, change or display current directory. 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 toolikit
• history.js - localStorage backed command history
• killring.js - killring for kill & yank handling in readline

What to use Josh for and when to use it

Josh allows developers to build their own command line interface to any sites. It supports full CLI Readline in the browser like TAB completion, emacs-style line editing, killring and history with reverse search. When you are tired of clicking your way through a hierachy tree, Josh will come in handy. It will helps you browse or navigate text files quickly and minimal the using of mouse click.

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.

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
• base shell UI should get some basic behaviors
  • more-like handling for output that exceeds the shell viewport size
  • resizing and close chrome
• Readline has not been tested with non-ascii.

Usage

Until documentation is written, refer to index.html and example.js (Annotated Source) 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

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

pathhandler.js

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, Underscore as shell.js and also uses Underscore templating.

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

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

killring.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.

Changelog

0.2.10 -- 2014/04/03

• Added bower support (pr#19 - @bricef)
• Code clean-up for closure compiler issues (pr#20 - @aaronmars)

0.2.9 -- 2013/08/31

• Added ability to bind ReadLine/Shell to an element.
• Added ability to bind/unbind keys (could be used to replace emacs bindings of readline, but primarily added to unbind some keys for using readline on input elements.
• Created input.js for easy binding of readline to either an input element or a span behaving like an input.

0.2.8 -- 2013/03/13

• Added handling of . and .. in Josh.PathHandler.pathcompletionhandler, so that a trailing .. completes to ../ and . to ./
• Removed the hardcoded strong in the input template, making it a span instead so it can be styled via css instead.
• The prompt value itself is now assumed to be html instead of plain text, allowing for richer formatting without changing the input template.

0.2.7 -- 2013/02/13

• Removed all html used for Shell UI generation from config to Shell.templates, so that they can easily be customized (see: Issue 11)
• Removed PathHandler.templates. PathHandler now attches its templates to Shell.templates as well

0.2.6 -- 2013/01/21

• Removed Activation/Deactivation keybindings from Readline, making it an outside concern (see: Issue 2)
• Fixed Backspace regression introduced by 0.2.5
• Fixed M-d not deleting last character of line
• Example shell can now be resized (via jquery-ui.resizable)

0.2.5 -- 2013/01/14

• Implemented missing Readline behavior (see: Issue 1)
• Added scrollbar to sample implemenation (also adds scrollwheel support)

0.2.4 -- 2013/01/14

• fixed path completion handling for scenarios of two possible completions where one is the root of the other
• noted that spaces in paths are completely unsupported right now.. they will complete, but the exec handler will see the space as a separator between arguments

0.2.3 -- 2013/01/13

• changed internal handling of the default command handler (i.e. when no named command is defined).
• removed the pathhandler commandhandlers from the public object, since they should be accessed via shell.getCommandHandler if required
• some readline.js property naming cleanup to make closure compiler happy

0.2.2 -- 2013/01/09

• changed rendering of completion to be more bash-like, i.e. now renders completion and then re-renders prompt with completed text, rather than as a pop-under that disappears.

0.2.1 -- 2013/01/08

• fixed activation/deactivation propagation through the shell, which caused issues with first time activation via activation key instead of method call to fail.

0.2 -- 2013/01/07

• console wrapper to allow debug logging to be turned on and off
• refactored how pathhandler attaches to shell because it needs to keep a reference to the shell
• refactored how prompts are set. now uses dedicated callback rather than returning the prompt in the onEnter callback
• tested and made fixes to ensure compatibility with major modern browsers

0.1 -- 2013/01/04

• Initial code-complete release