SWI-Prolog

https://www.swi-prolog.org/pldoc
Admin
SWI-Prolog is a free and open-source Prolog implementation with extensive libraries for logic...
Tokens:11,894,718
Snippets:86,595
Trust Score:9.4
Update:1 hour ago
Show doc for...
Tokens:
Raw
### Start local SWI-Prolog website server

Source: https://www.swi-prolog.org/pldoc/doc/_CWD_/index.html

Command to start the website locally after installation, providing access to the same content as the public site except the download section.

```shell
% swipl load.pl -p 8080 -i
```

--------------------------------

### Setup local documentation server with doc_load_library/0

Source: https://www.swi-prolog.org/pldoc/doc_for?object=doc_load_library%2F0

Loads all library files to set up a local documentation server. The example starts the server on port 4000, allowing access from hosts in the '.my.org' domain, then loads the doc_library module and all library files. Requires the pldoc(doc_library) module.

```prolog
:- doc_server(4000,
              [ allow('.my.org')
              ]).
:- use_module(library(pldoc/doc_library)).
:- doc_load_library.
```

--------------------------------

### Start Linda server with initialization goal

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/ext/tipc/tipc/tipc_linda.pl

Starts the Linda server and calls my_init/0 in the current module after the server is successfully started or found already listening. my_init/0 can start client processes or initialize the tuple space.

```prolog
?- linda(my_init).
```

--------------------------------

### setup_signals/1 - Reinstall int signal to start debugger

Source: https://www.swi-prolog.org/pldoc/doc/_CWD_/packs/libssh/prolog/ssh_server.pl?format_comments=true&show=src

Re-installs the int signal to start the debugger. Notably, library(http/http_unix_daemon) binds this signal to terminate the process, so this predicate overrides that behavior. Any error during installation is caught and reported as a warning.

```prolog
setup_signals(_Options) :-
    E = error(_,_),
    catch(on_signal(int, _, debug), E, print_message(warning, E)).
```

--------------------------------

### Load TIPC Linda package and start server

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/ext/tipc/tipc/tipc_linda.pl

Loads the TIPC Linda library and starts the Linda server in the current process. The server prints its TIPC port_id reference to the current output stream.

```prolog
?- use_module(library(tipc/tipc_linda)).

?- linda.
   TIPC Linda server now listening at: port_id('<1.1.1:3200515722>')
   true.
```

--------------------------------

### Start Linda server and show existing server behavior

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/ext/tipc/tipc/tipc_linda.pl

Starts the Linda server. If a server is already listening on the cluster, it reports the existing server's address instead of registering a new one.

```prolog
?- linda.
   TIPC Linda server now listening at: port_id('<1.1.1:3200515722>')
   true.

?- linda.
   TIPC Linda server still listening at: port_id('<1.1.1:3200515722>')
   true.
```

--------------------------------

### Load sweeprolog library in Emacs

Source: https://www.swi-prolog.org/pldoc/doc_for?object=section%28%27packages%2Fsweep.html%27%29

Loads the sweeprolog Elisp library after installation. Enables Sweep for Prolog development and integrating Prolog into Emacs Lisp code.

```emacs-lisp
  (require 'sweeprolog)
```

--------------------------------

### Server setup with tcp_socket, tcp_bind, tcp_listen, tcp_open_socket

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/ext/clib/socket.pl?public_only=false

Typical sequence for creating a server: create a socket, bind to a port, listen, and open a stream pair. The resulting AcceptFd is used for dispatching connections. Close the server with close/1 on the StreamPair.

```prolog
create_server(Port) :-
      tcp_socket(Socket),
      tcp_bind(Socket, Port),
      tcp_listen(Socket, 5),
      tcp_open_socket(Socket, StreamPair),
      stream_pair(StreamPair, AcceptFd, _),
      <dispatch>
```

--------------------------------

### check_installation/1 and helper predicates

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/check_installation.pl?format_comments=true&show=src

Main entry point that runs all installation checks and converts internal issue terms to public ones. It retracts previous issues, checks each component, and collects the results.

