http://sdether.github.io/josh.js/
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 handlingpathhandler.js
- provide cd, ls, pwd and path completion toolikithistory.js
- localStorage backed command historykillring.js
- killring for kill & yank handling in readline
- 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
- CLI all the things: Introducing Josh.js Article about the origins of Josh.js with an example console for wordpress sites.
josh.js is licensed under the Apache 2.0 License
- 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.
Until documentation is written, refer to index.html
and example.js
(Annotated Source) for a sample implementation of a shell with path completion.
josh is built from 5 components and can be used in part or in full.
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.
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
orLeft Arrow
- Move back one character
M-b
orRight Arrow
- Move back one word
C-f
- Move forward one character
M-f
- Move forward one word
C-a
orHome
- Move to the beginning of the line
C-e
orEnd
- Move to the end of the line
- Edit/Kill
Backspace
- Delete one character back
C-d
orDelete
- 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
orUp Arrow
- Previous entry in history
C-n
orDown 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
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
inhistory.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
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.
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.
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 toShell.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