bduggan/raku-jupyter-kernel

Jupyter::Kernel for Raku

autocomplete

This is a pure Raku implementation of a Raku kernel for Jupyter clients¹.

Jupyter notebooks provide a web-based (or console-based) Read Eval Print Loop (REPL) for running code and serializing input and output.

REALLY QUICK START

Binder provides a way to instantly launch a Docker image and open a notebook². Click launch | binder above to start this kernel with a sample notebook. (See below for similar alternatives.)

Installation

You'll need to install zmq. Note that currently, version 4.1 is recommended by Net::ZMQ (though 4.2 is installed by, e.g. homebrew). If you run into stability issues, you may need to downgrade.

brew install zmq           # on OS/X
apt-get install libzmq-dev # on Ubuntu

You'll also want jupyter, for the front end:

pip install jupyter

Finally, install Jupyter::Kernel:

zef install 'Jupyter::Kernel:auth<zef:bduggan>'

At the end of the above installation, you'll see the location of the bin/ directory which has jupyter-kernel.raku. Make sure that is in your PATH.

Configuration

Server Configuration

To generate a configuration directory, and to install a kernel config file and icons into the default location:

jupyter-kernel.raku --generate-config

Use --location=XXX to specify another location.
Use --force to override an existing configuration.

Logging

By default a log file jupyter.log will be written in the current directory. An option --logfile=XXX argument can be added to the argv argument of the server configuration file (located at $(jupyter --data)/kernels/raku/kernel.json) to change this.

Client configuration

The jupyter documentation describes the client configuration. To start, you can generate files for the notebook or console clients like this:

jupyter notebook --generate-config
jupyter console --generate-config

Some suggested configuration changes for the console client:

set kernel_is_complete_timeout to a high number. Otherwise, if the kernel takes more than 1 second to respond, then from then on, the console client uses internal (non-Raku) heuristics to guess when a block of code is complete.
set highlighting_style to vim. This avoids having dark blue on a black background in the console client.

Running

Start the web UI with:

jupyter-notebook
Then select New -> Raku.

You can also use it in the console like this:

jupyter-console --kernel=raku

Or make a handy shell alias:

alias iraku='jupyter-console --kernel=raku'

FEATURES

Autocompletion: Typing [tab] in the client will send an autocomplete request. Possible autocompletions are:
- methods: after a . the invocant will be evaluated to find methods
- set operators: after a (, set operators (unicode and texas) will be shown (note the whitespace before the ()).
- equality/inequality operators: after =, <, or >, related operators will be shown.
- autocompleting * or / will give × or ÷ respectively.
- autocompleting ** or a superscript will give you superscripts (for typing exponents).
- the word 'atomic' autocompletes to the atomic operators. (Use atomic- or atom to get the subroutines with their ASCII names).
- a colon followed by a sequence of word characters will autocomplete to characters whose unicode name contains that string. Dashes are treated as spaces. e.g. :straw will find 🍓 ("STRAWBERRY") or 🥤 ("CUP WITH STRAW") and :smiling-face-with-smiling-eye will find 😊 ("SMILING FACE WITH SMILING EYES")
Keep output: All cells are evaluated in item context. Outputs are then saved to an array named $Out. You can read from this directly or:
- via the subroutine Out (e.g. Out[3])
- via an underscore and the output number (e.g. _3)
- for the most recent output: via a plain underscore (_).
Keep input: Similiarly, the input text can be accessed via In[N] (e.g. In[3].EVAL or In[3].AST would eval or produce the ast for a cell)
Magics: There is some support for jupyter "magics". If the first line of a code cell starts with #% or %%, it may be interpreted as a directive by the kernel. See EXAMPLES. The following magics are supported:
- #% javascript: interpret the cell as javascript; i.e. run it in the browser
- #% js: return the output as javascript
- #% > js: return stdout as javascript
- #% html: return the output as html
- #% latex: return the output as LaTeX. Use latex(equation) to wrap the output in \begin{equation} and \end{equation}. (Or replace "equation" with another string to use something else.)
- #% markdown (or md): the output will be interpreted as markdown. Note that this is for generating markdown as the output of a cell, not for writing markdown, which can be done without magics. Also, this simply sends the data with the markdown mime-type, and the notebook does the rendering.
- #% > markdown (or md): interpret stdout as markdown
- #% html > latex: The above can be combined to render, for instance, the output cell as HTML, but stdout as LaTeX. The word before the > indicates the type of the output cell. The word after the > indictes the type of stdout.
- %% bash: Interpret the cell as bash. stdout becomes the contents of the next cell. Behaves like Raku's built-in shell.
- %% run FILENAME: Prepend the contents of FILENAME to the contents of the current cell (if any) before execution. Note this is different from the built-in EVALFILE in that if any lexical variables, subroutines, etc. are declared in FILENAME, they will become available in the notebook execution context.
- %% always [SUBCOMMAND] CODE: SUBCOMMAND defaults to prepend but can be:
- prepend: Prepend each cell by CODE;\n
- append: Append ;\nCODE after each command
- clear: Clear all always registered actions
- show: Show always registered actions You can combine it with another magic. For example: %% always prepend %% run file.raku
Comms: Comms allow for asynchronous communication between a notebook and the kernel. For an example of using comms, see this notebook

Usage notes

In the console, pressing return will execute the code in a cell. If you want a cell to span several lines, put a \ at the end of the line, like so:

In [1]: 42
Out[1]: 42

In [2]: 42 +
Out[2]: Missing required term after infix

In [3]: 42 + \
      : 10 + \
      : 3 + \
      : 12
Out[3]: 67

Note that this is not the same as the raku 'unspace' -- a backslash followed by a newline will be replaced with a newline before the code is executed. To create an unspace at the end of the line, you can use two backslashes.

DOCKER

This blog post provides a tutorial for running this kernel with Docker. This one describes using Binder.

EXAMPLES

The eg/ directory of this repository has some example notebooks:

KNOWN ISSUES

Newly declared methods might not be available in autocompletion unless SPESH is disabled (see tests in this PR).

THANKS

Matt Oates

Suman Khanal

Timo Paulssen

Tinmarino

Anton Antonov

FOOTNOTES

¹ Jupyter clients are user interfaces to interact with an interpreter kernel like Jupyter::Kernel. Jupyter [Lab | Notebook | Console | QtConsole ] are the jupyter maintained clients. More info in the jupyter documentations site.

² mybinder.org provides a way to instantly launch a Docker image and open a notebook.