```prolog
check_installation(Issues) :-
    check_installation_(Issues0),
    maplist(public_issue, Issues0, Issues).

public_issue(installation(Term), Source-Issue) :-
    functor(Term, Issue, _),
    arg(1, Term, Properties),
    Source = Properties.source.

check_installation_(Issues) :-
    retractall(issue(_)),
    forall(component(Source, _Properties),
           check_component(Source)),
    findall(I, retract(issue(I)), Issues).

check_component(Source) :-
    component(Source, Properties),
    !,
    check_component(Source, Properties.put(source,Source)).

check_component(_Source, Properties) :-
    OS = Properties.get(os),
    \+ current_os(OS),
    !.
check_component(Source, Properties) :-
    compound(Source),
    !,
    check_source(Source, Properties).
check_component(Feature, Properties) :-
    print_message(informational, installation(checking(Feature))),
    (   call(Properties.test)
    ->  print_message(informational, installation(ok))
    ;   print_issue(installation(missing(Properties)))
    ).

check_source(Source, Properties) :-
    exists_source(Source),
    !,
    print_message(informational, installation(loading(Source))),
    (   run_silent(( (   Pre = Properties.get(pre)
                     ->  call(Pre)
                     ;   true
                     ),
                     load_files(Source, [silent(true), if(true)])
                   ),
                   Properties.put(action, load))
    ->  test_component(Properties),
        print_message(informational, installation(ok)),
        check_features(Properties)
    ;   true
    ).
check_source(_Source, Properties) :-
    Properties.get(optional) == true,
    !,
    print_message(silent,
                  installation(optional_not_found(Properties))).
check_source(_Source, Properties) :-
    print_issue(installation(not_found(Properties))).

current_os(unix)    :- current_prolog_flag(unix, true).
current_os(windows) :- current_prolog_flag(windows, true).
current_os(linux)   :- current_prolog_flag(arch, Arch),
                       sub_atom(Arch, _, _, _, linux).
```

--------------------------------

### Add rules from the console using [user]

Source: https://www.swi-prolog.org/pldoc/man?section=quickstart

Consult the pseudo file user to add clauses interactively. End input with the system end-of-file character (^D). The example defines a hello/0 predicate and then queries it.

```prolog
?- [user].
|: hello :- format('Hello world~n').
|: ^D
true.

?- hello.
Hello world
true.
```

--------------------------------

### Example: listen to key1 and key2 with reconnect

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/ext/redis/redis_streams.pl?format_comments=true&show=src

Shows how to start xlisten/3 in a detached thread on the default Redis server with reconnect(true) to re-establish lost connections. Uses start($) to get messages from the last.

```prolog
?- redis_connect(default, C, [reconnect(true)]),
   thread_create(xlisten(C, [key1, key2], [start($)]),
                 _, [detached(true)]).
```

--------------------------------

### Test with setup and cleanup options

Source: https://www.swi-prolog.org/pldoc/doc_for?object=section%28%27packages%2Fplunit.html%27%29

Shows a test using the setup and cleanup options to create and delete a temporary file. The setup predicate create_file/1 writes a term to a temporary file, and the cleanup predicate delete_file/1 removes it after the test body runs.

```prolog
create_file(Tmp) :-
        tmp_file(plunit, Tmp),
        open(Tmp, write, Out),
        write(Out, 'hello(World).\n'),
        close(Out).

test(read, [ setup(create_file(Tmp)),
             cleanup(delete_file(Tmp))
           ]) :-
        read_file_to_terms(Tmp, Terms, []),
        Term = hello(_).
```

--------------------------------

### Show MQI command line help

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/ext/mqi/mqi.pl?format_comments=true&show=src

Displays help for the `swipl mqi` command line options.

```bash
swipl mqi --help
```

--------------------------------

### Enable NonGNU ELPA in Emacs configuration

Source: https://www.swi-prolog.org/pldoc/doc_for?object=section%28%27packages%2Fsweep.html%27%29

Adds the NonGNU ELPA package archive to Emacs. Required for Emacs versions prior to 28 to install sweeprolog via package-install. Place in your Emacs configuration file.

```emacs-lisp
  (with-eval-after-load 'package
    (add-to-list 'package-archives '("nongnu" . "https://elpa.nongnu.org/nongnu/")))
```

--------------------------------

### setup_interactive: run one-time interactive setup

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/boot/toplevel.pl?format_comments=false&show=raw

Runs setup_backtrace, setup_readline, and setup_history once, catching and warning on errors. Uses dynamic/volatile setup_done to avoid re-running.

```prolog
setup_interactive :-
    setup_done,
    !.
setup_interactive :-
    asserta(setup_done),
    catch(setup_backtrace, E, print_message(warning, E)),
    catch(setup_readline,  E, print_message(warning, E)),
    catch(setup_history,   E, print_message(warning, E)).
```

--------------------------------

### tcp_connect client connection steps

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/ext/clib/socket.pl?public_only=false

Shows the low-level client API steps to connect to a host and port: create a socket, connect, and open streams.

```prolog
    tcp_socket(Socket),
    tcp_connect(Socket, Host:Port),
    tcp_open_socket(Socket, StreamPair)

```

