VU University Amsterdam University of Amsterdam

De Boelelaan 1081a, 1081 HV Amsterdam Kruislaan 419, 1098 VA Amsterdam

The Netherlands The Netherlands

Reference Manual
Updated for version 7.4-1, March 2017

Jan Wielemaker
[email protected]
http://www.swi-prolog.org

SWI-Prolog is a comprehensive and portable implementation of the Prolog programming

language. SWI-Prolog aims to be a robust and scalable implementation supporting a
wide range of applications. In particular, it ships with a wide range of interface libraries,
providing interfaces to other languages, databases, graphics and networking. It provides
extensive support for managing HTML/SGML/XML and RDF documents. The system
is particularly suited for server applications due to robust support for multithreading and
HTTP server libraries.
SWI-Prolog is designed in the Edinburgh tradition. In addition to the ISO Prolog stan-
dard it is largely compatible to Quintus, SICStus and YAP Prolog. SWI-Prolog provides
a compatibility framework developed in cooperation with YAP and instantiated for YAP,
SICStus and IF/Prolog.
SWI-Prolog aims at providing a good development environment, including extensive ed-
itor support, graphical source-level debugger, autoloading and make facility and much
more. SWI-Prolog editor and the PDT plugin for Eclipse provide alternative environ-
ments.
This document gives an overview of the features, system limits and built-in predicates.


This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported
License. To view a copy of this license, visit http://creativecommons.org/
licenses/by-sa/3.0/ or send a letter to Creative Commons, 444 Castro Street,
Suite 900, Mountain View, California, 94041, USA.
Contents

1 Introduction 11
1.1 Positioning SWI-Prolog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.2 Status and releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.3 Should I be using SWI-Prolog? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.4 Support the SWI-Prolog project . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.5 Implementation history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1.6 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2 Overview 16
2.1 Getting started quickly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.1.1 Starting SWI-Prolog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.1.2 Executing a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.2 The users initialisation file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.3 Initialisation files and goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.4 Command line options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.4.1 Informational command line options . . . . . . . . . . . . . . . . . . . . . . 19
2.4.2 Command line options for running Prolog . . . . . . . . . . . . . . . . . . . 19
2.4.3 Controlling the stack sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.4.4 Running goals from the command line . . . . . . . . . . . . . . . . . . . . . 22
2.4.5 Compilation options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.4.6 Maintenance options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.5 GNU Emacs Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.6 Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.7 Command line history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.8 Reuse of top-level bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.9 Overview of the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.10 Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.10.1 During program development . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.10.2 For running the result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.11 Environment Control (Prolog flags) . . . . . . . . . . . . . . . . . . . . . . . . . . 32
2.12 An overview of hook predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
2.13 Automatic loading of libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
2.14 Garbage Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
2.15 The SWI-Prolog syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
2.15.1 ISO Syntax Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
2.16 Rational trees (cyclic terms) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
2.17 Just-in-time clause indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
2.17.1 Future directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
2.17.2 Indexing and portability . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
2.18 Wide character support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

SWI-Prolog 7.4 Reference Manual

2

2.18.1 Wide character encodings on streams . . . . . . . . . . . . . . . . . . . . . 57

2.19 System limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
2.19.1 Limits on memory areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
2.19.2 Other Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
2.19.3 Reserved Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
2.20 SWI-Prolog and 64-bit machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
2.20.1 Supported platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
2.20.2 Comparing 32- and 64-bits Prolog . . . . . . . . . . . . . . . . . . . . . . . 62
2.20.3 Choosing between 32- and 64-bit Prolog . . . . . . . . . . . . . . . . . . . . 62

3 Initialising and Managing a Prolog Project 64

3.1 The project source files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3.1.1 File Names and Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3.1.2 Project Special Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
3.1.3 International source files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
3.2 Using modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
3.3 The test-edit-reload cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
3.3.1 Locating things to edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
3.3.2 Editing and incremental compilation . . . . . . . . . . . . . . . . . . . . . . 68
3.4 Using the PceEmacs built-in editor . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
3.4.1 Activating PceEmacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
3.4.2 Bluffing through PceEmacs . . . . . . . . . . . . . . . . . . . . . . . . . . 69
3.4.3 Prolog Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
3.5 The Graphical Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
3.5.1 Invoking the window-based debugger . . . . . . . . . . . . . . . . . . . . . 73
3.6 The Prolog Navigator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
3.7 Cross-referencer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
3.8 Accessing the IDE from your program . . . . . . . . . . . . . . . . . . . . . . . . . 76
3.9 Summary of the IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

4 Built-in Predicates 78
4.1 Notation of Predicate Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
4.2 Character representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
4.3 Loading Prolog source files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
4.3.1 Conditional compilation and program transformation . . . . . . . . . . . . . 90
4.3.2 Reloading files, active code and threads . . . . . . . . . . . . . . . . . . . . 94
4.3.3 Quick load files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
4.4 Editor Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
4.4.1 Customizing the editor interface . . . . . . . . . . . . . . . . . . . . . . . . 98
4.5 List the program, predicates or clauses . . . . . . . . . . . . . . . . . . . . . . . . . 99
4.6 Verify Type of a Term . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
4.7 Comparison and Unification of Terms . . . . . . . . . . . . . . . . . . . . . . . . . 102
4.7.1 Standard Order of Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
4.7.2 Special unification and comparison predicates . . . . . . . . . . . . . . . . . 103
4.8 Control Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
4.9 Meta-Call Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
4.10 Delimited continuations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

SWI-Prolog 7.4 Reference Manual

Contents 3

4.11 Exception handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

4.11.1 Debugging and exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
4.11.2 The exception term . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
4.11.3 Printing messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
4.12 Handling signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
4.12.1 Notes on signal handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
4.13 DCG Grammar rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
4.14 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
4.14.1 Managing (dynamic) predicates . . . . . . . . . . . . . . . . . . . . . . . . 123
4.14.2 The recorded database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
4.14.3 Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
4.14.4 Tries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
4.14.5 Update view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
4.14.6 Indexing databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
4.15 Declaring predicate properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
4.16 Examining the program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
4.17 Input and output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
4.17.1 Predefined stream aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
4.17.2 ISO Input and Output Streams . . . . . . . . . . . . . . . . . . . . . . . . . 136
4.17.3 Edinburgh-style I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
4.17.4 Switching between Edinburgh and ISO I/O . . . . . . . . . . . . . . . . . . 146
4.17.5 Write onto atoms, code-lists, etc. . . . . . . . . . . . . . . . . . . . . . . . . 146
4.17.6 Fast binary term I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
4.18 Status of streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
4.19 Primitive character I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
4.20 Term reading and writing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
4.21 Analysing and Constructing Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
4.21.1 Non-logical operations on terms . . . . . . . . . . . . . . . . . . . . . . . . 163
4.22 Analysing and Constructing Atoms . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
4.23 Localization (locale) support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
4.24 Character properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
4.24.1 Case conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
4.24.2 White space normalization . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
4.24.3 Language-specific comparison . . . . . . . . . . . . . . . . . . . . . . . . . 172
4.25 Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
4.26 Character Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
4.27 Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
4.27.1 Special purpose integer arithmetic . . . . . . . . . . . . . . . . . . . . . . . 175
4.27.2 General purpose arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
4.28 Misc arithmetic support predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
4.29 Built-in list operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
4.30 Finding all Solutions to a Goal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
4.31 Forall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
4.32 Formatted Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
4.32.1 Writef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
4.32.2 Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
4.32.3 Programming Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

SWI-Prolog 7.4 Reference Manual

4

4.33 Global variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

4.33.1 Compatibility of SWI-Prolog Global Variables . . . . . . . . . . . . . . . . 198
4.34 Terminal Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
4.35 Operating System Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
4.35.1 Windows-specific Operating System Interaction . . . . . . . . . . . . . . . . 201
4.35.2 Dealing with time and date . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
4.35.3 Controlling the swipl-win.exe console window . . . . . . . . . . . . . 208
4.36 File System Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
4.37 User Top-level Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
4.38 Creating a Protocol of the User Interaction . . . . . . . . . . . . . . . . . . . . . . . 215
4.39 Debugging and Tracing Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
4.40 Obtaining Runtime Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
4.41 Execution profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
4.41.1 Profiling predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
4.41.2 Visualizing profiling data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
4.41.3 Information gathering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
4.42 Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
4.43 Windows DDE interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
4.43.1 DDE client interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
4.43.2 DDE server mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
4.44 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

5 SWI-Prolog extensions 229

5.1 Lists are special . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
5.1.1 Motivating [|] and [] for lists . . . . . . . . . . . . . . . . . . . . . . . 230
5.2 The string type and its double quoted syntax . . . . . . . . . . . . . . . . . . . . . . 230
5.2.1 Predicates that operate on strings . . . . . . . . . . . . . . . . . . . . . . . . 231
5.2.2 Representing text: strings, atoms and code lists . . . . . . . . . . . . . . . . 234
5.2.3 Adapting code for double quoted strings . . . . . . . . . . . . . . . . . . . . 235
5.2.4 Why has the representation of double quoted text changed? . . . . . . . . . . 236
5.3 Syntax changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
5.3.1 Operators and quoted atoms . . . . . . . . . . . . . . . . . . . . . . . . . . 238
5.3.2 Compound terms with zero arguments . . . . . . . . . . . . . . . . . . . . . 238
5.3.3 Block operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
5.4 Dicts: structures with named arguments . . . . . . . . . . . . . . . . . . . . . . . . 240
5.4.1 Functions on dicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
5.4.2 Predicates for managing dicts . . . . . . . . . . . . . . . . . . . . . . . . . 243
5.4.3 When to use dicts? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
5.4.4 A motivation for dicts as primary citizens . . . . . . . . . . . . . . . . . . . 248
5.4.5 Implementation notes about dicts . . . . . . . . . . . . . . . . . . . . . . . 248
5.5 Integration of strings and dicts in the libraries . . . . . . . . . . . . . . . . . . . . . 248
5.5.1 Dicts and option processing . . . . . . . . . . . . . . . . . . . . . . . . . . 249
5.5.2 Dicts in core data structures . . . . . . . . . . . . . . . . . . . . . . . . . . 249
5.5.3 Dicts, strings and XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
5.5.4 Dicts, strings and JSON . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
5.5.5 Dicts, strings and HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
5.6 Remaining issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

SWI-Prolog 7.4 Reference Manual

Contents 5

6 Modules 251
6.1 Why Use Modules? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
6.2 Defining a Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
6.3 Importing Predicates into a Module . . . . . . . . . . . . . . . . . . . . . . . . . . 252
6.4 Defining a meta-predicate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
6.5 Overruling Module Boundaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
6.5.1 Explicit manipulation of the calling context . . . . . . . . . . . . . . . . . . 256
6.6 Interacting with modules from the top level . . . . . . . . . . . . . . . . . . . . . . 257
6.7 Composing modules from other modules . . . . . . . . . . . . . . . . . . . . . . . . 257
6.8 Operators and modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
6.9 Dynamic importing using import modules . . . . . . . . . . . . . . . . . . . . . . . 258
6.10 Reserved Modules and using the user module . . . . . . . . . . . . . . . . . . . . 259
6.11 An alternative import/export interface . . . . . . . . . . . . . . . . . . . . . . . . . 259
6.12 Dynamic Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
6.13 Transparent predicates: definition and context module . . . . . . . . . . . . . . . . . 260
6.14 Module properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
6.15 Compatibility of the Module System . . . . . . . . . . . . . . . . . . . . . . . . . . 263

7 Constraint Logic Programming 265

7.1 Attributed variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
7.1.1 Attribute manipulation predicates . . . . . . . . . . . . . . . . . . . . . . . 268
7.1.2 Attributed variable hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
7.1.3 Operations on terms with attributed variables . . . . . . . . . . . . . . . . . 269
7.1.4 Special purpose predicates for attributes . . . . . . . . . . . . . . . . . . . . 270
7.2 Coroutining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

8 CHR: Constraint Handling Rules 273

8.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
8.2 Syntax and Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
8.2.1 Syntax of CHR rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
8.2.2 Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
8.3 CHR in SWI-Prolog Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
8.3.1 Embedding in Prolog Programs . . . . . . . . . . . . . . . . . . . . . . . . 276
8.3.2 Constraint declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
8.3.3 Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
8.4 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
8.4.1 Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
8.4.2 Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
8.4.3 CHR Debugging Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . 282
8.5 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
8.6 Backwards Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
8.6.1 The Old SICStus CHR implemenation . . . . . . . . . . . . . . . . . . . . . 284
8.6.2 The Old ECLiPSe CHR implemenation . . . . . . . . . . . . . . . . . . . . 285
8.7 Programming Tips and Tricks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
8.8 Compiler Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
8.8.1 CHR Compiler Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

SWI-Prolog 7.4 Reference Manual

6

9 Multithreaded applications 288

9.1 Creating and destroying Prolog threads . . . . . . . . . . . . . . . . . . . . . . . . . 288
9.2 Monitoring threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
9.3 Thread communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
9.3.1 Message queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
9.3.2 Signalling threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
9.3.3 Threads and dynamic predicates . . . . . . . . . . . . . . . . . . . . . . . . 298
9.4 Thread synchronisation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
9.5 Thread support library(threadutil) . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
9.5.1 Debugging threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
9.5.2 Profiling threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
9.6 Multithreaded mixed C and Prolog applications . . . . . . . . . . . . . . . . . . . . 302
9.6.1 A Prolog thread for each native thread (one-to-one) . . . . . . . . . . . . . . 302
9.6.2 Pooling Prolog engines (many-to-many) . . . . . . . . . . . . . . . . . . . . 303
9.7 Multithreading and the XPCE graphics system . . . . . . . . . . . . . . . . . . . . . 304

10 Coroutining using Prolog engines 306

10.1 Examples using engines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
10.1.1 Aggregation using engines . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
10.1.2 State accumulation using engines . . . . . . . . . . . . . . . . . . . . . . . 308
10.1.3 Scalable many-agent applications . . . . . . . . . . . . . . . . . . . . . . . 310
10.2 Engine resource usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
10.3 Engine predicate reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

11 Foreign Language Interface 313

11.1 Overview of the Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
11.2 Linking Foreign Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
11.2.1 What linking is provided? . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
11.2.2 What kind of loading should I be using? . . . . . . . . . . . . . . . . . . . . 314
11.2.3 library(shlib): Utility library for loading foreign objects (DLLs, shared objects) 314
11.2.4 Low-level operations on shared libraries . . . . . . . . . . . . . . . . . . . . 316
11.2.5 Static Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
11.3 Interface Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
11.3.1 Type term t: a reference to a Prolog term . . . . . . . . . . . . . . . . . . 318
11.3.2 Other foreign interface types . . . . . . . . . . . . . . . . . . . . . . . . . . 320
11.4 The Foreign Include File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
11.4.1 Argument Passing and Control . . . . . . . . . . . . . . . . . . . . . . . . . 321
11.4.2 Atoms and functors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
11.4.3 Analysing Terms via the Foreign Interface . . . . . . . . . . . . . . . . . . . 325
11.4.4 Constructing Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
11.4.5 Unifying data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
11.4.6 Convenient functions to generate Prolog exceptions . . . . . . . . . . . . . . 342
11.4.7 BLOBS: Using atoms to store arbitrary binary data . . . . . . . . . . . . . . 344
11.4.8 Exchanging GMP numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
11.4.9 Calling Prolog from C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
11.4.10 Discarding Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
11.4.11 Foreign Code and Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

SWI-Prolog 7.4 Reference Manual

Contents 7

11.4.12 Prolog exceptions in foreign code . . . . . . . . . . . . . . . . . . . . . . . 352

11.4.13 Catching Signals (Software Interrupts) . . . . . . . . . . . . . . . . . . . . . 354
11.4.14 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
11.4.15 Errors and warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
11.4.16 Environment Control from Foreign Code . . . . . . . . . . . . . . . . . . . 359
11.4.17 Querying Prolog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
11.4.18 Registering Foreign Predicates . . . . . . . . . . . . . . . . . . . . . . . . . 360
11.4.19 Foreign Code Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
11.4.20 Storing foreign data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
11.4.21 Embedding SWI-Prolog in other applications . . . . . . . . . . . . . . . . . 367
11.5 Linking embedded applications using swipl-ld . . . . . . . . . . . . . . . . . . . . . 371
11.5.1 A simple example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
11.6 The Prolog home directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
11.7 Example of Using the Foreign Interface . . . . . . . . . . . . . . . . . . . . . . . . 375
11.8 Notes on Using Foreign Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
11.8.1 Foreign debugging functions . . . . . . . . . . . . . . . . . . . . . . . . . . 378
11.8.2 Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
11.8.3 Compatibility between Prolog versions . . . . . . . . . . . . . . . . . . . . 380
11.8.4 Debugging and profiling foreign code (valgrind) . . . . . . . . . . . . . . . 380
11.8.5 Name Conflicts in C modules . . . . . . . . . . . . . . . . . . . . . . . . . 381
11.8.6 Compatibility of the Foreign Interface . . . . . . . . . . . . . . . . . . . . . 381

12 Generating Runtime Applications 382

12.1 Limitations of qsave program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
12.2 Runtimes and Foreign Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
12.3 Using program resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
12.3.1 Resource manipulation predicates . . . . . . . . . . . . . . . . . . . . . . . 386
12.3.2 The swipl-rc program . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
12.4 Finding Application files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
12.4.1 Specifying a file search path from the command line . . . . . . . . . . . . . 388

A The SWI-Prolog library 389

A.1 library(aggregate): Aggregation operators on backtrackable predicates . . . . . . . . 389
A.2 library(apply): Apply predicates on a list . . . . . . . . . . . . . . . . . . . . . . . . 392
A.3 library(assoc): Association lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
A.3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
A.3.2 Creating association lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
A.3.3 Querying association lists . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
A.3.4 Modifying association lists . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
A.3.5 Conversion predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
A.3.6 Reasoning about association lists and their elements . . . . . . . . . . . . . 395
A.4 library(broadcast): Broadcast and receive event notifications . . . . . . . . . . . . . 396
A.5 library(charsio): I/O on Lists of Character Codes . . . . . . . . . . . . . . . . . . . 398
A.6 library(check): Consistency checking . . . . . . . . . . . . . . . . . . . . . . . . . 399
A.7 library(clpb): CLP(B): Constraint Logic Programming over Boolean Variables . . . . 401
A.7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
A.7.2 Boolean expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401

SWI-Prolog 7.4 Reference Manual

8

A.7.3 Interface predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

A.7.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
A.7.5 Obtaining BDDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
A.7.6 Enabling monotonic CLP(B) . . . . . . . . . . . . . . . . . . . . . . . . . . 404
A.7.7 Example: Pigeons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
A.7.8 Example: Boolean circuit . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
A.7.9 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
A.7.10 CLP(B) predicate index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
A.8 library(clpfd): CLP(FD): Constraint Logic Programming over Finite Domains . . . . 407
A.8.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
A.8.2 Arithmetic constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
A.8.3 Declarative integer arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . 409
A.8.4 Example: Factorial relation . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
A.8.5 Combinatorial constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
A.8.6 Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
A.8.7 Example: Sudoku . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
A.8.8 Residual goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
A.8.9 Core relations and search . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
A.8.10 Example: Eight queens puzzle . . . . . . . . . . . . . . . . . . . . . . . . . 415
A.8.11 Optimisation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
A.8.12 Reification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
A.8.13 Enabling monotonic CLP(FD) . . . . . . . . . . . . . . . . . . . . . . . . . 417
A.8.14 Custom constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
A.8.15 Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
A.8.16 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
A.8.17 CLP(FD) predicate index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
A.8.18 Closing and opening words about CLP(FD) . . . . . . . . . . . . . . . . . . 430
A.9 library(clpqr): Constraint Logic Programming over Rationals and Reals . . . . . . . 431
A.9.1 Solver predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
A.9.2 Syntax of the predicate arguments . . . . . . . . . . . . . . . . . . . . . . . 432
A.9.3 Use of unification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
A.9.4 Non-linear constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
A.9.5 Status and known problems . . . . . . . . . . . . . . . . . . . . . . . . . . 434
A.10 library(csv): Process CSV (Comma-Separated Values) data . . . . . . . . . . . . . . 435
A.11 library(debug): Print debug messages and test assertions . . . . . . . . . . . . . . . 436
A.12 library(error): Error generating support . . . . . . . . . . . . . . . . . . . . . . . . . 438
A.13 library(gensym): Generate unique identifiers . . . . . . . . . . . . . . . . . . . . . . 440
A.14 library(iostream): Utilities to deal with streams . . . . . . . . . . . . . . . . . . . . 441
A.15 library(lists): List Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
A.16 library(nb set): Non-backtrackable set . . . . . . . . . . . . . . . . . . . . . . . . . 447
A.17 library(www browser): Activating your Web-browser . . . . . . . . . . . . . . . . . 448
A.18 library(option): Option list processing . . . . . . . . . . . . . . . . . . . . . . . . . 448
A.19 library(optparse): command line parsing . . . . . . . . . . . . . . . . . . . . . . . . 450
A.19.1 Notes and tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
A.20 library(ordsets): Ordered set manipulation . . . . . . . . . . . . . . . . . . . . . . . 457
A.21 library(pairs): Operations on key-value lists . . . . . . . . . . . . . . . . . . . . . . 459
A.22 library(persistency): Provide persistent dynamic predicates . . . . . . . . . . . . . . 460

SWI-Prolog 7.4 Reference Manual

Contents 9

A.23 library(pio): Pure I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463

A.23.1 library(pure input): Pure Input from files and streams . . . . . . . . . . . . . 463
A.24 library(predicate options): Declare option-processing of predicates . . . . . . . . . . 465
A.24.1 The strength and weakness of predicate options . . . . . . . . . . . . . . . . 465
A.24.2 Options as arguments or environment? . . . . . . . . . . . . . . . . . . . . . 466
A.24.3 Improving on the current situation . . . . . . . . . . . . . . . . . . . . . . . 466
A.25 library(prolog pack): A package manager for Prolog . . . . . . . . . . . . . . . . . 469
A.26 library(prolog xref): Cross-reference data collection library . . . . . . . . . . . . . . 472
A.26.1 Extending the library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
A.27 library(quasi quotations): Define Quasi Quotation syntax . . . . . . . . . . . . . . . 473
A.28 library(random): Random numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . 475
A.29 library(readutil): Reading lines, streams and files . . . . . . . . . . . . . . . . . . . 477
A.30 library(record): Access named fields in a term . . . . . . . . . . . . . . . . . . . . . 478
A.31 library(registry): Manipulating the Windows registry . . . . . . . . . . . . . . . . . 479
A.32 library(simplex): Solve linear programming problems . . . . . . . . . . . . . . . . . 481
A.32.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
A.32.2 Delayed column generation . . . . . . . . . . . . . . . . . . . . . . . . . . 482
A.32.3 Solving LPs with special structure . . . . . . . . . . . . . . . . . . . . . . . 482
A.32.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
A.33 library(solution sequences): Modify solution sequences . . . . . . . . . . . . . . . . 485
A.34 library(tabling): Tabled execution (SLG) . . . . . . . . . . . . . . . . . . . . . . . . 487
A.34.1 Tabling predicate reference . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
A.35 library(thread pool): Resource bounded thread management . . . . . . . . . . . . . 491
A.36 library(ugraphs): Unweighted Graphs . . . . . . . . . . . . . . . . . . . . . . . . . 493
A.37 library(url): Analysing and constructing URL . . . . . . . . . . . . . . . . . . . . . 496
A.38 library(varnumbers): Utilities for numbered terms . . . . . . . . . . . . . . . . . . . 499
A.39 library(yall): Lambda expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . 500

B Hackers corner 503

B.1 Examining the Environment Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
B.2 Ancestral cuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
B.3 Intercepting the Tracer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
B.4 Breakpoint and watchpoint handling . . . . . . . . . . . . . . . . . . . . . . . . . . 507
B.5 Adding context to errors: prolog exception hook . . . . . . . . . . . . . . . . . . . 509
B.6 Hooks using the exception predicate . . . . . . . . . . . . . . . . . . . . . . . . . . 509
B.7 Hooks for integrating libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
B.8 Hooks for loading files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511

C Compatibility with other Prolog dialects 512

C.1 Some considerations for writing portable code . . . . . . . . . . . . . . . . . . . . . 513

D Glossary of Terms 516

E SWI-Prolog License Conditions and Tools 522

E.1 Contributing to the SWI-Prolog project . . . . . . . . . . . . . . . . . . . . . . . . 523
E.2 Software support to keep track of license conditions . . . . . . . . . . . . . . . . . . 523
E.3 License conditions inherited from used code . . . . . . . . . . . . . . . . . . . . . . 524

SWI-Prolog 7.4 Reference Manual

10

E.3.1 Cryptographic routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524

F Summary 525
F.1 Predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
F.2 Library predicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
F.2.1 library(aggregate) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
F.2.2 library(apply) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
F.2.3 library(assoc) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
F.2.4 library(broadcast) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
F.2.5 library(charsio) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
F.2.6 library(check) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
F.2.7 library(clpb) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
F.2.8 library(clpfd) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
F.2.9 library(clpqr) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544
F.2.10 library(csv) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544
F.2.11 library(debug) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544
F.2.12 library(error) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544
F.2.13 library(iostream) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
F.2.14 library(summaries.d/iostream/tex) . . . . . . . . . . . . . . . . . . . . . . . 545
F.2.15 library(lists) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
F.2.16 library(option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
F.2.17 library(optparse) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
F.2.18 library(ordsets) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
F.2.19 library(persistency) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
F.2.20 library(predicate options) . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
F.2.21 library(prologpack) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
F.2.22 library(prologxref) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
F.2.23 library(pairs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548
F.2.24 library(pio) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548
F.2.25 library(random) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548
F.2.26 library(readutil) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548
F.2.27 library(record) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
F.2.28 library(registry) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
F.2.29 library(simplex) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
F.2.30 library(ugraphs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549
F.2.31 library(url) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
F.2.32 library(www browser) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
F.2.33 library(solution sequences) . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
F.2.34 library(thread pool) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
F.2.35 library(varnumbers) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
F.2.36 library(yall) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
F.3 Arithmetic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
F.4 Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554

SWI-Prolog 7.4 Reference Manual

Introduction
This document is a reference manual. That means that it documents the system, but it does not
1
explain the basics of the Prolog language and it leaves many details of the syntax, semantics and built-
in primitives undefined where SWI-Prolog follows the standards. This manual is intended for people
that are familiar with Prolog. For those not familiar with Prolog, we recommend to start with a Prolog
textbook such as [Bratko, 1986], [Sterling & Shapiro, 1986] or [Clocksin & Melish, 1987]. For more
advanced Prolog usage we recommend [OKeefe, 1990].

1.1 Positioning SWI-Prolog

Most implementations of the Prolog language are designed to serve a limited set of use cases. SWI-
Prolog is no exception to this rule. SWI-Prolog positions itself primarily as a Prolog environment for
programming in the large and use cases where it plays a central role in an application, i.e., where
it acts as glue between components. At the same time, SWI-Prolog aims at providing a productive
rapid prototyping environment. Its orientation towards programming in the large is backed up by scal-
ability, compiler speed, program structuring (modules), support for multithreading to accommodate
servers, Unicode and interfaces to a large number of document formats, protocols and programming
languages. Prototyping is facilitated by good development tools, both for command line usage as for
usage with graphical development tools. Demand loading of predicates from the library and a make
facility avoids the requirement for using declarations and reduces typing.
SWI-Prolog is traditionally strong in education because it is free and portable, but also because of
its compatibility with textbooks and its easy-to-use environment.
Note that these positions do not imply that the system cannot be used with other scenarios. SWI-
Prolog is used as an embedded language where it serves as a small rule subsystem in a large applica-
tion. It is also used as a deductive database. In some cases this is the right choice because SWI-Prolog
has features that are required in the application, such as threading or Unicode support. In general
though, for example, GNU-Prolog is more suited for embedding because it is small and can com-
pile to native code, XSB is better for deductive databases because it provides advanced resolution
techniques (tabling), and ECLiPSe is better at constraint handling.
The syntax and set of built-in predicates is based on the ISO standard [Hodgson, 1998]. Most
extensions follow the Edinburgh tradition (DEC10 Prolog and C-Prolog) and Quintus Prolog
[Qui, 1997]. The infrastructure for constraint programming is based on hProlog [Demoen, 2002].
Some libraries are copied from the YAP1 system. Together with YAP we developed a portability
framework (see section C). This framework has been filled for SICStus Prolog, YAP, IF/Prolog and
Ciao. SWI-Prolog version 7 introduces various extensions to the Prolog language (see section 5). The
string data type and its supporting set of built-in predicates is compatibility with ECLiPSe.
1
http://www.dcc.fc.up.pt/{}vsc/Yap/

SWI-Prolog 7.4 Reference Manual

12 CHAPTER 1. INTRODUCTION

1.2 Status and releases

This manual describes version 7.4 of SWI-Prolog. SWI-Prolog is widely considered to be a robust
and scalable implementation of the Prolog language. It is widely used in education and research.
In addition, it is in use for 24 7 mission critical commercial server processes. The site http:
//www.swi-prolog.org is hosted using the SWI-Prolog HTTP server infrastructure. It receives
approximately 2.3 million hits and serves approximately 300 Gbytes on manual data and downloads
each month. SWI-Prolog applications range from student assignments to commercial applications
that count more than one million lines of Prolog code.
SWI-Prolog has two development tracks. Stable releases have an even minor version number
(e.g., 6.2.1) and are released as a branch from the development version when the development version
is considered stable and there is sufficient new functionality to justify a stable release. Stable releases
often get a few patch updates to deal with installation issues or major flaws. A new Development
version is typically released every couple of weeks as a snapshot of the public git repository. Extra
editions of the development version may be released after problems that severely hindered the user
in their progress have been fixed.
Known bugs that are not likely to be fixed soon are described as footnotes in this manual.

1.3 Should I be using SWI-Prolog?

There are a number of reasons why it might be better to choose a commercial, or another free, Prolog
system:

SWI-Prolog comes with no warranties

Although the developers or the community often provide a work-around or a fix for a bug, there
is no place you can go to for guaranteed support. However, the full source archive is available
and can be used to compile and debug SWI-Prolog using free tools on all major platforms.
Users requiring more support should ensure access to knowledgeable developers.

Performance is your first concern

Various free and commercial systems have better performance. But, standard Prolog bench-
marks disregard many factors that are often critical to the performance of large applications.
SWI-Prolog is not good at fast calling of simple predicates and if-then-else selection based on
simple built-in tests, but it is fast with dynamic code, meta-calling and predicates that contain
large numbers of clauses. Many of SWI-Prologs built-in predicates are written in C and have
excellent performance.

You need features not offered by SWI-Prolog

Although SWI-Prolog has many features, it also lacks some important features. The most well
known is probably tabling [Freire et al., 1997]. If you require additional features and you have
resources, be it financial or expertise, please contact the developers.

On the other hand, SWI-Prolog offers some facilities that are widely appreciated by users:

Nice environment
SWI-Prolog provides a good command line environment, including Do What I Mean, auto-
completion, history and a tracer that operates on single key strokes. The system automatically
recompiles modified parts of the source code using the make/0 command. The system can

SWI-Prolog 7.4 Reference Manual

1.4. SUPPORT THE SWI-PROLOG PROJECT 13

be instructed to open an arbitrary editor on the right file and line based on its source database.
It ships with various graphical tools and can be combined with the SWI-Prolog editor, PDT
(Eclipse plugin for Prolog) or GNU-Emacs.

Fast compiler
Even very large applications can be loaded in seconds on most machines. If this is not enough,
there is the Quick Load Format. See qcompile/1 and qsave program/2.

Transparent compiled code

SWI-Prolog compiled code can be treated just as interpreted code: you can list it, trace it, etc.
This implies you do not have to decide beforehand whether a module should be loaded for
debugging or not, and the performance of debugged code is close to that of normal operation.

Source level debugger

The source level debugger provides a good overview of your current location in the search tree,
variable bindings, your source code and open choice points. Choice point inspection provides
meaningful insight to both novices and experienced users. Avoiding unintended choice points
often provides a huge increase in performance and a huge saving in memory usage.

Profiling
SWI-Prolog offers an execution profiler with either textual output or graphical output. Finding
and improving hotspots in a Prolog program may result in huge speedups.

Flexibility
SWI-Prolog can easily be integrated with C, supporting non-determinism in Prolog calling C
as well as C calling Prolog (see section 11). It can also be embedded in external programs (see
section 11.5). System predicates can be redefined locally to provide compatibility with other
Prolog systems.

Threads
Robust support for multiple threads may improve performance and is a key enabling factor for
deploying Prolog in server applications.

Interfaces
SWI-Prolog ships with many extension packages that provide robust interfaces to processes,
encryption, TCP/IP, TIPC, ODBC, SGML/XML/HTML, RDF, HTTP, graphics and much more.

1.4 Support the SWI-Prolog project

You can support the SWI-Prolog project in several ways. Academics are invited to cite one of the
publications2 on SWI-Prolog. Users can help by identifying and/or fixing problems with the code or
its documentation.3 . Users can contribute new features or, more lightweight, contribute packs4 . Com-
mercial users may consider contacting the developers5 to sponsor the development of new features or
seek for opportunities to cooperate with the developers or other commercial users.
2
http://www.swi-prolog.org/Publications.html
3
http://www.swi-prolog.org/howto/SubmitPatch.html
4
http://www.swi-prolog.org/pack/list
5
mailto:[email protected]

SWI-Prolog 7.4 Reference Manual

14 CHAPTER 1. INTRODUCTION

1.5 Implementation history

SWI-Prolog started back in 1986 with the requirement for a Prolog that could handle recursive inter-
action with the C-language: Prolog calling C and C calling Prolog recursively. In those days Prolog
systems were not very aware of their environment and we needed such a system to support interactive
applications. Since then, SWI-Prologs development has been guided by requests from the user com-
munity, especially focussing on (in arbitrary order) interaction with the environment, scalability, (I/O)
performance, standard compliance, teaching and the program development environment.
SWI-Prolog is based on a simple Prolog virtual machine called ZIP [Bowen et al., 1983,
Neumerkel, 1993] which defines only 7 instructions. Prolog can easily be compiled into this lan-
guage, and the abstract machine code is easily decompiled back into Prolog. As it is also possible
to wire a standard 4-port debugger in the virtual machine, there is no need for a distinction between
compiled and interpreted code. Besides simplifying the design of the Prolog system itself, this ap-
proach has advantages for program development: the compiler is simple and fast, the user does not
have to decide in advance whether debugging is required, and the system only runs slightly slower in
debug mode compared to normal execution. The price we have to pay is some performance degra-
dation (taking out the debugger from the VM interpreter improves performance by about 20%) and
somewhat additional memory usage to help the decompiler and debugger.
SWI-Prolog extends the minimal set of instructions described in [Bowen et al., 1983] to improve
performance. While extending this set, care has been taken to maintain the advantages of decompi-
lation and tracing of compiled code. The extensions include specialised instructions for unification,
predicate invocation, some frequently used built-in predicates, arithmetic, and control (;/2, |/2),
if-then (->/2) and negation-by-failure (\+/1).

1.6 Acknowledgements
Some small parts of the Prolog code of SWI-Prolog are modified versions of the corresponding Edin-
burgh C-Prolog code: grammar rule compilation and writef/2. Also some of the C-code originates
from C-Prolog: finding the path of the currently running executable and some of the code underlying
absolute file name/2. Ideas on programming style and techniques originate from C-Prolog
and Richard OKeefes thief editor. An important source of inspiration are the programming tech-
niques introduced by Anjo Anjewierden in PCE version 1 and 2.
Our special thanks go to those who had the fate of using the early versions of this system, sug-
gested extensions or reported bugs. Among them are Anjo Anjewierden, Huub Knops, Bob Wielinga,
Wouter Jansweijer, Luc Peerdeman, Eric Nombden, Frank van Harmelen, Bert Rengel.
Martin Jansche ([email protected]) has been so kind to reor-
ganise the sources for version 2.1.3 of this manual. Horst von Brand has been so kind to fix many
typos in the 2.7.14 manual. Thanks! Randy Sharp fixed many issues in the 6.0.x version of the manual.
Bart Demoen and Tom Schrijvers have helped me adding coroutining, constraints, global variables
and support for cyclic terms to the kernel. Tom Schrijvers has provided a first clp(fd) constraint solver,
the CHR compiler and some of the coroutining predicates. Markus Triska contributed the current
clp(fd) implementation.
Paul Singleton has integrated Fred Dushins Java-calls-Prolog side with his Prolog-calls-Java side
into the current bidirectional JPL interface package.
Richard OKeefe is gratefully acknowledged for his efforts to educate beginners as well as valu-
able comments on proposed new developments.

SWI-Prolog 7.4 Reference Manual

1.6. ACKNOWLEDGEMENTS 15

Scientific Software and Systems Limited, www.sss.co.nz has sponsored the development of
the SSL library, unbounded integer and rational number arithmetic and many enhancements to the
memory management of the system.
Leslie de Koninck has made clp(QR) available to SWI-Prolog.
Jeff Rosenwald contributed the TIPC networking library and Googles protocol buffer handling.
Paulo Mouras great experience in maintaining Logtalk for many Prolog systems including SWI-
Prolog has helped in many places fixing compatibility issues. He also worked on the MacOS port and
fixed many typos in the 5.6.9 release of the documentation.

SWI-Prolog 7.4 Reference Manual

Overview
2.1 Getting started quickly
2
2.1.1 Starting SWI-Prolog
Starting SWI-Prolog on Unix
By default, SWI-Prolog is installed as swipl. The command line arguments of SWI-Prolog itself
and its utility programs are documented using standard Unix man pages. SWI-Prolog is normally
operated as an interactive application simply by starting the program:

machine% swipl
Welcome to SWI-Prolog ...
...

1 ?-

After starting Prolog, one normally loads a program into it using consult/1, which may be abbre-
viated by putting the name of the program file between square brackets. The following goal loads the
file likes.pl containing clauses for the predicates likes/2:

?- [likes].
% likes compiled, 0.00 sec, 17 clauses
true.

?-

After this point, Unix and Windows users unite, so if you are using Unix please continue at sec-
tion 2.1.2.

Starting SWI-Prolog on Windows

After SWI-Prolog has been installed on a Windows system, the following important new things are
available to the user:

A folder (called directory in the remainder of this document) called swipl containing the
executables, libraries, etc., of the system. No files are installed outside this directory.

A program swipl-win.exe, providing a window for interaction with Prolog. The program
swipl.exe is a version of SWI-Prolog that runs in a console window.

SWI-Prolog 7.4 Reference Manual

2.2. THE USERS INITIALISATION FILE 17

The file extension .pl is associated with the program swipl-win.exe. Opening a .pl
file will cause swipl-win.exe to start, change directory to the directory in which the file to
open resides, and load this file.

The normal way to start the likes.pl file mentioned in section 2.1.1 is by simply double-
clicking this file in the Windows explorer.

2.1.2 Executing a query

After loading a program, one can ask Prolog queries about the program. The query below asks Prolog
what food sam likes. The system responds with X = hvaluei if it can prove the goal for a certain
X. The user can type the semi-colon (;) or spacebar1 if (s)he wants another solution. Use the RETURN
key if you do not want to see the more answers. Prolog completes the output with a full stop (.) if
the user uses the RETURN key or Prolog knows there are no more answers. If Prolog cannot find
(more) answers, it writes false. Finally, Prolog answers using an error message to indicate the query
or program contains an error.

?- likes(sam, X).
X = dahl ;
X = tandoori ;
...
X = chips.

?-

Note that the answer written by Prolog is a valid Prolog program that, when executed, produces the
same set of answers as the original program.2

2.2 The users initialisation file

After the system initialisation, the system consults (see consult/1) the users startup file. The base-
name of this file follows conventions of the operating system. On MS-Windows, it is the file swipl.
ini and on Unix systems .swiplrc. The file is searched using the file search path/2
clauses for user profile.3 The table below shows the default value for this search path. The
phrase happdatai refers to the Windows CSIDL name for the folder. The actual name depends on the
Windows language. English versions typically use ApplicationData. See also win folder/2

Unix Windows
home happdatai/SWI-Prolog

After the first startup file is found it is loaded and Prolog stops looking for further startup files. The
name of the startup file can be changed with the -f file option. If File denotes an absolute path,
1
On most installations, single-character commands are executed without waiting for the RETURN key.
2
The SWI-Prolog top level differs in several ways from traditional Prolog top level. The current top level was designed
in cooperation with Ulrich Neumerkel.
3
Older versions first searched in the current working directory. This feature has been removed for security reasons.
Users can implement loading a setup file from the working directory in their global preference file.

SWI-Prolog 7.4 Reference Manual

18 CHAPTER 2. OVERVIEW

this file is loaded, otherwise the file is searched for using the same conventions as for the default
startup file. Finally, if file is none, no file is loaded.
The installation provides a file customize/dotswiplrc with (commented) commands that
are often used to customize the behaviour of Prolog, such as interfacing to the editor, color selection
or history parameters. Many of the development tools provide menu entries for editing the startup file
and starting a fresh startup file from the system skeleton.
See also the -s (script) and -F (system-wide initialisation) in section 2.4 and section 2.3.

2.3 Initialisation files and goals

Using command line arguments (see section 2.4), SWI-Prolog can be forced to load files and execute
queries for initialisation purposes or non-interactive operation. The most commonly used options
are -f file or -s file to make Prolog load a file, -g goal to define initialisation goals and
-t goal to define the top-level goal. The following is a typical example for starting an application
directly from the command line.

machine% swipl -s load.pl -g go -t halt

It tells SWI-Prolog to load load.pl, start the application using the entry point go/0 and instead
of entering the interactive top level exit after completing go/0.
The command line may have multiple -g goal occurrences. The goals are executed in order.
Possible choice points of individual goals are pruned. If a goal fails execution stops with exit status
1. If a goal raises an exception, the exception is printed and the process stops with exit code 2.
The -q may be used to suppress all informational messages as well as the error message that is
normally printed if an initialisation goal fails.
In MS-Windows, the same can be achieved using a short-cut with appropriately defined command
line arguments. A typically seen alternative is to write a file run.pl with content as illustrated below.
Double-clicking run.pl will start the application.

:- [load]. % load program

:- go. % run it
:- halt. % and exit

Section 2.10.2 discusses further scripting options, and chapter 12 discusses the generation of runtime
executables. Runtime executables are a means to deliver executables that do not require the Prolog
system.

2.4 Command line options

SWI-Prolog can be executed in one of the following modes:
swipl --help
swipl --version
swipl --arch
swipl --dump-runtime-variables
These options must appear as only option. They cause Prolog to print an informational message
and exit. See section 2.4.1.

SWI-Prolog 7.4 Reference Manual

2.4. COMMAND LINE OPTIONS 19

swipl [option ...] script-file [arg ...]

These arguments are passed on Unix systems if file that starts with
#!/path/to/executable [option ...] is executed. Arguments after the script file
are made available in the Prolog flag argv.

swipl [option ...] prolog-file ... [[--] arg ...]

This is the normal way to start Prolog. The options are described in section 2.4.2, section 2.4.3
and section 2.4.4. The Prolog flag argv provides access to arg ... If the options are followed
by one or more Prolog file names (i.e., names with extension .pl, .prolog or (on Windows)
the user preferred extension registered during installation), these files are loaded. The first file
is registered in the Prolog flag associated file. In addition, pl-win[.exe] switches
to the directory in which this primary source file is located using working directory/2.

swipl -o output -c prolog-file ...

The -c option is used to compile a set of Prolog files into an executable. See section 2.4.5.

swipl -o output -b bootfile prolog-file ...

Bootstrap compilation. See section 2.4.6.

2.4.1 Informational command line options

--arch
When given as the only option, it prints the architecture identifier (see Prolog flag arch) and
exits. See also -dump-runtime-variables. Also available as -arch.

--dump-runtime-variables [=format]
When given as the only option, it prints a sequence of variable settings that can be used in
shell scripts to deal with Prolog parameters. This feature is also used by swipl-ld (see
section 11.5). Below is a typical example of using this feature.

eval swipl --dump-runtime-variables

cc -I$PLBASE/include -L$PLBASE/lib/$PLARCH ...

The option can be followed by =sh to dump in POSIX shell format (default) or =cmd to dump
in MS-Windows cmd.exe compatible format.

--help
When given as the only option, it summarises the most important options. Also available as -h
and -help.

--version
When given as the only option, it summarises the version and the architecture identifier. Also
available as -v.

2.4.2 Command line options for running Prolog

--home=DIR
Use DIR as home directory. See section 11.6 for details.

SWI-Prolog 7.4 Reference Manual

20 CHAPTER 2. OVERVIEW

--quiet
Set the Prolog flag verbose to silent, suppressing informational and banner messages.
Also available as -q.

--nodebug
Disable debugging. See the current prolog flag/2 flag generate debug info for
details.

--nosignals
Inhibit any signal handling by Prolog, a property that is sometimes desirable for embedded
applications. This option sets the flag signals to false. See section 11.4.21 for details.

--pldoc [=port]
Start the PlDoc documentation system on a free network port and launch the users browser on
http://localhost:port. If port is specified, the server is started at the given port and the
browser is not launched.

-tty
Unix only. Switches controlling the terminal for allowing single-character commands to the
tracer and get single char/1. By default, manipulating the terminal is enabled unless
the system detects it is not connected to a terminal or it is running as a GNU-Emacs inferior
process. See also tty control.

--win app
This option is available only in swipl-win.exe and is used for the start-menu item. If
causes plwin to start in the folder ...\My Documents\Prolog or local equivalent
thereof (see win folder/2). The Prolog subdirectory is created if it does not exist.

-O
Optimised compilation. See current prolog flag/2 flag optimise for details.

-s file
Use file as a script file. The script file is loaded after the initialisation file specified with the
-f file option. Unlike -f file, using -s does not stop Prolog from loading the personal
initialisation file.

-f file
Use file as initialisation file instead of the default .swiplrc (Unix) or swipl.ini (Win-
dows). -f none stops SWI-Prolog from searching for a startup file. This option can be
used as an alternative to -s file that stops Prolog from loading the personal initialisation
file. See also section 2.2.

-F script
Select a startup script from the SWI-Prolog home directory. The script file is named
hscripti.rc. The default script name is deduced from the executable, taking the leading
alphanumerical characters (letters, digits and underscore) from the program name. -F none
stops looking for a script. Intended for simple management of slightly different versions. One
could, for example, write a script iso.rc and then select ISO compatibility mode using
pl -F iso or make a link from iso-pl to pl.

SWI-Prolog 7.4 Reference Manual

2.4. COMMAND LINE OPTIONS 21

-x bootfile
Boot from bootfile instead of the systems default boot file. A boot file is a file re-
sulting from a Prolog compilation using the -b or -c option or a program saved using
qsave program/[1,2].

-p alias=path1[:path2 . . . ]
Define a path alias for file search path. alias is the name of the alias, and argpath1 ... is a
list of values for the alias. On Windows the list separator is ;. On other systems it is :. A
value is either a term of the form alias(value) or pathname. The computed aliases are added to
file search path/2 using asserta/1, so they precede predefined values for the alias.
See file search path/2 for details on using this file location mechanism.

--traditional
This flag disables the most important extensions of SWI-Prolog version 7 (see section 5) that
introduce incompatibilities with earlier versions. In particular, lists are represented in the
traditional way, double quoted text is represented by a list of character codes and the functional
notation on dicts is not supported. Dicts as a syntactic entity, and the predicates that act on
them, are still supported if this flag is present.

--
Stops scanning for more arguments, so you can pass arguments for your application after this
one. See current prolog flag/2 using the flag argv for obtaining the command line
arguments.

2.4.3 Controlling the stack sizes

The default limit for the Prolog stacks is 128 MB on 32-bit and 256 MB on 64-bit hardware. The
128 MB limit on 32-bit systems is the highest possible value and the command line options can thus
only be used to lower the limit. On 64-bit systems, the limit can both be reduced and enlarged. See
section 2.19. Below are two examples, the first reducing the local stack limit to catch unbounded
recursion quickly and the second using a big (32 GB) global limit, which is only possible on 64-bit
hardware. Note that setting the limit using the command line only sets a soft limit. Stack parameters
can be changed (both reduced and enlarged) at any time using the predicate set prolog stack/2.

$ swipl -L8m
$ swipl -G32g

-Gsize[kmg]
Limit for the global stack (sometimes also called term stack or heap). This is where compound
terms and large numbers live.

-Lsize[kmg]
Limit for the local stack (sometimes also called environment stack). This is where environments
and choice points live.

-Tsize[kmg]
Limit for the trail stack. This is where we keep track of assignments, so we can rollback on
backtracking or exceptions.

SWI-Prolog 7.4 Reference Manual

22 CHAPTER 2. OVERVIEW

-Msize[kmg]
Limit for the table space. This is where tries holding memoized4 answers for tabling are
stored. The default is 1Gb on 64-bit machines and 512Mb on 32-bit machines. See the Prolog
flag table space

2.4.4 Running goals from the command line

-g goal
Goal is executed just before entering the top level. This option may appear multiple times. See
section 2.3 for details. If no initialization goal is present the system calls version/0 to print
the welcome message. The welcome message can be suppressed with --quiet, but also with
-g true. goal can be a complex term. In this case quotes are normally needed to protect
it from being expanded by the shell. A safe way to run a goal non-interactively is below. If
go/0/succeeds -g halt causes the process to stop with exit code 0. If it fails, the exit code
is 1 and it it raises an exception the exit code is 2.

% swipl <options> -g go -g halt

-t goal
Use goal as interactive top level instead of the default goal prolog/0. The goal can be a
complex term. If the top-level goal succeeds SWI-Prolog exits with status 0. If it fails the exit
status is 1. If the top level raises an exception, this is printed as an uncaught error and the
top level is restarted. This flag also determines the goal started by break/0 and abort/0.
If you want to prevent the user from entering interactive mode, start the application with
-g goal -t halt.

2.4.5 Compilation options

-c file . . .
Compile files into an intermediate code file. See section 2.10.

-o output
Used in combination with -c or -b to determine output file for compilation.

2.4.6 Maintenance options

The following options are for system maintenance. They are given for reference only.

-b initfile . . . -c file . . .
Boot compilation. initfile . . . are compiled by the C-written bootstrap compiler, file . . . by the
normal Prolog compiler. System maintenance only.

-d token1,token2,...
Print debug messages for DEBUG statements tagged with one of the indicated tokens. Only
has effect if the system is compiled with the -DO DEBUG flag. System maintenance only.
4
The letter M is used because the T was already in use. It is a memnonic for Memoizing.

SWI-Prolog 7.4 Reference Manual

2.5. GNU EMACS INTERFACE 23

2.5 GNU Emacs Interface

Unfortunately the default Prolog mode of GNU Emacs is not very good. There are several alternatives
though:

https://bruda.ca/emacs/prolog_mode_for_emacs
Prolog mode for Emacs and XEmacs maintained by Stefan Bruda.
https://www.metalevel.at/pceprolog/
Recommended configuration options for editing Prolog code with Emacs.
https://www.metalevel.at/ediprolog/
Interact with SWI-Prolog directly in Emacs buffers.
https://www.metalevel.at/etrace/
Trace Prolog code with Emacs.

2.6 Online Help

SWI-Prolog provides an online help system that covers this manual. If the XPCE graphics system is
available, online help opens a graphical window. Otherwise the documentation is shown in the Prolog
console. The help system is controlled by the predicates below. Note that this help system only covers
the core SWI-Prolog manual. The website5 provides an integrated manual that covers the core system
as well as all standard extension packages. It is possible to install the SWI-Prolog website locally by
cloning the website repository git://www.swi-prolog.org/home/pl/git/plweb.git
and following the instructions in the README file.

help
Equivalent to help(help/1).

help(+What)
Show specified part of the manual. What is one of:

hNamei/hArityi Give help on specified predicate

hNamei Give help on named predicate with any arity or C interface
function with that name
hSectioni Display specified section. Section numbers are dash-
separated numbers: 2-3 refers to section 2.3 of the man-
ual. Section numbers are obtained using apropos/1.

Examples:

?- help(assert). Give help on predicate assert

?- help(3-4). Display section 3.4 of the manual
?- help(PL retry). Give help on interface function PL retry()

See also apropos/1 and the SWI-Prolog home page at http://www.swi-prolog.org,

which provides a FAQ, an HTML version of the manual for online browsing, and HTML and
PDF versions for downloading.
5
http://www.swi-prolog.org

SWI-Prolog 7.4 Reference Manual

24 CHAPTER 2. OVERVIEW

!!. Repeat last query

!nr. Repeat query numbered hnri
!str. Repeat last query starting with hstri
h. Show history of commands
!h. Show this list

Table 2.1: History commands

apropos(+Pattern)
Display all predicates, functions and sections that have Pattern in their name or summary
description. Lowercase letters in Pattern also match a corresponding uppercase letter. Example:

?- apropos(file). Display predicates, functions and sections

that have file (or File, etc.) in their sum-
mary description.

explain(+ToExplain)
Give an explanation on the given object. The argument may be any Prolog data object. If the
argument is an atom, a term of the form Name/Arity or a term of the form Module:Name/Arity,
explain/1 describes the predicate as well as possible references to it. See also gxref/0.

explain(+ToExplain, -Explanation)
Unify Explanation with an explanation for ToExplain. Backtracking yields further explanations.

2.7 Command line history

SWI-Prolog offers a query substitution mechanism similar to what is seen in Unix shells. The avail-
ability of this feature is controlled by set prolog flag/2, using the history Prolog flag. By
default, history is available if no interactive command line editor is available. To enable history,
remembering the last 50 commands, put the following into your startup file (see section 2.2):

:- set_prolog_flag(history, 50).

The history system allows the user to compose new queries from those typed before and remembered
by the system. The available history commands are shown in table 2.1. History expansion is not done
if these sequences appear in quoted atoms or strings.

2.8 Reuse of top-level bindings

Bindings resulting from the successful execution of a top-level goal are asserted in a database if they
are not too large. These values may be reused in further top-level queries as $Var. If the same
variable name is used in a subsequent query the system associates the variable with the latest binding.
Example:
Note that variables may be set by executing =/2:

SWI-Prolog 7.4 Reference Manual

2.9. OVERVIEW OF THE DEBUGGER 25

1 ?- maplist(plus(1), "hello", X).

X = [105,102,109,109,112].

2 ?- format(sn, [$X]).
ifmmp
true.

3 ?-

Figure 2.1: Reusing top-level bindings

6 ?- X = statistics.
X = statistics.

7 ?- $X.
28.00 seconds cpu time for 183,128 inferences
4,016 atoms, 1,904 functors, 2,042 predicates, 52 modules
55,915 byte codes; 11,239 external references

Limit Allocated In use

Heap : 624,820 Bytes
Local stack : 2,048,000 8,192 404 Bytes
Global stack : 4,096,000 16,384 968 Bytes
Trail stack : 4,096,000 8,192 432 Bytes
true.

2.9 Overview of the Debugger

SWI-Prolog has a 6-port tracer, extending the standard 4-port tracer [Byrd, 1980,
Clocksin & Melish, 1987] with two additional ports. The optional unify port allows the user to
inspect the result after unification of the head. The exception port shows exceptions raised by
throw/1 or one of the built-in predicates. See section 4.11.
The standard ports are called call, exit, redo, fail and unify. The tracer is started by the
trace/0 command, when a spy point is reached and the system is in debugging mode (see spy/1
and debug/0), or when an exception is raised that is not caught.
The interactive top-level goal trace/0 means trace the next query. The tracer shows
the port, displaying the port name, the current depth of the recursion and the goal. The goal
is printed using the Prolog predicate write term/2. The style is defined by the Prolog flag
debugger write options and can be modified using this flag or using the w, p and d com-
mands of the tracer.
On leashed ports (set with the predicate leash/1, default are call, exit, redo and fail)
the user is prompted for an action. All actions are single-character commands which are executed
without waiting for a return, unless the command line option -tty is active. Tracer options:

SWI-Prolog 7.4 Reference Manual

26 CHAPTER 2. OVERVIEW

min_numlist([H|T], Min) :-
min_numlist(T, H, Min).

min_numlist([], Min, Min).

min_numlist([H|T], Min0, Min) :-
Min1 is min(H, Min0),
min_numlist(T, Min1, Min).

1 ?- visible(+all), leash(-exit).
true.

2 ?- trace, min_numlist([3, 2], X).

Call: (7) min_numlist([3, 2], _G0) ? creep
Unify: (7) min_numlist([3, 2], _G0)
Call: (8) min_numlist([2], 3, _G0) ? creep
Unify: (8) min_numlist([2], 3, _G0)
Call: (9) _G54 is min(2, 3) ? creep
Exit: (9) 2 is min(2, 3)
Call: (9) min_numlist([], 2, _G0) ? creep
Unify: (9) min_numlist([], 2, 2)
Exit: (9) min_numlist([], 2, 2)
Exit: (8) min_numlist([2], 3, 2)
Exit: (7) min_numlist([3, 2], 2)
X = 2.

Figure 2.2: Example trace of the program above showing all ports. The lines marked indicate calls
to transparent predicates. See section 6.

SWI-Prolog 7.4 Reference Manual

2.9. OVERVIEW OF THE DEBUGGER 27

+ (Spy)
Set a spy point (see spy/1) on the current predicate.

- (No spy)
Remove the spy point (see nospy/1) from the current predicate.

/ (Find)
Search for a port. After the /, the user can enter a line to specify the port to search for. This
line consists of a set of letters indicating the port type, followed by an optional term, that should
unify with the goal run by the port. If no term is specified it is taken as a variable, searching for
any port of the specified type. If an atom is given, any goal whose functor has a name equal to
that atom matches. Examples:

/f Search for any fail port

/fe solve Search for a fail or exit port of any goal with name
solve
/c solve(a, ) Search for a call to solve/2 whose first argument
is a variable or the atom a
/a member( , ) Search for any port on member/2. This is equiv-
alent to setting a spy point on member/2.

. (Repeat find)
Repeat the last find command (see /).

A (Alternatives)
Show all goals that have alternatives.

C (Context)
Toggle Show Context. If on, the context module of the goal is displayed between square
brackets (see section 6). Default is off.

L (Listing)
List the current predicate with listing/1.

a (Abort)
Abort Prolog execution (see abort/0).

b (Break)
Enter a Prolog break environment (see break/0).

c (Creep)
Continue execution, stop at next port. (Also RETURN, SPACE).

d (Display)
Set the max depth(Depth) option of debugger write options, limiting the depth to
which terms are printed. See also the w and p options.

e (Exit)
Terminate Prolog (see halt/0).

SWI-Prolog 7.4 Reference Manual

28 CHAPTER 2. OVERVIEW

f (Fail)
Force failure of the current goal.

g (Goals)
Show the list of parent goals (the execution stack). Note that due to tail recursion optimization
a number of parent goals might not exist any more.

h (Help)
Show available options (also ?).

i (Ignore)
Ignore the current goal, pretending it succeeded.

l (Leap)
Continue execution, stop at next spy point.

n (No debug)
Continue execution in no debug mode.

p (Print)
Set the Prolog flag debugger write options to [quoted(true),
portray(true), max depth(10), priority(699)]. This is the default.

r (Retry)
Undo all actions (except for database and I/O actions) back to the call port of the current goal
and resume execution at the call port.

s (Skip)
Continue execution, stop at the next port of this goal (thus skipping all calls to children of this
goal).

u (Up)
Continue execution, stop at the next port of the parent goal (thus skipping this goal and all
calls to children of this goal). This option is useful to stop tracing a failure driven loop.

w (Write)
Set the Prolog flag debugger write options to [quoted(true),
attributes(write), priority(699)], bypassing portray/1, etc.

The ideal 4-port model [Byrd, 1980] as described in many Prolog books
[Clocksin & Melish, 1987] is not visible in many Prolog implementations because code opti-
misation removes part of the choice and exit points. Backtrack points are not shown if either the goal
succeeded deterministically or its alternatives were removed using the cut. When running in debug
mode (debug/0) choice points are only destroyed when removed by the cut. In debug mode, last
call optimisation is switched off.6
Reference information to all predicates available for manipulating the debugger is in section 4.39.
6
This implies the system can run out of stack in debug mode, while no problems arise when running in non-debug mode.

SWI-Prolog 7.4 Reference Manual

2.10. COMPILATION 29

2.10 Compilation
2.10.1 During program development
During program development, programs are normally loaded using the list abbreviation (?-
[load].). It is common practice to organise a project as a collection of source files and a load
file, a Prolog file containing only use module/[1,2] or ensure loaded/1 directives, possi-
bly with a definition of the entry point of the program, the predicate that is normally used to start the
program. This file is often called load.pl. If the entry point is called go, a typical session starts as:

% swipl
<banner>

1 ?- [load].
<compilation messages>
true.

2 ?- go.
<program interaction>

When using Windows, the user may open load.pl from the Windows explorer, which will cause
swipl-win.exe to be started in the directory holding load.pl. Prolog loads load.pl before
entering the top level. If Prolog is started from an interactive shell, one may choose the type swipl
-s load.pl.

2.10.2 For running the result

There are various options if you want to make your program ready for real usage. The best choice
depends on whether the program is to be used only on machines holding the SWI-Prolog development
system, the size of the program, and the operating system (Unix vs. Windows).

Using PrologScript
A Prolog source file can be used directly as a Unix program using the Unix #! magic start. The same
mechanism is useful for specifying additional parameters for running a Prolog file on Windows. The
Unix #! magic is allowed because if the first letter of a Prolog file is #, the first line is treated as
a comment.7 To create a Prolog script, use one of the two alternatives below as first line. The first
can be used to bind a script to a specific Prolog installation, while the latter uses the default prolog
installed in $PATH.

!/path/to/swipl
!/usr/bin/env swipl

The interpretation of arguments to the executable in the HashBang line differs between Unix-derived
systems. For portability, the #! must be followed immediately with an absolute path to the executable
7
The #-sign can be the legal start of a normal Prolog clause. In the unlikely case this is required, leave the first line blank
or add a header comment.

SWI-Prolog 7.4 Reference Manual

30 CHAPTER 2. OVERVIEW

and should have none or one argument. Neither the executable path, nor the argument shall use quotes
or spaces. When started this way, the Prolog flag argv contains the command line arguments that
follow the script invocation. Below is a simple script doing expression evaluation:

#!/usr/bin/env swipl

:- initialization main.

eval :-
current_prolog_flag(argv, Argv),
concat_atom(Argv, , SingleArg),
term_to_atom(Term, SingleArg),
Val is Term,
format(wn, [Val]).

main :-
catch(eval, E, (print_message(error, E), fail)),
halt.
main :-
halt(1).

And here are two example runs:

% ./eval 1+2
3
% ./eval foo
ERROR: is/2: Arithmetic: foo/0 is not a function
%

The Windows version simply ignores the #! line.8

Creating a shell script

With the introduction of PrologScript (see section 2.10.2), using shell scripts as explained in this
section has become redundant for most applications.
Especially on Unix systems and not-too-large applications, writing a shell script that simply loads
your application and calls the entry point is often a good choice. A skeleton for the script is given
below, followed by the Prolog code to obtain the program arguments.

#!/bin/sh

base=<absolute-path-to-source>
PL=swipl
8
Older versions extracted command line arguments from the HashBang line. As of version 5.9 all relevant setup can
be achieved using directives. Due to the compatibility issues around HashBang line processing, we decided to remove it
completely.

SWI-Prolog 7.4 Reference Manual

2.10. COMPILATION 31

exec $PL -q -f "$base/load" --

:- initialization go.

go :-
current_prolog_flag(argv, Arguments),
go(Arguments).

go(Args) :-
...

On Windows systems, similar behaviour can be achieved by creating a shortcut to Prolog, passing the
proper options or writing a .bat file.

Creating a saved state

For larger programs, as well as for programs that are required to run on systems that do not have
the SWI-Prolog development system installed, creating a saved state is the best solution. A saved
state is created using qsave program/[1,2] or the -c command line option. A saved state
is a file containing machine-independent9 intermediate code in a format dedicated for fast loading.
Optionally, the emulator may be integrated in the saved state, creating a single file, but machine-
dependent, executable. This process is described in chapter 12.

Compilation using the -c command line option

This mechanism loads a series of Prolog source files and then creates a saved state as
qsave program/2 does. The command syntax is:

% swipl [option ...] [-o output] -c file.pl ...

The options argument are options to qsave program/2 written in the format below. The option
names and their values are described with qsave program/2.

--option-name=option-value

For example, to create a stand-alone executable that starts by executing main/0 and for which
the source is loaded through load.pl, use the command

% swipl --goal=main --stand_alone=true -o myprog -c load.pl

This performs exactly the same as executing

9
The saved state does not depend on the CPU instruction set or endianness. Saved states for 32- and 64-bits are not
compatible. Typically, saved states only run on the same version of Prolog on which they have been created.

SWI-Prolog 7.4 Reference Manual

32 CHAPTER 2. OVERVIEW

% swipl
<banner>

?- [load].
?- qsave_program(myprog,
[ goal(main),
stand_alone(true)
]).
?- halt.

2.11 Environment Control (Prolog flags)

The predicates current prolog flag/2 and set prolog flag/2 allow the user to examine
and modify the execution environment. It provides access to whether optional features are available
on this version, operating system, foreign code environment, command line arguments, version, as
well as runtime flags to control the runtime behaviour of certain predicates to achieve compatibility
with other Prolog environments.
current prolog flag(?Key, -Value) [ISO]
The predicate current prolog flag/2 defines an interface to installation features: op-
tions compiled in, version, home, etc. With both arguments unbound, it will generate all
defined Prolog flags. With Key instantiated, it unifies Value with the value of the Prolog flag or
fails if the Key is not a Prolog flag.
Flags marked rw can be modified by the user using set prolog flag/2. Flag values
are typed. Flags marked as bool can have the values true or false. The predicate
create prolog flag/3 may be used to create flags that describe or control behaviour of li-
braries and applications. The library settings provides an alternative interface for managing
notably application parameters.
Some Prolog flags are not defined in all versions, which is normally indicated in the documen-
tation below as if present and true. A boolean Prolog flag is true iff the Prolog flag is present
and the Value is the atom true. Tests for such flags should be written as below:

( current_prolog_flag(windows, true)
-> <Do MS-Windows things>
; <Do normal things>
)

Some Prolog flags are scoped to a source file. This implies that if they are set using a direc-
tive inside a file, the flag value encountered when loading of the file started is restored when
loading of the file is completed. Currently, the following flags are scoped to the source file:
generate debug info and optimise.
A new thread (see section 9) copies all flags from the thread that created the new thread (its
parent).10 As a consequence, modifying a flag inside a thread does not affect other threads.
10
This is implemented using the copy-on-write tecnhnique.

SWI-Prolog 7.4 Reference Manual

2.11. ENVIRONMENT CONTROL (PROLOG FLAGS) 33

access level (atom, changeable)

This flag defines a normal user view (user, default) or a system view. In system view
all system code is fully accessible as if it was normal user code. In user view, certain
operations are not permitted and some details are kept invisible. We leave the exact
consequences undefined, but, for example, system code can be traced using system access
and system predicates can be redefined.
address bits (integer)
Address size of the hosting machine. Typically 32 or 64. Except for the maximum stack
limit, this has few implications to the user. See also the Prolog flag arch.
agc margin (integer, changeable)
If this amount of atoms possible garbage atoms exist perform atom garbage collection at
the first opportunity. Initial value is 10,000. May be changed. A value of 0 (zero) disables
atom garbage collection. See also PL register atom().11
apple (bool)
If present and true, the operating system is MacOSX. Defined if the C compiler used
to compile this version of SWI-Prolog defines __APPLE__. Note that the unix is also
defined for MacOSX.
allow dot in atom (bool, changeable)
If true (default false), dots may be embedded into atoms that are not quoted and
start with a letter. The embedded dot must be followed by an identifier continuation
character (i.e., letter, digit or underscore). The dot is allowed in identifiers in many
languages, which can make this a useful flag for defining DSLs. Note that this conflicts
with cascading functional notation. For example, Post.meta.author is read as
.(Post, meta.author if this flag is set to true.
allow variable name as functor (bool, changeable)
If true (default is false), Functor(arg) is read as if it were written
Functor(arg). Some applications use the Prolog read/1 predicate for
reading an application-defined script language. In these cases, it is often difficult to
explain to non-Prolog users of the application that constants and functions can only start
with a lowercase letter. Variables can be turned into atoms starting with an uppercase
atom by calling read term/2 using the option variable names and binding the
variables to their name. Using this feature, F(x) can be turned into valid syntax for such
script languages. Suggested by Robert van Engelen. SWI-Prolog specific.
argv (list, changeable)
List is a list of atoms representing the application command line arguments. Application
command line arguments are those that have not been processed by Prolog during its
initialization. Note that Prologs argument processing stops at -- or the first non-option
argument. See also os argv.12
arch (atom)
Identifier for the hardware and operating system SWI-Prolog is running on. Used
to select foreign files for the right architecture. See also section 11.2.3 and
file search path/2.
11
Given that SWI-Prolog has no limit on the length of atoms, 10,000 atoms may still occupy a lot of memory. Applications
using extremely large atoms may wish to call garbage collect atoms/0 explicitly or lower the margin.
12
Prior to version 6.5.2, argv was defined as os argv is now. The change was made for compatibility reasone and
because the current definition is more practical.

SWI-Prolog 7.4 Reference Manual

34 CHAPTER 2. OVERVIEW

associated file (atom)

Set if Prolog was started with a prolog file as argument. Used by e.g., edit/0 to edit the
initial file.
autoload (bool, changeable)
If true (default) autoloading of library functions is enabled.
back quotes (codes,chars,string,symbol char, changeable)
Defines the term-representation for back-quoted material. The default is codes. If
--traditional is given, the default is symbol char, which allows using in
operators composed of symbols.13 . See also section 5.2.
backtrace (bool, changeable)
If true (default), print a backtrace on an uncaught exception.
backtrace depth (integer, changeable)
If backtraces on errors are enabled, this flag defines the maximum number of frames that
is printed (default 20).
backtrace goal depth (integer, changeable)
The frame of a backtrace is printed after making a shallow copy of the goal. This flag
determines the depth to which the goal term is copied. Default is 3.
backtrace show lines (bool, changeable)
If true (default), try to reconstruct the line number at which the exception happened.
bounded (bool)
ISO Prolog flag. If true, integer representation is bound by min integer and
max integer. If false integers can be arbitrarily large and the min integer and
max integer are not present. See section 4.27.2.
break level (integer)
Current break-level. The initial top level (started with -t) has value 0. See break/0.
This flag is absent from threads that are not running a top-level loop.
c cc (atom, changeable)
Name of the C compiler used to compile SWI-Prolog. Normally either gcc or cc. See
section 11.5.
c cflags (atom, changeable)
CFLAGS used to compile SWI-Prolog. See section 11.5.
c ldflags (atom, changeable)
LDFLAGS used to link SWI-Prolog. See section 11.5.
c libs (atom, changeable)
Libraries needed to link executables that embed SWI-Prolog. Typically -lswipl if the
SWI-Prolog kernel is a shared (DLL). If the SWI-Prolog kernel is in a static library, this
flag also contains the dependencies.
c libplso (atom, changeable)
Libraries needed to link extensions (shared object, DLL) to SWI-Prolog. Typically empty
on ELF systems and -lswipl on COFF-based systems. See section 11.5.
13
Older versions had a boolean flag backquoted strings, which toggled between string and symbol char

SWI-Prolog 7.4 Reference Manual

2.11. ENVIRONMENT CONTROL (PROLOG FLAGS) 35

char conversion (bool, changeable)

Determines whether character conversion takes place while reading terms. See also
char conversion/2.
character escapes (bool, changeable)
If true (default), read/1 interprets \ escape sequences in quoted atoms and strings.
May be changed. This flag is local to the module in which it is changed. See
section 2.15.1.
colon sets calling context (bool)
Using the construct hmodulei:hgoali sets the calling context for executing hgoali. This
flag is defined by ISO/IEC 13211-2 (Prolog modules standard). See section 6.
color term (bool, changeable)
This flag is managed by library ansi term, which is loaded at startup if the two con-
ditions below are both true. Note that this implies that setting this flag to false from
the system or personal initialization file (see section 2.2 disables colored output. The
predicate message property/2 can be used to control the actual color scheme
depending in the message type passed to print message/2.
stream_property(current_output, tty(true))
\+ current_prolog_flag(color_term, false)
compile meta arguments (atom, changeable)
Experimental flag that controls compilation of arguments passed to meta-calls marked 0
or (see meta predicate/1). Supported values are:
false
(default). Meta-arguments are passed verbatim.
control
Compile meta-arguments that contain control structures ((A,B), (A;B), (A-B;C),
etc.). If not compiled at compile time, such arguments are compiled to a temporary
clause before execution. Using this option enhances performance of processing
complex meta-goals that are known at compile time.
true
Also compile references to normal user predicates. This harms performance (a little),
but enhances the power of poor-mens consistency check used by make/0 and
implemented by list undefined/0.
always
Always create an intermediate clause, even for system predicates. This prepares for
replacing the normal head of the generated predicate with a special reference (similar
to database references as used by, e.g., assert/2) that provides direct access to the
executable code, thus avoiding runtime lookup of predicates for meta-calling.
compiled at (atom)
Describes when the system has been compiled. Only available if the C compiler used to
compile SWI-Prolog provides the DATE and TIME macros.
console menu (bool)
Set to true in swipl-win.exe to indicate that the console supports menus. See also
section 4.35.3.

SWI-Prolog 7.4 Reference Manual

36 CHAPTER 2. OVERVIEW

cpu count (integer, changeable)

Number of physical CPUs or cores in the system. The flag is marked read-
write both to allow pretending the system has more or less processors. See also
thread setconcurrency/2 and the library thread. This flag is not available on
systems where we do not know how to get the number of CPUs. This flag is not included
in a saved state (see qsave program/1).
dde (bool)
Set to true if this instance of Prolog supports DDE as described in section 4.43.
debug (bool, changeable)
Switch debugging mode on/off. If debug mode is activated the system traps encountered
spy points (see spy/1) and trace points (see trace/1). In addition, last-call optimi-
sation is disabled and the system is more conservative in destroying choice points to
simplify debugging.
Disabling these optimisations can cause the system to run out of memory on programs
that behave correctly if debug mode is off.
debug on error (bool, changeable)
If true, start the tracer after an error is detected. Otherwise just continue execution. The
goal that raised the error will normally fail. See also the Prolog flag report error.
Default is true.
debugger write options (term, changeable)
This argument is given as option-list to write term/2 for printing goals by
the debugger. Modified by the w, p and N d commands of the debug-
ger. Default is [quoted(true), portray(true), max depth(10),
attributes(portray)].
debugger show context (bool, changeable)
If true, show the context module while printing a stack-frame in the tracer. Normally
controlled using the C option of the tracer.
dialect (atom)
Fixed to swi. The code below is a reliable and portable way to detect SWI-Prolog.
is_dialect(swi) :-
catch(current_prolog_flag(dialect, swi), _, fail).

double quotes (codes,chars,atom,string, changeable)

This flag determines how double quoted strings are read by Prolog and is like
character escapes and back quotes maintained for each module. The default
is string, which produces a string as described in section 5.2. If --traditional
is given, the default is codes, which produces a list of character codes, integers that
represent a Unicode code-point. The value chars produces a list of one-character atoms
and the value atom makes double quotes the same as single quotes, creating a atom. See
also section 5.
editor (atom, changeable)
Determines the editor used by edit/1. See section 4.4.1 for details on selecting the
editor used.

SWI-Prolog 7.4 Reference Manual

2.11. ENVIRONMENT CONTROL (PROLOG FLAGS) 37

emacs inferior process (bool)

If true, SWI-Prolog is running as an inferior process of (GNU/X-)Emacs. SWI-Prolog
assumes this is the case if the environment variable EMACS is t and INFERIOR is yes.
encoding (atom, changeable)
Default encoding used for opening files in text mode. The initial value is deduced from
the environment. See section 2.18.1 for details.
executable (atom)
Pathname of the running executable. Used by qsave program/2 as default emulator.
exit status (integer)
Set by halt/1 to its argument, making the exit status available to hooks registered with
at halt/1.
file name case handling (atom, changeable)
This flag defines how Prolog handles the case of file names. The flag is used for case
normalization and to determine whether two names refer to the same file.14 It has one of
the following values:
case sensitive
The filesystem is fully case sensitive. Prolog does not perform any case modification
or case insensitive matching. This is the default on Unix systems.
case preserving
The filesystem is case insensitive, but it preserves the case with which the user jas
created a file. This is the default on Windows systems.
case insensitive
The filesystem doesnt store or match case. In this scenario Prolog maps all file
names to lower case.
file name variables (bool, changeable)
If true (default false), expand $varname and in arguments of built-in predicates
that accept a file name (open/3, exists file/1, access file/2, etc.). The
predicate expand file name/2 can be used to expand environment variables and
wildcard patterns. This Prolog flag is intended for backward compatibility with older
versions of SWI-Prolog.
file search cache time (number, changeable)
Time in seconds for which search results from absolute file name/3 are cached.
Within this time limit, the system will first check that the old search result satisfies the
conditions. Default is 10 seconds, which typically avoids most repetitive searches for
(library) files during compilation. Setting this value to 0 (zero) disables the cache.
gc (bool, changeable)
If true (default), the garbage collector is active. If false, neither garbage collection, nor
stack shifts will take place, even not on explicit request. May be changed.
generate debug info (bool, changeable)
If true (default) generate code that can be debugged using trace/0, spy/1, etc. Can
be set to false using the -nodebug. This flag is scoped within a source file. Many of
14
BUG: Note that file name case handling is typically a properly of the filesystem, while Prolog only has a global flag to
determine its file handling.

SWI-Prolog 7.4 Reference Manual

38 CHAPTER 2. OVERVIEW

the libraries have :- set_prolog_flag(generate_debug_info, false) to

hide their details from a normal trace.15
gmp version (integer)
If Prolog is linked with GMP, this flag gives the major version of the GMP library used.
See also section 11.4.8.
gui (bool)
Set to true if XPCE is around and can be used for graphics.
history (integer, changeable)
If integer > 0, support Unix csh(1)-like history as described in section 2.7. Otherwise,
only support reusing commands through the command line editor. The default is to set
this Prolog flag to 0 if a command line editor is provided (see Prolog flag readline)
and 15 otherwise.
home (atom)
SWI-Prologs notion of the home directory. SWI-Prolog uses its home directory to find
its startup file as hhomei/boot32.prc (32-bit machines) or hhomei/boot64.prc
(64-bit machines) and to find its library as hhomei/library.
hwnd (integer)
In swipl-win.exe, this refers to the MS-Windows window handle of the console
window.
integer rounding function (down,toward zero)
ISO Prolog flag describing rounding by // and rem arithmetic functions. Value depends
on the C compiler used.
iso (bool, changeable)
Include some weird ISO compatibility that is incompatible with normal SWI-Prolog
behaviour. Currently it has the following effect:
The //2 (float division) always returns a float, even if applied to integers that can be
divided.
In the standard order of terms (see section 4.7.1), all floats are before all integers.
atom length/2 yields a type error if the first argument is a number.
clause/[2,3] raises a permission error when accessing static predicates.
abolish/[1,2] raises a permission error when accessing static predicates.
Syntax is closer to the ISO standard:
Unquoted commas and bars appearing as atoms are not allowed. Instead of
f(,,a) now write f(,,a). Unquoted commas can only be used to sep-
arate arguments in functional notation and list notation, and as a conjunction
operator. Unquoted bars can only appear within lists to separate head and tail,
like [Head|Tail], and as infix operator for alternation in grammar rules, like
a --> b | c.
Within functional notation and list notation terms must have priority below
1000. That means that rules and control constructs appearing as arguments need
bracketing. A term like [a :- b, c]. must now be disambiguated to mean
[(a :- b), c]. or [(a :- b, c)].
15
In the current implementation this only causes a flag to be set on the predicate that causes children to be hidden from
the debugger. The name anticipates further changes to the compiler.

SWI-Prolog 7.4 Reference Manual

2.11. ENVIRONMENT CONTROL (PROLOG FLAGS) 39

Operators appearing as operands must be bracketed. Instead of

X == -, true. write X == (-), true. Currently, this is not en-
tirely enforced.
Backslash-escaped newlines are interpreted according to the ISO standard. See
section 2.15.1.
large files (bool)
If present and true, SWI-Prolog has been compiled with large file support (LFS) and
is capable of accessing files larger than 2GB on 32-bit hardware. Large file support is
default on installations built using configure that support it and may be switched off
using the configure option --disable-largefile.
last call optimisation (bool, changeable)
Determines whether or not last-call optimisation is enabled. Normally the value of this
flag is the negation of the debug flag. As programs may run out of stack if last-call
optimisation is omitted, it is sometimes necessary to enable it during debugging.
max arity (unbounded)
ISO Prolog flag describing there is no maximum arity to compound terms.
max integer (integer)
Maximum integer value if integers are bounded. See also the flag bounded and sec-
tion 4.27.2.
max tagged integer (integer)
Maximum integer value represented as a tagged value. Tagged integers require one
word storage. Larger integers are represented as indirect data and require significantly
more space.
min integer (integer)
Minimum integer value if integers are bounded. See also the flag bounded and sec-
tion 4.27.2.
min tagged integer (integer)
Start of the tagged-integer value range.
occurs check (atom, changeable)
This flag controls unification that creates an infinite tree (also called cyclic term) and can
have three values. Using false (default), unification succeeds, creating an infinite tree.
Using true, unification behaves as unify with occurs check/2, failing silently.
Using error, an attempt to create a cyclic term results in an occurs check exception.
The latter is intended for debugging unintentional creations of cyclic terms. Note that this
flag is a global flag modifying fundamental behaviour of Prolog. Changing the flag from
its default may cause libraries to stop functioning properly.
open shared object (bool)
If true, open shared object/2 and friends are implemented, providing access to
shared libraries (.so files) or dynamic link libraries (.DLL files).
optimise (bool, changeable)
If true, compile in optimised mode. The initial value is true if Prolog was started with
the -O command line option. The optimise flag is scoped to a source file.
Currently optimised compilation implies compilation of arithmetic, and deletion of redun-
dant true/0 that may result from expand goal/2.

SWI-Prolog 7.4 Reference Manual

40 CHAPTER 2. OVERVIEW

Later versions might imply various other optimisations such as integrating small predi-
cates into their callers, eliminating constant expressions and other predictable constructs.
Source code optimisation is never applied to predicates that are declared dynamic (see
dynamic/1).
os argv (list, changeable)
List is a list of atoms representing the command line arguments used to invoke SWI-
Prolog. Please note that all arguments are included in the list returned. See argv to get
the application options.
pid (int)
Process identifier of the running Prolog process. Existence of this flag is implementation-
defined.
pipe (bool, changeable)
If true, open(pipe(command), mode, Stream), etc. are supported. Can be
changed to disable the use of pipes in applications testing this feature. Not recommended.
print write options (term, changeable)
Specifies the options for write term/2 used by print/1 and print/2.
prompt alternatives on (atom, changeable)
Determines prompting for alternatives in the Prolog top level. Default is determinism,
which implies the system prompts for alternatives if the goal succeeded while leaving
choice points. Many classical Prolog systems behave as groundness: they prompt for
alternatives if and only if the query contains variables.
protect static code (bool, changeable)
If true (default false), clause/2 does not operate on static code, providing some
basic protection from hackers that wish to list the static code of your Prolog program.
Once the flag is true, it cannot be changed back to false. Protection is default in
ISO mode (see Prolog flag iso). Note that many parts of the development environment
require clause/2 to work on static code, and enabling this flag should thus only be
used for production code.
qcompile (atom, changeable)
This option provides the default for the qcompile(+Atom) option of load files/2.
readline (atom, changeable)
Specifies which form of command line editing is provided. Possible values are below. The
flag may be set from the users init file (see section 2.3) to one of false, readline or
editline. This causes the toplevel not to load a command line editor (false) or load
the specified one. If loading fails the flag is set to false.
false
No command line editing is available.
readline
The library readline is loaded, providing line editing based on the GNU readline
library.
editline
The library editline is loaded, providing line editing based on the BSD libedit.
This is the default if editline is available and can be loaded.

SWI-Prolog 7.4 Reference Manual

2.11. ENVIRONMENT CONTROL (PROLOG FLAGS) 41

swipl win
SWI-Prolog uses its own console (swipl-win.exe on Windows, the Qt based
swipl-win on MacOS) which provides line editing.
resource database (atom)
Set to the absolute filename of the attached state. Typically this is the file boot32.prc,
the file specified with -x or the running executable. See also resource/3.
report error (bool, changeable)
If true, print error messages; otherwise suppress them. May be changed. See also the
debug on error Prolog flag. Default is true, except for the runtime version.
runtime (bool)
If present and true, SWI-Prolog is compiled with -DO RUNTIME, disabling various
useful development features (currently the tracer and profiler).
sandboxed load (bool, changeable)
If true (default false), load files/2 calls hooks to allow library(sandbox) to
verify the safety of directives.
saved program (bool)
If present and true, Prolog has been started from a state saved with
qsave program/[1,2].
shared object extension (atom)
Extension used by the operating system for shared objects. .so for most Unix systems
and .dll for Windows. Used for locating files using the file type executable.
See also absolute file name/3.
shared object search path (atom)
Name of the environment variable used by the system to search for shared objects.
signals (bool)
Determine whether Prolog is handling signals (software interrupts). This flag is false
if the hosting OS does not support signal handling or the command line option
-nosignals is active. See section 11.4.21 for details.
stream type check (atom, changeable)
Defines whether and how strictly the system validates that byte I/O should not be applied
to text streams and text I/O should not be applied to binary streams. Values are false
(no checking), true (full checking) and loose. Using checking mode loose (default),
the system accepts byte I/O from text stream that use ISO Latin-1 encoding and accepts
writing text to binary streams.
system thread id (int)
Available in multithreaded version (see section 9) where the operating system provides
system-wide integer thread identifiers. The integer is the thread identifier used by the
operating system for the calling thread. See also thread self/1.
table space (integer, changeable)
Space reserved for storing answer tables for tabled predicates (see table/1).16 When
exceeded a resource error(table space) exception is raised.
16
BUG: Currently only counts the space occupied by the nodes in the answer tries.

SWI-Prolog 7.4 Reference Manual

42 CHAPTER 2. OVERVIEW

timezone (integer)
Offset in seconds west of GMT of the current time zone. Set at initialization time
from the timezone variable associated with the POSIX tzset() function. See also
format time/3.
toplevel mode (atom, changeable)
If backtracking (default), the toplevel backtracks after completing a query. If
recursive, the toplevel is implemented as a recursive loop. This implies that global
variables set using b setval/2 are maintained between queries. In recursive mode,
answers to toplevel variables (see section 2.8) are kept in backtrackable global variables
and thus not copied. In backtracking mode answers to toplevel variables are kept in the
recorded database (see section 4.14.2).
The recursive mode has been added for interactive usage of CHR (see section 8),17 which
maintains the global constraint store in backtrackable global variables.
toplevel print anon (bool, changeable)
If true, top-level variables starting with an underscore ( ) are printed normally. If false
they are hidden. This may be used to hide bindings in complex queries from the top level.
toplevel print factorized (bool, changeable)
If true (default false) show the internal sharing of subterms in the answer substi-
tution. The example below reveals internal sharing of leaf nodes in red-black trees as
implemented by the rbtrees predicate rb new/1:
?- set_prolog_flag(toplevel_print_factorized, true).
?- rb_new(X).
X = t(_S1, _S1), % where
_S1 = black(, _G387, _G388, ).

If this flag is false, the % where notation is still used to indicate cycles as illustrated
below. This example also shows that the implementation reveals the internal cycle length,
and not the minimal cycle length. Cycles of different length are indistinguishable in Prolog
(as illustrated by S == R).
?- S = s(S), R = s(s(R)), S == R.
S = s(S),
R = s(s(R)).

answer write options (term, changeable)

This argument is given as option-list to write term/2 for printing results of
queries. Default is [quoted(true), portray(true), max depth(10),
attributes(portray)].
toplevel prompt (atom, changeable)
Define the prompt that is used by the interactive top level. The following (tilde) se-
quences are replaced:

m Type in module if not user (see module/1)

l Break level if not 0 (see break/0)
d Debugging state if not normal execution (see debug/0, trace/0)
! History event if history is enabled (see flag history)
17
Suggested by Falco Nogatz

SWI-Prolog 7.4 Reference Manual

2.11. ENVIRONMENT CONTROL (PROLOG FLAGS) 43

toplevel var size (int, changeable)

Maximum size counted in literals of a term returned as a binding for a variable in a
top-level query that is saved for re-use using the $ variable reference. See section 2.8.
trace gc (bool, changeable)
If true (default false), garbage collections and stack-shifts will be reported on the
terminal. May be changed. Values are reported in bytes as G+T , where G is the global
stack value and T the trail stack value. Gained describes the number of bytes reclaimed.
used the number of bytes on the stack after GC and free the number of bytes allocated,
but not in use. Below is an example output.
% GC: gained 236,416+163,424 in 0.00 sec;
used 13,448+5,808; free 72,568+47,440

traditional (bool)
Available in SWI-Prolog version 7. If true, traditional mode has been selected using
--traditional. Notice that some SWI7 features, like the functional notation on
dicts, do not work in this mode. See also section 5.
tty control (bool, changeable)
Determines whether the terminal is switched to raw mode for get single char/1,
which also reads the user actions for the trace. May be set. If this flag is false at
startup, command line editing is disabled. See also the +/-tty command line option.
unix (bool)
If present and true, the operating system is some version of Unix. Defined if the C
compiler used to compile this version of SWI-Prolog either defines __unix__ or unix.
On other systems this flag is not available. See also apple and windows.
unknown (fail,warning,error, changeable)
Determines the behaviour if an undefined procedure is encountered. If fail, the pred-
icate fails silently. If warn, a warning is printed, and execution continues as if the
predicate was not defined, and if error (default), an existence error exception is
raised. This flag is local to each module and inherited from the modules import-module.
Using default setup, this implies that normal modules inherit the flag from user, which
in turn inherit the value error from system. The user may change the flag for module
user to change the default for all application modules or for a specific module. It is
strongly advised to keep the error default and use dynamic/1 and/or multifile/1
to specify possible non-existence of a predicate.
unload foreign libraries (bool, changeable)
If true (default false), unload all loaded foreign libraries. Default is false because
modern OSes reclaim the resources anyway and unloading the foreign code may cause
registered hooks to point to no longer existing data or code.
user flags (Atom, changeable)
Define the behaviour of set prolog flag/2 if the flag is not known. Values are
silent, warning and error. The first two create the flag on-the-fly, where
warning prints a message. The value error is consistent with ISO: it raises an
existence error and does not create the flag. See also create prolog flag/3. The
default is silent, but future versions may change that. Developers are encouraged to

SWI-Prolog 7.4 Reference Manual

44 CHAPTER 2. OVERVIEW

use another value and ensure proper use of create prolog flag/3 to create flags
for their library.
var prefix (bool, changeable)
If true (default false), variables must start with an underscore ( ). May be changed.
This flag is local to the module in which it is changed. See section 2.15.1.
verbose (atom, changeable)
This flag is used by print message/2. If its value is silent, messages of type
informational and banner are suppressed. The -q switches the value from the
initial normal to silent.
verbose autoload (bool, changeable)
If true the normal consult message will be printed if a library is autoloaded. By default
this message is suppressed. Intended to be used for debugging purposes.
verbose load (atom, changeable)
Determines messages printed for loading (compiling) Prolog files. Current values are
full (print a message at the start and end of each file loaded), normal (print a message
at the end of each file loaded), brief (print a message at end of loading the toplevel
file), and silent (no messages are printed, default). The value of this flag is normally
controlled by the option silent(Bool) provided by load files/2.
verbose file search (bool, changeable)
If true (default false), print messages indicating the progress of
absolute file name/[2,3] in locating files. Intended for debugging com-
plicated file-search paths. See also file search path/2.
version (integer)
The version identifier is an integer with value:

10000 Major + 100 Minor + Patch

version data (swi(Major, Minor, Patch, Extra))

Part of the dialect compatibility layer; see also the Prolog flag dialect and section C.
Extra provides platform-specific version information as a list. Extra is used for tagged
versions such as 7.4.0-rc1, in which case Extra contains a term tag(rc1).
version git (atom)
Available if created from a git repository. See git-describe for details.
warn override implicit import (bool, changeable)
If true (default), a warning is printed if an implicitly imported predicate is clobbered by
a local definition. See use module/1 for details.
win file access check (atom, changeable)
Controls the behaviour or access file/2 under Windows. There is no reliable way to
check access to files and directories on Windows. This flag allows for switching between
three alternative approximations.
access
Use Windows waccess() function. This ignores ACLs (Access Control List) and
thus may indicate that access is allowed while it is not.

SWI-Prolog 7.4 Reference Manual

2.11. ENVIRONMENT CONTROL (PROLOG FLAGS) 45

filesecurity
Use the Windows GetFileSecurity() function. This does not work on all file systems,
but is probably the best choice on file systems that do support it, notably local NTFS
volumes.
openclose
Try to open the file and close it. This works reliable for files, but not for directories.
Currently directories are checked using waccess(). This is the default.
windows (bool)
If present and true, the operating system is an implementation of Microsoft Windows.
This flag is only available on MS-Windows based versions. See also unix.
write attributes (atom, changeable)
Defines how write/1 and friends write attributed variables. The option values are
described with the attributes option of write term/3. Default is ignore.
write help with overstrike (bool)
Internal flag used by help/1 when writing to a terminal. If present and true it prints
bold and underlined text using overstrike.
xpce (bool)
Available and set to true if the XPCE graphics system is loaded.
xpce version (atom)
Available and set to the version of the loaded XPCE system.
xref (bool, changeable)
If true, source code is being read for analysis purposes such as cross-referencing. Oth-
erwise (default) it is being read to be compiled. This flag is used at several places by
term expansion/2 and goal expansion/2 hooks, notably if these hooks use
side effects. See also the libraries prolog source and prolog xref.

set prolog flag(:Key, +Value) [ISO]

Define a new Prolog flag or change its value. Key is an atom. If the flag is a system-
defined flag that is not marked changeable above, an attempt to modify the flag yields
a permission error. If the provided Value does not match the type of the flag, a
type error is raised.
Some flags (e.g., unknown) are maintained on a per-module basis. The addressed module is
determined by the Key argument.
In addition to ISO, SWI-Prolog allows for user-defined Prolog flags. The type of the flag is de-
termined from the initial value and cannot be changed afterwards. Defined types are boolean
(if the initial value is one of false, true, on or off), atom if the initial value is any other
atom, integer if the value is an integer that can be expressed as a 64-bit signed value. Any
other initial value results in an untyped flag that can represent any valid Prolog term.
The behaviour when Key denotes a non-existent key depends on the Prolog flag
user flags. The default is to define them silently. New code is encouraged to use
create prolog flag/3 for portability.

create prolog flag(+Key, +Value, +Options) [YAP]

Create a new Prolog flag. The ISO standard does not foresee creation of new flags, but many
libraries introduce new flags. Options is a list of the options below. See also user flags.

SWI-Prolog 7.4 Reference Manual

46 CHAPTER 2. OVERVIEW

access(+Access)
Define access rights for the flag. Values are read write and read only. The default
is read write.
type(+Atom)
Define a type restriction. Possible values are boolean, atom, integer, float and
term. The default is determined from the initial value. Note that term restricts the term
to be ground.
keep(+Boolean)
If true, do not modify the flag if it already exists. Otherwise (default), this predicate
behaves as set prolog flag/2 if the flag already exists.

2.12 An overview of hook predicates

SWI-Prolog provides a large number of hooks, mainly to control handling messages, debugging,
startup, shut-down, macro-expansion, etc. Below is a summary of all defined hooks with an indication
of their portability.

portray/1
Hook into write term/3 to alter the way terms are printed (ISO).
message hook/3
Hook into print message/2 to alter the way system messages are printed (Quin-
tus/SICStus).
message property/2
Hook into print message/2 that defines prefix, output stream, color, etc.
library directory/1
Hook into absolute file name/3 to define new library directories (most Prolog systems).
file search path/2
Hook into absolute file name/3 to define new search paths (Quintus/SICStus).
term expansion/2
Hook into load files/2 to modify read terms before they are compiled (macro-processing)
(most Prolog systems).
goal expansion/2
Same as term expansion/2 for individual goals (SICStus).
prolog load file/2
Hook into load files/2 to load other data formats for Prolog sources from non-file re-
sources. The load files/2 predicate is the ancestor of consult/1, use module/1,
etc.
qpredrefprolog editlocate3
Hook into edit/1 to locate objects (SWI).
qpredrefprolog editedit source1
Hook into edit/1 to call an internal editor (SWI).

SWI-Prolog 7.4 Reference Manual

2.13. AUTOMATIC LOADING OF LIBRARIES 47

prolog edit:edit command/2

Hook into edit/1 to define the external editor to use (SWI).

prolog list goal/1

Hook into the tracer to list the code associated to a particular goal (SWI).

prolog trace interception/4

Hook into the tracer to handle trace events (SWI).

qpredrefprologdebug control hook1

Hook in spy/1, nospy/1, nospyall/0 and debugging/0 to extend these control pred-
icates to higher-level libraries.

qpredrefprologhelp hook1
Hook in help/0, help/1 and apropos/1 to extend the help system.

resource/3
Define a new resource (not really a hook, but similar) (SWI).

exception/3
Old attempt to a generic hook mechanism. Handles undefined predicates (SWI).

attr unify hook/2

Unification hook for attributed variables. Can be defined in any module. See section 7.1 for
details.

2.13 Automatic loading of libraries

If at runtime an undefined predicate is trapped, the system will first try to import the pred-
icate from the modules default module (see section 6.9. If this fails the auto loader is acti-
vated.18 On first activation an index to all library files in all library directories is loaded in core
(see library directory/1, file search path/2 and reload library index/0). If
the undefined predicate can be located in one of the libraries, that library file is automatically loaded
and the call to the (previously undefined) predicate is restarted. By default this mechanism loads the
file silently. The current prolog flag/2 key verbose autoload is provided to get verbose
loading. The Prolog flag autoload can be used to enable/disable the autoload system.
Autoloading only handles (library) source files that use the module mechanism described in chap-
ter 6. The files are loaded with use module/2 and only the trapped undefined predicate is imported
into the module where the undefined predicate was called. Each library directory must hold a file
INDEX.pl that contains an index to all library files in the directory. This file consists of lines of the
following format:

index(Name, Arity, Module, File).

The predicate make/0 updates the autoload index. It searches for all library directories
(see library directory/1 and file search path/2) holding the file MKINDEX.pl or
INDEX.pl. If the current user can write or create the file INDEX.pl and it does not exist or
18
Actually, the hook user:exception/3 is called; only if this hook fails does it call the autoloader.

SWI-Prolog 7.4 Reference Manual

48 CHAPTER 2. OVERVIEW

is older than the directory or one of its files, the index for this directory is updated. If the file
MKINDEX.pl exists, updating is achieved by loading this file, normally containing a directive calling
make library index/2. Otherwise make library index/1 is called, creating an index for
all *.pl files containing a module.
Below is an example creating an indexed library directory.

% mkdir /lib/prolog
% cd /lib/prolog
% swipl -g true -t make_library_index(.)

If there is more than one library file containing the desired predicate, the following search schema is
followed:

1. If there is a library file that defines the module in which the undefined predicate is trapped, this
file is used.

2. Otherwise library files are considered in the order they appear in the library directory/1
predicate and within the directory alphabetically.

autoload path(+DirAlias)
Add DirAlias to the libraries that are used by the autoloader. This extends the search path
autoload and reloads the library index. For example:

:- autoload_path(library(http)).

If this call appears as a directive, it is term-expanded into a clause for user:file search path/2 and
a directive calling reload library index/0. This keeps source information and allows
for removing this directive.

make library index(+Directory)

Create an index for this directory. The index is written to the file INDEX.pl in the specified
directory. Fails with a warning if the directory does not exist or is write protected.

make library index(+Directory, +ListOfPatterns)

Normally used in MKINDEX.pl, this predicate creates INDEX.pl for Directory, indexing all
files that match one of the file patterns in ListOfPatterns.
Sometimes library packages consist of one public load file and a number of files used by this
load file, exporting predicates that should not be used directly by the end user. Such a library
can be placed in a sub-directory of the library and the files containing public functionality can
be added to the index of the library. As an example we give the XPCE librarys MKINDEX.pl,
including the public functionality of trace/browse.pl to the autoloadable predicates for
the XPCE package.

:- make_library_index(.,
[ *.pl,
trace/browse.pl
]).

SWI-Prolog 7.4 Reference Manual

2.14. GARBAGE COLLECTION 49

reload library index

Force reloading the index after modifying the set of library directories by changing the rules for
library directory/1, file search path/2, adding or deleting INDEX.pl files.
This predicate does not update the INDEX.pl files. Check make library index/[1,2]
and make/0 for updating the index files.
Normally, the index is reloaded automatically if a predicate cannot be found in the index and
the set of library directories has changed. Using reload library index/0 is necessary if
directories are removed or the order of the library directories is changed.

When creating an executable using either qsave program/2 or the -c command line options,
it is necessarry to load all predicates that would normally be autoloaded explicitly. This is discussed
in section 12. See autoload/0.

2.14 Garbage Collection

SWI-Prolog provides garbage collection, last-call optimization and atom garbage collection. These
features are controlled using Prolog flags (see current prolog flag/2).

2.15 The SWI-Prolog syntax

SWI-Prolog syntax is close to ISO-Prolog standard syntax, which is based on the Edinburgh Pro-
log syntax. A formal description can be found in the ISO standard document. For an informal
introduction we refer to Prolog text books (see section 1) and [online tutorials]http://www.swi-
prolog.org/Links.html. In addition to the differences from the ISO standard documented here, SWI-
Prolog offers several extensions, some of which also extend the syntax. See section 5 for more infor-
mation.

2.15.1 ISO Syntax Support

This section lists various extensions w.r.t. the ISO Prolog syntax.

Processor Character Set

The processor character set specifies the class of each character used for parsing Prolog source text.
Character classification is fixed to Unicode. See also section 2.18.

Nested comments
SWI-Prolog allows for nesting /* ...*/ comments. Where the ISO standard accepts
/* .../* ...*/ as a comment, SWI-Prolog will search for a terminating */. This is useful
if some code with /* ...*/ comment statements in it should be commented out. This modification
also avoids unintended commenting in the example below, where the closing */ of the first comment
has been forgotten.19
19
Recent copies of GCC give a style warning if /* is encountered in a comment, which suggests that this problem has
been recognised more widely.

SWI-Prolog 7.4 Reference Manual

50 CHAPTER 2. OVERVIEW

/* comment

code

/* second comment */

code

Character Escape Syntax

Within quoted atoms (using single quotes: <atom>) special characters are represented using es-
cape sequences. An escape sequence is led in by the backslash (\) character. The list of escape
sequences is compatible with the ISO standard but contains some extensions, and the interpretation of
numerically specified characters is slightly more flexible to improve compatibility. Undefined escape
characters raise a syntax error exception.20

\a
Alert character. Normally the ASCII character 7 (beep).

\b
Backspace character.

\c
No output. All input characters up to but not including the first non-layout character are skipped.
This allows for the specification of pretty-looking long lines. Not supported by ISO. Example:

format(This is a long line that looks better if it was \c

split across multiple physical lines in the input)

\hNEWLINEi
When in ISO mode (see the Prolog flag iso), only skip this sequence. In native mode, white
space that follows the newline is skipped as well and a warning is printed, indicating that this
construct is deprecated and advising to use \c. We advise using \c or putting the layout
before the \, as shown below. Using \c is supported by various other Prolog implementations
and will remain supported by SWI-Prolog. The style shown below is the most compatible
solution.21

format(This is a long line that looks better if it was \

split across multiple physical lines in the input)

instead of
20
Up to SWI-Prolog 6.1.9, undefined escape characters were copied verbatim, i.e., removing the backslash.
21
Future versions will interpret \hreturni according to ISO.

SWI-Prolog 7.4 Reference Manual

2.15. THE SWI-PROLOG SYNTAX 51

format(This is a long line that looks better if it was\

split across multiple physical lines in the input)

\e
Escape character (ASCII 27). Not ISO, but widely supported.

\f
Form-feed character.

\n
Next-line character.

\r
Carriage-return only (i.e., go back to the start of the line).

\s
Space character. Intended to allow writing 0\s to get the character code of the space charac-
ter. Not ISO.

\t
Horizontal tab character.

\v
Vertical tab character (ASCII 11).

\xXX..\
Hexadecimal specification of a character. The closing \ is obligatory according to the ISO
standard, but optional in SWI-Prolog to enhance compatibility with the older Edinburgh stan-
dard. The code \xa\3 emits the character 10 (hexadecimal a) followed by 3. Characters
specified this way are interpreted as Unicode characters. See also \u.

\uXXXX
Unicode character specification where the character is specified using exactly 4 hexadecimal
digits. This is an extension to the ISO standard, fixing two problems. First, where \x defines
a numeric character code, it doesnt specify the character set in which the character should be
interpreted. Second, it is not needed to use the idiosyncratic closing \ ISO Prolog syntax.

\UXXXXXXXX
Same as \uXXXX, but using 8 digits to cover the whole Unicode set.

\40
Octal character specification. The rules and remarks for hexadecimal specifications apply to
octal specifications as well.

\\
Escapes the backslash itself. Thus, \\ is an atom consisting of a single \.

\
Single quote. Note that \ and both describe the atom with a single , i.e.,
\ == is true.

SWI-Prolog 7.4 Reference Manual

52 CHAPTER 2. OVERVIEW

\"
Double quote.

\
Back quote.

Character escaping is only available if current prolog flag(character escapes, true)

is active (default). See current prolog flag/2. Character escapes conflict with writef/2
in two ways: \40 is interpreted as decimal 40 by writef/2, but as octal 40 (decimal 32)
by read. Also, the writef/2 sequence \l is illegal. It is advised to use the more widely
supported format/[2,3] predicate instead. If you insist upon using writef/2, either switch
character escapes to false, or use double \\, as in writef(\\l).

Syntax for non-decimal numbers

SWI-Prolog implements both Edinburgh and ISO representations for non-decimal numbers. Accord-
ing to Edinburgh syntax, such numbers are written as hradixi<number>, where hradixi is a number
between 2 and 36. ISO defines binary, octal and hexadecimal numbers using 0[bxo]hnumberi. For
example: A is 0b100 \/ 0xf00 is a valid expression. Such numbers are always unsigned.

Using digit groups in large integers

SWI-Prolog supports splitting long integers into digit groups. Digit groups can be separated with
the sequence hunderscorei, hoptional white spacei. If the hradixi is 10 or lower, they may also be
separated with exactly one space. The following all express the integer 1 million:

1_000_000
1 000 000
1_000_/*more*/000

Integers can be printed using this notation with format/2, using the I format specifier. For exam-
ple:

?- format(I, [1000000]).
1_000_000

The current syntax has been proposed by Ulrich Neumerkel on the SWI-Prolog mailinglist.

NaN and Infinity floats and their syntax

SWI-Prolog supports reading an printing special floating point values accord-
ing to [Proposal for Prolog Standard core update wrt floating point arith-
metic]http://eclipseclp.org/Specs/core update float.html by Joachim Schimpf and available in
ECLiPSe Prolog. In particular,

Infinity is printed as 1.0Inf or -1.0Inf. Any sequence matching the regular expression
[+-]?\sd+[.]\sd+Inf is mapped to plus or minus infinity.

SWI-Prolog 7.4 Reference Manual

2.15. THE SWI-PROLOG SYNTAX 53

NaN (Not a Number) is printed as 1.xxxNaN, where 1.xxx is the float after replacing the
exponent by 1. Such numbers are read, resulting in the same NaN. The NaN constant can also
be produced using the function nan/0, e.g.,

?- A is nan.
A = 1.5NaN.

Note that, compliant with the ISO standard, SWI-Prolog arithmetic (see section 4.27) never returns
one of the above values but instead raises an exception, e.g.,

?- A is 1/0.
ERROR: //2: Arithmetic: evaluation error: zero_divisor

There is one exception to this rule. For compatibility the functions inf/0 and nan/0 return 1.0Inf
and the default system NaN. The ability to create, read and write such values is primarily provided to
exchange data with languages that can represent the full range of IEEE doubles.

Force only underscore to introduce a variable

According to the ISO standard and most Prolog systems, identifiers that start with an uppercase letter
or an underscore are variables. In the past, Prolog by BIM provided an alternative syntax, where
only the underscore ( ) introduces a variable. As of SWI-Prolog 7.3.27 SWI-Prolog supports this
alternative syntax, controlled by the Prolog flag var prefix. As the character escapes flag,
this flag is maintained per module, where the default is false, supporting standard syntax.
Having only the underscore introduce a variable is particularly useful if code contains identifiers
for case sensitive external languages. Examples are the RDF library where code frequently specifies
property and class names22 and the R interface for specifying functions or variables that start with an
uppercase character. Lexical databases were part of the terms start with an uppercase letter is another
category were the readability of the code improves using this option.

Unicode Prolog source

The ISO standard specifies the Prolog syntax in ASCII characters. As SWI-Prolog supports Unicode
in source files we must extend the syntax. This section describes the implication for the source files,
while writing international source files is described in section 3.1.3.
The SWI-Prolog Unicode character classification is based on version 6.0.0 of the Unicode stan-
dard. Please note that char type/2 and friends, intended to be used with all text except Prolog
source code, is based on the C library locale-based classification routines.

Quoted atoms and strings

Any character of any script can be used in quoted atoms and strings. The escape sequences
\uXXXX and \UXXXXXXXX (see section 2.15.1) were introduced to specify Unicode code
points in ASCII files.
22
Samer Abdallah suggested this feature based on experience with non-Prolog users using the RDF library.

SWI-Prolog 7.4 Reference Manual

54 CHAPTER 2. OVERVIEW

Atoms and Variables

We handle them in one item as they are closely related. The Unicode standard defines a syntax
for identifiers in computer languages.23 In this syntax identifiers start with ID Start followed
by a sequence of ID Continue codes. Such sequences are handled as a single token in SWI-
Prolog. The token is a variable iff it starts with an uppercase character or an underscore ( ).
Otherwise it is an atom. Note that many languages do not have the notion of character case. In
such languages variables must be written as _name.

White space
All characters marked as separators (Z*) in the Unicode tables are handled as layout characters.

Control and unassigned characters

Control and unassigned (C*) characters produce a syntax error if encountered outside quoted
atoms/strings and outside comments.

Other characters
The first 128 characters follow the ISO Prolog standard. Unicode symbol and punctuation
characters (general category S* and P*) act as glueing symbol characters (i.e., just like ==: an
unquoted sequence of symbol characters are combined into an atom).
Other characters (this is mainly No: a numeric character of other type) are currently handled as
solo.

Singleton variable checking

A singleton variable is a variable that appears only one time in a clause. It can always be replaced
by _, the anonymous variable. In some cases, however, people prefer to give the variable a name.
As mistyping a variable is a common mistake, Prolog systems generally give a warning (controlled
by style check/1) if a variable is used only once. The system can be informed that a variable is
meant to appear once by starting it with an underscore, e.g., _Name. Please note that any variable,
except plain _, shares with variables of the same name. The term t(_X, _X) is equivalent to
t(X, X), which is different from t(_, _).
As Unicode requires variables to start with an underscore in many languages, this schema needs
to be extended.24 First we define the two classes of named variables.

Named singleton variables

Named singletons start with a double underscore (__) or a single underscore followed by an
uppercase letter, e.g., __var or _Var.

Normal variables
All other variables are normal variables. Note this makes _var a normal variable.25

Any normal variable appearing exactly once in the clause and any named singleton variables
appearing more than once are reported. Below are some examples with warnings in the right column.
Singleton messages can be suppressed using the style check/1 directive.
23
http://www.unicode.org/reports/tr31/
24
After a proposal by Richard OKeefe.
25
Some Prolog dialects write variables this way.

SWI-Prolog 7.4 Reference Manual

2.16. RATIONAL TREES (CYCLIC TERMS) 55

test( ).
test( a). Singleton variables: [ a]
test( 12). Singleton variables: [ 12]
test(A). Singleton variables: [A]
test( A).
test( a).
test( , ).
test( a, a).
test( a, a). Singleton-marked variables appearing more than once: [ a]
test( A, A). Singleton-marked variables appearing more than once: [ A]
test(A, A).

Semantic singletons Starting with version 6.5.1, SWI-Prolog has syntactic singletons and seman-
tic singletons. The first are checked by read clause/3 (and read term/3 using the option
singletons(warning)). The latter are generated by the compiler for variables that appear alone in
a branch. For example, in the code below the variable X is not a syntactic singleton, but the variable
X does not communicate any bindings and replacing X with does not change the semantics.

test :-
( test_1(X)
; test_2(X)
).

2.16 Rational trees (cyclic terms)

SWI-Prolog supports rational trees, also known as cyclic terms. Supports is so de-
fined that most relevant built-in predicates terminate when faced with rational trees. Al-
most all SWI-Prologs built-in term manipulation predicates process terms in a time that is
linear to the amount of memory used to represent the term on the stack. The follow-
ing set of predicates safely handles rational trees: =../2, ==/2, =@=/2, =/2, @</2,
@=</2, @>=/2, @>/2, \==/2, \=@=/2, \=/2, acyclic term/1, bagof/3, compare/3,
copy term/2, cyclic term/1, dif/2, duplicate term/2, findall/3, ground/1,
term hash/2, numbervars/3, numbervars/4, recorda/3, recordz/3, setof/3,
subsumes term/2, term variables/2, throw/1, unify with occurs check/2,
unifiable/3, when/2, write/1 (and related predicates) .
In addition, some built-ins recognise rational trees and raise an appropriate exception. Arithmetic
evaluation belongs to this group. The compiler (asserta/1, etc.) also raises an exception. Future
versions may support rational trees. Predicates that could provide meaningful processing of rational
trees raise a representation error. Predicates for which rational trees have no meaningful
interpretation raise a type error. For example:

1 ?- A = f(A), asserta(a(A)).
ERROR: asserta/1: Cannot represent due to cyclic_term
2 ?- A = 1+A, B is A.

SWI-Prolog 7.4 Reference Manual

56 CHAPTER 2. OVERVIEW

ERROR: is/2: Type error: expression expected, found

@(S_1,[S_1=1+S_1]) (cyclic term)

2.17 Just-in-time clause indexing

SWI-Prolog provides just-in-time indexing over multiple arguments.26 Just-in-time means that
clause indexes are not built by the compiler (or asserta/1 for dynamic predicates), but on the
first call to such a predicate where an index might help (i.e., a call where at least one argument is
instantiated). This section describes the rules used by the indexing logic. Note that this logic is not
set in stone. The indexing capabilities of the system will change. Although this inevitably leads to
some regressing on some particular use cases, we strive to avoid significant slowdowns.
The list below describes the clause selection process for various predicates and calls. The alterna-
tives are considered in the order they are presented.

Special purpose code

Currently two special cases are recognised by the compiler: static code with exactly one clause
and static code with two clauses, one where the first argument is the empty list ([]) and one
where the first argument is a non-empty list ([_|_]).

Linear scan on first argument

The principal clause list maintains a key for the first argument. An indexing key is either a
constant or a functor (name/arity reference). Calls with an instantiated first argument and less
than 10 clauses perform a linear scan for a possible matching clause using this index key.

Hash lookup
If none of the above applies, the system considers the available hash tables for which the corre-
sponding argument is instantiated. If a table is found with acceptable characteristics, it is used.
Otherwise, there are two cases. First, if no hash table is available for the instantiated arguments,
it assesses the clauses for all instantiated arguments and selects the best candidate for creating
a hash table. Arguments that cannot be indexed are flagged to avoid repeated scanning. Sec-
ond, if there is a hash table for an indexed argument but it has poor characteristics, the system
scans other instantiated arguments to see whether it can create a better hash table. The system
maintains a bit vector on each table in which it marks arguments that are less suitable than the
argument to which the table belongs.
Clauses that have a variable at an otherwise indexable argument must be linked into all hash
buckets. Currently, predicates that have more than 10% such clauses for a specific argument are
not considered for indexing on that argument.
Disregarding variables, the suitability of an argument for hashing is expressed as the number of
unique indexable values divided by the standard deviation of the number of duplicate values for
each value plus one.27
The indexes of dynamic predicates are deleted if the number of clauses is doubled since
its creation or reduced below 1/4th. The JIT approach will recreate a suitable index on
26
JIT indexing was added in version 5.11.29 (Oct. 2011).
27
Earlier versions simply used the number of unique values, but poor distribution of values makes a table less suitable.
This was analysed by Fabien Noth and Gunter Kniesel.

SWI-Prolog 7.4 Reference Manual

2.18. WIDE CHARACTER SUPPORT 57

the next call. Indexes of running predicates cannot be deleted. They are added to a re-
moved index list associated to the predicate. Outdated indexes of predicates are reclaimed
by garbage collect clauses/0. The clause garbage collector is scheduled automati-
cally, based on time and space based heuristics. See garbage collect clauses/0 for
details.

2.17.1 Future directions

The current indexing system is largely prepared for secondary indexes. This implies that if there
are many clauses that match a given key, the system could (JIT) create a secondary index. This
secondary index could exploit another argument or, if the key denotes a functor, an argument
inside the compound term.
The special cases can be extended. This is notably attractive for static predicates with a
relatively small number of clauses where a hash lookup is too costly.

2.17.2 Indexing and portability

The base-line functionality of Prolog implementations provides indexing on constants and functor
(name/arity) on the first argument. This must be your assumption if wide portability of your program
is important. This can typically be achieved by exploiting term hash/2 or term hash/4 and/or
maintaining multiple copies of a predicate with reordered arguments and wrappers that update all
implementations (assert/retract) and selects the appropriate implementation (query).
YAP provides full JIT indexing, including indexing arguments of compound terms. YAPs index-
ing has been the inspiration for enhancing SWI-Prologs indexing capabilities.

2.18 Wide character support

SWI-Prolog supports wide characters, characters with character codes above 255 that cannot be rep-
resented in a single byte. Universal Character Set (UCS) is the ISO/IEC 10646 standard that specifies
a unique 31-bit unsigned integer for any character in any language. It is a superset of 16-bit Unicode,
which in turn is a superset of ISO 8859-1 (ISO Latin-1), a superset of US-ASCII. UCS can handle
strings holding characters from multiple languages, and character classification (uppercase, lowercase,
digit, etc.) and operations such as case conversion are unambiguously defined.
For this reason SWI-Prolog has two representations for atoms and string objects (see section 5.2).
If the text fits in ISO Latin-1, it is represented as an array of 8-bit characters. Otherwise the text is
represented as an array of 32-bit numbers. This representational issue is completely transparent to the
Prolog user. Users of the foreign language interface as described in chapter 11 sometimes need to be
aware of these issues though.
Character coding comes into view when characters of strings need to be read from or written to
file or when they have to be communicated to other software components using the foreign language
interface. In this section we only deal with I/O through streams, which includes file I/O as well as I/O
through network sockets.

2.18.1 Wide character encodings on streams

Although characters are uniquely coded using the UCS standard internally, streams and files are byte
(8-bit) oriented and there are a variety of ways to represent the larger UCS codes in an 8-bit octet

SWI-Prolog 7.4 Reference Manual

58 CHAPTER 2. OVERVIEW

stream. The most popular one, especially in the context of the web, is UTF-8. Bytes 0 . . . 127
represent simply the corresponding US-ASCII character, while bytes 128 . . . 255 are used for multi-
byte encoding of characters placed higher in the UCS space. Especially on MS-Windows the 16-bit
Unicode standard, represented by pairs of bytes, is also popular.
Prolog I/O streams have a property called encoding which specifies the used encoding that influ-
ences get code/2 and put code/2 as well as all the other text I/O predicates.
The default encoding for files is derived from the Prolog flag encoding, which is initialised
from the environment. If the environment variable LANG ends in UTF-8, this encoding is as-
sumed. Otherwise the default is text and the translation is left to the wide-character functions
of the C library.28 The encoding can be specified explicitly in load files/2 for loading Prolog
source with an alternative encoding, open/4 when opening files or using set stream/2 on any
open stream. For Prolog source files we also provide the encoding/1 directive that can be used
to switch between encodings that are compatible with US-ASCII (ascii, iso latin 1, utf8
and many locales). See also section 3.1.3 for writing Prolog files with non-US-ASCII characters
and section 2.15.1 for syntax issues. For additional information and Unicode resources, please visit
http://www.unicode.org/.
SWI-Prolog currently defines and supports the following encodings:

octet
Default encoding for binary streams. This causes the stream to be read and written fully
untranslated.

ascii
7-bit encoding in 8-bit bytes. Equivalent to iso latin 1, but generates errors and warnings
on encountering values above 127.

iso latin 1
8-bit encoding supporting many Western languages. This causes the stream to be read and
written fully untranslated.

text
C library default locale encoding for text files. Files are read and written using the C library
functions mbrtowc() and wcrtomb(). This may be the same as one of the other locales, notably
it may be the same as iso latin 1 for Western languages and utf8 in a UTF-8 context.

utf8
Multi-byte encoding of full UCS, compatible with ascii. See above.

unicode be
Unicode Big Endian. Reads input in pairs of bytes, most significant byte first. Can only repre-
sent 16-bit characters.

unicode le
Unicode Little Endian. Reads input in pairs of bytes, least significant byte first. Can only
represent 16-bit characters.

Note that not all encodings can represent all characters. This implies that writing text to a stream
may cause errors because the stream cannot represent these characters. The behaviour of a stream
28
The Prolog native UTF-8 mode is considerably faster than the generic mbrtowc() one.

SWI-Prolog 7.4 Reference Manual

2.19. SYSTEM LIMITS 59

on these errors can be controlled using set stream/2. Initially the terminal stream writes the
characters using Prolog escape sequences while other streams generate an I/O exception.

BOM: Byte Order Mark

From section 2.18.1, you may have got the impression that text files are complicated. This section
deals with a related topic, making life often easier for the user, but providing another worry to the
programmer. BOM or Byte Order Marker is a technique for identifying Unicode text files as well as
the encoding they use. Such files start with the Unicode character 0xFEFF, a non-breaking, zero-width
space character. This is a pretty unique sequence that is not likely to be the start of a non-Unicode
file and uniquely distinguishes the various Unicode file formats. As it is a zero-width blank, it even
doesnt produce any output. This solves all problems, or . . .
Some formats start off as US-ASCII and may contain some encoding mark to switch to UTF-8,
such as the encoding="UTF-8" in an XML header. Such formats often explicitly forbid the use
of a UTF-8 BOM. In other cases there is additional information revealing the encoding, making the
use of a BOM redundant or even illegal.
The BOM is handled by SWI-Prolog open/4 predicate. By default, text files are probed for the
BOM when opened for reading. If a BOM is found, the encoding is set accordingly and the property
bom(true) is available through stream property/2. When opening a file for writing, writing a
BOM can be requested using the option bom(true) with open/4.

2.19 System limits

2.19.1 Limits on memory areas
SWI-Prolog has a number of memory areas which are only enlarged to a certain limit. The internal
data representation limits the local, global and trail stack to 128 MB on 32-bit processors, or more
generally to 2bits-per-pointer5 bytes. Considering that almost all modern hardware can deal with
this amount of memory with ease, the default limits are set to their maximum on 32-bit hardware.
The representation limits can easily exceed physical memory on 64-bit hardware. The default limits
on 64-bit hardware are double that of 32-bit hardware, which allows for storing the same amount of
(Prolog) data.
The limits can be changed from the command line as well as at runtime using
set prolog stack/2. The table below shows these areas. The first column gives the option
name to modify the size of the area. The option character is immediately followed by a number and
optionally by a k or m. With k or no unit indicator, the value is interpreted in Kbytes (1024 bytes);
with m, the value is interpreted in Mbytes (1024 1024 bytes).
The PrologScript facility described in section 2.10.2 provides a mechanism for specifying options
with the load file. On Windows the default stack sizes are controlled using the Windows registry
on the key HKEY_CURRENT_USER\Software\SWI\Prolog using the names localSize,
globalSize and trailSize. The value is a DWORD expressing the default stack size in Kbytes.
A GUI for modifying these values is provided using the XPCE package. To use this, start the XPCE
manual tools using manpce/0, after which you find Preferences in the File menu.
Considering portability, applications that need to modify the default limits are advised to do so
using set prolog stack/2.

SWI-Prolog 7.4 Reference Manual

60 CHAPTER 2. OVERVIEW

Option Default Area name Description

-L 128M local stack The local stack is used to store
the execution environments of
procedure invocations. The
space for an environment is re-
claimed when it fails, exits with-
out leaving choice points, the al-
ternatives are cut off with the
!/0 predicate or no choice points
have been created since the invo-
cation and the last subclause is
started (last call optimisation).
-G 128M global stack The global stack is used to store
terms created during Prologs
execution. Terms on this stack
will be reclaimed by backtrack-
ing to a point before the term
was created or by garbage col-
lection (provided the term is no
longer referenced).
-T 128M trail stack The trail stack is used to store as-
signments during execution. En-
tries on this stack remain alive
until backtracking before the
point of creation or the garbage
collector determines they are no
longer needed.

Table 2.2: Memory areas

SWI-Prolog 7.4 Reference Manual

2.19. SYSTEM LIMITS 61

The heap

With the heap, we refer to the memory area used by malloc() and friends. SWI-Prolog uses the area
to store atoms, functors, predicates and their clauses, records and other dynamic data. No limits are
imposed on the addresses returned by malloc() and friends.

2.19.2 Other Limits

Clauses The only limit on clauses is their arity (the number of arguments to the head), which is
limited to 1024. Raising this limit is easy and relatively cheap; removing it is harder.

Atoms and Strings SWI-Prolog has no limits on the sizes of atoms and strings. read/1 and its
derivatives, however, normally limit the number of newlines in an atom or string to 6 to improve
error detection and recovery. This can be switched off with style check/1.
The number of atoms is limited to 16777216 (16M) on 32-bit machines. On 64-bit machines
this is virtually unlimited. See also section 11.4.2.

Memory areas On 32-bit hardware, SWI-Prolog data is packed in a 32-bit word, which contains both
type and value information. The size of the various memory areas is limited to 128 MB for each
of the areas, except for the program heap, which is not limited. On 64-bit hardware there are no
meaningful limits.

Nesting of terms Most built-in predicates that process Prolog terms create an explicitly managed
stack and perform optimization for processing the last argument of a term. This implies they
can process deeply nested terms at constant and low usage of the C stack, and the system raises
a resource error if no more stack can be allocated. Currently only read/1 and write/1 (and
all variations thereof) still use the C stack and may cause the system to crash in an uncontrolled
way (i.e., not mapped to a Prolog exception that can be caught).

Integers On most systems SWI-Prolog is compiled with support for unbounded integers by means of
the GNU GMP library. In practice this means that integers are bound by the global stack size.
Too large integers cause a resource error. On systems that lack GMP, integers are 64-bit
on 32- as well as 64-bit machines.
Integers up to the value of the max tagged integer Prolog flag are represented
more efficiently on the stack. For integers that appear in clauses, the value (below
max tagged integer or not) has little impact on the size of the clause.

Floating point numbers Floating point numbers are represented as C-native double precision floats,
64-bit IEEE on most machines.

2.19.3 Reserved Names

The boot compiler (see -b option) does not support the module system. As large parts of the sys-
tem are written in Prolog itself we need some way to avoid name clashes with the users predicates,
database keys, etc. Like Edinburgh C-Prolog [Pereira, 1986] all predicates, database keys, etc., that
should be hidden from the user start with a dollar ($) sign.

SWI-Prolog 7.4 Reference Manual

62 CHAPTER 2. OVERVIEW

2.20 SWI-Prolog and 64-bit machines

Most of todays 64-bit platforms are capable of running both 32-bit and 64-bit applications. This asks
for some clarifications on the advantages and drawbacks of 64-bit addressing for (SWI-)Prolog.

2.20.1 Supported platforms

SWI-Prolog can be compiled for a 32- or 64-bit address space on any system with a suitable C com-
piler. Pointer arithmetic is based on the type (u)intptr t from stdint.h, with suitable emulation on
MS-Windows.

2.20.2 Comparing 32- and 64-bits Prolog

Most of Prologs memory usage consists of pointers. This indicates the primary drawback: Prolog
memory usage almost doubles when using the 64-bit addressing model. Using more memory means
copying more data between CPU and main memory, slowing down the system.
What then are the advantages? First of all, SWI-Prologs addressing of the Prolog stacks does not
cover the whole address space due to the use of type tag bits and garbage collection flags. On 32-bit
hardware the stacks are limited to 128 MB each. This tends to be too low for demanding applications
on modern hardware. On 64-bit hardware the limit is 232 times higher, exceeding the addressing
capabilities of todays CPUs and operating systems. This implies Prolog can be started with stack
sizes that use the full capabilities of your hardware.
Multi-threaded applications profit much more because every thread has its own set of stacks. The
Prolog stacks start small and are dynamically expanded (see section 2.19.1). The C stack is also
dynamically expanded, but the maximum size is reserved when a thread is started. Using 100 threads
at the maximum default C stack of 8Mb (Linux) costs 800Mb virtual memory!29
The implications of theoretical performance loss due to increased memory bandwidth implied by
exchanging wider pointers depend on the design of the hardware. We only have data for the popular
IA32 vs. AMD64 architectures. Here, it appears that the loss is compensated for by an instruction set
that has been optimized for modern programming. In particular, the AMD64 has more registers and
the relative addressing capabilities have been improved. Where we see a 10% performance degra-
dation when placing the SWI-Prolog kernel in a Unix shared object, we cannot find a measurable
difference on AMD64.

2.20.3 Choosing between 32- and 64-bit Prolog

For those cases where we can choose between 32 and 64 bits, either because the hardware and OS
support both or because we can still choose the hardware and OS, we give guidelines for this decision.
First of all, if SWI-Prolog needs to be linked against 32- or 64-bit native libraries, there is no
choice as it is not possible to link 32- and 64-bit code into a single executable. Only if all required
libraries are available in both sizes and there is no clear reason to use either do the different character-
istics of Prolog become important.
Prolog applications that require more than the 128 MB stack limit provided in 32-bit addressing
mode must use the 64-bit edition. Note however that the limits must be doubled to accommodate the
same Prolog application.
29
C-recursion over Prolog data structures is removed from most of SWI-Prolog. When removed from all predicates it
will often be possible to use lower limits in threads. See http://www.swi-prolog.org/Devel/CStack.html

SWI-Prolog 7.4 Reference Manual

2.20. SWI-PROLOG AND 64-BIT MACHINES 63

If the system is tight on physical memory, 32-bit Prolog has the clear advantage of using only
slightly more than half of the memory of 64-bit Prolog. This argument applies as long as the applica-
tion fits in the virtual address space of the machine. The virtual address space of 32-bit hardware is
4GB, but in many cases the operating system provides less to user applications.
The only standard SWI-Prolog library adding significantly to this calculation is the RDF database
provided by the semweb package. It uses approximately 80 bytes per triple on 32-bit hardware and
150 bytes on 64-bit hardware. Details depend on how many different resources and literals appear in
the dataset as well as desired additional literal indexes.
Summarizing, if applications are small enough to fit comfortably in virtual and physical memory,
simply take the model used by most of the applications on the OS. If applications require more than
128 MB per stack, use the 64-bit edition. If applications approach the size of physical memory, fit
in the 128 MB stack limit and fit in virtual memory, the 32-bit version has clear advantages. For
demanding applications on 64-bit hardware with more than about 6GB physical memory the 64-bit
model is the model of choice.

SWI-Prolog 7.4 Reference Manual

Initialising and Managing a
Prolog Project 3
Prolog text-books give you an overview of the Prolog language. The manual tells you what predicates
are provided in the system and what they do. This chapter explains how to run a project. There is
no ultimate right way to do this. Over the years we developed some practice in this area and SWI-
Prologs commands are there to support this practice. This chapter describes the conventions and
supporting commands.
The first two sections (section 3.1 and section 3.2) only require plain Prolog. The remainder
discusses the use of the built-in graphical tools that require the XPCE graphical library installed on
your system.

3.1 The project source files

Organisation of source files depends largely on the size of your project. If you are doing exercises for
a Prolog course youll normally use one file for each exercise. If you have a small project youll work
with one directory holding a couple of files and some files to link it all together. Even bigger projects
will be organised in sub-projects, each using its own directory.

3.1.1 File Names and Locations

File Name Extensions
The first consideration is what extension to use for the source files. Tradition calls for
.pl, but conflicts with Perl force the use of another extension on systems where ex-
tensions have global meaning, such as MS-Windows. On such systems .pro is the
common alternative. On MS-Windows, the alternative extension is stored in the reg-
istry key HKEY CURRENT USER/Software/SWI/Prolog/fileExtension or
HKEY LOCAL MACHINE/Software/SWI/Prolog/fileExtension. All versions of
SWI-Prolog load files with the extension .pl as well as with the registered alternative extension
without explicitly specifying the extension. For portability reasons we propose the following
convention:
If there is no conflict because you do not use a conflicting application or the system does not force
a unique relation between extension and application, use .pl.
With a conflict choose .pro and use this extension for the files you want to load through your file
manager. Use .pl for all other files for maximal portability.

Project Directories
Large projects are generally composed of sub-projects, each using its own directory or directory struc-
ture. If nobody else will ever touch your files and you use only one computer, there is little to worry

SWI-Prolog 7.4 Reference Manual

3.1. THE PROJECT SOURCE FILES 65

about, but this is rarely the case with a large project.

To improve portability, SWI-Prolog uses the POSIX notation for filenames, which uses the
forward slash (/) to separate directories. Just before reaching the file system, SWI-Prolog uses
prolog to os filename/2 to convert the filename to the conventions used by the hosting oper-
ating system. It is strongly advised to write paths using the /, especially on systems using the \ for
this purpose (MS-Windows). Using \ violates the portability rules and requires you to double the \
due to the Prolog quoted-atom escape rules.
Portable code should use prolog to os filename/2 to convert computed paths into system
paths when constructing commands for shell/1 and friends.

Sub-projects using search paths

Thanks to Quintus, Prolog adapted an extensible mechanism for searching files using
file search path/2. This mechanism allows for comfortable and readable specifications.
Suppose you have extensive library packages on graph algorithms, set operations and GUI primi-
tives. These sub-projects are likely candidates for re-use in future projects. A good choice is to create
a directory with sub-directories for each of these sub-projects.
Next, there are three options. One is to add the sub-projects to the directory hierarchy of the
current project. Another is to use a completely dislocated directory. Third, the sub-project can be
added to the SWI-Prolog hierarchy. Using local installation, a typical file search path/2 is:

:- prolog_load_context(directory, Dir),
asserta(user:file_search_path(myapp, Dir)).

user:file_search_path(graph, myapp(graph)).
user:file_search_path(ui, myapp(ui)).

When using sub-projects in the SWI-Prolog hierarchy, one should use the path alias swi as basis. For
a system-wide installation, use an absolute path.
Extensive sub-projects with a small well-defined API should define a load file with calls to
use module/1 to import the various library components and export the API.

3.1.2 Project Special Files

There are a number of tasks you typically carry out on your project, such as loading it, creating a
saved state, debugging it, etc. Good practice on large projects is to define small files that hold the
commands to execute such a task, name this file after the task and give it a file extension that makes
starting easy (see section 3.1.1). The task load is generally central to these tasks. Here is a tentative
list:

load.pl
Use this file to set up the environment (Prolog flags and file search paths) and load the sources.
Quite commonly this file also provides convenient predicates to parse command line options
and start the application.

run.pl
Use this file to start the application. Normally it loads load.pl in silent-mode, and calls one
of the starting predicates from load.pl.

SWI-Prolog 7.4 Reference Manual

66 CHAPTER 3. INITIALISING AND MANAGING A PROLOG PROJECT

save.pl
Use this file to create a saved state of the application by loading load.pl and calling
qsave program/2 to generate a saved state with the proper options.

debug.pl
Loads the program for debugging. In addition to loading load.pl this file defines rules for
portray/1 to modify printing rules for complex terms and customisation rules for the debug-
ger and editing environment. It may start some of these tools.

3.1.3 International source files

As discussed in section 2.18, SWI-Prolog supports international character handling. Its internal en-
coding is UNICODE. I/O streams convert to/from this internal format. This section discusses the
options for source files not in US-ASCII.
SWI-Prolog can read files in any of the encodings described in section 2.18. Two encodings are of
particular interest. The text encoding deals with the current locale, the default used by this computer
for representing text files. The encodings utf8, unicode le and unicode be are UNICODE
encodings: they can representin the same filecharacters of virtually any known language. In
addition, they do so unambiguously.
If one wants to represent non US-ASCII text as Prolog terms in a source file, there are several
options:

Use escape sequences

This approach describes NON-ASCII as sequences of the form \octal\. The numerical argu-
ment is interpreted as a UNICODE character.1 The resulting Prolog file is strict 7-bit US-ASCII,
but if there are many NON-ASCII characters it becomes very unreadable.

Use local conventions

Alternatively the file may be specified using local conventions, such as the EUC encoding for
Japanese text. The disadvantage is portability. If the file is moved to another machine, this
machine must use the same locale or the file is unreadable. There is no elegant way if files from
multiple locales must be united in one application using this technique. In other words, it is fine
for local projects in countries with uniform locale conventions.

Using UTF-8 files

The best way to specify source files with many NON-ASCII characters is definitely the use of
UTF-8 encoding. Prolog can be notified of this encoding in two ways, using a UTF-8 BOM (see
section 2.18.1) or using the directive :- encoding(utf8). Many of todays text editors,
including PceEmacs, are capable of editing UTF-8 files. Projects that were started using local
conventions can be re-coded using the Unix iconv tool or often using commands offered by
the editor.

3.2 Using modules

Modules have been debated fiercely in the Prolog world. Despite all counter-arguments we feel they
are extremely useful because:
1
To my knowledge, the ISO escape sequence is limited to 3 octal digits, which means most characters cannot be repre-
sented.

SWI-Prolog 7.4 Reference Manual

3.3. THE TEST-EDIT-RELOAD CYCLE 67

They hide local predicates

This is the reason they were invented in the first place. Hiding provides two features. They
allow for short predicate names without worrying about conflicts. Given the flat name-space in-
troduced by modules, they still require meaningful module names as well as meaningful names
for exported predicates.

They document the interface

Possibly more important than avoiding name conflicts is their role in documenting which part
of the file is for public usage and which is private. When editing a module you may assume you
can reorganise anything except the name and the semantics of the exported predicates without
worrying.

They help the editor

The PceEmacs built-in editor does on-the-fly cross-referencing of the current module, colouring
predicates based on their origin and usage. Using modules, the editor can quickly find out what
is provided by the imported modules by reading just the first term. This allows it to indicate in
real-time which predicates are not used or not defined.

Using modules is generally easy. Only if you write meta-predicates (predicates reasoning about
other predicates) that are exported from a module is a good understanding required of the resolution
of terms to predicates inside a module. Here is a typical example from readutil.

:- module(read_util,
[ read_line_to_codes/2, % +Fd, -Codes
read_line_to_codes/3, % +Fd, -Codes, ?Tail
read_stream_to_codes/2, % +Fd, -Codes
read_stream_to_codes/3, % +Fd, -Codes, ?Tail
read_file_to_codes/3, % +File, -Codes, +Options
read_file_to_terms/3 % +File, -Terms, +Options
]).

3.3 The test-edit-reload cycle

SWI-Prolog does not enforce the use of a particular editor for writing Prolog source code. Editors are
complicated programs that must be mastered in detail for real productive programming. If you are
familiar with a specific editor you should not be forced to change. You may specify your favourite
editor using the Prolog flag editor, the environment variable EDITOR or by defining rules for
prolog edit:edit source/1.
The use of a built-in editor, which is selected by setting the Prolog flag editor to pce emacs,
has advantages. The XPCE editor object, around which the built-in PceEmacs is built, can be opened
as a Prolog stream allowing analysis of your source by the real Prolog system.

3.3.1 Locating things to edit

The central predicate for editing something is edit/1, an extensible front-end that searches for
objects (files, predicates, modules, as well as XPCE classes and methods) in the Prolog database.

SWI-Prolog 7.4 Reference Manual

68 CHAPTER 3. INITIALISING AND MANAGING A PROLOG PROJECT

If multiple matches are found it provides a choice. Together with the built-in completion on atoms
bound to the TAB key this provides a quick way to edit objects:

?- edit(country).
Please select item to edit:

1 chat:country/10 /staff/jan/lib/prolog/chat/countr.pl:16
2 chat:country/1 /staff/jan/lib/prolog/chat/world0.pl:72

Your choice?

3.3.2 Editing and incremental compilation

One of the nice features of Prolog is that the code can be modified while the program is running.
Using pure Prolog you can trace a program, find it is misbehaving, enter a break environment, modify
the source code, reload it and finally do retry on the misbehaving predicate and try again. This
sequence is not uncommon for long-running programs. For faster programs one will normally abort
after understanding the misbehaviour, edit the source, reload it and try again.
One of the nice features of SWI-Prolog is the availability of make/0, a simple predicate that
checks all loaded source files to see which ones you have modified. It then reloads these files, consid-
ering the module from which the file was loaded originally. This greatly simplifies the trace-edit-verify
development cycle. For example, after the tracer reveals there is something wrong with prove/3,
you do:

?- edit(prove).

Now edit the source, possibly switching to other files and making multiple changes. After finishing,
invoke make/0, either through the editor UI (Compile/Make (Control-C Control-M)) or on
the top level, and watch the files being reloaded.2

?- make.
% show compiled into photo_gallery 0.03 sec, 3,360 bytes

3.4 Using the PceEmacs built-in editor

3.4.1 Activating PceEmacs
Initially edit/1 uses the editor specified in the EDITOR environment variable. There are two ways
to force it to use the built-in editor. One is to set the Prolog flag editor to pce emacs and the
other is by starting the editor explicitly using the emacs/[0,1] predicates.
2
Watching these files is a good habit. If expected files are not reloaded you may have forgotten to save them from the
editor or you may have been editing the wrong file (wrong directory).

SWI-Prolog 7.4 Reference Manual

3.4. USING THE PCEEMACS BUILT-IN EDITOR 69

3.4.2 Bluffing through PceEmacs

PceEmacs closely mimics Richard Stallmans GNU-Emacs commands, adding features from modern
window-based editors to make it more acceptable for beginners.3
At the basis, PceEmacs maps keyboard sequences to methods defined on the extended editor
object. Some frequently used commands are, with their key-binding, presented in the menu bar above
each editor window. A complete overview of the bindings for the current mode is provided through
Help/Show key bindings (Control-h Control-b).

Edit modes
Modes are the heart of (Pce)Emacs. Modes define dedicated editing support for a particular kind of
(source) text. For our purpose we want Prolog mode. There are various ways to make PceEmacs use
Prolog mode for a file.

Using the proper extension

If the file ends in .pl or the selected alternative (e.g. .pro) extension, Prolog mode is selected.

Using #!/path/to/.../swipl
If the file is a Prolog Script file, starting with the line #!/path/to/swipl options, Prolog
mode is selected regardless of the extension.

Using -*- Prolog -*-

If the above sequence appears in the first line of the file (inside a Prolog comment) Prolog mode
is selected.

Explicit selection
Finally, using File/Mode/Prolog you can switch to Prolog mode explicitly.

Frequently used editor commands

Below we list a few important commands and how to activate them.

Cut/Copy/Paste
These commands follow Unix/X11 traditions. Youre best suited with a three-button mouse.
After selecting using the left-mouse (double-click uses word-mode and triple line-mode), the
selected text is automatically copied to the clipboard (X11 primary selection on Unix). Cut is
achieved using the DEL key or by typing something else at the location. Paste is achieved using
the middle-mouse (or wheel) button. If you dont have a middle-mouse button, pressing the
left- and right-button at the same time is interpreted as a middle-button click. If nothing helps,
there is the Edit/Paste menu entry. Text is pasted at the caret location.

Undo
Undo is bound to the GNU-Emacs Control- as well as the MS-Windows Control-Z sequence.

Abort
Multi-key sequences can be aborted at any stage using Control-G.
3
Decent merging with MS-Windows control-key conventions is difficult as many conflict with GNU-Emacs. Especially
the cut/copy/paste commands conflict with important GNU-Emacs commands.

SWI-Prolog 7.4 Reference Manual

70 CHAPTER 3. INITIALISING AND MANAGING A PROLOG PROJECT

Find
Find (Search) is started using Control-S (forward) or Control-R (backward). PceEmacs imple-
ments incremental search. This is difficult to use for novices, but very powerful once you get
the clue. After one of the above start keys, the system indicates search mode in the status line.
As you are typing the search string, the system searches for it, extending the search with every
character you type. It illustrates the current match using a green background.
If the target cannot be found, PceEmacs warns you and no longer extends the search string.4
During search, some characters have special meaning. Typing anything but these characters
commits the search, re-starting normal edit mode. Special commands are:

Control-S
Search forwards for next.
Control-R
Search backwards for next.
Control-W
Extend search to next word boundary.
Control-G
Cancel search, go back to where it started.
ESC
Commit search, leaving caret at found location.
Backspace
Remove a character from the search string.

Dynamic Abbreviation
Also called dabbrev, dynamic abbreviation is an important feature of Emacs clones to support
programming. After typing the first few letters of an identifier, you may press Alt-/, causing
PceEmacs to search backwards for identifiers that start the same and use it to complete the text
you typed. A second Alt-/ searches further backwards. If there are no hits before the caret, it
starts searching forwards. With some practice, this system allows for entering code very fast
with nice and readable identifiers (or other difficult long words).

Open (a file)
Is called File/Find file (Control-x Control-f). By default the file is loaded into the
current window. If you want to keep this window, press Alt-s or click the little icon at the
bottom left to make the window sticky.

Split view
Sometimes you want to look at two places in the same file. To do this, use Control-x 2 to create
a new window pointing to the same file. Do not worry, you can edit as well as move around in
both. Control-x 1 kills all other windows running on the same file.

These are the most commonly used commands. In section 3.4.3 we discuss specific support for
dealing with Prolog source code.
4
GNU-Emacs keeps extending the string, but why? Adding more text will not make it match.

SWI-Prolog 7.4 Reference Manual

3.4. USING THE PCEEMACS BUILT-IN EDITOR 71

3.4.3 Prolog Mode

In the previous section (section 3.4.2) we explained the basics of PceEmacs. Here we continue with
Prolog-specific functionality. Possibly the most interesting is Syntax highlighting. Unlike most editors
where this is based on simple patterns, PceEmacs syntax highlighting is achieved by Prolog itself ac-
tually reading and interpreting the source as you type it. There are three moments at which PceEmacs
checks (part of) the syntax.

After typing a .
After typing a . that is not preceded by a symbol character, the system assumes you completed
a clause, tries to find the start of this clause and verifies the syntax. If this process succeeds it
colours the elements of the clause according to the rules given below. Colouring is done using
information from the last full check on this file. If it fails, the syntax error is displayed in the
status line and the clause is not coloured.

After the command Control-c Control-s

Acronym for Check Syntax, it performs the same checks as above for the clause surrounding
the caret. On a syntax error, however, the caret is moved to the expected location of the error.5

After pausing for two seconds

After a short pause (2 seconds), PceEmacs opens the edit buffer and reads it as a whole, creating
an index of defined, called, dynamic, imported and exported predicates. After completing this,
it re-reads the file and colours all clauses and calls with valid syntax.

After typing Control-l Control-l

The Control-l command re-centers the window (scrolls the window to make the caret the center
of the window). Typing this command twice starts the same process as above.

The colour schema itself is defined in emacs/prolog colour. The colouring can be extended
and modified using multifile predicates. Please check this source file for details. In general, underlined
objects have a popup (right-mouse button) associated with common commands such as viewing the
documentation or source. Bold text is used to indicate the definition of objects (typically predicates
when using plain Prolog). Other colours follow intuitive conventions. See table 3.4.3.

Layout support Layout is not just nice, it is essential for writing readable code. There is much
debate on the proper layout of Prolog. PceEmacs, being a rather small project, supports only one
particular style for layout.6 Below are examples of typical constructs.

head(arg1, arg2).

head(arg1, arg2) :- !.

head(Arg1, arg2) :- !,
call1(Arg1).

head(Arg1, arg2) :-
5
In most cases the location where the parser cannot proceed is further down the file than the actual error location.
6
Defined in Prolog in the file emacs/prolog mode, you may wish to extend this. Please contribute your extensions!

SWI-Prolog 7.4 Reference Manual

72 CHAPTER 3. INITIALISING AND MANAGING A PROLOG PROJECT

Clauses
Blue bold Head of an exported predicate
Red bold Head of a predicate that is not called
Black bold Head of remaining predicates
Calls in the clause body
Blue Call to built-in or imported predicate
Red Call to undefined predicate
Purple Call to dynamic predicate
Other entities
Dark green Comment
Dark blue Quoted atom or string
Brown Variable

Table 3.1: Colour conventions

( if(Arg1)
-> then
; else
).

head(Arg1) :-
( a
; b
).

head :-
a(many,
long,
arguments(with,
many,
more),
and([ a,
long,
list,
with,
a,
| tail
])).

PceEmacs uses the same conventions as GNU-Emacs. The TAB key indents the current line according
to the syntax rules. Alt-q indents all lines of the current clause. It provides support for head, calls
(indented 1 tab), if-then-else, disjunction and argument lists broken across multiple lines as illustrated
above.

SWI-Prolog 7.4 Reference Manual

3.5. THE GRAPHICAL DEBUGGER 73

Finding your way around

The command Alt-. extracts name and arity from the caret location and jumps (after conformation
or edit) to the definition of the predicate. It does so based on the source-location database of loaded
predicates also used by edit/1. This makes locating predicates reliable if all sources are loaded and
up-to-date (see make/0).
In addition, references to files in use module/[1,2], consult/1, etc. are red if the file can-
not be found and underlined blue if the file can be loaded. A popup allows for opening the referenced
file.

3.5 The Graphical Debugger

SWI-Prolog offers two debuggers. One is the traditional text console-based 4-port Prolog tracer and
the other is a window-based source level debugger. The window-based debugger requires XPCE
installed. It operates based on the prolog trace interception/4 hook and other low-level
functionality described in chapter B.
Window-based tracing provides a much better overview due to the eminent relation to your source
code, a clear list of named variables and their bindings as well as a graphical overview of the call and
choice point stack. There are some drawbacks though. Using a textual trace on the console, one can
scroll back and examine the past, while the graphical debugger just presents a (much better) overview
of the current state.

3.5.1 Invoking the window-based debugger

Whether the text-based or window-based debugger is used is controlled using the predicates
guitracer/0 and noguitracer/0. Entering debug mode is controlled using the normal pred-
icates for this: trace/0 and spy/1. In addition, PceEmacs prolog mode provides the command
Prolog/Break at (Control-c b) to insert a break-point at a specific location in the source code.
The graphical tracer is particulary useful for debugging threads. The tracer must be loaded from
the main thread before it can be used from a background thread.

guitracer
This predicate installs the above-mentioned hooks that redirect tracing to the window-based
environment. No window appears. The debugger window appears as actual tracing is started
through trace/0, by hitting a spy point defined by spy/1 or a break point defined using the
PceEmacs command Prolog/Break at (Control-c b).

noguitracer
Disable the hooks installed by guitracer/0, reverting to normal text console-based tracing.

gtrace
Utility defined as guitracer,trace.

gdebug
Utility defined as guitracer,debug.

gspy(+Predicate)
Utility defined as guitracer,spy(Predicate).

SWI-Prolog 7.4 Reference Manual

74 CHAPTER 3. INITIALISING AND MANAGING A PROLOG PROJECT

3.6 The Prolog Navigator

Another tool is the Prolog Navigator. This tool can be started from PceEmacs using the command
Browse/Prolog navigator, from the GUI debugger or using the programmatic IDE interface de-
scribed in section 3.8.

3.7 Cross-referencer
A cross-referencer is a tool that examines the caller-callee relation between predicates, and, using this
information to explicate dependency relations between source files, finds calls to non-existing pred-
icates and predicates for which no callers can be found. Cross-referencing is useful during program
development, reorganisation, clean-up, porting and other program maintenance tasks. The dynamic
nature of Prolog makes the task non-trivial. Goals can be created dynamically using call/1 after
construction of a goal term. Abstract interpretation can find some of these calls, but they can also come
from external communication, making it impossible to predict the callee. In other words, the cross-
referencer has only partial understanding of the program, and its results are necessarily incomplete.
Still, it provides valuable information to the developer.
SWI-Prologs cross-referencer is split into two parts. The standard Prolog library prolog xref
is an extensible library for information gathering described in section A.26, and the XPCE library
pce xref provides a graphical front-end for the cross-referencer described here. We demonstrate
the tool on CHAT80, a natural language question and answer system by Fernando C.N. Pereira and
David H.D. Warren.

gxref
Run cross-referencer on all currently loaded files and present a graphical overview of the result.
As the predicate operates on the currently loaded application it must be run after loading the
application.

The left window (see figure 3.1) provides browsers for loaded files and predicates. To avoid
long file paths, the file hierarchy has three main branches. The first is the current directory hold-
ing the sources. The second is marked alias, and below it are the file-search-path aliases (see
file search path/2 and absolute file name/3). Here you find files loaded from the sys-
tem as well as modules of the program loaded from other locations using the file search path. All
loaded files that fall outside these categories are below the last branch called /. Files where the
system found suspicious dependencies are marked with an exclamation mark. This also holds for
directories holding such files. Clicking on a file opens a File info window in the right pane.
The File info window shows a file, its main properties, its undefined and not-called predicates and
its import and export relations to other files in the project. Both predicates and files can be opened
by clicking on them. The number of callers in a file for a certain predicate is indicated with a blue
underlined number. A left-click will open a list and allow editing the calling predicate.
The Dependencies (see figure 3.2) window displays a graphical overview of dependencies be-
tween files. Using the background menu a complete graph of the project can be created. It is also
possible to drag files onto the graph window and use the menu on the nodes to incrementally expand
the graph. The underlined blue text indicates the number of predicates used in the destination file.
Left-clicking opens a menu to open the definition or select one of the callers.

SWI-Prolog 7.4 Reference Manual

3.7. CROSS-REFERENCER 75

Figure 3.1: File info for chattop.pl, part of CHAT80

Figure 3.2: Dependencies between source files of CHAT80

SWI-Prolog 7.4 Reference Manual

76 CHAPTER 3. INITIALISING AND MANAGING A PROLOG PROJECT

Module and non-module files The cross-referencer threads module and non-module project files
differently. Module files have explicit import and export relations and the tool shows the usage and
consistency of the relations. Using the Header menu command, the tool creates a consistent import
list for the module that can be included in the file. The tool computes the dependency relations
between the non-module files. If the user wishes to convert the project into a module-based one,
the Header command generates an appropriate module header and import list. Note that the cross-
referencer may have missed dependencies and does not deal with meta-predicates defined in one
module and called in another. Such problems must be resolved manually.

Settings The following settings can be controlled from the settings menu:

Warn autoload
By default disabled. If enabled, modules that require predicates to be autoloaded are flagged
with a warning and the file info window of a module shows the required autoload predicates.

Warn not called

If enabled (default), the file overview shows an alert icon for files that have predicates that are
not called.

3.8 Accessing the IDE from your program

Over the years a collection of IDE components have been developed, each with its own interface.
In addition, some of these components require each other, and loading IDE components must be on
demand to avoid the IDE being part of a saved state (see qsave program/2). For this reason,
access to the IDE is concentrated on a single interface called prolog ide/1:

prolog ide(+Action)
This predicate ensures the IDE-enabling XPCE component is loaded, creates the XPCE class
prolog ide and sends Action to its one and only instance @prolog_ide. Action is one of the
following:

open navigator(+Directory)
Open the Prolog Navigator (see section 3.6) in the given Directory.
open debug status
Open a window to edit spy and trace points.
open query window
Open a little window to run Prolog queries from a GUI component.
thread monitor
Open a graphical window indicating existing threads and their status.
debug monitor
Open a graphical front-end for the debug library that provides an overview of the topics
and catches messages.
xref
Open a graphical front-end for the cross-referencer that provides an overview of predicates
and their callers.

SWI-Prolog 7.4 Reference Manual

3.9. SUMMARY OF THE IDE 77

3.9 Summary of the IDE

The SWI-Prolog development environment consists of a number of interrelated but not (yet) integrated
tools. Here is a list of the most important features and tips.

Atom completion
The console7 completes a partial atom on the TAB key and shows alternatives on the command
Alt-?.

Use edit/1 for finding locations

The command edit/1 takes the name of a file, module, predicate or other entity registered
through extensions and starts the users preferred editor at the right location.

Select editor
External editors are selected using the EDITOR environment variable, by setting the Prolog flag
editor, or by defining the hook qpredrefprolog editedit source1.

Update Prolog after editing

Using make/0, all files you have edited are re-loaded.

PceEmacs
Offers syntax highlighting and checking based on real-time parsing of the editors buffer, layout
support and navigation support.

Using the graphical debugger

The predicates guitracer/0 and noguitracer/0 switch between traditional text-based
and window-based debugging. The tracer is activated using the trace/0, spy/1 or menu
items from PceEmacs or the Prolog Navigator.

The Prolog Navigator

Shows the file structure and structure inside the file. It allows for loading files, editing, setting
spy points, etc.

7
On Windows this is realised by swipl-win.exe, on Unix through the GNU readline library, which is included automati-
cally when found by configure.

SWI-Prolog 7.4 Reference Manual

Built-in Predicates
4.1 Notation of Predicate Descriptions
4
We have tried to keep the predicate descriptions clear and concise. First, the predicate name is printed
in bold face, followed by the arguments in italics. Arguments are preceded by a mode indicator.
There is no complete agreement on mode indicators in the Prolog community. We use the following
definitions:1

++ Argument must be ground, i.e., the argument may not contain a variable
anywhere.
+ Argument must be fully instantiated to a term that satisfies the type.
This is not necessarily ground, e.g., the term [ ] is a list, although its
only member is unbound.
- Argument is an output argument. Unless specified otherwise,
output arguments need not to be unbound. For example, the
goal findall(X, Goal, [T]) is good style and equivalent to
findall(X, Goal, Xs), Xs = [T]2 Note that the determin-
ism specification, e.g., det only applies if this argument is unbound.
Argument must be unbound. Typically used by predicates that create
something and return a handle to the created object, such as open/3
which creates a stream.
? Argument must be bound to a partial term of the indicated type.
Note that a variable is a partial term for any type. Think of the
argument as either input or output or both input and output. For
example, in stream property(S, reposition(Bool)), the
reposition part of the term is input and the uninstantiated Bool is
output.
: Argument is a meta-argument. Implies +. See chapter 6 for more infor-
mation on module handling.
@ Argument is not further instantiated. Typically used for type tests.
! Argument contains a mutable structure that may be modified using
setarg/3 or nb setarg/3.

Referring to a predicate in running text is done using a predicate indicator. The canonical and
most generic form of a predicate indicator is a term hmodulei:hnamei/harityi. If the module is irrele-
vant (built-in predicate) or can be inferred from the context it is often omitted. Compliant to the ISO
standard draft on DCG (see section 4.13), SWI-Prolog also allows for [hmodulei]:hnamei//harityi to
1
These definitions are taken from PlDoc. The current manual has only one mode declaration per predicate and therefore
predicates with mode (+,-) and (-,+) are described as (?,?). The @-mode is often replaced by +.

SWI-Prolog 7.4 Reference Manual

4.2. CHARACTER REPRESENTATION 79

refer to a grammar rule. For all non-negative arity, hnamei//harityi is the same as hnamei/harityi+2,
regardless of whether or not the referenced predicate is defined or can be used as a grammar rule. The
//-notation can be used in all places that traditionally allow for a predicate indicator, e.g., the module
declaration, spy/1, and dynamic/1.

4.2 Character representation

In traditional (Edinburgh) Prolog, characters are represented using character codes. Character codes
are integer indices into a specific character set. Traditionally the character set was 7-bit US-ASCII.
8-bit character sets have been allowed for a long time, providing support for national character sets,
of which iso-latin-1 (ISO 8859-1) is applicable to many Western languages.
ISO Prolog introduces three types, two of which are used for characters and one for accessing
binary streams (see open/4). These types are:

code
A character code is an integer representing a single character. As files may use multi-byte
encoding for supporting different character sets (utf-8 encoding for example), reading a code
from a text file is in general not the same as reading a byte.
char
Alternatively, characters may be represented as one-character atoms. This is a natural repre-
sentation, hiding encoding problems from the programmer as well as providing much easier
debugging.
byte
Bytes are used for accessing binary streams.

In SWI-Prolog, character codes are always the Unicode equivalent of the encoding. That is,
if get code/1 reads from a stream encoded as KOI8-R (used for the Cyrillic alphabet), it re-
turns the corresponding Unicode code points. Similarly, assembling or disassembling atoms using
atom codes/2 interprets the codes as Unicode points. See section 2.18.1 for details.
To ease the pain of the two character representations (code and char), SWI-Prologs built-in predi-
cates dealing with character data work as flexible as possible: they accept data in any of these formats
as long as the interpretation is unambiguous. In addition, for output arguments that are instantiated,
the character is extracted before unification. This implies that the following two calls are identical,
both testing whether the next input character is an a.

peek_code(Stream, a).
peek_code(Stream, 97).

The two character representations are handled by a large number of built-in predicates,
all of which are ISO-compatible. For converting between code and character there is
char code/2. For breaking atoms and numbers into characters there are atom chars/2,
atom codes/2, number chars/2 and number codes/2. For character I/O on streams
there are get char/[1,2], get code/[1,2], get byte/[1,2], peek char/[1,2],
peek code/[1,2], peek byte/[1,2], put code/[1,2], put char/[1,2] and
put byte/[1,2]. The Prolog flag double quotes controls how text between double quotes is
interpreted.

SWI-Prolog 7.4 Reference Manual

80 CHAPTER 4. BUILT-IN PREDICATES

4.3 Loading Prolog source files

This section deals with loading Prolog source files. A Prolog source file is a plain text file containing
a Prolog program or part thereof. Prolog source files come in three flavours:

A traditional Prolog source file contains Prolog clauses and directives, but no module declara-
tion (see module/1). They are normally loaded using consult/1 or ensure loaded/1.
Currently, a non-module file can only be loaded into a single module.3

A module Prolog source file starts with a module declaration. The subsequent Prolog code is loaded
into the specified module, and only the exported predicates are made available to the context
loading the module. Module files are normally loaded with use module/[1,2]. See chap-
ter 6 for details.

An include Prolog source file is loaded using the include/1 directive, textually including Prolog
text into another Prolog source. A file may be included into multiple source files and is typically
used to share declarations such as multifile or dynamic between source files.

Prolog source files are located using absolute file name/3 with the following options:

locate_prolog_file(Spec, Path) :-
absolute_file_name(Spec,
[ file_type(prolog),
access(read)
],
Path).

The file type(prolog) option is used to determine the extension of the file using
prolog file type/2. The default extension is .pl. Spec allows for the path alias construct de-
fined by absolute file name/3. The most commonly used path alias is library(LibraryFile).
The example below loads the library file ordsets.pl (containing predicates for manipulating or-
dered sets).

:- use_module(library(ordsets)).

SWI-Prolog recognises grammar rules (DCG) as defined in [Clocksin & Melish, 1987]. The user
may define additional compilation of the source file by defining the dynamic multifile predicates
term expansion/2, term expansion/4, goal expansion/2 and goal expansion/4.
It is not allowed to use assert/1, retract/1 or any other database predicate in
term expansion/2 other than for local computational purposes.4 Code that needs to create ad-
ditional clauses must use compile aux clauses/1. See library(apply macros) for an
example.
A directive is an instruction to the compiler. Directives are used to set (predicate) properties (see
section 4.15), set flags (see set prolog flag/2) and load files (this section). Directives are terms
of the form :- htermi.. Here are some examples:
3
This limitation may be lifted in the future. Existing limitations in SWI-Prologs source code administration make this
non-trivial.
4
It does work for normal loading, but not for qcompile/1.

SWI-Prolog 7.4 Reference Manual

4.3. LOADING PROLOG SOURCE FILES 81

Predicate if must be module import

consult/1 true false all
ensure loaded/1 not loaded false all
use module/1 not loaded true all
use module/2 not loaded true specified
reexport/1 not loaded true all
reexport/2 not loaded true specified

Table 4.1: Properties of the file-loading predicates. The import column specifies what is imported if
the loaded file is a module file.

:- use_module(library(lists)).
:- dynamic
store/2. % Name, Value

The directive initialization/1 can be used to run arbitrary Prolog goals. The specified goal is
started after loading the file in which it appears has completed.
SWI-Prolog compiles code as it is read from the file, and directives are executed as goals. This
implies that directives may call any predicate that has been defined before the point where the directive
appears. It also accepts ?- htermi. as a synonym.
SWI-Prolog does not have a separate reconsult/1 predicate. Reconsulting is implied auto-
matically by the fact that a file is consulted which is already loaded.
Advanced topics are handled in subsequent sections: mutually dependent files (section 4.3.2),
multithreaded loading (section 4.3.2) and reloading running code (section 4.3.2).
The core of the family of loading predicates is load files/2. The predicates consult/1,
ensure loaded/1, use module/1, use module/2 and reexport/1 pass the file argument
directly to load files/2 and pass additional options as expressed in the table 4.1:

load files(:Files)
Equivalent to load files(Files, []). Same as consult/1, See load files/2 for sup-
ported options.

load files(:Files, +Options)

The predicate load files/2 is the parent of all the other loading predicates except for
include/1. It currently supports a subset of the options of Quintus load files/2. Files
is either a single source file or a list of source files. The specification for a source file is handed
to absolute file name/2. See this predicate for the supported expansions. Options is a
list of options using the format OptionName(OptionValue).
The following options are currently supported:

autoload(Bool)
If true (default false), indicate that this load is a demand load. This implies that,
depending on the setting of the Prolog flag verbose autoload, the load action is
printed at level informational or silent. See also print message/2 and
current prolog flag/2.

SWI-Prolog 7.4 Reference Manual

82 CHAPTER 4. BUILT-IN PREDICATES

derived from(File)
Indicate that the loaded file is derived from File. Used by make/0 to time-check and
load the original file rather than the derived file.
dialect(+Dialect)
Load Files with enhanced compatibility with the target Prolog system identified by Di-
alect. See expects dialect/1 and section C for details.
encoding(Encoding)
Specify the way characters are encoded in the file. Default is taken from the Prolog flag
encoding. See section 2.18.1 for details.
expand(Bool)
If true, run the filenames through expand file name/2 and load the returned files.
Default is false, except for consult/1 which is intended for interactive use. Flexible
location of files is defined by file search path/2.
format(+Format)
Used to specify the file format if data is loaded from a stream using the stream(Stream)
option. Default is source, loading Prolog source text. If qlf, load QLF data (see
qcompile/1).
if(Condition)
Load the file only if the specified condition is satisfied. The value true loads the file
unconditionally, changed loads the file if it was not loaded before or has been modified
since it was loaded the last time, and not loaded loads the file if it was not loaded
before.
imports(Import)
Specify what to import from the loaded module. The default for use module/1 is
all. Import is passed from the second argument of use module/2. Traditionally it is
a list of predicate indicators to import. As part of the SWI-Prolog/YAP integration, we
also support Pred as Name to import a predicate under another name. Finally, Import
can be the term except(Exceptions), where Exceptions is a list of predicate indicators
that specify predicates that are not imported or Pred as Name terms to denote renamed
predicates. See also reexport/2 and use module/2.5
If Import equals all, all operators are imported as well. Otherwise, operators are not
imported. Operators can be imported selectively by adding terms op(Pri,Assoc,Name) to
the Import list. If such a term is encountered, all exported operators that unify with this
term are imported. Typically, this construct will be used with all arguments unbound to
import all operators or with only Name bound to import a particular operator.
modified(TimeStamp)
Claim that the source was loaded at TimeStamp without checking the source. This option
is intended to be used together with the stream(Input) option, for example after
extracting the time from an HTTP server or database.
module(+Module)
Load the indicated file into the given module, overruling the module name specified in
the :- module(Name, ...) directive. This currently serves two purposes: (1) allow
5
BUG: Name/Arity as NewName is currently implemented using a link clause. This harms efficiency and does not allow
for querying the relation through predicate property/2.

SWI-Prolog 7.4 Reference Manual

4.3. LOADING PROLOG SOURCE FILES 83

loading two module files that specify the same module into the same process and force
and (2): force loading source code in a specific module, even if the code provides its own
module name. Experimental.
must be module(Bool)
If true, raise an error if the file is not a module file. Used by use module/[1,2].
qcompile(Atom)
How to deal with quick-load-file compilation by qcompile/1. Values are:
never
Default. Do not use qcompile unless called explicitly.
auto
Use qcompile for all writeable files. See comment below.
large
Use qcompile if the file is large. Currently, files larger than 100 Kbytes are consid-
ered large.
part
If load files/2 appears in a directive of a file that is compiled into Quick Load
Format using qcompile/1, the contents of the argument files are included in the
.qlf file instead of the loading directive.
If this option is not present, it uses the value of the Prolog flag qcompile as default.
redefine module(+Action)
Defines what to do if a file is loaded that provides a module that is already loaded from
another file. Action is one of false (default), which prints an error and refuses to load
the file, or true, which uses unload file/1 on the old file and then proceeds loading
the new file. Finally, there is ask, which starts interaction with the user. ask is only
provided if the stream user input is associated with a terminal.
reexport(Bool)
If true re-export the imported predicate. Used by reexport/1 and reexport/2.
register(Bool)
If false, do not register the load location and options. This option is used by
make/0 and load hotfixes/1 to avoid polluting the load-context database. See
source file property/2.
sandboxed(Bool)
Load the file in sandboxed mode. This option controls the flag sandboxed load. The
only meaningful value for Bool is true. Using false while the Prolog flag is set to
true raises a permission error.
scope settings(Bool)
Scope style check/1 and expects dialect/1 to the file and files loaded from
the file after the directive. Default is true. The system and user initialization files (see
-f and -F) are loading with scope settings(false).
silent(Bool)
If true, load the file without printing a message. The specified value is the default for
all files loaded as a result of loading the specified files. This option writes the Prolog flag
verbose load with the negation of Bool.

SWI-Prolog 7.4 Reference Manual

84 CHAPTER 4. BUILT-IN PREDICATES

stream(Input)
This SWI-Prolog extension compiles the data from the stream Input. If this option is
used, Files must be a single atom which is used to identify the source location of the
loaded clauses as well as to remove all clauses if the data is reconsulted.
This option is added to allow compiling from non-file locations such as databases, the
web, the user (see consult/1) or other servers. It can be combined with format(qlf)
to load QLF data from a stream.

The load files/2 predicate can be hooked to load other data or data from objects other than
files. See prolog load file/2 for a description and http/http load for an example.
All hooks for load files/2 are documented in section B.8.

consult(:File)
Read File as a Prolog source file. Calls to consult/1 may be abbreviated by just typing a
number of filenames in a list. Examples:

?- consult(load). % consult load or load.pl

?- [library(lists)]. % load library lists
?- [user]. % Type program on the terminal

The predicate consult/1 is equivalent to load_files(File, []), except for handling

the special file user, which reads clauses from the terminal. See also the stream(Input)
option of load files/2. Abbreviation using ?- [file1,file2]. does not work for
the empty list ([]). This facility is implemented by defining the list as a predicate. Applications
may only rely on using the list abbreviation at the Prolog toplevel and in directives.

ensure loaded(:File)
If the file is not already loaded, this is equivalent to consult/1. Otherwise, if the file defines
a module, import all public predicates. Finally, if the file is already loaded, is not a module
file, and the context module is not the global user module, ensure loaded/1 will call
consult/1.
With this semantics, we hope to get as close as possible to the clear semantics with-
out the presence of a module system. Applications using modules should consider using
use module/[1,2].
Equivalent to load_files(Files, [if(not_loaded)]).6

include(+File) [ISO]
Textually include the content of File at the position where the directive
:- include(File). appears. The include construct is only honoured if it appears
as a directive in a source file. Textual include (similar to C/C++ #include) is obviously useful
for sharing declarations such as dynamic/1 or multifile/1 by including a file with
directives from multiple files that use these predicates.
Textually including files that contain clauses is less obvious. Normally, in SWI-Prolog, clauses
are owned by the file in which they are defined. This information is used to replace the old
6
On older versions the condition used to be if(changed). Poor time management on some machines or copying
often caused problems. The make/0 predicate deals with updating the running system after changing the source code.

SWI-Prolog 7.4 Reference Manual

4.3. LOADING PROLOG SOURCE FILES 85

definition after the file has been modified and is reloaded by, e.g., make/0. As we understand
it, include/1 is intended to include the same file multiple times. Including a file holding
clauses multiple times into the same module is rather meaningless as it just duplicates the same
clauses. Including a file holding clauses in multiple modules does not suffer from this problem,
but leads to multiple equivalent copies of predicates. Using use module/1 can achieve the
same result while sharing the predicates.
If include/1 is used to load files holding clauses, and if these files are loaded only once,
then these include/1 directives can be replaced by other predicates (such as consult/1).
However, there are several cases where either include/1 has no alternative, or using any
alternative also requires other changes. An example of the former is using include/1 to
share directives. An example of the latter are cases where clauses of different predicates
are distributed over multiple files: If these files are loaded with include/1, the directive
discontiguous/1 is appropriate, whereas if they are consulted, one must use the directive
multifile/1.
To accommodate included files holding clauses, SWI-Prolog distinguishes between the source
location of a clause (in this case the included file) and the owner of a clause (the file that includes
the file holding the clause). The source location is used by, e.g., edit/1, the graphical tracer,
etc., while the owner is used to determine which clauses are removed if the file is modified.
Relevant information is found with the following predicates:

source file/2 describes the owner relation.

predicate property/2 describes the source location (of the first clause).
clause property/2 provides access to both source and ownership.
source file property/2 can be used to query include relationships between files.

require(+ListOfNameAndArity)
Declare that this file/module requires the specified predicates to be defined with their com-
monly accepted definition. This predicate originates from the Prolog portability layer for
XPCE. It is intended to provide a portable mechanism for specifying that this module requires
the specified predicates.
The implementation normally first verifies whether the predicate is already defined. If not, it
will search the libraries and load the required library.
SWI-Prolog, having autoloading, does not load the library. Instead it creates a procedure header
for the predicate if it does not exist. This will flag the predicate as undefined. See also
check/0 and autoload/0.

encoding(+Encoding)
This directive can appear anywhere in a source file to define how characters are encoded in the
remainder of the file. It can be used in files that are encoded with a superset of US-ASCII,
currently UTF-8 and ISO Latin-1. See also section 2.18.1.

make
Consult all source files that have been changed since they were consulted. It checks all loaded
source files: files loaded into a compiled state using pl -c ... and files loaded using
consult/1 or one of its derivatives. The predicate make/0 is called after edit/1,
automatically reloading all modified files. If the user uses an external editor (in a separate

SWI-Prolog 7.4 Reference Manual

86 CHAPTER 4. BUILT-IN PREDICATES

window), make/0 is normally used to update the program after editing. In addition, make/0
updates the autoload indices (see section 2.13) and runs list undefined/0 from the
check library to report on undefined predicates.

library directory(?Atom)
Dynamic predicate used to specify library directories. Default ./lib, /lib/prolog and
the systems library (in this order) are defined. The user may add library directories using
assertz/1, asserta/1 or remove system defaults using retract/1. Deprecated. New
code should use file search path/2.

file search path(+Alias, -Path)

Dynamic multifile hook predicate used to specify path aliases. This hook is called by
absolute file name/3 to search files specified as Alias(Name), e.g., library(lists).
This feature is best described using an example. Given the definition:

file_search_path(demo, /usr/lib/prolog/demo).

the file specification demo(myfile) will be expanded to /usr/lib/prolog/demo/

myfile. The second argument of file search path/2 may be another alias.
Below is the initial definition of the file search path. This path implies swi(hPathi) and refers
to a file in the SWI-Prolog home directory. The alias foreign(hPathi) is intended for storing
shared libraries (.so or .DLL files). See also use foreign library/1.

user:file_search_path(library, X) :-
library_directory(X).
user:file_search_path(swi, Home) :-
current_prolog_flag(home, Home).
user:file_search_path(foreign, swi(ArchLib)) :-
current_prolog_flag(arch, Arch),
atom_concat(lib/, Arch, ArchLib).
user:file_search_path(foreign, swi(lib)).
user:file_search_path(path, Dir) :-
getenv(PATH, Path),
( current_prolog_flag(windows, true)
-> atomic_list_concat(Dirs, (;), Path)
; atomic_list_concat(Dirs, :, Path)
),
member(Dir, Dirs).

The file search path/2 expansion is used by all loading predicates as well as by
absolute file name/[2,3].
The Prolog flag verbose file search can be set to true to help debugging Prologs
search for files.

expand file search path(+Spec, -Path) [nondet]

Unifies Path with all possible expansions of the filename specification Spec. See also
absolute file name/3.

SWI-Prolog 7.4 Reference Manual

4.3. LOADING PROLOG SOURCE FILES 87

prolog file type(?Extension, ?Type)

This dynamic multifile predicate defined in module user determines the extensions considered
by file search path/2. Extension is the filename extension without the leading dot, and
Type denotes the type as used by the file type(Type) option of file search path/2.
Here is the initial definition of prolog file type/2:

user:prolog_file_type(pl, prolog).
user:prolog_file_type(Ext, prolog) :-
current_prolog_flag(associate, Ext),
Ext \== pl.
user:prolog_file_type(qlf, qlf).
user:prolog_file_type(Ext, executable) :-
current_prolog_flag(shared_object_extension, Ext).

Users can add extensions for Prolog source files to avoid conflicts (for example with perl)
as well as to be compatible with another Prolog implementation. We suggest using .pro for
avoiding conflicts with perl. Overriding the system definitions can stop the system from
finding libraries.

source file(?File)
True if File is a loaded Prolog source file. File is the absolute and canonical path to the source
file.

source file(:Pred, ?File)

True if the predicate specified by Pred is owned by file File, where File is an absolute path name
(see absolute file name/2). Can be used with any instantiation pattern, but the database
only maintains the source file for each predicate. If Pred is a multifile predicate this predicate
succeeds for all files that contribute clauses to Pred.7 See also clause property/2. Note
that the relation between files and predicates is more complicated if include/1 is used. The
predicate describes the owner of the predicate. See include/1 for details.

source file property(?File, ?Property)

True when Property is a property of the loaded file File. If File is non-var, it can be a file
specification that is valid for load files/2. Defined properties are:

derived from(Original, OriginalModified)

File was generated from the file Original, which was last modified at time OriginalMod-
ified at the time it was loaded. This property is available if File was loaded using the
derived from(Original) option to load files/2.
includes(IncludedFile, IncludedFileModified)
File used include/1 to include IncludedFile. The last modified time of IncludedFile
was IncludedFileModified at the time it was included.
included in(MasterFile, Line)
File was included into MasterFile from line Line. This is the inverse of the includes
property.
7
The current implementation performs a linear scan through all clauses to establish this set of files.

SWI-Prolog 7.4 Reference Manual

88 CHAPTER 4. BUILT-IN PREDICATES

load context(Module, Location, Options)

Module is the module into which the file was loaded. If File is a module, this is the
module into which the exports are imported. Otherwise it is the module into which the
clauses of the non-module file are loaded. Location describes the file location from
which the file was loaded. It is either a term hfilei:hlinei or the atom user if the file was
loaded from the terminal or another unknown source. Options are the options passed to
load files/2. Note that all predicates to load files are mapped to load files/2,
using the option argument to specify the exact behaviour.

load count(-Count)
Count is the number of times the file have been loaded, i.e., 1 (one) if the file has been
loaded once.

modified(Stamp)
File modification time when File was loaded. This is used by make/0 to find files whose
modification time is different from when it was loaded.

module(Module)
File is a module file that declares the module Module.

number of clauses(Count)
Count is the number of clauses associated with File. Note that clauses loaded from in-
cluded files are counted as part of the main file.

reloading
Present if the file is currently being reloaded.

unload file(+File)
Remove all clauses loaded from File. If File loaded a module, clear the modules export list
and disassociate it from the file. File is a canonical filename or a file indicator that is valid for
load files/2.

This predicate should be used with care. The multithreaded nature of SWI-Prolog makes re-
moving static code unsafe. Attempts to do this should be reserved for development or situations
where the application can guarantee that none of the clauses associated to File are active.

prolog load context(?Key, ?Value)

Obtain context information during compilation. This predicate can be used from directives
appearing in a source file to get information about the file being loaded as well as by the
term expansion/2 and goal expansion/2 hooks. See also source location/2
and if/1. The following keys are defined:

SWI-Prolog 7.4 Reference Manual

4.3. LOADING PROLOG SOURCE FILES 89

Key Description
directory Directory in which source lives
dialect Compatibility mode. See expects dialect/1.
file Similar to source, but returns the file being included when called while
an include file is being processed
module Module into which file is loaded
reload true if the file is being reloaded. Not present on first load
script Boolean that indicates whether the file is loaded as a script file (see -s)
source File being loaded. If the system is processing an included file, the value
is the main file. Returns the original Prolog file when loading a .qlf
file.
stream Stream identifier (see current input/1)
term position Start position of last term read. See also stream property/2
(position property and stream position data/3.8
term Term being expanded by expand term/2.
variable names A list of Name = Var of the last term read. See read term/2 for
details.

The directory is commonly used to add rules to file search path/2, setting up a
search path for finding files with absolute file name/3. For example:

:- dynamic user:file_search_path/2.
:- multifile user:file_search_path/2.

:- prolog_load_context(directory, Dir),
asserta(user:file_search_path(my_program_home, Dir)).

...
absolute_file_name(my_program_home(README.TXT), ReadMe,
[ access(read) ]),
...

source location(-File, -Line)

If the last term has been read from a physical file (i.e., not from the file user or a string), unify
File with an absolute path to the file and Line with the line number in the file. New code should
use prolog load context/2.

at halt(:Goal)
Register Goal to be run from PL cleanup(), which is called when the system halts. The
hooks are run in the reverse order they were registered (FIFO). Success or failure executing
a hook is ignored. If the hook raises an exception this is printed using print message/2.
An attempt to call halt/[0,1] from a hook is ignored. Hooks may call cancel halt/1,
causing halt/0 and PL halt(0) to print a message indicating that halting the system has
been cancelled.

cancel halt(+Reason)
If this predicate is called from a hook registered with at halt/1, halting Prolog is cancelled

SWI-Prolog 7.4 Reference Manual

90 CHAPTER 4. BUILT-IN PREDICATES

and an informational message is printed that includes Reason. This is used by the development
tools to cancel halting the system if the editor has unsafed data and the user decides to cancel.

:- initialization(:Goal) [ISO]
Call Goal after loading the source file in which this directive appears has been completed. In
addition, Goal is executed if a saved state created using qsave program/1 is restored.
The ISO standard only allows for using :- Term if Term is a directive. This means that
arbitrary goals can only be called from a directive by means of the initialization/1
directive. SWI-Prolog does not enforce this rule.
The initialization/1 directive must be used to do program initialization in saved states
(see qsave program/1). A saved state contains the predicates, Prolog flags and operators
present at the moment the state was created. Other resources (records, foreign resources, etc.)
must be recreated using initialization/1 directives or from the entry goal of the saved
state.
Up to SWI-Prolog 5.7.11, Goal was executed immediately rather than after load-
ing the program text in which the directive appears as dictated by the ISO stan-
dard. In many cases the exact moment of execution is irrelevant, but there are
exceptions. For example, load foreign library/1 must be executed immedi-
ately to make the loaded foreign predicates available for exporting. SWI-Prolog
now provides the directive use foreign library/1 to ensure immediate loading as
well as loading after restoring a saved state. If the system encounters a directive
:- initialization(load foreign library(...)), it will load the foreign li-
brary immediately and issue a warning to update your code. This behaviour can be extended
by providing clauses for the multifile hook predicate prolog:initialize now(Term, Ad-
vice), where Advice is an atom that gives advice on how to resolve the compatibility issue.

initialization(:Goal, +When)
Similar to initialization/1, but allows for specifying when Goal is executed while
loading the program text:

now
Execute Goal immediately.
after load
Execute Goal after loading program text. This is the same as initialization/1.
restore
Do not execute Goal while loading the program, but only when restoring a state.

compiling
True if the system is compiling source files with the -c option or qcompile/1 into
an intermediate code file. Can be used to perform conditional code optimisations in
term expansion/2 (see also the -O option) or to omit execution of directives during
compilation.

4.3.1 Conditional compilation and program transformation

ISO Prolog defines no way for program transformations such as macro expansion or conditional com-
pilation. Expansion through term expansion/2 and expand term/2 can be seen as part of the

SWI-Prolog 7.4 Reference Manual

4.3. LOADING PROLOG SOURCE FILES 91

de-facto standard. This mechanism can do arbitrary translation between valid Prolog terms read from
the source file to Prolog terms handed to the compiler. As term expansion/2 can return a list,
the transformation does not need to be term-to-term.
Various Prolog dialects provide the analogous goal expansion/2 and expand goal/2 that
allow for translation of individual body terms, freeing the user of the task to disassemble each clause.

term expansion(+Term1, -Term2)

Dynamic and multifile predicate, normally not defined. When defined by the user all terms
read during consulting are given to this predicate. If the predicate succeeds Prolog will assert
Term2 in the database rather than the read term (Term1). Term2 may be a term of the form
?- Goal. or :- Goal. Goal is then treated as a directive. If Term2 is a list, all terms of
the list are stored in the database or called (for directives). If Term2 is of the form below, the
system will assert Clause and record the indicated source location with it:

$source location(hFilei, hLinei):hClausei

When compiling a module (see chapter 6 and the directive module/2), expand term/2
will first try term expansion/2 in the module being compiled to allow for term expan-
sion rules that are local to a module. If there is no local definition, or the local definition
fails to translate the term, expand term/2 will try term expansion/2 in module user.
For compatibility with SICStus and Quintus Prolog, this feature should not be used. See also
expand term/2, goal expansion/2 and expand goal/2.

expand term(+Term1, -Term2)

This predicate is normally called by the compiler on terms read from the input to perform
preprocessing. It consists of four steps, where each step processes the output of the previous
step.

1. Test conditional compilation directives and translate all input to [] if we are in a false
branch of the conditional compilation. See section 4.3.1.
2. Call term expansion/2. This predicate is first tried in the module that is being com-
piled and then in the module user.
3. Call DCG expansion (dcg translate rule/2).
4. Call expand goal/2 on each body term that appears in the output of the previous steps.

goal expansion(+Goal1, -Goal2)

Like term expansion/2, goal expansion/2 provides for macro expansion of Prolog
source code. Between expand term/2 and the actual compilation, the body of clauses anal-
ysed and the goals are handed to expand goal/2, which uses the goal expansion/2
hook to do user-defined expansion.
The predicate goal expansion/2 is first called in the module that is being compiled, and
then follows the module inheritance path as defined by default module/2, i.e., by de-
fault user and system. If Goal is of the form Module:Goal where Module is instantiated,
goal expansion/2 is called on Goal using rules from module Module followed by default
modules for Module.
Only goals appearing in the body of clauses when reading a source file are expanded using
this mechanism, and only if they appear literally in the clause, or as an argument to a defined

SWI-Prolog 7.4 Reference Manual

92 CHAPTER 4. BUILT-IN PREDICATES

meta-predicate that is annotated using 0 (see meta predicate/1). Other cases need a real
predicate definition.
The expansion hook can use prolog load context/2 to obtain information about the con-
text in which the goal is exanded such as the module, variable names or the encapsulating term.

expand goal(+Goal1, -Goal2)

This predicate is normally called by the compiler to perform preprocessing using
goal expansion/2. The predicate computes a fixed-point by applying transforma-
tions until there are no more changes. If optimisation is enabled (see -O and optimise),
expand goal/2 simplifies the result by removing unneeded calls to true/0 and fail/0
as well as unreachable branches.

compile aux clauses(+Clauses)

Compile clauses on behalf of goal expansion/2. This predicate compiles the argument
clauses into static predicates, associating the predicates with the current file but avoids changing
the notion of current predicate and therefore discontiguous warnings.
Note that in some cases multiple expansions of similar goals can share the same compiled
auxiliary predicate. In such cases, the implementation of goal expansion/2 can use
predicate property/2 using the property defined to test whether the predicate is al-
ready defined in the current context.

dcg translate rule(+In, -Out)

This predicate performs the translation of a term Head-->Body into a normal Prolog clause.
Normally this functionality should be accessed using expand term/2.

var property(+Var, ?Property)

True when Property is a property of Var. These properties are available during goal- and
term-expansion. Defined properties are below. Future versions are likely to provide more
properties, such as whether the variable is a singleton or whether the variable is referenced in
the remainder of the term. See also goal expansion/2.

fresh(Bool)
Bool has the value true if the variable is guaranteed to be unbound at entry of the goal,
otherwise its value is false. This implies that the variable first appears in this goal or a
previous appearance was in a negation (\+/1) or a different branch of a disjunction.
name(Name)
True when variable appears with the given name in the source.

Program transformation with source layout info

This sections documents extended versions of the program transformation predicates that also trans-
form the source layout information. Extended layout information is currently processed, but unused.
Future versions will use for the following enhancements:

More precise locations of warnings and errors

More reliable setting of breakpoints

More reliable source layout information in the graphical debugger.

SWI-Prolog 7.4 Reference Manual

4.3. LOADING PROLOG SOURCE FILES 93

expand goal(+Goal1, ?Layout1, -Goal2, -Layout2)

goal expansion(+Goal1, ?Layout1, -Goal2, -Layout2)
expand term(+Term1, ?Layout1, -Term2, -Layout2)
term expansion(+Term1, ?Layout1, -Term2, -Layout2)

dcg translate rule(+In, ?LayoutIn, -Out, -LayoutOut)

These versions are called before their 2-argument counterparts. The input layout term is either
a variable (if no layout information is available) or a term carrying detailed layout information
as returned by the subterm positions of read term/2.

Conditional compilation
Conditional compilation builds on the same principle as term expansion/2,
goal expansion/2 and the expansion of grammar rules to compile sections of the source
code conditionally. One of the reasons for introducing conditional compilation is to simplify writing
portable code. See section C for more information. Here is a simple example:

:- if(\+source_exports(library(lists), suffix/2)).

suffix(Suffix, List) :-
append(_, Suffix, List).

:- endif.

Note that these directives can only appear as separate terms in the input. Typical usage scenarios
include:

Load different libraries on different dialects.

Define a predicate if it is missing as a system predicate.
Realise totally different implementations for a particular part of the code due to different capa-
bilities.
Realise different configuration options for your software.

:- if(:Goal)
Compile subsequent code only if Goal succeeds. For enhanced portability, Goal is processed
by expand goal/2 before execution. If an error occurs, the error is printed and processing
proceeds as if Goal has failed.

:- elif(:Goal)
Equivalent to :- else. :-if(Goal). ... :- endif. In a sequence as below, the
section below the first matching elif is processed. If no test succeeds, the else branch is
processed.

:- if(test1).
section_1.
:- elif(test2).

SWI-Prolog 7.4 Reference Manual

94 CHAPTER 4. BUILT-IN PREDICATES

section_2.
:- elif(test3).
section_3.
:- else.
section_else.
:- endif.

:- else
Start else branch.

:- endif
End of conditional compilation.

4.3.2 Reloading files, active code and threads

Traditionally, Prolog environments allow for reloading files holding currently active code. In particu-
lar, the following sequence is a valid use of the development environment:

Trace a goal
Find unexpected behaviour of a predicate
Enter a break using the b command
Fix the sources and reload them using make/0
Exit the break, retry executing the now fixed predicate using the r command

Reloading a previously loaded file is safe, both in the debug scenario above and when the code
is being executed by another thread. Executing threads switch atomically to the new definition of
modified predicates, while clauses that belong to the old definition are (eventually) reclaimed by
garbage collect clauses/0.9 Below we describe the steps taken for reloading a file to help
understanding the limitations of the process.

1. If a file is being reloaded, a reload context is associated to the file administration. This context
includes a table keeping track of predicates and a table keeping track of the module(s) associated
with this source.

2. If a new predicate is found, an entry is added to the context predicate table. Three options are
considered:

(a) The predicate is new. It is handled the same as if the file was loaded for the first time.
(b) The predicate is foreign or thread local. These too are threaded as if the file was loaded
for the first time.
(c) Normal predicates. Here we initialise a pointer to the current clause.

3. New clauses for normal predicates are considered as follows:

9
As of version 7.3.12. Older versions wipe all clauses originating from the file before loading the new clauses. This
causes threads that executes the code to (typically) die with an undefined predicate exception.

SWI-Prolog 7.4 Reference Manual

4.3. LOADING PROLOG SOURCE FILES 95

(a) If the clauses byte-code is the same as the predicates current clause, discard the clause
and advance the current clause pointer.
(b) If the clauses byte-code is the same as some clause further into the clause list of the
predicate, discard the new clause, mark all intermediate clauses for future deletion, and
advance the current clause pointer to the first clause after the matched one.
(c) If the clauses byte-code matches no clause, insert it for future activation before the current
clause and keep the current clause.
4. Properties such as dynamic or meta predicate are in part applied immediately and
in part during the fixup process after the file completes loading. Currently, dynamic and
thread local are applied immediately.
5. New modules are recorded in the reload context. Export declarations (the modules public list
and export/1 calls) are both applied and recorded.
6. When the end-of-file is reached, the following fixup steps are taken
(a) For each predicate
i. The current clause and subsequent clauses are marked for future deletion.
ii. All clauses marked for future deletion or creation are (in)activated by changing their
erased or created generation. Erased clauses are (eventually) reclaimed by the
clause garbage collector, see garbage collect clauses/0.
iii. Pending predicate property changes are applied.
(b) For each module
i. Exported predicates that are not encountered in the reload context are removed from
the export list.

The above generally ensures that changes to the content of source files can typically be activated
safely using make/0. Global changes such as operator changes, changes of module names, changes
to multi-file predicates, etc. sometimes require a restart. In almost all cases, the need for restart
is indicated by permission or syntax errors during the reload or existence errors while running the
program. If the content of a source file refers to itself there are some additional limitations, which
are listed below. In some cases, loading the file twice establishes the right result. In others one may
use unload file/1 to remove the file before reloading. In some cases, the process needs to be
restarted.

Directives that execute code in the current file will use the old definition of predicates because
the new only become available at the end of the loading process. If the standard required
initialization/1 directive is used there is no problem because the associated goal is
executed after the file completes loading.
Module-local rules for goal expansion/2 or term expansion/2 execute the old defi-
nition. If such rules are changed, they become active after loading the file twice, where the first
reload updates the expansion rules and the second uses them.
Expansion and directives can normally only refer to predicates defined before they are used.
During reload, it is also possible to refer to predicates defined after the location they are used.
This may cause a file to work properly while being reloaded, but failing while being loaded in
a fresh image.

SWI-Prolog 7.4 Reference Manual

96 CHAPTER 4. BUILT-IN PREDICATES

Using goal expansion/2 that calls compile aux clauses/1, assuming that multiple
expansions can use the same auxiliary definition must use predicate property/2 using
the property defined to test whether the definition is already defined in the current context.

garbage collect clauses

Reclaim retracted clauses. During normal operation, retracting a clause implies setting the
erased generation to the current generation of the database and increment the generation.
Keeping the clause around is both needed to realise the logical update view and deal with the
fact that other threads may be executing the clause. Both static and dynamic code is processed
this way.10 .
The clause garbage collector (CGC) scans the environment stacks of all threads for referenced
dirty predicates and at which generation this reference accesses the predicate. It then removes
the references for clauses that have been retracted before the oldest access generation from the
clause list as well as the secondary clauses indexes of the predicate. If the clause list is not
being scanned, the clause references and ultimately the clause itself is reclaimed.
The clause garbage collector is called under three conditions, (1) after reloading a source file,
(2) if the memory occupied by retracted but not yet reclaimed clauses exceeds 12.5% of the
program store, or (3) if skipping dead clauses in the clause lists becomes too costly. The cost of
clause garbage collection is proportional with the total size of the local stack of all threads (the
scanning phase) and the number of clauses in all dirty predicates (the reclaiming phase).

Compilation of mutually dependent code

Large programs are generally split into multiple files. If file A accesses predicates from file B which
accesses predicates from file A, we consider this a mutual or circular dependency. If traditional
load predicates (e.g., consult/1) are used to include file B from A and A from B, loading ei-
ther file results in a loop. This is because consult/1 is mapped to load files/2 using the
option if(true)(.) Such programs are typically loaded using a load file that consults all required
(non-module) files. If modules are used, the dependencies are made explicit using use module/1
statements. The use module/1 predicate, however, maps to load files/2 with the option
if(not loaded)(.) A use module/1 on an already loaded file merely makes the public predi-
cates of the used module available.
Summarizing, mutual dependency of source files is fully supported with no precautions when
using modules. Modules can use each other in an arbitrary dependency graph. When using
consult/1, predicate dependencies between loaded files can still be arbitrary, but the consult rela-
tions between files must be a proper tree.

Compilation with multiple threads

This section discusses compiling files for the first time. For reloading, see section 4.3.2.
In older versions, compilation was thread-safe due to a global lock in load files/2 and the
code dealing with autoloading (see section 2.13). Besides unnecessary stalling when multiple threads
trap unrelated undefined predicates, this easily leads to deadlocks, notably if threads are started from
an initialization/1 directive.11
10
Up to version 7.3.11, dynamic code was handled using reference counts.
11
Although such goals are started after loading the file in which they appear, the calling thread is still likely to hold the
load lock because it is compiling the file from which the file holding the directive is loaded.

SWI-Prolog 7.4 Reference Manual

4.3. LOADING PROLOG SOURCE FILES 97

Starting with version 5.11.27, the autoloader is no longer locked and multiple threads can compile
files concurrently. This requires special precautions only if multiple threads wish to load the same
file at the same time. Therefore, load files/2 checks automatically whether some other thread is
already loading the file. If not, it starts loading the file. If another thread is already loading the file, the
thread blocks until the other thread finishes loading the file. After waiting, and if the file is a module
file, it will make the public predicates available.
Note that this schema does not prevent deadlocks under all situations. Consider two mutually
dependent (see section 4.3.2) module files A and B, where thread 1 starts loading A and thread 2
starts loading B at the same time. Both threads will deadlock when trying to load the used module.
The current implementation does not detect such cases and the involved threads will freeze. This
problem can be avoided if a mutually dependent collection of files is always loaded from the same
start file.

4.3.3 Quick load files

SWI-Prolog supports compilation of individual or multiple Prolog source files into Quick Load Files.
A Quick Load File (.qlf file) stores the contents of the file in a precompiled format.
These files load considerably faster than source files and are normally more compact. They are
machine-independent and may thus be loaded on any implementation of SWI-Prolog. Note, however,
that clauses are stored as virtual machine instructions. Changes to the compiler will generally make
old compiled files unusable.
Quick Load Files are created using qcompile/1. They are loaded using consult/1 or one
of the other file-loading predicates described in section 4.3. If consult/1 is given an explicit .pl
file, it will load the Prolog source. When given a .qlf file, it will load the file. When no extension is
specified, it will load the .qlf file when present and the .pl file otherwise.

qcompile(:File)
Takes a file specification as consult/1, etc., and, in addition to the normal compilation,
creates a Quick Load File from File. The file extension of this file is .qlf. The basename of
the Quick Load File is the same as the input file.
If the file contains :- consult(+File), :- [+File] or
:- load files(+File, [qcompile(part), ...]) statements, the referred
files are compiled into the same .qlf file. Other directives will be stored in the .qlf file and
executed in the same fashion as when loading the .pl file.
For term expansion/2, the same rules as described in section 2.10 apply.
Conditional execution or optimisation may test the predicate compiling/0.
Source references (source file/2) in the Quick Load File refer to the Prolog source file
from which the compiled code originates.

qcompile(:File, +Options)
As qcompile/1, but processes additional options as defined by load files/2.12
12
BUG: Option processing is currently incomplete.

SWI-Prolog 7.4 Reference Manual

98 CHAPTER 4. BUILT-IN PREDICATES

4.4 Editor Interface

SWI-Prolog offers an extensible interface which allows the user to edit objects of the program: predi-
cates, modules, files, etc. The editor interface is implemented by edit/1 and consists of three parts:
locating, selecting and starting the editor. Any of these parts may be customized. See section 4.4.1.
The built-in edit specifications for edit/1 (see prolog edit:locate/3) are described in the table
below:

Fully specified objects

hModulei:hNamei/hArityi Refers to a predicate
module(hModulei) Refers to a module
file(hPathi) Refers to a file
source file(hPathi) Refers to a loaded source file
Ambiguous specifications
hNamei/hArityi Refers to this predicate in any module
hNamei Refers to (1) the named predicate in any module with any
arity, (2) a (source) file, or (3) a module.

edit(+Specification)
First, exploit prolog edit:locate/3 to translate Specification into a list of Locations.
If there is more than one hit, the user is asked to select from the locations found. Finally,
prolog edit:edit source/1 is used to invoke the users preferred editor. Typically,
edit/1 can be handed the name of a predicate, module, basename of a file, XPCE class,
XPCE method, etc.

edit
Edit the default file using edit/1. The default file is the file loaded with the command line
option -s or, in Windows, the file loaded by double-clicking from the Windows shell.

4.4.1 Customizing the editor interface

The predicates described in this section are hooks that can be defined to disambiguate specifications
given to edit/1, find the related source, and open an editor at the given source location.

prolog edit:locate(+Spec, -FullSpec, -Location)

Where Spec is the specification provided through edit/1. This multifile predicate is used to
enumerate locations where an object satisfying the given Spec can be found. FullSpec is unified
with the complete specification for the object. This distinction is used to allow for ambiguous
specifications. For example, if Spec is an atom, which appears as the basename of a loaded file
and as the name of a predicate, FullSpec will be bound to file(Path) or Name/Arity.
Location is a list of attributes of the location. Normally, this list will contain the term
file(File) and, if available, the term line(Line).

prolog edit:locate(+Spec, -Location)

Same as prolog edit:locate/3, but only deals with fully specified objects.

prolog edit:edit source(+Location)

Start editor on Location. See prolog edit:locate/3 for the format of a location term. This

SWI-Prolog 7.4 Reference Manual

4.5. LIST THE PROGRAM, PREDICATES OR CLAUSES 99

multifile predicate is normally not defined. If it succeeds, edit/1 assumes the editor is
started.
If it fails, edit/1 uses its internal defaults, which are defined by the Prolog flag editor
and/or the environment variable EDITOR. The following rules apply. If the Prolog flag
editor is of the format $hnamei, the editor is determined by the environment variable hnamei.
Else, if this flag is pce emacs or built in and XPCE is loaded or can be loaded, the built-in
Emacs clone is used. Else, if the environment EDITOR is set, this editor is used. Finally, vi is
used as default on Unix systems and notepad on Windows.
See the default user preferences file dotfiles/dotswiplrc for examples.

prolog edit:edit command(+Editor, -Command)

Determines how Editor is to be invoked using shell/1. Editor is the determined editor (see
qpredrefprolog editedit source1), without the full path specification, and without a possible
(.exe) extension. Command is an atom describing the command. The following %-sequences
are replaced in Command before the result is handed to shell/1:

%e Replaced by the (OS) command name of the editor

%f Replaced by the (OS) full path name of the file
%d Replaced by the line number

If the editor can deal with starting at a specified line, two clauses should be provided. The first
pattern invokes the editor with a line number, while the second is used if the line number is
unknown.
The default contains definitions for vi, emacs, emacsclient, vim, notepad and
wordpad . Starred editors do not provide starting at a given line number.
Please contribute your specifications to [email protected].

prolog edit:load
Normally an undefined multifile predicate. This predicate may be defined to provide loading
hooks for user extensions to the edit module. For example, XPCE provides the code below to
load swi edit, containing definitions to locate classes and methods as well as to bind this
package to the PceEmacs built-in editor.

:- multifile prolog_edit:load/0.

prolog_edit:load :-
ensure_loaded(library(swi_edit)).

4.5 List the program, predicates or clauses

listing(:Pred)
List predicates specified by Pred. Pred may be a predicate name (atom), which lists all
predicates with this name, regardless of their arity. It can also be a predicate indica-
tor (hnamei/harityi or hnamei//harityi), possibly qualified with a module. For example:
?- listing(lists:member/2)..

SWI-Prolog 7.4 Reference Manual

100 CHAPTER 4. BUILT-IN PREDICATES

A listing is produced by enumerating the clauses of the predicate using clause/2 and printing
each clause using portray clause/1. This implies that the variable names are generated
(A, B, . . . ) and the layout is defined by rules in portray clause/1.

listing
List all predicates from the calling module using listing/1. For example, ?- listing.
lists clauses in the default user module and ?- lists:listing. lists the clauses in the
module lists.

portray clause(+Clause)
Pretty print a clause. A clause should be specified as a term hHeadi :- hBodyi. Facts are
represented as hHeadi :- true or simply hHeadi. Variables in the clause are written as A,
B, . . . . Singleton variables are written as _. See also portray clause/2.

portray clause(+Stream, +Clause)

Pretty print a clause to Stream. See portray clause/1 for details.

4.6 Verify Type of a Term

Type tests are semi-deterministic predicates that succeed if the argument satisfies the requested type.
Type-test predicates have no error condition and do not instantiate their argument. See also library
error.

var(@Term) [ISO]
True if Term currently is a free variable.

nonvar(@Term) [ISO]
True if Term currently is not a free variable.

integer(@Term) [ISO]
True if Term is bound to an integer.

float(@Term) [ISO]
True if Term is bound to a floating point number.

rational(@Term)
True if Term is bound to a rational number. Rational numbers include integers.

rational(@Term, -Numerator, -Denominator)

True if Term is a rational number with given Numerator and Denominator. The Numerator and
Denominator are in canonical form, which means Denominator is a positive integer and there
are no common divisors between Numerator and Denominator.

number(@Term) [ISO]
True if Term is bound to an integer or floating point number.13

atom(@Term) [ISO]
True if Term is bound to an atom.
13
As rational numbers are not atomic in the current implementation and we do not want to break the rule that number/1
implies atomic/1, number/1 fails on rational numbers. This will change if rational numbers become atomic.

SWI-Prolog 7.4 Reference Manual

4.6. VERIFY TYPE OF A TERM 101

blob(@Term, ?Type)
True if Term is a blob of type Type. See section 11.4.7.

string(@Term)
True if Term is bound to a string. Note that string here refers to the built-in atomic type string as
described in section 5.2. Starting with version 7, the syntax for a string object is text between
double quotes, such as "hello".14 See also the Prolog flag double quotes.

atomic(@Term) [ISO]
True if Term is bound (i.e., not a variable) and is not compound. Thus, atomic acts as if defined
by:

atomic(Term) :-
nonvar(Term),
\+ compound(Term).

SWI-Prolog defines the following atomic datatypes: atom (atom/1), string (string/1), in-
teger (integer/1), floating point number (float/1) and blob (blob/2). In addition, the
symbol [] (empty list) is atomic, but not an atom. See section 5.1.

compound(@Term) [ISO]
True if Term is bound to a compound term. See also functor/3 =../2,
compound name arity/3 and compound name arguments/3.

callable(@Term) [ISO]
True if Term is bound to an atom or a compound term. This was intended as a type-test for
arguments to call/1 and call/2.. Note that callable only tests the surface term. Terms
such as (22,true) are considered callable, but cause call/1 to raise a type error. Module-
qualification of meta-argument (see meta predicate/1) using :/2 causes callable to
succeed on any meta-argument.15 Consider the program and query below:

:- meta_predicate p(0).

p(G) :- callable(G), call(G).

?- p(22).
ERROR: Type error: callable expected, found 22
ERROR: In:
ERROR: [6] p(user:22)

ground(@Term) [ISO]
True if Term holds no free variables.
14
In traditional Prolog systems, double quoted text is often mapped to a list of character codes.
15
We think that callable/1 should be deprecated and there should be two new predicates, one performing a test for
callable that is minimally module aware and possibly consistent with type-checking in call/1 and a second predicate that
tests for atom or compound.

SWI-Prolog 7.4 Reference Manual

102 CHAPTER 4. BUILT-IN PREDICATES

cyclic term(@Term)
True if Term contains cycles, i.e. is an infinite term. See also acyclic term/1 and sec-
tion 2.16.16

acyclic term(@Term) [ISO]

True if Term does not contain cycles, i.e. can be processed recursively in finite time. See also
cyclic term/1 and section 2.16.

4.7 Comparison and Unification of Terms

Although unification is mostly done implicitly while matching the head of a predicate, it is also pro-
vided by the predicate =/2.

?Term1 = ?Term2 [ISO]

Unify Term1 with Term2. True if the unification succeeds. For behaviour on cyclic terms see
the Prolog flag occurs check. It acts as if defined by the following fact:

=(Term, Term).

@Term1 \= @Term2 [ISO]

Equivalent to \+Term1 = Term2.
This predicate is logically sound if its arguments are sufficiently instantiated. In other cases,
such as ?- X \= Y., the predicate fails although there are solutions. This is due to the
incomplete nature of \+/1.
To make your programs work correctly also in situations where the arguments are not yet suffi-
ciently instantiated, use dif/2 instead.

4.7.1 Standard Order of Terms

Comparison and unification of arbitrary terms. Terms are ordered in the so-called standard order.
This order is defined as follows:

1. Variables < Numbers < Strings < Atoms < Compound Terms

2. Variables are sorted by address. Attaching attributes (see section 7.1) does not affect the order-
ing.

3. Numbers are compared by value. Mixed integer/float are compared as floats. If the comparison
is equal, the float is considered the smaller value. If the Prolog flag iso is defined, all floating
point numbers precede all integers.

4. Strings are compared alphabetically.

5. Atoms are compared alphabetically.

16
The predicates cyclic term/1 and acyclic term/1 are compatible with SICStus Prolog. Some Prolog systems
supporting cyclic terms use is cyclic/1.

SWI-Prolog 7.4 Reference Manual

4.7. COMPARISON AND UNIFICATION OF TERMS 103

6. Compound terms are first checked on their arity, then on their functor name (alphabetically) and
finally recursively on their arguments, leftmost argument first.

@Term1 == @Term2 [ISO]

True if Term1 is equivalent to Term2. A variable is only identical to a sharing variable.

@Term1 \== @Term2 [ISO]

Equivalent to \+Term1 == Term2.

@Term1 @< @Term2 [ISO]

True if Term1 is before Term2 in the standard order of terms.

@Term1 @=< @Term2 [ISO]

True if both terms are equal (==/2) or Term1 is before Term2 in the standard order of terms.

@Term1 @> @Term2 [ISO]

True if Term1 is after Term2 in the standard order of terms.

@Term1 @>= @Term2 [ISO]

True if both terms are equal (==/2) or Term1 is after Term2 in the standard order of terms.

compare(?Order, @Term1, @Term2) [ISO]

Determine or test the Order between two terms in the standard order of terms. Order is one of
<, > or =, with the obvious meaning.

4.7.2 Special unification and comparison predicates

This section describes special purpose variations on Prolog unification. The predicate
unify with occurs check/2 provides sound unification and is part of the ISO standard. The
predicate subsumes term/2 defines one-sided unification and is part of the ISO proposal estab-
lished in Edinburgh (2010). Finally, unifiable/3 is a what-if version of unification that is often
used as a building block in constraint reasoners.

unify with occurs check(+Term1, +Term2) [ISO]

As =/2, but using sound unification. That is, a variable only unifies to a term if this term does
not contain the variable itself. To illustrate this, consider the two queries below.

1 ?- A = f(A).
A = f(A).
2 ?- unify_with_occurs_check(A, f(A)).
false.

The first statement creates a cyclic term, also called a rational tree. The second executes log-
ically sound unification and thus fails. Note that the behaviour of unification through =/2 as
well as implicit unification in the head can be changed using the Prolog flag occurs check.
The SWI-Prolog implementation of unify with occurs check/2 is cycle-safe and only
guards against creating cycles, not against cycles that may already be present in one of the
arguments. This is illustrated in the following two queries:

SWI-Prolog 7.4 Reference Manual

104 CHAPTER 4. BUILT-IN PREDICATES

?- X = f(X), Y = X, unify_with_occurs_check(X, Y).

X = Y, Y = f(Y).
?- X = f(X), Y = f(Y), unify_with_occurs_check(X, Y).
X = Y, Y = f(Y).

Some other Prolog systems interpret unify with occurs check/2 as if defined by the
clause below, causing failure on the above two queries. Direct use of acyclic term/1 is
portable and more appropriate for such applications.

unify_with_occurs_check(X,X) :- acyclic_term(X).

+Term1 =@= +Term2

True if Term1 is a variant of (or structurally equivalent to) Term2. Testing for a variant is
weaker than equivalence (==/2), but stronger than unification (=/2). Two terms A and B are
variants iff there exists a renaming of the variables in A that makes A equivalent (==) to B and
vice versa.17 Examples:

1 a =@= A false
2 A =@= B true
3 x(A,A) =@= x(B,C) false
4 x(A,A) =@= x(B,B) true
5 x(A,A) =@= x(A,B) false
6 x(A,B) =@= x(C,D) true
7 x(A,B) =@= x(B,A) true
8 x(A,B) =@= x(C,A) true

A term is always a variant of a copy of itself. Term copying takes place in, e.g., copy term/2,
findall/3 or proving a clause added with asserta/1. In the pure Prolog world (i.e.,
without attributed variables), =@=/2 behaves as if defined below. With attributed variables,
variant of the attributes is tested rather than trying to satisfy the constraints.

A =@= B :-
copy_term(A, Ac),
copy_term(B, Bc),
numbervars(Ac, 0, N),
numbervars(Bc, 0, N),
Ac == Bc.

The SWI-Prolog implementation is cycle-safe and can deal with variables that are shared be-
tween the left and right argument. Its performance is comparable to ==/2, both on success and
(early) failure. 18
17
Row 7 and 8 of this table may come as a surprise, but row 8 is satisfied by (left-to-right) A C, B A and (right-
to-left) C A, A B. If the same variable appears in different locations in the left and right term, the variant relation
can be broken by consistent binding of both terms. E.g., after binding the first argument in row 8 to a value, both terms are
no longer variant.
18
The current implementation is contributed by Kuniaki Mukai.

SWI-Prolog 7.4 Reference Manual

4.8. CONTROL PREDICATES 105

This predicate is known by the name variant/2 in some other Prolog systems. Be aware
of possible differences in semantics if the arguments contain attributed variables or share vari-
ables.19

+Term1 \=@= +Term2

Equivalent to \+Term1 =@= Term2. See =@=/2 for details.

subsumes term(@Generic, @Specific) [ISO]

True if Generic can be made equivalent to Specific by only binding variables in Generic. The
current implementation performs the unification and ensures that the variable set of Specific is
not changed by the unification. On success, the bindings are undone.20 This predicate respects
constraints.

term subsumer(+Special1, +Special2, -General)

General is the most specific term that is a generalisation of Special1 and Special2. The imple-
mentation can handle cyclic terms.

unifiable(@X, @Y, -Unifier)

If X and Y can unify, unify Unifier with a list of Var = Value, representing the bindings required
to make X and Y equivalent.21 This predicate can handle cyclic terms. Attributed variables are
handled as normal variables. Associated hooks are not executed.

?=(@Term1, @Term2)
Succeeds if the syntactic equality of Term1 and Term2 can be decided safely, i.e. if the result of
Term1 == Term2 will not change due to further instantiation of either term. It behaves as if
defined by ?=(X,Y) :- \+ unifiable(X,Y,[_|_]).

4.8 Control Predicates

The predicates of this section implement control structures. Normally the constructs in this section,
except for repeat/0, are translated by the compiler. Please note that complex goals passed as ar-
guments to meta-predicates such as findall/3 below cause the goal to be compiled to a temporary
location before execution. It is faster to define a sub-predicate (i.e. one character atoms/1 in
the example below) and make a call to this simple predicate.

one_character_atoms(As) :-
findall(A, (current_atom(A), atom_length(A, 1)), As).

fail [ISO]
Always fail. The predicate fail/0 is translated into a single virtual machine instruction.

false [ISO]
Same as fail, but the name has a more declarative connotation.
19
In many systems variant is implemented using two calls to subsumes term/2.
20
This predicate is often named subsumes chk/2 in older Prolog dialects. The current name was established in the ISO
WG17 meeting in Edinburgh (2010). The chk postfix was considered to refer to determinism as in e.g., memberchk/2.
21
This predicate was introduced for the implementation of dif/2 and when/2 after discussion with Tom Schrijvers and
Bart Demoen. None of us is really happy with the name and therefore suggestions for a new name are welcome.

SWI-Prolog 7.4 Reference Manual

106 CHAPTER 4. BUILT-IN PREDICATES

true [ISO]
Always succeed. The predicate true/0 is translated into a single virtual machine instruction.

repeat [ISO]
Always succeed, provide an infinite number of choice points.

! [ISO]
Cut. Discard all choice points created since entering the predicate in which the cut appears.
In other words, commit to the clause in which the cut appears and discard choice points that
have been created by goals to the left of the cut in the current clause. Meta calling is opaque to
the cut. This implies that cuts that appear in a term that is subject to meta-calling (call/1)
only affect choice points created by the meta-called term. The following control structures are
transparent to the cut: ;/2, ->/2 and *->/2. Cuts appearing in the condition part of ->/2
and *->/2 are opaque to the cut. The table below explains the scope of the cut with examples.
Prunes here means prunes X choice point created by X.

t0 :- (a, !, b). % prunes a/0 and t0/0

t1 :- (a, !, fail ; b). % prunes a/0 and t1/0
t2 :- (a -> b, ! ; c). % prunes b/0 and t2/0
t3 :- call((a, !, fail ; b)). % prunes a/0
t4 :- \+(a, !, fail). % prunes a/0

:Goal1 , :Goal2 [ISO]

Conjunction. True if both Goal1 and Goal2 can be proved. It is defined as follows (this
definition does not lead to a loop as the second comma is handled by the compiler):

Goal1, Goal2 :- Goal1, Goal2.

:Goal1 ; :Goal2 [ISO]

The or predicate is defined as:

Goal1 ; _Goal2 :- Goal1.

_Goal1 ; Goal2 :- Goal2.

:Goal1 | :Goal2
Equivalent to ;/2. Retained for compatibility only. New code should use ;/2.

:Condition -> :Action [ISO]

If-then and If-Then-Else. The ->/2 construct commits to the choices made at its left-hand
side, destroying choice points created inside the clause (by ;/2), or by goals called by this
clause. Unlike !/0, the choice point of the predicate as a whole (due to multiple clauses) is
not destroyed. The combination ;/2 and ->/2 acts as if defined as:

If -> Then; _Else :- If, !, Then.

If -> _Then; Else :- !, Else.
If -> Then :- If, !, Then.

SWI-Prolog 7.4 Reference Manual

4.9. META-CALL PREDICATES 107

Please note that (If -> Then) acts as (If -> Then ; fail), making the construct fail if the condition
fails. This unusual semantics is part of the ISO and all de-facto Prolog standards.
Please note that (if->then;else) is read as ((if->then);else) and that the combined semantics
of this syntactic construct as defined above is different from the simple nesting of the two
individual constructs, i.e., the semantics of ->/2 changes when embedded in ;/2. See also
once/1.

:Condition *-> :Action ; :Else

This construct implements the so-called soft-cut. The control is defined as follows: If Condi-
tion succeeds at least once, the semantics is the same as (Condition, Action). If Condition does
not succeed, the semantics is that of (\+ Condition, Else). In other words, if Condition succeeds
at least once, simply behave as the conjunction of Condition and Action, otherwise execute
Else. The construct is known under the name if/3 in some other Prolog implementations.
The construct A *-> B, i.e., without an Else branch, is translated as the normal conjunction A,
B.22
This construct is rarely used. An example use case is the implementation of OPTIONAL in
SPARQL . The optional construct should preserve all solutions if the argument succeeds as least
once but still succeed otherwise. This is implemented as below.

optional(Goal) :-
( Goal
*-> true
; true
).

Now calling e.g., optional(member(X, [a,b])) has the solutions X = a and X = b,

while optional(member(X,[])) succeeds without binding X.

\+ :Goal [ISO]
True if Goal cannot be proven (mnemonic: + refers to provable and the backslash (\) is
normally used to indicate negation in Prolog).

4.9 Meta-Call Predicates

Meta-call predicates are used to call terms constructed at run time. The basic meta-call mechanism
offered by SWI-Prolog is to use variables as a subclause (which should of course be bound to a valid
goal at runtime). A meta-call is slower than a normal call as it involves actually searching the database
at runtime for the predicate, while for normal calls this search is done at compile time.

call(:Goal) [ISO]
Invoke Goal as a goal. Note that clauses may have variables as subclauses, which is identical
to call/1.
22
BUG: The decompiler implemented by clause/2 returns this construct as a normal conjunction too.

SWI-Prolog 7.4 Reference Manual

108 CHAPTER 4. BUILT-IN PREDICATES

call(:Goal, +ExtraArg1, . . . ) [ISO]

Append ExtraArg1, ExtraArg2, . . . to the argument list of Goal and call the result. For example,
call(plus(1), 2, X) will call plus(1, 2, X), binding X to 3.
The call/[2..] construct is handled by the compiler. The predicates call/[2-8] are defined
as real (meta-)predicates and are available to inspection through current predicate/1,
predicate property/2, etc.23 Higher arities are handled by the compiler and runtime
system, but the predicates are not accessible for inspection.24

apply(:Goal, +List)
Append the members of List to the arguments of Goal and call the resulting term. For example:
apply(plus(1), [2, X]) calls plus(1, 2, X). New code should use call/[2..] if
the length of List is fixed.

not(:Goal)
True if Goal cannot be proven. Retained for compatibility only. New code should use \+/1.

once(:Goal) [ISO]
Make a possibly nondet goal semidet, i.e., succeed at most once. Defined as:

once(Goal) :-
call(Goal), !.

once/1 can in many cases be replaced with ->/2. The only difference is how the cut behaves
(see !/0). The following two clauses below are identical. Be careful about the interaction with
;/2. The apply macros library defines an inline expansion of once/1, mapping it to
(Goal\send{true};fail). Using the full if-then-else constructs prevents its semantics
from being changed when embedded in a ;/2 disjunction.

1) a :- once((b, c)), d.
2) a :- b, c -> d.

ignore(:Goal)
Calls Goal as once/1, but succeeds, regardless of whether Goal succeeded or not. Defined as:

ignore(Goal) :-
Goal, !.
ignore(_).

call with depth limit(:Goal, +Limit, -Result)

If Goal can be proven without recursion deeper than Limit levels,
call with depth limit/3 succeeds, binding Result to the deepest recursion level
used during the proof. Otherwise, Result is unified with depth limit exceeded if the
23
Arities 2..8 are demanded by ISO/IEC 13211-1:1995/Cor.2:2012.
24
Future versions of the reflective predicate may fake the presence of call/9... Full logical behaviour, generating all
these pseudo predicates, is probably undesirable and will become impossible if max arity is removed.

SWI-Prolog 7.4 Reference Manual

4.9. META-CALL PREDICATES 109

limit was exceeded during the proof, or the entire predicate fails if Goal fails without exceeding
Limit.
The depth limit is guarded by the internal machinery. This may differ from the depth computed
based on a theoretical model. For example, true/0 is translated into an inline virtual machine
instruction. Also, repeat/0 is not implemented as below, but as a non-deterministic foreign
predicate.

repeat.
repeat :-
repeat.

As a result, call with depth limit/3 may still loop infinitely on programs that should
theoretically finish in finite time. This problem can be cured by using Prolog equivalents to
such built-in predicates.
This predicate may be used for theorem provers to realise techniques like iterative deepen-
ing. See also call with inference limit/3. It was implemented after discussion with
Steve Moyle [email protected].

call with inference limit(:Goal, +Limit, -Result)

Equivalent to call(Goal), but limits the number of inferences for each solution of Goal.25 .
Execution may terminate as follows:

If Goal does not terminate before the inference limit is exceeded, Goal is aborted by inject-
ing the exception inference limit exceeded into its execution. After termination
of Goal, Result is unified with the atom inference limit exceeded. Otherwise,
If Goal fails, call with inference limit/3 fails.
If Goal succeeds without a choice point, Result is unified with !.
If Goal succeeds with a choice point, Result is unified with true.
If Goal throws an exception, call with inference limit/3 re-throws the excep-
tion.

An inference is defined as a call or redo on a predicate. Please note that some primitive built-in
predicates are compiled to virtual machine instructions for which inferences are not counted.
The execution of predicates defined in other languages (e.g., C, C++) count as a single inference.
This includes potentially expensive built-in predicates such as sort/2.
Calls to this predicate may be nested. An inner call that sets the limit below the current is
honoured. An inner call that would terminate after the current limit does not change the effective
limit. See also call with depth limit/3 and call with time limit/2.

setup call cleanup(:Setup, :Goal, :Cleanup)

Calls (once(Setup), Goal). If Setup succeeds, Cleanup will be called exactly once after
Goal is finished: either on failure, deterministic success, commit, or an exception. The exe-
cution of Setup is protected from asynchronous interrupts like call with time limit/2
25
This predicate was realised after discussion with Ulrich Neumerkel and Markus Triska.

SWI-Prolog 7.4 Reference Manual

110 CHAPTER 4. BUILT-IN PREDICATES

(package clib) or thread signal/2. In most uses, Setup will perform temporary
side-effects required by Goal that are finally undone by Cleanup.
Success or failure of Cleanup is ignored, and choice points it created are destroyed (as
once/1). If Cleanup throws an exception, this is executed as normal.26
Typically, this predicate is used to cleanup permanent data storage required to execute Goal,
close file descriptors, etc. The example below provides a non-deterministic search for a term in
a file, closing the stream as needed.

term_in_file(Term, File) :-
setup_call_cleanup(open(File, read, In),
term_in_stream(Term, In),
close(In) ).

term_in_stream(Term, In) :-
repeat,
read(In, T),
( T == end_of_file
-> !, fail
; T = Term
).

Note that it is impossible to implement this predicate in Prolog. The closest approxima-
tion would be to read all terms into a list, close the file and call member/2. With-
out setup call cleanup/3 there is no way to gain control if the choice point left by
repeat/0 is removed by a cut or an exception.
setup call cleanup/3 can also be used to test determinism of a goal, providing a portable
alternative to deterministic/1:

?- setup_call_cleanup(true,(X=1;X=2), Det=yes).

X = 1 ;

X = 2,
Det = yes ;

This predicate is under consideration for inclusion into the ISO standard. For compatibility with
other Prolog implementations see call cleanup/2.
setup call catcher cleanup(:Setup, :Goal, +Catcher, :Cleanup)
Similar to setup call cleanup(Setup, Goal, Cleanup) with additional information on the
reason for calling Cleanup. Prior to calling Cleanup, Catcher unifies with the termination code
(see below). If this unification fails, Cleanup is not called.

exit
Goal succeeded without leaving any choice points.
26
BUG: During the execution of Cleanup, garbage collection and stack-shifts are disabled.

SWI-Prolog 7.4 Reference Manual

4.10. DELIMITED CONTINUATIONS 111

fail
Goal failed.
!
Goal succeeded with choice points and these are now discarded by the execution of a cut
(or other pruning of the search tree such as if-then-else).
exception(Exception)
Goal raised the given Exception.
external exception(Exception)
Goal succeeded with choice points and these are now discarded due to an exception. For
example:
?- setup_call_catcher_cleanup(true, (X=1;X=2),
Catcher, writeln(Catcher)),
throw(ball).
external_exception(ball)
ERROR: Unhandled exception: Unknown message: ball

call cleanup(:Goal, :Cleanup)

Same as setup call cleanup(true, Goal, Cleanup). This is provided for compatibility
with a number of other Prolog implementations only. Do not use call cleanup/2 if
you perform side-effects prior to calling that will be undone by Cleanup. Instead, use
setup call cleanup/3 with an appropriate first argument to perform those side-effects.

call cleanup(:Goal, +Catcher, :Cleanup)

Same as setup call catcher cleanup(true, Goal, Catcher, Cleanup). The same warn-
ing as for call cleanup/2 applies.

4.10 Delimited continuations

The predicates reset/3 and shift/1 implement delimited continuations for Prolog. Delimited
continuation for Prolog is described in [Schrijvers et al., 2013]. The mechanism allows for proper
coroutines, two or more routines whose execution is interleaved, while they exchange data. Note
that coroutines in this sense differ from coroutines realised using attributed variables as described
in chapter 7.
The suspension mechanism provided by delimited continuations is suitable for the implementation
of tabling [Desouter et al., 2015].

reset(:Goal, ?Ball, -Continuation)

Call Goal. If Goal calls shift/1 and the argument of shift/1 can be unified with Ball,27
shift/1 causes reset/3 to return, unifying Continuation with a goal that represents
the continuation after shift/1. In other words, meta-calling Continuation completes the
execution where shift it. If Goal does not call shift/1, both Ball and Continuation are
unified with the integer 0 (zero).
27
The argument order described in [Schrijvers et al., 2013] is reset(Goal,Continuation,Ball). We swapped the argu-
ment order for compatibility with catch/3

SWI-Prolog 7.4 Reference Manual

112 CHAPTER 4. BUILT-IN PREDICATES

shift(+Ball)
Abandon the execution of the current goal, returning control to just after the matching
reset/3 call. This is similar to throw/1 except that (1) nothing is undone and (2) the
3th argument of reset/3 is unified with the continuation, which allows the code calling
reset/3 to resume the current goal.

4.11 Exception handling

The predicates catch/3 and throw/1 provide ISO compliant raising and catching of exceptions.

catch(:Goal, +Catcher, :Recover) [ISO]

Behaves as call/1 if no exception is raised when executing Goal. If an exception is raised
using throw/1 while Goal executes, and the Goal is the innermost goal for which Catcher
unifies with the argument of throw/1, all choice points generated by Goal are cut, the system
backtracks to the start of catch/3 while preserving the thrown exception term, and Recover
is called as in call/1.
The overhead of calling a goal through catch/3 is comparable to call/1. Recovery from
an exception is much slower, especially if the exception term is large due to the copying thereof.

throw(+Exception) [ISO]
Raise an exception. The system looks for the innermost catch/3 ancestor for which Excep-
tion unifies with the Catcher argument of the catch/3 call. See catch/3 for details.
ISO demands that throw/1 make a copy of Exception, walk up the stack to a catch/3 call,
backtrack and try to unify the copy of Exception with Catcher. SWI-Prolog delays backtrack-
ing until it actually finds a matching catch/3 goal. The advantage is that we can start the
debugger at the first possible location while preserving the entire exception context if there is
no matching catch/3 goal. This approach can lead to different behaviour if Goal and Catcher
of catch/3 call shared variables. We assume this to be highly unlikely and could not think of
a scenario where this is useful.28
In addition to explicit calls to throw/1, many built-in predicates throw exceptions directly
from C. If the Exception term cannot be copied due to lack of stack space, the following actions
are tried in order:

1. If the exception is of the form error(Formal, ImplementationDefined), try to raise the

exception without the ImplementationDefined part.
2. Try to raise error(resource error(stack), global).
3. Abort (see abort/0).

If an exception is raised in a call-back from C (see chapter 11) and not caught in the same
call-back, PL next solution() fails and the exception context can be retrieved using
PL exception().
28
Id like to acknowledge Bart Demoen for his clarifications on these matters.

SWI-Prolog 7.4 Reference Manual

4.11. EXCEPTION HANDLING 113

4.11.1 Debugging and exceptions

Before the introduction of exceptions in SWI-Prolog a runtime error was handled by printing an error
message, after which the predicate failed. If the Prolog flag debug on error was in effect (default),
the tracer was switched on. The combination of the error message and trace information is generally
sufficient to locate the error.
With exception handling, things are different. A programmer may wish to trap an exception using
catch/3 to avoid it reaching the user. If the exception is not handled by user code, the interactive
top level will trap it to prevent termination.
If we do not take special precautions, the context information associated with an unexpected
exception (i.e., a programming error) is lost. Therefore, if an exception is raised which is not caught
using catch/3 and the top level is running, the error will be printed, and the system will enter trace
mode.
If the system is in a non-interactive call-back from foreign code and there is no catch/3 active
in the current context, it cannot determine whether or not the exception will be caught by the external
routine calling Prolog. It will then base its behaviour on the Prolog flag debug on error:

current prolog flag(debug on error, false)

The exception does not trap the debugger and is returned to the foreign routine calling Prolog,
where it can be accessed using PL exception(). This is the default.

current prolog flag(debug on error, true)

If the exception is not caught by Prolog in the current context, it will trap the tracer to help
analyse the context of the error.

While looking for the context in which an exception takes place, it is advised to switch on debug
mode using the predicate debug/0. The hook prolog exception hook/4 can be used to add
more debugging facilities to exceptions. An example is the library http/http error, generating
a full stack trace on errors in the HTTP server library.

4.11.2 The exception term

Built-in predicates generate exceptions using a term error(Formal, Context). The first argument
is the formal description of the error, specifying the class and generic defined context information.
When applicable, the ISO error term definition is used. The second part describes some additional
context to help the programmer while debugging. In its most generic form this is a term of the form
context(Name/Arity, Message), where Name/Arity describes the built-in predicate that raised the
error, and Message provides an additional description of the error. Any part of this structure may be a
variable if no information was present.

4.11.3 Printing messages

The predicate print message/2 is used to print a message term in a human-readable format.
The other predicates from this section allow the user to refine and extend the message system. A
common usage of print message/2 is to print error messages from exceptions. The code below
prints errors encountered during the execution of Goal, without further propagating the exception and
without starting the debugger.

SWI-Prolog 7.4 Reference Manual

114 CHAPTER 4. BUILT-IN PREDICATES

...,
catch(Goal, E,
( print_message(error, E),
fail
)),
...

Another common use is to define message hook/3 for printing messages that are normally silent,
suppressing messages, redirecting messages or make something happen in addition to printing the
message.

print message(+Kind, +Term)

The predicate print message/2 is used by the system and libraries to print messages.
Kind describes the nature of the message, while Term is a Prolog term that describes the
content. Printing messages through this indirection instead of using format/3 to the
stream user error allows displaying the message appropriate to the application (termi-
nal, logfile, graphics), acting on messages based on their content instead of a string (see
message hook/3) and creating language specific versions of the messages. See also
section 4.11.3. The following message kinds are known:

banner
The system banner message. Banner messages can be suppressed by setting the Prolog
flag verbose to silent.
debug(Topic)
Message from library(debug). See debug/3.
error
The message indicates an erroneous situation. This kind is used to print uncaught excep-
tions of type error(Formal, Context). See section introduction (section 4.11.3).
help
User requested help message, for example after entering h or ? to a prompt.
information
Information that is requested by the user. An example is statistics/0.
informational
Typically messages of events are progres that are considered useful to a developer. Such
messages can be suppressed by setting the Prolog flag verbose to silent.
silent
Message that is normally not printed. Applications may define message hook/3 to act
upon such messages.
trace
Messages from the (command line) tracer.
warning
The message indicates something dubious that is not considered fatal. For example,
discontiguous predicates (see discontiguous/1).

SWI-Prolog 7.4 Reference Manual

4.11. EXCEPTION HANDLING 115

The predicate print message/2 first translates the Term into a list of message lines (see
print message lines/3 for details). Next, it calls the hook message hook/3 to allow
the user to intercept the message. If message hook/3 fails it prints the message unless Kind
is silent.
The print message/2 predicate and its rules are in the file
hplhomei/boot/messages.pl, which may be inspected for more information on the
error messages and related error terms. If you need to write messages from your own
predicates, it is recommended to reuse the existing message terms if applicable. If no existing
message term is applicable, invent a fairly unique term that represents the event and define a
rule for the multifile predicate prolog:message//1. See section 4.11.3 for a deeper discussion
and examples.
See also message to string/2.

print message lines(+Stream, +Prefix, +Lines)

Print a message (see print message/2) that has been translated to a list of message ele-
ments. The elements of this list are:

hFormati-hArgsi
Where Format is an atom and Args is a list of format arguments. Handed to format/3.
flush
If this appears as the last element, Stream is flushed (see flush output/1) and no
final newline is generated. This is combined with a subsequent message that starts with
at same line to complete the line.
at same line
If this appears as first element, no prefix is printed for the first line and the line position is
not forced to 0 (see format/1, N).
ansi(+Attributes, +Format, +Args)
This message may be intercepted by means of the hook prolog:message line element/2.
The library ansi term implements this hook to achieve coloured output. If it is not
intercepted it invokes format(Stream, Format, Args).
nl
A new line is started. If the message is not complete, Prefix is printed before the remainder
of the message.
begin(Kind, Var)
end(Var)
The entire message is headed by begin(Kind, Var) and ended by end(Var). This feature
is used by, e.g., library ansi term to colour entire messages.
hFormati
Handed to format/3 as format(Stream, Format, []). Deprecated because it is am-
biguous if Format collides with one of the atomic commands.

See also print message/2 and message hook/3.

message hook(+Term, +Kind, +Lines)

Hook predicate that may be defined in the module user to intercept messages from

SWI-Prolog 7.4 Reference Manual

116 CHAPTER 4. BUILT-IN PREDICATES

print message/2. Term and Kind are the same as passed to print message/2. Lines
is a list of format statements as described with print message lines/3. See also
message to string/2.
This predicate must be defined dynamic and multifile to allow other modules defining clauses
for it too.

thread message hook(+Term, +Kind, +Lines)

As message hook/3, but this predicate is local to the calling thread (see
thread local/1). This hook is called before message hook/3. The pre-hook is
indented to catch messages they may be produced by calling some goal without affecting other
threads.

message property(+Kind, ?Property)

This hook can be used to define additional message kinds and the way they are displayed. The
following properties are defined:

color(-Attributes)
Print message using ANSI terminal attributes. See ansi format/3 for details. Here is
an example, printing help messages in blue:
:- multifile user:message_property/2.

user:message_property(help, color([fg(blue)])).

prefix(-Prefix)
Prefix printed before each line. This argument is handed to format/3. The default is
N. For example, messages of kind warning use NWarning: .
location prefix(+Location, -FirstPrefix, -ContinuePrefix)
Used for printing messages that are related to a source location. Currently, Location is a
term File:Line. FirstPrefix is the prefix for the first line and -ContinuePrefix is the prefix
for continuation lines. For example, the default for errors is
location_prefix(File:Line,
NERROR: w:d:-[File,Line], N\t)).

stream(-Stream)
Stream to which to print the message. Default is user error.
wait(-Seconds)
Amount of time to wait after printing the message. Default is not to wait.

prolog:message line element(+Stream, +Term)

This hook is called to print the individual elements of a message from
print message lines/3. This hook is used by e.g., library ansi term to colour
messages on ANSI-capable terminals.

message to string(+Term, -String)

Translates a message term into a string object (see section 5.2).

SWI-Prolog 7.4 Reference Manual

4.11. EXCEPTION HANDLING 117

version
Write the SWI-Prolog banner message as well as additional messages registered using
version/1. This is the default initialization goal which can be modified using -g.

version(+Message)
Register additional messages to be printed by version/0. Each registered message is handed
to the message translation DCG and can thus be defined using the hook prolog:message//1. If
not defined, it is simply printed.

Printing from libraries

Libraries should not use format/3 or other output predicates directly. Libraries that print informa-
tional output directly to the console are hard to use from code that depend on your textual output,
such as a CGI script. The predicates in section 4.11.3 define the API for dealing with messages. The
idea behind this is that a library that wants to provide information about its status, progress, events
or problems calls print message/2. The first argument is the level. The supported levels are de-
scribed with print message/2. Libraries typically use informational and warning, while
libraries should use exceptions for errors (see throw/1, type error/2, etc.).
The second argument is an arbitrary Prolog term that carries the information of the message, but
not the precise text. The text is defined by the grammar rule prolog:message//1. This distinction is
made to allow for translations and to allow hooks processing the information in a different way (e.g.,
to translate progress messages into a progress bar).
For example, suppose we have a library that must download data from the Internet (e.g., based on
http open/3). The library wants to print the progress after each downloaded file. The code below
is a good skeleton:

download_urls(List) :-
length(List, Total),
forall(nth1(I, List, URL),
( download_url(URL),
print_message(informational,
download_url(URL, I, Total)))).

The programmer can now specify the default textual output using the rule below. Note that this
rule may be in the same file or anywhere else. Notably, the application may come with several rule
sets for different languages. This, and the user-hook example below are the reason to represent the
message as a compound term rather than a string. This is similar to using message numbers in non-
symbolic languages. The documentation of print message lines/3 describes the elements that
may appear in the output list.

:- multifile
prolog:message//1.

prolog:message(download_url(URL, I, Total)) -->

{ Perc is round(I*100/Total) },
[ Downloaded w; D from D (d%)-[URL, I, Total, Perc] ].

SWI-Prolog 7.4 Reference Manual

118 CHAPTER 4. BUILT-IN PREDICATES

A user of the library may define rules for message hook/3. The rule below acts on the message
content. Other applications can act on the message level and, for example, popup a message box for
warnings and errors.

:- multifile user:message_hook/3.

message_hook(download_url(URL, I, Total), _Kind, _Lines) :-

<send this information to a GUI component>

In addition, using the command line option -q, the user can disable all informational messages.

4.12 Handling signals

As of version 3.1.0, SWI-Prolog is able to handle software interrupts (signals) in Prolog as well as in
foreign (C) code (see section 11.4.13).
Signals are used to handle internal errors (execution of a non-existing CPU instruction, arith-
metic domain errors, illegal memory access, resource overflow, etc.), as well as for dealing with
asynchronous interprocess communication.
Signals are defined by the POSIX standard and part of all Unix machines. The MS-Windows
Win32 provides a subset of the signal handling routines, lacking the vital functionality to raise a signal
in another thread for achieving asynchronous interprocess (or interthread) communication (Unix kill()
function).

on signal(+Signal, -Old, :New)

Determines the reaction on Signal. Old is unified with the old behaviour, while the behaviour is
switched to New. As with similar environment control predicates, the current value is retrieved
using on signal(Signal, Current, Current).
The action description is an atom denoting the name of the predicate that will be called if
Signal arrives. on signal/3 is a meta-predicate, which implies that hModulei:hNamei refers
to hNamei/1 in module hModulei. The handler is called with a single argument: the name of
the signal as an atom. The Prolog names for signals are explained below.
Two predicate names have special meaning. throw implies Prolog will map the signal onto
a Prolog exception as described in section 4.11. default resets the handler to the settings
active before SWI-Prolog manipulated the handler.
Signals bound to a foreign function through PL signal() are reported using the term
$foreign function(Address).
After receiving a signal mapped to throw, the exception raised has the following structure:

error(signal(<SigName>, <SigNum>), hContexti)

The signal names are defined by the POSIX standard as symbols of the form SIGSIGNAME.
The Prolog name for a signal is the lowercase version of SIGNAME. The predicate
current signal/3 may be used to map between names and signals.
Initially, some signals are mapped to throw, while all other signals are default. The fol-
lowing signals throw an exception: fpe, alrm, xcpu, xfsz and vtalrm.

SWI-Prolog 7.4 Reference Manual

4.13. DCG GRAMMAR RULES 119

current signal(?Name, ?Id, ?Handler)

Enumerate the currently defined signal handling. Name is the signal name, Id is the numerical
identifier and Handler is the currently defined handler (see on signal/3).

4.12.1 Notes on signal handling

Before deciding to deal with signals in your application, please consider the following:

Portability
On MS-Windows, the signal interface is severely limited. Different Unix brands support differ-
ent sets of signals, and the relation between signal name and number may vary. Currently, the
system only supports signals numbered 1 to 3229 . Installing a signal outside the limited set of
supported signals in MS-Windows crashes the application.

Safety
Immediately delivered signals (see below) are unsafe. This implies that foreign functions called
from a handler cannot safely use the SWI-Prolog API and cannot use C longjmp(). Handlers
defined as throw are unsafe. Handlers defined to call a predicate are safe. Note that the
predicate can call throw/1, but the delivery is delayed until Prolog is in a safe state.
The C-interface described in section 11.4.13 provides the option PL SIGSYNC to select either
safe synchronous or unsafe asynchronous delivery.

Time of delivery
Using throw or a foreign handler, signals are delivered immediately (as defined by the OS).
When using a Prolog predicate, delivery is delayed to a safe moment. Blocking system
calls or foreign loops may cause long delays. Foreign code can improve on that by calling
PL handle signals().
Signals are blocked when the garbage collector is active.

4.13 DCG Grammar rules

Grammar rules form a comfortable interface to difference lists. They are designed both to support
writing parsers that build a parse tree from a list of characters or tokens and for generating a flat list
from a term.
Grammar rules look like ordinary clauses using -->/2 for separating the head and body rather
than :-/2. Expanding grammar rules is done by expand term/2, which adds two additional
arguments to each term for representing the difference list.
The body of a grammar rule can contain three types of terms. A callable term is interpreted as a
reference to a grammar rule. Code between {. . . } is interpreted as plain Prolog code, and finally, a
list is interpreted as a sequence of literals. The Prolog control-constructs (\+/1, ->/2, ;//2, ,/2
and !/0) can be used in grammar rules.
We illustrate the behaviour by defining a rule set for parsing an integer.

integer(I) -->
digit(D0),
29
TBD: the system should support the Unix realtime signals

SWI-Prolog 7.4 Reference Manual

120 CHAPTER 4. BUILT-IN PREDICATES

digits(D),
{ number_codes(I, [D0|D])
}.

digits([D|T]) -->
digit(D), !,
digits(T).
digits([]) -->
[].

digit(D) -->
[D],
{ code_type(D, digit)
}.

Grammar rule sets are called using the built-in predicates phrase/2 and phrase/3:

phrase(:DCGBody, ?List)
Equivalent to phrase(DCGBody, InputList, []).

phrase(:DCGBody, ?List, ?Rest)

True when DCGBody applies to the difference List/Rest. Although DCGBody is typically a
callable term that denotes a grammar rule, it can be any term that is valid as the body of a DCG
rule.
The example below calls the rule set integer//1 defined in section 4.13 and available from
library(dcg/basics), binding Rest to the remainder of the input after matching the in-
teger.

?- [library(dcg/basics)].
?- atom_codes(42 times, Codes),
phrase(integer(X), Codes, Rest).
X = 42
Rest = [32, 116, 105, 109, 101, 115]

The next example exploits a complete body. Given the following definition of
digit weight//1, we can pose the query below.

digit_weight(W) -->
[D],
{ code_type(D, digit(W)) }.

?- atom_codes(Version 3.4, Codes),

phrase(("Version ",
digit_weight(Major),".",digit_weight(Minor)),
Codes).

SWI-Prolog 7.4 Reference Manual

4.13. DCG GRAMMAR RULES 121

Major = 3,
Minor = 4.

The SWI-Prolog implementation of phrase/3 verifies that the List and Rest arguments are
unbound, bound to the empty list or a list cons cell. Other values raise a type error.30 The
predicate call dcg/3 is provided to use grammar rules with terms that are not lists.
Note that the syntax for lists of codes changed in SWI-Prolog version 7 (see section 5.2). If a
DCG body is translated, both "text" and text is a valid code-list literal in version 7. A
version 7 string ("text") is not acceptable for the second and third arguments of phrase/3.
This is typically not a problem for applications as the input of a DCG rarely appears in the
source code. For testing in the toplevel, one must use double quoted text in versions prior to 7
and back quoted text in version 7 or later.
See also portray text/1, which can be used to print lists of character codes as a string to the
top level and debugger to facilitate debugging DCGs that process character codes. The library
apply macros compiles phrase/3 if the argument is sufficiently instantiated, eliminating
the runtime overhead of translating DCGBody and meta-calling.

call dcg(:DCGBody, ?State0, ?State)

As phrase/3, but without type checking State0 and State. This allows for using DCG rules
for threading an arbitrary state variable. This predicate was introduced after type checking was
added to phrase/3.31
A portable solution for threading state through a DCG can be implemented by wrapping the
state in a list and use the DCG semicontext facility. Subsequently, the following predicates may
be used to access and modify the state:32

state(S), [S] --> [S].

state(S0, S), [S] --> [S0].

As stated above, grammar rules are a general interface to difference lists. To illustrate, we show a
DCG-based implementation of reverse/2:

reverse(List, Reversed) :-
phrase(reverse(List), Reversed).

reverse([]) --> [].

reverse([H|T]) --> reverse(T), [H].

30
The ISO standard allows for both raising a type error and accepting any term as input and output. Note the tail of the
list is not checked for performance reasons.
31
After discussion with Samer Abdallah.
32
This solution was proposed by Markus Triska.

SWI-Prolog 7.4 Reference Manual

122 CHAPTER 4. BUILT-IN PREDICATES

4.14 Database
SWI-Prolog offers several ways to store data in globally accessible memory, i.e., outside the Prolog
stacks. Data stored this way notably does not change on backtracking. Typically it is a bad idea to use
any of the predicates in this section for realising global variables that can be assigned to. Typically,
first consider representing data processed by your program as terms passed around as predicate argu-
ments. If you need to reason over multiple solutions to a goal, consider findall/3, aggregate/3
and related predicates.
Nevertheless, there are scenarios where storing data outside the Prolog stacks is a good option.
Below are the main options for storing data:

Using dynamic predicates Dynamic predicates are predicates for which the list of clauses is mod-
ified at runtime using asserta/1, assertz/1, retract/1 or retractall/1. Fol-
lowing the ISO standard, predicates that are modified this way need to be declared using
the dynamic/1 directive. These facilities are defined by the ISO standard and widely sup-
ported. The mechanism is often considered slow in the literature. Performance depends
on the Prolog implementation. In SWI-Prolog, querying dynamic predicates has the same
performance as static ones. The manipulation predicates are fast. Using retract/1 or
retractall/1 on a predicate registers the predicate as dirty. Dirty predicates are cleaned
by garbage collect clauses/0, which is normally automatically invoked. Some work-
loads may result in significant performance reduction due to skipping retracted clauses and/or
clause garbage collection.
Dynamic predicates can be wrapped using library persistency to maintain a backup of the
data on disk. Dynamic predicates come in two flavours, shared between threads and local to
each thread. The latter version is created using the directive thread local/1.

The recorded database The recorded database registers a list of terms with a key, an atom or com-
pound term. The list is managed using recorda/3, recordz/3 and erase/1. It is queried
using recorded/3. The recorded database is not part of the ISO standard but fairly widely
supported, notably in implementations building on the Edinburgh tradition. There are few
reasons to use this database in SWI-Prolog due to the good performance of dynamic predicates.
Advantages are (1) the handle provides a direct reference to a term, (2) cyclic terms can be
stored and (3) attributes (section 7.1) are preserved. Disadvantages are (1) the terms in a list
associated with a key are not indexed, (2) the poorly specified immediate update semantics (see
section 4.14.5 applies to the recorded database and (3) reduced portability.

The flag/3 predicate The predicate flag/3 associates one simple value (number or atom) with
a key (atom, integer or compound). It is an old SWI-Prolog specific predicate that should be
considered deprecated, although there is no plan to remove it.

Using global variables The predicates b setval/2 and nb setval/2 associate a term living
on the Prolog stack with a name, either backtrackable or non-backtrackable. Backtrack-
able and non-backtrackable assignment without using a global name can be realised with
setarg/3 and nb setarg/3. Notably the latter are used to realise aggregation as e.g.,
aggregate all/3 performs.

Tries As of version 7.3.21, SWI-Prolog provides tries (prefix trees) to associate a term variant with
a value. Tries have been introduced to support tabling and are described in section 4.14.4.

SWI-Prolog 7.4 Reference Manual

4.14. DATABASE 123

4.14.1 Managing (dynamic) predicates

abolish(:PredicateIndicator) [ISO]
Removes all clauses of a predicate with functor Functor and arity Arity from the database. All
predicate attributes (dynamic, multifile, index, etc.) are reset to their defaults. Abolishing an
imported predicate only removes the import link; the predicate will keep its old definition in its
definition module.
According to the ISO standard, abolish/1 can only be applied to dynamic procedures.
This is odd, as for dealing with dynamic procedures there is already retract/1 and
retractall/1. The abolish/1 predicate was introduced in DEC-10 Prolog precisely
for dealing with static procedures. In SWI-Prolog, abolish/1 works on static procedures,
unless the Prolog flag iso is set to true.
It is advised to use retractall/1 for erasing all clauses of a dynamic predicate.

abolish(+Name, +Arity)
Same as abolish(Name/Arity). The predicate abolish/2 conforms to the Edinburgh
standard, while abolish/1 is ISO compliant.

copy predicate clauses(:From, :To)

Copy all clauses of predicate From to To. The predicate To must be dynamic or undefined. If
To is undefined, it is created as a dynamic predicate holding a copy of the clauses of From. If
To is a dynamic predicate, the clauses of From are added (as in assertz/1) to the clauses of
To. To and From must have the same arity. Acts as if defined by the program below, but at a
much better performance by avoiding decompilation and compilation.

copy_predicate_clauses(From, To) :-
head(From, MF:FromHead),
head(To, MT:ToHead),
FromHead =.. [_|Args],
ToHead =.. [_|Args],
forall(clause(MF:FromHead, Body),
assertz(MT:ToHead, Body)).

head(From, M:Head) :-
strip_module(From, M, Name/Arity),
functor(Head, Name, Arity).

redefine system predicate(+Head)

This directive may be used both in module user and in normal modules to redefine any
system predicate. If the system definition is redefined in module user, the new definition is
the default definition for all sub-modules. Otherwise the redefinition is local to the module.
The system definition remains in the module system.
Redefining system predicate facilitates the definition of compatibility packages. Use in other
contexts is discouraged.

retract(+Term) [ISO,nondet]
When Term is an atom or a term it is unified with the first unifying fact or clause in the database.

SWI-Prolog 7.4 Reference Manual

124 CHAPTER 4. BUILT-IN PREDICATES

The fact or clause is removed from the database. The retract/1 predicate respects the
logical update view. This implies that retract/1 succeeds for all clauses that match Term
when the predicate was called. The example below illustrates that the first call to retract/1
succeeds on bee on backtracking despite the fact that bee is already retracted.33 .

:- dynamic insect/1.
insect(ant).
insect(bee).

?- ( retract(insect(I)),
writeln(I),
retract(insect(bee)),
fail
; true
).
ant ;
bee.

If multiple threads start a retract on the same predicate at the same time their notion of the entry
generation is adjusted such that they do not retract the same first clause. This implies that, if
multiple threads use once(retract(Term)), no two threads will retract the same clause.
Note that on backtracking over retract/1, multiple threads may retract the same clause as
both threads respect the logical update view.
retractall(+Head) [ISO,det]
All facts or clauses in the database for which the head unifies with Head are removed. If Head
refers to a predicate that is not defined, it is implicitly created as a dynamic predicate. See also
dynamic/1.34
asserta(+Term) [ISO]
Assert a fact or clause in the database. Term is asserted as the first fact or clause of the corre-
sponding predicate. Equivalent to assert/1, but Term is asserted as first clause or fact of
the predicate. If the program space for the target module is limited (see set module/1),
asserta/1 can raise a resource error(program space).
assertz(+Term) [ISO]
Equivalent to asserta/1, but Term is asserted as the last clause or fact of the predicate.
assert(+Term)
Equivalent to assertz/1. Deprecated: new code should use assertz/1.
asserta(+Term, -Reference)
Asserts a clause as asserta/1 and unifies Reference with a handle to this clause. The handle
can be used to access this specific clause using clause/3 and erase/1.
assertz(+Term, -Reference)
Equivalent to asserta/1, asserting the new clause as the last clause of the predicate.
33
Example by Jan Burse
34
The ISO standard only allows using dynamic/1 as a directive.

SWI-Prolog 7.4 Reference Manual

4.14. DATABASE 125

assert(+Term, -Reference)
Equivalent to assertz/2. Deprecated: new code should use assertz/2.

4.14.2 The recorded database

recorda(+Key, +Term, -Reference)
Assert Term in the recorded database under key Key. Key is a small integer (range
min tagged integer . . . max tagged integer, atom or compound term. If the key is
a compound term, only the name and arity define the key. Reference is unified with an opaque
handle to the record (see erase/1).

recorda(+Key, +Term)
Equivalent to recorda(Key, Term, ).

recordz(+Key, +Term, -Reference)

Equivalent to recorda/3, but puts the Term at the tail of the terms recorded under Key.

recordz(+Key, +Term)
Equivalent to recordz(Key, Term, ).

recorded(?Key, ?Value, ?Reference)

True if Value is recorded under Key and has the given database Reference. If Reference is given,
this predicate is semi-deterministic. Otherwise, it must be considered non-deterministic. If
neither Reference nor Key is given, the triples are generated as in the code snippet below.35 See
also current key/1.

current_key(Key),
recorded(Key, Value, Reference)

recorded(+Key, -Value)
Equivalent to recorded(Key, Value, ).

erase(+Reference)
Erase a record or clause from the database. Reference is a db-reference returned by
recorda/3, recordz/3 or recorded/3, clause/3, assert/2, asserta/2 or
assertz/2. Fail silently if the referenced object no longer exists. Notably, if multiple
threads attempt to erase the same clause one will succeed and the others will fail.

instance(+Reference, -Term)
Unify Term with the referenced clause or database record. Unit clauses are represented as Head
:- true.

4.14.3 Flags
The predicate flag/3 is the oldest way to store global non-backtrackable data in SWI-Prolog. Flags
are global and shared by all threads. Their value is limited to atoms, small (64-bit) integers and floating
35
Note that, without a given Key, some implementations return triples in the order defined by recorda/2 and
recordz/2.

SWI-Prolog 7.4 Reference Manual

126 CHAPTER 4. BUILT-IN PREDICATES

point numbers. Flags are thread-safe. The flags described in this section must not be confused with
Prolog flags described in section 2.11.

get flag(+Key, -Value)

True when Value is the value currently associated with Key. If Key does not exist, a new flag
with value 0 (zero) is created.

set flag(+Key, Value)

Set flag Key to Value. Value must be an atom, small (64-bit) integer or float.

flag(+Key, -Old, +New)

True when Old is the current value of the flag Key and the flag has been set to New. New can be
an arithmetic expression. The update is atomic. This predicate can be used to create a shared
global counter as illustrated in the example below.

next_id(Id) :-
flag(my_id, Id, Id+1).

4.14.4 Tries
Tries (also called digital tree, radix tree or prefix tree maintain a mapping between a variant of a
term (see =@=/2) and a value. They have been introduced in SWI-Prolog 7.3.21 as part of the
implementation of tabling. The current implementation is rather immature. In particular, the following
limitations currently apply:

Tries are not thread-safe.

Tries should not be modified while non-deterministic predicates such as trie gen/3 are run-
ning on the trie.
Terms cannot have attributed variables.
Terms cannot be cyclic. Possibly this will not change because cyclic terms can only be sup-
ported after creating a canonical form of the term.

We give the definition of these predicates for reference and debugging tabled predicates.
Future versions are likely to get a more stable and safer implementation. The API to tries
should not be considered stable.

trie new(-Trie)
Create a new trie and unify Trie with a handle to the trie. The trie handle is a blob. Tries are
subject to atom garbage collection.

trie destroy(+Trie)
Destroy Trie. This removes all nodes from the trie and causes further access to Trie to raise an
existence error exception. The handle itself is reclaimed by atom garbage collection.

current trie(-Trie) [nondet]

True if Trie is a currently existing trie. As this enumerates and then filters all known atoms this
predicate is slow and should only be used for debugging purposes.

SWI-Prolog 7.4 Reference Manual

4.14. DATABASE 127

trie insert(+Trie, +Key, +Value)

Insert the term Key into Trie and associate it with Value. Currently, Value is either an atom or
small integer. Future versions will probably allow for arbitrary terms.

trie lookup(+Trie, +Key, -Value)

True if the term Key is in Trie and associated with Value.

trie insert new(+Trie, +Term, -Handle)

Add Term to Trie and return a handle to the node. Fails if Term is already part of the Trie. The
handle can used with trie term/2 to retrieve (a copy of) Term. This predicate is currently
unsafe as Handle is an integer used to encode a pointer. It was used to implement a pure Prolog
version of the tabling library.

trie term(+Handle, -Term)

True when Term is a copy of the term associated with Handle. The result is undefined (including
crashes) if Handle is not a handle returned by trie insert new/3 or the node has been
removed afterwards.

trie gen(+Trie, ?Key, -Value) [nondet]

True when Key is associated with Value in Trie. Backtracking retrieves all pairs. Currently
scans the entire trie, even if Key is partly known. Currently unsafe if Trie is modified while the
values are being enumerated.

trie property(?Trie, ?Property) [nondet]

True if Trie exists with Property. Intended for debugging and statistical purposes. Retrieving
some of these properties visit all nodes of the trie. Defined properties are

value count(-Count)
Number of key-value pairs in the trie.
node count(-Count)
Number of nodes in the trie.
size(-Bytes)
Required storage space of the trie.
hashed(-Count)
Number of nodes that use a hashed index to its children.

4.14.5 Update view

Traditionally, Prolog systems used the immediate update view: new clauses became visible to predi-
cates backtracking over dynamic predicates immediately, and retracted clauses became invisible im-
mediately.
Starting with SWI-Prolog 3.3.0 we adhere to the logical update view, where backtrackable pred-
icates that enter the definition of a predicate will not see any changes (either caused by assert/1
or retract/1) to the predicate. This view is the ISO standard, the most commonly used and the
most safe.36 Logical updates are realised by keeping reference counts on predicates and generation
information on clauses. Each change to the database causes an increment of the generation of the
database. Each goal is tagged with the generation in which it was started. Each clause is flagged with
36
For example, using the immediate update view, no call to a dynamic predicate is deterministic.

SWI-Prolog 7.4 Reference Manual

128 CHAPTER 4. BUILT-IN PREDICATES

the generation it was created in as well as the generation it was erased from. Only clauses with a
created . . . erased interval that encloses the generation of the current goal are considered visible.

4.14.6 Indexing databases

The indexing capabilities of SWI-Prolog are described in section 2.17. Summarizing, SWI-Prolog
creates indexes for any applicable argument, but only on one argument, and does not index on argu-
ments of compound terms. The predicates below provide building blocks to circumvent the limitations
of the current indexing system.
Programs that aim at portability should consider using term hash/2 and term hash/4 to
design their database such that indexing on constant or functor (name/arity reference) on the first
argument is sufficient.

term hash(+Term, -HashKey) [det]

If Term is a ground term (see ground/1), HashKey is unified with a positive integer value that
may be used as a hash key to the value. If Term is not ground, the predicate leaves HashKey an
unbound variable. Hash keys are in the range 0 . . . 16, 777, 215, the maximal integer that can
be stored efficiently on both 32 and 64 bit platforms.
This predicate may be used to build hash tables as well as to exploit argument indexing to find
complex terms more quickly.
The hash key does not rely on temporary information like addresses of atoms and may be as-
sumed constant over different invocations and versions of SWI-Prolog.37 Hashes differ between
big and little endian machines. The term hash/2 predicate is cycle-safe.38
term hash(+Term, +Depth, +Range, -HashKey) [det]
As term hash/2, but only considers Term to the specified Depth. The top-level term has
depth 1, its arguments have depth 2, etc. That is, Depth = 0 hashes nothing; Depth = 1 hashes
atomic values or the functor and arity of a compound term, not its arguments; Depth = 2 also
indexes the immediate arguments, etc.
HashKey is in the range [0 . . . Range 1]. Range must be in the range [1 . . . 2147483647]
variant sha1(+Term, -SHA1) [det]
Compute a SHA1-hash from Term. The hash is represented as a 40-byte hexadecimal atom.
Unlike term hash/2 and friends, this predicate produces a hash key for non-ground terms.
The hash is invariant over variable-renaming (see =@=/2) and constants over different
invocations of Prolog.39
This predicate raises an exception when trying to compute the hash on a cyclic term or at-
tributed term. Attributed terms are not handled because subsumes chk/2 is not considered
well defined for attributed terms. Cyclic terms are not supported because this would require es-
tablishing a canonical cycle. That is, given A=[aA] and B=[a,aB], A and B should produce
the same hash. This is not (yet) implemented.
This hash was developed for lookup of solutions to a goal stored in a table. By using a cryp-
tographic hash, heuristic algorithms can often ignore the possibility of hash collisions and thus
avoid storing the goal term itself as well as testing using =@=/2.
37
Last change: version 5.10.4
38
BUG: All arguments that (indirectly) lead to a cycle have the same hash key.
39
BUG: The hash depends on word order (big/little-endian) and the wordsize (32/64 bits).

SWI-Prolog 7.4 Reference Manual

4.15. DECLARING PREDICATE PROPERTIES 129

variant hash(+Term, -HashKey) [det]

Similar to variant sha1/2, but using a non-cryptographic hash and produces an integer
result like term hash/2. This version does deal with attributed variables, processing them
as normal variables. This hash is primarily intended to speedup finding variant terms in a set of
terms. 40

4.15 Declaring predicate properties

This section describes directives which manipulate attributes of predicate definitions. The functors
dynamic/1, multifile/1, discontiguous/1 and public/1 are operators of priority 1150
(see op/3), which implies that the list of predicates they involve can just be a comma-separated list:

:- dynamic
foo/0,
baz/2.

In SWI-Prolog all these directives are just predicates. This implies they can also be called by a pro-
gram. Do not rely on this feature if you want to maintain portability to other Prolog implementations.

dynamic :PredicateIndicator, . . . [ISO]

Informs the interpreter that the definition of the predicate(s) may change during execution
(using assert/1 and/or retract/1). In the multithreaded version, the clauses of dynamic
predicates are shared between the threads. The directive thread local/1 provides an
alternative where each thread has its own clause list for the predicate. Dynamic predicates can
be turned into static ones using compile predicates/1.
compile predicates(:ListOfPredicateIndicators)
Compile a list of specified dynamic predicates (see dynamic/1 and assert/1) into normal
static predicates. This call tells the Prolog environment the definition will not change anymore
and further calls to assert/1 or retract/1 on the named predicates raise a permission
error. This predicate is designed to deal with parts of the program that are generated at runtime
but do not change during the remainder of the program execution.41
multifile :PredicateIndicator, . . . [ISO]
Informs the system that the specified predicate(s) may be defined over more than one file. This
stops consult/1 from redefining a predicate when a new definition is found.
discontiguous :PredicateIndicator, . . . [ISO]
Informs the system that the clauses of the specified predicate(s) might not be together in the
source file. See also style check/1.
public :PredicateIndicator, . . .
Instructs the cross-referencer that the predicate can be called. It has no semantics.42 The public
40
BUG: As variant sha1/2, cyclic terms result in an exception.
41
The specification of this predicate is from Richard OKeefe. The implementation is allowed to optimise the predicate.
This is not yet implemented. In multithreaded Prolog, however, static code runs faster as it does not require synchronisation.
This is particularly true on SMP hardware.
42
This declaration is compatible with SICStus. In YAP, public/1 instructs the compiler to keep the source. As the
source is always available in SWI-Prolog, our current interpretation also enhances the compatibility with YAP.

SWI-Prolog 7.4 Reference Manual

130 CHAPTER 4. BUILT-IN PREDICATES

declaration can be queried using predicate property/2. The public/1 directive does
not export the predicate (see module/1 and export/1). The public directive is used for
(1) direct calls into the module from, e.g., foreign code, (2) direct calls into the module from
other modules, or (3) flag a predicate as being called if the call is generated by meta-calling
constructs that are not analysed by the cross-referencer.

4.16 Examining the program

current atom(-Atom)
Successively unifies Atom with all atoms known to the system. Note that current atom/1
always succeeds if Atom is instantiated to an atom.

current blob(?Blob, ?Type)

Examine the type or enumerate blobs of the given Type. Typed blobs are supported through
the foreign language interface for storing arbitrary BLOBs (Binary Large Object) or handles to
external entities. See section 11.4.7 for details.

current functor(?Name, ?Arity)

Successively unifies Name with the name and Arity with the arity of functors known to the
system.

current flag(-FlagKey)
Successively unifies FlagKey with all keys used for flags (see flag/3).

current key(-Key)
Successively unifies Key with all keys used for records (see recorda/3, etc.).

current predicate(:PredicateIndicator) [ISO]

True if PredicateIndicator is a currently defined predicate. A predicate is considered defined
if it exists in the specified module, is imported into the module or is defined in one of the
modules from which the predicate will be imported if it is called (see section 6.9). Note that
current predicate/1 does not succeed for predicates that can be autoloaded. See also
current predicate/2 and predicate property/2.
If PredicateIndicator is not fully specified, the predicate only generates values that are defined
in or already imported into the target module. Generating all callable predicates therefore re-
quires enumerating modules using current module/1. Generating predicates callable in
a given module requires enumerating the import modules using import module/2 and the
autoloadable predicates using the predicate property/2 autoload.

current predicate(?Name, :Head)

Classical pre-ISO implementation of current predicate/1, where the predicate is repre-
sented by the head term. The advantage is that this can be used for checking the existence of a
predicate before calling it without the need for functor/3:

call_if_exists(G) :-
current_predicate(_, G),
call(G).

SWI-Prolog 7.4 Reference Manual

4.16. EXAMINING THE PROGRAM 131

Because of this intended usage, current predicate/2 also succeeds if the predicate can
be autoloaded. Unfortunately, checking the autoloader makes this predicate relatively slow, in
particular because a failed lookup of the autoloader will cause the autoloader to verify that its
index is up-to-date.
predicate property(:Head, ?Property)
True when Head refers to a predicate that has property Property. With sufficiently instan-
tiated Head, predicate property/2 tries to resolve the predicate the same way
as calling it would do: if the predicate is not defined it scans the default modules (see
default module/2) and finally tries the autoloader. Unlike calling, failure to find the
target predicate causes predicate property/2 to fail silently. If Head is not sufficiently
bound, only currently locally defined and already imported predicates are enumerated.
See current predicate/1 for enumerating all predicates. A common issue concerns
generating all built-in predicates. This can be achieved using the code below:

generate_built_in(Name/Arity) :-
predicate_property(system:Head, built_in),
functor(Head, Name, Arity),
\+ sub_atom(Name, 0, _, _, $). % discard reserved names

Property is one of:

autoload(File)
True if the predicate can be autoloaded from the file File. Like undefined, this property
is not generated.
built in
True if the predicate is locked as a built-in predicate. This implies it cannot be redefined
in its definition module and it can normally not be seen in the tracer.
defined
True if the predicate is defined. This property is aware of sources being reloaded, in
which case it claims the predicate defined only if it is defined in another source or it has
seen a definition in the current source. See compile aux clauses/1.
dynamic
True if assert/1 and retract/1 may be used to modify the predicate. This property
is set using dynamic/1.
exported
True if the predicate is in the public list of the context module.
imported from(Module)
Is true if the predicate is imported into the context module from module Module.
file(FileName)
Unify FileName with the name of the source file in which the predicate is defined. See
also source file/2 and the property line count. Note that this reports the
file of the first clause of a predicate. A more robust interface can be achieved using
nth clause/3 and clause property/2.
foreign
True if the predicate is defined in the C language.

SWI-Prolog 7.4 Reference Manual

132 CHAPTER 4. BUILT-IN PREDICATES

implementation module(-Module)
True when Module is the module in which Head is or will be defined. Resolving this
property goes through the same search mechanism as when the an undefined predicate is
encountered, but does not perform any loading. It searches (1) the module inheritence
hierarchy (see default module/2) and (2) the autoload index if the unknown flag is
not set to fail in the target module.
indexed(Indexes)
Indexes43 is a list of additional (hash) indexes on the predicate. Each element of the list
is a term ArgSpec-Index. Currently ArgSpec is an integer denoting the argument position
and Index is a term hash(Buckets, Speedup, IsList). Here Buckets is the number of
buckets in the hash and Speedup is the expected speedup relative to trying all clauses
linearly. IsList indicates that a list is created for all clauses with the same key. This is
currently not used.
interpreted
True if the predicate is defined in Prolog. We return true on this because, although the
code is actually compiled, it is completely transparent, just like interpreted code.
iso
True if the predicate is covered by the ISO standard (ISO/IEC 13211-1).
line count(LineNumber)
Unify LineNumber with the line number of the first clause of the predicate. Fails if the
predicate is not associated with a file. See also source file/2. See also the file
property above, notably the reference to clause property/2.
multifile
True if there may be multiple (or no) files providing clauses for the predicate. This
property is set using multifile/1.
meta predicate(Head)
If the predicate is declared as a meta-predicate using meta predicate/1, unify Head
with the head-pattern. The head-pattern is a compound term with the same name and
arity as the predicate where each argument of the term is a meta-predicate specifier. See
meta predicate/1 for details.
nodebug
Details of the predicate are not shown by the debugger. This is the default for built-
in predicates. User predicates can be compiled this way using the Prolog flag
generate debug info.
notrace
Do not show ports of this predicate in the debugger.
number of clauses(ClauseCount)
Unify ClauseCount to the number of clauses associated with the predicate. Fails for
foreign predicates.
number of rules(RuleCount)
Unify RuleCount to the number of clauses associated with the predicate. A rule is defined
as a clauses that has a body that is not just true (i.e., a fact). Fails for foreign
43
This predicate property should be used for analysis and statistics only. The exact representation of Indexes may change
between versions.

SWI-Prolog 7.4 Reference Manual

4.16. EXAMINING THE PROGRAM 133

predicates. This property is used to avoid analysing predicates with only facts in
prolog codewalk.
public
Predicate is declared public using public/1. Note that without further definition,
public predicates are considered undefined and this property is not reported.
quasi quotation syntax
The predicate (with arity 4) is declared to provide quasi quotation syntax with
quasi quotation syntax/1.
static
The definition can not be modified using assertz/1 and friends. This property is the
opposite from dynamic, i.e., for each defined predicate, either static or dynamic is
true but never both.
thread local
If true (only possible on the multithreaded version) each thread has its own clauses for
the predicate. This property is set using thread local/1.
transparent
True if the predicate is declared transparent using the module transparent/1
or meta predicate/1 declaration. In the latter case the property
meta predicate(Head) is also provided. See chapter 6 for details.
undefined
True if a procedure definition block for the predicate exists, but there are no clauses for
it and it is not declared dynamic or multifile. This is true if the predicate occurs in the
body of a loaded predicate, an attempt to call it has been made via one of the meta-call
predicates, the predicate has been declared as e.g., a meta-predicate or the predicate had
a definition in the past. Originally used to find missing predicate definitions. The current
implementation of list undefined/0 used cross-referencing. Deprecated.
visible
True when predicate can be called without raising a predicate existence error. This means
that the predicate is (1) defined, (2) can be inherited from one of the default modules (see
default module/2) or (3) can be autoloaded. The behaviour is logically consistent
iff the property visible is provided explicitly. If the property is left unbound, only
defined predicates are enumerated.
volatile
If true, the clauses are not saved into a saved state by qsave program/[1,2]. This
property is set using volatile/1.

dwim predicate(+Term, -Dwim)

Do What I Mean (dwim) support predicate. Term is a term, whose name and arity are used
as a predicate specification. Dwim is instantiated with the most general term built from Name
and the arity of a defined predicate that matches the predicate specified by Term in the Do
What I Mean sense. See dwim match/2 for Do What I Mean string matching. Internal
system predicates are not generated, unless the access level is system (see access level).
Backtracking provides all alternative matches.

SWI-Prolog 7.4 Reference Manual

134 CHAPTER 4. BUILT-IN PREDICATES

clause(:Head, ?Body) [ISO]

True if Head can be unified with a clause head and Body with the corresponding clause body.
Gives alternative clauses on backtracking. For facts, Body is unified with the atom true.
clause(:Head, ?Body, ?Reference)
Equivalent to clause/2, but unifies Reference with a unique reference to the clause (see also
assert/2, erase/1). If Reference is instantiated to a reference the clauses head and body
will be unified with Head and Body.
nth clause(?Pred, ?Index, ?Reference)
Provides access to the clauses of a predicate using their index number. Counting starts at 1.
If Reference is specified it unifies Pred with the most general term with the same name/arity
as the predicate and Index with the index number of the clause. Otherwise the name and arity
of Pred are used to determine the predicate. If Index is provided, Reference will be unified
with the clause reference. If Index is unbound, backtracking will yield both the indexes and
the references of all clauses of the predicate. The following example finds the 2nd clause of
append/3:

?- use_module(library(lists)).
...
?- nth_clause(append(_,_,_), 2, Ref), clause(Head, Body, Ref).
Ref = <clause>(0x994290),
Head = lists:append([_G23|_G24], _G21, [_G23|_G27]),
Body = append(_G24, _G21, _G27).

clause property(+ClauseRef, -Property)

Queries properties of a clause. ClauseRef is a reference to a clause as produced by clause/3,
nth clause/3 or prolog frame attribute/3. Unlike most other predicates that
access clause references, clause property/2 may be used to get information about erased
clauses that have not yet been reclaimed. Property is one of the following:

file(FileName)
Unify FileName with the name of the file from which the clause is loaded. Fails if the
clause was not created by loading a file (e.g., clauses added using assertz/1). See
also source.
line count(LineNumber)
Unify LineNumber with the line number of the clause. Fails if the clause is not associated
to a file.
size(SizeInBytes)
True when SizeInBytes is the size that the clause uses in memory in bytes. The size
required by a predicate also includes the predicate data record, a linked list of clauses,
clause selection instructions and optionally one or more clause indexes.
source(FileName)
Unify FileName with the name of the source file that created the clause. This is the same
as the file property, unless the file is loaded from a file that is textually included into
source using include/1. In this scenario, file is the included file, while the source
property refers to the main file.

SWI-Prolog 7.4 Reference Manual

4.17. INPUT AND OUTPUT 135

fact
True if the clause has no body.
erased
True if the clause has been erased, but not yet reclaimed because it is referenced.
predicate(PredicateIndicator)
PredicateIndicator denotes the predicate to which this clause belongs. This is needed to
obtain information on erased clauses because the usual way to obtain this information
using clause/3 fails for erased clauses.
module(Module)
Module is the context module used to execute the body of the clause. For normal clauses,
this is the same as the module in which the predicate is defined. However, if a clause
is compiled with a module qualified head, the clause belongs to the predicate with the
qualified head, while the body is executed in the context of the module in which the
clause was defined.

4.17 Input and output

SWI-Prolog provides two different packages for input and output. The native I/O system is based
on the ISO standard predicates open/3, close/1 and friends.44 Being more widely portable and
equipped with a clearer and more robust specification, new code is encouraged to use these predicates
for manipulation of I/O streams.
Section 4.17.3 describes tell/1, see/1 and friends, providing I/O in the spirit of the traditional
Edinburgh standard. These predicates are layered on top of the ISO predicates. Both packages are
fully integrated; the user may switch freely between them.

4.17.1 Predefined stream aliases

Each thread has five stream aliases: user input, user output, user error,
current input, and current output. Newly created threads inherit these stream aliases
from their parent. The user input, user output and user error aliases of the main
thread are initially bound to the standard operating system I/O streams (stdin, stdout and stderr,
normally bound to the POSIX file handles 0, 1 and 2). These aliases may be re-bound, for ex-
ample if standard I/O refers to a window such as in the swipl-win.exe GUI executable for
Windows. They can be re-bound by the user using set prolog IO/3 and set stream/2 by
setting the alias of a stream (e.g, set stream(S, alias(user output))). An example of
rebinding can be found in library prolog server, providing a telnet service. The aliases
current input and current output define the source and destination for predicates that do
not take a stream argument (e.g., read/1, write/1, get code/1, . . . ). Initially, these are bound
to the same stream as user input and user error. They are re-bound by see/1, tell/1,
set input/1 and set output/1. The current output stream is also temporary re-bound
by with output to/2 or format/3 using e.g., format(atom(A), .... Note that code
which explicitly writes to the streams user output and user error will not be redirected by
with output to/2.
44
Actually based on Quintus Prolog, providing this interface before the ISO standard existed.

SWI-Prolog 7.4 Reference Manual

136 CHAPTER 4. BUILT-IN PREDICATES

Compatibility Note that the ISO standard only defines the user * streams. The current streams
can be accessed using current input/1 and current output/1. For example, an ISO com-
patible implementation of write/1 is

write(Term) :- current_output(Out), write_term(Out, Term).

while SWI-Prolog additionally allows for

write(Term) :- write(current_output, Term).

4.17.2 ISO Input and Output Streams

The predicates described in this section provide ISO compliant I/O, where streams are explicitly cre-
ated using the predicate open/3. The resulting stream identifier is then passed as a parameter to the
reading and writing predicates to specify the source or destination of the data.
This schema is not vulnerable to filename and stream ambiguities as well as changes to the work-
ing directory. On the other hand, using the notion of current-I/O simplifies reusability of code without
the need to pass arguments around. E.g., see with output to/2.
SWI-Prolog streams are, compatible with the ISO standard, either input or output streams. To
accommodate portability to other systems, a pair of streams can be packed into a stream-pair. See
stream pair/3 for details.
SWI-Prolog stream handles are unique symbols that have no syntactical representation. They are
written as <stream>(hex-number), which is not valid input for read/1. They are realised
using a blob of type stream (see blob/2 and section 11.4.7).

open(+SrcDest, +Mode, Stream, +Options) [ISO]

True when SrcDest can be opened in Mode and Stream is an I/O stream to/from the object.
SrcDest is normally the name of a file, represented as an atom or string. Mode is one of read,
write, append or update. Mode append opens the file for writing, positioning the file
pointer at the end. Mode update opens the file for writing, positioning the file pointer at the
beginning of the file without truncating the file. Stream is either a variable, in which case it
is bound to an integer identifying the stream, or an atom, in which case this atom will be the
stream identifier.45
SWI-Prolog also allows SrcDest to be a term pipe(Command). In this form, Command is
started as a child process and if Mode is write, output written to Stream is sent to the standard
input of Command. Viso versa, if Mode is read, data written by Command to the standard out-
put may be read from Stream. On Unix systems, Command is handed to popen() which hands it
to the Unix shell. On Windows, Command is executed directly. See also process create/3
from process.
The following Options are recognised by open/4:

alias(Atom)
Gives the stream a name. Below is an example. Be careful with this option as stream
names are global. See also set stream/2.
45
New code should use the alias(Alias) option for compatibility with the ISO standard.

SWI-Prolog 7.4 Reference Manual

4.17. INPUT AND OUTPUT 137

?- open(data, read, Fd, [alias(input)]).

...,
read(input, Term),
...

bom(Bool)
Check for a BOM (Byte Order Marker) or write one. If omitted, the default is true
for mode read and false for mode write. See also stream property/2 and
especially section 2.18.1 for a discussion of this feature.
buffer(Buffering)
Defines output buffering. The atom full (default) defines full buffering, line buffering
by line, and false implies the stream is fully unbuffered. Smaller buffering is useful
if another process or the user is waiting for the output as it is being produced. See also
flush output/[0,1]. This option is not an ISO option.
close on abort(Bool)
If true (default), the stream is closed on an abort (see abort/0). If false, the stream
is not closed. If it is an output stream, however, it will be flushed. Useful for logfiles and
if the stream is associated to a process (using the pipe/1 construct).
create(+List)
Specifies how a new file is created when opening in write, append or update mode.
Currently, List is a list of atoms that describe the permissions of the created file.46 Defined
values are below. Not recognised values are silently ignored, allowing for adding platform
specific extensions to this set.
read
Allow read access to the file.
write
Allow write access to the file.
execute
Allow execution access to the file.
default
Allow read and write access to the file.
all
Allow any access provided by the OS.
Note that if List is empty, the created file has no associated access permissions. The create
options map to the POSIX mode option of open(), where read map to 0444, write to
0222 and execute to 0111. On POSIX systems, the final permission is defined as (mode
& umask).
encoding(Encoding)
Define the encoding used for reading and writing text to this stream. The default encoding
for type text is derived from the Prolog flag encoding. For binary streams the
default encoding is octet. For details on encoding issues, see section 2.18.1.
46
Added after feedback from Joachim Shimpf and Per Mildner.

SWI-Prolog 7.4 Reference Manual

138 CHAPTER 4. BUILT-IN PREDICATES

eof action(Action)
Defines what happens if the end of the input stream is reached. Action eof code makes
get0/1 and friends return -1, and read/1 and friends return the atom end of file.
Repetitive reading keeps yielding the same result. Action error is like eof code, but
repetitive reading will raise an error. With action reset, Prolog will examine the file
again and return more data if the file has grown.
locale(+Locale)
Set the locale that is used by notably format/2 for output on this stream. See sec-
tion 4.23.
lock(LockingMode)
Try to obtain a lock on the open file. Default is none, which does not lock the file. The
value read or shared means other processes may read the file, but not write it. The
value write or exclusive means no other process may read or write the file.
Locks are acquired through the POSIX function fcntl() using the command F SETLKW,
which makes a blocked call wait for the lock to be released. Please note that fcntl() locks
are advisory and therefore only other applications using the same advisory locks honour
your lock. As there are many issues around locking in Unix, especially related to NFS
(network file system), please study the fcntl() manual page before trusting your locks!
The lock option is a SWI-Prolog extension.
type(Type)
Using type text (default), Prolog will write a text file in an operating system compatible
way. Using type binary the bytes will be read or written without any translation. See
also the option encoding.
wait(Bool)
This option can be combined with the lock option. If false (default true), the open
call returns immediately with an exception if the file is locked. The exception has the
format permission error(lock, source sink, SrcDest).

The option reposition is not supported in SWI-Prolog. All streams connected to a file may
be repositioned.

open(+SrcDest, +Mode, Stream) [ISO]

Equivalent to open/4 with an empty option list.

open null stream(Stream)

Open an output stream that produces no output. All counting functions are enabled on such
a stream. It can be used to discard output (like Unix /dev/null) or exploit the counting
properties. The initial encoding of Stream is utf8, enabling arbitrary Unicode output. The
encoding can be changed to determine byte counts of the output in a particular encoding or
validate if output is possible in a particular encoding. For example, the code below determines
the number of characters emitted when writing Term.

write_length(Term, Len) :-
open_null_stream(Out),
write(Out, Term),
character_count(Out, Len0),

SWI-Prolog 7.4 Reference Manual

4.17. INPUT AND OUTPUT 139

close(Out),
Len = Len0.

close(+Stream) [ISO]
Close the specified stream. If Stream is not open, an existence error is raised. See
stream pair/3 for the implications of closing a stream pair.
If the closed stream is the current input, output or error stream, the stream alias is bound to the
initial standard I/O streams of the process. Calling close/1 on the initial standard I/O streams
of the process is a no-op for an input stream and flushes an output stream without closing it.47
close(+Stream, +Options) [ISO]
Provides close(Stream, [force(true)]) as the only option. Called this way, any resource errors
(such as write errors while flushing the output buffer) are ignored.
stream property(?Stream, ?StreamProperty) [ISO]
True when StreamProperty is a property of Stream. If enumeration of streams or properties
is demanded because either Stream or StreamProperty are unbound, the implementation
enumerates all candidate streams and properties while locking the stream database. Properties
are fetched without locking the stream and may be outdated before this predicate returns due to
asynchronous activity.

alias(Atom)
If Atom is bound, test if the stream has the specified alias. Otherwise unify Atom with the
first alias of the stream.48
buffer(Buffering)
SWI-Prolog extension to query the buffering mode of this stream. Buffering is one of
full, line or false. See also open/4.
buffer size(Integer)
SWI-Prolog extension to query the size of the I/O buffer associated to a stream in bytes.
Fails if the stream is not buffered.
bom(Bool)
If present and true, a BOM (Byte Order Mark) was detected while opening the file for
reading, or a BOM was written while opening the stream. See section 2.18.1 for details.
close on abort(Bool)
Determine whether or not abort/0 closes the stream. By default streams are closed.
close on exec(Bool)
Determine whether or not the stream is closed when executing a new process (exec() in
Unix, CreateProcess() in Windows). Default is to close streams. This maps to fcntl()
F SETFD using the flag FD CLOEXEC on Unix and (negated) HANDLE FLAG INHERIT
on Windows.
encoding(Encoding)
Query the encoding used for text. See section 2.18.1 for an overview of wide character
and encoding issues in SWI-Prolog.
47
This behaviour was defined with purely interactive usage of Prolog in mind. Applications should not count on this
behaviour. Future versions may allow for closing the initial standard I/O streams.
48
BUG: Backtracking does not give other aliases.

SWI-Prolog 7.4 Reference Manual

140 CHAPTER 4. BUILT-IN PREDICATES

end of stream(E)
If Stream is an input stream, unify E with one of the atoms not, at or past. See also
at end of stream/[0,1].
eof action(A)
Unify A with one of eof code, reset or error. See open/4 for details.
file name(Atom)
If Stream is associated to a file, unify Atom to the name of this file.
file no(Integer)
If the stream is associated with a POSIX file descriptor, unify Integer with the descriptor
number. SWI-Prolog extension used primarily for integration with foreign code. See also
Sfileno() from SWI-Stream.h.
input
True if Stream has mode read.
locale(Locale)
True when Locale is the current locale associated with the stream. See section 4.23.
mode(IOMode)
Unify IOMode to the mode given to open/4 for opening the stream. Values are: read,
write, append and the SWI-Prolog extension update.
newline(NewlineMode)
One of posix or dos. If dos, text streams will emit \r\n for \n and discard \r from
input streams. Default depends on the operating system.
nlink(-Count)
Number of hard links to the file. This expresses the number of names the file has. Not
supported on all operating systems and the value might be bogus. See the documentation
of fstat() for your OS and the value st nlink.
output
True if Stream has mode write, append or update.
position(Pos)
Unify Pos with the current stream position. A stream position is an opaque
term whose fields can be extracted using stream position data/3. See also
set stream position/2.
reposition(Bool)
Unify Bool with true if the position of the stream can be set (see seek/4). It is assumed
the position can be set if the stream has a seek-function and is not based on a POSIX file
descriptor that is not associated to a regular file.
representation errors(Mode)
Determines behaviour of character output if the stream cannot represent a character. For
example, an ISO Latin-1 stream cannot represent Cyrillic characters. The behaviour is
one of error (throw an I/O error exception), prolog (write \...\ escape code) or
xml (write &#...; XML character entity). The initial mode is prolog for the user
streams and error for all other streams. See also section 2.18.1 and set stream/2.
timeout(-Time)
Time is the timeout currently associated with the stream. See set stream/2 with the
same option. If no timeout is specified, Time is unified to the atom infinite.

SWI-Prolog 7.4 Reference Manual

4.17. INPUT AND OUTPUT 141

type(Type)
Unify Type with text or binary.
tty(Bool)
This property is reported with Bool equal to true if the stream is associated with a
terminal. See also set stream/2.

current stream(?Object, ?Mode, ?Stream)

The predicate current stream/3 is used to access the status of a stream as well as to
generate all open streams. Object is the name of the file opened if the stream refers to an open
file, an integer file descriptor if the stream encapsulates an operating system stream, or the
atom [] if the stream refers to some other object. Mode is one of read or write.

is stream(+Term)
True if Term is a stream name or valid stream handle. This predicate realises a safe test for the
existence of a stream alias or handle.

stream pair(?StreamPair, ?Read, ?Write)

This predicate can be used in mode (-,+,+) to create a stream-pair from an input stream and an
output stream. Mode (+,-,-) can be used to get access to the underlying streams. If a stream has
already been closed, the corresponding argument is left unbound. If mode (+,-,-) is used on a
single stream, either Read or Write is unified with the stream while the other argument is left
unbound. This behaviour simplifies writing code that must operate both on streams and stream
pairs.
Stream-pairs can be used by all I/O operations on streams, where the operation selects the
appropriate member of the pair. The predicate close/1 closes the still open streams of the
pair.49 The output stream is closed before the input stream. If closing the output stream results
in an error, the input stream is still closed. Success is only returned if both streams were closed
successfully.

set stream position(+Stream, +Pos) [ISO]

Set the current position of Stream to Pos. Pos is a term as returned by stream property/2
using the position(Pos) property. See also seek/4.

stream position data(?Field, +Pos, -Data)

Extracts information from the opaque stream position term as returned by
stream property/2 requesting the position(Pos) property. Field is one
of line count, line position, char count or byte count. See also
line count/2, line position/2, character count/2 and byte count/2.50

seek(+Stream, +Offset, +Method, -NewLocation)

Reposition the current point of the given Stream. Method is one of bof, current or eof,
indicating positioning relative to the start, current point or end of the underlying object.
NewLocation is unified with the new offset, relative to the start of the stream.
Positions are counted in units. A unit is 1 byte, except for text files using 2-byte Uni-
code encoding (2 bytes) or wchar encoding (sizeof(wchar t)). The latter guarantees com-
fortable interaction with wide-character text objects. Otherwise, the use of seek/4 on
49
As of version 7.1.19, it is allowed to close one of the members of the stream directly and close the pair later.
50
Introduced in version 5.6.4 after extending the position term with a byte count. Compatible with SICStus Prolog.

SWI-Prolog 7.4 Reference Manual

142 CHAPTER 4. BUILT-IN PREDICATES

non-binary files (see open/4) is of limited use, especially when using multi-byte text
encodings (e.g. UTF-8) or multi-byte newline files (e.g. DOS/Windows). On text files,
SWI-Prolog offers reliable backup to an old position using stream property/2 and
set stream position/2. Skipping N character codes is achieved calling get code/2
N times or using copy stream data/3, directing the output to a null stream (see
open null stream/1). If the seek modifies the current location, the line number and char-
acter position in the line are set to 0.
If the stream cannot be repositioned, a permission error is raised. If applying the offset
would result in a file position less than zero, a domain error is raised. Behaviour when
seeking to positions beyond the size of the underlying object depend on the object and possi-
bly the operating system. The predicate seek/4 is compatible with Quintus Prolog, though
the error conditions and signalling is ISO compliant. See also stream property/2 and
set stream position/2.

set stream(+Stream, +Attribute)

Modify an attribute of an existing stream. Attribute specifies the stream property to set. If
stream is a pair (see stream pair/3) both streams are modified, unless the property is only
meaningful on one of the streams or setting both is not meaningful. In particular, eof action
only applies to the read stream, representation errors only applies to the write stream
and trying to set alias or line position on a pair results in a permission error
exception. See also stream property/2 and open/4.

alias(AliasName)
Set the alias of an already created stream. If AliasName is the name of one of the standard
streams, this stream is rebound. Thus, set stream(S, current input) is the
same as set input/1, and by setting the alias of a stream to user input, etc., all
user terminal input is read from this stream. See also interactor/0.
buffer(Buffering)
Set the buffering mode of an already created stream. Buffering is one of full, line or
false.
buffer size(+Size)
Set the size of the I/O buffer of the underlying stream to Size bytes.
close on abort(Bool)
Determine whether or not the stream is closed by abort/0. By default, streams are
closed.
close on exec(Bool)
Set the close on exec property. See stream property/2.
encoding(Atom)
Defines the mapping between bytes and character codes used for the stream. See sec-
tion 2.18.1 for supported encodings. The value bom causes the stream to check whether
the current character is a Unicode BOM marker. If a BOM marker is found, the encoding
is set accordingly and the call succeeds. Otherwise the call fails.
eof action(Action)
Set end-of-file handling to one of eof code, reset or error.

SWI-Prolog 7.4 Reference Manual

4.17. INPUT AND OUTPUT 143

file name(FileName)
Set the filename associated to this stream. This call can be used to set the file for error
locations if Stream corresponds to FileName and is not obtained by opening the file
directly but, for example, through a network service.
line position(LinePos)
Set the line position attribute of the stream. This feature is intended to correct position
management of the stream after sending a terminal escape sequence (e.g., setting ANSI
character attributes). Setting this attribute raises a permission error if the stream does
not record positions. See line position/2 and stream property/2 (property
position).
locale(+Locale)
Change the locale of the stream. See section 4.23.
newline(NewlineMode)
Set input or output translation for newlines. See corresponding stream property/2
for details. In addition to the detected modes, an input stream can be set in mode
detect. It will be set to dos if a \r character was removed.
timeout(Seconds)
This option can be used to make streams generate an exception if it takes longer than
Seconds before any new data arrives at the stream. The value infinite (default) makes the
stream block indefinitely. Like wait for input/3, this call only applies to streams
that support the select() system call. For further information about timeout handling, see
wait for input/3. The exception is of the form
error(timeout error(read, Stream), )
type(Type)
Set the type of the stream to one of text or binary. See also open/4 and the
encoding property of streams. Switching to binary sets the encoding to octet.
Switching to text sets the encoding to the default text encoding.
record position(Bool)
Do/do not record the line count and line position (see line count/2 and
line position/2).
representation errors(Mode)
Change the behaviour when writing characters to the stream that cannot be represented
by the encoding. See also stream property/2 and section 2.18.1.
tty(Bool)
Modify whether Prolog thinks there is a terminal (i.e. human interaction) connected
to this stream. On Unix systems the initial value comes from isatty(). On Win-
dows, the initial user streams are supposed to be associated to a terminal. See also
stream property/2.

set prolog IO(+In, +Out, +Error)

Prepare the given streams for interactive behaviour normally associated to the terminal. In
becomes the user input and current input of the calling thread. Out becomes
user output and current output. If Error equals Out an unbuffered stream is
associated to the same destination and linked to user error. Otherwise Error is used

SWI-Prolog 7.4 Reference Manual

144 CHAPTER 4. BUILT-IN PREDICATES

for user error. Output buffering for Out is set to line and buffering on Error is
disabled. See also prolog/0 and set stream/2. The clib package provides the library
prolog server, creating a TCP/IP server for creating an interactive session to Prolog.

4.17.3 Edinburgh-style I/O

The package for implicit input and output destinations is (almost) compatible with Edinburgh DEC-10
and C-Prolog. The reading and writing predicates refer to, resp., the current input and output streams.
Initially these streams are connected to the terminal. The current output stream is changed using
tell/1 or append/1. The current input stream is changed using see/1. The streams current
value can be obtained using telling/1 for output and seeing/1 for input.
Source and destination are either a file, user, or a term pipe(Command). The reserved
stream name user refers to the terminal.51 In the predicate descriptions below we will call the
source/destination argument SrcDest. Below are some examples of source/destination specifica-
tions.

?- see(data). % Start reading from file data.

?- tell(user). % Start writing to the terminal.
?- tell(pipe(lpr)). % Start writing to the printer.

Another example of using the pipe/1 construct is shown below.52 Note that the pipe/1 con-
struct is not part of Prologs standard I/O repertoire.

getwd(Wd) :-
seeing(Old), see(pipe(pwd)),
collect_wd(String),
seen, see(Old),
atom_codes(Wd, String).

collect_wd([C|R]) :-
get0(C), C \== -1, !,
collect_wd(R).
collect_wd([]).

The effect of tell/1 is not undone on backtracking, and since the stream handle is not specified
explicitly in further I/O operations when using Edinburgh-style I/O, you may write to unintended
streams more easily than when using ISO compliant I/O. For example, the following query writes
both a and b into the file out :

?- (tell(out), write(a), false ; write(b)), told.

51
The ISO I/O layer uses user input, user output and user error.
52
As of version 5.3.15, the pipe construct is supported in the MS-Windows version, both for swipl.exe and
swipl-win.exe. The implementation uses code from the LUA programming language (http://www.lua.org).

SWI-Prolog 7.4 Reference Manual

4.17. INPUT AND OUTPUT 145

Compatibility notes
Unlike Edinburgh Prolog systems, telling/1 and seeing/1 do not return the filename of the
current input/output but rather the stream identifier, to ensure the design pattern below works under
all circumstances:53
...,
telling(Old), tell(x),
...,
told, tell(Old),
...,

The predicates tell/1 and see/1 first check for user, the pipe(command) and a stream handle.
Otherwise, if the argument is an atom it is first compared to open streams associated to a file with
exactly the same name. If such a stream exists, created using tell/1 or see/1, output (input) is
switched to the open stream. Otherwise a file with the specified name is opened.
The behaviour is compatible with Edinburgh Prolog. This is not without problems. Changing
directory, non-file streams, and multiple names referring to the same file easily lead to unexpected
behaviour. New code, especially when managing multiple I/O channels, should consider using the
ISO I/O predicates defined in section 4.17.2.
see(+SrcDest)
Open SrcDest for reading and make it the current input (see set input/1). If SrcDest is a
stream handle, just make this stream the current input. See the introduction of section 4.17.3
for details.
tell(+SrcDest)
Open SrcDest for writing and make it the current output (see set output/1). If SrcDest is a
stream handle, just make this stream the current output. See the introduction of section 4.17.3
for details.
append(+File)
Similar to tell/1, but positions the file pointer at the end of File rather than truncating an
existing file. The pipe construct is not accepted by this predicate.
seeing(?SrcDest)
Same as current input/1, except that user is returned if the current input is the stream
user input to improve compatibility with traditional Edinburgh I/O. See the introduction of
section 4.17.3 for details.
telling(?SrcDest)
Same as current output/1, except that user is returned if the current output is the stream
user output to improve compatibility with traditional Edinburgh I/O. See the introduction
of section 4.17.3 for details.
seen
Close the current input stream. The new input stream becomes user input.
told
Close the current output stream. The new output stream becomes user output.
53
Filenames can be ambiguous and SWI-Prolog streams can refer to much more than just files.

SWI-Prolog 7.4 Reference Manual

146 CHAPTER 4. BUILT-IN PREDICATES

4.17.4 Switching between Edinburgh and ISO I/O

The predicates below can be used for switching between the implicit and the explicit stream-based
I/O predicates.

set input(+Stream) [ISO]

Set the current input stream to become Stream. Thus,
open(file, read, Stream), set input(Stream) is equivalent to see(file).
set output(+Stream) [ISO]
Set the current output stream to become Stream. See also with output to/2.
current input(-Stream) [ISO]
Get the current input stream. Useful for getting access to the status predicates associated with
streams.
current output(-Stream) [ISO]
Get the current output stream.

4.17.5 Write onto atoms, code-lists, etc.

with output to(+Output, :Goal)
Run Goal as once/1, while characters written to the current output are sent to Output. The
predicate is SWI-Prolog-specific, inspired by various posts to the mailinglist. It provides a
flexible replacement for predicates such as sformat/3, swritef/3, term to atom/2,
atom number/2 converting numbers to atoms, etc. The predicate format/3 accepts the
same terms as output argument.
Applications should generally avoid creating atoms by breaking and concatenating other atoms,
as the creation of large numbers of intermediate atoms generally leads to poor performance,
even more so in multithreaded applications. This predicate supports creating difference lists
from character data efficiently. The example below defines the DCG rule term//1 to insert a
term in the output:

term(Term, In, Tail) :-

with_output_to(codes(In, Tail), write(Term)).

?- phrase(term(hello), X).

X = [104, 101, 108, 108, 111]

A Stream handle or alias

Temporarily switch current output to the given stream. Redirection using
with output to/2 guarantees the original output is restored, also if Goal fails
or raises an exception. See also call cleanup/2.
atom(-Atom)
Create an atom from the emitted characters. Please note the remark above.
string(-String)
Create a string object as defined in section 5.2.

SWI-Prolog 7.4 Reference Manual

4.17. INPUT AND OUTPUT 147

codes(-Codes)
Create a list of character codes from the emitted characters, similar to atom codes/2.
codes(-Codes, -Tail)
Create a list of character codes as a difference list.
chars(-Chars)
Create a list of one-character atoms from the emitted characters, similar to
atom chars/2.
chars(-Chars, -Tail)
Create a list of one-character atoms as a difference list.

4.17.6 Fast binary term I/O

The predicates in this section provide fast binary I/O of arbitrary Prolog terms, including cyclic terms
and terms holding attributed variables. Library fastrw is a SICSTus/Ciao compatible library that
extends the core primitives described below.
The binary representation the same as used by PL record external(). The use of these
primitives instead of using write canonical/2 has advantages and disadvantages. Below are the
main considerations:

Using write canonical/2 allows or exchange of terms with other Prolog systems. The
format is stable and, as it is text based, it can be inspected and corrected.

Using the binary format improves the performance roughly 3 times.

The size of both representations is comparable.

The binary format can deal with cycles, sharing and attributes. Special precautions are
needed to transfer such terms using write canonical/2. See term factorized/3
and copy term/3.

In the current version, reading the binary format has only incomplete consistency checks. This
implies a user must be able to trust the source as crafted messages may compromise the reading
Prolog system.

fast term serialized(?Term, ?String)

(De-)serialize Term to/from String.

fast write(+Output, +Term)

Write Term using the fast serialization format to the Output stream. Output must be a binary
stream.

fast read(+Input, -Term)

Read Term using the fast serialization format from the Input stream. Input must be a binary
stream.54
54
BUG: The predicate fast read/2 may crash on arbitrary input.

SWI-Prolog 7.4 Reference Manual

148 CHAPTER 4. BUILT-IN PREDICATES

4.18 Status of streams

wait for input(+ListOfStreams, -ReadyList, +TimeOut) [det]
Wait for input on one of the streams in ListOfStreams and return a list of streams on which input
is available in ReadyList. wait for input/3 waits for at most TimeOut seconds. TimeOut
may be specified as a floating point number to specify fractions of a second. If TimeOut equals
infinite, wait for input/3 waits indefinitely. If Timeout is 0 or 0.0 this predicate
returns without waiting.55
This predicate can be used to implement timeout while reading and to handle input from multi-
ple sources and is typically used to wait for multiple (network) sockets. On Unix systems it may
be used on any stream that is associated with a system file descriptor. On Windows it can only
be used on sockets. If ListOfStreams contains a stream that is not associated with a supported
device, a domain error(waitable stream, Stream) is raised.
The example below waits for input from the user and an explicitly opened secondary terminal
stream. On return, Inputs may hold user input or P4 or both.

?- open(/dev/ttyp4, read, P4),

wait_for_input([user_input, P4], Inputs, 0).

When available, the implementation is based on the poll() system call. The poll() puts no ad-
ditional restriction on the number of open files the process may have. It does limit the time
to 231 1 milliseconds (a bit less than 25 days). Specifying a too large timeout raises a
representation error(timeout) exception. If poll() is not supported by the OS, select()
is used. The select() call can only handle file descriptors up to FD SETSIZE. If the set contains
a descriptor that exceeds this limit a representation error(FD SETSIZE) is raised.
Note that wait for input/3 returns streams that have data waiting. This does not mean
you can, for example, call read/2 on the stream without blocking as the stream might hold an
incomplete term. The predicate set stream/2 using the option timeout(Seconds) can be
used to make the stream generate an exception if no new data arrives within the timeout period.
Suppose two processes communicate by exchanging Prolog terms. The following code makes
the server immune for clients that write an incomplete term:

...,
tcp_accept(Server, Socket, _Peer),
tcp_open(Socket, In, Out),
set_stream(In, timeout(10)),
catch(read(In, Term), _, (close(Out), close(In), fail)),
...,

byte count(+Stream, -Count)

Byte position in Stream. For binary streams this is the same as character count/2.
For text files the number may be different due to multi-byte encodings or additional record
separators (such as Control-M in Windows).
55
Prior to 7.3.23, the integer value 0 was the same as infinite.

SWI-Prolog 7.4 Reference Manual

4.19. PRIMITIVE CHARACTER I/O 149

character count(+Stream, -Count)

Unify Count with the current character index. For input streams this is the number of characters
read since the open; for output streams this is the number of characters written. Counting starts
at 0.

line count(+Stream, -Count)

Unify Count with the number of lines read or written. Counting starts at 1.

line position(+Stream, -Count)

Unify Count with the position on the current line. Note that this assumes the position is 0 after
the open. Tabs are assumed to be defined on each 8-th character, and backspaces are assumed
to reduce the count by one, provided it is positive.

4.19 Primitive character I/O

See section 4.2 for an overview of supported character representations.

nl [ISO]
Write a newline character to the current output stream. On Unix systems nl/0 is equivalent to
put(10).

nl(+Stream) [ISO]
Write a newline to Stream.

put(+Char)
Write Char to the current output stream. Char is either an integer expression evaluating to a
character code or an atom of one character. Deprecated. New code should use put char/1
or put code/1.

put(+Stream, +Char)
Write Char to Stream. See put/1 for details.

put byte(+Byte) [ISO]

Write a single byte to the output. Byte must be an integer between 0 and 255.

put byte(+Stream, +Byte) [ISO]

Write a single byte to Stream. Byte must be an integer between 0 and 255.

put char(+Char) [ISO]

Write a character to the current output, obeying the encoding defined for the current output
stream. Note that this may raise an exception if the encoding of the output stream cannot
represent Char.

put char(+Stream, +Char) [ISO]

Write a character to Stream, obeying the encoding defined for Stream. Note that this may raise
an exception if the encoding of Stream cannot represent Char.

put code(+Code) [ISO]

Similar to put char/1, but using a character code. Code is a non-negative integer. Note that
this may raise an exception if the encoding of the output stream cannot represent Code.

SWI-Prolog 7.4 Reference Manual

150 CHAPTER 4. BUILT-IN PREDICATES

put code(+Stream, +Code) [ISO]

Same as put code/1 but directing Code to Stream.

tab(+Amount)
Write Amount spaces on the current output stream. Amount should be an expression that evalu-
ates to a positive integer (see section 4.27).

tab(+Stream, +Amount)
Write Amount spaces to Stream.

flush output [ISO]

Flush pending output on current output stream. flush output/0 is automatically generated
by read/1 and derivatives if the current input stream is user and the cursor is not at the left
margin.

flush output(+Stream) [ISO]

Flush output on the specified stream. The stream must be open for writing.

ttyflush
Flush pending output on stream user. See also flush output/[0,1].

get byte(-Byte) [ISO]

Read the current input stream and unify the next byte with Byte (an integer between 0 and 255).
Byte is unified with -1 on end of file.

get byte(+Stream, -Byte) [ISO]

Read the next byte from Stream and unify Byte with an integer between 0 and 255.

get code(-Code) [ISO]

Read the current input stream and unify Code with the character code of the next character.
Code is unified with -1 on end of file. See also get char/1.

get code(+Stream, -Code) [ISO]

Read the next character code from Stream.

get char(-Char) [ISO]

Read the current input stream and unify Char with the next character as a one-character atom.
See also atom chars/2. On end-of-file, Char is unified to the atom end of file.

get char(+Stream, -Char) [ISO]

Unify Char with the next character from Stream as a one-character atom. See also
get char/2, get byte/2 and get code/2.

get0(-Char) [deprecated]
Edinburgh version of the ISO get code/1 predicate. Note that Edinburgh Prolog didnt
support wide characters and therefore technically speaking get0/1 should have been mapped
to get byte/1. The intention of get0/1, however, is to read character codes.

get0(+Stream, -Char) [deprecated]

Edinburgh version of the ISO get code/2 predicate. See also get0/1.

SWI-Prolog 7.4 Reference Manual

4.19. PRIMITIVE CHARACTER I/O 151

get(-Char) [deprecated]
Read the current input stream and unify the next non-blank character with Char. Char is
unified with -1 on end of file. The predicate get/1 operates on character codes. See also
get0/1.

get(+Stream, -Char) [deprecated]

Read the next non-blank character from Stream. See also get/1, get0/1 and get0/2.

peek byte(-Byte) [ISO]

peek byte(+Stream, -Byte) [ISO]
peek code(-Code) [ISO]
peek code(+Stream, -Code) [ISO]
peek char(-Char) [ISO]
peek char(+Stream, -Char) [ISO]
Read the next byte/code/char from the input without removing it. These predicates do not
modify the streams position or end-of-file status. These predicates require a buffered stream
(see set stream/2) and raise a permission error if the stream is unbuffered or the buffer is
too small to hold the longest multi-byte sequence that might need to be buffered.

peek string(+Stream, +Len, -String)

Read the next Len characters (if the stream is a text stream) or bytes (if the stream is binary)
from Stream without removing the data. If Len is larger that the stream buffer size, the buffer
size is increased to Len. String can be shorter than Len if the stream contains less data. This
predicate is intended to guess the content type of data read from non-repositionable streams.

skip(+Code)
Read the input until Code or the end of the file is encountered. A subsequent call to
get code/1 will read the first character after Code.

skip(+Stream, +Code)
Skip input (as skip/1) on Stream.

get single char(-Code)

Get a single character from input stream user (regardless of the current input stream). Unlike
get code/1, this predicate does not wait for a return. The character is not echoed to the
users terminal. This predicate is meant for keyboard menu selection, etc. If SWI-Prolog was
started with the -tty option this predicate reads an entire line of input and returns the first
non-blank character on this line, or the character code of the newline (10) if the entire line
consisted of blank characters.

at end of stream [ISO]

Succeeds after the last character of the current input stream has been read. Also succeeds if
there is no valid current input stream.

at end of stream(+Stream) [ISO]

Succeeds after the last character of the named stream is read, or Stream is not a valid input
stream. The end-of-stream test is only available on buffered input streams (unbuffered input
streams are rarely used; see open/4).

SWI-Prolog 7.4 Reference Manual

152 CHAPTER 4. BUILT-IN PREDICATES

set end of stream(+Stream)

Set the size of the file opened as Stream to the current file position. This is typically used in
combination with the open-mode update.

copy stream data(+StreamIn, +StreamOut, +Len)

Copy Len codes from StreamIn to StreamOut. Note that the copy is done using the semantics
of get code/2 and put code/2, taking care of possibly recoding that needs to take place
between two text files. See section 2.18.1.

copy stream data(+StreamIn, +StreamOut)

Copy all (remaining) data from StreamIn to StreamOut.

fill buffer(+Stream) [det]

Fill the Streams input buffer. Subsequent calls try to read more input until the buffer is com-
pletely filled. This predicate is used together with read pending codes/3 to process input
with minimal buffering.

read pending codes(+StreamIn, -Codes, ?Tail)

Read input pending in the input buffer of StreamIn and return it in the difference list Codes-Tail.
That is, the available characters codes are used to create the list Codes ending in the tail Tail.
On encountering end-of-file, both Codes and Tail are unified with the empty list ([]).
This predicate is intended for efficient unbuffered copying and filtering of input coming from
network connections or devices. It also enables the library pure input, which processes
input from files and streams using a DCG.
The following code fragment realises efficient non-blocking copying of data from an input
to an output stream. The at end of stream/1 call checks for end-of-stream and fills the
input buffer. Note that the use of a get code/2 and put code/2 based loop requires a
flush output/1 call after each put code/2. The copy stream data/2 does not al-
low for inspection of the copied data and suffers from the same buffering issues.

copy(In, Out) :-
repeat,
fill_buffer(In),
read_pending_codes(In, Chars, Tail),
\+ \+ ( Tail = [],
format(Out, s, [Chars]),
flush_output(Out)
),
( Tail == []
-> !
; fail
).

read pending chars(+StreamIn, -Chars, ?Tail)

As read pending codes/3, but returns a difference list of one-character atoms.

SWI-Prolog 7.4 Reference Manual

4.20. TERM READING AND WRITING 153

4.20 Term reading and writing

This section describes the basic term reading and writing predicates. The predicates format/[1,2]
and writef/2 provide formatted output. Writing to Prolog data structures such as atoms or code-
lists is supported by with output to/2 and format/3.
Reading is sensitive to the Prolog flag character escapes, which controls the interpretation
of the \ character in quoted atoms and strings.

write term(+Term, +Options) [ISO]

The predicate write term/2 is the generic form of all Prolog term-write predicates. Valid
options are:

attributes(Atom)
Define how attributed variables (see section 7.1) are written. The default is determined by
the Prolog flag write attributes. Defined values are ignore (ignore the attribute),
dots (write the attributes as {...}), write (simply hand the attributes recursively to
write term/2) and portray (hand the attributes to attr portray hook/2).
back quotes(Atom)
Fulfills the same role as the back quotes prolog flag. Notably, the value string
causes string objects to be printed between back quotes and symbol char causes the
backquote to be printed unquoted. In all other cases the backquote is printed as a quoted
atom.
brace terms(Bool)
If true (default), write {}(X) as {X}. See also dotlists and ignore ops.
blobs(Atom)
Define how non-text blobs are handled. By default, this is left to the write handler spec-
ified with the blob type. Using portray, portray/1 is called for each blob
encountered. See section 11.4.7.
character escapes(Bool)
If true and quoted(true) is active, special characters in quoted atoms and strings are
emitted as ISO escape sequences. Default is taken from the reference module (see below).
cycles(Bool)
If true (default), cyclic terms are written as @(Template, Substitutions), where Substi-
tutions is a list Var = Value. If cycles is false, max depth is not given, and Term
is cyclic, write term/2 raises a domain error.56 See also the cycles option in
read term/2.
dotlists(Bool)
If true (default false), write lists using the dotted term notation rather than the list no-
tation.57 Note that as of version 7, the list constructor is [|]. Using dotlists(true),
write term/2 writes a list using . as constructor. This is intended for communication
with programs such as other Prolog systems, that rely on this notation.
56
The cycles option and the cyclic term representation using the @-term are copied from SICStus Prolog. However, the
default in SICStus is set to false and SICStus writes an infinite term if not protected by, e.g., the depth limit option.
57
Copied from ECLiPSe.

SWI-Prolog 7.4 Reference Manual

154 CHAPTER 4. BUILT-IN PREDICATES

fullstop(Bool)
If true (default false), add a fullstop token to the output. The dot is preceeded by a
space if needed and followed by a space (default) or newline if the nl(true) option is also
given.58
ignore ops(Bool)
If true, the generic term representation (hfunctori(hargsi . . . )) will be used for all terms.
Otherwise (default), operators will be used where appropriate.59 .
max depth(Integer)
If the term is nested deeper than Integer, print the remainder as ellipses (. . . ). A 0 (zero)
value (default) imposes no depth limit. This option also delimits the number of printed
items in a list. Example:
?- write_term(a(s(s(s(s(0)))), [a,b,c,d,e,f]),
[max_depth(3)]).
a(s(s(...)), [a, b|...])
true.

Used by the top level and debugger to limit screen output. See also the Prolog flags
answer write options and debugger write options.
module(Module)
Define the reference module (default user). This defines the default value for the
character escapes option as well as the operator definitions to use. See also op/3.
nl(Bool)
Add a newline to the output. See also the fullstop option.
numbervars(Bool)
If true, terms of the format $VAR(N), where N is a non-negative integer, will be written
as a variable name. If N is an atom it is written without quotes. This extension allows
for writing variables with user-provided names. The default is false. See also
numbervars/3 and the option variable names.
partial(Bool)
If true (default false), do not reset the logic that inserts extra spaces that separate
tokens where needed. This is intended to solve the problems with the code below. Calling
write value(.) writes .., which cannot be read. By adding partial(true) to the
option list, it correctly emits . .. Similar problems appear when emitting operators
using multiple calls to write term/3.
write_value(Value) :-
write_term(Value, [partial(true)]),
write(.), nl.

portray(Bool)
Same as portrayed(Bool). Deprecated.
58
Compatible with ECLiPSe
59
In traditional systems this flag also stops the syntactic sugar notation for lists and brace terms. In SWI-Prolog, these
are controlled by the separate options dotlists and brace terms

SWI-Prolog 7.4 Reference Manual

4.20. TERM READING AND WRITING 155

portray goal(:Goal)
Implies portray(true), but calls Goal rather than the predefined hook portray/1.
Goal is called through call/3, where the first argument is Goal, the second is the term
to be printed and the 3rd argument is the current write option list. The write option list is
copied from the write term call, but the list is guaranteed to hold an option priority
that reflects the current priority.
portrayed(Bool)
If true, the hook portray/1 is called before printing a term that is not a variable. If
portray/1 succeeds, the term is considered printed. See also print/1. The default
is false. This option is an extension to the ISO write term options.
priority(Integer)
An integer between 0 and 1200 representing the context priority. Default is 1200. Can
be used to write partial terms appearing as the argument to an operator. For example:
format(w = , [VarName]),
write_term(Value, [quoted(true), priority(699)])

quoted(Bool)
If true, atoms and functors that need quotes will be quoted. The default is false.
spacing(+Spacing)
Determines whether and where extra white space is added to enhance readability. The
default is standard, adding only space where needed for proper tokenization by
read term/3. Currently, the only other value is next argument, adding a space
after a comma used to separate arguments in a term or list.
variable names(+List)
Assign names to variables in Term. List is a list of terms Name = Var, where Name is
an atom that represents a valid Prolog variable name. Terms where Var is bound or is
a variable that does not appear in Term are ignored. Raises an error if List is not a list,
one of the members is not a term Name = Var, Name is not an atom or Name does not
represent a valid Prolog variable name.
The implementation binds the variables from List to a term $VAR(Name). Like
write canonical/1, terms that where already bound to $VAR(X) before
write term/2 are printed normally, unless the option numbervars(true) is also pro-
vided. If the option numbervars(true) is used, the user is responsible for avoiding col-
lisions between assigned names and numbered names. See also the variable names
option of read term/2.
Possible variable attributes (see section 7.1) are ignored. In most cases one should use
copy term/3 to obtain a copy that is free of attributed variables and handle the associ-
ated constraints as appropriate for the use-case.

write term(+Stream, +Term, +Options) [ISO]

As write term/2, but output is sent to Stream rather than the current output.

write length(+Term, -Length, +Options) [semidet]

True when Length is the number of characters emitted for write termTerm, Options. In addition
to valid options for write term/2, it processes the option:

SWI-Prolog 7.4 Reference Manual

156 CHAPTER 4. BUILT-IN PREDICATES

max length(+MaxLength)
If provided, fail if Length would be larger than MaxLength. The implementation ensures
that the runtime is limited when computing the length of a huge term with a bounded
maximum.

write canonical(+Term) [ISO]

Write Term on the current output stream using standard parenthesised prefix notation (i.e.,
ignoring operator declarations). Atoms that need quotes are quoted. Terms written with this
predicate can always be read back, regardless of current operator declarations. Equivalent
to write term/2 using the options ignore ops, quoted and numbervars after
numbervars/4 using the singletons option.
Note that due to the use of numbervars/4, non-ground terms must be written using a single
write canonical/1 call. This used to be the case anyhow, as garbage collection between
multiple calls to one of the write predicates can change the _GNNN identity of the variables.

write canonical(+Stream, +Term) [ISO]

Write Term in canonical form on Stream.

write(+Term) [ISO]
Write Term to the current output, using brackets and operators where appropriate.

write(+Stream, +Term) [ISO]

Write Term to Stream.

writeq(+Term) [ISO]
Write Term to the current output, using brackets and operators where appropriate. Atoms that
need quotes are quoted. Terms written with this predicate can be read back with read/1
provided the currently active operator declarations are identical.

writeq(+Stream, +Term) [ISO]

Write Term to Stream, inserting quotes.

writeln(+Term)
Equivalent to write(Term), nl.. The output stream is locked, which implies no output
from other threads can appear between the term and newline.

writeln(+Stream, +Term)
Equivalent to write(Stream, Term), nl(Stream).. The output stream is locked,
which implies no output from other threads can appear between the term and newline.

print(+Term)
Print a term for debugging purposes. The predicate print/1 acts as if defined as below.

print(Term) :-
current_prolog_flag(print_write_options, Options), !,
write_term(Term, Options).
print(Term) :-
write_term(Term, [ portray(true),
numbervars(true),

SWI-Prolog 7.4 Reference Manual

4.20. TERM READING AND WRITING 157

quoted(true)
]).

The print/1 predicate is used primarily through the p escape sequence of format/2,
which is commonly used in the recipies used by print message/2 to emit messages.
The classical definition of this predicate is equivalent to the ISO predicate write term/2
using the options portray(true) and numbervars(true). The portray(true) option al-
lows the user to implement application-specific printing of terms printed during debugging to
facilitate easy understanding of the output. See also portray/1 and portray text. SWI-
Prolog adds quoted(true) to (1) facilitate the copying/pasting of terms that are not affected by
portray/1 and to (2) allow numbers, atoms and strings to be more easily distinguished, e.g.,
42, 42 and "42".

print(+Stream, +Term)
Print Term to Stream.

portray(+Term)
A dynamic predicate, which can be defined by the user to change the behaviour of print/1
on (sub)terms. For each subterm encountered that is not a variable print/1 first calls
portray/1 using the term as argument. For lists, only the list as a whole is given to
portray/1. If portray/1 succeeds print/1 assumes the term has been written.

read(-Term) [ISO]
Read the next Prolog term from the current input stream and unify it with Term. On a syntax
error read/1 displays an error message, attempts to skip the erroneous term and fails. On
reaching end-of-file Term is unified with the atom end of file.

read(+Stream, -Term) [ISO]

Read Term from Stream.

read clause(+Stream, -Term, +Options)

Equivalent to read term/3, but sets options according to the current compilation context
and optionally processes comments. Defined options:

syntax errors(+Atom)
See read term/3, but the default is dec10 (report and restart).
term position(-TermPos)
Same as for read term/3.
subterm positions(-TermPos)
Same as for read term/3.
variable names(-Bindings)
Same as for read term/3.
process comment(+Boolean)
If true (default), call prolog:comment hook(Comments, TermPos, Term) if this
multifile hook is defined (see prolog:comment hook/3). This is used to drive PlDoc.

SWI-Prolog 7.4 Reference Manual

158 CHAPTER 4. BUILT-IN PREDICATES

comments(-Comments)
If provided, unify Comments with the comments encountered while reading Term. This
option implies process comment(false).

The singletons option of read term/3 is initialised from the active style-checking
mode. The module option is initialised to the current compilation module (see
prolog load context/2).

read term(-Term, +Options) [ISO]

Read a term from the current input stream and unify the term with Term. The reading is con-
trolled by options from the list of Options. If this list is empty, the behaviour is the same as
for read/1. The options are upward compatible with Quintus Prolog. The argument order
is according to the ISO standard. Syntax errors are always reported using exception-handling
(see catch/3). Options:

backquoted string(Bool)
If true, read . . . to a string object (see section 5.2). The default depends on the
Prolog flag back quotes.
character escapes(Bool)
Defines how to read \ escape sequences in quoted atoms. See the Prolog flag
character escapes in current prolog flag/2. (SWI-Prolog).
comments(-Comments)
Unify Comments with a list of Position-Comment, where Position is a stream position
object (see stream position data/3) indicating the start of a comment and
Comment is a string object containing the text including delimiters of a comment. It
returns all comments from where the read term/2 call started up to the end of the
term read.
cycles(Bool)
If true (default false), re-instantiate templates as produced by the corresponding
write term/2 option. Note that the default is false to avoid misinterpretation
of @(Template, Substutions), while the default of write term/2 is true because
emitting cyclic terms without using the template construct produces an infinitely large
term (read: it will generate an error after producing a huge amount of output).
dotlists(Bool)
If true (default false), read .(a,[]) as a list, even if lists are internally nor con-
structed using the dot as functor. This is primarily intended to read the output from
write canonical/1 from other Prolog systems. See section 5.1.
double quotes(Atom)
Defines how to read . . . strings. See the Prolog flag double quotes. (SWI-Prolog).
module(Module)
Specify Module for operators, character escapes flag and double quotes flag.
The value of the latter two is overruled if the corresponding read term/3 option is
provided. If no module is specified, the current source module is used. (SWI-Prolog).
quasi quotations(-List)
If present, unify List with the quasi quotations (see section A.27) instead of evaluating

SWI-Prolog 7.4 Reference Manual

4.20. TERM READING AND WRITING 159

quasi quotations. Each quasi quotation is a term quasi quotation(+Syntax, +Quo-

tation, +VarDict, -Result), where Syntax is the term in {|Syntax||..|}, Quotation is
a list of character codes that represent the quotation, VarDict is a list of Name=Variable
and Result is a variable that shares with the place where the quotation must be inserted.
This option is intended to support tools that manipulate Prolog source text.
singletons(Vars)
As variable names, but only reports the variables occurring only once in the Term
read. Variables starting with an underscore ( ) are not included in this list. (ISO). If Vars
is the constant warning, singleton variables are reported using print message/2.
The variables appear in the order they have been read.
syntax errors(Atom)
If error (default), throw an exception on a syntax error. Other values are fail, which
causes a message to be printed using print message/2, after which the predicate
fails, quiet which causes the predicate to fail silently, and dec10 which causes syntax
errors to be printed, after which read term/[2,3] continues reading the next term.
Using dec10, read term/[2,3] never fails. (Quintus, SICStus).
subterm positions(TermPos)
Describes the detailed layout of the term. The formats for the various types of terms are
given below. All positions are character positions. If the input is related to a normal
stream, these positions are relative to the start of the input; when reading from the
terminal, they are relative to the start of the term.
From-To
Used for primitive types (atoms, numbers, variables).
string position(From, To)
Used to indicate the position of a string enclosed in double quotes (").
brace term position(From, To, Arg)
Term of the form {...}, as used in DCG rules. Arg describes the argument.
list position(From, To, Elms, Tail)
A list. Elms describes the positions of the elements. If the list specifies the tail as
|TailTerm, Tail is unified with the term position of the tail, otherwise with the
atom none.
term position(From, To, FFrom, FTo, SubPos)
Used for a compound term not matching one of the above. FFrom and FTo describe
the position of the functor. SubPos is a list, each element of which describes the term
position of the corresponding subterm.
dict position(From, To, TagFrom, TagTo, KeyValuePosList)
Used for a dict (see section 5.4). The position of the key-value pairs is described
by KeyValuePosList, which is a list of key value position/7 terms. The
key value position/7 terms appear in the order of the input. Because maps to
not preserve ordering, the key is provided in the position description.
key value position(From, To, SepFrom, SepTo, Key, KeyPos, ValuePos)
Used for key-value pairs in a map (see section 5.4). It is similar to the
term position/5 that would be created, except that the key and value po-
sitions do not need an intermediate list and the key is provided in Key to enable
synchronisation of the file position data with the data structure.

SWI-Prolog 7.4 Reference Manual

160 CHAPTER 4. BUILT-IN PREDICATES

parentheses term position(From, To, ContentPos)

Used for terms between parentheses. This is an extension compared to the original
Quintus specification that was considered necessary for secure refactoring of terms.
quasi quotation position(From, To, SyntaxFrom, SyntaxTo, ContentPos)
Used for quasi quotations.
term position(Pos)
Unifies Pos with the starting position of the term read. Pos is of the same format as used
by stream property/2.
var prefix(Bool)
If true, demand variables to start with an underscore. See section 2.15.1.
variables(Vars)
Unify Vars with a list of variables in the term. The variables appear in the order they have
been read. See also term variables/2. (ISO).
variable names(Vars)
Unify Vars with a list of Name = Var, where Name is an atom describing the variable
name and Var is a variable that shares with the corresponding variable in Term. (ISO).
The variables appear in the order they have been read.

read term(+Stream, -Term, +Options) [ISO]

Read term with options from Stream. See read term/2.

read term from atom(+Atom, -Term, +Options)

Use read term/3 to read the next term from Atom. Atom is either an atom or a string object
(see section 5.2). It is not required for Atom to end with a full-stop. This predicate supersedes
atom to term/3.

read history(+Show, +Help, +Special, +Prompt, -Term, -Bindings)

Similar to read term/2 using the option variable names, but allows for history sub-
stitutions. read history/6 is used by the top level to read the users actions. Show is
the command the user should type to show the saved events. Help is the command to get an
overview of the capabilities. Special is a list of commands that are not saved in the history.
Prompt is the first prompt given. Continuation prompts for more lines are determined by
prompt/2. A %w in the prompt is substituted by the event number. See section 2.7 for
available substitutions.
SWI-Prolog calls read history/6 as follows:

read_history(h, !h, [trace], %w ?- , Goal, Bindings)

prompt(-Old, +New)
Set prompt associated with read/1 and its derivatives. Old is first unified with the current
prompt. On success the prompt will be set to New if this is an atom. Otherwise an error
message is displayed. A prompt is printed if one of the read predicates is called and the cursor
is at the left margin. It is also printed whenever a newline is given and the term has not been
terminated. Prompts are only printed when the current input stream is user.

SWI-Prolog 7.4 Reference Manual

4.21. ANALYSING AND CONSTRUCTING TERMS 161

prompt1(+Prompt)
Sets the prompt for the next line to be read. Continuation lines will be read using the prompt
defined by prompt/2.

4.21 Analysing and Constructing Terms

functor(?Term, ?Name, ?Arity) [ISO]
True when Term is a term with functor Name/Arity. If Term is a variable it is unified with a new
term whose arguments are all different variables (such a term is called a skeleton). If Term is
atomic, Arity will be unified with the integer 0, and Name will be unified with Term. Raises
instantiation error if Term is unbound and Name/Arity is insufficiently instantiated.
SWI-Prolog also supports terms with arity 0, as in a() (see section 5. Such terms must be
processed using compound name arity/3. The predicate functor/3 and =../2 raise
a domain error when faced with these terms. Without this precaution, the inconsistency
demonstrated below could happen silently.60

?- functor(a(), N, A).
N = a, A = 0.
?- functor(T, a, 0).
T = a.

arg(?Arg, +Term, ?Value) [ISO]

Term should be instantiated to a term, Arg to an integer between 1 and the arity of Term.
Value is unified with the Arg-th argument of Term. Arg may also be unbound. In this case
Value will be unified with the successive arguments of the term. On successful unifica-
tion, Arg is unified with the argument number. Backtracking yields alternative solutions.61
The predicate arg/3 fails silently if Arg = 0 or Arg > arity and raises the exception
domain error(not less than zero, Arg) if Arg < 0.

?Term =.. ?List [ISO]

List is a list whose head is the functor of Term and the remaining arguments are the arguments
of the term. Either side of the predicate may be a variable, but not both. This predicate is called
Univ.

?- foo(hello, X) =.. List.

List = [foo, hello, X]

?- Term =.. [baz, foo(1)].

Term = baz(foo(1))

SWI-Prolog also supports terms with arity 0, as in a() (see section 5. Such terms must be
processed using compound name arguments/3. This predicate raises a domain error as
shown below. See also functor/3.
60
Raising a domain error was suggested by Jeff Schultz.
61
The instantiation pattern (-, +, ?) is an extension to standard Prolog. Some systems provide genarg/3 that covers
this pattern.

SWI-Prolog 7.4 Reference Manual

162 CHAPTER 4. BUILT-IN PREDICATES

?- a() =.. L.
ERROR: Domain error: compound_non_zero_arity expected, found a()

compound name arity(?Compound, ?Name, ?Arity)

Rationalized version of functor/3 that only works for compound terms and can
examine and create compound terms with zero arguments (e.g, name(). See also
compound name arguments/3.

compound name arguments(?Compound, ?Name, ?Arguments)

Rationalized version of =../2 that can compose and decompose compound terms with zero
arguments. See also compound name arity/3.

numbervars(+Term, +Start, -End)

Unify the free variables in Term with a term $VAR(N), where N is the number of the variable.
Counting starts at Start. End is unified with the number that should be given to the next
variable.62 The example below illustrates this. Note that the toplevel prints $VAR(0) as A
due to the numbervars(true) option used to print answers.

?- Term = f(X,Y,X),
numbervars(Term, 0, End),
write_canonical(Term), nl.
f($VAR(0),$VAR(1),$VAR(0))
Term = f(A, B, A),
X = A,
Y = B,
End = 2.

See also the numbervars option to write term/3 and numbervars/4.

numbervars(+Term, +Start, -End, +Options)

As numbervars/3, providing the following options:

functor name(+Atom)
Name of the functor to use instead of $VAR.
attvar(+Action)
What to do if an attributed variable is encountered. Options are skip, which causes
numbervars/3 to ignore the attributed variable, bind which causes it to thread it as
a normal variable and assign the next $VAR(N) term to it, or (default) error which
raises a type error exception.63
62
BUG: Only tagged integers are supported (see the Prolog flag max tagged integer). This suffices to count all
variables that can appear in the largest term that can be represented, but does not support arbitrary large integer values for
Start. On overflow, a representation error(tagged integer) exception is raised.
63
This behaviour was decided after a long discussion between David Reitter, Richard OKeefe, Bart Demoen and Tom
Schrijvers.

SWI-Prolog 7.4 Reference Manual

4.21. ANALYSING AND CONSTRUCTING TERMS 163

singletons(+Bool)
If true (default false), numbervars/4 does singleton detection. Singleton variables
are unified with $VAR(_), causing them to be printed as _ by write term/2
using the numbervars option. This option is exploited by portray clause/2 and
write canonical/2.64

var number(@Term, -VarNumber)

True if Term is numbered by numbervars/3 and VarNumber is the number given to this
variable. This predicate avoids the need for unification with $VAR(X) and opens the path
for replacing this valid Prolog term by an internal representation that has no textual equivalent.

term variables(+Term, -List) [ISO]

Unify List with a list of variables, each sharing with a unique variable of Term.65 The variables
in List are ordered in order of appearance traversing Term depth-first and left-to-right. See also
term variables/3. For example:

?- term_variables(a(X, b(Y, X), Z), L).

L = [X, Y, Z].

term variables(+Term, -List, ?Tail)

Difference list version of term variables/2. That is, Tail is the tail of the variable list
List.

copy term(+In, -Out) [ISO]

Create a version of In with renamed (fresh) variables and unify it to Out. Attributed variables
(see section 7.1) have their attributes copied. The implementation of copy term/2 can deal
with infinite trees (cyclic terms). As pure Prolog cannot distinguish a ground term from another
ground term with exactly the same structure, ground sub-terms are shared between In and Out.
Sharing ground terms does affect setarg/3. SWI-Prolog provides duplicate term/2 to
create a true copy of a term.

4.21.1 Non-logical operations on terms

Prolog is not able to modify instantiated parts of a term. Lacking that capability makes the language
much safer, but unfortunately there are problems that suffer severely in terms of time and/or memory
usage. Always try hard to avoid the use of these primitives, but they can be a good alternative to using
dynamic predicates. See also section 4.33, discussing the use of global variables.

setarg(+Arg, +Term, +Value)

Extra-logical predicate. Assigns the Arg-th argument of the compound term Term with the
given Value. The assignment is undone if backtracking brings the state back into a position
before the setarg/3 call. See also nb setarg/3.
This predicate may be used for destructive assignment to terms, using them as an extra-logical
storage bin. Always try hard to avoid the use of setarg/3 as it is not supported by many
64
BUG: Currently this option is ignored for cyclic terms.
65
This predicate used to be called free variables/2. The name term variables/2 is more widely used. The
old predicate is still available from the library backcomp.

SWI-Prolog 7.4 Reference Manual

164 CHAPTER 4. BUILT-IN PREDICATES

Prolog systems and one has to be very careful about unexpected copying as well as unexpected
noncopying of terms. A good practice to improve somewhat on this situation is to make sure that
terms whose arguments are subject to setarg/3 have one unused and unshared variable in
addition to the used arguments. This variable avoids unwanted sharing in, e.g., copy term/2,
and causes the term to be considered as non-ground. An alternative is to use put attr/3 to
attach information to attributed variables (see section 7.1).

nb setarg(+Arg, +Term, +Value)

Assigns the Arg-th argument of the compound term Term with the given Value as setarg/3,
but on backtracking the assignment is not reversed. If Value is not atomic, it is duplicated
using duplicate term/2. This predicate uses the same technique as nb setval/2.
We therefore refer to the description of nb setval/2 for details on non-backtrackable
assignment of terms. This predicate is compatible with GNU-Prolog setarg(A,T,V,false),
removing the type restriction on Value. See also nb linkarg/3. Below is an example for
counting the number of solutions of a goal. Note that this implementation is thread-safe,
reentrant and capable of handling exceptions. Realising these features with a traditional
implementation based on assert/retract or flag/3 is much more complicated.

:- meta_predicate
succeeds_n_times(0, -).

succeeds_n_times(Goal, Times) :-
Counter = counter(0),
( Goal,
arg(1, Counter, N0),
N is N0 + 1,
nb_setarg(1, Counter, N),
fail
; arg(1, Counter, Times)
).

nb linkarg(+Arg, +Term, +Value)

As nb setarg/3, but like nb linkval/2 it does not duplicate Value. Use with extreme
care and consult the documentation of nb linkval/2 before use.

duplicate term(+In, -Out)

Version of copy term/2 that also copies ground terms and therefore ensures that destruc-
tive modification using setarg/3 does not affect the copy. See also nb setval/2,
nb linkval/2, nb setarg/3 and nb linkarg/3.

same term(@T1, @T2) [semidet]

True if T1 and T2 are equivalent and will remain equivalent, even if setarg/3 is used on
either of them. This means T1 and T2 are the same variable, equivalent atomic data or a
compound term allocated at the same address.

SWI-Prolog 7.4 Reference Manual

4.22. ANALYSING AND CONSTRUCTING ATOMS 165

4.22 Analysing and Constructing Atoms

These predicates convert between Prolog constants and lists of character codes. The predicates
atom codes/2, number codes/2 and name/2 behave the same when converting from a con-
stant to a list of character codes. When converting the other way around, atom codes/2 will
generate an atom, number codes/2 will generate a number or exception and name/2 will return
a number if possible and an atom otherwise.
The ISO standard defines atom chars/2 to describe the broken-up atom as a list of one-
character atoms instead of a list of codes. Up to version 3.2.x, SWI-Prologs atom chars/2
behaved like atom codes, compatible with Quintus and SICStus Prolog. As of 3.3.x, SWI-Prolog
atom codes/2 and atom chars/2 are compliant to the ISO standard.
To ease the pain of all variations in the Prolog community, all SWI-Prolog predicates behave as
flexible as possible. This implies the list-side accepts either a code-list or a char-list and the atom-
side accepts all atomic types (atom, number and string).

atom codes(?Atom, ?String) [ISO]

Convert between an atom and a list of character codes. If Atom is instantiated, it will be trans-
lated into a list of character codes and the result is unified with String. If Atom is unbound and
String is a list of character codes, Atom will be unified with an atom constructed from this list.

atom chars(?Atom, ?CharList) [ISO]

As atom codes/2, but CharList is a list of one-character atoms rather than a list of character
codes.66

?- atom_chars(hello, X).

X = [h, e, l, l, o]

char code(?Atom, ?Code) [ISO]

Convert between character and character code for a single character.67

number chars(?Number, ?CharList) [ISO]

Similar to atom chars/2, but converts between a number and its representation as a list of
one-character atoms. Fails with a syntax error if Number is unbound or CharList does not
describe a number. Following the ISO standard, it allows for leading white space (including
newlines) and does not allow for trailing white space.68

number codes(?Number, ?CodeList) [ISO]

As number chars/2, but converts to a list of character codes rather than one-character
atoms. In the mode (-, +), both predicates behave identically to improve handling of non-ISO
source.
66
Up to version 3.2.x, atom chars/2 behaved as the current atom codes/2. The current definition is compliant
with the ISO standard.
67
This is also called atom char/2 in older versions of SWI-Prolog as well as some other Prolog implementations. The
atom char/2 predicate is available from the library backcomp.pl
68
ISO also allows for Prolog comments in leading white space. Weand most other implementationsbelieve this is
incorrect. We also beleive it would have been better not to allow for white space, or to allow for both leading and trailing
white space. Prolog syntax-based conversion can be achieved using format/3 and read from chars/2.

SWI-Prolog 7.4 Reference Manual

166 CHAPTER 4. BUILT-IN PREDICATES

atom number(?Atom, ?Number)

Realises the popular combination of atom codes/2 and number codes/2 to convert
between atom and number (integer or float) in one predicate, avoiding the intermediate list.
Unlike the ISO number codes/2 predicates, atom number/2 fails silently in mode (+,-)
if Atom does not represent a number.69 See also atomic list concat/2 for assembling
an atom from atoms and numbers.

name(?Atomic, ?CodeList)
CodeList is a list of character codes representing the same text as Atomic. Each of the argu-
ments may be a variable, but not both. When CodeList describes an integer or floating point
number and Atomic is a variable, Atomic will be unified with the numeric value described by
CodeList (e.g., name(N, "300"), 400 is N + 100 succeeds). If CodeList is not a
representation of a number, Atomic will be unified with the atom with the name given by the
character code list. When Atomic is an atom or number, the unquoted print representation of it
as a character code list will be unified with CodeList.
Note that it is not possible to produce the atom 300 using name/2, and that
name(300, CodeList), name(300, CodeList) succeeds. For these reasons,
new code should consider using the ISO predicates atom codes/2 or number codes/2.70
See also atom number/2.

term to atom(?Term, ?Atom)

True if Atom describes a term that unifies with Term. When Atom is instantiated, Atom is
parsed and the result unified with Term. If Atom has no valid syntax, a syntax error
exception is raised. Otherwise Term is written on Atom using write term/2 with the
option quoted(true). See also format/3, with output to/2 and term string/2.

atom to term(+Atom, -Term, -Bindings) [deprecated]

Use Atom as input to read term/2 using the option variable names and return the
read term in Term and the variable bindings in Bindings. Bindings is a list of Name = Var
couples, thus providing access to the actual variable names. See also read term/2. If
Atom has no valid syntax, a syntax error exception is raised. New code should use
read term from atom/3.

atom concat(?Atom1, ?Atom2, ?Atom3) [ISO]

Atom3 forms the concatenation of Atom1 and Atom2. At least two of the arguments must be
instantiated to atoms. This predicate also allows for the mode (-,-,+), non-deterministically
splitting the 3rd argument into two parts (as append/3 does for lists). SWI-Prolog allows for
atomic arguments. Portable code must use atomic concat/3 if non-atom arguments are
involved.

atomic concat(+Atomic1, +Atomic2, -Atom)

Atom represents the text after converting Atomic1 and Atomic2 to text and concatenating the
result:
69
Versions prior to 6.1.7 raise a syntax error, compliant to number codes/2
70
Unfortunately, the ISO predicates provide no neat way to check that a string can be interpreted as a number. The
most sensible way is to use catch/3 to catch the exception from number codes/2; however, this is both slow and
cumbersome. We consider making, e.g., number codes(N, "abc") fail silently in future versions.

SWI-Prolog 7.4 Reference Manual

4.22. ANALYSING AND CONSTRUCTING ATOMS 167

?- atomic_concat(name, 42, X).

X = name42.

atomic list concat(+List, -Atom) [commons]

List is a list of strings, atoms, integers or floating point numbers. Succeeds if Atom can be
unified with the concatenated elements of List. Equivalent to atomic list concat(List, ,
Atom).

atomic list concat(+List, +Separator, -Atom) [commons]

Creates an atom just like atomic list concat/2, but inserts Separator between each pair
of inputs. For example:

?- atomic_list_concat([gnu, gnat], , , A).

A = gnu, gnat

The SWI-Prolog version of this predicate can also be used to split atoms by instantiating Sepa-
rator and Atom as shown below. We kept this functionality to simplify porting old SWI-Prolog
code where this predicate was called concat atom/3. When used in mode (-,+,+), Separator
must be a non-empty atom. See also split string/4.

?- atomic_list_concat(L, -, gnu-gnat).

L = [gnu, gnat]

atom length(+Atom, -Length) [ISO]

True if Atom is an atom of Length characters. The SWI-Prolog version accepts all atomic
types, as well as code-lists and character-lists. New code should avoid this feature and use
write length/3 to get the number of characters that would be written if the argument was
handed to write term/3.

atom prefix(+Atom, +Prefix) [deprecated]

True if Atom starts with the characters from Prefix. Its behaviour is equivalent to
?- sub atom(Atom, 0, , , Prefix). Deprecated.

sub atom(+Atom, ?Before, ?Len, ?After, ?Sub) [ISO]

ISO predicate for breaking atoms. It maintains the following relation: Sub is a sub-atom of
Atom that starts at Before, has Len characters, and Atom contains After characters after the
match.

?- sub_atom(abc, 1, 1, A, S).

A = 1, S = b

The implementation minimises non-determinism and creation of atoms. This is a flexible pred-
icate that can do search, prefix- and suffix-matching, etc.

SWI-Prolog 7.4 Reference Manual

168 CHAPTER 4. BUILT-IN PREDICATES

sub atom icasechk(+Haystack, ?Start, +Needle) [semidet]

True when Needle is a sub atom of Haystack starting at Start. The match is half case in-
sensitive, i.e., uppercase letters in Needle only match themselves, while lowercase letters in
Needle match case insensitively. Start is the first 0-based offset inside Haystack where Needle
matches.71

4.23 Localization (locale) support

SWI-Prolog provides (currently limited) support for localized applications.

The predicates char type/2 and code type/2 query character classes depending on the
locale.

The predicates collation key/2 and locale sort/2 can be used for locale dependent
sorting of atoms.

The predicate format time/3 can be used to format time and date representations, where
some of the specifiers are locale dependent.

The predicate format/2 provides locale-specific formating of numbers. This functionality is

based on a more fine-grained localization model that is the subject of this section.

A locale is a (optionally named) read-only object that provides information to locale specific
functions.72 The system creates a default locale object named default from the system locale. This
locale is used as the initial locale for the three standard streams as well as the main thread. Locale
sensitive output predicates such as format/3 get their locale from the stream to which they deliver
their output. New streams get their locale from the thread that created the stream. Threads get their
locale from the thread that created them.

locale create(-Locale, +Default, +Options)

Create a new locale object. Default is either an existing locale or a string that denotes the name
of a locale provided by the system, such as "en_EN.UTF-8". The values read from the
default locale can be modified using Options. Options provided are:

alias(+Atom)
Give the locale a name.
decimal point(+Atom)
Specify the decimal point to use.
thousands sep(+Atom)
Specify the string that delimits digit groups. Only effective is grouping is also specified.
71
This predicate replaces $apropos match/2, used by the help system, while extending it with locating the (first) match
and performing case insensitive prefix matching. We are still not happy with the name and interface.
72
The locale interface described in this section and its effect on format/2 and reading integers from digit groups was
discussed on the SWI-Prolog mailinglist. Most input in this discussion is from Ulrich Neumerkel and Richard OKeefe.
The predicates in this section were designed by Jan Wielemaker.

SWI-Prolog 7.4 Reference Manual

4.24. CHARACTER PROPERTIES 169

grouping(+List)
Specify the grouping of digits. Groups are created from the right (least significant) digits,
left of the decimal point. List is a list of integers, specifying the number of digits in each
group, counting from the right. If the last element is repeat(Count), the remaining
digits are grouped in groups of size Count. If the last element is a normal integer, digits
further to the left are not grouped.

For example, the English locale uses

[ decimal_point(.), thousands_sep(,), grouping([repeat(3)]) ]

Named locales exists until they are destroyed using locale destroy/1 and they are no
longer referenced. Unnamed locales are subject to (atom) garbage collection.

locale destroy(+Locale)
Destroy a locale. If the locale is named, this removes the name association from the locale,
after which the locale is left to be reclaimed by garbage collection.

locale property(?Locale, ?Property)

True when Locale has Property. Properties are the same as the Options described with
locale create/3.

set locale(+Locale)
Set the default locale for the current thread, as well as the locale for the standard streams
(user input, user output, user error, current output and current input.
This locale is used for new streams, unless overruled using the locale(Locale) option of
open/4 or set stream/2.

current locale(-Locale)
True when Locale is the locale of the calling thread.

4.24 Character properties

SWI-Prolog offers two comprehensive predicates for classifying characters and character codes.
These predicates are defined as built-in predicates to exploit the C-character classifications handling
of locale (handling of local character sets). These predicates are fast, logical and deterministic if
applicable.
In addition, there is the library ctypes providing compatibility with some other Prolog systems.
The predicates of this library are defined in terms of code type/2.

char type(?Char, ?Type)

Tests or generates alternative Types or Chars. The character types are inspired by the standard
C <ctype.h> primitives.

alnum
Char is a letter (upper- or lowercase) or digit.
alpha
Char is a letter (upper- or lowercase).

SWI-Prolog 7.4 Reference Manual

170 CHAPTER 4. BUILT-IN PREDICATES

csym
Char is a letter (upper- or lowercase), digit or the underscore (_). These are valid C and
Prolog symbol characters.
csymf
Char is a letter (upper- or lowercase) or the underscore (_). These are valid first characters
for C and Prolog symbols.
ascii
Char is a 7-bit ASCII character (0..127).
white
Char is a space or tab, i.e. white space inside a line.
cntrl
Char is an ASCII control character (0..31).
digit
Char is a digit.
digit(Weight)
Char is a digit with value Weight. I.e. char type(X, digit(6) yields X = 6.
Useful for parsing numbers.
xdigit(Weight)
Char is a hexadecimal digit with value Weight. I.e. char type(a, xdigit(X)
yields X = 10. Useful for parsing numbers.
graph
Char produces a visible mark on a page when printed. Note that the space is not included!
lower
Char is a lowercase letter.
lower(Upper)
Char is a lowercase version of Upper. Only true if Char is lowercase and Upper upper-
case.
to lower(Upper)
Char is a lowercase version of Upper. For non-letters, or letter without case, Char and
Lower are the same. See also upcase atom/2 and downcase atom/2.
upper
Char is an uppercase letter.
upper(Lower)
Char is an uppercase version of Lower. Only true if Char is uppercase and Lower lower-
case.
to upper(Lower)
Char is an uppercase version of Lower. For non-letters, or letter without case, Char and
Lower are the same. See also upcase atom/2 and downcase atom/2.
punct
Char is a punctuation character. This is a graph character that is not a letter or digit.
space
Char is some form of layout character (tab, vertical tab, newline, etc.).

SWI-Prolog 7.4 Reference Manual

4.24. CHARACTER PROPERTIES 171

end of file
Char is -1.
end of line
Char ends a line (ASCII: 10..13).
newline
Char is a newline character (10).
period
Char counts as the end of a sentence (.,!,?).
quote
Char is a quote character (", , ).
paren(Close)
Char is an open parenthesis and Close is the corresponding close parenthesis.
prolog var start
Char can start a Prolog variable name.
prolog atom start
Char can start a unquoted Prolog atom that is not a symbol.
prolog identifier continue
Char can continue a Prolog variable name or atom.
prolog prolog symbol
Char is a Prolog symbol character. Sequences of Prolog symbol characters glue together
to form an unquoted atom. Examples are =.., \=, etc.

code type(?Code, ?Type)

As char type/2, but uses character codes rather than one-character atoms. Please note
that both predicates are as flexible as possible. They handle either representation if the
argument is instantiated and will instantiate only with an integer code or a one-character atom,
depending of the version used. See also the Prolog flag double quotes, atom chars/2
and atom codes/2.

4.24.1 Case conversion

There is nothing in the Prolog standard for converting case in textual data. The SWI-Prolog predicates
code type/2 and char type/2 can be used to test and convert individual characters. We have
started some additional support:

downcase atom(+AnyCase, -LowerCase)

Converts the characters of AnyCase into lowercase as char type/2 does (i.e. based on
the defined locale if Prolog provides locale support on the hosting platform) and unifies the
lowercase atom with LowerCase.

upcase atom(+AnyCase, -UpperCase)

Converts, similar to downcase atom/2, an atom to uppercase.

SWI-Prolog 7.4 Reference Manual

172 CHAPTER 4. BUILT-IN PREDICATES

4.24.2 White space normalization

normalize space(-Out, +In)
Normalize white space in In. All leading and trailing white space is removed. All non-empty
sequences for Unicode white space characters are replaced by a single space (\u0020)
character. Out uses the same conventions as with output to/2 and format/3.

4.24.3 Language-specific comparison

This section deals with predicates for language-specific string comparison operations.

collation key(+Atom, -Key)

Create a Key from Atom for locale-specific comparison. The key is defined such that if the
key of atom A precedes the key of atom B in the standard order of terms, A is alphabetically
smaller than B using the sort order of the current locale.
The predicate collation key/2 is used by locale sort/2 from library(sort). Please
examine the implementation of locale sort/2 as an example of using this call.
The Key is an implementation-defined and generally unreadable string. On systems that do not
support locale handling, Key is simply unified with Atom.

locale sort(+List, -Sorted)

Sort a list of atoms using the current locale. List is a list of atoms or string objects (see sec-
tion 5.2). Sorted is unified with a list containing all atoms of List, sorted to the rules of the
current locale. See also collation key/2 and setlocale/3.

4.25 Operators
Operators are defined to improve the readability of source code. For example, without operators, to
write 2*3+4*5 one would have to write +(*(2,3),*(4,5)). In Prolog, a number of operators
have been predefined. All operators, except for the comma (,) can be redefined by the user.
Some care has to be taken before defining new operators. Defining too many operators might
make your source natural looking, but at the same time make it hard to understand the limits of your
syntax. To ease the pain, as of SWI-Prolog 3.3.0, operators are local to the module in which they are
defined. Operators can be exported from modules using a term op(Precedence, Type, Name) in the
export list as specified by module/2. Many modern Prolog systems have module specific operators.
Unfortunately, there is no established interface for exporting and importing operators. SWI-Prologs
convention has been addopted by YAP.
The module table of the module user acts as default table for all modules and can be modified
explicitly from inside a module to achieve compatibility with other Prolog that do not have module-
local operators:

:- module(prove,
[ prove/1
]).

:- op(900, xfx, user:(=>)).

SWI-Prolog 7.4 Reference Manual

4.26. CHARACTER CONVERSION 173

In SWI-Prolog, a quoted atom never acts as an operator. Note that the portable way to stop an atom
acting as an operator is to enclose it in parentheses like this: (myop). See also section 5.3.1.

op(+Precedence, +Type, :Name) [ISO]

Declare Name to be an operator of type Type with precedence Precedence. Name can also be
a list of names, in which case all elements of the list are declared to be identical operators.
Precedence is an integer between 0 and 1200. Precedence 0 removes the declaration. Type is
one of: xf, yf, xfx, xfy, yfx, fy or fx. The f indicates the position of the functor, while
x and y indicate the position of the arguments. y should be interpreted as on this position a
term with precedence lower or equal to the precedence of the functor should occur. For x
the precedence of the argument must be strictly lower. The precedence of a term is 0, unless its
principal functor is an operator, in which case the precedence is the precedence of this operator.
A term enclosed in parentheses (...) has precedence 0.
The predefined operators are shown in table 4.2. Operators can be redefined, unless prohibited
by one of the limitations below. Applications must be careful with (re-)defining operators be-
cause changing operators may cause (other) files to be interpreted differently. Often this will
lead to a syntax error. In other cases, text is read silently into a different term which may lead
to subtle and difficult to track errors.

It is not allowed to redefine the comma (,).

The bar (|) can only be (re-)defined as infix operator with priority not less than 1001.
It is not allowed to define the empty list ([]) or the curly-bracket pair ({}) as operators.

In SWI-Prolog, operators are local to a module (see also section 6.8). Keeping operators in
modules and using controlled import/export of operators as described with the module/2 di-
rective keep the issues manageable. The module system provides the operators from table 4.2
and these operators cannot be modified. Files that are loaded from the SWI-Prolog directories
resolve operators and predicates from this system module rather than user, which makes the
semantics of the library and development system modules independent of operator changes to
the user module.
current op(?Precedence, ?Type, ?:Name) [ISO]
True if Name is currently defined as an operator of type Type with precedence Precedence. See
also op/3.

4.26 Character Conversion

Although I wouldnt really know why you would like to use these features, they are provided for ISO
compliance.

char conversion(+CharIn, +CharOut) [ISO]

Define that term input (see read term/3) maps each character read as CharIn to the charac-
ter CharOut. Character conversion is only executed if the Prolog flag char conversion is
set to true and not inside quoted atoms or strings. The initial table maps each character onto
itself. See also current char conversion/2.
current char conversion(?CharIn, ?CharOut) [ISO]
Queries the current character conversion table. See char conversion/2 for details.

SWI-Prolog 7.4 Reference Manual

174 CHAPTER 4. BUILT-IN PREDICATES

1200 xf x -->, :-
1200 fx :-, ?-
1150 fx dynamic, discontiguous, initialization,
meta predicate, module transparent, multifile,
public, thread local, thread initialization,
volatile
1100 xf y ;, |
1050 xf y ->, *->
1000 xf y ,
990 xf x :=
900 fy \+
700 xf x <, =, =.., =@=, \=@=, =:=, =<, ==, =\=, >, >=, @<, @=<, @>,
@>=, \=, \==, as, is, >:<, :<
600 xf y :
500 yf x +, -, /\, \/, xor
500 fx ?
400 yf x *, /, //, div, rdiv, <<, >>, mod, rem
200 xf x **
200 xf y
200 fy +, -, \
100 yf x .
1 fx $

Table 4.2: System operators

SWI-Prolog 7.4 Reference Manual

4.27. ARITHMETIC 175

4.27 Arithmetic
Arithmetic can be divided into some special purpose integer predicates and a series of general pred-
icates for integer, floating point and rational arithmetic as appropriate. The general arithmetic predi-
cates all handle expressions. An expression is either a simple number or a function. The arguments of
a function are expressions. The functions are described in section 4.27.2.

4.27.1 Special purpose integer arithmetic

The predicates in this section provide more logical operations between integers. They are not covered
by the ISO standard, although they are part of the community and found as either library or built-in
in many other Prolog systems.

between(+Low, +High, ?Value)

Low and High are integers, High Low. If Value is an integer, Low Value High. When
Value is a variable it is successively bound to all integers between Low and High. If High
is inf or infinite73 between/3 is true iff Value Low, a feature that is particularly
interesting for generating integers from a certain value.
succ(?Int1, ?Int2)
True if Int2 = Int1 + 1 and Int1 0. At least one of the arguments must be instantiated to a
natural number. This predicate raises the domain error not less than zero if called with
a negative integer. E.g. succ(X, 0) fails silently and succ(X, -1) raises a domain error.74
plus(?Int1, ?Int2, ?Int3)
True if Int3 = Int1 + Int2. At least two of the three arguments must be instantiated to integers.
divmod(+Dividend, +Divisor, -Quotient, -Remainder)
This predicate is a shorthand for computing both the Quotient and Remainder of two integers
in a single operation. This allows for exploiting the fact that the low level implementation
for computing the quotient also produces the remainder. Timing confirms that this predicate
is almost twice as fast as performing the steps independently. Semantically, divmod/4 is
defined as below.

divmod(Dividend, Divisor, Quotient, Remainder) :-

Quotient is Dividend div Divisor,
Remainder is Dividend mod Divisor.

Note that this predicate is only available if SWI-Prolog is compiled with unbounded integer
support. This is the case for all packaged versions.
nth integer root and remainder(+N, +I, -Root, -Remainder)
True when RootN + Remainder = I. N and I must be integers.75 N must be one or more. If I
is negative and N is odd, Root and Remainder are negative, i.e., the following holds for I < 0:
73
We prefer infinite, but some other Prolog systems already use inf for infinity; we accept both for the time being.
74
The behaviour to deal with natural numbers only was defined by Richard OKeefe to support the common count-down-
to-zero in a natural way. Up to 5.1.8, succ/2 also accepted negative integers.
75
This predicate was suggested by Markus Triska. The final name and argument order is by Richard OKeefe. The
decision to include the remainder is by Jan Wielemaker. Including the remainder makes this predicate about twice as slow
if Root is not exact.

SWI-Prolog 7.4 Reference Manual

176 CHAPTER 4. BUILT-IN PREDICATES

% I < 0,
% N mod 2 =\= 0,
nth_integer_root_and_remainder(
N, I, Root, Remainder),
IPos is -I,
nth_integer_root_and_remainder(
N, IPos, RootPos, RemainderPos),
Root =:= -RootPos,
Remainder =:= -RemainderPos.

4.27.2 General purpose arithmetic

The general arithmetic predicates are optionally compiled (see set prolog flag/2 and the -O
command line option). Compiled arithmetic reduces global stack requirements and improves perfor-
mance. Unfortunately compiled arithmetic cannot be traced, which is why it is optional.

+Expr1 > +Expr2 [ISO]

True if expression Expr1 evaluates to a larger number than Expr2.

+Expr1 < +Expr2 [ISO]

True if expression Expr1 evaluates to a smaller number than Expr2.

+Expr1 =< +Expr2 [ISO]

True if expression Expr1 evaluates to a smaller or equal number to Expr2.

+Expr1 >= +Expr2 [ISO]

True if expression Expr1 evaluates to a larger or equal number to Expr2.

+Expr1 =\= +Expr2 [ISO]

True if expression Expr1 evaluates to a number non-equal to Expr2.

+Expr1 =:= +Expr2 [ISO]

True if expression Expr1 evaluates to a number equal to Expr2.

-Number is +Expr [ISO]

True when Number is the value to which Expr evaluates. Typically, is/2 should be used with
unbound left operand. If equality is to be tested, =:=/2 should be used. For example:

?- 1 is sin(pi/2). Fails! sin(pi/2) evaluates to the float 1.0,

which does not unify with the integer 1.
?- 1 =:= sin(pi/2). Succeeds as expected.

Arithmetic types

SWI-Prolog defines the following numeric types:

SWI-Prolog 7.4 Reference Manual

4.27. ARITHMETIC 177

integer
If SWI-Prolog is built using the GNU multiple precision arithmetic library (GMP), integer
arithmetic is unbounded, which means that the size of integers is limited by available memory
only. Without GMP, SWI-Prolog integers are 64-bits, regardless of the native integer size of
the platform. The type of integer support can be detected using the Prolog flags bounded,
min integer and max integer. As the use of GMP is default, most of the following
descriptions assume unbounded integer arithmetic.
Internally, SWI-Prolog has three integer representations. Small integers (defined by the Prolog
flag max tagged integer) are encoded directly. Larger integers are represented as 64-bit
values on the global stack. Integers that do not fit in 64 bits are represented as serialised GNU
MPZ structures on the global stack.
rational number
Rational numbers (Q) are quotients of two integers. Rational arithmetic is only provided if GMP
is used (see above). Rational numbers are currently not supported by a Prolog type. They are
represented by the compound term rdiv(N,M). Rational numbers that are returned from is/2
are canonical, which means M is positive and N and M have no common divisors. Rational
numbers are introduced in the computation using the rational/1, rationalize/1 or
the rdiv/2 (rational division) function. Using the same functor for rational division and for
representing rational numbers allows for passing rational numbers between computations as
well as for using format/3 for printing.
In the long term, it is likely that rational numbers will become atomic as well as a subtype of
number. User code that creates or inspects the rdiv(M,N) terms will not be portable to future
versions. Rationals are created using one of the functions mentioned above and inspected using
rational/3.
float
Floating point numbers are represented using the C type double. On most of todays platforms
these are 64-bit IEEE floating point numbers.
Arithmetic functions that require integer arguments accept, in addition to integers, rational num-
bers with (canonical) denominator 1. If the required argument is a float the argument is converted to
float. Note that conversion of integers to floating point numbers may raise an overflow exception. In
all other cases, arguments are converted to the same type using the order below.
integer rational number floating point number

Rational number examples

The use of rational numbers with unbounded integers allows for exact integer or fixed point arithmetic
under addition, subtraction, multiplication and division. To exploit rational arithmetic rdiv/2 should
be used instead of / and floating point numbers must be converted to rational using rational/1.
Omitting the rational/1 on floats will convert a rational operand to float and continue the arith-
metic using floating point numbers. Here are some examples.
A is 2 rdiv 6 A = 1 rdiv 3
A is 4 rdiv 3 + 1 A = 7 rdiv 3
A is 4 rdiv 3 + 1.5 A = 2.83333
A is 4 rdiv 3 + rational(1.5) A = 17 rdiv 6

SWI-Prolog 7.4 Reference Manual

178 CHAPTER 4. BUILT-IN PREDICATES

Note that floats cannot represent all decimal numbers exactly. The function rational/1 creates
an exact equivalent of the float, while rationalize/1 creates a rational number that is within the
float rounding error from the original float. Please check the documentation of these functions for
details and examples.
Rational numbers can be printed as decimal numbers with arbitrary precision using the
format/3 floating point conversion:

?- A is 4 rdiv 3 + rational(1.5),
format(50fn, [A]).
2.83333333333333333333333333333333333333333333333333

A = 17 rdiv 6

Arithmetic Functions
Arithmetic functions are terms which are evaluated by the arithmetic predicates described in sec-
tion 4.27.2. There are four types of arguments to functions:

Expr Arbitrary expression, returning either a floating point value or an

integer.
IntExpr Arbitrary expression that must evaluate to an integer.
RatExpr Arbitrary expression that must evaluate to a rational number.
FloatExpr Arbitrary expression that must evaluate to a floating point.

For systems using bounded integer arithmetic (default is unbounded, see section 4.27.2 for de-
tails), integer operations that would cause overflow automatically convert to floating point arithmetic.
SWI-Prolog provides many extensions to the set of floating point functions defined by the ISO
standard. The current policy is to provide such functions on as-needed basis if the function is widely
supported elsewhere and notably if it is part of the C99 mathematical library. In addition, we try to
maintain compatibility with YAP.

- +Expr [ISO]
Result = Expr

+ +Expr [ISO]
Result = Expr. Note that if + is followed by a number, the parser discards the +. I.e.
?- integer(+1) succeeds.

+Expr1 + +Expr2 [ISO]

Result = Expr1 + Expr2

+Expr1 - +Expr2 [ISO]

Result = Expr1 Expr2

+Expr1 * +Expr2 [ISO]

Result = Expr1 Expr2

SWI-Prolog 7.4 Reference Manual

4.27. ARITHMETIC 179

+Expr1 / +Expr2 [ISO]

Expr1
Result = Expr2 . If the flag iso is true, both arguments are converted to float and the return
value is a float. Otherwise (default), if both arguments are integers the operation returns an
integer if the division is exact. If at least one of the arguments is rational and the other argument
is integer, the operation returns a rational number. In all other cases the return value is a float.
See also ///2 and rdiv/2.

+IntExpr1 mod +IntExpr2 [ISO]

Modulo, defined as Result = IntExpr1 - (IntExpr1 div IntExpr2) IntExpr2, where div is
floored division.

+IntExpr1 rem +IntExpr2 [ISO]

Remainder of integer division. Behaves as if defined by
Result is IntExpr1 - (IntExpr1 // IntExpr2) IntExpr2

+IntExpr1 // +IntExpr2 [ISO]

Integer division, defined as Result is rndI (Expr1/Expr2). The function rndI is the
default rounding used by the C compiler and available through the Prolog flag
integer rounding function. In the C99 standard, C-rounding is defined as
towards zero. 76

div(+IntExpr1, +IntExpr2) [ISO]

Integer division, defined as Result is (IntExpr1 - IntExpr1 mod IntExpr2) // IntExpr2. In other
words, this is integer division that rounds towards -infinity. This function guarantees behaviour
that is consistent with mod/2, i.e., the following holds for every pair of integers X, Y where
Y =\= 0.

Q is div(X, Y),
M is mod(X, Y),
X =:= Y*Q+M.

+RatExpr rdiv +RatExpr

Rational number division. This function is only available if SWI-Prolog has been compiled
with rational number support. See section 4.27.2 for details.

+IntExpr1 gcd +IntExpr2

Result is the greatest common divisor of IntExpr1, IntExpr2.

abs(+Expr) [ISO]
Evaluate Expr and return the absolute value of it.

sign(+Expr) [ISO]
Evaluate to -1 if Expr < 0, 1 if Expr > 0 and 0 if Expr = 0. If Expr evaluates to a float, the
return value is a float (e.g., -1.0, 0.0 or 1.0). In particular, note that sign(-0.0) evaluates to 0.0.
See also copysign/2
76
Future versions might guarantee rounding towards zero.

SWI-Prolog 7.4 Reference Manual

180 CHAPTER 4. BUILT-IN PREDICATES

copysign(+Expr1, +Expr2) [ISO]

Evaluate to X, where the absolute value of X equals the absolute value of Expr1 and the sign of
X matches the sign of Expr2. This function is based on copysign() from C99, which works on
double precision floats and deals with handling the sign of special floating point values such as
-0.0. Our implementation follows C99 if both arguments are floats. Otherwise, copysign/2
evaluates to Expr1 if the sign of both expressions matches or -Expr1 if the signs do not match.
Here, we use the extended notion of signs for floating point numbers, where the sign of -0.0
and other special floats is negative.

max(+Expr1, +Expr2) [ISO]

Evaluate to the larger of Expr1 and Expr2. Both arguments are compared after converting to
the same type, but the return value is in the original type. For example, max(2.5, 3) compares
the two values after converting to float, but returns the integer 3.

min(+Expr1, +Expr2) [ISO]

Evaluate to the smaller of Expr1 and Expr2. See max/2 for a description of type handling.

.(+Int, [])
A list of one element evaluates to the element. This implies "a" evaluates to the character code
of the letter a (97) using the traditional mapping of double quoted string to a list of character
codes. Arithmetic evaluation also translates a string object (see section 5.2) of one character
length into the character code for that character. This implies that expression "a" also works
of the Prolog flag double quotes is set to string. The recommended way to specify the
character code of the letter a is 0a.

random(+IntExpr)
Evaluate to a random integer i for which 0 i < IntExpr. The system has two implemen-
tations. If it is compiled with support for unbounded arithmetic (default) it uses the GMP
library random functions. In this case, each thread keeps its own random state. The default
algorithm is the Mersenne Twister algorithm. The seed is set when the first random number in
a thread is generated. If available, it is set from /dev/random. Otherwise it is set from the
system clock. If unbounded arithmetic is not supported, random numbers are shared between
threads and the seed is initialised from the clock when SWI-Prolog was started. The predicate
set random/1 can be used to control the random number generator.

random float
Evaluate to a random float I for which 0.0 < i < 1.0. This function shares the random state with
random/1. All remarks with the function random/1 also apply for random float/0.
Note that both sides of the domain are open. This avoids evaluation errors on, e.g., log/1 or
//2 while no practical application can expect 0.0.77

round(+Expr) [ISO]
Evaluate Expr and round the result to the nearest integer. According to ISO, round/1 is
defined as floor(Expr+1/2), i.e., rounding down. This is an unconventional choice and
77
Richard OKeefe said: If you are generating IEEE doubles with the claimed uniformity, then 0 has a 1 in 253 =
1in9, 007, 199, 254, 740, 992 chance of turning up. No program that expects [0.0,1.0) is going to be surprised when 0.0
fails to turn up in a few millions of millions of trials, now is it? But a program that expects (0.0,1.0) could be devastated if
0.0 did turn up.

SWI-Prolog 7.4 Reference Manual

4.27. ARITHMETIC 181

under which the relation round(Expr) == -round(-Expr) does not hold. SWI-Prolog
rounds outward, e.g., round(1.5) =:= 2 and round round(-1.5) =:= -2.

integer(+Expr)
Same as round/1 (backward compatibility).

float(+Expr) [ISO]
Translate the result to a floating point number. Normally, Prolog will use integers whenever
possible. When used around the 2nd argument of is/2, the result will be returned as a floating
point number. In other contexts, the operation has no effect.

rational(+Expr)
Convert the Expr to a rational number or integer. The function returns the input on integers
and rational numbers. For floating point numbers, the returned rational number exactly
represents the float. As floats cannot exactly represent all decimal numbers the results may be
surprising. In the examples below, doubles can represent 0.25 and the result is as expected, in
contrast to the result of rational(0.1). The function rationalize/1 remedies this. See
section 4.27.2 for more information on rational number support.

?- A is rational(0.25).

A is 1 rdiv 4
?- A is rational(0.1).
A = 3602879701896397 rdiv 36028797018963968

rationalize(+Expr)
Convert the Expr to a rational number or integer. The function is similar to rational/1,
but the result is only accurate within the rounding error of floating point numbers, generally
producing a much smaller denominator.78

?- A is rationalize(0.25).

A = 1 rdiv 4
?- A is rationalize(0.1).

A = 1 rdiv 10

float fractional part(+Expr) [ISO]

Fractional part of a floating point number. Negative if Expr is negative, rational
if Expr is rational and 0 if Expr is integer. The following relation is always true:
Xisf loatf ractionalp art(X) + f loati ntegerp art(X).

float integer part(+Expr) [ISO]

Integer part of floating point number. Negative if Expr is negative, Expr if Expr is integer.
78
The names rational/1 and rationalize/1 as well as their semantics are inspired by Common Lisp.

SWI-Prolog 7.4 Reference Manual

182 CHAPTER 4. BUILT-IN PREDICATES

truncate(+Expr) [ISO]
Truncate Expr to an integer. If Expr 0 this is the same as floor(Expr). For Expr < 0 this is
the same as ceil(Expr). That is, truncate/1 rounds towards zero.

floor(+Expr) [ISO]
Evaluate Expr and return the largest integer smaller or equal to the result of the evaluation.

ceiling(+Expr) [ISO]
Evaluate Expr and return the smallest integer larger or equal to the result of the evaluation.

ceil(+Expr)
Same as ceiling/1 (backward compatibility).

+IntExpr1 >> +IntExpr2 [ISO]

Bitwise shift IntExpr1 by IntExpr2 bits to the right. The operation performs arithmetic shift,
which implies that the inserted most significant bits are copies of the original most significant
bits.

+IntExpr1 << +IntExpr2 [ISO]

Bitwise shift IntExpr1 by IntExpr2 bits to the left.

+IntExpr1 \/ +IntExpr2 [ISO]

Bitwise or IntExpr1 and IntExpr2.

+IntExpr1 /\ +IntExpr2 [ISO]

Bitwise and IntExpr1 and IntExpr2.

+IntExpr1 xor +IntExpr2 [ISO]

Bitwise exclusive or IntExpr1 and IntExpr2.

\ +IntExpr [ISO]
Bitwise negation. The returned value is the ones complement of IntExpr.

sqrt(+Expr) [ISO]

Result = Expr

sin(+Expr) [ISO]
Result = sin Expr. Expr is the angle in radians.

cos(+Expr) [ISO]
Result = cos Expr. Expr is the angle in radians.

tan(+Expr) [ISO]
Result = tan Expr. Expr is the angle in radians.

asin(+Expr) [ISO]
Result = arcsin Expr. Result is the angle in radians.

acos(+Expr) [ISO]
Result = arccos Expr. Result is the angle in radians.

atan(+Expr) [ISO]
Result = arctan Expr. Result is the angle in radians.

SWI-Prolog 7.4 Reference Manual

4.27. ARITHMETIC 183

atan2(+YExpr, +XExpr) [ISO]

YExpr
Result = arctan XExpr . Result is the angle in radians. The return value is in the range
[ . . . ]. Used to convert between rectangular and polar coordinate system.
Note that the ISO Prolog standard demands atan2(0.0,0.0) to raise an evaluation error,
whereas the C99 and POSIX standards demand this to evaluate to 0.0. SWI-Prolog follows
C99 and POSIX.
atan(+YExpr, +XExpr)
Same as atan2/2 (backward compatibility).
sinh(+Expr)
eX eX
Result = sinh Expr. The hyperbolic sine of X is defined as 2 .
cosh(+Expr)
eX +eX
Result = cosh Expr. The hyperbolic cosine of X is defined as 2 .
tanh(+Expr)
sinh X
Result = tanh Expr. The hyperbolic tangent of X is defined as cosh X .

asinh(+Expr)
Result = arcsinh(Expr) (inverse hyperbolic sine).
acosh(+Expr)
Result = arccosh(Expr) (inverse hyperbolic cosine).
atanh(+Expr)
Result = arctanh(Expr). (inverse hyperbolic tangent).
log(+Expr) [ISO]
Natural logarithm. Result = ln Expr
log10(+Expr)
Base-10 logarithm. Result = lg Expr
exp(+Expr) [ISO]
Result = eExpr
+Expr1 ** +Expr2 [ISO]
Result = Expr1 Expr2 . The result is a float, unless SWI-Prolog is compiled with unbounded in-
teger support and the inputs are integers and produce an integer result. The integer expressions
0I , 1I and 1I are guaranteed to work for any integer I. Other integer base values generate a
resource error if the result does not fit in memory.
The ISO standard demands a float result for all inputs and introduces /2 for integer expo-
nentiation. The function float/1 can be used on one or both arguments to force a floating
point result. Note that casting the input result in a floating point computation, while casting the
output performs integer exponentiation followed by a conversion to float.
+Expr1 +Expr2 [ISO]
In SWI-Prolog, /2 is equivalent to **/2. The ISO version is similar, except that it produces
a evaluation error if both Expr1 and Expr2 are integers and the result is not an integer. The
table below illustrates the behaviour of the exponentiation functions in ISO and SWI.

SWI-Prolog 7.4 Reference Manual

184 CHAPTER 4. BUILT-IN PREDICATES

Expr1 Expr2 Function SWI ISO

Int Int **/2 Int or Float Float
Int Float **/2 Float Float
Float Int **/2 Float Float
Float Float **/2 Float Float
Int Int /2 Int or Float Int or error
Int Float /2 Float Float
Float Int /2 Float Float
Float Float /2 Float Float

powm(+IntExprBase, +IntExprExp, +IntExprMod)

Result = (IntExprBaseIntExprExp ) modulo IntExprMod. Only available when compiled with
unbounded integer support. This formula is required for Diffie-Hellman key-exchange, a
technique where two parties can establish a secret key over a public network. IntExprBase and
IntExprExp must be non-negative (>= 0), IntExprMod must be positive (> 0).79

lgamma(+Expr)
Return the natural logarithm of the absolute value of the Gamma function.80

erf(+Expr)
WikipediA: In mathematics, the error function (also called the Gauss error function) is a
special function (non-elementary) of sigmoid shape which occurs in probability, statistics and
partial differential equations.

erfc(+Expr)
WikipediA: The complementary error function.

pi [ISO]
Evaluate to the mathematical constant (3.14159. . . ).

e
Evaluate to the mathematical constant e (2.71828. . . ).

epsilon
Evaluate to the difference between the float 1.0 and the first larger floating point number.

inf
Evaluate to positive infinity. See section 2.15.1. This value can be negated using -/1.

nan
Evaluate to Not a Number. See section 2.15.1.

cputime
Evaluate to a floating point number expressing the CPU time (in seconds) used by Prolog up till
now. See also statistics/2 and time/1.
79
The underlying GMP mpz powm() function allows negative values under some conditions. As the conditions are
expensive to pre-compute, error handling from GMP is non-trivial and negative values are not needed for Diffie-Hellman
key-exchange we do not support these.
80
Some interfaces also provide the sign of the Gamma function. We canot do that in an arithmetic function. Future
versions may provide a predicate lgamma/3 that returns both the value and the sign.

SWI-Prolog 7.4 Reference Manual

4.28. MISC ARITHMETIC SUPPORT PREDICATES 185

eval(+Expr)
Evaluate Expr. Although ISO standard dictates that A=1+2, B is A works and unifies B to 3,
it is widely felt that source level variables in arithmetic expressions should have been limited
to numbers. In this view the eval function can be used to evaluate arbitrary expressions.81

Bitvector functions The functions below are not covered by the standard. The msb/1 function
also appears in hProlog and SICStus Prolog. The getbit/2 function also appears in ECLiPSe,
which also provides setbit(Vector,Index) and clrbit(Vector,Index). The others are SWI-Prolog
extensions that improve handling of unbounded integers as bit-vectors.

msb(+IntExpr)
Return the largest integer N such that (IntExpr >> N) /\ 1 =:= 1. This is the (zero-
origin) index of the most significant 1 bit in the value of IntExpr, which must evaluate to a
positive integer. Errors for 0, negative integers, and non-integers.

lsb(+IntExpr)
Return the smallest integer N such that (IntExpr >> N) /\ 1 =:= 1. This is the
(zero-origin) index of the least significant 1 bit in the value of IntExpr, which must evaluate to
a positive integer. Errors for 0, negative integers, and non-integers.

popcount(+IntExpr)
Return the number of 1s in the binary representation of the non-negative integer IntExpr.

getbit(+IntExprV, +IntExprI)
Evaluates to the bit value (0 or 1) of the IntExprI-th bit of IntExprV. Both arguments must eval-
uate to non-negative integers. The result is equivalent to (IntExprV >> IntExprI)/\1,
but more efficient because materialization of the shifted value is avoided. Future versions
will optimise (IntExprV >> IntExprI)/\1 to a call to getbit/2, providing both
portability and performance.82

4.28 Misc arithmetic support predicates

set random(+Option)
Controls the random number generator accessible through the functions random/1 and
random float/0. Note that the library random provides an alternative API to the same
random primitives.

seed(+Seed)
Set the seed of the random generator for this thread. Seed is an integer or the atom
random. If random, repeat the initialization procedure described with the function
random/1. Here is an example:
?- set_random(seed(111)), A is random(6).
A = 5.
81
The eval/1 function was first introduced by ECLiPSe and is under consideration for YAP.
82
This issue was fiercely debated at the ISO standard mailinglist. The name getbit was selected for compatibility with
ECLiPSe, the only system providing this support. Richard OKeefe disliked the name and argued that efficient handling of
the above implementation is the best choice for this functionality.

SWI-Prolog 7.4 Reference Manual

186 CHAPTER 4. BUILT-IN PREDICATES

?- set_random(seed(111)), A is random(6).
A = 5.

state(+State)
Set the generator to a state fetched using the state property of random property/1.
Using other values may lead to undefined behaviour.83

random property(?Option)
True when Option is a current property of the random generator. Currently, this predicate
provides access to the state. This predicate is not present on systems where the state is
inaccessible.

state(-State)
Describes the current state of the random generator. State is a normal Prolog term that can
be asserted or written to a file. Applications should make no other assumptions about its
representation. The only meaningful operation is to use as argument to set random/1
using the state(State) option.84

current arithmetic function(?Head)

True when Head is an evaluable function. For example:

?- current_arithmetic_function(sin(_)).
true.

4.29 Built-in list operations

Most list operations are defined in the library lists described in section A.15. Some that are imple-
mented with more low-level primitives are built-in and described here.

is list(+Term)
True if Term is bound to the empty list ([]) or a term with functor [|]85 and arity 2 and
the second argument is a list.86 This predicate acts as if defined by the definition below on
acyclic terms. The implementation fails safely if Term represents a cyclic list.

is_list(X) :-
var(X), !,
fail.
is_list([]).
83
The limitations of the underlying (GMP) library are unknown, which makes it impossible to validate the State.
84
BUG: GMP provides no portable mechanism to fetch and restore the state. The current implementation works, but the
state depends on the platform. I.e., it is generally not possible to reuse the state with another version of GMP or on a CPU
with different datasizes or endian-ness.
85
The traditional list functor is the dot (.). This is still the case of the command line option --traditional is
given. See also section 5.1.
86
In versions before 5.0.1, is list/1 just checked for [] or [ | ] and proper list/1 had the role of the current
is list/1. The current definition conforms to the de facto standard. Assuming proper coding standards, there should
only be very few cases where a quick-and-dirty is list/1 is a good choice. Richard OKeefe pointed at this issue.

SWI-Prolog 7.4 Reference Manual

4.29. BUILT-IN LIST OPERATIONS 187

is_list([_|T]) :-
is_list(T).

memberchk(?Elem, +List) [semidet]

True when Elem is an element of List. This chk variant of member/2 is semi deterministic
and typically used to test membership of a list. Raises a type error if scanning List encounters
a non-list. Note that memberchk/2 does not perform a full list typecheck. For example,
memberchk(a, [a|b]) succeeds without error. If List is cyclic and Elem is not a member
of List, memberchk/2 eventually raises a type error.87

length(?List, ?Int) [ISO]

True if Int represents the number of elements in List. This predicate is a true relation and
can be used to find the length of a list or produce a list (holding variables) of length Int. The
predicate is non-deterministic, producing lists of increasing length if List is a partial list and
Int is unbound. It raises errors if

Int is bound to a non-integer.

Int is a negative integer.
List is neither a list nor a partial list. This error condition includes cyclic lists.88

This predicate fails if the tail of List is equivalent to Int (e.g., length(L,L)).89

sort(+List, -Sorted) [ISO]

True if Sorted can be unified with a list holding the elements of List, sorted to the standard
order of terms (see section 4.7). Duplicates are removed. The implementation is in C, using
natural merge sort.90 The sort/2 predicate can sort a cyclic list, returning a non-cyclic
version with the same elements.

sort(+Key, +Order, +List, -Sorted)

True when Sorted can be unified with a list holding the element of List. Key determines which
part of each element in List is used for comparing two term and Order describes the relation
between each set of consecutive elements in Sorted.91
If Key is the integer zero (0), the entire term is used to compare two elements. Using Key=0 can
be used to sort arbitrary Prolog terms. Other values for Key can only be used with compound
terms or dicts (see section 5.4). An integer key extracts the Key-th argument from a compound
term. An integer or atom key extracts the value from a dict that is associated with the given key.
A type error is raised if the list element is of the wrong type and an existence error is raised if
the compound has not enough argument or the dict does not contain the requested key.
87
Eventually here means it will scan as many elements as the longest list that may exist given the current stack usage
before raising the exception.
88
ISO demands failure here. We think an error is more appropriate.
89
This is logically correct. An exception would be more appropriate, but to our best knowledge, current practice in Prolog
does not describe a suitable candidate exception term.
90
Contributed by Richard OKeefe.
91
The definition of this predicate was established after discussion with Joachim Schimpf from the ECLiPSe team.
ECLiPSe currently only accepts <, =<, > and >= for the Order argument but this is likely to change. SWI-Prolog ex-
tends this predicate to deal with dicts.

SWI-Prolog 7.4 Reference Manual

188 CHAPTER 4. BUILT-IN PREDICATES

Deeper nested elements of structures can be selected by using a list of keys for the Key argument.
The Order argument is described in the table below92

Order Ordering Duplicate handling

@< ascending remove
@=< ascending keep
@> descending remove
@>= descending keep

The sort is stable, which implies that, if duplicates are kept, the order of duplicates is not
changed. If duplicates are removed, only the first element of a sequence of duplicates appears
in Sorted.
This predicate supersedes most of the other sorting primitives, for example:

sort(List, Sorted) :- sort(0, @<, List, Sorted).

msort(List, Sorted) :- sort(0, @=<, List, Sorted).
keysort(Pairs, Sorted) :- sort(1, @=<, Pairs, Sorted).

The following example sorts a list of rows, for example resulting from csv read file/2)
ascending on the 3th column and descending on the 4th column:

sort(4, @>=, Rows0, Rows1),

sort(3, @=<, Rows1, Sorted).

See also sort/2 (ISO), msort/2, keysort/2, predsort/3 and order by/2.
msort(+List, -Sorted)
Equivalent to sort/2, but does not remove duplicates. Raises a type error if List is a
cyclic list or not a list.
keysort(+List, -Sorted) [ISO]
Sort a list of pairs. List must be a list of Key-Value pairs, terms whose principal functor is (-)/2.
List is sorted on Key according to the standard order of terms (see section 4.7.1). Duplicates are
not removed. Sorting is stable with regard to the order of the Values, i.e., the order of multiple
elements that have the same Key is not changed.
The keysort/2 predicate is often used together with library pairs. It can be used to sort
lists on different or multiple criteria. For example, the following predicates sorts a list of atoms
according to their length, maintaining the initial order for atoms that have the same length.

:- use_module(library(pairs)).

sort_atoms_by_length(Atoms, ByLength) :-
map_list_to_pairs(atom_length, Atoms, Pairs),
keysort(Pairs, Sorted),
pairs_values(Sorted, ByLength).
92
For compatibility with ECLiPSe, the values <, =<, > and >= are allowed as synonyms.

SWI-Prolog 7.4 Reference Manual

4.30. FINDING ALL SOLUTIONS TO A GOAL 189

predsort(+Pred, +List, -Sorted)

Sorts similar to sort/2, but determines the order of two terms by calling
Pred(-Delta, +E1, +E2). This call must unify Delta with one of <, > or =. If the built-
in predicate compare/3 is used, the result is the same as sort/2. See also keysort/2.

4.30 Finding all Solutions to a Goal

findall(+Template, :Goal, -Bag) [ISO]
Create a list of the instantiations Template gets successively on backtracking over Goal and
unify the result with Bag. Succeeds with an empty list if Goal has no solutions. findall/3
is equivalent to bagof/3 with all free variables bound with the existential operator (), except
that bagof/3 fails when Goal has no solutions.

findall(+Template, :Goal, -Bag, +Tail)

As findall/3, but returns the result as the difference list Bag-Tail. The 3-argument version
is defined as

findall(Templ, Goal, Bag) :-

findall(Templ, Goal, Bag, [])

findnsols(+N, @Template, :Goal, -List) [nondet]

findnsols(+N, @Template, :Goal, -List, ?Tail) [nondet]
As findall/3 and findall/4, but generates at most N solutions. If N solutions are
returned, this predicate succeeds with a choice point if Goal has a choice point. Backtracking
returns the next chunk of (at most) N solutions. In addition to passing a plain integer for N,
a term of the form count(N) is accepted. Using count(N), the size of the next chunk can
be controlled using nb setarg/3. The non-deterministic behaviour used to implement the
chunk option in pengines. Based on Ciao, but the Ciao version is deterministic. Portability
can be achieved by wrapping the goal in once/1. Below are three examples. The first
illustrates standard chunking of answers. The second illustrates that the chunk size can be
adjusted dynamically and the last illustrates that no choice point is left if Goal leaves no
choice-point after the last solution.

?- findnsols(5, I, between(1, 12, I), L).

L = [1, 2, 3, 4, 5] ;
L = [6, 7, 8, 9, 10] ;
L = [11, 12].

?- State = count(2),
findnsols(State, I, between(1, 12, I), L),
nb_setarg(1, State, 5).
State = count(5), L = [1, 2] ;
State = count(5), L = [3, 4, 5, 6, 7] ;
State = count(5), L = [8, 9, 10, 11, 12].

SWI-Prolog 7.4 Reference Manual

190 CHAPTER 4. BUILT-IN PREDICATES

?- findnsols(4, I, between(1, 4, I), L).

L = [1, 2, 3, 4].

bagof(+Template, :Goal, -Bag) [ISO]

Unify Bag with the alternatives of Template. If Goal has free variables besides the one sharing
with Template, bagof/3 will backtrack over the alternatives of these free variables, unifying
Bag with the corresponding alternatives of Template. The construct +VarGoal tells bagof/3
not to bind Var in Goal. bagof/3 fails if Goal has no solutions.
The example below illustrates bagof/3 and the operator. The variable bindings are printed
together on one line to save paper.

2 ?- listing(foo).
foo(a, b, c).
foo(a, b, d).
foo(b, c, e).
foo(b, c, f).
foo(c, c, g).
true.

3 ?- bagof(C, foo(A, B, C), Cs).

A = a, B = b, C = G308, Cs = [c, d] ;
A = b, B = c, C = G308, Cs = [e, f] ;
A = c, B = c, C = G308, Cs = [g].

4 ?- bagof(C, Afoo(A, B, C), Cs).

A = G324, B = b, C = G326, Cs = [c, d] ;
A = G324, B = c, C = G326, Cs = [e, f, g].

5 ?-

setof(+Template, +Goal, -Set) [ISO]

Equivalent to bagof/3, but sorts the result using sort/2 to get a sorted list of alternatives
without duplicates.

4.31 Forall
forall(:Cond, :Action) [semidet]
For all alternative bindings of Cond, Action can be proven. The example verifies that all arith-
metic statements in the given list are correct. It does not say which is wrong if one proves
wrong.

?- forall(member(Result = Formula, [2 = 1 + 1, 4 = 2 * 2]),

Result =:= Formula).

SWI-Prolog 7.4 Reference Manual

4.32. FORMATTED WRITE 191

The predicate forall/2 is implemented as \+ ( Cond, \+ Action), i.e., There is

no instantiation of Cond for which Action is false.. The use of double negation implies that
forall/2 does not change any variable bindings. It proves a relation. The forall/2 con-
trol structure can be used for its side-effects. E.g., the following asserts relations in a list into
the dynamic database:

?- forall(member(Child-Parent, ChildPairs),
assertz(child_of(Child, Parent))).

Using forall/2 as forall(Generator, SideEffect) is preferred over the classical failure

driven loop as shown below because it makes it explicit which part of the construct is the
generator and which part creates the side effects. Also, unexpected failure of the side effect
causes the construct to fail. Failure makes it evident that there is an issue with the code, while
a failure driven loop would succeed with an erroneous result.

...,
( Generator,
SideEffect,
fail
; true
)

If your intent is to create variable bindings, the forall/2 control structure is inadequate.
Possibly you are looking for maplist/2, findall/3 or foreach/2.

4.32 Formatted Write

The current version of SWI-Prolog provides two formatted write predicates. The writef family
(writef/1, writef/2, swritef/3), is compatible with Edinburgh C-Prolog and should be con-
sidered deprecated. The format family (format/1, format/2, format/3), was defined by
Quintus Prolog and currently available in many Prolog systems, although the details vary.

4.32.1 Writef
writef(+Atom) [deprecated]
Equivalent to writef(Atom, []). See writef/2 for details.

writef(+Format, +Arguments) [deprecated]

Formatted write. Format is an atom whose characters will be printed. Format may contain
certain special character sequences which specify certain formatting and substitution actions.
Arguments provides all the terms required to be output.
Escape sequences to generate a single special character:

SWI-Prolog 7.4 Reference Manual

192 CHAPTER 4. BUILT-IN PREDICATES

\n Output a newline character (see also nl/[0,1])

\l Output a line separator (same as \n)
\r Output a carriage return character (ASCII 13)
\t Output the ASCII character TAB (9)
\\ The character \ is output
\% The character % is output
\nnn where hnnni is an integer (1-3 digits); the character with
code hnnni is output (NB : hnnni is read as decimal)

Note that \l, \nnn and \\ are interpreted differently when character escapes are in effect. See
section 2.15.1.
Escape sequences to include arguments from Arguments. Each time a % escape sequence is
found in Format the next argument from Arguments is formatted according to the specification.

%t
print/1 the next item (mnemonic: term)
%w
write/1 the next item
%q
writeq/1 the next item
%d Write the term, ignoring operators. See also
write term/2. Mnemonic: old Edinburgh
display/1
%p
print/1 the next item (identical to %t)
%n Put the next item as a character (i.e., it is a character code)
%r Write the next item N times where N is the second item
(an integer)
%s Write the next item as a String (so it must be a list of char-
acters)
%f Perform a ttyflush/0 (no items used)
%Nc Write the next item Centered in N columns
%Nl Write the next item Left justified in N columns
%Nr Write the next item Right justified in N columns. N is a
decimal number with at least one digit. The item must be
an atom, integer, float or string.

swritef(-String, +Format, +Arguments) [deprecated]

Equivalent to writef/2, but writes the result on String instead of the current output stream.
Example:

?- swritef(S, %15L%w, [Hello, World]).

S = "Hello World"

swritef(-String, +Format) [deprecated]

Equivalent to swritef(String, Format, []).

SWI-Prolog 7.4 Reference Manual

4.32. FORMATTED WRITE 193

4.32.2 Format
The format family of predicates is the most versatile and portable93 way to produce textual output.

format(+Format)
Defined as format(Format) :- format(Format, []).. See format/2 for de-
tails.

format(+Format, :Arguments)
Format is an atom, list of character codes, or a Prolog string. Arguments provides the arguments
required by the format specification. If only one argument is required and this single argument
is not a list, the argument need not be put in a list. Otherwise the arguments are put in a list.
Special sequences start with the tilde (), followed by an optional numeric argument, option-
ally followed by a colon modifier (:), 94 followed by a character describing the action to be
undertaken. A numeric argument is either a sequence of digits, representing a positive decimal
number, a sequence hcharacteri, representing the character code value of the character (only
useful for t) or a asterisk (*), in which case the numeric argument is taken from the next argu-
ment of the argument list, which should be a positive integer. E.g., the following three examples
all pass 46 (.) to t:

?- format(w 46t w72|n, [Title, Page]).

?- format(w .t w72|n, [Title, Page]).
?- format(w *t w72|n, [Title, 46, Page]).

Numeric conversion (d, D, e, E, f, g and G) accept an arithmetic expression as argument. This

is introduced to handle rational numbers transparently (see section 4.27.2). The floating point
conversions allow for unlimited precision for printing rational numbers in decimal form. E.g.,
the following will write as many 3s as you want by changing the 50.

?- format(50f, [10 rdiv 3]).

3.33333333333333333333333333333333333333333333333333

Output the tilde itself.

a Output the next argument, which must be an atom. This option is equivalent to w, except
that it requires the argument to be an atom.
c Interpret the next argument as a character code and add it to the output. This argument
must be a valid Unicode character code. Note that the actually emitted bytes are defined by
the character encoding of the output stream and an exception may be raised if the output
stream is not capable of representing the requested Unicode character. See section 2.18.1
for details.
d Output next argument as a decimal number. It should be an integer. If a numeric argument
is specified, a dot is inserted argument positions from the right (useful for doing fixed
point arithmetic with integers, such as handling amounts of money).
93
Unfortunately not covered by any standard.
94
The colon modifiers is a SWI-Prolog extension, proposed by Richard OKeefe.

SWI-Prolog 7.4 Reference Manual

194 CHAPTER 4. BUILT-IN PREDICATES

The colon modifier (e.g., :d) causes the number to be printed according to the locale of
the output stream. See section 4.23.
D Same as d, but makes large values easier to read by inserting a comma every three digits
left or right of the dot. This is the same as :d, but using the fixed English locale.
e Output next argument as a floating point number in exponential notation. The numeric
argument specifies the precision. Default is 6 digits. Exact representation depends on the
C library function printf(). This function is invoked with the format %.hprecisionie.
E Equivalent to e, but outputs a capital E to indicate the exponent.
f Floating point in non-exponential notation. The numeric argument defines the number of
digits right of the decimal point. If the colon modifier (:) is used, the float is formatted
using conventions from the current locale, which may define the decimal point as well as
grouping of digits left of the decimal point.
g Floating point in e or f notation, whichever is shorter.
G Floating point in E or f notation, whichever is shorter.
i Ignore next argument of the argument list. Produces no output.
I Emit a decimal number using Prolog digit grouping (the underscore, _). The argument
describes the size of each digit group. The default is 3. See also section 2.15.1. For
example:
?- A is 1<<100, format(10I, [A]).
1_2676506002_2822940149_6703205376

k Give the next argument to write canonical/1.

n Output a newline character.
N Only output a newline if the last character output on this stream was not a newline. Not
properly implemented yet.
p Give the next argument to print/1.
q Give the next argument to writeq/1.
r Print integer in radix numeric argument notation. Thus 16r prints its argument hex-
adecimal. The argument should be in the range [2, . . . , 36]. Lowercase letters are used for
digits above 9. The colon modifier may be used to form locale-specific digit groups.
R Same as r, but uses uppercase letters for digits above 9.
s Output text from a list of character codes or a string (see string/1 and section 5.2)
from the next argument.95
@ Interpret the next argument as a goal and execute it. Output written to the
current output stream is inserted at this place. Goal is called in the module calling
format/3. This option is not present in the original definition by Quintus, but supported
by some other Prolog systems.
t All remaining space between 2 tab stops is distributed equally over t statements between
the tab stops. This space is padded with spaces by default. If an argument is supplied, it
is taken to be the character code of the character used for padding. This can be used to do
left or right alignment, centering, distributing, etc. See also | and + to set tab stops. A
tab stop is assumed at the start of each line.
95
The s modifier also accepts an atom for compatibility. This is deprecated due to the ambiguity of [].

SWI-Prolog 7.4 Reference Manual

4.32. FORMATTED WRITE 195

| Set a tab stop on the current position. If an argument is supplied set a tab stop on the
position of that argument. This will cause all ts to be distributed between the previous
and this tab stop.
+ Set a tab stop (as |) relative to the last tab stop or the beginning of the line if no tab
stops are set before the +. This constructs can be used to fill fields. The partial format
sequence below prints an integer right-aligned and padded with zeros in 6 columns. The
. . . sequences in the example illustrate that the integer is aligned in 6 columns regardless
of the remainder of the format specification.
format(...|0td6+..., [..., Integer, ...])

w Give the next argument to write/1.

W Give the next two arguments to write term/2. For example,
format(W, [Term, [numbervars(true)]]). This option is SWI-Prolog
specific.

Example:

simple_statistics :-
<obtain statistics> % left to the user
format(tStatisticst72|nn),
format(Runtime: .t 2f34| Inferences: .t D72|n,
[RunT, Inf]),
....

will output

Statistics

Runtime: .................. 3.45 Inferences: .......... 60,345

format(+Output, +Format, :Arguments)

As format/2, but write the output on the given Output. The de-facto standard only allows
Output to be a stream. The SWI-Prolog implementation allows all valid arguments for
with output to/2.96 For example:

?- format(atom(A), D, [1000000]).
A = 1,000,000

4.32.3 Programming Format

format predicate(+Char, +Head)
If a sequence c (tilde, followed by some character) is found, the format/3 and friends
first check whether the user has defined a predicate to handle the format. If not, the built-in
96
Earlier versions defined sformat/3. These predicates have been moved to the library backcomp.

SWI-Prolog 7.4 Reference Manual

196 CHAPTER 4. BUILT-IN PREDICATES

formatting rules described above are used. Char is either a character code or a one-character
atom, specifying the letter to be (re)defined. Head is a term, whose name and arity are used
to determine the predicate to call for the redefined formatting character. The first argument
to the predicate is the numeric argument of the format command, or the atom default if
no argument is specified. The remaining arguments are filled from the argument list. The
example below defines T to print a timestamp in ISO8601 format (see format time/3).
The subsequent block illustrates a possible call.

:- format_predicate(T, format_time(_Arg,_Time)).

format_time(_Arg, Stamp) :-
must_be(number, Stamp),
format_time(current_output, %FT%T%z, Stamp).

?- get_time(Now),
format(Now, it is Tn, [Now]).
Now, it is 2012-06-04T19:02:01+0200
Now = 1338829321.6620328.

current format predicate(?Code, ?:Head)

True when Code is handled by the user-defined predicate specified by Head.

4.33 Global variables

Global variables are associations between names (atoms) and terms. They differ in various ways from
storing information using assert/1 or recorda/3.

The value lives on the Prolog (global) stack. This implies that lookup time is independent of the
size of the term. This is particularly interesting for large data structures such as parsed XML
documents or the CHR global constraint store.

They support both global assignment using nb setval/2 and backtrackable assignment using
b setval/2.

Only one value (which can be an arbitrary complex Prolog term) can be associated to a variable
at a time.

Their value cannot be shared among threads. Each thread has its own namespace and values for
global variables.

Currently global variables are scoped globally. We may consider module scoping in future
versions.

Both b setval/2 and nb setval/2 implicitly create a variable if the referenced name does
not already refer to a variable.
Global variables may be initialised from directives to make them available during the program
lifetime, but some considerations are necessary for saved states and threads. Saved states do not store

SWI-Prolog 7.4 Reference Manual

4.33. GLOBAL VARIABLES 197

global variables, which implies they have to be declared with initialization/1 to recreate them
after loading the saved state. Each thread has its own set of global variables, starting with an empty
set. Using thread initialization/1 to define a global variable it will be defined, restored
after reloading a saved state and created in all threads that are created after the registration. Finally,
global variables can be initialised using the exception hook exception/3. The latter technique is
used by CHR (see chapter 8).

b setval(+Name, +Value)
Associate the term Value with the atom Name or replace the currently associated value with
Value. If Name does not refer to an existing global variable, a variable with initial value [] is
created (the empty list). On backtracking the assignment is reversed.

b getval(+Name, -Value)
Get the value associated with the global variable Name and unify it with Value. Note that this
unification may further instantiate the value of the global variable. If this is undesirable the
normal precautions (double negation or copy term/2) must be taken. The b getval/2
predicate generates errors if Name is not an atom or the requested variable does not exist.

nb setval(+Name, +Value)
Associates a copy of Value created with duplicate term/2 with the atom Name. Note that
this can be used to set an initial value other than [] prior to backtrackable assignment.

nb getval(+Name, -Value)
The nb getval/2 predicate is a synonym for b getval/2, introduced for compatibility
and symmetry. As most scenarios will use a particular global variable using either non-
backtrackable or backtrackable assignment, using nb getval/2 can be used to document
that the variable is non-backtrackable. Raises existence error(variable, Name) if the
variable does not exist. Alternatively, nb current/2 can used to query a global variable.
This version fails if the variable does not exist rather than raising an exception.

nb linkval(+Name, +Value)
Associates the term Value with the atom Name without copying it. This is a fast special-
purpose variation of nb setval/2 intended for expert users only because the semantics on
backtracking to a point before creating the link are poorly defined for compound terms. The
principal term is always left untouched, but backtracking behaviour on arguments is undone if
the original assignment was trailed and left alone otherwise, which implies that the history that
created the term affects the behaviour on backtracking. Consider the following example:

demo_nb_linkval :-
T = nice(N),
( N = world,
nb_linkval(myvar, T),
fail
; nb_getval(myvar, V),
writeln(V)
).

SWI-Prolog 7.4 Reference Manual

198 CHAPTER 4. BUILT-IN PREDICATES

nb current(?Name, ?Value)
Enumerate all defined variables with their value. The order of enumeration is undefined. Note
that nb current/2 can be used as an alternative for nb getval/2 to request the value of
a variable and fail silently if the variable does not exists.

nb delete(+Name)
Delete the named global variable. Succeeds also if the named variable does not exist.

4.33.1 Compatibility of SWI-Prolog Global Variables

Global variables have been introduced by various Prolog implementations recently. The implemen-
tation of them in SWI-Prolog is based on hProlog by Bart Demoen. In discussion with Bart it was
decided that the semantics of hProlog nb setval/2, which is equivalent to nb linkval/2, is
not acceptable for normal Prolog users as the behaviour is influenced by how built-in predicates that
construct terms (read/1, =../2, etc.) are implemented.
GNU-Prolog provides a rich set of global variables, including arrays. Arrays can be implemented
easily in SWI-Prolog using functor/3 and setarg/3 due to the unrestricted arity of compound
terms.

4.34 Terminal Control

The following predicates form a simple access mechanism to the Unix termcap library to provide
terminal-independent I/O for screen terminals. These predicates are only available on Unix machines.
The SWI-Prolog Windows console accepts the ANSI escape sequences.

tty get capability(+Name, +Type, -Result)

Get the capability named Name from the termcap library. See termcap(5) for the capability
names. Type specifies the type of the expected result, and is one of string, number or
bool. String results are returned as an atom, number results as an integer, and bool results as
the atom on or off. If an option cannot be found, this predicate fails silently. The results are
only computed once. Successive queries on the same capability are fast.

tty goto(+X, +Y)

Goto position (X, Y) on the screen. Note that the predicates line count/2 and
line position/2 will not have a well-defined behaviour while using this predicate.

tty put(+Atom, +Lines)

Put an atom via the termcap library function tputs(). This function decodes padding information
in the strings returned by tty get capability/3 and should be used to output these
strings. Lines is the number of lines affected by the operation, or 1 if not applicable (as in
almost all cases).

tty size(-Rows, -Columns)

Determine the size of the terminal. Platforms:

Unix If the system provides ioctl calls for this, these are used and tty size/2 properly
reflects the actual size after a user resize of the window. The ioctl is issued on teh
file descriptor associated with the user input stream. As a fallback, the system uses

SWI-Prolog 7.4 Reference Manual

4.35. OPERATING SYSTEM INTERACTION 199

tty get capability/3 using li and co capabilities. In this case the reported size
reflects the size at the first call and is not updated after a user-initiated resize of the termi-
nal.
Windows Getting the size of the terminal is provided for swipl-win.exe. The requested
value reflects the current size. For the multithreaded version the console that is associated
with the user input stream is used.

4.35 Operating System Interaction

shell(+Command)
Equivalent to shell(Command, 0). See shell/2 for details.

shell(+Command, -Status)
Execute Command on the operating system. Command is given to the Bourne shell (/bin/sh).
Status is unified with the exit status of the command.
On Windows, shell/[1,2] executes the command using the CreateProcess() API and waits
for the command to terminate. If the command ends with a & sign, the command is handed to
the WinExec() API, which does not wait for the new task to terminate. See also win exec/2
and win shell/2. Please note that the CreateProcess() API does not imply the Windows
command interpreter (cmd.exe and therefore commands that are built in the command inter-
preter can only be activated using the command interpreter. For example, a file can be compied
using the command below.

?- shell(cmd.exe /C copy file1.txt file2.txt).

Note that many of the operations that can be achieved using the shell built-in commands can
easily be achieved using Prolog primitives. See make directory/1, delete file/1,
rename file/2, etc. The clib package provides filesex, implementing various high level
file operations such as copy file/2. Using Prolog primitives instead of shell commands
improves the portability of your program.
The library process provides process create/3 and several related primitives that sup-
port more fine-grained interaction with processes, including I/O redirection and management of
asynchronous processes.

getenv(+Name, -Value)
Get environment variable. Fails silently if the variable does not exist. Please note that environ-
ment variable names are case-sensitive on Unix systems and case-insensitive on Windows.

setenv(+Name, +Value)
Set an environment variable. Name and Value must be instantiated to atoms or integers. The en-
vironment variable will be passed to shell/[0-2] and can be requested using getenv/2.
They also influence expand file name/2. Environment variables are shared between
threads. Depending on the underlying C library, setenv/2 and unsetenv/1 may not be
thread-safe and may cause memory leaks. Only changing the environment once and before
starting threads is safe in all versions of SWI-Prolog.

SWI-Prolog 7.4 Reference Manual

200 CHAPTER 4. BUILT-IN PREDICATES

unsetenv(+Name)
Remove an environment variable from the environment. Some systems lack the underlying
unsetenv() library function. On these systems unsetenv/1 sets the variable to the empty
string.

setlocale(+Category, -Old, +New)

Set/Query the locale setting which tells the C library how to interpret text files, write num-
bers, dates, etc. Category is one of all, collate, ctype, messages, monetary,
numeric or time. For details, please consult the C library locale documentation. See also
section 2.18.1. Please note that the locale is shared between all threads and thread-safe usage
of setlocale/3 is in general not possible. Do locale operations before starting threads or
thoroughly study threading aspects of locale support in your environment before using in multi-
threaded environments. Locale settings are used by format time/3, collation key/2
and locale sort/2.

unix(+Command)
This predicate comes from the Quintus compatibility library and provides a partial imple-
mentation thereof. It provides access to some operating system features and unlike the name
suggests, is not operating system specific. Defined Commands are below.

system(+Command)
Equivalent to calling shell/1. Use for compatibility only.
shell(+Command)
Equivalent to calling shell/1. Use for compatibility only.
shell
Equivalent to calling shell/0. Use for compatibility only.
cd
Equivalent to calling working directory/2 to the expansion (see
expand file name/2) of . For compatibility only.
cd(+Directory)
Equivalent to calling working directory/2. Use for compatibility only.
argv(-Argv)
Unify Argv with the list of command line arguments provided to this Prolog run. Please
note that Prolog system arguments and application arguments are separated by --.
Integer arguments are passed as Prolog integers, float arguments and Prolog floating
point numbers and all other arguments as Prolog atoms. New applications should use the
Prolog flag argv. See also the Prolog flag argv.
A stand-alone program could use the following skeleton to handle command line argu-
ments. See also section 2.10.2.
main :-
current_prolog_flag(argv, Argv),
append(_PrologArgs, [--|AppArgs], Argv), !,
main(AppArgs).

SWI-Prolog 7.4 Reference Manual

4.35. OPERATING SYSTEM INTERACTION 201

4.35.1 Windows-specific Operating System Interaction

The predicates in this section are only available on the Windows version of SWI-Prolog. Their use
is discouraged if there are portably alternatives. For example, win exec/2 and win shell/2 can
often be replaced by the more portable shell/2 or the more powerful process create/3.

win exec(+Command, +Show)

Windows only. Spawns a Windows task without waiting for its completion. Show is one
of the Win32 SW * constants written in lowercase without the SW *: hide maximize
minimize restore show showdefault showmaximized showminimized
showminnoactive showna shownoactive shownormal. In addition, iconic is a
synonym for minimize and normal for shownormal.

win shell(+Operation, +File, +Show)

Windows only. Opens the document File using the Windows shell rules for doing so. Operation
is one of open, print or explore or another operation registered with the shell for the
given document type. On modern systems it is also possible to pass a URL as File, opening the
URL in Windows default browser. This call interfaces to the Win32 API ShellExecute(). The
Show argument determines the initial state of the opened window (if any). See win exec/2
for defined values.

win shell(+Operation, +File)

Same as win shell(Operation, File, normal)

win registry get value(+Key, +Name, -Value)

Windows only. Fetches the value of a Windows registry key. Key is an atom formed as a
path name describing the desired registry key. Name is the desired attribute name of the key.
Value is unified with the value. If the value is of type DWORD, the value is returned as an
integer. If the value is a string, it is returned as a Prolog atom. Other types are currently
not supported. The default root is HKEY CURRENT USER. Other roots can be specified
explicitly as HKEY CLASSES ROOT, HKEY CURRENT USER, HKEY LOCAL MACHINE
or HKEY USERS. The example below fetches the extension to use for Prolog files (see
README.TXT on the Windows version):

?- win_registry_get_value(
HKEY_LOCAL_MACHINE/Software/SWI/Prolog,
fileExtension,
Ext).

Ext = pl

win folder(?Name, -Directory)

True if Name is the Windows CSIDL of Directory. If Name is unbound, all known Windows
special paths are generated. Name is the CSIDL after deleting the leading CSIDL and
mapping the constant to lowercase. Check the Windows documentation for the function
SHGetSpecialFolderPath() for a description of the defined constants. This example extracts the
My Documents folder:

SWI-Prolog 7.4 Reference Manual

202 CHAPTER 4. BUILT-IN PREDICATES

?- win_folder(personal, MyDocuments).

MyDocuments = C:/Documents and Settings/jan/My Documents

win add dll directory(+AbsDir)

This predicate adds a directory to the search path for dependent DLL files. If possible, this
is achieved with win add dll directory/2. Otherwise, %PATH% is extended with
the provided directory. AbsDir may be specified in the Prolog canonical syntax. See
prolog to os filename/2. Note that use foreign library/1 passes an abso-
lute path to the DLL if the destination DLL can be located from the specification using
absolute file name/3.

win add dll directory(+AbsDir, -Cookie)

This predicate adds a directory to the search path for dependent DLL files. If the call is success-
ful it unifies Cookie with a handle that must be passed to win remove dll directory/1
to remove the directory from the search path. Error conditions:

This predicate is available in the Windows port of SWI-Prolog starting from 6.3.8/6.2.6.
This predicate fails if Windows does not yet support the underlying primitives. These are
available in recently patched Windows 7 systems and later.
This predicate throws an acception if the provided path is invalid or the underlying Win-
dows API returns an error.

If open shared object/2 is passed an absolute path to a DLL on a Win-

dows installation that supports AddDllDirectory() and friends,97 SWI-Prolog uses
LoadLibraryEx() with the flags LOAD LIBRARY SEARCH DLL LOAD DIR and
LOAD LIBRARY SEARCH DEFAULT DIRS. In this scenario, directories from %PATH%
and not searched. Additional directories can be added using win add dll directory/2.

win remove dll directory(-Cookie)

Remove a DLL search directory installed using win add dll directory/2.

4.35.2 Dealing with time and date

Representing time in a computer system is surprisingly complicated. There are a large number of
time representations in use, and the correct choice depends on factors such as compactness, resolution
and desired operations. Humans tend to think about time in hours, days, months, years or centuries.
Physicists think about time in seconds. But, a month does not have a defined number of seconds.
Even a day does not have a defined number of seconds as sometimes a leap-second is introduced to
synchronise properly with our earths rotation. At the same time, resolution demands a range from
better than pico-seconds to millions of years. Finally, civilizations have a wide range of calendars.
Although there exist libraries dealing with most if this complexity, our desire to keep Prolog clean and
lean stops us from fully supporting these.
97
Windows 7 with up-to-date patches or Windows 8.

SWI-Prolog 7.4 Reference Manual

4.35. OPERATING SYSTEM INTERACTION 203

For human-oriented tasks, time can be broken into years, months, days, hours, minutes, seconds
and a timezone. Physicists prefer to have time in an arithmetic type representing seconds or frac-
tion thereof, so basic arithmetic deals with comparison and durations. An additional advantage of
the physicists approach is that it requires much less space. For these reasons, SWI-Prolog uses an
arithmetic type as its prime time representation.
Many C libraries deal with time using fixed-point arithmetic, dealing with a large but finite time
interval at constant resolution. In our opinion, using a floating point number is a more natural choice
as we can use a natural unit and the interface does not need to be changed if a higher resolution is
required in the future. Our unit of choice is the second as it is the scientific unit.98 We have placed
our origin at 1970-1-1T0:0:0Z for compatibility with the POSIX notion of time as well as with older
time support provided by SWI-Prolog.
Where older versions of SWI-Prolog relied on the POSIX conversion functions, the current im-
plementation uses libtai to realise conversion between time-stamps and calendar dates for a period of
10 million years.

Time and date data structures

We use the following time representations

TimeStamp
A TimeStamp is a floating point number expressing the time in seconds since the Epoch at
1970-1-1.

date(Y,M,D,H,Mn,S,Off,TZ,DST)
We call this term a date-time structure. The first 5 fields are integers expressing the year,
month (1..12), day (1..31), hour (0..23) and minute (0..59). The S field holds the seconds as a
floating point number between 0.0 and 60.0. Off is an integer representing the offset relative to
UTC in seconds, where positive values are west of Greenwich. If converted from local time
(see stamp date time/3), TZ holds the name of the local timezone. If the timezone is not
known, TZ is the atom -. DST is true if daylight saving time applies to the current time,
false if daylight saving time is relevant but not effective, and - if unknown or the timezone
has no daylight saving time.

date(Y,M,D)
Date using the same values as described above. Extracted using date time value/3.

time(H,Mn,S)
Time using the same values as described above. Extracted using date time value/3.

Time and date predicates

get time(-TimeStamp)
Return the current time as a TimeStamp. The granularity is system-dependent. See sec-
tion 4.35.2.

stamp date time(+TimeStamp, -DateTime, +TimeZone)

Convert a TimeStamp to a DateTime in the given timezone. See section 4.35.2 for details on
98
Using Julian days is a choice made by the Eclipse team. As conversion to dates is needed for a human readable notation
of time and Julian days cannot deal naturally with leap seconds, we decided for the second as our unit.

SWI-Prolog 7.4 Reference Manual

204 CHAPTER 4. BUILT-IN PREDICATES

the data types. TimeZone describes the timezone for the conversion. It is one of local to
extract the local time, UTC to extract a UTC time or an integer describing the seconds west
of Greenwich.

date time stamp(+DateTime, -TimeStamp)

Compute the timestamp from a date/9 term. Values for month, day, hour, minute or second
need not be normalized. This flexibility allows for easy computation of the time at any given
number of these units from a given timestamp. Normalization can be achieved following this
call with stamp date time/3. This example computes the date 200 days after 2006-7-14:

?- date_time_stamp(date(2006,7,214,0,0,0,0,-,-), Stamp),
stamp_date_time(Stamp, D, 0),
date_time_value(date, D, Date).
Date = date(2007, 1, 30)

When computing a time stamp from a local time specification, the UTC offset (arg 7), TZ (arg 8)
and DST (arg 9) argument may be left unbound and are unified with the proper information.
The example below, executed in Amsterdam, illustrates this behaviour. On the 25th of March
at 01:00, DST does not apply. At 02.00, the clock is advanced by one hour and thus both 02:00
and 03:00 represent the same time stamp.

1 ?- date_time_stamp(date(2012,3,25,1,0,0,UTCOff,TZ,DST),
Stamp).
UTCOff = -3600,
TZ = CET,
DST = false,
Stamp = 1332633600.0.

2 ?- date_time_stamp(date(2012,3,25,2,0,0,UTCOff,TZ,DST),
Stamp).
UTCOff = -7200,
TZ = CEST,
DST = true,
Stamp = 1332637200.0.

3 ?- date_time_stamp(date(2012,3,25,3,0,0,UTCOff,TZ,DST),
Stamp).
UTCOff = -7200,
TZ = CEST,
DST = true,
Stamp = 1332637200.0.

Note that DST and offset calculation are based on the POSIX function mktime(). If mktime()
returns an error, a representation error dst is generated.

date time value(?Key, +DateTime, ?Value)

Extract values from a date/9 term. Provided keys are:

SWI-Prolog 7.4 Reference Manual

4.35. OPERATING SYSTEM INTERACTION 205

key value
year Calendar year as an integer
month Calendar month as an integer 1..12
day Calendar day as an integer 1..31
hour Clock hour as an integer 0..23
minute Clock minute as an integer 0..59
second Clock second as a float 0.0..60.0
utc offset Offset to UTC in seconds (positive is west)
time zone Name of timezone; fails if unknown
daylight saving Bool (true) if dst is in effect
date Term date(Y,M,D)
time Term time(H,M,S)

format time(+Out, +Format, +StampOrDateTime)

Modelled after POSIX strftime(), using GNU extensions. Out is a destination as specified
with with output to/2. Format is an atom or string with the following conversions.
Conversions start with a percent (%) character.99 StampOrDateTime is either a numeric
time-stamp, a term date(Y,M,D,H,M,S,O,TZ,DST) or a term date(Y,M,D).

a The abbreviated weekday name according to the current locale. Use format time/4
for POSIX locale.
A The full weekday name according to the current locale. Use format time/4 for POSIX
locale.
b The abbreviated month name according to the current locale. Use format time/4 for
POSIX locale.
B The full month name according to the current locale. Use format time/4 for POSIX
locale.
c The preferred date and time representation for the current locale.
C The century number (year/100) as a 2-digit integer.
d The day of the month as a decimal number (range 01 to 31).
D Equivalent to %m/%d/%y. (For Americans only. Americans should note that in other
countries %d/%m/%y is rather common. This means that in an international context this
format is ambiguous and should not be used.)
e Like %d, the day of the month as a decimal number, but a leading zero is replaced by a
space.
E Modifier. Not implemented.
f Number of microseconds. The f can be prefixed by an integer to print the desired number
of digits. E.g., %3f prints milliseconds. This format is not covered by any standard, but
available with different format specifiers in various incarnations of the strftime() function.
F Equivalent to %Y-%m-%d (the ISO 8601 date format).
g Like %G, but without century, i.e., with a 2-digit year (00-99).
99
Descriptions taken from Linux Programmers Manual

SWI-Prolog 7.4 Reference Manual

206 CHAPTER 4. BUILT-IN PREDICATES

G The ISO 8601 year with century as a decimal number. The 4-digit year corresponding to
the ISO week number (see %V). This has the same format and value as %y, except that if
the ISO week number belongs to the previous or next year, that year is used instead.
V The ISO 8601:1988 week number of the current year as a decimal number, range 01 to
53, where week 1 is the first week that has at least 4 days in the current year, and with
Monday as the first day of the week. See also %U and %W.
h Equivalent to %b.
H The hour as a decimal number using a 24-hour clock (range 00 to 23).
I The hour as a decimal number using a 12-hour clock (range 01 to 12).
j The day of the year as a decimal number (range 001 to 366).
k The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded
by a blank. (See also %H.)
l The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded
by a blank. (See also %I.)
m The month as a decimal number (range 01 to 12).
M The minute as a decimal number (range 00 to 59).
n A newline character.
O Modifier to select locale-specific output. Not implemented.
p Either AM or PM according to the given time value, or the corresponding strings for
the current locale. Noon is treated as pm and midnight as am.
P Like %p but in lowercase: am or pm or a corresponding string for the current locale.
r The time in a.m. or p.m. notation. In the POSIX locale this is equivalent to %I:%M:%S
%p.
R The time in 24-hour notation (%H:%M). For a version including the seconds, see %T
below.
s The number of seconds since the Epoch, i.e., since 1970-01-01 00:00:00 UTC.
S The second as a decimal number (range 00 to 60). (The range is up to 60 to allow for
occasional leap seconds.)
t A tab character.
T The time in 24-hour notation (%H:%M:%S).
u The day of the week as a decimal, range 1 to 7, Monday being 1. See also %w.
U The week number of the current year as a decimal number, range 00 to 53, starting with
the first Sunday as the first day of week 01. See also %V and %W.
w The day of the week as a decimal, range 0 to 6, Sunday being 0. See also %u.
W The week number of the current year as a decimal number, range 00 to 53, starting with
the first Monday as the first day of week 01.
x The preferred date representation for the current locale without the time.
X The preferred time representation for the current locale without the date.
y The year as a decimal number without a century (range 00 to 99).

SWI-Prolog 7.4 Reference Manual

4.35. OPERATING SYSTEM INTERACTION 207

Y The year as a decimal number including the century.

z The timezone as hour offset from GMT using the format HHmm. Required to emit
RFC822-conforming dates (using %a, %d %b %Y %T %z). Our implementation
supports %:z, which modifies the output to HH:mm as required by XML-Schema. Note
that both notations are valid in ISO 8601. The sequence %:z is compatible to the GNU
date(1) command.
Z The timezone or name or abbreviation.
+ The date and time in date(1) format.
% A literal % character.

The table below gives some format strings for popular time representations. RFC1123
is used by HTTP. The full implementation of http timestamp/2 as available from
http/http header is here.

http_timestamp(Time, Atom) :-
stamp_date_time(Time, Date, UTC),
format_time(atom(Atom),
%a, %d %b %Y %T GMT,
Date, posix).

Standard Format string

xsd %FT%T%:z
ISO8601 %FT%T%z
RFC822 %a, %d %b %Y %T %z
RFC1123 %a, %d %b %Y %T GMT

format time(+Out, +Format, +StampOrDateTime, +Locale)

Format time given a specified Locale. This predicate is a work-around for lacking proper
portable and thread-safe time and locale handling in current C libraries. In its current
implementation the only value allowed for Locale is posix, which currently only modifies
the behaviour of the a, A, b and B format specifiers. The predicate is used to be able to emit
POSIX locale week and month names for emitting standardised time-stamps such as RFC1123.

parse time(+Text, -Stamp)

Same as parse time(Text, Format, Stamp). See parse time/3.

parse time(+Text, ?Format, -Stamp)

Parse a textual time representation, producing a time-stamp. Supported formats for Text are
in the table below. If the format is known, it may be given to reduce parse time and avoid
ambiguities. Otherwise, Format is unified with the format encountered.

SWI-Prolog 7.4 Reference Manual

208 CHAPTER 4. BUILT-IN PREDICATES

Name Example
rfc 1123 Fri, 08 Dec 2006 15:29:44 GMT
Fri, 08 Dec 2006 15:29:44 +0000
iso 8601 2006-12-08T17:29:44+02:00
20061208T172944+0200
2006-12-08T15:29Z
2006-12-08
20061208
2006-12
2006-W49-5
2006-342

day of the week(+Date,-DayOfTheWeek)

Computes the day of the week for a given date. Date = date(Year,Month,Day). Days of
the week are numbered from one to seven: Monday = 1, Tuesday = 2, . . . , Sunday = 7.

4.35.3 Controlling the swipl-win.exe console window

The Windows executable swipl-win.exe console has a number of predicates to control the appear-
ance of the console. Being totally non-portable, we do not advise using it for your own application,
but use XPCE or another portable GUI platform instead. We give the predicates for reference here.

window title(-Old, +New)

Unify Old with the title displayed in the console and change the title to New.100

win window pos(+ListOfOptions)

Interface to the MS-Windows SetWindowPos() function, controlling size, position and stacking
order of the window. ListOfOptions is a list that may hold any number of the terms below:

size(W, H)
Change the size of the window. W and H are expressed in character units.
position(X, Y)
Change the top-left corner of the window. The values are expressed in pixel units.
zorder(ZOrder)
Change the location in the window stacking order. Values are bottom, top, topmost
and notopmost. Topmost windows are displayed above all other windows.
show(Bool)
If true, show the window, if false hide the window.
activate
If present, activate the window.

win has menu

True if win insert menu/2 and win insert menu item/4 are present.
100
BUG: This predicate should have been called win window title for consistent naming.

SWI-Prolog 7.4 Reference Manual

4.36. FILE SYSTEM INTERACTION 209

win insert menu(+Label, +Before)

Insert a new entry (pulldown) in the menu. If the menu already contains this entry, nothing is
done. The Label is the label and, using the Windows convention, a letter prefixed with & is
underlined and defines the associated accelerator key. Before is the label before which this one
must be inserted. Using - adds the new entry at the end (right). For example, the call below
adds an Application entry just before the Help menu.

win_insert_menu(&Application, &Help)

win insert menu item(+Pulldown, +Label, +Before, :Goal)

Add an item to the named Pulldown menu. Label and Before are handled as in
win insert menu/2, but the label - inserts a separator. Goal is called if the user
selects the item.

4.36 File System Interaction

access file(+File, +Mode)
True if File exists and can be accessed by this Prolog process under mode Mode. Mode is one
of the atoms read, write, append, exist, none or execute. File may also be the name
of a directory. Fails silently otherwise. access file(File, none) simply succeeds
without testing anything.
If Mode is write or append, this predicate also succeeds if the file does not exist and the
user has write access to the directory of the specified location.
The bahaviour is backed up by the POSIX access() API. The Windows replacement ( waccess())
returns incorrect results because it does not consider ACLs (Access Control Lists). The Prolog
flag win file access check may be used to control the level of checking performed by
Prolog. Please note that checking access never provides a guarantee that a subsequent open
succeeds without errors due to inherent concurrency in file operations. It is generally more
robust to try and open the file and handle possible exceptions. See open/4 and catch/3.

exists file(+File)
True if File exists and is a regular file. This does not imply the user has read and/or write
permission for the file. This is the same as access file(File, exist).

file directory name(+File, -Directory)

Extracts the directory part of File. The returned Directory name does not end in /. There are
two special cases. The directory name of / is / itself, and the directory name is . if File does
not contain any / characters. If the File argument ends with a /, e.g., /hello/, it is not a
valid file name. In this case the final / is removed from File, e.g., /hello.
See also directory file path/3 from filesex. The system ensures that for every
valid Path using the Prolog (POSIX) directory separators, following is true on systems with a
sound implementation of same file/2.101 See also prolog to os filename/2.
101
On some systems, Path and Path2 refer to the same entry in the file system, but same file/2 may fail.

SWI-Prolog 7.4 Reference Manual

210 CHAPTER 4. BUILT-IN PREDICATES

...,
file_directory_name(Path, Dir),
file_base_name(Path, File),
directory_file_path(Dir, File, Path2),
same_file(Path, Path2).

file base name(+File, -BaseName)

Extracts the filename part from a path specification. If File does not contain any directory
separators, File is returned in BaseName. See also file directory name/2. If the File
arguments ends with a /, e.g., /hello/, BaseName is unified with the empty atom ().

same file(+File1, +File2)

True if both filenames refer to the same physical file. That is, if File1 and File2 are the same
string or both names exist and point to the same file (due to hard or symbolic links and/or
relative vs. absolute paths). On systems that provide stat() with meaningful values for st dev
and st inode, same file/2 is implemented by comparing the device and inode identifiers.
On Windows, same file/2 compares the strings returned by the GetFullPathName() system
call.

exists directory(+Directory)
True if Directory exists and is a directory. This does not imply the user has read, search or
write permission for the directory.

delete file(+File)
Remove File from the file system.

rename file(+File1, +File2)

Rename File1 as File2. The semantics is compatible to the POSIX semantics of the rename()
system call as far as the operating system allows. Notably, if File2 exists, the operation
succeeds (except for possible permission errors) and is atomic (meaning there is no window
where File2 does not exist).

size file(+File, -Size)

Unify Size with the size of File in bytes.

time file(+File, -Time)

Unify the last modification time of File with Time. Time is a floating point number expressing
the seconds elapsed since Jan 1, 1970. See also convert time/[2,8] and get time/1.

absolute file name(+File, -Absolute)

Expand a local filename into an absolute path. The absolute path is canonicalised: refer-
ences to . and .. are deleted. This predicate ensures that expanding a filename re-
turns the same absolute path regardless of how the file is addressed. SWI-Prolog uses
absolute filenames to register source files independent of the current working direc-
tory. See also absolute file name/3. See also absolute file name/3 and
expand file name/2.

SWI-Prolog 7.4 Reference Manual

4.36. FILE SYSTEM INTERACTION 211

absolute file name(+Spec, -Absolute, +Options)

Convert the given file specification into an absolute path. Spec is a term Alias(Relative) (e.g.,
(library(lists)), a relative filename or an absolute filename. The primary intention of
this predicate is to resolve files specified as Alias(Relative). Option is a list of options to guide
the conversion:

extensions(ListOfExtensions)
List of file extensions to try. Default is . For each extension,
absolute file name/3 will first add the extension and then verify the condi-
tions imposed by the other options. If the condition fails, the next extension on the list is
tried. Extensions may be specified both as .ext or plain ext.
relative to(+FileOrDir)
Resolve the path relative to the given directory or the directory holding the given
file. Without this option, paths are resolved relative to the working directory (see
working directory/2) or, if Spec is atomic and absolute file name/[2,3]
is executed in a directive, it uses the current source file as reference.
access(Mode)
Imposes the condition access file(File, Mode). Mode is one of read, write, append,
execute, exist or none. See also access file/2.
file type(Type)
Defines extensions. Current mapping: txt implies [], prolog implies [.pl,
], executable implies [.so, ], qlf implies [.qlf, ] and
directory implies []. The file type source is an alias for prolog for com-
patibility with SICStus Prolog. See also prolog file type/2. This predicate only
returns non-directories, unless the option file type(directory) is specified.
file errors(fail/error)
If error (default), throw an existence error exception if the file cannot be found.
If fail, stay silent.102
solutions(first/all)
If first (default), the predicate leaves no choice point. Otherwise a choice point will be
left and backtracking may yield more solutions.
expand(true/false)
If true (default is false) and Spec is atomic, call expand file name/2 followed
by member/2 on Spec before proceeding. This is a SWI-Prolog extension.

The Prolog flag verbose file search can be set to true to help debugging Prologs
search for files.
This predicate is derived from Quintus Prolog. In Quintus Prolog, the argument order was
absolute file name(+Spec, +Options, -Path). The argument order has been changed for
compatibility with ISO and SICStus. The Quintus argument order is still accepted.

is absolute file name(+File)

True if File specifies an absolute path name. On Unix systems, this implies the path starts
with a /. For Microsoft-based systems this implies the path starts with hletteri:. This
102
Silent operation was the default up to version 3.2.6.

SWI-Prolog 7.4 Reference Manual

212 CHAPTER 4. BUILT-IN PREDICATES

predicate is intended to provide platform-independent checking for absolute paths. See also
absolute file name/2 and prolog to os filename/2.

file name extension(?Base, ?Extension, ?Name)

This predicate is used to add, remove or test filename extensions. The main reason for its
introduction is to deal with different filename properties in a portable manner. If the file system
is case-insensitive, testing for an extension will also be done case-insensitive. Extension may
be specified with or without a leading dot (.). If an Extension is generated, it will not have a
leading dot.

directory files(+Directory, -Entries)

Unify Entries with a list of entries in Directory. Each member of Entries is an atom denoting an
entry relative to Directory. Entries contains all entries, including hidden files and, if supplied
by the OS, the special entries . and ... See also expand file name/2.103

expand file name(+WildCard, -List)

Unify List with a sorted list of files or directories matching WildCard. The normal Unix wild-
card constructs ?, *, [...] and {...} are recognised. The interpretation of {...}
is slightly different from the C shell (csh(1)). The comma-separated argument can be arbitrary
patterns, including {...} patterns. The empty pattern is legal as well: \{.pl,\} matches
either .pl or the empty string.
If the pattern contains wildcard characters, only existing files and directories are returned. Ex-
panding a pattern without wildcard characters returns the argument, regardless of whether or
not it exists.
Before expanding wildcards, the construct $var is expanded to the value of the environment
variable var, and a possible leading character is expanded to the users home directory.104

prolog to os filename(?PrologPath, ?OsPath)

Convert between the internal Prolog path name conventions and the operating system path
name conventions. The internal conventions follow the POSIX standard, which implies that
this predicate is equivalent to =/2 (unify) on POSIX (e.g., Unix) systems. On Windows systems
it changes the directory separator from \ into /.

read link(+File, -Link, -Target)

If File points to a symbolic link, unify Link with the value of the link and Target to the file the
link is pointing to. Target points to a file, directory or non-existing entry in the file system, but
never to a link. Fails if File is not a link. Fails always on systems that do not support symbolic
links.

tmp file(+Base, -TmpName) [deprecated]

Create a name for a temporary file. Base is an identifier for the category of file. The TmpName
is guaranteed to be unique. If the system halts, it will automatically remove all created
103
This predicate should be considered a misnomer because it returns entries rather than files. We stick to this name for
compatibility with, e.g., SICStus, Ciao and YAP.
104
On Windows, the home directory is determined as follows: if the environment variable HOME exists, this is used. If
the variables HOMEDRIVE and HOMEPATH exist (Windows-NT), these are used. At initialisation, the system will set the
environment variable HOME to point to the SWI-Prolog home directory if neither HOME nor HOMEPATH and HOMEDRIVE
are defined.

SWI-Prolog 7.4 Reference Manual

4.36. FILE SYSTEM INTERACTION 213

temporary files. Base is used as part of the final filename. Portable applications should limit
themselves to alphanumeric characters.
Because it is possible to guess the generated filename, attackers may create the filesystem entry
as a link and possibly create a security issue. New code should use tmp file stream/3.

tmp file stream(+Encoding, -FileName, -Stream)

Create a temporary filename FileName and open it for writing in the given Encoding. Encoding
is a text-encoding name or binary. Stream is the output stream. If the OS supports it, the
created file is only accessible to the current user. If the OS supports it, the file is created using
the open()-flag O EXCL, which guarantees that the file did not exist before this call. This
predicate is a safe replacement of tmp file/2. Note that in those cases where the temporary
file is needed to store output from an external command, the file must be closed first. E.g., the
following downloads a file from a URL to a temporary file and opens the file for reading (on
Unix systems you can delete the file for cleanup after opening it for reading):

open_url(URL, In) :-
tmp_file_stream(text, File, Stream),
close(Stream),
process_create(curl, [-o, File, URL], []),
open(File, read, In),
delete_file(File). % Unix-only

Temporary files created using this call are removed if the Prolog process terminates gracefully.
Calling delete file/1 using FileName removes the file and removes the entry from the
administration of files-to-be-deleted.

make directory(+Directory)
Create a new directory (folder) on the filesystem. Raises an exception on failure. On Unix
systems, the directory is created with default permissions (defined by the process umask
setting).

delete directory(+Directory)
Delete directory (folder) from the filesystem. Raises an exception on failure. Please note that
in general it will not be possible to delete a non-empty directory.

working directory(-Old, +New)

Unify Old with an absolute path to the current working directory and change working directory
to New. Use the pattern working directory(CWD, CWD) to get the current directory. See
also absolute file name/2 and chdir/1.105 Note that the working directory is shared
between all threads.

chdir(+Path)
Compatibility predicate. New code should use working directory/2.
105
BUG: Some of the file I/O predicates use local filenames. Changing directory while file-bound streams are open causes
wrong results on telling/1, seeing/1 and current stream/3.

SWI-Prolog 7.4 Reference Manual

214 CHAPTER 4. BUILT-IN PREDICATES

4.37 User Top-level Manipulation

break
Recursively start a new Prolog top level. This Prolog top level shares everything from the
environment it was started in. Debugging is switched off on entering a break and restored on
leaving one. The break environment is terminated by typing the systems end-of-file character
(control-D). If that is somehow not functional, the term end of file. can be entered to
return from the break environment. If the -t toplevel command line option is given, this
goal is started instead of entering the default interactive top level (prolog/0).
Notably the gui based versions (swipl-win on Windows and MacOS) provide the menu
Run/New thread that opens a new toplevel that runs concurrently with the initial toplevel.
The concurrent toplevel can be used to examine the program, in particular global dy-
namic predicates. It can not access global variables or thread-local dynamic predicates (see
thread local/1) of the main thread.

abort
Abort the Prolog execution and restart the top level. If the -t toplevel command line
option is given, this goal is started instead of entering the default interactive top level.
Aborting is implemented by throwing the reserved exception $aborted. This exception
can be caught using catch/3, but the recovery goal is wrapped with a predicate that prunes
the choice points of the recovery goal (i.e., as once/1) and re-throws the exception. This is
illustrated in the example below, where we press control-C and a.

?- catch((repeat,fail), E, true).
CAction (h for help) ? abort
% Execution Aborted

halt [ISO]
Terminate Prolog execution. This is the same as halt(0). See halt/1 for details.

halt(+Status) [ISO]
Terminate Prolog execution with Status. This predicate calls PL halt() which preforms the
following steps:

1. Set the Prolog flag exit status to Status.

2. Call all hooks registered using at halt/1. If Status equals 0 (zero), any of these hooks
calls cancel halt/1, termination is cancelled.
3. Call all hooks registered using PL at halt(). In the future, if any of these hooks returns
non-zero, termination will be cancelled. Currently, this only prints a warning.
4. Perform the following system cleanup actions:
Cancel all threads, calling thread at exit/1 registered termination hooks.
Threads not responding within 1 second are cancelled forcefully.
Flush I/O and close all streams except for standard I/O.
Reset the terminal if its properties were changed.
Remove temporary files and incomplete compilation output.

SWI-Prolog 7.4 Reference Manual

4.38. CREATING A PROTOCOL OF THE USER INTERACTION 215

Reclaim memory.
5. Call exit(Status) to terminate the process

prolog
This goal starts the default interactive top level. Queries are read from the stream user input.
See also the Prolog flag history. The prolog/0 predicate is terminated (succeeds) by
typing the end-of-file character (typically control-D).
The following two hooks allow for expanding queries and handling the result of a query. These
hooks are used by the top level variable expansion mechanism described in section 2.8.
expand query(+Query, -Expanded, +Bindings, -ExpandedBindings)
Hook in module user, normally not defined. Query and Bindings represents the query read
from the user and the names of the free variables as obtained using read term/3. If this
predicate succeeds, it should bind Expanded and ExpandedBindings to the query and bindings
to be executed by the top level. This predicate is used by the top level (prolog/0). See also
expand answer/2 and term expansion/2.
expand answer(+Bindings, -ExpandedBindings)
Hook in module user, normally not defined. Expand the result of a successfully executed
top-level query. Bindings is the query < N ame >= hValuei binding list from the query.
ExpandedBindings must be unified with the bindings the top level should print.

4.38 Creating a Protocol of the User Interaction

SWI-Prolog offers the possibility to log the interaction with the user on a file.106 All Prolog interac-
tion, including warnings and tracer output, are written to the protocol file.
protocol(+File)
Start protocolling on file File. If there is already a protocol file open, then close it first. If File
exists it is truncated.
protocola(+File)
Equivalent to protocol/1, but does not truncate the File if it exists.
noprotocol
Stop making a protocol of the user interaction. Pending output is flushed on the file.
protocolling(-File)
True if a protocol was started with protocol/1 or protocola/1 and unifies File with the
current protocol output file.

4.39 Debugging and Tracing Programs

This section is a reference to the debugger interaction predicates. A more use-oriented overview of
the debugger is in section 2.9.
If you have installed XPCE, you can use the graphical front-end of the tracer. This front-end is
installed using the predicate guitracer/0.
106
A similar facility was added to Edinburgh C-Prolog by Wouter Jansweijer.

SWI-Prolog 7.4 Reference Manual

216 CHAPTER 4. BUILT-IN PREDICATES

trace
Start the tracer. trace/0 itself cannot be seen in the tracer. Note that the Prolog top level
treats trace/0 special; it means trace the next goal.

tracing
True if the tracer is currently switched on. tracing/0 itself cannot be seen in the tracer.

notrace
Stop the tracer. notrace/0 itself cannot be seen in the tracer.

guitracer
Installs hooks (see prolog trace interception/4) into the system that redirect tracing
information to a GUI front-end providing structured access to variable bindings, graphical
overview of the stack and highlighting of relevant source code.

noguitracer
Revert back to the textual tracer.

trace(+Pred)
Equivalent to trace(Pred, +all).

trace(+Pred, +Ports)
Put a trace point on all predicates satisfying the predicate specification Pred. Ports is a list
of port names (call, redo, exit, fail). The atom all refers to all ports. If the port is
preceded by a - sign, the trace point is cleared for the port. If it is preceded by a +, the trace
point is set.
The predicate trace/2 activates debug mode (see debug/0). Each time a port (of the 4-
port model) is passed that has a trace point set, the goal is printed as with trace/0. Unlike
trace/0, however, the execution is continued without asking for further information. Exam-
ples:

?- trace(hello). Trace all ports of hello with any arity in any mod-
ule.
?- trace(foo/2, +fail). Trace failures of foo/2 in any module.
?- trace(bar/1, -all). Stop tracing bar/1.

The predicate debugging/0 shows all currently defined trace points.

notrace(:Goal)
Call Goal, but suspend the debugger while Goal is executing. The current implementation cuts
the choice points of Goal after successful completion. See once/1. Later implementations
may have the same semantics as call/1.

debug
Start debugger. In debug mode, Prolog stops at spy and trace points, disables last-call optimi-
sation and aggressive destruction of choice points to make debugging information accessible.
Implemented by the Prolog flag debug.
Note that the min free parameter of all stacks is enlarged to 8 K cells if debugging is switched
off in order to avoid excessive GC. GC complicates tracing because it renames the GNNN

SWI-Prolog 7.4 Reference Manual

4.39. DEBUGGING AND TRACING PROGRAMS 217

variables and replaces unreachable variables with the atom <garbage_collected>. Call-
ing nodebug/0 does not reset the initial free-margin because several parts of the top level and
debugger disable debugging of system code regions. See also set prolog stack/2.
nodebug
Stop debugger. Implemented by the Prolog flag debug. See also debug/0.
debugging
Print debug status and spy points on current output stream. See also the Prolog flag debug.
spy(+Pred)
Put a spy point on all predicates meeting the predicate specification Pred. See section 4.5.
nospy(+Pred)
Remove spy point from all predicates meeting the predicate specification Pred.
nospyall
Remove all spy points from the entire program.
leash(?Ports)
Set/query leashing (ports which allow for user interaction). Ports is one of +Name, -Name,
?Name or a list of these. +Name enables leashing on that port, -Name disables it and ?Name
succeeds or fails according to the current setting. Recognised ports are call, redo, exit,
fail and unify. The special shorthand all refers to all ports, full refers to all ports
except for the unify port (default). half refers to the call, redo and fail port.
visible(+Ports)
Set the ports shown by the debugger. See leash/1 for a description of the Ports specification.
Default is full.
unknown(-Old, +New)
Edinburgh-Prolog compatibility predicate, interfacing to the ISO Prolog flag unknown. Val-
ues are trace (meaning error) and fail. If the unknown flag is set to warning,
unknown/2 reports the value as trace.
style check(+Spec)
Modify/query style checking options. Spec is one of the terms below or a list of these.

+Style enables a style check

-Style disables a style check
?(Style) queries a style check (note the brackets). If Style is unbound, all active style check
options are returned on backtracking.

Loading a file using load files/2 or one of its derived predicates reset the style checking
options to their value before loading the file, scoping the option to the remainder of the file and
all files loaded after changing the style checking.

singleton(true)
The predicate read clause/3 (used by the compiler to read source code) warns on
variables appearing only once in a term (clause) which have a name not starting with an
underscore. See section 2.15.1 for details on variable handling and warnings.

SWI-Prolog 7.4 Reference Manual

218 CHAPTER 4. BUILT-IN PREDICATES

no effect(true)
This warning is generated by the compiler for BIPs (built-in predicates) that are inlined
by the compiler and for which the compiler can prove that they are meaningless. An
example is using ==/2 against a not-yet-initialised variable as illustrated in the example
below. This comparison is always false.

always_false(X) :-
X == Y,
write(Y).

var branches(false)
Verifies that if a variable is introduced in a branch and used after the branch, it is in-
troduced in all branches. This code aims at bugs following the skeleton below, where
p(Next) may be called with Next unbound.

p(Arg) :-
( Cond
-> Next = value1
; true
),
p(Next).

If a variable V is intended to be left unbound, one can use V= . This construct is removed
by the compiler and thus has no implications for the performance of your program.
This check was suggested together with semantic singleton checking. The SWI-Prolog
libraries contain about a hundred clauses that are triggered by this style check. Unlike
semantic singleton analysis, only a tiny fraction of these clauses proofed faulty. In most
cases, the branches failing to bind the variable fail or raise an exception or the caller
handles the case where the variable is unbound. The status of this style check is unclear. It
might be removed in the future or it might be enhanced with a deeper analysis to be more
precise.

atom(true)
The predicate read/1 and derived predicates produce an error message on quoted atoms
or strings with more than 6 unescaped newlines. Newlines may be escaped with \ or \c.
This flag also enables warnings on \hnewlinei followed by blank space in native mode.
See section 2.15.1. Note that the ISO standard does not allow for unescaped newlines in
quoted atoms.

discontiguous(true)
Warn if the clauses for a predicate are not together in the same source file. It is advised
to disable the warning for discontiguous predicates using the discontiguous/1
directive.

charset(false)
Warn on atoms and variable names holding non-ASCII characters that are not quoted.
See also section 2.15.1.

SWI-Prolog 7.4 Reference Manual

4.40. OBTAINING RUNTIME STATISTICS 219

4.40 Obtaining Runtime Statistics

statistics(+Key, -Value)
Unify system statistics determined by Key with Value. The possible keys are given in the
table 4.3. This predicate supports additional keys for compatibility reasons. These keys are
described in table 4.4.

statistics
Display a table of system statistics on the stream user error.

time(:Goal)
Execute Goal just like call/1 and print time used, number of logical inferences and the
average number of lips (logical inferences per second). Note that SWI-Prolog counts the actual
executed number of inferences rather than the number of passes through the call and redo ports
of the theoretical 4-port model. If Goal is non-deterministic, print statistics for each solution,
where the reported values are relative to the previous answer.

4.41 Execution profiling

This section describes the hierarchical execution profiler. This profiler is based on ideas from gprof
described in [Graham et al., 1982]. The profiler consists of two parts: the information-gathering com-
ponent built into the kernel,107 and a presentation component which is defined in the statistics
library. The latter can be hooked, which is used by the XPCE module swi/pce profile to provide
an interactive graphical frontend for the results.

4.41.1 Profiling predicates

The following predicates are defined to interact with the profiler.

profile(:Goal)
Execute Goal just like once/1, collecting profiling statistics, and call show profile([]).
With XPCE installed this opens a graphical interface to examine the collected profiling data.

profile(:Goal, +Options)
Execute Goal just like once/1. Collect profiling statistics according to Options and call
show profile/1 with Options. The default collects CPU profiling and opens a graphical
interface when provided, printing the plain time usage of the top 25 predicates as a ballback.
Options are described below. Remaining options are passed to show profile/1.

time(+Which)
If Which is cpu (default), collect CPU timing statistics. If wall, collect wall time
statistics based on a 5 millisecond sampling rate. Wall time statistics can be useful if Goal
calls blocking system calls.

show profile(+Options)
This predicate first calls prolog:show profile hook/1. If XPCE is loaded, this hook is used to
107
There are two implementations; one based on setitimer() using the SIGPROF signal and one using Windows Multi
Media (MM) timers. On other systems the profiler is not provided.

SWI-Prolog 7.4 Reference Manual

220 CHAPTER 4. BUILT-IN PREDICATES

Native keys (times as float in seconds)

agc Number of atom garbage collections performed
agc gained Number of atoms removed
agc time Time spent in atom garbage collections
atoms Total number of defined atoms
c stack System (C-) stack limit. 0 if not known.
cgc Number of clause garbage collections performed
cgc gained Number of clauses reclaimed
cgc time Time spent in clause garbage collections
clauses Total number of clauses in the program
codes Total size of (virtual) executable code in words
cputime (User) CPU time since thread was started in seconds
epoch Time stamp when thread was started
functors Total number of defined name/arity pairs
global Allocated size of the global stack in bytes
globalused Number of bytes in use on the global stack
globallimit Size to which the global stack is allowed to grow
global shifts Number of global stack expansions
heapused Bytes of heap in use by Prolog (0 if not maintained)
inferences Total number of passes via the call and redo ports since Prolog was started
modules Total number of defined modules
local Allocated size of the local stack in bytes
local shifts Number of local stack expansions
locallimit Size to which the local stack is allowed to grow
localused Number of bytes in use on the local stack
table space used Amount of bytes in use by the threads answer tables
trail Allocated size of the trail stack in bytes
trail shifts Number of trail stack expansions
traillimit Size to which the trail stack is allowed to grow
trailused Number of bytes in use on the trail stack
shift time Time spent in stack-shifts
stack Total memory in use for stacks in all threads
predicates Total number of predicates. This includes predicates that are undefined or not
yet resolved.
process epoch Time stamp when Prolog was started
process cputime (User) CPU time since Prolog was started in seconds
thread cputime MT-version: Seconds CPU time used by finished threads. Basically non-
portable. Works on Linux, MacOSX, Windows and probably some more.
threads MT-version: number of active threads
threads created MT-version: number of created threads
engines MT-version: number of existing engines
engines created MT-version: number of created engines

Table 4.3: Keys for statistics/2. Space is expressed in bytes. Time is expressed in seconds,
represented as a floating point number.

SWI-Prolog 7.4 Reference Manual

4.41. EXECUTION PROFILING 221

Compatibility keys (times in milliseconds)

runtime [ CPU time, CPU time since last ] (milliseconds, excluding time spent in
garbage collection)
system time [ System CPU time, System CPU time since last ] (milliseconds)
real time [ Wall time, Wall time since last ] (integer seconds. See get time/1)
walltime [ Wall time since start, Wall time since last] (milliseconds, SICStus compati-
bility)
memory [ Total unshared data, free memory ] (Uses getrusage() if available, otherwise
incomplete own statistics.)
stacks [ global use, local use ]
program [ heap, 0 ]
global stack [ global use, global free ]
local stack [ local use, local free ]
trail [ trail use, trail free ]
garbage collection [ number of GC, bytes gained, time spent, bytes left ] The last column is a SWI-
Prolog extension. It contains the sum of the memory left after each collection,
which can be divided by the count to find the average working set size after
GC. Use [Count, Gained, Time| ] for compatiblity.
stack shifts [ global shifts, local shifts, time spent ]
atoms [ number, memory use, 0 ]
atom garbage collection [ number of AGC, bytes gained, time spent ]
clause garbage collection [ number of CGC, clauses gained, time spent ]
core Same as memory

Table 4.4: Compatibility keys for statistics/2. Time is expressed in milliseconds.

SWI-Prolog 7.4 Reference Manual

222 CHAPTER 4. BUILT-IN PREDICATES

activate a GUI interface to visualise the profile results. If not, a report is printed to the terminal
according to Options:

top(+N)
Show the only top N predicates. Default is 25.
cumulative(+Bool)
If true (default false), include the time spent in children in the time reported for a
predicate.

profiler(-Old, +New)
Query or change the status of the profiler. The status is one of

false
The profiler is not activated.
cputime
The profiler collects CPU statistics.
walltime
The profiler collects wall time statistics.

The value true is accepted as a synonym for cputime for compatibility reasons.

reset profiler
Switches the profiler to false and clears all collected statistics.

noprofile(+Name/+Arity, . . . )
Declares the predicate Name/Arity to be invisible to the profiler. The time spent in the named
predicate is added to the caller, and the callees are linked directly to the caller. This is
particularly useful for simple meta-predicates such as call/1, ignore/1, catch/3, etc.

4.41.2 Visualizing profiling data

Browsing the annotated call-tree as described in section 4.41.3 itself is not very attractive. Therefore,
the results are combined per predicate, collecting all callers and callees as well as the propagation
of time and activations in both directions. Figure 4.1 illustrates this. The central yellowish line is
the current predicate with counts for time spent in the predicate (Self), time spent in its children
(Siblings), activations through the call and redo ports. Above that are the callers. Here, the two time
fields indicate how much time is spent serving each of the callers. The columns sum to the time in the
yellowish line. The caller <recursive> is the number of recursive calls. Below the yellowish lines are
the callees, with the time spent in the callee itself for serving the current predicate and the time spent
in the callees of the callee (Siblings), so the whole time-block adds up to the Siblings field of the
current predicate. The Access fields show how many times the current predicate accesses each of
the callees.
The predicates have a menu that allows changing the view of the detail window to the given caller
or callee, showing the documentation (if it is a built-in) and/or jumping to the source.
The statistics shown in the report field of figure 4.1 show the following information:

SWI-Prolog 7.4 Reference Manual

4.41. EXECUTION PROFILING 223

Figure 4.1: Execution profiler showing the activity of the predicate chat:inv map list/5.

samples
Number of times the call-tree was sampled for collecting time statistics. On most hardware, the
resolution of SIGPROF is 1/100 second. This number must be sufficiently large to get reliable
timing figures. The Time menu allows viewing time as samples, relative time or absolute time.

sec
Total user CPU time with the profiler active.

predicates
Total count of predicates that have been called at least one time during the profile.

nodes
Number of nodes in the call-tree.

distortion
How much of the time is spent building the call-tree as a percentage of the total execution time.
Timing samples while the profiler is building the call-tree are not added to the call-tree.

4.41.3 Information gathering

While the program executes under the profiler, the system builds a dynamic call-tree. It does this using
three hooks from the kernel: one that starts a new goal (profCall), one that tells the system which goal
is resumed after an exit (profExit) and one that tells the system which goal is resumed after a fail
(i.e., which goal is used to retry (profRedo)). The profCall() function finds or creates the subnode
for the argument predicate below the current node, increments the call-count of this link and returns
the sub-node which is recorded in the Prolog stack-frame. Choice-points are marked with the current
profiling node. profExit() and profRedo() pass the profiling node where execution resumes.
Just using the above algorithm would create a much too big tree due to recursion. For this reason
the system performs detection of recursion. In the simplest case, recursive procedures increment the
recursive count on the current node. Mutual recursion, however, is not easily detected. For example,
call/1 can call a predicate that uses call/1 itself. This can be viewed as a recursive invocation,
but this is generally not desirable. Recursion is currently assumed if the same predicate with the
same parent appears higher in the call-graph. Early experience with some non-trivial programs are
promising.

SWI-Prolog 7.4 Reference Manual

224 CHAPTER 4. BUILT-IN PREDICATES

The last part of the profiler collects statistics on the CPU time used in each node. On systems
providing setitimer() with SIGPROF, it ticks the current node of the call-tree each time the timer
fires. On Windows, a MM-timer in a separate thread checks 100 times per second how much time is
spent in the profiled thread and adds this to the current node. See section 4.41.3 for details.

Profiling in the Windows Implementation

Profiling in the Windows version is similar, but as profiling is a statistical process it is good to be
aware of the implementation108 for proper interpretation of the results.
Windows does not provide timers that fire asynchronously, frequent and proportional to the CPU
time used by the process. Windows does provide multi-media timers that can run at high frequency.
Such timers, however, run in a separate thread of execution and they are fired on the wall clock
rather than the amount of CPU time used. The profiler installs such a timer running, for saving
CPU time, rather inaccurately at about 100 Hz. Each time it is fired, it determines the CPU time in
milliseconds used by Prolog since the last time it was fired. If this value is non-zero, active predicates
are incremented with this value.

4.42 Memory Management

garbage collect
Invoke the global and trail stack garbage collector. Normally the garbage collector is invoked
automatically if necessary. Explicit invocation might be useful to reduce the need for
garbage collections in time-critical segments of the code. After the garbage collection
trim stacks/0 is invoked to release the collected memory resources.
garbage collect atoms
Reclaim unused atoms. Normally invoked after agc margin (a Prolog flag) atoms have been
created. On multithreaded versions the actual collection is delayed until there are no threads
performing normal garbage collection. In this case garbage collect atoms/0 returns
immediately. Note that there is no guarantee it will ever happen, as there may always be threads
performing garbage collection.
trim stacks
Release stack memory resources that are not in use at this moment, returning them to the
operating system. It can be used to release memory resources in a backtracking loop, where
the iterations require typically seconds of execution time and very different, potentially large,
amounts of stack space. Such a loop can be written as follows:

loop :-
generator,
trim_stacks,
potentially_expensive_operation,
stop_condition, !.

The Prolog top-level loop is written this way, reclaiming memory resources after every user
query.
108
We hereby acknowledge Lionel Fourquaux, who suggested the design described here after a newsnet enquiry.

SWI-Prolog 7.4 Reference Manual

4.43. WINDOWS DDE INTERFACE 225

set prolog stack(+Stack, +KeyValue)

Set a parameter for one of the Prolog runtime stacks. Stack is one of local, global, trail
or argument. The table below describes the Key(Value) pairs. Value can be an arithmetic
integer expression. For example, to specify a 2 GB limit for the global stack, one can use:

?- set_prolog_stack(global, limit(2*10**9)).

Current settings can be retrieved with prolog stack property/2.

limit(+Bytes)
Set the limit to which the stack is allowed to grow. If the specified value is lower than the
current usage a permission error is raised. If the limit is larger than supported, the
system silently reduces the requested limit to the system limit.
min free(+Cells)
Minimum amount of free space after trimming or shifting the stack. Setting this value
higher can reduce the number of garbage collections and stack-shifts at the cost of higher
memory usage. The spare stack amount is reported and specified in cells. A cell is 4
bytes in the 32-bit version and 8 bytes on the 64-bit version. See address bits. See
also trim stacks/0 and debug/0.
spare(+Cells)
All stacks trigger overflow before actually reaching the limit, so the resulting error can be
handled gracefully. The spare stack is used for print message/2 from the garbage
collector and for handling exceptions. The default suffices, unless the user redefines
related hooks. Do not specify large values for this because it reduces the amount of
memory available for your real task.
Related hooks are message hook/3 (redefining GC messages),
prolog trace interception/4 and prolog exception hook/4.

prolog stack property(?Stack, ?KeyValue)

True if KeyValue is a current property of Stack. See set prolog stack/2 for defined
properties.

4.43 Windows DDE interface

The predicates in this section deal with MS-Windows Dynamic Data Exchange or DDE protocol.109
A Windows DDE conversation is a form of interprocess communication based on sending reserved
window events between the communicating processes.
Failing DDE operations raise an error of the structure below, where Operation is the name of the
(partial) operation that failed and Message is a translation of the operator error code. For some errors,
Context provides additional comments.

error(dde_error(Operation, Message), Context)

109
This interface is contributed by Don Dwiggins.

SWI-Prolog 7.4 Reference Manual

226 CHAPTER 4. BUILT-IN PREDICATES

4.43.1 DDE client interface

The DDE client interface allows Prolog to talk to DDE server programs. We will demonstrate the use
of the DDE interface using the Windows PROGMAN (Program Manager) application:

1 ?- open_dde_conversation(progman, progman, C).

C = 0
2 ?- dde_request(0, groups, X)

--> Unifies X with description of groups

3 ?- dde_execute(0, [CreateGroup("DDE Demo")]).

true.

4 ?- close_dde_conversation(0).
true.

For details on interacting with progman, use the SDK online manual section on the Shell DDE
interface. See also the Prolog library(progman), which may be used to write simple Windows
setup scripts in Prolog.

open dde conversation(+Service, +Topic, -Handle)

Open a conversation with a server supporting the given service name and topic (atoms). If
successful, Handle may be used to send transactions to the server. If no willing server is found
this predicate fails silently.

close dde conversation(+Handle)

Close the conversation associated with Handle. All opened conversations should be closed
when theyre no longer needed, although the system will close any that remain open on process
termination.

dde request(+Handle, +Item, -Value)

Request a value from the server. Item is an atom that identifies the requested data, and Value
will be a string (CF TEXT data in DDE parlance) representing that data, if the request is
successful.

dde execute(+Handle, +Command)

Request the DDE server to execute the given command string. Succeeds if the command could
be executed and fails with an error message otherwise.

dde poke(+Handle, +Item, +Command)

Issue a POKE command to the server on the specified Item. command is passed as data of type
CF TEXT.

4.43.2 DDE server mode

The library(dde) defines primitives to realise simple DDE server applications in SWI-Prolog.
These features are provided as of version 2.0.6 and should be regarded as prototypes. The C part

SWI-Prolog 7.4 Reference Manual

4.43. WINDOWS DDE INTERFACE 227

of the DDE server can handle some more primitives, so if you need features not provided by this
interface, please study library(dde).

dde register service(+Template, +Goal)

Register a server to handle DDE request or DDE execute requests from other applications.
To register a service for a DDE request, Template is of the form:

+Service(+Topic, +Item, +Value)

Service is the name of the DDE service provided (like progman in the client example above).
Topic is either an atom, indicating Goal only handles requests on this topic, or a variable that
also appears in Goal. Item and Value are variables that also appear in Goal. Item represents the
request data as a Prolog atom.110
The example below registers the Prolog current prolog flag/2 predicate to be accessi-
ble from other applications. The request may be given from the same Prolog as well as from
another application.

?- dde_register_service(prolog(current_prolog_flag, F, V),
current_prolog_flag(F, V)).

?- open_dde_conversation(prolog, current_prolog_flag, Handle),

dde_request(Handle, home, Home),
close_dde_conversation(Handle).

Home = /usr/local/lib/pl-2.0.6/

Handling DDE execute requests is very similar. In this case the template is of the form:

+Service(+Topic, +Item)

Passing a Value argument is not needed as execute requests either succeed or fail. If Goal
fails, a not processed is passed back to the caller of the DDE request.

dde unregister service(+Service)

Stop responding to Service. If Prolog is halted, it will automatically call this on all open
services.

dde current service(-Service, -Topic)

Find currently registered services and the topics served on them.

dde current connection(-Service, -Topic)

Find currently open conversations.
110
Up to version 3.4.5 this was a list of character codes. As recent versions have atom garbage collection there is no need
for this anymore.

SWI-Prolog 7.4 Reference Manual

228 CHAPTER 4. BUILT-IN PREDICATES

4.44 Miscellaneous
dwim match(+Atom1, +Atom2)
True if Atom1 matches Atom2 in the Do What I Mean sense. Both Atom1 and Atom2 may
also be integers or floats. The two atoms match if:

They are identical

They differ by one character (spy spu)
One character is inserted/deleted (debug deug)
Two characters are transposed (trace tarce)
Sub-words are glued differently (existsfile existsFile exists file)
Two adjacent sub-words are transposed (existsFile fileExists)

dwim match(+Atom1, +Atom2, -Difference)

Equivalent to dwim match/2, but unifies Difference with an atom identifying the differ-
ence between Atom1 and Atom2. The return values are (in the same order as above):
equal, mismatched char, inserted char, transposed char, separated and
transposed word.

wildcard match(+Pattern, +String)

True if String matches the wildcard pattern Pattern. Pattern is very similar to the Unix csh
pattern matcher. The patterns are given below:

? Matches one arbitrary character.

* Matches any number of arbitrary characters.
[...] Matches one of the characters specified between the brackets.
hchar1i-hchar2i indicates a range.
{...} Matches any of the patterns of the comma-separated list between the braces.

Example:

?- wildcard_match([a-z]*.{pro,pl}[%], a_hello.pl%).
true.

sleep(+Time)
Suspend execution Time seconds. Time is either a floating point number or an integer. Gran-
ularity is dependent on the systems timer granularity. A negative time causes the timer to
return immediately. On most non-realtime operating systems we can only ensure execution is
suspended for at least Time seconds.
On Unix systems the sleep/1 predicate is realised in order of preference by nanosleep(),
usleep(), select() if the time is below 1 minute, or sleep(). On Windows systems Sleep() is used.

SWI-Prolog 7.4 Reference Manual

SWI-Prolog extensions 5
This chapter describes extensions to the Prolog language introduced with SWI-Prolog version 7. The
changes bring more modern syntactical conventions to Prolog such as key-value maps, called dicts
as primary citizens and a restricted form of functional notation. They also extend Prolog basic types
with strings, providing a natural notation to textual material as opposed to identifiers (atoms) and lists.
These extensions make the syntax more intuitive to new users, simplify the integration of domain
specific languages (DSLs) and facilitate a more natural Prolog representation for popular exchange
languages such as XML and JSON.
While many programs run unmodified in SWI-Prolog version 7, especially those that pass double
quoted strings to general purpose list processing predicates require modifications. We provide a tool
(list strings/0) that we used to port a huge code base in half a day.

5.1 Lists are special

As of version 7, SWI-Prolog lists can be distinguished unambiguously at runtime from ./2 terms
and the atom []. The constant [] is special constant that is not an atom. It has the following
properties:

?- atom([]).
false.
?- atomic([]).
true.
?- [] == [].
false.
?- [] == [].
true.

The cons operator for creating list cells has changed from the pretty atom . to the ugly atom
[|], so we can use the . for other purposes. See section 5.4.1.
This modification has minimal impact on typical Prolog code. It does affect foreign code (see sec-
tion 11) that uses the normal atom and compound term interface for manipulation lists. In most cases
this can be avoided by using the dedicated list functions. For convenience, the macros ATOM nil and
ATOM dot are provided by SWI-Prolog.h.
Another place that is affected is write canonical/1. Impact is minimized by using
the list syntax for lists. The predicates read term/2 and write term/2 support the option
dotlists(true), which causes read term/2 to read .(a,[]) as [a] and write term/2
to write [a] as .(a,[]).

SWI-Prolog 7.4 Reference Manual

230 CHAPTER 5. SWI-PROLOG EXTENSIONS

5.1.1 Motivating [|] and [] for lists

Representing lists the conventional way using ./2 as cons-cell and [] as list terminator both (inde-
pendently) poses conflicts, while these conflicts are easily avoided.

Using ./2 prevents using this commonly used symbol as an operator because a.B cannot be
distinguished from [a|B]. Freeing ./2 provides us with a unique term that we can use for
functional notation on dicts as described in section 5.4.1.

Using [] as list terminator prevents dynamic distinction between atoms and lists. As a result,
we cannot use type polymorphism that involve both atoms and lists. For example, we cannot
use multi lists (arbitrary deeply nested lists) of atoms. Multi lists of atoms are in some situations
a good representation of a flat list that is assembled from sub sequences. The alternative, using
difference lists or DCGs is often less natural and sometimes demands for opening proper lists
(i.e., copying the list while replacing the terminating empty list with a variable) that have to be
added to the sequence. The ambiguity of atom and list is particularly painful when mapping
external data representations that do not suffer from this ambiguity.
At the same time, avoiding [] as a list terminator makes the various text representations
unambiguous, which allows us to write predicates that require a textual argument to accept both
atoms, strings, and lists of character codes or one-character atoms. Traditionally, the empty list
can be interpreted both as the string [] and .

5.2 The string type and its double quoted syntax

As of SWI-Prolog version 7, text enclosed in double quotes (e.g., "Hello world") is read as
objects of the type string. A string is a compact representation of a character sequence that lives on
the global (term) stack. Strings represent sequences of Unicode characters including the character
code 0 (zero). The length strings is limited by the available space on the global (term) stack (see
set prolog stack/2). Strings are distinct from lists, which makes it possible to detect them at
runtime and print them using the string syntax, as illustrated below:

?- write("Hello world!").
Hello world!

?- writeq("Hello world!").
"Hello world!"

Back quoted text (as in text) is mapped to a list of character codes in version 7. The settings for
the flags that control how double and back quoted text is read is summarised in table 5.1. Programs
that aim for compatibility should realise that the ISO standard defines back quoted text, but does not
define the back quotes Prolog flag and does not define the term that is produced by back quoted
text.
Section 5.2.4 motivates the introduction of strings and mapping double quoted text to this type.

SWI-Prolog 7.4 Reference Manual

5.2. THE STRING TYPE AND ITS DOUBLE QUOTED SYNTAX 231

Mode double quotes back quotes

Version 7 default string codes
--traditional codes symbol char

Table 5.1: Mapping of double and back quoted text in the two modes.

5.2.1 Predicates that operate on strings

Strings may be manipulated by a set of predicates that is similar to the manipulation of atoms. In
addition to the list below, string/1 performs the type check for this type and is described in sec-
tion 4.6.
SWI-Prologs string primitives are being synchronized with ECLiPSe. We expect the set of predi-
cates documented in this section to be stable, although it might be expanded. In general, SWI-Prologs
text manipulation predicates accept any form of text as input argument and produce the type indicated
by the predicate name as output. This policy simplifies migration and writing programs that can run
unmodified or with minor modifications on systems that do not support strings. Code should avoid
relying on this feature as much as possible for clarity as well as to facilitate a more strict mode and/or
type checking in future releases.

atom string(?Atom, ?String)

Bi-directional conversion between an atom and a string. At least one of the two arguments
must be instantiated. Atom can also be an integer or floating point number.

number string(?Number, ?String)

Bi-directional conversion between a number and a string. At least one of the two arguments
must be instantiated. Besides the type used to represent the text, this predicate differs in several
ways from its ISO cousin:1

If String does not represent a number, the predicate fails rather than throwing a syntax
error exception.
Leading white space and Prolog comments are not allowed.
Numbers may start with + or -.
It is not allowed to have white space between a leading + or - and the number.
Floating point numbers in exponential notation do not require a dot before exponent, i.e.,
"1e10" is a valid number.

term string(?Term, ?String)

Bi-directional conversion between a term and a string. If String is instantiated, it is parsed and
the result is unified with Term. Otherwise Term is written using the option quoted(true) and
the result is converted to String.

term string(?Term, ?String, +Options)

As term string/2, passing Options to either read term/2 or write term/2. For
example:
1
Note that SWI-Prologs syntax for numbers is not ISO compatible either.

SWI-Prolog 7.4 Reference Manual

232 CHAPTER 5. SWI-PROLOG EXTENSIONS

?- term_string(Term, a(A), [variable_names(VNames)]).

Term = a(_G1466),
VNames = [A=_G1466].

string chars(?String, ?Chars)

Bi-directional conversion between a string and a list of characters (one-character atoms). At
least one of the two arguments must be instantiated.

string codes(?String, ?Codes)

Bi-directional conversion between a string and a list of character codes. At least one of the two
arguments must be instantiated.

text to string(+Text, -String) [det]

Converts Text to a string. Text is an atom, string or list of characters (codes or chars). When
running in --traditional mode, [] is ambiguous and interpreted as an empty string.

string length(+String, -Length)

Unify Length with the number of characters in String. This predicate is functionally equivalent
to atom length/2 and also accepts atoms, integers and floats as its first argument.

string code(?Index, +String, ?Code)

True when Code represents the character at the 1-based Index position in String. If Index is
unbound the string is scanned from index 1. Raises a domain error if Index is negative. Fails
silently if Index is zero or greater than the length of String. The mode string code(-,+,+) is
deterministic if the searched-for Code appears only once in String. See also sub string/5.

get string code(+Index, +String, -Code)

Semi-deterministic version of string code/3. In addition, this version provides strict range
checking, throwing a domain error if Index is less than 1 or greater than the length of String.
ECLiPSe provides this to support String[Index] notation.

string concat(?String1, ?String2, ?String3)

Similar to atom concat/3, but the unbound argument will be unified with a string object
rather than an atom. Also, if both String1 and String2 are unbound and String3 is bound to text,
it breaks String3, unifying the start with String1 and the end with String2 as append does with
lists. Note that this is not particularly fast on long strings, as for each redo the system has to
create two entirely new strings, while the list equivalent only creates a single new list-cell and
moves some pointers around.

split string(+String, +SepChars, +PadChars, -SubStrings) [det]

Break String into SubStrings. The SepChars argument provides the characters that act as
separators and thus the length of SubStrings is one more than the number of separators found if
SepChars and PadChars do not have common characters. If SepChars and PadChars are equal,
sequences of adjacent separators act as a single separator. Leading and trailing characters for
each substring that appear in PadChars are removed from the substring. The input arguments
can be either atoms, strings or char/code lists. Compatible with ECLiPSe. Below are some
examples:

SWI-Prolog 7.4 Reference Manual

5.2. THE STRING TYPE AND ITS DOUBLE QUOTED SYNTAX 233

% a simple split
?- split_string("a.b.c.d", ".", "", L).
L = ["a", "b", "c", "d"].
% Consider sequences of separators as a single one
?- split_string("/home//jan///nice/path", "/", "/", L).
L = ["home", "jan", "nice", "path"].
% split and remove white space
?- split_string("SWI-Prolog, 7.0", ",", " ", L).
L = ["SWI-Prolog", "7.0"].
% only remove leading and trailing white space
?- split_string(" SWI-Prolog ", "", "\s\t\n", L).
L = ["SWI-Prolog"].

In the typical use cases, SepChars either does not overlap PadChars or is equivalent to han-
dle multiple adjacent separators as a single (often white space). The behaviour with par-
tially overlapping sets of padding and separators should be considered undefined. See also
read string/5.

sub string(+String, ?Before, ?Length, ?After, ?SubString)

SubString is a substring of String. There are Before characters in String before SubString,
SubString contains Length character and is followed by After characters in String. If not enough
information is provided to compute the start of the match, String is scanned left-to-right. This
predicate is functionally equivalent to sub atom/5, but operates on strings. The following
example splits a string of the form hnamei=hvaluei into the name part (an atom) and the value
(a string).

name_value(String, Name, Value) :-

sub_string(String, Before, _, After, "="), !,
sub_string(String, 0, Before, _, NameString),
atom_string(Name, NameString),
sub_string(String, _, After, 0, Value).

atomics to string(+List, -String)

List is a list of strings, atoms, integers or floating point numbers. Succeeds if String can be
unified with the concatenated elements of List. Equivalent to atomics to string(List, ,
String).

atomics to string(+List, +Separator, -String)

Creates a string just like atomics to string/2, but inserts Separator between each pair
of inputs. For example:

?- atomics_to_string([gnu, "gnat", 1], , , A).

A = "gnu, gnat, 1"

SWI-Prolog 7.4 Reference Manual

234 CHAPTER 5. SWI-PROLOG EXTENSIONS

string upper(+String, -UpperCase)

Convert String to upper case and unify the result with UpperCase.

string lower(+String, LowerCase)

Convert String to lower case and unify the result with LowerCase.

read string(+Stream, ?Length, -String)

Read at most Length characters from Stream and return them in the string String. If Length is
unbound, Stream is read to the end and Length is unified with the number of characters read.

read string(+Stream, +SepChars, +PadChars, -Sep, -String)

Read a string from Stream, providing functionality similar to split string/4. The predi-
cate performs the following steps:

1. Skip all characters that match PadChars

2. Read up to a character that matches SepChars or end of file
3. Discard trailing characters that match PadChars from the collected input
4. Unify String with a string created from the input and Sep with the separator character read.
If input was terminated by the end of the input, Sep is unified with -1.

The predicate read string/5 called repeatedly on an input until Sep is -1 (end of file) is
equivalent to reading the entire file into a string and calling split string/4, provided that
SepChars and PadChars are not partially overlapping.2 Below are some examples:

% Read a line
read_string(Input, "\n", "\r", End, String)
% Read a line, stripping leading and trailing white space
read_string(Input, "\n", "\r\t ", End, String)
% Read upto , or ), unifying End with 0, or 0)
read_string(Input, ",)", "\t ", End, String)

open string(+String, -Stream)

True when Stream is an input stream that accesses the content of String. String can be any text
representation, i.e., string, atom, list of codes or list of characters.

5.2.2 Representing text: strings, atoms and code lists

With the introduction of strings as a Prolog data type, there are three main ways to represent text:
using strings, atoms or code lists. This section explains what to choose for what purpose. Both strings
and atoms are atomic objects: you can only look inside them using dedicated predicates. Lists of
character codes are compound datastructures.

Lists of character codes is what you need if you want to parse text using Prolog gram-
mar rules (DCGs, see phrase/3). Most of the text reading predicates (e.g.,
read line to codes/2) return a list of character codes because most applications need
to parse these lines before the data can be processed.
2
Behaviour that is fully compatible would requite unlimited look-ahead.

SWI-Prolog 7.4 Reference Manual

5.2. THE STRING TYPE AND ITS DOUBLE QUOTED SYNTAX 235

Atoms are identifiers. They are typically used in cases where identity comparison is the main oper-
ation and that are typically not composed nor taken apart. Examples are RDF resources (URIs
that identify something), system identifiers (e.g., Boeing 747), but also individual words
in a natural language processing system. They are also used where other languages would use
enumerated types, such as the names of days in the week. Unlike enumerated types, Prolog
atoms do not form not a fixed set and the same atom can represent different things in different
contexts.

Strings typically represents text that is processed as a unit most of the time, but which is not an
identifier for something. Format specifications for format/3 is a good example. Another
example is a descriptive text provided in an application. Strings may be composed and decom-
posed using e.g., string concat/3 and sub string/5 or converted for parsing using
string codes/2 or created from codes generated by a generative grammar rule, also using
string codes/2.

5.2.3 Adapting code for double quoted strings

The predicates in this section can help adapting your program to the new convention for handling
double quoted strings. We have adapted a huge code base with which we were not familiar in about
half a day.

list strings
This predicate may be used to assess compatibility issues due to the representation of double
quoted text as string objects. See section 5.2 and section 5.2.4. To use it, load your program
into Prolog and run list strings/0. The predicate lists source locations of string objects
encountered in the program that are not considered safe. Such string need to be examined
manually, after which one of the actions below may be appropriate:

Rewrite the code. For example, change [X] = "a" into X = 0a.
If a particular module relies heavily on representing strings as lists of character code,
consider adding the following directive to the module. Note that this flag only applies to
the module in which it appears.
:- set_prolog_flag(double_quotes, codes).

Use a back quoted string (e.g., text). Note that this will not make your code run re-
gardless of the --traditional command line option and code exploiting this mapping
is also not portable to ISO compliant systems.
If the strings appear in facts and usage is safe, add a clause to the multifile predicate
check:string predicate/1 to silence list strings/0 on all clauses of that predicate.
If the strings appear as an argument to a predicate that can handle string objects, add a
clause to the multifile predicate check:valid string goal/1 to silence list strings/0.

check:string predicate(:PredicateIndicator)
Declare that PredicateIndicator has clauses that contain strings, but that this is safe. For ex-
ample, if there is a predicate help info/2, where the second argument contains a double
quoted string that is handled properly by the predicates of the applications help system, add
the following declaration to stop list strings/0 from complaining:

SWI-Prolog 7.4 Reference Manual

236 CHAPTER 5. SWI-PROLOG EXTENSIONS

:- multifile check:string_predicate/1.

check:string_predicate(user:help_info/2).

check:valid string goal(:Goal)

Declare that calls to Goal are safe. The module qualification is the actual module in which Goal
is defined. For example, a call to format/3 is resolved by the predicate system:format/3.
and the code below specifies that the second argument may be a string (system predicates that
accept strings are defined in the library).

:- multifile check:valid_string_goal/1.

check:valid_string_goal(system:format(_,S,_)) :- string(S).

5.2.4 Why has the representation of double quoted text changed?

Prolog defines two forms of quoted text. Traditionally, single quoted text is mapped to atoms while
double quoted text is mapped to a list of character codes (integers) or characters represented as 1-
character atoms. Representing text using atoms is often considered inadequate for several reasons:

It hides the conceptual difference between text and program symbols. Where content of text
often matters because it is used in I/O, program symbols are merely identifiers that match with
the same symbol elsewhere. Program symbols can often be consistently replaced, for example
to obfuscate or compact a program.

Atoms are globally unique identifiers. They are stored in a shared table. Volatile strings repre-
sented as atoms come at a significant price due to the required cooperation between threads for
creating atoms. Reclaiming temporary atoms using Atom garbage collection is a costly process
that requires significant synchronisation.

Many Prolog systems (not SWI-Prolog) put severe restrictions on the length of atoms or the
maximum number of atoms.

Representing text as a list of character codes or 1-character atoms also comes at a price:

It is not possible to distinguish (at runtime) a list of integers or atoms from a string. Sometimes
this information can be derived from (implicit) typing. In other cases the list must be embedded
in a compound term to distinguish the two types. For example, s("hello world") could
be used to indicate that we are dealing with a string.
Lacking runtime information, debuggers and the toplevel can only use heuristics to decide
whether to print a list of integers as such or as a string (see portray text/1).
While experienced Prolog programmers have learned to cope with this, we still consider this an
unfortunate situation.

SWI-Prolog 7.4 Reference Manual

5.2. THE STRING TYPE AND ITS DOUBLE QUOTED SYNTAX 237

Lists are expensive structures, taking 2 cells per character (3 for SWI-Prolog in its current form).
This stresses memory consumption on the stacks while pushing them on the stack and dealing
with them during garbage collection is unnecessarilly expensive.

We observe that in many programs, most strings are only handled as a single unit during their life-
time. Examining real code tells us that double quoted strings typically appear in one of the following
roles:

A DCG literal Although represented as a list of codes is the correct representation for handling in
DCGs, the DCG translator can recognise the literal and convert it to the proper representation.
Such code need not be modified.
A format string This is a typical example of text that is conceptually not a program identifier. For-
mat is designed to deal with alternative representations of the format string. Such code need not
be modified.
Getting a character code The construct [X] = "a" is a commonly used template for getting the
character code of the letter a. ISO Prolog defines the syntax 0a for this purpose. Code using
this must be modified. The modified code will run on any ISO compliant processor.
As argument to list predicates to operate on strings Here, we see code such as
append("name:", Rest, Codes). Such code needs to be modi-
fied. In this particular example, the following is a good portable alternative:
phrase("name:", Codes, Rest)
Checks for a character to be in a set Such tests are often performed with code such as this:
memberchk(C, "!@#$"). This is a rather inefficient check in a traditional Prolog sys-
tem because it pushes a list of character codes cell-by-cell the Prolog stack and then traverses
this list cell-by-cell to see whether one of the cells unifies with C. If the test is successful, the
string will eventually be subject to garbage collection. The best code for this is to write a predi-
cate as below, which pushes noting on the stack and performs an indexed lookup to see whether
the character code is in my class.

my_class(0).
my_class(0!).
...

An alternative to reach the same effect is to use term expansion to create the clauses:

term_expansion(my_class(_), Clauses) :-
findall(my_class(C),
string_code(_, "!@#$", C),
Clauses).

my_class(_).

Finally, the predicate string code/3 can be exploited directly as a replacement for the
memberchk/2 on a list of codes. Although the string is still pushed onto the stack, it is more
compact and only a single entity.

SWI-Prolog 7.4 Reference Manual

238 CHAPTER 5. SWI-PROLOG EXTENSIONS

We offer the predicate list strings/0 to help porting your program.

5.3 Syntax changes

5.3.1 Operators and quoted atoms
As of SWI-Prolog version 7, quoted atoms loose their operator property. This means that expressions
such as A = dynamic/1 are valid syntax, regardless of the operator definitions. From questions
on the mailinglist this is what people expect.3 To accomodate for real quoted operators, a quoted atom
that needs quotes can still act as an operator.4 A good use-case for this is a unit library5 , which allows
for expressions such as below.

?- Y isu 600kcal - 1h*200W.

Y = 1790400.0J.

5.3.2 Compound terms with zero arguments

As of SWI-Prolog version 7, the system supports compound terms that have no arguments. This
implies that e.g., name() is valid syntax. This extension aims at functions on dicts (see sec-
tion 5.4) as well as the implementation of domain specific languages (DSLs). To minimise the
consequences, the classic predicates functor/3 and =../2 have not been modified. The predi-
cates compound name arity/3 and compound name arguments/3 have been added. These
predicates operate only on compound terms and behave consistently for compounds with zero argu-
ments. Code that generalises a term using the sequence below should generally be changed to use
compound name arity/3.

...,
functor(Specific, Name, Arity),
functor(General, Name, Arity),
...,

Replacement of =../2 by compound name arguments/3 is typically needed to deal with code
that follow the skeleton below.

...,
Term0 =.. [Name|Args0],
maplist(convert, Args0, Args),
Term =.. [Name|Args],
...,

3
We believe that most users expect an operator declaration to define a new token, which would explain why the operator
name is often quoted in the declaration, but not while the operator is used. We are afraid that allowing for this easily creates
ambiguous syntax. Also, many development environments are based on tokenization. Having dynamic tokenization due to
operator declarations would make it hard to support Prolog in such editors.
4
Suggested by Joachim Schimpf.
5
https://groups.google.com/d/msg/comp.lang.prolog/ozqdzI-gi_g/2G16GYLIS0IJ

SWI-Prolog 7.4 Reference Manual

5.3. SYNTAX CHANGES 239

For predicates, goals and arithmetic functions (evaluable terms), hnamei and hnamei() are equivalent.
Below are some examples that illustrate this behaviour.

go() :- format(Hello worldn).

?- go().
Hello world

?- go.
Hello world

?- Pi is pi().
Pi = 3.141592653589793.

?- Pi is pi.
Pi = 3.141592653589793.

Note that the cannonical representation of predicate heads and functions without arguments is an
atom. Thus, clause(go(), Body) returns the clauses for go/0, but clause(-Head, -Body, +Ref)
unifies Head with an atom if the clause specified by Ref is part of a predicate with zero arguments.

5.3.3 Block operators

Introducing curly bracket and array subscripting.6 The symbols [] and {} may be declared as an
operator, which has the following effect:

[]
This operator is typically declared as a low-priority yf postfix operator, which allows for
array[index] notation. This syntax produces a term []([index],array).

{}
This operator is typically declared as a low-priority xf postfix operator, which
allows for head(arg) { body } notation. This syntax produces a term
{}({body},head(arg)).

Below is an example that illustrates the representation of a typical curly bracket language in
Prolog.

?- op(100, xf, {}).

?- op(100, yf, []).
?- op(1100, yf, ;).

?- displayq(func(arg)
6
Introducing block operators was proposed by Jose Morales. It was discussed in the Prolog standardization mailing list,
but there were too many conflicts with existing extensions (ECLiPSe and B-Prolog) and doubt about their need to reach an
agreement. Increasing need to get to some solution resulted in what is documented in this section. These extensions are also
implemented in recent versions of YAP.

SWI-Prolog 7.4 Reference Manual

240 CHAPTER 5. SWI-PROLOG EXTENSIONS

{ a[10] = 5;
update();
}).
{}({;(=([]([10],a),5),;(update()))},func(arg))

5.4 Dicts: structures with named arguments

SWI-Prolog version 7 introduces dicts as an abstract object with a concrete modern syntax and func-
tional notation for accessing members and as well as access functions defined by the user. The syntax
for a dict is illustrated below. Tag is either a variable or an atom. As with compound terms, there is
no space between the tag and the opening brace. The keys are either atoms or small integers (up to
max tagged integer). The values are arbitrary Prolog terms which are parsed using the same
rules as used for arguments in compound terms.

Tag{Key1:Value1, Key2:Value2, ...}

A dict can not hold duplicate keys. The dict is transformed into an opaque internal representation
that does not respect the order in which the key-value pairs appear in the input text. If a dict is
written, the keys are written according to the standard order of terms (see section 4.7.1). Here are
some examples, where the second example illustrates that the order is not maintained and the third
illustrates an anonymous dict.

?- A = point{x:1, y:2}.
A = point{x:1, y:2}.

?- A = point{y:2, x:1}.
A = point{x:1, y:2}.

?- A = _{first_name:"Mel", last_name:"Smith"}.
A = _G1476{first_name:"Mel", last_name:"Smith"}.

Dicts can be unified following the standard symmetric Prolog unification rules. As dicts use an internal
canonical form, the order in which the named keys are represented is not relevant. This behaviour is
illustrated by the following example.

?- point{x:1, y:2} = Tag{y:2, x:X}.

Tag = point,
X = 1.

Note In the current implementation, two dicts unify only if they have the same set of keys and the tags
and values associated with the keys unify. In future versions, the notion of unification between dicts
could be modified such that two dicts unify if their tags and the values associated with common keys
unify, turning both dicts into a new dict that has the union of the keys of the two original dicts.

SWI-Prolog 7.4 Reference Manual

5.4. DICTS: STRUCTURES WITH NAMED ARGUMENTS 241

5.4.1 Functions on dicts

The infix operator dot (op(100, yfx, .) is used to extract values and evaluate functions on dicts.
Functions are recognised if they appear in the argument of a goal in the source text, possibly nested
in a term. The keys act as field selector, which is illustrated in this example.

?- X = point{x:1,y:2}.x.
X = 1.

?- Pt = point{x:1,y:2}, write(Pt.y).
2
Pt = point{x:1,y:2}.

?- X = point{x:1,y:2}.C.
X = 1,
C = x ;
X = 2,
C = y.

The compiler translates a goal that contains ./2 terms in its arguments into a conjunction of calls to
./3 defined in the system module. Terms functor.2 that appears in the head are replaced with a
variable and calls to ./3 are inserted at the start of the body. Below are two examples, where the
first extracts the x key from a dict and the second extends a dict containing an address with the postal
code, given a find postal code/4 predicate.

dict_x(X, X.x).

add_postal_code(Dict, Dict.put(postal_code, Code)) :-

find_postal_code(Dict.city,
Dict.street,
Dict.house_number,
Code).

Note that expansion of ./2 terms implies that such terms cannot be created by writing them
explicitly in your source code. Such terms can still be created with functor/3, =../2,
compound name arity/3 and compound name arguments/3.7

.(+Dict, +Function, -Result)

This predicate is called to evaluate ./2 terms found in the arguments of a goal. This predicate
evaluates the field extraction described above, which is mapped to get dict ex/3. If
Function is a compound term, it checks for the predefined functions on dicts described in
section 5.4.1 or executes a user defined function as described in section 5.4.1.
7
Traditional code is unlikely to use ./2 terms because they were practically reserved for usage in lists. We do not
provide a quoting mechanism as found in functional languages because it would only be needed to quote ./2 terms, such
terms are rare and term manipulation provides an escape route.

SWI-Prolog 7.4 Reference Manual

242 CHAPTER 5. SWI-PROLOG EXTENSIONS

User defined functions on dicts

The tag of a dict associates the dict to a module. If the dot notation uses a compound term, this calls
the goal below.

hmodulei:hnamei(Arg1, ..., +Dict, -Value)

Functions are normal Prolog predicates. The dict infrastructure provides a more convenient syntax
for representing the head of such predicates without worrying about the argument calling conventions.
The code below defines a function multiply(Times) on a point that creates a new point by multi-
plying both coordinates. and len8 to compute the length from the origin. The . and := operators
are used to abstract the location of the predicate arguments. It is allowed to define multiple a function
with multiple clauses, providing overloading and non-determinism.

:- module(point, []).

M.multiply(F) := point{x:X, y:Y} :-

X is M.x*F,
Y is M.y*F.

M.len() := Len :-
Len is sqrt(M.x**2 + M.y**2).

After these definitions, we can evaluate the following functions:

?- X = point{x:1, y:2}.multiply(2).
X = point{x:2, y:4}.

?- X = point{x:1, y:2}.multiply(2).len().
X = 4.47213595499958.

Predefined functions on dicts

Dicts currently define the following reserved functions:

get(?Key)
Same as Dict.Key, but maps to get dict/3 instead of get dict ex/3. This implies that
the function evaluation fails silently if Key does not appear in Dict. See also :</2, which can
be used to test for existence and unify multiple key values from a dict. For example:

?- write(t{a:x}.get(a)).
x
?- write(t{a:x}.get(b)).
false.

8
as length would result in a predicate length/2, this name cannot be used. This might change in future versions.

SWI-Prolog 7.4 Reference Manual

5.4. DICTS: STRUCTURES WITH NAMED ARGUMENTS 243

put(+New)
Evaluates to a new dict where the key-values in New replace or extend the key-values in the
original dict. See put dict/3.

put(+KeyPath, +Value)
Evaluates to a new dict where the KeyPath-Value replaces or extends the key-values in the
original dict. KeyPath is either a key or a term KeyPath/Key,9 replacing the value associated
with Key in a sub-dict of the dict on which the function operates. See put dict/4. Below
are some examples:

?- A = _{}.put(a, 1).
A = _G7359{a:1}.

?- A = _{a:1}.put(a, 2).
A = _G7377{a:2}.

?- A = _{a:1}.put(b/c, 2).
A = _G1395{a:1, b:_G1584{c:2}}.

?- A = _{a:_{b:1}}.put(a/b, 2).
A = _G1429{a:_G1425{b:2}}.

?- A = _{a:1}.put(a/b, 2).
A = _G1395{a:_G1578{b:2}}.

5.4.2 Predicates for managing dicts

This section documents the predicates that are defined on dicts. We use the naming and argument
conventions of the traditional assoc.

is dict(@Term)
True if Term is a dict. This is the same as is dict(Term, ).

is dict(@Term, -Tag)
True if Term is a dict of Tag.

get dict(?Key, +Dict, -Value)

Unify the value associated with Key in dict with Value. If Key is unbound, all associations
in Dict are returned on backtracking. The order in which the associations are returned is
undefined. This predicate is normally accessed using the functional notation Dict.Key. See
section 5.4.1.

get dict(+Key, +Dict, -Value, -NewDict, +NewValue) [semidet]

Create a new dict after updating the value for Key. Fails if Value does not unify with the current
value associated with Key. Acts according to the following below. Dict is either a dict or a list
the can be converted into a dict.
9
Note that we do not use the . functor here, because the ./2 would evaluate.

SWI-Prolog 7.4 Reference Manual

244 CHAPTER 5. SWI-PROLOG EXTENSIONS

get_dict(Key, Dict, Value, NewDict, NewDict) :-

get_dict(Key, Dict, Value),
put_dict(Key, Dict, NewDict, NewDict).

dict create(-Dict, +Tag, +Data)

Create a dict in Tag from Data. Data is a list of attribute-value pairs using the syntax
Key:Value, Key=Value, Key-Value or Key(Value). An exception is raised if Data is
not a proper list, one of the elements is not of the shape above, a key is neither an atom nor a
small integer or there is a duplicate key.

dict pairs(?Dict, ?Tag, ?Pairs)

Bi-directional mapping between a dict and an ordered list of pairs (see section A.21).

put dict(+New, +DictIn, -DictOut)

DictOut is a new dict created by replacing or adding key-value pairs from New to Dict. New is
either a dict or a valid input for dict create/3. This predicate is normally accessed using
the functional notation. Below are some examples:

?- A = point{x:1, y:2}.put(_{x:3}).
A = point{x:3, y:2}.

?- A = point{x:1, y:2}.put([x=3]).
A = point{x:3, y:2}.

?- A = point{x:1, y:2}.put([x=3,z=0]).
A = point{x:3, y:2, z:0}.

put dict(+Key, +DictIn, +Value, -DictOut)

DictOut is a new dict created by replacing or adding Key-Value to DictIn. This predicate is
normally accessed using the functional notation. Below is an example:

?- A = point{x:1, y:2}.put(x, 3).

A = point{x:3, y:2}.

del dict(+Key, +DictIn, ?Value, -DictOut)

True when Key-Value is in DictIn and DictOut contains all associations of DictIn except for
Key.

+Select :< +From [semidet]

True when Select is a sub dict of From: the tages must unify and all keys in Select must
appear with unifying values in From. From may contain keys that are not in Select. This
operation is frequently used to match a dict and at the same time extract relevant values from
it. For example:

SWI-Prolog 7.4 Reference Manual

5.4. DICTS: STRUCTURES WITH NAMED ARGUMENTS 245

plot(Dict, On) :-
_{x:X, y:Y, z:Z} :< Dict, !,
plot_xyz(X, Y, Z, On).
plot(Dict, On) :-
_{x:X, y:Y} :< Dict, !,
plot_xy(X, Y, On).

The goal Select :< From is equivalent to select dict(Select, From, ).

select dict(+Select, +From, -Rest) [semidet]

True when the tags of Select and From have been unified, all keys in Select appear in From and
the corresponding values have been unified. The key-value pairs of From that do not appear in
Select are used to form an anonymous dict, which us unified with Rest. For example:

?- select_dict(P{x:0, y:Y}, point{x:0, y:1, z:2}, R).

P = point,
Y = 1,
R = _G1705{z:2}.

See also select dict/2 to ignore Rest and >:</2 for a symmetric partial unification of
two dicts.

+Dict1 >:< +Dict2

This operator specifies a partial unification between Dict1 and Dict2. It is true when the tags
and the values associated with all common keys have been unified. The values associated to
keys that do not appear in the other dict are ignored. Partial unification is symmetric. For
example, given a list of dicts, find dicts that represent a point with X equal to zero:

member(Dict, List),
Dict >:< point{x:0, y:Y}.

See also :</2 and select dict/3.

Destructive assignment in dicts

This section describes the destructive update operations defined on dicts. These actions can only
update keys and not add or remove keys. If the requested key does not exist the predicate raises
existence error(key, Key, Dict). Note the additional argument.
Destructive assignment is a non-logical operation and should be used with care because the system
may copy or share identical Prolog terms at any time. Some of this behaviour can be avoided by
adding an additional unbound value to the dict. This prevents unwanted sharing and ensures that
copy term/2 actually copies the dict. This pitfall is demonstrated in the example below:

?- A = a{a:1}, copy_term(A,B), b_set_dict(a, A, 2).

A = B, B = a{a:2}.

SWI-Prolog 7.4 Reference Manual

246 CHAPTER 5. SWI-PROLOG EXTENSIONS

?- A = a{a:1,dummy:_}, copy_term(A,B), b_set_dict(a, A, 2).

A = a{a:2, dummy:_G3195},
B = a{a:1, dummy:_G3391}.

b set dict(+Key, !Dict, +Value) [det]

Destructively update the value associated with Key in Dict to Value. The update is trailed and
undone on backtracking. This predicate raises an existence error if Key does not appear in Dict.
The update semantics are equivalent to setarg/3 and b setval/2.

nb set dict(+Key, !Dict, +Value) [det]

Destructively update the value associated with Key in Dict to a copy of Value. The update is
not undone on backtracking. This predicate raises an existence error if Key does not appear in
Dict. The update semantics are equivalent to nb setarg/3 and nb setval/2.

nb link dict(+Key, !Dict, +Value) [det]

Destructively update the value associated with Key in Dict to Value. The update is not undone
on backtracking. This predicate raises an existence error if Key does not appear in Dict. The
update semantics are equivalent to nb linkarg/3 and nb linkval/2. Use with extreme
care and consult the documentation of nb linkval/2 before use.

5.4.3 When to use dicts?

Dicts are a new type in the Prolog world. They compete with several other types and libraries. In
the list below we have a closer look at these relations. We will see that dicts are first of all a good
replacement for compound terms with a high or not clearly fixed arity, library record and option
processing.

Compound terms Compound terms with positional arguments form the traditional way to package
data in Prolog. This representation is well understood, fast and compound terms are stored
efficiently. Compound terms are still the representation of choice, provided that the number of
arguments is low and fixed or compactness or performance are of utmost importance.
A good example of a compound term is the representation of RDF triples using the term
rdf(Subject, Predicate, Object) because RDF triples are defined to have precisely these three
arguments and they are always referred to in this order. An application processing information
about persons should probably use dicts because the information that is related to a person is not
so fixed. Typically we see first and last name. But there may also be title, middle name, gender,
date of birth, etc. The number of arguments becomes unmanagable when using a compound
term, while adding or removing an argument leads to many changes in the program.

Library record Using library record relieves the maintenance issues associated with using com-
pound terms significantly. The library generates access and modification predicates for each
field in a compound term from a declaration. The library provides sound access to compound
terms with many arguments. One of its problems is the verbose syntax needed to access or
modify fields which results from long names for the generated predicates and the restriction
that each field needs to be extracted with a separate goal. Consider the example below, where
the first uses library record and the second uses dicts.

SWI-Prolog 7.4 Reference Manual

5.4. DICTS: STRUCTURES WITH NAMED ARGUMENTS 247

...,
person_first_name(P, FirstName),
person_last_name(P, LastName),
format(Dear w w,nn, [FirstName, LastName]).

...,
format(Dear w w,nn, [Dict.first_name, Dict.last_name]).

Records have a fixed number of arguments and (non-)existence of an argument must be rep-
resented using a value that is outside the normal domain. This lead to unnatural code. For
example, suppose our person also has a title. If we know the first name we use this and else we
use the title. The code samples below illustrate this.

salutation(P) :-
person_first_name(P, FirstName), nonvar(FirstName), !,
person_last_name(P, LastName),
format(Dear w w,nn, [FirstName, LastName]).
salutation(P) :-
person_title(P, Title), nonvar(Title), !,
person_last_name(P, LastName),
format(Dear w w,nn, [Title, LastName]).

salutation(P) :-
_{first_name:FirstName, last_name:LastName} :< P, !,
format(Dear w w,nn, [FirstName, LastName]).
salutation(P) :-
_{title:Title, last_name:LastName} :< P, !,
format(Dear w w,nn, [Title, LastName]).

Library assoc This library implements a balanced binary tree. Dicts can replace the use of this
library if the association is fairly static (i.e., there are few update operations), all keys are atoms
or (small) integers and the code does not rely on ordered operations.

Library option Option lists are introduced by ISO Prolog, for example for read term/3,
open/4, etc. The option library provides operations to extract options, merge options lists,
etc. Dicts are well suited to replace option lists because they are cheaper, can be processed
faster and have a more natural syntax.

Library pairs This library is commonly used to process large name-value associations. In many
cases this concerns short-lived datastructures that result from findall/3, maplist/3 and
similar list processing predicates. Dicts may play a role if frequent random key lookups
are needed on the resulting association. For example, the skeleton create a pairs list, use
list to assoc/2 to create an assoc, followed by frequent usage of get assoc/3 to ex-
tract key values can be replaced using dict pairs/3 and the dict access functions. Using
dicts in this scenario is more efficient and provides a more pleasant access syntax.

SWI-Prolog 7.4 Reference Manual

248 CHAPTER 5. SWI-PROLOG EXTENSIONS

5.4.4 A motivation for dicts as primary citizens

Dicts, or key-value associations, are a common data structure. A good old example are property lists
as found in Lisp, while a good recent example is formed by JavaScript objects. Traditional Prolog
does not offer native property lists. As a result, people are using a wide range of data structures for
key-value associations:

Using compound terms and positional arguments, e.g., point(1,2).

Using compound terms with library record, which generates access predicates for a term
using positional arguments from a description.

Using lists of terms Name=Value, Name-Value, Name:Value or Name(Value).

Using library assoc which represents the associations as a balanced binary tree.

This situation is unfortunate. Each of these have their advantages and disadvantages. E.g., com-
pound terms are compact and fast, but inflexible and using positional arguments quickly breaks down.
Library record fixes this, but the syntax is considered hard to use. Lists are flexible, but expensive
and the alternative key-value representations that are used complicate the matter even more. Library
assoc allows for efficient manipulation of changing associations, but the syntactical representation
of an assoc is complex, which makes them unsuitable for e.g., options lists as seen in predicates such
as open/4.

5.4.5 Implementation notes about dicts

Although dicts are designed as an abstract data type and we deliberately reserve the possibility to
change the representation and even use multiple representations, this section describes the current
implementation.
Dicts are currently represented as a compound term using the functor dict. The first argument
is the tag. The remaining arguments create an array of sorted key-value pairs. This representation is
compact and guarantees good locality. Lookup is order log N , while adding values, deleting values
and merging with other dicts has order N . The main disadvantage is that changing values in large
dicts is costly, both in terms of memory and time.
Future versions may share keys in a separate structure or use a binary trees to allow for cheaper
updates. One of the issues is that the representation must either be kept cannonical or unification must
be extended to compensate for alternate representations.

5.5 Integration of strings and dicts in the libraries

While lacking proper string support and dicts when designed, many predicates and libraries use inter-
faces that must be classified as suboptimal. Changing these interfaces is likely to break much more
code than the changes described in this chapter. This section discusses some of these issues. Roughly,
there are two cases. There where key-value associations or text is required as input, we can facilitate
the new features by overloading the accepted types. Interfaces that produce text or key-value associ-
ations as their output however must make a choice. We plan to resolve that using either options that
specify the desired output or provide an alternative library.

SWI-Prolog 7.4 Reference Manual

5.5. INTEGRATION OF STRINGS AND DICTS IN THE LIBRARIES 249

5.5.1 Dicts and option processing

System predicates and predicates based on library options process dicts as an alternative to tradi-
tional option lists.

5.5.2 Dicts in core data structures

Some predicates now produce structured data using compound terms and access predicates. We con-
sider migrating these to dicts. Below is a tentative list of candidates. Portable code should use the
provided access predicates and not rely on the term representation.

Stream position terms

Date and time records

5.5.3 Dicts, strings and XML

The XML representation could benefit significantly from the new features. In due time we plan to
provide an set of alternative predicates and options to existing predicates that can be used to exploit
the new types. We propose the following changes to the data representation:

The attribute list of the element(Name, Attributes, Content) will become a dict.
Attribute values will remain atoms
CDATA in element content will be represented as strings

5.5.4 Dicts, strings and JSON

The JSON representation could benefit significantly from the new features. In due time we plan to
provide an set of alternative predicates and options to existing predicates that can be used to exploit
the new types. We propose the following changes to the data representation:

Instead of using json(KeyValueList), the new interface will translate JSON objects to a dict.
The type of this dict will be json.
String values in JSON will be mapped to strings.
The values true, false and null will be represented as atoms.

5.5.5 Dicts, strings and HTTP

The HTTP library and related data structures would profit from exploiting dicts. Below is a list of
data structures that might be affected by future changes. Code can be made more robust by using the
option library functions for extracting values from these structures.

The HTTP request structure

The HTTP parameter interface
URI components
Attributes to HTML elements

SWI-Prolog 7.4 Reference Manual

250 CHAPTER 5. SWI-PROLOG EXTENSIONS

5.6 Remaining issues

The changes and extensions described in this chapter resolve a many limitations of the Prolog language
we have encountered. Still, there are remaining issues for which we seek solutions in the future.

Text representation Although strings resolve this issue for many applications, we are still faced
with the representation of text as lists of characters which we need for parsing using DCGs. The
ISO standard provides two representations, a list of character codes (codes for short) and a list
of one-character atoms (chars for short). There are two sets of predicates, named * code(s) and
* char(s) that provide the same functionality (e.g., atom codes/2 and atom chars/2) using
their own representation of characters. Codes can be used in arithmetic expressions, while chars are
more readable. Neither can unambiguously be interpreted as a representation for text because codes
can be interpreted as a list of integers and chars as a list of atoms.
We have not found a convincing way out. One of the options could be the introduction of a char
type. This type can be allowed in arithmetic and with the 0char syntax we have a concrete syntax
for it.

Arrays Although lists are generally a much cleaner alternative for Prolog, real arrays with direct
access to elements can be useful for particular tasks. The problem of integrating arrays is twofold.
First of all, there is no good one-size-fits-all data representation for arrays. Many tasks that involve
arrays require mutable arrays, while Prolog data is immutable by design. Second, standard Prolog
has no good syntax support for arrays. SWI-Prolog version 7 has block operators (see section 5.3.3)
which can resolve the syntactic issues. Block operators have been adopted by YAP.

Lambda expressions Although many alternatives10 have been proposed, we still feel uneasy with
them.

Loops Many people have explored routes to avoid the need for recursion in Prolog for simple iter-
ations over data. ECLiPSe have proposed logical loops [Schimpf, 2002], while B-Prolog introduced
declarative loops and list comprehension11 . The above mentioned lambda expressions, combined with
maplist/2 can achieve similar results.

10
See e.g., http://www.complang.tuwien.ac.at/ulrich/Prolog-inedit/ISO-Hiord
11
http://www.probp.com/download/loops.pdf

SWI-Prolog 7.4 Reference Manual

Modules 6
A Prolog module is a collection of predicates which defines a public interface by means of a set of
provided predicates and operators. Prolog modules are defined by an ISO standard. Unfortunately,
the standard is considered a failure and, as far as we are aware, not implemented by any concrete
Prolog implementation. The SWI-Prolog module system syntax is derived from the Quintus Prolog
module system. The Quintus module system has been the starting point for the module systems of
a number of mainstream Prolog systems, such as SICStus, Ciao and YAP. The underlying primitives
of the SWI-Prolog module system differ from the mentioned systems. These primitives allow for
multiple modules in a file, hierarchical modules, emulation of other modules interfaces, etc.
This chapter motivates and describes the SWI-Prolog module system. Novices can start using
the module system after reading section 6.2 and section 6.3. The primitives defined in these sections
suffice for basic usage until one needs to export predicates that call or manage other predicates dy-
namically (e.g., use call/1, assert/1, etc.). Such predicates are called meta predicates and are
discussed in section 6.4. Section 6.5 to section 6.8 describe more advanced issues. Starting with
section 6.9, we discuss more low-level aspects of the SWI-Prolog module system that are used to
implement the visible module system, and can be used to build other code reuse mechanisms.

6.1 Why Use Modules?

In classic Prolog systems, all predicates are organised in a single namespace and any predicate can
call any predicate. Because each predicate in a file can be called from anywhere in the program, it
becomes very hard to find the dependencies and enhance the implementation of a predicate without
risking to break the overall application. This is true for any language, but even worse for Prolog due
to its frequent need for helper predicates.
A Prolog module encapsulates a set of predicates and defines an interface. Modules can import
other modules, which makes the dependencies explicit. Given explicit dependencies and a well-
defined interface, it becomes much easier to change the internal organisation of a module without
breaking the overall application.
Explicit dependencies can also be used by the development environment. The SWI-Prolog library
prolog xref can be used to analyse completeness and consistency of modules. This library is used
by the built-in editor PceEmacs for syntax highlighting, jump-to-definition, etc.

6.2 Defining a Module

Modules are normally created by loading a module file. A module file is a file holding a module/2
directive as its first term. The module/2 directive declares the name and the public (i.e., externally
visible) predicates of the module. The rest of the file is loaded into the module. Below is an example

SWI-Prolog 7.4 Reference Manual

252 CHAPTER 6. MODULES

of a module file, defining reverse/2 and hiding the helper predicate rev/3. A module can use all
built-in predicates and, by default, cannot redefine system predicates.

:- module(reverse, [reverse/2]).

reverse(List1, List2) :-
rev(List1, [], List2).

rev([], List, List).

rev([Head|List1], List2, List3) :-
rev(List1, [Head|List2], List3).

The module is named reverse. Typically, the name of a module is the same as the name of the file
by which it is defined without the filename extension, but this naming is not enforced. Modules are
organised in a single and flat namespace and therefore module names must be chosen with some care
to avoid conflicts. As we will see, typical applications of the module system rarely use the name of a
module explicitly in the source text.

:- module(+Module, +PublicList)
This directive can only be used as the first term of a source file. It declares the file to be
a module file, defining a module named Module. Note that a module name is an atom.
The module exports the predicates of PublicList. PublicList is a list of predicate indicators
(name/arity or name//arity pairs) or operator declarations using the format op(Precedence,
Type, Name). Operators defined in the export list are available inside the module as well as to
modules importing this module. See also section 4.25.
Compatible to Ciao Prolog, if Module is unbound, it is unified with the basename without
extension of the file being loaded.

:- module(+Module, +PublicList, +Dialect)

Same as module/2. The additional Dialect argument provides a list of language options.
Each atom in the list Dialect is mapped to a use module/1 goal as given below. See also
section C. The third argument is supported for compatibility with the Prolog Commons project.

:- use_module(library(dialect/LangOption)).

6.3 Importing Predicates into a Module

Predicates can be added to a module by importing them from another module. Importing adds pred-
icates to the namespace of a module. An imported predicate can be called exactly the same as a
locally defined predicate, although its implementation remains part of the module in which it has been
defined.
Importing the predicates from another module is achieved using the directives use module/1
or use module/2. Note that both directives take filename(s) as arguments. That is, modules are
imported based on their filename rather than their module name.

SWI-Prolog 7.4 Reference Manual

6.3. IMPORTING PREDICATES INTO A MODULE 253

use module(+Files)
Load the file(s) specified with Files just like ensure loaded/1. The files must all be module
files. All exported predicates from the loaded files are imported into the module from which
this predicate is called. This predicate is equivalent to ensure loaded/1, except that it
raises an error if Files are not module files.
The imported predicates act as weak symbols in the module into which they are imported. This
implies that a local definition of a predicate overrides (clobbers) the imported definition. If the
flag warn override implicit import is true (default), a warning is printed. Below
is an example of a module that uses library(lists), but redefines flatten/2, giving it a totally
different meaning:

:- module(shapes, []).
:- use_module(library(lists)).

flatten(cube, square).
flatten(ball, circle).

Loading the above file prints the following message:

Warning: /home/janw/Bugs/Import/t.pl:5:
Local definition of shapes:flatten/2
overrides weak import from lists

This warning can be avoided by (1) using use module/2 to only import the
predicates from the lists library that are actually used in the shapes mod-
ule, (2) using the except([flatten/2]) option of use module/2, (3)
use :- abolish(flatten/2). before the local definition or (4) setting
warn override implicit import to false. Globally disabling this warning is
only recommended if overriding imported predicates is common as a result of design choices
or the program is ported from a system that silently overrides imported predicates.
Note that it is always an error to import two modules with use module/1 that export the
same predicate. Such conflicts must be resolved with use module/2 as described above.

use module(+File, +ImportList)

Load File, which must be a module file, and import the predicates as specified by ImportList.
ImportList is a list of predicate indicators specifying the predicates that will be imported from
the loaded module. ImportList also allows for renaming or import-everything-except. See
also the import option of load files/2. The first example below loads member/2
from the lists library and append/2 under the name list concat, which is how this
predicate is named in YAP. The second example loads all exports from library option except
for meta options/3. These renaming facilities are generally used to deal with portability
issues with as few changes as possible to the actual code. See also section C and section 6.7.

:- use_module(library(lists), [ member/2,
append/2 as list_concat

SWI-Prolog 7.4 Reference Manual

254 CHAPTER 6. MODULES

]).
:- use_module(library(option), except([meta_options/3])).

In most cases a module is imported because some of its predicates are being used. However,
sometimes a module is imported for other reasons, e.g., for its declarations. In such cases it is best
practice to use use module/2 with empty ImportList. This distinguishes an imported module that
is used, although not for its predicates, from a module that is needlessly imported.
The module/2, use module/1 and use module/2 directives are sufficient to partition a
simple Prolog program into modules. The SWI-Prolog graphical cross-referencing tool gxref/0
can be used to analyse the dependencies between non-module files and propose module declarations
for each file.

6.4 Defining a meta-predicate

A meta-predicate is a predicate that calls other predicates dynamically, modifies a predicate, or reasons
about properties of a predicate. Such predicates use either a compound term or a predicate indica-
tor to describe the predicate they address, e.g., assert(name(jan)) or abolish(name/1).
With modules, this simple schema no longer works as each module defines its own mapping
from name+arity to predicate. This is resolved by wrapping the original description in a term
hmodulei:htermi, e.g., assert(person:name(jan)) or abolish(person:name/1).
Of course, when calling assert/1 from inside a module, we expect to assert to a predicate
local to this module. In other words, we do not wish to provide this :/2 wrapper by hand. The
meta predicate/1 directive tells the compiler that certain arguments are terms that will be used
to look up a predicate and thus need to be wrapped (qualified) with hmodulei:htermi, unless they are
already wrapped.
In the example below, we use this to define maplist/3 inside a module. The argument 2 in the
meta predicate declaration means that the argument is module-sensitive and refers to a predicate with
an arity that is two more than the term that is passed in. The compiler only distinguishes the values
0..9 and :, which denote module-sensitive arguments, from +, - and ?, which denote modes. The
values 0..9 are used by the cross-referencer and syntax highlighting. Note that the helper predicate
maplist /3 does not need to be declared as a meta-predicate because the maplist/3 wrapper
already ensures that Goal is qualified as hmodulei:Goal. See the description of meta predicate/1
for details.

:- module(maplist, [maplist/3]).
:- meta_predicate maplist(2, ?, ?).

%% maplist(:Goal, +List1, ?List2)

%
% True if Goal can successfully be applied to all
% successive pairs of elements from List1 and List2.

maplist(Goal, L1, L2) :-

maplist_(L1, L2, Goal).

maplist_([], [], _).

SWI-Prolog 7.4 Reference Manual

6.4. DEFINING A META-PREDICATE 255

maplist_([H0|T0], [H|T], Goal) :-

call(Goal, H0, H),
maplist_(T0, T, Goal).

meta predicate +Head, . . .

Define the predicates referenced by the comma-separated list Head as meta-predicates. Each
argument of each head is a meta argument specifier. Defined specifiers are given below. Only
0..9, : and are interpreted; the mode declarations +, - and ? are ignored.

0..9
The argument is a term that is used to reference a predicate with N more arguments than
the given argument term. For example: call(0) or maplist(1, +).
:
The argument is module-sensitive, but does not directly refer to a predicate. For example:
consult(:).
-
The argument is not module-sensitive and unbound on entry.
?
The argument is not module-sensitive and the mode is unspecified.
*
The argument is not module-sensitive and the mode is unspecified. The specifica-
tion * is equivalent to ?. It is accepted for compatibility reasons. The predicate
predicate property/2 reports arguments declared using * with ?.
+
The argument is not module-sensitive and bound (i.e., nonvar) on entry.

This extension is used to denote the possibly -annotated goal of setof/3, bagof/3,
aggregate/3 and aggregate/4. It is processed similar to 0, but leaving the /2
intact.
//
The argument is a DCG body. See phrase/3.

Each argument that is module-sensitive (i.e., marked 0..9, : or ) is qualified with the context
module of the caller if it is not already qualified. The implementation ensures that the argument
is passed as hmodulei:htermi, where hmodulei is an atom denoting the name of a module and
htermi itself is not a :/2 term where the first argument is an atom. Below is a simple declaration
and a number of queries.

:- meta_predicate
meta(0, +).

meta(Module:Term, _Arg) :-
format(Module=w, Term = qn, [Module, Term]).

SWI-Prolog 7.4 Reference Manual

256 CHAPTER 6. MODULES

?- meta(test, x).
Module=user, Term = test
?- meta(m1:test, x).
Module=m1, Term = test
?- m2:meta(test, x).
Module=m2, Term = test
?- m1:meta(m2:test, x).
Module=m2, Term = test
?- meta(m1:m2:test, x).
Module=m2, Term = test
?- meta(m1:42:test, x).
Module=42, Term = test

The meta predicate/1 declaration is the portable mechanism for defining meta-predicates
and replaces the old SWI-Prolog specific mechanism provided by the deprecated predicates
module transparent/1, context module/1 and strip module/3. See also sec-
tion 6.15.

6.5 Overruling Module Boundaries

The module system described so far is sufficient to distribute programs over multiple modules. There
are, however, cases in which we would like to be able to overrule this schema and explicitly call
a predicate in some module or assert explicitly into some module. Calling in a particular module
is useful for debugging from the users top level or to access multiple implementations of the same
interface that reside in multiple modules. Accessing the same interface from multiple modules cannot
be achieved using importing because importing a predicate with the same name and arity from two
modules results in a name conflict. Asserting in a different module can be used to create models
dynamically in a new module. See section 6.12.
Direct addressing of modules is achieved using a :/2 explicitly in a program and relies on the
module qualification mechanism described in section 6.4. Here are a few examples:

?- assert(world:done). % asserts done/0 into module world

?- world:asserta(done). % the same
?- world:done. % calls done/0 in module world

Note that the second example is the same due to the Prolog flag colon sets calling context.
The system predicate asserta/1 is called in the module world, which is possible because system
predicates are visible in all modules. At the same time, the calling context is set to world. Because
meta arguments are qualified with the calling context, the resulting call is the same as the first example.

6.5.1 Explicit manipulation of the calling context

Quintus derived module systems have no means to separate the lookup module (for finding predi-
cates) from the calling context (for qualifying meta arguments). Some other Prolog implementations
(e.g., ECLiPSe and IF/Prolog) distinguish these operations, using @/2 for setting the calling context
of a goal. This is provided by SWI-Prolog, currently mainly to support compatibility layers.

SWI-Prolog 7.4 Reference Manual

6.6. INTERACTING WITH MODULES FROM THE TOP LEVEL 257

@(:Goal, +Module)
Execute Goal, setting the calling context to Module. Setting the calling context affects meta-
predicates, for which meta arguments are qualified with Module and transparent predicates (see
module transparent/1). It has no implications for other predicates.
For example, the code asserta(done)@world is the same as asserta(world:done).
Unlike in world:asserta(done), asserta/1 is resolved in the current module rather
than the module world. This makes no difference for system predicates, but usually does make
a difference for user predicates.
Not that SWI-Prolog does not define @ as an operator. Some systems define this construct using
op(900, xfx, @).

6.6 Interacting with modules from the top level

Debugging often requires interaction with predicates that reside in modules: running them, setting spy
points on them, etc. This can be achieved using the hmodulei:htermi construct explicitly as described
above. In SWI-Prolog, you may also wish to omit the module qualification. Setting a spy point
(spy/1) on a plain predicate sets a spy point on any predicate with that name in any module. Editing
(edit/1) or calling an unqualified predicate invokes the DWIM (Do What I Mean) mechanism,
which generally suggests the correct qualified query.
Mainly for compatibility, we provide module/1 to switch the module with which the interactive
top level interacts:

module(+Module)
The call module(Module) may be used to switch the default working module for the inter-
active top level (see prolog/0). This may be used when debugging a module. The example
below lists the clauses of file of label/2 in the module tex.

1 ?- module(tex).
true.
tex: 2 ?- listing(file_of_label/2).
...

6.7 Composing modules from other modules

The predicates in this section are intended to create new modules from the content of other mod-
ules. Below is an example to define a composite module. The example exports all public pred-
icates of module 1, module 2 and module 3, pred/1 from module 4, all predicates from
module 5 except do not use/1 and all predicates from module 6 while renaming pred/1
into mypred/1.

:- module(my_composite, []).
:- reexport([ module_1,
module_2,
module_3
]).

SWI-Prolog 7.4 Reference Manual

258 CHAPTER 6. MODULES

:- reexport(module_4, [ pred/1 ]).

:- reexport(module_5, except([do_not_use/1])).
:- reexport(module_6, except([pred/1 as mypred])).

reexport(+Files)
Load and import predicates as use module/1 and re-export all imported predicates. The
reexport declarations must immediately follow the module declaration.

reexport(+File, +Import)
Import from File as use module/2 and re-export the imported predicates. The reexport
declarations must immediately follow the module declaration.

6.8 Operators and modules

Operators (section 4.25) are local to modules, where the initial table behaves as if it is copied
from the module user (see section 6.10). A specific operator can be disabled inside a mod-
ule using :- op(0, Type, Name). Inheritance from the public table can be restored using
:- op(-1, Type, Name).
In addition to using the op/3 directive, operators can be declared in the module/2 directive as
shown below. Such operator declarations are visible inside the module, and importing such a module
makes the operators visible in the target module. Exporting operators is typically used by modules
that implement sub-languages such as chr (see chapter 8). The example below is copied from the
library clpfd.

:- module(clpfd,
[ op(760, yfx, #<==>),
op(750, xfy, #==>),
op(750, yfx, #<==),
op(740, yfx, #\/),
...
(#<==>)/2,
(#==>)/2,
(#<==)/2,
(#\/)/2,
...
]).

6.9 Dynamic importing using import modules

Until now we discussed the public module interface that is, at least to some extent, portable between
Prolog implementations with a module system that is derived from Quintus Prolog. The remainder of
this chapter describes the underlying mechanisms that can be used to emulate other module systems
or implement other code-reuse mechanisms.

SWI-Prolog 7.4 Reference Manual

6.10. RESERVED MODULES AND USING THE USER MODULE 259

In addition to built-in predicates, imported predicates and locally defined predicates, SWI-Prolog
modules can also call predicates from its import modules. Each module has a (possibly empty) list of
import modules. In the default setup, each new module has a single import module, which is user
for all normal user modules and system for all system library modules. Module user imports from
system where all built-in predicates reside. These special modules are described in more detail in
section 6.10.
The list of import modules can be manipulated and queried using the following predicates, as well
as using set module/1.

import module(+Module, -Import) [nondet]

True if Module inherits directly from Import. All normal modules only import from
user, which imports from system. The predicates add import module/3 and
delete import module/2 can be used to manipulate the import list. See also
default module/2.
default module(+Module, -Default) [multi]
True if predicates and operators in Default are visible in Module. Modules are returned in
the same search order used for predicates and operators. That is, Default is first unified with
Module, followed by the depth-first transitive closure of import module/2.
add import module(+Module, +Import, +StartOrEnd)
If Import is not already an import module for Module, add it to this list at the start or end
depending on StartOrEnd. See also import module/2 and delete import module/2.
delete import module(+Module, +Import)
Delete Import from the list of import modules for Module. Fails silently if Import is not in the
list.

One usage scenario of import modules is to define a module that is a copy of another, but where
one or more predicates have an alternative definition.

6.10 Reserved Modules and using the user module

As mentioned above, SWI-Prolog contains two special modules. The first one is the module system.
This module contains all built-in predicates. Module system has no import module. The second
special module is the module user. This module forms the initial working space of the user. Initially
it is empty. The import module of module user is system, making all built-in predicates available.
All other modules import from the module user. This implies they can use all predicates im-
ported into user without explicitly importing them. If an application loads all modules from the
user module using use module/1, one achieves a scoping system similar to the C-language,
where every module can access all exported predicates without any special precautions.

6.11 An alternative import/export interface

The use module/1 predicate from section 6.3 defines import and export relations based on the
filename from which a module is loaded. If modules are created differently, such as by asserting
predicates into a new module as described in section 6.12, this interface cannot be used. The interface
below provides for import/export from modules that are not created using a module file.

SWI-Prolog 7.4 Reference Manual

260 CHAPTER 6. MODULES

export(+PredicateIndicator, . . . )
Add predicates to the public list of the context module. This implies the predicate will be
imported into another module if this module is imported with use module/[1,2]. Note
that predicates are normally exported using the directive module/2. export/1 is meant to
handle export from dynamically created modules.

import(+PredicateIndicator, . . . )
Import predicates PredicateIndicator into the current context module. PredicateIndicator must
specify the source module using the hmodulei:hpii construct. Note that predicates are normally
imported using one of the directives use module/[1,2]. The import/1 alternative
is meant for handling imports into dynamically created modules. See also export/1 and
export list/2.

6.12 Dynamic Modules

So far, we discussed modules that were created by loading a module file. These modules have been
introduced to facilitate the development of large applications. The modules are fully defined at load-
time of the application and normally will not change during execution. Having the notion of a set of
predicates as a self-contained world can be attractive for other purposes as well. For example, assume
an application that can reason about multiple worlds. It is attractive to store the data of a particular
world in a module, so we extract information from a world simply by invoking goals in this world.
Dynamic modules can easily be created. Any built-in predicate that tries to locate a predicate in a
specific module will create this module as a side-effect if it did not yet exist. For example:

?- assert(world_a:consistent),
set_prolog_flag(world_a:unknown, fail).

These calls create a module called world a and make the call world a:consistent succeed. Unde-
fined predicates will not raise an exception for this module (see unknown).
Import and export from a dynamically created world can be achieved using import/1 and
export/1 or by specifying the import module as described in section 6.9.

?- world_b:export(solve/2). % exports solve/2 from world_b

?- world_c:import(world_b:solve/2). % and import it to world_c

6.13 Transparent predicates: definition and context module

The module-transparent mechanism is still underlying the actual implementation. Direct usage by
programmers is deprecated. Please use meta predicate/1 to deal with meta-predicates.
The qualification of module-sensitive arguments described in section 6.4 is realised using trans-
parent predicates. It is now deprecated to use this mechanism directly. However, studying the un-
derlying mechanism helps to understand SWI-Prologs modules. In some respect, the transparent
mechanism is more powerful than meta-predicate declarations.

SWI-Prolog 7.4 Reference Manual

6.13. TRANSPARENT PREDICATES: DEFINITION AND CONTEXT MODULE 261

Each predicate of the program is assigned a module, called its definition module. The definition
module of a predicate is always the module in which the predicate was originally defined. Each active
goal in the Prolog system has a context module assigned to it.
The context module is used to find predicates for a Prolog term. By default, the context module
is the definition module of the predicate running the goal. For transparent predicates, however, this
is the context module of the goal inherited from the parent goal. Below, we implement maplist/3
using the transparent mechanism. The code of maplist/3 and maplist /3 is the same as in
section 6.4, but now we must declare both the main predicate and the helper as transparent to avoid
changing the context module when calling the helper.

:- module(maplist, maplist/3).

:- module_transparent
maplist/3,
maplist_/3.

maplist(Goal, L1, L2) :-

maplist_(L1, L2, G).

maplist_([], [], _).

maplist_([H0|T0], [H|T], Goal) :-
call(Goal, H0, H),
maplist_(T0, T, Goal).

Note that any call that translates terms into predicates is subject to the transparent mechanism, not
just the terms passed to module-sensitive arguments. For example, the module below counts the
number of unique atoms returned as bindings for a variable. It works as expected. If we use the
directive :- module transparent count atom results/3. instead, atom result/2
is called wrongly in the module calling count atom results/3. This can be solved using
strip module/3 to create a qualified goal and a non-transparent helper predicate that is defined in
the same module.

:- module(count_atom_results,
[ count_atom_results/3
]).
:- meta_predicate count_atom_results(-,0,-).

count_atom_results(A, Goal, Count) :-

setof(A, atom_result(A, Goal), As), !,
length(As, Count).
count_atom_results(_, _, 0).

atom_result(Var, Goal) :-
call(Goal),
atom(Var).

The following predicates support the module-transparent interface:

SWI-Prolog 7.4 Reference Manual

262 CHAPTER 6. MODULES

:- module transparent(+Preds)
Preds is a comma-separated list of name/arity pairs (like dynamic/1). Each goal associated
with a transparent-declared predicate will inherit the context module from its parent goal.

context module(-Module)
Unify Module with the context module of the current goal. context module/1 itself is, of
course, transparent.

strip module(+Term, -Module, -Plain)

Used in module-transparent predicates or meta-predicates to extract the referenced module and
plain term. If Term is a module-qualified term, i.e. of the format Module:Plain, Module and
Plain are unified to these values. Otherwise, Plain is unified to Term and Module to the context
module.

6.14 Module properties

The following predicates can be used to query the module system for reflexive programming:

current module(?Module) [nondet]

True if Module is a currently defined module. This predicate enumerates all modules, whether
loaded from a file or created dynamically. Note that modules cannot be destroyed in the current
version of SWI-Prolog.

module property(?Module, ?Property)

True if Property is a property of Module. Defined properties are:

class(-Class)
True when Class is the class of the module. Defined classes are
user
Default for user-defined modules.
system
Module system and modules from hhomei/boot.
library
Other modules from the system directories.
temporary
Module is temporary.
test
Modules that create tests.
development
Modules that only support the development environment.
file(?File)
True if Module was loaded from File.
line count(-Line)
True if Module was loaded from the N-th line of file.

SWI-Prolog 7.4 Reference Manual

6.15. COMPATIBILITY OF THE MODULE SYSTEM 263

exports(-ListOfPredicateIndicators)
True if Module exports the given predicates. Predicate indicators are in canonical
form (i.e., always using name/arity and never the DCG form name//arity). Fu-
ture versions may also use the DCG form and include public operators. See also
predicate property/2.
exported operators(-ListOfOperators)
True if Module exports the given operators. Each exported operator is represented as a
term op(Pri,Assoc,Name).
program size(-Bytes)
Memory (in bytes) used for storing the predicates of this module. This figure includes
the predicate header and clauses. Future versions might give a more precise number,
including e.g., the clause index tables.
program space(-Bytes)
If present, this number limits the program size. See set module/1.

set module(:Property)
Modify properties of the module. Currently, the following properties may be modified:

base(+Base)
Set the default import module of the current module to Module. Typically, Module is one
of user or system. See section 6.9.
class(+Class)
Set the class of the module. See module property/2.
program space(+Bytes)
Maximum amount of memory used to store the predicates defined inside the module.
Raises a permission error if the current usage is above the requested limit. Setting the
limit to 0 (zero) removes the limit. An attempt to assert clauses that causes the limit to
be exceeded causes a resource error(program space) exception. See assertz/1
and module property/2.

6.15 Compatibility of the Module System

The SWI-Prolog module system is largely derived from the Quintus Prolog module system, which
is also adopted by SICStus, Ciao and YAP. Originally, the mechanism for defining meta-predicates
in SWI-Prolog was based on the module transparent/1 directive and strip module/3.
Since 5.7.4 it supports the de-facto standard meta predicate/1 directive for implementing meta-
predicates, providing much better compatibility.
The support for the meta predicate/1 mechanism, however, is considerably different.
On most systems, the caller of a meta-predicate is compiled differently to provide the required
hmodulei:htermi qualification. This implies that the meta-declaration must be available to the com-
piler when compiling code that calls a meta-predicate. In practice, this implies that other systems pose
the following restrictions on meta-predicates:

Modules that provide meta-predicates for a module to be compiled must be loaded explicitly by
that module.

SWI-Prolog 7.4 Reference Manual

264 CHAPTER 6. MODULES

The meta-predicate directives of exported predicates must follow the module/2 directive im-
mediately.

After changing a meta-declaration, all modules that call the modified predicates need to be
recompiled.

In SWI-Prolog, meta-predicates are also module-transparent, and qualifying the module-sensitive

arguments is done inside the meta-predicate. As a result, the caller need not be aware that it is calling
a meta-predicate and none of the above restrictions hold for SWI-Prolog. However, code that aims at
portability must obey the above rules.
Other differences are listed below.

If a module does not define a predicate, it is searched for in the import modules. By default, the
import module of any user-defined module is the user module. In turn, the user module im-
ports from the module system that provides all built-in predicates. The auto-import hierarchy
can be changed using add import module/3 and delete import module/2.
This mechanism can be used to realise a simple object-oriented system or a hierarchical module
system.

Operator declarations are local to a module and may be exported. In Quintus and SICStus
all operators are global. YAP and Ciao also use local operators. SWI-Prolog provides global
operator declarations from within a module by explicitly qualifying the operator name with the
user module. I.e., operators are inherited from the import modules (see above).

:- op(precedence, type, user:(operatorname)).

SWI-Prolog 7.4 Reference Manual

Constraint Logic Programming
This chapter describes the extensions primarily designed to support constraint logic program-
7
ming (CLP), an important declarative programming paradigm with countless practical applications.
CLP(X) stands for constraint logic programming over the domain X. Plain Prolog can be re-
garded as CLP(H), where H stands for Herbrand terms. Over this domain, =/2 and dif/2 are the
most important constraints that express, respectively, equality and disequality of terms. Constraint
logic programming is thus a natural generalization of plain Prolog.
There are dedicated constraint solvers for several important domains:

CLP(FD) for integers (section A.8)

CLP(B) for Boolean variables (section A.7)
CLP(Q) for rational numbers (section A.9)
CLP(R) for floating point numbers (section A.9).

In addition, CHR (chapter 8) provides a general purpose constraint handling language to reason
over user-defined constraints.
A key advantage of constraints is their ability to combine all available information that is stated
about the entities you reason about, independent of the order in which you state it, and before the
actual search for solutions even begins. Using the available information to prune parts of the search
space is called constraint propagation, and it is performed automatically by the available constraint
solvers for their respective domains.
Among the most important and typical instances is CLP(FD), constraint logic programming
over integers. For example, using constraints, you can state in the most general way that a vari-
able X is an integer greater than 0. If, later, X is bound to a concrete integer, the constraint solver
automatically ensures this. If you in addition constrain X to integers less than 3, the constraint solver
combines the existing knowledge to infer that X is either 1 or 2 (see below). To obtain concrete values
for X, you can ask the solver to label X and produce 1 and 2 on backtracking. See section A.8.

?- use_module(library(clpfd)).
...
true.

?- X #> 0, X #< 3.
X in 1..2.

?- X #> 0, X #< 3, indomain(X).

X = 1 ;
X = 2.

SWI-Prolog 7.4 Reference Manual

266 CHAPTER 7. CONSTRAINT LOGIC PROGRAMMING

Contrast this with plain Prolog, which has no efficient means to deal with (integer) X > 0 and X < 3.
At best it could translate X > 0 to between(1, infinite, X) and a similar primitive for X < 3. If the
two are combined it has no choice but to generate and test over this infinite two-dimensional space.
Using constraints therefore makes your program more declarative in that it frees you from some
procedural aspects and limitations of Prolog.
When working with constraints, keep in mind the following:

As with plain Prolog, !/0 also destroys the declarative semantics of constraints. A cut after
a goal that is delayed may prematurely prune the search space, because the truth of delayed
goals is not yet established. There are several ways to avoid cuts in constraint logic programs,
retaining both generality and determinism of your programs. See for example zcompare/3.

Term-copying operations (assertz/1, retract/1, findall/3, copy term/2, etc.)

generally also copy constraints. The effect varies from ok, silent copying of huge constraint
networks to violations of the internal consistency of constraint networks. As a rule of thumb,
copying terms holding attributes must be deprecated. If you need to reason about a term that is
involved in constraints, use copy term/3 to obtain the constraints as Prolog goals, and use
these goals for further processing.

All of the mentioned constraint solvers are implemented using the attributed variables interface
described in section 7.1. These are lower-level predicates that are mainly intended for library authors,
not for typical Prolog programmers.

7.1 Attributed variables

Attributed variables provide a technique for extending the Prolog unification algorithm
[Holzbaur, 1992] by hooking the binding of attributed variables. There is no consensus in the Pro-
log community on the exact definition and interface to attributed variables. The SWI-Prolog interface
is identical to the one realised by Bart Demoen for hProlog [Demoen, 2002]. This interface is sim-
ple and available on all Prolog systems that can run the Leuven CHR system (see chapter 8 and the
Leuven CHR page).
Binding an attributed variable schedules a goal to be executed at the first possible opportunity.
In the current implementation the hooks are executed immediately after a successful unification of
the clause-head or successful completion of a foreign language (built-in) predicate. Each attribute
is associated to a module, and the hook (attr unify hook/2) is executed in this module. The
example below realises a very simple and incomplete finite domain reasoner:

:- module(domain,
[ domain/2 % Var, ?Domain
]).
:- use_module(library(ordsets)).

domain(X, Dom) :-
var(Dom), !,
get_attr(X, domain, Dom).
domain(X, List) :-
list_to_ord_set(List, Domain),

SWI-Prolog 7.4 Reference Manual

7.1. ATTRIBUTED VARIABLES 267

put_attr(Y, domain, Domain),

X = Y.

% An attributed variable with attribute value Domain has been

% assigned the value Y

attr_unify_hook(Domain, Y) :-
( get_attr(Y, domain, Dom2)
-> ord_intersection(Domain, Dom2, NewDomain),
( NewDomain == []
-> fail
; NewDomain = [Value]
-> Y = Value
; put_attr(Y, domain, NewDomain)
)
; var(Y)
-> put_attr( Y, domain, Domain )
; ord_memberchk(Y, Domain)
).

% Translate attributes from this module to residual goals

attribute_goals(X) -->
{ get_attr(X, domain, List) },
[domain(X, List)].

Before explaining the code we give some example queries:

?- domain(X, [a,b]), X = c fail

?- domain(X, [a,b]), domain(X, [a,c]). X=a
?- domain(X, [a,b,c]), domain(X, [a,c]). domain(X, [a, c])

The predicate domain/2 fetches (first clause) or assigns (second clause) the variable a domain,
a set of values the variable can be unified with. In the second clause, domain/2 first associates the
domain with a fresh variable (Y) and then unifies X to this variable to deal with the possibility that
X already has a domain. The predicate attr unify hook/2 (see below) is a hook called after a
variable with a domain is assigned a value. In the simple case where the variable is bound to a concrete
value, we simply check whether this value is in the domain. Otherwise we take the intersection of the
domains and either fail if the intersection is empty (first example), assign the value if there is only one
value in the intersection (second example), or assign the intersection as the new domain of the variable
(third example). The nonterminal attribute goals//1 is used to translate remaining attributes
to user-readable goals that, when called, reinstate these attributes or attributes that correspond to
equivalent constraints.
Implementing constraint solvers (chapter 7) is the most common, but not the only use case for
attributed variables: If you implement algorithms that require efficient destructive modifications, then
using attributed variables is often a more convenient and somewhat more declarative alternative for
setarg/3 and related predicates whose sharing semantics are harder to understand. In particular,

SWI-Prolog 7.4 Reference Manual

268 CHAPTER 7. CONSTRAINT LOGIC PROGRAMMING

attributed variables make it easy to express graph networks and graph-oriented algorithms, since each
variable can store pointers to further variables in its attributes. In such cases, the use of attributed vari-
ables should be confined within a module that exposes its functionality via more declarative interface
predicates.

7.1.1 Attribute manipulation predicates

attvar(@Term)
Succeeds if Term is an attributed variable. Note that var/1 also succeeds on attributed vari-
ables. Attributed variables are created with put attr/3.

put attr(+Var, +Module, +Value)

If Var is a variable or attributed variable, set the value for the attribute named Module to Value.
If an attribute with this name is already associated with Var, the old value is replaced. Back-
tracking will restore the old value (i.e., an attribute is a mutable term; see also setarg/3).
This predicate raises an uninstantiation error if Var is not a variable, and a type error if Module
is not an atom.

get attr(+Var, +Module, -Value)

Request the current value for the attribute named Module. If Var is not an attributed variable
or the named attribute is not associated to Var this predicate fails silently. If Module is not an
atom, a type error is raised.

del attr(+Var, +Module)

Delete the named attribute. If Var loses its last attribute it is transformed back into a traditional
Prolog variable. If Module is not an atom, a type error is raised. In all other cases this predicate
succeeds regardless of whether or not the named attribute is present.

7.1.2 Attributed variable hooks

Attribute names are linked to modules. This means that certain operations on attributed variables
cause hooks to be called in the module whose name matches the attribute name.

attr unify hook(+AttValue, +VarValue)

A hook that must be defined in the module to which an attributed variable refers. It is called
after the attributed variable has been unified with a non-var term, possibly another attributed
variable. AttValue is the attribute that was associated to the variable in this module and VarValue
is the new value of the variable. If this predicate fails, the unification fails. If VarValue is
another attributed variable the hook often combines the two attributes and associates the
combined attribute with VarValue using put attr/3.

To be done The way in which this hook currently works makes the implementation of important
classes of constraint solvers impossible or at least extremely impractical. For increased gen-
erality and convenience, simultaneous unifications as in [X,Y]=[0,1] should be processed
sequentially by the Prolog engine, or a more general hook should be provided in the future. See
[Triska, 2016] for more information.

attribute goals(+Var) //
This nonterminal is the main mechanism in which residual constraints are obtained. It is called
in every module where it is defined, and Var has an attribute. Its argument is that variable.

SWI-Prolog 7.4 Reference Manual

7.1. ATTRIBUTED VARIABLES 269

In each module, attribute goals//1 must describe a list of Prolog goals that are
declaratively equivalent to the goals that caused the attributes of that module to be present and
in their current state. It is always possible to do this (since these attributes stem from such
goals), and it is the responsibility of constraint library authors to provide this mapping without
exposing any library internals. Ideally and typically, remaining relevant attributes are mapped
to pure and potentially simplified Prolog goals that satisfy both of the following:

They are declaratively equivalent to the constraints that were originally posted.
They use only predicates that are themselves exported and documented in the modules
they stem from.

The latter property ensures that users can reason about residual goals, and see for themselves
whether a constraint library behaves correctly. It is this property that makes it possible to
thoroughly test constraint solvers by contrasting obtained residual goals with expected answers.
This nonterminal is used by copy term/3, on which the Prolog top level relies to ensure the
basic invariant of pure Prolog programs: The answer is declaratively equivalent to the query.
Note that instead of defaulty representations, a Prolog list is used to represent residual goals.
This simplifies processing and reasoning about residual goals throughout all programs that need
this functionality.
project attributes(+QueryVars, +ResidualVars)
A hook that can be defined in each module to project constraints on newly introduced variables
back to the query variables. QueryVars is the list of variables occurring in the query and
ResidualVars is a list of variables that have attributes attached. There may be variables that
occur in both lists. If possible, project attributes/2 should change the attributes so
that all constraints are expressed as residual goals that refer only to QueryVars, while other
variables are existentially quantified.
attr portray hook(+AttValue, +Var) [deprecated]
Called by write term/2 and friends for each attribute if the option attributes(portray)
is in effect. If the hook succeeds the attribute is considered printed. Otherwise
Module = ... is printed to indicate the existence of a variable. This predicate is
deprecated because it cannot work with pure interface predicates like copy term/3. Use
attribute goals//1 instead to map attributes to residual goals.

7.1.3 Operations on terms with attributed variables

copy term(+Term, -Copy, -Gs)
Create a regular term Copy as a copy of Term (without any attributes), and a list Gs of goals
that represents the attributes. The goal maplist(call, Gs) recreates the attributes for
Copy. The nonterminal attribute goals//1, as defined in the modules the attributes
stem from, is used to convert attributes to lists of goals.
This building block is used by the top level to report pending attributes in a portable and under-
standable fashion. This predicate is the preferred way to reason about and communicate terms
with constraints.
The form copy term(Term, Term, Gs) can be used to reason about the constraints in
which Term is involved.

SWI-Prolog 7.4 Reference Manual

270 CHAPTER 7. CONSTRAINT LOGIC PROGRAMMING

copy term nat(+Term, -Copy)

As copy term/2. Attributes, however, are not copied but replaced by fresh variables.

term attvars(+Term, -AttVars)

AttVars is a list of all attributed variables in Term and its attributes. That is,
term attvars/2 works recursively through attributes. This predicate is cycle-safe.
The goal term attvars(Term, []) in an efficient test that Term has no attributes; scanning
the term is aborted after the first attributed variable is found.

7.1.4 Special purpose predicates for attributes

Normal user code should deal with put attr/3, get attr/3 and del attr/2. The routines in
this section fetch or set the entire attribute list of a variable. Use of these predicates is anticipated to
be restricted to printing and other special purpose operations.

get attrs(+Var, -Attributes)

Get all attributes of Var. Attributes is a term of the form att(Module, Value, MoreAttributes),
where MoreAttributes is [] for the last attribute.

put attrs(+Var, -Attributes)

Set all attributes of Var. See get attrs/2 for a description of Attributes.

del attrs(+Var)
If Var is an attributed variable, delete all its attributes. In all other cases, this predicate succeeds
without side-effects.

7.2 Coroutining
Coroutining allows us to delay the execution of Prolog goals until their truth can be safely decided.
Among the most important coroutining predicates is dif/2, which expresses disequality of terms
in a sound way. The actual test is delayed until the terms are sufficiently different, or have become
identical. For example:

?- dif(X, Y), X = a, Y = b.
X = a,
Y = b.

?- dif(X, Y), X = a, Y = a.
false.

There are also lower-level coroutining predicates that are intended as building blocks for higher-level
constraints. For example, we can use freeze/2 to define a variable that can only be assigned an
atom:

?- freeze(X, atom(X)), X = a.
X = a.

In this case, calling atom/1 earlier causes the whole query to fail:

SWI-Prolog 7.4 Reference Manual

7.2. COROUTINING 271

?- atom(X), X = a.
false.

If available, domain-specific constraints should be used in such cases. For example, to state that a
variable can only assume even integers, use the CLP(FD) constraint #=/2:

?- X mod 2 #= 0.
X mod 2#=0.

Importantly, domain-specific constraints can apply stronger propagation by exploiting logical proper-
ties of their respective domains. For example:

?- X mod 2 #= 0, X in 1..3.
X = 2.

Remaining constraints, such as X mod 2#=0 in the example above, are called residual goals. They
are said to flounder, because their truth is not yet decided. Declaratively, the query is only true if all
residual goals are satisfiable. Use call residue vars/2 to collect all variables that are involved
in constraints.

dif(@A, @B)
The dif/2 predicate is a constraint that is true if and only if A and B are different terms. If
A and B can never unify, dif/2 succeeds deterministically. If A and B are identical, it fails
immediately. Finally, if A and B can unify, goals are delayed that prevent A and B to become
equal. It is this last property that makes dif/2 a more general and more declarative alternative
for \=/2 and related predicates.
This predicate behaves as if defined by dif(X, Y) :- when(?=(X,Y), X \== Y).
See also ?=/2. The implementation can deal with cyclic terms.
The dif/2 predicate is realised using attributed variables associated with the module dif. It
is an autoloaded predicate that is defined in the library dif.
freeze(+Var, :Goal)
Delay the execution of Goal until Var is bound (i.e. is not a variable or attributed variable).
If Var is bound on entry freeze/2 is equivalent to call/1. The freeze/2 pred-
icate is realised using an attributed variable associated with the module freeze. Use
frozen(Var, Goal) to find out whether and which goals are delayed on Var.
frozen(@Var, -Goal)
Unify Goal with the goal or conjunction of goals delayed on Var. If no goals are frozen on Var,
Goal is unified to true.
when(@Condition, :Goal)
Execute Goal when Condition becomes true. Condition is one of ?=(X, Y), nonvar(X),
ground(X), ,(Cond1, Cond2) or ;(Cond1, Cond2). See also freeze/2 and dif/2. The
implementation can deal with cyclic terms in X and Y.
The when/2 predicate is realised using attributed variables associated with the module when.
It is defined in the autoload library when.

SWI-Prolog 7.4 Reference Manual

272 CHAPTER 7. CONSTRAINT LOGIC PROGRAMMING

call residue vars(:Goal, -Vars)

Find residual attributed variables left by Goal. This predicate is intended for reasoning about
and debugging programs that use coroutining or constraints. To see why this predicate is
necessary, consider a predicate that poses contradicting constraints on a variable, and where
that variable does not appear in any argument of the predicate and hence does not yield any
residual goals on the toplevel when the predicate is invoked. Such programs should fail,
but sometimes succeed because the constraint solver is too weak to detect the contradiction.
Ideally, delayed goals and constraints are all executed at the end of the computation. The
meta predicate call residue vars/2 finds variables that are given attributes or whose
attributes are modified by Goal, regardless of whether or not these variables are reachable from
the arguments of Goal.1 .

1
The implementation of call residue vars/2 is completely redone in version 7.3.2 (7.2.1) after discussion with
Bart Demoen. The current implementation no longer performs full scans of the stacks. The overhead is proportional to the
number of attributed variables on the stack, dead or alive.

SWI-Prolog 7.4 Reference Manual

CHR: Constraint Handling
Rules
This chapter is written by Tom Schrijvers, K.U. Leuven, and adjustments by Jan Wielemaker.
8
The CHR system of SWI-Prolog is the K.U.Leuven CHR system. The runtime environment is
written by Christian Holzbaur and Tom Schrijvers while the compiler is written by Tom Schrijvers.
Both are integrated with SWI-Prolog and licensed under compatible conditions with permission from
the authors.
The main reference for the K.U.Leuven CHR system is:

T. Schrijvers, and B. Demoen, The K.U.Leuven CHR System: Implementation and Applica-
tion, First Workshop on Constraint Handling Rules: Selected Contributions (Fruhwirth, T. and
Meister, M., eds.), pp. 15, 2004.

On the K.U.Leuven CHR website (http://dtai.cs.kuleuven.be/CHR/) you can find

more related papers, references and example programs.

8.1 Introduction

Constraint Handling Rules (CHR) is a committed-choice rule-based language embedded in Prolog. It

is designed for writing constraint solvers and is particularly useful for providing application-specific
constraints. It has been used in many kinds of applications, like scheduling, model checking, abduc-
tion, and type checking, among many others.
CHR has previously been implemented in other Prolog systems (SICStus, Eclipse, Yap), Haskell
and Java. This CHR system is based on the compilation scheme and runtime environment of CHR in
SICStus.
In this documentation we restrict ourselves to giving a short overview of CHR in general and
mainly focus on elements specific to this implementation. For a more thorough review of CHR we
refer the reader to [Fruhwirth, 2009]. More background on CHR can be found at [Fruhwirth, ].
In section 8.2 we present the syntax of CHR in Prolog and explain informally its operational se-
mantics. Next, section 8.3 deals with practical issues of writing and compiling Prolog programs con-
taining CHR. Section 8.4 explains the (currently primitive) CHR debugging facilities. Section 8.4.3
provides a few useful predicates to inspect the constraint store, and section 8.5 illustrates CHR with
two example programs. Section 8.6 describes some compatibility issues with older versions of this
system and SICStus CHR system. Finally, section 8.7 concludes with a few practical guidelines for
using CHR.

SWI-Prolog 7.4 Reference Manual

274 CHAPTER 8. CHR: CONSTRAINT HANDLING RULES

8.2 Syntax and Semantics

8.2.1 Syntax of CHR rules

rules --> rule, rules ; [].

rule --> name, actual_rule, pragma, [atom(.)].

name --> atom, [atom(@)] ; [].

actual_rule --> simplification_rule.

actual_rule --> propagation_rule.
actual_rule --> simpagation_rule.

simplification_rule --> head, [atom(<=>)], guard, body.

propagation_rule --> head, [atom(==>)], guard, body.
simpagation_rule --> head, [atom(\)], head, [atom(<=>)],
guard, body.

head --> constraints.

constraints --> constraint, constraint_id.

constraints --> constraint, constraint_id,
[atom(,)], constraints.

constraint --> compound_term.

constraint_id --> [].

constraint_id --> [atom(#)], variable.
constraint_id --> [atom(#)], [atom(passive)] .

guard --> [] ; goal, [atom(|)].

body --> goal.

pragma --> [].

pragma --> [atom(pragma)], actual_pragmas.

actual_pragmas --> actual_pragma.

actual_pragmas --> actual_pragma, [atom(,)], actual_pragmas.

actual_pragma --> [atom(passive()], variable, [atom())].

Note that the guard of a rule may not contain any goal that binds a variable in the head of the rule with
a non-variable or with another variable in the head of the rule. It may, however, bind variables that do
not appear in the head of the rule, e.g. an auxiliary variable introduced in the guard.

SWI-Prolog 7.4 Reference Manual

8.2. SYNTAX AND SEMANTICS 275

8.2.2 Semantics
In this subsection the operational semantics of CHR in Prolog are presented informally. They do not
differ essentially from other CHR systems.
When a constraint is called, it is considered an active constraint and the system will try to apply
the rules to it. Rules are tried and executed sequentially in the order they are written.
A rule is conceptually tried for an active constraint in the following way. The active constraint
is matched with a constraint in the head of the rule. If more constraints appear in the head, they are
looked for among the suspended constraints, which are called passive constraints in this context. If
the necessary passive constraints can be found and all match with the head of the rule and the guard of
the rule succeeds, then the rule is committed and the body of the rule executed. If not all the necessary
passive constraints can be found, or the matching or the guard fails, then the body is not executed and
the process of trying and executing simply continues with the following rules. If for a rule there are
multiple constraints in the head, the active constraint will try the rule sequentially multiple times, each
time trying to match with another constraint.
This process ends either when the active constraint disappears, i.e. it is removed by some rule, or
after the last rule has been processed. In the latter case the active constraint becomes suspended.
A suspended constraint is eligible as a passive constraint for an active constraint. The other way
it may interact again with the rules is when a variable appearing in the constraint becomes bound to
either a non-variable or another variable involved in one or more constraints. In that case the constraint
is triggered, i.e. it becomes an active constraint and all the rules are tried.

Rule Types There are three different kinds of rules, each with its specific semantics:

simplification
The simplification rule removes the constraints in its head and calls its body.
propagation
The propagation rule calls its body exactly once for the constraints in its head.
simpagation
The simpagation rule removes the constraints in its head after the \ and then calls its body. It is
an optimization of simplification rules of the form:

constraints1 , constraints2 <=> constraints1 , body

Namely, in the simpagation form:

constraints1 \constraints2 <=> body

The constraints 1 constraints are not called in the body.

Rule Names Naming a rule is optional and has no semantic meaning. It only functions as documen-
tation for the programmer.

Pragmas The semantics of the pragmas are:

passive(Identifier)
The constraint in the head of a rule Identifier can only match a passive constraint in that rule.
There is an abbreviated syntax for this pragma. Instead of:

SWI-Prolog 7.4 Reference Manual

276 CHAPTER 8. CHR: CONSTRAINT HANDLING RULES

..., c # Id, ... <=> ... pragma passive(Id)

you can also write

..., c # passive, ... <=> ...

Additional pragmas may be released in the future.

:- chr option(+Option, +Value)

It is possible to specify options that apply to all the CHR rules in the module. Options are
specified with the chr option/2 declaration:

:- chr_option(Option,Value).

and may appear in the file anywhere after the first constraints declaration.
Available options are:

check guard bindings

This option controls whether guards should be checked for (illegal) variable bindings or
not. Possible values for this option are on to enable the checks, and off to disable the
checks. If this option is on, any guard fails when it binds a variable that appears in the
head of the rule. When the option is off (default), the behaviour of a binding in the guard
is undefined.
optimize
This option controls the degree of optimization. Possible values are full to enable
all available optimizations, and off (default) to disable all optimizations. The default
is derived from the SWI-Prolog flag optimise, where true is mapped to full.
Therefore the command line option -O provides full CHR optimization. If optimization
is enabled, debugging must be disabled.
debug
This option enables or disables the possibility to debug the CHR code. Possible values
are on (default) and off. See section 8.4 for more details on debugging. The default is
derived from the Prolog flag generate debug info, which is true by default. See
-nodebug. If debugging is enabled, optimization must be disabled.

8.3 CHR in SWI-Prolog Programs

8.3.1 Embedding in Prolog Programs
The CHR constraints defined in a .pl file are associated with a module. The default module is user.
One should never load different .pl files with the same CHR module name.

SWI-Prolog 7.4 Reference Manual

8.3. CHR IN SWI-PROLOG PROGRAMS 277

8.3.2 Constraint declaration

:- chr constraint(+Specifier)
Every constraint used in CHR rules has to be declared with a chr constraint/1 decla-
ration by the constraint specifier. For convenience multiple constraints may be declared at
once with the same chr constraint/1 declaration followed by a comma-separated list of
constraint specifiers.
A constraint specifier is, in its compact form, F /A where F and A are respectively the functor
name and arity of the constraint, e.g.:

:- chr_constraint foo/1.
:- chr_constraint bar/2, baz/3.

In its extended form, a constraint specifier is c(A1 ,...,An ) where c is the constraints func-
tor, n its arity and the Ai are argument specifiers. An argument specifier is a mode, optionally
followed by a type. Example:

:- chr_constraint get_value(+,?).
:- chr_constraint domain(?int, +list(int)),
alldifferent(?list(int)).

Modes A mode is one of:

-
The corresponding argument of every occurrence of the constraint is always unbound.

+
The corresponding argument of every occurrence of the constraint is always ground.

?
The corresponding argument of every occurrence of the constraint can have any instantiation,
which may change over time. This is the default value.

Types A type can be a user-defined type or one of the built-in types. A type comprises a (possibly
infinite) set of values. The type declaration for a constraint argument means that for every instance of
that constraint the corresponding argument is only ever bound to values in that set. It does not state
that the argument necessarily has to be bound to a value.
The built-in types are:
int
The corresponding argument of every occurrence of the constraint is an integer number.

dense int
The corresponding argument of every occurrence of the constraint is an integer that can be used
as an array index. Note that if this argument takes values in [0, n], the array takes O(n) space.

float
. . . a floating point number.

SWI-Prolog 7.4 Reference Manual

278 CHAPTER 8. CHR: CONSTRAINT HANDLING RULES

number
. . . a number.

natural
. . . a positive integer.

any
The corresponding argument of every occurrence of the constraint can have any type. This is
the default value.

:- chr type(+TypeDeclaration)
User-defined types are algebraic data types, similar to those in Haskell or the discriminated
unions in Mercury. An algebraic data type is defined using chr type/1:

:- chr_type type ---> body.

If the type term is a functor of arity zero (i.e. one having zero arguments), it names a monomor-
phic type. Otherwise, it names a polymorphic type; the arguments of the functor must be distinct
type variables. The body term is defined as a sequence of constructor definitions separated by
semi-colons.
Each constructor definition must be a functor whose arguments (if any) are types. Discriminated
union definitions must be transparent: all type variables occurring in the body must also occur
in the type.
Here are some examples of algebraic data type definitions:

:- chr_type color ---> red ; blue ; yellow ; green.

:- chr_type tree ---> empty ; leaf(int) ; branch(tree, tree).

:- chr_type list(T) ---> [] ; [T | list(T)].

:- chr_type pair(T1, T2) ---> (T1 - T2).

Each algebraic data type definition introduces a distinct type. Two algebraic data types that
have the same bodies are considered to be distinct types (name equivalence).
Constructors may be overloaded among different types: there may be any number of construc-
tors with a given name and arity, so long as they all have different types.
Aliases can be defined using ==. For example, if your program uses lists of lists of integers,
you can define an alias as follows:

:- chr_type lli == list(list(int)).

SWI-Prolog 7.4 Reference Manual

8.3. CHR IN SWI-PROLOG PROGRAMS 279

Type Checking Currently two complementary forms of type checking are performed:
1. Static type checking is always performed by the compiler. It is limited to CHR rule heads and
CHR constraint calls in rule bodies.
Two kinds of type error are detected. The first is where a variable has to belong to two types.
For example, in the program:

:-chr_type foo ---> foo.

:-chr_type bar ---> bar.

:-chr_constraint abc(?foo).
:-chr_constraint def(?bar).

foobar @ abc(X) <=> def(X).

the variable X has to be of both type foo and bar. This is reported as a type clash error:

CHR compiler ERROR:

--> Type clash for variable _ in rule foobar:
expected type foo in body goal def(_, _)
expected type bar in head def(_, _)

The second kind of error is where a functor is used that does not belong to the declared type.
For example in:

:- chr_type foo ---> foo.

:- chr_type bar ---> bar.

:- chr_constraint abc(?foo).

foo @ abc(bar) <=> true.

bar appears in the head of the rule where something of type foo is expected. This is reported
as:

CHR compiler ERROR:

--> Invalid functor in head abc(bar) of rule foo:
found bar,
expected type foo!

No runtime overhead is incurred in static type checking.

2. Dynamic type checking checks at runtime, during program execution, whether the arguments
of CHR constraints respect their declared types. The when/2 co-routining library is used to
delay dynamic type checks until variables are instantiated.
The kind of error detected by dynamic type checking is where a functor is used that does not
belong to the declared type. For example, for the program:

SWI-Prolog 7.4 Reference Manual

280 CHAPTER 8. CHR: CONSTRAINT HANDLING RULES

:-chr_type foo ---> foo.

:-chr_constraint abc(?foo).

we get the following error in an erroneous query:

?- abc(bar).
ERROR: Type error: foo expected, found bar
(CHR Runtime Type Error)

Dynamic type checking is weaker than static type checking in the sense that it only checks the
particular program execution at hand rather than all possible executions. It is stronger in the
sense that it tracks types throughout the whole program.
Note that it is enabled only in debug mode, as it incurs some (minor) runtime overhead.

8.3.3 Compilation
The SWI-Prolog CHR compiler exploits term expansion/2 rules to translate the constraint han-
dling rules to plain Prolog. These rules are loaded from the library chr. They are activated if the
compiled file has the .chr extension or after finding a declaration in the following format:

:- chr_constraint ...

It is advised to define CHR rules in a module file, where the module declaration is immediately
followed by including the library(chr) library as exemplified below:

:- module(zebra, [ zebra/0 ]).

:- use_module(library(chr)).

:- chr_constraint ...

Using this style, CHR rules can be defined in ordinary Prolog .pl files and the operator definitions
required by CHR do not leak into modules where they might cause conflicts.

8.4 Debugging
The CHR debugging facilities are currently rather limited. Only tracing is currently available. To use
the CHR debugging facilities for a CHR file it must be compiled for debugging. Generating debug
info is controlled by the CHR option debug, whose default is derived from the SWI-Prolog flag
generate debug info. Therefore debug info is provided unless the -nodebug is used.

SWI-Prolog 7.4 Reference Manual

8.4. DEBUGGING 281

8.4.1 Ports
For CHR constraints the four standard ports are defined:

call
A new constraint is called and becomes active.

exit
An active constraint exits: it has either been inserted in the store after trying all rules or has
been removed from the constraint store.

fail
An active constraint fails.

redo
An active constraint starts looking for an alternative solution.

In addition to the above ports, CHR constraints have five additional ports:

wake
A suspended constraint is woken and becomes active.

insert
An active constraint has tried all rules and is suspended in the constraint store.

remove
An active or passive constraint is removed from the constraint store.

try
An active constraint tries a rule with possibly some passive constraints. The try port is entered
just before committing to the rule.

apply
An active constraint commits to a rule with possibly some passive constraints. The apply port
is entered just after committing to the rule.

8.4.2 Tracing
Tracing is enabled with the chr trace/0 predicate and disabled with the chr notrace/0 pred-
icate.
When enabled the tracer will step through the call, exit, fail, wake and apply ports,
accepting debug commands, and simply write out the other ports.
The following debug commands are currently supported:

CHR debug options:

<cr> creep c creep

s skip
g ancestors
n nodebug
b break

SWI-Prolog 7.4 Reference Manual

282 CHAPTER 8. CHR: CONSTRAINT HANDLING RULES

a abort
f fail
? help h help

Their meaning is:

creep
Step to the next port.

skip
Skip to exit port of this call or wake port.

ancestors
Print list of ancestor call and wake ports.

nodebug
Disable the tracer.

break
Enter a recursive Prolog top level. See break/0.

abort
Exit to the top level. See abort/0.

fail
Insert failure in execution.

help
Print the above available debug options.

8.4.3 CHR Debugging Predicates

The chr module contains several predicates that allow inspecting and printing the content of the
constraint store.

chr trace
Activate the CHR tracer. By default the CHR tracer is activated and deactivated automatically
by the Prolog predicates trace/0 and notrace/0.

chr notrace
Deactivate the CHR tracer. By default the CHR tracer is activated and deactivated automatically
by the Prolog predicates trace/0 and notrace/0.

chr leash(+Spec)
Define the set of CHR ports on which the CHR tracer asks for user intervention (i.e. stops).
Spec is either a list of ports as defined in section 8.4.1 or a predefined alias. Defined aliases
are: full to stop at all ports, none or off to never stop, and default to stop at the call,
exit, fail, wake and apply ports. See also leash/1.

SWI-Prolog 7.4 Reference Manual

8.5. EXAMPLES 283

chr show store(+Mod)

Prints all suspended constraints of module Mod to the standard output. This predicate is auto-
matically called by the SWI-Prolog top level at the end of each query for every CHR module
currently loaded. The Prolog flag chr toplevel show store controls whether the top
level shows the constraint stores. The value true enables it. Any other value disables it.

find chr constraint(-Constraint)

Returns a constraint in the constraint store. Via backtracking, all constraints in the store can be
enumerated.

8.5 Examples
Here are two example constraint solvers written in CHR.

The program below defines a solver with one constraint, leq/2/, which is a less-than-or-
equal constraint, also known as a partial order constraint.

:- module(leq,[leq/2]).
:- use_module(library(chr)).

:- chr_constraint leq/2.
reflexivity @ leq(X,X) <=> true.
antisymmetry @ leq(X,Y), leq(Y,X) <=> X = Y.
idempotence @ leq(X,Y) \ leq(X,Y) <=> true.
transitivity @ leq(X,Y), leq(Y,Z) ==> leq(X,Z).

When the above program is saved in a file and loaded in SWI-Prolog, you can call the leq/2
constraints in a query, e.g.:

?- leq(X,Y), leq(Y,Z).
leq(_G23837, _G23841)
leq(_G23838, _G23841)
leq(_G23837, _G23838)
true .

When the query succeeds, the SWI-Prolog top level prints the content of the CHR constraint
store and displays the bindings generated during the query. Some of the query variables may
have been bound to attributed variables, as you see in the above example.

The program below implements a simple finite domain constraint solver.

:- module(dom,[dom/2]).
:- use_module(library(chr)).

:- chr_constraint dom(?int,+list(int)).
:- chr_type list(T) ---> [] ; [T|list(T)].

SWI-Prolog 7.4 Reference Manual

284 CHAPTER 8. CHR: CONSTRAINT HANDLING RULES

dom(X,[]) <=> fail.

dom(X,[Y]) <=> X = Y.
dom(X,L) <=> nonvar(X) | memberchk(X,L).
dom(X,L1), dom(X,L2) <=> intersection(L1,L2,L3), dom(X,L3).

When the above program is saved in a file and loaded in SWI-Prolog, you can call the dom/2
constraints in a query, e.g.:

?- dom(A,[1,2,3]), dom(A,[3,4,5]).
A = 3.

8.6 Backwards Compatibility

8.6.1 The Old SICStus CHR implemenation
There are small differences between the current K.U.Leuven CHR system in SWI-Prolog, older ver-
sions of the same system, and SICStus CHR system.
The current system maps old syntactic elements onto new ones and ignores a number of no longer
required elements. However, for each a deprecated warning is issued. You are strongly urged to
replace or remove deprecated features.
Besides differences in available options and pragmas, the following differences should be noted:

The constraints/1 declaration

This declaration is deprecated. It has been replaced with the chr constraint/1 declara-
tion.

The option/2 declaration

This declaration is deprecated. It has been replaced with the chr option/2 declaration.

The handler/1 declaration

In SICStus every CHR module requires a handler/1 declaration declaring a unique handler
name. This declaration is valid syntax in SWI-Prolog, but will have no effect. A warning will
be given during compilation.

The rules/1 declaration

In SICStus, for every CHR module it is possible to only enable a subset of the available rules
through the rules/1 declaration. The declaration is valid syntax in SWI-Prolog, but has no
effect. A warning is given during compilation.

Guard bindings
The check guard bindings option only turns invalid calls to unification into failure. In
SICStus this option does more: it intercepts instantiation errors from Prolog built-ins such as
is/2 and turns them into failure. In SWI-Prolog, we do not go this far, as we like to separate
concerns more. The CHR compiler is aware of the CHR code, the Prolog system, and the
programmer should be aware of the appropriate meaning of the Prolog goals used in guards and
bodies of CHR rules.

SWI-Prolog 7.4 Reference Manual

8.7. PROGRAMMING TIPS AND TRICKS 285

8.6.2 The Old ECLiPSe CHR implemenation

The old ECLiPSe CHR implementation features a label with/1 construct for labeling variables
in CHR constraints. This feature has long since been abandoned. However, a simple transformation
is all that is required to port the functionality.

label_with Constraint1 if Condition1.

...
label_with ConstraintN if ConditionN.
Constraint1 :- Body1.
...
ConstraintN :- BodyN.

is transformed into

:- chr_constraint my_labeling/0.

my_labeling \ Constraint1 <=> Condition1 | Body1.

...
my_labeling \ ConstraintN <=> ConditionN | BodyN.
my_labeling <=> true.

Be sure to put this code after all other rules in your program! With my labeling/0 (or another
predicate name of your choosing) the labeling is initiated, rather than ECLiPSes chr labeling/0.

8.7 Programming Tips and Tricks

In this section we cover several guidelines on how to use CHR to write constraint solvers and how to
do so efficiently.

Check guard bindings yourself

It is considered bad practice to write guards that bind variables of the head and to rely on the
system to detect this at runtime. It is inefficient and obscures the working of the program.

Set semantics
The CHR system allows the presence of identical constraints, i.e. multiple constraints with the
same functor, arity and arguments. For most constraint solvers, this is not desirable: it affects
efficiency and possibly termination. Hence appropriate simpagation rules should be added of
the form:
constraint\constraint <=> true

Multi-headed rules
Multi-headed rules are executed more efficiently when the constraints share one or more vari-
ables.

Mode and type declarations

Provide mode and type declarations to get more efficient program execution. Make sure to
disable debug (-nodebug) and enable optimization (-O).

SWI-Prolog 7.4 Reference Manual

286 CHAPTER 8. CHR: CONSTRAINT HANDLING RULES

Compile once, run many times

Does consulting your CHR program take a long time in SWI-Prolog? Probably it takes the
CHR compiler a long time to compile the CHR rules into Prolog code. When you disable opti-
mizations the CHR compiler will be a lot quicker, but you may lose performance. Alternatively,
you can just use SWI-Prologs qcompile/1 to generate a .qlf file once from your .pl file.
This .qlf contains the generated code of the CHR compiler (be it in a binary format). When
you consult the .qlf file, the CHR compiler is not invoked and consultation is much faster.

Finding Constraints
The find chr constraint/1 predicate is fairly expensive. Avoid it, if possible. If you
must use it, try to use it with an instantiated top-level constraint symbol.

8.8 Compiler Errors and Warnings

In this section we summarize the most important error and warning messages of the CHR compiler.

8.8.1 CHR Compiler Errors

Type clash for variable ... in rule ...
This error indicates an inconsistency between declared types; a variable can not belong to two
types. See static type checking.

Invalid functor in head ... of rule ...

This error indicates an inconsistency between a declared type and the use of a functor in a rule.
See static type checking.

Cyclic alias definition: ... == ...

You have defined a type alias in terms of itself, either directly or indirectly.

Ambiguous type aliases You have defined two overlapping type aliases.

Multiple definitions for type

You have defined the same type multiple times.

Non-ground type in constraint definition: ...

You have declared a non-ground type for a constraint argument.

Could not find type definition for ...

You have used an undefined type in a type declaration.

Illegal mode/type declaration You have used invalid syntax in a constraint declaration.

Constraint multiply defined There is more than one declaration for the same constraint.

Undeclared constraint ... in head of ...

You have used an undeclared constraint in the head of a rule. This often indicates a misspelled
constraint name or wrong number of arguments.

SWI-Prolog 7.4 Reference Manual

8.8. COMPILER ERRORS AND WARNINGS 287

Invalid pragma ... in ... Pragma should not be a variable.

You have used a variable as a pragma in a rule. This is not allowed.

Invalid identifier ... in pragma passive in ...

You have used an identifier in a passive pragma that does not correspond to an identifier in the
head of the rule. Likely the identifier name is misspelled.

Unknown pragma ... in ...

You have used an unknown pragma in a rule. Likely the pragma is misspelled or not supported.

Something unexpected happened in the CHR compiler

You have most likely bumped into a bug in the CHR compiler. Please contact Tom Schrijvers
to notify him of this error.

SWI-Prolog 7.4 Reference Manual

Multithreaded applications
SWI-Prolog multithreading is based on standard C language multithreading support. It is not like
9
ParLog or other parallel implementations of the Prolog language. Prolog threads have their own
stacks and only share the Prolog heap: predicates, records, flags and other global non-backtrackable
data. SWI-Prolog thread support is designed with the following goals in mind.

Multithreaded server applications

Todays computing services often focus on (internet) server applications. Such applications
often have need for communication between services and/or fast non-blocking service to mul-
tiple concurrent clients. The shared heap provides fast communication, and thread creation is
relatively cheap.1

Interactive applications
Interactive applications often need to perform extensive computation. If such computations are
executed in a new thread, the main thread can process events and allow the user to cancel the
ongoing computation. User interfaces can also use multiple threads, each thread dealing with
input from a distinct group of windows. See also section 9.7.

Natural integration with foreign code

Each Prolog thread runs in a native thread of the operating system, automatically making them
cooperate with MT-safe foreign code. In addition, any foreign thread can create its own Prolog
engine for dealing with calling Prolog from C code.

SWI-Prolog multithreading is based on the POSIX thread standard [Butenhof, 1997] used on most
popular systems except for MS-Windows. On Windows it uses the pthread-win32 emulation of POSIX
threads mixed with the Windows native API for smoother and faster operation. The SWI-Prolog thread
implementation has been discussed in the ISO WG17 working group and is largely addopted by YAP
and XSB Prolog.2

9.1 Creating and destroying Prolog threads

thread create(:Goal, -Id, +Options)
Create a new Prolog thread (and underlying operating system thread) and start it by executing
Goal. If the thread is created successfully, the thread identifier of the created thread is unified
to Id.
1
On an Intel i7-2600K, running Ubuntu Linux 12.04, SWI-Prolog 6.2 creates and joins 32,000 threads per second elapsed
time.
2
The latest version of the ISO draft can be found at http://logtalk.org/plstd/threads.pdf. It appears to
have dropped from the ISO WG17 agenda.

SWI-Prolog 7.4 Reference Manual

9.1. CREATING AND DESTROYING PROLOG THREADS 289

Id is the alias name if the option alias(name) is given. Otherwise it is a blob of type
thread. The anonymous blobs are subject to atom garbage collection. If a thread handle
is garbage collected and the thread is not detached, it is joined if it has already terminated (see
thread join/2) and detached otherwise (see thread detach/1).3 The thread identi-
fier blobs are printed as <thread>(I,Ptr), where I is the internal thread identifier and Ptr
is the unique address of the identifier. The I is accepted as input argument for all thread
APIs that accept a thread identifier for convenient interaction from the toplevel. See also
thread property/2.
Options is a list of options. The currently defined options are below. Stack size options can also
take the value inf or infinite, which is mapped to the maximum stack size supported by
the platform.

alias(AliasName)
Associate an alias name with the thread. This name may be used to refer to the thread
and remains valid until the thread is joined (see thread join/2).
at exit(:AtExit)
Register AtExit as using thread at exit/1 before entering the thread goal. Unlike
calling thread at exit/1 as part of the normal Goal, this ensures the AtExit is called.
Using thread at exit/1, the thread may be signalled or run out of resources before
thread at exit/1 is reached.
debug(+Bool)
Enable/disable debugging the new thread. If false (default true), the new thread is
created with the property debug(false) and debugging is disabled before the new thread
is started. The thread debugging predicates such as tspy/1 and tdebug/0 do not
signal threads with the debug property set to false.4
detached(Bool)
If false (default), the thread can be waited for using thread join/2.
thread join/2 must be called on this thread to reclaim all resources associated
with the thread. If true, the system will reclaim all associated resources automatically
after the thread finishes. Please note that thread identifiers are freed for reuse after a
detached thread finishes or a normal thread has been joined. See also thread join/2
and thread detach/1.
If a detached thread dies due to failure or exception of the initial goal, the thread prints a
message using print message/2. If such termination is considered normal, the code
must be wrapped using ignore/1 and/or catch/3 to ensure successful completion.
inherit from(+ThreadId)
Inherit defaults from the given ThreadId instead of the calling thread.
This option was added to ensure that the thread pool manager (see
thread create in pool/4), which is created lazily, has a predictable state.
The following properties are inherited:
3
Up to version 7.3.23, anonymous thread handles were integers. Using integers did not allow for safe checking of the
threads status as the thread may have died and the handle may have been reused and did not allow for garbage collection to
take care of forgotten threads.
4
Currently, the flag is only used as a hint for the the various debugging primitives, i.e., the system does not really enforce
that the target thread stays in nodebug mode.

SWI-Prolog 7.4 Reference Manual

290 CHAPTER 9. MULTITHREADED APPLICATIONS

The prompt (see prompt/2)

The typein module (see module/1)
The standard streams (user input, etc.)
The default encoding (see encoding)
The default locale (see setlocale/1)
All prolog flags
The limits of Prolog stacks (see set prolog stack/2)
global(K-Bytes)
Set the limit to which the global stack of this thread may grow. If omitted, the limit of the
calling thread is used. See also the -G command line option.
local(K-Bytes)
Set the limit to which the local stack of this thread may grow. If omitted, the limit of the
calling thread is used. See also the -L command line option.
c stack(K-Bytes)
Set the limit to which the system stack of this thread may grow. The default, minimum
and maximum values are system-dependent.5
trail(K-Bytes)
Set the limit to which the trail stack of this thread may grow. If omitted, the limit of the
calling thread is used. See also the -T command line option.

The Goal argument is copied to the new Prolog engine. This implies that further instantiation
of this term in either thread does not have consequences for the other thread: Prolog threads do
not share data from their stacks.

thread self(-Id)
Get the Prolog thread identifier of the running thread. If the thread has an alias, the alias name
is returned.

thread join(+Id, -Status)

Wait for the termination of the thread with the given Id. Then unify the result status of the
thread with Status. After this call, Id becomes invalid and all resources associated with the
thread are reclaimed. Note that threads with the attribute detached(true) cannot be joined.
See also thread property/2.
A thread that has been completed without thread join/2 being called on it is partly re-
claimed: the Prolog stacks are released and the C thread is destroyed. A small data structure
representing the exit status of the thread is retained until thread join/2 is called on the
thread. Defined values for Status are:

true
The goal has been proven successfully.
false
The goal has failed.
5
Older versions used stack. This is still accepted as a synonym.

SWI-Prolog 7.4 Reference Manual

9.1. CREATING AND DESTROYING PROLOG THREADS 291

exception(Term)
The thread is terminated on an exception. See print message/2 to turn system
exceptions into readable messages.
exited(Term)
The thread is terminated on thread exit/1 using the argument Term.

thread detach(+Id)
Switch thread into detached state (see detached(Bool) option at thread create/3) at
runtime. Id is the identifier of the thread placed in detached state. This may be the result of
thread self/1.
One of the possible applications is to simplify debugging. Threads that are created as de-
tached leave no traces if they crash. For non-detached threads the status can be inspected using
thread property/2. Threads nobody is waiting for may be created normally and detach
themselves just before completion. This way they leave no traces on normal completion and
their reason for failure can be inspected.
thread exit(+Term) [deprecated]
Terminates the thread immediately, leaving exited(Term) as result state for
thread join/2. If the thread has the attribute detached(true) it terminates, but its
exit status cannot be retrieved using thread join/2, making the value of Term irrelevant.
The Prolog stacks and C thread are reclaimed.
The current implementation does not guarantee proper releasing of all mutexes and proper
cleanup in setup call cleanup/3, etc. Please use the exception mechanism (throw/1)
to abort execution using non-standard control.
thread initialization(:Goal)
Run Goal when thread is started. This predicate is similar to initialization/1, but is
intended for initialization operations of the runtime stacks, such as setting global variables as
described in section 4.33. Goal is run on four occasions: at the call to this predicate, after
loading a saved state, on starting a new thread and on creating a Prolog engine through the C
interface. On loading a saved state, Goal is executed after running the initialization/1
hooks.
thread at exit(:Goal)
Run Goal just before releasing the thread resources. This is to be compared to at halt/1, but
only for the current thread. These hooks are run regardless of why the execution of the thread
has been completed. When these hooks are run, the return code is already available through
thread property/2 using the result of thread self/1 as thread identifier. Note that
there are two scenarios for using exit hooks. Using thread at exit/1 is typically used
if the thread creates a side-effect that must be reverted if the thread dies. Another scenario is
where the creator of the thread wants to be informed when the thread ends. That cannot be
guaranteed by means of thread at exit/1 because it is possible that the thread cannot be
created or dies almost instantly due to a signal or resource error. The at exit(Goal) option
of thread create/3 is designed to deal with this scenario.
thread setconcurrency(-Old, +New)
Determine the concurrency of the process, which is defined as the maximum number of con-
currently active threads. Active here means they are using CPU time. This option is provided

SWI-Prolog 7.4 Reference Manual

292 CHAPTER 9. MULTITHREADED APPLICATIONS

if the thread implementation provides pthread setconcurrency(). Solaris is a typical example of

this family. On other systems this predicate unifies Old to 0 (zero) and succeeds silently.

9.2 Monitoring threads

Normal multithreaded applications should not need the predicates from this section because almost
any usage of these predicates is unsafe. For example checking the existence of a thread before sig-
nalling it is of no use as it may vanish between the two calls. Catching exceptions using catch/3 is
the only safe way to deal with thread-existence errors.
These predicates are provided for diagnosis and monitoring tasks. See also section 9.5, describing
more high-level primitives.

is thread(@Term)
True if Term is a handle to an existing thread.

thread property(?Id, ?Property)

True if thread Id has Property. Either or both arguments may be unbound, enumerating all
relations on backtracking. Calling thread property/2 does not influence any thread. See
also thread join/2. For threads that have an alias name, this name is returned in Id instead
of the opaque thread identifier. Defined properties are:

alias(Alias)
Alias is the alias name of thread Id.
detached(Boolean)
Current detached status of the thread.
id(Integer)
Integer identifier for the thread. Can be used as argument to the thread predicates, but
applications must be aware that these references are reused.
status(Status)
Current status of the thread. Status is one of:
running
The thread is running. This is the initial status of a thread. Please note that threads
waiting for something are considered running too.
suspended
Only if the thread is an engine (see section 10). Indicates that the engine is currently
not associated with an OS thread.
false
The Goal of the thread has been completed and failed.
true
The Goal of the thread has been completed and succeeded.
exited(Term)
The Goal of the thread has been terminated using thread exit/1 with Term as
argument. If the underlying native thread has exited (using pthread exit()) Term is
unbound.

SWI-Prolog 7.4 Reference Manual

9.3. THREAD COMMUNICATION 293

exception(Term)
The Goal of the thread has been terminated due to an uncaught exception (see
throw/1 and catch/3).
engine(Boolean)
If the thread is an engine (see chapter 10), Boolean is true. Othwerwise the property is
not present.
thread(ThreadId)
If the thread is an engine that is currently attached to a thread, ThreadId is the thread that
executes the engine.
system thread id(Integer)
Thread identifier used by the operating system for the calling thread. Not available on all
OSes. This is the same as the Prolog flag system thread id for the calling thread.
Access to the system thread identifier can, on some systems, be used to gain additional
control over or information about Prolog threads.

See also thread statistics/3 to obtain resource usage information and

message queue property/2 to get the number of queued messages for a thread.

thread statistics(+Id, +Key, -Value)

Obtains statistical information on thread Id as statistics/2 does in single-threaded appli-
cations. This call supports all keys of statistics/2, although only stack sizes, cputime,
inferences and epoch yield different values for each thread.6

mutex statistics
Print usage statistics on internal mutexes and mutexes associated with dynamic predicates.
For each mutex two numbers are printed: the number of times the mutex was acquired and
the number of collisions: the number of times the calling thread has to wait for the mutex.
Generally collision count is close to zero on single-CPU hardware.

9.3 Thread communication

9.3.1 Message queues
Prolog threads can exchange data using dynamic predicates, database records, and other globally
shared data. These provide no suitable means to wait for data or a condition as they can only be
checked in an expensive polling loop. Message queues provide a means for threads to wait for data or
conditions without using the CPU.
Each thread has a message queue attached to it that is identified by the thread. Additional queues
are created using message queue create/1. Explicitly created queues come in two flavours.
When given an alias, they must be destroyed by the user. Anonymous message queues are identified
by a blob (see section 11.4.7) and subject to garbage collection.

thread send message(+QueueOrThreadId, +Term)

Place Term in the given queue or default queue of the indicated thread (which can even be the
6
There is no portable interface to obtain thread-specific CPU time and some operating systems provide no access to this
information at all. On such systems the total process CPU is returned. Thread CPU time is supported on MS-Windows,
Linux and MacOSX.

SWI-Prolog 7.4 Reference Manual

294 CHAPTER 9. MULTITHREADED APPLICATIONS

message queue of itself, see thread self/1). Any term can be placed in a message queue,
but note that the term is copied to the receiving thread and variable bindings are thus lost. This
call returns immediately.
If more than one thread is waiting for messages on the given queue and at least one of these
is waiting with a partially instantiated Term, the waiting threads are all sent a wake-up signal,
starting a rush for the available messages in the queue. This behaviour can seriously harm
performance with many threads waiting on the same queue as all-but-the-winner perform a
useless scan of the queue. If there is only one waiting thread or all waiting threads wait with an
unbound variable, an arbitrary thread is restarted to scan the queue.7

thread send message(+Queue, +Term, +Options) [semidet]

As thread send message/2, but providing additional Options. These are to
deal with the case that the queue has a finite maximum size and is full: whereas
thread send message/2 will block until the queue has drained sufficiently to accept a
new message, thread send message/3 can accept a time-out or deadline analogously to
thread get message/3. The options are:

deadline(+AbsTime)
The call fails (silently) if no space has become available before AbsTime. See
get time/1 for the representation of absolute time. If AbsTime is earlier then the
current time, thread send message/3 fails immediately. Both resolution and
maximum wait time is platform-dependent.8
timeout(+Time)
Time is a float or integer and specifies the maximum time to wait in seconds. This is a
relative-time version of the deadline option. If both options are provided, the earlier
time is effective.
If Time is 0 or 0.0, thread send message/3 examines the queue and sends the mes-
sage if space is availabel, but does not suspend if no space is available, failing immediately
instead.
If Time < 0, thread send message/3 fails immediately without sending the mes-
sage.

thread get message(?Term)

Examines the thread message queue and if necessary blocks execution until a term that unifies
to Term arrives in the queue. After a term from the queue has been unified to Term, the term is
deleted from the queue.
Please note that non-unifying messages remain in the queue. After the following has been
executed, thread 1 has the term b(gnu) in its queue and continues execution using A = gnat.

<thread 1>
thread_get_message(a(A)),

7
See the documentation for the POSIX thread functions pthread cond signal() v.s. pthread cond broadcast() for back-
ground information.
8
The implementation uses MsgWaitForMultipleObjects() on MS-Windows and pthread cond timedwait() on other sys-
tems.

SWI-Prolog 7.4 Reference Manual

9.3. THREAD COMMUNICATION 295

<thread 2>
thread_send_message(Thread_1, b(gnu)),
thread_send_message(Thread_1, a(gnat)),

See also thread peek message/1.

thread peek message(?Term)

Examines the thread message queue and compares the queued terms with Term until
one unifies or the end of the queue has been reached. In the first case the call suc-
ceeds, possibly instantiating Term. If no term from the queue unifies, this call fails. I.e.,
thread peek message/1 never waits and does not remove any term from the queue. See
also thread get message/3.

message queue create(?Queue)

Equivalent to message queue create(Queue,[]). For compatibility, calling
message queue create(+Atom) is equivalent to message queue create(Queue,
[alias(Atom)]). New code should use message queue create/2 to create a named queue.

message queue create(-Queue, +Options)

Create a message queue from Options. Defined options are:

alias(+Alias)
Create a message queue that is identified by the atom Alias. Message queues created this
way must be explicitly destroyed by the user. If the alias option is omitted, an Anonymous
queue is created that is indentified by a blob (see section 11.4.7) and subject to garbage
collection.9
max size(+Size)
Maximum number of terms in the queue. If this number is reached,
thread send message/2 will suspend until the queue is drained. The option
can be used if the source, sending messages to the queue, is faster than the drain,
consuming the messages.

message queue destroy(+Queue) [det]

Destroy a message queue created with message queue create/1. A permission error
is raised if Queue refers to (the default queue of) a thread. Other threads that are waiting for
Queue using thread get message/2 receive an existence error.

thread get message(+Queue, ?Term) [det]

As thread get message/1, operating on a given queue. It is allowed (but not advised)
to get messages from the queue of other threads. This predicate raises an existence error
exception if Queue doesnt exist or is destroyed using message queue destroy/1 while
this predicate is waiting.

thread get message(+Queue, ?Term, +Options) [semidet]

As thread get message/2, but providing additional Options:
9
Garbage collecting anonymous message queues is not part of the ISO proposal and most likely not a widely imple-
mented feature.

SWI-Prolog 7.4 Reference Manual

296 CHAPTER 9. MULTITHREADED APPLICATIONS

deadline(+AbsTime)
The call fails (silently) if no message has arrived before AbsTime. See get time/1
for the representation of absolute time. If AbsTime is earlier then the current time,
thread get message/3 fails immediately. Both resolution and maximum wait time
is platform-dependent.10
timeout(+Time)
Time is a float or integer and specifies the maximum time to wait in seconds. This is a
relative-time version of the deadline option. If both options are provided, the earlier
time is effective.
If Time is 0 or 0.0, thread get message/3 examines the queue but does not sus-
pend if no matching term is available. Note that unlike thread peek message/2, a
matching term is removed from the queue.
If Time < 0, thread get message/3 fails immediately without removing any mes-
sage from the queue.

thread peek message(+Queue, ?Term) [semidet]

As thread peek message/1, operating on a given queue. It is allowed to peek into an-
other threads message queue, an operation that can be used to check whether a thread has
swallowed a message sent to it.

message queue property(?Queue, ?Property)

True if Property is a property of Queue. Defined properties are:

alias(Alias)
Queue has the given alias name.
max size(Size)
Maximum number of terms that can be in the queue. See message queue create/2.
This property is not present if there is no limit (default).
size(Size)
Queue currently contains Size terms. Note that due to concurrent access the returned
value may be outdated before it is returned. It can be used for debugging purposes as well
as work distribution purposes.

The size(Size) property is always present and may be used to enumerate the created message
queues. Note that this predicate does not enumerate threads, but can be used to query the
properties of the default queue of a thread.

Explicit message queues are designed with the worker-pool model in mind, where multiple threads
wait on a single queue and pick up the first goal to execute. Below is a simple implementation where
the workers execute arbitrary Prolog goals. Note that this example provides no means to tell when all
work is done. This must be realised using additional synchronisation.

%% create_workers(?Id, +N)
%
10
The implementation uses MsgWaitForMultipleObjects() on MS-Windows and pthread cond timedwait() on other sys-
tems.

SWI-Prolog 7.4 Reference Manual

9.3. THREAD COMMUNICATION 297

% Create a pool with Id and number of workers.

% After the pool is created, post_job/1 can be used to
% send jobs to the pool.

create_workers(Id, N) :-
message_queue_create(Id),
forall(between(1, N, _),
thread_create(do_work(Id), _, [])).

do_work(Id) :-
repeat,
thread_get_message(Id, Goal),
( catch(Goal, E, print_message(error, E))
-> true
; print_message(error, goal_failed(Goal, worker(Id)))
),
fail.

%% post_job(+Id, +Goal)
%
% Post a job to be executed by one of the pools workers.

post_job(Id, Goal) :-
thread_send_message(Id, Goal).

9.3.2 Signalling threads

These predicates provide a mechanism to make another thread execute some goal as an interrupt.
Signalling threads is safe as these interrupts are only checked at safe points in the virtual machine.
Nevertheless, signalling in multithreaded environments should be handled with care as the receiving
thread may hold a mutex (see with mutex/2). Signalling probably only makes sense to start de-
bugging threads and to cancel no-longer-needed threads with throw/1, where the receiving thread
should be designed carefully to handle exceptions at any point.

thread signal(+ThreadId, :Goal)

Make thread ThreadId execute Goal at the first opportunity. In the current implementation, this
implies at the first pass through the Call port. The predicate thread signal/2 itself places
Goal into the signalled threads signal queue and returns immediately.
Signals (interrupts) do not cooperate well with the world of multithreading, mainly because the
status of mutexes cannot be guaranteed easily. At the call port, the Prolog virtual machine holds
no locks and therefore the asynchronous execution is safe.
Goal can be any valid Prolog goal, including throw/1 to make the receiving thread generate
an exception, and trace/0 to start tracing the receiving thread.
In the Windows version, the receiving thread immediately executes the signal if it reaches a
Windows GetMessage() call, which generally happens if the thread is waiting for (user) input.

SWI-Prolog 7.4 Reference Manual

298 CHAPTER 9. MULTITHREADED APPLICATIONS

9.3.3 Threads and dynamic predicates

Besides queues (section 9.3.1) threads can share and exchange data using dynamic predicates. The
multithreaded version knows about two types of dynamic predicates. By default, a predicate declared
dynamic (see dynamic/1) is shared by all threads. Each thread may assert, retract and run the dy-
namic predicate. Synchronisation inside Prolog guarantees the consistency of the predicate. Updates
are logical: visible clauses are not affected by assert/retract after a query started on the predicate. In
many cases primitives from section 9.4 should be used to ensure that application invariants on the
predicate are maintained.
Besides shared predicates, dynamic predicates can be declared with the thread local/1 di-
rective. Such predicates share their attributes, but the clause list is different in each thread.

thread local +Functor/+Arity, . . .

This directive is related to the dynamic/1 directive. It tells the system that the predicate may
be modified using assert/1, retract/1, etc., during execution of the program. Unlike
normal shared dynamic data, however, each thread has its own clause list for the predicate. As
a thread starts, this clause list is empty. If there are still clauses when the thread terminates,
these are automatically reclaimed by the system (see also volatile/1). The thread local
property implies the properties dynamic and volatile.
Thread-local dynamic predicates are intended for maintaining thread-specific state or interme-
diate results of a computation.
It is not recommended to put clauses for a thread-local predicate into a file, as in the example
below, because the clause is only visible from the thread that loaded the source file. All other
threads start with an empty clause list.

:- thread_local
foo/1.

foo(gnat).

DISCLAIMER Whether or not this declaration is appropriate in the sense of the proper mech-
anism to reach the goal is still debated. If you have strong feelings in favour or against, please
share them in the SWI-Prolog mailing list.

9.4 Thread synchronisation

All internal Prolog operations are thread-safe. This implies that two Prolog threads can operate on the
same dynamic predicate without corrupting the consistency of the predicate. This section deals with
user-level mutexes (called monitors in ADA or critical sections by Microsoft). A mutex is a MUTual
EXclusive device, which implies that at most one thread can hold a mutex.
Mutexes are used to realise related updates to the Prolog database. With related, we refer to
the situation where a transaction implies two or more changes to the Prolog database. For example,
we have a predicate address/2, representing the address of a person and we want to change the
address by retracting the old and asserting the new address. Between these two operations the database
is invalid: this person has either no address or two addresses, depending on the assert/retract order.

SWI-Prolog 7.4 Reference Manual

9.4. THREAD SYNCHRONISATION 299

The code below provides a solution to this problem based on with mutex/2. It also il-
lustrates the problem of mutexes. The predicate with mutex/2 behaves as once/1 with re-
spect to the guarded goal. This means that our predicate address/2 is no longer a nice logical
non-deterministic relation. This could be solved by explicit locking and unlocking a mutex using
setup call cleanup/2, but at the risk of deadlocking the program if the choice point is left
open by accident.

change_address(Id, Address) :-
with_mutex(addressbook,
( retractall(address(Id, _)),
asserta(address_db(Id, Address))
)).

address(Id, Address) :-
with_mutex(addressbook,
address_db(Id, Address)).

Message queues (see message queue create/3) often provide simpler and more robust ways
for threads to communicate. Still, mutexes can be a sensible solution and are therefore provided.

mutex create(?MutexId)
Create a mutex. If MutexId is an atom, a named mutex is created. If it is a variable, an anony-
mous mutex reference is returned. Anonymous mutexes are subject to (atom) garbage
collection.

mutex create(-MutexId, +Options)

Create a mutex using options. Defined options are:

alias(Alias)
Set the alias name. Using mutex create(X, [alias(name)]) is preferred over the equiv-
alent mutex create(name).

mutex destroy(+MutexId)
Destroy a mutex. If the mutex is not locked, it is destroyed and further access yields an
existence error exception. As of version 7.1.19, this behaviour is reliable. If the mutex
is locked, the mutex is sheduled for delayed destruction: it will be destroyed when it becomes
unlocked.

with mutex(+MutexId, :Goal)

Execute Goal while holding MutexId. If Goal leaves choice points, these are destroyed (as
in once/1). The mutex is unlocked regardless of whether Goal succeeds, fails or raises an
exception. An exception thrown by Goal is re-thrown after the mutex has been successfully
unlocked. See also mutex create/1 and setup call cleanup/3.
Although described in the thread section, this predicate is also available in the single-threaded
version, where it behaves simply as once/1.

mutex lock(+MutexId)
Lock the mutex. Prolog mutexes are recursive mutexes: they can be locked multiple times by

SWI-Prolog 7.4 Reference Manual

300 CHAPTER 9. MULTITHREADED APPLICATIONS

the same thread. Only after unlocking it as many times as it is locked does the mutex become
available for locking by other threads. If another thread has locked the mutex the calling thread
is suspended until the mutex is unlocked.
If MutexId is an atom, and there is no current mutex with that name, the mutex is created
automatically using mutex create/1. This implies named mutexes need not be declared
explicitly.
Please note that locking and unlocking mutexes should be paired carefully. Especially make
sure to unlock mutexes even if the protected code fails or raises an exception. For most common
cases, use with mutex/2, which provides a safer way for handling Prolog-level mutexes. The
predicate setup call cleanup/3 is another way to guarantee that the mutex is unlocked
while retaining non-determinism.

mutex trylock(+MutexId)
As mutex lock/1, but if the mutex is held by another thread, this predicates fails immedi-
ately.

mutex unlock(+MutexId)
Unlock the mutex. This can only be called if the mutex is held by the calling thread. If this is
not the case, a permission error exception is raised.

mutex unlock all [deprecated]

Unlock all mutexes held by the current thread. This predicate should not be needed if mutex
unlocking is guaranteed with with mutex/2 or setup call cleanup/3.11

mutex property(?MutexId, ?Property)

True if Property is a property of MutexId. Defined properties are:

alias(Alias)
Mutex has the defined alias name. See mutex create/2 using the alias option.
status(Status)
Current status of the mutex. One of unlocked if the mutex is currently not locked,
or locked(Owner, Count) if mutex is locked Count times by thread Owner. Note that
unless Owner is the calling thread, the locked status can change at any time. There is no
useful application of this property, except for diagnostic purposes.12

9.5 Thread support library(threadutil)

This library defines a couple of useful predicates for demonstrating and debugging multithreaded
applications. This library is certainly not complete.

threads
Lists all current threads and their status.

join threads
Join all terminated threads. For normal applications, dealing with terminated threads must be
11
The also deprecated thread exit/1 bypasses the automatic cleanup.
12
BUG: As Owner and Count are fetched separately from the mutex, the values may be inconsistent.

SWI-Prolog 7.4 Reference Manual

9.5. THREAD SUPPORT LIBRARY(THREADUTIL) 301

part of the application logic, either detaching the thread before termination or making sure it
will be joined. The predicate join threads/0 is intended for interactive sessions to reclaim
resources from threads that died unexpectedly during development.
interactor
Create a new console and run the Prolog top level in this new console. See also
attach console/0. In the Windows version a new interactor can also be created
from the Run/New thread menu.

9.5.1 Debugging threads

Support for debugging threads is still very limited. Debug and trace mode are flags that are local
to each thread. Individual threads can be debugged either using the graphical debugger described
in section 3.5 (see tspy/1 and friends) or by attaching a console to the thread and running the
traditional command line debugger (see attach console/0). When using the graphical debugger,
the debugger must be loaded from the main thread (for example using guitracer) before gtrace/0
can be called from a thread.

attach console
If the current thread has no console attached yet, attach one and redirect the user streams (input,
output, and error) to the new console window. On Unix systems the console is an xterm
application. On Windows systems this requires the GUI version swipl-win.exe rather than
the console-based swipl.exe.
This predicate has a couple of useful applications. One is to separate (debugging) I/O of differ-
ent threads. Another is to start debugging a thread that is running in the background. If thread
10 is running, the following sequence starts the tracer on this thread:

?- thread_signal(10, (attach_console, trace)).

tdebug(+ThreadId)
Prepare ThreadId for debugging using the graphical tracer. This implies installing the tracer
hooks in the thread and switching the thread to debug mode using debug/0. The call is
injected into the thread using thread signal/2. We refer to the documentation of this
predicate for asynchronous interaction with threads. New threads created inherit their debug
mode from the thread that created them.
tdebug
Call tdebug/1 in all running threads.
tnodebug(+ThreadId)
Disable debugging thread ThreadId.
tnodebug
Disable debugging in all threads.
tspy(:Spec, +ThreadId)
Set a spy point as spy/1 and enable the thread for debugging using tdebug/1. Note that a
spy point is a global flag on a predicate that is visible from all threads. Spy points are honoured
in all threads that are in debug mode and ignored in threads that are in nodebug mode.

SWI-Prolog 7.4 Reference Manual

302 CHAPTER 9. MULTITHREADED APPLICATIONS

tspy(:Spec)
Set a spy point as spy/1 and enable debugging in all threads using tdebug/0. Note that
removing spy points can be done using nospy/1. Disabling spy points in a specific thread is
achieved by tnodebug/1.

9.5.2 Profiling threads

In the current implementation, at most one thread can be profiled at any moment. Any thread can call
profile/1 to profile the execution of some part of its code. The predicate tprofile/1 allows
for profiling the execution of another thread until the user stops collecting profile data.

tprofile(+ThreadId)
Start collecting profile data in ThreadId and ask the user to hit hreturni to stop the profiler. See
section 4.41 for details on the execution profiler.

9.6 Multithreaded mixed C and Prolog applications

All foreign code linked to the multithreading version of SWI-Prolog should be thread-safe (reentrant)
or guarded in Prolog using with mutex/2 from simultaneous access from multiple Prolog threads.
If you want to write mixed multithreaded C and Prolog applications you should first familiarise your-
self with writing multithreaded applications in C (C++).
If you are using SWI-Prolog as an embedded engine in a multithreaded application you can access
the Prolog engine from multiple threads by creating an engine in each thread from which you call
Prolog. Without creating an engine, a thread can only use functions that do not use the term t type
(for example PL new atom()).
The system supports two models. Section 9.6.1 describes the original one-to-one mapping. In this
schema a native thread attaches a Prolog thread if it needs to call Prolog and detaches it when finished,
as opposed to the model from section 9.6.2, where threads temporarily use a Prolog engine.

9.6.1 A Prolog thread for each native thread (one-to-one)

In the one-to-one model, the thread that called PL initialise() has a Prolog engine at-
tached. If another C thread in the system wishes to call Prolog it must first attach an engine us-
ing PL thread attach engine() and call PL thread destroy engine() after all Prolog
work is finished. This model is especially suitable with long running threads that need to do Prolog
work regularly. See section 9.6.2 for the alternative many-to-many model.

int PL thread self()

Returns the integer Prolog identifier of the engine or -1 if the calling thread has no Prolog
engine. This function is also provided in the single-threaded version of SWI-Prolog, where it
returns -2.

int PL unify thread id(term t t, int i)

Unify t with the Prolog thread identifier for thread i. Thread identifiers are normally returned
from PL thread self(). Returns -1 if the thread does not exist or the unification fails.

int PL thread attach engine(const PL thread attr t *attr)

Creates a new Prolog engine in the calling thread. If the calling thread already has an engine

SWI-Prolog 7.4 Reference Manual

9.6. MULTITHREADED MIXED C AND PROLOG APPLICATIONS 303

the reference count of the engine is incremented. The attr argument can be NULL to create a
thread with default attributes. Otherwise it is a pointer to a structure with the definition below.
For any field with value 0, the default is used. The cancel field may be filled with a pointer
to a function that is called when PL cleanup() terminates the running Prolog engines. If
this function is not present or returns FALSE pthread cancel() is used. The flags field defines
the following flags:

PL THREAD NO DEBUG
If this flag is present, the thread starts in normal no-debug status. By default, the debug
status is inherited from the main thread.

typedef struct
{ unsigned long local_size; /* Stack sizes (Kbytes) */
unsigned long global_size;
unsigned long trail_size;
unsigned long argument_size;
char * alias; /* alias name */
int (*cancel)(int thread);
intptr_t flags;
} PL_thread_attr_t;

The structure may be destroyed after PL thread attach engine() has returned. On suc-
cess it returns the Prolog identifier for the thread (as returned by PL thread self()). If an
error occurs, -1 is returned. If this Prolog is not compiled for multithreading, -2 is returned.
int PL thread destroy engine()
Destroy the Prolog engine in the calling thread. Only takes ef-
fect if PL thread destroy engine() is called as many times as
PL thread attach engine() in this thread. Returns TRUE on success and FALSE
if the calling thread has no engine or this Prolog does not support threads.
Please note that construction and destruction of engines are relatively expensive operations.
Only destroy an engine if performance is not critical and memory is a critical resource.
int PL thread at exit(void (*function)(void *), void *closure, int global)
Register a handle to be called as the Prolog engine is destroyed. The handler function is called
with one void * argument holding closure. If global is TRUE, the handler is installed for all
threads. Globally installed handlers are executed after the thread-local handlers. If the handler
is installed local for the current thread only (global == FALSE) it is stored in the same FIFO
queue as used by thread at exit/1.

9.6.2 Pooling Prolog engines (many-to-many)

In this model Prolog engines live as entities that are independent from threads. If a thread needs to
call Prolog it takes one of the engines from the pool and returns the engine when done. This model is
suitable in the following identified cases:
Compatibility with the single-threaded version
In the single-threaded version, foreign threads must serialise access to the one and only thread
engine. Functions from this section allow sharing one engine among multiple threads.

SWI-Prolog 7.4 Reference Manual

304 CHAPTER 9. MULTITHREADED APPLICATIONS

Many native threads with infrequent Prolog work

Prolog threads are expensive in terms of memory and time to create and destroy them. For
systems that use a large number of threads that only infrequently need to call Prolog, it is better
to take an engine from a pool and return it there.

Prolog status must be handed to another thread

This situation has been identified by Uwe Lesta when creating a .NET interface for SWI-Prolog.
.NET distributes work for an active internet connection over a pool of threads. If a Prolog engine
contains the state for a connection, it must be possible to detach the engine from a thread and
re-attach it to another thread handling the same connection.

PL engine t PL create engine(PL thread attr t *attributes)

Create a new Prolog engine. attributes is described with PL thread attach engine().
Any thread can make this call after PL initialise() returns success. The returned engine
is not attached to any thread and lives until PL destroy engine() is used on the returned
handle.
In the single-threaded version this call always returns NULL, indicating failure.

int PL destroy engine(PL engine t e)

Destroy the given engine. Destroying an engine is only allowed if the engine is not attached to
any thread or attached to the calling thread. On success this function returns TRUE, on failure
the return value is FALSE.

int PL set engine(PL engine t engine, PL engine t *old)

Make the calling thread ready to use engine. If old is non-NULL the current engine associated
with the calling thread is stored at the given location. If engine equals PL ENGINE MAIN the
initial engine is attached to the calling thread. If engine is PL ENGINE CURRENT the engine is
not changed. This can be used to query the current engine. This call returns PL ENGINE SET
if the engine was switched successfully, PL ENGINE INVAL if engine is not a valid engine
handle and PL ENGINE INUSE if the engine is currently in use by another thread.
Engines can be changed at any time. For example, it is allowed to select an engine to initiate
a Prolog goal, detach it and at a later moment execute the goal from another thread. Note,
however, that the term t, qid t and fid t types are interpreted relative to the engine for
which they are created. Behaviour when passing one of these types from one engine to another
is undefined.
In the single-threaded version this call only succeeds if engine refers to the main engine.

9.7 Multithreading and the XPCE graphics system

GUI applications written in XPCE can benefit from Prolog threads if they need to do expensive com-
putations that would otherwise block the UI. The XPCE message passing system is guarded with a
single mutex, which synchronises both access from Prolog and activation through the GUI. In MS-
Windows, GUI events are processed by the thread that created the window in which the event occurred,
whereas in Unix/X11 they are processed by the thread that dispatches messages. In practice, the most
feasible approach to graphical Prolog implementations is to control XPCE from a single thread and
deploy other threads for (long) computations.

SWI-Prolog 7.4 Reference Manual

9.7. MULTITHREADING AND THE XPCE GRAPHICS SYSTEM 305

Traditionally, XPCE runs in the foreground (main) thread. We are working towards a situation
where XPCE can run comfortably in a separate thread. A separate XPCE thread can be created using
pce dispatch/1. It is also possible to create this thread as the (pce) is loaded by setting the
xpce threaded to true.
Threads other than the thread in which XPCE runs are provided with two predicates to communi-
cate with XPCE.

in pce thread(:Goal) [det]

Assuming XPCE is running in the foreground thread, this call gives background threads the
opportunity to make calls to the XPCE thread. A call to in pce thread/1 succeeds
immediately, copying Goal to the XPCE thread. Goal is added to the XPCE event queue and
executed synchronous to normal user events like typing and clicking.

in pce thread sync(:Goal) [semidet]

Same as in pce thread/1, but wait for Goal to be completed. Success depends on the suc-
cess of executing Goal. Variable bindings inside Goal are visible to the caller, but it should be
noted that the values are being copied. If Goal throws an exception, this exception is re-thrown
by in pce thread/1. If the calling thread is the pce thread, in pce thread sync/1
executes a direct meta-call. See also pce thread/1.
Note that in pce thread sync/1 is expensive because it requires copying and thread com-
munication. For example, in pce thread synctrue runs at approximately 50,000 calls
per second (AMD Phenom 9600B, Ubuntu 11.04).

pce dispatch(+Options)
Create a Prolog thread with the alias name pce for XPCE event handling. In the X11 version
this call creates a thread that executes the X11 event-dispatch loop. In MS-Windows it creates
a thread that executes a windows event-dispatch loop. The XPCE event-handling thread has
the alias pce. Options specifies the thread attributes as thread create/3.

SWI-Prolog 7.4 Reference Manual

Coroutining using Prolog
engines 10
Where the term coroutine in Prolog typically refer to hooks triggered by attributed variables (sec-
tion 7.1), SWI-Prolog provides two other forms of coroutines. Delimited continuations (see sec-
tion 4.10) allow creating coroutines that run in the same Prolog engine by capturing and restarting the
continuation. This section discusses engines, also known as interactors. The idea was pinned by Paul
Tarau [Tarau, 2011]. The API described in this chapter has been established together with Paul Tarau
and Paulo Moura.
Engines are closely related to threads (section 9). An engine is a Prolog virtual machine that has its
own stacks and (virtual) machine state. Unlike normal Prolog threads though, they are not associated
with an operating system thread. Instead, you ask an engine for a next answer (engine next/2).
Asking an engine for the next answer attaches the engine to the calling operating system thread and
cause it to run until the engine calls engine yield/1 or its associated goal completes with an
answer, failure or an exception. After the engine yields or completes, it is detached from the operating
system thread and the answer term is made available to the calling thread. Communicating with an
engine is similar to communicating with a Prolog system though the terminal. In this sense engines are
related to Pengines as provided by library pengines, but where Pengines aim primarily at accessing
Prolog engines through the network, engines are in-process entities.

10.1 Examples using engines

We introduce engines by describing application areas and providing simple example programs. The
predicates are defined in section 10.3. We identify the following application areas for engines.

1. Aggregating solutions from one or more goals. See section 10.1.1.

2. Access the terms produced in forward execution through backtracking without collecting all of
them first. Section 10.1.1 illustrates this as well.

3. State accumulation and sharing. See section 10.1.2.

4. Scalable many-agent applications. See section 10.1.3.

10.1.1 Aggregation using engines

Engines can be used to reason about solutions produced by a goal through backtracking. In this sce-
nario we create an engine with the goal we wish to backtrack over and we enumerate all its solution us-
ing engine next/1. This usage scenario competes with the all solution predicates (findall/3,
bagof/3, etc.) and the predicates from library aggregate. Below we implement findall/3
using engines.

SWI-Prolog 7.4 Reference Manual

10.1. EXAMPLES USING ENGINES 307

findall(Templ, Goal, List) :-

setup_call_cleanup(
engine_create(Templ, Goal, E),
get_answers(E, List),
engine_destroy(E)).

get_answers(E, [H|T]) :-
engine_next(E, H), !,
get_answers(E, T).
get_answers(_, []).

The above is not a particularly attractive alternative for the built-in findall/3. It is mostly slower
due to time required to create and destroy the engine as well as the (currently1 ) higher overhead of
copying terms between engines than the overhead required by the dedicated representation used by
findall/3.
It gets more interesting if we wish to combine answers from multiple backtracking predicates.
Assume we have two predicates that, on backtracking, return ordered solutions and we wish to merge
the two answer streams into a single ordered stream of answers. The solution in classical Prolog is
below. It collects both answer sets, merges them using ordered set merging and extract the answers.
The code is clean and short, but it doesnt produce any answers before both generaters are fully
enumerated and it uses memory that is proportional to the combined set of answers.

:- meta_predicate merge(?,0, ?,0, -).

merge_answers(T1,G1, T2,G2, A) :-
findall(T1, G1, L1),
findall(T2, G2, L2),
ord_union(L1, L2, Ordered),
member(A, Ordered).

We can achieve the same using engines. We create two engines to generate the solutions to both our
generators. Now, we cas ask both for an answer, put the smallest in the answer set and ask the engine
that created the smallest for its next answer, etc. This way we can create an ordered list of answers
as above, but now without creating intermediate lists. We can avoid creating the intermediate list by
introducing a third engine that controls the two generators and yields the answers rather than putting
them in a list. This is a general example of turning a predicate that builds a set of terms into a non-
deterministic predicate that produces the results on backtracking. The full code is below. Merging the
answers of two generators, each generating a set of 10,000 integers is currently about 20% slower than
the code above, but the engine-based solution runs in constant space and generates the first solution
immediately after both our generators have produced their first solution.

:- meta_predicate merge(?,0, ?,0, -).

1
The current implementation of engines is built on top of primitives that are not optimal for the engine use case. There
is considerable opportunity to reduce the overhead.

SWI-Prolog 7.4 Reference Manual

308 CHAPTER 10. COROUTINING USING PROLOG ENGINES

merge(T1,G1, T2,G2, A) :-
engine_create(A, merge(T1,G1, T2,G2), E),
repeat,
( engine_next(E, A)
-> true
; !, fail
).

merge(T1,G1, T2,G2) :-
engine_create(T1, G1, E1),
engine_create(T2, G2, E2),
( engine_next(E1, S1)
-> ( engine_next(E2, S2)
-> order_solutions(S1, S2, E1, E2)
; yield_remaining(S1, E1)
)
; engine_next(E2, S2),
yield_remaining(S2, E2)
).

order_solutions(S1, S2, E1, E2) :- !,

( S1 @=< S2
-> engine_yield(S1),
( engine_next(E1, S11)
-> order_solutions(S11, S2, E1, E2)
; yield_remaining(S2, E2)
)
; engine_yield(S2),
( engine_next(E2, S21)
-> order_solutions(S1, S21, E1, E2)
; yield_remaining(S1, E1)
)
).

yield_remaining(S, E) :-
engine_yield(S),
engine_next(E, S1),
yield_remaining(S1, E).

10.1.2 State accumulation using engines

Applications that need to manage a state can do so by passing the state around in an additional ar-
gument, storing it in a global variable or update it in the dynamic database using assertz/1 and
retract/1. Both using an additional argument and a global variable (see b setval/2), make the
state subject to backtracking. This may or may not be desirable. If having a state is that subject to

SWI-Prolog 7.4 Reference Manual

10.1. EXAMPLES USING ENGINES 309

backtracking is required, using an additional argument or backtrackable global variable is the right ap-
proach. Otherwise, non-backtrackable global variables (nb setval/2) and dynamic database come
into the picture, where global variables are always local to a thread and the dynamic database may or
may not be shared between threads (see thread local/1).
Engines bring an alternative that packages a state inside the engine where it is typically represented
in a (threaded) Prolog variable. The state may be updated, while controlled backtracking to a previous
state belongs to the possibilities. It can be accessed and updated by anyone with access to the engines
handle. Using an engine to represent state has the following advantages:

The programming style needed inside the engine is much more Prolog friendly, using
engine fetch/1 to read a request and engine yield/1 to reply to it.

The state is packaged and subject to (atom) garbage collection.

The state may be accessed from multiple threads. Access to the state is synchronized without
the need for explicit locks.

The example below implements a shared priority heap based on library heaps. The predicate
update heap/1 shows the typical update loop for maintaining state inside an engine: fetch a com-
mand, update the state, yield with the reply and call the updater recursively. The update step is guarded
against failure. For robustness one may also guard it against exceptions using catch/3. Note that
heap get/2 passes the Priority and Key it wishes to delete from the heap such that if the unification
fails, the heap remains unchanged.
The resulting heap is a global object with either a named or anonymous handle that evolves inde-
pendently from the Prolog thread(s) that access it. If the heap is anonymous, it is subject to (atom)
garbage collection.

:- use_module(library(heaps)).

create_heap(E) :-
empty_heap(H),
engine_create(_, update_heap(H), E).

update_heap(H) :-
engine_fetch(Command),
( update_heap(Command, Reply, H, H1)
-> true
; H1 = H,
Reply = false
),
engine_yield(Reply),
update_heap(H1).

update_heap(add(Priority, Key), true, H0, H) :-

add_to_heap(H0, Priority, Key, H).
update_heap(get(Priority, Key), Priority-Key, H0, H) :-
get_from_heap(H0, Priority, Key, H).

SWI-Prolog 7.4 Reference Manual

310 CHAPTER 10. COROUTINING USING PROLOG ENGINES

heap_add(Priority, Key, E) :-
engine_post(E, add(Priority, Key), true).

heap_get(Priority, Key, E) :-
engine_post(E, get(Priority, Key), Priority-Key).

10.1.3 Scalable many-agent applications

The final application area we touch are agent systems were we wish to capture an agent
in a Prolog goal. Such systems can be implemented using threads (see section 9) that use
thread send message/2 and thread get message/1 to communicate. The main problem
is that each thread is associated by an operating system thread. OS threads are, depending on the
OS, relatively expensive. Scalability of this design typically ends, depending on OS and hardware,
somewhere between 1,000 and 100,000 agents.
Engines provide an alternative. A detached Prolog engine currently requires approximately
20 Kbytes memory on 64 bit hardware, growing with the size of the Prolog stacks. The Prolog stacks
may be minimised by calling garbage collect/0 followed by trim stacks/0, providing a
deep sleep mode. The set of agents, each represented by an engine can be controlled by a static or
dynamic pool of threads. Scheduling the execution of agents and their communication is completely
open and can be optimised to satisfy the requirements of the application.

This section needs an example. Preferably something that fits on one page and would
not scale using threads. Engines might work nice to implement Antrank: An ant colony
algorithm for ranking web pages.2

10.2 Engine resource usage

A Prolog engine consists of a virtual machine state that includes the Prolog stacks. An
empty engine requires aout 20 KBytes of memory. This grows when the engine re-
quires additional stack space. Anonymous engines are subject to atom garbage collec-
tion (see garbage collect atoms/0). Engines may be reclaimed immediately using
engine destroy/1. Calling engine destroy/1 destroys the virtual machine state, while the
handle itself is left to atom garbage collection. The virtual machine is reclaimed as soon as an engine
produced its last result, failed or raised an exception. This implies that it is only advantageous to call
engine destroy/1 explicitly if you are not interested in further answers.
Engines that are expected to be left in inactive state for a prelonged time can be mini-
mized by calling garbage collect/0 and trimm stacks/0 (in that order) before calling
engine yield/1 or succeeding.

10.3 Engine predicate reference

This section documents the built-in predicates that deal with engines. In addition to these, most
predicates dealing with threads and message queue can be used to access engines.
2
http://www.ijettcs.org/Volume3Issue2/IJETTCS-2014-04-23-113.pdf

SWI-Prolog 7.4 Reference Manual

10.3. ENGINE PREDICATE REFERENCE 311

engine create(+Template, :Goal, ?Engine) [det]

engine create(+Template, :Goal, -Engine, +Options) [det]
Create a new engine and unify Engine with a handle to it. Template and Goal form a pair similar
to findall/3: the instantiation of Template becomes available though engine next/2
after Goal succeeds. Options is a list of the following options. See thread create/3 for
details.

alias(+Name)
Give the engine a name. Name must be an atom. If this option is provided, Engine is
unified with Name. The name space for engines is shared with threads and mutexes.
global(KBytes)
Set the limit for the global stack in KBytes.
local(KBytes)
Set the limit for the local stack in KBytes.
trail(KBytes)
Set the limit for the trail stack in KBytes.

The Engine argument of engine create/3 may be instantiated to an atom, creating an

engine with the given alias.

engine next(+Engine, -Term) [semidet]

Ask the engine Engine to produce a next answer. On this first call on a specific engine, the
Goal of the engine is started. If a previous call returned an answer through completion, this
causes the engine to backtrack and finally, if the engine produces a previous result using
engine yield/1, execution proceeds after the engine yield/1 call.

engine next reified(+Engine, -Term) [det]

Similar to engine next/2, but instead of success, failure or or raising an exception, Term is
unified with one of terms below. This predicate is provided primarily for compatibility with
Lean Prolog.

the(Answer)
Goal succeeded with Template bound to Answer or Goal yielded with a term Answer.
no
Goal failed.
exception(Exception)
Goal raises the error Exception.

engine post(+Engine, +Term) [det]

Make Term available to engine fetch/1 inside the Engine. This call must be followed by
a call to engine next/2 and the engine must call engine fetch/1.

engine post(+Engine, +Term, -Reply) [det]

Combines engine post/2 and engine next/2.

engine yield(+Term) [det]

Called from within the engine, causing engine next/2 in the caller to return with Term. A
subsequent call to engine next/2 causes engine yield/1 to return. This predicate

SWI-Prolog 7.4 Reference Manual

312 CHAPTER 10. COROUTINING USING PROLOG ENGINES

can only be called if the engine is not involved in a callback from C, i.e., when the engine calls
a predicate defined in C that calls back Prolog it is not possible to use this predicate. Trying to
do so results in a permission error exception.

engine fetch(-Term) [det]

Called from within the engine to fetch the term made available through engine post/2 or
engine post/3. If no term is available an existence error exception is raised.

engine self(-Engine) [det]

Called from within the engine to get access to the handle to the engine itself.

is engine(@Term) [semidet]
True if Term is a reference to or the alias name of an existing engine.

current engine(-Engine) [nondet]

True when Engine is an existing engine.

SWI-Prolog 7.4 Reference Manual

Foreign Language Interface 11
SWI-Prolog offers a powerful interface to C [Kernighan & Ritchie, 1978]. The main design objectives
of the foreign language interface are flexibility and performance. A foreign predicate is a C function
that has the same number of arguments as the predicate represented. C functions are provided to
analyse the passed terms, convert them to basic C types as well as to instantiate arguments using
unification. Non-deterministic foreign predicates are supported, providing the foreign function with a
handle to control backtracking.
C can call Prolog predicates, providing both a query interface and an interface to extract multiple
solutions from a non-deterministic Prolog predicate. There is no limit to the nesting of Prolog calling
C, calling Prolog, etc. It is also possible to write the main in C and use Prolog as an embedded
logical engine.

11.1 Overview of the Interface

A special include file called SWI-Prolog.h should be included with each C source file that is to be
loaded via the foreign interface. The installation process installs this file in the directory include in
the SWI-Prolog home directory (?- current prolog flag(home, Home).). This C header
file defines various data types, macros and functions that can be used to communicate with SWI-
Prolog. Functions and macros can be divided into the following categories:

Analysing Prolog terms

Constructing new terms
Unifying terms
Returning control information to Prolog
Registering foreign predicates with Prolog
Calling Prolog from C
Recorded database interactions
Global actions on Prolog (halt, break, abort, etc.)

11.2 Linking Foreign Modules

Foreign modules may be linked to Prolog in two ways. Using static linking, the extensions, a (short)
file defining main() which attaches the extension calls to Prolog, and the SWI-Prolog kernel distributed
as a C library, are linked together to form a new executable. Using dynamic linking, the extensions

SWI-Prolog 7.4 Reference Manual

314 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

are linked to a shared library (.so file on most Unix systems) or dynamic link library (.DLL file on
Microsoft platforms) and loaded into the running Prolog process.1

11.2.1 What linking is provided?

The static linking schema can be used on all versions of SWI-Prolog. Whether or not dy-
namic linking is supported can be deduced from the Prolog flag open shared object (see
current prolog flag/2). If this Prolog flag yields true, open shared object/2 and
related predicates are defined. See section 11.2.3 for a suitable high-level interface to these predi-
cates.

11.2.2 What kind of loading should I be using?

All described approaches have their advantages and disadvantages. Static linking is portable and
allows for debugging on all platforms. It is relatively cumbersome and the libraries you need to pass
to the linker may vary from system to system, though the utility program swipl-ld described in
section 11.5 often hides these problems from the user.
Loading shared objects (DLL files on Windows) provides sharing and protection and is
generally the best choice. If a saved state is created using qsave program/[1,2], an
initialization/1 directive may be used to load the appropriate library at startup.
Note that the definition of the foreign predicates is the same, regardless of the linking type used.

11.2.3 library(shlib): Utility library for loading foreign objects (DLLs, shared objects)
This section discusses the functionality of the (autoload) library(shlib), providing an interface
to manage shared libraries. We describe the procedure for using a foreign resource (DLL in Windows
and shared object in Unix) called mylib.
First, one must assemble the resource and make it compatible to SWI-Prolog. The details for this
vary between platforms. The swipl-ld(1) utility can be used to deal with this in a portable manner.
The typical commandline is:

swipl-ld -o mylib file.{c,o,cc,C} ...

Make sure that one of the files provides a global function install_mylib() that initialises
the module using calls to PL register foreign(). Here is a simple example file mylib.c, which creates
a Windows MessageBox:

#include <windows.h>
#include <SWI-Prolog.h>

static foreign_t
pl_say_hello(term_t to)
{ char *a;
1
The system also contains code to load .o files directly for some operating systems, notably Unix systems using the
BSD a.out executable format. As the number of Unix platforms supporting this quickly gets smaller and this interface is
difficult to port and slow, it is no longer described in this manual. The best alternative would be to use the dld package on
machines that do not have shared libraries.

SWI-Prolog 7.4 Reference Manual

11.2. LINKING FOREIGN MODULES 315

if ( PL_get_atom_chars(to, &a) )
{ MessageBox(NULL, a, "DLL test", MB_OK|MB_TASKMODAL);

PL_succeed;
}

PL_fail;
}

install_t
install_mylib()
{ PL_register_foreign("say_hello", 1, pl_say_hello, 0);
}

Now write a file mylib.pl:

:- module(mylib, [ say_hello/1 ]).

:- use_foreign_library(foreign(mylib)).

The file mylib.pl can be loaded as a normal Prolog file and provides the predicate defined in
C.

load foreign library(:FileSpec) [det]

load foreign library(:FileSpec, +Entry:atom) [det]
Load a shared object or DLL. After loading the Entry function is called without arguments.
The default entry function is composed from =install =, followed by the file base-name. E.g.,
the load-call below calls the function install_mylib(). If the platform prefixes extern
functions with = =, this prefix is added before calling.

...
load_foreign_library(foreign(mylib)),
...

Arguments
FileSpec is a specification for absolute file name/3. If search-
ing the file fails, the plain name is passed to the OS to try
the default method of the OS for locating foreign objects. The
default definition of file search path/2 searches <prolog
home>/lib/<arch> on Unix and <prolog home>/bin on Win-
dows.

See also use foreign library/1,2 are intended for use in directives.

SWI-Prolog 7.4 Reference Manual

316 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

use foreign library(+FileSpec) [det]

use foreign library(+FileSpec, +Entry:atom) [det]
Load and install a foreign library as load foreign library/1,2 and register the
installation using initialization/2 with the option now. This is similar to using:

:- initialization(load_foreign_library(foreign(mylib))).

but using the initialization/1 wrapper causes the library to be loaded after loading of
the file in which it appears is completed, while use foreign library/1 loads the library
immediately. I.e. the difference is only relevant if the remainder of the file uses functionality of
the C-library.
unload foreign library(+FileSpec) [det]
unload foreign library(+FileSpec, +Exit:atom) [det]
Unload a shared object or DLL. After calling the Exit function, the shared object is removed
from the process. The default exit function is composed from =uninstall =, followed by the file
base-name.
current foreign library(?File, ?Public)
Query currently loaded shared libraries.
reload foreign libraries
Reload all foreign libraries loaded (after restore of a state created using qsave program/2.

11.2.4 Low-level operations on shared libraries

The interface defined in this section allows the user to load shared libraries (.so files on most Unix
systems, .dll files on Windows). This interface is portable to Windows as well as to Unix machines
providing dlopen(2) (Solaris, Linux, FreeBSD, Irix and many more) or shl open(2) (HP/UX).
It is advised to use the predicates from section 11.2.3 in your application.

open shared object(+File, -Handle)

File is the name of a shared object file (DLL in MS-Windows). This file is attached to
the current process, and Handle is unified with a handle to the library. Equivalent to
open shared object(File, Handle, []). See also open shared object/3
and load foreign library/1.
On errors, an exception shared object(Action, Message) is raised. Message is the return
value from dlerror().
open shared object(+File, -Handle, +Options)
As open shared object/2, but allows for additional flags to be passed. Options is a list of
atoms. now implies the symbols are resolved immediately rather than lazy (default). global
implies symbols of the loaded object are visible while loading other shared objects (by default
they are local). Note that these flags may not be supported by your operating system. Check
the documentation of dlopen() or equivalent on your operating system. Unsupported flags are
silently ignored.
close shared object(+Handle)
Detach the shared object identified by Handle.

SWI-Prolog 7.4 Reference Manual

11.2. LINKING FOREIGN MODULES 317

call shared object function(+Handle, +Function)

Call the named function in the loaded shared library. The function is called without arguments
and the return value is ignored. Normally this function installs foreign language predicates
using calls to PL register foreign().

11.2.5 Static Linking

Below is an outline of the file structure required for statically linking SWI-Prolog with foreign ex-
tensions. .../swipl refers to the SWI-Prolog home directory (see the Prolog flag home). harchi
refers to the architecture identifier that may be obtained using the Prolog flag arch.

.../swipl/runtime/harchi/libswipl.a SWI-Library
.../swipl/include/SWI-Prolog.h Include file
.../swipl/include/SWI-Stream.h Stream I/O include file
.../swipl/include/SWI-Exports Export declarations (AIX only)
.../swipl/include/stub.c Extension stub

The definition of the foreign predicates is the same as for dynamic linking. Unlike with dynamic
linking, however, there is no initialisation function. Instead, the file .../swipl/include/stub.
c may be copied to your project and modified to define the foreign extensions. Below is stub.c,
modified to link the lowercase example described later in this chapter:

#include <stdio.h>
#include <SWI-Prolog.h>

extern foreign_t pl_lowercase(term, term);

PL_extension predicates[] =
{
/*{ "name", arity, function, PL_FA_<flags> },*/

{ "lowercase", 2 pl_lowercase, 0 },
{ NULL, 0, NULL, 0 } /* terminating line */
};

int
main(int argc, char **argv)
{ PL_register_extensions(predicates);

if ( !PL_initialise(argc, argv) )
PL_halt(1);

PL_halt(PL_toplevel() ? 0 : 1);
}

Now, a new executable may be created by compiling this file and linking it to libpl.a from the
runtime directory and the libraries required by both the extensions and the SWI-Prolog kernel. This

SWI-Prolog 7.4 Reference Manual

318 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

may be done by hand, or by using the swipl-ld utility described in section 11.5. If the linking is
performed by hand, the command line option -dump-runtime-variables (see section 2.4) can
be used to obtain the required paths, libraries and linking options to link the new executable.

11.3 Interface Data Types

11.3.1 Type term t: a reference to a Prolog term
The principal data type is term t. Type term t is what Quintus calls QP term ref. This name
indicates better what the type represents: it is a handle for a term rather than the term itself. Terms can
only be represented and manipulated using this type, as this is the only safe way to ensure the Prolog
kernel is aware of all terms referenced by foreign code and thus allows the kernel to perform garbage
collection and/or stack-shifts while foreign code is active, for example during a callback from C.
A term reference is a C unsigned long, representing the offset of a variable on the
Prolog environment stack. A foreign function is passed term references for the predi-
cate arguments, one for each argument. If references for intermediate results are needed,
such references may be created using PL new term ref() or PL new term refs().
These references normally live till the foreign function returns control back to Pro-
log. Their scope can be explicitly limited using PL open foreign frame() and
PL close foreign frame()/PL discard foreign frame().
A term t always refers to a valid Prolog term (variable, atom, integer, float or compound term).
A term lives either until backtracking takes us back to a point before the term was created, the garbage
collector has collected the term, or the term was created after a PL open foreign frame() and
PL discard foreign frame() has been called.
The foreign interface functions can either read, unify or write to term references. In this document
we use the following notation for arguments of type term t:

term t +t Accessed in read-mode. The + indicates the argument is input.

term t -t Accessed in write-mode.
term t ?t Accessed in unify-mode.

WARNING Term references that are accessed in write (-) mode will refer to an invalid term if
the term is allocated on the global stack and backtracking takes us back to a point before the term was
written.2 Compounds, large integers, floats and strings are all allocated on the global stack. Below is
a typical scenario where this may happen. The first solution writes a term extracted from the solution
into a. After the system backtracks due to PL next solution(), a becomes a reference to a term
that no longer exists.

term_t a = PL_new_term_ref();
...
query = PL_open_query(...);
while(PL_next_solution(query))
{ PL_get_arg(i, ..., a);
}
PL_close_query(query);
2
This could have been avoided by trailing term references when data is written to them. This seriously hurds performance
in some scenarios though. If this is desired, use PL put variable() followed by one of the PL unify *() functions.

SWI-Prolog 7.4 Reference Manual

11.3. INTERFACE DATA TYPES 319

There are two solutions to this problem. One is to scope the term reference using
PL open foreign frame() and PL close foreign frame() and makes sure it goes
out of scope before backtracking happens. The other is to clear the term reference using
PL put variable() before backtracking.
Term references are obtained in any of the following ways:

Passed as argument
The C functions implementing foreign predicates are passed their arguments as term references.
These references may be read or unified. Writing to these variables causes undefined behaviour.

Created by PL new term ref()

A term created by PL new term ref() is normally used to build temporary terms or to be
written by one of the interface functions. For example, PL get arg() writes a reference to
the term argument in its last argument.

Created by PL new term refs(int n)

This function returns a set of term references with the same characteristics as
PL new term ref(). See PL open query().

Created by PL copy term ref(term t t)

Creates a new term reference to the same term as the argument. The term may be written to.
See figure 11.2.

Term references can safely be copied to other C variables of type term t, but all copies will
always refer to the same term.

term t PL new term ref()

Return a fresh reference to a term. The reference is allocated on the local stack. Allocating
a term reference may trigger a stack-shift on machines that cannot use sparse memory
management for allocation of the Prolog stacks. The returned reference describes a variable.

term t PL new term refs(int n)

Return n new term references. The first term reference is returned. The others are t + 1, t + 2,
etc. There are two reasons for using this function. PL open query() expects the arguments
as a set of consecutive term references, and very time-critical code requiring a number of term
references can be written as:

pl_mypredicate(term_t a0, term_t a1)

{ term_t t0 = PL_new_term_refs(2);
term_t t1 = t0+1;

...
}

term t PL copy term ref(term t from)

Create a new term reference and make it point initially to the same term as from. This function
is commonly used to copy a predicate argument to a term reference that may be written.

SWI-Prolog 7.4 Reference Manual

320 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

void PL reset term refs(term t after)

Destroy all term references that have been created after after, including after itself. Any refer-
ence to the invalidated term references after this call results in undefined behaviour.
Note that returning from the foreign context to Prolog will reclaim all references used in the
foreign context. This call is only necessary if references are created inside a loop that never exits
back to Prolog. See also PL open foreign frame(), PL close foreign frame()
and PL discard foreign frame().

Interaction with the garbage collector and stack-shifter

Prolog implements two mechanisms for avoiding stack overflow: garbage collection and stack ex-
pansion. On machines that allow for it, Prolog will use virtual memory management to detect stack
overflow and expand the runtime stacks. On other machines Prolog will reallocate the stacks and
update all pointers to them. To do so, Prolog needs to know which data is referenced by C code.
As all Prolog data known by C is referenced through term references (term t), Prolog has all the
information necessary to perform its memory management without special precautions from the C
programmer.

11.3.2 Other foreign interface types

atom t An atom in Prologs internal representation. Atoms are pointers to an opaque structure. They
are a unique representation for represented text, which implies that atom A represents the same
text as atom B if and only if A and B are the same pointer.
Atoms are the central representation for textual constants in Prolog. The transformation of a
character string C to an atom implies a hash-table lookup. If the same atom is needed often, it
is advised to store its reference in a global variable to avoid repeated lookup.

functor t A functor is the internal representation of a name/arity pair. They are used to find the name
and arity of a compound term as well as to construct new compound terms. Like atoms they
live for the whole Prolog session and are unique.

predicate t Handle to a Prolog predicate. Predicate handles live forever (although they can lose their
definition).

qid t Query identifier. Used by PL open query(), PL next solution() and

PL close query() to handle backtracking from C.

fid t Frame identifier. Used by PL open foreign frame() and

PL close foreign frame().

module t A module is a unique handle to a Prolog module. Modules are used only to call predicates
in a specific module.

foreign t Return type for a C function implementing a Prolog predicate.

control t Passed as additional argument to non-deterministic foreign functions. See PL retry*() and
PL foreign context*().

install t Type for the install() and uninstall() functions of shared or dynamic link libraries. See sec-
tion 11.2.3.

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 321

int64 t Actually part of the C99 standard rather than Prolog. As of version 5.5.6, Prolog integers are
64-bit on all hardware. The C99 type int64 t is defined in the stdint.h standard header
and provides platform-independent 64-bit integers. Portable code accessing Prolog should use
this type to exchange integer values. Please note that PL get long() can return FALSE on
Prolog integers that cannot be represented as a C long. Robust code should not assume any of
the integer fetching functions to succeed, even if the Prolog term is known to be an integer.

PL ARITY AS SIZE
As of SWI-Prolog 7.3.12, the arity of terms has changed from int to size t. To deal with this tran-
sition, all affecting functions have two versions, where the old name exchanges the arity as int and a
new function with name * sz() exchanges the arity as size t. If the C macro PL ARITY AS SIZE
is defined before loading SWI-Prolog.h, macros are put in place that map the old names to the
new functions. Without precautions, the old code is compatible, but the following warning is printed
when compiling:

#warning "Term arity has changed from int to size_t."

#warning "Please update your code and use #define PL_ARITY_AS_SIZE 1."

To make the code compile silently again, include SWI-Prolog.h as below and change the types
you use to represent arity from int to size t. Please be aware that size t is unsigned.

#define PL_ARITY_AS_SIZE
#include <SWI-Prolog.h>

11.4 The Foreign Include File

11.4.1 Argument Passing and Control
If Prolog encounters a foreign predicate at run time it will call a function specified in the predicate
definition of the foreign predicate. The arguments 1, . . . , harityi pass the Prolog arguments to the goal
as Prolog terms. Foreign functions should be declared of type foreign t. Deterministic foreign
functions have two alternatives to return control back to Prolog:

(return) foreign t PL succeed()

Succeed deterministically. PL succeed is defined as return TRUE.

(return) foreign t PL fail()

Fail and start Prolog backtracking. PL fail is defined as return FALSE.

Non-deterministic Foreign Predicates

By default foreign predicates are deterministic. Using the PL FA NONDETERMINISTIC attribute
(see PL register foreign()) it is possible to register a predicate as a non-deterministic predi-
cate. Writing non-deterministic foreign predicates is slightly more complicated as the foreign function
needs context information for generating the next solution. Note that the same foreign function should

SWI-Prolog 7.4 Reference Manual

322 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

be prepared to be simultaneously active in more than one goal. Suppose the natural number below n/2
is a non-deterministic foreign predicate, backtracking over all natural numbers lower than the first ar-
gument. Now consider the following predicate:

quotient_below_n(Q, N) :-
natural_number_below_n(N, N1),
natural_number_below_n(N, N2),
Q =:= N1 / N2, !.

In this predicate the function natural number below n/2 simultaneously generates solutions for both
its invocations.
Non-deterministic foreign functions should be prepared to handle three different calls from Prolog:

Initial call (PL FIRST CALL)

Prolog has just created a frame for the foreign function and asks it to produce the first answer.

Redo call (PL REDO)

The previous invocation of the foreign function associated with the current goal indicated it was
possible to backtrack. The foreign function should produce the next solution.

Terminate call (PL PRUNED)

The choice point left by the foreign function has been destroyed by a cut. The foreign function
is given the opportunity to clean the environment.

Both the context information and the type of call is provided by an argument of type
control t appended to the argument list for deterministic foreign functions. The macro
PL foreign control() extracts the type of call from the control argument. The foreign func-
tion can pass a context handle using the PL retry*() macros and extract the handle from the extra
argument using the PL foreign context*() macro.

(return) foreign t PL retry(intptr t value)

The foreign function succeeds while leaving a choice point. On backtracking over this goal the
foreign function will be called again, but the control argument now indicates it is a Redo call
and the macro PL foreign context() returns the handle passed via PL retry(). This
handle is a signed value two bits smaller than a pointer, i.e., 30 or 62 bits (two bits are used for
status indication). Defined as return PL retry(n). See also PL succeed().

(return) foreign t PL retry address(void *)

As PL retry(), but ensures an address as returned by malloc() is correctly recovered by
PL foreign context address(). Defined as return PL retry address(n).
See also PL succeed().

int PL foreign control(control t)

Extracts the type of call from the control argument. The return values are described above.
Note that the function should be prepared to handle the PL PRUNED case and should be aware
that the other arguments are not valid in this case.

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 323

typedef struct /* define a context structure */

{ ...
} context;

foreign_t
my_function(term_t a0, term_t a1, control_t handle)
{ struct context * ctxt;

switch( PL_foreign_control(handle) )
{ case PL_FIRST_CALL:
ctxt = malloc(sizeof(struct context));
...
PL_retry_address(ctxt);
case PL_REDO:
ctxt = PL_foreign_context_address(handle);
...
PL_retry_address(ctxt);
case PL_PRUNED:
ctxt = PL_foreign_context_address(handle);
...
free(ctxt);
PL_succeed;
}
}

Figure 11.1: Skeleton for non-deterministic foreign functions

intptr t PL foreign context(control t)

Extracts the context from the context argument. If the call type is PL FIRST CALL the context
value is 0L. Otherwise it is the value returned by the last PL retry() associated with this
goal (both if the call type is PL REDO or PL PRUNED).

void * PL foreign context address(control t)

Extracts an address as passed in by PL retry address().

predicate t PL foreign context predicate(control t)

Fetch the Prolog predicate that is executing this function. Note that if the predicate is imported,
the returned predicate refers to the final definition rather than the imported predicate, i.e., the
module reported by PL predicate info() is the module in which the predicate is defined
rather than the module where it was called. See also PL predicate info().

Note: If a non-deterministic foreign function returns using PL succeed() or PL fail(),

Prolog assumes the foreign function has cleaned its environment. No call with control argument
PL PRUNED will follow.
The code of figure 11.1 shows a skeleton for a non-deterministic foreign predicate definition.

SWI-Prolog 7.4 Reference Manual

324 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

11.4.2 Atoms and functors

The following functions provide for communication using atoms and functors.

atom t PL new atom(const char *)

Return an atom handle for the given C-string. This function always succeeds. The returned
handle is valid as long as the atom is referenced (see section 11.4.2). The following atoms are
provided as macros, giving access to the empty list symbol and the name of the list constructor.
Prior to version 7, ATOM nil is the same as PL new atom([]) and ATOM dot is the
same as PL new atom(.). This is no long the case in SWI-Prolog version 7.

atom t ATOM nil(A)

tomic constant that represents the empty list. It is adviced to use PL get nil(),
PL put nil() or PL unify nil() where applicable.
atom t ATOM dot(A)
tomic constant that represents the name of the list constructor. The list constructor itself is
created using PL new functor(ATOM dot,2). It is adviced to use PL get list(),
PL put list() or PL unify list() where applicable.

const char* PL atom chars(atom t atom)

Return a C-string for the text represented by the given atom. The returned text will not be
changed by Prolog. It is not allowed to modify the contents, not even temporary as the string
may reside in read-only memory. The returned string becomes invalid if the atom is garbage
collected (see section 11.4.2). Foreign functions that require the text from an atom passed in a
term t normally use PL get atom chars() or PL get atom nchars().

functor t PL new functor(atom t name, int arity)

Returns a functor identifier, a handle for the name/arity pair. The returned handle is valid for
the entire Prolog session.

atom t PL functor name(functor t f)

Return an atom representing the name of the given functor.

size t PL functor arity(functor t f)

Return the arity of the given functor.

Atoms and atom garbage collection

With the introduction of atom garbage collection in version 3.3.0, atoms no longer live as long as the
process. Instead, their lifetime is guaranteed only as long as they are referenced. In the single-threaded
version, atom garbage collections are only invoked at the call-port. In the multithreaded version (see
chapter 9), they appear asynchronously, except for the invoking thread.
For dealing with atom garbage collection, two additional functions are provided:

void PL register atom(atom t atom)

Increment the reference count of the atom by one. PL new atom() performs this automati-
cally, returning an atom with a reference count of at least one.3
3
Otherwise asynchronous atom garbage collection might destroy the atom before it is used.

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 325

void PL unregister atom(atom t atom)

Decrement the reference count of the atom. If the reference count drops below zero, an assertion
error is raised.

Please note that the following two calls are different with respect to atom garbage collection:

PL_unify_atom_chars(t, "text");
PL_unify_atom(t, PL_new_atom("text"));

The latter increments the reference count of the atom text, which effectively ensures the atom will
never be collected. It is advised to use the * chars() or * nchars() functions whenever applicable.

11.4.3 Analysing Terms via the Foreign Interface

Each argument of a foreign function (except for the control argument) is of type term t, an opaque
handle to a Prolog term. Three groups of functions are available for the analysis of terms. The first
just validates the type, like the Prolog predicates var/1, atom/1, etc., and are called PL is *().
The second group attempts to translate the argument into a C primitive type. These predicates take a
term t and a pointer to the appropriate C type and return TRUE or FALSE depending on successful
or unsuccessful translation. If the translation fails, the pointed-to data is never modified.

Testing the type of a term

int PL term type(term t)

Obtain the type of a term, which should be a term returned by one of the other interface pred-
icates or passed as an argument. The function returns the type of the Prolog term. The type
identifiers are listed below. Note that the extraction functions PL get *() also validate the
type and thus the two sections below are equivalent.

if ( PL_is_atom(t) )
{ char *s;

PL_get_atom_chars(t, &s);
...;
}

or

char *s;
if ( PL_get_atom_chars(t, &s) )
{ ...;
}

Version 7 added PL NIL, PL BLOB, PL LIST PAIR and PL DICT. Older versions classify
PL NIL and PL BLOB as PL ATOM, PL LIST PAIR as PL TERM and do not have dicts.

SWI-Prolog 7.4 Reference Manual

326 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

PL VARIABLE A variable or attributed variable

PL ATOM A Prolog atom
PL NIL The constant []
PL BLOB A blob (see section 11.4.7)
PL STRING A string (see section 5.2)
PL INTEGER A integer
PL FLOAT A floating point number
PL TERM A compound term
PL LIST PAIR A list cell ([H|T])
PL DICT A dict (see section 5.4))

The functions PL is htypei are an alternative to PL term type(). The test

PL is variable(term) is equivalent to PL term type(term) == PL VARIABLE, but
the first is considerably faster. On the other hand, using a switch over PL term type() is faster
and more readable then using an if-then-else using the functions below. All these functions return
either TRUE or FALSE.

int PL is variable(term t)
Returns non-zero if term is a variable.
int PL is ground(term t)
Returns non-zero if term is a ground term. See also ground/1. This function is cycle-safe.
int PL is atom(term t)
Returns non-zero if term is an atom.
int PL is string(term t)
Returns non-zero if term is a string.
int PL is integer(term t)
Returns non-zero if term is an integer.
int PL is float(term t)
Returns non-zero if term is a float.
int PL is callable(term t)
Returns non-zero if term is a callable term. See callable/1 for details.
int PL is compound(term t)
Returns non-zero if term is a compound term.
int PL is functor(term t, functor t)
Returns non-zero if term is compound and its functor is functor. This test is equivalent to
PL get functor(), followed by testing the functor, but easier to write and faster.
int PL is list(term t)
Returns non-zero if term is a compound term using the list constructor or the list terminator.
See also PL is pair() and PL skip list().
int PL is pair(term t)
Returns non-zero if term is a compound term using the list constructor. See also
PL is list() and PL skip list().

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 327

int PL is atomic(term t)
Returns non-zero if term is atomic (not variable or compound).

int PL is number(term t)
Returns non-zero if term is an integer or float.

int PL is acyclic(term t)
Returns non-zero if term is acyclic (i.e. a finite tree).

Reading data from a term

The functions PL get *() read information from a Prolog term. Most of them take two arguments.
The first is the input term and the second is a pointer to the output value or a term reference.

int PL get atom(term t +t, atom t *a)

If t is an atom, store the unique atom identifier over a. See also PL atom chars() and
PL new atom(). If there is no need to access the data (characters) of an atom, it is
advised to manipulate atoms using their handle. As the atom is referenced by t, it will live
at least as long as t does. If longer live-time is required, the atom should be locked using
PL register atom().

int PL get atom chars(term t +t, char **s)

If t is an atom, store a pointer to a 0-terminated C-string in s. It is explicitly not allowed
to modify the contents of this string. Some built-in atoms may have the string allocated in
read-only memory, so temporary manipulation can cause an error.

int PL get string chars(term t +t, char **s, size t *len)

If t is a string object, store a pointer to a 0-terminated C-string in s and the length of the string
in len. Note that this pointer is invalidated by backtracking, garbage collection and stack-shifts,
so generally the only save operations are to pass it immediately to a C function that doesnt
involve Prolog.

int PL get chars(term t +t, char **s, unsigned flags)

Convert the argument term t to a 0-terminated C-string. flags is a bitwise disjunction from two
groups of constants. The first specifies which term types should be converted and the second
how the argument is stored. Below is a specification of these constants. BUF RING implies,
if the data is not static (as from an atom), that the data is copied to the next buffer from a ring
of 16 buffers. This is a convenient way of converting multiple arguments passed to a foreign
predicate to C-strings. If BUF MALLOC is used, the data must be freed using PL free()
when no longer needed.
With the introduction of wide characters (see section 2.18.1), not all atoms can be converted into
a char*. This function fails if t is of the wrong type, but also if the text cannot be represented.
See the REP * flags below for details.

CVT ATOM
Convert if term is an atom.
CVT STRING
Convert if term is a string.

SWI-Prolog 7.4 Reference Manual

328 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

CVT LIST
Convert if term is a list of of character codes.
CVT INTEGER
Convert if term is an integer.
CVT FLOAT
Convert if term is a float. The characters returned are the same as write/1 would write
for the floating point number.
CVT NUMBER
Convert if term is an integer or float.
CVT ATOMIC
Convert if term is atomic.
CVT VARIABLE
Convert variable to print-name
CVT WRITE
Convert any term that is not converted by any of the other flags using write/1. If no
BUF * is provided, BUF RING is implied.
CVT WRITE CANONICAL
As CVT WRITE, but using write canonical/2.
CVT WRITEQ
As CVT WRITE, but using writeq/2.
CVT ALL
Convert if term is any of the above, except for CVT VARIABLE and CVT WRITE*.
CVT EXCEPTION
If conversion fails due to a type error, raise a Prolog type error exception in addition to
failure
BUF DISCARDABLE
Data must copied immediately
BUF RING
Data is stored in a ring of buffers
BUF MALLOC
Data is copied to a new buffer returned by PL malloc(3). When no longer needed the
user must call PL free() on the data.
REP ISO LATIN 1
Text is in ISO Latin-1 encoding and the call fails if text cannot be represented. This flag
has the value 0 and is thus the default.
REP UTF8
Convert the text to a UTF-8 string. This works for all text.
REP MB
Convert to default locale-defined 8-bit string. Success depends on the locale. Conversion
is done using the wcrtomb() C library function.

int PL get list chars(+term t l, char **s, unsigned flags)

Same as PL get chars(l, s, CVT LISTflags), provided flags contains none of the CVT *
flags.

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 329

int PL get integer(+term t t, int *i)

If t is a Prolog integer, assign its value over i. On 32-bit machines, this is the same as
PL get long(), but avoids a warning from the compiler. See also PL get long().
int PL get long(term t +t, long *i)
If t is a Prolog integer that can be represented as a long, assign its value over i. If t is an
integer that cannot be represented by a C long, this function returns FALSE. If t is a floating
point number that can be represented as a long, this function succeeds as well. See also
PL get int64().
int PL get int64(term t +t, int64 t *i)
If t is a Prolog integer or float that can be represented as a int64 t, assign its value over
i. Currently all Prolog integers can be represented using this type, but this might change if
SWI-Prolog introduces unbounded integers.
int PL get intptr(term t +t, intptr t *i)
Get an integer that is at least as wide as a pointer. On most platforms this is the
same as PL get long(), but on Win64 pointers are 8 bytes and longs only 4. Unlike
PL get pointer(), the value is not modified.
int PL get bool(term t +t, int *val)
If t has the value true or false, set val to the C constant TRUE or FALSE and return success,
otherwise return failure.
int PL get pointer(term t +t, void **ptr)
In the current system, pointers are represented by Prolog integers, but need some manipu-
lation to make sure they do not get truncated due to the limited Prolog integer range.
PL put pointer() and PL get pointer() guarantee pointers in the range of malloc()
are handled without truncating.
int PL get float(term t +t, double *f)
If t is a float or integer, its value is assigned over f.
int PL get functor(term t +t, functor t *f)
If t is compound or an atom, the Prolog representation of the name-arity pair will be assigned
over f. See also PL get name arity() and PL is functor().
int PL get name arity(term t +t, atom t *name, size t *arity)
If t is compound or an atom, the functor name will be assigned over name and the arity over
arity. See also PL get functor() and PL is functor(). See section 11.3.2.
int PL get compound name arity(term t +t, atom t *name, size t *arity)
If t is compound term, the functor name will be assigned over name and the arity over arity.
This is the same as PL get name arity(), but this function fails if t is an atom.
int PL get module(term t +t, module t *module)
If t is an atom, the system will look up or create the corresponding module and assign an
opaque pointer to it over module.
int PL get arg(size t index, term t +t, term t -a)
If t is compound and index is between 1 and arity (inclusive), assign a with a term reference to
the argument.

SWI-Prolog 7.4 Reference Manual

330 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

int PL get arg(size t index, term t +t, term t -a)

Same as PL get arg(), but no checking is performed, neither whether t is actually a term
nor whether index is a valid argument index.

Exchanging text using length and string

All internal text representation in SWI-Prolog is represented using char * plus length and allow
for 0-bytes in them. The foreign library supports this by implementing a * nchars() function for each
applicable * chars() function. Below we briefly present the signatures of these functions. For full
documentation consult the * chars() function.

int PL get atom nchars(term t t, size t *len, char **s)

See PL get atom chars().

int PL get list nchars(term t t, size t *len, char **s)

See PL get list chars().

int PL get nchars(term t t, size t *len, char **s, unsigned int flags)
See PL get chars().

int PL put atom nchars(term t t, size t len, const char *s)

See PL put atom chars().

int PL put string nchars(term t t, size t len, const char *s)

See PL put string chars().

int PL put list ncodes(term t t, size t len, const char *s)

See PL put list codes().

int PL put list nchars(term t t, size t len, const char *s)

See PL put list chars().

int PL unify atom nchars(term t t, size t len, const char *s)

See PL unify atom chars().

int PL unify string nchars(term t t, size t len, const char *s)

See PL unify string chars().

int PL unify list ncodes(term t t, size t len, const char *s)

See PL unify codes().

int PL unify list nchars(term t t, size t len, const char *s)

See PL unify list chars().

In addition, the following functions are available for creating and inspecting atoms:

atom t PL new atom nchars(size t len, const char *s)

Create a new atom as PL new atom(), but using the given length and characters. If len is
(size t)-1, it is computed from s using strlen().

const char * PL atom nchars(atom t a, size t *len)

Extract the text and length of an atom.

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 331

Wide-character versions
Support for exchange of wide-character strings is still under consideration. The functions dealing
with 8-bit character strings return failure when operating on a wide-character atom or Prolog string
object. The functions below can extract and unify both 8-bit and wide atoms and string objects. Wide
character strings are represented as C arrays of objects of the type pl wchar t, which is guaranteed
to be the same as wchar t on platforms supporting this type. For example, on MS-Windows, this
represents 16-bit UCS2 characters, while using the GNU C library (glibc) this represents 32-bit UCS4
characters.

atom t PL new atom wchars(size t len, const pl wchar t *s)

Create atom from wide-character string as PL new atom nchars() does for ISO-Latin-1
strings. If s only contains ISO-Latin-1 characters a normal byte-array atom is created. If len is
(size t)-1, it is computed from s using wcslen().

pl wchar t* PL atom wchars(atom t atom, int *len)

Extract characters from a wide-character atom. Succeeds on any atom marked as text. If
the underlying atom is a wide-character atom, the returned pointer is a pointer into the atom
structure. If it is an ISO-Latin-1 character, the returned pointer comes from Prologs buffer
ring (see PL get chars()).

int PL get wchars(term t t, size t *len, pl wchar t **s, unsigned flags)

Wide-character version of PL get chars(). The flags argument is the same as for
PL get chars().

int PL unify wchars(term t t, int type, size t len, const pl wchar t *s)
Unify t with a textual representation of the C wide-character array s. The type argument de-
fines the Prolog representation and is one of PL ATOM, PL STRING, PL CODE LIST or
PL CHAR LIST.

int PL unify wchars diff(term t +t, term t -tail, int type, size t len, const pl wchar t *s)
Difference list version of PL unify wchars(), only supporting the types PL CODE LIST
and PL CHAR LIST. It serves two purposes. It allows for returning very long lists from
data read from a stream without the need for a resizing buffer in C. Also, the use of dif-
ference lists is often practical for further processing in Prolog. Examples can be found in
packages/clib/readutil.c from the source distribution.

Reading a list
The functions from this section are intended to read a Prolog list from C. Suppose we expect a list of
atoms; the following code will print the atoms, each on a line:

foreign_t
pl_write_atoms(term_t l)
{ term_t head = PL_new_term_ref(); /* the elements */
term_t list = PL_copy_term_ref(l); /* copy (we modify list) */

while( PL_get_list(list, head, list) )

{ char *s;

SWI-Prolog 7.4 Reference Manual

332 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

if ( PL_get_atom_chars(head, &s) )
Sprintf("%s\n", s);
else
PL_fail;
}

return PL_get_nil(list); /* test end for [] */

}

Note that as of version 7, lists have a new representation unless the option --traditional is used.
see section 5.1.
int PL get list(term t +l, term t -h, term t -t)
If l is a list and not the empty list, assign a term reference to the head to h and to the tail to t.
int PL get head(term t +l, term t -h)
If l is a list and not the empty list, assign a term reference to the head to h.
int PL get tail(term t +l, term t -t)
If l is a list and not the empty list, assign a term reference to the tail to t.
int PL get nil(term t +l)
Succeeds if l represents the list termination constant.
int PL skip list(term t +list, term t -tail, size t *len)
This is a multi-purpose function to deal with lists. It allows for finding the length of a list,
checking whether something is a list, etc. The reference tail is set to point to the end of the list,
len is filled with the number of list-cells skipped, and the return value indicates the status of the
list:

PL LIST
The list is a proper list: one that ends in the list terminator constant and tail is filled with
the terminator constant.
PL PARTIAL LIST
The list is a partial list: one that ends in a variable and tail is a reference to this variable.
PL CYCLIC TERM
The list is cyclic (e.g. X = [aX]). tail points to an arbitrary cell of the list and len is at
most twice the cycle length of the list.
PL NOT A LIST
The term list is not a list at all. tail is bound to the non-list term and len is set to the
number of list-cells skipped.

It is allowed to pass 0 for tail and NULL for len.

An example: defining write/1 in C

Figure 11.2 shows a simplified definition of write/1 to illustrate the described functions. This
simplified version does not deal with operators. It is called display/1, because it mimics closely
the behaviour of this Edinburgh predicate.

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 333

foreign_t
pl_display(term_t t)
{ functor_t functor;
int arity, len, n;
char *s;

switch( PL_term_type(t) )
{ case PL_VARIABLE:
case PL_ATOM:
case PL_INTEGER:
case PL_FLOAT:
PL_get_chars(t, &s, CVT_ALL);
Sprintf("%s", s);
break;
case PL_STRING:
PL_get_string_chars(t, &s, &len);
Sprintf("\"%s\"", s);
break;
case PL_TERM:
{ term_t a = PL_new_term_ref();

PL_get_name_arity(t, &name, &arity);

Sprintf("%s(", PL_atom_chars(name));
for(n=1; n<=arity; n++)
{ PL_get_arg(n, t, a);
if ( n > 1 )
Sprintf(", ");
pl_display(a);
}
Sprintf(")");
break;
default:
PL_fail; /* should not happen */
}
}

PL_succeed;
}

Figure 11.2: A Foreign definition of display/1

SWI-Prolog 7.4 Reference Manual

334 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

11.4.4 Constructing Terms

Terms can be constructed using functions from the PL put *() and PL cons *() families. This
approach builds the term inside-out, starting at the leaves and subsequently creating compound
terms. Alternatively, terms may be created top-down, first creating a compound holding only vari-
ables and subsequently unifying the arguments. This section discusses functions for the first approach.
This approach is generally used for creating arguments for PL call() and PL open query().

void PL put variable(term t -t)

Put a fresh variable in the term, resetting the term reference to its initial state.4
void PL put atom(term t -t, atom t a)
Put an atom in the term reference from a handle. See also PL new atom() and
PL atom chars().
void PL put bool(term t -t, int val)
Put one of the atoms true or false in the term reference See also PL put atom(),
PL unify bool() and PL get bool().
int PL put atom chars(term t -t, const char *chars)
Put an atom in the term reference constructed from the zero-terminated string. The string itself
will never be referenced by Prolog after this function.
int PL put string chars(term t -t, const char *chars)
Put a zero-terminated string in the term reference. The data will be copied. See also
PL put string nchars().
int PL put string nchars(term t -t, size t len, const char *chars)
Put a string, represented by a length/start pointer pair in the term reference. The data will be
copied. This interface can deal with 0-bytes in the string. See also section 11.4.20.
int PL put list chars(term t -t, const char *chars)
Put a list of ASCII values in the term reference.
int PL put integer(term t -t, long i)
Put a Prolog integer in the term reference.
int PL put int64(term t -t, int64 t i)
Put a Prolog integer in the term reference.
int PL put pointer(term t -t, void *ptr)
Put a Prolog integer in the term reference. Provided ptr is in the malloc()-area,
PL get pointer() will get the pointer back.
int PL put float(term t -t, double f)
Put a floating-point value in the term reference.
int PL put functor(term t -t, functor t functor)
Create a new compound term from functor and bind t to this term. All arguments of the term
will be variables. To create a term with instantiated arguments, either instantiate the arguments
using the PL unify *() functions or use PL cons functor().
4
Older versions created a variable on the global stack.

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 335

int PL put list(term t -l)

As PL put functor(), using the list-cell functor. Note that on classical Prolog systems
or in SWI-Prolog using the option --traditional, this is ./2, while on SWI-Prolog
version 7 this is [|]/2.

int PL put nil(term t -l)

Put the list terminator constant in l. Always returns TRUE. Note that in classical Pro-
log systems or in SWI-Prolog using the option --traditional, this is the same as
PL put atom chars([]). See section 5.1.

void PL put term(term t -t1, term t +t2)

Make t1 point to the same term as t2.

int PL cons functor(term t -h, functor t f, . . . )

Create a term whose arguments are filled from a variable argument list holding the same number
of term t objects as the arity of the functor. To create the term animal(gnu, 50), use:

{ term_t a1 = PL_new_term_ref();
term_t a2 = PL_new_term_ref();
term_t t = PL_new_term_ref();
functor_t animal2;

/* animal2 is a constant that may be bound to a global

variable and re-used
*/
animal2 = PL_new_functor(PL_new_atom("animal"), 2);

PL_put_atom_chars(a1, "gnu");
PL_put_integer(a2, 50);
PL_cons_functor(t, animal2, a1, a2);
}

After this sequence, the term references a1 and a2 may be used for other purposes.

int PL cons functor v(term t -h, functor t f, term t a0)

Create a compound term like PL cons functor(), but a0 is an array of term references
as returned by PL new term refs(). The length of this array should match the number of
arguments required by the functor.

int PL cons list(term t -l, term t +h, term t +t)

Create a list (cons-) cell in l from the head h and tail t. The code below creates a list of atoms
from a char **. The list is built tail-to-head. The PL unify *() functions can be used to
build a list head-to-tail.

void
put_list(term_t l, int n, char **words)
{ term_t a = PL_new_term_ref();

SWI-Prolog 7.4 Reference Manual

336 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

PL_put_nil(l);
while( --n >= 0 )
{ PL_put_atom_chars(a, words[n]);
PL_cons_list(l, a, l);
}
}

Note that l can be redefined within a PL cons list call as shown here because operationally
its old value is consumed before its new value is set.

11.4.5 Unifying data

The functions of this section unify terms with other terms or translated C data structures. Except
for PL unify(), these functions are specific to SWI-Prolog. They have been introduced because
they shorten the code for returning data to Prolog and at the same time make this more efficient by
avoiding the need to allocate temporary term references and reduce the number of calls to the Prolog
API. Consider the case where we want a foreign function to return the host name of the machine
Prolog is running on. Using the PL get *() and PL put *() functions, the code becomes:

foreign_t
pl_hostname(term_t name)
{ char buf[100];

if ( gethostname(buf, sizeof(buf)) )
{ term_t tmp = PL_new_term_ref();

PL_put_atom_chars(tmp, buf);
return PL_unify(name, tmp);
}

PL_fail;
}

Using PL unify atom chars(), this becomes:

foreign_t
pl_hostname(term_t name)
{ char buf[100];

if ( gethostname(buf, sizeof(buf)) )
return PL_unify_atom_chars(name, buf);

PL_fail;
}

Note that unification functions that perform multiple bindings may leave part of the bindings in case
of failure. See PL unify() for details.

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 337

int PL unify(term t ?t1, term t ?t2)

Unify two Prolog terms and return TRUE on success.
Care is needed if PL unify() returns FAIL and the foreign function does not immediately
return to Prolog with FAIL. Unification may perform multiple changes to either t1 or t2. A
failing unification may have created bindings before failure is detected. Already created bind-
ings are not undone. For example, calling PL unify() on a(X, a) and a(c,b) binds X to c and
fails when trying to unify a to b. If control remains in C or even if we want to return success to
Prolog, we must undo such bindings. This is achieved using PL open foreign frame()
and PL rewind foreign frame(), as shown in the snippet below.

{ fid_t fid = PL_open_foreign_frame();

...
if ( !PL_unify(t1, t2) )
PL_rewind_foreign_frame(fid);
...

PL_close_foreign_frame(fid);
}

In addition, PL unify() may have failed on an exception, typically a resource (stack) over-
flow. This can be tested using PL exception(), passing 0 (zero) for the query-id argument.
Foreign functions that encounter an exception must return FAIL to Prolog as soon as possible
or call PL clear exception() if they wish to ignore the exception.

int PL unify atom(term t ?t, atom t a)

Unify t with the atom a and return non-zero on success.

int PL unify bool(term t ?t, int a)

Unify t with either true or false.

int PL unify chars(term t ?t, int flags, size t len, const char *chars)
New function to deal with unification of char* with various encodings to a Prolog represen-
tation. The flags argument is a bitwise or specifying the Prolog target type and the encoding of
chars. A Prolog type is one of PL ATOM, PL STRING, PL CODE LIST or PL CHAR LIST. A
representation is one of REP ISO LATIN 1, REP UTF8 or REP MB. See PL get chars()
for a definition of the representation types. If len is -1 chars must be zero-terminated and the
length is computed from chars using strlen().
If flags includes PL DIFF LIST and type is one of PL CODE LIST or PL CHAR LIST, the
text is converted to a difference list. The tail of the difference list is t + 1.

int PL unify atom chars(term t ?t, const char *chars)

Unify t with an atom created from chars and return non-zero on success.

int PL unify list chars(term t ?t, const char *chars)

Unify t with a list of ASCII characters constructed from chars.

SWI-Prolog 7.4 Reference Manual

338 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

void PL unify string chars(term t ?t, const char *chars)

Unify t with a Prolog string object created from the zero-terminated string chars. The data will
be copied. See also PL unify string nchars().

int PL unify integer(term t ?t, intptr t n)

Unify t with a Prolog integer from n.

int PL unify int64(term t ?t, int64 t n)

Unify t with a Prolog integer from n.

int PL unify float(term t ?t, double f)

Unify t with a Prolog float from f.

int PL unify pointer(term t ?t, void *ptr)

Unify t with a Prolog integer describing the pointer. See also PL put pointer() and
PL get pointer().

int PL unify functor(term t ?t, functor t f)

If t is a compound term with the given functor, just succeed. If it is unbound, create a term
and bind the variable, else fail. Note that this function does not create a term if the argument
is already instantiated. If f is a functor with arity 0, t is unified with an atom. See also
PL unify compound().

int PL unify compound(term t ?t, functor t f)

If t is a compound term with the given functor, just succeed. If it is unbound, create a term and
bind the variable, else fail. Note that this function does not create a term if the argument is
already instantiated. If f is a functor with arity 0, t is unified with compound without arguments.
See also PL unify functor().

int PL unify list(term t ?l, term t -h, term t -t)

Unify l with a list-cell (./2). If successful, write a reference to the head of the list into h
and a reference to the tail of the list into t. This reference may be used for subsequent calls
to this function. Suppose we want to return a list of atoms from a char **. We could use
the example described by PL put list(), followed by a call to PL unify(), or we can
use the code below. If the predicate argument is unbound, the difference is minimal (the code
based on PL put list() is probably slightly faster). If the argument is bound, the code
below may fail before reaching the end of the word list, but even if the unification succeeds,
this code avoids a duplicate (garbage) list and a deep unification.

foreign_t
pl_get_environ(term_t env)
{ term_t l = PL_copy_term_ref(env);
term_t a = PL_new_term_ref();
extern char **environ;
char **e;

for(e = environ; *e; e++)

{ if ( !PL_unify_list(l, a, l) ||
!PL_unify_atom_chars(a, *e) )

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 339

PL_fail;
}

return PL_unify_nil(l);
}

int PL unify nil(term t ?l)

Unify l with the atom [].

int PL unify arg(int index, term t ?t, term t ?a)

Unifies the index-th argument (1-based) of t with a.

int PL unify term(term t ?t, . . . )

Unify t with a (normally) compound term. The remaining arguments are a sequence of a type
identifier followed by the required arguments. This predicate is an extension to the Quintus and
SICStus foreign interface from which the SWI-Prolog foreign interface has been derived, but
has proved to be a powerful and comfortable way to create compound terms from C. Due to
the vararg packing/unpacking and the required type-switching this interface is slightly slower
than using the primitives. Please note that some bad C compilers have fairly low limits on the
number of arguments that may be passed to a function.
Special attention is required when passing numbers. C promotes any integral smaller than int
to int. That is, the types char, short and int are all passed as int. In addition, on most
32-bit platforms int and long are the same. Up to version 4.0.5, only PL INTEGER could
be specified, which was taken from the stack as long. Such code fails when passing small
integral types on machines where int is smaller than long. It is advised to use PL SHORT,
PL INT or PL LONG as appropriate. Similarly, C compilers promote float to double and
therefore PL FLOAT and PL DOUBLE are synonyms.
The type identifiers are:

PL VARIABLE none
No op. Used in arguments of PL FUNCTOR.
PL BOOL int
Unify the argument with true or false.
PL ATOM atom t
Unify the argument with an atom, as in PL unify atom().
PL CHARS const char *
Unify the argument with an atom constructed from the C char *, as in
PL unify atom chars().
PL NCHARS size t, const char *
Unify the argument with an atom constructed from length and char* as in
PL unify atom nchars().
PL UTF8 CHARS const char *
Create an atom from a UTF-8 string.
PL UTF8 STRING const char *
Create a packed string object from a UTF-8 string.

SWI-Prolog 7.4 Reference Manual

340 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

PL MBCHARS const char *

Create an atom from a multi-byte string in the current locale.
PL MBCODES const char *
Create a list of character codes from a multi-byte string in the current locale.
PL MBSTRING const char *
Create a packed string object from a multi-byte string in the current locale.
PL NWCHARS size t, const wchar t *
Create an atom from a length and a wide character pointer.
PL NWCODES size t, const wchar t *
Create a list of character codes from a length and a wide character pointer.
PL NWSTRING size t, const wchar t *
Create a packed string object from a length and a wide character pointer.
PL SHORT short
Unify the argument with an integer, as in PL unify integer(). As short is pro-
moted to int, PL SHORT is a synonym for PL INT.
PL INTEGER long
Unify the argument with an integer, as in PL unify integer().
PL INT int
Unify the argument with an integer, as in PL unify integer().
PL LONG long
Unify the argument with an integer, as in PL unify integer().
PL INT64 int64 t
Unify the argument with a 64-bit integer, as in PL unify int64().
PL INTPTR intptr t
Unify the argument with an integer with the same width as a pointer. On most machines
this is the same as PL LONG. but on 64-bit MS-Windows pointers are 64 bits while longs
are only 32 bits.
PL DOUBLE double
Unify the argument with a float, as in PL unify float(). Note that, as the argument
is passed using the C vararg conventions, a float must be casted to a double explicitly.
PL FLOAT double
Unify the argument with a float, as in PL unify float().
PL POINTER void *
Unify the argument with a pointer, as in PL unify pointer().
PL STRING const char *
Unify the argument with a string object, as in PL unify string chars().
PL TERM term t
Unify a subterm. Note this may be the return value of a PL new term ref() call to
get access to a variable.
PL FUNCTOR functor t, . . .
Unify the argument with a compound term. This specification should be followed by
exactly as many specifications as the number of arguments of the compound term.

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 341

PL FUNCTOR CHARS const char *name, int arity, . . .

Create a functor from the given name and arity and then behave as PL FUNCTOR.
PL LIST int length, . . .
Create a list of the indicated length. The remaining arguments contain the elements of the
list.

For example, to unify an argument with the term language(dutch), the following skeleton
may be used:

static functor_t FUNCTOR_language1;

static void
init_constants()
{ FUNCTOR_language1 = PL_new_functor(PL_new_atom("language"),1);
}

foreign_t
pl_get_lang(term_t r)
{ return PL_unify_term(r,
PL_FUNCTOR, FUNCTOR_language1,
PL_CHARS, "dutch");
}

install_t
install()
{ PL_register_foreign("get_lang", 1, pl_get_lang, 0);
init_constants();
}

int PL chars to term(const char *chars, term t -t)

Parse the string chars and put the resulting Prolog term into t. chars may or may not be closed
using a Prolog full-stop (i.e., a dot followed by a blank). Returns FALSE if a syntax error
was encountered and TRUE after successful completion. In addition to returning FALSE, the
exception-term is returned in t on a syntax error. See also term to atom/2.
The following example builds a goal term from a string and calls it.

int
call_chars(const char *goal)
{ fid_t fid = PL_open_foreign_frame();
term_t g = PL_new_term_ref();
BOOL rval;

if ( PL_chars_to_term(goal, g) )
rval = PL_call(goal, NULL);
else
rval = FALSE;

SWI-Prolog 7.4 Reference Manual

342 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

PL_discard_foreign_frame(fid);
return rval;
}
...
call_chars("consult(load)");
...

int PL wchars to term(const pl wchar t *chars, term t -t)

Wide character version of PL chars to term().

char * PL quote(int chr, const char *string)

Return a quoted version of string. If chr is \, the result is a quoted atom. If chr is ", the
result is a string. The result string is stored in the same ring of buffers as described with the
BUF RING argument of PL get chars();
In the current implementation, the string is surrounded by chr and any occurrence of chr is
doubled. In the future the behaviour will depend on the character escapes Prolog flag.

11.4.6 Convenient functions to generate Prolog exceptions

The typical implementation of a foreign predicate first uses the PL get *() functions to extract C data
types from the Prolog terms. Failure of any of these functions is normally because the Prolog term
is of the wrong type. The * ex() family of functions are wrappers around (mostly) the PL get *()
functions, such that we can write code in the style below and get proper exceptions if an argument is
uninstantiated or of the wrong type.

/** set_size(+Name:atom, +Width:int, +Height:int) is det.

static foreign_t
set_size(term_t name, term_t width, term_t height)
{ char *n;
int w, h;

if ( !PL_get_chars(name, &n, CVT_ATOM|CVT_EXCEPTION) ||

!PL_get_integer_ex(with, &w) ||
!PL_get_integer_ex(height, &h) )
return FALSE;

...

int PL get atom ex(term t t, atom t *a)

As PL get atom(), but raises a type or instantiation error if t is not an atom.

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 343

int PL get integer ex(term t t, int *i)

As PL get integer(), but raises a type or instantiation error if t is not an integer, or a
representation error if the Prolog integer does not fit in a C int.
int PL get long ex(term t t, long *i)
As PL get long(), but raises a type or instantiation error if t is not an atom, or a represen-
tation error if the Prolog integer does not fit in a C long.
int PL get int64 ex(term t t, int64 t *i)
As PL get int64(), but raises a type or instantiation error if t is not an atom, or a represen-
tation error if the Prolog integer does not fit in a C int64 t.
int PL get intptr ex(term t t, intptr t *i)
As PL get intptr(), but raises a type or instantiation error if t is not an atom, or a repre-
sentation error if the Prolog integer does not fit in a C intptr t.
int PL get size ex(term t t, size t *i)
As PL get size(), but raises a type or instantiation error if t is not an atom, or a represen-
tation error if the Prolog integer does not fit in a C size t.
int PL get bool ex(term t t, int *i)
As PL get bool(), but raises a type or instantiation error if t is not an boolean.
int PL get float ex(term t t, double *f)
As PL get float(), but raises a type or instantiation error if t is not a float.
int PL get char ex(term t t, int *p, int eof)
Get a character code from t, where t is either an integer or an atom with length one. If eof
is TRUE and t is -1, p is filled with -1. Raises an appropriate error if the conversion is not
possible.
int PL get pointer ex(term t t, void **addrp)
As PL get pointer(), but raises a type or instantiation error if t is not a pointer.
int PL get list ex(term t l, term t h, term t t)
As PL get list(), but raises a type or instantiation error if t is not a list.
int PL get nil ex(term t l)
As PL get nil(), but raises a type or instantiation error if t is not the empty list.
int PL unify list ex(term t l, term t h, term t t)
As PL unify list(), but raises a type error if t is not a variable, list-cell or the empty list.
int PL unify nil ex(term t l)
As PL unify nil(), but raises a type error if t is not a variable, list-cell or the empty list.
int PL unify bool ex(term t t, int val)
As PL unify bool(), but raises a type error if t is not a variable or a boolean.
The second family of functions in this section simplifies the generation of ISO compatible error
terms. Any foreign function that calls this function must return to Prolog with the return code of the
error function or the constant FALSE. If available, these error functions add the name of the calling
predicate to the error context. See also PL raise exception().

SWI-Prolog 7.4 Reference Manual

344 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

int PL instantiation error(term t culprit)

Raise instantiation error. Culprit is ignored, but should be bound to the term that is
insufficiently instantiated. See instantiation error/1.

int PL uninstantiation error(term t culprit)

Raise uninstantiation error(culprit). This should be called if an argument that
must be unbound at entry is bound to culprit. This error is typically raised for a pure output
arguments such as a newly created stream handle (e.g., the third argument of open/3).

int PL representation error(const char *resource)

Raise representation error(resource). See representation error/1.

int PL type error(const char *expected, term t culprit)

Raise type error(expected, culprit). See type error/2.

int PL domain error(const char *expected, term t culprit)

Raise domain error(expected, culprit). See domain error/2.

int PL existence error(const char *type, term t culprit)

Raise existence error(type, culprit). See type error/2.

int PL permission error(const char *operation, const char *type, term t culprit)
Raise permission error(operation, type, culprit). See
permission error/3.

int PL resource error(const char *resource)

Raise resource error(resource). See resource error/1.

int PL syntax error(const char *message, IOSTREAM *in)

Raise syntax error(message). If arg is not NULL, add information about the current
position of the input stream.

11.4.7 BLOBS: Using atoms to store arbitrary binary data

SWI-Prolog atoms as well as strings can represent arbitrary binary data of arbitrary length. This
facility is attractive for storing foreign data such as images in an atom. An atom is a unique handle to
this data and the atom garbage collector is able to destroy atoms that are no longer referenced by the
Prolog engine. This property of atoms makes them attractive as a handle to foreign resources, such as
Java atoms, Microsofts COM objects, etc., providing safe combined garbage collection.
To exploit these features safely and in an organised manner, the SWI-Prolog foreign interface
allows for creating atoms with additional type information. The type is represented by a structure
holding C function pointers that tell Prolog how to handle releasing the atom, writing it, sorting it,
etc. Two atoms created with different types can represent the same sequence of bytes. Atoms are first
ordered on the rank number of the type and then on the result of the compare() function. Rank
numbers are assigned when the type is registered.

Defining a BLOB type

The type PL blob t represents a structure with the layout displayed below. The structure contains
additional fields at the . . . for internal bookkeeping as well as future extensions.

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 345

typedef struct PL_blob_t

{ uintptr_t magic; /* PL_BLOB_MAGIC */
uintptr_t flags; /* Bitwise or of PL_BLOB_* */
char * name; /* name of the type */
int (*release)(atom_t a);
int (*compare)(atom_t a, atom_t b);
int (*write)(IOSTREAM *s, atom_t a, int flags);
void (*acquire)(atom_t a);
...
} PL_blob_t;

For each type, exactly one such structure should be allocated. Its first field must be initialised to
PL BLOB MAGIC. The flags is a bitwise or of the following constants:

PL BLOB TEXT
If specified the blob is assumed to contain text and is considered a normal Prolog atom.

PL BLOB UNIQUE
If specified the system ensures that the blob-handle is a unique reference for a blob with the
given type, length and content. If this flag is not specified, each lookup creates a new blob.

PL BLOB NOCOPY
By default the content of the blob is copied. Using this flag the blob references the external
data directly. The user must ensure the provided pointer is valid as long as the atom lives. If
PL BLOB UNIQUE is also specified, uniqueness is determined by comparing the pointer rather
than the data pointed at.

The name field represents the type name as available to Prolog. See also current blob/2.
The other fields are function pointers that must be initialised to proper functions or NULL to get the
default behaviour of built-in atoms. Below are the defined member functions:

void acquire(atom t a)
Called if a new blob of this type is created through PL put blob() or PL unify blob().
This callback may be used together with the release hook to deal with reference-counted
external objects.

int release(atom t a)
The blob (atom) a is about to be released. This function can retrieve the data of the blob using
PL blob data(). If it returns FALSE the atom garbage collector will not reclaim the atom.

int compare(atom t a, atom t b)

Compare the blobs a and b, both of which are of the type associated to this blob type. Return
values are, as memcmp(), < 0 if a is less than b, = 0 if both are equal, and > 0 otherwise.

int write(IOSTREAM *s, atom t a, int flags)

Write the content of the blob a to the stream s respecting the flags. The flags are a bitwise or of
zero or more of the PL WRT * flags defined in SWI-Prolog.h. This prototype is available if
the undocumented SWI-Stream.h is included before SWI-Prolog.h.

SWI-Prolog 7.4 Reference Manual

346 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

If this function is not provided, write/1 emits the content of the blob for blobs of type
PL BLOB TEXT or a string of the format <#hex data> for binary blobs.

If a blob type is registered from a loadable object (shared object or DLL) the blob type must be
deregistered before the object may be released.

int PL unregister blob type(PL blob t *type)

Unlink the blob type from the registered type and transform the type of possible living blobs
to unregistered, avoiding further reference to the type structure, functions referred by it,
as well as the data. This function returns TRUE if no blobs of this type existed and FALSE
otherwise. PL unregister blob type() is intended for the uninstall() hook of foreign
modules, avoiding further references to the module.

Accessing blobs

The blob access functions are similar to the atom accessing functions. Blobs being atoms, the atom
functions operate on blobs and vice versa. For clarity and possible future compatibility issues, how-
ever, it is not advised to rely on this.

int PL is blob(term t t, PL blob t **type)

Succeeds if t refers to a blob, in which case type is filled with the type of the blob.

int PL unify blob(term t t, void *blob, size t len, PL blob t *type)

Unify t to a new blob constructed from the given data and associated to the given type. See also
PL unify atom nchars().

int PL put blob(term t t, void *blob, size t len, PL blob t *type)

Store the described blob in t. The return value indicates whether a new blob was allocated
(FALSE) or the blob is a reference to an existing blob (TRUE). Reporting new/existing can be
used to deal with external objects having their own reference counts. If the return is TRUE this
reference count must be incremented, and it must be decremented on blob destruction callback.
See also PL put atom nchars().

int PL get blob(term t t, void **blob, size t *len, PL blob t **type)

If t holds a blob or atom, get the data and type and return TRUE. Otherwise return FALSE.
Each result pointer may be NULL, in which case the requested information is ignored.

void * PL blob data(atom t a, size t *len, PL blob t **type)

Get the data and type associated to a blob. This function is mainly used from the callback
functions described in section 11.4.7.

11.4.8 Exchanging GMP numbers

If SWI-Prolog is linked with the GNU Multiple Precision Arithmetic Library (GMP, used by default),
the foreign interface provides functions for exchanging numeric values to GMP types. To access these
functions the header <gmp.h> must be included before <SWI-Prolog.h>. Foreign code using
GMP linked to SWI-Prolog asks for some considerations.

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 347

SWI-Prolog normally rebinds the GMP allocation functions using mp set memory functions().
This means SWI-Prolog must be initialised before the foreign code touches any GMP function.
You can call \cfuncref{PL_action}{PL_GMP_SET_ALLOC_FUNCTIONS, TRUE}
to force Prologs GMP initialization without doing the rest of the Prolog ini-
tialization. If you do not want Prolog rebinding the GMP allocation, call
\cfuncref{PL_action}{PL_GMP_SET_ALLOC_FUNCTIONS, FALSE} before
initializing Prolog.

On Windows, each DLL has its own memory pool. To make exchange of GMP numbers be-
tween Prolog and foreign code possible you must either let Prolog rebind the allocation func-
tions (default) or you must recompile SWI-Prolog to link to a DLL version of the GMP library.

Here is an example exploiting the function mpz nextprime():

#include <gmp.h>
#include <SWI-Prolog.h>

static foreign_t
next_prime(term_t n, term_t prime)
{ mpz_t mpz;
int rc;

mpz_init(mpz);
if ( PL_get_mpz(n, mpz) )
{ mpz_nextprime(mpz, mpz);

rc = PL_unify_mpz(prime, mpz);
} else
rc = FALSE;

mpz_clear(mpz);
return rc;
}

install_t
install()
{ PL_register_foreign("next_prime", 2, next_prime, 0);
}

int PL get mpz(term t t, mpz t mpz)

If t represents an integer, mpz is filled with the value and the function returns TRUE. Otherwise
mpz is untouched and the function returns FALSE. Note that mpz must have been initialised
before calling this function and must be cleared using mpz clear() to reclaim any storage
associated with it.

int PL get mpq(term t t, mpq t mpq)

If t is an integer or rational number (term rdiv/2), mpq is filled with the normalised rational

SWI-Prolog 7.4 Reference Manual

348 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

number and the function returns TRUE. Otherwise mpq is untouched and the function returns
FALSE. Note that mpq must have been initialised before calling this function and must be
cleared using mpq clear() to reclaim any storage associated with it.
int PL unify mpz(term t t, mpz t mpz)
Unify t with the integer value represented by mpz and return TRUE on success. The mpz
argument is not changed.
int PL unify mpq(term t t, mpq t mpq)
Unify t with a rational number represented by mpq and return TRUE on success. Note that t is
unified with an integer if the denominator is 1. The mpq argument is not changed.

11.4.9 Calling Prolog from C

The Prolog engine can be called from C. There are two interfaces for this. For the first, a term is
created that could be used as an argument to call/1, and then PL call() is used to call Prolog.
This system is simple, but does not allow to inspect the different answers to a non-deterministic goal
and is relatively slow as the runtime system needs to find the predicate. The other interface is based on
PL open query(), PL next solution() and PL cut query() or PL close query().
This mechanism is more powerful, but also more complicated to use.

Predicate references
This section discusses the functions used to communicate about predicates. Though a Prolog predicate
may be defined or not, redefined, etc., a Prolog predicate has a handle that is neither destroyed nor
moved. This handle is known by the type predicate t.

predicate t PL pred(functor t f, module t m)

Return a handle to a predicate for the specified name/arity in the given module. This function
always succeeds, creating a handle for an undefined predicate if no handle was available. If the
module argument m is NULL, the current context module is used.
predicate t PL predicate(const char *name, int arity, const char* module)
Same as PL pred(), but provides a more convenient interface to the C programmer.
void PL predicate info(predicate t p, atom t *n, size t *a, module t *m)
Return information on the predicate p. The name is stored over n, the arity over a, while m
receives the definition module. Note that the latter need not be the same as specified with
PL predicate(). If the predicate is imported into the module given to PL predicate(),
this function will return the module where the predicate is defined. Any of the arguments n, a
and m can be NULL.

Initiating a query from C

This section discusses the functions for creating and manipulating queries from C. Note that a foreign
context can have at most one active query. This implies that it is allowed to make strictly nested calls
between C and Prolog (Prolog calls C, calls Prolog, calls C, etc.), but it is not allowed to open multiple
queries and start generating solutions for each of them by calling PL next solution(). Be sure
to call PL cut query() or PL close query() on any query you opened before opening the
next or returning control back to Prolog.

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 349

qid t PL open query(module t ctx, int flags, predicate t p, term t +t0)

Opens a query and returns an identifier for it. ctx is the context module of the goal. When
NULL, the context module of the calling context will be used, or user if there is no
calling context (as may happen in embedded systems). Note that the context module
only matters for meta-predicates. See meta predicate/1, context module/1 and
module transparent/1. The p argument specifies the predicate, and should be the result
of a call to PL pred() or PL predicate(). Note that it is allowed to store this handle as
global data and reuse it for future queries. The term reference t0 is the first of a vector of term
references as returned by PL new term refs(n).
The flags arguments provides some additional options concerning debugging and exception
handling. It is a bitwise or of the following values:

PL Q NORMAL
Normal operation. The debugger inherits its settings from the environment. If an excep-
tion occurs that is not handled in Prolog, a message is printed and the tracer is started to
debug the error.5
PL Q NODEBUG
Switch off the debugger while executing the goal. This option is used by many calls
to hook-predicates to avoid tracing the hooks. An example is print/1 calling
portray/1 from foreign code.
PL Q CATCH EXCEPTION
If an exception is raised while executing the goal, do not report it, but make it available
for PL exception().
PL Q PASS EXCEPTION
As PL Q CATCH EXCEPTION, but do not invalidate the exception-term while calling
PL close query(). This option is experimental.
PL Q ALLOW YIELD
Support the I YIELD instruction for engine-based coroutining. See
$engine yield/2 in boot/init.pl for details.
PL Q EXT STATUS
Make PL next solution() return extended status. Instead of only TRUE or FALSE
extended status as illustrated in the following table:

Extended Normal
PL S EXCEPTION FALSE Exception available through PL exception()
PL S FALSE FALSE Query failed
PL S TRUE TRUE Query succeeded with choicepoint
PL S LAST TRUE Query succeeded without choicepoint

PL open query() can return the query identifier 0 if there is not enough space on the
environment stack. This function succeeds, even if the referenced predicate is not defined. In
this case, running the query using PL next solution() will return an existence error. See
PL exception().
5
Do not pass the integer 0 for normal operation, as this is interpreted as PL Q NODEBUG for backward compatibility
reasons.

SWI-Prolog 7.4 Reference Manual

350 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

The example below opens a query to the predicate is_a/2 to find the ancestor of me. The
reference to the predicate is valid for the duration of the process and may be cached by the
client.

char *
ancestor(const char *me)
{ term_t a0 = PL_new_term_refs(2);
static predicate_t p;

if ( !p )
p = PL_predicate("is_a", 2, "database");

PL_put_atom_chars(a0, me);
PL_open_query(NULL, PL_Q_NORMAL, p, a0);
...
}

int PL next solution(qid t qid)

Generate the first (next) solution for the given query. The return value is TRUE if a solution
was found, or FALSE to indicate the query could not be proven. This function may be called
repeatedly until it fails to generate all solutions to the query.

void PL cut query(qid t qid)

Discards the query, but does not delete any of the data created by the query. It just invalidates
qid, allowing for a new call to PL open query() in this context.

void PL close query(qid t qid)

As PL cut query(), but all data and bindings created by the query are destroyed.

qid t PL current query(void)

Returns the query id of of the current query or 0 if the current thread is not executing any
queries.

int PL call predicate(module t m, int flags, predicate t pred, term t +t0)

Shorthand for PL open query(), PL next solution(), PL cut query(), generat-
ing a single solution. The arguments are the same as for PL open query(), the return value
is the same as PL next solution().

int PL call(term t t, module t m)

Call term t just like the Prolog predicate once/1. t is called in the module m, or in the context
module if m == NULL. Returns TRUE if the call succeeds, FALSE otherwise. Figure 11.3
shows an example to obtain the number of defined atoms. All checks are omitted to improve
readability.

11.4.10 Discarding Data

The Prolog data created and term references needed to set up the call and/or analyse the result can
in most cases be discarded right after the call. PL close query() allows for destroying the data,

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 351

int
count_atoms()
{ fid_t fid = PL_open_foreign_frame();
term_t goal = PL_new_term_ref();
term_t a1 = PL_new_term_ref();
term_t a2 = PL_new_term_ref();
functor_t s2 = PL_new_functor(PL_new_atom("statistics"), 2);
int atoms;

PL_put_atom_chars(a1, "atoms");
PL_cons_functor(goal, s2, a1, a2);
PL_call(goal, NULL); /* call it in current module */

PL_get_integer(a2, &atoms);
PL_discard_foreign_frame(fid);

return atoms;
}

Figure 11.3: Calling Prolog

while leaving the term references. The calls below may be used to destroy term references and data.
See figure 11.3 for an example.

fid t PL open foreign frame()

Create a foreign frame, holding a mark that allows the system to undo bindings and destroy
data created after it, as well as providing the environment for creating term references. This
function is called by the kernel before calling a foreign predicate.

void PL close foreign frame(fid t id)

Discard all term references created after the frame was opened. All other Prolog data is re-
tained. This function is called by the kernel whenever a foreign function returns control back
to Prolog.

void PL discard foreign frame(fid t id)

Same as PL close foreign frame(), but also undo all bindings made since the open and
destroy all Prolog data.

void PL rewind foreign frame(fid t id)

Undo all bindings and discard all term references created since the frame was created, but do
not pop the frame. That is, the same frame can be rewound multiple times, and must eventually
be closed or discarded.

It is obligatory to call either of the two closing functions to discard a foreign frame. Foreign
frames may be nested.

SWI-Prolog 7.4 Reference Manual

352 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

11.4.11 Foreign Code and Modules

Modules are identified via a unique handle. The following functions are available to query and ma-
nipulate modules.

module t PL context()
Return the module identifier of the context module of the currently active foreign predicate.

int PL strip module(term t +raw, module t *m, term t -plain)

Utility function. If raw is a term, possibly holding the module construct hmodulei:hresti, this
function will make plain a reference to hresti and fill module * with hmodulei. For further
nested module constructs the innermost module is returned via module *. If raw is not a module
construct, raw will simply be put in plain. The value pointed to by m must be initialized before
calling PL strip module(), either to the default module or to NULL. A NULL value is
replaced by the current context module if raw carries no module. The following example shows
how to obtain the plain term and module if the default module is the user module:

{ module m = PL_new_module(PL_new_atom("user"));
term_t plain = PL_new_term_ref();

PL_strip_module(term, &m, plain);

...
}

atom t PL module name(module t module)

Return the name of module as an atom.

module t PL new module(atom t name)

Find an existing module or create a new module with the name name.

11.4.12 Prolog exceptions in foreign code

This section discusses PL exception(), PL throw() and PL raise exception(), the
interface functions to detect and generate Prolog exceptions from C code. PL throw()
and PL raise exception() from the C interface raise an exception from foreign code.
PL throw() exploits the C function longjmp() to return immediately to the innermost
PL next solution(). PL raise exception() registers the exception term and returns
FALSE. If a foreign predicate returns FALSE, while an exception term is registered, a Prolog ex-
ception will be raised by the virtual machine.
Calling these functions outside the context of a function implementing a foreign predicate results
in undefined behaviour.
PL exception() may be used after a call to PL next solution() fails, and returns a term
reference to an exception term if an exception was raised, and 0 otherwise.
If a C function implementing a predicate calls Prolog and detects an exception
using PL exception(), it can handle this exception or return with the exception.
Some caution is required though. It is not allowed to call PL close query() or
PL discard foreign frame() afterwards, as this will invalidate the exception term. Below
is the code that calls a Prolog-defined arithmetic function (see arithmetic function/1).

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 353

If PL next solution() succeeds, the result is analysed and translated to a number, after
which the query is closed and all Prolog data created after PL open foreign frame() is de-
stroyed. On the other hand, if PL next solution() fails and if an exception was raised, just
pass it. Otherwise generate an exception (PL error() is an internal call for building the standard
error terms and calling PL raise exception()). After this, the Prolog environment should be
discarded using PL cut query() and PL close foreign frame() to avoid invalidating the
exception term.

static int
prologFunction(ArithFunction f, term_t av, Number r)
{ int arity = f->proc->definition->functor->arity;
fid_t fid = PL_open_foreign_frame();
qid_t qid;
int rval;

qid = PL_open_query(NULL, PL_Q_NORMAL, f->proc, av);

if ( PL_next_solution(qid) )
{ rval = valueExpression(av+arity-1, r);
PL_close_query(qid);
PL_discard_foreign_frame(fid);
} else
{ term_t except;

if ( (except = PL_exception(qid)) )
{ rval = PL_throw(except); /* pass exception */
} else
{ char *name = stringAtom(f->proc->definition->functor->name);

/* generate exception */
rval = PL_error(name, arity-1, NULL, ERR_FAILED, f->proc);
}

PL_cut_query(qid); /* donot destroy data */

PL_close_foreign_frame(fid); /* same */
}

return rval;
}

int PL raise exception(term t exception)

Generate an exception (as throw/1) and return FALSE. Below is an example returning an
exception from a foreign predicate:

foreign_t
pl_hello(term_t to)

SWI-Prolog 7.4 Reference Manual

354 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

{ char *s;

if ( PL_get_atom_chars(to, &s) )
{ Sprintf("Hello \"%s\"\n", s);

PL_succeed;
} else
{ term_t except = PL_new_term_ref();

PL_unify_term(except,
PL_FUNCTOR_CHARS, "type_error", 2,
PL_CHARS, "atom",
PL_TERM, to);

return PL_raise_exception(except);
}
}

int PL throw(term t exception)

Similar to PL raise exception(), but returns using the C longjmp() function to the
innermost PL next solution().

term t PL exception(qid t qid)

If PL next solution() fails, this can be due to normal failure of the Prolog call, or because
an exception was raised using throw/1. This function returns a handle to the exception
term if an exception was raised, or 0 if the Prolog goal simply failed. If there is an exception,
PL exception() allocates a term-handle using PL new term ref() that is used to return
the exception term.
Additionally, \cfuncref{PL_exception}{0} returns the pending exception in the cur-
rent query or 0 if no exception is pending. This can be used to check the error status after a
failing call to, e.g., one of the unification functions.

void PL clear exception(void)

Tells Prolog that the encountered exception must be ignored. This function must be called if
control remains in C after a previous API call fails with an exception.6

11.4.13 Catching Signals (Software Interrupts)

SWI-Prolog offers both a C and Prolog interface to deal with software interrupts (signals). The Prolog
mapping is defined in section 4.12. This subsection deals with handling signals from C.
If a signal is not used by Prolog and the handler does not call Prolog in any way, the native signal
interface routines may be used.
Any handler that wishes to call one of the Prolog interface functions should call PL signal()
for its installation.
6
This feature is non-portable. Other Prolog systems (e.g., YAP) have no facilities to ignore raised exceptions, and the
design of YAPs exception handling does not support such a facility.

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 355

void (*)() PL signal(sig, func)

This function is equivalent to the BSD-Unix signal() function, regardless of the platform used.
The signal handler is blocked while the signal routine is active, and automatically reactivated
after the handler returns.
After a signal handler is registered using this function, the native signal interface redirects the
signal to a generic signal handler inside SWI-Prolog. This generic handler validates the en-
vironment, creates a suitable environment for calling the interface functions described in this
chapter and finally calls the registered user-handler.
By default, signals are handled asynchronously (i.e., at the time they arrive). It is inherently
dangerous to call extensive code fragments, and especially exception related code from asyn-
chronous handlers. The interface allows for synchronous handling of signals. In this case
the native OS handler just schedules the signal using PL raise(), which is checked by
PL handle signals() at the call- and redo-port. This behaviour is realised by or-ing sig
with the constant PL SIGSYNC.7
Signal handling routines may raise exceptions using PL raise exception(). The use of
PL throw() is not safe. If a synchronous handler raises an exception, the exception is delayed
to the next call to PL handle signals();

int PL raise(int sig)

Register sig for synchronous handling by Prolog. Synchronous signals are handled at the
call-port or if foreign code calls PL handle signals(). See also thread signal/2.

int PL handle signals(void)

Handle any signals pending from PL raise(). PL handle signals() is called at each
pass through the call- and redo-port at a safe point. Exceptions raised by the handler using
PL raise exception() are properly passed to the environment.
The user may call this function inside long-running foreign functions to handle scheduled inter-
rupts. This routine returns the number of signals handled. If a handler raises an exception, the
return value is -1 and the calling routine should return with FALSE as soon as possible.

int PL get signum ex(term t t, int *sig)

Extract a signal specification from a Prolog term and store as an integer signal number in sig.
The specification is an integer, a lowercase signal name without SIG or the full signal name.
These refer to the same: 9, kill and SIGKILL. Leaves a typed, domain or instantiation error
if the conversion fails.

11.4.14 Miscellaneous
Term Comparison
int PL compare(term t t1, term t t2)
Compares two terms using the standard order of terms and returns -1, 0 or 1. See also
compare/3.

int PL same compound(term t t1, term t t2)

Yields TRUE if t1 and t2 refer to physically the same compound term and FALSE otherwise.
7
A better default would be to use synchronous handling, but this interface preserves backward compatibility.

SWI-Prolog 7.4 Reference Manual

356 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

Recorded database
In some applications it is useful to store and retrieve Prolog terms from C code. For example, the
XPCE graphical environment does this for storing arbitrary Prolog data as slot-data of XPCE objects.
Please note that the returned handles have no meaning at the Prolog level and the recorded terms
are not visible from Prolog. The functions PL recorded() and PL erase() are the only func-
tions that can operate on the stored term.
Two groups of functions are provided. The first group (PL record() and friends) store Prolog
terms on the Prolog heap for retrieval during the same session. These functions are also used by
recorda/3 and friends. The recorded database may be used to communicate Prolog terms between
threads.

record t PL record(term t +t)

Record the term t into the Prolog database as recorda/3 and return an opaque handle to the
term. The returned handle remains valid until PL erase() is called on it. PL recorded()
is used to copy recorded terms back to the Prolog stack.
record t PL duplicate record(record t record)
Return a duplicate of record. As records are read-only objects this function merely increments
the records reference count.
int PL recorded(record t record, term t -t)
Copy a recorded term back to the Prolog stack. The same record may be used to copy multiple
instances at any time to the Prolog stack. Returns TRUE on success, and FALSE if there
is not enough space on the stack to accommodate the term. See also PL record() and
PL erase().
void PL erase(record t record)
Remove the recorded term from the Prolog database, reclaiming all associated memory re-
sources.

The second group (headed by PL record external()) provides the same functionality, but
the returned data has properties that enable storing the data on an external device. It has been designed
to make it possible to store Prolog terms fast and compact in an external database. Here are the main
features:

Independent of session
Records can be communicated to another Prolog session and made visible using
PL recorded external().
Binary
The representation is binary for maximum performance. The returned data may contain zero
bytes.
Byte-order independent
The representation can be transferred between machines with different byte order.
No alignment restrictions
There are no memory alignment restrictions and copies of the record can thus be moved freely.
For example, it is possible to use this representation to exchange terms using shared memory
between different Prolog processes.

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 357

Compact
It is assumed that a smaller memory footprint will eventually outperform slightly faster repre-
sentations.

Stable
The format is designed for future enhancements without breaking compatibility with older
records.

char * PL record external(term t +t, size t *len)

Record the term t into the Prolog database as recorda/3 and return an opaque handle to the
term. The returned handle remains valid until PL erase external() is called on it.
It is allowed to copy the data and use PL recorded external() on the copy. The user
is responsible for the memory management of the copy. After copying, the original may be
discarded using PL erase external().
PL recorded external() is used to copy such recorded terms back to the Prolog stack.

int PL recorded external(const char *record, term t -t)

Copy a recorded term back to the Prolog stack. The same record may be used to copy mul-
tiple instances at any time to the Prolog stack. See also PL record external() and
PL erase external().

int PL erase external(char *record)

Remove the recorded term from the Prolog database, reclaiming all associated memory re-
sources.

Getting file names

The function PL get file name() provides access to Prolog filenames and its file-search mech-
anism described with absolute file name/3. Its existence is motivated to realise a uniform
interface to deal with file properties, search, naming conventions, etc., from foreign code.

int PL get file name(term t spec, char **name, int flags)

Translate a Prolog term into a file name. The name is stored in the static buffer ring described
with th PL get chars() option BUF RING. Conversion from the internal UNICODE
encoding is done using standard C library functions. flags is a bit-mask controlling the
conversion process. Options are:

PL FILE ABSOLUTE
Return an absolute path to the requested file.
PL FILE OSPATH
Return the name using the hosting OS conventions. On MS-Windows, \ is used to sepa-
rate directories rather than the canonical /.
PL FILE SEARCH
Invoke absolute file name/3. This implies rules from file search path/2
are used.
PL FILE EXIST
Demand the path to refer to an existing entity.

SWI-Prolog 7.4 Reference Manual

358 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

PL FILE READ
Demand read-access on the result.
PL FILE WRITE
Demand write-access on the result.
PL FILE EXECUTE
Demand execute-access on the result.
PL FILE NOERRORS
Do not raise any exceptions.

int PL get file nameW(term t spec, wchar t **name, int flags)

Same as PL get file name(), but returns the filename as a wide-character string. This
is intended for Windows to access the Unicode version of the Win32 API. Note that the flag
PL FILE OSPATH must be provided to fetch a filename in OS native (e.g., C:\x\y) notation.

Dealing with Prolog flags from C

Foreign code can set or create Prolog flags using PL set prolog flag(). See
set prolog flag/2 and create prolog flag/3.8

int PL set prolog flag(const char *name, int type, ...)

Set/create a Prolog flag from C. name is the name of the affected flag. type is one of the
values below, which also dictates the type of the final argument. The function returns TRUE
on success and FALSE on failure. This function can be called before PL initialise(),
making the flag available to the Prolog startup code.

PL BOOL
Create a boolean (true or false) flag. The argument must be an int.
PL ATOM
Create a flag with an atom as value. The argument must be of type const char *.
PL INTEGER
Create a flag with an integer as value. The argument must be of type intptr t *.

11.4.15 Errors and warnings

PL warning() prints a standard Prolog warning message to the standard error (user error)
stream. Please note that new code should consider using PL raise exception() to raise a Prolog
exception. See also section 4.11.

int PL warning(format, a1, . . . )

Print an error message starting with [WARNING: , followed by the output from format,
followed by a ] and a newline. Then start the tracer. format and the arguments are the same
as for printf(2). Always returns FALSE.
8
The current C API does not provide for a dedicated mechanism for fetching the value of Prolog flags. Relatively slow
access is provided by calling PL call predicate() using current prolog flag/2.

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 359

11.4.16 Environment Control from Foreign Code

int PL action(int, ...)
Perform some action on the Prolog system. int describes the action. Remaining arguments
depend on the requested action. The actions are listed below:

PL ACTION TRACE
Start Prolog tracer (trace/0). Requires no arguments.
PL ACTION DEBUG
Switch on Prolog debug mode (debug/0). Requires no arguments.
PL ACTION BACKTRACE
Print backtrace on current output stream. The argument (an int) is the number of frames
printed.
PL ACTION HALT
Halt Prolog execution. This action should be called rather than Unix exit() to give Prolog
the opportunity to clean up. This call does not return. The argument (an int) is the exit
code. See halt/1.
PL ACTION ABORT
Generate a Prolog abort (abort/0). This call does not return. Requires no arguments.
PL ACTION BREAK
Create a standard Prolog break environment (break/0). Returns after the user types the
end-of-file character. Requires no arguments.
PL ACTION GUIAPP
Windows: Used to indicate to the kernel that the application is a GUI application if the
argument is not 0, and a console application if the argument is 0. If a fatal error occurs,
the system uses a windows messagebox to report this on a GUI application, and otherwise
simply prints the error and exits.
PL ACTION TRADITIONAL
Same effect as using --traditional. Must be called before PL initialise().
PL ACTION WRITE
Write the argument, a char * to the current output stream.
PL ACTION FLUSH
Flush the current output stream. Requires no arguments.
PL ACTION ATTACH CONSOLE
Attach a console to a thread if it does not have one. See attach console/0.
PL GMP SET ALLOC FUNCTIONS
Takes an integer argument. If TRUE, the GMP allocations are immediately bound to the
Prolog functions. If FALSE, SWI-Prolog will never rebind the GMP allocation functions.
See mp set memory functions() in the GMP documentation. The action returns FALSE
if there is no GMP support or GMP is already initialised.

11.4.17 Querying Prolog

long PL query(int)
Obtain status information on the Prolog system. The actual argument type depends on the

SWI-Prolog 7.4 Reference Manual

360 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

PL QUERY ARGC Return an integer holding the number of ar-

guments given to Prolog from Unix.
PL QUERY ARGV Return a char ** holding the argument
vector given to Prolog from Unix.
PL QUERY SYMBOLFILE Return a char * holding the current symbol
file of the running process.
PL MAX INTEGER Return a long, representing the maximal inte-
ger value represented by a Prolog integer.
PL MIN INTEGER Return a long, representing the minimal inte-
ger value.
PL QUERY VERSION Return a long, representing the version as
10, 000 M + 100 m + p, where M is
the major, m the minor version number and p
the patch level. For example, 20717 means
2.7.17.
PL QUERY ENCODING Return the default stream encoding of Prolog
(of type IOENC).
PL QUERY USER CPU Get amount of user CPU time of the process
in milliseconds.

Table 11.1: PL query() options

information required. int describes what information is wanted.9 The options are given in
table 11.1.

11.4.18 Registering Foreign Predicates

int PL register foreign in module(char *mod, char *name, int arity, foreign t (*f)(), int flags, ...)
Register the C function f to implement a Prolog predicate. After this call returns successfully a
predicate with name name (a char *) and arity arity (a C int) is created in module mod. If
mod is NULL, the predicate is created in the module of the calling context, or if no context is
present in the module user.
When called in Prolog, Prolog will call function. flags form a bitwise ored list of options for
the installation. These are:
PL FA META Provide meta-predicate info (see below)
PL FA TRANSPARENT Predicate is module transparent (deprecated)
PL FA NONDETERMINISTIC Predicate is non-deterministic. See also
PL retry().
PL FA NOTRACE Predicate cannot be seen in the tracer
PL FA VARARGS Use alternative calling convention.
If PL FA META is provided, PL register foreign in module() takes one extra ar-
gument. This argument is of type const char*. This string must be exactly as long as
the number of arguments of the predicate and filled with characters from the set 0-9:-+?.
See meta predicate/1 for details. PL FA TRANSPARENT is implied if at least one
9
Returning pointers and integers as a long is bad style. The signature of this function should be changed.

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 361

meta-argument is provided (0-9:). Note that meta-arguments are not always passed as
hmodulei:htermi. Always use PL strip module() to extract the module and plain term
from a meta-argument.10
Predicates may be registered either before or after PL initialise(). When registered be-
fore initialisation the registration is recorded and executed after installing the system predicates
and before loading the saved state.
Default calling (i.e. without PL FA VARARGS) function is passed the same number of term t
arguments as the arity of the predicate and, if the predicate is non-deterministic, an extra ar-
gument of type control t (see section 11.4.1). If PL FA VARARGS is provided, function
is called with three arguments. The first argument is a term t handle to the first argument.
Further arguments can be reached by adding the offset (see also PL new term refs()). The
second argument is the arity, which defines the number of valid term references in the argument
vector. The last argument is used for non-deterministic calls. It is currently undocumented and
should be defined of type void*. Here is an example:

static foreign_t
atom_checksum(term_t a0, int arity, void* context)
{ char *s;

if ( PL_get_atom_chars(a0, &s) )
{ int sum;

for(sum=0; *s; s++)

sum += *s&0xff;

return PL_unify_integer(a0+1, sum&0xff);

}

return FALSE;
}

install_t
install()
{ PL_register_foreign("atom_checksum", 2,
atom_checksum, PL_FA_VARARGS);
}

int PL register foreign(const char *name, int arity, foreign t (*function)(), int flags, ...)
Same as PL register foreign in module(), passing NULL for the module.

void PL register extensions in module(const char *module, PL extension *e)

Register a series of predicates from an array of definitions of the type PL extension in the
given module. If module is NULL, the predicate is created in the module of the calling context,
or if no context is present in the module user. The PL extension type is defined as
10
It is encouraged to pass an additional NULL pointer for non-meta-predicates.

SWI-Prolog 7.4 Reference Manual

362 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

typedef struct PL_extension

{ char *predicate_name; /* Name of the predicate */
short arity; /* Arity of the predicate */
pl_function_t function; /* Implementing functions */
short flags; /* Or of PL_FA_... */
} PL_extension;

For details, see PL register foreign in module(). Here is an example of its usage:

static PL_extension predicates[] = {

{ "foo", 1, pl_foo, 0 },
{ "bar", 2, pl_bar, PL_FA_NONDETERMINISTIC },
{ NULL, 0, NULL, 0 }
};

main(int argc, char **argv)

{ PL_register_extensions_in_module("user", predicates);

if ( !PL_initialise(argc, argv) )
PL_halt(1);

...
}

void PL register extensions( PL extension *e)

Same as PL register extensions in module() using NULL for the module argu-
ment.

11.4.19 Foreign Code Hooks

For various specific applications some hooks are provided.
PL dispatch hook t PL dispatch hook(PL dispatch hook t)
If this hook is not NULL, this function is called when reading from the terminal. It is supposed
to dispatch events when SWI-Prolog is connected to a window environment. It can return
two values: PL DISPATCH INPUT indicates Prolog input is available on file descriptor 0
or PL DISPATCH TIMEOUT to indicate a timeout. The old hook is returned. The type
PL dispatch hook t is defined as:

typedef int (*PL_dispatch_hook_t)(void);

void PL abort hook(PL abort hook t)

Install a hook when abort/0 is executed. SWI-Prolog abort/0 is implemented using C
setjmp()/longjmp() construct. The hooks are executed in the reverse order of their registra-
tion after the longjmp() took place and before the Prolog top level is reinvoked. The type
PL abort hook t is defined as:

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 363

typedef void (*PL_abort_hook_t)(void);

int PL abort unhook(PL abort hook t)

Remove a hook installed with PL abort hook(). Returns FALSE if no such hook is found,
TRUE otherwise.

void PL on halt(int (*f)(int, void *), void *closure)

Register the function f to be called if SWI-Prolog is halted. The function is called with two
arguments: the exit code of the process (0 if this cannot be determined) and the closure
argument passed to the PL on halt() call. Handlers must return 0. Other return values
are reserved for future use. See also at halt/1.11 These handlers are called before system
cleanup and can therefore access all normal Prolog resources. See also PL exit hook().

void PL exit hook(int (*f)(int, void *), void *closure)

Similar to PL on halt(), but the hooks are executed by PL halt() instead of
PL cleanup() just before calling exit().

PL agc hook t PL agc hook(PL agc hook t new)

Register a hook with the atom-garbage collector (see garbage collect atoms/0) that is
called on any atom that is reclaimed. The old hook is returned. If no hook is currently defined,
NULL is returned. The argument of the called hook is the atom that is to be garbage collected.
The return value is an int. If the return value is zero, the atom is not reclaimed. The hook
may invoke any Prolog predicate.
The example below defines a foreign library for printing the garbage collected atoms for debug-
ging purposes.

#include <SWI-Stream.h>
#include <SWI-Prolog.h>

static int
atom_hook(atom_t a)
{ Sdprintf("AGC: deleting %s\n", PL_atom_chars(a));

return TRUE;
}

static PL_agc_hook_t old;

install_t
install()
{ old = PL_agc_hook(atom_hook);
}

install_t
11
BUG: Although both PL on halt() and at halt/1 are called in FIFO order, all at halt/1 handlers are called
before all PL on halt() handlers.

SWI-Prolog 7.4 Reference Manual

364 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

uninstall()
{ PL_agc_hook(old);
}

11.4.20 Storing foreign data

When combining foreign code with Prolog, it can be necessary to make data represented in the foreign
language available to Prolog. For example, to pass it to another foreign function. At the end of this
section, there is a partial implementation of using foreign functions to manage bit-vectors. Another
example is the SGML/XML library that manages a parser object, an object that represents the current
state of the parser and that can be directed to perform actions such as parsing a document or make
queries about the document content.
This section provides some hints for handling foreign data in Prolog. There are four options for
storing such data:

Natural Prolog data

Uses the representation one would choose if no foreign interface was required. For example, a
bitvector representing a list of small integers can be represented as a Prolog list of integers.

Opaque packed data on the stacks

It is possible to represent the raw binary representation of the foreign object as a
Prolog string (see section 5.2). Strings may be created from foreign data using
PL put string nchars() and retrieved using PL get string chars(). It is good
practice to wrap the string in a compound term with arity 1, so Prolog can identify the type.
The hook portray/1 rules may be used to streamline printing such terms during develop-
ment.

Opaque packed data in a blob

Similar to the above solution, binary data can be stored in an atom. The blob interface (sec-
tion 11.4.7) provides additional facilities to assign a type and hook-functions that act on creation
and destruction of the underlying atom.

Natural foreign data, passed as a pointer

An alternative is to pass a pointer to the foreign data. Again, the pointer is often wrapped in a
compound term.

The choice may be guided using the following distinctions

Is the data opaque to Prolog

With opaque data, we refer to data handled in foreign functions, passed around in Prolog, but
where Prolog never examines the contents of the data itself. If the data is opaque to Prolog, the
selection will be driven solely by simplicity of the interface and performance.

What is the lifetime of the data

With lifetime we refer to how it is decided that the object is (or can be) destroyed. We can
distinguish three cases:

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 365

1. The object must be destroyed on backtracking and normal Prolog garbage collection (i.e.,
it acts as a normal Prolog term). In this case, representing the object as a Prolog string
(second option above) is the only feasible solution.
2. The data must survive Prolog backtracking. This leaves two options. One is to represent
the object using a pointer and use explicit creation and destruction, making the program-
mer responsible. The alternative is to use the blob-interface, leaving destruction to the
(atom) garbage collector.
3. The data lives as during the lifetime of a foreign function that implements a predicate. If
the predicate is deterministic, foreign automatic variables are suitable. If the predicate is
non-deterministic, the data may be allocated using malloc() and a pointer may be passed.
See section 11.4.1.

Examples for storing foreign data

In this section, we outline some examples, covering typical cases. In the first example, we will deal
with extending Prologs data representation with integer sets, represented as bit-vectors. Then, we
discuss the outline of the DDE interface.

Integer sets with not-too-far-apart upper- and lower-bounds can be represented using bit-vectors.
Common set operations, such as union, intersection, etc., are reduced to simple anding and oring
the bit-vectors. This can be done using Prologs unbounded integers.
For really demanding applications, foreign representation will perform better, especially time-
wise. Bit-vectors are naturally expressed using string objects. If the string is wrapped in
bitvector/1, the lower-bound of the vector is 0 and the upper-bound is not defined; an imple-
mentation for getting and putting the sets as well as the union predicate for it is below.

#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

SWI-Prolog 7.4 Reference Manual

366 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

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);

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 367

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

}

The DDE interface (see section 4.43) represents another common usage of the foreign interface:
providing communication to new operating system features. The DDE interface requires knowledge
about active DDE server and client channels. These channels contains various foreign data types. Such
an interface is normally achieved using an open/close protocol that creates and destroys a handle. The
handle is a reference to a foreign data structure containing the relevant information.
There are a couple of possibilities for representing the handle. The choice depends on respon-
sibilities and debugging facilities. The simplest approach is to use PL unify pointer() and
PL get pointer(). This approach is fast and easy, but has the drawbacks of (untyped) point-
ers: there is no reliable way to detect the validity of the pointer, nor to verify that it is pointing to a
structure of the desired type. The pointer may be wrapped into a compound term with arity 1 (i.e.,
dde channel(hPointeri)), making the type-problem less serious.
Alternatively (used in the DDE interface), the interface code can maintain a (preferably variable
length) array of pointers and return the index in this array. This provides better protection. Especially
for debugging purposes, wrapping the handle in a compound is a good suggestion.

11.4.21 Embedding SWI-Prolog in other applications

With embedded Prolog we refer to the situation where the main program is not the Prolog applica-
tion. Prolog is sometimes embedded in C, C++, Java or other languages to provide logic based services
in a larger application. Embedding loads the Prolog engine as a library to the external language. Pro-
log itself only provides for embedding in the C language (compatible with C++). Embedding in Java
is achieved using JPL using a C-glue between the Java and Prolog C interfaces.
The most simple embedded program is below. The interface function PL initialise()
must be called before any of the other SWI-Prolog foreign language functions described in
this chapter, except for PL initialise hook(), PL new atom(), PL new functor() and
PL register foreign(). PL initialise() interprets all the command line arguments, ex-
cept for the -t toplevel flag that is interpreted by PL toplevel().

int
main(int argc, char **argv)
{ if ( !PL_initialise(argc, argv) )
PL_halt(1);

PL_halt(PL_toplevel() ? 0 : 1);
}

int PL initialise(int argc, char **argv)

Initialises the SWI-Prolog heap and stacks, restores the Prolog state, loads the system and
personal initialisation files, runs the initialization/1 hooks and finally runs the
-g goal hook.
Special consideration is required for argv[0]. On Unix, this argument passes the part of the
command line that is used to locate the executable. Prolog uses this to find the file holding the

SWI-Prolog 7.4 Reference Manual

368 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

running executable. The Windows version uses this to find a module of the running executable.
If the specified module cannot be found, it tries the module libpl.dll, containing the Prolog
runtime kernel. In all these cases, the resulting file is used for two purposes:

See whether a Prolog saved state is appended to the file. If this is the case, this state will
be loaded instead of the default boot.prc file from the SWI-Prolog home directory. See
also qsave program/[1,2] and section 11.5.
Find the Prolog home directory. This process is described in detail in section 11.6.

PL initialise() returns 1 if all initialisation succeeded and 0 otherwise.12

In most cases, argc and argv will be passed from the main program. It is allowed to create
your own argument vector, provided argv[0] is constructed according to the rules above. For
example:

int
main(int argc, char **argv)
{ char *av[10];
int ac = 0;

av[ac++] = argv[0];
av[ac++] = "-x";
av[ac++] = "mystate";
av[ac] = NULL;

if ( !PL_initialise(ac, av) )
PL_halt(1);
...
}

Please note that the passed argument vector may be referred from Prolog at any time and should
therefore be valid as long as the Prolog engine is used.
A good setup in Windows is to add SWI-Prologs bin directory to your PATH and either pass
a module holding a saved state, or "libpl.dll" as argv[0]. If the Prolog state is attached
to a DLL (see the -dll option of swipl-ld), pass the name of this DLL.

int PL is initialised(int *argc, char ***argv)

Test whether the Prolog engine is already initialised. Returns FALSE if Prolog is not initialised
and TRUE otherwise. If the engine is initialised and argc is not NULL, the argument count used
with PL initialise() is stored in argc. Same for the argument vector argv.

int PL set resource db mem(const unsigned char *data, size t size)

This function must be called at most once and before calling PL initialise(). The mem-
ory area designated by data and size must contain the resource data and be in the format as
12
BUG: Various fatal errors may cause PL initialise() to call PL halt(1), preventing it from returning at all.

SWI-Prolog 7.4 Reference Manual

11.4. THE FOREIGN INCLUDE FILE 369

produced by qsave program/2. The memory area is accessed by PL initialise() as

well as calls to open resource/3.13
For example, we can include the bootstrap data into an embedded executable using the steps
below. The advantage of this approach is that it is fully supported by any OS and you obtain a
single file executable.

1. Create a saved state using qsave program/2 or

% swipl -o state -c file.pl ...

2. Create a C source file from the state using e.g., the Unix utility xxd(1):
% xxd -i state > state.h

3. Embed Prolog as in the example below. Instead of calling the toplevel you probably want
to call your application code.
#include <SWI-Prolog.h>
#include "state.h"

int
main(int argc, char **argv)
{ if ( !PL_set_resource_db_mem(state, state_len) ||
!PL_initialise(argc, argv) )
PL_halt(1);

return PL_toplevel();
}

Alternative to xxd, it is possible to use inline assembler, e.g. the gcc incbin instruction.
Code for gcc was provided by Roberto Bagnara on the SWI-Prolog mailinglist. Given the state
in a file state, create the following assembler program:

.globl _state
.globl _state_end
_state:
.incbin "state"
_state_end:

Now include this as follows:

#include <SWI-Prolog.h>

#if __linux
#define STATE _state
13
This implies that the data must remain accessible during the lifetime of the process if open resource/3 is used.
Future versions may provide a function to detach the resource database and cause open resource/3 to raise an excep-
tion.

SWI-Prolog 7.4 Reference Manual

370 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

#define STATE_END _state_end

#else
#define STATE state
#define STATE_END state_end
#endif

extern unsigned char STATE[];

extern unsigned char STATE_END[];

int
main(int argc, char **argv)
{ if ( !PL_set_resource_db_mem(STATE, STATE_END - STATE) ||
!PL_initialise(argc, argv) )
PL_halt(1);
return PL_toplevel();
}

As Jose Morales pointed at https://github.com/graphitemaster/incbin, which

contains a portability layer on top of the above idea.

int PL toplevel()
Runs the goal of the -t toplevel switch (default prolog/0) and returns 1 if successful,
0 otherwise.

int PL cleanup(int status)

This function performs the reverse of PL initialise(). It runs the PL on halt() and
at halt/1 handlers, closes all streams (except for the standard I/O streams which are
flushed only), deallocates all memory and restores all signal handlers. The status argument is
passed to the various termination hooks and indicates the exit-status.
The function returns TRUE if successful and FALSE otherwise. Currently, FALSE is returned
when an attempt is made to call PL cleanup() recursively or if one of the exit handlers
cancels the termination using cancel halt/1. Exit handlers may only cancel termination if
status is 0.
In theory, this function allows deleting and restarting the Prolog system in the same process. In
practice, SWI-Prologs cleanup process is far from complete, and trying to revive the system
using PL initialise() will leak memory in the best case. It can also crash the appliction.
In this state, there is little practical use for this function. If you want to use Prolog temporarily,
consider running it in a separate process. If you want to be able to reset Prolog, your options
are (again) a separate process, modules or threads.

void PL cleanup fork()

Stop intervaltimer that may be running on behalf of profile/1. The call is intended to be
used in combination with fork():

if ( (pid=fork()) == 0 )
{ PL_cleanup_fork();

SWI-Prolog 7.4 Reference Manual

11.5. LINKING EMBEDDED APPLICATIONS USING SWIPL-LD 371

<some exec variation>

}

The call behaves the same on Windows, though there is probably no meaningful application.

int PL halt(int status)

Clean up the Prolog environment using PL cleanup() and if successful call exit() with the
status argument. Returns FALSE if exit was cancelled by PL cleanup().

Threading, Signals and embedded Prolog

This section applies to Unix-based environments that have signals or multithreading. The Windows
version is compiled for multithreading, and Windows lacks proper signals.
We can distinguish two classes of embedded executables. There are small C/C++ programs that
act as an interfacing layer around Prolog. Most of these programs can be replaced using the normal
Prolog executable extended with a dynamically loaded foreign extension and in most cases this is
the preferred route. In other cases, Prolog is embedded in a complex application thatlike Prolog
wants to control the process environment. A good example is Java. Embedding Prolog is generally
the only way to get these environments together in one process image. Java VMs, however, are by
nature multithreaded and appear to do signal handling (software interrupts).
On Unix systems, SWI-Prolog uses two signals:

SIGUSR2 has an empty signal handler. This signal is sent to a thread after sending a thread-signal
(see thread signal/2). It causes blocking system calls to return with EINTR, which gives
them the opportunity to react to thread-signals.

SIGINT is used by the top level to activate the tracer (typically bound to control-C). The first control-
C posts a request for starting the tracer in a safe, synchronous fashion. If control-C is hit again
before the safe route is executed, it prompts the user whether or not a forced interrupt is desired.

The --nosignals option can be used to inhibit processing of SIGINT. The handling of
SIGUSR2 is vital for dealing with blocking system call in threads. If the way SWI-Prolog uses
this signal conflicts with other applications, signal handling of either component must be modified.
The SWI-Prolog signals are defined in pl-thread.h of the source distribution.

11.5 Linking embedded applications using swipl-ld

The utility program swipl-ld (Win32: swipl-ld.exe) may be used to link a combination of C files
and Prolog files into a stand-alone executable. swipl-ld automates most of what is described in the
previous sections.
In normal usage, a copy is made of the default embedding template .../swipl/include/
stub.c. The main() routine is modified to suit your application. PL initialise() must be
passed the program name (argv[0]) (Win32: the executing program can be obtained using GetMod-
uleFileName()). The other elements of the command line may be modified. Next, swipl-ld is
typically invoked as:

swipl-ld -o output stubfile.c [other-c-or-o-files] [plfiles]

SWI-Prolog 7.4 Reference Manual

372 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

swipl-ld will first split the options into various groups for both the C compiler and the Prolog
compiler. Next, it will add various default options to the C compiler and call it to create an executable
holding the users C code and the Prolog kernel. Then, it will call the SWI-Prolog compiler to create
a saved state from the provided Prolog files and finally, it will attach this saved state to the created
emulator to create the requested executable.
Below, it is described how the options are split and which additional options are passed.
-help
Print brief synopsis.
-pl prolog
Select the Prolog to use. This Prolog is used for two purposes: get the home directory as well
as the compiler/linker options and create a saved state of the Prolog code.
-ld linker
Linker used to link the raw executable. Default is to use the C compiler (Win32: link.exe).
-cc C compiler
Compiler for .c files found on the command line. Default is the compiler used to build SWI-
Prolog accessible through the Prolog flag c cc (Win32: cl.exe).
-c++ C++-compiler
Compiler for C++ source file (extensions .cpp, .cxx, .cc or .C) found on the command
line. Default is c++ or g++ if the C compiler is gcc (Win32: cl.exe).
-nostate
Just relink the kernel, do not add any Prolog code to the new kernel. This is used to create a new
kernel holding additional foreign predicates on machines that do not support the shared-library
(DLL) interface, or if building the state cannot be handled by the default procedure used by
swipl-ld. In the latter case the state is created separately and appended to the kernel using
cat hkerneli hstatei > houti (Win32: copy /b hkerneli+hstatei houti).
-shared
Link C, C++ or object files into a shared object (DLL) that can be loaded by the
load foreign library/1 predicate. If used with -c it sets the proper options to
compile a C or C++ file ready for linking into a shared object.
-dll
Windows only. Embed SWI-Prolog into a DLL rather than an executable.
-c
Compile C or C++ source files into object files. This turns swipl-ld into a replacement for
the C or C++ compiler, where proper options such as the location of the include directory are
passed automatically to the compiler.
-E
Invoke the C preprocessor. Used to make swipl-ld a replacement for the C or C++ compiler.
-pl-options ,. . .
Additional options passed to Prolog when creating the saved state. The first character immedi-
ately following pl-options is used as separator and translated to spaces when the argument
is built. Example: -pl-options,-F,xpce passes -F xpce as additional flags to Prolog.

SWI-Prolog 7.4 Reference Manual

11.5. LINKING EMBEDDED APPLICATIONS USING SWIPL-LD 373

-ld-options ,. . .
Passes options to the linker, similar to -pl-options.

-cc-options ,. . .
Passes options to the C/C++ compiler, similar to -pl-options.

-v
Select verbose operation, showing the various programs and their options.

-o outfile
Reserved to specify the final output file.

-llibrary
Specifies a library for the C compiler. By default, -lswipl (Win32: libpl.lib) and the libraries
needed by the Prolog kernel are given.

-Llibrary-directory
Specifies a library directory for the C compiler. By default the directory containing the Prolog
C library for the current architecture is passed.

-g | -Iinclude-directory | -Ddefinition
These options are passed to the C compiler. By default, the include directory containing
SWI-Prolog.h is passed. swipl-ld adds two additional * -Ddef flags:

-D SWI PROLOG
Indicates the code is to be connected to SWI-Prolog.
-D SWI EMBEDDED
Indicates the creation of an embedded program.

*.o | *.c | *.C | *.cxx | *.cpp

Passed as input files to the C compiler.

*.pl |*.qlf
Passed as input files to the Prolog compiler to create the saved state.

*
All other options. These are passed as linker options to the C compiler.

11.5.1 A simple example

The following is a very simple example going through all the steps outlined above. It provides an
arithmetic expression evaluator. We will call the application calc and define it in the files calc.c
and calc.pl. The Prolog file is simple:

calc(Atom) :-
term_to_atom(Expr, Atom),
A is Expr,
write(A),
nl.

SWI-Prolog 7.4 Reference Manual

374 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

#include <stdio.h>
#include <SWI-Prolog.h>

#define MAXLINE 1024

int
main(int argc, char **argv)
{ char expression[MAXLINE];
char *e = expression;
char *program = argv[0];
char *plav[2];
int n;

/* combine all the arguments in a single string */

for(n=1; n<argc; n++)

{ if ( n != 1 )
*e++ = ;
strcpy(e, argv[n]);
e += strlen(e);
}

/* make the argument vector for Prolog */

plav[0] = program;
plav[1] = NULL;

/* initialise Prolog */

if ( !PL_initialise(1, plav) )
PL_halt(1);

/* Lookup calc/1 and make the arguments and call */

{ predicate_t pred = PL_predicate("calc", 1, "user");

term_t h0 = PL_new_term_refs(1);
int rval;

PL_put_atom_chars(h0, expression);
rval = PL_call_predicate(NULL, PL_Q_NORMAL, pred, h0);

PL_halt(rval ? 0 : 1);
}

return 0;
}

SWI-Prolog 7.4 Reference Manual Figure 11.4: C source for the calc application
11.6. THE PROLOG HOME DIRECTORY 375

The C part of the application parses the command line options, initialises the Prolog engine, locates
the calc/1 predicate and calls it. The coder is in figure 11.4.
The application is now created using the following command line:

% swipl-ld -o calc calc.c calc.pl

The following indicates the usage of the application:

% calc pi/2
1.5708

11.6 The Prolog home directory

Executables embedding SWI-Prolog should be able to find the home directory of the devel-
opment environment unless a self-contained saved state has been added to the executable (see
qsave program/[1,2] and section 11.5).
If Prolog starts up, it will try to locate the development environment. To do so, it will try the
following steps until one succeeds:

1. If the --home=DIR is provided, use this.

2. If the environment variable SWI HOME DIR is defined and points to an existing directory, use
this.

3. If the environment variable SWIPL is defined and points to an existing directory, use this.

4. Locate the primary executable or (Windows only) a component (module) thereof and check
whether the parent directory of the directory holding this file contains the file swipl. If so,
this file contains the (relative) path to the home directory. If this directory exists, use this. This
is the normal mechanism used by the binary distribution.

5. If the precompiled path exists, use it. This is only useful for a source installation.

If all fails and there is no state attached to the executable or provided Windows module (see
PL initialise()), SWI-Prolog gives up. If a state is attached, the current working directory is
used.
The file search path/2 alias swi is set to point to the home directory located.

11.7 Example of Using the Foreign Interface

Below is an example showing all stages of the declaration of a foreign predicate that transforms atoms
possibly holding uppercase letters into an atom only holding lowercase letters. Figure 11.5 shows the
C source file, figure 11.6 illustrates compiling and loading of foreign code.

SWI-Prolog 7.4 Reference Manual

376 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

/* Include file depends on local installation */

#include <SWI-Prolog.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>

foreign_t
pl_lowercase(term_t u, term_t l)
{ char *copy;
char *s, *q;
int rval;

if ( !PL_get_atom_chars(u, &s) )
return PL_warning("lowercase/2: instantiation fault");
copy = malloc(strlen(s)+1);

for( q=copy; *s; q++, s++)

*q = (isupper(*s) ? tolower(*s) : *s);
* = \0;
q

rval = PL_unify_atom_chars(l, copy);

free(copy);

return rval;
}

install_t
install()
{ PL_register_foreign("lowercase", 2, pl_lowercase, 0);
}

Figure 11.5: Lowercase source file

SWI-Prolog 7.4 Reference Manual

11.7. EXAMPLE OF USING THE FOREIGN INTERFACE 377

% gcc -I/usr/local/lib/swipl-\plversion/include -fpic -c lowercase.c

% gcc -shared -o lowercase.so lowercase.o
% swipl
Welcome to SWI-Prolog (...)
...

1 ?- load_foreign_library(lowercase).
true.

2 ?- lowercase(Hello World!, L).

L = hello world!.

Figure 11.6: Compiling the C source and loading the object file

SWI-Prolog 7.4 Reference Manual

378 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

11.8 Notes on Using Foreign Code

11.8.1 Foreign debugging functions
The functions in this section are primarily intended for debugging foreign extensions or embedded
Prolog. Violating the constraints of the foreign interface often leads to crashes in a subsequent garbage
collection. If this happens, the system needs to be recompiled with the cflags -DO DEBUG. This is
normally achieved by editing src/Makefile and changing the definition of COFLAGS to the value
below. The -gdwarf-2 -g3 provides detailed debugging information for gcc. If you use another
C compiler you may need other flags.

COFLAGS=-DO_DEBUG -gdwarf-2 -g3

After recompiling the Prolog kernel all functions listed above are available to use from the debugger
(e.g. gdb) or can be placed at critical location in your code or the system code.

void PL backtrace(int depth, int flags)

Dump a Prolog backtrace to the user error stream. Depth is the number of frames to dump.
Flags is a bitwise or of the following constants:

PL BT SAFE
(0x1) Do not try to print goals. Instead, just print the predicate name and arity. This
reduces the likelyhood to crash if PL backtrace() is called in a damaged environment.
PL BT USER
(0x2) Only show user frames. Default is to also show frames of hidden built-in predi-
cates.

char * PL backtrace string(int depth, int flags)

As PL backtrace(), but returns the stack as a string. The string uses UTF-8 encoding. The
returned string must be freed using PL free(). This function is was added to get stack traces
from running servers where I/O is redirected or discarded. For example, using gdb, a stack
trace is printed in the gdb console regardless of Prolog I/O redirection using the following
command:

(gdb) printf "%s", PL_backtrace_string(25,0)

The source distribution provides the script scripts/swipl-bt that exploits gdb and
PL backtrace string() to print stack traces in various formats for a SWI-Prolog pro-
cess, given its process id.

int PL check data(term t data)

Check the consistency of the term data. Returns TRUE this is actually implemented in the
current version and FALSE otherwise. The actual implementation only exists if the system is
compiled with the cflag -DO DEBUG or -DO MAINTENANCE. This is not the default.

int PL check stacks()

Check the consistency of the runtime stacks of the calling thread. Returns TRUE this is actually
implemented in the current version and FALSE otherwise. The actual implementation only

SWI-Prolog 7.4 Reference Manual

11.8. NOTES ON USING FOREIGN CODE 379

exists if the system is compiled with the cflag -DO DEBUG or -DO MAINTENANCE. This is
not the default.

The Prolog kernel sources use the macro DEBUG(Topic, Code). These macros are disabled in the
production version and must be enabled by recompiling the system as described above. Specific topics
can be enabled and disabled using the predicates prolog debug/1 and prolog nodebug/1. In
addition, they can be activated from the commandline using commandline option -d topics, where
topics is a comma-separated list of debug topics to enable. For example, the code below adds many
consistency checks and prints messages if the Prolog signal handler dispatches signals.

$ swipl -d chk_secure,msg_signal

prolog debug(+Topic)
prolog nodebug(+Topic)
Enable/disable a debug topic. Topic is an atom that identifies the desired topic. The available
topics are defined in src/pl-debug.h. Please search the sources to find out what is actually
printed and when. We highlight one topic here:

chk secure(A)
dd many expensive consistency checks to the system. This should typically be used
when the system crashes, notably in the garbage collector. Garbage collection crashes
are in most cases caused by invalid data on the Prolog stacks. This debug topic may help
locating how the invalid data was created.

11.8.2 Memory Allocation

SWI-Prologs heap memory allocation is based on the malloc(3) library routines. SWI-Prolog
provides the functions below as a wrapper around malloc(). Allocation errors in these functions trap
SWI-Prologs fatal-error handler, in which case PL malloc() or PL realloc() do not return.
Portable applications must use PL free() to release strings returned by PL get chars()
using the BUF MALLOC argument. Portable applications may use both PL malloc() and friends or
malloc() and friends but should not mix these two sets of functions on the same memory.

void * PL malloc(size t bytes)

Allocate bytes of memory. On failure SWI-Prologs fatal-error handler is called and
PL malloc() does not return. Memory allocated using these functions must use
PL realloc() and PL free() rather than realloc() and free().

void * PL realloc(void *mem, size t size)

Change the size of the allocated chunk, possibly moving it. The mem argument must be ob-
tained from a previous PL malloc() or PL realloc() call.

void PL free(void *mem)

Release memory. The mem argument must be obtained from a previous PL malloc() or
PL realloc() call.

SWI-Prolog 7.4 Reference Manual

380 CHAPTER 11. FOREIGN LANGUAGE INTERFACE

Boehm-GC support

This section is obsolete. Although the Boehm-GC interfaces still exist, it turns out that
the scalability is not good enough for SWI-Prolog. It is unlikely that SWI-Prolog will
ever switch to Boehm-GC.

To accommodate future use of the Boehm garbage collector14 for heap memory allocation, the
interface provides the functions described below. Foreign extensions that wish to use the Boehm-GC
facilities can use these wrappers. Please note that if SWI-Prolog is not compiled to use Boehm-GC
(default), the user is responsible for calling PL free() to reclaim memory.

void* PL malloc atomic(size t bytes)

void* PL malloc uncollectable(size t bytes)
void* PL malloc atomic uncollectable(size t bytes)
If Boehm-GC is not used, these are all the same as PL malloc(). With Boehm-GC, these
map to the corresponding Boehm-GC functions. Atomic means that the content should not
be scanned for pointers, and uncollectable means that the object should never be garbage
collected.

void* PL malloc stubborn(size t bytes)

void PL end stubborn change(void *memory)
These functions allow creating objects, promising GC that the content will not change after
PL end stubborn change().

11.8.3 Compatibility between Prolog versions

Great care is taken to ensure binary compatibility of foreign extensions between different Prolog
versions. Only the much less frequently used stream interface has been responsible for binary incom-
patibilities.
Source code that relies on new features of the foreign interface can use the macro PLVERSION
to find the version of SWI-Prolog.h and PL query() using the option PL QUERY VERSION to
find the version of the attached Prolog system. Both follow the same numbering schema explained
with PL query().

11.8.4 Debugging and profiling foreign code (valgrind)

This section is only relevant for Unix users on platforms supported by valgrind. Valgrind is an excel-
lent binary instrumentation platform. Unlike many other instrumentation platforms, valgrind can deal
with code loaded through dlopen().
The callgrind tool can be used to profile foreign code loaded under SWI-Prolog. Compile
the foreign library adding -g option to gcc or swipl-ld. By setting the environment variable
VALGRIND to yes, SWI-Prolog will not release loaded shared objects using dlclose(). This trick
is required to get source information on the loaded library. Without, valgrind claims that the shared
object has no debugging information.15 Here is the complete sequence using bash as login shell:
14
http://www.hpl.hp.com/personal/Hans_Boehm/gc/
15
Tested using valgrind version 3.2.3 on x64.

SWI-Prolog 7.4 Reference Manual

11.8. NOTES ON USING FOREIGN CODE 381

% VALGRIND=yes valgrind --tool=callgrind pl <args>

<prolog interaction>
% kcachegrind callgrind.out.<pid>

11.8.5 Name Conflicts in C modules

In the current version of the system all public C functions of SWI-Prolog are in the symbol table.
This can lead to name clashes with foreign code. Someday I should write a program to strip all these
symbols from the symbol table (why does Unix not have that?). For now I can only suggest you give
your function another name. You can do this using the C preprocessor. Iffor exampleyour foreign
package uses a function warning(), which happens to exist in SWI-Prolog as well, the following macro
should fix the problem:

#define warning warning_

Note that shared libraries do not have this problem as the shared library loader will only look for
symbols in the main executable for symbols that are not defined in the library itself.

11.8.6 Compatibility of the Foreign Interface

The term reference mechanism was first used by Quintus Prolog version 3. SICStus Prolog version 3
is strongly based on the Quintus interface. The described SWI-Prolog interface is similar to using the
Quintus or SICStus interfaces, defining all foreign-predicate arguments of type +term. SWI-Prolog
explicitly uses type functor t, while Quintus and SICStus use hnamei and harityi. As the names
of the functions differ from Prolog to Prolog, a simple macro layer dealing with the names can also
deal with this detail. For example:

#define QP_put_functor(t, n, a) \
PL_put_functor(t, PL_new_functor(n, a))

The PL unify *() functions are lacking from the Quintus and SICStus interface. They can easily
be emulated, or the put/unify approach should be used to write compatible code.
The PL open foreign frame()/PL close foreign frame() combination is
lacking from both other Prologs. SICStus has PL new term refs(0), followed by
PL reset term refs(), that allows for discarding term references.
The Prolog interface for the graphical user interface package XPCE shares about 90% of the code
using a simple macro layer to deal with different naming and calling conventions of the interfaces.

SWI-Prolog 7.4 Reference Manual

Generating Runtime
Applications 12
This chapter describes the features of SWI-Prolog for delivering applications that can run without the
development version of the system installed.
A SWI-Prolog runtime executable is a file consisting of two parts. The first part is the emulator,
which is machine-dependent. The second part is the resource archive, which contains the compiled
program in a machine-independent format, startup options and possibly user-defined resources; see
resource/3 and open resource/3.
These two parts can be connected in various ways. The most common way for distributed runtime
applications is to concatenate the two parts. This can be achieved using external commands (Unix:
cat, Windows: copy), or using the stand alone option to qsave program/2. The second
option is to attach a startup script in front of the resource that starts the emulator with the proper
options. This is the default under Unix. Finally, an emulator can be told to use a specified resource
file using the -x command line switch.

qsave program(+File, +Options)

Saves the current state of the program to the file File. The result is a resource archive containing
a saved state that expresses all Prolog data from the running program and all user-defined
resources. Depending on the stand alone option, the resource is headed by the emulator, a
Unix shell script or nothing. Options is a list of additional options:

local(+KBytes)
Limit for the local stack. See section 2.4.3.
global(+KBytes)
Limit for the global stack. See section 2.4.3.
trail(+KBytes)
Limit for the trail stack. See section 2.4.3.
goal(:Callable)
Initialization goal for the new executable (see -g).
toplevel(:Callable)
Top-level goal for the new executable (see -t).
init file(+Atom)
Default initialization file for the new executable. See -f.
class(+Class)
If runtime, only read resources from the state (default). If kernel, lock all predicates
as system predicates. If development, save the predicates in their current state and
keep reading resources from their source (if present). See also resource/3.
autoload(+Boolean)
If true (default), run autoload/0 first.

SWI-Prolog 7.4 Reference Manual

 383

map(+File)
Dump a human-readable trace of what has been saved in File.
op(+Action)
One of save (default) to save the current operator table or standard to use the initial
table of the emulator.
stand alone(+Boolean)
If true, the emulator is the first part of the state. If the emulator is started it will test
whether a boot file (state) is attached to the emulator itself and load this state. Provided
the application has all libraries loaded, the resulting executable is completely independent
of the runtime environment or location where it was built. See also section 2.10.2.
emulator(+File)
File to use for the emulator. Default is the running Prolog image.
foreign(+Action)
If save, include shared objects (DLLs) into the saved state. See
current foreign library/2. If the program strip is available, this is first used
to reduce the size of the shared object. If a state is started, use foreign library/1
first tries to locate the foreign resource in the executable. When found it copies the
content of the resource to a temporary file and loads it. If possible (Unix), the temporary
object is deleted immediately after opening.1

qsave program(+File)
Equivalent to qsave program(File, []).

autoload
Check the current Prolog program for predicates that are referred to, are undefined and have a
definition in the Prolog library. Load the appropriate libraries.
This predicate is used by qsave program/[1,2] to ensure the saved state does not depend
on availability of the libraries. The predicate autoload/0 examines all clauses of the loaded
program (obtained with clause/2) and analyzes the body for referenced goals. Such an anal-
ysis cannot be complete in Prolog, which allows for the creation of arbitrary terms at runtime
and the use of them as a goal. The current analysis is limited to the following:

Direct goals appearing in the body

Arguments of declared meta-predicates that are marked with an integer (0..9). See
meta predicate/1.

The analysis of meta-predicate arguments is limited to cases where the argument appears liter-
ally in the clause or is assigned using =/2 before the meta-call. That is, the following fragment
is processed correctly:

...,
Goal = prove(Theory),
forall(current_theory(Theory),
Goal)),
1
This option is experimental and currently disabled by default. It will become the default if it proves robust.

SWI-Prolog 7.4 Reference Manual

384 CHAPTER 12. GENERATING RUNTIME APPLICATIONS

But, the calls to prove simple/1 and prove complex/1 in the example below are not
discovered by the analysis and therefore the modules that define these predicates must be loaded
explicitly using use module/1,2.

...,
member(Goal, [ prove_simple(Theory),
prove_complex(Theory)
]),
forall(current_theory(Theory),
Goal)),

It is good practice to use gxref/0 to make sure that the program has sufficient declarations
such that the analaysis tools can verify that all required predicates can be resolved and that all
code is called. See meta predicate/1, dynamic/1, public/1 and prolog:called by/2.

volatile +Name/Arity, . . .
Declare that the clauses of specified predicates should not be saved to the program. The volatile
declaration is normally used to prevent the clauses of dynamic predicates that represent data
for the current session from being saved in the state file.

12.1 Limitations of qsave program

There are three areas that require special attention when using qsave program/[1,2].

If the program is an embedded Prolog application or uses the foreign language interface, care
has to be taken to restore the appropriate foreign context. See section 12.2 for details.

If the program uses directives (:- goal. lines) that perform other actions than setting predi-
cate attributes (dynamic, volatile, etc.) or loading files (consult, etc.), the directive may need to
be prefixed with initialization/1.

Database references as returned by clause/3, recorded/3, etc., are not preserved and may
thus not be part of the database when saved.

12.2 Runtimes and Foreign Code

Some applications may need to use the foreign language interface. Object code is by definition
machine-dependent and thus cannot be part of the saved program file.
To complicate the matter even further there are various ways of loading foreign code:

Using the library(shlib) predicates

This is the preferred way of dealing with foreign code. It loads quickly and ensures an accept-
able level of independence between the versions of the emulator and the foreign code loaded. It
works on Unix machines supporting shared libraries and library functions to load them. Most
modern Unixes, as well as Win32 (Windows 95/NT), satisfy this constraint.

SWI-Prolog 7.4 Reference Manual

12.3. USING PROGRAM RESOURCES 385

Static linking
This mechanism works on all machines, but generally requires the same C compiler and linker
to be used for the external code as is used to build SWI-Prolog itself.

To make a runtime executable that can run on multiple platforms one must make runtime checks
to find the correct way of linking. Suppose we have a source file myextension.c defining the
installation function install().
If this file is compiled into a shared library, load foreign library/1 will load this library
and call the installation function to initialise the foreign code. If it is loaded as a static extension,
define install() as the predicate install/0:

static foreign_t
pl_install()
{ install();

PL_succeed;
}

PL_extension PL_extensions [] =
{
/*{ "name", arity, function, PL_FA_<flags> },*/

{ "install", 0, pl_install, 0 },
{ NULL, 0, NULL, 0 } /* terminating line */
};

Now, use the following Prolog code to load the foreign library:

load_foreign_extensions :-
current_predicate(install, install), !, % static loaded
install.
load_foreign_extensions :- % shared library
load_foreign_library(foreign(myextension)).

:- initialization load_foreign_extensions.

The path alias foreign is defined by file search path/2. By default it searches the di-
rectories hhomei/lib/harchi and hhomei/lib. The application can specify additional rules for
file search path/2.

12.3 Using program resources

A resource is very similar to a file. Resources, however, can be represented in two different formats:
on files, as well as part of the resource archive of a saved state (see qsave program/2).
A resource has a name and a class. The source data of the resource is a file. Resources
are declared by declaring the predicate resource/3. They are accessed using the predicate
open resource/3.

SWI-Prolog 7.4 Reference Manual

386 CHAPTER 12. GENERATING RUNTIME APPLICATIONS

Before going into details, let us start with an example. Short texts can easily be expressed in Prolog
source code, but long texts are cumbersome. Assume our application defines a command help that
prints a helptext to the screen. We put the content of the helptext into a file called help.txt. The
following code implements our help command such that help.txt is incorporated into the runtime
executable.

resource(help, text, help.txt).

help :-
open_resource(help, text, In),
call_cleanup(copy_stream_data(In, user_output),
close(In)).

The predicate help/0 opens the resource as a Prolog stream. If we are executing this from the devel-
opment environment, this will actually return a stream to the file help.txt itself. When executed
from the saved state, the stream will actually be a stream opened on the program resource file, taking
care of the offset and length of the resource.

12.3.1 Resource manipulation predicates

resource(+Name, +Class, +FileSpec)
This predicate is defined as a dynamic predicate in the module user. Clauses for it may be
defined in any module, including the user module. Name is the name of the resource (an atom).
A resource name may contain any character, except for $ and :, which are reserved for internal
usage by the resource library. Class describes the kind of object stored in the resource. In
the current implementation, it is just an atom. FileSpec is a file specification that may exploit
file search path/2 (see absolute file name/2).
Normally, resources are defined as unit clauses (facts), but the definition of this predicate also
allows for rules. For proper generation of the saved state, it must be possible to enumerate the
available resources by calling this predicate with all its arguments unbound.
Dynamic rules are useful to turn all files in a certain directory into resources, without specifying
a resource for each file. For example, assume the file search path/2 icons refers to
the resource directory containing icon files. The following definition makes all these images
available as resources:

resource(Name, image, icons(XpmName)) :-

atom(Name), !,
file_name_extension(Name, xpm, XpmName).
resource(Name, image, XpmFile) :-
var(Name),
absolute_file_name(icons(.), [type(directory)], Dir)
concat(Dir, /*.xpm, Pattern),
expand_file_name(Pattern, XpmFiles),
member(XpmFile, XpmFiles).

SWI-Prolog 7.4 Reference Manual

12.4. FINDING APPLICATION FILES 387

open resource(+Name, ?Class, -Stream)

Opens the resource specified by Name and Class. If the latter is a variable, it will be unified to
the class of the first resource found that has the specified Name. If successful, Stream becomes
a handle to a binary input stream, providing access to the content of the resource.
The predicate open resource/3 first checks resource/3. When successful it will open
the returned resource source file. Otherwise it will look in the programs resource database.
When creating a saved state, the system normally saves the resource contents into the resource
archive, but does not save the resource clauses.
This way, the development environment uses the files (and modifications) to the resource/3
declarations and/or files containing resource info, thus immediately affecting the running envi-
ronment, while the runtime system quickly accesses the system resources.

12.3.2 The swipl-rc program

The utility program swipl-rc can be used to examine and manipulate the contents of a SWI-Prolog
resource file. The options are inspired by the Unix ar program. The basic command is:

% swipl-rc option resource-file member ...

The options are described below.

l
List contents of the archive.
x
Extract named (or all) members of the archive into the current directory.
a
Add files to the archive. If the archive already contains a member with the same name, the
contents are replaced. Anywhere in the sequence of members, the options --class=class
and --encoding=encoding may appear. They affect the class and encoding of subsequent
files. The initial class is data and encoding none.
d
Delete named members from the archive.

This command is also described in the pl(1) Unix manual page.

12.4 Finding Application files

If your application uses files that are not part of the saved program such as database files, configuration
files, etc., the runtime version has to be able to locate these files. The file search path/2
mechanism in combination with the -palias command line argument is the preferred way to locate
runtime files. The first step is to define an alias for the top-level directory of your application. We will
call this directory gnatdir in our examples.
A good place for storing data associated with SWI-Prolog runtime systems is below the emulators
home directory. swi is a predefined alias for this directory. The following is a useful default definition
for the search path.

SWI-Prolog 7.4 Reference Manual

388 CHAPTER 12. GENERATING RUNTIME APPLICATIONS

user:file_search_path(gnatdir, swi(gnat)).

The application should locate all files using absolute file name. Suppose gnatdir contains a file
config.pl to define the local configuration. Then use the code below to load this file:

configure_gnat :-
( absolute_file_name(gnatdir(config.pl), ConfigFile)
-> consult(ConfigFile)
; format(user_error, gnat: Cannot locate config.pln),
halt(1)
).

12.4.1 Specifying a file search path from the command line

Suppose the system administrator has installed the SWI-Prolog runtime environment in /usr/
local/lib/rt-pl-3.2.0. A user wants to install gnat, but gnat will look for its configu-
ration in /usr/local/lib/rt-pl-3.2.0/gnat where the user cannot write.
The user decides to install the gnat runtime files in /users/bob/lib/gnat. For one-time
usage, the user may decide to start gnat using the command:

% gnat -p gnatdir=/users/bob/lib/gnat

SWI-Prolog 7.4 Reference Manual

The SWI-Prolog library
This chapter documents the SWI-Prolog library. As SWI-Prolog provides auto-loading, there is little
A
difference between library predicates and built-in predicates. Part of the library is therefore docu-
mented in the rest of the manual. Library predicates differ from built-in predicates in the following
ways:

User definition of a built-in leads to a permission error, while using the name of a library pred-
icate is allowed.

If autoloading is disabled explicitly or because trapping unknown predicates is disabled (see

unknown/2 and current prolog flag/2), library predicates must be loaded explicitly.

Using libraries reduces the footprint of applications that dont need them.

The documentation of the library has just started. Material from the standard packages
should be moved here, some material from other parts of the manual should be moved
too and various libraries are not documented at all.

A.1 library(aggregate): Aggregation operators on backtrackable pred-

icates
Compatibility Quintus, SICStus 4. The forall/2 is a SWI-Prolog built-in and term variables/3
is a SWI-Prolog built-in with different semantics.
To be done
- Analysing the aggregation template and compiling a predicate for the list aggregation can be done at
compile time.
- aggregate all/3 can be rewritten to run in constant space using non-backtrackable assignment
on a term.

This library provides aggregating operators over the solutions of a predicate. The operations
are a generalisation of the bagof/3, setof/3 and findall/3 built-in predicates. The defined
aggregation operations are counting, computing the sum, minimum, maximum, a bag of solutions and
a set of solutions. We first give a simple example, computing the country with the smallest area:

smallest_country(Name, Area) :-
aggregate(min(A, N), country(N, A), min(Area, Name)).

There are four aggregation predicates (aggregate/3, aggregate/4, aggregate all/3

and aggregate/4), distinguished on two properties.

SWI-Prolog 7.4 Reference Manual

390 APPENDIX A. THE SWI-PROLOG LIBRARY

aggregate vs. aggregate all The aggregate predicates use setof/3 (aggregate/4) or
bagof/3 (aggregate/3), dealing with existential qualified variables (VarGoal) and pro-
viding multiple solutions for the remaining free variables in Goal. The aggregate all/3
predicate uses findall/3, implicitly qualifying all free variables and providing exactly one
solution, while aggregate all/4 uses sort/2 over solutions that Discriminator (see be-
low) generated using findall/3.
The Discriminator argument The versions with 4 arguments deduplicate redundant solutions of
Goal. Solutions for which both the template variables and Discriminator are identical will be
treated as one solution. For example, if we wish to compute the total population of all countries,
and for some reason country(belgium, 11000000) may succeed twice, we can use the
following to avoid counting the population of Belgium twice:

aggregate(sum(P), Name, country(Name, P), Total)

All aggregation predicates support the following operators below in Template. In addition, they
allow for an arbitrary named compound term, where each of the arguments is a term from the list
below. For example, the term r(min(X), max(X)) computes both the minimum and maximum
binding for X.

count
Count number of solutions. Same as sum(1).
sum(Expr)
Sum of Expr for all solutions.
min(Expr)
Minimum of Expr for all solutions.
min(Expr, Witness)
A term min(Min, Witness), where Min is the minimal version of Expr over all solutions,
and Witness is any other template applied to solutions that produced Min. If multiple solutions
provide the same minimum, Witness corresponds to the first solution.
max(Expr)
Maximum of Expr for all solutions.
max(Expr, Witness)
As min(Expr, Witness), but producing the maximum result.
set(X)
An ordered set with all solutions for X.
bag(X)
A list of all solutions for X.

Acknowledgements
The development of this library was sponsored by SecuritEase, http://www.securitease.
com

SWI-Prolog 7.4 Reference Manual

A.1. LIBRARY(AGGREGATE): AGGREGATION OPERATORS ON BACKTRACKABLE
PREDICATES 391

aggregate(+Template, :Goal, -Result) [nondet]

Aggregate bindings in Goal according to Template. The aggregate/3 version performs
bagof/3 on Goal.
aggregate(+Template, +Discriminator, :Goal, -Result) [nondet]
Aggregate bindings in Goal according to Template. The aggregate/4 version performs
setof/3 on Goal.
aggregate all(+Template, :Goal, -Result) [semidet]
Aggregate bindings in Goal according to Template. The aggregate all/3 version per-
forms findall/3 on Goal. Note that this predicate fails if Template contains one or more of
min(X), max(X), min(X,Witness) or max(X,Witness) and Goal has no solutions,
i.e., the minumum and maximum of an empty set is undefined.
aggregate all(+Template, +Discriminator, :Goal, -Result) [semidet]
Aggregate bindings in Goal according to Template. The aggregate all/4 version per-
forms findall/3 followed by sort/2 on Goal. See aggregate all/3 to understand
why this predicate can fail.
foreach(:Generator, :Goal)
True if conjunction of results is true. Unlike forall/2, which runs a failure-driven loop that
proves Goal for each solution of Generator, foreach/2 creates a conjunction. Each member
of the conjunction is a copy of Goal, where the variables it shares with Generator are filled
with the values from the corresponding solution.
The implementation executes forall/2 if Goal does not contain any variables that are not
shared with Generator.
Here is an example:

?- foreach(between(1,4,X), dif(X,Y)), Y = 5.
Y = 5.
?- foreach(between(1,4,X), dif(X,Y)), Y = 3.
false.

bug Goal is copied repeatedly, which may cause problems if attributed variables are involved.

free variables(:Generator, +Template, +VarList0, -VarList) [det]

Find free variables in bagof/setof template. In order to handle variables properly, we have to
find all the universally quantified variables in the Generator. All variables as yet unbound are
universally quantified, unless

1. they occur in the template

2. they are bound by XP, setof/3, or bagof/3

free_variables(Generator, Template, OldList, NewList) finds this set

using OldList as an accumulator.

author
- Richard OKeefe
- Jan Wielemaker (made some SWI-Prolog enhancements)

SWI-Prolog 7.4 Reference Manual

392 APPENDIX A. THE SWI-PROLOG LIBRARY

license Public domain (from DEC10 library).

To be done
- Distinguish between control-structures and data terms.
- Exploit our built-in term variables/2 at some places?

sandbox:safe meta(+Goal, -Called) [semidet,multifile]

Declare the aggregate meta-calls safe. This cannot be proven due to the manipulations of the
argument Goal.

A.2 library(apply): Apply predicates on a list

See also
- apply_macros.pl provides compile-time expansion for part of this library.
- http://www.cs.otago.ac.nz/staffpriv/ok/pllib.htm
To be done Add include/4, include/5, exclude/4, exclude/5

This module defines meta-predicates that apply a predicate on all members of a list.

include(:Goal, +List1, ?List2) [det]

Filter elements for which Goal succeeds. True if List2 contains those elements Xi of List1 for
which call(Goal, Xi) succeeds.

See also Older versions of SWI-Prolog had sublist/3 with the same arguments and semantics.

exclude(:Goal, +List1, ?List2) [det]

Filter elements for which Goal fails. True if List2 contains those elements Xi of List1 for which
call(Goal, Xi) fails.

partition(:Pred, +List, ?Included, ?Excluded) [det]

Filter elements of List according to Pred. True if Included contains all elements for which
call(Pred, X) succeeds and Excluded contains the remaining elements.

partition(:Pred, +List, ?Less, ?Equal, ?Greater) [semidet]

Filter List according to Pred in three sets. For each element Xi of List, its destination is de-
termined by call(Pred, Xi, Place), where Place must be unified to one of <, = or >.
Pred must be deterministic.

maplist(:Goal, ?List)
True if Goal can successfully be applied on all elements of List. Arguments are reordered to
gain performance as well as to make the predicate deterministic under normal circumstances.

maplist(:Goal, ?List1, ?List2)

As maplist/2, operating on pairs of elements from two lists.

maplist(:Goal, ?List1, ?List2, ?List3)

As maplist/2, operating on triples of elements from three lists.

maplist(:Goal, ?List1, ?List2, ?List3, ?List4)

As maplist/2, operating on quadruples of elements from four lists.

SWI-Prolog 7.4 Reference Manual

A.3. LIBRARY(ASSOC): ASSOCIATION LISTS 393

foldl(:Goal, +List, +V0, -V)

foldl(:Goal, +List1, +List2, +V0, -V)
foldl(:Goal, +List1, +List2, +List3, +V0, -V)
foldl(:Goal, +List1, +List2, +List3, +List4, +V0, -V)
Fold a list, using arguments of the list as left argument. The foldl family of predicates is defined
by:

foldl(P, [X11,...,X1n], ..., [Xm1,...,Xmn], V0, Vn) :-

P(X11, ..., Xm1, V0, V1),
...
P(X1n, ..., Xmn, V, Vn).

scanl(:Goal, +List, +V0, -Values)

scanl(:Goal, +List1, +List2, +V0, -Values)
scanl(:Goal, +List1, +List2, +List3, +V0, -Values)
scanl(:Goal, +List1, +List2, +List3, +List4, +V0, -Values)
Left scan of list. The scanl family of higher order list operations is defined by:

scanl(P, [X11,...,X1n], ..., [Xm1,...,Xmn], V0,

[V0,V1,...,Vn]) :-
P(X11, ..., Xm1, V0, V1),
...
P(X1n, ..., Xmn, V, Vn).

A.3 library(assoc): Association lists

Authors: Richard A. OKeefe, L.Damas, V.S.Costa and Markus Triska

A.3.1 Introduction
An association list as implemented by this library is a collection of unique keys that are associated to
values. Keys must be ground, values need not be.
An association list can be used to fetch elements via their keys and to enumerate its elements in
ascending order of their keys.
This library uses AVL trees to implement association lists. This means that

inserting a key
changing an association
fetching a single element

are all O(log(N)) worst-case (and expected) time operations, where N denotes the number of
elements in the association list.
The logarithmic overhead is often acceptable in practice. Notable advantages of association lists
over several other methods are:

SWI-Prolog 7.4 Reference Manual

394 APPENDIX A. THE SWI-PROLOG LIBRARY

library(assoc) is written entirely in Prolog, making it portable to other systems

the interface predicates fit the declarative nature of Prolog, avoiding destructive updates to terms

AVL trees scale very predictably and can be used to represent sparse arrays efficiently.

A.3.2 Creating association lists

An assocation list is created with one of the following predicates:

empty assoc(?Assoc) [semidet]

Is true if Assoc is the empty association list.

list to assoc(+Pairs, -Assoc) [det]

Create an association from a list Pairs of Key-Value pairs. List must not contain duplicate keys.

Errors domain_error(unique_key_pairs, List) if List contains duplicate keys

ord list to assoc(+Pairs, -Assoc) [det]

Assoc is created from an ordered list Pairs of Key-Value pairs. The pairs must occur in strictly
ascending order of their keys.

Errors domain_error(key_ordered_pairs, List) if pairs are not ordered.

A.3.3 Querying association lists

An association list can be queried with:

get assoc(+Key, +Assoc, -Value) [semidet]

True if Key-Value is an association in Assoc.

Errors type_error(assoc, Assoc) if Assoc is not an association list.

get assoc(+Key, +Assoc0, ?Val0, ?Assoc, ?Val) [semidet]

True if Key-Val0 is in Assoc0 and Key-Val is in Assoc.

max assoc(+Assoc, -Key, -Value) [semidet]

True if Key-Value is in Assoc and Key is the largest key.

min assoc(+Assoc, -Key, -Value) [semidet]

True if Key-Value is in assoc and Key is the smallest key.

gen assoc(?Key, +Assoc, ?Value) [nondet]

True if Key-Value is an association in Assoc. Enumerates keys in ascending order on backtrack-
ing.

See also get assoc/3.

SWI-Prolog 7.4 Reference Manual

A.3. LIBRARY(ASSOC): ASSOCIATION LISTS 395

A.3.4 Modifying association lists

Elements of an association list can be changed and inserted with:

put assoc(+Key, +Assoc0, +Value, -Assoc) [det]

Assoc is Assoc0, except that Key is associated with Value. This can be used to insert and change
associations.

del assoc(+Key, +Assoc0, ?Value, -Assoc) [semidet]

True if Key-Value is in Assoc0. Assoc is Assoc0 with Key-Value removed.

del min assoc(+Assoc0, ?Key, ?Val, -Assoc) [semidet]

True if Key-Value is in Assoc0 and Key is the smallest key. Assoc is Assoc0 with Key-Value
removed. Warning: This will succeed with no bindings for Key or Val if Assoc0 is empty.

del max assoc(+Assoc0, ?Key, ?Val, -Assoc) [semidet]

True if Key-Value is in Assoc0 and Key is the greatest key. Assoc is Assoc0 with Key-Value
removed. Warning: This will succeed with no bindings for Key or Val if Assoc0 is empty.

A.3.5 Conversion predicates

Conversion of (parts of) an association list to lists is possible with:

assoc to list(+Assoc, -Pairs) [det]

Translate Assoc to a list Pairs of Key-Value pairs. The keys in Pairs are sorted in ascending
order.

assoc to keys(+Assoc, -Keys) [det]

True if Keys is the list of keys in Assoc. The keys are sorted in ascending order.

assoc to values(+Assoc, -Values) [det]

True if Values is the list of values in Assoc. Values are ordered in ascending order of the key to
which they were associated. Values may contain duplicates.

A.3.6 Reasoning about association lists and their elements

Further inspection predicates of an association list and its elements are:

is assoc(+Assoc) [semidet]
True if Assoc is an association list. This predicate checks that the structure is valid, elements
are in order, and tree is balanced to the extent guaranteed by AVL trees. I.e., branches of each
subtree differ in depth by at most 1.

map assoc(:Pred, +Assoc) [semidet]

True if Pred(Value) is true for all values in Assoc.

map assoc(:Pred, +Assoc0, ?Assoc) [semidet]

Map corresponding values. True if Assoc is Assoc0 with Pred applied to all corresponding
pairs of of values.

SWI-Prolog 7.4 Reference Manual

396 APPENDIX A. THE SWI-PROLOG LIBRARY

Changed-messages

Interface Interface
Ether
component component

Querying listen

Database broadcast
Broadcast
manipulation

assert/retract

Prolog database

Figure A.1: Information-flow using broadcasting service

A.4 library(broadcast): Broadcast and receive event notifications

The broadcast library was invented to realise GUI applications consisting of stand-alone compo-
nents that use the Prolog database for storing the application data. Figure A.1 illustrates the flow of
information using this design
The broadcasting service provides two services. Using the shout service, an unknown number of
agents may listen to the message and act. The broadcaster is not (directly) aware of the implications.
Using the request service, listening agents are asked for an answer one-by-one and the broadcaster
is allowed to reject answers using normal Prolog failure.
Shouting is often used to inform about changes made to a common database. Other messages can
be save yourself or show this.
Requesting is used to get information while the broadcaster is not aware who might be able to
answer the question. For example who is showing X?.
broadcast(+Term)
Broadcast Term. There are no limitations to Term, though being a global service, it is good
practice to use a descriptive and unique principal functor. All associated goals are started and
regardless of their success or failure, broadcast/1 always succeeds. Exceptions are passed.
broadcast request(+Term)
Unlike broadcast/1, this predicate stops if an associated goal succeeds. Backtracking
causes it to try other listeners. A broadcast request is used to fetch information without
knowing the identity of the agent providing it. C.f. Is there someone who knows the age of
John? could be asked using

...,
broadcast_request(age_of(John, Age)),

If there is an agent (listener) that registered an age-of service and knows about the age of
John this question will be answered.

SWI-Prolog 7.4 Reference Manual

A.4. LIBRARY(BROADCAST): BROADCAST AND RECEIVE EVENT NOTIFICATIONS
397

listen(+Template, :Goal)
Register a listen channel. Whenever a term unifying Template is broadcasted, call Goal. The
following example traps all broadcasted messages as a variable unifies to any message. It is
commonly used to debug usage of the library.

?- listen(Term, (writeln(Term),fail)).
?- broadcast(hello(world)).
hello(world)
true.

listen(+Listener, +Template, :Goal)

Declare Listener as the owner of the channel. Unlike a channel opened using listen/2,
channels that have an owner can terminate the channel. This is commonly used if an object is
listening to broadcast messages. In the example below we define a name-item displaying the
name of an identifier represented by the predicate name of/2.

:- pce_begin_class(name_item, text_item).

variable(id, any, get, "Id visualised").

initialise(NI, Id:any) :->

name_of(Id, Name),
send_super(NI, initialise, name, Name,
message(NI, set_name, @arg1)),
send(NI, slot, id, Id),
listen(NI, name_of(Id, Name),
send(NI, selection, Name)).

unlink(NI) :->
unlisten(NI),
send_super(NI, unlink).

set_name(NI, Name:name) :->

get(NI, id, Id),
retractall(name_of(Id, _)),
assert(name_of(Id, Name)),
broadcast(name_of(Id, Name)).

:- pce_end_class.

unlisten(+Listener)
Deregister all entries created with listen/3 whose Listener unify.

unlisten(+Listener, +Template)
Deregister all entries created with listen/3 whose Listener and Template unify.

SWI-Prolog 7.4 Reference Manual

398 APPENDIX A. THE SWI-PROLOG LIBRARY

unlisten(+Listener, +Template, :Goal)

Deregister all entries created with listen/3 whose Listener, Template and Goal unify.

listening(?Listener, ?Template, ?Goal)

Examine the current listeners. This predicate is useful for debugging purposes.

A.5 library(charsio): I/O on Lists of Character Codes

Compatibility The naming of this library is not in line with the ISO standard. We believe that the SWI-
Prolog native predicates form a more elegant alternative for this library.

This module emulates the Quintus/SICStus library charsio.pl for reading and writing from/to
lists of character codes. Most of these predicates are straight calls into similar SWI-Prolog primitives.
Some can even be replaced by ISO standard predicates.

format to chars(+Format, +Args, -Codes) [det]

Use format/2 to write to a list of character codes.

format to chars(+Format, +Args, -Codes, ?Tail) [det]

Use format/2 to write to a difference list of character codes.

write to chars(+Term, -Codes)

Write a term to a code list. True when Codes is a list of character codes written by write/1
on Term.

write to chars(+Term, -Codes, ?Tail)

Write a term to a code list. Codes\Tail is a difference list of character codes produced by
write/1 on Term.

atom to chars(+Atom, -Codes) [det]

Convert Atom into a list of character codes.

deprecated Use ISO atom codes/2.

atom to chars(+Atom, -Codes, ?Tail) [det]

Convert Atom into a difference list of character codes.

number to chars(+Number, -Codes) [det]

Convert Atom into a list of character codes.

deprecated Use ISO number codes/2.

number to chars(+Number, -Codes, ?Tail) [det]

Convert Number into a difference list of character codes.

read from chars(+Codes, -Term) [det]

Read Codes into Term.

Compatibility The SWI-Prolog version does not require Codes to end in a full-stop.

SWI-Prolog 7.4 Reference Manual

A.6. LIBRARY(CHECK): CONSISTENCY CHECKING 399

read term from chars(+Codes, -Term, +Options) [det]

Read Codes into Term. Options are processed by read term/3.

Compatibility sicstus

open chars stream(+Codes, -Stream) [det]

Open Codes as an input stream.

See also open string/2.

with output to chars(:Goal, -Codes) [det]

Run Goal as with once/1. Output written to current_output is collected in Codes.

with output to chars(:Goal, -Codes, ?Tail) [det]

Run Goal as with once/1. Output written to current_output is collected in Codes\Tail.

with output to chars(:Goal, -Stream, -Codes, ?Tail) [det]

Same as with output to chars/3 using an explicit stream. The difference list
Codes\Tail contains the character codes that Goal has written to Stream.

A.6 library(check): Consistency checking

See also
- gxref/0 provides a graphical cross referencer
- PceEmacs performs real time consistency checks while you edit
- library(prolog_xref) implements offline cross-referencing
- library(prolog_codewalk) implements online analysis

This library provides some consistency checks for the loaded Prolog program. The predicate
make/0 runs list undefined/0 to find undefined predicates in user modules.

check [det]
Run all consistency checks defined by checker/2. Checks enabled by default are:

list undefined/0 reports undefined predicates

list trivial fails/0 reports calls for which there is no matching clause.
list redefined/0 reports predicates that have a local definition and a global defini-
tion. Note that these are not errors.
list autoload/0 lists predicates that will be defined at runtime using the autoloader.

list undefined [det]

list undefined(+Options) [det]
Report undefined predicates. This predicate finds undefined predciates by decompiling and
analyzing the body of all clauses. Options:

module class(+Classes)
Process modules of the given Classes. The default for classes is [user]. For example,
to include the libraries into the examination, use [user,library].

SWI-Prolog 7.4 Reference Manual

400 APPENDIX A. THE SWI-PROLOG LIBRARY

See also
- gxref/0 provides a graphical cross-referencer.
- make/0 calls list undefined/0

list autoload [det]

Report predicates that may be auto-loaded. These are predicates that are not defined, but will
be loaded on demand if referenced.

See also autoload/0

To be done This predicate uses an older mechanism for finding undefined predicates. Should be syn-
chronized with list undefined.

list redefined
Lists predicates that are defined in the global module user as well as in a normal module; that
is, predicates for which the local definition overrules the global default definition.

list void declarations [det]

List predicates that have declared attributes, but no clauses.

list trivial fails [det]

list trivial fails(+Options) [det]
List goals that trivially fail because there is no matching clause. Options:

module class(+Classes)
Process modules of the given Classes. The default for classes is [user]. For example,
to include the libraries into the examination, use [user,library].

trivial fail goal(:Goal) [multifile]

Multifile hook that tells list trivial fails/0 to accept Goal as valid.

list strings [det]

list strings(+Options) [det]
List strings that appear in clauses. This predicate is used to find portability issues for changing
the Prolog flag double_quotes from codes to string, creating packed string objects.
Warnings may be suppressed using the following multifile hooks:

string predicate/1 to stop checking certain predicates

valid string goal/1 to tell the checker that a goal is safe.

See also Prolog flag double_quotes.

string predicate(:PredicateIndicator) [multifile]

Multifile hook to disable list strings/0 on the given predicate. This is typically used for
facts that store strings.

valid string goal(+Goal) [semidet,multifile]

Multifile hook that qualifies Goal as valid for list strings/0. For example,
format("Hello worldn") is considered proper use of string constants.

SWI-Prolog 7.4 Reference Manual

A.7. LIBRARY(CLPB): CLP(B): CONSTRAINT LOGIC PROGRAMMING OVER
BOOLEAN VARIABLES 401

checker(:Goal, +Message:text) [multifile]

Register code validation routines. Each clause defines a Goal which performs a consistency
check executed by check/0. Message is a short description of the check. For example,
assuming the my_checks module defines a predicate list format mistakes/0:

:- multifile check:checker/2.
check:checker(my_checks:list_format_mistakes,
"errors with format/2 arguments").

The predicate is dynamic, so you can disable checks with retract/1. For example, to stop
reporting redefined predicates:

retract(check:checker(list_redefined,_)).

A.7 library(clpb): CLP(B): Constraint Logic Programming over

Boolean Variables
author Markus Triska

A.7.1 Introduction
This library provides CLP(B), Constraint Logic Programming over Boolean variables. It can be used
to model and solve combinatorial problems such as verification, allocation and covering tasks.
CLP(B) is an instance of the general CLP(X) scheme (section 7), extending logic programming
with reasoning over specialised domains.
The implementation is based on reduced and ordered Binary Decision Diagrams (BDDs).
Usage examples of this library are available in a public git repository: github.com/triska/clpb
We recommend the following reference (PDF: metalevel.at/swiclpb.pdf) for citing this library in
scientific publications:

@inproceedings{Triska2016,
author = "Markus Triska",
title = "The {Boolean} Constraint Solver of {SWI-Prolog}:
System Description",
booktitle = "FLOPS",
series = "LNCS",
volume = 9613,
year = 2016,
pages = "45--61"
}

A.7.2 Boolean expressions

A Boolean expression is one of:

SWI-Prolog 7.4 Reference Manual

402 APPENDIX A. THE SWI-PROLOG LIBRARY

0 false
1 true
variable unknown truth value
atom universally quantified variable
Expr logical NOT
Expr + Expr logical OR
Expr * Expr logical AND
Expr # Expr exclusive OR
Var Expr existential quantification
Expr =:= Expr equality
Expr =\= Expr disequality (same as #)
Expr =< Expr less or equal (implication)
Expr >= Expr greater or equal
Expr < Expr less than
Expr > Expr greater than
card(Is,Exprs) see below
+(Exprs) see below
*(Exprs) see below

where Expr again denotes a Boolean expression.

The Boolean expression card(Is,Exprs) is true iff the number of true expressions in the list
Exprs is a member of the list Is of integers and integer ranges of the form From-To.
+(Exprs) and *(Exprs) denote, respectively, the disjunction and conjunction of all elements
in the list Exprs of Boolean expressions.
Atoms denote parametric values that are universally quantified. All universal quantifiers appear
implicitly in front of the entire expression. In residual goals, universally quantified variables always
appear on the right-hand side of equations. Therefore, they can be used to express functional depen-
dencies on input variables.

A.7.3 Interface predicates

The most frequently used CLP(B) predicates are:

sat(+Expr)
True iff the Boolean expression Expr is satisfiable.

taut(+Expr, -T)
If Expr is a tautology with respect to the posted constraints, succeeds with T = 1. If Expr cannot
be satisfied, succeeds with T = 0. Otherwise, it fails.

labeling(+Vs)
Assigns truth values to the variables Vs such that all constraints are satisfied.

The unification of a CLP(B) variable X with a term T is equivalent to posting the constraint
sat(X=:=T).

A.7.4 Examples
Here is an example session with a few queries and their answers:

SWI-Prolog 7.4 Reference Manual

A.7. LIBRARY(CLPB): CLP(B): CONSTRAINT LOGIC PROGRAMMING OVER
BOOLEAN VARIABLES 403

?- use_module(library(clpb)).
true.

?- sat(X*Y).
X = Y, Y = 1.

?- sat(X * X).
false.

?- taut(X * X, T).
T = 0,
sat(X=:=X).

?- sat(XY(X+Y)).
sat(X=:=X),
sat(Y=:=Y).

?- sat(X*Y + X*Z), labeling([X,Y,Z]).

X = Z, Z = 1, Y = 0 ;
X = Y, Y = 1, Z = 0 ;
X = Y, Y = Z, Z = 1.

?- sat(X =< Y), sat(Y =< Z), taut(X =< Z, T).

T = 1,
sat(X=:=X*Y),
sat(Y=:=Y*Z).

?- sat(1#X#a#b).
sat(X=:=a#b).

The pending residual goals constrain remaining variables to Boolean expressions and are declar-
atively equivalent to the original query. The last example illustrates that when applicable, remaining
variables are expressed as functions of universally quantified variables.

A.7.5 Obtaining BDDs

By default, CLP(B) residual goals appear in (approximately) algebraic normal form (ANF). This
projection is often computationally expensive. We can set the Prolog flag clpb_residuals to the
value bdd to see the BDD representation of all constraints. This results in faster projection to residual
goals, and is also useful for learning more about BDDs. For example:

?- set_prolog_flag(clpb_residuals, bdd).
true.

?- sat(X#Y).
node(3)- (v(X, 0)->node(2);node(1)),

SWI-Prolog 7.4 Reference Manual

404 APPENDIX A. THE SWI-PROLOG LIBRARY

node(1)- (v(Y, 1)->true;false),

node(2)- (v(Y, 1)->false;true).

Note that this representation cannot be pasted back on the toplevel, and its details are subject to
change. Use copy term/3 to obtain such answers as Prolog terms.
The variable order of the BDD is determined by the order in which the variables first appear in
constraints. To obtain different orders, we can for example use:

?- sat(+[1,Y,X]), sat(X#Y).
node(3)- (v(Y, 0)->node(2);node(1)),
node(1)- (v(X, 1)->true;false),
node(2)- (v(X, 1)->false;true).

A.7.6 Enabling monotonic CLP(B)

In the default execution mode, CLP(B) constraints are not monotonic. This means that adding con-
straints can yield new solutions. For example:

?- sat(X=:=1), X = 1+0.
false.

?- X = 1+0, sat(X=:=1), X = 1+0.

X = 1+0.

This behaviour is highly problematic from a logical point of view, and it may render declarative
debugging techniques inapplicable.
Set the flag clpb_monotonic to true to make CLP(B) monotonic. If this mode is enabled,
then you must wrap CLP(B) variables with the functor v/1. For example:

?- set_prolog_flag(clpb_monotonic, true).
true.

?- sat(v(X)=:=1#1).
X = 0.

A.7.7 Example: Pigeons

In this example, we are attempting to place I pigeons into J holes in such a way that each hole contains
at most one pigeon. One interesting property of this task is that it can be formulated using only
cardinality constraints (card/2). Another interesting aspect is that this task has no short resolution
refutations in general.
In the following, we use Prolog DCG notation to describe a list Cs of CLP(B) constraints that
must all be satisfied.

:- use_module(library(clpb)).
:- use_module(library(clpfd)).

SWI-Prolog 7.4 Reference Manual

A.7. LIBRARY(CLPB): CLP(B): CONSTRAINT LOGIC PROGRAMMING OVER
BOOLEAN VARIABLES 405

pigeon(I, J, Rows, Cs) :-

length(Rows, I), length(Row, J),
maplist(same_length(Row), Rows),
transpose(Rows, TRows),
phrase((all_card1(Rows),all_max1(TRows)), Cs).

all_card1([]) --> [].

all_card1([Ls|Lss]) --> [card([1],Ls)], all_card1(Lss).

all_max1([]) --> [].

all_max1([Ls|Lss]) --> [card([0,1],Ls)], all_max1(Lss).

Example queries:

?- pigeon(9, 8, Rows, Cs), sat(*(Cs)).

false.

?- pigeon(2, 3, Rows, Cs), sat(*(Cs)),

append(Rows, Vs), labeling(Vs),
maplist(writeln, Rows).
[0,0,1]
[0,1,0]

A.7.8 Example: Boolean circuit

Consider a Boolean circuit that express the Boolean function XOR with 4 NAND gates. We can model
such a circuit with CLP(B) constraints as follows:

:- use_module(library(clpb)).

nand_gate(X, Y, Z) :- sat(Z =:= (X*Y)).

xor(X, Y, Z) :-
nand_gate(X, Y, T1),
nand_gate(X, T1, T2),
nand_gate(Y, T1, T3),
nand_gate(T2, T3, Z).

Using universally quantified variables, we can show that the circuit does compute XOR as intended:

?- xor(x, y, Z).
sat(Z=:=x#y).

SWI-Prolog 7.4 Reference Manual

406 APPENDIX A. THE SWI-PROLOG LIBRARY

A.7.9 Acknowledgments
The interface predicates of this library follow the example of SICStus Prolog.
Use SICStus Prolog for higher performance in many cases.

A.7.10 CLP(B) predicate index

In the following, each CLP(B) predicate is described in more detail.
We recommend the following link to refer to this manual:
http://eu.swi-prolog.org/man/clpb.html

sat(+Expr) [semidet]
True iff Expr is a satisfiable Boolean expression.

taut(+Expr, -T) [semidet]

Tautology check. Succeeds with T = 0 if the Boolean expression Expr cannot be satisfied, and
with T = 1 if Expr is always true with respect to the current constraints. Fails otherwise.

labeling(+Vs) [multi]
Enumerate concrete solutions. Assigns truth values to the Boolean variables Vs such that all
stated constraints are satisfied.

sat count(+Expr, -Count) [det]

Count the number of admissible assignments. Count is the number of different assignments
of truth values to the variables in the Boolean expression Expr, such that Expr is true and all
posted constraints are satisfiable.
A common form of invocation is sat_count(+[1|Vs], Count): This counts the number
of admissible assignments to Vs without imposing any further constraints.
Examples:

?- sat(A =< B), Vs = [A,B], sat_count(+[1|Vs], Count).

Vs = [A, B],
Count = 3,
sat(A=:=A*B).

?- length(Vs, 120),
sat_count(+Vs, CountOr),
sat_count(*(Vs), CountAnd).
Vs = [...],
CountOr = 1329227995784915872903807060280344575,
CountAnd = 1.

weighted maximum(+Weights, +Vs, -Maximum) [multi]

Enumerate weighted optima over admissible assignments. Maximize a linear objective function
over Boolean variables Vs with integer coefficients Weights. This predicate assigns 0 and 1 to
the variables in Vs such that all stated constraints are satisfied, and Maximum is the maximum
of sum(Weight_i*V_i) over all admissible assignments. On backtracking, all admissible
assignments that attain the optimum are generated.

SWI-Prolog 7.4 Reference Manual

A.8. LIBRARY(CLPFD): CLP(FD): CONSTRAINT LOGIC PROGRAMMING OVER
FINITE DOMAINS 407

This predicate can also be used to minimize a linear Boolean program, since negative integers
can appear in Weights.
Example:

?- sat(A#B), weighted_maximum([1,2,1], [A,B,C], Maximum).

A = 0, B = 1, C = 1, Maximum = 3.

random labeling(+Seed, +Vs) [det]

Select a single random solution. An admissible assignment of truth values to the Boolean
variables in Vs is chosen in such a way that each admissible assignment is equally likely. Seed
is an integer, used as the initial seed for the random number generator.

A.8 library(clpfd): CLP(FD): Constraint Logic Programming over Fi-

nite Domains
author Markus Triska

Development of this library has moved to SICStus Prolog.

Please see CLP(Z) for more information.

A.8.1 Introduction
This library provides CLP(FD): Constraint Logic Programming over Finite Domains. This is an
instance of the general CLP(X) scheme (section 7), extending logic programming with reasoning
over specialised domains.
CLP(FD) lets us reason about integers in a way that honors the relational nature of Prolog. An
introduction is available from metalevel.at/prolog/clpfd.
There are two major use cases of CLP(FD) constraints:

1. declarative integer arithmetic (section A.8.3)

2. solving combinatorial problems such as planning, scheduling and allocation tasks.

The predicates of this library can be classified as:

arithmetic constraints like #=/2, #>/2 and #\=/2 (section A.8.17)

the membership constraints in/2 and ins/2 (section A.8.17)

the enumeration predicates indomain/1, label/1 and labeling/2 (section A.8.17)

combinatorial constraints like all distinct/1 and global cardinality/2 (sec-

tion A.8.17)

reification predicates such as #<==>/2 (section A.8.17)

reflection predicates such as fd dom/2 (section A.8.17)

SWI-Prolog 7.4 Reference Manual

408 APPENDIX A. THE SWI-PROLOG LIBRARY

In most cases, arithmetic constraints (section A.8.2) are the only predicates you will ever need
from this library. When reasoning over integers, simply replace low-level arithmetic predicates like
(is)/2 and (>)/2 by the corresponding CLP(FD) constraints like #=/2 and #>/2 to honor and
preserve declarative properties of your programs. For satisfactory performance, arithmetic constraints
are implicitly rewritten at compilation time so that low-level fallback predicates are automatically
used whenever possible.
Almost all Prolog programs also reason about integers. Therefore, it is highly advisable that you
make CLP(FD) constraints available in all your programs. One way to do this is to put the following
directive in your /.swiplrc initialisation file:

:- use_module(library(clpfd)).

All example programs that appear in the CLP(FD) documentation assume that you have done this.
Important concepts and principles of this library are illustrated by means of usage examples that
are available in a public git repository: github.com/triska/clpfd
If you are used to the complicated operational considerations that low-level arithmetic primitives
necessitate, then moving to CLP(FD) constraints may, due to their power and convenience, at first
feel to you excessive and almost like cheating. It isnt. Constraints are an integral part of all popular
Prolog systems, and they are designed to help you eliminate and avoid the use of low-level and less
general primitives by providing declarative alternatives that are meant to be used instead.
When teaching Prolog, CLP(FD) constraints should be introduced before explaining low-level
arithmetic predicates and their procedural idiosyncrasies. This is because constraints are easy to
explain, understand and use due to their purely relational nature. In contrast, the modedness and
directionality of low-level arithmetic primitives are impure limitations that are better deferred to more
advanced lectures.
We recommend the following reference (PDF: metalevel.at/swiclpfd.pdf) for citing this library in
scientific publications:

@inproceedings{Triska12,
author = {Markus Triska},
title = {The Finite Domain Constraint Solver of {SWI-Prolog}},
booktitle = {FLOPS},
series = {LNCS},
volume = {7294},
year = {2012},
pages = {307-316}
}

More information about CLP(FD) constraints and their implementation is contained in: met-
alevel.at/drt.pdf
The best way to discuss applying, improving and extending CLP(FD) constraints is to use the ded-
icated clpfd tag on stackoverflow.com. Several of the worlds foremost CLP(FD) experts regularly
participate in these discussions and will help you for free on this platform.

A.8.2 Arithmetic constraints

In modern Prolog systems, arithmetic constraints subsume and supersede low-level predicates over
integers. The main advantage of arithmetic constraints is that they are true relations and can be used

SWI-Prolog 7.4 Reference Manual

A.8. LIBRARY(CLPFD): CLP(FD): CONSTRAINT LOGIC PROGRAMMING OVER
FINITE DOMAINS 409

in all directions. For most programs, arithmetic constraints are the only predicates you will ever need
from this library.
The most important arithmetic constraint is #=/2, which subsumes both (is)/2 and (=:=)/2
over integers. Use #=/2 to make your programs more general.
In total, the arithmetic constraints are:

Expr1 #= Expr2 Expr1 equals Expr2

Expr1 #\= Expr2 Expr1 is not equal to Expr2
Expr1 #>= Expr2 Expr1 is greater than or equal to Expr2
Expr1 #=< Expr2 Expr1 is less than or equal to Expr2
Expr1 #> Expr2 Expr1 is greater than Expr2
Expr1 #< Expr2 Expr1 is less than Expr2

Expr1 and Expr2 denote arithmetic expressions, which are:

integer Given value

variable Unknown integer
?(variable) Unknown integer
-Expr Unary minus
Expr + Expr Addition
Expr * Expr Multiplication
Expr - Expr Subtraction
Expr Expr Exponentiation
min(Expr,Expr) Minimum of two expressions
max(Expr,Expr) Maximum of two expressions
Expr mod Expr Modulo induced by floored division
Expr rem Expr Modulo induced by truncated division
abs(Expr) Absolute value
Expr // Expr Truncated integer division
Expr div Expr Floored integer division

where Expr again denotes an arithmetic expression.

The bitwise operations (\)/1, (/\)/2, (\/)/2, (>>)/2, (<<)/2, lsb/1, msb/1,
popcount/1 and (xor)/2 are also supported.

A.8.3 Declarative integer arithmetic

The arithmetic constraints (section A.8.2) #=/2, #>/2 etc. are meant to be used instead of the prim-
itives (is)/2, (=:=)/2, (>)/2 etc. over integers. Almost all Prolog programs also reason about
integers. Therefore, it is recommended that you put the following directive in your /.swiplrc
initialisation file to make CLP(FD) constraints available in all your programs:

:- use_module(library(clpfd)).

Throughout the following, it is assumed that you have done this.

The most basic use of CLP(FD) constraints is evaluation of arithmetic expressions involving in-
tegers. For example:

SWI-Prolog 7.4 Reference Manual

410 APPENDIX A. THE SWI-PROLOG LIBRARY

?- X #= 1+2.
X = 3.

This could in principle also be achieved with the lower-level predicate (is)/2. However, an
important advantage of arithmetic constraints is their purely relational nature: Constraints can be used
in all directions, also if one or more of their arguments are only partially instantiated. For example:

?- 3 #= Y+2.
Y = 1.

This relational nature makes CLP(FD) constraints easy to explain and use, and well suited for
beginners and experienced Prolog programmers alike. In contrast, when using low-level integer arith-
metic, we get:

?- 3 is Y+2.
ERROR: is/2: Arguments are not sufficiently instantiated

?- 3 =:= Y+2.
ERROR: =:=/2: Arguments are not sufficiently instantiated

Due to the necessary operational considerations, the use of these low-level arithmetic predicates
is considerably harder to understand and should therefore be deferred to more advanced lectures.
For supported expressions, CLP(FD) constraints are drop-in replacements of these low-level arith-
metic predicates, often yielding more general programs. See n_factorial/2 (section A.8.4) for
an example.
This library uses goal expansion/2 to automatically rewrite constraints at compilation time
so that low-level arithmetic predicates are automatically used whenever possible. For example, the
predicate:

positive_integer(N) :- N #>= 1.

is executed as if it were written as:

positive_integer(N) :-
( integer(N)
-> N >= 1
; N #>= 1
).

This illustrates why the performance of CLP(FD) constraints is almost always completely sat-
isfactory when they are used in modes that can be handled by low-level arithmetic. To disable the
automatic rewriting, set the Prolog flag clpfd_goal_expansion to false.
If you are used to the complicated operational considerations that low-level arithmetic primitives
necessitate, then moving to CLP(FD) constraints may, due to their power and convenience, at first
feel to you excessive and almost like cheating. It isnt. Constraints are an integral part of all popular
Prolog systems, and they are designed to help you eliminate and avoid the use of low-level and less
general primitives by providing declarative alternatives that are meant to be used instead.

SWI-Prolog 7.4 Reference Manual

A.8. LIBRARY(CLPFD): CLP(FD): CONSTRAINT LOGIC PROGRAMMING OVER
FINITE DOMAINS 411

A.8.4 Example: Factorial relation

We illustrate the benefit of using #=/2 for more generality with a simple example.
Consider first a rather conventional definition of n_factorial/2, relating each natural number
N to its factorial F:

n_factorial(0, 1).
n_factorial(N, F) :-
N #> 0,
N1 #= N - 1,
n_factorial(N1, F1),
F #= N * F1.

This program uses CLP(FD) constraints instead of low-level arithmetic throughout, and every-
thing that would have worked with low-level arithmetic also works with CLP(FD) constraints, retain-
ing roughly the same performance. For example:

?- n_factorial(47, F).
F = 258623241511168180642964355153611979969197632389120000000000 ;
false.

Now the point: Due to the increased flexibility and generality of CLP(FD) constraints, we are free
to reorder the goals as follows:

n_factorial(0, 1).
n_factorial(N, F) :-
N #> 0,
N1 #= N - 1,
F #= N * F1,
n_factorial(N1, F1).

In this concrete case, termination properties of the predicate are improved. For example, the
following queries now both terminate:

?- n_factorial(N, 1).
N = 0 ;
N = 1 ;
false.

?- n_factorial(N, 3).
false.

To make the predicate terminate if any argument is instantiated, add the (implied) constraint
F #\= 0 before the recursive call. Otherwise, the query n_factorial(N, 0) is the only non-
terminating case of this kind.
The value of CLP(FD) constraints does not lie in completely freeing us from all procedural phe-
nomena. For example, the two programs do not even have the same termination properties in all cases.

SWI-Prolog 7.4 Reference Manual

412 APPENDIX A. THE SWI-PROLOG LIBRARY

Instead, the primary benefit of CLP(FD) constraints is that they allow you to try different execution
orders and apply declarative debugging techniques at all! Reordering goals (and clauses) can sig-
nificantly impact the performance of Prolog programs, and you are free to try different variants if you
use declarative approaches. Moreover, since all CLP(FD) constraints always terminate, placing them
earlier can at most improve, never worsen, the termination properties of your programs. An additional
benefit of CLP(FD) constraints is that they eliminate the complexity of introducing (is)/2 and
(=:=)/2 to beginners, since both predicates are subsumed by #=/2 when reasoning over integers.

A.8.5 Combinatorial constraints

In addition to subsuming and replacing low-level arithmetic predicates, CLP(FD) constraints
are often used to solve combinatorial problems such as planning, scheduling and allocation
tasks. Among the most frequently used combinatorial constraints are all distinct/1,
global cardinality/2 and cumulative/2. This library also provides several other con-
straints like disjoint2/1 and automaton/8, which are useful in more specialized applications.

A.8.6 Domains
Each CLP(FD) variable has an associated set of admissible integers, which we call the variables
domain. Initially, the domain of each CLP(FD) variable is the set of all integers. CLP(FD) constraints
like #=/2, #>/2 and #\=/2 can at most reduce, and never extend, the domains of their arguments.
The constraints in/2 and ins/2 let us explicitly state domains of CLP(FD) variables. The process of
determining and adjusting domains of variables is called constraint propagation, and it is performed
automatically by this library. When the domain of a variable contains only one element, then the
variable is automatically unified to that element.
Domains are taken into account when further constraints are stated, and by enumeration predicates
like labeling/2.

A.8.7 Example: Sudoku

As another example, consider Sudoku: It is a popular puzzle over integers that can be easily solved
with CLP(FD) constraints.

sudoku(Rows) :-
length(Rows, 9), maplist(same_length(Rows), Rows),
append(Rows, Vs), Vs ins 1..9,
maplist(all_distinct, Rows),
transpose(Rows, Columns),
maplist(all_distinct, Columns),
Rows = [As,Bs,Cs,Ds,Es,Fs,Gs,Hs,Is],
blocks(As, Bs, Cs),
blocks(Ds, Es, Fs),
blocks(Gs, Hs, Is).

blocks([], [], []).

blocks([N1,N2,N3|Ns1], [N4,N5,N6|Ns2], [N7,N8,N9|Ns3]) :-
all_distinct([N1,N2,N3,N4,N5,N6,N7,N8,N9]),
blocks(Ns1, Ns2, Ns3).

SWI-Prolog 7.4 Reference Manual

A.8. LIBRARY(CLPFD): CLP(FD): CONSTRAINT LOGIC PROGRAMMING OVER
FINITE DOMAINS 413

problem(1, [[_,_,_,_,_,_,_,_,_],
[_,_,_,_,_,3,_,8,5],
[_,_,1,_,2,_,_,_,_],
[_,_,_,5,_,7,_,_,_],
[_,_,4,_,_,_,1,_,_],
[_,9,_,_,_,_,_,_,_],
[5,_,_,_,_,_,_,7,3],
[_,_,2,_,1,_,_,_,_],
[_,_,_,_,4,_,_,_,9]]).

Sample query:

?- problem(1, Rows), sudoku(Rows), maplist(writeln, Rows).

[9,8,7,6,5,4,3,2,1]
[2,4,6,1,7,3,9,8,5]
[3,5,1,9,2,8,7,4,6]
[1,2,8,5,3,7,6,9,4]
[6,3,4,8,9,2,1,5,7]
[7,9,5,4,6,1,8,3,2]
[5,1,9,2,8,6,4,7,3]
[4,7,2,3,1,9,5,6,8]
[8,6,3,7,4,5,2,1,9]
Rows = [[9, 8, 7, 6, 5, 4, 3, 2|...], ... , [...|...]].

In this concrete case, the constraint solver is strong enough to find the unique solution without any
search.

A.8.8 Residual goals

Here is an example session with a few queries and their answers:

?- X #> 3.
X in 4..sup.

?- X #\= 20.
X in inf..19\/21..sup.

?- 2*X #= 10.
X = 5.

?- X*X #= 144.
X in -12\/12.

?- 4*X + 2*Y #= 24, X + Y #= 9, [X,Y] ins 0..sup.

X = 3,

SWI-Prolog 7.4 Reference Manual

414 APPENDIX A. THE SWI-PROLOG LIBRARY

Y = 6.

?- X #= Y #<==> B, X in 0..3, Y in 4..5.

B = 0,
X in 0..3,
Y in 4..5.

The answers emitted by the toplevel are called residual programs, and the goals that comprise
each answer are called residual goals. In each case above, and as for all pure programs, the residual
program is declaratively equivalent to the original query. From the residual goals, it is clear that the
constraint solver has deduced additional domain restrictions in many cases.
To inspect residual goals, it is best to let the toplevel display them for us. Wrap the call of your
predicate into call residue vars/2 to make sure that all constrained variables are displayed. To
make the constraints a variable is involved in available as a Prolog term for further reasoning within
your program, use copy term/3. For example:

?- X #= Y + Z, X in 0..5, copy_term([X,Y,Z], [X,Y,Z], Gs).

Gs = [clpfd: (X in 0..5), clpfd: (Y+Z#=X)],
X in 0..5,
Y+Z#=X.

This library also provides reflection predicates (like fd dom/2, fd size/2 etc.) with which
we can inspect a variables current domain. These predicates can be useful if you want to implement
your own labeling strategies.

A.8.9 Core relations and search

Using CLP(FD) constraints to solve combinatorial tasks typically consists of two phases:

1. First, all relevant constraints are stated.

2. Second, if the domain of each involved variable is finite, then enumeration predicates can be
used to search for concrete solutions.

It is good practice to keep the modeling part, via a dedicated predicate called the core relation,
separate from the actual search for solutions. This lets us observe termination and determinism prop-
erties of the core relation in isolation from the search, and more easily try different search strategies.
As an example of a constraint satisfaction problem, consider the cryptoarithmetic puzzle SEND +
MORE = MONEY, where different letters denote distinct integers between 0 and 9. It can be modeled
in CLP(FD) as follows:

puzzle([S,E,N,D] + [M,O,R,E] = [M,O,N,E,Y]) :-

Vars = [S,E,N,D,M,O,R,Y],
Vars ins 0..9,
all_different(Vars),
S*1000 + E*100 + N*10 + D +
M*1000 + O*100 + R*10 + E #=

SWI-Prolog 7.4 Reference Manual

A.8. LIBRARY(CLPFD): CLP(FD): CONSTRAINT LOGIC PROGRAMMING OVER
FINITE DOMAINS 415

M*10000 + O*1000 + N*100 + E*10 + Y,

M #\= 0, S #\= 0.

Notice that we are not using labeling/2 in this predicate, so that we can first execute and
observe the modeling part in isolation. Sample query and its result (actual variables replaced for
readability):

?- puzzle(As+Bs=Cs).
As = [9, A2, A3, A4],
Bs = [1, 0, B3, A2],
Cs = [1, 0, A3, A2, C5],
A2 in 4..7,
all_different([9, A2, A3, A4, 1, 0, B3, C5]),
91*A2+A4+10*B3#=90*A3+C5,
A3 in 5..8,
A4 in 2..8,
B3 in 2..8,
C5 in 2..8.

From this answer, we see that this core relation terminates and is in fact deterministic. Moreover,
we see from the residual goals that the constraint solver has deduced more stringent bounds for all
variables. Such observations are only possible if modeling and search parts are cleanly separated.
Labeling can then be used to search for solutions in a separate predicate or goal:

?- puzzle(As+Bs=Cs), label(As).
As = [9, 5, 6, 7],
Bs = [1, 0, 8, 5],
Cs = [1, 0, 6, 5, 2] ;
false.

In this case, it suffices to label a subset of variables to find the puzzles unique solution, since the
constraint solver is strong enough to reduce the domains of remaining variables to singleton sets. In
general though, it is necessary to label all variables to obtain ground solutions.

A.8.10 Example: Eight queens puzzle

We illustrate the concepts of the preceding sections by means of the so-called eight queens puzzle.
The task is to place 8 queens on an 8x8 chessboard such that none of the queens is under attack. This
means that no two queens share the same row, column or diagonal.
To express this puzzle via CLP(FD) constraints, we must first pick a suitable representation. Since
CLP(FD) constraints reason over integers, we must find a way to map the positions of queens to
integers. Several such mappings are conceivable, and it is not immediately obvious which we should
use. On top of that, different constraints can be used to express the desired relations. For such reasons,
modeling combinatorial problems via CLP(FD) constraints often necessitates some creativity and has
been described as more of an art than a science.

SWI-Prolog 7.4 Reference Manual

416 APPENDIX A. THE SWI-PROLOG LIBRARY

In our concrete case, we observe that there must be exactly one queen per column. The following
representation therefore suggests itself: We are looking for 8 integers, one for each column, where
each integer denotes the row of the queen that is placed in the respective column, and which are subject
to certain constraints.
In fact, let us now generalize the task to the so-called N queens puzzle, which is obtained by re-
placing 8 by N everywhere it occurs in the above description. We implement the above considerations
in the core relation n_queens/2, where the first argument is the number of queens (which is iden-
tical to the number of rows and columns of the generalized chessboard), and the second argument is a
list of N integers that represents a solution in the form described above.

n_queens(N, Qs) :-
length(Qs, N),
Qs ins 1..N,
safe_queens(Qs).

safe_queens([]).
safe_queens([Q|Qs]) :- safe_queens(Qs, Q, 1), safe_queens(Qs).

safe_queens([], _, _).
safe_queens([Q|Qs], Q0, D0) :-
Q0 #\= Q,
abs(Q0 - Q) #\= D0,
D1 #= D0 + 1,
safe_queens(Qs, Q0, D1).

Note that all these predicates can be used in all directions: We can use them to find solutions, test
solutions and complete partially instantiated solutions.
The original task can be readily solved with the following query:

?- n_queens(8, Qs), label(Qs).

Qs = [1, 5, 8, 6, 3, 7, 2, 4] .

Using suitable labeling strategies, we can easily find solutions with 80 queens and more:

?- n_queens(80, Qs), labeling([ff], Qs).

Qs = [1, 3, 5, 44, 42, 4, 50, 7, 68|...] .

?- time((n_queens(90, Qs), labeling([ff], Qs))).

% 5,904,401 inferences, 0.722 CPU in 0.737 seconds (98% CPU)
Qs = [1, 3, 5, 50, 42, 4, 49, 7, 59|...] .

Experimenting with different search strategies is easy because we have separated the core relation
from the actual search.

SWI-Prolog 7.4 Reference Manual

A.8. LIBRARY(CLPFD): CLP(FD): CONSTRAINT LOGIC PROGRAMMING OVER
FINITE DOMAINS 417

A.8.11 Optimisation
We can use labeling/2 to minimize or maximize the value of a CLP(FD) expression, and generate
solutions in increasing or decreasing order of the value. See the labeling options min(Expr) and
max(Expr), respectively.
Again, to easily try different labeling options in connection with optimisation, we recommend to
introduce a dedicated predicate for posting constraints, and to use labeling/2 in a separate goal.
This way, we can observe properties of the core relation in isolation, and try different labeling options
without recompiling our code.
If necessary, we can use once/1 to commit to the first optimal solution. However, it is often
very valuable to see alternative solutions that are also optimal, so that we can choose among optimal
solutions by other criteria. For the sake of purity and completeness, we recommend to avoid once/1
and other constructs that lead to impurities in CLP(FD) programs.
Related to optimisation with CLP(FD) constraints are library(simplex) and CLP(Q) which
reason about linear constraints over rational numbers.

A.8.12 Reification
The constraints in/2, #=/2, #\=/2, #</2, #>/2, #=</2, and #>=/2 can be reified, which
means reflecting their truth values into Boolean values represented by the integers 0 and 1. Let P and
Q denote reifiable constraints or Boolean variables, then:

#\ Q True iff Q is false

P #\/ Q True iff either P or Q
P #/\ Q True iff both P and Q
P #\ Q True iff either P or Q, but not both
P #<==> Q True iff P and Q are equivalent
P #==> Q True iff P implies Q
P #<== Q True iff Q implies P

The constraints of this table are reifiable as well.

When reasoning over Boolean variables, also consider using CLP(B) constraints as provided by
library(clpb).

A.8.13 Enabling monotonic CLP(FD)

In the default execution mode, CLP(FD) constraints still exhibit some non-relational properties. For
example, adding constraints can yield new solutions:

?- X #= 2, X = 1+1.
false.

?- X = 1+1, X #= 2, X = 1+1.
X = 1+1.

This behaviour is highly problematic from a logical point of view, and it may render declarative
debugging techniques inapplicable.

SWI-Prolog 7.4 Reference Manual

418 APPENDIX A. THE SWI-PROLOG LIBRARY

Set the Prolog flag clpfd_monotonic to true to make CLP(FD) monotonic: This means that
adding new constraints cannot yield new solutions. When this flag is true, we must wrap variables
that occur in arithmetic expressions with the functor (?)/1 or (#)/1. For example:

?- set_prolog_flag(clpfd_monotonic, true).
true.

?- #(X) #= #(Y) + #(Z).

#(Y)+ #(Z)#= #(X).

?- X #= 2, X = 1+1.
ERROR: Arguments are not sufficiently instantiated

The wrapper can be omitted for variables that are already constrained to integers.

A.8.14 Custom constraints

We can define custom constraints. The mechanism to do this is not yet finalised, and we welcome
suggestions and descriptions of use cases that are important to you.
As an example of how it can be done currently, let us define a new custom constraint
oneground(X,Y,Z), where Z shall be 1 if at least one of X and Y is instantiated:

:- multifile clpfd:run_propagator/2.

oneground(X, Y, Z) :-
clpfd:make_propagator(oneground(X, Y, Z), Prop),
clpfd:init_propagator(X, Prop),
clpfd:init_propagator(Y, Prop),
clpfd:trigger_once(Prop).

clpfd:run_propagator(oneground(X, Y, Z), MState) :-

( integer(X) -> clpfd:kill(MState), Z = 1
; integer(Y) -> clpfd:kill(MState), Z = 1
; true
).

First, clpfd:make propagator/2 is used to transform a user-defined representation of the

new constraint to an internal form. With clpfd:init propagator/2, this internal form is
then attached to X and Y. From now on, the propagator will be invoked whenever the domains
of X or Y are changed. Then, clpfd:trigger once/1 is used to give the propagator its
first chance for propagation even though the variables domains have not yet changed. Finally,
clpfd:run propagator/2 is extended to define the actual propagator. As explained, this pred-
icate is automatically called by the constraint solver. The first argument is the user-defined represen-
tation of the constraint as used in clpfd:make propagator/2, and the second argument is a
mutable state that can be used to prevent further invocations of the propagator when the constraint has
become entailed, by using clpfd:kill/1. An example of using the new constraint:

SWI-Prolog 7.4 Reference Manual

A.8. LIBRARY(CLPFD): CLP(FD): CONSTRAINT LOGIC PROGRAMMING OVER
FINITE DOMAINS 419

?- oneground(X, Y, Z), Y = 5.
Y = 5,
Z = 1,
X in inf..sup.

A.8.15 Applications
CLP(FD) applications that we find particularly impressive and worth studying include:

Michael Hendricks uses CLP(FD) constraints for flexible reasoning about dates and times in
the julian package.

Julien Cumin uses CLP(FD) constraints for integer arithmetic in Brachylog.

A.8.16 Acknowledgments
This library gives you a glimpse of what SICStus Prolog can do. The API is intentionally mostly
compatible with that of SICStus Prolog, so that you can easily switch to a much more feature-rich
and much faster CLP(FD) system when you need it. I thank Mats Carlsson, the designer and main
implementor of SICStus Prolog, for his elegant example. I first encountered his system as part of the
excellent GUPU teaching environment by Ulrich Neumerkel. Ulrich was also the first and most de-
termined tester of the present system, filing hundreds of comments and suggestions for improvement.
Tom Schrijvers has contributed several constraint libraries to SWI-Prolog, and I learned a lot from his
coding style and implementation examples. Bart Demoen was a driving force behind the implemen-
tation of attributed variables in SWI-Prolog, and this library could not even have started without his
prior work and contributions. Thank you all!

A.8.17 CLP(FD) predicate index

In the following, each CLP(FD) predicate is described in more detail.
We recommend the following link to refer to this manual:
http://eu.swi-prolog.org/man/clpfd.html

Arithmetic constraints
Arithmetic constraints are the most basic use of CLP(FD). Every time you use (is)/2 or one of
the low-level arithmetic comparisons ((<)/2, (>)/2 etc.) over integers, consider using CLP(FD)
constraints instead. This can at most increase the generality of your programs. See declarative integer
arithmetic (section A.8.3).

?X #= ?Y
The arithmetic expression X equals Y. This is the most important arithmetic constraint (sec-
tion A.8.2), subsuming and replacing both (is)/2 and (=:=)/2 over integers. See
declarative integer arithmetic (section A.8.3).

?X #\= ?Y
The arithmetic expressions X and Y evaluate to distinct integers. When reasoning over integers,

SWI-Prolog 7.4 Reference Manual

420 APPENDIX A. THE SWI-PROLOG LIBRARY

replace (=\=)/2 by #\=/2 to obtain more general relations. See declarative integer
arithmetic (section A.8.3).

?X #>= ?Y
Same as Y #=< X. When reasoning over integers, replace (>=)/2 by #>=/2 to obtain more
general relations. See declarative integer arithmetic (section A.8.3).

?X #=< ?Y
The arithmetic expression X is less than or equal to Y. When reasoning over integers, replace
(=<)/2 by #=</2 to obtain more general relations. See declarative integer arithmetic
(section A.8.3).

?X #> ?Y
Same as Y #< X. When reasoning over integers, replace (>)/2 by #>/2 to obtain more
general relations See declarative integer arithmetic (section A.8.3).

?X #< ?Y
The arithmetic expression X is less than Y. When reasoning over integers, replace (<)/2 by
#</2 to obtain more general relations. See declarative integer arithmetic (section A.8.3).
In addition to its regular use in tasks that require it, this constraint can also be useful to eliminate
uninteresting symmetries from a problem. For example, all possible matches between pairs built
from four players in total:

?- Vs = [A,B,C,D], Vs ins 1..4,

all_different(Vs),
A #< B, C #< D, A #< C,
findall(pair(A,B)-pair(C,D), label(Vs), Ms).
Ms = [ pair(1, 2)-pair(3, 4),
pair(1, 3)-pair(2, 4),
pair(1, 4)-pair(2, 3)].

Membership constraints
If you are using CLP(FD) to model and solve combinatorial tasks, then you typically need to specify
the admissible domains of variables. The membership constraints in/2 and ins/2 are useful in
such cases.

?Var in +Domain
Var is an element of Domain. Domain is one of:

Integer
Singleton set consisting only of Integer.
Lower .. Upper
All integers I such that Lower =< I =< Upper. Lower must be an integer or the atom inf,
which denotes negative infinity. Upper must be an integer or the atom sup, which denotes
positive infinity.
Domain1 \/ Domain2
The union of Domain1 and Domain2.

SWI-Prolog 7.4 Reference Manual

A.8. LIBRARY(CLPFD): CLP(FD): CONSTRAINT LOGIC PROGRAMMING OVER
FINITE DOMAINS 421

+Vars ins +Domain

The variables in the list Vars are elements of Domain. See in/2 for the syntax of Domain.

Enumeration predicates
When modeling combinatorial tasks, the actual search for solutions is typically performed by enu-
meration predicates like labeling/2. See the the section about core relations and search for more
information.

indomain(?Var)
Bind Var to all feasible values of its domain on backtracking. The domain of Var must be finite.
label(+Vars)
Equivalent to labeling([], Vars). See labeling/2.
labeling(+Options, +Vars)
Assign a value to each variable in Vars. Labeling means systematically trying out values for
the finite domain variables Vars until all of them are ground. The domain of each variable in
Vars must be finite. Options is a list of options that let you exhibit some control over the search
process. Several categories of options exist:
The variable selection strategy lets you specify which variable of Vars is labeled next and is one
of:

leftmost
Label the variables in the order they occur in Vars. This is the default.
ff
First fail. Label the leftmost variable with smallest domain next, in order to detect infea-
sibility early. This is often a good strategy.
ffc
Of the variables with smallest domains, the leftmost one participating in most constraints
is labeled next.
min
Label the leftmost variable whose lower bound is the lowest next.
max
Label the leftmost variable whose upper bound is the highest next.

The value order is one of:

up
Try the elements of the chosen variables domain in ascending order. This is the default.
down
Try the domain elements in descending order.

The branching strategy is one of:

step
For each variable X, a choice is made between X = V and X #\= V, where V is determined
by the value ordering options. This is the default.

SWI-Prolog 7.4 Reference Manual

422 APPENDIX A. THE SWI-PROLOG LIBRARY

enum
For each variable X, a choice is made between X = V 1, X = V 2 etc., for all values V i
of the domain of X. The order is determined by the value ordering options.
bisect
For each variable X, a choice is made between X #=< M and X #> M, where M is the
midpoint of the domain of X.

At most one option of each category can be specified, and an option must not occur repeatedly.
The order of solutions can be influenced with:

min(Expr)
max(Expr)

This generates solutions in ascending/descending order with respect to the evaluation of the
arithmetic expression Expr. Labeling Vars must make Expr ground. If several such options are
specified, they are interpreted from left to right, e.g.:

?- [X,Y] ins 10..20, labeling([max(X),min(Y)],[X,Y]).

This generates solutions in descending order of X, and for each binding of X, solutions are
generated in ascending order of Y. To obtain the incomplete behaviour that other systems exhibit
with maximize(Expr) and minimize(Expr), use once/1, e.g.:

once(labeling([max(Expr)], Vars))

Labeling is always complete, always terminates, and yields no redundant solutions. See core
relations and search (section A.8.9) for usage advice.

Global constraints
A global constraint expresses a relation that involves many variables at once. The most fre-
quently used global constraints of this library are the combinatorial constraints all distinct/1,
global cardinality/2 and cumulative/2.

all distinct(+Vars)
True iff Vars are pairwise distinct. For example, all distinct/1 can detect that not all
variables can assume distinct values given the following domains:

?- maplist(in, Vs,
[1\/3..4, 1..2\/4, 1..2\/4, 1..3, 1..3, 1..6]),
all_distinct(Vs).
false.

all different(+Vars)
Like all distinct/1, but with weaker propagation. Consider using all distinct/1
instead, since all distinct/1 is typically acceptably efficient and propagates much more
strongly.

SWI-Prolog 7.4 Reference Manual

A.8. LIBRARY(CLPFD): CLP(FD): CONSTRAINT LOGIC PROGRAMMING OVER
FINITE DOMAINS 423

sum(+Vars, +Rel, ?Expr)

The sum of elements of the list Vars is in relation Rel to Expr. Rel is one of #=, #\=, #<, #>,
#=< or #>=. For example:

?- [A,B,C] ins 0..sup, sum([A,B,C], #=, 100).

A in 0..100,
A+B+C#=100,
B in 0..100,
C in 0..100.

scalar product(+Cs, +Vs, +Rel, ?Expr)

True iff the scalar product of Cs and Vs is in relation Rel to Expr. Cs is a list of integers, Vs is a
list of variables and integers. Rel is #=, #\=, #<, #>, #=< or #>=.

lex chain(+Lists)
Lists are lexicographically non-decreasing.

tuples in(+Tuples, +Relation)

True iff all Tuples are elements of Relation. Each element of the list Tuples is a list of integers
or finite domain variables. Relation is a list of lists of integers. Arbitrary finite relations, such
as compatibility tables, can be modeled in this way. For example, if 1 is compatible with 2 and
5, and 4 is compatible with 0 and 3:

?- tuples_in([[X,Y]], [[1,2],[1,5],[4,0],[4,3]]), X = 4.
X = 4,
Y in 0\/3.

As another example, consider a train schedule represented as a list of quadruples, denoting

departure and arrival places and times for each train. In the following program, Ps is a feasible
journey of length 3 from A to D via trains that are part of the given schedule.

trains([[1,2,0,1],
[2,3,4,5],
[2,3,0,1],
[3,4,5,6],
[3,4,2,3],
[3,4,8,9]]).

threepath(A, D, Ps) :-
Ps = [[A,B,_T0,T1],[B,C,T2,T3],[C,D,T4,_T5]],
T2 #> T1,
T4 #> T3,
trains(Ts),
tuples_in(Ps, Ts).

In this example, the unique solution is found without labeling:

SWI-Prolog 7.4 Reference Manual

424 APPENDIX A. THE SWI-PROLOG LIBRARY

?- threepath(1, 4, Ps).
Ps = [[1, 2, 0, 1], [2, 3, 4, 5], [3, 4, 8, 9]].

serialized(+Starts, +Durations)
Describes a set of non-overlapping tasks. Starts = [S 1,...,S n], is a list of variables or integers,
Durations = [D 1,...,D n] is a list of non-negative integers. Constrains Starts and Durations to
denote a set of non-overlapping tasks, i.e.: S i + D i =< S j or S j + D j =< S i for all 1 =< i <
j =< n. Example:

?- length(Vs, 3),
Vs ins 0..3,
serialized(Vs, [1,2,3]),
label(Vs).
Vs = [0, 1, 3] ;
Vs = [2, 0, 3] ;
false.

See also Dorndorf et al. 2000, Constraint Propagation Techniques for the Disjunctive Scheduling
Problem

element(?N, +Vs, ?V)

The N-th element of the list of finite domain variables Vs is V. Analogous to nth1/3.
global cardinality(+Vs, +Pairs)
Global Cardinality constraint. Equivalent to global_cardinality(Vs, Pairs, []).
See global cardinality/3.
Example:

?- Vs = [_,_,_], global_cardinality(Vs, [1-2,3-_]), label(Vs).

Vs = [1, 1, 3] ;
Vs = [1, 3, 1] ;
Vs = [3, 1, 1].

global cardinality(+Vs, +Pairs, +Options)

Global Cardinality constraint. Vs is a list of finite domain variables, Pairs is a list of Key-Num
pairs, where Key is an integer and Num is a finite domain variable. The constraint holds iff each
V in Vs is equal to some key, and for each Key-Num pair in Pairs, the number of occurrences
of Key in Vs is Num. Options is a list of options. Supported options are:

consistency(value)
A weaker form of consistency is used.
cost(Cost, Matrix)
Matrix is a list of rows, one for each variable, in the order they occur in Vs. Each of these
rows is a list of integers, one for each key, in the order these keys occur in Pairs. When
variable v i is assigned the value of key k j, then the associated cost is Matrix {ij}. Cost
is the sum of all costs.

SWI-Prolog 7.4 Reference Manual

A.8. LIBRARY(CLPFD): CLP(FD): CONSTRAINT LOGIC PROGRAMMING OVER
FINITE DOMAINS 425

circuit(+Vs)
True iff the list Vs of finite domain variables induces a Hamiltonian circuit. The k-th element
of Vs denotes the successor of node k. Node indexing starts with 1. Examples:

?- length(Vs, _), circuit(Vs), label(Vs).

Vs = [] ;
Vs = [1] ;
Vs = [2, 1] ;
Vs = [2, 3, 1] ;
Vs = [3, 1, 2] ;
Vs = [2, 3, 4, 1] .

cumulative(+Tasks)
Equivalent to cumulative(Tasks, [limit(1)]). See cumulative/2.

cumulative(+Tasks, +Options)
Schedule with a limited resource. Tasks is a list of tasks, each of the form
task(S_i, D_i, E_i, C_i, T_i). S i denotes the start time, D i the positive
duration, E i the end time, C i the non-negative resource consumption, and T i the task
identifier. Each of these arguments must be a finite domain variable with bounded domain, or
an integer. The constraint holds iff at each time slot during the start and end of each task, the
total resource consumption of all tasks running at that time does not exceed the global resource
limit. Options is a list of options. Currently, the only supported option is:

limit(L)
The integer L is the global resource limit. Default is 1.

For example, given the following predicate that relates three tasks of durations 2 and 3 to a list
containing their starting times:

tasks_starts(Tasks, [S1,S2,S3]) :-
Tasks = [task(S1,3,_,1,_),
task(S2,2,_,1,_),
task(S3,2,_,1,_)].

We can use cumulative/2 as follows, and obtain a schedule:

?- tasks_starts(Tasks, Starts), Starts ins 0..10,

cumulative(Tasks, [limit(2)]), label(Starts).
Tasks = [task(0, 3, 3, 1, _G36), task(0, 2, 2, 1, _G45), ...],
Starts = [0, 0, 2] .

disjoint2(+Rectangles)
True iff Rectangles are not overlapping. Rectangles is a list of terms of the form F(X i, W i,
Y i, H i), where F is any functor, and the arguments are finite domain variables or integers that
denote, respectively, the X coordinate, width, Y coordinate and height of each rectangle.

SWI-Prolog 7.4 Reference Manual

426 APPENDIX A. THE SWI-PROLOG LIBRARY

automaton(+Vs, +Nodes, +Arcs)

Describes a list of finite domain variables with a finite automaton. Equivalent to
automaton(Vs, _, Vs, Nodes, Arcs, [], [], _), a common use case of
automaton/8. In the following example, a list of binary finite domain variables is
constrained to contain at least two consecutive ones:

two_consecutive_ones(Vs) :-
automaton(Vs, [source(a),sink(c)],
[arc(a,0,a), arc(a,1,b),
arc(b,0,a), arc(b,1,c),
arc(c,0,c), arc(c,1,c)]).

Example query:

?- length(Vs, 3), two_consecutive_ones(Vs), label(Vs).

Vs = [0, 1, 1] ;
Vs = [1, 1, 0] ;
Vs = [1, 1, 1].

automaton(+Sequence, ?Template, +Signature, +Nodes, +Arcs, +Counters, +Initials, ?Finals)

Describes a list of finite domain variables with a finite automaton. True iff the finite automaton
induced by Nodes and Arcs (extended with Counters) accepts Signature. Sequence is a list
of terms, all of the same shape. Additional constraints must link Sequence to Signature, if
necessary. Nodes is a list of source(Node) and sink(Node) terms. Arcs is a list of
arc(Node,Integer,Node) and arc(Node,Integer,Node,Exprs) terms that
denote the automatons transitions. Each node is represented by an arbitrary term. Transitions
that are not mentioned go to an implicit failure node. Exprs is a list of arithmetic expressions, of
the same length as Counters. In each expression, variables occurring in Counters symbolically
refer to previous counter values, and variables occurring in Template refer to the current
element of Sequence. When a transition containing arithmetic expressions is taken, each
counter is updated according to the result of the corresponding expression. When a transition
without arithmetic expressions is taken, all counters remain unchanged. Counters is a list of
variables. Initials is a list of finite domain variables or integers denoting, in the same order,
the initial value of each counter. These values are related to Finals according to the arithmetic
expressions of the taken transitions.
The following example is taken from Beldiceanu, Carlsson, Debruyne and Petit: Reformu-
lation of Global Constraints Based on Constraints Checkers, Constraints 10(4), pp 339-362
(2005). It relates a sequence of integers and finite domain variables to its number of inflexions,
which are switches between strictly ascending and strictly descending subsequences:

sequence_inflexions(Vs, N) :-
variables_signature(Vs, Sigs),
automaton(Sigs, _, Sigs,
[source(s),sink(i),sink(j),sink(s)],
[arc(s,0,s), arc(s,1,j), arc(s,2,i),
arc(i,0,i), arc(i,1,j,[C+1]), arc(i,2,i),

SWI-Prolog 7.4 Reference Manual

A.8. LIBRARY(CLPFD): CLP(FD): CONSTRAINT LOGIC PROGRAMMING OVER
FINITE DOMAINS 427

arc(j,0,j), arc(j,1,j),
arc(j,2,i,[C+1])],
[C], [0], [N]).

variables_signature([], []).
variables_signature([V|Vs], Sigs) :-
variables_signature_(Vs, V, Sigs).

variables_signature_([], _, []).
variables_signature_([V|Vs], Prev, [S|Sigs]) :-
V #= Prev #<==> S #= 0,
Prev #< V #<==> S #= 1,
Prev #> V #<==> S #= 2,
variables_signature_(Vs, V, Sigs).

Example queries:

?- sequence_inflexions([1,2,3,3,2,1,3,0], N).
N = 3.

?- length(Ls, 5), Ls ins 0..1,

sequence_inflexions(Ls, 3), label(Ls).
Ls = [0, 1, 0, 1, 0] ;
Ls = [1, 0, 1, 0, 1].

chain(+Zs, +Relation)
Zs form a chain with respect to Relation. Zs is a list of finite domain variables that are a chain
with respect to the partial order Relation, in the order they appear in the list. Relation must be
#=, #=<, #>=, #< or #>. For example:

?- chain([X,Y,Z], #>=).
X#>=Y,
Y#>=Z.

Reification predicates
Many CLP(FD) constraints can be reified. This means that their truth value is itself turned into a
CLP(FD) variable, so that we can explicitly reason about whether a constraint holds or not. See
reification (section A.8.12).

#\ +Q
Q does not hold. See reification (section A.8.12).
For example, to obtain the complement of a domain:

?- #\ X in -3..0\/10..80.
X in inf.. -4\/1..9\/81..sup.

SWI-Prolog 7.4 Reference Manual

428 APPENDIX A. THE SWI-PROLOG LIBRARY

?P #<==> ?Q
P and Q are equivalent. See reification (section A.8.12).
For example:

?- X #= 4 #<==> B, X #\= 4.
B = 0,
X in inf..3\/5..sup.

The following example uses reified constraints to relate a list of finite domain variables to the
number of occurrences of a given value:

vs_n_num(Vs, N, Num) :-
maplist(eq_b(N), Vs, Bs),
sum(Bs, #=, Num).

eq_b(X, Y, B) :- X #= Y #<==> B.

Sample queries and their results:

?- Vs = [X,Y,Z], Vs ins 0..1, vs_n_num(Vs, 4, Num).

Vs = [X, Y, Z],
Num = 0,
X in 0..1,
Y in 0..1,
Z in 0..1.

?- vs_n_num([X,Y,Z], 2, 3).
X = 2,
Y = 2,
Z = 2.

?P #==> ?Q
P implies Q. See reification (section A.8.12).

?P #<== ?Q
Q implies P. See reification (section A.8.12).

?P #/\ ?Q
P and Q hold. See reification (section A.8.12).

?P #\/ ?Q
P or Q holds. See reification (section A.8.12).
For example, the sum of natural numbers below 1000 that are multiples of 3 or 5:

?- findall(N, (N mod 3 #= 0 #\/ N mod 5 #= 0, N in 0..999,

indomain(N)),

SWI-Prolog 7.4 Reference Manual

A.8. LIBRARY(CLPFD): CLP(FD): CONSTRAINT LOGIC PROGRAMMING OVER
FINITE DOMAINS 429

Ns),
sum(Ns, #=, Sum).
Ns = [0, 3, 5, 6, 9, 10, 12, 15, 18|...],
Sum = 233168.

?P #\ ?Q
Either P holds or Q holds, but not both. See reification (section A.8.12).

zcompare(?Order, ?A, ?B)

Analogous to compare/3, with finite domain variables A and B.
This predicate allows you to make several predicates over integers deterministic while preserv-
ing their generality and completeness. For example:

n_factorial(N, F) :-
zcompare(C, N, 0),
n_factorial_(C, N, F).

n_factorial_(=, _, 1).
n_factorial_(>, N, F) :-
F #= F0*N, N1 #= N - 1,
n_factorial(N1, F0).

This version is deterministic if the first argument is instantiated, because first argument indexing
can distinguish the two different clauses:

?- n_factorial(30, F).
F = 265252859812191058636308480000000.

The predicate can still be used in all directions, including the most general query:

?- n_factorial(N, F).
N = 0,
F = 1 ;
N = F, F = 1 ;
N = F, F = 2 .

Reflection predicates
Reflection predicates let us obtain, in a well-defined way, information that is normally internal to this
library. In addition to the predicates explained below, also take a look at call residue vars/2
and copy term/3 to reason about CLP(FD) constraints that arise in programs. This can be useful
in program analyzers and declarative debuggers.

fd var(+Var)
True iff Var is a CLP(FD) variable.

SWI-Prolog 7.4 Reference Manual

430 APPENDIX A. THE SWI-PROLOG LIBRARY

fd inf(+Var, -Inf)
Inf is the infimum of the current domain of Var.

fd sup(+Var, -Sup)
Sup is the supremum of the current domain of Var.

fd size(+Var, -Size)
Reflect the current size of a domain. Size is the number of elements of the current domain of
Var, or the atom sup if the domain is unbounded.

fd dom(+Var, -Dom)
Dom is the current domain (see in/2) of Var. This predicate is useful if you want to reason
about domains. It is not needed if you only want to display remaining domains; instead,
separate your model from the search part and let the toplevel display this information via
residual goals.
For example, to implement a custom labeling strategy, you may need to inspect the current
domain of a finite domain variable. With the following code, you can convert a finite domain to
a list of integers:

dom_integers(D, Is) :- phrase(dom_integers_(D), Is).

dom_integers_(I) --> { integer(I) }, [I].

dom_integers_(L..U) --> { numlist(L, U, Is) }, Is.
dom_integers_(D1\/D2) --> dom_integers_(D1), dom_integers_(D2).

Example:

?- X in 1..5, X #\= 4, fd_dom(X, D), dom_integers(D, Is).

D = 1..3\/5,
Is = [1,2,3,5],
X in 1..3\/5.

A.8.18 Closing and opening words about CLP(FD)

CLP(FD) constraints are one of the main reasons why logic programming approaches are picked
over other paradigms for solving many tasks of high practical relevance. The usefulness of CLP(FD)
constraints for scheduling, allocation and combinatorial optimization tasks is well-known both in
academia and industry.
With this library, we take the applicability of CLP(FD) constraints one step further, following
the road that visionary systems like SICStus Prolog have already clearly outlined: This library is
designed to completely subsume and replace low-level predicates over integers, which were in the past
repeatedly found to be a major stumbling block when introducing logic programming to beginners.
Embrace the change and new opportunities that this paradigm allows! Use CLP(FD) constraints
in your programs. The use of CLP(FD) constraints instead of low-level arithmetic is also a good
indicator to judge the quality of any introductory Prolog text.

SWI-Prolog 7.4 Reference Manual

A.9. LIBRARY(CLPQR): CONSTRAINT LOGIC PROGRAMMING OVER RATIONALS
AND REALS 431

A.9 library(clpqr): Constraint Logic Programming over Rationals and

Reals
Author: Christian Holzbaur, ported to SWI-Prolog by Leslie De Koninck, K.U. Leuven

This CLP(Q,R) system is a port of the CLP(Q,R) system of Sicstus Prolog by Christian Holzbaur:
Holzbaur C.: OFAI clp(q,r) Manual, Edition 1.3.3, Austrian Research Institute for Artificial Intelli-
gence, Vienna, TR-95-09, 1995.1 This manual is roughly based on the manual of the above mentioned
CLP(Q,R) implementation.
The CLP(Q,R) system consists of two components: the CLP(Q) library for handling constraints
over the rational numbers and the CLP(R) library for handling constraints over the real numbers (using
floating point numbers as representation). Both libraries offer the same predicates (with exception of
bb inf/4 in CLP(Q) and bb inf/5 in CLP(R)). It is allowed to use both libraries in one program,
but using both CLP(Q) and CLP(R) constraints on the same variable will result in an exception.
Please note that the clpqr library is not an autoload library and therefore this library must be
loaded explicitly before using it:

:- use_module(library(clpq)).

or

:- use_module(library(clpr)).

A.9.1 Solver predicates

The following predicates are provided to work with constraints:

{}(+Constraints)
Adds the constraints given by Constraints to the constraint store.

entailed(+Constraint)
Succeeds if Constraint is necessarily true within the current constraint store. This means that
adding the negation of the constraint to the store results in failure.

inf(+Expression, -Inf)
Computes the infimum of Expression within the current state of the constraint store and returns
that infimum in Inf. This predicate does not change the constraint store.

sup(+Expression, -Sup)
Computes the supremum of Expression within the current state of the constraint store and
returns that supremum in Sup. This predicate does not change the constraint store.

minimize(+Expression)
Minimizes Expression within the current constraint store. This is the same as computing the
infimum and equating the expression to that infimum.
1
http://www.ai.univie.ac.at/cgi-bin/tr-online?number+95-09

SWI-Prolog 7.4 Reference Manual

432 APPENDIX A. THE SWI-PROLOG LIBRARY

maximize(+Expression)
Maximizes Expression within the current constraint store. This is the same as computing the
supremum and equating the expression to that supremum.

bb inf(+Ints, +Expression, -Inf, -Vertex, +Eps)

This predicate is offered in CLP(R) only. It computes the infimum of Expression within the
current constraint store, with the additional constraint that in that infimum, all variables in Ints
have integral values. Vertex will contain the values of Ints in the infimum. Eps denotes how
much a value may differ from an integer to be considered an integer. E.g. when Eps = 0.001,
then X = 4.999 will be considered as an integer (5 in this case). Eps should be between 0 and
0.5.

bb inf(+Ints, +Expression, -Inf, -Vertex)

This predicate is offered in CLP(Q) only. It behaves the same as bb inf/5 but does not use
an error margin.

bb inf(+Ints, +Expression, -Inf)

The same as bb inf/5 or bb inf/4 but without returning the values of the integers. In
CLP(R), an error margin of 0.001 is used.

dump(+Target, +Newvars, -CodedAnswer)

Returns the constraints on Target in the list CodedAnswer where all variables of Target have
been replaced by NewVars. This operation does not change the constraint store. E.g. in

dump([X,Y,Z],[x,y,z],Cons)

Cons will contain the constraints on X, Y and Z, where these variables have been replaced by
atoms x, y and z.

A.9.2 Syntax of the predicate arguments

The arguments of the predicates defined in the subsection above are defined in table A.1. Failing to
meet the syntax rules will result in an exception.

A.9.3 Use of unification

Instead of using the {}/1 predicate, you can also use the standard unification mechanism to store
constraints. The following code samples are equivalent:

Unification
{X =:= Y} with a variable
{X = Y}
X = Y

Unification
{X =:= 5.0} with a number
{X = 5.0}
X = 5.0

SWI-Prolog 7.4 Reference Manual

A.9. LIBRARY(CLPQR): CONSTRAINT LOGIC PROGRAMMING OVER RATIONALS
AND REALS 433

hConstraintsi ::= hConstrainti single constraint

| hConstrainti , hConstraintsi conjunction
| hConstrainti ; hConstraintsi disjunction
hConstrainti ::= hExpressioni < hExpressioni less than
| hExpressioni > hExpressioni greater than
| hExpressioni =< hExpressioni less or equal
| <=(hExpressioni, hExpressioni) less or equal
| hExpressioni >= hExpressioni greater or equal
| hExpressioni =\= hExpressioni not equal
| hExpressioni =:= hExpressioni equal
| hExpressioni = hExpressioni equal
hExpressioni ::= hVariablei Prolog variable
| hNumberi Prolog number
| +hExpressioni unary plus
| -hExpressioni unary minus
| hExpressioni + hExpressioni addition
| hExpressioni - hExpressioni substraction
| hExpressioni * hExpressioni multiplication
| hExpressioni / hExpressioni division
| abs(hExpressioni) absolute value
| sin(hExpressioni) sine
| cos(hExpressioni) cosine
| tan(hExpressioni) tangent
| exp(hExpressioni) exponent
| pow(hExpressioni) exponent
| hExpressioni hExpressioni exponent
| min(hExpressioni, hExpressioni) minimum
| max(hExpressioni, hExpressioni) maximum

Table A.1: CLP(Q,R) constraint BNF

SWI-Prolog 7.4 Reference Manual

434 APPENDIX A. THE SWI-PROLOG LIBRARY

A=BC B or C is ground A = 5 * C or A = B * 4
A and (B or C) are ground 20 = 5 * C or 20 = B * 4
A = B/C C is ground A=B/3
A and B are ground 4 = 12 / C
X = min(Y, Z) Y and Z are ground X = min(4,3)
X = max(Y, Z) Y and Z are ground X = max(4,3)
X = abs(Y ) Y is ground X = abs(-7)
X = pow(Y, Z) X and Y are ground 8=2Z
X = exp(Y, Z) X and Z are ground 8=Y3
X =Y Z Y and Z are ground X=23
X = sin(Y ) X is ground 1 = sin(Y)
X = cos(Y ) Y is ground X = sin(1.5707)
X = tan(Y )

Table A.2: CLP(Q,R) isolating axioms

A.9.4 Non-linear constraints

The CLP(Q,R) system deals only passively with non-linear constraints. They remain in a passive
state until certain conditions are satisfied. These conditions, which are called the isolation axioms, are
given in table A.2.

A.9.5 Status and known problems

The clpq and clpr libraries are orphaned, i.e., they currently have no maintainer.

Top-level output
The top-level output may contain variables not present in the original query:

?- {X+Y>=1}.
{Y=1-X+_G2160, _G2160>=0}.

?-

Nonetheless, for linear constraints this kind of answer means unconditional satisfiability.

Dumping constraints
The first argument of dump/3 has to be a list of free variables at call-time:

?- {X=1},dump([X],[Y],L).
ERROR: Unhandled exception: Unknown message:
instantiation_error(dump([1],[_G11],_G6),1)
?-

SWI-Prolog 7.4 Reference Manual

A.10. LIBRARY(CSV): PROCESS CSV (COMMA-SEPARATED VALUES) DATA 435

A.10 library(csv): Process CSV (Comma-Separated Values) data

See also RFC 4180
To be done
- Implement immediate assert of the data to avoid possible stack overflows.
- Writing creates an intermediate code-list, possibly overflowing resources. This waits for pure output!

This library parses and generates CSV data. CSV data is represented in Prolog as a list of rows.
Each row is a compound term, where all rows have the same name and arity.

csv read file(+File, -Rows) [det]

csv read file(+File, -Rows, +Options) [det]
Read a CSV file into a list of rows. Each row is a Prolog term with the same arity. Options
is handed to csv//2. Remaining options are processed by phrase from file/3. The
default separator depends on the file name extension and is \t for .tsv files and , otherwise.
Suppose we want to create a predicate table/6 from a CSV file that we know contains 6
fields per record. This can be done using the code below. Without the option arity(6), this
would generate a predicate table/N, where N is the number of fields per record in the data.

?- csv_read_file(File, Rows, [functor(table), arity(6)]),

maplist(assert, Rows).

csv(?Rows) // [det]
csv(?Rows, +Options) // [det]
Prolog DCG to read/write CSV data. Options:

separator(+Code)
The comma-separator. Must be a character code. Default is (of course) the comma.
Character codes can be specified using the 0 notion. E.g., using separator(0;)
parses a semicolon separated file.
ignore quotes(+Boolean)
If true (default false), threat double quotes as a normal character.
strip(+Boolean)
If true (default false), strip leading and trailing blank space. RFC4180 says that
blank space is part of the data.
convert(+Boolean)
If true (default), use name/2 on the field data. This translates the field into a number if
possible.
functor(+Atom)
Functor to use for creating row terms. Default is row.
arity(?Arity)
Number of fields in each row. This predicate raises a
domain_error(row_arity(Expected), Found) if a row is found with
different arity.

SWI-Prolog 7.4 Reference Manual

436 APPENDIX A. THE SWI-PROLOG LIBRARY

match arity(+Boolean)
If false (default true), do not reject CSV files where lines provide a varying number
of fields (columns). This can be a work-around to use some incorrect CSV files.

csv read file row(+File, -Row, +Options) [nondet]

True when Row is a row in File. First unifies Row with the first row in File. Backtracking
yields the second, ... row. This interface is an alternative to csv read file/3 that avoids
loading all rows in memory. Note that this interface does not guarantee that all rows in File
have the same arity.
In addition to the options of csv read file/3, this predicate processes the option:

line(-Line)
Line is unified with the 1-based line-number from which Row is read. Note that Line is
not the physical line, but rather the logical record number.
To be done Input is read line by line. If a record separator is embedded in a quoted field, parsing the
record fails and another line is added to the input. This does not nicely deal with other reasons
why parsing the row may fail.

csv write file(+File, +Data) [det]

csv write file(+File, +Data, +Options) [det]
Write a list of Prolog terms to a CSV file. Options are given to csv//2. Remaining options
are given to open/4. The default separator depends on the file name extension and is \t for
.tsv files and , otherwise.
csv write stream(+Stream, +Data, +Options) [det]
Write the rows in Data to Stream. This is similar to csv write file/3, but can deal with
data that is produced incrementally. The example below saves all answers from the predicate
data/3 to File.

save_data(File) :-
setup_call_cleanup(
open(File, write, Out),
forall(data(C1,C2,C3),
csv_write_stream(Out, [row(C1,C2,C3)], [])),
close(Out)),

A.11 library(debug): Print debug messages and test assertions

author Jan Wielemaker

This library is a replacement for format/3 for printing debug messages. Messages are assigned
a topic. By dynamically enabling or disabling topics the user can select desired messages. Debug
statements are removed when the code is compiled for optimization.
See manual for details. With XPCE, you can use the call below to start a graphical monitoring
tool.

?- prolog_ide(debug_monitor).

SWI-Prolog 7.4 Reference Manual

A.11. LIBRARY(DEBUG): PRINT DEBUG MESSAGES AND TEST ASSERTIONS 437

Using the predicate assertion/1 you can make assumptions about your program explicit,
trapping the debugger if the condition does not hold.

debugging(+Topic) [semidet]
debugging(-Topic) [nondet]
debugging(?Topic, ?Bool) [nondet]
Examine debug topics. The form debugging(+Topic) may be used to perform more
complex debugging tasks. A typical usage skeleton is:

( debugging(mytopic)
-> <perform debugging actions>
; true
),
...

The other two calls are intended to examine existing and enabled debugging tokens and are
typically not used in user programs.

debug(+Topic) [det]
nodebug(+Topic) [det]
Add/remove a topic from being printed. nodebug(_) removes all topics. Gives a warning if
the topic is not defined unless it is used from a directive. The latter allows placing debug topics
at the start of a (load-)file without warnings.
For debug/1, Topic can be a term Topic > Out, where Out is either a stream or stream-alias
or a filename (atom). This redirects debug information on this topic to the given output.

list debug topics [det]

List currently known debug topics and their setting.

debug message context(+What) [det]

Specify additional context for debug messages. What is one of +Context or -Context, and Con-
text is one of thread, time or time(Format), where Format is a format specification for
format time/3 (default is %T.%3f). Initially, debug/3 shows only thread information.

debug(+Topic, +Format, :Args) [det]

Format a message if debug topic is enabled. Similar to format/3 to user_error, but only
prints if Topic is activated through debug/1. Args is a meta-argument to deal with goal for the
@-command. Output is first handed to the hook prolog:debug print hook/3.
If this fails, Format+Args is translated to text using the message-translation (see
print message/2) for the term debug(Format, Args) and then printed to ev-
ery matching destination (controlled by debug/1) using print message lines/3.
The message is preceded by % and terminated with a newline.

See also format/3.

SWI-Prolog 7.4 Reference Manual

438 APPENDIX A. THE SWI-PROLOG LIBRARY

prolog:debug print hook(+Topic, +Format, +Args) [semidet,multifile]

Hook called by debug/3. This hook is used by the graphical frontend that can be activated
using prolog ide/1:

?- prolog_ide(debug_monitor).

assertion(:Goal) [det]
Acts similar to C assert() macro. It has no effect if Goal succeeds. If Goal fails or throws
an exception, the following steps are taken:

call prolog:assertion failed/2. If prolog:assertion failed/2 fails,

then:
If this is an interactive toplevel thread, print a message, the stack-trace, and finally
trap the debugger.
Otherwise, throw error(assertion_error(Reason, G),_) where Reason
is one of fail or the exception raised.

prolog:assertion failed(+Reason, +Goal) [semidet,multifile]

This hook is called if the Goal of assertion/1 fails. Reason is unified with either fail
if Goal simply failed or an exception call otherwise. If this hook fails, the default behaviour
is activated. If the hooks throws an exception it will be propagated into the caller of
assertion/1.

A.12 library(error): Error generating support

author
- Jan Wielemaker
- Richard OKeefe
- Ulrich Neumerkel
See also
- library(debug) and library(prolog_stack).
- print message/2 is used to print (uncaught) error terms.

This module provides predicates to simplify error generation and checking. Its implementation
is based on a discussion on the SWI-Prolog mailinglist on best practices in error handling. The utility
predicate must be/2 provides simple run-time type validation. The * error predicates are simple
wrappers around throw/1 to simplify throwing the most common ISO error terms.

type error(+Type, +Term)

Tell the user that Term is not of the expected Type. This error is closely related to
domain error/2 because the notion of types is not really set in stone in Prolog. We
introduce the difference using a simple example.
Suppose an argument must be a non-negative integer. If the actual argument is not an integer,
this is a type error. If it is a negative integer, it is a domain error.
Typical borderline cases are predicates accepting a compound term, e.g., point(X,Y). One
could argue that the basic type is a compound-term and any other compound term is a domain

SWI-Prolog 7.4 Reference Manual

A.12. LIBRARY(ERROR): ERROR GENERATING SUPPORT 439

error. Most Prolog programmers consider each compound as a type and would consider a
compoint that is not point(_,_) a type error.
domain error(+Type, +Term)
The argument is of the proper type, but has a value that is outside the supported values. See
type error/2 for a more elaborate discussion of the distinction between type- and
domain-errors.
existence error(+Type, +Term)
Term is of the correct type and correct domain, but there is no existing (external) resource that
is represented by it.
permission error(+Action, +Type, +Term)
It is not allowed to perform Action on the object Term that is of the given Type.
instantiation error(+Term)
An argument is under-instantiated. I.e. it is not acceptable as it is, but if some variables are
bound to appropriate values it would be acceptable.
Arguments
Term is the term that needs (further) instantiation. Unfortunately, the
ISO error does not allow for passing this term along with the error,
but we pass it to this predicate for documentation purposes and to
allow for future enhancement.
uninstantiation error(+Term)
An argument is over-instantiated. This error is used for output arguments whose value cannot
be known upfront. For example, the goal open(File, read, input) cannot succeed
because the system will allocate a new unique stream handle that will never unify with input.
representation error(+Reason)
A representation error indicates a limitation of the implementation. SWI-Prolog has no such
limits that are not covered by other errors, but an example of a representation error in another
Prolog implementation could be an attempt to create a term with an arity higher than supported
by the system.
syntax error(+Culprit)
A text has invalid syntax. The error is described by Culprit.
To be done Deal with proper description of the location of the error. For short texts, we allow for
Type(Text), meaning Text is not a valid Type. E.g. syntax_error(number(1a)) means
that 1a is not a valid number.

resource error(+Culprit)
A goal cannot be completed due to lack of resources.
must be(+Type, @Term) [det]
True if Term satisfies the type constraints for Type. Defined types are atom, atomic,
between, boolean, callable, chars, codes, text, compound, constant,
float, integer, nonneg, positive_integer, negative_integer, nonvar,
number, oneof, list, list_or_partial_list, symbol, var, rational,
encoding, dict and string.

SWI-Prolog 7.4 Reference Manual

440 APPENDIX A. THE SWI-PROLOG LIBRARY

Most of these types are defined by an arity-1 built-in predicate of the same name. Below is a
brief definition of the other types.

boolean one of true or false

char Atom of length 1
code Representation Unicode code point
chars Proper list of 1-character atoms
codes Proper list of Unicode character codes
text One of atom, string, chars or codes
between(IntL,IntU) Integer [IntL..IntU]
between(FloatL,FloatU) Number [FloatL..FloatU]
nonneg Integer >= 0
positive integer Integer > 0
negative integer Integer < 0
oneof(L) Ground term that is member of L
encoding Valid name for a character encoding
cyclic Cyclic term (rational tree)
acyclic Acyclic term (tree)
list(Type) Proper list with elements of Type
list or partial list A list or an open list (ending in a variable

Note: The Windows version can only represent Unicode code points up to 216-1. Higher
values cause a representation error on most text handling predicates.

throws instantiation error if Term is insufficiently instantiated and type_error(Type, Term)

if Term is not of Type.

is of type(+Type, @Term) [semidet]

True if Term satisfies Type.

has type(+Type, @Term) [semidet,multifile]

True if Term satisfies Type.

current type(?Type, @Var, -Body) [nondet]

True when Type is a currently defined type and Var satisfies Type of the body term Body suc-
ceeds.

A.13 library(gensym): Generate unique identifiers

Gensym (Generate Symbols) is an old library for generating unique symbols (atoms). Such symbols
are generated from a base atom which gets a sequence number appended. Of course there is no
guarantee that catch22 is not an already defined atom and therefore one must be aware these atoms
are only unique in an isolated context.
The SWI-Prolog gensym library is thread-safe. The sequence numbers are global over all threads
and therefore generated atoms are unique over all threads.

gensym(+Base, -Unique)
Generate a unique atom from base Base and unify it with Unique. Base should be an atom. The

SWI-Prolog 7.4 Reference Manual

A.14. LIBRARY(IOSTREAM): UTILITIES TO DEAL WITH STREAMS 441

first call will return hbasei1, the next hbasei2, etc. Note that this is no guarantee that the atom
is unique in the system.

reset gensym(+Base)
Restart generation of identifiers from Base at hBasei1. Used to make sure a program produces
the same results on subsequent runs. Use with care.

reset gensym
Reset gensym for all registered keys. This predicate is available for compatibility only. New
code is strongly advised to avoid the use of reset gensym or at least to reset only the keys used
by your program to avoid unexpected side effects on other components.

A.14 library(iostream): Utilities to deal with streams

See also library(archive), library(process), library(zlib),
library(http/http_stream)

This library contains utilities that deal with streams, notably originating from non-built-in sources
such as URLs, archives, windows, processes, etc.
The predicate open any/5 acts as a broker between applications that can process data from a
stream and libraries that can create streams from diverse sources. Without this predicate, processing
data inevitally follows the pattern below. As call some open variation can be anything, this blocks
us from writing predicates such as load_xml(From, DOM) that can operate on arbitrary input
sources.

setup_call_cleanup(
call_some_open_variation(Spec, In),
process(In),
close(In)).

Libraries that can open streams can install the hook iostream:open hook/6 to make their
functionality available through open any/5.

open any(+Specification, +Mode, -Stream, -Close, +Options)

Establish a stream from Specification that should be closed using Close, which can either be
called or passed to close any/1. Options processed:

encoding(Enc)
Set stream to encoding Enc.

Without loaded plugins, the open any/5 processes the following values for Specification. If
no rule matches, open any/5 processes Specification as file(Specification).

Stream
A plain stream handle. Possisible post-processing options such as encoding are applied.
Close does not close the stream, but resets other side-effects such as the encoding.

SWI-Prolog 7.4 Reference Manual

442 APPENDIX A. THE SWI-PROLOG LIBRARY

stream(Stream)
Same as a plain Stream.
FileURL
If Specification is of the form =file://...=, the pointed to file is opened using open/4.
Requires library(uri) to be installed.
file(Path)
Explicitly open the file Path. Path can be an Path(File) term as accepted by
absolute file name/3.
string(String)
Open a Prolog string, atom, list of characters or codes as an input stream.

The typical usage scenario is given in the code below, where <process> processes the input.

setup_call_cleanup(
open_any(Spec, read, In, Close, Options),
<process>(In),
Close).

Currently, the following libraries extend this predicate:

library(http/http open)
Adds support for URLs using the http and https schemes.

close any(+Goal)
Execute the Close closure returned by open any/5. The closure can also be called directly.
Using close any/1 can be considered better style and enhances tractability of the source
code.

open hook(+Spec, +Mode, -Stream, -Close, +Options0, -Options) [semidet,multifile]

Open Spec in Mode, producing Stream.
Arguments
Close is unified to a goal that must be called to undo the side-effects of
the action, e.g., typically the term close(Stream)
Options0 are the options passed to open any/5
Options are passed to the post processing filters that may be installed by
open any/5.

A.15 library(lists): List Manipulation

Compatibility Virtually every Prolog system has library(lists), but the set of provided predicates
is diverse. There is a fair agreement on the semantics of most of these predicates, although error
handling may vary.

This library provides commonly accepted basic predicates for list manipulation in the Prolog
community. Some additional list manipulations are built-in. See e.g., memberchk/2, length/2.

SWI-Prolog 7.4 Reference Manual

A.15. LIBRARY(LISTS): LIST MANIPULATION 443

The implementation of this library is copied from many places. These include: The Craft of
Prolog, the DEC-10 Prolog library (LISTRO.PL) and the YAP lists library. Some predicates are
reimplemented based on their specification by Quintus and SICStus.

member(?Elem, ?List)
True if Elem is a member of List. The SWI-Prolog definition differs from the classical one.
Our definition avoids unpacking each list element twice and provides determinism on the last
element. E.g. this is deterministic:

member(X, [One]).

author Gertjan van Noord

append(?List1, ?List2, ?List1AndList2)

List1AndList2 is the concatenation of List1 and List2

append(+ListOfLists, ?List)
Concatenate a list of lists. Is true if ListOfLists is a list of lists, and List is the concatenation of
these lists.
Arguments
ListOfLists must be a list of possibly partial lists

prefix(?Part, ?Whole)
True iff Part is a leading substring of Whole. This is the same as
append(Part, _, Whole).

select(?Elem, ?List1, ?List2)

Is true when List1, with Elem removed, results in List2.

selectchk(+Elem, +List, -Rest) [semidet]

Semi-deterministic removal of first element in List that unifies with Elem.

select(?X, ?XList, ?Y, ?YList) [nondet]

Select from two lists at the same positon. True if XList is unifiable with YList apart a single
element at the same position that is unified with X in XList and with Y in YList. A typical
use for this predicate is to replace an element, as shown in the example below. All possible
substitutions are performed on backtracking.

?- select(b, [a,b,c,b], 2, X).

X = [a, 2, c, b] ;
X = [a, b, c, 2] ;
false.

See also selectchk/4 provides a semidet version.

selectchk(?X, ?XList, ?Y, ?YList) [semidet]

Semi-deterministic version of select/4.

SWI-Prolog 7.4 Reference Manual

444 APPENDIX A. THE SWI-PROLOG LIBRARY

nextto(?X, ?Y, ?List)

True if Y directly follows X in List.

delete(+List1, @Elem, -List2) [det]

Delete matching elements from a list. True when List2 is a list with all elements from List1
except for those that unify with Elem. Matching Elem with elements of List1 is uses
\+ Elem \= H, which implies that Elem is not changed.

See also select/3, subtract/3.

deprecated There are too many ways in which one might want to delete elements from a list to justify
the name. Think of matching (= vs. ==), delete first/all, be deterministic or not.

nth0(?Index, ?List, ?Elem)

True when Elem is the Indexth element of List. Counting starts at 0.

Errors type_error(integer, Index) if Index is not an integer or unbound.

See also nth1/3.

nth1(?Index, ?List, ?Elem)

Is true when Elem is the Indexth element of List. Counting starts at 1.

See also nth0/3.

nth0(?N, ?List, ?Elem, ?Rest) [det]

Select/insert element at index. True when Elem is the Nth (0-based) element of List and Rest
is the remainder (as in by select/3) of List. For example:

?- nth0(I, [a,b,c], E, R).

I = 0, E = a, R = [b, c] ;
I = 1, E = b, R = [a, c] ;
I = 2, E = c, R = [a, b] ;
false.

?- nth0(1, L, a1, [a,b]).

L = [a, a1, b].

nth1(?N, ?List, ?Elem, ?Rest) [det]

As nth0/4, but counting starts at 1.

last(?List, ?Last)
Succeeds when Last is the last element of List. This predicate is semidet if List is a list and
multi if List is a partial list.

Compatibility There is no de-facto standard for the argument order of last/2. Be careful when
porting code or use append(_, [Last], List) as a portable alternative.

proper length(@List, -Length) [semidet]

True when Length is the number of elements in the proper list List. This is equivalent to

SWI-Prolog 7.4 Reference Manual

A.15. LIBRARY(LISTS): LIST MANIPULATION 445

proper_length(List, Length) :-
is_list(List),
length(List, Length).

same length(?List1, ?List2)

Is true when List1 and List2 are lists with the same number of elements. The predicate is
deterministic if at least one of the arguments is a proper list. It is non-deterministic if both
arguments are partial lists.

See also length/2

reverse(?List1, ?List2)
Is true when the elements of List2 are in reverse order compared to List1.

permutation(?Xs, ?Ys) [nondet]

True when Xs is a permutation of Ys. This can solve for Ys given Xs or Xs given Ys, or even
enumerate Xs and Ys together. The predicate permutation/2 is primarily intended to
generate permutations. Note that a list of length N has N! permutations, and unbounded
permutation generation becomes prohibitively expensive, even for rather short lists (10! =
3,628,800).
If both Xs and Ys are provided and both lists have equal length the order is |Xs|2. Simply
testing whether Xs is a permutation of Ys can be achieved in order log(|Xs|) using msort/2
as illustrated below with the semidet predicate is permutation/2:

is_permutation(Xs, Ys) :-
msort(Xs, Sorted),
msort(Ys, Sorted).

The example below illustrates that Xs and Ys being proper lists is not a sufficient condition to
use the above replacement.

?- permutation([1,2], [X,Y]).
X = 1, Y = 2 ;
X = 2, Y = 1 ;
false.

Errors type_error(list, Arg) if either argument is not a proper or partial list.

flatten(+NestedList, -FlatList) [det]

Is true if FlatList is a non-nested version of NestedList. Note that empty lists are removed. In
standard Prolog, this implies that the atom [] is removed too. In SWI7, [] is distinct from
[].
Ending up needing flatten/2 often indicates, like append/3 for appending two lists, a bad
design. Efficient code that generates lists from generated small lists must use difference lists,
often possible through grammar rules for optimal readability.

SWI-Prolog 7.4 Reference Manual

446 APPENDIX A. THE SWI-PROLOG LIBRARY

See also append/2

max member(-Max, +List) [semidet]

True when Max is the largest member in the standard order of terms. Fails if List is empty.

See also
- compare/3
- max list/2 for the maximum of a list of numbers.

min member(-Min, +List) [semidet]

True when Min is the smallest member in the standard order of terms. Fails if List is empty.

See also
- compare/3
- min list/2 for the minimum of a list of numbers.

sum list(+List, -Sum) [det]

Sum is the result of adding all numbers in List.

max list(+List:list(number), -Max:number) [semidet]

True if Max is the largest number in List. Fails if List is empty.

See also max member/2.

min list(+List:list(number), -Min:number) [semidet]

True if Min is the smallest number in List. Fails if List is empty.

See also min member/2.

numlist(+Low, +High, -List) [semidet]

List is a list [Low, Low+1, ... High]. Fails if High < Low.

Errors
- type_error(integer, Low)
- type_error(integer, High)

is set(@Set) [semidet]
True if Set is a proper list without duplicates. Equivalence is based on ==/2. The implemen-
tation uses sort/2, which implies that the complexity is N*log(N) and the predicate may
cause a resource-error. There are no other error conditions.

list to set(+List, ?Set) [det]

True when Set has the same elements as List in the same order. The left-most copy of duplicate
elements is retained. List may contain variables. Elements E1 and E2 are considered duplicates
iff E1 == E2 holds. The complexity of the implementation is N*log(N).

Errors List is type-checked.

See also sort/2 can be used to create an ordered set. Many set operations on ordered sets are order
N rather than order N**2. The list to set/2 predicate is more expensive than sort/2
because it involves, two sorts and a linear scan.
Compatibility Up to version 6.3.11, list to set/2 had complexity N**2 and equality was tested
using =/2.

SWI-Prolog 7.4 Reference Manual

A.16. LIBRARY(NB SET): NON-BACKTRACKABLE SET 447

intersection(+Set1, +Set2, -Set3) [det]

True if Set3 unifies with the intersection of Set1 and Set2. The complexity of this predicate is
|Set1|*|Set2|

See also ord intersection/3.

union(+Set1, +Set2, -Set3) [det]

True if Set3 unifies with the union of Set1 and Set2. The complexity of this predicate is
|Set1|*|Set2|

See also ord union/3.

subset(+SubSet, +Set) [semidet]

True if all elements of SubSet belong to Set as well. Membership test is based on
memberchk/2. The complexity is |SubSet|*|Set|.

See also ord subset/2.

subtract(+Set, +Delete, -Result) [det]

Delete all elements in Delete from Set. Deletion is based on unification using memberchk/2.
The complexity is |Delete|*|Set|.

See also ord subtract/3.

A.16 library(nb set): Non-backtrackable set

The library nb set defines non-backtrackable sets, implemented as binary trees. The sets are repre-
sented as compound terms and manipulated using nb setarg/3. Non-backtrackable manipulation
of datastructures is not supported by a large number of Prolog implementations, but it has several
advantages over using the database. It produces less garbage, is thread-safe, reentrant and deals with
exceptions without leaking data.
Similar to the assoc library, keys can be any Prolog term, but it is not allowed to instantiate or
modify a term.
One of the ways to use this library is to generate unique values on backtracking without generating
all solutions first, for example to act as a filter between a generator producing many duplicates and an
expensive test routine, as outlined below:

generate_and_test(Solution) :-
empty_nb_set(Set),
generate(Solution),
add_nb_set(Solution, Set, true),
test(Solution).

empty nb set(?Set)
True if Set is a non-backtrackable empty set.

SWI-Prolog 7.4 Reference Manual

448 APPENDIX A. THE SWI-PROLOG LIBRARY

add nb set(+Key, !Set)

Add Key to Set. If Key is already a member of Set, add nb set/3 succeeds without modifying
Set.

add nb set(+Key, !Set, ?New)

If Key is not in Set and New is unified to true, Key is added to Set. If Key is in Set, New is
unified to false. It can be used for many purposes:

add nb set(+, +, false) Test membership

add nb set(+, +, true) Succeed only if new member
add nb set(+, +, Var) Succeed, binding Var

gen nb set(+Set, -Key)

Generate all members of Set on backtracking in the standard order of terms. To test member-
ship, use add nb set/3.

size nb set(+Set, -Size)

Unify Size with the number of elements in Set.

nb set to list(+Set, -List)

Unify List with a list of all elements in Set in the standard order of terms (i.e., an ordered list).

A.17 library(www browser): Activating your Web-browser

This library deals with the very system-dependent task of opening a web page in a browser. See also
url and the HTTP package.

www open url(+URL)

Open URL in an external web browser. The reason to place this in the library is to centralise
the maintenance on this highly platform- and browser-specific task. It distinguishes between
the following cases:

MS-Windows
If it detects MS-Windows it uses win shell/2 to open the URL. The behaviour and
browser started depends on the version of Windows and Windows-shell configuration, but
in general it should be the behaviour expected by the user.
Other platforms
On other platforms it tests the environment variable (see getenv/2) named BROWSER
or uses netscape if this variable is not set. If the browser is either mozilla or
netscape, www open url/1 first tries to open a new window on a running browser
using the -remote option of Netscape. If this fails or the browser is not mozilla or
netscape the system simply passes the URL as first argument to the program.

A.18 library(option): Option list processing

See also
- library(record)
- Option processing capabilities may be declared using the directive predicate options/3.

SWI-Prolog 7.4 Reference Manual

A.18. LIBRARY(OPTION): OPTION LIST PROCESSING 449

To be done We should consider putting many options in an assoc or record with appropriate preprocessing
to achieve better performance.

The library(option) provides some utilities for processing option lists. Option lists are
commonly used as an alternative for many arguments. Examples of built-in predicates are open/4
and write term/3. Naming the arguments results in more readable code, and the list nature makes
it easy to extend the list of options accepted by a predicate. Option lists come in two styles, both of
which are handled by this library.

Name(Value) This is the preferred style.

Name = Value This is often used, but deprecated.

Processing options inside time-critical code (loops) can cause serious overhead. One possibility is
to define a record using library(record) and initialise this using make <record>/2. In addition
to providing good performance, this also provides type-checking and central declaration of defaults.

:- record atts(width:integer=100, shape:oneof([box,circle])=box).

process(Data, Options) :-
make_atts(Options, Attributes),
action(Data, Attributes).

action(Data, Attributes) :-
atts_shape(Attributes, Shape),
...

Options typically have exactly one argument. The library does support options with 0 or more
than one argument with the following restrictions:

The predicate option/3 and select option/4, involving default are meaningless. They
perform an arg(1, Option, Default), causing failure without arguments and filling
only the first option-argument otherwise.
meta options/3 can only qualify options with exactly one argument.

option(?Option, +OptionList, +Default) [semidet]

Get an Option from OptionList. OptionList can use the Name=Value as well as the Name(Value)
convention.
Arguments
Option Term of the form Name(?Value).
option(?Option, +OptionList) [semidet]
Get an Option from OptionList. OptionList can use the Name=Value as well as the Name(Value)
convention. Fails silently if the option does not appear in OptionList.
Arguments
Option Term of the form Name(?Value).

SWI-Prolog 7.4 Reference Manual

450 APPENDIX A. THE SWI-PROLOG LIBRARY

select option(?Option, +Options, -RestOptions) [semidet]

Get and remove Option from an option list. As option/2, removing the matching option
from Options and unifying the remaining options with RestOptions.

select option(?Option, +Options, -RestOptions, +Default) [det]

Get and remove Option with default value. As select option/3, but if Option is not in
Options, its value is unified with Default and RestOptions with Options.

merge options(+New, +Old, -Merged) [det]

Merge two option lists. Merged is a sorted list of options using the canonical format
Name(Value) holding all options from New and Old, after removing conflicting options from
Old.
Multi-values options (e.g., proxy(Host, Port)) are allowed, where both option-name and
arity define the identity of the option.

meta options(+IsMeta, :Options0, -Options) [det]

Perform meta-expansion on options that are module-sensitive. Whether an option name is
module-sensitive is determined by calling call(IsMeta, Name). Here is an example:

meta_options(is_meta, OptionsIn, Options),

...

is_meta(callback).

Meta-options must have exactly one argument. This argument will be qualified.

To be done Should be integrated with declarations from predicate options/3.

dict options(?Dict, ?Options) [det]

Convert between an option list and a dictionary. One of the arguments must be instantiated.
If the option list is created, it is created in canonical form, i.e., using Option(Value) with the
Options sorted in the standard order of terms. Note that the conversion is not always possible
due to different constraints and convertion may thus lead to (type) errors.

Dict keys can be integers. This is not allowed in canonical option lists.
Options can hold multiple options with the same key. This is not allowed in dicts.
Options can have more than one value (name(V1,V2)). This is not allowed in dicts.

Also note that most system predicates and predicates using this library for processing the option
argument can both work with classical Prolog options and dicts objects.

A.19 library(optparse): command line parsing

author Marcus Uneson
version 0.20 (2011-04-27)
To be done : validation? e.g, numbers; file path existence; one-out-of-a-set-of-atoms

SWI-Prolog 7.4 Reference Manual

A.19. LIBRARY(OPTPARSE): COMMAND LINE PARSING 451

This module helps in building a command-line interface to an application. In particular, it provides

functions that take an option specification and a list of atoms, probably given to the program on the
command line, and return a parsed representation (a list of the customary Key(Val) by default; or
optionally, a list of Func(Key, Val) terms in the style of current prolog flag/2). It can also
synthesize a simple help text from the options specification.
The terminology in the following is partly borrowed from python, see http://docs.
python.org/library/optparse.html#terminology . Very briefly, arguments is what
you provide on the command line and for many prologs show up as a list of atoms Args in
current_prolog_flag(argv, Args). For a typical prolog incantation, they can be divided
into

runtime arguments, which controls the prolog runtime; conventionally, they are ended by ;

options, which are key-value pairs (with a boolean value possibly implicit) intended to control
your program in one way or another; and

positional arguments, which is what remains after all runtime arguments and options have been
removed (with implicit arguments true/false for booleans filled in).

Positional arguments are in particular used for mandatory arguments without which your program
wont work and for which there are no sensible defaults (e.g,, input file names). Options, by contrast,
offer flexibility by letting you change a default setting. Options are optional not only by etymology:
this library has no notion of mandatory or required options (see the python docs for other rationales
than laziness).
The command-line arguments enter your program as a list of atoms, but the programs perhaps
expects booleans, integers, floats or even prolog terms. You tell the parser so by providing an options
specification. This is just a list of individual option specifications. One of those, in turn, is a list of
ground prolog terms in the customary Name(Value) format. The following terms are recognized (any
others raise error).

opt(Key)
Key is what the option later will be accessed by, just like for
current_prolog_flag(Key, Value). This term is mandatory (an error is thrown if
missing).

shortflags(ListOfFlags)
ListOfFlags denotes any single-dashed, single letter args specifying the current option
(-s , -K, etc). Uppercase letters must be quoted. Usually ListOfFlags will be a singleton
list, but sometimes aliased flags may be convenient.

longflags(ListOfFlags)
ListOfFlags denotes any double-dashed arguments specifying the current option
(--verbose, --no-debug, etc). They are basically a more readable alternative to
short flags, except

1. long flags can be specified as --flag value or --flag=value (but not as

--flagvalue); short flags as -f val or -fval (but not -f=val)

SWI-Prolog 7.4 Reference Manual

452 APPENDIX A. THE SWI-PROLOG LIBRARY

2. boolean long flags can be specified as --bool-flag or --bool-flag=true

or --bool-flag true; and they can be negated as --no-bool-flag or
--bool-flag=false or --bool-flag false.
Except that shortflags must be single characters, the distinction between long and short is in
calling convention, not in namespaces. Thus, if you have shortflags([v]), you can use it
as -v2 or -v 2 or --v=2 or --v 2 (but not -v=2 or --v2).
Shortflags and longflags both default to []. It can be useful to have flagless options see
example below.

meta(Meta)
Meta is optional and only relevant for the synthesized usage message and is the name (an atom)
of the metasyntactic variable (possibly) appearing in it together with type and default value
(e.g, x:integer=3, interest:float=0.11). It may be useful to have named variables
(x, interest) in case you wish to mention them again in the help text. If not given the
Meta: part is suppressed see example below.

type(Type)
Type is one of boolean, atom, integer, float, term. The corresponding argu-
ment will be parsed appropriately. This term is optional; if not given, defaults to term.

default(Default)
Default value. This term is optional; if not given, or if given the special value , an uninstan-
tiated variable is created (and any type declaration is ignored).

help(Help)
Help is (usually) an atom of text describing the option in the help text. This term is optional
(but obviously strongly recommended for all options which have flags).
Long lines are subject to basic word wrapping split on white space, reindent, rejoin. However,
you can get more control by supplying the line breaking yourself: rather than a single line of
text, you can provide a list of lines (as atoms). If you do, they will be joined with the appropriate
indent but otherwise left untouched (see the option mode in the example below).

Absence of mandatory option specs or the presence of more than one for a particular option throws
an error, as do unknown or incompatible types.
As a concrete example from a fictive application, suppose we want the following options to be
read from the command line (long flag(s), short flag(s), meta:type=default, help)

--mode -m atom=SCAN data gathering mode,

one of
SCAN: do this
READ: do that
MAKE: make numbers
WAIT: do nothing
--rebuild-cache -r boolean=true rebuild cache in
each iteration
--heisenberg-threshold -t,-h float=0.1 heisenberg threshold
--depths, --iters -i,-d K:integer=3 stop after K

SWI-Prolog 7.4 Reference Manual

A.19. LIBRARY(OPTPARSE): COMMAND LINE PARSING 453

iterations
--distances term=[1,2,3,5] initial prolog term
--output-file -o FILE:atom=_ write output to FILE
--label -l atom=REPORT report label
--verbosity -v V:integer=2 verbosity level,
1 <= V <= 3

We may also have some configuration parameters which we currently think not needs to be con-
trolled from the command line, say path(/some/file/path).
This interface is described by the following options specification (order between the specifications
of a particular option is irrelevant).

ExampleOptsSpec =
[ [opt(mode ), type(atom), default(SCAN),
shortflags([m]), longflags([mode] ),
help([ data gathering mode, one of
, SCAN: do this
, READ: do that
, MAKE: fabricate some numbers
, WAIT: dont do anything])]

, [opt(cache), type(boolean), default(true),

shortflags([r]), longflags([rebuild-cache]),
help(rebuild cache in each iteration)]

, [opt(threshold), type(float), default(0.1),

shortflags([t,h]), longflags([heisenberg-threshold]),
help(heisenberg threshold)]

, [opt(depth), meta(K), type(integer), default(3),

shortflags([i,d]),longflags([depths,iters]),
help(stop after K iterations)]

, [opt(distances), default([1,2,3,5]),
longflags([distances]),
help(initial prolog term)]

, [opt(outfile), meta(FILE), type(atom),

shortflags([o]), longflags([output-file]),
help(write output to FILE)]

, [opt(label), type(atom), default(REPORT),

shortflags([l]), longflags([label]),
help(report label)]

, [opt(verbose), meta(V), type(integer), default(2),

shortflags([v]), longflags([verbosity]),

SWI-Prolog 7.4 Reference Manual

454 APPENDIX A. THE SWI-PROLOG LIBRARY

help(verbosity level, 1 <= V <= 3)]

, [opt(path), default(/some/file/path/)]
].

The help text above was accessed by opt_help(ExamplesOptsSpec, HelpText). The

options appear in the same order as in the OptsSpec.
Given ExampleOptsSpec, a command line (somewhat syntactically inconsistent, in order to
demonstrate different calling conventions) may look as follows

ExampleArgs = [ -d5
, --heisenberg-threshold, 0.14
, --distances=[1,1,2,3,5,8]
, --iters, 7
, -ooutput.txt
, --rebuild-cache, true
, input.txt
, --verbosity=2
].

opt_parse(ExampleOptsSpec, ExampleArgs, Opts, PositionalArgs)

would then succeed with

Opts = [ mode(SCAN)
, label(REPORT)
, path(/some/file/path)
, threshold(0.14)
, distances([1,1,2,3,5,8])
, depth(7)
, outfile(output.txt)
, cache(true)
, verbose(2)
],
PositionalArgs = [input.txt].

Note that path(/some/file/path) showing up in Opts has a default value (of the im-
plicit type term), but no corresponding flags in OptsSpec. Thus it cant be set from the command
line. The rest of your program doesnt need to know that, of course. This provides an alternative
to the common practice of asserting such hard-coded parameters under a single predicate (for in-
stance setting(path, /some/file/path)), with the advantage that you may seamlessly
upgrade them to command-line options, should you one day find this a good idea. Just add an ap-
propriate flag or two and a line of help text. Similarly, suppressing an option in a cluttered interface
amounts to commenting out the flags.
opt parse/5 allows more control through an additional argument list as shown in the example
below.

SWI-Prolog 7.4 Reference Manual

A.19. LIBRARY(OPTPARSE): COMMAND LINE PARSING 455

?- opt_parse(ExampleOptsSpec, ExampleArgs, Opts, PositionalArgs,

[ output_functor(appl_config)
]).

Opts = [ appl_config(verbose, 2),

, appl_config(label, REPORT)
...
]

This representation may be preferable with the empty-flag configuration parameter style above
(perhaps with asserting appl config/2).

A.19.1 Notes and tips

In the example we were mostly explicit about the types. Since the default is term, which
subsumes integer, float, atom, it may be possible to get away cheaper (e.g., by only
giving booleans). However, it is recommended practice to always specify types: parsing be-
comes more reliable and error messages will be easier to interpret.

Note that -sbar is taken to mean -s bar, not -s -b -a -r, that is, there is no clustering
of flags.

-s=foo is disallowed. The rationale is that although some command-line parsers will silently
interpret this as -s =foo, this is very seldom what you want. To have an option argument start
with = (very un-recommended), say so explicitly.

The example specifies the option depth twice: once as -d5 and once as --iters 7. The
default when encountering duplicated flags is to keeplast (this behaviour can be controlled,
by ParseOption duplicated flags).

The order of the options returned by the parsing functions is the same as given on the command
line, with non-overridden defaults prepended and duplicates removed as in previous item. You
should not rely on this, however.

Unknown flags (not appearing in OptsSpec) will throw errors. This is usually a Good Thing.
Sometimes, however, you may wish to pass along flags to an external program (say, one called
by shell/2), and it means duplicated effort and a maintenance headache to have to specify
all possible flags for the external program explicitly (if it even can be done). On the other
hand, simply taking all unknown flags as valid makes error checking much less efficient and
identification of positional arguments uncertain. A better solution is to collect all arguments
intended for passing along to an indirectly called program as a single argument, probably as an
atom (if you dont need to inspect them first) or as a prolog term (if you do).

opt arguments(+OptsSpec, -Opts, -PositionalArgs) [det]

Extract commandline options according to a specification. Convenience predicate, assuming

SWI-Prolog 7.4 Reference Manual

456 APPENDIX A. THE SWI-PROLOG LIBRARY

that command-line arguments can be accessed by current prolog flag/2 (as in swi-
prolog). For other access mechanisms and/or more control, get the args and pass them as a list
of atoms to opt parse/4 or opt parse/5 instead.
Opts is a list of parsed options in the form Key(Value). Dashed args not in OptsSpec are not
permitted and will raise error (see tip on how to pass unknown flags in the module description).
PositionalArgs are the remaining non-dashed args after each flag has taken its argument (filling
in true or false for booleans). There are no restrictions on non-dashed arguments and they
may go anywhere (although it is good practice to put them last). Any leading arguments for the
runtime (up to and including ) are discarded.

opt parse(+OptsSpec, +ApplArgs, -Opts, -PositionalArgs) [det]

Equivalent to opt_parse(OptsSpec, ApplArgs, Opts, PositionalArgs, []).

opt parse(+OptsSpec, +ApplArgs, -Opts, -PositionalArgs, +ParseOptions) [det]

Parse the arguments Args (as list of atoms) according to OptsSpec. Any runtime arguments
(typically terminated by ) are assumed to be removed already.
Opts is a list of parsed options in the form Key(Value), or (with the option functor(Func)
given) in the form Func(Key, Value). Dashed args not in OptsSpec are not permitted and will
raise error (see tip on how to pass unknown flags in the module description). PositionalArgs are
the remaining non-dashed args after each flag has taken its argument (filling in true or false
for booleans). There are no restrictions on non-dashed arguments and they may go anywhere
(although it is good practice to put them last). ParseOptions are

output functor(Func)
Set the functor Func of the returned options Func(Key,Value). Default is the special value
OPTION (upper-case), which makes the returned options have form Key(Value).
duplicated flags(Keep)
Controls how to handle options given more than once on the commad line. Keep is
one of keepfirst, keeplast, keepall with the obvious meaning. Default is
keeplast.
allow empty flag spec(Bool)
If true (default), a flag specification is not required (it is allowed that both shortflags
and longflags be either [] or absent). Flagless options cannot be manipulated from the
command line and will not show up in the generated help. This is useful when you have
(also) general configuration parameters in your OptsSpec, especially if you think they
one day might need to be controlled externally. See example in the module overview.
allow_empty_flag_spec(false) gives the more customary behaviour of raising
error on empty flags.

opt help(+OptsSpec, -Help:atom) [det]

True when Help is a help string synthesized from OptsSpec.

parse type(+Type, +Codes:list(code), -Result) [semidet,multifile]

Hook to parse option text Codes to an object of type Type.

SWI-Prolog 7.4 Reference Manual

A.20. LIBRARY(ORDSETS): ORDERED SET MANIPULATION 457

A.20 library(ordsets): Ordered set manipulation

Ordered sets are lists with unique elements sorted to the standard order of terms (see sort/2). Ex-
ploiting ordering, many of the set operations can be expressed in order N rather than N2 when
dealing with unordered sets that may contain duplicates. The library(ordsets) is available
in a number of Prolog implementations. Our predicates are designed to be compatible with com-
mon practice in the Prolog community. The implementation is incomplete and relies partly on
library(oset), an older ordered set library distributed with SWI-Prolog. New applications are
advised to use library(ordsets).
Some of these predicates match directly to corresponding list operations. It is advised to use
the versions from this library to make clear you are operating on ordered sets. An exception is
member/2. See ord memberchk/2.
The ordsets library is based on the standard order of terms. This implies it can handle all Prolog
terms, including variables. Note however, that the ordering is not stable if a term inside the set is
further instantiated. Also note that variable ordering changes if variables in the set are unified with
each other or a variable in the set is unified with a variable that is older than the newest variable in
the set. In practice, this implies that it is allowed to use member(X, OrdSet) on an ordered set
that holds variables only if X is a fresh variable. In other cases one should cease using it as an ordset
because the order it relies on may have been changed.

is ordset(@Term) [semidet]
True if Term is an ordered set. All predicates in this library expect ordered sets as input argu-
ments. Failing to fullfil this assumption results in undefined behaviour. Typically, ordered sets
are created by predicates from this library, sort/2 or setof/3.

ord empty(?List) [semidet]

True when List is the empty ordered set. Simply unifies list with the empty list. Not part of
Quintus.

ord seteq(+Set1, +Set2) [semidet]

True if Set1 and Set2 have the same elements. As both are canonical sorted lists, this is the
same as ==/2.

Compatibility sicstus

list to ord set(+List, -OrdSet) [det]

Transform a list into an ordered set. This is the same as sorting the list.

ord intersect(+Set1, +Set2) [semidet]

True if both ordered sets have a non-empty intersection.

ord disjoint(+Set1, +Set2) [semidet]

True if Set1 and Set2 have no common elements. This is the negation of ord intersect/2.

ord intersect(+Set1, +Set2, -Intersection)

Intersection holds the common elements of Set1 and Set2.

deprecated Use ord intersection/3

SWI-Prolog 7.4 Reference Manual

458 APPENDIX A. THE SWI-PROLOG LIBRARY

ord intersection(+PowerSet, -Intersection)

Intersection of a powerset. True when Intersection is an ordered set holding all elements
common to all sets in PowerSet.

Compatibility sicstus

ord intersection(+Set1, +Set2, -Intersection) [det]

Intersection holds the common elements of Set1 and Set2.

ord intersection(+Set1, +Set2, ?Intersection, ?Difference) [det]

Intersection and difference between two ordered sets. Intersection is
the intersection between Set1 and Set2, while Difference is defined by
ord_subtract(Set2, Set1, Difference).

See also ord intersection/3 and ord subtract/3.

ord add element(+Set1, +Element, ?Set2) [det]

Insert an element into the set. This is the same as
ord_union(Set1, [Element], Set2).

ord del element(+Set, +Element, -NewSet) [det]

Delete an element from an ordered set. This is the same as
ord_subtract(Set, [Element], NewSet).

ord selectchk(+Item, ?Set1, ?Set2) [semidet]

Selectchk/3, specialised for ordered sets. Is true when select(Item, Set1, Set2)
and Set1, Set2 are both sorted lists without duplicates. This implementation is only
expected to work for Item ground and either Set1 or Set2 ground. The chk suf-
fix is meant to remind you of memberchk/2, which also expects its first argument
to be ground. ord_selectchk(X, S, T) => ord_memberchk(X, S) & \+
ord_memberchk(X, T).

author Richard OKeefe

ord memberchk(+Element, +OrdSet) [semidet]

True if Element is a member of OrdSet, compared using ==. Note that enumerating elements
of an ordered set can be done using member/2.
Some Prolog implementations also provide ord member/2, with the same semantics as
ord memberchk/2. We believe that having a semidet ord member/2 is unacceptably
inconsistent with the * chk convention. Portable code should use ord memberchk/2 or
member/2.

author Richard OKeefe

ord subset(+Sub, +Super) [semidet]

Is true if all elements of Sub are in Super

ord subtract(+InOSet, +NotInOSet, -Diff) [det]

Diff is the set holding all elements of InOSet that are not in NotInOSet.

SWI-Prolog 7.4 Reference Manual

A.21. LIBRARY(PAIRS): OPERATIONS ON KEY-VALUE LISTS 459

ord union(+SetOfSets, -Union) [det]

True if Union is the union of all elements in the superset SetOfSets. Each member of SetOfSets
must be an ordered set, the sets need not be ordered in any way.

author Copied from YAP, probably originally by Richard OKeefe.

ord union(+Set1, +Set2, ?Union) [det]

Union is the union of Set1 and Set2

ord union(+Set1, +Set2, -Union, -New) [det]

True iff ord_union(Set1, Set2, Union) and ord_subtract(Set2, Set1, New).

ord symdiff(+Set1, +Set2, ?Difference) [det]

Is true when Difference is the symmetric difference of Set1 and Set2. I.e., Difference contains
all elements that are not in the intersection of Set1 and Set2. The semantics is the same as the
sequence below (but the actual implementation requires only a single scan).

ord_union(Set1, Set2, Union),

ord_intersection(Set1, Set2, Intersection),
ord_subtract(Union, Intersection, Difference).

For example:

?- ord_symdiff([1,2], [2,3], X).

X = [1,3].

A.21 library(pairs): Operations on key-value lists

author Jan Wielemaker
See also keysort/2, library(assoc)

This module implements common operations on Key-Value lists, also known as Pairs. Pairs have
great practical value, especially due to keysort/2 and the library assoc.pl.
This library is based on disussion in the SWI-Prolog mailinglist, including specifications from
Quintus and a library proposal by Richard OKeefe.

pairs keys values(?Pairs, ?Keys, ?Values) [det]

True if Keys holds the keys of Pairs and Values the values.
Deterministic if any argument is instantiated to a finite list and the others are either free or finite
lists. All three lists are in the same order.

See also pairs values/2 and pairs keys/2.

pairs values(+Pairs, -Values) [det]

Remove the keys from a list of Key-Value pairs. Same as
pairs_keys_values(Pairs, _, Values)

SWI-Prolog 7.4 Reference Manual

460 APPENDIX A. THE SWI-PROLOG LIBRARY

pairs keys(+Pairs, -Keys) [det]

Remove the values from a list of Key-Value pairs. Same as
pairs_keys_values(Pairs, Keys, _)

group pairs by key(+Pairs, -Joined:list(Key-Values)) [det]

Group values with equivalent (==/2) consecutive keys. For example:

?- group_pairs_by_key([a-2, a-1, b-4, a-3], X).

X = [a-[2,1], b-[4], a-[3]]

Sorting the list of pairs before grouping can be used to group all values associated with a key.
For example, finding all values associated with the largest key:

?- sort(1, @>=, [a-1, b-2, c-3, a-4, a-5, c-6], Ps),

group_pairs_by_key(Ps, [K-Vs|_]).
K = c,
Vs = [3, 6].

In this example, sorting by key only (first argument of sort/4 is 1) ensures that the order of
the values in the original list of pairs is maintained.
Arguments
Pairs Key-Value list
Joined List of Key-Group, where Group is the list of Values associated
with equivalent consecutive Keys in the same order as they appear
in Pairs.

transpose pairs(+Pairs, -Transposed) [det]

Swap Key-Value to Value-Key. The resulting list is sorted using keysort/2 on the new key.

map list to pairs(:Function, +List, -Keyed)

Create a Key-Value list by mapping each element of List. For example, if we have a list of lists
we can create a list of Length-List using

map_list_to_pairs(length, ListOfLists, Pairs),

A.22 library(persistency): Provide persistent dynamic predicates

To be done
- Provide type safety while loading
- Thread safety must now be provided at the user-level. Can we provide generic thread safety? Ba-
sically, this means that we must wrap all exported predicates. That might better be done outside this
library.
- Transaction management?
- Should assert <name> only assert if the database does not contain a variant?

SWI-Prolog 7.4 Reference Manual

A.22. LIBRARY(PERSISTENCY): PROVIDE PERSISTENT DYNAMIC PREDICATES 461

This module provides simple persistent storage for one or more dynamic predicates. A database
is always associated with a module. A module that wishes to maintain a database must declare the
terms that can be placed in the database using the directive persistent/1.
The persistent/1 expands each declaration into four predicates:

name(Arg, ...)
assert_name(Arg, ...)
retract_name(Arg, ...)
retractall_name(Arg, ...)

As mentioned, a database can only be accessed from within a single module. This limitation is on
purpose, forcing the user to provide a proper API for accessing the shared persistent data.
Below is a simple example:

:- module(user_db,
[ attach_user_db/1, % +File
current_user_role/2, % ?User, ?Role
add_user/2, % +User, +Role
set_user_role/2 % +User, +Role
]).
:- use_module(library(persistency)).

:- persistent
user_role(name:atom, role:oneof([user,administrator])).

attach_user_db(File) :-
db_attach(File, []).

%% current_user_role(+Name, -Role) is semidet.

current_user_role(Name, Role) :-
with_mutex(user_db, user_role(Name, Role)).

add_user(Name, Role) :-
assert_user_role(Name, Role).

set_user_role(Name, Role) :-
user_role(Name, Role), !.
set_user_role(Name, Role) :-
with_mutex(user_db,
( retractall_user_role(Name, _),
assert_user_role(Name, Role))).

SWI-Prolog 7.4 Reference Manual

462 APPENDIX A. THE SWI-PROLOG LIBRARY

persistent +Spec
Declare dynamic database terms. Declarations appear in a directive and have the following
format:

:- persistent
<callable>,
<callable>,
...

Each specification is a callable term, following the conventions of library(record), where

each argument is of the form

name:type

Types are defined by library(error).

current persistent predicate(:PI) [nondet]

True if PI is a predicate that provides access to the persistent database DB.

db attach(:File, +Options)
Use File as persistent database for the calling module. The calling module must defined
persistent/1 to declare the database terms. Defined options:

sync(+Sync)
One of close (close journal after write), flush (default, flush journal after write) or
none (handle as fully buffered stream).

db detach [det]
Detach persistency from the calling module and delete all persistent clauses from the Prolog
database. Note that the file is not affected. After this operation another file may be attached,
providing it satisfies the same persistency declaration.

db sync(:What)
Synchronise database with the associated file. What is one of:

reload
Database is reloaded from file if the file was modified since loaded.
update
As reload, but use incremental loading if possible. This allows for two processes to
examine the same database file, where one writes the database and the other periodycally
calls db_sync(update) to follow the modified data.
gc
Database was re-written, deleting all retractall statements. This is the same as gc(50).
gc(Percentage)
GC DB if the number of deleted terms is the given percentage of the total number of
terms.

SWI-Prolog 7.4 Reference Manual

A.23. LIBRARY(PIO): PURE I/O 463

close
Database stream was closed
detach
Remove all registered persistency for the calling module
nop
No-operation performed

With unbound What, db sync/1 reloads the database if it was modified on disk, gc it if it is
dirty and close it if it is opened.

db sync all(+What)
Sync all registered databases.

A.23 library(pio): Pure I/O

This library provides pure list-based I/O processing for Prolog, where the communication to the actual
I/O device is performed transparently through coroutining. This module itself is just an interface to
the actual implementation modules.

A.23.1 library(pure input): Pure Input from files and streams

To be done Provide support for alternative input readers, e.g. reading terms, tokens, etc.

This module is part of pio.pl, dealing with pure input: processing input streams from the
outside world using pure predicates, notably grammar rules (DCG). Using pure predicates makes
non-deterministic processing of input much simpler.
Pure input uses attributed variables to read input from the external source into a list on de-
mand. The overhead of lazy reading is more than compensated for by using block reads based on
read pending codes/3.
Ulrich Neumerkel came up with the idea to use coroutining for creating a lazy list. His implemen-
tation repositioned the file to deal with re-reading that can be necessary on backtracking. The current
implementation uses destructive assignment together with more low-level attribute handling to realise
pure input on any (buffered) stream.

phrase from file(:Grammar, +File) [nondet]

Process the content of File using the DCG rule Grammar. The space usage of this mechanism
depends on the length of the not committed part of Grammar. Committed parts of the
temporary list are reclaimed by the garbage collector, while the list is extended on demand
due to unification of the attributed tail variable. Below is an example that counts the number
of times a string appears in a file. The library dcg/basics provides string//1 matching
an arbitrary string and remainder//1 which matches the remainder of the input without
parsing.

:- use_module(library(dcg/basics)).

file_contains(File, Pattern) :-

SWI-Prolog 7.4 Reference Manual

464 APPENDIX A. THE SWI-PROLOG LIBRARY

phrase_from_file(match(Pattern), File).

match(Pattern) -->
string(_),
string(Pattern),
remainder(_).

match_count(File, Pattern, Count) :-

aggregate_all(count, file_contains(File, Pattern), Count).

This can be called as (note that the pattern must be a string (code list)):

?- match_count(pure_input.pl, file, Count).

phrase from file(:Grammar, +File, +Options) [nondet]

As phrase from file/2, providing additional Options. Options are passed to open/4.

phrase from stream(:Grammer, +Stream)

Run Grammer against the character codes on Stream. Stream must be buffered.

syntax error(+Error) //
Throw the syntax error Error at the current location of the input. This predicate is designed to
be called from the handler of phrase from file/3.

throws error(syntax_error(Error), Location)

lazy list location(-Location) // [det]

Determine current (error) location in a lazy list. True when Location is an (error) location term
that represents the current location in the DCG list.
Arguments
Location is a term file(Name, Line, LinePos, CharNo) or
stream(Stream, Line, LinePos, CharNo) if no file
is associated to the stream RestLazyList. Finally, if the Lazy
list is fully materialized (ends in []), Location is unified with
end_of_file-CharCount.

See also lazy list character count//1 only provides the character count.

lazy list character count(-CharCount) //

True when CharCount is the current character count in the Lazy list. The character count is
computed by finding the distance to the next frozen tail of the lazy list. CharCount is one of:

An integer
A term end of file-Count

See also lazy list location//1 provides full details of the location for error reporting.

SWI-Prolog 7.4 Reference Manual

A.24. LIBRARY(PREDICATE OPTIONS): DECLARE OPTION-PROCESSING OF
PREDICATES 465

stream to lazy list(+Stream, -List) [det]

Create a lazy list representing the character codes in Stream. List is a partial list ending in an
attributed variable. Unifying this variable reads the next block of data. The block is stored with
the attribute value such that there is no need to re-read it.
Compatibility Unlike the previous version of this predicate this version does not require a reposition-
able stream. It does require a buffer size of at least the maximum number of bytes of a multi-byte
sequence (6).

A.24 library(predicate options): Declare option-processing of predi-

cates
Discussions with Jeff Schultz helped shaping this library

A.24.1 The strength and weakness of predicate options

Many ISO predicates accept options, e.g., open/4, write term/3. Options offer an attractive
alternative to proliferation into many predicates and using high-arity predicates. Properly defined and
used, they also form a mechanism for extending the API of both system and application predicates
without breaking portability. I.e., previously fixed behaviour can be replaced by dynamic behaviour
controlled by an option where the default is the previously defined fixed behaviour. The alternative to
using options is to add an additional argument and maintain the previous definition. While a series of
predicates with increasing arity is adequate for a small number of additional parameters, the untyped
positional argument handling of Prolog quickly makes this unmanageable.
The ISO standard uses the extensibility offered by options by allowing implementations to extend
the set of accepted options. While options form a perfect solution to maintain backward portability in
a linear development model, it is not well equipped to deal with concurrent branches because

1. There is no API to find which options are supported in a particular implementation.

2. While the portability problem caused by a missing predicate in Prolog A can easily be solved
by implementing this predicate, it is much harder to add processing of an additional option to
an already existing predicate.

Different Prolog implementations can be seen as concurrent development branches of the Prolog
language. Different sets of supported options pose a serious portability issue. Using an option O that
establishes the desired behaviour on system A leads (on most systems) to an error or system B. Porting
may require several actions:

Drop O (if the option is not vital, such as the layout options to write term/3)
Replace O by O2 (i.e., a differently named option doing the same)
Something else (cannot be ported; requires a totally different approach, etc.)

Predicates that process options are particularly a problem when writing a compatibility layer to
run programs developed for System A on System B because complete emulation is often hard, may
cause a serious slowdown and is often not needed because the application-to-be-ported only uses
options that are shared by all target Prolog implementations. Unfortunately, the consequences of a
partial emulation cannot be assessed by tools.

SWI-Prolog 7.4 Reference Manual

466 APPENDIX A. THE SWI-PROLOG LIBRARY

A.24.2 Options as arguments or environment?

We distinguish two views on options. One is to see them as additional parameters that require strict
existence, type and domain-checking and the other is to consider them locally scoped environment
variables. Most systems adopt the first option. SWI-Prolog adopts the second: it silently ignores
options that are not supported but does type and domain checking of option-values. The environment
view is commonly used in applications to create predicates supporting more options using the skeleton
below. This way of programming requires that pred1 and pred2 do not interpret the same option
differently. In cases where this is not true, the options must be distributed by some pred. We have
been using this programming style for many years and in practice it turns out that the need for active
distribution of options is rare. I.e., options either have distinct names or multiple predicates implement
the same option but this has the desired effect. An example of the latter is the encoding option,
which typically needs to be applied consistently.

some_pred(..., Options) :-
pred1(..., Options),
pred2(..., Options).

As stated before, options provide a readable alternative to high-arity predicates and offer a robust
mechanism to evolve the API, but at the cost of some runtime overhead and weaker consistency
checking, both at compiletime and runtime. From our experience, the environment approach is
productive, but the consequence is that mistyped options are silently ignored. The option infrastructure
described in this section tries to remedy these problems.

A.24.3 Improving on the current situation

Whether we see options as arguments or locally scoped environment variables, the most obvious
way to improve on the current situation is to provide reflective support for options: discover that an
argument is an option-list and find what options are supported. Reflective access to options can be
used by the compiler and development environment as well as by the runtime system to warn or throw
errors.

Options as types
An obvious approach to deal with options is to define the different possible option values as a type and
type the argument that processes the option as list(<option type>), as illustrated below. Considering
options as types fully covers the case where we consider options as additional parameters.

:- type open_option ---> type(stream_type) |

alias(atom) | ... .
:- pred open(source_sink, open_mode, stream, list(open_option)).

There are three reasons for considering a different approach:

There is no consensus about types in the Prolog world, neither about what types should look
like, nor whether or not they are desirable. It is not likely that this debate will be resolved
shortly.

SWI-Prolog 7.4 Reference Manual

A.24. LIBRARY(PREDICATE OPTIONS): DECLARE OPTION-PROCESSING OF
PREDICATES 467

Considering options as types does not support the environment view, which we consider the
most productive.

Even when using types, we need reflective access to what options are provided in order to be
able to write compile or runtime conditional code.

Reflective access to options

From the above, we conclude that we require reflective access to find out whether an option is sup-
ported and valid for a particular predicate. Possible option values must be described by types. Due
to lack of a type system, we use library(error) to describe allowed option values. Predicate
options are declared using predicate options/3:

predicate options(:PI, +Arg, +Options) [det]

Declare that the predicate PI processes options on Arg. Options is a list of options processed.
Each element is one of:

Option(ModeAndType) PI processes Option. The option-value must comply to Mode-

AndType. Mode is one of + or - and Type is a type as accepted by must be/2.
pass to(:PI,Arg) The option-list is passed to the indicated predicate.

Below is an example that processes the option header(boolean) and passes all options to
open/4:

:- predicate_options(write_xml_file/3, 3,
[ header(boolean),
pass_to(open/4, 4)
]).

write_xml_file(File, XMLTerm, Options) :-

open(File, write, Out, Options),
( option(header(true), Option, true)
-> write_xml_header(Out)
; true
),
...

This predicate may only be used as a directive and is processed by expand term/2. Option
processing can be specified at runtime using assert predicate options/3, which is
intended to support program analysis.

assert predicate options(:PI, +Arg, +Options, ?New) [semidet]

As predicate options(:PI, +Arg, +Options). New is a boolean indicating whether the declara-
tions have changed. If New is provided and false, the predicate becomes semidet and fails
without modifications if modifications are required.

The predicates below realise the support for compile and runtime checking for supported options.

SWI-Prolog 7.4 Reference Manual

468 APPENDIX A. THE SWI-PROLOG LIBRARY

current predicate option(:PI, ?Arg, ?Option) [nondet]

True when Arg of PI processes Option. For example, the following is true:

?- current_predicate_option(open/4, 4, type(text)).
true.

This predicate is intended to support conditional compilation using if/1 ... endif/0. The
predicate current predicate options/3 can be used to access the full capabilities of a
predicate.
check predicate option(:PI, +Arg, +Option) [det]
Verify predicate options at runtime. Similar to current predicate option/3, but in-
tended to support runtime checking.
Errors
- existence_error(option, OptionName) if the option is not supported by PI.
- type_error(Type, Value) if the option is supported but the value does not match the
option type. See must be/2.

The predicates below can be used in a development environment to inform the user about sup-
ported options. PceEmacs uses this for colouring option names and values.
current option arg(:PI, ?Arg) [nondet]
True when Arg of PI processes predicate options. Which options are processed can be accessed
using current predicate option/3.
current predicate options(:PI, ?Arg, ?Options) [nondet]
True when Options is the current active option declaration for PI on Arg. See
predicate options/3 for the argument descriptions. If PI is ground and refers to
an undefined predicate, the autoloader is used to obtain a definition of the predicate.
The library can execute a complete check of your program using
check predicate options/0:
check predicate options [det]
Analyse loaded program for erroneous options. This predicate decompiles the current program
and searches for calls to predicates that process options. For each option list, it validates
whether the provided options are supported and validates the argument type. This predicate
performs partial dataflow analysis to track option-lists inside a clause.
See also derive predicate options/0 can be used to derive declarations for
predicates that pass options. This predicate should normally be called before
check predicate options/0.

The library offers predicates that may be used to create declarations for your application. These
predicates are designed to cooperate with the module system.
derive predicate options [det]
Derive new predicate option declarations. This predicate analyses the loaded program to find
clauses that process options using one of the predicates from library(option) or passes
options to other predicates that are known to process options. The process is repeated until no
new declarations are retrieved.

SWI-Prolog 7.4 Reference Manual

A.25. LIBRARY(PROLOG PACK): A PACKAGE MANAGER FOR PROLOG 469

See also autoload/0 may be used to complete the loaded program.

retractall predicate options [det]

Remove all dynamically (derived) predicate options.

derived predicate options(:PI, ?Arg, ?Options) [nondet]

Derive option arguments using static analysis. True when Options is the current derived active
option declaration for PI on Arg.

derived predicate options(+Module) [det]

Derive predicate option declarations for a module. The derived options are printed to the
current_output stream.

A.25 library(prolog pack): A package manager for Prolog

See also Installed packages can be inspected using ?- doc_browser.
To be done
- Version logic
- Find and resolve conflicts
- Upgrade git packages
- Validate git packages
- Test packages: run tests from directory test.

The library(prolog_pack) provides the SWI-Prolog package manager. This library lets
you inspect installed packages, install packages, remove packages, etc. It is complemented by the
built-in attach packs/0 that makes installed packages available as libaries.

pack list installed [det]

List currently installed packages. Unlike pack list/1, only locally installed packages are
displayed and no connection is made to the internet.

See also Use pack list/1 to find packages.

pack info(+Pack)
Print more detailed information about Pack.

pack search(+Query) [det]

pack list(+Query) [det]
Query package server and installed packages and display results. Query is matches case-
insensitively against the name and title of known and installed packages. For each matching
package, a single line is displayed that provides:

Installation status
p: package, not installed
i: installed package; up-to-date with public version
U: installed package; can be upgraded
A: installed package; newer than publically available

SWI-Prolog 7.4 Reference Manual

470 APPENDIX A. THE SWI-PROLOG LIBRARY

l: installed package; not on server

Name@Version
Name@Version(ServerVersion)
Title

Hint: ?- pack_list(). lists all packages.

The predicates pack list/1 and pack search/1 are synonyms. Both contact the package
server at http://www.swi-prolog.org to find available packages.

See also pack list installed/0 to list installed packages without contacting the server.

pack install(+Spec:atom) [det]

Install a package. Spec is one of

Archive file name

HTTP URL of an archive file name. This URL may contain a star (*) for the version. In
this case pack install asks for the deirectory content and selects the latest version.
GIT URL (not well supported yet)
A local directory name given as file:// URL.
A package name. This queries the package repository at http://www.swi-prolog.
org

After resolving the type of package, pack install/2 is used to do the actual installation.

pack install(+Name, +Options) [det]

Install package Name. Processes the options below. Default options as would be used by
pack install/1 are used to complete the provided Options.

url(+URL)
Source for downloading the package
package directory(+Dir)
Directory into which to install the package
interactive(+Boolean)
Use default answer without asking the user if there is a default action.
silent(+Boolean)
If true (default false), suppress informational progress messages.
upgrade(+Boolean)
If true (default false), upgrade package if it is already installed.
git(+Boolean)
If true (default false unless URL ends with =.git=), assume the URL is a GIT reposi-
tory.

Non-interactive installation can be established using the option interactive(false). It

is adviced to install from a particular trusted URL instead of the plain pack name for unattented
operation.

SWI-Prolog 7.4 Reference Manual

A.25. LIBRARY(PROLOG PACK): A PACKAGE MANAGER FOR PROLOG 471

pack url file(+URL, -File) [det]

True if File is a unique id for the referenced pack and version. Normally, that is simply the base
name, but GitHub archives destroy this picture. Needed by the pack manager.
pack rebuild(+Pack) [det]
Rebuilt possible foreign components of Pack.
pack rebuild [det]
Rebuild foreign components of all packages.
environment(-Name, -Value) [nondet,multifile]
Hook to define the environment for building packs. This Multifile hook extends the process
environment for building foreign extensions. A value provided by this hook overrules defaults
provided by def environment/2. In addition to changing the environment, this may be
used to pass additional values to the environment, as in:

prolog_pack:environment(USER, User) :-
getenv(USER, User).

Arguments
Name is an atom denoting a valid variable name
Value is either an atom or number representing the value of the variable.
pack upgrade(+Pack) [semidet]
Try to upgrade the package Pack.
To be done Update dependencies when updating a pack from git?

pack remove(+Name) [det]

Remove the indicated package.
pack property(?Pack, ?Property) [nondet]
True when Property is a property of Pack. This interface is intended for programs that wish to
interact with the package manager. Defined properties are:

directory(Directory)
Directory into which the package is installed
version(Version)
Installed version
title(Title)
Full title of the package
author(Author)
Registered author
download(URL)
Official download URL
readme(File)
Package README file (if present)
todo(File)
Package TODO file (if present)

SWI-Prolog 7.4 Reference Manual

472 APPENDIX A. THE SWI-PROLOG LIBRARY

A.26 library(prolog xref): Cross-reference data collection library

This library collects information on defined and used objects in Prolog source files. Typically these
are predicates, but we expect the library to deal with other types of objects in the future. The library is
a building block for tools doing dependency tracking in applications. Dependency tracking is useful
to reveal the structure of an unknown program or detect missing components at compile time, but also
for program transformation or minimising a program saved state by only saving the reachable objects.
This section gives a partial description of the library API, providing some insight in how you can
use it for analysing your program. The library should be further modularized, moving its knowledge
about, for example, XPCE into a different file and allowing for adding knowledge about other libraries
such as Logtalk. Please do not consider this interface rock-solid.
The library is exploited by two graphical tools in the SWI-Prolog environment: the XPCE front-
end started by gxref/0 and described in section 3.7, and PceEmacs (section 3.4), which exploits
this library for its syntax colouring.
For all predicates described below, Source is the source that is processed. This is normally a
filename in any notation acceptable to the file loading predicates (see load files/2). Using the
hooks defined in section A.26.1 it can be anything else that can be translated into a Prolog stream
holding Prolog source text. Callable is a callable term (see callable/1). Callables do not carry a
module qualifier unless the referred predicate is not in the module defined Source.

xref source(+Source)
Gather information on Source. If Source has already been processed and is still up-to-date
according to the file timestamp, no action is taken. This predicate must be called on a file
before information can be gathered.
xref current source(?Source)
Source has been processed.
xref clean(+Source)
Remove the information gathered for Source
xref defined(?Source, ?Callable, -How)
Callable is defined in Source. How is one of

dynamic(Line) Declared dynamic at Line

thread local(Line) Declared thread local at Line
multifile(Line) Declared multifile at Line
local(Line) First clause at Line
foreign(Line) Foreign library loaded at Line
constraint(Line) CHR Constraint at Line
imported(File) Imported from File

xref called(?Source, ?Callable, ?By)

Callable is called in Source by By.
xref exported(?Source, ?Callable)
Callable is public (exported from the module).
xref module(?Source, ?Module)
Source is a module file defining the given module.

SWI-Prolog 7.4 Reference Manual

A.27. LIBRARY(QUASI QUOTATIONS): DEFINE QUASI QUOTATION SYNTAX 473

xref built in(?Callable)

True if Callable is a built-in predicate. Currently this is assumed for all predicates defined in
the system module and having the property built in. Built-in predicates are not registered
as called.

A.26.1 Extending the library

The library provides hooks for extending the rules it uses for finding predicates called by some pro-
gramming construct.

prolog:called by(+Goal, -Called)

Goal is a non-var subgoal appearing in the called object (typically a clause body). If it succeeds
it must return a list of goals called by Goal. As a special construct, if a term Callable + N
is returned, N variable arguments are added to Callable before further processing. For simple
meta-calls a single fact suffices. Complex rules as used in the html write library provided
by the HTTP package examine the arguments and create a list of called objects.
The current system cannot deal with the same name/arity in different modules that behave dif-
ferently with respect to called arguments.

A.27 library(quasi quotations): Define Quasi Quotation syntax

author Jan Wielemaker. Introduction of Quasi Quotation was suggested by Michael Hendricks.
See also Why its nice to be quoted: quasiquoting for haskell

Inspired by Haskell, SWI-Prolog support quasi quotation. Quasi quotation allows for embedding
(long) strings using the syntax of an external language (e.g., HTML, SQL) in Prolog text and syntax-
aware embedding of Prolog variables in this syntax. At the same time, quasi quotation provides an
alternative to represent long strings and atoms in Prolog.
The basic form of a quasi quotation is defined below. Here, Syntax is an arbitrary Prolog term
that must parse into a callable (atom or compound) term and Quotation is an arbitrary sequence of
characters, not including the sequence |}. If this sequence needs to be embedded, it must be escaped
according to the rules of the target language or the quoter must provide an escaping mechanism.

{|Syntax||Quotation|}

While reading a Prolog term, and if the Prolog flag quasi_quotes is set to true (which is the
case if this library is loaded), the parser collects quasi quotations. After reading the final full stop, the
parser makes the call below. Here, SyntaxName is the functor name of Syntax above and SyntaxArgs
is a list holding the arguments, i.e., Syntax =.. [SyntaxName|SyntaxArgs]. Splitting the
syntax into its name and arguments is done to make the quasi quotation parser a predicate with a
consistent arity 4, regardless of the number of additional arguments.

call(+SyntaxName, +Content, +SyntaxArgs, +VariableNames, -Result)

The arguments are defined as

SWI-Prolog 7.4 Reference Manual

474 APPENDIX A. THE SWI-PROLOG LIBRARY

SyntaxName is the principal functor of the quasi quotation syntax. This must be declared using
quasi quotation syntax/1 and there must be a predicate SyntaxName/4.

Content is an opaque term that carries the content of the quasi quoted material and position
information about the source code. It is passed to with quasi quote input/3.

SyntaxArgs carries the additional arguments of the Syntax. These are commonly used to make
the parameter passing between the clause and the quasi quotation explicit. For example:

...,
{|html(Name, Address)||
<tr><td>Name<td>Address</tr>
|}

VariableNames is the complete variable dictionary of the clause as it is made available throug
read term/3 with the option variable_names. It is a list of terms Name = Var.

Result is a variable that must be unified to resulting term. Typically, this term is structured Pro-
log tree that carries a (partial) representation of the abstract syntax tree with embedded variables
that pass the Prolog parameters. This term is normally either passed to a predicate that serializes
the abstract syntax tree, or a predicate that processes the result in Prolog. For example, HTML is
commonly embedded for writing HTML documents (see library(http/html_write)).
Examples of languages that may be embedded for processing in Prolog are SPARQL, RuleML
or regular expressions.

The file library(http/html_quasiquotations) provides the, suprisingly simple,

quasi quotation parser for HTML.

with quasi quotation input(+Content, -Stream, :Goal) [det]

Process the quasi-quoted Content using Stream parsed by Goal. Stream is a temporary stream
with the following properties:

Its initial position represents the position of the start of the quoted material.
It is a text stream, using utf8 encoding.
It allows for repositioning
It will be closed after Goal completes.

Arguments
Goal is executed as once(Goal). Goal must succeed. Failure or ex-
ceptions from Goal are interpreted as syntax errors.

See also phrase from quasi quotation/2 can be used to process a quotation using a gram-
mar.

phrase from quasi quotation(:Grammar, +Content) [det]

Process the quasi quotation using the DCG Grammar. Failure of the grammer is interpreted as
a syntax error.

SWI-Prolog 7.4 Reference Manual

A.28. LIBRARY(RANDOM): RANDOM NUMBERS 475

See also with quasi quotation input/3 for processing quotations from stream.

quasi quotation syntax(:SyntaxName) [det]

Declare the predicate SyntaxName/4 to implement the the quasi quote syntax SyntaxName.
Normally used as a directive.
quasi quotation syntax error(+Error)
Report syntax_error(Error) using the current location in the quasi quoted input parser.
throws error(syntax_error(Error), Position)

A.28 library(random): Random numbers

author R.A. OKeefe, V.S. Costa, L. Damas, Jan Wielemaker
See also Built-in function random/1: A is random(10)

This library is derived from the DEC10 library random. Later, the core random generator was
moved to C. The current version uses the SWI-Prolog arithmetic functions to realise this library.
These functions are based on the GMP library.

random(-R:float) [det]
Binds R to a new random float in the open interval (0.0,1.0).
See also
- setrand/1, getrand/1 may be used to fetch/set the state.
- In SWI-Prolog, random/1 is implemented by the function random float/0.

random between(+L:int, +U:int, -R:int) [semidet]

Binds R to a random integer in [L,U] (i.e., including both L and U). Fails silently if U<L.
random(+L:int, +U:int, -R:int) [det]
random(+L:float, +U:float, -R:float) [det]
Generate a random integer or float in a range. If L and U are both integers, R is a random
integer in the half open interval [L,U). If L and U are both floats, R is a float in the open interval
(L,U).
deprecated Please use random/1 for generating a random float and random between/3 for gen-
erating a random integer. Note that the random between/3 includes the upper bound, while
this predicate excludes the upper bound.

setrand(+State) [det]
getrand(-State) [det]
Query/set the state of the random generator. This is intended for restarting the generator
at a known state only. The predicate setrand/1 accepts an opaque term returned by
getrand/1. This term may be asserted, written and read. The application may not make
other assumptions about this term.
For compatibility reasons with older versions of this library, setrand/1 also accepts a term
rand(A,B,C), where A, B and C are integers in the range 1..30,000. This argument is used
to seed the random generator. Deprecated.

SWI-Prolog 7.4 Reference Manual

476 APPENDIX A. THE SWI-PROLOG LIBRARY

Errors existence_error(random_state, _) is raised if the underlying infrastructure can-

not fetch the random state. This is currently the case if SWI-Prolog is not compiled with the
GMP library.
See also set random/1 and random property/1 provide the SWI-Prolog native implementa-
tion.

maybe [semidet]
Succeed/fail with equal probability (variant of maybe/1).

maybe(+P) [semidet]
Succeed with probability P, fail with probability 1-P

maybe(+K, +N) [semidet]

Succeed with probability K/N (variant of maybe/1)

random perm2(?A, ?B, ?X, ?Y) [semidet]

Does X=A,Y=B or X=B,Y=A with equal probability.

random member(-X, +List:list) [semidet]

X is a random member of List. Equivalent to random between(1, |List|), followed by nth1/3.
Fails of List is the empty list.

Compatibility Quintus and SICStus libraries.

random select(-X, +List, -Rest) [semidet]

random select(+X, -List, +Rest) [det]
Randomly select or insert an element. Either List or Rest must be a list. Fails if List is the
empty list.

Compatibility Quintus and SICStus libraries.

randset(+K:int, +N:int, -S:list(int)) [det]

S is a sorted list of K unique random integers in the range 1..N. Implemented by enumerating
1..N and deciding whether or not the number should be part of the set. For example:

?- randset(5, 5, S).
S = [1, 2, 3, 4, 5]. (always)
?- randset(5, 20, S).
S = [2, 7, 10, 19, 20].

See also randseq/3.

bug Slow if N is large and K is small.

randseq(+K:int, +N:int, -List:list(int)) [det]

S is a list of K unique random integers in the range 1..N. The order is random. Works as if
defined by the following code.

randseq(K, N, List) :-
randset(K, N, Set),
random_permutation(Set, List).

SWI-Prolog 7.4 Reference Manual

A.29. LIBRARY(READUTIL): READING LINES, STREAMS AND FILES 477

See also randset/3.

random permutation(+List, -Permutation) [det]

random permutation(-List, +Permutation) [det]
Permutation is a random permutation of List. This is intended to process the elements of List
in random order. The predicate is symmetric.

Errors instantiation error, type_error(list, _).

A.29 library(readutil): Reading lines, streams and files

This library contains primitives to read lines, files, multiple terms, etc. The package clib provides
a shared object (DLL) named readutil. If the library can locate this shared object it will use the
foreign implementation for reading character codes. Otherwise it will use a Prolog implementation.
Distributed applications should make sure to deliver the readutil shared object if performance of
these predicates is critical.

read line to codes(+Stream, -Codes)

Read the next line of input from Stream and unify the result with Codes after the line has been
read. A line is ended by a newline character or end-of-file. Unlike read line to codes/3,
this predicate removes a trailing newline character.
On end-of-file the atom end of file is returned. See also at end of stream/[0,1].

read line to codes(+Stream, -Codes, ?Tail)

Difference-list version to read an input line to a list of character codes. Reading stops at the
newline or end-of-file character, but unlike read line to codes/2, the newline is retained
in the output. This predicate is especially useful for reading a block of lines up to some
delimiter. The following example reads an HTTP header ended by a blank line:

read_header_data(Stream, Header) :-
read_line_to_codes(Stream, Header, Tail),
read_header_data(Header, Stream, Tail).

read_header_data("\r\n", _, _) :- !.
read_header_data("\n", _, _) :- !.
read_header_data("", _, _) :- !.
read_header_data(_, Stream, Tail) :-
read_line_to_codes(Stream, Tail, NewTail),
read_header_data(Tail, Stream, NewTail).

read stream to codes(+Stream, -Codes)

Read all input until end-of-file and unify the result to Codes.

read stream to codes(+Stream, -Codes, ?Tail)

Difference-list version of read stream to codes/2.

SWI-Prolog 7.4 Reference Manual

478 APPENDIX A. THE SWI-PROLOG LIBRARY

read file to codes(+Spec, -Codes, +Options)

Read a file to a list of character codes. Spec is a file specification for
absolute file name/3. Codes is the resulting code list. Options is a list of op-
tions for absolute file name/3 and open/4. In addition, the option tail(Tail) is
defined, forming a difference-list.
read file to terms(+Spec, -Terms, +Options)
Read a file to a list of Prolog terms (see read/1). Spec is a file specification for
absolute file name/3. Terms is the resulting list of Prolog terms. Options is a list of
options for absolute file name/3 and open/4. In addition, the option tail(Tail) is
defined, forming a difference-list.

A.30 library(record): Access named fields in a term

The library record provides named access to fields in a record represented as a compound term such
as point(X, Y). The Prolog world knows various approaches to solve this problem, unfortunately
with no consensus. The approach taken by this library is proposed by Richard OKeefe on the SWI-
Prolog mailinglist.
The approach automates a technique commonly described in Prolog text-books, where access and
modification predicates are defined for the record type. Such predicates are subject to normal im-
port/export as well as analysis by cross-referencers. Given the simple nature of the access predicates,
an optimizing compiler can easily inline them for optimal preformance.
A record is defined using the directive record/1. We introduce the library with a short example:

:- record point(x:integer=0, y:integer=0).

...,
default_point(Point),
point_x(Point, X),
set_x_of_point(10, Point, Point1),

make_point([y(20)], YPoint),

The principal functor and arity of the term used defines the name and arity of the compound used as
records. Each argument is described using a term of the format below.

hnamei[:htypei][=hdefaulti]

In this definition, hnamei is an atom defining the name of the argument, htypei is an optional type
specification as defined by must be/2 from library error, and hdefaulti is the default initial value.
The htypei defaults to any. If no default value is specified the default is an unbound variable.
A record declaration creates a set of predicates through term-expansion. We describe these predi-
cates below. In this description, hconstructori refers to the name of the record (point in the example
above) and hnamei to the name of an argument (field).

default hconstructori(-Record)
Create a new record where all fields have their default values. This is the same as
make hconstructori([], Record).

SWI-Prolog 7.4 Reference Manual

A.31. LIBRARY(REGISTRY): MANIPULATING THE WINDOWS REGISTRY 479

make hconstructori(+Fields, -Record)

Create a new record where specified fields have the specified values and remaining fields have
their default value. Each field is specified as a term hnamei(hvaluei). See example in the
introduction.

make hconstructori(+Fields, -Record, -RestFields)

Same as make hconstructori/2, but named fields that do not appear in Record are returned in
RestFields. This predicate is motivated by option-list processing. See library option.

hconstructori hnamei(Record, Value)

Unify Value with argument in Record named hnamei.2

hconstructori data(?Name, +Record, ?Value)

True when Value is the value for the field named Name in Record. This predicate does not
perform type-checking.

set hnamei of hconstructori(+Value, +OldRecord, -NewRecord)

Replace the value for hnamei in OldRecord by Value and unify the result with NewRecord.

set hnamei of hconstructori(+Value, !Record)

Destructively replace the argument hnamei in Record by Value based on setarg/3. Use with
care.

nb set hnamei of hconstructori(+Value, !Record)

As above, but using non-backtrackable assignment based on nb setarg/3. Use with extreme
care.

set hconstructori fields(+Fields, +Record0, -Record)

Set multiple fields using the same syntax as make hconstructori/2, but starting with Record0
rather than the default record.

set hconstructori fields(+Fields, +Record0, -Record, -RestFields)

Similar to set hconstructori fields/4, but fields not defined by hconstructori are returned in
RestFields.

set hconstructori field(+Field, +Record0, -Record)

Set a single field specified as a term hnamei(hvaluei).

record(+Spec)
The construct :- record Spec, ... is used to define access to named fields in a com-
pound. It is subject to term-expansion (see expand term/2) and cannot be called as a
predicate. See section A.30 for details.

A.31 library(registry): Manipulating the Windows registry

The registry is only available on the MS-Windows version of SWI-Prolog. It loads the foreign
extension plregtry.dll, providing the predicates described below. This library only makes the
most common operations on the registry available through the Prolog user. The underlying DLL
2
Note this is not called get as it performs unification and can perfectly well instantiate the argument.

SWI-Prolog 7.4 Reference Manual

480 APPENDIX A. THE SWI-PROLOG LIBRARY

provides a more complete coverage of the Windows registry API. Please consult the sources in pl/
src/win32/foreign/plregtry.c for further details.
In all these predicates, Path refers to a / separated path into the registry. This is not an atom
containing /-characters as used for filenames, but a term using the functor //2. Windows defines the
following roots for the registry: classes root, current user, local machine and users.
registry get key(+Path, -Value)
Get the principal (default) value associated to this key. Fails silently if the key does not exist.
registry get key(+Path, +Name, -Value)
Get a named value associated to this key.
registry set key(+Path, +Value)
Set the principal (default) value of this key. Creates (a path to) the key if it does not already
exist.
registry set key(+Path, +Name, +Value)
Associate a named value to this key. Creates (a path to) the key if it does not already exist.
registry delete key(+Path)
Delete the indicated key.
shell register file type(+Ext, +Type, +Name, +OpenAction)
Register a file-type. Ext is the extension to associate. Type is the type name, often something
like prolog.type. Name is the name visible in the Windows file-type browser. Finally,
OpenAction defines the action to execute when a file with this extension is opened in the
Windows explorer.
shell register dde(+Type, +Action, +Service, +Topic, +Command, +IfNotRunning)
Associate DDE actions to a type. Type is the same type as used for the 2nd argument of
shell register file type/4, Action is the action to perform, Service and Topic
specify the DDE topic to address, and Command is the command to execute on this topic.
Finally, IfNotRunning defines the command to execute if the required DDE server is not
present.
shell register prolog(+Ext)
Default registration of SWI-Prolog, which is invoked as part of the initialisation process on
Windows systems. As the source also includes the above predicates, it is given as an example:

shell_register_prolog(Ext) :-
current_prolog_flag(argv, [Me|_]),
atomic_list_concat([", Me, " "%1"], OpenCommand),
shell_register_file_type(
Ext, prolog.type, Prolog Source, OpenCommand),
shell_register_dde(
prolog.type, consult,
prolog, control, consult(%1), Me),
shell_register_dde(
prolog.type, edit,
prolog, control, edit(%1), Me).

SWI-Prolog 7.4 Reference Manual

A.32. LIBRARY(SIMPLEX): SOLVE LINEAR PROGRAMMING PROBLEMS 481

A.32 library(simplex): Solve linear programming problems

author Markus Triska

A.32.1 Introduction
A linear programming problem or simply linear program (LP) consists of:

a set of linear constraints

a set of variables
a linear objective function.

The goal is to assign values to the variables so as to maximize (or minimize) the value of the
objective function while satisfying all constraints.
Many optimization problems can be modeled in this way. As one basic example, consider a
knapsack with fixed capacity C, and a number of items with sizes s(i) and values v(i). The goal
is to put as many items as possible in the knapsack (not exceeding its capacity) while maximizing the
sum of their values.
As another example, suppose you are given a set of coins with certain values, and you are to find
the minimum number of coins such that their values sum up to a fixed amount. Instances of these
problems are solved below.
Solving an LP or integer linear program (ILP) with this library typically comprises 4 stages:

1. an initial state is generated with gen state/1

2. all relevant constraints are added with constraint/3

3. maximize/3 or minimize/3 are used to obtain a solved state that represents an optimum
solution

4. variable value/3 and objective/2 are used on the solved state to obtain variable
values and the objective function at the optimum.

The most frequently used predicates are thus:

gen state(-State)
Generates an initial state corresponding to an empty linear program.

constraint(+Constraint, +S0, -S)

Adds a linear or integrality constraint to the linear program corresponding to state S0. A linear
constraint is of the form Left Op C, where Left is a list of Coefficient*Variable
terms (variables in the context of linear programs can be atoms or compound terms) and
C is a non-negative numeric constant. The list represents the sum of its elements. Op can
be =, =< or >=. The coefficient 1 can be omitted. An integrality constraint is of the form
integral(Variable) and constrains Variable to an integral value.

maximize(+Objective, +S0, -S)

Maximizes the objective function, stated as a list of Coefficient*Variable terms that
represents the sum of its elements, with respect to the linear program corresponding to state S0.
\arg{S} is unified with an internal representation of the solved instance.

SWI-Prolog 7.4 Reference Manual

482 APPENDIX A. THE SWI-PROLOG LIBRARY

minimize(+Objective, +S0, -S)

Analogous to maximize/3.
variable value(+State, +Variable, -Value)
Value is unified with the value obtained for Variable. State must correspond to a solved instance.
objective(+State, -Objective)
Unifies Objective with the result of the objective function at the obtained extremum. State must
correspond to a solved instance.
All numeric quantities are converted to rationals via rationalize/1, and rational arithmetic
is used throughout solving linear programs. In the current implementation, all variables are implicitly
constrained to be non-negative. This may change in future versions, and non-negativity constraints
should therefore be stated explicitly.

A.32.2 Delayed column generation

Delayed column generation means that more constraint columns are added to an existing LP. The
following predicates are frequently used when this method is applied:
constraint(+Name, +Constraint, +S0, -S)
Like constraint/3, and attaches the name Name (an atom or compound term) to the new
constraint.
shadow price(+State, +Name, -Value)
Unifies Value with the shadow price corresponding to the linear constraint whose name is
Name. State must correspond to a solved instance.
constraint add(+Name, +Left, +S0, -S)
Left is a list of Coefficient*Variable terms. The terms are added to the left-hand side
of the constraint named Name. S is unified with the resulting state.
An example application of delayed column generation to solve a bin packing task is available
from: metalevel.at/various/colgen/

A.32.3 Solving LPs with special structure

The following predicates allow you to solve specific kinds of LPs more efficiently:
transportation(+Supplies, +Demands, +Costs, -Transport)
Solves a transportation problem. Supplies and Demands must be lists of non-negative integers.
Their respective sums must be equal. Costs is a list of lists representing the cost matrix, where
an entry (i,j) denotes the integer cost of transporting one unit from i to j. A transportation plan
having minimum cost is computed and unified with Transport in the form of a list of lists that
represents the transportation matrix, where element (i,j) denotes how many units to ship from i
to j.
assignment(+Cost, -Assignment)
Solves a linear assignment problem. Cost is a list of lists representing the quadratic cost matrix,
where element (i,j) denotes the integer cost of assigning entity $i$ to entity $j$. An assignment
with minimal cost is computed and unified with Assignment as a list of lists, representing an
adjacency matrix.

SWI-Prolog 7.4 Reference Manual

A.32. LIBRARY(SIMPLEX): SOLVE LINEAR PROGRAMMING PROBLEMS 483

A.32.4 Examples
We include a few examples for solving LPs with this library.

Example 1
This is the radiation therapy example, taken from Introduction to Operations Research by Hillier
and Lieberman.
Prolog DCG notation is used to implicitly thread the state through posting the constraints:

:- use_module(library(simplex)).

radiation(S) :-
gen_state(S0),
post_constraints(S0, S1),
minimize([0.4*x1, 0.5*x2], S1, S).

post_constraints -->
constraint([0.3*x1, 0.1*x2] =< 2.7),
constraint([0.5*x1, 0.5*x2] = 6),
constraint([0.6*x1, 0.4*x2] >= 6),
constraint([x1] >= 0),
constraint([x2] >= 0).

An example query:

?- radiation(S), variable_value(S, x1, Val1),

variable_value(S, x2, Val2).
Val1 = 15 rdiv 2,
Val2 = 9 rdiv 2.

Example 2
Here is an instance of the knapsack problem described above, where C = 8, and we have two types
of items: One item with value 7 and size 6, and 2 items each having size 4 and value 4. We introduce
two variables, x(1) and x(2) that denote how many items to take of each type.

:- use_module(library(simplex)).

knapsack(S) :-
knapsack_constraints(S0),
maximize([7*x(1), 4*x(2)], S0, S).

knapsack_constraints(S) :-
gen_state(S0),
constraint([6*x(1), 4*x(2)] =< 8, S0, S1),
constraint([x(1)] =< 1, S1, S2),
constraint([x(2)] =< 2, S2, S).

SWI-Prolog 7.4 Reference Manual

484 APPENDIX A. THE SWI-PROLOG LIBRARY

An example query yields:

?- knapsack(S), variable_value(S, x(1), X1),

variable_value(S, x(2), X2).
X1 = 1
X2 = 1 rdiv 2.

That is, we are to take the one item of the first type, and half of one of the items of the other type
to maximize the total value of items in the knapsack.
If items can not be split, integrality constraints have to be imposed:

knapsack_integral(S) :-
knapsack_constraints(S0),
constraint(integral(x(1)), S0, S1),
constraint(integral(x(2)), S1, S2),
maximize([7*x(1), 4*x(2)], S2, S).

Now the result is different:

?- knapsack_integral(S), variable_value(S, x(1), X1),

variable_value(S, x(2), X2).

X1 = 0
X2 = 2

That is, we are to take only the two items of the second type. Notice in particular that always
choosing the remaining item with best performance (ratio of value to size) that still fits in the knapsack
does not necessarily yield an optimal solution in the presence of integrality constraints.

Example 3
We are given:

3 coins each worth 1 unit

20 coins each worth 5 units and
10 coins each worth 20 units.

The task is to find a minimal number of these coins that amount to 111 units in total. We introduce
variables c(1), c(5) and c(20) denoting how many coins to take of the respective type:

:- use_module(library(simplex)).

coins(S) :-
gen_state(S0),
coins(S0, S).

SWI-Prolog 7.4 Reference Manual

A.33. LIBRARY(SOLUTION SEQUENCES): MODIFY SOLUTION SEQUENCES 485

coins -->
constraint([c(1), 5*c(5), 20*c(20)] = 111),
constraint([c(1)] =< 3),
constraint([c(5)] =< 20),
constraint([c(20)] =< 10),
constraint([c(1)] >= 0),
constraint([c(5)] >= 0),
constraint([c(20)] >= 0),
constraint(integral(c(1))),
constraint(integral(c(5))),
constraint(integral(c(20))),
minimize([c(1), c(5), c(20)]).

An example query:

?- coins(S), variable_value(S, c(1), C1),

variable_value(S, c(5), C5),
variable_value(S, c(20), C20).

C1 = 1,
C5 = 2,
C20 = 5.

A.33 library(solution sequences): Modify solution sequences

See also
- all solution predicates findall/3, bagof/3 and setof/3.
- library(aggregate)

The meta predicates of this library modify the sequence of solutions of a goal. The modifications
and the predicate names are based on the classical database operations DISTINCT, LIMIT, OFFSET,
ORDER BY and GROUP BY.
These predicates were introduced in the context of the SWISH Prolog browser-based shell, which
can represent the solutions to a predicate as a table. Notably wrapping a goal in distinct/1 avoids
duplicates in the result table and using order by/2 produces a nicely ordered table.
However, the predicates from this library can also be used to stay longer within the clean paradigm
where non-deterministic predicates are composed from simpler non-deterministic predicates by means
of conjunction and disjunction. While evaluating a conjunction, we might want to eliminate duplicates
of the first part of the conjunction. Below we give both the classical solution for solving variations of
(a(X), b(X)) and the ones using this library side-by-side.

Avoid duplicates
setof(X, of earlier
a(X), steps
Xs), distinct(a(X)),
member(X, Xs), b(X)
b(X).

SWI-Prolog 7.4 Reference Manual

486 APPENDIX A. THE SWI-PROLOG LIBRARY

Note that the distinct/1 based solution returns the first result of distinct(a(X)) im-
mediately after a/1 produces a result, while the setof/3 based solution will first compute
all results of a/1.

Only try b(X) only fora(X),

setof(X, the top-10
Xs),a(X) limit(10, order_by([desc(X)], a(X))),
reverse(Xs, Desc), b(X)
first_max_n(10, Desc, Limit),
member(X, Limit),
b(X)

Here we see power of composing primitives from this library and staying within the paradigm
of pure non-deterministic relational predicates.

distinct(:Goal)
distinct(?Witness, :Goal)
True if Goal is true and no previous solution of Goal bound Witness to the same value. As
previous answers need to be copied, equivalence testing is based on term variance (=@=/2).
The variant distinct/1 is equivalent to distinct(Goal,Goal).
If the answers are ground terms, the predicate behaves as the code below, but answers are
returned as soon as they become available rather than first computing the complete answer set.

distinct(Goal) :-
findall(Goal, Goal, List),
list_to_set(List, Set),
member(Goal, Set).

limit(+Count, :Goal)
Limit the number of solutions. True if Goal is true, returning at most Count solutions. Solutions
are returned as soon as they become available.

offset(+Count, :Goal)
Ignore the first Count solutions. True if Goal is true and produces more than Count solutions.
This predicate computes and ignores the first Count solutions.

order by(Spec, Goal)

Order solutions according to Spec. Spec is a list of terms, where each element is one of. The
ordering of solutions of Goal that only differ in variables that are not shared with Spec is not
changed.

asc(Term)
Order solution according to ascending Term
desc(Term)
Order solution according to descending Term

SWI-Prolog 7.4 Reference Manual

A.34. LIBRARY(TABLING): TABLED EXECUTION (SLG) 487

group by(+By, +Template, :Goal, -Bag) [nondet]

Group bindings of Template that have the same value for By. This predicate is almost the same
as bagof/3, but instead of specifying the existential variables we specify the free variables.
It is provided for consistency and complete coverage of the common database vocabulary.

A.34 library(tabling): Tabled execution (SLG)

The library tabling provides support for Tabled execution of one or more Prolog predicates, also
called SLG resolution. Tabling a predicate provides two properties:

1. Re-evaluation of a tabled predicate is avoided by memoizing the answers. This can realise huge
performance enhancements as illustrated in section A.34. It also comes with two downsides: the
memoized answers are not automatically updated or invalidated if the world (set of predicates
on which the answers depend) changes and the answer tables must be stored (in memory).

2. Left recursion, a goal calling a variant of itself recursively and thus looping under the normal
Prolog SLD resolution is avoided by suspending the variant call and resuming it with answers
from the table. This is illustrated in section A.34.

Tabling is particularly suited to simplify inference over a highly entangled set of predicates that
express axioms and rules in a static (not changing) world. When using SLD resolution for such
problems, it is hard to ensure termination and avoid frequent recomputation of intermediate results. A
solution is to use Datalog style bottom-up evaluation, i.e., applying rules on the axioms and derived
facts until a fixed point is reached. However, bottom-up evaluation typically derives many facts that
are never used. Tabling provides a goal oriented resolution strategy for such problems and is enabled
simply by adding a table/1 directive to the program.

Example 1: using tabling for memoizing

As a first classical example we use tabling for memoizing intermediate results. We use Fibonacci
numbers to illustrate the approach. The Fibonacci number I is defined as the sum of the Fibonacci
numbers for I 1 and I 2, while the Fibonacci number of 0 and 1 are both defined to be 1. This
can be translated naturally into Prolog:

fib(0, 1) :- !.
fib(1, 1) :- !.
fib(N, F) :-
N > 1,
N1 is N-1,
N2 is N-2,
fib(N1, F1),
fib(N2, F2),
F is F1+F2.

The complexity of executing this using SLD resolution however is 2N and thus becomes prohibitively
slow rather quickly, e.g., the execution time for N = 30 is already 0.4 seconds. Using tabling,
fib(N,F) for each value of N is computed only once and the algorithm becomes linear. Tabling

SWI-Prolog 7.4 Reference Manual

488 APPENDIX A. THE SWI-PROLOG LIBRARY

effectively inverts the execution order for this case: it suspends the final addition (F is F1+F2) until
the two preceeding Fibonacci numbers have been added to the answer tables. Thus, we can reduce
the complexity from the show-stopping 2N to linear by adding a tabling directive and otherwise not
changing the algorithm. The code becomes:

:- use_module(library(tabling)).
:- table fib/2.

fib(0, 1) :- !.
fib(1, 1) :- !.
fib(N, F) :-
N > 1,
N1 is N-1,
N2 is N-2,
fib(N1, F1),
fib(N2, F2),
F is F1+F2.

The price that we pay is that a table fib(I,F) is created for each I in 0..N . The execution time for
N = 30 is now 1 millisecond and computing the Fibonacci number for N = 1000 is doable (output
edited for readability).

1 ?- time(fib(1000, X)).
% 52,991 inferences, 0.013 CPU in 0.013 seconds
X = 70330367711422815821835254877183549770181269836358
73274260490508715453711819693357974224949456261173
34877504492417659910881863632654502236471060120533
74121273867339111198139373125598767690091902245245
323403501.

In the case of Fibonacci numbers we can still rather easily achieve linear complexity using program
transformation, where we use bottom-up instead of top-down evaluation, i.e., we compute fib(N,F)
for growing N , where we pass the last two Fibonacci numbers to the next iteration. Not having to
create the tables and not having to suspend and resume goals makes this implementatio about 25 times
faster than the tabled one. However, even in this simple case the transformation is not obvious and it
is far more difficult to recognise the algorithm as an implementation of Fibonacci numbers.

fib(0, 1) :- !.
fib(1, 1) :- !.
fib(N, F) :-
fib(1,1,1,N,F).

fib(_F, F1, N, N, F1) :- !.

fib(F0, F1, I, N, F) :-
F2 is F0+F1,
I2 is I + 1,
fib(F1, F2, I2, N, F).

SWI-Prolog 7.4 Reference Manual

A.34. LIBRARY(TABLING): TABLED EXECUTION (SLG) 489

Example 2: avoiding non-termination

SLD resolution easily results in an infinite loop due to left recursion, a goal that (indirectly) calls a
variant of itself or cycles in the input data. Thus, if we have a series of connection/2 statements
that define railway connections between two cities, we cannot use the most natural logical definition
to express that we can travel between two cities:

% :- use_module(library(tabling)).
% :- table connection/2.

connection(X, Y) :-
connection(X, Z),
connection(Z, Y).
connection(X, Y) :-
connection(Y, X).

connection(Amsterdam, Schiphol).
connection(Amsterdam, Haarlem).
connection(Schiphol, Leiden).
connection(Haarlem, Leiden).

After enabling tabling however, the above works just fine as illustrated in the session below.
Where is the magic and what is the price we paid? The magic is, again, the fact that new goals
to the tabled predicate suspend. So, all recursive goals are suspended. Eventually, a table for
connection(Amsterdam, X) is created with the two direct connections from Amsterdam. Now, it
resumes the first clause using the tabled solutions, continuing the last connection/2 subgoal with
connection(Schiphol, X) and connection(Haarlem, X). These two go through the same pro-
cess, creating new suspended recursive calls and creating tables for the connections from Schiphol and
Haarlem. Eventually, we end up with a set of tables for each call variant that is involved in computing
the transitive closure of the network starting in Amsterdam. However, if the Japanese rail network
would have been in our data as well, we would not have produced tables for that.

1 ?- connection(Amsterdam, X).
X = Haarlem ;
X = Schiphol ;
X = Amsterdam ;
X = Leiden.

Again, the fact that a simple table/1 directive turns the pure logical specification into a fairly
efficient algorithm is a clear advantage. Without tabling the program needs to be stratified, introducing
a base layer with the raw connections, a second layer that introduces the commutative property of a
railway (if you can travel from A to B you can also travel from B to A and a final layer that realises
transitivity (if you can travel from A to B and from B to C you can also travel from A to C). The
third and final layer must keep track which cities you have already visited to avoid traveling in circles.
The transformed program however uses little memory (the list of already visited cities and the still
open choices) and does not need to deal with maintaining consistency between the tables and ground
facts.

SWI-Prolog 7.4 Reference Manual

490 APPENDIX A. THE SWI-PROLOG LIBRARY

A.34.1 Tabling predicate reference

table +PredicateIndicators
Prepare the given PredicateIndicators for tabling. Can only be used as a directive. The example
below prepares the predicate edge/2 and the non-terminal statement//1 for tabled
execution.

:- table edge/2, statement//1.

abolish all tables

Remove all tables. This is normally used to free up the space or recompute the result after
predicates on which the result for some tabled predicates depend.

Errors permission_error(abolish, table, all) if tabling is in progress.

abolish table subgoals(:Subgoal) [det]

Abolish all tables that unify with SubGoal.

About the tabling implementation

The SWI-Prolog implementation uses Delimited continuations (see section 4.10 to realise sus-
pension of variant calls. The initial version was written by Benoit Desouter and described in
[Desouter et al., 2015]. We moved the main data structures required for tabling, the answer tables
(see section 4.14.4) and the worklist to SWI-Prologs C core.
The table/1 directive causes the creation of a wrapper calling the renamed original predicate.
For example, the program in section A.34 is translated into the following program. We give this
information to improve your understanding of the current tabling implementation. Future versions are
likely to use a more low-level translation that is not based on wrappers.

connection(A, B) :-
start_tabling(user:connection(A, B),
connection tabled(A, B)).

connection tabled(X, Y) :-
connection(X, Z),
connection(Z, Y).
connection tabled(X, Y) :-
connection(Y, X).

connection tabled(Amsterdam, Schiphol).

connection tabled(Amsterdam, Haarlem).
connection tabled(Schiphol, Leiden).
connection tabled(Haarlem, Leiden).

SWI-Prolog 7.4 Reference Manual

A.35. LIBRARY(THREAD POOL): RESOURCE BOUNDED THREAD MANAGEMENT491

Status of tabling
The current implementation is merely a first prototype. It needs several enhancements before we
can consider it a serious competitor to Prolog systems with mature tabling such as XSB, YAP and
B-Prolog. In particular,

The performance needs to be improved.

Memory usage needs to be reduced.
mode-directed tabling should be added.
Tables must be shared between threads, both to reduce space and avoid recomputation.
Tables must be invalidated and reclaimed automatically.
Notably XSB supports incremental tabeling and well-founded semantics under negation.

A.35 library(thread pool): Resource bounded thread management

See also http handler/3 and http spawn/2.

The module library(thread_pool) manages threads in pools. A pool defines properties

of its member threads and the maximum number of threads that can coexist in the pool. The call
thread create in pool/4 allocates a thread in the pool, just like thread create/3. If the
pool is fully allocated it can be asked to wait or raise an error.
The library has been designed to deal with server applications that receive a variety of requests,
such as HTTP servers. Simply starting a thread for each request is a bit too simple minded for such
servers:

Creating many CPU intensive threads often leads to a slow-down rather than a speedup.
Creating many memory intensive threads may exhaust resources
Tasks that require little CPU and memory but take long waiting for external resources can run
many threads.

Using this library, one can define a pool for each set of tasks with comparable characteristics
and create threads in this pool. Unlike the worker-pool model, threads are not started immediately.
Depending on the design, both approaches can be attractive.
The library is implemented by means of a manager thread with the fixed thread id
__thread_pool_manager. All state is maintained in this manager thread, which receives and
processes requests to create and destroy pools, create threads in a pool and handle messages from
terminated threads. Thread pools are not saved in a saved state and must therefore be recreated using
the initialization/1 directive or otherwise during startup of the application.

thread pool create(+Pool, +Size, +Options) [det]

Create a pool of threads. A pool of threads is a declaration for creating threads with shared
properties (stack sizes) and a limited number of threads. Threads are created using
thread create in pool/4. If all threads in the pool are in use, the behaviour depends
on the wait option of thread create in pool/4 and the backlog option described
below. Options are passed to thread create/3, except for

SWI-Prolog 7.4 Reference Manual

492 APPENDIX A. THE SWI-PROLOG LIBRARY

backlog(+MaxBackLog)
Maximum number of requests that can be suspended. Default is infinite. Otherwise
it must be a non-negative integer. Using backlog(0) will never delay thread creation
for this pool.

The pooling mechanism does not interact with the detached state of a thread. Threads can
be created both detached and normal and must be joined using thread join/2 if they are
not detached.

thread pool destroy(+Name) [det]

Destroy the thread pool named Name.

Errors existence_error(thread_pool, Name).

current thread pool(?Name) [nondet]

True if Name refers to a defined thread pool.

thread pool property(?Name, ?Property) [nondet]

True if Property is a property of thread pool Name. Defined properties are:

options(Options)
Thread creation options for this pool
free(Size)
Number of free slots on this pool
size(Size)
Total number of slots on this pool
members(ListOfIDs)
ListOfIDs is the list or threads running in this pool
running(Running)
Number of running threads in this pool
backlog(Size)
Number of delayed thread creations on this pool

thread create in pool(+Pool, :Goal, -Id, +Options) [det]

Create a thread in Pool. Options overrule default thread creation options associated to the pool.
In addition, the following option is defined:

wait(+Boolean)
If true (default) and the pool is full, wait until a member of the pool completes. If
false, throw a resource error.

Errors
- resource_error(threads_in_pool(Pool)) is raised if wait is false or the back-
log limit has been reached.
- existence_error(thread_pool, Pool) if Pool does not exist.

SWI-Prolog 7.4 Reference Manual

A.36. LIBRARY(UGRAPHS): UNWEIGHTED GRAPHS 493

create pool(+PoolName) [semidet,multifile]

Hook to create a thread pool lazily. The hook is called if thread create in pool/4
discovers that the thread pool does not exist. If the hook succeeds,
thread create in pool/4 retries creating the thread. For example, we can use the
following declaration to create threads in the pool media, which holds a maximum of 20
threads.

:- multifile thread_pool:create_pool/1.

thread_pool:create_pool(media) :-
thread_pool_create(media, 20, []).

A.36 library(ugraphs): Unweighted Graphs

Authors: Richard OKeefe & Vitor Santos Costa

Implementation and documentation are copied from YAP 5.0.1. The ugraph library is
based on code originally written by Richard OKeefe. The code was then extended to be
compatible with the SICStus Prolog ugraphs library. Code and documentation have been
cleaned and style has been changed to be more in line with the rest of SWI-Prolog.
The ugraphs library was originally released in the public domain. The YAP version is
covered by the Perl Artistic license, version 2.0. This code is dual-licensed under the
modified GPL as used for all SWI-Prolog libraries or the Perl Artistic license, version
2.0.

The routines assume directed graphs; undirected graphs may be implemented by using two edges.
Originally graphs were represented in two formats. The SICStus library and this version of
ugraphs.pl only use the S-representation. The S-representation of a graph is a list of (vertex-
neighbors) pairs, where the pairs are in standard order (as produced by keysort) and the neighbors
of each vertex are also in standard order (as produced by sort). This form is convenient for many
calculations. Each vertex appears in the S-representation, even if it has no neighbors.

vertices edges to ugraph(+Vertices, +Edges, -Graph)

Given a graph with a set of Vertices and a set of Edges, Graph must unify with the correspond-
ing S-representation. Note that vertices without edges will appear in Vertices but not in Edges.
Moreover, it is sufficient for a vertex to appear in Edges.

?- vertices_edges_to_ugraph([],[1-3,2-4,4-5,1-5], L).
L = [1-[3,5], 2-[4], 3-[], 4-[5], 5-[]]

In this case all vertices are defined implicitly. The next example shows three unconnected
vertices:

?- vertices_edges_to_ugraph([6,7,8],[1-3,2-4,4-5,1-5], L).
L = [1-[3,5], 2-[4], 3-[], 4-[5], 5-[], 6-[], 7-[], 8-[]] ?

SWI-Prolog 7.4 Reference Manual

494 APPENDIX A. THE SWI-PROLOG LIBRARY

vertices(+Graph, -Vertices)
Unify Vertices with all vertices appearing in Graph. Example:

?- vertices([1-[3,5],2-[4],3-[],4-[5],5-[]], L).
L = [1, 2, 3, 4, 5]

edges(+Graph, -Edges)
Unify Edges with all edges appearing in Graph. Example:

?- edges([1-[3,5],2-[4],3-[],4-[5],5-[]], L).
L = [1-3, 1-5, 2-4, 4-5]

add vertices(+Graph, +Vertices, -NewGraph)

Unify NewGraph with a new graph obtained by adding the list of Vertices to Graph. Example:

?- add_vertices([1-[3,5],2-[]], [0,1,2,9], NG).

NG = [0-[], 1-[3,5], 2-[], 9-[]]

del vertices(+Graph, +Vertices, -NewGraph)

Unify NewGraph with a new graph obtained by deleting the list of Vertices and all edges that
start from or go to a vertex in Vertices from Graph. Example:

?- del_vertices([2,1],
[1-[3,5],2-[4],3-[],4-[5],
5-[],6-[],7-[2,6],8-[]],
NL).
NL = [3-[],4-[5],5-[],6-[],7-[6],8-[]]

add edges(+Graph, +Edges, -NewGraph)

Unify NewGraph with a new graph obtained by adding the list of Edges to Graph. Example:

?- add_edges([1-[3,5],2-[4],3-[],4-[5],
5-[],6-[],7-[],8-[]],
[1-6,2-3,3-2,5-7,3-2,4-5],
NL).
NL = [1-[3,5,6], 2-[3,4], 3-[2], 4-[5],
5-[7], 6-[], 7-[], 8-[]]

del edges(+Graph, +Edges, -NewGraph)

Unify NewGraph with a new graph obtained by removing the list of Edges from Graph. Notice
that no vertices are deleted. Example:

SWI-Prolog 7.4 Reference Manual

A.36. LIBRARY(UGRAPHS): UNWEIGHTED GRAPHS 495

?- del_edges([1-[3,5],2-[4],3-[],4-[5],5-[],6-[],7-[],8-[]],
[1-6,2-3,3-2,5-7,3-2,4-5,1-3],
NL).
NL = [1-[5],2-[4],3-[],4-[],5-[],6-[],7-[],8-[]]

transpose ugraph(+Graph, -NewGraph)

Unify NewGraph with a new graph obtained from Graph by replacing all edges of the form
V1-V2 by edges of the form V2-V1. The cost is O(|V |2 ). Notice that an undirected graph is
its own transpose. Example:

?- transpose_ugraph([1-[3,5],2-[4],3-[],4-[5],
5-[],6-[],7-[],8-[]], NL).
NL = [1-[],2-[],3-[1],4-[2],5-[1,4],6-[],7-[],8-[]]

neighbours(+Vertex, +Graph, -Vertices)

Unify Vertices with the list of neighbours of vertex Vertex in Graph. Example:

?- neighbours(4,[1-[3,5],2-[4],3-[],
4-[1,2,7,5],5-[],6-[],7-[],8-[]], NL).
NL = [1,2,7,5]

neighbors(+Vertex, +Graph, -Vertices)

American version of neighbours/3.

complement(+Graph, -NewGraph)
Unify NewGraph with the graph complementary to Graph. Example:

?- complement([1-[3,5],2-[4],3-[],
4-[1,2,7,5],5-[],6-[],7-[],8-[]], NL).
NL = [1-[2,4,6,7,8],2-[1,3,5,6,7,8],3-[1,2,4,5,6,7,8],
4-[3,5,6,8],5-[1,2,3,4,6,7,8],6-[1,2,3,4,5,7,8],
7-[1,2,3,4,5,6,8],8-[1,2,3,4,5,6,7]]

compose(+LeftGraph, +RightGraph, -NewGraph)

Compose NewGraph by connecting the drains of LeftGraph to the sources of RightGraph.
Example:

?- compose([1-[2],2-[3]],[2-[4],3-[1,2,4]],L).
L = [1-[4], 2-[1,2,4], 3-[]]

ugraph union(+Graph1, +Graph2, -NewGraph)

NewGraph is the union of Graph1 and Graph2. Example:

SWI-Prolog 7.4 Reference Manual

496 APPENDIX A. THE SWI-PROLOG LIBRARY

?- ugraph_union([1-[2],2-[3]],[2-[4],3-[1,2,4]],L).
L = [1-[2], 2-[3,4], 3-[1,2,4]]

top sort(+Graph, -Sort)

Generate the set of nodes Sort as a topological sorting of Graph, if one is possible. A toplogical
sort is possible if the graph is connected and acyclic. In the example we show how topological
sorting works for a linear graph:

?- top_sort([1-[2], 2-[3], 3-[]], L).

L = [1, 2, 3]

top sort(+Graph, -Sort0, -Sort)

Generate the difference list Sort-Sort0 as a topological sorting of Graph, if one is possible.

transitive closure(+Graph, -Closure)

Generate the graph Closure as the transitive closure of Graph. Example:

?- transitive_closure([1-[2,3],2-[4,5],4-[6]],L).
L = [1-[2,3,4,5,6], 2-[4,5,6], 4-[6]]

reachable(+Vertex, +Graph, -Vertices)

Unify Vertices with the set of all vertices in Graph that are reachable from Vertex. Example:

?- reachable(1,[1-[3,5],2-[4],3-[],4-[5],5-[]],V).
V = [1, 3, 5]

A.37 library(url): Analysing and constructing URL

author
- Jan Wielemaker
- Lukas Faulstich
deprecated New code should use library(uri), provided by the clib package.

This library deals with the analysis and construction of a URL, Universal Resource Locator. URL
is the basis for communicating locations of resources (data) on the web. A URL consists of a protocol
identifier (e.g. HTTP, FTP, and a protocol-specific syntax further defining the location. URLs are
standardized in RFC-1738.
The implementation in this library covers only a small portion of the defined protocols. Though the
initial implementation followed RFC-1738 strictly, the current is more relaxed to deal with frequent
violations of the standard encountered in practical use.

global url(+URL, +Base, -Global) [det]

Translate a possibly relative URL into an absolute one.

SWI-Prolog 7.4 Reference Manual

A.37. LIBRARY(URL): ANALYSING AND CONSTRUCTING URL 497

Errors syntax_error(illegal_url) if URL is not legal.

is absolute url(+URL)
True if URL is an absolute URL. That is, a URL that starts with a protocol identifier.

http location(?Parts, ?Location)

Construct or analyze an HTTP location. This is similar to parse url/2, but only deals with
the location part of an HTTP URL. That is, the path, search and fragment specifiers. In the
HTTP protocol, the first line of a message is

<Action> <Location> HTTP/<version>

Arguments
Location Atom or list of character codes.

parse url(?URL, ?Attributes) [det]

Construct or analyse a URL. URL is an atom holding a URL or a variable. Attributes is a list of
components. Each component is of the format Name(Value). Defined components are:

protocol(Protocol)
The used protocol. This is, after the optional url:, an identifier separated from the
remainder of the URL using :. parse url/2 assumes the http protocol if no protocol
is specified and the URL can be parsed as a valid HTTP url. In addition to the RFC-1738
specified protocols, the file protocol is supported as well.
host(Host)
Host-name or IP-address on which the resource is located. Supported by all network-based
protocols.
port(Port)
Integer port-number to access on the \arg{Host}. This only appears if the port is explic-
itly specified in the URL. Implicit default ports (e.g., 80 for HTTP) do not appear in the
part-list.
path(Path)
(File-) path addressed by the URL. This is supported for the ftp, http and file
protocols. If no path appears, the library generates the path /.
search(ListOfNameValue)
Search-specification of HTTP URL. This is the part after the ?, normally used to transfer
data from HTML forms that use the GET protocol. In the URL it consists of a www-form-
encoded list of Name=Value pairs. This is mapped to a list of Prolog Name=Value terms
with decoded names and values.
fragment(Fragment)
Fragment specification of HTTP URL. This is the part after the # character.

The example below illustrates all of this for an HTTP URL.

?- parse_url(http://www.xyz.org/hello?msg=Hello+World%21#x,
P).

SWI-Prolog 7.4 Reference Manual

498 APPENDIX A. THE SWI-PROLOG LIBRARY

P = [ protocol(http),
host(www.xyz.org),
fragment(x),
search([ msg = Hello World!
]),
path(/hello)
]

By instantiating the parts-list this predicate can be used to create a URL.

parse url(+URL, +BaseURL, -Attributes) [det]

Similar to parse url/2 for relative URLs. If URL is relative, it is resolved using the absolute
URL BaseURL.

www form encode(+Value, -XWWWFormEncoded) [det]

www form encode(-Value, +XWWWFormEncoded) [det]
En/decode to/from application/x-www-form-encoded. Encoding encodes all characters except
RFC 3986 unreserved (ASCII alnum (see code type/2)), and one of -. using percent
encoding. Newline is mapped to %OD%OA. When decoding, newlines appear as a single
newline (10) character.
Note that a space is encoded as %20 instead of +. Decoding decodes both to a space.

deprecated Use uri encoded/3 for new code.

set url encoding(?Old, +New) [semidet]

Query and set the encoding for URLs. The default is utf8. The only other defined value is
iso_latin_1.

To be done Having a global flag is highly inconvenient, but a work-around for old sites using ISO
Latin 1 encoding.

url iri(+Encoded, -Decoded) [det]

url iri(-Encoded, +Decoded) [det]
Convert between a URL, encoding in US-ASCII and an IRI. An IRI is a fully expanded
Unicode string. Unicode strings are first encoded into UTF-8, after which %-encoding takes
place.

parse url search(?Spec, ?Fields:list(Name=Value)) [det]

Construct or analyze an HTTP search specification. This deals with form data using the MIME-
type application/x-www-form-urlencoded as used in HTTP GET requests.

file name to url(+File, -URL) [det]

file name to url(-File, +URL) [semidet]
Translate between a filename and a file:// URL.

To be done Current implementation does not deal with paths that need special encoding.

SWI-Prolog 7.4 Reference Manual

A.38. LIBRARY(VARNUMBERS): UTILITIES FOR NUMBERED TERMS 499

A.38 library(varnumbers): Utilities for numbered terms

See also numbervars/4, =@=/2 (variant/2).
Compatibility This library was introduced by Quintus and available in many related implementations, al-
though not with exactly the same set of predicates.

This library provides the inverse functionality of the built-in numbervars/3. Note that this
library suffers from the known issues that $VAR(X) is a normal Prolog term and, -unlike the built-in
numbervars-, the inverse predicates do not process cyclic terms. The following predicate is true for
any acyclic term that contains no $VAR(X), integer(X) terms and no constraint variables:

always_true(X) :-
copy_term(X, X2),
numbervars(X),
varnumbers(X, Copy),
Copy =@= X2.

numbervars(+Term) [det]
Number variables in Term using $VAR(N). Equivalent to numbervars(Term, 0, _).

See also numbervars/3, numbervars/4

varnumbers(+Term, -Copy) [det]

Inverse of numbervars/1. Equivalent to varnumbers(Term, 0, Copy).

varnumbers(+Term, +Start, -Copy) [det]

Inverse of numbervars/3. True when Copy is a copy of Term with all variables numbered
>= Start consistently replaced by fresh variables. Variables in Term are shared with Copy
rather than replaced by fresh variables.

Errors domain_error(acyclic_term, Term) if Term is cyclic.

Compatibility Quintus, SICStus. Not in YAP version of this library

max var number(+Term, +Start, -Max) [det]

True when Max is the max of Start and the highest numbered $VAR(N) term.

author Vitor Santos Costa

Compatibility YAP

varnumbers names(+Term, -Copy, -VariableNames) [det]

If Term is a term with numbered and named variables using the reserved term $VAR(X),
Copy is a copy of Term where each $VAR(X) is consistently replaced by a fresh variable and
Bindings is a list X = Var, relating the X terms with the variable it is mapped to.

See also numbervars/3, varnumbers/3, read term/3 using the variable_names op-
tion.

SWI-Prolog 7.4 Reference Manual

500 APPENDIX A. THE SWI-PROLOG LIBRARY

A.39 library(yall): Lambda expressions

author Paulo Moura and Jan Wielemaker
To be done Extend optimization support

Prolog realizes high-order programming with meta-calling. The core predicate of this is call/1,
which simply calls its argument. This can be used to define higher-order predicates such as
ignore/1 or forall/2. The call/N construct calls a closure with N-1 additional arguments.
This is used to define higher-order predicates such as the maplist/N family or foldl/N.
The problem with higher order predicates based on call/N is that the additional arguments
are always added to the end of the closures argument list. This often requires defining triv-
ial helper predicates to get the argument order right. For example, if you want to add a com-
mon postfix to a list of atoms you need to apply atom_concat(In,Postfix,Out), but
maplist(x(PostFix),ListIn,ListOut) calls x(PostFix,In,Out). This is where this
library comes in, which allows us to write

?- maplist([In,Out]>>atom_concat(In,_p,Out), [a,b], ListOut).

ListOut = [a_p, b_p].

The {...} specifies which variables are shared between the lambda and the context. This
allows us to write the code below. Without the {PostFix} a free variable would be passed to
atom concat/3.

add_postfix(PostFix, ListIn, ListOut) :-

maplist({PostFix}/[In,Out]>>atom_concat(In,PostFix,Out),
ListIn, ListOut).

This introduces the second application area of lambda expressions: the ability to stop binding
variables in the context. This features shines when combined with bagof/3 or setof/3 where
you normally have to specify the the variables in whose binding you are not interested using the
VarGoal construct (marking Var as existential quantified). Lambdas allow doing the reverse: spec-
ify the variables in which you are interested.
Lambda expressions use the syntax below

{...}/[...]>>Goal.

The {...} optional part is used for lambda-free variables. The order of variables doesnt matter
hence the {...} set notation.
The [...] optional part lists lambda parameters. Here order of variables matters hence the list
notation.
As / and >> are standard infix operators, no new operators are added by this library. An advantage
of this syntax is that we can simply unify a lambda expression with Free/Parameters>>Lambda to
access each of its components. Spaces in the lambda expression are not a problem although the goal
may need to be written between ()s. Goals that are qualified by a module prefix also need to be
wrapped inside parentheses.
Combined with library(apply_macros), library(yall) allows writing one-liners for
many list operations that have the same performance as hand written code.

SWI-Prolog 7.4 Reference Manual

A.39. LIBRARY(YALL): LAMBDA EXPRESSIONS 501

The module name, yall, stands for Yet Another Lambda Library.
This module implements Logtalks lambda expressions syntax. The development of this module
was sponsored by Kyndi, Inc.

+Parameters >> +Lambda

>>(+Parameters, +Lambda, ?A1)
>>(+Parameters, +Lambda, ?A1, ?A2)
>>(+Parameters, +Lambda, ?A1, ?A2, ?A3)
>>(+Parameters, +Lambda, ?A1, ?A2, ?A3, ?A4)
>>(+Parameters, +Lambda, ?A1, ?A2, ?A3, ?A4, ?A5)
>>(+Parameters, +Lambda, ?A1, ?A2, ?A3, ?A4, ?A5, ?A6)
>>(+Parameters, +Lambda, ?A1, ?A2, ?A3, ?A4, ?A5, ?A6, ?A7)
Calls a copy of Lambda. This is similar to call(Lambda,A1,...), but arguments are
reordered according to the list Parameters:

The first length(Parameters) arguments from A1, ... are unified with (a copy of)
Parameters, which may share them with variables in Lambda.
Possible excess arguments are passed by position.

Arguments
Parameters is either a plain list of parameters or a term {Free}/List. Free
represents variables that are shared between the context and the
Lambda term. This is needed for compiling Lambda expressions.

+Free / :Lambda
/(+Free, :Lambda, ?A1)
/(+Free, :Lambda, ?A1, ?A2)
/(+Free, :Lambda, ?A1, ?A2, ?A3)
/(+Free, :Lambda, ?A1, ?A2, ?A3, ?A4)
/(+Free, :Lambda, ?A1, ?A2, ?A3, ?A4, ?A5)
/(+Free, :Lambda, ?A1, ?A2, ?A3, ?A4, ?A5, ?A6)
/(+Free, :Lambda, ?A1, ?A2, ?A3, ?A4, ?A5, ?A6, ?A7)
Shorthand for Free/[]>>Lambda. This is the same as applying call/N on Lambda, except
that only variables appearing in Free are bound by the call. For example

p(1,a).
p(2,b).

?- {X}/p(X,Y).
X = 1;
X = 2.

This can in particularly be combined with bagof/3 and setof/3 to select particular vari-
ables to be concerned rather than using existential quantification (/2) to exclude variables.
For example, the two calls below are equivalent.

SWI-Prolog 7.4 Reference Manual

502 APPENDIX A. THE SWI-PROLOG LIBRARY

setof(X, Yp(X,Y), Xs)

setof(X, {X}/p(X,_), Xs)

is lambda(@Term) [semidet]
True if Term is a valid Lambda expression.

lambda calls(+LambdaExpression, -Goal) [det]

lambda calls(+LambdaExpression, +ExtraArgs, -Goal) [det]
Goal is the goal called if call/N is applied to LambdaExpression, where ExtraArgs are the
additional arguments to call/N. ExtraArgs can be an integer or a list of concrete arguments.
This predicate is used for cross-referencing and code highlighting.

SWI-Prolog 7.4 Reference Manual

Hackers corner
This appendix describes a number of predicates which enable the Prolog user to inspect the Prolog
B
environment and manipulate (or even redefine) the debugger. They can be used as entry points for
experiments with debugging tools for Prolog. The predicates described here should be handled with
some care as it is easy to corrupt the consistency of the Prolog system by misusing them.

B.1 Examining the Environment Stack

prolog current frame(-Frame) [det]
Unify Frame with an integer providing a reference to the parent of the current local stack
frame. A pointer to the current local frame cannot be provided as the predicate succeeds
deterministically and therefore its frame is destroyed immediately after succeeding.

prolog current choice(-Choice) [semidet]

Unify Choice with an integer provided a reference to the last choice point. Fails if the current
environment has no choice points. See also prolog choice attribute/3.

prolog frame attribute(+Frame, +Key, :Value)

Obtain information about the local stack frame Frame. Frame is a frame reference as ob-
tained through prolog current frame/1, prolog trace interception/4 or this
predicate. The key values are described below.

alternative
Value is unified with an integer reference to the local stack frame in which execution is
resumed if the goal associated with Frame fails. Fails if the frame has no alternative
frame.
has alternatives
Value is unified with true if Frame still is a candidate for backtracking; false other-
wise.
goal
Value is unified with the goal associated with Frame. If the definition module of the
active predicate is not the calling context, the goal is represented as hmodulei:hgoali. Do
not instantiate variables in this goal unless you know what you are doing! Note that the
returned term may contain references to the frame and should be discarded before the
frame terminates.1
1
The returned term is actually an illegal Prolog term that may hold references from the global to the local stack to
preserve the variable names.

SWI-Prolog 7.4 Reference Manual

504 APPENDIX B. HACKERS CORNER

parent goal
If Value is instantiated to a callable term, find a frame executing the predicate described
by Value and unify the arguments of Value to the goal arguments associated with the
frame. This is intended to check the current execution context. The user must ensure the
checked parent goal is not removed from the stack due to last-call optimisation and be
aware of the slow operation on deeply nested calls.
predicate indicator
Similar to goal, but only returning the [hmodulei:]hnamei/harityi term describing the
term, not the actual arguments. It avoids creating an illegal term as goal and is used by
the library prolog stack.
clause
Value is unified with a reference to the currently running clause. Fails if the current
goal is associated with a foreign (C) defined predicate. See also nth clause/3 and
clause property/2.
level
Value is unified with the recursion level of Frame. The top level frame is at level 0.
parent
Value is unified with an integer reference to the parent local stack frame of Frame. Fails
if Frame is the top frame.
context module
Value is unified with the name of the context module of the environment.
top
Value is unified with true if Frame is the top Prolog goal from a recursive call back
from the foreign language; false otherwise.
hidden
Value is unified with true if the frame is hidden from the user, either because a parent
has the hide-childs attribute (all system predicates), or the system has no trace-me
attribute.
skipped
Value is true if this frame was skipped in the debugger.
pc
Value is unified with the program pointer saved on behalf of the parent goal if the parent
goal is not owned by a foreign predicate or belongs to a compound meta-call (e.g.,
call((a,b))).
argument(N)
Value is unified with the N-th slot of the frame. Argument 1 is the first argument of the
goal. Arguments above the arity refer to local variables. Fails silently if N is out of range.

prolog choice attribute(+ChoicePoint, +Key, -Value)

Extract attributes of a choice point. ChoicePoint is a reference to a choice point as
passed to prolog trace interception/4 on the 3rd argument or obtained using
prolog current choice/1. Key specifies the requested information:

parent
Requests a reference to the first older choice point.

SWI-Prolog 7.4 Reference Manual

B.2. ANCESTRAL CUTS 505

frame
Requests a reference to the frame to which the choice point refers.
type
Requests the type. Defined values are clause (the goal has alternative clauses),
foreign (non-deterministic foreign predicate), jump (clause internal choice point),
top (first dummy choice point), catch (catch/3 to allow for undo), debug (help the
debugger), or none (has been deleted).

This predicate is used for the graphical debugger to show the choice point stack.
deterministic(-Boolean)
Unifies its argument with true if no choice point exists that is more recent than the entry of the
clause in which it appears. There are few realistic situations for using this predicate. It is used
by the prolog/0 top level to check whether Prolog should prompt the user for alternatives.
Similar results can be achieved in a more portable fashion using call cleanup/2.

B.2 Ancestral cuts

prolog cut to(+Choice)
Prunes all choice points created since Choice. Can be used together with
prolog current choice/1 to implement ancestral cuts. This predicate is in the
hackers corner because it should not be used in normal Prolog code. It may be used to create
new high level control structures, particularly for compatibility purposes.
Note that in the current implementation, the pruned choice points and environment frames are
not reclaimed. As a consequence, where predicates that are deterministic due to clause indexing,
normal cuts or (if\send{then};else) and and tail recursive run in bounded local stack
space, predicates using prolog cut to/1 will run out of stack.

B.3 Intercepting the Tracer

prolog trace interception(+Port, +Frame, +Choice, -Action)
Dynamic predicate, normally not defined. This predicate is called from the SWI-Prolog debug-
ger just before it would show a port. If this predicate succeeds, the debugger assumes that the
trace action has been taken care of and continues execution as described by Action. Otherwise
the normal Prolog debugger actions are performed.
Port denotes the reason to activate the tracer (port in the 4/5-port, but with some additions):

call
Normal entry through the call port of the 4-port debugger.
redo(PC)
Normal entry through the redo port of the 4-port debugger. The redo port signals resum-
ing a predicate to generate alternative solutions. If PC is 0 (zero), clause indexing has
found another clause that will be tried next. Otherwise, PC is the program counter in the
current clause where execution continues. This implies we are dealing with an in-clause
choice point left by, e.g., ;/2. Note that non-determinism in foreign predicates are also
handled using an in-clause choice point.

SWI-Prolog 7.4 Reference Manual

506 APPENDIX B. HACKERS CORNER

unify
The unify port represents the neck instruction, signalling the end of the head-matching
process. This port is normally invisible. See leash/1 and visible/1.
exit
The exit port signals the goal is proved. It is possible for the goal to have alternatives. See
prolog frame attribute/3 to examine the goal stack.
fail
The fail port signals final failure of the goal.
exception(Except)
An exception is raised and still pending. This port is activated on each parent frame of the
frame generating the exception until the exception is caught or the user restarts normal
computation using retry. Except is the pending exception term.
break(PC)
A break instruction is executed. PC is program counter. This port is used by the graphi-
cal debugger.
cut call(PC)
A cut is encountered at PC. This port is used by the graphical debugger to visualise the
effect of the cut.
cut exit(PC)
A cut has been executed. See cut call(PC) for more information.

Frame is a reference to the current local stack frame, which can be examined using
prolog frame attribute/3. Choice is a reference to the last choice point and can be
examined using prolog choice attribute/3. Action must be unified with a term that
specifies how execution must continue. The following actions are defined:

abort
Abort execution. See abort/0.
continue
Continue (i.e., creep in the command line debugger).
fail
Make the current goal fail.
ignore
Step over the current goal without executing it.
nodebug
Continue execution in normal nodebugging mode. See nodebug/0.
retry
Retry the current frame.
retry(Frame)
Retry the given frame. This must be a parent of the current frame.
skip
Skip over the current goal (i.e., skip in the command line debugger).
up
Skip to the parent goal (i.e., up in the command line debugger).

SWI-Prolog 7.4 Reference Manual

B.4. BREAKPOINT AND WATCHPOINT HANDLING 507

Together with the predicates described in section 4.39 and the other predicates of this chapter,
this predicate enables the Prolog user to define a complete new debugger in Prolog. Besides
this, it enables the Prolog programmer to monitor the execution of a program. The example
below records all goals trapped by the tracer in the database.

prolog_trace_interception(Port, Frame, _PC, continue) :-

prolog_frame_attribute(Frame, goal, Goal),
prolog_frame_attribute(Frame, level, Level),
recordz(trace, trace(Port, Level, Goal)).

To trace the execution of go this way the following query should be given:

?- trace, go, notrace.

prolog skip frame(-Frame)

Indicate Frame as a skipped frame and set the skip level (see prolog skip level/2 to
the recursion depth of Frame. The effect of the skipped flag is that a redo on a child of this
frame is handled differently. First, a redo trace is called for the child, where the skip level is
set to redo in skip. Next, the skip level is set to skip level of the skipped frame.
prolog skip level(-Old, +New)
Unify Old with the old value of skip level and then set this level according to New. New
is an integer, the atom very deep (meaning dont skip) or the atom skip in redo
(see prolog skip frame/1). The skip level is a setting of each Prolog thread that
disables the debugger on all recursion levels deeper than the level of the variable. See also
prolog skip frame/1.

B.4 Breakpoint and watchpoint handling

SWI-Prolog support breakpoints. Breakpoints can be manipulated with the library
prolog breakpoints. Setting a breakpoint replaces a virtual machine instruction with the
D BREAK instruction. If the virtual machine executes a D BREAK, it performs a callback to decide on
the action to perform. This section describes this callback, called prolog:break hook/6.

prolog:break hook(+Clause, +PC, +FR, +BFR, +Expression, -Action) [hook,semidet]

Experimental This hook is called if the virtual machine executes a D BREAK, set using
set breakpoint/4. Clause and PC identify the breakpoint. FR and BFR provide the
environment frame and current choicepoint. Expression identifies the action that is interrupted,
and is one of the following:

call(Goal)
The instruction will call Goal. This is generated for nearly all instructions. Note that
Goal is semantically equivalent to the compiled body term, but might differ syntactically.
This is notably the case when arithmetic expressions are compiled in optimized mode
(see optimise). In particular, the arguments of arithmetic expressions have already
been evaluated. Thus, A is 3*B, where B equals 3 results in a term call(A is 9) if
the clause was compiled with optimization enabled.

SWI-Prolog 7.4 Reference Manual

508 APPENDIX B. HACKERS CORNER

!
The instruction will call the cut. Because the semantics of metacalling the cut differs
from executing the cut in its original context we do not wrap the cut in call/1.
:-
The breakpoint is on the neck instruction, i.e., after performing the head unifications.
exit
The breakpoint is on the exit instruction, i.e., at the end of the clause. Note that the exit
instruction may not be reached due to last-call optimisation.
unify exit
The breakpoint is on the completion of an in-lined unification while the system is not
in debug mode. If the system is in debug mode, inlined unification is returned as
call(Var=Term).2

If prolog:break hook/6 succeeds, it must unify Action with a value that describes how execution
must continue. Possible values for Action are:

continue
Just continue as if no breakpoint was present.
debug
Continue in debug mode. See debug/0.
trace
Continue in trace mode. See trace/0.
call(Goal)
Execute Goal instead of the goal that would be executed. Goal is executed as call/1,
preserving (non-)determinism and exceptions.

If this hook throws an exception, the exception is propagated normally. If this hook is not
defined or fails, the default action is executed. This implies that, if the thread is in debug mode,
the tracer will be enabled (trace) and otherwise the breakpoint is ignored (continue).
This hook allows for injecting various debugging scenarios into the executable without recom-
piling. The hook can access variables of the calling context using the frame inspection predi-
cates. Here are some examples.

Create conditional breakpoints by imposing conditions before deciding the return trace.
Watch variables at a specific point in the execution. Note that binding of these variables
can be monitored using attributed variables, see section 7.1.
Dynamically add assertions on variables using assertion/1.
Wrap the Goal into a meta-call that traces progress of the Goal.
2
This hack will disappear if we find a good solution for applying D BREAK to inlined unification. Only option might
be to place the break on both the unification start and end instructions.

SWI-Prolog 7.4 Reference Manual

B.5. ADDING CONTEXT TO ERRORS: PROLOG EXCEPTION HOOK 509

B.5 Adding context to errors: prolog exception hook

The hook prolog exception hook/4 has been introduced in SWI-Prolog 5.6.5 to provide ded-
icated exception handling facilities for application frameworks, for example non-interactive server
applications that wish to provide extensive context for exceptions for offline debugging.

prolog exception hook(+ExceptionIn, -ExceptionOut, +Frame, +CatcherFrame)

This hook predicate, if defined in the module user, is between raising an exception and
handling it. It is intended to allow a program adding additional context to an exception to
simplify diagnosing the problem. ExceptionIn is the exception term as raised by throw/1 or
one of the built-in predicates. The output argument ExceptionOut describes the exception that
is actually raised. Frame is the innermost frame. See prolog frame attribute/3 and
the library prolog stack for getting information from this. CatcherFrame is a reference to
the frame calling the matching catch/3, none if the exception is not caught or C if the
exception is caught in C calling Prolog using the flag PL Q CATCH EXCEPTION.
The hook is run in nodebug mode. If it succeeds, ExceptionOut is considered the current
exception. If it fails, ExceptionIn is used for further processing. The hook is never called
recursively. The hook is not allowed to modify ExceptionOut in such a way that it no longer
unifies with the catching frame.
Typically, prolog exception hook/4 is used to fill the second argument of
error(Formal, Context) exceptions. Formal is defined by the ISO standard, while SWI-
Prolog defines Context as a term context(Location, Message). Location is bound to a term
hnamei/harityi by the kernel. This hook can be used to add more information on the calling
context, such as a full stack trace.
Applications that use exceptions as part of normal processing must do a quick test of the envi-
ronment before starting expensive gathering information on the state of the program.
The hook can call trace/0 to enter trace mode immediately. For example, imagine an appli-
cation performing an unwanted division by zero while all other errors are expected and handled.
We can force the debugger using the hook definition below. Run the program in debug mode
(see debug/0) to preserve as much as possible of the error context.

user:prolog_exception_hook(
error(evaluation_error(zero_divisor), _),
_, _, _) :-
trace, fail.

B.6 Hooks using the exception predicate

This section describes the predicate exception/3, which can be defined by the user in the module
user as a multifile predicate. Unlike the name suggests, this is actually a hook predicate that has no
relation to Prolog exceptions as defined by the ISO predicates catch/3 and throw/1.
The predicate exception/3 is called by the kernel on a couple of events, allowing the user to
fix errors just-in-time. The mechanism allows for lazy creation of objects such as predicates.

SWI-Prolog 7.4 Reference Manual

510 APPENDIX B. HACKERS CORNER

exception(+Exception, +Context, -Action)

Dynamic predicate, normally not defined. Called by the Prolog system on run-time exceptions
that can be repaired just-in-time. The values for Exception are described below. See also
catch/3 and throw/1.
If this hook predicate succeeds it must instantiate the Action argument to the atom fail to
make the operation fail silently, retry to tell Prolog to retry the operation or error to make
the system generate an exception. The action retry only makes sense if this hook modified
the environment such that the operation can now succeed without error.

undefined predicate
Context is instantiated to a predicate indicator ([module]:hnamei/harityi). If the predicate
fails, Prolog will generate an existence error exception. The hook is intended
to implement alternatives to the built-in autoloader, such as autoloading code from a
database. Do not use this hook to suppress existence errors on predicates. See also
unknown and section 2.13.
undefined global variable
Context is instantiated to the name of the missing global variable. The hook must call
nb setval/2 or b setval/2 before returning with the action retry.

B.7 Hooks for integrating libraries

Some libraries realise an entirely new programming paradigm on top of Prolog. An example is XPCE
which adds an object system to Prolog as well as an extensive set of graphical primitives. SWI-Prolog
provides several hooks to improve the integration of such libraries. See also section 4.5 for editing
hooks and section 4.11.3 for hooking into the message system.

prolog list goal(:Goal)

Hook, normally not defined. This hook is called by the L command of the tracer in the
module user to list the currently called predicate. This hook may be defined to list only
relevant clauses of the indicated Goal and/or show the actual source code in an editor. See also
portray/1 and multifile/1.

prolog:debug control hook(:Action)

Hook for the debugger control predicates that allows the creator of more high-level program-
ming languages to use the common front-end predicates to control the debugger. For example,
XPCE uses these hooks to allow for spying methods rather than predicates. Action is one of:

spy(Spec)
Hook in spy/1. If the hook succeeds spy/1 takes no further action.
nospy(Spec)
Hook in nospy/1. If the hook succeeds nospy/1 takes no further action. If spy/1 is
hooked, it is advised to place a complementary hook for nospy/1.
nospyall
Hook in nospyall/0. Should remove all spy points. This hook is called in a failure-
driven loop.

SWI-Prolog 7.4 Reference Manual

B.8. HOOKS FOR LOADING FILES 511

debugging
Hook in debugging/0. It can be used in two ways. It can report the status of the
additional debug points controlled by the above hooks and fail to let the system report the
others, or it succeeds, overruling the entire behaviour of debugging/0.

prolog:help hook(+Action)
Hook into help/0 and help/1. If the hook succeeds, the built-in actions are not executed.
For example, ?- help(picture). is caught by the XPCE help hook to give help on the
class picture. Defined actions are:

help
User entered plain help/0 to give default help. The default performs help(help/1),
giving help on help.
help(What)
Hook in help/1 on the topic What.
apropos(What)
Hook in apropos/1 on the topic What.

B.8 Hooks for loading files

All loading of source files is achieved by load files/2. The hook prolog load file/2 can
be used to load Prolog code from non-files or even load entirely different information, such as foreign
files.
prolog load file(+Spec, +Options)
Load a single object. If this call succeeds, load files/2 assumes the action has been taken
care of. This hook is only called if Options does not contain the stream(Input) option. The
hook must be defined in the module user.
This can be used to load from unusual places. For example, library http/http load loads
Prolog directly from an HTTP server. It can also be used to load source in unusual forms, such
as loading compressed files without decompressing them first. There is currently no example of
that.
prolog:comment hook(+Comments, +Pos, +Term)
This hook allows for processing comments encountered by the compiler. If this hook is defined,
the compiler calls read term/2 with the option comments(Comments). If the list of
comments returned by read term/2 is not empty it calls this comment hook with the
following arguments.

Comments is the non-empty list of comments. Each comment is a pair Position-String,

where String is a string object (see section 5.2) that contains the comment including de-
limiters. Consecutive line comments are returned as a single comment.
Pos is a stream-position term that describes the starting position of Term
Term is the term read.

This hook is exploited by the documentation system. See stream position data/3. See
also read term/3.

SWI-Prolog 7.4 Reference Manual

Compatibility with other
Prolog dialects C
This chapter explains issues for writing portable Prolog programs. It was started after discussion with
Vitor Santos Costa, the leading developer of YAP Prolog1 YAP and SWI-Prolog have expressed the
ambition to enhance the portability beyond the trivial Prolog examples, including complex libraries
involving foreign code.
Although it is our aim to enhance compatibility, we are still faced with many incompatibilities
between the dialects. As a first step both YAP and SWI will provide some instruments that help
developing portable code. A first release of these tools appeared in SWI-Prolog 5.6.43. Some of the
facilities are implemented in the base system, others in the library dialect.pl.

The Prolog flag dialect is an unambiguous and fast way to find out which Prolog dialect
executes your program. It has the value swi for SWI-Prolog and yap on YAP.

The Prolog flag version data is bound to a term swi(Major, Minor, Patch, Extra)

Conditional compilation using :- if(Condition) . . . :- endif is supported. See sec-

tion 4.3.1.

The predicate expects dialect/1 allows for specifying for which Prolog system the code
was written.

The predicates exists source/1 and source exports/2 can be used to query the li-
brary content. The require/1 directive can be used to get access to predicates without know-
ing their location.

The module predicates use module/1, use module/2 have been extended with a notion
for import-except and import-as. This is particularly useful together with reexport/1
and reexport/2 to compose modules from other modules and mapping names.

Foreign code can expect SWI PROLOG when compiled for SWI-Prolog and
YAP PROLOG when compiled on YAP.

:- expects dialect(+Dialect)
This directive states that the code following the directive is written for the given Prolog Dialect.
See also dialect. The declaration holds until the end of the file in which it appears. The
current dialect is available using prolog load context/2.
The exact behaviour of this predicate is still subject to discussion. Of course, if Dialect
matches the running dialect the directive has no effect. Otherwise we check for the existence of
library(dialect/Dialect) and load it if the file is found. Currently, this file has this function-
ality:
1
http://yap.sourceforge.net/

SWI-Prolog 7.4 Reference Manual

C.1. SOME CONSIDERATIONS FOR WRITING PORTABLE CODE 513

Define system predicates of the requested dialect we do not have.

Apply goal expansion/2 rules that map conflicting predicates to versions emulating
the requested dialect. These expansion rules reside in the dialect compatibility module,
but are applied if prolog load context(dialect, Dialect) is active.
Modify the search path for library directories, putting libraries compatible with the target
dialect before the native libraries.
Setup support for the default filename extension of the dialect.

exists source(+Spec)
Is true if Spec exists as a Prolog source. Spec uses the same conventions as load files/2.
Fails without error if Spec cannot be found.

source exports(+Spec, +Export)

Is true if source Spec exports Export, a predicate indicator. Fails without error otherwise.

C.1 Some considerations for writing portable code

The traditional way to write portable code is to define custom predicates for all potentially non-
portable code and define these separately for all Prolog dialects one wishes to support. Here are some
considerations.

Probably the best reason for this is that it allows to define minimal semantics required by the
application for the portability predicates. Such functionality can often be mapped efficiently to
the target dialect. Contrary, if code was written for dialect X, the defined semantics are those
of dialect X. Emulating all extreme cases and full error handling compatibility may be tedious
and result in a much slower implementation that needed. Take for example call cleanup/2.
The SICStus definition is fundamentally different from the SWI definition, but 99% of the appli-
cations just want to make calls like below to guarantee StreamIn is closed, even if process/1
misbehaves.

call_cleanup(process(StreamIn), close(In))

As a drawback, the code becomes full of my call cleanup, etc. and every potential portability
conflict needs to be abstracted. It is hard for people who have to maintain such code later to
grasp the exact semantics of the my * predicates and applications that combine multiple libraries
using this compatibility approach are likely to encounter conflicts between the portability layers.
A good start is not to use my *, but a prefix derived from the library or application name or
names that explain the intended semantics more precisely.

Another problem is that most code is initially not written with portability in mind. Instead,
ports are requested by users or arise from the desire to switch Prolog dialect. Typically, we
want to achieve compatibility with the new Prolog dialect with minimal changes, often keeping
compatibility with the original dialect(s). This problem is well known from the C/Unix world
and we advise anyone to study the philosophy of GNU autoconf, from which we will illustrate
some highlights below.

SWI-Prolog 7.4 Reference Manual

514 APPENDIX C. COMPATIBILITY WITH OTHER PROLOG DIALECTS

The GNU autoconf suite, known to most people as configure, was an answer to the frustrating
life of Unix/C programmers when Unix dialects were about as abundant and poorly standardised as
Prolog dialects today. Writing a portable C program can only be achieved using cpp, the C preproces-
sor. The C preprocessor performs two tasks: macro expansion and conditional compilation. Prolog
realises macro expansion through term expansion/2 and goal expansion/2. Conditional
compilation is achieved using :- if(Condition) as explained in section 4.3.1. The situation
appears similar.
The important lesson learned from GNU autoconf is that the last resort for conditional compilation
to achieve portability is to switch on the platform or dialect. Instead, GNU autoconf allows you to
write tests for specific properties of the platform. Most of these are whether or not some function or
file is available. Then there are some standard tests for difficult-to-write-portable situations and finally
there is a framework that allows you to write arbitrary C programs and check whether they can be
compiled and/or whether they show the intended behaviour. Using a separate configure program
is needed in C, as you cannot perform C compilation step or run C programs from the C preprocessor.
In most Prolog environments we do not need this distinction as the compiler is integrated into the
runtime environment and Prolog has excellent reflexion capabilities.
We must learn from the distinction to test for features instead of platform (dialect), as this makes
the platform-specific code robust for future changes of the dialect. Suppose we need compare/3 as
defined in this manual. The compare/3 predicate is not part of the ISO standard, but many systems
support it and it is not unlikely it will become ISO standard or the intended dialect will start supporting
it. GNU autoconf strongly advises to test for the availability:

:- if(\+current_predicate(_, compare(_,_,_))).
compare(<, Term1, Term2) :-
Term1 @< Term2, !.
compare(>, Term1, Term2) :-
Term1 @> Term2, !.
compare(=, Term1, Term2) :-
Term1 == Term2.
:- endif.

This code is much more robust against changes to the intended dialect and, possibly at least as impor-
tant, will provide compatibility with dialects you didnt even consider porting to right now.
In a more challenging case, the target Prolog has compare/3, but the semantics are different.
What to do? One option is to write a my compare/3 and change all occurrences in the code.
Alternatively you can rename calls using goal expansion/2 like below. This construct will not
only deal with Prolog dialects lacking compare/3 as well as those that only implement it for numeric
comparison or have changed the argument order. Of course, writing rock-solid code would require a
complete test-suite, but this example will probably cover all Prolog dialects that allow for conditional
compilation, have core ISO facilities and provide goal expansion/2, the things we claim a Prolog
dialect should have to start writing portable code for it.

:- if(\+catch(compare(<,a,b), _, fail)).
compare_standard_order(<, Term1, Term2) :-
Term1 @< Term2, !.
compare_standard_order(>, Term1, Term2) :-
Term1 @> Term2, !.

SWI-Prolog 7.4 Reference Manual

C.1. SOME CONSIDERATIONS FOR WRITING PORTABLE CODE 515

compare_standard_order(=, Term1, Term2) :-

Term1 == Term2.

goal_expansion(compare(Order, Term1, Term2),

compare_standard_order(Order, Term1, Term2)).
:- endif.

SWI-Prolog 7.4 Reference Manual

Glossary of Terms
anonymous [variable]
D
The variable _ is called the anonymous variable. Multiple occurrences of _ in a single term are
not shared.

arguments
Arguments are terms that appear in a compound term. A1 and a2 are the first and second
argument of the term myterm(A1, a2).

arity
Argument count (= number of arguments) of a compound term.

assert
Add a clause to a predicate. Clauses can be added at either end of the clause-list of a predicate.
See asserta/1 and assertz/1.

atom
Textual constant. Used as name for compound terms, to represent constants or text.

backtracking
Search process used by Prolog. If a predicate offers multiple clauses to solve a goal, they are
tried one-by-one until one succeeds. If a subsequent part of the proof is not satisfied with the
resulting variable binding, it may ask for an alternative solution (= binding of the variables),
causing Prolog to reject the previously chosen clause and try the next one.

binding [of a variable]

Current value of the variable. See also backtracking and query.

built-in [predicate]
Predicate that is part of the Prolog system. Built-in predicates cannot be redefined by the user,
unless this is overruled using redefine system predicate/1.

body
Part of a clause behind the neck operator (:-).

choice point
A choice point represents a choice in the search for a solution. Choice points are created if
multiple clauses match a query or using disjunction (;/2). On backtracking, the execution
state of the most recent choice point is restored and search continues with the next alternative
(i.e., next clause or second branch of ;/2).

SWI-Prolog 7.4 Reference Manual

 517

clause
Sentence of a Prolog program. A clause consists of a head and body separated by the neck
operator (:-) or it is a fact. For example:

parent(X) :-
father(X, _).

Expressed as X is a parent if X is a father of someone. See also variable and predicate.

compile
Process where a Prolog program is translated to a sequence of instructions. See also interpreted.
SWI-Prolog always compiles your program before executing it.

compound [term]
Also called structure. It consists of a name followed by N arguments, each of which are terms.
N is called the arity of the term.

context module
If a term is referring to a predicate in a module, the context module is used to find the target
module. The context module of a goal is the module in which the predicate is defined, unless
this predicate is module transparent, in which case the context module is inherited from the
parent goal. See also module transparent/1 and meta-predicate.

dcg
Abbreviation for Definite Clause Grammar.

det [determinism]
Short for deterministic.

determinism
How many solutions a goal can provide. Values are nondet (zero to infinite), multi (one to
infinite), det (exactly one) and semidet (zero or one).

deterministic
A predicate is deterministic if it succeeds exactly one time without leaving a choice point.

dynamic [predicate]
A dynamic predicate is a predicate to which clauses may be asserted and from which clauses
may be retracted while the program is running. See also update view.

exported [predicate]
A predicate is said to be exported from a module if it appears in the public list. This im-
plies that the predicate can be imported into another module to make it visible there. See also
use module/[1,2].

fact
Clause without a body. This is called a fact because, interpreted as logic, there is no condition
to be satisfied. The example below states john is a person.

person(john).

SWI-Prolog 7.4 Reference Manual

518 APPENDIX D. GLOSSARY OF TERMS

fail
A goal is said to haved failed if it could not be proven.

float
Computers crippled representation of a real number. Represented as IEEE double.

foreign
Computer code expressed in languages other than Prolog. SWI-Prolog can only cooperate
directly with the C and C++ computer languages.

functor
Combination of name and arity of a compound term. The term foo(a, b, c) is said to be a term
belonging to the functor foo/3. foo/0 is used to refer to the atom foo.

goal
Question stated to the Prolog engine. A goal is either an atom or a compound term. A goal
either succeeds, in which case the variables in the compound terms have a binding, or it fails if
Prolog fails to prove it.

hashing
Indexing technique used for quick lookup.

head
Part of a clause before the neck operator (:-). This is an atom or compound term.

imported [predicate]
A predicate is said to be imported into a module if it is defined in another module and made
available in this module. See also chapter 6.

indexing
Indexing is a technique used to quickly select candidate clauses of a predicate for a specific
goal. In most Prolog systems, indexing is done (only) on the first argument of the head. If this
argument is instantiated to an atom, integer, float or compound term with functor, hashing is
used to quickly select all clauses where the first argument may unify with the first argument of
the goal. SWI-Prolog supports just-in-time and multi-argument indexing. See section 2.17.

integer
Whole number. On all implementations of SWI-Prolog integers are at least 64-bit signed
values. When linked to the GNU GMP library, integer arithmetic is unbounded. See also
current prolog flag/2, flags bounded, max integer and min integer.

interpreted
As opposed to compiled, interpreted means the Prolog system attempts to prove a goal by
directly reading the clauses rather than executing instructions from an (abstract) instruction set
that is not or only indirectly related to Prolog.

instantiation [of an argument]

To what extend a term is bound to a value. Typical levels are unbound (a variable), ground
(term without variables) or partially bound (term with embedded variables).

SWI-Prolog 7.4 Reference Manual

 519

meta-predicate
A predicate that reasons about other predicates, either by calling them, (re)defining them or
querying properties.
mode [declaration]
Declaration of an argument instantiation pattern for a predicate, often accompanied with a
determinism.
module
Collection of predicates. Each module defines a name-space for predicates. built-in predicates
are accessible from all modules. Predicates can be published (exported) and imported to make
their definition available to other modules.
module transparent [predicate]
A predicate that does not change the context module. Sometimes also called a meta-predicate.
multi [determinism]
A predicate is said to have determinism multi if it generates at least one answer.
multifile [predicate]
Predicate for which the definition is distributed over multiple source files. See multifile/1.
neck
Operator (:-) separating head from body in a clause.
nondet
Short for non deterministic.
non deterministic
A non deterministic predicate is a predicate that mail fail or succeed any number of times.
operator
Symbol (atom) that may be placed before its operand (prefix), after its operand (postfix) or
between its two operands (infix).
In Prolog, the expression a+b is exactly the same as the canonical term +(a,b).
operand
Argument of an operator.
precedence
The priority of an operator. Operator precedence is used to interpret a+b*c as
+(a, *(b,c)).
predicate
Collection of clauses with the same functor (name/arity). If a goal is proved, the system looks
for a predicate with the same functor, then uses indexing to select candidate clauses and then
tries these clauses one-by-one. See also backtracking.
predicate indicator
Term of the form Name/Arity (traditional) or Name//Arity (ISO DCG proposal), where Name
is an atom and Arity a non-negative integer. It acts as an indicator (or reference) to a predicate
or DCG rule.

SWI-Prolog 7.4 Reference Manual

520 APPENDIX D. GLOSSARY OF TERMS

priority
In the context of operators a synonym for precedence.

program
Collection of predicates.

property
Attribute of an object. SWI-Prolog defines various * property predicates to query the status of
predicates, clauses. etc.

prove
Process where Prolog attempts to prove a query using the available predicates.

public list
List of predicates exported from a module.

query
See goal.

retract
Remove a clause from a predicate. See also dynamic, update view and assert.

semidet
Shorthand for

semi deterministic
.

semi deterministic
A predicate that is semi deterministic either fails or succeeds exactly once without a choice
point. See also deterministic.

shared
Two variables are called shared after they are unified. This implies if either of them is bound,
the other is bound to the same value:

?- A = B, A = a.
A = B, B = a.

singleton [variable]
Variable appearing only one time in a clause. SWI-Prolog normally warns for this to avoid
you making spelling mistakes. If a variable appears on purpose only once in a clause, write
it as _ (see anonymous). Rules for naming a variable and avoiding a warning are given in
section 2.15.1.

solution
Bindings resulting from a successfully proven goal.

structure
Synonym for compound term.

SWI-Prolog 7.4 Reference Manual

 521

string
Used for the following representations of text: a packed array (see section 5.2, SWI-Prolog
specific), a list of character codes or a list of one-character atoms.

succeed
A goal is said to have succeeded if it has been proven.

term
Value in Prolog. A term is either a variable, atom, integer, float or compound term. In addition,
SWI-Prolog also defines the type string.

transparent
See module transparent.

unify
Prolog process to make two terms equal by assigning variables in one term to values at the
corresponding location of the other term. For example:

?- foo(a, B) = foo(A, b).

A = a,
B = b.

Unlike assignment (which does not exist in Prolog), unification is not directed.

update view
How Prolog behaves when a dynamic predicate is changed while it is running. There are two
models. In most older Prolog systems the change becomes immediately visible to the goal, in
modern systems including SWI-Prolog, the running goal is not affected. Only new goals see
the new definition.

variable
A Prolog variable is a value that is not yet bound. After binding a variable, it cannot be
modified. Backtracking to a point in the execution before the variable was bound will turn it
back into a variable:

?- A = b, A = c.
false.

?- (A = b; true; A = c).
A = b ;
true ;
A = c .

See also unify.

SWI-Prolog 7.4 Reference Manual

SWI-Prolog License Conditions
and Tools E
As of version 7.4.01 , the SWI-Prolog source code is distributed under the Simplified BSD license:

Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright

notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright

notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the
distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

This, unfortunately, does not mean you can any version of SWI-Prolog under the above license.
The SWI-Prolog core may be linked to libraries that are more restrictive and in addition your code
may have loaded extension packages that have more restrictive conditions. In particular, the core is
by default linked to libgmp, distributed under the Lesser GNU Public license.
The above implies you need to configure and recompile the system without these components.
For this we provide options to the configure script:

./configure --without-gpl
./configure --without-lgpl

1
Actually pre-release 7.3.33

SWI-Prolog 7.4 Reference Manual

E.1. CONTRIBUTING TO THE SWI-PROLOG PROJECT 523

The GNU MP Bignum Library provides unbounded integers, rational numbers and some crypto-
graphical functionality. As libgmp is provided under the Lesser GNU Public license it may legally be
combined with proprietary software as long as libgmp is dynamically linked (default) and the end user
can replace the libgmp shared object and use your application with their (possibly modified) version
of libgmp. In practice this leads to problems if the application is not accessible (e.g., embedded in
closed hardware) or you want to avoid customers to peek around in the process memory as they can
easily do so by adding a backdoor to the modified LGPL component. Note that such a protection is
in general not possible anyway if the customer has unrestricted access to the machine on which the
application runs.

E.1 Contributing to the SWI-Prolog project

To reach maximal coherence we will, as a rule of thumb, only accept new code that has the Simplified
BSD license and existing code with a permissive license such as MIT, Apache, BSD-3, etc. In excep-
tional cases we may accept code with GPL or LGPL conditions. Such code must be tagged using a
license/1 directive (Prolog) or a call to PL license() for foreign code and, if they are part of
the core, the code must be excluded using the --without-gpl or --without-lgpl option.

E.2 Software support to keep track of license conditions

Given the above, it is possible that SWI-Prolog packages and extensions rely on the GPL, LGPL or
other licenses. The predicates below allow for registering license requirements for Prolog files and
foreign modules. The predicate license/0 reports which components from the currently config-
ured system are distributed under non-permissive open source licenses and therefore may need to be
replaced to suit your requirements.

license
Evaluate the license conditions of all loaded components. If the system contains one or more
components that are licenced under GPL-like restrictions the system indicates this program
may only be distributed under the GPL license as well as which components prohibit the use of
other license conditions. Likewise for for LGPL components.

license(+LicenseId, +Component)
Register the fact that Component is distributed under a license identified by LicenseId. Known
license identifiers can be listed using known licenses/0. A new license can be registered
as a known language using a declaration like below. The second argument defines the category
if the license, which is one of gpl, lgpl, permissive or proprietary.

:- multifile license:license/3.

license:license(mylicense, permissive,
[ comment(My personal license),
url(http://www.mine.org/license.html)
]).

:- license(mylicense).

SWI-Prolog 7.4 Reference Manual

524 APPENDIX E. SWI-PROLOG LICENSE CONDITIONS AND TOOLS

license(+LicenseId)
Intended as a directive in Prolog source files. It takes the current filename and calls
license/2.

void PL license(const char *LicenseId, const char *Component)

Intended for the install() procedure of foreign libraries. This call can be made before
PL initialise().

known licenses
List all licenses known to the system. This does not imply the system contains code covered by
the listed licenses. See license/2.

E.3 License conditions inherited from used code

E.3.1 Cryptographic routines
Cryptographic routines are used in variant sha1/2 and crypt. These routines are provided
under the following conditions:

Copyright (c) 2002, Dr Brian Gladman, Worcester, UK. All rights reserved.

LICENSE TERMS

The free distribution and use of this software in both source and binary
form is allowed (with or without changes) provided that:

1. distributions of this source code include the above copyright

notice, this list of conditions and the following disclaimer;

2. distributions in binary form include the above copyright

notice, this list of conditions and the following disclaimer
in the documentation and/or other associated materials;

3. the copyright holders name is not used to endorse products

built using this software without specific written permission.

ALTERNATIVELY, provided that this notice is retained in full, this product

may be distributed under the terms of the GNU General Public License (GPL),
in which case the provisions of the GPL apply INSTEAD OF those given above.

DISCLAIMER

This software is provided as is with no explicit or implied warranties

in respect of its properties, including, but not limited to, correctness
and/or fitness for purpose.

SWI-Prolog 7.4 Reference Manual

Summary
F.1 Predicates
F
The predicate summary is used by the Prolog predicate apropos/1 to suggest predicates from a
keyword.

@/2 Call using calling context

!/0 Cut (discard choicepoints)
,/2 Conjunction of goals
->/2 If-then-else
*->/2 Soft-cut
./2 Consult. Also functional notation
:</2 Select keys from a dict
;/2 Disjunction of two goals
</2 Arithmetic smaller
=/2 True when arguments are unified
=../2 Univ. Term to list conversion
=:=/2 Arithmetic equality
=</2 Arithmetic smaller or equal
==/2 Test for strict equality
=@=/2 Test for structural equality (variant)
=\=/2 Arithmetic not equal
>/2 Arithmetic larger
>=/2 Arithmetic larger or equal
>:</2 Partial dict unification
?=/2 Test of terms can be compared now
@</2 Standard order smaller
@=</2 Standard order smaller or equal
@>/2 Standard order larger
@>=/2 Standard order larger or equal
\+/1 Negation by failure. Same as not/1
\=/2 True if arguments cannot be unified
\==/2 True if arguments are not strictly equal
\=@=/2 Not structural identical
/2 Existential quantification (bagof/3, setof/3)
|/2 Disjunction in DCGs. Same as ;/2
{}/1 DCG escape; constraints
abolish/1 Remove predicate definition from the database
abolish/2 Remove predicate definition from the database

SWI-Prolog 7.4 Reference Manual

526 APPENDIX F. SUMMARY

abolish all tables/0 Abolish computed tables

abolish table subgoals/1 Abolish tables for a goal
abort/0 Abort execution, return to top level
absolute file name/2 Get absolute path name
absolute file name/3 Get absolute path name with options
access file/2 Check access permissions of a file
acyclic term/1 Test term for cycles
add import module/3 Add module to the auto-import list
add nb set/2 Add term to a non-backtrackable set
add nb set/3 Add term to a non-backtrackable set
append/1 Append to a file
apply/2 Call goal with additional arguments
apropos/1 online help Search manual
arg/3 Access argument of a term
assoc to list/2 Convert association tree to list
assert/1 Add a clause to the database
assert/2 Add a clause to the database, give reference
asserta/1 Add a clause to the database (first)
asserta/2 Add a clause to the database (first)
assertion/1 Make assertions about your program
assertz/1 Add a clause to the database (last)
assertz/2 Add a clause to the database (last)
attach console/0 Attach I/O console to thread
attribute goals/3 Project attributes to goals
attr unify hook/2 Attributed variable unification hook
attr portray hook/2 Attributed variable print hook
attvar/1 Type test for attributed variable
at end of stream/0 Test for end of file on input
at end of stream/1 Test for end of file on stream
at halt/1 Register goal to run at halt/1
atom/1 Type check for an atom
atom chars/2 Convert between atom and list of characters
atom codes/2 Convert between atom and list of characters codes
atom concat/3 Contatenate two atoms
atom length/2 Determine length of an atom
atom number/2 Convert between atom and number
atom prefix/2 Test for start of atom
atom string/2 Conversion between atom and string
atom to term/3 Convert between atom and term
atomic/1 Type check for primitive
atomic concat/3 Concatenate two atomic values to an atom
atomic list concat/2 Append a list of atomics
atomic list concat/3 Append a list of atomics with separator
atomics to string/2 Concatenate list of inputs to a string
atomics to string/3 Concatenate list of inputs to a string
autoload/0 Autoload all predicates now
autoload path/1 Add directories for autoloading

SWI-Prolog 7.4 Reference Manual

F.1. PREDICATES 527

b getval/2 Fetch backtrackable global variable

b set dict/3 Destructive assignment on a dict
b setval/2 Assign backtrackable global variable
bagof/3 Find all solutions to a goal
between/3 Integer range checking/generating
blob/2 Type check for a blob
break/0 Start interactive top level
break hook/6 (hook) Debugger hook
byte count/2 Byte-position in a stream
call/1 Call a goal
call/[2..] Call with additional arguments
call cleanup/3 Guard a goal with a cleaup-handler
call cleanup/2 Guard a goal with a cleaup-handler
call dcg/3 As phrase/3 without type checking
call residue vars/2 Find residual attributed variables
call shared object function/2 UNIX: Call C-function in shared (.so) file
call with depth limit/3 Prove goal with bounded depth
call with inference limit/3 Prove goal in limited inferences
callable/1 Test for atom or compound term
cancel halt/1 Cancel halt/0 from an at halt/1 hook
catch/3 Call goal, watching for exceptions
char code/2 Convert between character and character code
char conversion/2 Provide mapping of input characters
char type/2 Classify characters
character count/2 Get character index on a stream
chdir/1 Compatibility: change working directory
chr constraint/1 CHR Constraint declaration
chr show store/1 List suspended CHR constraints
chr trace/0 Start CHR tracer
chr type/1 CHR Type declaration
chr notrace/0 Stop CHR tracer
chr leash/1 Define CHR leashed ports
chr option/2 Specify CHR compilation options
clause/2 Get clauses of a predicate
clause/3 Get clauses of a predicate
clause property/2 Get properties of a clause
close/1 Close stream
close/2 Close stream (forced)
close dde conversation/1 Win32: Close DDE channel
close shared object/1 UNIX: Close shared library (.so file)
collation key/2 Sort key for locale dependent ordering
comment hook/3 (hook) handle comments in sources
compare/3 Compare, using a predicate to determine the order
compile aux clauses/1 Compile predicates for goal expansion/2
compile predicates/1 Compile dynamic code to static
compiling/0 Is this a compilation run?
compound/1 Test for compound term

SWI-Prolog 7.4 Reference Manual

528 APPENDIX F. SUMMARY

compound name arity/3 Name and arity of a compound term

compound name arguments/3 Name and arguments of a compound term
code type/2 Classify a character-code
consult/1 Read (compile) a Prolog source file
context module/1 Get context module of current goal
convert time/8 Break time stamp into fields
convert time/2 Convert time stamp to string
copy stream data/2 Copy all data from stream to stream
copy stream data/3 Copy n bytes from stream to stream
copy predicate clauses/2 Copy clauses between predicates
copy term/2 Make a copy of a term
copy term/3 Copy a term and obtain attribute-goals
copy term nat/2 Make a copy of a term without attributes
create prolog flag/3 Create a new Prolog flag
current arithmetic function/1 Examine evaluable functions
current atom/1 Examine existing atoms
current blob/2 Examine typed blobs
current char conversion/2 Query input character mapping
current engine/1 Enumerate known engines
current flag/1 Examine existing flags
current foreign library/2 shlib Examine loaded shared libraries (.so files)
current format predicate/2 Enumerate user-defined format codes
current functor/2 Examine existing name/arity pairs
current input/1 Get current input stream
current key/1 Examine existing database keys
current locale/1 Get the current locale
current module/1 Examine existing modules
current op/3 Examine current operator declarations
current output/1 Get the current output stream
current predicate/1 Examine existing predicates (ISO)
current predicate/2 Examine existing predicates
current signal/3 Current software signal mapping
current stream/3 Examine open streams
current trie/1 Enumerate known tries
cyclic term/1 Test term for cycles
day of the week/2 Determine ordinal-day from date
date time stamp/2 Convert date structure to time-stamp
date time value/3 Extract info from a date structure
dcg translate rule/2 Source translation of DCG rules
dcg translate rule/4 Source translation of DCG rules
dde current connection/2 Win32: Examine open DDE connections
dde current service/2 Win32: Examine DDE services provided
dde execute/2 Win32: Execute command on DDE server
dde register service/2 Win32: Become a DDE server
dde request/3 Win32: Make a DDE request
dde poke/3 Win32: POKE operation on DDE server
dde unregister service/1 Win32: Terminate a DDE service

SWI-Prolog 7.4 Reference Manual

F.1. PREDICATES 529

debug/0 Test for debugging mode

debug/1 Select topic for debugging
debug/3 Print debugging message on topic
debug control hook/1 (hook) Extend spy/1, etc.
debugging/0 Show debugger status
debugging/1 Test where we are debugging topic
default module/2 Query module inheritance
del attr/2 Delete attribute from variable
del attrs/1 Delete all attributes from variable
del dict/4 Delete Key-Value pair from a dict
delete directory/1 Remove a folder from the file system
delete file/1 Remove a file from the file system
delete import module/2 Remove module from import list
deterministic/1 Test deterministicy of current clause
dif/2 Constrain two terms to be different
directory files/2 Get entries of a directory/folder
discontiguous/1 Indicate distributed definition of a predicate
divmod/4 Compute quotient and remainder of two integers
downcase atom/2 Convert atom to lower-case
duplicate term/2 Create a copy of a term
dwim match/2 Atoms match in Do What I Mean sense
dwim match/3 Atoms match in Do What I Mean sense
dwim predicate/2 Find predicate in Do What I Mean sense
dynamic/1 Indicate predicate definition may change
edit/0 Edit current script- or associated file
edit/1 Edit a file, predicate, module (extensible)
elif/1 Part of conditional compilation (directive)
else/0 Part of conditional compilation (directive)
empty assoc/1 Create/test empty association tree
empty nb set/1 Test/create an empty non-backtrackable set
encoding/1 Define encoding inside a source file
endif/0 End of conditional compilation (directive)
engine create/3 Create an interactor
engine create/4 Create an interactor
engine fetch/1 Get term from caller
engine next/2 Ask interactor for next term
engine next reified/2 Ask interactor for next term
engine post/2 Send term to an interactor
engine post/3 Send term to an interactor and wait for reply
engine self/1 Get handle to running interactor
engine yield/1 Make term available to caller
ensure loaded/1 Consult a file if that has not yet been done
erase/1 Erase a database record or clause
exception/3 (hook) Handle runtime exceptions
exists directory/1 Check existence of directory
exists file/1 Check existence of file
exists source/1 Check existence of a Prolog source

SWI-Prolog 7.4 Reference Manual

530 APPENDIX F. SUMMARY

expand answer/2 Expand answer of query

expand file name/2 Wildcard expansion of file names
expand file search path/2 Wildcard expansion of file paths
expand goal/2 Compiler: expand goal in clause-body
expand goal/4 Compiler: expand goal in clause-body
expand query/4 Expanded entered query
expand term/2 Compiler: expand read term into clause(s)
expand term/4 Compiler: expand read term into clause(s)
expects dialect/1 For which Prolog dialect is this code written?
explain/1 explain Explain argument
explain/2 explain 2nd argument is explanation of first
export/1 Export a predicate from a module
fail/0 Always false
false/0 Always false
fast term serialized/2 Fast term (de-)serialization
fast read/2 Read binary term serialization
fast write/2 Write binary term serialization
current prolog flag/2 Get system configuration parameters
file base name/2 Get file part of path
file directory name/2 Get directory part of path
file name extension/3 Add, remove or test file extensions
file search path/2 Define path-aliases for locating files
find chr constraint/1 Returns a constraint from the store
findall/3 Find all solutions to a goal
findall/4 Difference list version of findall/3
findnsols/4 Find first N solutions
findnsols/5 Difference list version of findnsols/4
fill buffer/1 Fill the input buffer of a stream
flag/3 Simple global variable system
float/1 Type check for a floating point number
flush output/0 Output pending characters on current stream
flush output/1 Output pending characters on specified stream
forall/2 Prove goal for all solutions of another goal
format/1 Formatted output
format/2 Formatted output with arguments
format/3 Formatted output on a stream
format time/3 C strftime() like date/time formatter
format time/4 date/time formatter with explicit locale
format predicate/2 Program format/[1,2]
term attvars/2 Find attributed variables in a term
term variables/2 Find unbound variables in a term
term variables/3 Find unbound variables in a term
text to string/2 Convert arbitrary text to a string
freeze/2 Delay execution until variable is bound
frozen/2 Query delayed goals on var
functor/3 Get name and arity of a term or construct a term
garbage collect/0 Invoke the garbage collector

SWI-Prolog 7.4 Reference Manual

F.1. PREDICATES 531

garbage collect atoms/0 Invoke the atom garbage collector

garbage collect clauses/0 Invoke clause garbage collector
gen assoc/3 Enumerate members of association tree
gen nb set/2 Generate members of non-backtrackable set
gensym/2 Generate unique atoms from a base
get/1 Read first non-blank character
get/2 Read first non-blank character from a stream
get assoc/3 Fetch key from association tree
get assoc/5 Fetch key from association tree
get attr/3 Fetch named attribute from a variable
get attrs/2 Fetch all attributes of a variable
get byte/1 Read next byte (ISO)
get byte/2 Read next byte from a stream (ISO)
get char/1 Read next character as an atom (ISO)
get char/2 Read next character from a stream (ISO)
get code/1 Read next character (ISO)
get code/2 Read next character from a stream (ISO)
get dict/3 Get the value associated to a key from a dict
get dict/5 Replace existing value in a dict
get flag/2 Get value of a flag
get single char/1 Read next character from the terminal
get string code/3 Get character code at index in string
get time/1 Get current time
get0/1 Read next character
get0/2 Read next character from a stream
getenv/2 Get shell environment variable
goal expansion/2 Hook for macro-expanding goals
goal expansion/4 Hook for macro-expanding goals
ground/1 Verify term holds no unbound variables
gdebug/0 Debug using graphical tracer
gspy/1 Spy using graphical tracer
gtrace/0 Trace using graphical tracer
guitracer/0 Install hooks for the graphical debugger
gxref/0 Cross-reference loaded program
halt/0 Exit from Prolog
halt/1 Exit from Prolog with status
term hash/2 Hash-value of ground term
term hash/4 Hash-value of term with depth limit
help/0 Give help on help
help/1 Give help on predicates and show parts of manual
help hook/1 (hook) User-hook in the help-system
if/1 Start conditional compilation (directive)
ignore/1 Call the argument, but always succeed
import/1 Import a predicate from a module
import module/2 Query import modules
in pce thread/1 Run goal in XPCE thread
in pce thread sync/1 Run goal in XPCE thread

SWI-Prolog 7.4 Reference Manual

532 APPENDIX F. SUMMARY

include/1 Include a file with declarations

initialization/1 Initialization directive
initialization/2 Initialization directive
instance/2 Fetch clause or record from reference
integer/1 Type check for integer
interactor/0 Start new thread with console and top level
is/2 Evaluate arithmetic expression
is absolute file name/1 True if arg defines an absolute path
is assoc/1 Verify association list
is engine/1 Type check for an engine handle
is list/1 Type check for a list
is dict/1 Type check for a dict
is dict/2 Type check for a dict in a class
is stream/1 Type check for a stream handle
is thread/1 Type check for an thread handle
join threads/0 Join all terminated threads interactively
keysort/2 Sort, using a key
known licenses/0 Print known licenses
last/2 Last element of a list
leash/1 Change ports visited by the tracer
length/2 Length of a list
library directory/1 (hook) Directories holding Prolog libraries
license/0 Evaluate licenses of loaded modules
license/1 Define license for current file
license/2 Define license for named module
line count/2 Line number on stream
line position/2 Character position in line on stream
list debug topics/0 List registered topics for debugging
list to assoc/2 Create association tree from list
list to set/2 Remove duplicates from a list
list strings/0 Help porting to version 7
listing/0 List program in current module
listing/1 List predicate
load files/1 Load source files
load files/2 Load source files with options
load foreign library/1 shlib Load shared library (.so file)
load foreign library/2 shlib Load shared library (.so file)
locale create/3 Create a new locale object
locale destroy/1 Destroy a locale object
locale property/2 Query properties of locale objects
locale sort/2 Language dependent sort of atoms
make/0 Reconsult all changed source files
make directory/1 Create a folder on the file system
make library index/1 Create autoload file INDEX.pl
make library index/2 Create selective autoload file INDEX.pl
map assoc/2 Map association tree
map assoc/3 Map association tree

SWI-Prolog 7.4 Reference Manual

F.1. PREDICATES 533

dict create/3 Create a dict from data

dict pairs/3 Convert between dict and list of pairs
max assoc/3 Highest key in association tree
memberchk/2 Deterministic member/2
message hook/3 Intercept print message/2
message line element/2 (hook) Intercept print message lines/3
message property/2 (hook) Define display of a message
message queue create/1 Create queue for thread communication
message queue create/2 Create queue for thread communication
message queue destroy/1 Destroy queue for thread communication
message queue property/2 Query message queue properties
message to string/2 Translate message-term to string
meta predicate/1 Declare access to other predicates
min assoc/3 Lowest key in association tree
module/1 Query/set current type-in module
module/2 Declare a module
module/3 Declare a module with language options
module property/2 Find properties of a module
module transparent/1 Indicate module based meta-predicate
msort/2 Sort, do not remove duplicates
multifile/1 Indicate distributed definition of predicate
mutex create/1 Create a thread-synchronisation device
mutex create/2 Create a thread-synchronisation device
mutex destroy/1 Destroy a mutex
mutex lock/1 Become owner of a mutex
mutex property/2 Query mutex properties
mutex statistics/0 Print statistics on mutex usage
mutex trylock/1 Become owner of a mutex (non-blocking)
mutex unlock/1 Release ownership of mutex
mutex unlock all/0 Release ownership of all mutexes
name/2 Convert between atom and list of character codes
nb current/2 Enumerate non-backtrackable global variables
nb delete/1 Delete a non-backtrackable global variable
nb getval/2 Fetch non-backtrackable global variable
nb link dict/3 Non-backtrackable assignment to dict
nb linkarg/3 Non-backtrackable assignment to term
nb linkval/2 Assign non-backtrackable global variable
nb set to list/2 Convert non-backtrackable set to list
nb set dict/3 Non-backtrackable assignment to dict
nb setarg/3 Non-backtrackable assignment to term
nb setval/2 Assign non-backtrackable global variable
nl/0 Generate a newline
nl/1 Generate a newline on a stream
nodebug/0 Disable debugging
nodebug/1 Disable debug-topic
noguitracer/0 Disable the graphical debugger
nonvar/1 Type check for bound term

SWI-Prolog 7.4 Reference Manual

534 APPENDIX F. SUMMARY

noprofile/1 Hide (meta-) predicate for the profiler

noprotocol/0 Disable logging of user interaction
normalize space/2 Normalize white space
nospy/1 Remove spy point
nospyall/0 Remove all spy points
not/1 Negation by failure (argument not provable). Same as \+/1
notrace/0 Stop tracing
notrace/1 Do not debug argument goal
nth clause/3 N-th clause of a predicate
nth integer root and remainder/4 Integer root and remainder
number/1 Type check for integer or float
number chars/2 Convert between number and one-char atoms
number codes/2 Convert between number and character codes
number string/2 Convert between number and string
numbervars/3 Number unbound variables of a term
numbervars/4 Number unbound variables of a term
on signal/3 Handle a software signal
once/1 Call a goal deterministically
op/3 Declare an operator
open/3 Open a file (creating a stream)
open/4 Open a file (creating a stream)
open dde conversation/3 Win32: Open DDE channel
open null stream/1 Open a stream to discard output
open resource/3 Open a program resource as a stream
open shared object/2 UNIX: Open shared library (.so file)
open shared object/3 UNIX: Open shared library (.so file)
open string/2 Open a string as a stream
ord list to assoc/2 Convert ordered list to assoc
parse time/2 Parse text to a time-stamp
parse time/3 Parse text to a time-stamp
pce dispatch/1 Run XPCE GUI in separate thread
pce call/1 Run goal in XPCE GUI thread
peek byte/1 Read byte without removing
peek byte/2 Read byte without removing
peek char/1 Read character without removing
peek char/2 Read character without removing
peek code/1 Read character-code without removing
peek code/2 Read character-code without removing
peek string/3 Read a string without removing
phrase/2 Activate grammar-rule set
phrase/3 Activate grammar-rule set (returning rest)
phrase from quasi quotation/2 Parse quasi quotation with DCG
please/3 Query/change environment parameters
plus/3 Logical integer addition
portray/1 (hook) Modify behaviour of print/1
portray clause/1 Pretty print a clause
portray clause/2 Pretty print a clause to a stream

SWI-Prolog 7.4 Reference Manual

F.1. PREDICATES 535

predicate property/2 Query predicate attributes

predsort/3 Sort, using a predicate to determine the order
print/1 Print a term
print/2 Print a term on a stream
print message/2 Print message from (exception) term
print message lines/3 Print message to stream
profile/1 Obtain execution statistics
profile/2 Obtain execution statistics
profile count/3 Obtain profile results on a predicate
profiler/2 Obtain/change status of the profiler
prolog/0 Run interactive top level
prolog choice attribute/3 Examine the choice point stack
prolog current choice/1 Reference to most recent choice point
prolog current frame/1 Reference to goals environment stack
prolog cut to/1 Realise global cuts
prolog edit:locate/2 Locate targets for edit/1
prolog edit:locate/3 Locate targets for edit/1
prolog edit:edit source/1 Call editor for edit/1
prolog edit:edit command/2 Specify editor activation
prolog edit:load/0 Load edit/1 extensions
prolog exception hook/4 Rewrite exceptions
prolog file type/2 Define meaning of file extension
prolog frame attribute/3 Obtain information on a goal environment
prolog ide/1 Program access to the development environment
prolog list goal/1 (hook) Intercept tracer L command
prolog load context/2 Context information for directives
prolog load file/2 (hook) Program load files/2
prolog skip level/2 Indicate deepest recursion to trace
prolog skip frame/1 Perform skip on a frame
prolog stack property/2 Query properties of the stacks
prolog to os filename/2 Convert between Prolog and OS filenames
prolog trace interception/4 user Intercept the Prolog tracer
project attributes/2 Project constraints to query variables
prompt1/1 Change prompt for 1 line
prompt/2 Change the prompt used by read/1
protocol/1 Make a log of the user interaction
protocola/1 Append log of the user interaction to file
protocolling/1 On what file is user interaction logged
public/1 Declaration that a predicate may be called
put/1 Write a character
put/2 Write a character on a stream
put assoc/4 Add Key-Value to association tree
put attr/3 Put attribute on a variable
put attrs/2 Set/replace all attributes on a variable
put byte/1 Write a byte
put byte/2 Write a byte on a stream
put char/1 Write a character

SWI-Prolog 7.4 Reference Manual

536 APPENDIX F. SUMMARY

put char/2 Write a character on a stream

put code/1 Write a character-code
put code/2 Write a character-code on a stream
put dict/3 Add/replace multiple keys in a dict
put dict/4 Add/replace a single key in a dict
qcompile/1 Compile source to Quick Load File
qcompile/2 Compile source to Quick Load File
qsave program/1 Create runtime application
qsave program/2 Create runtime application
quasi quotation syntax/1 Declare quasi quotation syntax
quasi quotation syntax error/1 Raise syntax error
random property/1 Query properties of random generation
rational/1 Type check for a rational number
rational/3 Decompose a rational
read/1 Read Prolog term
read/2 Read Prolog term from stream
read clause/3 Read clause from stream
read history/6 Read using history substitution
read link/3 Read a symbolic link
read pending codes/3 Fetch buffered input from a stream
read pending chars/3 Fetch buffered input from a stream
read string/3 Read a number of characters into a string
read string/5 Read string upto a delimiter
read term/2 Read term with options
read term/3 Read term with options from stream
read term from atom/3 Read term with options from atom
recorda/2 Record term in the database (first)
recorda/3 Record term in the database (first)
recorded/2 Obtain term from the database
recorded/3 Obtain term from the database
recordz/2 Record term in the database (last)
recordz/3 Record term in the database (last)
redefine system predicate/1 Abolish system definition
reexport/1 Load files and re-export the imported predicates
reexport/2 Load predicates from a file and re-export it
reload foreign libraries/0 Reload DLLs/shared objects
reload library index/0 Force reloading the autoload index
rename file/2 Change name of file
repeat/0 Succeed, leaving infinite backtrack points
require/1 This file requires these predicates
reset/3 Wrapper for delimited continuations
reset gensym/1 Reset a gensym key
reset gensym/0 Reset all gensym keys
reset profiler/0 Clear statistics obtained by the profiler
resource/3 Declare a program resource
retract/1 Remove clause from the database
retractall/1 Remove unifying clauses from the database

SWI-Prolog 7.4 Reference Manual

F.1. PREDICATES 537

same file/2 Succeeds if arguments refer to same file

same term/2 Test terms to be at the same address
see/1 Change the current input stream
seeing/1 Query the current input stream
seek/4 Modify the current position in a stream
seen/0 Close the current input stream
select dict/2 Select matching attributes from a dict
select dict/3 Select matching attributes from a dict
set end of stream/1 Set physical end of an open file
set flag/2 Set value of a flag
set input/1 Set current input stream from a stream
set locale/1 Set the default local
set module/1 Set properties of a module
set output/1 Set current output stream from a stream
set prolog IO/3 Prepare streams for interactive session
set prolog flag/2 Define a system feature
set prolog stack/2 Modify stack characteristics
set random/1 Control random number generation
set stream/2 Set stream attribute
set stream position/2 Seek stream to position
setup call cleanup/3 Undo side-effects safely
setup call catcher cleanup/4 Undo side-effects safely
setarg/3 Destructive assignment on term
setenv/2 Set shell environment variable
setlocale/3 Set/query C-library regional information
setof/3 Find all unique solutions to a goal
shell/1 Execute OS command
shell/2 Execute OS command
shift/1 Shift control to the closest reset/3
show profile/1 Show results of the profiler
size file/2 Get size of a file in characters
size nb set/2 Determine size of non-backtrackable set
skip/1 Skip to character in current input
skip/2 Skip to character on stream
sleep/1 Suspend execution for specified time
sort/2 Sort elements in a list
sort/4 Sort elements in a list
source exports/2 Check whether source exports a predicate
source file/1 Examine currently loaded source files
source file/2 Obtain source file of predicate
source file property/2 Information about loaded files
source location/2 Location of last read term
split string/4 Break a string into substrings
spy/1 Force tracer on specified predicate
stamp date time/3 Convert time-stamp to date structure
statistics/0 Show execution statistics
statistics/2 Obtain collected statistics

SWI-Prolog 7.4 Reference Manual

538 APPENDIX F. SUMMARY

stream pair/3 Create/examine a bi-directional stream

stream position data/3 Access fields from stream position
stream property/2 Get stream properties
string/1 Type check for string
string concat/3 atom concat/3 for strings
string length/2 Determine length of a string
string chars/2 Conversion between string and list of characters
string codes/2 Conversion between string and list of character codes
string code/3 Get or find a character code in a string
string lower/2 Case conversion to lower case
string upper/2 Case conversion to upper case
string predicate/1 (hook) Predicate contains strings
strip module/3 Extract context module and term
style check/1 Change level of warnings
sub atom/5 Take a substring from an atom
sub atom icasechk/3 Case insensitive substring match
sub string/5 Take a substring from a string
subsumes term/2 One-sided unification test
succ/2 Logical integer successor relation
swritef/2 Formatted write on a string
swritef/3 Formatted write on a string
tab/1 Output number of spaces
tab/2 Output number of spaces on a stream
table/1 Declare predicate to be tabled
tdebug/0 Switch all threads into debug mode
tdebug/1 Switch a thread into debug mode
tell/1 Change current output stream
telling/1 Query current output stream
term expansion/2 (hook) Convert term before compilation
term expansion/4 (hook) Convert term before compilation
term string/2 Read/write a term from/to a string
term string/3 Read/write a term from/to a string
term subsumer/3 Most specific generalization of two terms
term to atom/2 Convert between term and atom
thread at exit/1 Register goal to be called at exit
thread create/3 Create a new Prolog task
thread detach/1 Make thread cleanup after completion
thread exit/1 Terminate Prolog task with value
thread get message/1 Wait for message
thread get message/2 Wait for message in a queue
thread get message/3 Wait for message in a queue
thread initialization/1 Run action at start of thread
thread join/2 Wait for Prolog task-completion
thread local/1 Declare thread-specific clauses for a predicate
thread message hook/3 Thread local message hook/3
thread peek message/1 Test for message
thread peek message/2 Test for message in a queue

SWI-Prolog 7.4 Reference Manual

F.1. PREDICATES 539

thread property/2 Examine Prolog threads

thread self/1 Get identifier of current thread
thread send message/2 Send message to another thread
thread send message/3 Send message to another thread
thread setconcurrency/2 Number of active threads
thread signal/2 Execute goal in another thread
thread statistics/3 Get statistics of another thread
threads/0 List running threads
throw/1 Raise an exception (see catch/3)
time/1 Determine time needed to execute goal
time file/2 Get last modification time of file
tmp file/2 Create a temporary filename
tmp file stream/3 Create a temporary file and open it
tnodebug/0 Switch off debug mode in all threads
tnodebug/1 Switch off debug mode in a thread
told/0 Close current output
tprofile/1 Profile a thread for some period
trace/0 Start the tracer
trace/1 Set trace point on predicate
trace/2 Set/Clear trace point on ports
tracing/0 Query status of the tracer
trie destroy/1 Destroy a trie
trie gen/3 Get all terms from a trie
trie insert/3 Insert term into a trie
trie insert new/3 Insert term into a trie
trie lookup/3 Lookup a term in a trie
trie new/1 Create a trie
trie property/2 Examine a tries properties
trie term/2 Get term from a trie by handle
trim stacks/0 Release unused memory resources
true/0 Succeed
tspy/1 Set spy point and enable debugging in all threads
tspy/2 Set spy point and enable debugging in a thread
tty get capability/3 Get terminal parameter
tty goto/2 Goto position on screen
tty put/2 Write control string to terminal
tty size/2 Get row/column size of the terminal
ttyflush/0 Flush output on terminal
unify with occurs check/2 Logically sound unification
unifiable/3 Determining binding required for unification
unix/1 OS interaction
unknown/2 Trap undefined predicates
unload file/1 Unload a source file
unload foreign library/1 shlib Detach shared library (.so file)
unload foreign library/2 shlib Detach shared library (.so file)
unsetenv/1 Delete shell environment variable
upcase atom/2 Convert atom to upper-case

SWI-Prolog 7.4 Reference Manual

540 APPENDIX F. SUMMARY

use foreign library/1 Load DLL/shared object (directive)

use foreign library/2 Load DLL/shared object (directive)
use module/1 Import a module
use module/2 Import predicates from a module
valid string goal/1 (hook) Goal handles strings
var/1 Type check for unbound variable
var number/2 Check that var is numbered by numbervars
var property/2 Variable properties during macro expansion
variant sha1/2 Term-hash for term-variants
variant hash/2 Term-hash for term-variants
version/0 Print system banner message
version/1 Add messages to the system banner
visible/1 Ports that are visible in the tracer
volatile/1 Predicates that are not saved
wait for input/3 Wait for input with optional timeout
when/2 Execute goal when condition becomes true
wildcard match/2 Csh(1) style wildcard match
win add dll directory/1 Add directory to DLL search path
win add dll directory/2 Add directory to DLL search path
win remove dll directory/1 Remove directory from DLL search path
win exec/2 Win32: spawn Windows task
win has menu/0 Win32: true if console menu is available
win folder/2 Win32: get special folder by CSIDL
win insert menu/2 swipl-win.exe: add menu
win insert menu item/4 swipl-win.exe: add item to menu
win shell/2 Win32: open document through Shell
win shell/3 Win32: open document through Shell
win registry get value/3 Win32: get registry value
win window pos/1 Win32: change size and position of window
window title/2 Win32: change title of window
with mutex/2 Run goal while holding mutex
with output to/2 Write to strings and more
with quasi quotation input/3 Parse quasi quotation from stream
working directory/2 Query/change CWD
write/1 Write term
write/2 Write term to stream
writeln/1 Write term, followed by a newline
writeln/2 Write term, followed by a newline to a stream
write canonical/1 Write a term with quotes, ignore operators
write canonical/2 Write a term with quotes, ignore operators on a stream
write length/3 Dermine #characters to output a term
write term/2 Write term with options
write term/3 Write term with options to stream
writef/1 Formatted write
writef/2 Formatted write on stream
writeq/1 Write term, insert quotes
writeq/2 Write term, insert quotes on stream

SWI-Prolog 7.4 Reference Manual

F.2. LIBRARY PREDICATES 541

F.2 Library predicates

F.2.1 library(aggregate)

aggregate/3 Aggregate bindings in Goal according to Template.

aggregate/4 Aggregate bindings in Goal according to Template.
aggregate all/3 Aggregate bindings in Goal according to Template.
aggregate all/4 Aggregate bindings in Goal according to Template.
foreach/2 True if conjunction of results is true.
free variables/4 Find free variables in bagof/setof template.

F.2.2 library(apply)

exclude/3 Filter elements for which Goal fails.

foldl/4 Fold a list, using arguments of the list as left argument.
foldl/5 Fold a list, using arguments of the list as left argument.
foldl/6 Fold a list, using arguments of the list as left argument.
foldl/7 Fold a list, using arguments of the list as left argument.
include/3 Filter elements for which Goal succeeds.
maplist/2 True if Goal can successfully be applied on all elements of List.
maplist/3 As maplist/2, operating on pairs of elements from two lists.
maplist/4 As maplist/2, operating on triples of elements from three lists.
maplist/5 As maplist/2, operating on quadruples of elements from four lists.
partition/4 Filter elements of List according to Pred.
partition/5 Filter List according to Pred in three sets.
scanl/4 Left scan of list.
scanl/5 Left scan of list.
scanl/6 Left scan of list.
scanl/7 Left scan of list.

F.2.3 library(assoc)

assoc to list/2 Translate assoc into a pairs list

assoc to keys/2 Translate assoc into a key list
assoc to values/2 Translate assoc into a value list
empty assoc/1 Test/create an empty assoc
gen assoc/3 Non-deterministic enumeration of assoc
get assoc/3 Get associated value
get assoc/5 Get and replace associated value
list to assoc/2 Translate pair list to assoc
map assoc/2 Test assoc values
map assoc/3 Map assoc values
max assoc/3 Max key-value of an assoc
min assoc/3 Min key-value of an assoc
ord list to assoc/2 Translate ordered list into an assoc
put assoc/4 Add association to an assoc

SWI-Prolog 7.4 Reference Manual

542 APPENDIX F. SUMMARY

F.2.4 library(broadcast)

broadcast/1 Send event notification

broadcast request/1 Request all agents
listen/2 Listen to event notifications
listen/3 Listen to event notifications
unlisten/1 Stop listening to event notifications
unlisten/2 Stop listening to event notifications
unlisten/3 Stop listening to event notifications
listening/3 Who is listening to event notifications?

F.2.5 library(charsio)

atom to chars/2 Convert Atom into a list of character codes.

atom to chars/3 Convert Atom into a difference list of character codes.
format to chars/3 Use format/2 to write to a list of character codes.
format to chars/4 Use format/2 to write to a difference list of character codes.
number to chars/2 Convert Atom into a list of character codes.
number to chars/3 Convert Number into a difference list of character codes.
open chars stream/2 Open Codes as an input stream.
read from chars/2 Read Codes into Term.
read term from chars/3 Read Codes into Term.
with output to chars/2 Run Goal as with once/1.
with output to chars/3 Run Goal as with once/1.
with output to chars/4 Same as with output to chars/3 using an explicit stream.
write to chars/2 Write a term to a code list.
write to chars/3 Write a term to a code list.

F.2.6 library(check)

check/0 Run all consistency checks defined by checker/2.

checker/2 Register code validation routines.
list autoload/0 Report predicates that may be auto-loaded.
list redefined/0 Lists predicates that are defined in the global module =user= as well as in a normal module; tha
list strings/0 List strings that appear in clauses.
list strings/1 List strings that appear in clauses.
list trivial fails/0 List goals that trivially fail because there is no matching clause.
list trivial fails/1 List goals that trivially fail because there is no matching clause.
list undefined/0 Report undefined predicates.
list undefined/1 Report undefined predicates.
list void declarations/0 List predicates that have declared attributes, but no clauses.
string predicate/1 Multifile hook to disable list strings/0 on the given predicate.
trivial fail goal/1 Multifile hook that tells list trivial fails/0 to accept Goal as valid.
valid string goal/1 Multifile hook that qualifies Goal as valid for list strings/0.

SWI-Prolog 7.4 Reference Manual

F.2. LIBRARY PREDICATES 543

F.2.7 library(clpb)

labeling/1 Enumerate concrete solutions.

random labeling/2 Select a single random solution.
sat/1 True iff Expr is a satisfiable Boolean expression.
sat count/2 Count the number of admissible assignments.
taut/2 Tautology check.
weighted maximum/3 Enumerate weighted optima over admissible assignments.

F.2.8 library(clpfd)

#/\/2 P and Q hold.

#</2 The arithmetic expression X is less than Y.
#<==/2 Q implies P.
#<==>/2 P and Q are equivalent.
#=/2 The arithmetic expression X equals Y.
#=</2 The arithmetic expression X is less than or equal to Y.
#==>/2 P implies Q.
#>/2 Same as Y #< X.
#>=/2 Same as Y #=< X.
#\/1 Q does not hold.
#\/2 Either P holds or Q holds, but not both.
#\//2 P or Q holds.
#\=/2 The arithmetic expressions X and Y evaluate to distinct integers.
all different/1 Like all distinct/1, but with weaker propagation.
all distinct/1 True iff Vars are pairwise distinct.
automaton/3 Describes a list of finite domain variables with a finite automaton.
automaton/8 Describes a list of finite domain variables with a finite automaton.
chain/2 Zs form a chain with respect to Relation.
circuit/1 True iff the list Vs of finite domain variables induces a Hamiltonian circuit.
cumulative/1 Equivalent to cumulative(Tasks, [limit(1)]).
cumulative/2 Schedule with a limited resource.
disjoint2/1 True iff Rectangles are not overlapping.
element/3 The N-th element of the list of finite domain variables Vs is V.
fd dom/2 Dom is the current domain (see in/2) of Var.
fd inf/2 Inf is the infimum of the current domain of Var.
fd size/2 Reflect the current size of a domain.
fd sup/2 Sup is the supremum of the current domain of Var.
fd var/1 True iff Var is a CLP(FD) variable.
global cardinality/2 Global Cardinality constraint.
global cardinality/3 Global Cardinality constraint.
in/2 Var is an element of Domain.
indomain/1 Bind Var to all feasible values of its domain on backtracking.
ins/2 The variables in the list Vars are elements of Domain.
label/1 Equivalent to labeling([], Vars).
labeling/2 Assign a value to each variable in Vars.

SWI-Prolog 7.4 Reference Manual

544 APPENDIX F. SUMMARY

lex chain/1 Lists are lexicographically non-decreasing.

scalar product/4 True iff the scalar product of Cs and Vs is in relation Rel to Expr.
serialized/2 Describes a set of non-overlapping tasks.
sum/3 The sum of elements of the list Vars is in relation Rel to Expr.
transpose/2 Transpose a list of lists of the same length.
tuples in/2 True iff all Tuples are elements of Relation.
zcompare/3 Analogous to compare/3, with finite domain variables A and B.

F.2.9 library(clpqr)

entailed/1 Check if constraint is entailed

inf/2 Find the infimum of an expression
sup/2 Find the supremum of an expression
minimize/1 Minimizes an expression
maximize/1 Maximizes an expression
bb inf/3 Infimum of expression for mixed-integer problems
bb inf/4 Infimum of expression for mixed-integer problems
bb inf/5 Infimum of expression for mixed-integer problems
dump/3 Dump constraints on variables

F.2.10 library(csv)

csv read file/2 Read a CSV file into a list of rows.

csv read file/3 Read a CSV file into a list of rows.
csv read file row/3 True when Row is a row in File.
csv write file/2 Write a list of Prolog terms to a CSV file.
csv write file/3 Write a list of Prolog terms to a CSV file.
csv write stream/3 Write the rows in Data to Stream.
csv//1 Prolog DCG to read/write CSV data.
csv//2 Prolog DCG to read/write CSV data.

F.2.11 library(debug)

assertion/1 Acts similar to C assert() macro.

assertion failed/2 This hook is called if the Goal of assertion/1 fails.
debug/1 Add/remove a topic from being printed.
debug/3 Format a message if debug topic is enabled.
debug message context/1 Specify additional context for debug messages.
debug print hook/3 Hook called by debug/3.
debugging/1 Examine debug topics.
debugging/2 Examine debug topics.
list debug topics/0 List currently known debug topics and their setting.
nodebug/1 Add/remove a topic from being printed.

F.2.12 library(error)

SWI-Prolog 7.4 Reference Manual

F.2. LIBRARY PREDICATES 545

current type/3 True when Type is a currently defined type and Var satisfies Type of the body term Body succee
domain error/2 The argument is of the proper type, but has a value that is outside the supported values.
existence error/2 Term is of the correct type and correct domain, but there is no existing (external) resource that i
has type/2 True if Term satisfies Type.
instantiation error/1 An argument is under-instantiated.
is of type/2 True if Term satisfies Type.
must be/2 True if Term satisfies the type constraints for Type.
permission error/3 It is not allowed to perform Action on the object Term that is of the given Type.
representation error/1 A representation error indicates a limitation of the implementation.
resource error/1 A goal cannot be completed due to lack of resources.
syntax error/1 A text has invalid syntax.
type error/2 Tell the user that Term is not of the expected Type.
uninstantiation error/1 An argument is over-instantiated.

F.2.13 library(iostream)
F.2.14 library(summaries.d/iostream/tex)
F.2.15 library(lists)

append/2 Concatenate a list of lists.

append/3 List1AndList2 is the concatenation of List1 and List2.
delete/3 Delete matching elements from a list.
flatten/2 Is true if FlatList is a non-nested version of NestedList.
intersection/3 True if Set3 unifies with the intersection of Set1 and Set2.
is set/1 True if Set is a proper list without duplicates.
last/2 Succeeds when Last is the last element of List.
list to set/2 True when Set has the same elements as List in the same order.
max list/2 True if Max is the largest number in List.
max member/2 True when Max is the largest member in the standard order of terms.
member/2 True if Elem is a member of List.
min list/2 True if Min is the smallest number in List.
min member/2 True when Min is the smallest member in the standard order of terms.
nextto/3 True if Y directly follows X in List.
nth0/3 True when Elem is the Indexth element of List.
nth0/4 Select/insert element at index.
nth1/3 Is true when Elem is the Indexth element of List.
nth1/4 As nth0/4, but counting starts at 1.
numlist/3 List is a list [Low, Low+1, ... High].
permutation/2 True when Xs is a permutation of Ys.
prefix/2 True iff Part is a leading substring of Whole.
proper length/2 True when Length is the number of elements in the proper list List.
reverse/2 Is true when the elements of List2 are in reverse order compared to List1.
same length/2 Is true when List1 and List2 are lists with the same number of elements.
select/3 Is true when List1, with Elem removed, results in List2.
select/4 Select from two lists at the same positon.
selectchk/3 Semi-deterministic removal of first element in List that unifies with Elem.

SWI-Prolog 7.4 Reference Manual

546 APPENDIX F. SUMMARY

selectchk/4 Semi-deterministic version of select/4.

subset/2 True if all elements of SubSet belong to Set as well.
subtract/3 Delete all elements in Delete from Set.
sum list/2 Sum is the result of adding all numbers in List.
union/3 True if Set3 unifies with the union of Set1 and Set2.

F.2.16 library(option)

dict options/2 Convert between an option list and a dictionary.

merge options/3 Merge two option lists.
meta options/3 Perform meta-expansion on options that are module-sensitive.
option/2 Get an Option from OptionList.
option/3 Get an Option from OptionList.
select option/3 Get and remove Option from an option list.
select option/4 Get and remove Option with default value.

F.2.17 library(optparse)

opt arguments/3 Extract commandline options according to a specification.

opt help/2 True when Help is a help string synthesized from OptsSpec.
opt parse/4 Equivalent to opt parse(OptsSpec, ApplArgs, Opts, PositionalArgs, []).
opt parse/5 Parse the arguments Args (as list of atoms) according to OptsSpec.
parse type/3 Hook to parse option text Codes to an object of type Type.

F.2.18 library(ordsets)

is ordset/1 True if Term is an ordered set.

list to ord set/2 Transform a list into an ordered set.
ord add element/3 Insert an element into the set.
ord del element/3 Delete an element from an ordered set.
ord disjoint/2 True if Set1 and Set2 have no common elements.
ord empty/1 True when List is the empty ordered set.
ord intersect/2 True if both ordered sets have a non-empty intersection.
ord intersect/3 Intersection holds the common elements of Set1 and Set2.
ord intersection/2 Intersection of a powerset.
ord intersection/3 Intersection holds the common elements of Set1 and Set2.
ord intersection/4 Intersection and difference between two ordered sets.
ord memberchk/2 True if Element is a member of OrdSet, compared using ==.
ord selectchk/3 Selectchk/3, specialised for ordered sets.
ord seteq/2 True if Set1 and Set2 have the same elements.
ord subset/2 Is true if all elements of Sub are in Super.
ord subtract/3 Diff is the set holding all elements of InOSet that are not in NotInOSet.
ord symdiff/3 Is true when Difference is the symmetric difference of Set1 and Set2.
ord union/2 True if Union is the union of all elements in the superset SetOfSets.
ord union/3 Union is the union of Set1 and Set2.
ord union/4 True iff ord union(Set1, Set2, Union) and ord subtract(Set2, Set1, New).

SWI-Prolog 7.4 Reference Manual

F.2. LIBRARY PREDICATES 547

F.2.19 library(persistency)

current persistent predicate/1 True if PI is a predicate that provides access to the persistent database DB.
db attach/2 Use File as persistent database for the calling module.
db detach/0 Detach persistency from the calling module and delete all persistent clauses from the Pro
db sync/1 Synchronise database with the associated file.
db sync all/1 Sync all registered databases.
persistent/1 Declare dynamic database terms.

F.2.20 library(predicate options)

assert predicate options/4 As predicate options(:PI, +Arg, +Options).

check predicate option/3 Verify predicate options at runtime.
check predicate options/0 Analyse loaded program for erroneous options.
current option arg/2 True when Arg of PI processes predicate options.
current predicate option/3 True when Arg of PI processes Option.
current predicate options/3 True when Options is the current active option declaration for PI on Arg.
derive predicate options/0 Derive new predicate option declarations.
derived predicate options/1 Derive predicate option declarations for a module.
derived predicate options/3 Derive option arguments using static analysis.
predicate options/3 Declare that the predicate PI processes options on Arg.
retractall predicate options/0 Remove all dynamically (derived) predicate options.

F.2.21 library(prologpack)

environment/2 Hook to define the environment for building packs.

pack info/1 Print more detailed information about Pack.
pack install/1 Install a package.
pack install/2 Install package Name.
pack list/1 Query package server and installed packages and display results.
pack list installed/0 List currently installed packages.
pack property/2 True when Property is a property of Pack.
pack rebuild/0 Rebuild foreign components of all packages.
pack rebuild/1 Rebuilt possible foreign components of Pack.
pack remove/1 Remove the indicated package.
pack search/1 Query package server and installed packages and display results.
pack upgrade/1 Try to upgrade the package Pack.
pack url file/2 True if File is a unique id for the referenced pack and version.

F.2.22 library(prologxref)

prolog:called by/2 (hook) Extend cross-referencer

xref built in/1 Examine defined built-ins
xref called/3 Examine called predicates
xref clean/1 Remove analysis of source
xref current source/1 Examine cross-referenced sources

SWI-Prolog 7.4 Reference Manual

548 APPENDIX F. SUMMARY

xref defined/3 Examine defined predicates

xref exported/2 Examine exported predicates
xref module/2 Module defined by source
xref source/1 Cross-reference analysis of source

F.2.23 library(pairs)

group pairs by key/2 Group values with equivalent (==/2) consecutive keys.
map list to pairs/3 Create a Key-Value list by mapping each element of List.
pairs keys/2 Remove the values from a list of Key-Value pairs.
pairs keys values/3 True if Keys holds the keys of Pairs and Values the values.
pairs values/2 Remove the keys from a list of Key-Value pairs.
transpose pairs/2 Swap Key-Value to Value-Key.

F.2.24 library(pio)
library(pure input)

phrase from file/2 Process the content of File using the DCG rule Grammar.
phrase from file/3 As phrase from file/2, providing additional Options.
phrase from stream/2 Run Grammer against the character codes on Stream.
stream to lazy list/2 Create a lazy list representing the character codes in Stream.
lazy list character count//1 True when CharCount is the current character count in the Lazy list.
lazy list location//1 Determine current (error) location in a lazy list.
syntax error//1 Throw the syntax error Error at the current location of the input.

F.2.25 library(random)

getrand/1 Query/set the state of the random generator.

maybe/0 Succeed/fail with equal probability (variant of maybe/1).
maybe/1 Succeed with probability P, fail with probability 1-P.
maybe/2 Succeed with probability K/N (variant of maybe/1).
random/1 Binds R to a new random float in the open interval (0.0,1.0).
random/3 Generate a random integer or float in a range.
random between/3 Binds R to a random integer in [L,U] (i.e., including both L and U).
random member/2 X is a random member of List.
random perm2/4 Does X=A,Y=B or X=B,Y=A with equal probability.
random permutation/2 Permutation is a random permutation of List.
random select/3 Randomly select or insert an element.
randseq/3 S is a list of K unique random integers in the range 1..N.
randset/3 S is a sorted list of K unique random integers in the range 1..N.
setrand/1 Query/set the state of the random generator.

F.2.26 library(readutil)

read line to codes/2 Read line from a stream

SWI-Prolog 7.4 Reference Manual

F.2. LIBRARY PREDICATES 549

read line to codes/3 Read line from a stream

read stream to codes/2 Read contents of stream
read stream to codes/3 Read contents of stream
read file to codes/3 Read contents of file
read file to terms/3 Read contents of file to Prolog terms

F.2.27 library(record)

record/1 Define named fields in a term

F.2.28 library(registry)
This library is only available on Windows systems.

registry get key/2 Get principal value of key

registry get key/3 Get associated value of key
registry set key/2 Set principal value of key
registry set key/3 Set associated value of key
registry delete key/1 Remove a key
shell register file type/4 Register a file-type
shell register dde/6 Register DDE action
shell register prolog/1 Register Prolog

F.2.29 library(simplex)

assignment/2 Solve assignment problem

constraint/3 Add linear constraint to state
constraint/4 Add named linear constraint to state
constraint add/4 Extend a named constraint
gen state/1 Create empty linear program
maximize/3 Maximize objective function in to linear constraints
minimize/3 Minimize objective function in to linear constraints
objective/2 Fetch value of objective function
shadow price/3 Fetch shadow price in solved state
transportation/4 Solve transportation problem
variable value/3 Fetch value of variable in solved state

F.2.30 library(ugraphs)

vertices edges to ugraph/3 Create unweighted graph

vertices/2 Find vertices in graph
edges/2 Find edges in graph
add vertices/3 Add vertices to graph
del vertices/3 Delete vertices from graph
add edges/3 Add edges to graph
del edges/3 Delete edges from graph

SWI-Prolog 7.4 Reference Manual

550 APPENDIX F. SUMMARY

transpose ugraph/2 Invert the direction of all edges

neighbors/3 Find neighbors of vertice
neighbours/3 Find neighbors of vertice
complement/2 Inverse presense of edges
compose/3
top sort/2 Sort graph topologically
top sort/3 Sort graph topologically
transitive closure/2 Create transitive closure of graph
reachable/3 Find all reachable vertices
ugraph union/3 Union of two graphs

F.2.31 library(url)

file name to url/2 Translate between a filename and a file:// URL.

global url/3 Translate a possibly relative URL into an absolute one.
http location/2 Construct or analyze an HTTP location.
is absolute url/1 True if URL is an absolute URL.
parse url/2 Construct or analyse a URL.
parse url/3 Similar to parse url/2 for relative URLs.
parse url search/2 Construct or analyze an HTTP search specification.
set url encoding/2 Query and set the encoding for URLs.
url iri/2 Convert between a URL, encoding in US-ASCII and an IRI.
www form encode/2 En/decode to/from application/x-www-form-encoded.

F.2.32 library(www browser)

www open url/1 Open a web-page in a browser

F.2.33 library(solution sequences)

distinct/1 True if Goal is true and no previous solution of Goal bound Witness to the same value.
distinct/2 True if Goal is true and no previous solution of Goal bound Witness to the same value.
group by/4 Group bindings of Template that have the same value for By.
limit/2 Limit the number of solutions.
offset/2 Ignore the first Count solutions.
order by/2 Order solutions according to Spec.

F.2.34 library(thread pool)

create pool/1 Hook to create a thread pool lazily.

current thread pool/1 True if Name refers to a defined thread pool.
thread create in pool/4 Create a thread in Pool.
thread pool create/3 Create a pool of threads.
thread pool destroy/1 Destroy the thread pool named Name.
thread pool property/2 True if Property is a property of thread pool Name.

SWI-Prolog 7.4 Reference Manual

F.2. LIBRARY PREDICATES 551

F.2.35 library(varnumbers)

max var number/3 True when Max is the max of Start and the highest numbered $VAR(N) term.
numbervars/1 Number variables in Term using $VAR(N).
varnumbers/2 Inverse of numbervars/1.
varnumbers/3 Inverse of numbervars/3.
varnumbers names/3 If Term is a term with numbered and named variables using the reserved term $VAR(X), Copy

F.2.36 library(yall)

//2 Shorthand for Free/[]>>Lambda.

//3 Shorthand for Free/[]>>Lambda.
//4 Shorthand for Free/[]>>Lambda.
//5 Shorthand for Free/[]>>Lambda.
//6 Shorthand for Free/[]>>Lambda.
//7 Shorthand for Free/[]>>Lambda.
//8 Shorthand for Free/[]>>Lambda.
//9 Shorthand for Free/[]>>Lambda.
>>/2 Calls a copy of Lambda.
>>/3 Calls a copy of Lambda.
>>/4 Calls a copy of Lambda.
>>/5 Calls a copy of Lambda.
>>/6 Calls a copy of Lambda.
>>/7 Calls a copy of Lambda.
>>/8 Calls a copy of Lambda.
>>/9 Calls a copy of Lambda.
is lambda/1 True if Term is a valid Lambda expression.
lambda calls/2 Goal is the goal called if call/N is applied to LambdaExpression, where ExtraArgs are the additional arg
lambda calls/3 Goal is the goal called if call/N is applied to LambdaExpression, where ExtraArgs are the additional arg

SWI-Prolog 7.4 Reference Manual

552 APPENDIX F. SUMMARY

F.3 Arithmetic Functions

*/2 Multiplication
**/2 Power function
+/1 Unary plus (No-op)
+/2 Addition
-/1 Unary minus
-/2 Subtraction
//2 Division
///2 Integer division
/\/2 Bitwise and
<</2 Bitwise left shift
>>/2 Bitwise right shift
./2 List of one character: character code
\/1 Bitwise negation
\//2 Bitwise or
/2 Power function
abs/1 Absolute value
acos/1 Inverse (arc) cosine
acosh/1 Inverse hyperbolic cosine
asin/1 Inverse (arc) sine
asinh/1 Inverse (arc) sine
atan/1 Inverse hyperbolic sine
atan/2 Rectangular to polar conversion
atanh/1 Inverse hyperbolic tangent
atan2/2 Rectangular to polar conversion
ceil/1 Smallest integer larger than arg
ceiling/1 Smallest integer larger than arg
cos/1 Cosine
cosh/1 Hyperbolic cosine
copysign/2 Apply sign of N2 to N1
cputime/0 Get CPU time
div/2 Integer division
e/0 Mathematical constant
erf/1 Gauss error function
erfc/1 Complementary error function
epsilon/0 Floating point precision
eval/1 Evaluate term as expression
exp/1 Exponent (base e)
float/1 Explicitly convert to float
float fractional part/1 Fractional part of a float
float integer part/1 Integer part of a float
floor/1 Largest integer below argument
gcd/2 Greatest common divisor
getbit/2 Get bit at index from large integer
inf/0 Positive infinity

SWI-Prolog 7.4 Reference Manual

F.3. ARITHMETIC FUNCTIONS 553

integer/1 Round to nearest integer

lgamma/1 Log of gamma function
log/1 Natural logarithm
log10/1 10 base logarithm
lsb/1 Least significant bit
max/2 Maximum of two numbers
min/2 Minimum of two numbers
msb/1 Most significant bit
mod/2 Remainder of division
nan/0 Not a Number (NaN)
powm/3 Integer exponent and modulo
random/1 Generate random number
random float/0 Generate random number
rational/1 Convert to rational number
rationalize/1 Convert to rational number
rdiv/2 Ration number division
rem/2 Remainder of division
round/1 Round to nearest integer
truncate/1 Truncate float to integer
pi/0 Mathematical constant
popcount/1 Count 1s in a bitvector
sign/1 Extract sign of value
sin/1 Sine
sinh/1 Hyperbolic sine
sqrt/1 Square root
tan/1 Tangent
tanh/1 Hyperbolic tangent
xor/2 Bitwise exclusive or

SWI-Prolog 7.4 Reference Manual

554 APPENDIX F. SUMMARY

F.4 Operators

$ 1 fx Bind top-level variable

200 xf y Existential qualification
200 xf y Arithmetic function
mod 300 xf x Arithmetic function
* 400 yf x Arithmetic function
/ 400 yf x Arithmetic function
// 400 yf x Arithmetic function
<< 400 yf x Arithmetic function
>> 400 yf x Arithmetic function
xor 400 yf x Arithmetic function
+ 500 fx Arithmetic function
- 500 fx Arithmetic function
? 500 fx XPCE: obtainer
\ 500 fx Arithmetic function
+ 500 yf x Arithmetic function
- 500 yf x Arithmetic function
/\ 500 yf x Arithmetic function
\/ 500 yf x Arithmetic function
: 600 xf y module:term separator
< 700 xf x Predicate
= 700 xf x Predicate
=.. 700 xf x Predicate
=:= 700 xf x Predicate
< 700 xf x Predicate
== 700 xf x Predicate
=@= 700 xf x Predicate
=\= 700 xf x Predicate
> 700 xf x Predicate
>= 700 xf x Predicate
@< 700 xf x Predicate
@=< 700 xf x Predicate
@> 700 xf x Predicate
@>= 700 xf x Predicate
is 700 xf x Predicate
\= 700 xf x Predicate
\== 700 xf x Predicate
=@= 700 xf x Predicate
not 900 fy Predicate
\+ 900 fy Predicate
, 1000 xf y Predicate
-> 1050 xf y Predicate
*-> 1050 xf y Predicate
; 1100 xf y Predicate
| 1105 xf y DCG disjunction

SWI-Prolog 7.4 Reference Manual

F.4. OPERATORS 555

discontiguous 1150 fx Directive

dynamic 1150 fx Directive
module transparent 1150 fx Directive
meta predicate 1150 fx Head
multifile 1150 fx Directive
thread local 1150 fx Directive
volatile 1150 fx Directive
initialization 1150 fx Directive
:- 1200 fx Introduces a directive
?- 1200 fx Introduces a directive
--> 1200 xf x DCGrammar: rewrite
:- 1200 xf x head :- body. separator

SWI-Prolog 7.4 Reference Manual

Bibliography

[Bowen et al., 1983] D. L. Bowen, L. M. Byrd, and WF. Clocksin. A portable Prolog com-
piler. In L. M. Pereira, editor, Proceedings of the Logic Programming
Workshop 1983, Lisabon, Portugal, 1983. Universidade nova de Lisboa.
[Bratko, 1986] I. Bratko. Prolog Programming for Artificial Intelligence. Addison-
Wesley, Reading, Massachusetts, 1986.
[Butenhof, 1997] David R. Butenhof. Programming with POSIX threads. Addison-Wes-
ley, Reading, MA, USA, 1997.
[Byrd, 1980] L. Byrd. Understanding the control flow of Prolog programs. Logic
Programming Workshop, 1980.
[Clocksin & Melish, 1987] W. F. Clocksin and C. S. Melish. Programming in Prolog. Springer-
Verlag, New York, Third, Revised and Extended edition, 1987.
[Demoen, 2002] Bart Demoen. Dynamic attributes, their hProlog implementation,
and a first evaluation. Report CW 350, Department of Com-
puter Science, K.U.Leuven, Leuven, Belgium, oct 2002. URL =
http://www.cs.kuleuven.ac.be/publicaties/rapporten/cw/CW350.abs.html.
[Desouter et al., 2015] Benoit Desouter, Marko van Dooren, and Tom Schrijvers. Tabling as a
library with delimited control. TPLP, 15(4-5):419433, 2015.
[Freire et al., 1997] Juliana Freire, David S. Warren, Konstantinos Sagonas, Prasad Rao,
and Terrance Swift. XSB: A system for efficiently computing well-
founded semantics. In Proceedings of LPNMR 97, pages 430440,
Berlin, Germany, jan 1997. Springer Verlag. LNCS 1265.
[Fruhwirth, ] T. Fruhwirth. Thom Fruehwirths constraint handling rules website.
http://www.constraint-handling-rules.org.
[Fruhwirth, 2009] T. Fruhwirth. Constraint Handling Rules. Cambridge University Press,
2009.
[Graham et al., 1982] Susan L. Graham, Peter B. Kessler, and Marshall K. McKusick. gprof:
a call graph execution profiler. In SIGPLAN Symposium on Compiler
Construction, pages 120126, 1982.
[Hodgson, 1998] Jonathan Hodgson. validation suite for conformance with part 1 of
the standard, 1998, http://www.sju.edu/jhodgson/pub/
suite.tar.gz.
[Holzbaur, 1992] Christian Holzbaur. Metastructures versus attributed variables in the
context of extensible unification. In PLILP, volume 631, pages 260
268. Springer-Verlag, 1992. LNCS 631.

SWI-Prolog 7.4 Reference Manual

BIBLIOGRAPHY 557

[Kernighan & Ritchie, 1978] B. W. Kernighan and D. M. Ritchie. The C Programming Language.
Prentice-Hall, Englewood Cliffs, New Jersey, 1978.

[Neumerkel, 1993] Ulrich Neumerkel. The binary WAM, a simplified Prolog en-
gine. Technical report, Technische Universitat Wien, 1993.
http://www.complang.tuwien.ac.at/ulrich/papers/PDF/binwam-
nov93.pdf.

[OKeefe, 1990] R. A. OKeefe. The Craft of Prolog. MIT Press, Massachussetts, 1990.

[Pereira, 1986] F. Pereira. C-Prolog Users Manual. EdCaad, University of Edinburgh,

1986.

[Qui, 1997] AI International ltd., Berkhamsted, UK. Quintus Prolog, User Guide
and Reference Manual, 1997.

[Schimpf, 2002] Joachim Schimpf. Logical loops. In PeterJ. Stuckey, editor, Logic Pro-
gramming, volume 2401 of Lecture Notes in Computer Science, pages
224238. Springer Berlin Heidelberg, 2002.

[Schrijvers et al., 2013] Tom Schrijvers, Bart Demoen, Benoit Desouter, and Jan Wielemaker.
Delimited continuations for prolog. TPLP, 13(4-5):533546, 2013.

[Sterling & Shapiro, 1986] L. Sterling and E. Shapiro. The Art of Prolog. MIT Press, Cambridge,
Massachusetts, 1986.

[Tarau, 2011] Paul Tarau. Coordination and concurrency in multi-engine prolog. In

Wolfgang De Meuter and Gruia-Catalin Roman, editors, Coordination
Models and Languages - 13th International Conference, COORDINA-
TION 2011, Reykjavik, Iceland, June 6-9, 2011. Proceedings, volume
6721 of Lecture Notes in Computer Science, pages 157171. Springer,
2011.

[Triska, 2016] Markus Triska. The Boolean constraint solver of SWI-Prolog: System
description. In FLOPS, volume 9613 of LNCS, pages 4561, 2016.
https://www.metalevel.at/swiclpb.pdf.

SWI-Prolog 7.4 Reference Manual

Index

( library, 305 =</2, 176

-lswipl library, 373 #<==/2, 428
.pl, 64 <</2, 182
.pro, 64 </2, 176
?=/2, 105 >:</2, 245
@/2, 257 :</2, 244
=:=/2, 176 -/1, 178
/\/2, 182 -/2, 178
=\=/2, 176 \=/2, 102
|/2, 106 \/1, 182
#/\/2, 428 \==/2, 103
#=/2, 419 \+/1, 107
#<==>/2, 428 \//2, 182
#>=/2, 420 +/1, 178
#>/2, 420 +/2, 178
#=</2, 420 **/2, 183
#</2, 420 #==>/2, 428
#\=/2, 419 >>/2, 182, 501
#\/1, 427 >>/3, 501
#\/2, 429 >>/4, 501
,/2, 106 >>/5, 501
#\//2, 428 >>/6, 501
{}/1, 431 >>/7, 501
!/0, 106 >>/8, 501
/, 64 >>/9, 501
//2, 179, 501 ;/2, 106
//3, 501 *->/2, 107
//4, 501 =@=/2, 104
//5, 501 \=@=/2, 105
//6, 501 @>=/2, 103
//7, 501 @>/2, 103
//8, 501 */2, 178
//9, 501 @=</2, 103
./2, 180 @</2, 103
./3, 241 =../2, 161
=/2, 102 \, 64
==/2, 103 PL get arg(), 330
>=/2, 176 64-bits
>/2, 176 platforms, 62
/2, 183
///2, 179 abolish/1, 123
->/2, 106 abolish/2, 123

SWI-Prolog 7.4 Reference Manual

INDEX 559

abolish/[1 asinh/1, 183

2], 38 assert, 516
abolish all tables/0, 490 assert/1, 80, 124, 127, 129, 131, 196, 251, 254,
abolish table subgoals/1, 490 298
abort/0, 22, 27, 112, 137, 139, 142, 214, 282, 359, assert/2, 35, 125, 134
362, 506 assert predicate options/4, 467
abs/1, 179 asserta/1, 21, 55, 56, 86, 104, 122, 124, 256, 257,
absolute file name/2, 14, 81, 87, 210, 212, 213, 516
386 asserta/2, 124, 125
absolute file name/3, 37, 41, 46, 74, 80, 86, 89, assertion/1, 438, 508
202, 210, 211, 357, 478 assertz/1, 86, 122124, 133, 134, 263, 266, 308,
absolute file name/[2 516
3], 44, 86, 211 assertz/2, 124, 125
access file/2, 37, 44, 209, 211 assignment/2, 482
acos/1, 182 assoc library, 243, 247, 248, 447
acosh/1, 183 assoc to keys/2, 395
acquire(), 345 assoc to list/2, 395
acyclic term/1, 55, 102, 104 assoc to values/2, 395
add edges/3, 494 at end of stream/0, 151
add import module/3, 259, 264 at end of stream/1, 151, 152
add nb set/2, 448 at end of stream/[0
add nb set/3, 448 1], 140, 477
add vertices/3, 494 at halt/1, 37, 89, 214, 291, 363, 370, 527
agent, 396 atan/1, 182
aggregate library, 306 atan/2, 183
aggregate/3, 122, 255, 391 atan2/2, 183
aggregate/4, 255, 391 atanh/1, 183
aggregate all/3, 122, 391 atom, 516
aggregate all/4, 391 atom/1, 100, 101, 270, 325
all different/1, 422 atom chars/2, 79, 147, 150, 165, 171, 250
all distinct/1, 422 atom codes/2, 79, 147, 165, 166, 171, 250
AMD64, 62 atom concat/3, 166, 232
anonymous ATOM dot(), 324
variable, 54 atom length/2, 38, 167, 232
anonymous variable, 516 ATOM nil(), 324
ansi format/3, 116 atom number/2, 146, 166
ansi term library, 35, 115, 116 atom prefix/2, 167
append/1, 144, 145 atom result/2, 261
append/2, 253, 443 atom string/2, 231
append/3, 134, 166, 443 atom to chars/2, 398
apply/2, 108 atom to chars/3, 398
apply macros library, 108, 121 atom to term/3, 160, 166
apropos/1, 23, 24, 47, 511, 525 atomic/1, 100, 101
arg/3, 161 atomic concat/3, 166
arithmetic function/1, 352 atomic list concat/2, 166, 167
arity, 516 atomic list concat/3, 167
asin/1, 182 atomics to string/2, 233

SWI-Prolog 7.4 Reference Manual

560 INDEX

atomics to string/3, 233 call residue vars/2, 271, 272

attach console/0, 301, 359 call shared object function/2, 317
attr portray hook/2, 153, 269 call with depth limit/3, 108, 109
attr unify hook/2, 266268 call with inference limit/3, 109
attribute goals//1, 267, 269 call with time limit/2, 109
attribute goals/1, 268 callable/1, 101, 326, 472
attvar/1, 268 cancel halt/1, 89, 214, 370
autoload/0, 49, 85, 382, 383 catch/3, 111113, 158, 166, 209, 214, 222, 289,
autoload path/1, 48 292, 293, 309, 505, 509, 510, 539
automaton/3, 426 ceil/1, 182
automaton/8, 426 ceiling/1, 182
chain/2, 427
b getval/2, 197 char code/2, 79, 165
b set dict/3, 246 char conversion/2, 35, 173
b setval/2, 42, 122, 196, 197, 246, 308, 510 char type/2, 53, 168, 169, 171
backcomp library, 163, 195 character set, 49
backtracking, 516 character count/2, 141, 148, 149
bagof/3, 55, 189, 190, 255, 306, 525 chdir/1, 213
bb inf/3, 432 check library, 86
bb inf/4, 432 check/0, 85, 399
bb inf/5, 432 check:string predicate/1, 235
between/3, 175 check:valid string goal/1, 236
binding, 516 check predicate option/3, 468
bits check predicate options/0, 468
64, 62 checker/2, 401
blackboard, 396 choice point, 516
blob/2, 101, 136 chr library, 280, 282
body, 516 chr constraint/1, 277, 284
Boehm GC, 380 chr leash/1, 282
BOM, 59 chr notrace/0, 281, 282
break/0, 22, 27, 34, 42, 214, 282, 359 chr option/2, 276, 284
broadcast, 396 chr show store/1, 283
broadcast library, 396 chr trace/0, 281, 282
broadcast/1, 396 chr type/1, 278
broadcast request/1, 396 circuit/1, 425
built-in predicate, 516 clause, 517
Byte Order Mark, 59 clause/2, 40, 100, 107, 133, 134, 383
byte count/2, 141, 148 clause/3, 124, 125, 134, 135, 384
clause/[2
call/1, 74, 101, 106, 107, 112, 216, 219, 222, 223, 3], 38
251, 271, 348, 508 clause property/2, 85, 87, 131, 132, 134, 504
call/2, 101, 108 close/1, 135, 139, 141
call/3, 155 close/2, 139
call/[2-8], 108 close any/1, 442
call cleanup/2, 110, 111, 146, 505, 513 close dde conversation/1, 226
call cleanup/3, 111 close shared object/1, 316
call dcg/3, 121 CLP, 265

SWI-Prolog 7.4 Reference Manual

INDEX 561

clpfd library, 258 cputime/0, 184

clpqr library, 431 create pool/1, 493
code type/2, 168, 169, 171 create prolog flag/3, 32, 4345, 358
collate, 172 crypt library, 524
collation key/2, 168, 172, 200 csv//1, 435
COM, 344 csv//2, 435
command line csv read file/2, 188, 435
arguments, 21 csv read file/3, 435
compare csv read file row/3, 436
language-specific, 172 csv write file/2, 436
compare(), 345 csv write file/3, 436
compare/3, 55, 103, 189, 355, 514 csv write stream/3, 436
compile aux clauses/1, 80, 92, 96, 131 ctypes library, 169
compile predicates/1, 129 cumulative/1, 425
compiling/0, 90, 97 cumulative/2, 425
complement/2, 495 current arithmetic function/1, 186
completion current atom/1, 130
TAB, 67 current blob/2, 130, 345
compose/3, 495 current char conversion/2, 173
compound, 517 current engine/1, 312
compound/1, 101 current flag/1, 130
compound name arguments/3, 101, 161, 162, current foreign library/2, 316, 383
238, 241 current format predicate/2, 196
compound name arity/3, 101, 161, 162, 238, 241 current functor/2, 130
concat atom/3, 167 current input/1, 89, 136, 145, 146
constraint programming, 265 current key/1, 125, 130
constraint/3, 481 current locale/1, 169
constraint/4, 482 current module/1, 130, 262
constraint add/4, 482 current op/3, 173
consult/1, 16, 17, 46, 73, 8082, 84, 85, 96, 97, current option arg/2, 468
129 current output/1, 136, 145, 146
context module, 517 current persistent predicate/1, 462
context module/1, 256, 262, 349 current predicate/1, 108, 130, 131
convert time/[2 current predicate/2, 130, 131
8], 210 current predicate option/3, 468
copy file/2, 199 current predicate options/3, 468
copy predicate clauses/2, 123 current prolog flag/2, 20, 21, 32, 47, 49, 52, 81,
copy stream data/2, 152 158, 227, 314, 358, 389, 518
copy stream data/3, 142, 152 current signal/3, 118, 119
copy term/2, 55, 104, 163, 164, 197, 245, 266, current stream/3, 141, 213
270 current thread pool/1, 492
copy term/3, 147, 155, 266, 269 current trie/1, 126
copy term nat/2, 270 current type/3, 440
copysign/2, 180 cyclic terms, 55
cos/1, 182 cyclic term/1, 55, 102
cosh/1, 183
count atom results/3, 261 daemon, 396

SWI-Prolog 7.4 Reference Manual

562 INDEX

date time stamp/2, 204 det, 517

date time value/3, 203, 204 determinism, 517
day of the week/2, 208 deterministic, 517
db attach/2, 462 deterministic/1, 110, 505
db detach/0, 462 Development environment, 64
db sync/1, 462 dialect.pl library, 512
db sync all/1, 463 dict create/3, 244
DCG, 80, 119 dict options/2, 450
dcg, 517 dict pairs/3, 244, 247
dcg translate rule/2, 91, 92 dif library, 271
dcg translate rule/4, 93 dif/2, 55, 102, 105, 265, 270, 271
dde current connection/2, 227 directory file path/3, 209
dde current service/2, 227 directory files/2, 212
dde execute/2, 226 discontiguous/1, 85, 114, 129, 218
dde poke/4, 226 disjoint2/1, 425
dde register service/2, 227 display/1, 192, 332, 333
dde request/3, 226 distinct/1, 486
dde unregister service/1, 227 distinct/2, 486
debug library, 76 div/2, 179
debug/0, 25, 28, 42, 113, 216, 217, 225, 301, 359, divmod/4, 175
508, 509 dld, 314
debug/1, 437 do not use/1, 257
debug/3, 114, 437 domain/2, 267
debug message context/1, 437 domain error/2, 344, 439
debugging downcase atom/2, 170, 171
exceptions, 113 dump/3, 432, 434
debugging/0, 47, 216, 217, 511 duplicate term/2, 55, 163, 164, 197
debugging/1, 437 dwim match/2, 133, 228
debugging/2, 437 dwim match/3, 228
declarative, 266 dwim predicate/2, 133
default module/2, 91, 131133, 259 dynamic predicate, 517
del assoc/4, 395 dynamic/1, 40, 43, 79, 84, 122, 124, 129, 131,
del attr/2, 268, 270 262, 298, 384
del attrs/1, 270
del dict/4, 244 e/0, 184
del edges/3, 494 edges/2, 494
del max assoc/4, 395 edit/0, 34, 98
del min assoc/4, 395 edit/1, 36, 46, 47, 67, 68, 73, 77, 85, 98, 99, 257,
del vertices/3, 494 535
delete/3, 444 editline library, 40
delete directory/1, 213 element/3, 424
delete file/1, 199, 210, 213 elif/1, 93
delete import module/2, 259, 264 else/0, 94
derive predicate options/0, 468 Emacs, 23
derived predicate options/1, 469 emacs/prolog colour library, 71
derived predicate options/3, 469 emacs/prolog mode library, 71
deserialize, 119 empty assoc/1, 394

SWI-Prolog 7.4 Reference Manual

INDEX 563

empty nb set/1, 447 fact, 517

encoding/1, 58, 85 fail/0, 92, 105
endif/0, 94 false/0, 105
engine create/3, 311 fast read/2, 147
engine create/4, 311 fast term serialized/2, 147
engine destroy/1, 310 fast write/2, 147
engine fetch/1, 309, 311, 312 fastrw library, 147
engine next/1, 306 fd dom/2, 430
engine next/2, 306, 311 fd inf/2, 430
engine next reified/2, 311 fd size/2, 430
engine post/2, 311, 312 fd sup/2, 430
engine post/3, 311, 312 fd var/1, 429
engine self/1, 312 file base name/2, 210
engine yield/1, 306, 309311 file directory name/2, 209, 210
ensure loaded/1, 29, 80, 81, 84, 253 file name extension/3, 212
entailed/1, 431 file name to url/2, 498
environment/2, 471 file of label/2, 257
epsilon/0, 184 file search path/2, 17, 21, 33, 44, 47, 49, 65, 74,
erase/1, 122, 124, 125, 134 82, 86, 87, 89, 357, 375, 385387
erf/1, 184 filesex library, 199, 209
erfc/1, 184 fill buffer/1, 152
error library, 100, 478 find chr constraint/1, 283
eval/1, 185 findall/3, 55, 104, 105, 122, 189, 191, 247, 266,
exception/3, 197, 509, 510 306, 307, 311, 530
exceptions findall/4, 189
debugging, 113 findnsols/4, 189, 530
exclude/3, 392 findnsols/5, 189
existence error/2, 439 flag/3, 122, 125, 126, 130, 164
exists directory/1, 210 flag:access level, 33
exists file/1, 37, 209 flag:address bits, 33
exists source/1, 512, 513 flag:agc margin, 33
exp/1, 183 flag:allow dot in atom, 33
expand answer/2, 215 flag:allow variable name as functor, 33
expand file name/2, 37, 82, 199, 200, 210212 flag:answer write options, 42
expand file search path/2, 86 flag:apple, 33
expand goal/2, 39, 9193 flag:arch, 33
expand goal/4, 93 flag:argv, 33
expand query/4, 215 flag:associated file, 34
expand term/2, 8992, 119, 479 flag:autoload, 34
expand term/4, 93 flag:back quotes, 34
expects dialect/1, 82, 83, 89, 512 flag:backtrace, 34
explain library, 530 flag:backtrace depth, 34
explain/1, 24 flag:backtrace goal depth, 34
explain/2, 24 flag:backtrace show lines, 34
export/1, 95, 130, 260 flag:bounded, 34
export list/2, 260 flag:break level, 34
exported predicate, 517 flag:c cc, 34

SWI-Prolog 7.4 Reference Manual

564 INDEX

flag:c cflags, 34 flag:pid, 40

flag:c ldflags, 34 flag:pipe, 40
flag:c libplso, 34 flag:print write options, 40
flag:c libs, 34 flag:prompt alternatives on, 40
flag:char conversion, 35 flag:protect static code, 40
flag:character escapes, 35 flag:qcompile, 40
flag:colon sets calling context, 35 flag:readline, 40
flag:color term, 35 flag:report error, 41
flag:compile meta arguments, 35 flag:resource database, 41
flag:compiled at, 35 flag:runtime, 41
flag:console menu, 35 flag:sandboxed load, 41
flag:cpu count, 36 flag:saved program, 41
flag:dde, 36 flag:shared object extension, 41
flag:debug, 36 flag:shared object search path, 41
flag:debug on error, 36 flag:signals, 41
flag:debugger show context, 36 flag:stream type check, 41
flag:debugger write options, 36 flag:system thread id, 41
flag:dialect, 36 flag:table space, 41
flag:double quotes, 36 flag:timezone, 42
flag:editor, 36 flag:toplevel mode, 42
flag:emacs inferior process, 37 flag:toplevel print anon, 42
flag:encoding, 37 flag:toplevel print factorized, 42
flag:executable, 37 flag:toplevel prompt, 42
flag:exit status, 37 flag:toplevel var size, 43
flag:file name case handling, 37 flag:trace gc, 43
flag:file name variables, 37 flag:traditional, 43
flag:file search cache time, 37 flag:tty control, 43
flag:gc, 37 flag:unix, 43
flag:generate debug info, 37 flag:unknown, 43
flag:gmp version, 38 flag:unload foreign libraries, 43
flag:gui, 38 flag:user flags, 43
flag:history, 38 flag:var prefix, 44
flag:home, 38 flag:verbose, 44
flag:hwnd, 38 flag:verbose autoload, 44
flag:integer rounding function, 38 flag:verbose file search, 44
flag:iso, 38 flag:verbose load, 44
flag:large files, 39 flag:version, 44
flag:last call optimisation, 39 flag:version data, 44
flag:max arity, 39 flag:version git, 44
flag:max integer, 39 flag:warn override implicit import, 44
flag:max tagged integer, 39 flag:win file access check, 44
flag:min integer, 39 flag:windows, 45
flag:min tagged integer, 39 flag:write attributes, 45
flag:occurs check, 39 flag:write help with overstrike, 45
flag:open shared object, 39 flag:xpce, 45
flag:optimise, 39 flag:xpce version, 45
flag:os argv, 40 flag:xref, 45

SWI-Prolog 7.4 Reference Manual

INDEX 565

flatten/2, 253, 445 get0/2, 150, 151

float/1, 100, 101, 181 get assoc/3, 247, 394
float fractional part/1, 181 get assoc/5, 394
float integer part/1, 181 get attr/3, 268, 270
floor/1, 182 get attrs/2, 270
flounder, 271 get byte/1, 150
flush output/0, 150 get byte/2, 150
flush output/1, 115, 150, 152 get byte/[1
flush output/[0 2], 79
1], 137, 150 get char/1, 150
foldl/4, 393 get char/2, 150
foldl/5, 393 get char/[1
foldl/6, 393 2], 79
foldl/7, 393 get code/1, 79, 135, 150, 151
forall/2, 190, 191 get code/2, 58, 142, 150, 152
foreach/2, 191, 391 get code/[1
format/1, 115, 191, 193 2], 79
format/2, 52, 138, 157, 168, 191, 193, 195 get dict/3, 242, 243
format/3, 114117, 135, 146, 153, 165, 166, 168, get dict/5, 243
172, 177, 178, 191, 194, 195, 235, 236 get dict ex/3, 241, 242
format/[1 get flag/2, 126
2], 153, 530 get single char/1, 20, 43, 151
format/[2 get string code/3, 232
3], 52 get time/1, 203, 210, 221, 294, 296
format predicate/2, 195 getbit/2, 185
format time/3, 42, 168, 196, 200, 205 getenv/2, 199, 448
format time/4, 205, 207 getrand/1, 475
format to chars/3, 398 global cardinality/2, 424
format to chars/4, 398 global cardinality/3, 424
free variables/4, 391 global url/3, 496
freeze/2, 270, 271 GMP, 177
frozen/2, 271 GNU-Emacs, 23
functor, 518 go/0, 239
functor/3, 101, 130, 161, 162, 198, 238, 241 goal, 518
goal expansion/2, 45, 80, 88, 9193, 95, 96, 513,
garbage collect/0, 224, 310 514, 527
garbage collect atoms/0, 33, 224, 310, 363 goal expansion/4, 80, 93
garbage collect clauses/0, 57, 9496, 122 ground/1, 55, 101, 128, 326
gcd/2, 179 group by/4, 487
gdebug/0, 73 group pairs by key/2, 460
gen assoc/3, 394 gspy/1, 73
gen nb set/2, 448 gtrace/0, 73, 301
gen state/1, 481 guitracer/0, 73, 77, 215, 216
gensym/2, 440 gxref/0, 24, 74, 254, 384, 472
get/1, 151, 242
get/2, 151 halt/0, 27, 89, 214, 527
get0/1, 138, 150, 151 halt/1, 37, 214, 359, 526

SWI-Prolog 7.4 Reference Manual

566 INDEX

halt/[0 integer, 518

1], 89 unbounded, 176
has type/2, 440 integer//1, 120
hashing, 518 integer/1, 100, 101, 181
head, 518 interactor/0, 142, 301
heaps library, 309 internationalization, 57
help/0, 23, 47, 386, 511 interpreted, 518
help/1, 23, 45, 47, 511 intersection/3, 447
Herbrand term, 265 is/2, 176, 177, 181, 284
hooks, 46 is absolute file name/1, 211
html write library, 473 is absolute url/1, 497
http/http error library, 113 is assoc/1, 395
http/http header library, 207 is dict/1, 243
http/http load library, 84, 511 is dict/2, 243
http location/2, 497 is engine/1, 312
http open/3, 117 is lambda/1, 502
http timestamp/2, 207 is list/1, 186
is of type/2, 440
IA32, 62 is ordset/1, 457
IDE, 64 is set/1, 446
if is stream/1, 141
directive, 93 is thread/1, 292
if/1, 88, 93 ISO Latin 1, 49
ignore/1, 108, 222, 289
immediate Java, 344
update view, 127 jitindex, 56
import/1, 260 join threads/0, 300, 301
import module/2, 130, 259
keysort/2, 188, 189
imported predicate, 518
known licenses/0, 523, 524
in/2, 420
in pce thread/1, 305 label/1, 421
in pce thread sync/1, 305 labeling/1, 406
include/1, 80, 81, 84, 85, 87, 134 labeling/2, 421
include/3, 392 lambda calls/2, 502
indexing, 518 lambda calls/3, 502
term-hashes, 128 last/2, 444
indomain/1, 421 lazy list character count/1, 464
inf/0, 184 lazy list location//1, 464
inf/2, 431 leash/1, 25, 217, 282, 506
infinite trees, 55 length/2, 187, 242
initialization/1, 81, 90, 95, 96, 197, 291, 314, 367, lex chain/1, 423
384 lgamma/1, 184
initialization/2, 90 library(apply macros) library, 80
ins/2, 421 library(dcg/basics) library, 120
instance/2, 125 library directory/1, 4749, 86
instantiation, 518 license/0, 523
instantiation error/1, 344, 439 license/1, 523, 524

SWI-Prolog 7.4 Reference Manual

INDEX 567

license/2, 523, 524 map assoc/2, 395

limit/2, 486 map assoc/3, 395
line count/2, 141, 143, 149, 198 map list to pairs/3, 460
line position/2, 141, 143, 149, 198 maplist/2, 191, 250, 392
list autoload/0, 400 maplist/3, 247, 254, 261, 392
list debug topics/0, 437 maplist/4, 392
list redefined/0, 400 maplist/5, 392
list strings/0, 229, 235, 238, 400 maplist /3, 254, 261
list strings/1, 400 max/2, 180
list to assoc/2, 247, 394 max assoc/3, 394
list to ord set/2, 457 max list/2, 446
list to set/2, 446 max member/2, 446
list trivial fails/0, 400 max var number/3, 499
list trivial fails/1, 400 maximize/1, 432
list undefined/0, 35, 86, 133, 399 maximize/3, 481
list undefined/1, 399 maybe/0, 476
list void declarations/0, 400 maybe/1, 476
listen/2, 397 maybe/2, 476
listen/3, 397, 398 member/2, 27, 110, 187, 211, 253, 443, 533
listening/3, 398 memberchk/2, 105, 187, 237
listing/0, 100 memory
listing/1, 27, 99, 100 layout, 61
lists library, 186 merge options/3, 450
load files/1, 81 message
load files/2, 40, 41, 44, 46, 58, 81, 83, 84, 87, 88, service, 396
96, 97, 217, 253, 472, 511, 513, 535 message hook/3, 114116, 118, 225, 538
load foreign library/1, 90, 315, 316, 372, 385 message property/2, 35, 116
load foreign library/2, 315 message queue create/1, 293, 295
locale, 172 message queue create/2, 295, 296
locale create/3, 168, 169 message queue create/3, 299
locale destroy/1, 169 message queue destroy/1, 295
locale property/2, 169 message queue property/2, 293, 296
locale sort/2, 168, 172, 200 message to string/2, 115, 116
log/1, 183 meta-predicate, 519
log10/1, 183 meta options/3, 253, 450
logical meta predicate/1, 35, 92, 101, 132, 133, 254256,
update view, 127 260, 263, 349, 360, 383, 384
lsb/1, 185 min/2, 180
min assoc/3, 394
MacOS, 33 min list/2, 446
make/0, 12, 35, 47, 49, 68, 73, 77, 8286, 88, 94, min member/2, 446
95 minimize/1, 431
make directory/1, 199, 213 minimize/3, 482
make library index/1, 48 mod/2, 179
make library index/2, 48 mode, 519
make library index/[1 module, 519
2], 49 contex, 517

SWI-Prolog 7.4 Reference Manual

568 INDEX

module transparent, 519 1], 192

module/1, 42, 80, 130, 257, 290 nodebug/0, 217, 506
module/2, 91, 172, 173, 251, 252, 254, 258, 260, nodebug/1, 437
264 noguitracer/0, 73, 77, 216
module/3, 252 non deterministic, 519
module property/2, 262, 263 nondet, 519
module transparent/1, 133, 256, 257, 262, 263, nonvar/1, 100
349, 517 noprofile/1, 222
msb/1, 185 noprotocol/0, 215
msort/2, 188 normalize space/2, 172
multi, 519 nospy/1, 27, 47, 217, 302, 510
multifile/1, 43, 84, 85, 129, 132, 510, 519 nospyall/0, 47, 217, 510
must be/2, 439, 478 not/1, 108, 525
mutex create/1, 299, 300 notrace/0, 216, 282
mutex create/2, 299, 300 notrace/1, 216
mutex destroy/1, 299 nth0/3, 444
mutex lock/1, 299, 300 nth0/4, 444
mutex property/2, 300 nth1/3, 444
mutex statistics/0, 293 nth1/4, 444
mutex trylock/1, 300 nth clause/3, 131, 134, 504
mutex unlock/1, 300 nth integer root and remainder/4, 175
mutex unlock all/0, 300 number
my compare/3, 514 rational, 176
mypred/1, 257 number/1, 100
number chars/2, 79, 165
name/1, 254 number codes/2, 79, 165, 166
name/2, 165, 166 number string/2, 231
name of/2, 397 number to chars/2, 398
nan/0, 184 number to chars/3, 398
nb current/2, 197, 198 numbervars/1, 499
nb delete/1, 198 numbervars/3, 55, 154, 162, 163
nb getval/2, 197, 198 numbervars/4, 55, 156, 162, 163
nb link dict/3, 246 numlist/3, 446
nb linkarg/3, 164, 246
nb linkval/2, 164, 197, 198, 246 objective/2, 482
nb set library, 447 occurs check, 103
nb set dict/3, 246 offset/2, 486
nb set to list/2, 448 on signal/3, 118, 119
nb setarg/3, 78, 122, 163, 164, 189, 246, 447, 479 once/1, 107, 108, 110, 146, 189, 214, 216, 219,
nb setval/2, 122, 164, 196198, 246, 309, 510 299, 350
neck, 519 online help library, 526
neighbors/3, 495 op/3, 129, 154, 173, 258
neighbours/3, 495 open/3, 37, 78, 135, 136, 138, 344
nextto/3, 444 open/4, 58, 59, 79, 136, 138140, 142, 143, 151,
nl/0, 149 169, 209, 247, 248, 478
nl/1, 149 open any/5, 441
nl/[0 open chars stream/2, 399

SWI-Prolog 7.4 Reference Manual

INDEX 569

open dde conversation/3, 226 pack remove/1, 471

open hook/6, 442 pack search/1, 469
open null stream/1, 138, 142 pack upgrade/1, 471
open resource/3, 369, 382, 385, 387 pack url file/2, 471
open shared object/2, 39, 202, 314, 316 pairs library, 188, 247
open shared object/3, 316 pairs keys/2, 460
open string/2, 234 pairs keys values/3, 459
operand, 519 pairs values/2, 459
operator, 519 parse time/2, 207
and modules, 172 parse time/3, 207
opt arguments/3, 455 parse type/3, 456
opt help/2, 456 parse url/2, 497
opt parse/4, 456 parse url/3, 498
opt parse/5, 456 parse url search/2, 498
option library, 247, 249, 479 partition/4, 392
option/2, 449 partition/5, 392
option/3, 449 pce dispatch/1, 305
options library, 249 pce thread/1, 305
ord add element/3, 458 pce xref library, 74
ord del element/3, 458 peek byte/1, 151
ord disjoint/2, 457 peek byte/2, 151
ord empty/1, 457 peek byte/[1
ord intersect/2, 457 2], 79
ord intersect/3, 457 peek char/1, 151
ord intersection/2, 458 peek char/2, 151
ord intersection/3, 458 peek char/[1
ord intersection/4, 458 2], 79
ord list to assoc/2, 394 peek code/1, 151
ord memberchk/2, 458 peek code/2, 151
ord selectchk/3, 458 peek code/[1
ord seteq/2, 457 2], 79
ord subset/2, 458 peek string/3, 151
ord subtract/3, 458 pengines library, 189, 306
ord symdiff/3, 459 permission error/3, 344, 439
ord union/2, 459 permutation/2, 445
ord union/3, 459 persistency library, 122
ord union/4, 459 persistent/1, 462
order by/2, 188, 486 phrase/2, 120
phrase/3, 120, 121, 234, 255, 527
pack info/1, 469 phrase from file/2, 463
pack install/1, 470 phrase from file/3, 464
pack install/2, 470 phrase from quasi quotation/2, 474
pack list/1, 469 phrase from stream/2, 464
pack list installed/0, 469 pi/0, 184
pack property/2, 471 PL abort hook(), 362
pack rebuild/0, 471 PL abort unhook(), 363
pack rebuild/1, 471 PL action(), 359

SWI-Prolog 7.4 Reference Manual

570 INDEX

PL agc hook(), 363 PL functor arity(), 324

PL atom chars(), 324 PL functor name(), 324
PL atom nchars(), 330 PL get arg(), 329
PL atom wchars(), 331 PL get atom(), 327
PL backtrace(), 378 PL get atom chars(), 327
PL backtrace string(), 378 PL get atom ex(), 342
PL blob data(), 346 PL get atom nchars(), 330
PL BLOB NOCOPY, 345 PL get blob(), 346
PL BLOB TEXT, 345 PL get bool(), 329
PL BLOB UNIQUE, 345 PL get bool ex(), 343
PL call(), 350 PL get char ex(), 343
PL call predicate(), 350 PL get chars(), 327
PL chars to term(), 341 PL get compound name arity(), 329
PL check data(), 378 PL get file name(), 357
PL check stacks(), 378 PL get file nameW(), 358
PL cleanup(), 370 PL get float(), 329
PL cleanup fork(), 370 PL get float ex(), 343
PL clear exception(), 354 PL get functor(), 329
PL close foreign frame(), 351 PL get head(), 332
PL close query(), 350 PL get int64(), 329
PL compare(), 355 PL get int64 ex(), 343
PL cons functor(), 335 PL get integer(), 329
PL cons functor v(), 335 PL get integer ex(), 343
PL cons list(), 335 PL get intptr(), 329
PL context(), 352 PL get intptr ex(), 343
PL copy term ref(), 319 PL get list(), 332
PL create engine(), 304 PL get list chars(), 328
PL current query(), 350 PL get list ex(), 343
PL cut query(), 350 PL get list nchars(), 330
PL CYCLIC TERM, 332 PL get long(), 329
PL destroy engine(), 304 PL get long ex(), 343
PL discard foreign frame(), 351 PL get module(), 329
PL dispatch hook(), 362 PL get mpq(), 347
PL domain error(), 344 PL get mpz(), 347
PL duplicate record(), 356 PL get name arity(), 329
PL end stubborn change(), 380 PL get nchars(), 330
PL erase(), 356 PL get nil(), 332
PL erase external(), 357 PL get nil ex(), 343
PL exception(), 354 PL get pointer(), 329
PL existence error(), 344 PL get pointer ex(), 343
PL exit hook(), 363 PL get signum ex(), 355
PL fail(), 321 PL get size ex(), 343
PL foreign context(), 323 PL get string chars(), 327
PL foreign context address(), 323 PL get tail(), 332
PL foreign context predicate(), 323 PL get wchars(), 331
PL foreign control(), 322 PL halt(), 371
PL free(), 379 PL handle signals(), 355

SWI-Prolog 7.4 Reference Manual

INDEX 571

PL initialise(), 367 PL put bool(), 334

PL instantiation error(), 344 PL put float(), 334
PL is acyclic(), 327 PL put functor(), 334
PL is atom(), 326 PL put int64(), 334
PL is atomic(), 327 PL put integer(), 334
PL is blob(), 346 PL put list(), 335
PL is callable(), 326 PL put list chars(), 334
PL is compound(), 326 PL put list nchars(), 330
PL is float(), 326 PL put list ncodes(), 330
PL is functor(), 326 PL put nil(), 335
PL is ground(), 326 PL put pointer(), 334
PL is initialised(), 368 PL put string chars(), 334
PL is integer(), 326 PL put string nchars(), 330, 334
PL is list(), 326 PL put term(), 335
PL is number(), 327 PL put variable(), 334
PL is pair(), 326 PL query(), 359
PL is string(), 326 PL quote(), 342
PL is variable(), 326 PL raise(), 355
PL license(), 524 PL raise exception(), 353
PL LIST, 332 PL realloc(), 379
PL malloc(), 379 PL record(), 356
PL malloc atomic(), 380 PL record external(), 357
PL malloc atomic uncollectable(), 380 PL recorded(), 356
PL malloc stubborn(), 380 PL recorded external(), 357
PL malloc uncollectable(), 380 PL register atom(), 324
PL module name(), 352 PL register extensions(), 362
PL new atom(), 324 PL register extensions in module(), 361
PL new atom nchars(), 330 PL register foreign(), 361
PL new atom wchars(), 331 PL register foreign in module(), 360
PL new functor(), 324 PL representation error(), 344
PL new module(), 352 PL reset term refs(), 320
PL new term ref(), 319 PL resource error(), 344
PL new term refs(), 319 PL retry(), 322
PL next solution(), 350 PL retry address(), 322
PL NOT A LIST, 332 PL rewind foreign frame(), 351
PL on halt(), 363 PL same compound(), 355
PL open foreign frame(), 351 PL set engine(), 304
PL open query(), 349 PL set prolog flag(), 358
PL PARTIAL LIST, 332 PL set resource db mem(), 368
PL permission error(), 344 PL signal(), 355
PL pred(), 348 PL skip list(), 332
PL predicate(), 348 PL strip module(), 352
PL predicate info(), 348 PL succeed(), 321
PL put atom(), 334 PL syntax error(), 344
PL put atom chars(), 334 PL term type(), 325
PL put atom nchars(), 330 PL thread at exit(), 303
PL put blob(), 346 PL thread attach engine(), 302

SWI-Prolog 7.4 Reference Manual

572 INDEX

PL thread destroy engine(), 303 portray clause/1, 100

PL thread self(), 302 portray clause/2, 100, 163
PL throw(), 354 portray text library, 157
PL toplevel(), 370 portray text/1, 121, 236
PL type error(), 344 powm/3, 184
PL unify(), 337 precedence, 519
PL unify arg(), 339 pred/1, 257
PL unify atom(), 337 predicate, 519
PL unify atom chars(), 337 dynamic, 517
PL unify atom nchars(), 330 exported, 517
PL unify blob(), 346 imported, 518
PL unify bool(), 337 predicate indicator, 78, 519
PL unify bool ex(), 343 predicate options/3, 467
PL unify chars(), 337 predicate property/2, 82, 85, 92, 96, 108, 130,
PL unify compound(), 338 131, 255, 263
PL unify float(), 338 predsort/3, 188, 189
PL unify functor(), 338 prefix/2, 443
PL unify int64(), 338 print/1, 40, 155157, 192, 194, 349, 534
PL unify integer(), 338 print/2, 40, 157
PL unify list(), 338 print message/2, 35, 44, 46, 81, 89, 113117,
PL unify list chars(), 337 157, 159, 225, 289, 291, 533
PL unify list ex(), 343 print message lines/3, 115117, 533
PL unify list nchars(), 330 priority, 520
PL unify list ncodes(), 330 process library, 136, 199
PL unify mpq(), 348 process create/3, 136, 199, 201
PL unify mpz(), 348 profile file, 17
PL unify nil(), 339 profile/1, 219, 302, 370
PL unify nil ex(), 343 profile/3, 219
PL unify pointer(), 338 profiler/2, 222
PL unify string chars(), 338 profiling
PL unify string nchars(), 330 foreign code, 380
PL unify term(), 339 program, 520
PL unify thread id(), 302 project attributes/2, 269
PL unify wchars(), 331 prolog/0, 22, 144, 214, 215, 257, 370, 505
PL unify wchars diff(), 331 prolog/assertion failed, 438
PL uninstantiation error(), 344 prolog/debug print hook, 438
PL unregister atom(), 325 prolog:break hook/6, 507
PL unregister blob type(), 346 prolog:called by/2, 473
PL warning(), 358 prolog:comment hook/3, 511
PL wchars to term(), 342 prolog:debug control hook/1, 510
plus/3, 175 prolog:help hook/1, 511
PLVERSION, 380 prolog:message line element/2, 116
poll(), 148 prolog breakpoints library, 507
popcount/1, 185 prolog choice attribute/3, 503, 504, 506
portable prolog codewalk library, 133
prolog code, 512 prolog current choice/1, 503505
portray/1, 28, 66, 153, 155, 157, 349, 364, 510 prolog current frame/1, 503

SWI-Prolog 7.4 Reference Manual

INDEX 573

prolog cut to/1, 505 2], 79

prolog debug/1, 379 put char/1, 149
prolog edit:edit command/2, 99 put char/2, 149
prolog edit:edit source/1, 98 put char/[1
prolog edit:load/0, 99 2], 79
prolog edit:locate/2, 98 put code/1, 149, 150
prolog edit:locate/3, 98 put code/2, 58, 150, 152
prolog exception hook/4, 113, 225, 509 put code/[1
prolog file type/2, 80, 87, 211 2], 79
prolog frame attribute/3, 134, 503, 506, 509 put dict/3, 243, 244
prolog ide/1, 76 put dict/4, 243, 244
prolog list goal/1, 510
prolog load context/2, 88, 89, 92, 158, 512 qcompile/1, 13, 80, 82, 83, 90, 97, 286
prolog load file/2, 84, 511 qcompile/2, 97
prolog nodebug/1, 379 qsave program/1, 36, 90, 383
prolog server library, 135, 144 qsave program/2, 13, 31, 37, 49, 66, 76, 369, 382,
prolog skip frame/1, 507 385
prolog skip level/2, 507 qsave program/[1
prolog source library, 45 2], 21, 31, 41, 133, 314, 368, 375, 383, 384
prolog stack library, 504, 509 quasi quotation syntax/1, 133, 475
prolog stack property/2, 225 quasi quotation syntax error/1, 475
prolog to os filename/2, 65, 202, 209, 212 query, 518
prolog trace interception/4, 73, 216, 225, 503 quiet, 20
505
prolog xref library, 45, 74, 251 random library, 185
prompt random/1, 180, 475
alternatives, 40 random/3, 475
prompt/2, 160, 161, 290 random between/3, 475
prompt1/1, 161 random float/0, 180
propagation, 265 random labeling/2, 407
proper length/2, 444 random member/2, 476
property, 520 random perm2/4, 476
protocol/1, 215 random permutation/2, 477
protocola/1, 215 random property/1, 186
protocolling/1, 215 random select/3, 476
prove, 520 randseq/3, 476
public list, 520 randset/3, 476
public/1, 129, 130, 133, 384 rational
pure input library, 152 number, 176
put/1, 149, 243 rational trees, 55
put/2, 149, 243 rational/1, 100, 181
put assoc/4, 395 rational/3, 100, 177
put attr/3, 164, 268, 270 rationalize/1, 181
put attrs/2, 270 rbtrees library, 42
put byte/1, 149 RDF
put byte/2, 149 memory usage, 63
put byte/[1 rdiv/2, 179

SWI-Prolog 7.4 Reference Manual

574 INDEX

reachable/3, 496 release(), 345

read/1, 33, 35, 61, 135, 136, 138, 150, 156158, reload foreign libraries/0, 316
160, 198, 218, 478, 535 reload library index/0, 4749
read/2, 148, 157 rem/2, 179
read clause/3, 55, 157, 217 rename file/2, 199, 210
read file to codes/3, 478 repeat/0, 105, 106, 109, 110
read file to terms/3, 478 representation error/1, 344, 439
read from chars/2, 165, 398 require/1, 85, 512
read history/6, 160 reset/3, 111, 112, 537
read line to codes/2, 234, 477 reset gensym/0, 441
read line to codes/3, 477 reset gensym/1, 441
read link/3, 212 reset profiler/0, 222
read pending chars/3, 152 residual, 271
read pending codes/3, 152 resource/3, 41, 382, 385387
read stream to codes/2, 477 resource error/1, 344, 439
read stream to codes/3, 477 retract, 520
read string/3, 234 retract/1, 80, 86, 122124, 127, 129, 131, 266,
read string/5, 233, 234 298, 308
read term/2, 33, 89, 93, 153, 155, 158, 160, 166, retractall/1, 122124
229, 231, 511 retractall predicate options/0, 469
read term/3, 55, 155, 157, 158, 160, 173, 215, rev/3, 252
247, 511 reverse/2, 121, 252, 445
read term/[2 round/1, 180
3], 159
read term from atom/3, 160, 166 same file/2, 209, 210
read term from chars/3, 399 same length/2, 445
readline library, 40 same term/2, 164
readutil library, 67 sandbox/safe meta, 392
reconsult, 81 sat/1, 406
record library, 246, 248, 478 sat count/2, 406
record/1, 478, 479 scalar product/4, 423
recorda/2, 125 scanl/4, 393
recorda/3, 55, 122, 125, 130, 196, 356, 357 scanl/5, 393
recorded/2, 125 scanl/6, 393
recorded/3, 122, 125, 384 scanl/7, 393
recordz/2, 125 see/1, 135, 144, 145
recordz/3, 55, 122, 125 seeing/1, 144, 145, 213
redefine system predicate/1, 123, 516 seek/4, 140142
reexport/1, 81, 83, 258, 512 seen/0, 145
reexport/2, 8183, 258, 512 select(), 148
registry, 59 select/3, 443
registry library, 479 select/4, 443
registry delete key/1, 480 select dict/2, 245
registry get key/2, 480 select dict/3, 245
registry get key/3, 480 select option/3, 450
registry set key/2, 480 select option/4, 450
registry set key/3, 480 selectchk/3, 443

SWI-Prolog 7.4 Reference Manual

INDEX 575

selectchk/4, 443 singleton, 520

semi deterministic, 520 variable, 54
semidet, 520 sinh/1, 183
serialize, 119 size file/2, 210
serialized/2, 424 size nb set/2, 448
set breakpoint/4, 507 skip/1, 151
set end of stream/1, 152 skip/2, 151
set flag/2, 126 sleep/1, 228
set input/1, 135, 142, 145, 146 SLG
set locale/1, 169 resolution, 487
set module/1, 124, 259, 263 Solaris, 291
set output/1, 135, 145, 146 solution, 520
set prolog flag/2, 24, 32, 43, 45, 46, 80, 176, 358 sort/2, 109, 187190
set prolog IO/3, 135, 143 sort/4, 187
set prolog stack/2, 21, 59, 217, 225, 230, 290 source exports/2, 512, 513
set random/1, 180, 185, 186 source file/1, 87
set stream/2, 58, 59, 135, 136, 140142, 144, source file/2, 85, 87, 97, 131, 132
148, 151, 169 source file property/2, 83, 85, 87
set stream position/2, 140142 source location/2, 88, 89
set url encoding/2, 498 split string/4, 167, 232, 234
setarg/3, 78, 122, 163, 164, 198, 246, 267, 268, spy/1, 25, 27, 36, 37, 47, 73, 77, 79, 217, 257,
479 301, 302, 510, 529
setenv/2, 199 sqrt/1, 182
setlocale/1, 290 stack
setlocale/3, 172, 200 memory management, 61
setof/3, 55, 190, 255, 525 stamp date time/3, 203, 204
setrand/1, 475 startup file, 17
settings library, 32 statistics library, 219
setup call catcher cleanup/4, 110 statistics/0, 114, 219
setup call cleanup/2, 299 statistics/2, 184, 219221, 293
setup call cleanup/3, 109111, 291, 299, 300 stream pair/3, 136, 139, 141, 142
shadow price/3, 482 stream position data/3, 89, 140, 141, 158, 511
shared, 520 stream property/2, 59, 89, 137, 139, 141143,
shell/0, 200 160
shell/1, 65, 99, 199, 200 stream to lazy list/2, 465
shell/2, 199, 201 string/1, 101, 194, 231
shell/[0-2], 199 string chars/2, 232
shell/[1 string code/3, 232, 237
2], 199 string codes/2, 232, 235
shell register dde/6, 480 string concat/3, 232, 235
shell register file type/4, 480 string length/2, 232
shell register prolog/1, 480 string lower/2, 234
shift/1, 111, 112 string predicate/1, 400
shlib library, 528, 532, 539 string upper/2, 234
show profile/1, 219 strip module/3, 256, 261263
sign/1, 179 structure, 520
sin/1, 182 style check/1, 54, 61, 83, 129, 217

SWI-Prolog 7.4 Reference Manual

576 INDEX

sub atom/5, 167, 233 cyclic, 55

sub atom icasechk/3, 168 text to string/2, 232
sub string/5, 232, 233, 235 thread library, 36
subset/2, 447 thread at exit/1, 214, 289, 291, 303
subsumes chk/2, 105, 128 thread create/3, 288, 291, 305, 311
subsumes term/2, 55, 103, 105 thread create in pool/4, 289, 492
subtract/3, 447 thread detach/1, 289, 291
succ/2, 175 thread exit/1, 291, 292, 300
succeed, 521 thread get message/1, 294, 295, 310
sum/3, 423 thread get message/2, 295
sum list/2, 446 thread get message/3, 294296
sup/2, 431 thread initialization/1, 197, 291
swi/pce profile library, 219 thread join/2, 289292
swi edit library, 99 thread local/1, 116, 122, 129, 133, 214, 298, 309
swritef/2, 192 thread message hook/3, 116
swritef/3, 146, 191, 192 thread peek message/1, 295, 296
syntax error/1, 439, 464 thread peek message/2, 296
thread pool create/3, 491
TAB thread pool destroy/1, 492
completion, 67 thread pool property/2, 492
tab/1, 150 thread property/2, 289292
tab/2, 150 thread self/1, 41, 290, 291, 294
table/1, 41, 487, 489, 490 thread send message/2, 293295, 310
tabling library, 127, 487 thread send message/3, 294
tan/1, 182 thread setconcurrency/2, 36, 291
tanh/1, 183 thread signal/2, 110, 297, 301, 355, 371
taut/2, 406 thread statistics/3, 293
tdebug/0, 289, 301, 302 threads/0, 300
tdebug/1, 301 throw/1, 25, 55, 112, 117, 119, 291, 293, 297,
tell/1, 135, 144, 145 353, 354, 509, 510
telling/1, 144, 145, 213 time/1, 184, 219
term, 521 time file/2, 210
term//1, 146 tmp file/2, 212, 213
term attvars/2, 270 tmp file stream/3, 213
term expansion/2, 45, 46, 80, 88, 90, 91, 93, 95, tnodebug/0, 301
97, 215, 280, 514 tnodebug/1, 301, 302
term expansion/4, 80, 93 told/0, 145
term factorized/3, 147 top sort/2, 496
term hash/2, 55, 57, 128, 129 top sort/3, 496
term hash/4, 57, 128 tprofile/1, 302
term string/2, 166, 231 trace/0, 25, 37, 42, 73, 77, 216, 282, 297, 359,
term string/3, 231 508, 509
term subsumer/3, 105 trace/1, 36, 216
term to atom/2, 146, 166, 341 trace/2, 216
term variables/2, 55, 160, 163 tracing/0, 216
term variables/3, 163 transformation
terms of program, 90

SWI-Prolog 7.4 Reference Manual

INDEX 577

transitive closure/2, 496 unsetenv/1, 199, 200

transparent, 519 upcase atom/2, 170, 171
transportation/4, 482 update view, 127, 521
transpose pairs/2, 460 URL, 201
transpose ugraph/2, 495 url library, 448
trie destroy/1, 126 url iri/2, 498
trie gen/3, 126, 127 use foreign library/1, 86, 90, 202, 316, 383
trie insert/3, 127 use foreign library/2, 316
trie insert new/3, 127 use module/1, 44, 46, 65, 81, 82, 85, 96, 252
trie lookup/3, 127 254, 258, 259, 384, 512
trie new/1, 126 use module/2, 47, 81, 82, 252254, 258, 512
trie property/2, 127 use module/[1
trie term/2, 127 2], 29, 73, 80, 83, 84, 260, 517
trim stacks/0, 224, 225, 310 user library, 535
trimm stacks/0, 310 user profile file, 17
trivial fail goal/1, 400 UTF-8, 57
true/0, 39, 92, 106, 109 utf-8, 79
truncate/1, 182
tspy/1, 289, 301, 302 valgrind, 380
tspy/2, 301 valid string goal/1, 400
tty get capability/3, 198, 199 var/1, 100, 268, 325
tty goto/2, 198 var number/2, 163
tty put/2, 198 var property/2, 92
tty size/2, 198 variable, 521
ttyflush/0, 150, 192 anonymous, 516
tuples in/2, 423 variable value/3, 482
type error/2, 117, 344, 438 variant, 104
variant hash/2, 129
UCS, 57 variant sha1/2, 128, 129, 524
ugraph library, 493 varnumbers/2, 499
ugraph union/3, 495 varnumbers/3, 499
ugraphs.pl library, 493 varnumbers names/3, 499
Unicode, 57 verbose, 20
unifiable/3, 55, 103, 105 version/0, 22, 117
unify, 521 version/1, 117
unify with occurs check/2, 39, 55, 103, 104 vertices/2, 494
uninstantiation error/1, 439 vertices edges to ugraph/3, 493
union/3, 447 view
unix, 43 update, 521
unix/1, 200 visible/1, 217, 506
unknown/2, 217, 389 volatile/1, 133, 298, 384
unlisten/1, 397
unlisten/2, 397 wait for input/3, 143, 148
unlisten/3, 398 weighted maximum/3, 406
unload file/1, 83, 88, 95 when library, 271
unload foreign library/1, 316 when/2, 55, 105, 271
unload foreign library/2, 316 wildcard match/2, 228

SWI-Prolog 7.4 Reference Manual

578 INDEX

win add dll directory/1, 202 xref current source/1, 472

win add dll directory/2, 202 xref defined/3, 472
win exec/2, 199, 201 xref exported/2, 472
win folder/2, 17, 20, 201 xref module/2, 472
win has menu/0, 208 xref source/1, 472
win insert menu/2, 208, 209
win insert menu item/4, 208, 209 YAP
win registry get value/3, 201 prolog, 512
win remove dll directory/1, 202
zcompare/3, 266, 429
win shell/2, 199, 201, 448
win shell/3, 201
win window pos/1, 208
window title/2, 208
windows, 45
with mutex/2, 297, 299, 300, 302
with output to/2, 135, 136, 146, 153, 166, 172,
195, 205
with output to chars/2, 399
with output to chars/3, 399
with output to chars/4, 399
with quasi quotation input/3, 474
working directory/2, 19, 200, 211, 213
write(), 345
write/1, 45, 55, 61, 135, 136, 156, 192, 195, 328,
332, 346
write/2, 156
write canonical/1, 155, 156, 158, 194, 229
write canonical/2, 147, 156, 163, 328
write length/3, 155, 167
write term/2, 25, 36, 40, 42, 153, 155158, 163,
166, 192, 195, 229, 231, 269
write term/3, 45, 46, 154, 155, 162, 167
write to chars/2, 398
write to chars/3, 398
writef/1, 191
writef/2, 14, 52, 153, 191, 192
writeln/1, 156
writeln/2, 156
writeq/1, 156, 192, 194
writeq/2, 156, 328
www form encode/2, 498
www open url/1, 448

xor/2, 182
xref built in/1, 473
xref called/3, 472
xref clean/1, 472

SWI-Prolog 7.4 Reference Manual