YAP Prolog

@setcontentsaftertitlepage

This file documents the YAP Prolog System version No value for VERSION, a high-performance Prolog compiler developed at LIACC, Universidade do Porto. YAP is based on David H. D. Warren's WAM (Warren Abstract Machine), with several optimizations for better performance. YAP follows the Edinburgh tradition, and is largely compatible with DEC-10 Prolog, Quintus Prolog, and especially with C-Prolog.

This file contains extracts of the SWI-Prolog manual, as written by Jan Wielemaker. Our thanks to the author for his kind permission in allowing us to include his text in this document.

Built In Predicates

Subnodes of Running

Subnodes of Syntax

Subnodes of Tokens

Subnodes of Numbers

Subnodes of Loading Programs

Subnodes of Modules

Subnodes of Input/Output

Subnodes of Database

Subnodes of Library

Subnodes of Debugging

Subnodes of Compatibility

Subnodes of Attributes

Subnodes of SWI-Prolog

Subnodes of CLPR

Subnodes of CHR

Subnodes of C-Interface

Subnodes of C-Prolog

C-Prolog

Subnodes of SICStus Prolog

SICStus Prolog

SICStus Prolog

Tables

Introduction

This document provides User information on version No value for VERSION of YAP (yet another prolog). The YAP Prolog System is a high-performance Prolog compiler developed at LIACC, Universidade do Porto. YAP provides several important features:

• Speed: YAP is widely considered one of the fastest available Prolog systems.
• Functionality: it supports stream I/O, sockets, modules, exceptions, Prolog debugger, C-interface, dynamic code, internal database, DCGs, saved states, co-routining, arrays.
• We explicitly allow both commercial and non-commercial use of YAP.

YAP is based on the David H. D. Warren's WAM (Warren Abstract Machine), with several optimizations for better performance. YAP follows the Edinburgh tradition, and was originally designed to be largely compatible with DEC-10 Prolog, Quintus Prolog, and especially with C-Prolog.

YAP implements most of the ISO-Prolog standard. We are striving at full compatibility, and the manual describes what is still missing. The manual also includes a (largely incomplete) comparison with SICStus Prolog.

The document is intended neither as an introduction to Prolog nor to the implementation aspects of the compiler. A good introduction to programming in Prolog is the book The Art of Prolog, by L. Sterling and E. Shapiro, published by "The MIT Press, Cambridge MA". Other references should include the classical Programming in Prolog, by W.F. Clocksin and C.S. Mellish, published by Springer-Verlag.

YAP 4.3 is known to build with many versions of gcc (<= gcc-2.7.2, >= gcc-2.8.1, >= egcs-1.0.1, gcc-2.95.*) and on a variety of Unixen: SunOS 4.1, Solaris 2.*, Irix 5.2, HP-UX 10, Dec Alpha Unix, Linux 1.2 and Linux 2.* (RedHat 4.0 thru 5.2, Debian 2.*) in both the x86 and alpha platforms. It has been built on Windows NT 4.0 using Cygwin from Cygnus Solutions (see README.nt) and using Visual C++ 6.0.

The overall copyright and permission notice for YAP4.3 can be found in the Artistic file in this directory. YAP follows the Perl Artistic license, and it is thus non-copylefted freeware.

If you have a question about this software, desire to add code, found a bug, want to request a feature, or wonder how to get further assistance, please send e-mail to yappers@ncc.up.pt. To subscribe to the mailing list, send a request to majordomo@ncc.up.pt with body "subscribe yappers".

Online documentation is available for YAP at:

http://www.ncc.up.pt/~vsc/Yap/

Recent versions of Yap, including both source and selected binaries, can be found from this same URL.

This manual was written by Vítor Santos Costa, Luís Damas, Rogério Reis, and Rúben Azevedo. The manual is largely based on the DECsystem-10 Prolog User's Manual by D.L. Bowen, L. Byrd, F. C. N. Pereira, L. M. Pereira, and D. H. D. Warren. We have also used comments from the Edinburgh Prolog library written by R. O'Keefe. We would also like to gratefully acknowledge the contributions from Ashwin Srinivasian.

We are happy to include in YAP several excellent packages developed under separate licenses. Our thanks to the authors for their kind authorization to include these packages.

The packages are, in alphabetical order:

• The CHR package developed by Tom Schrijvers, Christian Holzbaur, and Jan Wielemaker.
• The CLP(R) package developed Leslie De Koninck, Bart Demoen, Tom Schrijvers and Jan Wielemaker and based on the CLP(Q,R) implementation by Christian Holzbauer.
• The Logtalk Object-Oriented system is developed at the University of Beira Interior, Portugal, by Paulo Moura. The package is distributed under the Perl Artistic License. Instructions about loading this package are included in this document. The documentation on this package (including full installation instructions) is distributed separately from yap.tex.

  Copyright © 1998-2006 Paulo Moura

• The Pillow WEB library developed at Universidad Politecnica de Madrid by the CLIP group. This package is distributed under the FSF's LGPL. Documentation on this package is distributed separately from yap.tex.
• The yap2swi library implements some of the functionality of SWI's PL interface. Please do refer to the SWI-Prolog home page:

  http://www.swi-prolog.org

  for more information on SWI-Prolog and for a detailed description of its foreign interface.

1. Installing YAP

To compile YAP it should be sufficient to:

1. mkdir ARCH.
2. cd ARCH.
3. ../configure ...options....

   Notice that by default configure gives you a vanilla configuration. For instance, in order to use coroutining and/or CLP you need to do

   ../configure --enable-coroutining ...options...

   Please see section Tuning the Functionality of YAP for extra options.

4. check the Makefile for any extensions or changes you want to make.

   YAP uses autoconf. Recent versions of Yap try to follow GNU conventions on where to place software.

   • The main executable is placed at BINDIR. This executable is actually a script that calls the Prolog engine, stored at LIBDIR.
   • LIBDIR is the directory where libraries are stored. YAPLIBDIR is a subdirectory that contains the Prolog engine and a Prolog library.
   • INCLUDEDIR is used if you want to use Yap as a library.
   • INFODIR is where to store info files. Usually /usr/local/info, /usr/info, or /usr/share/info.
5. make.
6. If the compilation succeeds, try ./yap.
7. If you feel satisfied with the result, do make install.
8. make install-info will create the info files in the standard info directory.
9. make html will create documentation in html format in the predefined directory.

   In most systems you will need to be superuser in order to do make install and make info on the standard directories.

1.1 Tuning the Functionality of YAP

Compiling Yap with the standard options give you a plain vanilla Prolog. You can tune Yap to include extra functionality by calling configure with the appropriate options:

• --enable-rational-trees=yes gives you support for infinite rational trees.
• --enable-coroutining=yes gives you support for coroutining, including freezing of goals, attributed variables, and constraints. This will also enable support for infinite rational trees.
• --enable-depth-limit=yes allows depth limited evaluation, say for implementing iterative deepening.
• --enable-low-level-tracer=yes allows support for tracing all calls, retries, and backtracks in the system. This can help in debugging your application, but results in performance loss.
• --enable-wam-profile=yes allows profiling of abstract machine instructions. This is useful when developing YAP, should not be so useful for normal users.
• --enable-condor=yes allows using the Condor system that support High Throughput Computing (HTC) on large collections of distributively owned computing resources.
• --enable-tabling=yes allows tabling support. This option is still experimental.
• --enable-parallelism={env-copy,sba,a-cow} allows or-parallelism supported by one of these three forms. This option is still highly experimental.
• --with-gmp[=DIR] give a path to where one can find the GMP library if not installed in the default path.

Next follow machine dependent details:

1.2 Tuning YAP for a Particular Machine and Compiler

The default options should give you best performance under GCC. Although the system is tuned for this compiler we have been able to compile versions of Yap under lcc in Linux, Sun's cc compiler, IBM's xlc, SGI's cc, and Microsoft's Visual C++ 6.0.

1.3 Tuning YAP for GCC.

Yap has been developed to take advantage of GCC (but not to depend on it). The major advantage of GCC is threaded code and explicit register reservation.

YAP is set by default to compile with the best compilation flags we know. Even so, a few specific options reduce portability. The option

• --enable-max-performance=yes will try to support the best available flags for a specific architectural model. Currently, the option assumes a recent version of GCC.
• --enable-debug-yap compiles Yap so that it can be debugged by tools such as dbx or gdb.

Here follow a few hints:

On x86 machines the flags:

YAP_EXTRAS= ... -DBP_FREE=1

tells us to use the %bp register (frame-pointer) as the emulator's program counter. This seems to be stable and is now default.

On Sparc/Solaris2 use:

YAP_EXTRAS= ...   -mno-app-regs -DOPTIMISE_ALL_REGS_FOR_SPARC=1

and YAP will get two extra registers! This trick does not work on SunOS 4 machines.

Note that versions of GCC can be tweaked to recognize different processors within the same instruction set, e.g. 486, Pentium, and PentiumPro for the x86; or Ultrasparc, and Supersparc for Sparc. Unfortunately, some of these tweaks do may make Yap run slower or not at all in other machines with the same instruction set, so they cannot be made default.

Last, the best options also depends on the version of GCC you are using, and it is a good idea to consult the GCC manual under the menus "Invoking GCC"/"Submodel Options". Specifically, you should check -march=XXX for recent versions of GCC/EGCS. In the case of GCC2.7 and other recent versions of GCC you can check:

486:

In order to take advantage of 486 specific optimizations in GCC 2.7.*:

YAP_EXTRAS= ... -m486 -DBP_FREE=1

Pentium:

YAP_EXTRAS= ... -m486 -malign-loops=2 -malign-jumps=2 \ -malign-functions=2

PentiumPro and other recent Intel and AMD machines:

PentiumPros are known not to require alignment. Check your version of GCC for the best -march option.

Super and UltraSparcs:

YAP_EXTRAS= ... -msupersparc

MIPS: if have a recent machine and you need a 64 bit wide address

space you can use the abi 64 bits or eabi option, as in:

CC="gcc -mabi=64" ./configure --...

Be careful. At least for some versions of GCC, compiling with -g seems to result in broken code.

WIN32: GCC is distributed in the MINGW32 and CYGWIN packages.

The Mingw32 environment is available from the URL:

http://www.mingw.org

You will need to install the msys and mingw packages. You should be able to do configure, make and make install.

If you use mingw32 you may want to search the contributed packages for the gmp multi-precision arithmetic library. If you do setup Yap with gmp note that libgmp.dll must be in the path, otherwise Yap will not be able to execute.

CygWin environment is available from the URL:

http://www.cygwin.com

and mirrors. We suggest using recent versions of the cygwin shell. The compilation steps under the cygwin shell are as follows:

mkdir cyg $YAPSRC/configure --enable-coroutining \\ --enable-depth-limit \\ --enable-max-performance make make install

By default, Yap will use the --enable-cygwin=no option to disable the use of the cygwin dll and to enable the mingw32 subsystem instead. Yap thus will not need the cygwin dll. It instead accesses the system's CRTDLL.DLL C run time library supplied with Win32 platforms through the mingw32 interface. Note that some older WIN95 systems may not have CRTDLL.DLL, in this case it should be sufficient to import the file from a newer WIN95 or WIN98 machine.

You should check the default installation path which is set to /Yap in the standard Makefile. This string will usually be expanded into c:\Yap by Windows.

The cygwin environment does not provide gmp. You can fetch a dll for the gmp library from http://www.sf.net/projects/mingwrep.

It is also possible to configure Yap to be a part of the cygwin environment. In this case you should use:

mkdir cyg $YAPSRC/configure --enable-coroutining \\ --enable-max-performance \\ --enable-cygwin=yes make make install

Yap will then compile using the cygwin library and will be installed in cygwin's /usr/local. You can use Yap from a cygwin console, or as a standalone application as long as it can find cygwin1.dll in its path.

1.3.1 Compiling Under Visual C++

Yap compiles cleanly under Microsoft's Visual C++ release 6.0. We next give a step-by-step tutorial on how to compile Yap manually using this environment.

First, it is a good idea to build Yap as a DLL:

1. create a project named yapdll using File.New. The project will be a DLL project, initially empty.

   Notice that either the project is named yapdll or you must replace the preprocessors variable YAPDLL_EXPORTS to match your project names in the files YapInterface.h and c_interface.c.