--------------------------------

### trap/1

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/prolog_debug.pl

Installs a trap on error(Formal, Context) exceptions that unify. The tracer is started when a matching exception is raised. This predicate enables debug mode using debug/0 to get more context about the exception.

```APIDOC
## trap/1

### Description
Installs a trap on error(Formal, Context) exceptions that unify. The tracer is started when a matching exception is raised. This predicate enables debug mode using debug/0 to get more context about the exception.

### Signature
trap(+Formal) is det

### Parameters
- **Formal** (term) - Required - The formal part of the exception to trap.

### See Also
- gtrap/1 to trap using the graphical debugger.
- _Edit exceptions_ menu in PceEmacs and the graphical debugger that provide a graphical frontend to trap exceptions.
```

--------------------------------

### Start SWI-Prolog with a source file as command line argument

Source: https://www.swi-prolog.org/pldoc/man?section=starting

Passes likes.pl directly on the command line to load it at startup. Assumes likes.pl is in the working directory.

```shell
$ swipl likes.pl
Welcome to SWI-Prolog ...
...

1 ?-
```

--------------------------------

### Producer-consumer example: init_producer and producer

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/ext/tipc/tipc/tipc_linda.pl?format_comments=false&show=raw

Shows a simple producer-consumer setup for TIPC Linda. In client 1, init_producer/0 connects to the Linda server with linda_client(global) and starts the producer loop, which repeatedly produces a value X and writes it to the tuple space with out(p(X)). The example is truncated in the source and does not include the consumer side.

```prolog
init_producer :-
       linda_client(global),
       producer.

producer :-
       produce(X),
       out(p(X)),
       producer.
```

--------------------------------

### Example 3: transportation problem setup and transpose helpers

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/clp/simplex.pl?format_comments=true&show=src

Shows the initial part of Example 3, including the maplist/lists_transpose setup and the transpose helper predicates. The code is part of the simplex library's transportation example.

```prolog
        maplist(=(0), Alphas),
        lists_transpose(Costs, TCs),
        maplist(min_list, TCs, Betas).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

lists_transpose([], []).
lists_transpose([L|Ls], Ts) :- foldl(transpose_, L, Ts, [L|Ls], _).

transpose_(_, Fs, Lists0, Lists) :-
        maplist(list_first_rest, Lists0, Fs, Lists).

list_first_rest([L|Ls], L, Ls).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
   TODO: use attributed variables throughout
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
```

--------------------------------

### Start the pengine server

Source: https://www.swi-prolog.org/pldoc/doc_for?object=section%28%27packages%2Fpengines.html%27%29

Loads the server module and starts the server on port 10001. The server prints the URL it is listening on.

```prolog
?- [server].
true.

?- server(10001).
% Started server at http://localhost:10001/
true.
```

--------------------------------

### linda/0 and linda/1 usage examples

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/ext/tipc/tipc/tipc_linda.pl

Shows the output of calling linda/0 twice: the first call starts a TIPC Linda server and reports its address, the second call reports the existing server's address. The linda(my_init) example calls my_init/0 in the current module after the server is started or found listening.

```prolog
?- linda.
   TIPC Linda server now listening at: port_id('<1.1.1:3200515722>')
   true.

?- linda.
   TIPC Linda server still listening at: port_id('<1.1.1:3200515722>')
   true.
```

```prolog
?- linda(my_init).
```

--------------------------------

### setup_output/1

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/ext/http/http/http_unix_daemon.pl?format_comments=true&show=src

Sets up output from the daemon process. With the 'output' option, it opens the file for writing with UTF-8 encoding and line buffering, then detaches I/O. Otherwise, it sends all output to a null stream.

```prolog
setup_output(Options) :-
    option(output(File), Options),
    !,
    open(File, write, Out, [encoding(utf8)]),
    set_stream(Out, buffer(line)),
    detach_IO(Out).
setup_output(_) :-
    open_null_stream(Out),
    detach_IO(Out).
```

--------------------------------

### pool_manager/1 - Get or start the pool manager thread

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/thread_pool.pl?format_comments=false&show=raw

Returns the alias identifier of the manager thread, starting it if it is not already running.

```prolog
pool_manager(TID) :-
    TID = '__thread_pool_manager',
    (   thread_running(TID)
    ->  true
    ;   with_mutex('__thread_pool', create_pool_manager(TID))
    ).
```

--------------------------------

### opt_help/2 descriptions for MQI options

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/ext/mqi/mqi.pl?format_comments=true&show=src

Provides human-readable help text for each MQI option. The help strings describe the purpose and defaults, such as pending_connections default 5 and query_timeout default infinite.

