Using the Ciao Prolog Playground

The Ciao Prolog Playground includes a number of areas, most of which are editable (note that the arrangement of the areas is configurable):

The editor area (left area, or top if the window is narrow) is an editor for the program or notebook-style document. Users can add their code into this editor and modify it there. Programs can be loaded into the system's top level (see below), where they can be run by entering queries at the prompt. Documents are processed in the top level and rendered in the preview area (see below). If the document contains runnable examples these can be executed there.
The top-level area (on the right, or bottom if the window is narrow) is where most communication with the system takes place. The top-level first shows Loading Ciao... while the system is loading its dependencies. When the top-level is completely ready to use, it will show the prompt ?- . Now programs can be loaded and queries issued. This area is also an editor that allows, e.g., editing the query, recalling previous queries, etc.
The preview area is where documents or program documentation is rendered. This preview area (and other areas) can be also used for other graphical program output.

Buttons

Area selector

Allows selecting which areas are visible.

New

Erases all previous content from the editor and allows loading a small sample program or document. This also switches the new content in the editor area to be treated as a program (.pl) or as a document (.md).

File

Open: Lets you upload your own Prolog code (.pl file) or document (.md or .lpdoc file) from your local file system. This action also erases all previous content present in the editor. The playground will switch to program mode or document mode depending on the type of file uploaded.
Save (Ctrl-x + Ctrl-s): Allows downloading the code or document written in the playground directly to your file system.

Examples

Allows loading a number of examples of programs and active logic documents to get started.

.pl / .md (Playground mode)

Indicates if the playground is in code (.pl) or document (.md) development mode. It also allows toggling between these two modes.

Load (Ctrl-c + l)

In code mode, loads the program in the editor area into the top level. It compiles it and, in case there are any errors, they are printed in top-level area and highlighted in the editor. Once you click this button, you can ask queries about your code in the top-level.

🔎 (Debug, Ctrl-c + d)

In code mode, load code source in debug mode and enable tracing the control flow of the program for subsequent queries. Clicking again turns debug mode off. See the debugger documentation for more information.

📖 (Preview documentation, Ctrl-c + D)

In code mode (.pl) generate and preview the documentation for the code in the editor area using LPdoc.
In document mode (.md) process the document source in the editor it in the top level and render it in the preview area using LPdoc. If the document contains runnable examples these can be executed there.

⇱⇲ (Toggle presentation mode)

Switches to a full window view of the document or any other content of the preview area. In this view:

The pencil ✎ icon allows returning to the editor mode.
The rectangular ▭ icon switches to slides presentation mode, where each document section is presented as a separate slide.
To exit slides presentation mode use the ESC key.

↻ (Toggle on-the-fly mode)

If turned on, documents are rendered interactively, as they are edited, and programs are also processed in this way. Program errors and warnings are then shown on the code as it is being modified, or the results of editing a document source are shown progressively as the document is edited. This button is highlighted in red when on-the-fly mode is on.

Share!

Is an alternative form of save, very useful for sharing!:

In code mode (.pl) it copies into the clipboard a shareable link which, when clicked, will open a playground with the current state of the program loaded in the editor area.
In document mode (.md) it copies into the clipboard a shareable link which, when clicked, will open directly the rendered document, which can then also be edited.

These links can be sent by email, embedded in other documents, etc. See also adding links to runnable examples and notebooks to arbitrary documents).

Abort query

This button will appear below the top-level when running a query that is taking too long. It terminates the query currently running.

This button fully terminates the Ciao worker executing the Ciao process, so it may take a some time to reload dependencies after aborting. The code in the editor area will be reloaded into the top-level.

Additionally

In addition, in the More... pull-down the following can be selected:

Run tests (Ctrl-c + u): Loads the unit test library (unittest) into the top-level and runs any unit tests (test assertions) that may appear in the code.
Analyze and check assertions (Ctrl-c + V): Analyze the program and perform compile-time checking of the assertions (types, modes, determinacy, ...) in the current module (using CiaoPP).
Analyze and check assertions (w/output): Same as above, but also show in a separate area the results of analysis, i.e., the program annotated with the analysis results.
Specialize code (Ctrl-c + O): Run the CiaoPP specializer (partial evaluator) on the code in the editor area.
Browse analysis/checking/optimizing options: Open the CiaoPP graphical menu for selecting different options for analysis, assertion checking, and optimization.

Key bindings

The playground supports a number of key bindings (including some of the most used in Emacs). They are listed below, classified by functionality.

Editing key bindings

These commands and bindings are useful for editing and moving around in the editor area, top levels, etc.:

Ctrl-a - move cursor to the beginning of the line.
Ctrl-e - move cursor the end of the line.
Ctrl-f - move cursor forward.
Ctrl-b - move cursor backward.
Ctrl-p - previous line.
Ctrl-n - next line.
Ctrl-s - search forward in the editor.
Ctrl-r - search backward in the editor.
Ctrl-d - delete character to the right.
Ctrl-h - delete character to the left.
Ctrl-k - kill the line after the cursor.
Ctrl-m - insert line below.
Ctrl-o - insert line after the current position.
Ctrl-z - undo.
Ctrl-g - go to line.
Ctrl-x + u - undo.
Ctrl-X + o - move to another playground area.
Ctrl-v - go to the end of the editor.
Ctrl-x + Ctrl-p - select all.
Ctrl-x + Ctrl-u - transform selected text to upper case.
Ctrl-x + Ctrl-l - transform selected text to lower case.
Esc + d - delete the next word.
Esc + v - move cursor to the beginning.
Esc + Backspace - delete word to the left.
Esc + ; - comment/uncomment current line or selected lines.

Code processing key bindings

These commands perform Ciao or filesystem-related actions:

Ctrl-x + Ctrl-s - save file (same as button).
Ctrl-c + l - load code into top-level (same as button).

These commands perform actions on the source code:

Ctrl-c + d - (un)debug source code (same as button).
Ctrl-c + D - preview documentation (same as button).
Ctrl-c + u - run any tests in the source code (same as menu).
Ctrl-c + V - analyze and check assertions in source code (same as menu).
Ctrl-c + O - run specializer on source code (same as menu).

Specific key bindings for the top-level

The top-level area includes some key bindings of its own:

Up arrow - previous query in history.
Down arrow - next query in history.
Ctrl-p - previous query in history.
Ctrl-n - next query in history.
Ctrl-c - abort current query, if there is any running.

Ctrl-c fully terminates the Ciao worker executing the Ciao process in the browser, so it may take some time to reload dependencies after aborting. The code present in the left (or top) window will be reloaded to the top-level.

Some playground characteristics and current limitations

In this platform the Ciao system code (binaries) and libraries are downloaded into your browser and all code is executed locally. This has the advantage that no connection is required other than this initial download, no server is necessary, etc. Also note that with this approach no information about your code or document will be uploaded or gathered.

Please also be aware of some current limitations of the playground with respect to a full, native installation of the Ciao system:

To reduce download times, only a subset of the libraries are loaded by default.
Currently this platform is limited to 32-bit binaries, runs around 2-3x slower than native binaries, and only offers partial POSIX features. Some Prolog libraries that depend on 3rd-party binaries (via the foreign interface) may not be currently available.
The top level currently has some limitations regarding the loading of packages, portraying answers, and others. We are actively working on all of these and are adding functionality continuously.
Reading input from standard input (read/1) is currently not directly supported, due to WebAssembly limitations. We also plan to fix this soon.
To save space, only a subset of the analyses (abstract domains) and the capabilities of CiaoPP for program verification (assertion checking, etc.) and optimization are currently available.

Please ask us if some useful library or feature is missing; if technically possible, we will add it. In any case, for intensive use we recommend installing Ciao Prolog natively, for improved performance and full features.