Table of Contents

Basic operation

Prolog is about running a query against a program. The query goes into the bottom-right editor and the program into the left editor. The program can be empty, executing queries against the built-in predicates of Prolog. For example: 

?- format("Hello world!~n").

A query can be executed by hitting RETURN if the query is complete (i.e., ends in a full-stop) or by using the Run! button. At this moment, the following happens:

  1. The interface creates a runner in the top-right window that controls the execution of the query.
  2. The runner collects the text from the top-left editor (if any) and the query and sends this to the server, which creates a Pengine (Prolog Engine).
  3. The Pengine compiles the program into a temporary private module.
  4. The Pengine assesses whether executing the query can compromise the server. If this fails, an error is displated. See the help topic Caveats ... for details.
  5. If the query is considered safe, it executes the query and communicates with the runner about the results using JSON messages. The runner interaction is described in the help topic Runner ...

Note that you do not have to save your program to execute it. If your are not satisfied with the answer to a query, you can simply edit the program and use Run! again. The new query is executed in a completely new environment. In particular, data that you asserted in a previous query is not available in the next.

Use Ctrl + Enter ↵ to insert a newline in a complete query

Embedding examples in the program text

If you include example goals inside comments as shown below, they will be used to populate the example menu and make the first goal show in the Goal input field. 

/** <examples>

?- loves(X, mia).
?- jealous(X, Y).

*/

Save or share your program

The menu File/Save ... can be used to save your program. There are several options:

The Info & History ... menu can be used to examine and use old versions of the program.

Include other programs

If you know the name of a saved program (see above), you can reuse this program using Prolog's include/1 predicate as illustrated below. 

:- include(clever).

You can also include a specific version of a program by including its hash. You can find the hash of a specific version using Info & History ..., selecting the desired version and opening it using the play button. This will display the hash in the browser's address field. Now, include this version using e.g., 

:- include('23dacada6952ec6701da2dc9d4ebcf5c7b860380').

You can also use the Alias(Name) syntax to include files from the directories in the search path Alias. By default this is enabled for example, so the following directive allow you to reuse the predicates from the movies example: 

:- include(example(movies)).

Using File/Collaborate ..., you create a TogetherJS session that provides shared editing, chat and voice communication.

Download query results as CSV

After running a query, the complete result set for the query can be downloaded as a CSV (Comma Separated Values) document by clicking the button at the top-right of a runner window or using the Download answers as CSV option from the button on notebook query cells. This causes a dialogue to appear that allows for specifying the columns, optionally the detailed result format (if the server provides multiple result formats), whether only distinct results should be returned and the maximum number of results to return. The latter is by default set to 10 000 to avoid sending huge documents by accident. The field can be cleared to return all results.

Download query results through an API

The CSV results can also be downloaded programmatically by directly approaching the Pengine API. Example client code is available. For example, the `swish-ask.sh` client can be used with `bash` to download the results for a query. The call below downloads a CSV file for the sin function. 

$ bash swish.ask.sh --server=http://swish.swi-prolog.org \
		    X,Y \
		    "between(0,90,X),Y is sin(X*pi/180)"

The script can ask queries against stored Prolog scripts by specifying the script on the commandline. For example: 

$ bash swish.ask.sh --server=http://swish.swi-prolog.org \
		    sin_table.pl X,Y "sin_table(X,Y)"

Prolog can exploit the Pengine API directly. For example, the above can be called as: 

?- [library(pengines)].
?- pengine_rpc('http://swish.swi-prolog.org',
	       sin_table(X,Y),
	       [ src_text(':- include(sin_table).'),
		 application(swish)
	       ]).
X = 0,
Y = 0.0 ;
X = 1,
Y = 0.01745240643728351 ;
X = 2
...

Preload SWISH with data

You can make SWISH start with a loaded program using the URL http://swish.swi-prolog.org/ and providing the parameters below. The URL accepts both `GET` and `POST` requests.

code
Either the concrete code or a URL from which the code will be downloaded. If code is a URL and the extension is .swinb, the data is loaded into a SWISH notebook.
background
As code, but this part of the code will not be visible in the editor.
examples
As the above described examples comment block.
q
The initial query to load into the query window. Note that the following characters need to be escaped: '#', '&' and the space.

The URL below opens SWISH on a file from GitHub with a default query. 

http://swish.swi-prolog.org/?code=https://github.com/SWI-Prolog/swipl-devel/raw/master/demo/likes.pl&q=likes(sam,Food).
Try it! (launches a new tab)

The URL below opens SWISH on notebook. 

http://localhost:3050/?code=https://raw.githubusercontent.com/SWI-Prolog/swish/master/examples/htmlcell.swinb
Try it! (launches a new tab)