```prolog
opt_help(port,                      "TCP/IP port for clients to connect to").
opt_help(create_unix_domain_socket, "Create a Unix domain socket for clients to connect to").
opt_help(unix_domain_socket,        "File path for the Unix domain socket").
opt_help(password,                  "Connection password").
opt_help(pending_connections,       "Max number of queued connections (5)").
opt_help(query_timeout,             "Max query runtime in seconds (default infinite)").
opt_help(run_server_on_thread,      "Run server in a background thread (true)").
opt_help(exit_main_on_failure,      "Exit the process on a failure").
opt_help(write_connection_values,   "Print info for clients to connect").
opt_help(write_output_to_file,      "Write stdout and stderr to file").
```

--------------------------------

### setup_app: restore working directory for app mode

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/boot/toplevel.pl?format_comments=false&show=raw

Called during startup on Unix-like platforms. If running as an app, restores the working directory and cuts; otherwise does nothing.

```prolog
setup_app :-
    running_as_app,
    restore_working_directory,
    !.
setup_app.
```

--------------------------------

### Start documentation server and load application

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/ext/pldoc/pldoc.pl?format_comments=true&show=src

Typical development setup: starts the PlDoc web server on port 4000 and loads the application source. The server allows starting an editor only from localhost by default.

```prolog
:- doc_server(4000).
:- [application].
```

--------------------------------

### run_netscape/1 example

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/ext/clib/unix.pl?format_comments=true&show=src

Example of using fork/1 and exec/1 to start netscape on a URL in the background. The child remains in the process group and Prolog does not wait for it.

```prolog
run_netscape(URL) :-
        (    fork(child),
             exec(netscape(URL))
        ;    true
        ).
```

--------------------------------

### begin_tests/2

Source: https://www.swi-prolog.org/pldoc/doc_for?object=section%28%27packages%2Fplunit.html%27%29

Starts a named test unit with options for conditional processing, setup, and cleanup.

```APIDOC
## begin_tests/2

### Description
Starts a named test unit with options for conditional processing, setup, and cleanup.

### Method
Predicate

### Signature
`begin_tests(+Name, +Options)`

### Parameters
#### Options
- **blocked(+Reason)** - Test-unit has been blocked for the given Reason.
- **condition(:Goal)** - Executed before any tests; if it fails, tests are skipped.
- **setup(:Goal)** - Executed before any tests.
- **cleanup(:Goal)** - Executed after all tests in the unit.
- **occurs_check(+Mode)** - Default occurs-check mode for tests in the unit.

### Example
```prolog
begin_tests(my_tests, [setup(setup_goal), cleanup(cleanup_goal)]).
```
```

--------------------------------

### gui_setup_ and editor_setup for GUI initialization

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/swipl.rc?format_comments=true&show=src

Prepares the GUI environment. Sets the gui flag to true, configures the editor to PceEmacs if it is still 'default', and loads swi_hooks. The first clause succeeds if gui is already true.

```prolog
   80gui_setup_ :-
   81    current_prolog_flag(gui, true),
   82    !.
   83gui_setup_ :-
   84    create_prolog_flag(gui, true, []),
   85    editor_setup,
   86    use_module(user:library(swi_hooks)).
   87
   88editor_setup :-
   89    current_prolog_flag(editor, default),
   90    !,
   91    set_prolog_flag(editor, pce_emacs).
   92editor_setup.
```

--------------------------------

### linda/0 and linda/1

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/ext/tipc/tipc/tipc_linda.pl?format_comments=true&show=src

Starts a Linda-server in the current process or reports an existing server. The optional goal is called after the server is started or found listening.

```APIDOC
## linda/0, linda/1

### Description
Starts a Linda-server in this process. The network address is written to the current output stream as a TIPC port_id/2 reference (e.g. `port_id('<1.1.1:3200515722>')`). This predicate looks to see if a server is already listening on the cluster. If so, it reports the address of the existing server. Otherwise, it registers a new server and reports its address. The variant with a goal calls that goal after the server is successfully started or found already listening.

### Predicates
- **linda** is det
- **linda**(:Goal) is det

### Parameters
#### Goal (for linda/1)
- **:Goal** (callable) - Required - A goal to call after the server is started or found listening.

### Example
```prolog
?- linda.
   TIPC Linda server now listening at: port_id('<1.1.1:3200515722>')
   true.

?- linda.
   TIPC Linda server still listening at: port_id('<1.1.1:3200515722>')
   true.

?- linda(my_init).
```
```

--------------------------------