2. add all .c files in the $YAPSRC/C directory and in the $YAPSRC\OPTYap directory to the Project's Source Files (use FileView).
3. add all .h files in the $YAPSRC/H directory, $YAPSRC\include directory and in the $YAPSRC\OPTYap subdirectory to the Project's Header Files.
4. Ideally, you should now use m4 to generate extra .h from .m4 files and use configure to create a config.h. Or, you can be lazy, and fetch these files from $YAPSRC\VC\include.
5. You may want to go to Build.Set Active Configuration and set Project Type to Release
6. To use Yap's own include directories you have to set the Project option Project.Project Settings.C/C++.Preprocessor.Additional Include Directories to include the directories $YAPSRC\H, $YAPSRC\VC\include, $YAPSRC\OPTYap and $YAPSRC\include. The syntax is:

   $YAPSRC\H, $YAPSRC\VC\include, $YAPSRC\OPTYap, $YAPSRC\include

7. Build: the system should generate an yapdll.dll and an yapdll.lib.
8. Copy the file yapdll.dll to your path. The file yapdll.lib should also be copied to a location where the linker can find it.

Now you are ready to create a console interface for Yap:

1. create a second project say wyap with File.New. The project will be a WIN32 console project, initially empty.
2. add $YAPSRC\console\yap.c to the Source Files.
3. add $YAPSRC\VC\include\config.h and the files in $YAPSRC\include to the Header Files.
4. You may want to go to Build.Set Active Configuration and set Project Type to Release.
5. you will eventually need to bootstrap the system by booting from boot.yap, so write:

   -b $YAPSRC\pl\boot.yap

   in Project.Project Settings.Debug.Program Arguments.

6. You need the sockets and yap libraries. Add

   ws2_32.lib yapdll.lib to

   to

   to Project.Project Settings.Link.Object/Library Modules

   You may also need to set the Link Path so that VC++ will find yapdll.lib.

7. set Project.Project Settings.C/C++.Preprocessor.Additional Include Directories to include the $YAPSRC/VC/include and $YAPSRC/include.

   The syntax is:

   $YAPSRC\VC\include, $YAPSRC\include

8. Build the system.
9. Use Build.Start Debug to boot the system, and then create the saved state with

   ['$YAPSRC\\pl\\init']. save_program(startup). ^Z

   That's it, you've got Yap and the saved state!

The $YAPSRC\VC directory has the make files to build Yap4.3.17 under VC++ 6.0.

1.3.2 Compiling Under SGI's cc

YAP should compile under the Silicon Graphic's cc compiler, although we advise using the GNUCC compiler, if available.

64 bit

Support for 64 bits should work by using (under Bourne shell syntax):

CC="cc -64" $YAP_SRC_PATH/configure --...

2. Running YAP

We next describe how to invoke Yap in Unix systems.

2.1 Running Yap Interactively

Most often you will want to use Yap in interactive mode. Assuming that YAP is in the user's search path, the top-level can be invoked under Unix with the following command:

yap [-s n] [-h n] [-a n] [-c IP_HOST port ] [filename]

All the arguments and flags are optional and have the following meaning:

-?

print a short error message.

-s n

allocate n K bytes for local and global stacks

-h n

allocate n K bytes for heap and auxiliary stacks

-t n

allocate n K bytes for the trail stack

-l YAP_FILE

compile the Prolog file YAP_FILE before entering the top-level.

-L YAP_FILE

compile the Prolog file YAP_FILE and then halt. This option is useful for implementing scripts.

-g Goal

run the goal Goal before top-level. The goal is converted from an atom to a Prolog term.

-z Goal

run the goal Goal as top-level. The goal is converted from an atom to a Prolog term.

-b BOOT_FILE

boot code is in Prolog file BOOT_FILE. The filename must define the predicate '$live'/0.

-c IP_HOST port

connect standard streams to host IP_HOST at port port

filename

restore state saved in the given file

--

separator for arguments to Prolog code. These arguments are visible through the unix/1 built-in.

Note that YAP will output an error message on the following conditions:

• a file name was given but the file does not exist or is not a saved YAP state;
• the necessary amount of memory could not be allocated;
• the allocated memory is not enough to restore the state.

When restoring a saved state, YAP will allocate the same amount of memory as that in use when the state was saved, unless a different amount is specified by flags in the command line. By default, YAP restores the file `startup' from the current directory or from the YAP library.

• YAP usually boots from a saved state. The saved state will use the default installation directory to search for the YAP binary unless you define the environment variable YAPBINDIR.
• YAP always tries to find saved states from the current directory first. If it cannot it will use the environment variable YAPLIBDIR, if defined, or search the default library directory.
• YAP will try to find library files from the YAPSHAREDIR/library directory.

2.2 Running Prolog Files

YAP can also be used to run Prolog files as scripts, at least in Unix-like environments. A simple example is shown next:

#!/usr/local/bin/yap -L --
#
# Hello World script file using Yap
#
# put a dot because of syntax errors .

:- write('Hello World'), nl.

The #! characters specify that the script should call the binary file Yap. Notice that many systems will require the complete path to the Yap binary. The -L flag indicates that YAP should consult the current file when booting and then halt. The remaining arguments are then passed to YAP. Note that YAP will skip the first lines if they start with # (the comment sign for Unix's shell). YAP will consult the file and execute any commands.

A slightly more sophisticated example is:

#!/usr/bin/yap -L --
#
# Hello World script file using Yap
# .

:- initialization(main).

main :- write('Hello World'), nl.

The initialization directive tells Yap to execute the goal main after consulting the file. Source code is thus compiled and main executed at the end. The . is useful while debugging the script as a Prolog program: it guarantees that the syntax error will not propagate to the Prolog code.

Notice that the -- is required so that the shell passes the extra arguments to YAP. As an example, consider the following script dump_args:

#!/usr/bin/yap -L --
#.

main( [] ).
main( [H|T] ) :-
        write( H ), nl,
        main( T ).

:- unix( argv(AllArgs) ), main( AllArgs ).

If you this run this script with the arguments:

./dump_args -s 10000

the script will start an YAP process with stack size 10MB, and the list of arguments to the process will be empty.

Often one wants to run the script as any other program, and for this it is convenient to ignore arguments to YAP. This is possible by using L -- as in the next version of dump_args:

#!/usr/bin/yap -L --

main( [] ).
main( [H|T] ) :-
        write( H ), nl,
        main( T ).

:- unix( argv(AllArgs) ), main( AllArgs ).

The -- indicates the next arguments are not for YAP. Instead, they must be sent directly to the argv built-in. Hence, running

./dump_args test

will write test on the standard output.

3. Syntax

We will describe the syntax of YAP at two levels. We first will describe the syntax for Prolog terms. In a second level we describe the tokens from which Prolog terms are built.

3.1 Syntax of Terms

Below, we describe the syntax of YAP terms from the different classes of tokens defined above. The formalism used will be BNF, extended where necessary with attributes denoting integer precedence or operator type.

 term       ---->     subterm(1200)   end_of_term_marker

 subterm(N) ---->     term(M)         [M <= N]

 term(N)    ---->     op(N, fx) subterm(N-1)
             |        op(N, fy) subterm(N)
             |        subterm(N-1) op(N, xfx) subterm(N-1)
             |        subterm(N-1) op(N, xfy) subterm(N)
             |        subterm(N) op(N, yfx) subterm(N-1)
             |        subterm(N-1) op(N, xf)
             |        subterm(N) op(N, yf)

 term(0)   ---->      atom '(' arguments ')'
             |        '(' subterm(1200)  ')'
             |        '{' subterm(1200)  '}'
             |        list
             |        string
             |        number
             |        atom
             |        variable

 arguments ---->      subterm(999)
             |        subterm(999) ',' arguments

 list      ---->      '[]'
             |        '[' list_expr ']'

 list_expr ---->      subterm(999)
             |        subterm(999) list_tail

 list_tail ---->      ',' list_expr
             |        ',..' subterm(999)
             |        '|' subterm(999)

Notes:

• op(N,T) denotes an atom which has been previously declared with type T and base precedence N.
• Since ',' is itself a pre-declared operator with type xfy and precedence 1000, is subterm starts with a '(', op must be followed by a space to avoid ambiguity with the case of a functor followed by arguments, e.g.:

  + (a,b) [the same as '+'(','(a,b)) of arity one]

  versus

  +(a,b) [the same as '+'(a,b) of arity two]

• In the first rule for term(0) no blank space should exist between atom and '('.
• Each term to be read by the YAP parser must end with a single dot, followed by a blank (in the sense mentioned in the previous paragraph). When a name consisting of a single dot could be taken for the end of term marker, the ambiguity should be avoided by surrounding the dot with single quotes.

3.2 Prolog Tokens

Prolog tokens are grouped into the following categories:

3.2.1 Numbers

Numbers can be further subdivided into integer and floating-point numbers.

3.2.1.1 Integers

Integer numbers are described by the following regular expression:

<integer> := {<digit>+<single-quote>|0{xXo}}<alpha_numeric_char>+

where {...} stands for optionality, + optional repetition (one or more times), <digit> denotes one of the characters 0 ... 9, | denotes or, and <single-quote> denotes the character "'". The digits before the <single-quote> character, when present, form the number basis, that can go from 0, 1 and up to 36. Letters from A to Z are used when the basis is larger than 10.

Note that if no basis is specified then base 10 is assumed. Note also that the last digit of an integer token can not be immediately followed by one of the characters 'e', 'E', or '.'.

Following the ISO standard, YAP also accepts directives of the form 0x to represent numbers in hexadecimal base and of the form 0o to represent numbers in octal base. For usefulness, YAP also accepts directives of the form 0X to represent numbers in hexadecimal base.

Example: the following tokens all denote the same integer

10  2'1010  3'101  8'12  16'a  36'a  0xa  0o12

Numbers of the form 0'a are used to represent character constants. So, the following tokens denote the same integer:

0'd  100

YAP (version No value for VERSION) supports integers that can fit the word size of the machine. This is 32 bits in most current machines, but 64 in some others, such as the Alpha running Linux or Digital Unix. The scanner will read larger or smaller integers erroneously.

3.2.1.2 Floating-point Numbers

Floating-point numbers are described by:

   <float> := <digit>+{<dot><digit>+}
               <exponent-marker>{<sign>}<digit>+
            |<digit>+<dot><digit>+
               {<exponent-marker>{<sign>}<digit>+}

where <dot> denotes the decimal-point character '.', <exponent-marker> denotes one of 'e' or 'E', and <sign> denotes one of '+' or '-'.

Examples:

10.0   10e3   10e-3   3.1415e+3

Floating-point numbers are represented as a double in the target machine. This is usually a 64-bit number.

3.2.2 Character Strings

Strings are described by the following rules:

  string --> '"' string_quoted_characters '"'

  string_quoted_characters --> '"' '"' string_quoted_characters
  string_quoted_characters --> '\'
                          escape_sequence string_quoted_characters
  string_quoted_characters -->
                          string_character string_quoted_characters

  escape_sequence --> 'a' | 'b' | 'r' | 'f' | 't' | 'n' | 'v'
  escape_sequence --> '\' | '"' | ''' | '`'
  escape_sequence --> at_most_3_octal_digit_seq_char '\'
  escape_sequence --> 'x' at_most_2_hexa_digit_seq_char '\'

where string_character in any character except the double quote and escape characters.

Examples:

""   "a string"   "a double-quote:""" 

The first string is an empty string, the last string shows the use of double-quoting. The implementation of YAP represents strings as lists of integers. Since Yap4.3.0 there is no static limit on string size.

Escape sequences can be used to include the non-printable characters a (alert), b (backspace), r (carriage return), f (form feed), t (horizontal tabulation), n (new line), and v (vertical tabulation). Escape sequences also be include the meta-characters \, ", ', and `. Last, one can use escape sequences to include the characters either as an octal or hexadecimal number.

The next examples demonstrates the use of escape sequences in YAP:

"\x0c\" "\01\" "\f" "\\" 

The first three examples return a list including only character 12 (form feed). The last example escapes the escape character.

Escape sequences were not available in C-Prolog and in original versions of YAP up to 4.2.0. Escape sequences can be disable by using:

:- yap_flag(character_escapes,off).

3.2.3 Atoms

Atoms are defined by one of the following rules:

   atom --> solo-character
   atom --> lower-case-letter name-character*
   atom --> symbol-character+
   atom --> single-quote  single-quote
   atom --> ''' atom_quoted_characters '''


  atom_quoted_characters --> ''' ''' atom_quoted_characters
  atom_quoted_characters --> '\' atom_sequence string_quoted_characters
  atom_quoted_characters --> character string_quoted_characters

