ijavascript

Here's a sample notebook that makes use of the IJavascript kernel:

Contents

• Announcements
• Main Features
• Installation
• Troubleshooting
• Usage
• Contributions
• TODO

Announcements

• IJavascript v5.2 builds have started to fail in Node.js v0.10, because the installation of zeromq depends on prebuild-install and they are now using const declarations.
• SUPPORT NOTICE: IJavascript v5.2 will be the last version supporting Node.js 0.10, Node.js 4, Node.js 6 and Node.js 8.
• IJavascript v5.1 added new functionality to the API (see NEL for preliminary documentation):
  • $$.clear({wait}) to send a clear_output request.
  • $$.display({id}) to send display_data and update_display_data messages.
  • $$.input(options, {callback}) to send a input_request and handle input_reply messages.
• Starting with IJavascript v5.0.11, it is possible to customise the output of an object based on its type. See the documentation on custom output for details.
• The use of $$mimer$$ and $$defaultMimer$$ to customise output is now deprecated.
• To avoid clutter in the global context, the use of $$async$$, $$done$$, $$mime$$, $$html$$, $$svg$$, $$png$$ and $$jpeg$$ has also been deprecated and replaced with the global object $$.

Main Features

• Run Javascript code inside a Node.js session
• Hello, World!
• Asynchronous output
• Custom output for HTML, SVG, PNG, ...
• Autocompletion: press TAB to complete keywords and object properties
• Object inspection: press Shift-TAB to inspect an object and show its content or, if available, its documentation

Installation

IJavascript is distributed as an npm package and thus it requires:

• Node.js
• npm

Depending on your use, other Jupyter tools will be necessary (e.g. Jupyter notebook). Note that IJavascript has been kept backwards-compatibility with IPython v1, so that it's possible to use the IPython notebook distributed in Ubuntu 14.04 LTS and Ubuntu 16.04 LTS.

For other platforms not listed below, or if you find any problems with the instructions above, please, refer to the installation notes.

Ubuntu

To install IJavascript in Ubuntu 18.04 for your user only, run:

sudo apt-get install nodejs npm jupyter
npm config set prefix $HOME
npm install -g ijavascript
ijsinstall

Note: if ~/bin folder didn't exist before, after running this instructions, you may need to log out and back in for ~/bin to be added to your PATH.

To install IJavascript in Ubuntu 18.04 for all users, run instead:

sudo apt-get install nodejs npm jupyter
sudo npm install -g --unsafe-perm ijavascript
sudo ijsinstall --install=global

Also, note that older versions of Ubuntu (e.g. Ubuntu 16.04 LTS) depend on nodejs-legacy and ipython-notebook instead:

sudo apt-get install nodejs-legacy npm ipython ipython-notebook

Windows (Official Python Distribution)

In the command line:

pip3 install --upgrade pip
pip3 install jupyter
npm install -g ijavascript
ijsinstall
# Or run: %appdata%\npm\ijsinstall

Then you can run jupyter notebook in your terminal to load Jupyter Notebook. When you create a new Jupyter Notebook, you should see the Javascript (Node) kernel available.

Windows (Anaconda Distribution)

Open the Anaconda prompt and run:

conda install nodejs
npm install -g ijavascript
ijsinstall

Then you can run jupyter notebook in your terminal to load Jupyter Notebook. When you create a new Jupyter Notebook, you should see the Javascript (Node) kernel available.

macOS

In macOS, Homebrew and pip can be used to install IJavascript and its prerequisites:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install pkg-config node zeromq
sudo easy_install pip
pip install --upgrade pyzmq jupyter
npm install -g ijavascript
ijsinstall

Usage

IJavascript provides 5 executables: ijsinstall, ijsnotebook, ijsconsole, ijskernel and ijs. Their purpose and basic use is described in the sections below. Please, refer to the usage notes for further details.

ijsinstall: IJavascript kernel spec installer

ijsinstall registers the IJavascript kernel with Jupyter, so that other tools (e.g. the Jupyter notebook) can invoke it. The following command flags are recognised:

…

ijsnotebook: IJavascript notebook

After running ijsinstall, Jupyter notebook users can invoke the Jupyter notebook as usual. ijsnotebook is provided for convenience to users of the IPython notebook prior to version 3. ijsnotebook is a wrapper around ipython notebook. It extends the command flags accepted by ipython notebook with the following:

…

ijsconsole: IJavascript console

ijsconsole is provided for convenience to users as a wrapper around ipython console. The following command flags are recognised:

…

ijskernel: IJavascript kernel

ijskernel is the executable invoked by Jupyter tools (e.g. the notebook) and that appears in the kernel spec that ijsinstall creates for IJavascript. You won't need this command, unless you want to create a custom kernel spec.

Usage:
    ijskernel [options] connection_file

Options:
    --debug                           enable debug messages
    --hide-undefined                  do not show undefined results
    --protocol=Major[.minor[.patch]]  set protocol version, e.g. 5.0
    --session-working-dir=path        set session working directory
    --show-undefined                  show undefined results
    --startup-script=path             run script on startup
					  (path can be a file or a folder)

ijs: Deprecated CLI

ijs is provided for backwards-compatibility. It will be removed in the next major-version update. Please, use ijsinstall or ijsnotebook instead.

Contributions

First of all, thank you for taking the time to contribute. Please, read CONTRIBUTING and use the issue tracker for any contributions: support requests, bug reports, enhancement requests, pull requests, submission of tutorials...

TODO

See the issue tracker and the TODO list in the packages jp-kernel and NEL for additional items.