### index_examples/0 and index_examples/1 with mutex and transaction

Source: https://www.swi-prolog.org/pldoc/doc/_CWD_/examples.pl?format_comments=true&show=src

Entry points for indexing example files. index_examples/0 calls index_examples/60. The predicates use a mutex and a transaction to avoid concurrent reindexing and check if the index is up to date.

```prolog
index_examples :-
    index_examples(60).

index_examples(Backlog) :-
    index_up_to_data(Backlog), !.
index_examples(Backlog) :-
    with_mutex(index_examples, index_examples2(Backlog)).

index_examples2(Backlog) :-
    index_up_to_data(Backlog), !.
index_examples2(_) :-
    transaction(reindex_examples).
```

--------------------------------

### REST handler for GET and POST

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/ext/http/http/http_dispatch.pl?format_comments=false&show=raw

Example handler clauses for the REST path. The first clause handles GET requests, the second handles POST requests.

```prolog
user(get, User, Request) :-
    ...
```

```prolog
user(post, User, Request) :-
    ...
```

--------------------------------

### Change working directory and start doc server

Source: https://www.swi-prolog.org/pldoc/doc_for?object=section(%27packages/pldoc.html%27)

Sets the working directory to a specific path and starts the doc server. The output shows the previous working directory and the server startup message.

```prolog
?- working_directory(Old,'/home/paquette/docs/alpha/').
Old = '/home/paquette/'.

?- doc_server(4000).
% Started server at http://localhost:4000/pldoc/
true.
```

--------------------------------

### Start TIPC Listener Daemon

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/ext/tipc/tipc/tipc_broadcast.pl?format_comments=false&show=src

Starts the TIPC listener daemon if not already running. Uses thread_create with alias 'tipc_listener_daemon' and waits for a ready message with a 6-second timeout.

```prolog
catch(thread_property(tipc_listener_daemon, status(running)),_, fail),
    !.

start_tipc_listener_daemon :-
    thread_self(Self),
    thread_create(tipc_listener_daemon(Self), _,
           [alias(tipc_listener_daemon), detached(true)]),
    call_with_time_limit(6.0,
                         thread_get_message(tipc_listener_daemon_ready)).
```

--------------------------------

### Stop the Prolog toplevel with halt/0

Source: https://www.swi-prolog.org/pldoc/man?section=quickstart

Terminates the interactive toplevel. The shell prompt ($) appears after halting. Alternatively, you can press the system end-of-file character (typically Control-D).

```prolog
?- halt.
$
```

--------------------------------

### pce_setup_ predicate with lazy XPCE loading

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/swipl.rc?format_comments=false&show=src

Sets up XPCE based on the current Prolog flag and display availability. If the xpce flag is true, preloads the library; otherwise, if a display is present, sets up lazy loading. If no display, asserts pce_setup_done(false).

```prolog
pce_setup_ :-
    pce_setup_done(_),
    !.
pce_setup_ :-
    (   current_prolog_flag(xpce, true)
    ->  Preload = true,
        How = true
    ;   has_display,                % no explicit xpce flag
        Preload = false,
        How = lazy
    ),
    !,
    set_prolog_flag(xpce, true),
    asserta(pce_setup_done(How)),
    reload_library_index,
    gui_setup_,
    (   Preload == true
    ->  ensure_loaded(user:library(pce))
    ;   true
    ).
pce_setup_ :-                       % Implicit and no display
    asserta(pce_setup_done(false)).
```

--------------------------------

### ex_repo/1

Source: https://www.swi-prolog.org/pldoc/doc/_CWD_/examples.pl?format_comments=true&show=src

True when Dir is a toplevel example directory. Uses absolute_file_name/3 with the alias examples(.) and requires a readable directory.

```prolog
ex_repo(Dir) :-
    absolute_file_name(examples(.), Dir,
                       [ file_type(directory),
                         access(read),
                         solutions(all)
                       ]).
```

--------------------------------

### predicate_name/2 with module-qualified output fails

Source: https://www.swi-prolog.org/pldoc/doc_for?object=prolog_clause%3Apredicate_name%2F2

Attempting to get the module-qualified name using M:S as the second argument fails, returning false. The example raises the question of when the module name is added.

```prolog
?- predicate_name(is_ordset(_),M:S).
false.
```

--------------------------------

### walltime/1 - Get wall time since Prolog started

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/dialect/xsb.pl?format_comments=true&show=src

True when Seconds is the wall time since Prolog was started. Computes the difference between current time and the epoch.

```prolog
walltime(Seconds) :-
    get_time(Now),
    statistics(epoch, Epoch),
    Seconds is Now - Epoch.
```