where:

   <solo-character>     denotes one of:    ! ;
   <symbol-character>   denotes one of:    # & * + - . / : < 
                                           = > ? @ \ ^ ` ~
   <lower-case-letter>  denotes one of:    a...z
   <name-character>     denotes one of:    _ a...z A...Z 0....9
   <single-quote>       denotes:           '

and string_character denotes any character except the double quote and escape characters. Note that escape sequences in strings and atoms follow the same rules.

Examples:

a   a12x   '$a'   !   =>  '1 2'

Version 4.2.0 of YAP removed the previous limit of 256 characters on an atom. Size of an atom is now only limited by the space available in the system.

3.2.4 Variables

Variables are described by:

   <variable-starter><variable-character>+

where

  <variable-starter>   denotes one of:    _ A...Z
  <variable-character> denotes one of:    _ a...z A...Z

If a variable is referred only once in a term, it needs not to be named and one can use the character _ to represent the variable. These variables are known as anonymous variables. Note that different occurrences of _ on the same term represent different anonymous variables.

3.2.5 Punctuation Tokens

Punctuation tokens consist of one of the following characters:

 ( ) , [ ] { } |

These characters are used to group terms.

3.2.6 Layout

Any characters with ASCII code less than or equal to 32 appearing before a token are ignored.

All the text appearing in a line after the character % is taken to be a comment and ignored (including %). Comments can also be inserted by using the sequence /* to start the comment and */ to finish it. In the presence of any sequence of comments or layout characters, the YAP parser behaves as if it had found a single blank character. The end of a file also counts as a blank character for this purpose.

4. Loading Programs

Loading Programs 4.1 Program loading and updating  Program Loading and Updating 4.2 Changing the Compiler's Behavior  Changing the compiler's parameters 4.3 Saving and Loading Prolog States  Saving and Restoring Programs

4.1 Program loading and updating

consult(+F)

Adds the clauses written in file F or in the list of files F to the program.

In YAP consult/1 does not remove previous clauses for the procedures defined in F. Moreover, note that all code in YAP is compiled.

reconsult(+F)

Updates the program replacing the previous definitions for the predicates defined in F.

[+F]

The same as consult(F).

[-+F]

The same as reconsult(F)

Example:

?- [file1, -file2, -file3, file4].

will consult file1 file4 and reconsult file2 and file3.

compile(+F)

In YAP, the same as reconsult/1.

ensure_loaded(+F) [ISO]

When the files specified by F are module files, ensure_loaded/1 loads them if they have note been previously loaded, otherwise advertises the user about the existing name clashes and prompts about importing or not those predicates. Predicates which are not public remain invisible.

When the files are not module files, ensure_loaded/1 loads them if they have not been loaded before, does nothing otherwise.

F must be a list containing the names of the files to load.

include(+F) [ISO]

The include directive includes the text files or sequence of text files specified by F into the file being currently consulted.

4.2 Changing the Compiler's Behavior

This section presents a set of built-ins predicates designed to set the environment for the compiler.

source_mode(-O,+N)

The state of source mode can either be on or off. When the source mode is on, all clauses are kept both as compiled code and in a "hidden" database. O is unified with the previous state and the mode is set according to N.

source

After executing this goal, YAP keeps information on the source of the predicates that will be consulted. This enables the use of listing/0, listing/1 and clause/2 for those clauses.

The same as source_mode(_,on) or as declaring all newly defined static procedures as public.

no_source

The opposite to source.

The same as source_mode(_,off).

compile_expressions

After a call to this predicate, arithmetical expressions will be compiled. (see example below). This is the default behavior.

do_not_compile_expressions

After a call to this predicate, arithmetical expressions will not be compiled.

?- source, do_not_compile_expressions. yes ?- [user]. | p(X) :- X is 2 * (3 + 8). | :- end_of_file. ?- compile_expressions. yes ?- [user]. | q(X) :- X is 2 * (3 + 8). | :- end_of_file. :- listing. p(A):- A is 2 * (3 + 8). q(A):- A is 22.

hide(+Atom)

Make atom Atom invisible.

unhide(+Atom)

Make hidden atom Atom visible.

hide_predicate(+Pred)

Make predicate Pred invisible to current_predicate/2, listing, and friends.

expand_exprs(-O,+N)

Puts YAP in state N (on or off) and unify O with the previous state, where On is equivalent to compile_expressions and off is equivalent to do_not_compile_expressions. This predicate was kept to maintain compatibility with C-Prolog.

path(-D)

Unifies D with the current directory search-path of YAP. Note that this search-path is only used by YAP to find the files for consult/1, reconsult/1 and restore/1 and should not be taken for the system search path.

add_to_path(+D)

Adds D to the end of YAP's directory search path.

add_to_path(+D,+N)

Inserts D in the position, of the directory search path of YAP, specified by N. N must be either of first or last.

remove_from_path(+D)

Remove D from YAP's directory search path.

style_check(+X)

Turns on style checking according to the attribute specified by X, which must be one of the following:

single_var

Checks single occurrences of named variables in a clause.

discontiguous

Checks non-contiguous clauses for the same predicate in a file.

multiple

Checks the presence of clauses for the same predicate in more than one file when the predicate has not been declared as multifile

all

Performs style checking for all the cases mentioned above.

By default, style checking is disabled in YAP unless we are in sicstus or iso language mode.

The style_check/1 built-in is now deprecated. Please use the set_prolog_flag/1 instead.

no_style_check(+X)

Turns off style checking according to the attribute specified by X, which has the same meaning as in style_check/1.

The no_style_check/1 built-in is now deprecated. Please use the set_prolog_flag/1 instead.

multifile P [ISO]

Instructs the compiler about the declaration of a predicate P in more than one file. It must appear in the first of the loaded files where the predicate is declared, and before declaration of any of its clauses.

Multifile declarations affect reconsult/1 and compile/1: when a multifile predicate is reconsulted, only the clauses from the same file are removed.

Since Yap4.3.0 multifile procedures can be static or dynamic.

discontiguous(+G) [ISO]

Declare that the arguments are discontiguous procedures, that is, clauses for discontigous procedures may be separated by clauses from other procedures.

initialization(+G) [ISO]

The compiler will execute goals G after consulting the current file.

library_directory(+D)

Succeeds when D is a current library directory name. Library directories are the places where files specified in the form library(File) are searched by the predicates consult/1, reconsult/1, use_module/1 or ensure_loaded/1.

file_search_path(+NAME,-DIRECTORY)

Allows writing file names as compound terms. The NAME and DIRECTORY must be atoms. The predicate may generate multiple solutions. The predicate is originally defined as follows:

file_search_path(library,A) :- library_directory(A). file_search_path(system,A) :- prolog_flag(host_type,A).

Thus, [library(A)] will search for a file using library_directory/1 to obtain the prefix.

library_directory(+D)

Succeeds when D is a current library directory name. Library directories are the places where files specified in the form library(File) are searched by the predicates consult/1, reconsult/1, use_module/1 or ensure_loaded/1.

prolog_file_name(+Name,-FullPath)

Unify FullPath with the absolute path YAP would use to consult file Name.

public P [ISO]

Instructs the compiler that the source of a predicate of a list of predicates P must be kept. This source is then accessible through the clause/2 procedure and through the listing family of built-ins.

Note that all dynamic procedures are public. The source directive defines all new or redefined predicates to be public.

Since Yap4.3.0 multifile procedures can be static or dynamic.

4.3 Saving and Loading Prolog States

save(+F)

Saves an image of the current state of YAP in file F. From Yap4.1.3 onwards, YAP saved states are executable files in the Unix ports.

save(+F,-OUT)

Saves an image of the current state of YAP in file F. From Yap4.1.3 onwards, YAP saved states are executable files in the Unix ports.

Unify OUT with 1 when saving the file and OUT with 0 when restoring the saved state.

save_program(+F)

Saves an image of the current state of the YAP database in file F.

save_program(+F, :G)

Saves an image of the current state of the YAP database in file F, and guarantee that execution of the restored code will start by trying goal G.

restore(+F)

Restores a previously saved state of YAP from file F.

YAP always tries to find saved states from the current directory first. If it cannot it will use the environment variable YAPLIBDIR, if defined, or search the default library directory.

5. The Module System

Module systems are quite important for the development of large applications. YAP implements a module system compatible with the Quintus Prolog module system.

The YAP module system is predicate-based. This means a module consists of a set of predicates (or procedures), such that some predicates are public and the others are local to a module. Atoms and terms in general are global to the system. Moreover, the module system is flat, meaning that we do not support an hierarchy of modules. Modules can automatically import other modules, though. For compatibility with other module systems the YAP module system is non-strict, meaning both that there is both a way to access predicates private to a module and that is possible to declare predicates for a module from some other module.

YAP allows one to ignore the module system if one does not want to use it. Last note that using the module system does not introduce any significant overheads: only meta-calls that cross module boundaries are slowed down by the presence of modules.

5.1 Module Concepts

The YAP module system applies to predicates. All predicates belong to a module. System predicates belong to the module primitives, and by default new predicates belong to the module user. Predicates from the module primitives are automatically visible to every module.

Every predicate must belong to a module. This module is called its source module.

By default, the source module for a clause occurring in a source file with a module declaration is the declared module. For goals typed in a source file without module declarations, their module is the module the file is being loaded into. If no module declarations exist, this is the current type-in module. The default type-in module is user, but one can set the current module by using the built-in module/1.

Note that in this module system one can explicitly specify the source mode for a clause by prefixing a clause with its module, say:

user:(a :- b).

In fact, to specify the source module for a clause it is sufficient to specify the source mode for the clause's head:

user:a :- b.

The rules for goals are similar. If a goal appears in a text file with a module declaration, the goal's source module is the declared module. Otherwise, it is the module the file is being loaded into or the type-in module.

One can override this rule by prefixing a goal with the module it is supposed to be executed into, say:

nasa:launch(apollo,13).

will execute the goal launch(apollo,13) as if the current source module was nasa.

Note that this rule breaks encapsulation and should be used with care.

5.2 Defining a New Module

A new module is defined by a module declaration:

module(+M,+L)

This predicate defines the file where it appears as a module file; it must be the first declaration in the file. M must be an atom specifying the module name; L must be a list containing the module's public predicates specification, in the form [predicate_name/arity,...].

The public predicates of a module file can be made accessible by other files through the predicates consult/1, reconsult/1, ensure_loaded/1 or use_module/2. The non-public predicates of a module file are not visible by other files; they can, however, be accessed if the module name is prefixed to the file name through the :/2 operator.

The built-in module/1 sets the current source module:

module(+M,+L, +Options)

Similar to module/2, this predicate defines the file where it appears as a module file; it must be the first declaration in the file. M must be an atom specifying the module name; L must be a list containing the module's public predicates specification, in the form [predicate_name/arity,...].

The last argument Options must be a list of options, which can be:

filename

the filename for a module to import into the current module.

library(file)

a library file to import into the current module.

hide(Opt)

if Opt is false, keep source code for current module, if true, disable.

module(+M)

Defines M to be the current working or type-in module. All files which are not binded to a module are assumed to belong to the working module (also referred to as type-in module). To compile a non-module file into a module which is not the working one, prefix the file name with the module name, in the form Module:File, when loading the file.

5.3 Using Modules

By default, all procedures to consult a file will load the modules defined therein. The two following declarations allow one to import a module explicitly. They differ on whether one imports all predicate declared in the module or not.

use_module(+F)

Loads the files specified by F, importing all their public predicates. Predicate name clashes are resolved by asking the user about importing or not the predicate. A warning is displayed when F is not a module file.

use_module(+F,+L)

Loads the files specified by F, importing the predicates specified in the list L. Predicate name clashes are resolved by asking the user about importing or not the predicate. A warning is displayed when F is not a module file.

use_module(?M,?F,+L)

If module M has been defined, import the procedures in L to the current module. Otherwise, load the files specified by F, importing the predicates specified in the list L.

5.4 Meta-Predicates in Modules

The module system must know whether predicates operate on goals or clauses. Otherwise, such predicates would call a goal in the module they were defined, instead of calling it in the module they are currently executing. So, for instance:

:- module(example,[a/1]).

...

a(G) :- call(G)

...

The expected behavior for this procedure is to execute goal G within the current module, that is, within example. On the other hand, when executing call/1 the system only knows where call/1 was defined, that is, it only knows of primitives. A similar problem arises for assert/1 and friends.

The meta_predicate/1 declaration informs the system that some arguments of a procedure are goals, clauses or clauses heads, and that these arguments must be expanded to receive the current source module:

meta_predicate G1,....,Gn

Each Gi is a mode specification. For example, a declaration for call/1 and setof/3 would be of the form:

:- meta_predicate call(:), setof(?,:,?).

If the argument is : or an integer, the argument is a call and must be expanded. Otherwise, the argument should not be expanded. Note that the system already includes declarations for all built-ins.

In the previous example, the only argument to call/1 must be expanded, resulting in the following code:

:- module(example,[a/1]).

...

a(G) :- call(example:G)

...

6. Built-In Predicates

Builtins, Debugging, Syntax, Top 6.1 Control Predicates  Controlling the Execution of Prolog Programs 6.2 Handling Undefined Procedures  Handling calls to Undefined Procedures 6.3 Predicates on terms  Predicates on Terms 6.4 Comparing Terms  Comparison of Terms 6.5 Arithmetic  Arithmetic in Yap 6.6 I/O Predicates  Input/Output with Yap 6.7 Using the Clausal Data Base  Modifying Prolog's Database 6.10 Collecting Solutions to a Goal  Finding All Possible Solutions 6.11 Grammar Rules  Grammar Rules 6.17 Predicate Information  Predicate Information 6.12 Access to Operating System Functionality  Access to Operating System Functionality 6.13 Term Modification  Updating Prolog Terms 6.14 Profiling Prolog Programs  Profiling Prolog Execution 6.15 Counting Calls  Limiting the Maximum Number of Reductions 6.16 Arrays  Supporting Global and Local Arrays 6.17 Predicate Information  Information on Predicates 6.18 Miscellaneous  Miscellaneous Predicates

6.1 Control Predicates

This chapter describes the predicates for controlling the execution of Prolog programs.

In the description of the arguments of functors the following notation will be used:

• a preceding plus sign will denote an argument as an "input argument" - it cannot be a free variable at the time of the call;
• a preceding minus sign will denote an "output argument";
• an argument with no preceding symbol can be used in both ways.

+P, +Q [ISO]

Conjunction of goals (and).

Example:

p(X) :- q(X), r(X).

should be read as "p(X) if q(X) and r(X)".

+P ; +Q [ISO]

Disjunction of goals (or).

Example:

p(X) :- q(X); r(X).

should be read as "p(X) if q(X) or r(X)".

true [ISO]

Succeeds once.

fail [ISO]

Fails always.

false

The same as fail

! [ISO]

Read as "cut". Cuts any choices taken in the current procedure. When first found "cut" succeeds as a goal, but if backtracking should later return to it, the parent goal (the one which matches the head of the clause containing the "cut", causing the clause activation) will fail. This is an extra-logical predicate and cannot be explained in terms of the declarative semantics of Prolog.

example:

member(X,[X|_]). member(X,[_|L]) :- member(X,L).

With the above definition

?- member(X,[1,2,3]).

will return each element of the list by backtracking. With the following definition:

member(X,[X|_]) :- !. member(X,[_|L]) :- member(X,L).

the same query would return only the first element of the list, since backtracking could not "pass through" the cut.

\+ +P [ISO]

Goal P is not provable. The execution of this predicate fails if and only if the goal P finitely succeeds. It is not a true logical negation, which is impossible in standard Prolog, but "negation-by-failure".

This predicate might be defined as:

\+(P) :- P, !, fail. \+(_).

if P did not include "cuts".

not +P

Goal P is not provable. The same as '\+ P'.

This predicate is kept for compatibility with C-Prolog and previous versions of YAP. Uses of not/1 should be replace by (\+)/1, as YAP does not implement true negation.

+P -> +Q [ISO]

Read as "if-then-else" or "commit". This operator is similar to the conditional operator of imperative languages and can be used alone or with an else part as follows:

+P -> +Q

"if P then Q".

+P -> +Q; +R

"if P then Q else R".

These two predicates could be defined respectively in Prolog as:

(P -> Q) :- P, !, Q.

and

(P -> Q; R) :- P, !, Q. (P -> Q; R) :- R.

if there were no "cuts" in P, Q and R.

Note that the commit operator works by "cutting" any alternative solutions of P.

Note also that you can use chains of commit operators like:

P -> Q ; R -> S ; T.

Note that (->)/2 does not affect the scope of cuts in its arguments.

repeat [ISO]

Succeeds repeatedly.

In the next example, repeat is used as an efficient way to implement a loop. The next example reads all terms in a file:

a :- repeat, read(X), write(X), nl, X=end_of_file, !.

the loop is effectively terminated by the cut-goal, when the test-goal X=end succeeds. While the test fails, the goals read(X), write(X), and nl are executed repeatedly, because backtracking is caught by the repeat goal.

The built-in repeat/1 could be defined in Prolog by:

repeat. repeat :- repeat.

call(+P) [IS0]

If P is instantiated to an atom or a compound term, the goal call(P) is executed as if the value of P was found instead of the call to call/1, except that any "cut" occurring in P only cuts alternatives in the execution of P.

incore(+P)

The same as call/1.

call_with_args(+Name,...,?Ai,...)

Meta-call where Name is the name of the procedure to be called and the Ai are the arguments. The number of arguments varies between 0 and 10.

If Name is a complex term, then call_with_args/n behaves as call/n:

call(p(X1,...,Xm), Y1,...,Yn) :- p(X1,...,Xm,Y1,...,Yn).

+P

The same as call(P). This feature has been kept to provide compatibility with C-Prolog. When compiling a goal, YAP generates a call(X) whenever a variable X is found as a goal.

a(X) :- X.

is converted to:

a(X) :- call(X).

if(?G,?H,?I) [IS0]

Call goal H once per each solution of goal H. If goal H has no solutions, call goal I.

The built-in if/3 is similar to ->/3, with the difference that it will backtrack over the test goal. Consider the following small data-base:

a(1). b(a). c(x). a(2). b(b). c(y).

Execution of an if/3 query will proceed as follows:

?- if(a(X),b(Y),c(Z)). X = 1, Y = a ? ; X = 1, Y = b ? ; X = 2, Y = a ? ; X = 2, Y = b ? ; no

The system will backtrack over the two solutions for a/1 and the two solutions for b/1, generating four solutions.

Cuts are allowed inside the first goal G, but they will only prune over G.

If you want G to be deterministic you should use if-then-else, as it is both more efficient and more portable.

once(:G) [IS0]

Execute the goal G only once. The predicate is defined by:

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

Note that cuts inside once/1 can only cut the other goals inside once/1.

abort

Abandons the execution of the current goal and returns to top level. All break levels (see break/0 below) are terminated. It is mainly used during debugging or after a serious execution error, to return to the top-level.

break

Suspends the execution of the current goal and creates a new execution level similar to the top level, displaying the following message:

[ Break (level <number>) ]

telling the depth of the break level just entered. To return to the previous level just type the end-of-file character or call the end_of_file predicate. This predicate is especially useful during debugging.

halt [ISO]

Halts Prolog, and exits to the calling application. In YAP, halt/0 returns the exit code 0.

halt(+ I) [ISO]

Halts Prolog, and exits to the calling application returning the code given by the integer I.

catch(+Goal,+Exception,+Action) [IS0]

The goal catch(Goal,Exception,Action) tries to execute goal Goal. If during its execution, Goal throws an exception E' and this exception unifies with Exception, the exception is considered to be caught and Action is executed. If the exception E' does not unify with Exception, control again throws the exception.

The top-level of YAP maintains a default exception handler that is responsible to capture uncaught exceptions.

throw(+Ball) [ISO]

The goal throw(Ball) throws an exception. Execution is stopped, and the exception is sent to the ancestor goals until reaching a matching catch/3, or until reaching top-level.

garbage_collect

The goal garbage_collect forces a garbage collection.

garbage_collect_atoms

The goal garbage_collect forces a garbage collection of the atoms in the data-base. Currently, only atoms are recovered.

gc

The goal gc enables garbage collection. The same as yap_flag(gc,on).

nogc

The goal nogc disables garbage collection. The same as yap_flag(gc,off).

grow_heap(+Size)

Increase heap size Size kilobytes.

grow_stack(+Size)

Increase stack size Size kilobytes.

6.2 Handling Undefined Procedures

A predicate in a module is said to be undefined if there are no clauses defining the predicate, and if the predicate has not been declared to be dynamic. What YAP does when trying to execute undefined predicates can be specified through three different ways:

• By setting an YAP flag, through the yap_flag/2 or set_prolog_flag/2 built-ins. This solution generalizes the ISO standard.
• By using the unknown/2 built-in (this solution is compatible with previous releases of YAP).
• By defining clauses for the hook predicate user:unknown_predicate_handler/3. This solution is compatible with SICStus Prolog.

In more detail:

unknown(-O,+N)

Specifies an handler to be called is a program tries to call an undefined static procedure P.

The arity of N may be zero or one. If the arity is 0, the new action must be one of fail, warning, or error. If the arity is 1, P is an user-defined handler and at run-time, the argument to the handler P will be unified with the undefined goal. Note that N must be defined prior to calling unknown/2, and that the single argument to N must be unbound.

In YAP, the default action is to fail (note that in the ISO Prolog standard the default action is error).

After defining undefined/1 by:

undefined(A) :- format('Undefined predicate: ~w~n',[A]), fail.

and executing the goal:

unknown(U,undefined(X)).

a call to a predicate for which no clauses were defined will result in the output of a message of the form:

Undefined predicate: user:xyz(A1,A2)

followed by the failure of that call.

yap_flag(unknown,+SPEC)

Alternatively, one can use yap_flag/2, current_prolog_flag/2, or set_prolog_flag/2, to set this functionality. In this case, the first argument for the built-ins should be unknown, and the second argument should be either error, warning, fail, or a goal.

user:unknown_predicate_handler(+G,+M,?NG)

The user may also define clauses for user:unknown_predicate_handler/3 hook predicate. This user-defined procedure is called before any system processing for the undefined procedure, with the first argument G set to the current goal, and the second M set to the current module. The predicate G will be called from within the user module.

If user:unknown_predicate_handler/3 succeeds, the system will execute NG. If user:unknown_predicate_handler/3 fails, the system will execute default action as specified by unknown/2.

6.3 Predicates on terms

var(T) [ISO]

Succeeds if T is currently a free variable, otherwise fails.

atom(T) [ISO]

Succeeds if and only if T is currently instantiated to an atom.

atomic(T) [ISO]

Checks whether T is an atomic symbol (atom or number).

compound(T) [ISO]

Checks whether T is a compound term.

db_reference(T)

Checks whether T is a database reference.

float(T) [ISO]

Checks whether T is a floating point number.

integer(T) [ISO]

Succeeds if and only if T is currently instantiated to an integer.

nonvar(T) [ISO]

The opposite of var(T).

number(T) [ISO]

Checks whether T is an integer or a float.

primitive(T)

Checks whether T is an atomic term or a database reference.

simple(T)

Checks whether T is unbound, an atom, or a number.

callable(T)

Checks whether T is a callable term, that is, an atom or a compound term.

name(A,L)

The predicate holds when at least one of the arguments is ground (otherwise, an error message will be displayed). The argument A will be unified with an atomic symbol and L with the list of the ASCII codes for the characters of the external representation of A.

name(yap,L).

will return:

L = [121,97,112].

and

name(3,L).

will return:

L = [51].

atom_chars(?A,?L) [ISO]

The predicate holds when at least one of the arguments is ground (otherwise, an error message will be displayed). The argument A must be unifiable with an atom, and the argument L with the list of the ASCII codes for the characters of the external representation of A.

The ISO-Prolog standard dictates that atom_chars/2 should unify the second argument with a list of one-char atoms, and not the character codes. For compatibility with previous versions of YAP, and with other Prolog implementations, YAP unifies the second argument with the character codes, as in atom_codes/2. Use the set_prolog_flag(to_chars_mode,iso) to obtain ISO standard compatibility.

atom_codes(?A,?L) [ISO]

The predicate holds when at least one of the arguments is ground (otherwise, an error message will be displayed). The argument A will be unified with an atom and L with the list of the ASCII codes for the characters of the external representation of A.

atom_concat(+As,?A)

The predicate holds when the first argument is a list of atoms, and the second unifies with the atom obtained by concatenating all the atoms in the first list.

atomic_concat(+As,?A)

The predicate holds when the first argument is a list of atoms, and the second unifies with the atom obtained by concatenating all the atomic terms in the first list. The first argument thus may contain atoms or numbers.

atom_concat(+A1,+A2,?A)

The predicate holds when the first argument and second argument are atoms, and the third unifies with the atom obtained by concatenating the first two arguments.

atom_length(+A,?I) [ISO]

The predicate holds when the first argument is an atom, and the second unifies with the number of characters forming that atom.

atom_concat(?A1,?A2,?A12) [ISO]

The predicate holds when the third argument unifies with an atom, and the first and second unify with atoms such that their representations concatenated are the representation for A12.

If A1 and A2 are unbound, the built-in will find all the atoms that concatenated give A12.

number_chars(?I,?L)

The predicate holds when at least one of the arguments is ground (otherwise, an error message will be displayed). The argument I must be unifiable with a number, and the argument L with the list of the ASCII codes for the characters of the external representation of I.

The ISO-Prolog standard dictates that number_chars/2 should unify the second argument with a list of one-char atoms, and not the character codes. For compatibility with previous versions of YAP, and with other Prolog implementations, YAP unifies the second argument with the character codes, as in number_codes/2. Use the set_prolog_flag(to_chars_mode,iso) to obtain ISO standard compatibility.

number_codes(?A,?L) [ISO]

The predicate holds when at least one of the arguments is ground (otherwise, an error message will be displayed). The argument A will be unified with a number and L with the list of the ASCII codes for the characters of the external representation of A.

number_atom(?I,?L)

The predicate holds when at least one of the arguments is ground (otherwise, an error message will be displayed). The argument I must be unifiable with a number, and the argument L must be unifiable with an atom representing the number.

char_code(?A,?I) [ISO]

The built-in succeeds with A bound to character represented as an atom, and I bound to the character code represented as an integer. At least, one of either A or I must be bound before the call.

sub_atom(+A,?Bef, ?Size, ?After, ?At_out) [ISO]

True when A and At_out are atoms such that the name of At_out has size Size and is a substring of the name of A, such that Bef is the number of characters before and After the number of characters afterwards.

Note that A must always be known, but At_out can be unbound when calling this built-in. If all the arguments for sub_atom/5 but A are unbound, the built-in will backtrack through all possible substrings of A.

numbervars(T,+N1,-Nn)

Instantiates each variable in term T to a term of the form: '$VAR'(I), with I increasing from N1 to Nn.

ground(T)

Succeeds if there are no free variables in the term T.

arg(+N,+T,A) [ISO]

Succeeds if the argument N of the term T unifies with A. The arguments are numbered from 1 to the arity of the term.

The current version will generate an error if T or N are unbound, if T is not a compound term, of if N is not a positive integer. Note that previous versions of YAP would fail silently under these errors.

functor(T,F,N)

The top functor of term T is named F and has arity N.

When T is not instantiated, F and N must be. If N is 0, F must be an atomic symbol, which will be unified with T. If N is not 0, then F must be an atom and T becomes instantiated to the most general term having functor F and arity N. If T is instantiated to a term then F and N are respectively unified with its top functor name and arity.

In the current version of YAP the arity N must be an integer. Previous versions allowed evaluable expressions, as long as the expression would evaluate to an integer. This feature is not available in the ISO Prolog standard.

T =.. L [ISO]

The list L is built with the functor and arguments of the term T. If T is instantiated to a variable, then L must be instantiated either to a list whose head is an atom, or to a list consisting of just a number.

X = Y [ISO]

Tries to unify terms X and Y.

X \= Y [ISO]

Succeeds if terms X and Y are not unifiable.

unify_with_occurs_check(?T1,?T2) [ISO]

Obtain the most general unifier of terms T1 and T2, if there is one.

This predicate implements the full unification algorithm. An example:n

unify_with_occurs_check(a(X,b,Z),a(X,A,f(B)).

will succeed with the bindings A = b and Z = f(B). On the other hand:

unify_with_occurs_check(a(X,b,Z),a(X,A,f(Z)).

would fail, because Z is not unifiable with f(Z). Note that (=)/2 would succeed for the previous examples, giving the following bindings A = b and Z = f(Z).

copy_term(?TI,-TF) [ISO]

Term TF is a variant of the original term TI, such that for each variable V in the term TI there is a new variable V' in term TF.

6.4 Comparing Terms

The following predicates are used to compare and order terms, using the standard ordering:

• variables come before numbers, numbers come before atoms which in turn come before compound terms, i.e.: variables @< numbers @< atoms @< compound terms.
• variables are roughly ordered by "age" (the "oldest" variable is put first);
• floating point numbers are sorted in increasing order;
• Integers are sorted in increasing order;
• atoms are sorted in lexicographic order;
• compound terms are ordered first by name, then by arity of the main functor, and finally by their arguments in left-to-right order.

compare(C,X,Y)

As a result of comparing X and Y, C may take one of the following values:

• = if X and Y are identical;
• < if X precedes Y in the defined order;
• > if Y precedes X in the defined order;

X == Y [ISO]

Succeeds if terms X and Y are strictly identical. The difference between this predicate and =/2 is that, if one of the arguments is a free variable, it only succeeds when they have already been unified.

?- X == Y.

fails, but,

?- X = Y, X == Y.

succeeds.

?- X == 2.

fails, but,

?- X = 2, X == 2.

succeeds.

X \== Y [ISO]

Terms X and Y are not strictly identical.

X @< Y [ISO]

Term X precedes term Y in the standard order.

X @=< Y [ISO]

Term X does not follow term Y in the standard order.

X @> Y [ISO]

Term X follows term Y in the standard order.

X @>= Y [ISO]

Term X does not precede term Y in the standard order.

sort(+L,-S)

Unifies S with the list obtained by sorting L and merging identical (in the sense of ==) elements.

keysort(+L,S)

Assuming L is a list of the form Key-Value, keysort(+L,S) unifies S with the list obtained from L, by sorting its elements according to the value of Key.

?- keysort([3-a,1-b,2-c,1-a,1-b],S).

would return:

S = [1-b,1-a,1-b,2-c,3-a]

length(?L,?S)

Unify the well-defined list L with its length. The procedure can be used to find the length of a pre-defined list, or to build a list of length S.

6.5 Arithmetic

Arithmetic expressions in YAP may use the following operators or evaluable predicates:

+X

The value of X itself.

-X [ISO]

Symmetric value.

X+Y [ISO]

Sum.

X-Y [ISO]

Difference.

X*Y [ISO]

Product.

X/Y [ISO]

Quotient.

X//Y [ISO]

Integer quotient.

X mod Y [ISO]

Integer remainder.

X rem Y

Integer remainder, the same as mod.

exp(X) [ISO]

Natural exponential.

log(X) [ISO]

Natural logarithm.

log10(X)

Decimal logarithm.

sqrt(X) [ISO]

Square root.

sin(X) [ISO]

Sine.

cos(X) [ISO]

Cosine.

tan(X)

Tangent.

asin(X)

Arc sine.

acos(X)

Arc cosine.

atan(X) [ISO]

Arc tangent.

atan2(X)

Four-quadrant arc tangent.

sinh(X)

Hyperbolic sine.

cosh(X)

Hyperbolic cosine.

tanh(X)

Hyperbolic tangent.

asinh(X)

Hyperbolic arc sine.

acosh(X)

Hyperbolic arc cosine.

atanh(X)

Hyperbolic arc tangent.

integer(X) [ISO]

If X evaluates to a float, the integer between the value of X and 0 closest to the value of X, else if X evaluates to an integer, the value of X.

float(X) [ISO]

If X evaluates to an integer, the corresponding float, else the float itself.

float_fractional_part(X) [ISO]

The fractional part of the floating point number X, or 0.0 if X is an integer. In the iso language mode, X must be an integer.

float_integer_part(X) [ISO]

The float giving the integer part of the floating point number X, or X if X is an integer. In the iso language mode, X must be an integer.

abs(X) [ISO]

The absolute value of X.

ceiling(X) [ISO]

The float that is the smallest integral value not smaller than X.

In iso language mode the argument must be a floating point-number and the result is an integer.

floor(X) [ISO]

The float that is the greatest integral value not greater than X.

In iso language mode the argument must be a floating point-number and the result is an integer.

round(X) [ISO]

The nearest integral value to X. If X is equidistant to two integers, it will be rounded to the closest even integral value.

In iso language mode the argument must be a floating point-number, the result is an integer and it the float is equidistant it is rounded up, that is, to the least integer greater than X.

sign(X) [ISO]

Return 1 if the X evaluates to a positive integer, 0 it if evaluates to 0, and -1 if it evaluates to a negative integer. If X evaluates to a floating-point number return 1.0 for a positive X, 0.0 for 0.0, and -1.0 otherwise.

truncate(X)

The float that is the integral value between X and 0 closest to X.

max(X,Y)

The greater value of X and Y.

min(X,Y)

The lesser value of X and Y.

X ^ Y

X raised to the power of Y, (from the C-Prolog syntax).

exp(X,Y)

X raised to the power of Y, (from the Quintus Prolog syntax).

X ** Y [ISO]

X raised to the power of Y (from ISO).

X /\ Y [ISO]

Integer bitwise conjunction.

X \/ Y [ISO]

Integer bitwise disjunction.

X # Y [ISO]

Integer bitwise exclusive disjunction.

X << Y

Integer bitwise left logical shift of X by Y places.

X >> Y [ISO]

Integer bitwise right logical shift of X by Y places.

\ X [ISO]

Integer bitwise negation.

gcd(X,Y)

The greatest common divisor of the two integers X and Y.

msb(X)

The most significant bit of the integer X.

[X]

Evaluates to X for expression X. Useful because character strings in Prolog are lists of character codes.

X is Y*10+C-"0"

is the same as

X is Y*10+C-[48].

which would be evaluated as:

X is Y*10+C-48.

Besides numbers and the arithmetic operators described above, certain atoms have a special meaning when present in arithmetic expressions:

pi

The value of pi, the ratio of a circle's circumference to its diameter.

e

The base of the natural logarithms.

inf

Infinity according to the IEEE Floating-Point standard. Note that evaluating this term will generate a domain error in the iso language mode.

nan

Not-a-number according to the IEEE Floating-Point standard. Note that evaluating this term will generate a domain error in the iso language mode.

cputime

CPU time in seconds, since YAP was invoked.

heapused

Heap space used, in bytes.

local

Local stack in use, in bytes.

global

Global stack in use, in bytes.

random

A "random" floating point number between 0 and 1.

The primitive YAP predicates involving arithmetic expressions are:

X is +Y [2]

This predicate succeeds iff the result of evaluating the expression Y unifies with X. This is the predicate normally used to perform evaluation of arithmetic expressions:

X is 2+3*4

succeeds with X = 14.

+X < +Y [ISO]

The value of the expression X is less than the value of expression Y.

+X =< +Y [ISO]

The value of the expression X is less than or equal to the value of expression Y.

+X > +Y [ISO]

The value of the expression X is greater than the value of expression Y.

+X >= +Y [ISO]

The value of the expression X is greater than or equal to the value of expression Y.

+X =:= +Y [ISO]

The value of the expression X is equal to the value of expression Y.

+X =\= +Y [ISO]

The value of the expression X is different from the value of expression Y.

srandom(+X)

Use the argument X as a new seed for YAP's random number generator. The argument should be an integer, but floats are acceptable.

Notes:

• In contrast to previous versions of Yap, Yap4 does not convert automatically between integers and floats.
• arguments to trigonometric functions are expressed in radians.
• if a (non-instantiated) variable occurs in an arithmetic expression YAP will generate an exception. If no error handler is available, execution will be thrown back to the top-level.

6.6 I/O Predicates

Some of the I/O predicates described below will in certain conditions provide error messages and abort only if the file_errors flag is set. If this flag is cleared the same predicates will just fail. Details on setting and clearing this flag are given under 7.7.

Subnodes of Input/Output 6.6.1 Handling Streams and Files  Handling Streams and Files 6.6.2 Handling Streams and Files  C-Prolog Compatible File Handling 6.6.3 Handling Input/Output of Terms  Input/Output of terms 6.6.4 Handling Input/Output of Characters  Input/Output of Characters 6.6.5 Input/Output Predicates applied to Streams  Input/Output using Streams 6.6.6 Compatible C-Prolog predicates for Terminal I/O  C-Prolog compatible Character I/O to terminal 6.6.7 Controlling Input/Output  Controlling your Input/Output 6.6.8 Using Sockets From Yap  Using Sockets from Yap

6.6.1 Handling Streams and Files

open(+F,+M,-S) [ISO]

Opens the file with name F in mode M ('read', 'write' or 'append'), returning S unified with the stream name.

At most, there are 17 streams opened at the same time. Each stream is either an input or an output stream but not both. There are always 3 open streams: user_input for reading, user_output for writing and user_error for writing. If there is no ambiguity, the atoms user_input and user_output may be referred to as user.

The file_errors flag controls whether errors are reported when in mode 'read' or 'append' the file F does not exist or is not readable, and whether in mode 'write' or 'append' the file is not writable.

open(+F,+M,-S,+Opts) [ISO]

Opens the file with name F in mode M ('read', 'write' or 'append'), returning S unified with the stream name, and following these options:

type(+T)

Specify whether the stream is a text stream (default), or a binary stream.

reposition(+Bool)

Specify whether it is possible to reposition the stream (true), or not (false). By default, YAP enables repositioning for all files, except terminal files and sockets.

eof_action(+Action)

Specify the action to take if attempting to input characters from a stream where we have previously found an end-of-file. The possible actions are error, that raises an error, reset, that tries to reset the stream and is used for tty type files, and eof_code, which generates a new end-of-file (default for non-tty files).

alias(+Name)

Specify an alias to the stream. The alias Name must be an atom. The alias can be used instead of the stream descriptor for every operation concerning the stream.

The operation will fail and give an error if the alias name is already in use. YAP allows several aliases for the same file, but only one is returned by stream_property/2

close(+S) [ISO]

Closes the stream S. If S does not stand for a stream currently opened an error is reported. The streams user_input, user_output, and user_error can never be closed.

By default, give a file name, close/1 will also try to close a corresponding open stream. This feature is not available in ISO or SICStus languages mode and is deprecated.

close(+S,+O) [ISO]

Closes the stream S, following options O.

The only valid options are force(true) and force(false). YAP currently ignores these options.

absolute_file_name(+Name,-FullPath)

Give the path a full path FullPath Yap would use to consult a file named Name. Unify FullPath with user if the file name is user.

current_stream(F,M,S)

Defines the relation: The stream S is opened on the file F in mode M. It might be used to obtain all open streams (by backtracking) or to access the stream for a file F in mode M, or to find properties for a stream S.

flush_output [ISO]

Send all data in the output buffer to current output stream.

flush_output(+S) [ISO]

Send all data in the output buffer to stream S.

set_input(+S)

Set stream S as the current input stream. Predicates like read/1 and get/1 will start using stream S.

set_output(+S)

Set stream S as the current output stream. Predicates like write/1 and put/1 will start using stream S.

stream_select(+STREAMS,+TIMEOUT,-READSTREAMS)

Given a list of open STREAMS openeded in read mode and a TIMEOUT return a list of streams who are now available for reading.

If the TIMEOUT is instantiated to off, stream_select/3 will wait indefinitely for a stream to become open. Otherwise the timeout must be of the form SECS:USECS where SECS is an integer gives the number of seconds to wait for a timeout and USECS adds the number of micro-seconds.

This built-in is only defined if the system call select is available in the system.

current_input(-S) [ISO]

Unify S with the current input stream.

current_output(-S) [ISO]

Unify S with the current output stream.

at_end_of_stream [ISO]

Succeed if the current stream has stream position end-of-stream or past-end-of-stream.

at_end_of_stream(+S) [ISO]

Succeed if the stream S has stream position end-of-stream or past-end-of-stream. Note that S must be a readable stream.

set_stream_position(+S, +POS) [ISO]

Given a stream position POS for a stream S, set the current stream position for S to be POS.

stream_property(?Stream,?Prop) [ISO]

Obtain the properties for the open streams. If the first argument is unbound, the procedure will backtrack through all open streams. Otherwise, the first argument must be a stream term (you may use current_stream to obtain a current stream given a file name).

The following properties are recognized:

file_name(P)

An atom giving the file name for the current stream. The file names are user_input, user_output, and user_error for the standard streams.

mode(P)

The mode used to open the file. It may be one of append, read, or write.

input

The stream is readable.

output

The stream is writable.

alias(A)

ISO-Prolog primitive for stream aliases. Yap returns one of the existing aliases for the stream.

position(P)

A term describing the position in the stream.

end_of_stream(E)

Whether the stream is at the end of stream, or it has found the end of stream and is past, or whether it has not yet reached the end of stream.

eof_action(A)

The action to take when trying to read after reaching the end of stream. The action may be one of error, generate an error, eof_code, return character code -1, or reset the stream.

reposition(B)

Whether the stream can be repositioned or not, that is, whether it is seekable.

type(T)

Whether the stream is a text stream or a binary stream.

6.6.2 Handling Streams and Files

tell(+S)

If S is a currently opened stream for output, it becomes the current output stream. If S is an atom it is taken to be a filename. If there is no output stream currently associated with it, then it is opened for output, and the new output stream created becomes the current output stream. If it is not possible to open the file, an error occurs. If there is a single opened output stream currently associated with the file, then it becomes the current output stream; if there are more than one in that condition, one of them is chosen.

Whenever S is a stream not currently opened for output, an error may be reported, depending on the state of the file_errors flag. The predicate just fails, if S is neither a stream nor an atom.

telling(-S)

The current output stream is unified with S.

told

Closes the current output stream, and the user's terminal becomes again the current output stream. It is important to remember to close streams after having finished using them, as the maximum number of simultaneously opened streams is 17.

see(+S)

If S is a currently opened input stream then it is assumed to be the current input stream. If S is an atom it is taken as a filename. If there is no input stream currently associated with it, then it is opened for input, and the new input stream thus created becomes the current input stream. If it is not possible to open the file, an error occurs. If there is a single opened input stream currently associated with the file, it becomes the current input stream; if there are more than one in that condition, then one of them is chosen.

When S is a stream not currently opened for input, an error may be reported, depending on the state of the file_errors flag. If S is neither a stream nor an atom the predicates just fails.

seeing(-S)

The current input stream is unified with S.

seen

Closes the current input stream (see 6.7.).

6.6.3 Handling Input/Output of Terms

read(-T) [ISO]

Reads the next term from the current input stream, and unifies it with T. The term must be followed by a dot ('.') and any blank-character as previously defined. The syntax of the term must match the current declarations for operators (see op). If the end-of-stream is reached, T is unified with the atom end_of_file. Further reads from of the same stream may cause an error failure (see open/3).

read_term(-T,+Options) [ISO]

Reads term T from the current input stream with execution controlled by the following options:

singletons(-Names)

Unify Names with a list of the form Name=Var, where Name is the name of a non-anonymous singleton variable in the original term, and Var is the variable's representation in YAP.

syntax_errors(+Val)

Control action to be taken after syntax errors. See yap_flag/2 for detailed information.

variable_names(-Names)

Unify Names with a list of the form Name=Var, where Name is the name of a non-anonymous variable in the original term, and Var is the variable's representation in YAP.

variables(-Names)

Unify Names with a list of the variables in term T.

char_conversion(+IN,+OUT) [ISO]

While reading terms convert unquoted occurrences of the character IN to the character OUT. Both IN and OUT must be bound to single characters atoms.

Character conversion only works if the flag char_conversion is on. This is default in the iso and sicstus language modes. As an example, character conversion can be used for instance to convert characters from the ISO-LATIN-1 character set to ASCII.

If IN is the same character as OUT, char_conversion/2 will remove this conversion from the table.

current_char_conversion(?IN,?OUT) [ISO]

If IN is unbound give all current character translations. Otherwise, give the translation for IN, if one exists.

write(T) [ISO]

The term T is written to the current output stream according to the operator declarations in force.

display(+T)

Displays term T on the current output stream. All Prolog terms are written in standard parenthesized prefix notation.

write_canonical(+T) [ISO]

Displays term T on the current output stream. Atoms are quoted when necessary, and operators are ignored, that is, the term is written in standard parenthesized prefix notation.

write_term(+T, +Opts) [ISO]

Displays term T on the current output stream, according to the following options:

quoted(+Bool)

If true, quote atoms if this would be necessary for the atom to be recognized as an atom by YAP's parser. The default value is false.

ignore_ops(+Bool)

If true, ignore operator declarations when writing the term. The default value is false.

numbervars(+Bool)

If true, output terms of the form '$VAR'(N), where N is an integer, as a sequence of capital letters. The default value is false.

portrayed(+Bool)

If true, use portray/1 to portray bound terms. The default value is false.

max_depth(+Depth)

If Depth is a positive integer, use Depth as the maximum depth to portray a term. The default is 0, that is, unlimited depth.

writeq(T) [ISO]

Writes the term T, quoting names to make the result acceptable to the predicate 'read' whenever necessary.

print(T)

Prints the term T to the current output stream using write/1 unless T is bound and a call to the user-defined predicate portray/1 succeeds. To do pretty printing of terms the user should define suitable clauses for portray/1 and use print/1.

format(+T,+L)

Print formatted output to the current output stream. The arguments in list L are output according to the string or atom T.

A control sequence is introduced by a w. The following control sequences are available in YAP:

'~~'

Print a single tilde.

'~a'

The next argument must be an atom, that will be printed as if by write.

'~Nc'

The next argument must be an integer, that will be printed as a character code. The number N is the number of times to print the character (default 1).

'~Ne'

'~NE'

'~Nf'

'~Ng'

'~NG'

The next argument must be a floating point number. The float F, the number N and the control code c will be passed to printf as:

printf("%s.Nc", F)

As an example:

?- format("~8e, ~8E, ~8f, ~8g, ~8G~w", [3.14,3.14,3.14,3.14,3.14,3.14]). 3.140000e+00, 3.140000E+00, 3.140000, 3.14, 3.143.14

'~Nd'

The next argument must be an integer, and N is the number of digits after the decimal point. If N is 0 no decimal points will be printed. The default is N = 0.

?- format("~2d, ~d",[15000, 15000]). 150.00, 15000

'~ND'

Identical to '~Nd', except that commas are used to separate groups of three digits.

?- format("~2D, ~D",[150000, 150000]). 1,500.00, 150,000

'~i'

Ignore the next argument in the list of arguments:

?- format('The ~i met the boregrove',[mimsy]). The met the boregrove

'~k'

Print the next argument with write_canonical:

?- format("Good night ~k",a+[1,2]). Good night +(a,[1,2])

'~Nn'

Print N newlines (where N defaults to 1).

'~NN'

Print N newlines if at the beginning of the line (where N defaults to 1).

'~Nr'

The next argument must be an integer, and N is interpreted as a radix, such that 2 <= N <= 36 (the default is 8).

?- format("~2r, 0x~16r, ~r", [150000, 150000, 150000]). 100100100111110000, 0x249f0, 444760

Note that the letters a-z denote digits larger than 9.

'~NR'

Similar to '~NR'. The next argument must be an integer, and N is interpreted as a radix, such that 2 <= N <= 36 (the default is 8).

?- format("~2r, 0x~16r, ~r", [150000, 150000, 150000]). 100100100111110000, 0x249F0, 444760

The only difference is that letters A-Z denote digits larger than 9.

'~p'

Print the next argument with print/1:

?- format("Good night ~p",a+[1,2]). Good night a+[1,2]

'~q'

Print the next argument with writeq/1:

?- format("Good night ~q",'Hello'+[1,2]). Good night 'Hello'+[1,2]

'~Ns'

The next argument must be a list of character codes. The system then outputs their representation as a string, where N is the maximum number of characters for the string (N defaults to the length of the string).

?- format("The ~s are ~4s",["woods","lovely"]). The woods are love

'~w'

Print the next argument with write/1:

?- format("Good night ~w",'Hello'+[1,2]). Good night Hello+[1,2]

The number of arguments, N, may be given as an integer, or it may be given as an extra argument. The next example shows a small procedure to write a variable number of a characters:

write_many_as(N) :- format("~*c",[N,0'a]).

The format/2 built-in also allows for formatted output. One can specify column boundaries and fill the intermediate space by a padding character:

'~N|'

Set a column boundary at position N, where N defaults to the current position.

'~N+'

Set a column boundary at N characters past the current position, where N defaults to 8.

'~Nt'

Set padding for a column, where N is the fill code (default is SPC).

The next example shows how to align columns and padding. We first show left-alignment:

?- format("~n*Hello~16+*~n",[]). *Hello *

Note that we reserve 16 characters for the column.

The following example shows how to do right-alignment:

?- format("*~tHello~16+*~n",[]). * Hello*

The ~t escape sequence forces filling before Hello.

We next show how to do centering:

?- format("*~tHello~t~16+*~n",[]). * Hello *

The two ~t escape sequence force filling both before and after Hello. Space is then evenly divided between the right and the left sides.

format(+S,+T,+L)

Print formatted output to stream S.

6.6.4 Handling Input/Output of Characters

put(+N)

Outputs to the current output stream the character whose ASCII code is N. The character N must be a legal ASCII character code, an expression yielding such a code, or a list in which case only the first element is used.

put_byte(+N) [ISO]

Outputs to the current output stream the character whose code is N. The current output stream must be a binary stream.

put_char(+N) [ISO]

Outputs to the current output stream the character who is used to build the representation of atom A. The current output stream must be a text stream.

put_code(+N) [ISO]

Outputs to the current output stream the character whose ASCII code is N. The current output stream must be a text stream. The character N must be a legal ASCII character code, an expression yielding such a code, or a list in which case only the first element is used.

get(-C)

The next non-blank character from the current input stream is unified with C. Blank characters are the ones whose ASCII codes are not greater than 32. If there are no more non-blank characters in the stream, C is unified with -1. If end_of_stream has already been reached in the previous reading, this call will give an error message.

get0(-C)

The next character from the current input stream is consumed, and then unified with C. There are no restrictions on the possible values of the ASCII code for the character, but the character will be internally converted by YAP.

get_byte(-C) [ISO]

If C is unbound, or is a character code, and the current stream is a binary stream, read the next byte from the current stream and unify its code with C.

get_char(-C) [ISO]

If C is unbound, or is an atom representation of a character, and the current stream is a text stream, read the next character from the current stream and unify its atom representation with C.

get_code(-C) [ISO]

If C is unbound, or is the code for a character, and the current stream is a text stream, read the next character from the current stream and unify its code with C.

peek_byte(-C) [ISO]

If C is unbound, or is a character code, and the current stream is a binary stream, read the next byte from the current stream and unify its code with C, while leaving the current stream position unaltered.

peek_char(-C) [ISO]

If C is unbound, or is an atom representation of a character, and the current stream is a text stream, read the next character from the current stream and unify its atom representation with C, while leaving the current stream position unaltered.

peek_code(-C) [ISO]

If C is unbound, or is the code for a character, and the current stream is a text stream, read the next character from the current stream and unify its code with C, while leaving the current stream position unaltered.

skip(+N)

Skips input characters until the next occurrence of the character with ASCII code N. The argument to this predicate can take the same forms as those for put (see 6.11).

tab(+N)

Outputs N spaces to the current output stream.

nl [ISO]

Outputs a new line to the current output stream.

6.6.5 Input/Output Predicates applied to Streams

read(+S,-T) [ISO]

Reads term T from the stream S instead of from the current input stream.

read_term(+S,-T,+Options) [ISO]

Reads term T from stream S with execution controlled by the same options as read_term/2.

write(+S,T) [ISO]

Writes term T to stream S instead of to the current output stream.

write_canonical(+S,+T) [ISO]

Displays term T on the stream S. Atoms are quoted when necessary, and operators are ignored.

write_term(+S, +T, +Opts) [ISO]

Displays term T on the current output stream, according to the same options used by write_term/3.

writeq(+S,T) [ISO]

As writeq/1, but the output is sent to the stream S.

display(+S,T)

Like display/1, but using stream S to display the term.

print(+S,T)

Prints term T to the stream S instead of to the current output stream.

put(+S,+N)

As put(N), but to stream S.

put_byte(+S,+N) [ISO]

As put_byte(N), but to binary stream S.

put_char(+S,+A) [ISO]

As put_char(A), but to text stream S.

put_code(+S,+N) [ISO]

As put_code(N), but to text stream S.

get(+S,-C)

The same as get(C), but from stream S.

get0(+S,-C)

The same as get0(C), but from stream S.

get_byte(+S,-C) [ISO]

If C is unbound, or is a character code, and the stream S is a binary stream, read the next byte from that stream and unify its code with C.

get_char(+S,-C) [ISO]

If C is unbound, or is an atom representation of a character, and the stream S is a text stream, read the next character from that stream and unify its representation as an atom with C.

get_code(+S,-C) [ISO]

If C is unbound, or is a character code, and the stream S is a text stream, read the next character from that stream and unify its code with C.

peek_byte(+S,-C) [ISO]

If C is unbound, or is a character code, and S is a binary stream, read the next byte from the current stream and unify its code with C, while leaving the current stream position unaltered.

peek_char(+S,-C) [ISO]

If C is unbound, or is an atom representation of a character, and the stream S is a text stream, read the next character from that stream and unify its representation as an atom with C, while leaving the current stream position unaltered.

peek_code(+S,-C) [ISO]

If C is unbound, or is an atom representation of a character, and the stream S is a text stream, read the next character from that stream and unify its representation as an atom with C, while leaving the current stream position unaltered.

skip(+S,-C)

Like skip/1, but using stream S instead of the current input stream.

tab(+S,+N)

The same as tab/1, but using stream S.

nl(+S)

Outputs a new line to stream S.

6.6.6 Compatible C-Prolog predicates for Terminal I/O

ttyput(+N)

As put(N) but always to user_output.

ttyget(-C)

The same as get(C), but from stream user_input.

ttyget0(-C)

The same as get0(C), but from stream user_input.

ttyskip(-C)

Like skip/1, but always using stream user_input. stream.

ttytab(+N)

The same as tab/1, but using stream user_output.

ttynl

Outputs a new line to stream user_output.

6.6.7 Controlling Input/Output

exists(+F)

Checks if file F exists in the current directory.

nofileerrors

Switches off the file_errors flag, so that the predicates see/1, tell/1, open/3 and close/1 just fail, instead of producing an error message and aborting whenever the specified file cannot be opened or closed.

fileerrors

Switches on the file_errors flag so that in certain error conditions I/O predicates will produce an appropriated message and abort.

write_depth(T,L,A)

Unifies T with the value of the maximum depth of a term to be written, L with the maximum length of a list to write, and A with the maximum number of arguments of a compound term to write. The setting will be used by write/1 or write/2. The default value for all arguments is 0, meaning unlimited depth and length.

?- write_depth(3,5,5). yes ?- write(a(b(c(d(e(f(g))))))). a(b(c(....))) yes ?- write([1,2,3,4,5,6,7,8]). [1,2,3,4,5,...] yes ?- write(a(1,2,3,4,5,6,7,8)). a(1,2,3,4,5,...) yes

write_depth(T,L)

Same as write_depth(T,L,_). Unifies T with the value of the maximum depth of a term to be written, and L with the maximum length of a list to write. The setting will be used by write/1 or write/2. The default value for all arguments is 0, meaning unlimited depth and length.

?- write_depth(3,5,5). yes ?- write(a(b(c(d(e(f(g))))))). a(b(c(....))) yes ?- write([1,2,3,4,5,6,7,8]). [1,2,3,4,5,...] yes

always_prompt_user

Force the system to prompt the user even if the user_input stream is not a terminal. This command is useful if you want to obtain interactive control from a pipe or a socket.

6.6.8 Using Sockets From Yap

YAP includes a SICStus Prolog compatible socket interface. This is a low level interface that provides direct access to the major socket system calls. These calls can be used both to open a new connection in the network or connect to a networked server. Socket connections are described as read/write streams, and standard I/O built-ins can be used to write on or read from sockets. The following calls are available:

socket(+DOMAIN,+TYPE,+PROTOCOL,-SOCKET)

Corresponds to the BSD system call socket. Create a socket for domain DOMAIN of type TYPE and protocol PROTOCOL. Both DOMAIN and TYPE should be atoms, whereas PROTOCOL must be an integer. The new socket object is accessible through a descriptor bound to the variable SOCKET.

The current implementation of YAP only accepts two socket domains: 'AF_INET' and 'AF_UNIX'. Socket types depend on the underlying operating system, but at least the following types are supported: 'SOCK_STREAM' and 'SOCK_DGRAM'.

socket(+DOMAIN,-SOCKET)

Call socket/4 with TYPE bound to 'SOCK_STREAM' and PROTOCOL bound to 0.

socket_close(+SOCKET)

Close socket SOCKET. Note that sockets used in socket_connect (that is, client sockets) should not be closed with socket_close, as they will be automatically closed when the corresponding stream is closed with close/1 or close/2.

socket_bind(+SOCKET, ?PORT)

Interface to system call bind, as used for servers: bind socket to a port. Port information depends on the domain:

'AF_UNIX'(+FILENAME)

'AF_FILE'(+FILENAME)

use file name FILENAME for UNIX or local sockets.

'AF_INET'(?HOST,?PORT)

If HOST is bound to an atom, bind to host HOST, otherwise if unbound bind to local host (HOST remains unbound). If port PORT is bound to an integer, try to bind to the corresponding port. If variable PORT is unbound allow operating systems to choose a port number, which is unified with PORT.

socket_connect(+SOCKET, +PORT, -STREAM)

Interface to system call connect, used for clients: connect socket SOCKET to PORT. The connection results in the read/write stream STREAM.

Port information depends on the domain:

'AF_UNIX'(+FILENAME)

'AF_FILE'(+FILENAME)

connect to socket at file FILENAME.

'AF_INET'(+HOST,+PORT)

Connect to socket at host HOST and port PORT.

socket_listen(+SOCKET, +LENGTH)

Interface to system call listen, used for servers to indicate willingness to wait for connections at socket SOCKET. The integer LENGTH gives the queue limit for incoming connections, and should be limited to 5 for portable applications. The socket must be of type SOCK_STREAM or SOCK_SEQPACKET.

socket_accept(+SOCKET, -STREAM)

socket_accept(+SOCKET, -CLIENT, -STREAM)

Interface to system call accept, used for servers to wait for connections at socket SOCKET. The stream descriptor STREAM represents the resulting connection. If the socket belongs to the domain 'AF_INET', CLIENT unifies with an atom containing the IP address for the client in numbers and dots notation.

socket_accept(+SOCKET, -STREAM)

Accept a connection but do not return client information.

socket_buffering(+SOCKET, -MODE, -OLD, +NEW)

Set buffering for SOCKET in read or write MODE. OLD is unified with the previous status, and NEW receives the new status which may be one of unbuf or fullbuf.

socket_select(+SOCKETS, -NEWSTREAMS, +TIMEOUT, +STREAMS, -READSTREAMS)

Interface to system call select, used for servers to wait for connection requests or for data at sockets. The variable SOCKETS is a list of form KEY-SOCKET, where KEY is an user-defined identifier and SOCKET is a socket descriptor. The variable TIMEOUT is either off, indicating execution will wait until something is available, or of the form SEC-USEC, where SEC and USEC give the seconds and microseconds before socket_select/5 returns. The variable SOCKETS is a list of form KEY-STREAM, where KEY is an user-defined identifier and STREAM is a stream descriptor

Execution of socket_select/5 unifies READSTREAMS from STREAMS with readable data, and NEWSTREAMS with a list of the form KEY-STREAM, where KEY was the key for a socket with pending data, and STREAM the stream descriptor resulting from accepting the connection.

current_host(?HOSTNAME)

Unify HOSTNAME with an atom representing the fully qualified hostname for the current host. Also succeeds if HOSTNAME is bound to the unqualified hostname.

hostname_address(?HOSTNAME,?IP_ADDRESS)

HOSTNAME is an host name and IP_ADDRESS its IP address in number and dots notation.

6.7 Using the Clausal Data Base

Predicates in YAP may be dynamic or static. By default, when consulting or reconsulting, predicates are assumed to be static: execution is faster and the code will probably use less space. Static predicates impose some restrictions: in general there can be no addition or removal of clauses for a procedure if it is being used in the current execution.

Dynamic predicates allow programmers to change the Clausal Data Base with the same flexibility as in C-Prolog. With dynamic predicates it is always possible to add or remove clauses during execution and the semantics will be the same as for C-Prolog. But the programmer should be aware of the fact that asserting or retracting are still expensive operations, and therefore he should try to avoid them whenever possible.

dynamic +P

Declares predicate P or list of predicates [P1,...,Pn] as a dynamic predicate. P must be written in form: name/arity.

:- dynamic god/1.

a more convenient form can be used:

:- dynamic son/3, father/2, mother/2.

or, equivalently,

:- dynamic [son/3, father/2, mother/2].

Note:

a predicate is assumed to be dynamic when asserted before being defined.

dynamic_predicate(+P,+Semantics)

Declares predicate P or list of predicates [P1,...,Pn] as a dynamic predicate following either logical or immediate semantics.

Subnodes of Database 6.7.1 Modification of the Data Base  Asserting and Retracting 6.7.2 Looking at the Data Base  Finding out what is in the Data Base 6.7.3 Using Data Base References  Using Data Base References 6.8 Internal Data Base  Yap's Internal Database 6.9 The Blackboard  Storing and Fetching Terms in the BlackBoard

6.7.1 Modification of the Data Base

These predicates can be used either for static or for dynamic predicates:

assert(+C)

Adds clause C to the program. If the predicate is undefined, declare it as dynamic.

Most Prolog systems only allow asserting clauses for dynamic predicates. This is also as specified in the ISO standard. YAP allows asserting clauses for static predicates, as long as the predicate is not in use and the language flag is cprolog. Note that this feature is deprecated, if you want to assert clauses for static procedures you should use assert_static/1.

asserta(+C) [ISO]

Adds clause C to the beginning of the program. If the predicate is undefined, declare it as dynamic.

assertz(+C) [ISO]

Adds clause C to the end of the program. If the predicate is undefined, declare it as dynamic.

Most Prolog systems only allow asserting clauses for dynamic predicates. This is also as specified in the ISO standard. YAP allows asserting clauses for static predicates. The current version of YAP supports this feature, but this feature is deprecated and support may go away in future versions.

abolish(+PredSpec) [ISO]

Deletes the predicate given by PredSpec from the database. If PredSpec is an unbound variable, delete all predicates for the current module. The specification must include the name and arity, and it may include module information. Under iso language mode this built-in will only abolish dynamic procedures. Under other modes it will abolish any procedures.

abolish(+P,+N)

Deletes the predicate with name P and arity N. It will remove both static and dynamic predicates.

assert_static(:C)

Adds clause C to a static procedure. Asserting a static clause for a predicate while choice-points for the predicate are available has undefined results.

asserta_static(:C)

Adds clause C to the beginning of a static procedure.

assertz_static(:C)

Adds clause C to the end of a static procedure. Asserting a static clause for a predicate while choice-points for the predicate are available has undefined results.

The following predicates can be used for dynamic predicates and for static predicates, if source mode was on when they were compiled:

clause(+H,B) [ISO]

A clause whose head matches H is searched for in the program. Its head and body are respectively unified with H and B. If the clause is a unit clause, B is unified with true.

This predicate is applicable to static procedures compiled with source active, and to all dynamic procedures.

clause(+H,B,-R)

The same as clause/2, plus R is unified with the reference to the clause in the database. You can use instance/2 to access the reference's value. Note that you may not use erase/1 on the reference on static procedures.

nth_clause(+H,I,-R)

Find the Ith clause in the predicate defining H, and give a reference to the clause. Alternatively, if the reference R is given the head H is unified with a description of the predicate and I is bound to its position.

The following predicates can only be used for dynamic predicates:

retract(+C) [ISO]

Erases the first clause in the program that matches C. This predicate may also be used for the static predicates that have been compiled when the source mode was on. For more information on source/0 (see section Changing the Compiler's Behavior).

retractall(+G)

Retract all the clauses whose head matches the goal G. Goal G must be a call to a dynamic predicate.

6.7.2 Looking at the Data Base

listing

Lists in the current output stream all the clauses for which source code is available (these include all clauses for dynamic predicates and clauses for static predicates compiled when source mode was on).

listing(+P)

Lists predicate P if its source code is available.

portray_clause(+C)

Write clause C as if written by listing/0.

portray_clause(+S,+C)

Write clause C on stream S as if written by listing/0.

current_atom(A)

Checks whether A is a currently defined atom. It is used to find all currently defined atoms by backtracking.

current_predicate(F) [ISO]

F is the predicate indicator for a currently defined user or library predicate. F is of the form Na/Ar, where the atom Na is the name of the predicate, and Ar its arity.

current_predicate(A,P)

Defines the relation: P is a currently defined predicate whose name is the atom A.

system_predicate(A,P)

Defines the relation: P is a built-in predicate whose name is the atom A.

predicate_property(P,Prop)

For the predicates obeying the specification P unify Prop with a property of P. These properties may be:

built_in

true for built-in predicates,

dynamic

true if the predicate is dynamic

static

true if the predicate is static

meta_predicate(M)

true if the predicate has a meta_predicate declaration M.

multifile

true if the predicate was declared to be multifile

imported_from(Mod)

true if the predicate was imported from module Mod.

exported

true if the predicate is exported in the current module.

public

true if the predicate is public; note that all dynamic predicates are public.

tabled

true if the predicate is tabled; note that only static predicates can be tabled in YAP.

source

true if source for the predicate is available.

number_of_clauses(ClauseCount)

Number of clauses in the predicate definition. Always one if external or built-in.

6.7.3 Using Data Base References

Data Base references are a fast way of accessing terms. The predicates erase/1 and instance/1 also apply to these references and may sometimes be used instead of retract/1 and clause/2.

assert(+C,-R)

The same as assert(C) (see section Modification of the Data Base) but unifies R with the database reference that identifies the new clause, in a one-to-one way. Note that asserta/2 only works for dynamic predicates. If the predicate is undefined, it will automatically be declared dynamic.

asserta(+C,-R)

The same as asserta(C) but unifying R with the database reference that identifies the new clause, in a one-to-one way. Note that asserta/2 only works for dynamic predicates. If the predicate is undefined, it will automatically be declared dynamic.

assertz(+C,-R)

The same as assertz(C) but unifying R with the database reference that identifies the new clause, in a one-to-one way. Note that asserta/2 only works for dynamic predicates. If the predicate is undefined, it will automatically be declared dynamic.

retract(+C,-R)

Erases from the program the clause C whose database reference is R. The predicate must be dynamic.

6.8 Internal Data Base

Some programs need global information for, e.g. counting or collecting data obtained by backtracking. As a rule, to keep this information, the internal data base should be used instead of asserting and retracting clauses (as most novice programmers do), . In YAP (as in some other Prolog systems) the internal data base (i.d.b. for short) is faster, needs less space and provides a better insulation of program and data than using asserted/retracted clauses. The i.d.b. is implemented as a set of terms, accessed by keys that unlikely what happens in (non-Prolog) data bases are not part of the term. Under each key a list of terms is kept. References are provided so that terms can be identified: each term in the i.d.b. has a unique reference (references are also available for clauses of dynamic predicates).

recorda(+K,T,-R)

Makes term T the first record under key K and unifies R with its reference.

recordz(+K,T,-R)

Makes term T the last record under key K and unifies R with its reference.

recorda_at(+R0,T,-R)

Makes term T the record preceding record with reference R0, and unifies R with its reference.

recordz_at(+R0,T,-R)

Makes term T the record following record with reference R0, and unifies R with its reference.

recordaifnot(+K,T,-R)

If a term equal to T up to variable renaming is stored under key K fail. Otherwise, make term T the first record under key K and unify R with its reference.

recordzifnot(+K,T,-R)

If a term equal to T up to variable renaming is stored under key K fail. Otherwise, make term T the first record under key K and unify R with its reference.

recorded(+K,T,R)

Searches in the internal database under the key K, a term that unifies with T and whose reference matches R. This built-in may be used in one of two ways:

• K may be given, in this case the built-in will return all elements of the internal data-base that match the key.
• R may be given, if so returning the key and element that match the reference.

nth_instance(?K,?Index,T,?R)

Fetches the Indexnth entry in the internal database under the key K. Entries are numbered from one. If the key K are the Index are bound, a reference is unified with R. Otherwise, the reference R must be given, and the term the system will find the matching key and index.

erase(+R)

The term referred to by R is erased from the internal database. If reference R does not exist in the database, erase just fails.

erased(+R)

Succeeds if the object whose database reference is R has been erased.

instance(+R,-T)

If R refers to a clause or a recorded term, T is unified with its most general instance. If R refers to an unit clause C, then T is unified with C :- true. When R is not a reference to an existing clause or to a recorded term, this goal fails.

eraseall(+K)

All terms belonging to the key K are erased from the internal database. The predicate always succeeds.

current_key(?A,?K)

Defines the relation: K is a currently defined database key whose name is the atom A. It can be used to generate all the keys for the internal data-base.

key_statistics(+K,-Entries,-Size,-IndexSize)

Returns several statistics for a key K. Currently, it says how many entries we have for that key, Entries, what is the total size spent on entries, Size, and what is the amount of space spent in indices.

key_statistics(+K,-Entries,-TotalSize)

Returns several statistics for a key K. Currently, it says how many entries we have for that key, Entries, what is the total size spent on this key.

get_value(+A,-V)

In YAP, atoms can be associated with constants. If one such association exists for atom A, unify the second argument with the constant. Otherwise, unify V with [].

This predicate is YAP specific.

set_value(+A,+C)

Associate atom A with constant C.

The set_value and get_value built-ins give a fast alternative to the internal data-base. This is a simple form of implementing a global counter.

read_and_increment_counter(Value) :- get_value(counter, Value), Value1 is Value+1, set_value(counter, Value1).

This predicate is YAP specific.

recordzifnot(+K,T,-R)

If a variant of T is stored under key K fail. Otherwise, make term T the last record under key K and unify R with its reference.

This predicate is YAP specific.

recordaifnot(+K,T,-R)

If a variant of T is stored under key K fail. Otherwise, make term T the first record under key K and unify R with its reference.

This predicate is YAP specific.

There is a strong analogy between the i.d.b. and the way dynamic predicates are stored. In fact, the main i.d.b. predicates might be implemented using dynamic predicates:

recorda(X,T,R) :- asserta(idb(X,T),R).
recordz(X,T,R) :- assertz(idb(X,T),R).
recorded(X,T,R) :- clause(idb(X,T),R).

We can take advantage of this, the other way around, as it is quite easy to write a simple Prolog interpreter, using the i.d.b.:

asserta(G) :- recorda(interpreter,G,_).
assertz(G) :- recordz(interpreter,G,_).
retract(G) :- recorded(interpreter,G,R), !, erase(R).
call(V) :- var(V), !, fail.
call((H :- B)) :- !, recorded(interpreter,(H :- B),_), call(B).
call(G) :- recorded(interpreter,G,_).

In YAP, much attention has been given to the implementation of the i.d.b., especially to the problem of accelerating the access to terms kept in a large list under the same key. Besides using the key, YAP uses an internal lookup function, transparent to the user, to find only the terms that might unify. For instance, in a data base containing the terms

b
b(a)
c(d)
e(g)
b(X)
e(h)

stored under the key k/1, when executing the query

:- recorded(k(_),c(_),R).

recorded would proceed directly to the third term, spending almost the time as if a(X) or b(X) was being searched. The lookup function uses the functor of the term, and its first three arguments (when they exist). So, recorded(k(_),e(h),_) would go directly to the last term, while recorded(k(_),e(_),_) would find first the fourth term, and then, after backtracking, the last one.

This mechanism may be useful to implement a sort of hierarchy, where the functors of the terms (and eventually the first arguments) work as secondary keys.

In the YAP's i.d.b. an optimized representation is used for terms without free variables. This results in a faster retrieval of terms and better space usage. Whenever possible, avoid variables in terms in terms stored in the i.d.b.

6.9 The Blackboard

YAP implements a blackboard in the style of the SICStus Prolog blackboard. The blackboard uses the same underlying mechanism as the internal data-base but has several important differences:

• It is module aware, in contrast to the internal data-base.
• Keys can only be atoms or integers, and not compound terms.
• A single term can be stored per key.
• An atomic update operation is provided; this is useful for parallelism.

bb_put(+Key,?Term)

Store term table Term in the blackboard under key Key. If a previous term was stored under key Key it is simply forgotten.

bb_get(+Key,?Term)

Unify Term with a term stored in the blackboard under key Key, or fail silently if no such term exists.

bb_delete(+Key,?Term)

Delete any term stored in the blackboard under key Key and unify it with Term. Fail silently if no such term exists.

bb_update(+Key,?Term,?New)

Atomically unify a term stored in the blackboard under key Key with Term, and if the unification succeeds replace it by New. Fail silently if no such term exists or if unification fails.

6.10 Collecting Solutions to a Goal

When there are several solutions to a goal, if the user wants to collect all the solutions he may be led to use the data base, because backtracking will forget previous solutions.

YAP allows the programmer to choose from several system predicates instead of writing his own routines. findall/3 gives you the fastest, but crudest solution. The other built-in predicates post-process the result of the query in several different ways:

findall(T,+G,-L) [ISO]

Unifies L with a list that contains all the instantiations of the term T satisfying the goal G.

With the following program:

a(2,1). a(1,1). a(2,2).

the answer to the query

findall(X,a(X,Y),L).

would be:

X = _32 Y = _33 L = [2,1,2]; no

findall(T,+G,+L,-L0)

Similar to findall/3, but appends all answers to list L0.

all(T,+G,-L)

Similar to findall(T,G,L) but eliminating repeated elements. Thus, assuming the same clauses as in the above example, the reply to the query

all(X,a(X,Y),L).

would be:

X = _32 Y = _33 L = [2,1]; no

bagof(T,+G,-L) [ISO]

For each set of possible instances of the free variables occurring in G but not in T, generates the list L of the instances of T satisfying G. Again, assuming the same clauses as in the examples above, the reply to the query

bagof(X,a(X,Y),L). would be: X = _32 Y = 1 L = [2,1]; X = _32 Y = 2 L = [2]; no

setof(X,+P,-B) [ISO]

Similar to bagof(T,G,L) but sorting list L and keeping only one copy of each element. Again, assuming the same clauses as in the examples above, the reply to the query

setof(X,a(X,Y),L).

would be:

X = _32 Y = 1 L = [1,2]; X = _32 Y = 2 L = [2]; no