m-kus / xeus-fift

🍬 Jupyter kernels for Fift and FunC languages

Xeus-Fift

Jupyter kernels for the Fift and FunC languages (and TVM assembler)

Features

Fift kernel

Aside from the convenient Jupyter interactive workflow this kernel provides:

• Syntax highlighting
• Words autocomplete via Tab (including those which are included or defined by you)
• In-place docstrings via Shift+Tab (for words defined in FiftBase and TVM pdf files)

FunC kernel

• Syntax highlighting including (non)const methods and pseudo-namespaces
• Autoindentation
• Autocomplete by Tab using keywords and global functions
• Inspect function signature by Shift+Tab
• Extra: #include macro and print debug helper

FunC Workflow

1. At the top-level of each cell you can use #include "path/to/file" macro to load functions from a .fc file. They will be available throughout the notebook.
2. You can define multiple functions in any cell, they will also be available from everywhere.
3. At the end of the cell (using separate cell is recommended) you can write piece of code not wrapped by a function definition. It will be automatically used as main body. Such code cannot be accessed from another cell.
4. Alternatively, you can specify main function explicitly.
5. You can omit return and trailing ; in the main code block - they will be added during the execution.
6. Note, that every time you re-run a cell, all functions defined in this cell are being overwritten.

Examples

Return constant

<<< 2 + 2
>>> 4

Return variable

<<< int i = 42
>>> 42

Return function result

<<< int sum(int a, int b) { return a + b; }
... sum(2, 2)
>>> 4

Print variables

<<< int i = 1;
... int j = 2;
... print(i);
... print(j);
>>> 2 1

How to use

Run online!

Powered by awesome Binder: https://mybinder.org/v2/gh/atomex-me/xeus-fift/binder?filepath=func_cheat_sheet.ipynb

Run in docker

0. Get the latest image from dockerhub (only when new releases are published)

docker pull atomex/xeus-fift

1. Create container using verified docker image:

docker run --rm -it -p 127.0.0.1:8888:8888 -v $(pwd):/home/jupyter/notebooks atomex/xeus-fift

2. Open the link from container output in your browser
3. Save notebooks in the mapped folder in order not to loose them

Install .deb package

1. Check out the latest release tag at https://github.com/atomex-me/xeus-fift/releases
2. Download and install the package

wget https://github.com/atomex-me/xeus-fift/releases/download/0.1.0/xeus-fift_0.1.0-1_amd64.deb -P /tmp/
sudo dpkg -i /tmp/xeus-fift_0.1.0-1_amd64.deb

3. Check that Jupyter is now supporting Fift and FunC kernels

jupyter kernelspec list

Install from sources

1. Ensure the following packages are installed: libssl-dev zlib1g-dev uuid-dev
2. Get the sources, build and install

git clone https://github.com/atomex-me/xeus-fift
cd xeus-fift
mkdir build
cd build
cmake ..
make xeus-fift
sudo make install

3. Check that Jupyter is now supporting Fift and FunC kernels

jupyter kernelspec list

xeus-fift's Issues

FunC #include: failed to load "�.fc"

When I try to run #include "stdlib.fc", I have this error in console: failed to load "�.fc". Also when I try enter full path to the .fc file, I receive failed to load "�dmitry/Coding/ton/ton/crypto/smartcont/stdlib.fc".

Full Jupyter execution log:

[I 18:53:05.556 NotebookApp] Serving notebooks from local directory: /home/dmitry/Coding/ton
[I 18:53:05.556 NotebookApp] The Jupyter Notebook is running at:
[I 18:53:05.556 NotebookApp] http://localhost:8888/?token=9d1f0beab14cefd0dfd85ea4ca8a248191a2ad62f725da40
[I 18:53:05.557 NotebookApp]  or http://127.0.0.1:8888/?token=9d1f0beab14cefd0dfd85ea4ca8a248191a2ad62f725da40
[I 18:53:05.557 NotebookApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation).
[C 18:53:05.575 NotebookApp] 
    
    To access the notebook, open this file in a browser:
        file:///home/dmitry/.local/share/jupyter/runtime/nbserver-32055-open.html
    Or copy and paste one of these URLs:
        http://localhost:8888/?token=9d1f0beab14cefd0dfd85ea4ca8a248191a2ad62f725da40
     or http://127.0.0.1:8888/?token=9d1f0beab14cefd0dfd85ea4ca8a248191a2ad62f725da40
[W 18:53:13.236 NotebookApp] 404 GET /nbextensions/widgets/notebook/js/extension.js?v=20191216185305 (127.0.0.1) 10.79ms referer=http://localhost:8888/notebooks/Untitled.ipynb
[I 18:53:13.431 NotebookApp] Kernel started: e41dde80-5145-4a41-8de3-47a292325869
[W 18:53:14.945 NotebookApp] 404 GET /api/kernels/21074eaf-4e5c-454c-b395-0cdb5de35d09/channels?session_id=a7e1ed1fc4c24e76885b954743034700 (127.0.0.1): Kernel does not exist: 21074eaf-4e5c-454c-b395-0cdb5de35d09
[W 18:53:14.947 NotebookApp] 404 GET /api/kernels/21074eaf-4e5c-454c-b395-0cdb5de35d09/channels?session_id=a7e1ed1fc4c24e76885b954743034700 (127.0.0.1) 4.87ms referer=None
[I 18:53:21.117 NotebookApp] Starting buffering for e41dde80-5145-4a41-8de3-47a292325869:1849a1eb68b24253802c1a48566e22de
[I 18:53:21.426 NotebookApp] Kernel shutdown: e41dde80-5145-4a41-8de3-47a292325869
[I 18:53:21.463 NotebookApp] Kernel started: 4d8f280f-8732-4d27-a299-c415382cdfc3
failed to load `�.fc`
Found 1 function declarations
function print : Forall (A) A -> ()
new type of function print : Forall (A) A -> ()
Starting xeus-func kernel...

If you want to connect to this kernel from an other client, you can use the /home/dmitry/.local/share/jupyter/runtime/kernel-4d8f280f-8732-4d27-a299-c415382cdfc3.json file.
Run with XEUS 0.23.2
[W 18:53:47.949 NotebookApp] Replacing stale connection: 21074eaf-4e5c-454c-b395-0cdb5de35d09:a7e1ed1fc4c24e76885b954743034700
[W 18:53:56.957 NotebookApp] 404 GET /api/contents/myfunc.ipynb?content=0&_=1576515116009 (127.0.0.1): No such file or directory: myfunc.ipynb
[W 18:53:56.957 NotebookApp] No such file or directory: myfunc.ipynb
[W 18:53:56.957 NotebookApp] 404 GET /api/contents/myfunc.ipynb?content=0&_=1576515116009 (127.0.0.1) 1.15ms referer=http://localhost:8888/notebooks/myfunc.ipynb
[I 18:53:56.964 NotebookApp] Uploading file to /myfunc.ipynb
failed to load `�dmitry/Coding/ton/ton/crypto/smartcont/stdlib.fc`
ERROR: during execute_request
[json.exception.type_error.316] invalid UTF-8 byte at index 17: 0x01
[I 18:55:13.967 NotebookApp] Saving file at /Untitled.ipynb

.zshrc looks like this:

export FUNCPATH=/home/dmitry/Coding/ton/ton/crypto/smartcont:/home/dmitry/Coding/ton/ton/build/crypto

Tried also with $HOME instead of full home directories. Fift kernel with example commands from repository readme looks like are working. Kubuntu 19.10, .deb install, tried versions 0.2.5 and 0.2.1. In Jupyter about window I have Python 3.7.5, notebook version 6.0.2