--------------------------------

### Create Log and Pack Directories with Permissions

Source: https://www.swi-prolog.org/pldoc/doc/_CWD_/index.html

Creates the logging and pack mirror directories, sets the group to www-data, and applies setgid and group-write permissions. These directories must be writeable by the server and new subdirectories must inherit the same permissions.

```bash
% mkdir log pack
% chgrp www-data log pack
% chmod g+ws log pack
```

--------------------------------

### '$run_initialization'/2 and /3 with helper predicates

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/boot/init.pl?format_comments=true&show=src

Runs initialization directives for all files (unbound File) or a specific file. '$run_initialization'/3 with Action 'loaded' is a no-op for QLF files; otherwise it delegates to /2. Uses setup_call_cleanup to manage sandboxed_load flag and input context. '$run_init_goal'/2 catches errors and reports initialization_error or initialization_failure messages.

```prolog
'$run_initialization'(_, loaded, _) :- !.
'$run_initialization'(File, _Action, Options) :-
    '$run_initialization'(File, Options).

'$run_initialization'(File, Options) :-
    setup_call_cleanup(
	'$start_run_initialization'(Options, Restore),
	'$run_initialization_2'(File),
	'$end_run_initialization'(Restore)).

'$start_run_initialization'(Options, OldSandBoxed) :-
    '$push_input_context'(initialization),
    '$set_sandboxed_load'(Options, OldSandBoxed).
'$end_run_initialization'(OldSandBoxed) :-
    set_prolog_flag(sandboxed_load, OldSandBoxed),
    '$pop_input_context'.

'$run_initialization_2'(File) :-
    (   '$init_goal'(File, Goal, Ctx),
	File \= when(_),
	'$run_init_goal'(Goal, Ctx),
	fail
    ;   true
    ).

'$run_init_goal'(Goal, Ctx) :-
    (   catch_with_backtrace('$run_init_goal'(Goal), E,
			     '$initialization_error'(E, Goal, Ctx))
    ->  true
    ;   '$initialization_failure'(Goal, Ctx)
    ).

:- multifile prolog:sandbox_allowed_goal/1.

'$run_init_goal'(Goal) :-
    current_prolog_flag(sandboxed_load, false),
    !,
    call(Goal).
'$run_init_goal'(Goal) :-
    prolog:sandbox_allowed_goal(Goal),
    call(Goal).

'$initialization_context'(Source, Ctx) :-
    (   source_location(File, Line)
    ->  Ctx = File:Line,
	'$input_context'(Context),
	'$top_file'(Context, File, Source)
    ;   Ctx = (-),
	File = (-)
    ).

'$top_file'([input(include, F1, _, _)|T], _, F) :-
    !,
    '$top_file'(T, F1, F).
'$top_file'(_, F, F).


'$initialization_error'(unwind(halt(Status)), Goal, Ctx) :-
    !,
    print_message(warning, initialization(halt(Status), Goal, Ctx)).
'$initialization_error'(E, Goal, Ctx) :-
    print_message(error, initialization_error(Goal, E, Ctx)).

'$initialization_failure'(Goal, Ctx) :-
    print_message(warning, initialization_failure(Goal, Ctx)).
```

--------------------------------

### Project pack installation file packs.pl

Source: https://www.swi-prolog.org/pldoc/man?section=pack-install

Example `packs.pl` file that defines project dependencies and installs them with `pack_install_local/3`. The `attach_packs/2` directive must match the project's configuration. The `pack/2` clauses specify each pack and its options (e.g., commit). Run with `swipl packs.pl`.

```prolog
:- module(packs, []).
:- use_module(library(prolog_pack)).
:- attach_packs(packs, [replace(true)]).

:- initialization(install, main).

pack(scasp, [commit('HEAD')]).
pack(environ, []).
pack(date_time, []).

install :-
    pack_install_local(pack, packs, []).
```

--------------------------------

### Example: http_read_request/2 parsing a GET request

Source: https://www.swi-prolog.org/pldoc/doc_for?object=section%28%27packages%2Fhttp.html%27%29

Shows the interactive query and output for http_read_request/2 when reading a GET request from user_input. The request includes a search specification (?class=person) and a Host header, producing fields like method(get), search([class=person]), path('/mydb'), http_version(1-0), and host(gollem).

```prolog
?- http_read_request(user_input, X).
|: GET /mydb?class=person HTTP/1.0
|: Host: gollem
|:
X = [ input(user),
      method(get),
      search([ class = person
             ]),
      path('/mydb'),
      http_version(1-0),
      host(gollem)
    ].
```

--------------------------------

