Repository files navigation

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.

Binder provides a way to instantly launch a Dockerimage and open a notebook². Clicklaunch | binder aboveto start this kernel with a sample notebook. (See belowfor similar alternatives.)

• Installation
• Configuration
• Running

You'll need to install zmq. Note that currently, version 4.1 isrecommended 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/Xapt-get install libzmq-dev # on Ubuntu

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

pip install jupyter

Finally, installJupyter::Kernel:

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

At the end of the above installation, you'll see the locationof thebin/ directory which hasjupyter-kernel.raku. Makesure that is in yourPATH.

To generate a configuration directory, and to install a kernelconfig 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.

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

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

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

Some suggested configuration changes for the console client:

• setkernel_is_complete_timeout to a high number. Otherwise,if the kernel takes more than 1 second to respond, then fromthen on, the console client uses internal (non-Raku) heuristicsto guess when a block of code is complete.

• sethighlighting_style tovim. This avoids having dark blueon a black background in the console client.

Start the web UI with:

jupyter-notebookThen 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'

• 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 theatomic operators. (Useatomic- oratom to get the subroutines with their ASCII names).

  • a colon followed by a sequence of word characters will autocompleteto characters whose unicode name contains that string. Dashes aretreated 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 arraynamed$Out. You can read from this directly or:

  • via the subroutineOut (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 viaIn[N] (e.g.In[3].EVAL orIn[3].AST would eval or produce the ast for a cell)

• Magics: There is some support for jupyter "magics". If the first lineof a code cell starts with#% or%%, it may be interpreted as a directiveby 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. Uselatex(equation) to wrapthe output in\begin{equation} and\end{equation}. (Or replace"equation" with another string to use something else.)

  • #% markdown (ormd): the output will be interpreted as markdown.Note that this is for generating markdown as the output of a cell, not forwriting markdown, which can be done without magics. Also, this simplysends the data with the markdown mime-type, and the notebook does the rendering.

  • #% > markdown (ormd): 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> indictesthe type of stdout.

  • %% bash: Interpret the cell as bash. stdout becomes the contents ofthe next cell. Behaves like Raku's built-inshell.

  • %% run FILENAME: Prepend the contents of FILENAME to thecontents of the current cell (if any) before execution.Note this is different from the built-inEVALFILE in thatif any lexical variables, subroutines, etc. are declared in FILENAME,they will become available in the notebook execution context.

  • %% always [SUBCOMMAND] CODE: SUBCOMMAND defaults toprepend but can be:

    • prepend: Prepend each cell byCODE;\n
    • append: Append;\nCODE after each command
    • clear: Clear allalways registered actions
    • show: Showalways registered actionsYou can combine it with another magic. For example:%% always prepend %% run file.raku

• Comms: Comms allow for asynchronous communication between a notebookand the kernel. For an example of using comms, seethis notebook

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

In [1]: 42Out[1]: 42In [2]: 42 +Out[2]: Missing required term after infixIn [3]: 42 + \      : 10 + \      : 3 + \      : 12Out[3]: 67

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

This blog post providesa tutorial for running this kernel with Docker.This one describes usingBinder.

Theeg/ directory of this repository has someexample notebooks:

• Hello, world.

• Generating an SVG.

• Some unicodey math examples

• magics

• Docker image for Raku

• iperl6kernel

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

Matt Oates

Suman Khanal

Timo Paulssen

Tinmarino

Anton Antonov

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

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