Skip to content
Perl 6 Kernel for Jupyter/IPython notebooks
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
eg
lib/Jupyter Only set PROCESS vars temporarily May 15, 2018
resources Add generation of configuration file. Aug 31, 2017
t
.gitignore Initial commit Jul 25, 2017
.travis.yml
Dockerfile Version 0.0.9 Mar 5, 2018
META6.json Version 0.0.9 Mar 5, 2018
README.md Add autocompletion for arbitrary unicode chars Feb 8, 2018

README.md

Jupyter::Kernel for Perl 6

Build Status

Binder

autocomplete

This is a pure-Perl 6 implementation of a Perl 6 kernel for Jupyter notebooks.

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

REALLY QUICK START

mybinder.org 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.)

QUICK START

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

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

Server Configuration

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

jupyter-kernel.p6 --generate-config
  • Use --location=XXX to specify another location.
  • Use --force to override an existing configuration.

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-Perl6) 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.

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 server configuration file to change this.

Running

Start the web UI with:

jupyter-notebook
Then select new -> perl6.

You can also use it in the console like this:

jupyter-console --kernel=perl6

Or make a handy shell alias:

alias iperl6='jupyter-console --kernel=perl6'

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")

  • 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 (_).

  • 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: return the code as javascript to the browser

    • #% 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.)

    • #% html > latex: The above two can be combined to render, for instance, the output cell as HTML, but stdout as LaTeX.

    • %% bash: Interpret the cell as bash. stdout becomes the contents of the next cell. Behaves like Perl 6'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.

  • Comms. Comms allow for asynchronous communication between a notebook and the kernel. For an example of using comms, see this notebook

Docker

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

EXAMPLES

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

SEE ALSO

KNOWN ISSUES

  • Definitions of operators are not preserved (see bug 131530).

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

THANKS

Suman Khanal

Matt Oates

Timo Paulssen

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.