### Hello World example with pwp:ask and pwp:use

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/ext/sgml/pwp.pl?format_comments=true&show=src

A minimal PWP page that loads a Prolog file via pwp:ask and uses a variable to insert text. The Prolog file msg.pl defines the message. Note that PWP does not allow embedding Prolog clauses directly in the template; they must be in separate files.

```html
<html
  xmlns:pwp="http://www.cs.otago.ac.nz/staffpriv/ok/pwp.pl"
  pwp:ask = "ensure_loaded(msg), once(msg(Greeting))">
  <head>
    <title pwp:use="Greeting"/>
  </head>
  <body>
    <p><span pwp:use="Greeting" pwp:tag='-'/></p>
  </body>
</html>
```

```prolog
msg('Hello, World!').
```

--------------------------------

### mqi_start(+Options:list)

Source: https://www.swi-prolog.org/pldoc/doc_for?object=section%28%27packages%2Fmqi.html%27%29

Starts a Prolog Machine Query Interface (MQI) using the provided options. The MQI listens for TCP/IP or Unix Domain Socket connections and authenticates them using the provided password before processing messages.

```APIDOC
## mqi_start(+Options:list)

### Description
Starts a Prolog Machine Query Interface (MQI) using the provided options. The MQI listens for TCP/IP or Unix Domain Socket connections and authenticates them using the provided password before processing messages.

### Method
Predicate

### Signature
mqi_start(+Options:list)

### Parameters
#### Options
- **port(?Port)** - Optional - The TCP/IP port to bind to on localhost. Ignored if unix_domain_socket/1 is set. Port is either a legal TCP/IP port number (integer) or a variable term. If a variable, the system selects a free port and unifies the variable with it. If write_connection_values(true) is set, the selected port is output to STDOUT followed by \n on startup.
- **unix_domain_socket(?Unix_Domain_Socket_Path_And_File)** - Optional - If set, Unix Domain Sockets are used for communication. Specifies the fully qualified path and filename for the socket. If a variable, a temporary directory and socket file are generated. If write_connection_values(true) is set, the fully qualified path is output to STDOUT followed by \n on startup.

### Usage Examples
#### Standalone Mode (Prolog top level)
```prolog
mqi_start([unix_domain_socket(Socket), password('a password')])
```

#### Embedded Mode (command line)
```
swipl mqi --write_connection_values=true --password="a password" --create_unix_domain_socket=true
```

### Debugging
- `debug(mqi(protocol))` - Traces protocol messages to show the flow of commands and connections.
- `debug(mqi(query))` - Traces messages that involve each query and its results.

### Notes
- The MQI is normally started automatically by a library built for a particular programming language (e.g., the `swiplserver` Python library).
- Starting manually can be useful when debugging Prolog code in some scenarios.
- See the documentation on "Standalone Mode" for more information.
- The messages processed by the MQI are described in section 1.6.
- For Unix Domain Socket files, the path must be below 92 bytes long (including null terminator) to be portable according to Linux documentation.
- If the file exists when the MQI is launched, it will be deleted.
- The Prolog process will attempt to create and, if Prolog exits cleanly, delete this file (and directory if created) when the MQI closes.
- For security reasons, the filename should not be predictable and the directory should have permissions set so that files created are only accessible to the current user.
```

--------------------------------

### Bit-vector foreign data example: get_bitvector, unify_bitvector, pl_bitvector_union

Source: https://www.swi-prolog.org/pldoc/man?section=foreigninclude

Shows how to store integer sets as bit-vectors using SWI-Prolog foreign interface. Defines helper functions to get and unify bitvector/1 terms and a foreign predicate bitvector_union/3. Uses PL_is_functor, PL_get_string, PL_unify_string_nchars, and PL_register_foreign. The install() function registers the foreign predicate and creates the functor for bitvector/1.

```C
#include <SWI-Prolog.h>

#define max(a, b) ((a) > (b) ? (a) : (b))
#define min(a, b) ((a) < (b) ? (a) : (b))

static functor_t FUNCTOR_bitvector1;

static int
get_bitvector(term_t in, int *len, unsigned char **data)
{ if ( PL_is_functor(in, FUNCTOR_bitvector1) )
  { term_t a = PL_new_term_ref();

    PL_get_arg(1, in, a);
    return PL_get_string(a, (char **)data, len);
  }

  PL_fail;
}

static int
unify_bitvector(term_t out, int len, const unsigned char *data)
{ if ( PL_unify_functor(out, FUNCTOR_bitvector1) )
  { term_t a = PL_new_term_ref();

    PL_get_arg(1, out, a);

    return PL_unify_string_nchars(a, len, (const char *)data);
  }

  PL_fail;
}

static foreign_t
pl_bitvector_union(term_t t1, term_t t2, term_t u)
{ unsigned char *s1, *s2;
  int l1, l2;

  if ( get_bitvector(t1, &l1, &s1) &&
       get_bitvector(t2, &l2, &s2) )
  { int l = max(l1, l2);
    unsigned char *s3 = alloca(l);

    if ( s3 )
    { int n;
      int ml = min(l1, l2);

      for(n=0; n<ml; n++)
        s3[n] = s1[n] | s2[n];
      for( ; n < l1; n++)
        s3[n] = s1[n];
      for( ; n < l2; n++)
        s3[n] = s2[n];

      return unify_bitvector(u, l, s3);
    }

    return PL_warning("Not enough memory");
  }

  PL_fail;
}


install_t
install()
{ PL_register_foreign("bitvector_union", 3, pl_bitvector_union, 0);

  FUNCTOR_bitvector1 = PL_new_functor(PL_new_atom("bitvector"), 1);
}

```

--------------------------------

### Enumerate starting indices of overlapping sub-atom with sub_atom/5

Source: https://www.swi-prolog.org/pldoc/doc_for?object=sub_atom%2F5

Query sub_atom/5 to find all 0-based starting positions of a possibly overlapping sub-atom in an atom. The example shows backtracking over solutions and the final false.

```prolog
?- sub_atom(banana, Pos, _, _, ana).
Pos = 1 ;
Pos = 3 ;
false.
```

--------------------------------

### setup/3: call setup handler and fail on error

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/ext/plunit/plunit.pl?format_comments=false&show=src

Calls the setup handler and fails if it cannot run for some reason. Context is either unit(Unit) or test(Unit,Name,Line). Reports errors via print_message/2.

```prolog
setup(Module, Context, Options) :-
    option(setup(Setup), Options),
    !,
    capture_output(reify(call_ex(Module, Setup), Result), Output),
    (   Result == true
    ->  true
    ;   print_message(error,
		      plunit(error(setup, Context, Output, Result))),
	fail
    ).
setup(_,_,_).
```

--------------------------------

### start_connection creates engine and opens query

Source: https://www.swi-prolog.org/pldoc/man?section=foreign-yield

Creates a Prolog engine and opens a query to handle_connection/1 on a given stream. Uses PL_WITH_ENGINE to make the engine current, and passes PL_Q_CATCH_EXCEPTION|PL_Q_ALLOW_YIELD|PL_Q_EXT_STATUS to PL_open_query. Error checking is omitted for readability.

```c
qid_t
start_connection(IOSTREAM *c)
{ predicate_t p = PL_predicate("handle_connection", 1, "user");

  PL_engine_t e = PL_create_engine(NULL);
  qid_t q = NULL;
  PL_WITH_ENGINE(e)
  { term_t av = PL_new_term_refs(1);
    PL_unify_stream(av+0, c);
    q = PL_open_query(e, NULL,
                      PL_Q_CATCH_EXCEPTION|
                      PL_Q_ALLOW_YIELD|
                      PL_Q_EXT_STATUS,
                      p, av);
  }
  return q;
}

```

--------------------------------

### sequence(:Start, :Element, :Sep, :End, ?List)//

Source: https://www.swi-prolog.org/pldoc/doc/_SWI_/library/dcg/high_order.pl?format_comments=false&show=raw

Matches or generates a sequence of elements enclosed by a start and end, with separators between elements. It matches the pattern Start, (Element, (Sep,Element)*)?, End. The example matches a Prolog list of integers.

```APIDOC
## sequence(:Start, :Element, :Sep, :End, ?List)//

### Description
Matches or generates a sequence of elements enclosed by a start and end, with separators between elements. It matches the pattern Start, (Element, (Sep,Element)*)?, End. The example matches a Prolog list of integers.

### Signature
sequence(:Start, :Element, :Sep, :End, ?List)//

### Parameters
- **Start** (callable) - Required - A DCG goal that matches the start delimiter.
- **Element** (callable) - Required - A DCG goal that matches a single element.
- **Sep** (callable) - Required - A DCG goal that matches the separator between elements.
- **End** (callable) - Required - A DCG goal that matches the end delimiter.
- **List** (list) - Required - The list of elements to match or generate.

### Example
```prolog
?- phrase(sequence(("[",blanks), number, (",",blanks), (blanks,"]"), L), `[1, 2, 3 ] a`, Tail).
L = [1, 2, 3],
Tail = [32, 97].
```
```
Tokens:
Raw