Home

SWI-Prolog 5.0 Reference Manual

1. Table 4 1 System operators op Precedence Type Name Declare Name to be an operator of type Type with precedence Precedence Name can also be a list of names in which case all elements of the list are declared to be identical operators Precedence is an integer between 0 and 1200 Precedence 0 removes the declaration Type is one of xf yf xfx xfy yfx yfy fy or fx The f indicates the position of the functor while x and y indicate the position of the arguments y should be interpreted as on this position a term with precedence lower or equal to the precedence of the functor should occur For x the precedence of the argument must be strictly lower The precedence of a term is 0 unless its principal functor is an operator in which case the precedence is the precedence of this operator A term enclosed in brackets has precedence 0 The predefined operators are shown in table 4 1 Note that all operators can be redefined by the user current_op Precedence Type Name Succeeds when Name is currently defined as an operator of type Type with precedence Prece dence See also op 3 4 25 Character Conversion Although I wouldn t really know for what you would like to use these features they are provided for ISO complicancy char_conversion Charln CharOut Define that term input see read_term 3 maps each character read as CharIn to the character CharOut Char
2. change_address Id Address mutex_lock addressbook retractall address Id _ asserta address Id Address mutex_unlock addressbook mutex_create MutexId Create a mutex if MutexId is an atom a named mutex is created If it is a variable an anony mous mutex reference is returned There is no limit to the number of mutexes that can be created mutex_destroy Mutexld Destroy a mutex After this call MutexId becomes invalid and further references yield an existence error exception mutex_lock Mutexld Lock the mutex Prolog mutexes are recursive mutexes they can be locked multiple times by the same thread Only after unlocking it as many times as it is locked the mutex becomes available for locking by other threads If another thread has locked the mutex the calling thread is suspended until to mutex is unlocked If Mutexld is an atom and there is no current mutex with that name the mutex is created automatically using mutex_create 1 This implies named mutexes need not be declared explicitly Please note that locking and unlocking mutexes should be paired carefully Especially make sure to unlock mutexes even if the protected code fails or raises an exception For most common cases use with mutex 2 wich provides a safer way for handling prolog level mutexes SWI Prolog 5 0 Reference Manual 4 39 MULTI THREADING ALPHA CODE 127 mutex_trylock MutexId As mutex_lock 1 but if the mutex is held by
3. If the prolog flag see current_prolog_flag 2 verbose is silent messages with Kind informational or banner are treated as silent See q This predicate first translates the Term into a list of message lines see print _message_lines 3 for details Next it will call the hook message_hook 3 to allow the user intercepting the message If message_hook 3 fails it will print the message unless Kind is silent The print message 2 predicate and its rules are in the file plhome boot messages pl which may be inspected for more information on the error messages and related error terms See alsomessage_to_string 2 print message _lines Stream Prefix Lines Print a message see print_message 2 that has been translated to a list of message ele ments The elements of this list are Format Args Where Format is an atom and Args is a list of format argument Handed to format 3 flush If this appears as the last element Stream is flushed see lush_out put 1 and no final newline is generated at_same_line If this appears as first element no prefix is printed for the first line and the line position is not forced to O see format 1 N SWI Prolog 5 0 Reference Manual 4 10 HANDLING SIGNALS 71 Format Handed to format 3 as format Stream Format nl A new line is started and if the message is not complete the Prefix is printed too See also print_message 2 and message_hook 3 message_h
4. PL_put_integer a2 50 L_cons_functor t animal2 al a2 FU After this sequence the term references al and a2 may be used for other purposes void PL_cons functor_v term_t h functor1 f term_t a0 Creates a compound term like PL_cons_functor but a0 is an array of term references as returned by PL_new_term_refs The length of this array should match the number of arguments required by the functor void PL cons _list term_t l term_t h term_t 1 Create a list cons cell in from the head and tail The code below creates a list of atoms from achar The list is built tail to head The PL_unify_ functions can be used to build a list head to tail void put_list termt 1 int n char words termt a PL_new_term_ref PL_put_nil 1 while n gt 0 PL_put_atom_chars a words n PL cons list 1 ay 1 Note that can be redefined within a PL_cons_list call as shown here because operationally its old value is consumed before its new value is set SWI Prolog 5 0 Reference Manual 168 CHAPTER 6 FOREIGN LANGUAGE INTERFACE 6 6 5 Unifying data The functions of this sections unify terms with other terms or translated C data structures Except for PL_unify the functions of this section are specific to SWI Prolog They have been introduced to make translation of old code easier but also because they provide for a faster mechanism for returning data to Prolog that require
5. SWI Prolog offers both a C and Prolog interface to deal with software interrupts signals The Prolog mapping is defined in section 4 10 This subsection deals with handling signals from C If a signal is not used by Prolog and the handler does not call Prolog in any way the native signal interface routines may be used Some versions of SWI Prolog notably running on popular Unix platforms handle SIG_SEGV for guarding the Prolog stacks If the application whishes to handle this signal too it should use PL_signal to install its handler after initialisating Prolog SWI Prolog will pass SIG_SEGV to the user code if it detected the signal is not related to a Prolog stack overflow Any handler that wishes to call one of the Prolog interface functions should call PL_signal for its installation void PL_signal sig func This function is equivalent to the BSD Unix signal function regardless of the platform used The signal handler is blocked while the signal routine is active and automatically reactivated after the handler returns After a signal handler is registered using this function the native signal interface redirects the signal to a generic signal handler inside SWI Prolog This generic handler validates the en vironment creates a suitable environment for calling the interface functions described in this chapter and finally calls the registered user handler 6 6 13 Errors and warnings PL warning prints a standard Pr
6. This may be replaced with your own main C program The interface function PL_initialise must be called before any of the other SWI Prolog foreign language functions described in this chap ter PL_initialise interprets all the command line arguments except for the t toplevel flag that is interpreted by PL_toplevel int PL _initialise int argc char argv Initialises the SWI Prolog heap and stacks restores the boot QLF file loads the system and personal initialisation files runs the at_initialization 1 hooks and finally runs the g goal hook Special consideration is required for argv 0 On Unix this argument passes the part of the commandline that is used to locate the executable Prolog uses this to find the file holding the running executable The Windows version uses this to find a module of the running executable If the specified module cannot be found it tries the module 1ibp1 d11 containing the Prolog runtime kernel In all these cases the resulting file is used for two purposes e See whether a Prolog saved state is appended to the file If this is the case this state will be loaded instead of the default boot pra file from the SWI Prolog home directory See also qsave_program 1 2 and section 6 7 e Find the Prolog home directory This process is described in detail in section 6 8 PL_initialise returns 1 if all initialisation succeeded and 0 otherwise In most cases argc and argv will be passed from th
7. brace_term_position From To Arg Term of the form as used in DCG rules Arg describes the argument list_position From To Elms Tail A list Elms describes the positions of the elements If the list specifies the tail as TailTerm Tail is unified with the term position of the tail otherwise with the atom none term_position From To FFrom FTo SubPos Used for a compound term not matching one of the above FFrom and FTo describe the position of the functor SubPos is a list each element of which describes the term position of the corresponding subterm SWI Prolog 5 0 Reference Manual 94 CHAPTER 4 BUILT IN PREDICATES read_term Stream Term Options Read term with options from Stream See read_term 2 read _history Show Help Special Prompt Term Bindings Similar to read_term 2 using the option variable_names but allows for history substi tutions read_history 6 is used by the top level to read the user s actions Show is the com mand the user should type to show the saved events Help is the command to get an overview of the capabilities Special is a list of commands that are not saved in the history Prompt is the first prompt given Continuation prompts for more lines are determined by prompt 2 A Sw in the prompt is substituted by the event number See section 2 7 for available substitutions SWI Prolog calls read_history 6 as follows read_history h h trace Sw Go
8. current_prolog_flag home Home user file_search_path foreign swi ArchLib current_prolog_flag arch Arch atom_concat lib Arch ArchLib user file_search_path foreign swi lib The file_search_path 2 expansion is used by all loading predicates as well as by absolute_file_name 2 3 The prolog flag verbose_file_search can be set to true to help debugging Prolog s search for files expand file search path Spec Path Unifies Path with all possible expansions of the file name specification Spec See also absolute file name 3 prolog file type Extension Type This dynamic multifile predicate defined in module user determines the extensions considered by file search path 2 Extension is the filename extension without the leading dot Type denotes the type as used by the file_type Type option of file_search_path 2 Here is the initial definition of prolog_file type 2 user prolog_file_type pl prolog user prolog_file_type Ext prolog current_prolog_flag associate Ext Ext pl user prolog_file_type qlf alf user prolog_file_type Ext executable current_prolog_flag shared_object_extension Ext Users may wish to change the extension used for Prolog source files to avoid conflicts for example with perl as well as to be compatible with some specific implementation The preferred alternative extension is pro source file File Suc
9. is_absolute_file_name File True if File specifies and absolute path name On Unix systems this implies the path starts with a Y For Microsoft based systems this implies the path starts with letter This predicate is intended to provide platform independent checking for absolute paths See also absolute_file_name 2 and prolog_to_os_filename 2 file name_extension Base Extension Name This predicate is used to add remove or test filename extensions The main reason for its introduction is to deal with different filename properties in a portable manner If the file system is case insensitive testing for an extension will be done case insensitive too Extension may be specified with or without a leading dot If an Extension is generated it will not have a leading dot expand file name WildCard List Unify List with a sorted list of files or directories matching WildCard The normal Unix wild card constructs and are recognised The interpretation of Y F Silent operation was the default up to version 3 2 6 SWI Prolog 5 0 Reference Manual 122 CHAPTER 4 BUILT IN PREDICATES is interpreted slightly different from the C shell csh 1 The comma separated argument can be arbitrary patterns including Y patterns The empty pattern is legal as well p1 XP matches either p1 or the empty string If the pattern does contains wildcard characters
10. 1 2 compiling Succeeds if the system is compiling source files with the c option into an intermediate code file Can be used to perform code optimisations in expand_t erm 2 under this condition preprocessor Old New Read the input file via a Unix process that acts as preprocessor A preprocessor is specified as an atom The first occurrence of the string Sf is replaced by the name of the file to be loaded The resulting atom is called as a Unix command and the standard output of this command is loaded To use the Unix C preprocessor one should define preprocessor Old lib cpp C P f consult Old none 4 3 1 Quick load files SWI Prolog supports compilation of individual or multiple Prolog source files into Quick Load Files A Quick Load Files q1f file stores the contents of the file in a precompiled format These files load considerably faster than source files and are normally more compact They are machine independent and may thus be loaded on any implementation of SWI Prolog Note however SWI Prolog 5 0 Reference Manual 60 CHAPTER 4 BUILT IN PREDICATES that clauses are stored as virtual machine instructions Changes to the compiler will generally make old compiled files unusable Quick Load Files are created using qcompile 1 They are loaded using consult 1 or one of the other file loading predicates described in section 4 3 If consult is given the explicit p1 file it
11. PL_INTEGER A Prolog integer PL_FLOAT A Prolog floating point number PL_TERM A compound term Note that a list is a compound term 2 The functions PL _is type are an alternative to PL_term_type The test PL_is variable term is equivalent to PL term type term PL VARIABLE but the first is considerably faster On the other hand using a switch over PL_term_type is faster and more readable then using an if then else using the functions below All these functions return either TRUE or FALSE int PL_is_variable term_t Returns non zero if term is a variable int PL_is_atom term_t Returns non zero if term is an atom int PL_is_string term_t Returns non zero if term is a string int PL_is_integer term_t Returns non zero if term is an integer SWI Prolog 5 0 Reference Manual 6 6 THE FOREIGN INCLUDE FILE 161 in in in in in in t PL_is_float term_t Returns non zero if term is a float t PL_is_compound term_t Returns non zero if term is a compound term t PL_is_functor term_t functor_t Returns non zero if term is compound and its functor is functor This test is equivalent to PL_get_functor followed by testing the functor but easier to write and faster t PL_is_list term_t Returns non zero if term is a compound term with functor 2 or the atom t PL_is_atomic term_t Returns non zero if term is atomic not variable or compound t PL_is_number term_t
12. The following example build a goal term from a string and calls it int call_chars const char goal fid t fid PL_open_foreign_frame SWI Prolog 5 0 Reference Manual 172 CHAPTER 6 FOREIGN LANGUAGE INTERFACE term_t g PL_new_term_ref BOOL rval if PL_string_to_term goal g rval PL_call goal NULL else rval FALSE PL_discard_foreign_frame fid return rval call_chars consult load char PL_quote int chr const char string Return a quoted version of string If chris X the result is a quoted atom If chris the result is a string The result string is stored in the same ring of buffers as described with the BUF_RING argument of PL_get_chars In the current implementation the string is surrounded by chr and any occurence of chr is doubled In the future the behaviour will depend on the character_escape prolog flag See current_prolog_flag 2 6 6 6 Calling Prolog from C The Prolog engine can be called from C There are two interfaces for this For the first a term is created that could be used as an argument to call 1 and next PL_call is used to call Prolog This system is simple but does not allow to inspect the different answers to a non deterministic goal and is relatively slow as the runtime system needs to find the predicate The other interface is based on PL_open_query PL_next_solution and PL_cut_query or PL_close_query This mechanism is m
13. atom_to_term Atom Term Bindings Use Atom as input to read_term 2 using the option variable_names and return the read term in Term and the variable bindings in Bindings Bindings is a list of Name Var couples thus providing access to the actual variable names See also read_term 2 If Atom has no valid syntax a syntax_error exception is raised atom_concat Atoml Atom2 Atom3 Atom3 forms the concatenation of Atom and Atom2 At least two of the arguments must be instantiated to atoms integers or floating point numbers For ISO compliance the instantiation pattern is allowed too non deterministically splitting the 3 th argument into two parts as append 3 does for lists See also string_concat 3 concat_atom List Atom List is a list of atoms integers or floating point numbers Succeeds if Atom can be uni fied with the concatenated elements of List If List has exactly 2 elements it is equivalent to atom_concat 3 allowing for variables in the list concat_atom List Separator Atom Creates an atom just like concat_atom 2 but inserts Separator between each pair of atoms For example SWI Prolog 5 0 Reference Manual 98 CHAPTER 4 BUILT IN PREDICATES concat_atom gnu gnat A A gnu gnat This predicate can also be used to split atoms by instantiating Separator and Atom concat_atom L gnu gnat L gnu gnat atom length Atom Length Succeeds if Atomis a
14. ignore _ SWI Prolog 5 0 Reference Manual 4 8 META CALL PREDICATES 67 call_with_depth_limit Goal Limit Result If Goal can be proven without recursion deeper than Limit levels call with depth limit 3 succeeds binding Result to the deepest recursion level used during the proof Otherwise Result is unified with depth_limit_exceeded if the limit was exceeded during the proof or the entire predicate fails if Goal fails without exceeding Limit The depth limit is guarded by the internal machinery This may differ from the depth computed based on a theoretical model For example t rue 0 is translated into an inlined virtual machine instruction Also repeat 0 is not implemented as below but as a non deterministic foreign predicate repeat repeat repeat As a result call with depth 1imit 3 may still loop inifitly on programs that should theoretically finish in finite time This problem can be cured by using Prolog equivalents to such built in predicates This predicate may be used for theorem provers to realise techniques like iterrative deepening It was implemented after discussion with Steve Moyle smoyle ermine ox ac uk call_cleanup Goal Catcher Cleanup Calls Goal If Goal is completely finished either by deterministic success failure its choice point being cut or raising an exception and Catcher unifies to the termination code see below Cleanup is called Success or failure of Cleanup is igno
15. prologFunction ArithFunction f term_t av Number r int arity f gt proc gt definition gt functor gt arity fid_t fid PL_open_foreign_frame SWI Prolog 5 0 Reference Manual 6 6 THE FOREIGN INCLUDE FILE 177 aid_t qid int rval aid PL_open query NULL PL_Q NORMAL f gt proc av if PL_next_solution qid rval valueExpression avtarity 1 r PL_close_query qid PL_discard_foreign_frame fid else ab Sgt term_t except if except PL_exception qid rval PL_throw except pass exception else char name stringAtom f gt proc gt definition gt functor gt name generat xception rval PL_error name arity 1 NULL ERR_FAILED f gt proc PL_cut_query qid donot destroy data L_close_foreign_frame fid same FU return rval int PL raise exception term_t exception Generate an exception as throw 1 and return FALSE Below is an example returning an exception from foreign predicate foreign_t pl_hello term_t to char s if PL_get_atom_chars to amp s Sprintf Hello Ss n 8s PL_succeed else term_t except PL_new_term_ref PL_unify_term except PL_FUNCTOR_CHARS type_error PL_CHARS atom SWI Prolog 5 0 Reference Manual 178 CHAPTER 6 FOREIGN LANGUAGE INTERFACE PL_TERM to return PL_raise_exception except int PL_throw term_t exception Similar to
16. tray true max_depth 10 This is the default r Retry Undo all actions except for database and i o actions back to the call port of the current goal and resume execution at the call port s Skip Continue execution stop at the next port of this goal thus skipping all calls to children of this goal u Up Continue execution stop at the next port of the parent goal thus skipping this goal and all calls to children of this goal This option is useful to stop tracing a failure driven loop w Write Set the prolog flag debugger_print_options to quoted true bypassing portray 1 etc The ideal 4 port model as described in many Prolog books Clocksin amp Melish 1987 is not vis ible in many Prolog implementations because code optimisation removes part of the choice and SWI Prolog 5 0 Reference Manual 28 CHAPTER 2 OVERVIEW exit points Backtrack points are not shown if either the goal succeeded deterministically or its alter natives were removed using the cut When running in debug mode debug 0 choice points are only destroyed when removed by the cut In debug mode tail recursion optimisation is switched off Reference information to all predicates available for manipulating the debugger is in section 4 42 2 10 Compilation 2 10 1 During program development During program development programs are normally loaded using consult 1 or the list abbre viation It is common practice to organise a
17. 1 if the calling thread has no Prolog engine This function is also provided in the single threaded version of SWI Prolog where it returns 2 int PL_thread_attach_engine PL_thread_attr_t attr Creates a new Prolog engine in the calling thread If the calling thread already has an engine the reference count of the engine is incremented The attr argument can be NULL to create a thread with default attributes Otherwise it is a pointer to a structure with the definition below For any field with value 0 the default is used typedef struct unsigned long local_size Stack sizes K bytes unsigned long global_size unsigned long trail_size This interface differs in two ways from Quintus The calling predicates simp y signal failure if an exception was raised and a term referenced is returned rather passed and filled with the error term Exceptions can only be handled using the PL_next_solution interface as a handle to the query is required SWI Prolog 5 0 Reference Manual 6 6 THE FOREIGN INCLUDE FILE 179 unsigned long argument_size char alias alias name PL_thread_attr_t The structure may be destroyed after PL_thread_attach_engine has returned If an error occurs 1 is returned If this Prolog is not compiled for multi threading 2 is returned int PL_thread_destroy_engine Destroy the Prolog engine in the calling thread Only takes ef fect if PL_thread_destroy_engine is cal
18. 2 2 2 and 0 can be used in grammar rules Grammar rule sets are called using the builtin predicates phrase 2 and phrase 3 phrase RuleSet InputList Equivalent to phrase RuleSet InputList SWI Prolog 5 0 Reference Manual 4 13 DATABASE 75 phrase RuleSet InputList Rest Activate the rule set with given name InputList is the list of tokens to parse Rest is unified with the remaining tokens if the sentence is parsed correctly The example below calls the rule set integer defined above phrase integer X 42 times Rest X 42 Rest 32 116 105 109 101 115 4 13 Database SWI Prolog offers three different database mechanisms The first one is the common assert retract mechanism for manipulating the clause database As facts and clauses asserted using assert 1 or one of its derivatives become part of the program these predicates compile the term given to them retract 1 and retractal1 1 have to unify a term and therefore have to decompile the pro gram For these reasons the assert retract mechanism is expensive On the other hand once compiled queries to the database are faster than querying the recorded database discussed below See also dynamic 1 The second way of storing arbitrary terms in the database is using the recorded database In this database terms are associated with a key A key can be an atom integer or term In the last case only the functor and arity d
19. 2 is available from the library backcomp pl SWI Prolog 5 0 Reference Manual 4 21 ANALYSING AND CONSTRUCTING ATOMS 97 number_codes Number CodeList As number_chars 2 but converts to a list of character codes normally ASCII values rather than one character atoms In the mode both predicates behave identically to improve handling of non ISO source name AtomOrInt String String is a list of ASCII values describing Atom Each of the arguments may be a vari able but not both When String is bound to an ASCII value list describing an integer and Atom is a variable Atom will be unified with the integer value described by String e g name N 300 400 is N 100 succeeds int_to_atom nt Base Atom Convert Int to an ASCII representation using base Base and unify the result with Atom If Base 10 the base will be prepended to Atom Base O will try to interpret Int as an ASCII value and return 0 c Otherwise 2 lt Base lt 36 Some examples are given below int_to_atom 45 2 A A gt 2 101101 intto_atom 97 0 A A 0O a int_to_atom 56 10 A A 56 int_to_atom nt Atom Equivalent to int_to_atom Int 10 Atom term_to_atom Term Atom Succeeds if Atom describes a term that unifies with Term When Atom is instantiated Atom is converted and then unified with Term If Atom has no valid syntax a syntax_error exception is raised Otherwise Term is written on Atom using write 1
20. A 3 LIBRARY NETSCAPE ACTIVATING YOUR WEB BROWSER 209 read_file_to_terms Spec Terms Options Read a file to a list of character codes Spec is a file specification for absolute file _name 3 Terms is the resulting list of Prolog terms Options is a list of options for absolute_file_name 3 and open 4 In addition the option tail Zail is defined forming a difference list A 3 library net scape Activating your Web browser This library deals with the very system dependent task of opening a web browser See also li brary ur 1 wWww_open_url URL Open URL in an external web browser The reason to place this in the library is to centralise the maintenance on this highly platform and browser specific task It distinguishes between the following cases e MS Windows If it detects MS Windows it uses win_shel1 2 to open the URL The behaviour and browser started depends on the Window and Windows shell configuration but in general it should be the behaviour expected by the user e Other platforms On other platforms it assumes the browser is netscape It first tries to tell a running netscape to open the page and only after this fails it starts a new browser A 4 library registry Manipulating the Windows registry The library regi st ry is only available on the MS Windows version of SWI Prolog It loads the foreign extension plregtry dl1l providing the predicates described below This library only makes the most common operatio
21. Put a Prolog integer in the term reference void PL_put_pointer term_t t void ptr Put a Prolog integer in the term reference Provided ptr is in the malloc area PL_get_pointer will get the pointer back void PL put float term_t t double f Put a floating point value in the term reference void PL put functor term_t t functor_t functor Create a new compound term from functor and bind t to this term All arguments of the term will be variables To create a term with instantiated arguments either instantiate the arguments using the PL_unify _ functions or use PL_cons_functor void PL_put_list term_t 1 Same as PL_put_functor l PL_new_functor PL_new_atom 2 void PL put nil term_t Same as PL_put_atom_chars SWI Prolog 5 0 Reference Manual 6 6 THE FOREIGN INCLUDE FILE 167 void PL_put_term term_t tl term_t 12 Make t point to the same term as 2 void PL_cons_functor term_t h functor_1 f Create a term whose arguments are filled from variable argument list holding the same number of term_t objects as the arity of the functor To create the term animal gnu 50 use term t al PL_new_term_ref term_t a2 PL_new_term_ref term t t PL_new_term_ref functor_t animal2 animal2 is a constant that may be bound to a global variable and re used animal2 PL_new_functor PL_new_atom animal 2 PL_put_atom_chars al gnu
22. Returns non zero if term is an integer or float Reading data from a term The functions PL_get_ read information from a Prolog term Most of them take two arguments The first is the input term and the second is a pointer to the output value or a term reference int PL_get_atom term_t t atom_t a If t is an atom store the unique atom identifier over a See also PL_atom_chars and PL_new_atom If there is no need to access the data characters of an atom it is ad vised to manipulate atoms using their handle As the atom is referenced by f it will live at least as long as does If longer live time is required the atom should be locked using PL_register_atom int PL_get_atom_chars term_t t char s If is an atom store a pointer to a 0 terminated C string in s It is explicitly not allowed to modify the contents of this string Some built in atoms may have the string allocated in read only memory so temporary manipulation can cause an error int PL_get string_chars term_t t char s int len If is a string object store a pointer to a 0 terminated C string in s and the length of the string in len Note that this pointer is invalidated by backtracking garbage collection and stack shifts so generally the only save operations are to pass it immediately to a C function that doesn t involve Prolog int PL_get_chars term_t t char s unsigned flags Convert the argument term to a 0 terminate
23. The type PL_dispatch_hook_t is defined as typedef int PL_dispatch_hook_t void void PL_abort_hook PL_abort_hook_t Install a hook when abort 0 is executed SWI Prolog abort 0 is implemented using C setimpO longjmp construct The hooks are executed in the reverse order of their registra tion after the longjmp took place and before the Prolog toplevel is reinvoked The type PL_abort_hook_t is defined as typedef void PL_abort_hook_t void int PL_abort_unhook PL_abort_hook_t Remove a hook installed with PL_abort_hook Returns FALSE if no such hook is found TRUE otherwise void PL on halt void f int void void closure Register the function f to be called if SWI Prolog is halted The function is called with two arguments the exit code of the process 0 if this cannot be determined on your operating system and the closure argument passed to the PL_on_halt call See also at_halt 1 PL_agc_hook_t PL_age_hook PL_agc_hook_t new Register a hook with the atom garbage collector see garbage_collect_atoms O0 that is called on any atom that is reclaimed The old hook is returned If no hook is currently defined NULL is returned The argument of the called hook is the atom that is to be garbage collected The return value is an int If the return value is zero the atom is not reclaimed The hook may invoke any Prolog predicate The example below defines a foreign library for printing the garbage collected at
24. c 1990 2002 University of Amsterdam SWI Prolog comes with ABSOLUTELY NO WARRANTY This is free software and you are welcome to redistribute it under certain conditions Please visit http www swi prolog org for details For help use help Topic or apropos Word After starting Prolog one normally loads a program into it using consult 1 which for historical reasons may be abbreviated by putting the name of the program file between square brackets The following goal loads the file Likes p1 containing clauses for the predicates likes 2 likes o likes compiled 0 00 sec 596 bytes Yes pe After this point Unix and Windows users unite so if you are using Unix please continue at sec tion 2 1 2 Starting SWI Prolog on Windows After SWI Prolog has been installed on a Windows system the following important new things are available to the user SWI Prolog 5 0 Reference Manual 18 CHAPTER 2 OVERVIEW e A folder called directory in the remainder of this document called p1 containing the executa bles libraries etc of the system No files are installed outside this directory e A program plwin exe providing a window for interaction with Prolog The program plcon exe is a version of SWI Prolog that runs in a DOS box e The file extension pl is associated with the program plwin exe Opening a p1 file will cause plwin exe to start change directory to the directory in which the
25. caller of findall 3 assert findall solution Var fail store _ _ A A collect Bag E Figure 5 1 finda11 3 using modules SWI Prolog 5 0 Reference Manual 148 CHAPTER 5 USING MODULES 5 9 1 Emulating meta_predicate 1 The Quintus meta_predicate 1 directive can in many cases be replaced by the transparent dec laration Below is the definition of meta predicate 1 as available from library quintus op 1150 fx meta_predicate meta_predicate Head More meta_predicatel Head meta_predicate More meta_predicate Head meta_predicatel Head meta_predicatel Head Head Name Arguments member Arg Arguments module_expansion_argument Arg functor Head Name Arity module_transparent Name Arity o meta_predicatel _ just a mode declaration module_expansion_argument module_expansion_argument N integer N The discussion above about the problems with the transparent mechanism show the two cases in which this simple transformation does not work SWI Prolog 5 0 Reference Manual Foreign Language Interface SWI Prolog offers a powerful interface to C Kernighan amp Ritchie 1978 The main design objectives of the foreign language interface are flexibility and performance A foreign predicate is a C function that has the same number of arguments as the predicate represented C functions are provided to analyse the passed
26. checkselect library 15 clause 2 81 clause 3 76 77 81 201 clause 2 3 34 206 clause_property 2 81 clause_property 2 58 213 clib package 190 close 1 84 close 2 85 close_dde_conversation 1 136 close_shared_object 1 151 code_type 2 100 code_type 2 98 commandline arguments 21 compare 3 64 110 179 compiling O 59 completion TAB 46 compound 1 62 concat_atom 2 97 concat_atom 3 97 concat_atom 2 97 consult 1 17 18 28 51 54 56 60 78 92 131 context_module 1 145 context_module 1 145 173 convert_time 2 119 convert_time 8 119 convert_time 2 119 convert_time 8 119 convert_time 2 8 120 copy_stream_data 2 90 SWI Prolog 5 0 Reference Manual 244 INDEX copy_stream_data 3 90 copy _term 2 95 copy_term 2 95 cos 1 106 cputime O 107 ctype library 98 current_arithmetic_function 1 108 current_atom 1 79 current _char_conversion 2 103 current flag 1 79 current_foreign_library 2 151 current format _predicate 2 116 current _functor 2 79 current_input 1 87 current_key 1 79 current_module 1 145 current_module 2 145 current_mutex 3 127 current_op 3 102 current_output 1 87 current_predicate 1 79 current_predicate 2 79 current_prolog flag 2 31 current_signal 3 73 current_stream 3 15 85 122 current_thread 2 124 current_atom 1 79 current_char_conversion 2 103 current_input 1 58 current_predicate 1 79 current_predicate 2 79 134 current_prolog
27. command line arguments version as well as runtime flags to control the runtime behaviour of certain predicates to achieve compatibility with other Prolog environments current prolog flag Key Value The predicate current _prolog flag 2 defines an interface to installation features op tions compiled in version home etc With both arguments unbound it will generate all defined prolog flags With the Key instantiated it unify the value of the prolog flag Features come in three types boolean prolog flags prolog flags with an atom value and prolog flags with an integer value A boolean prolog flag is true iff the prolog flag is present and the Value is the atom true Currently defined keys arch atom Identifier for the hardware and operating system SWI Prolog is running on Used to de termine the startup file as well as to select foreign files for the right architecture See also section 6 4 version integer The version identifier is an integer with value 10000 x Major 100 x Minor Patch Note that in releases up to 2 7 10 this prolog flag yielded an atom holding the three numbers separated by dots The current representation is much easier for implementing version conditional statements home atom SWI Prolog s notion of the home directory SWI Prolog uses it s home directory to find its startup file as home startup startup arch and to find its library as home library SWI Prolog 5 0 Reference Ma
28. 122 seek 4 85 86 seen O 83 select 3 15 108 set_feature 2 15 set_input 1 86 set_output 1 86 set_prolog_flag 2 36 set_stream 2 86 set_stream_position 2 86 SWI Prolog 5 0 Reference Manual INDEX 251 set_tty 2 117 set_feature 2 15 set_input 1 86 set_prolog_flag 2 15 23 31 103 set_stream 2 83 setarg 3 94 95 setenv 2 61 118 setof 3 111 225 sformat 2 115 sformat 3 90 115 shell O 117 118 shell 1 44 61 117 118 shell 2 117 shell 0 2 118 shell 1 2 117 shell_register_dde 6 210 shell_register_file_type 4 210 shell_register_prolog 1 210 shell register file type 4 210 shlib library 227 230 234 show profile 1 133 show_profile 1 133 sign 1 105 silent 70 sin 1 104 106 size file 2 120 skip 1 90 skip 2 90 sleep 1 138 socket library 87 sort 2 109 111 source_file 1 57 source file 2 58 source _location 2 58 source file 2 60 80 source_file 1 2 145 source _location 2 58 spy 1 25 35 37 51 52 130 216 227 sqrt 1 106 stack memory management 41 stack_parameter 4 135 startup file 18 statistics 0 133 statistics 2 107 131 132 stream_property 2 85 stream _position 3 83 86 93 stream_property 2 86 string 1 62 115 string_concat 3 101 string length 2 101 string_to_atom 2 101 string to_list 2 101 string_concat 3 97 style_check 1 131 style_check 1 41 78 220 sub_atom 5 98 sub_string 5 101 sub_atom 5 101 sublist 3 112 su
29. 236 use_module 1 141 use_module 2 141 use_module 1 44 use_module 2 37 use_module 1 2 28 51 54 56 140 142 145 218 user library 232 user profile file 18 utf 8 53 var 1 12 62 159 verbose 20 visible 1 131 volatile 1 201 wait_for_input 3 87 wait_for_input 3 87 wildcard_match 2 137 win_exec 2 117 win_insert_menu 2 119 win_insert_menu_item 4 119 win_registry_get_value 3 117 win_shell 2 117 win_exec 2 117 win_insert_menu 2 119 win_shell 2 117 209 Window interface 10 windows 36 with_mutex 2 127 with_mutex 2 126 178 working _directory 2 122 working directory 2 118 122 write 1 33 91 92 97 98 113 115 162 164 write 2 91 write_canonical 1 91 write_canonical 2 91 write_term 2 90 write_term 3 91 write_canonical 1 21 13 write_term 2 25 33 63 90 91 113 115 write_term 3 36 write_term 2 3 13 writef 1 112 writef 2 16 40 90 112 113 writef 1 2 112 writeln 1 112 writeq 1 92 113 114 writeq 2 92 www_form_encode 2 212 www_open_url 1 209 X11 10 xor 2 106 SWI Prolog 5 0 Reference Manual INDEX 253 XPCE 10 SWI Prolog 5 0 Reference Manual
30. 5 0 Reference Manual E 4 OPERATORS 239 E 4 Operators XOr Ww Ne 200 200 300 400 400 400 400 400 400 500 500 500 500 500 500 500 500 600 700 700 700 700 700 700 700 700 700 700 700 700 700 700 700 700 700 700 900 900 1000 1050 1050 1100 1100 fx rfy rfy fx yfr yfr yfr yfr yfr yfr fx fx fx fx yfr yfr yfr yfr rfy fx fx fx fx fx fx fx fx fx fx fx fx fx fx fx fx fx fx fy fy rfy rfy rfy rfy rfy Bind toplevel variable Predicate Arithmetic function Arithmetic function Arithmetic function Arithmetic function Arithmetic function Arithmetic function Arithmetic function Arithmetic function Arithmetic function Arithmetic function XPCE obtainer Arithmetic function Arithmetic function Arithmetic function Arithmetic function Arithmetic function module term separator Predicate Predicate Predicate Predicate Predicate Predicate Predicate Predicate Predicate Predicate Predicate Predicate Predicate Predicate Predicate Predicate Predicate Predicate Predicate Predicate Predicate Predicate Predicate Predicate Predicate SWI Prolog 5 0 Reference Manual 240 APPENDIX E SUMMARY discontiguous dynamic module_transparent multifile volatile initialization 1150 1150 1150 1150 1150 1150 1200 1200 1200 1200 fx fx fx fx fx fx fx fx fx fx Predicate Predicate Predicate Predicate
31. 8 5 no limits are imposed on the addresses returned by malloc and friends On some machines the runtime stacks described above are allocated using sparse allocation Virtual space up to the limit is claimed at startup and committed and released while the area grows and shrinks On Win32 platform this is realised using VirtualAlloc and friends On Unix systems this is realised using mmap 2 16 2 Other Limits Clauses The only limit on clauses is their arity the number of arguments to the head which is limited to 1024 Raising this limit is easy and relatively cheap removing it is harder Atoms and Strings SWI Prolog has no limits on the sizes of atoms and strings read 1 and its derivatives however normally limit the number of newlines in an atom or string to 5 to improve error detection and recovery This can be switched off with style_check 1 The number of atoms is limited to 16777216 16M on 32 bit machines On 64 bit machines this is virtually unlimited See also section 6 6 2 Address space SWI Prolog data is packed in a 32 bit word which contains both type and value information The size of the various memory areas is limited to 128 Mb for each of the areas except for the program heap which is not limited Integers Integers are 32 bit 64 on 64 bit machines to the user but integers up to the value of the max_tagged_integer prolog flag are represented more efficiently Floats Floating point numbers are represent
32. Atom2 Succeeds if Atom matches Atom2 in Do What I Mean sense Both Atom and Atom2 may also be integers or floats The two atoms match if e They are identical e They differ by one character spy spu e One character is inserted deleted debug deug e Two characters are transposed trace tarce e Sub words are glued differently existsfile existsFile exists_file e Two adjacent sub words are transposed existsFile fileExists dwim_match Atom1 Atom2 Difference Equivalent to dwim_match 2 but unifies Difference with an atom identifying the the differ ence between Atom and Atom2 The return values are in the same order as above equal mismatched_char inserted_char transposed_char separated and trans posed_word wildcard_match Pattern String Succeeds if String matches the wildcard pattern Pattern Pattern is very similar the the Unix csh pattern matcher The patterns are given below Matches one arbitrary character Ed Matches any number of arbitrary characters Matches one of the characters specified between the brackets char char2 indicates a range Matches any of the patterns of the comma separated list between the braces SWI Prolog 5 0 Reference Manual 138 CHAPTER 4 BUILT IN PREDICATES Example wildcard_match a z pro pl a_hello pl Yes gensym Base Unique Generate a unique atom from base Base and unify it with Unique
33. BUILT IN PREDICATES fail Label Calling fail 1 makes the innermost block which Label unifies fail immediately Implemented as fail Label Label fail Label Cut all choice points created since the entry of the innermost block which Label unifies 4 12 DCG Grammar rules Grammar rules form a comfortable interface to difference lists They are designed both to support writing parsers that build a parse tree from a list as for generating a flat list from a term Unfortunately Definite Clause Grammar DCG handling is not part of the Prolog standard Most Prolog engines implement DCG but the details differ slightly Grammar rules look like ordinary clauses using gt 2 for separating the head and body rather then 2 Expanding grammar rules is done by expand_term 2 which adds two additional argument to each term for representing the difference list We will illustrate the behaviour by defining a rule set for parsing an integer integer I gt digit DO digits D number_chars I DOI D Yes digits D T gt digit D digits T digits gt ie digit D gt Dl code_type D digit The body of a grammar rule can contain three types of terms A compound term interpreted as a reference to a grammar rule Code between is interpreted as a reference to ordinary Prolog code and finally a list is interpreted as a sequence of literals The Prolog control constructs 1 gt
34. Base should be an atom The first call will return base 1 the next base 2 etc Note that this is no warrant that the atom is unique in the system sleep Time Suspend execution Time seconds Time is either a floating point number or an integer Gran ularity is dependent on the system s timer granularity A negative time causes the timer to return immediately On most non realtime operating systems we can only ensure execution is suspended for at least Time seconds BUG I plan to supply a real gensym 2 which does give this warrant for future versions SWI Prolog 5 0 Reference Manual Using Modules 5 1 Why Using Modules In traditional Prolog systems the predicate space was flat This approach is not very suitable for the development of large applications certainly not if these applications are developed by more than one programmer In many cases the definition of a Prolog predicate requires sub predicates that are intended only to complete the definition of the main predicate With a flat and global predicate space these support predicates will be visible from the entire program For this reason it is desirable that each source module has it s own predicate space A module consists of a declaration for it s name it s public predicates and the predicates themselves This approach allow the programmer to use short local names for support predicates without worrying about name conflicts with the support predicat
35. Contents 7 E Summary 225 BL at co ass as er teeter ash ce Ee Ae Se ee eh Ge ee a eh a 225 B 2 Library predicates vo 3 ce eee ER a a ra a a ed eee a 236 ELL brechas aa Be Ge ee a ee ees ee aS 236 E22 dibtary eesautil oore aaa ee ee ee ea Pa eR aa eS 236 E23 librarynebscepe sierra ba to Ba ke Oded ws 236 B2e brary registry ed a eee a AS pode ee a a S 236 Bao DDA UEI cda eG Bk he Ble ee in Sh ew wt ee ed 236 E3 Arthm c Functions e ss sss acuda a ee aw a aS 237 EA Opent o eena ee ew a Ee a ee 239 SWI Prolog 5 0 Reference Manual Introduction 1 1 SWI Prolog SWI Prolog has been designed and implemented to get a Prolog implementation which can be used for experiments with logic programming and the relation to other programming paradigms The inten tion was to build a Prolog environment which offers enough power and flexibility to write substantial applications but is straightforward enough to be modified for experiments with debugging optimi sation or the introduction of non standard data types Performance optimisation is limited due to the main objectives portability SWI Prolog is entirely written in C and Prolog and modifiability SWI Prolog is based on a very restricted form of the WAM Warren Abstract Machine described in Bowen amp Byrd 1983 which defines only 7 instructions Prolog can easily be compiled into this language and the abstract machine code is easily decompiled back into Prolog As it is also
36. DOS machine is happy with the output format_predicate n dos_newline _Arg dos_newline Arg between 1 Ar _ put 13 put 10 fail true current format _predicate Code Head Enumerates all user defined format predicates Code is the character code of the format charac ter Head is unified with a term with the same name and arity as the predicate If the predicate does not reside in module user Head is qualified with the definition module of the predicate 4 36 Terminal Control The following predicates form a simple access mechanism to the Unix termcap library to provide terminal independent I O for screen terminals These predicates are only available on Unix machines The SWI Prolog Windows consoles accepts the ANSI escape sequences tty_get_capability Name Type Result Get the capability named Name from the termcap library See termcap 5 for the capability names Type specifies the type of the expected result and is one of string number or bool String results are returned as an atom number result as an integer and bool results as the atom on or of f If an option cannot be found this predicate fails silently The results are only computed once Successive queries on the same capability are fast tty_goto X Y Goto position X Y on the screen Note that the predicates line_count 2 and line position 2 will not have a well defined behaviour while using this predicate tty_put Atom Lines Put an a
37. Equivalent to calling she11 1 Use for compatibility only shell Command Equivalent to calling she11 1 Use for compatibility only shell Equivalent to calling she11 0 Use for compatibility only cd Equivalent to calling working_directory 2 to the expansion see expand_file_name 2 of For compatibility only cd Directory Equivalent to calling working_directory 2 Use for compatibility only argv Argv Unify Argv with the list of commandline arguments provides to this Prolog run Please note that Prolog system arguments and application arguments are separated by Integer arguments are passed as Prolog integers float arguments and Prolog floating point num bers and all other arguments as Prolog atoms New applications should use the prolog flag argv A stand alone program could use the following skeleton to handle command line argu ments See also section 5 SWI Prolog 5 0 Reference Manual 4 37 OPERATING SYSTEM INTERACTION 119 main unix argv Argv append _PrologArgs AppArgs Argv main AppArgs 4 37 1 Dealing with time and date There is no standard for time representation in the Prolog community SWI Prolog represents it as a floating point number using the same basic representation as the POSIX standard seconds elapsed since the January 1970 0 hours This format is also used for predicates accessing time information from files see time_file 2 get time Time Return the
38. Halt Prolog execution This action should be called rather than Unix exit to give Prolog the opportunity to clean up This call does not return The argument an int is the exit code See halt 1 Generate a Prolog abort abort 0 This call does not return Requires no arguments Create a standard Prolog break environment break 0 Returns after the user types the end of file character Re quires no arguments Win32 Used to indicate the kernel that the application is a GUI application if the argument is not 0 and a console application if the argument is 0 If a fatal error occurs the system uses a windows messagebox to report this on a GUI application and simply prints the error and exits otherwise Write the argument a char to the current output stream Flush the current output stream Requires no arguments Table 6 1 PL_action options PL_QUERY_ARGC PL_QUERY_ARGV PL_QUERY_SYMBOLFILE PL_MAX_INTEGER PL_MIN_INTEGER PL_ QUERY_VERSION Return an integer holding the number of arguments given to Prolog from Unix Return a char holding the argument vector given to Pro log from Unix Return a char holding the current symbol file of the run ning process Return a long representing the maximal integer value rep resented by a Prolog integer Return a long representing the minimal integer value Return a long representing the version as 10 000 x M 100 x m p where M
39. IN PREDICATES writeq Term Write Term to the current output using brackets and operators where appropriate Atoms that need quotes are quoted Terms written with this predicate can be read back with read 1 provided the currently active operator declarations are identical writeq Stream Term Write Term to Stream inserting quotes print 7erm Prints Term on the current output stream similar to write 1 but for each sub term of Term first the dynamic predicate portray 1 is called If this predicate succeeds print assumes the sub term has been written This allows for user defined term writing print Stream Term Print Term to Stream portray Term A dynamic predicate which can be defined by the user to change the behaviour of print 1 on sub terms For each subterm encountered that is not a variable print 1 first calls portray 1 using the term as argument For lists only the list as a whole is given to portray 1 If portray succeeds print 1 assumes the term has been written read Term Read the next Prolog term from the current input stream and unify it with Term On a syntax error read 1 displays an error message attempts to skip the erroneous term and fails On reaching end of file Term is unified with the atom end of file read Stream Term Read Term from Stream read_clause 7erm Equivalent to read 1 but warns the user for variables only occurring once in a term sin gleton variables which do not s
40. Keefe The Craft of Prolog MIT Press Massachussetts 1990 F Pereira C Prolog User s Manual 1986 Quintus Prolog User Guide and Reference Manual Berkham sted UK 1997 L Sterling and E Shapiro The Art of Prolog MIT Press Cam bridge Massachusetts 1986 SWI Prolog 5 0 Reference Manual Index MANUAL library 22 lpl library 191 lreadline library 205 pl 43 pro 43 2 103 2 106 2 103 1 2 65 12 65 1 0 64 1 1 74 43 12 104 2 105 2 63 2 63 gt 2 103 gt 2 103 12 107 12 105 gt 2 65 lt 2 103 lt lt 2 106 lt 2 103 1 104 2 104 2 63 1 106 2 63 1 65 2 106 2 104 2 107 gt gt 2 106 7 2 65 gt 2 65 2 63 2 64 gt 2 64 gt 2 64 2 104 SWI Prolog 5 0 Reference Manual lt 2 64 lt 2 64 2 95 _PL_get_arg 163 43 abolish 1 13 75 abolish 2 75 151 abolish 1 2 34 abort 0 21 26 35 84 86 127 128 182 184 abs 1 105 absolute_file_name 2 120 absolute_file_name 3 121 absolute_file_name 2 16 55 58 121 122 203 absolute_file_name 3 32 36 54 57 121 151 208 209 absolute_file_name 2 3 34 57 access_file 2 120 access_file 2 36 121 acos 1 106 address 2 126 Alpha DEC 13 append 1 82 83 append 3 97 108 apply 2 66 apropos 1 23 37 216 225 arg 3 94 arithmethic_function 1 176 arithmetic_function 1 107 arith
41. Load the file specified with File only one file is accepted File should be a module file ImportList is a list of name arity pairs specifying the predicates that should be imported from the loaded module If a predicate is specified that is not exported from the loaded module a warning will be printed The predicate will nevertheless be imported to simplify debugging import Head Import predicate Head into the current context module Head should specify the source module using the module term construct Note that predicates are normally imported using one of the directives use_module 1 2 import 1 is meant for handling imports into dynami cally created modules It would be rather inconvenient to have to import each predicate referred to by the module includ ing the system predicates For this reason each module is assigned a default module All predicates in the default module are available without extra declarations Their definition however can be over ruled in the local module This schedule is implemented by the exception handling mechanism of SWI Prolog if an undefined predicate exception is raised for a predicate in some module the excep tion handler first tries to import the predicate from the module s default module On success normal execution is resumed 5 4 1 Reserved Modules SWI Prolog contains two special modules The first one is the module system This module contains all built in predicates described in this
42. Prolog With opaque data we refer to data handled in foreign functions passed around in Prolog but of which Prolog never examines the contents of the data itself If the data is opaque to Prolog the choosen representation does not depend on simple analysis by Prolog and the selection will be driven solely by simplicity of the interface and performance both in time and space How big is the data Is effient encoding required For examine a boolean aray may be expressed as a compound term holding integers each of which contains a number of bits or as a list of t rue and false SWI Prolog 5 0 Reference Manual 186 CHAPTER 6 FOREIGN LANGUAGE INTERFACE e What is the nature of the data For examples in C constants are often expressed using enum or define d integer values If prolog needs to handle this data atoms are a more logical choice Whether or not this mapping is used depends on whether Prolog needs to interpret the data how important debugging is and how important performance is e What is the lifetime of the data We can distinguish three cases 1 The lifetime is dictated by the accesibility of the data on the Prolog stacks Their is no way by which the foreign code when the data becomes garbage and the data thus needs to be represented on the Prolog stacks using Prolog data types 2 2 The data lives on the heap and is explicitly allocated and deallocated In this case representing the da
43. Prolog calls C etc but it is not allowed to open multiple queries and start generating solutions for each of them by calling PL_next_solution Be sure to call PL_cut_query or PL_close_query on any query you opened before opening the next or returning control back to Prolog qid_t PL_open_query module_t ctx int flags predicate_t p term_t 10 Opens a query and returns an identifier for it This function always succeeds regardless whether the predicate is defined or not ctx is the context module of the goal When NULL the context module of the calling context will be used or user if there is no calling context as may happen in embedded systems Note that the context module only matters for module_transparent pred icates See context _module 1 andmodule_transparent 1 The p argument specifies the predicate and should be the result of a call to PLpred or PLpredicate Note that it is allowed to store this handle as global data and reuse it for future queries The term reference 10 is the first of a vector of term references as returned by PL_new_term_refs n The flags arguments provides some additional options concerning debugging and exception handling It is a bitwise or of the following values PL_Q_NORMAL Normal operation The debugger inherits its settings from the environment If an excep tion occurs that is not handled in Prolog a message is printed and the tracer is started to debug the error PL_Q_NODEBUG
44. Stream Char Unify Char with the next character from Stream as a one character atom See also get_char 2 get_byte 2 and get_code 2 get0 Char Edinburgh version of the ISO get _byte 1 predicate get0 Stream Char Edinburgh version of the ISO get _byte 2 predicate get Char Read the current input stream and unify the next non blank character with Char Char is unified with 1 on end of file get Stream Char Read the next non blank character from Stream peek_byte Byte Reads the next input byte like get _byte 1 but does not remove it from the input stream peek_byte Stream Byte Reads the next input byte like get _byte 2 but does not remove it from the stream peek_code Code Reads the next input code like get __code 1 but does not remove it from the input stream peek_code Stream Code Reads the next input code like get __code 2 but does not remove it from the stream peek_char Char Reads the next input character like get _char 1 but does not remove it from the input stream peek_char Stream Char Reads the next input character like get_char 2 but does not remove it from the stream SWI Prolog 5 0 Reference Manual 90 CHAPTER 4 BUILT IN PREDICATES skip Char Read the input until Char or the end of the file is encountered A subsequent call to get 0 1 will read the first character after Char skip Stream Char Skip input as skip 1 on Stream get single char Char Ge
45. Strings are stores as a byte array on the global term stack and thus destroyed on backtracking and reclaimed by the garbage collector Strings were added to SWI Prolog based on an early draft of the ISO standard offerring a mech anism to represent temporary character data efficiently As SWI Prolog strings can handle 0 bytes they are frequently used through the foreign language interface section 6 for storing arbitrary byte sequences Starting with version 3 3 SWI Prolog offers garbage collection on the atom space as well as representing 0 bytes in atoms Although strings and atoms still have different features new code should consider using atoms to avoid too many representations for text as well as for compatibility to other Prolog systems Below are some of the differences e creation Creating strings is fast as the data is simply copied to the global stack Atoms are unique and therefore more expensive in terms of memory and time to create On the other hand if the same text has to be represented multiple times atoms are more efficient e destruction Backtracking destroys strings at no cost They are cheap to handle by the garbage collector SWI Prolog 5 0 Reference Manual 4 24 OPERATORS 101 but it should be noted that extensive use of strings will cause many garbage collections Atom garbage collection is generally faster See also the prolog flag double_quotes string_to_atom String Atom Logical conversion b
46. Take a substring from a string Delete elements that do not meet condition Logical integer successor relation Formatted write on a string Formatted write on a string SWI Prolog 5 0 Reference Manual 234 APPENDIX E SUMMARY tab 1 Output number of spaces tab 2 Output number of spaces on a stream tell 1 Change current output stream telling 1 Query current output stream term_expansion 2 term_to_atom 2 thread_at_exit 1 thread_create 3 thread_exit 1 thread_get_message 1 thread_join 2 thread_peek_message 1 thread_self 1 thread_send_message 2 thread_signal 2 threads 0 throw 1 time l time file 2 tmp file 2 told 0 trace 0 trace 1 trace 2 tracing 0 trim_stacks 0 true 0 tty_get_capability 3 tty _goto 2 tty _put 2 tty _size 2 ttyflush 0 union 3 unify _with_occurs_check 2 unix l unknown 2 unload _foreign_library l unsetenv 1 use_module 1 use_module 2 var l visible 1 volatile 1 wait_for_input 3 wildcard_match 2 win_exec 2 win_insert_menu 2 hook Convert term before compilation Convert between term and atom Register goal to be called at exit Create a new Prolog task Terminate Prolog task with value Wait for message Wait for Prolog task completion Test for message in queue Get identifier of current thread Send message to another thread Execute goal in another thread List running threads Raise an exception see cat ch 3 Determine time needed to execute goal Get last modification time o
47. a character code on a stream Compile source to Quick Load File Create runtime application Create runtime application Read Prolog term Read Prolog term from stream Read clause Read clause from stream Read using history substitution Read a symbolic link Read term with options Read term with options from stream Record term in the database first Record term in the database first Obtain term from the database Obtain term from the database Record term in the database last Record term in the database last Abolish system definition Change name of file Succeed leaving infinite backtrack points This file requires these predicates Clear statistics obtained by the profiler Declare a program resource Remove clause from the database Remove unifying clauses from the database Inverse the order of the elements in a list Succeeds if arguments refer to same file Change the current input stream Query the current input stream SWI Prolog 5 0 Reference Manual E 1 PREDICATES 233 seek 4 seen 0 select 3 set_input 1 set_output 1 set_prolog_flag 2 set_stream 2 set_stream_position 2 set_tty 2 setarg 3 setenv 2 setof 3 sformat 2 sformat 3 shell 0 shell 1 shell 2 show _profile 1 size_file 2 skip 1 skip 2 rl_add_history 1 rl_read_init_file 1 sleep 1 sort 2 source_file 1 source_file 2 source_location 2 spy 1 stack_parameter 4 statistics 0 statistics 2 stream_property 2 string 1 string _co
48. a name based module system also data is local to the module This introduces another serious problem SWI Prolog 5 0 Reference Manual 140 CHAPTER 5 USING MODULES module action action 3 action Object sleep Arg action Object awake Arg module process awake_process 2 awake_process Process Arg action Process awake Arg This code uses a simple object oriented implementation technique were atoms are used as method selectors Using a name based module system this code will not work unless we declare the selectors public atoms in all modules that use them Predicate based module systems do not require particular precautions for handling this case It appears we have to choose either to have local data or to have trouble with meta predicates Probably it is best to choose for the predicate based approach as novice users will not often write generic meta predicates that have to be used across multiple modules but are likely to write programs that pass data around across modules Experienced Prolog programmers should be able to deal with the complexities of meta predicates in a predicate based module system 5 3 Defining a Module Modules normally are created by loading a module file A module file is a file holding a module 2 directive as its first term The module 2 directive declares the name and the public i e externally visible predicates of the module The rest of the file is loaded into
49. a positive integer Actions are Q Q h H H Output the tilde itself Output the next argument which should be an atom This option is equivalent to w Compatibility reasons only Output the next argument as an ASCII value This argument should be an integer in the range 0 255 including 0 and 255 Output next argument as a decimal number It should be an integer If a numeric argument is specified a dot is inserted argument positions from the right useful for doing fixed point arithmetic with integers such as handling amounts of money Same as d but makes large values easier to read by inserting a comma every three digits left to the dot or right Output next argument as a floating point number in exponential notation The numeric argument specifies the precision Default is 6 digits Exact representation depends on the C library function printf This function is invoked with the format precision e Equivalent to e but outputs a capital E to indicate the exponent Floating point in non exponential notation See C library function printf Floating point in e or f notation whichever is shorter Floating point in E or f notation whichever is shorter Ignore next argument of the argument list Produces no output Give the next argument to displayq 1 canonical write n Output a newline character Only output a newline if the last character output on this stream was not a newline Not properly imple
50. a pro gram Do not rely on this feature if you want to maintain portability to other Prolog implementations dynamic Functor Arity Informs the interpreter that the definition of the predicate s may change during execution us ing assert 1 and or retract 1 Currently dynamic 1 only stops the interpreter from complaining about undefined predicates see unknown 2 Future releases might prohibit assert 1and retract 1 for not dynamic declared procedures multifile Functor Arity Informs the system that the specified predicate s may be defined over more than one file This stops consult 1 from redefining a predicate when a new definition is found discontiguous Functor Arity Informs the system that the clauses of the specified predicate s might not be together in the source file See also st yle_check 1 index Head Index the clauses of the predicate with the same name and arity as Head on the specified argu ments Head is a term of which all arguments are either 1 denoting index this argument or 0 denoting do not index this argument Indexing has no implications for the semantics of a predicate only on its performance If indexing is enabled on a predicate a special purpose algorithm is used to select candidate clauses based on the actual arguments of the goal This algorithm checks whether indexed arguments might unify in the clause head Only atoms in tegers and compound terms are consider
51. after which the predicate fails quiet which causes the predicate to fail silently and dec10 which causes syntax errors to be printed after which read_term 2 3 continues reading the next term Using dec10 read term 2 3 never fails Quintus SICStus module Module Specify Module for operators character_escapes flag and double_quotes flag The value of the latter two is overruled if the corresponding read_term 3 option is provided If no module is specified the current source module is used SWI Prolog character _escapes Bool Defines how to read escape sequences in quoted atoms See the prolog flags charac ter_escapes current_prolog_flag 2 SWI Prolog double_quotes Boo Defines how to read strings See the prolog flags double quotes current_prolog_flag 2 SWI Prolog term_position Pos Unifies Pos with the starting position of the term read Pos if of the same format as use by stream position 3 subterm_positions 7ermPos Describes the detailed layout of the term The formats for the various types of terms if given below All positions are character positions If the input is related to a normal stream these positions are relative to the start of the input when reading from the terminal they are relative to the start of the term From To Used for primitive types atoms numbers variables string_position From To Used to indicate the position of a string enclosed in double quotes
52. ai aa de a e A dada saa das 204 74 Finding Application files o s a eces a e aa a e k a ee a a 204 7 4 1 Passing a path to the application o oaoa 205 io The Runtime Environment a s os coce a e er y ES 205 TAL The Runtime Emulator aia Gedo do ed oS take ade d a gas 205 A The SWI Prolog library 207 A 1 library check Elementary completeness checks o o 207 A 2 library readut il Reading lines streams and files 208 A3 library net scape Activating your Web browser o o 209 A 4 library registry Manipulating the Windows registry 209 A S library ur1 Analysing and constructing URL o 210 B Hackers corner 213 B 1 Examining the Environment Stack lt oo mc o c cn da 213 B 2 Intercepting the Tracer s oars i u a eoa e a a a ee ee OE hes we AS 214 B 3 Hooks using the exception 3 predicate o oo 215 B 4 Hooks for integrating libraries o o coa aose e a e e ee 215 BS R adline Interactions coc 6 o a A oa 216 C Glossary of Terms 217 D SWI Prolog License Conditions and Tools 222 D 1 The SWI Prolog kernel and foreign libraries o a 222 D 1 1 The SWI Prolog Prolog libraries o o e 222 D 2 Contributing to the SWI Prolog project o o e 223 D 3 Software support to keep track of license conditions 223 SWI Prolog 5 0 Reference Manual
53. alignment restrictions and copies of the record can thus be moved freely For example it is possible to use this representation to exchange terms using shared memory between different Prolog processes e Compact It is assumed that a smaller memory footprint will eventually outperform slightly faster repre sentations e Stable The format is designed for future enhancements without breaking compatibility with older records char PL_record_external term_t t unsigned int len Record the term into the Prolog database as recorda 3 and return an opaque handle to the term The returned handle remains valid until PL_erase is called on it It is allowed to copy the data and use PL_recorded external on the copy The user is responsible for the memory management of the copy After copying the original may be discarded using PL_erase_external PL_recorded_external is used to copy such recorded terms back to the Prolog stack int PL_recorded_external const char record term_t t Copy a recorded term back to the Prolog stack The same record may be used to copy mul tiple instances at any time to the Prolog stack See also PL_record_external and PL_erase_external int PL_erase_external char record Remove the recorded term from the Prolog database reclaiming all associated memory re sources SWI Prolog 5 0 Reference Manual 6 6 THE FOREIGN INCLUDE FILE 181 6 6 12 Catching Signals Software Interrupts
54. and all re sources associated with the thread are reclaimed See also current _thread 2 A thread that has been completed without thread_join 2 being called on it is partly re claimed the Prolog stacks are released and the C thread is destroyed A small data structure represening the exit status of the thread is retained until thread_join 2 is called on the thread thread_exit Term Terminates the thread immediately leaving exited Term as result state The Prolog stacks and C thread are reclaimed SWI Prolog 5 0 Reference Manual 4 39 MULTI THREADING ALPHA CODE 125 thread_at_exit Goal Run Goal after the execution of this thread has terminated This is to be compared to at halt 1 but only for the current thread These hooks are ran regardless of why the ex ecution of the thread has been completed As these hooks are run the return code is already available through current thread 2 4 39 1 Thread communication Prolog threads can exchange data using dynamic predicates database records and other globally shared data In addition they can send messages to each other If a threads needs to wait for another thread until that thread has produced some data using only the database forces the waiting thread to poll the database continuously Waiting for a message suspends the thread execution until the message has arrived in its message queue thread_send_message Threadld Term Place Term in the message queue of the indi
55. another thread this predicates fails immedi ately mutex_unlock MutexId Unlock the mutex This can only be called if the mutex is held by the calling thread If this is not the case a permission_error exception is raised mutex_unlock_all Unlock all mutexes held by the current thread This call is especially useful to handle thread termination using abort 0 or exceptions See also thread signal 2 current_mutex Mutexld ThreadId Count Enumerates all existing mutexes If the mutex is held by some thread ThreadId is unified with the identifier of te holding thread and Count with the recursive count of the mutex Otherwise ThreadId is and Count is 0 with_mutex Mutexld Goal Execute Goal while holding MutexId If Goal leaves choicepointes these are destroyed as in once 1 The mutex is unlocked regardless of whether Goal succeeds fails or raises an exception An exception thrown by Goal is re thrown after the mutex has been successfully unlocked See also mutex_create 2 Although described in the thread section this predicate is also available in the single threaded version where it behaves simply as once 1 4 39 3 Thread support library threadutil This library defines a couple of useful predicates for demonstrating and debugging multi threaded applications This library is certainly not complete threads Lists all current threads and their status In addition all zombie threads finished threads that are
56. any longer A 1M argument stack The argument stack is used to store one of the intermediate code interpreter s registers The amount of space needed on this stack is determined entirely by the depth in which terms are nested in the clauses that con stitute the program Overflow is most likely when using long strings in a clause Table 2 2 Memory areas SWI Prolog 5 0 Reference Manual Initialising and Managing a Prolog Project Prolog text books give you an overview of the Prolog language The manual tells you what predicates are provided in the system and what they do This chapter wants to explain how to run a project There is no ultimate right way to do this Over the years we developed some practice in this area and SWI Prolog s commands are there to support this practice This chapter describes the conventions and supporting commands The first two sections section 3 1 and section 3 2 only require plain Prolog The remainder dis cusses the use of the built in graphical tools that require the XPCE graphical library installed on your system 3 1 The project source files Organisation of source files depends largely on the size of your project If you are doing exercises for a Prolog course you ll normally use one file for each exercise If you have a small project you ll work work with one directory holding a couple of files and some files to link it all together Even bigger projects will be
57. argument is the satellite data to be carried along with the key keysort 2 sorts List like msort 2 but only compares the keys Can be used to sort terms not on standard order but on any criterion that can be expressed on a multi dimensional scale Sorting on more than one criterion can be done using terms as keys putting the first criterion as argument 1 the second as argument 2 etc The order of multiple elements that have the same Key is not changed predsort Pred List Sorted Sorts similar to sort 2 but determines the order of two terms by calling Pred Delta El E2 This call must unify Delta with one of lt const gt or If built in predicate compare 3 is used the result is the same as sort 2 See also keysort 2 4 32 Finding all Solutions to a Goal findall Var Goal Bag Creates a list of the instantiations Var gets successively on backtracking over Goal and unifies the result with Bag Succeeds with an empty list if Goal has no solutions findall 3 is equivalent to bagof 3 with all free variables bound with the existence operator except that bagof 3 fails when goal has no solutions bagof Var Goal Bag Unify Bag with the alternatives of Var 1f Goal has free variables besides the one sharing with ISPlease note that the semantics have changed between 3 1 1 and 3 1 2 SWI Prolog 5 0 Reference Manual 4 33 INVOKING PREDICATES ON ALL MEMBERS OF A LIST 111 Var bagof will backtrac
58. as flexible as possible they accept data in any of these formats as long as the interpretation is unambiguous In addition for output arguments that are instantiated the character These marks do not suggest instantiation e g var Var SWI Prolog 5 0 Reference Manual 54 CHAPTER 4 BUILT IN PREDICATES is extracted before unification This implies that the following two calls are identical both testing whether the next input characters is an a peek_code Stream a peek_code Stream 97 These multiple representations are handled by a large number of built in predicates all of which are ISO compatible For converting betweem code and character there is char_code 2 For breaking atoms and numbers into characters are are atom_chars 2 atom_codes 2 number_codes 2 and number_chars 2 For character I O on streams there is get_char 1 2 get_code 1 2 get byte 1 2 peek_char 1 2 peek_code 1 2 peek_byte 1 2 put code 1 2 put_char 1 2 and put_byte 1 2 The prolog flag double_quotes see current_prolog flag 2 controls how text between double quotes is interpreted 4 3 Loading Prolog source files This section deals with loading Prolog source files A Prolog source file is a text file often referred to as ASCIT file containing a Prolog program or part thereof Prolog source files come in three flavours A traditional Prolog source file contains a Prolog clauses and directives but no module declaratio
59. automatically loaded and the call to the previously undefined predicate is resumed By default this mechanism loads the file silently The current prolog flag 2 verbose_autoload is provided to get verbose loading The prolog flag autoload can be used to enable disable the entire auto load system The auto loader only works if the unknown flag see unknown 2 is set to trace default A more appropriate interaction with this flag should be considered Autoloading only handles library source files that use the module mechanism described in chap ter 5 The files are loaded with use_module 2 and only the trapped undefined predicate will be imported to the module where the undefined predicate was called Each library directory must hold a file INDEX p1 that contains an index to all library files in the directory This file consists of lines of the following format index Name Arity Module File SWI Prolog 5 0 Reference Manual 38 CHAPTER 2 OVERVIEW The predicate make 0 updates the autoload index It searches for all library directories see library directory 1 and file_search_path 2 holding the file MKINDEX p1 or INDEX pl If the current user can write or create the file INDEX pl and it does not exist or is older than the directory or one of its files the index for this directory is updated If the file MKINDEX p1 exists updating is achieved by loading this file normally containing a directive calling make_library_index 2 Otherw
60. be simultaneously active in more than one goal Suppose the natural_number_below_n 2 is anon deterministic foreign predicate backtracking over all natural numbers lower than the first ar gument Now consider the following predicate quotient_below_n Q N natural_number_below_n N N1 natural_number_below_n N N2 Q N1 N2 In this predicate the function natural_number_below_n 2 simultaneously generates solutions for both its invocations Non deterministic foreign functions should be prepared to handle three different calls from Prolog e Initial call PL FIRST_CALL Prolog has just created a frame for the foreign function and asks it to produce the first answer e Redo call PL_REDO The previous invocation of the foreign function associated with the current goal indicated it was possible to backtrack The foreign function should produce the next solution SWI Prolog 5 0 Reference Manual 6 6 THE FOREIGN INCLUDE FILE 157 e Terminate call PL_CUTTED The choice point left by the foreign function has been destroyed by a cut The foreign function is given the opportunity to clean the environment Both the context information and the type of call is provided by an argument of type control t appended to the argument list for deterministic foreign functions The macro PL_foreign_control extracts the type of call from the control argument The foreign func tion can pass a context handle using the PL_retry
61. between and gt ensure If gt Then Else is actually a term of the form gt If Then Else The first two clauses belong to the definition of 2 while only the last defines gt 2 Condition gt Action Else This construct implements the so called soft cut The control is defined as follows If Condi tion succeeds at least once the semantics is the same as Condition Action If Condition does not succeed the semantics is that of Condition Else In other words If Condition succeeds at least once simply behave as the conjunction of Condition and Action otherwise execute Else Goal Succeeds if Goal cannot be proven mnemonic refers to provable and the backslash is normally used to indicate negation Up to version 4 0 6 the sequence X X acted as a true cut This feature has been deleted for ISO compliance SWI Prolog 5 0 Reference Manual 66 CHAPTER 4 BUILT IN PREDICATES 4 8 Meta Call Predicates Meta call predicates are used to call terms constructed at run time The basic meta call mechanism offered by SWI Prolog is to use variables as a subclause which should of course be bound to a valid goal at runtime A meta call is slower than a normal call as it involves actually searching the database at runtime for the predicate while for normal calls this search is done at compile time call Goal Invoke Goal as a goal Note that clauses may have variables as subcl
62. change e Argument order in select 3 The list processing predicate select 3 somehow got into a very early version of SWI Prolog with the wrong argument order This has been fixed in 3 4 0 The correct order is select Elem List Rest As select 3 has no error conditions runtime checking cannot be done To simplify debug ging the library module library checkselect will print references to select 3 in your source code and install a version of select that enters the debugger if select is called and the second argument is not a list This library can be loaded explicitely or by calling check_old_select 0 SWI Prolog 5 0 Reference Manual 16 CHAPTER 1 INTRODUCTION 1 6 13 Version 4 0 Release Notes As of version 4 0 the standard distribution of SWI Prolog is bundled with a number of its popular extension packages among which the now open source XPCE GUI toolkit see section 1 5 No significant changes have been made to the basic SWI Prolog engine Some useful tricks in the integrated environment e Register the GUI tracer Using a call to guitracer 0 hooks are installed that replace the normal command line driven tracer with a graphical forntend e Register PceEmacs for editing files From your initialisation file you can load library emacs swi_prolog that cause edit 1 to use the built in PceEmacs editor 1 7 Acknowledgements Some small parts of the Prolog code of SWI Prolog are modified versions of the correspondi
63. changed This flag is local to the module in which it is changed double_quotes codes chars atom string changeable This flag determines how double quotes strings are read by Prolog and is like charac ter_escapes maintained for each module If codes default a list of character codes is returned if chars a list of one character atoms if atom double quotes are the same as single quotes and finally st ring reads the text into a Prolog string see section 4 23 See also atom_chars 2 and atom_codes 2 allow_variable_name_as_functor bool changeable If true default is false Functor arg is read as if it was written Functor arg Some applications use the Prolog read 1 predicate for reading an application defined script language In these cases it is often difficult to explain to non Prolog users of the application that constants and functions can only start with a lowercase letter Variables can be turned into atoms starting with an uppercase atom by calling read_term 2 using the option variable_names and binding the variables to their name Using this feature F x can be turned into valid syntax for such script languages Suggested by Robert van Engelen SWI Prolog specific SWI Prolog 5 0 Reference Manual 34 CHAPTER 2 OVERVIEW history integer changeable If integer gt 0 support Unix csh 1 like history as described in section 2 7 Otherwise only support reusing commands through the commandline editor T
64. conforms to the Edinburgh standard while abolish 1 is ISO compliant SWI Prolog 5 0 Reference Manual 76 CHAPTER 4 BUILT IN PREDICATES redefine_system_predicate Head This directive may be used both in module user and in normal modules to redefine any system predicate If the system definition is redefined in module user the new definition is the default definition for all sub modules Otherwise the redefinition is local to the module The system definition remains in the module system Redefining system predicate facilitates the definition of compatibility packages Use in other context is discouraged retract Term When Term is an atom or a term it is unified with the first unifying fact or clause in the database The fact or clause is removed from the database retractall Head All facts or clauses in the database for which the head unifies with Head are removed assert Term Assert a fact or clause in the database Term is asserted as the last fact or clause of the corre sponding predicate asserta Term Equivalent to assert 1 but Term is asserted as first clause or fact of the predicate assertz Term Equivalent to assert 1 assert Term Reference Equivalent to assert 1 but Reference is unified with a unique reference to the asserted clause This key can later be used with clause 3 or erase 1 asserta Term Reference Equivalent to assert 2 but Term is asserted as first clause or fact of t
65. current_input Stream Get the current input stream Useful to get access to the status predicates associated with streams current_output Stream Get the current output stream 4 17 Status of streams wait_for_input ListOfStreams ReadyList TimeOut Wait for input on one of the streams in ListOfStreams and return a list of streams on which input is available in ReadyList wait_for_input 3 waits for at most TimeOut seconds Timeout may be specified as a floating point number to specify fractions of a second If Timeout equals 0 wait_for_input 3 waits indefinitely This predicate can be used to implement timeout while reading and to handle input from multiple sources The following example will wait for input from the user and an explicitly opened second terminal On return Inputs may hold user or P4 or both open dev ttyp4 read P4 wait_for_input user P4 Inputs 0 This predicate relies on the select call on most operating systems On Unix this call is imple mented for any stream referring to a file handle which implies all OS based streams sockets terminals pipes etc On non Unix systems select is generally only implemented for socket based streams See also library socket from the clib package character_count Stream Count Unify Count with the current character index For input streams this is the number of characters read since the open for output streams this is the number of characters writte
66. in this context void PL_close_query qid As PL_cut_query but all data and bindings created by the query are destroyed int PL call predicate module_t m int flags predicate_t pred term_t 10 Shorthand for PL_open_query PL_next_solution PL_cut_query generat ing a single solution The arguments are the same as for PL_open_query the return value is the same as PL_next_solution int PL_call term_t module_t Call term just like the Prolog predicate once 1 Term is called in the specified module or in the context module if module_t NULL Returns TRUE if the call succeeds FALSE otherwise Figure 6 4 shows an example to obtain the number of defined atoms All checks are omitted to improve readability 6 6 7 Discarding Data The Prolog data created and term references needed to setup the call and or analyse the result can in most cases be discarded right after the call PL_close query allows for destructing the data while leaving the term references The calls below may be used to destroy term references and data See figure 6 4 for an example fid_t PL open foreign frame Created a foreign frame holding a mark that allows the system to undo bindings and destroy data created after it as well as providing the environment for creating term references This function is called by the kernel before calling a foreign predicate SWI Prolog 5 0 Reference Manual 6 6 THE FOREIGN INCLUDE FILE 175 int count_ato
67. innermost PL_next_solution thus forcing an external procedure to be abandoned at an arbitrary moment Most likely not all SWI Prologs own foreign code is yet safe too Garbage Collection The garbage collector will block all signals that are handled by Prolog While handling a signal the garbage collector is disabled Time of delivery Normally delivery is immediate or as defined by the operating system used Signals are blocked when the garbage collector is active and internally delayed if they occur within in a critical section The critical sections are generally very short 4 11 The block control structure The block 3 predicate and friends have been introduced before ISO compatible catch 3 excep tion handling for compatibility with some Prolog implementation The only feature not covered by catch 3 and throw 1 is the posibility to execute global cuts New code should use catch 3 and throw 1 to deal with exceptions block Label Goal ExitValue Execute Goal in a block Label is the name of the block Label is normally an atom but the system imposes no type constraints and may even be a variable ExitValue is normally unified to the second argument of an exit 2 call invoked by Goal exit Label Value Calling exit 2 makes the innermost block which Label unifies exit The block s ExitValue is unified with Value If this unification fails the block fails SWI Prolog 5 0 Reference Manual 74 CHAPTER 4
68. int len const char s int PL unify _list_ncodes term_t t unsigned int len const char s int PL_unify_list_nchars term_t t unsigned int len const char s In addition the following functions are available for creating and inspecting atoms atom_t PL_new_atom_nchars unsigned int len const char s Create a new atom as PL_new_atom but from length and characters SWI Prolog 5 0 Reference Manual 164 CHAPTER 6 FOREIGN LANGUAGE INTERFACE const char PL_atom_nchars atom_t a unsigned int len Extract text and length of an atom Reading a list The functions from this section are intended to read a Prolog list from C Suppose we expect a list of atoms the following code will print the atoms each on a line foreign_t pl_write_atoms term_t 1 term_t head PL_new_term_ref variable for the ele ments term_t list PL_copy_term_ref 1 copy as we need to write while PL_get_list list head list char s if PL _get_atom_chars head amp s Sprintf Ss n s else PL_fail return PL_get_nil list test end for int PL_get list term_t l term_t h term_t t If lis a list and not assign a term reference to the head to h and to the tail to t int PL_get_head term_t 1 term_t h If lis a list and not assign a term reference to the head to A int PL_get_tail term_t l term_t t If lis a list and not assign a term referen
69. is no difference between the two on Unix systems alias Atom Gives the stream a name Below is an example Be careful with this option as stream names are global See also set _stream 2 SWI Prolog 5 0 Reference Manual 84 CHAPTER 4 BUILT IN PREDICATES open data read Fd alias input or read input Term eof_action Action Defines what happens if the end of the input stream is reached Action eof code makes get0 1 and friends return 1 and read 1 and friends return the atom end_of_file Repetitive reading keeps yielding the same result Action error is like eof_code but repetitive reading will raise an error With action reset Prolog will examine the file again and return more data if the file has grown buffer Buffering Defines output buffering The atom full default defines full buffering 1ine buffering by line and false implies the stream is fully unbuffered Smaller buffering is useful if another process or the user is waiting for the output as it is being produced See also flush_output 0 1 This option is not an ISO option close_on_abort Bool If t rue default the stream is closed on an abort see abort 0 If false the stream is not closed If it is an output stream it will be flushed however Useful for logfiles and if the stream is associated to a process using the pipe 1 construct lock LockingMode Try to obtain a lock on the open file Default is none which does not lock
70. is the major m the minor version number and p the patch level For example 20717 means Lil Table 6 2 PL_quer y options SWI Prolog 5 0 Reference Manual 6 6 THE FOREIGN INCLUDE FILE 183 6 6 16 Registering Foreign Predicates int PL_register_foreign const char name int arity foreign_t function int flags Register a C function to implement a Prolog predicate After this call returns successfully a predicate with name name a char and arity arity a C int is created As a special case name may consist of a sequence of alpha numerical characters followed by the colon In this case the name uptil the colon is taken to be the destination module and the rest of the name the predicate name When called in Prolog Prolog will call function flags forms bitwise or ed list of options for the installation These are PL_FA_NOTRACE Predicate cannot be seen in the tracer PL_FA_TRANSPARENT Predicate is module transparent PL_FA_NONDETERMINISTIC Predicate is non deterministic See also PL_retry PL_FA_ VARARGS Use alternative calling convention void PL_load_extensions PL_extension e Register foreign predicates from a table of structures This is an alternative to multiple calls to PL_register_foreign and simplifies code that wishes to use PL register extensions as an alternative The type PL extension is defined as typedef struct _PL_extension char predicate_name Name
71. of predicates clauses etc prove Process where Prolog attempts to prove a query using the available predicates public list List of predicates exported from a module query See goal retract Remove a clause from a predicate See also dynamic update view and assert shared Two variables are called shared after they are unified This implies if either of them is bound the other is bound to the same value A B A a A a B a singleton variable Variable appearing only one time in a clause SWI Prolog normally warns for this to avoid you making spelling mistakes If a variable appears on purpose only once in a clause write it as _ see anonymous or make sure the first character is a _ See also the style check 1 option singletons solution Bindings resulting from a successfully proven goal SWI Prolog 5 0 Reference Manual 221 structure Synonym for compound term string Used for the following representations of text a packed array see section 4 23 SWI Prolog specific a list of character codes or a list of one character atoms succeed A goal is said to have succeeded if it has been proven term Value in Prolog A term is either a variable atom integer float or compound term In addition SWI Prolog also defines the type string transparent See module transparent unify Prolog process to make two terms equal by assigning variables in one term to values at the corresponding location of t
72. only existing files and directories are returned Expanding a pattern without wildcard characters returns the argument regardless on whether or not it exists Before expanding wildchards the construct var is expanded to the value of the environment variable var and a possible leading character is expanded to the user s home directory prolog_to_os_filename PrologPath OsPath Converts between the internal Prolog pathname conventions and the operating system pathname conventions The internal conventions are Unix and this predicates is equivalent to 2 unify on Unix systems On DOS systems it will change the directory separator limit the filename length map dots except for the last one onto underscores read_link File Link Target If File points to a symbolic link unify Link with the value of the link and Target to the file the link is pointing to Target points to a file directory or non existing entry in the file system but never to a link Fails if File is not a link Fails always on systems that do not support symbolic links tmp _file Base TmpName Create a name for a temporary file Base is an identifier for the category of file The TmpName is guaranteed to be unique If the system halts it will automatically remove all created temporary files make_directory Directory Create a new directory folder on the filesystem Raises an exception on failure On Unix systems the directory is created w
73. opened in the Windows explorer shell_register_dde Type Action Service Topic Command IfNotRunning Associate DDE actions to a type Type is the same type as used for the 2nd argument of shell_register_file_type 4 Action is the a action to perform Service and Topic spec ify the DDE topic to address and Command is the command to execute on this topic Finally IfNotRunning defines the command to execute if the required DDE server is not present shell_register_prolog Ex Default registration of SWI Prolog which is invoked as part of the initialisation process on Windows systems As the source also explains the above predicates it is given as an example shell_register_prolog Ext current_prolog_flag argv Me _ concat_atom Me S1 OpenCommand shell_register_file_type Ext prolog type Pro log Source OpenCommand shell_register_dde prolog type consult prolog control teon sult 1 Me shell_register_dde prolog type edit prolog control edit 1 Me A S library ur1 Analysing and constructing URL This library deals with the analysis and construction of a URL Universal Resource Locator URL is the basis for communicating locations of resources data on the web A URL consists of a protocol identifier e g HTTP FTP and a protocol specific syntax further defining the location URLs are standardized in RFC 1738 The imple
74. organised in sub projects each using their own directory 3 1 1 File Names and Locations File Name Extensions The first consideration is what extension to use for the source files Tradition calls for p1 but con flicts with Perl force the use of another extension on systems where extensions have global meaning such as MS Windows On such systems pro is the common alternative All versions of SWI Prolog load files with the extension p1 as well as with the registered alter native extension without explicitly specifying the extension For portability reasons we propose the following convention If there is no conflict because you do not use a conflicting application or the system does not force a unique relation between extension and application use pl With a conflict choose pro and use this extension for the files you want to load through your file manager Use p1 for all other files for maximal portability Project Directories Large projects are generally composed of sub projects each using their own directory or directory structure If nobody else will ever touch your files and you use only one computer there is little to On MS Windows the alternative extension is stored in the registry key HKEY_CURRENT_USER Software SWI Prolog fileExtension or HKEY_LOCAL MACHINE Software SWI Prolog filel SWI Prolog 5 0 Reference Manual Exte 44 CHAPTER 3 INITIALISING AND MANAGING A PROLOG PRO
75. possible to wire a standard 4 port debugger in the WAM interpreter there is no need for a distinction between compiled and interpreted code Besides simplifying the design of the Prolog system itself this ap proach has advantages for program development the compiler is simple and fast the user does not have to decide in advance whether debugging is required and the system only runs slightly slower when in debug mode The price we have to pay is some performance degradation taking out the debugger from the WAM interpreter improves performance by about 20 and somewhat additional memory usage to help the decompiler and debugger SWI Prolog extends the minimal set of instructions described in Bowen amp Byrd 1983 to im prove performance While extending this set care has been taken to maintain the advantages of de compilation and tracing of compiled code The extensions include specialised instructions for unifi cation predicate invocation some frequently used built in predicates arithmetic and control 2 2 if then gt 2 and negation by failure 1 1 1 1 Other books about Prolog This manual does not describe the full syntax and semantics of Prolog nor how one should write a pro gram in Prolog These subjects have been described extensively in the literature See Bratko 1986 Sterling amp Shapiro 1986 and Clocksin amp Melish 1987 For more advanced Prolog material see O Keefe 1990 Syntax and standard o
76. redefined through the foreign language interface facilitating much simpler integration in window environments 1 6 4 Version 2 5 Release Notes Version 2 5 is an intermediate release on the path from 2 1 to 3 0 All changes are to the foreign language interface both to user and system predicates implemented in the C language The aim is twofold First of all to make garbage collection and stack expansion stack shifts possible while foreign code is active without the C programmer having to worry about locking and unlocking C variables pointing to Prolog terms The new approach is closely compatible to the Quintus and SIC Stus Prolog foreign interface using the t erm argument specification see their respective manuals This allows for writing foreign interfaces that are easily portable over these three Prolog platforms Apart from various bug fixes listed in the Changelog file these are the main changes since 2 1 0 e ISO compatibility Many ISO compatibility features have been added open 4 arithmetic functions syntax etc e Win32 Many fixes for the Win32 NT 95 and win32s platforms Notably many problems related to pathnames and a problem in the garbage collector e Performance Many changes to the clause indexing system added hash tables lazy computation of the index information etc SWI Prolog 5 0 Reference Manual 1 6 RELEASE NOTES 13 e Portable saved states The predicate qsave_program 1 2 allows for the cre
77. s library explain Explain argument library explain 2nd argument is explanation of first Export a predicate from a module List of public predicates of a module Always false Immediately fail named block See block 3 Get system configuration parameters Get file part of path Get directory part of path Add remove or test file extensions Define path aliases for locating files Do Don t warn on file errors Find all solutions to a goal Simple global variable system Transform nested list into flat list Type check for a floating point number Output pending characters on current stream Output pending characters on specified stream Prove goal for all solutions of another goal Formatted output Formatted output with arguments Formatted output on a stream Program format 1 2 Find unbound variables in a term SWI Prolog 5 0 Reference Manual E 1 PREDICATES 229 functor 3 garbage_collect 0 garbage collect_atoms 0 gensym 2 get 1 get 2 get0 1 get0 2 get_byte 1 get_byte 2 get_char 1 get_char 2 get_code 1 get_code 2 get_single_char 1 get_time 1 getenv 2 goal_expansion 2 ground 1 guitracer 0 halt 0 halt 1 hash_term 2 help O help 1 help_hook 1 ignore 1 import 1 include 1 index 1 initialization 1 int_to_atom 2 int_to_atom 3 integer 1 interactor 0 intersection 3 is 2 is_absolute_file_name 1 is_list 1 is_set 1 keysort 2 last 2 leash 1 length 2 library _directory 1 license 1 l
78. stacks program global_stack local_stack trail garbage_collection stack_shifts atoms atom_garbage_collection core CPU time CPU time since last milliseconds System CPU time System CPU time since last milliseconds Wall time Wall time since last seconds since 1970 Total unshared data free memory Uses getrusage if available otherwise incomplete own statistics global use local use heap 0 global use global free local use local free trail use O number of GC bytes gained time spent global shifts local shifts time spent fails if no shifter in this version number memory use 0 number of AGC bytes gained time spent Same as memory Table 4 2 Keys for statistics 2 SWI Prolog 5 0 Reference Manual 4 44 FINDING PERFORMANCE BOTTLENECKS 133 statistics Display a table of system statistics on the current output stream time Goal Execute Goal just like once 1 1 e leaving no choice points but print used time number of logical inferences and the average number of lips logical inferences per second Note that SWI Prolog counts the actual executed number of inferences rather than the number of passes through the call and redo ports of the theoretical 4 port model 4 44 Finding Performance Bottlenecks SWI Prolog offers a statistical program profiler similar to Unix prof 1 for C and some other lan guages A profiler is used a
79. the module Below is an example of a module file defining reverse 2 module reverse reverse 2 reverse Listl List2 rev Listl List2 rev List List rev Head Listl List2 List3 rev Listl Head List2 List3 5 4 Importing Predicates into a Module As explained before in the predicate based approach adapted by SWI Prolog each module has it s own predicate space In SWI Prolog a module initially is completely empty Predicates can be added to a module by loading a module file as demonstrated in the previous section using assert or by importing them from another module Two mechanisms for importing predicates explicitly from another module exist The use_module 1 2 predicates load a module file and import part of the public predicates of the file The import 1 predicate imports any predicate from any module SWI Prolog 5 0 Reference Manual 5 5 USING THE MODULE SYSTEM 141 use_module File Load the file s specified with File just like ensure_loaded 1 The files should all be mod ule files All exported predicates from the loaded files are imported into the context module The difference between this predicate and ensure_loaded 1 becomes apparent if the file is al ready loaded into another module In this case ensure_loaded 1 does nothing use_module will import all public predicates of the module into the current context module use_module File ImportList
80. trim_stacks Release stack memory resources that are not in use at this moment returning them to the oper ating system Trim stack is a relatively cheap call It can be used to release memory resources in a backtracking loop where the iterations require typically seconds of execution time and very different potentially large amounts of stack space Such a loop should be written as follows Loop i generator trim_stacks potentially_expensive_operation stop_condition The prolog top level loop is written this way reclaiming memory resources after every user query SWI Prolog 5 0 Reference Manual 4 46 WINDOWS DDE INTERFACE 135 stack_parameter Stack Key Old New Query set a parameter for the runtime stacks Stack is one of local global trail or argument The table below describes the Key Value pairs Old is first unified with the current value limit Maximum size of the stack in bytes min_free Minimum free space at entry of foreign predicate This predicate is currently only available on versions that use the stack shifter to enlarge the runtime stacks when necessary It s definition is subject to change 4 46 Windows DDE interface The predicates in this section deal with MS Windows Dynamic Data Exchange or DDE protocol A Windows DDE conversation is a form of interprocess communication based on sending reserved window events between the communicating processes See also sect
81. will follow The code of figure 6 2 shows a skeleton for a non deterministic foreign predicate definition 6 6 2 Atoms and functors The following functions provide for communication using atoms and functors atom_t PL_new_atom const char Return an atom handle for the given C string This function always succeeds The returned handle is valid as long as the atom is referenced see section 6 6 2 const char PL_atom_chars atom_t atom Return a C string for the text represented by the given atom The returned text will not be changed by Prolog It is not allowed to modify the contents not even temporary as the string may reside in read only memory SWI Prolog 5 0 Reference Manual 158 CHAPTER 6 FOREIGN LANGUAGE INTERFACE typedef struct define a context structure context foreign_t my_function term_t a0 term_t al foreign_t handle struct context ctxt switch PL_foreign_control handle case PL_FIRST_CALL ctxt malloc sizeof struct context PL_retry_address ctxt case PL_REDO ctxt PL_foreign_context_address handle PL_retry_address ctxt case PL_CUTTED free ctxt PL_succeed Figure 6 2 Skeleton for non deterministic foreign functions SWI Prolog 5 0 Reference Manual 6 6 THE FOREIGN INCLUDE FILE 159 functor_t PL_new functor atom_t name int arity Returns a functor identifier a handle for the name arity pair The returned handle is valid f
82. will load the Prolog source When given the q1f file it will load the file When no extension is specified it will load the q1f file when present and the p1 file otherwise qcompile File Takes a single file specification like consult 1 i e accepts constructs like library LibFile and creates a Quick Load File from File The file extension of this file is q1 f The base name of the Quick Load File is the same as the input file If the file contains consult File or File statements the referred files are compiled into the same qlf file Other directives will be stored in the q1f file and executed in the same fashion as when loading the p1 file For term_expansion 2 the same rules as described in section 2 10 apply Source references source_file 2 in the Quick Load File refer to the Prolog source file from which the compiled code originates 4 4 Listing and Editor Interface SWI Prolog offers an extensible interface which allows the user to edit objects of the program predi cates modules files etc The editor interface is implemented by edit 1 and consists of three parts locating selecting and starting the editor Any of these parts may be extended or redefined by adding clauses to various multi file see multifile 1 predicates defined in the module prolog_edit The built in edit specifications for edit 1 see prolog_edit locate 3 are described be low Fully specified obje
83. 0 Reference Manual 2 4 COMMAND LINE OPTIONS 21 F script Selects a startup script from the SWI Prolog home directory The script file is named script rc The default script name is deduced from the executable taking the leading al phanumerical characters letters digits and underscore from the program name F none stops looking for a script Intended for simple management of slightly different versions One could for example write a script iso rc and then select ISO compatibility mode using pl F iso or make a link from iso p1 to pl g goal Goal is executed just before entering the top level Default is a predicate which prints the wel come message The welcome message can thus be suppressed by giving g true goal can be a complex term In this case quotes are normally needed to protect it from being expanded by the Unix shell t goal Use goal as interactive toplevel instead of the default goal prolog 0 goal can be a complex term If the toplevel goal succeeds SWI Prolog exits with status 0 If it fails the exit status is 1 This flag also determines the goal started by break 0 and abort 0 If you want to stop the user from entering interactive mode start the application with g goa and give halt as toplevel tty Unix only Switches controlling the terminal for allowing single character commands to the tracer and get_single_char 1 By default manipulating the terminal is enabled unless the system detects it is no
84. 1 Register an evaluable function assert 1 Add a clause to the database assert 2 Add a clause to the database give reference asserta 1 Add a clause to the database first asserta 2 Add a clause to the database first assertz 1 Add a clause to the database last assertz 2 Add a clause to the database last attach_console 0 at_end_of_stream 0 at_end_of_stream 1 at_halt 1 at_initialization 1 atom 1 atom_chars 2 atom_codes 2 atom_length 2 atom_prefix 2 atom_to_term 3 atomic l autoload 0 bagof 3 between 3 block 3 break O call 1 call 2 call_cleanup 3 call_cleanup 2 call_shared_object function 2 call_with_depth_limit 3 callable 1 catch 3 char_code 2 char_conversion 2 char_type 2 character_count 2 chdir 1 checklist 2 clause 2 clause 3 clause_property 2 close 1 Attach I O console to thread Test for end of file on input Test for end of file on stream Register goal to run at halt 1 Register goal to run at start up Type check for an atom Convert between atom and list of characters Convert between atom and list of ASCII values Determine length of an atom Test for start of atom Convert between atom and term Type check for primitive Autoload all predicates now Find all solutions to a goal Integer range checking generating Start a block catch throw Start interactive toplevel Call a goal Call with additional arguments Guard a goal with a cleaup handler Guard a goal with a cleaup
85. 2 Intl 1 At least one of the arguments must be instantiated to an integer plus nt1 Int2 Int3 Succeeds if Int3 Intl Int2 At least two of the three arguments must be instantiated to integers Exprl gt Expr2 Succeeds when expression Exprl evaluates to a larger number than Expr2 Exprl lt Expr2 Succeeds when expression Expr evaluates to a smaller number than Expr2 Exprl lt Expr2 Succeeds when expression Expr evaluates to a smaller or equal number to Expr2 Exprl gt Expr2 Succeeds when expression Exprl evaluates to a larger or equal number to Expr2 Exprl1 X Expr2 Succeeds when expression Expr evaluates to a number non equal to Expr2 Exprl Expr2 Succeeds when expression Expr evaluates to a number equal to Expr2 Number is Expr Succeeds when Number has successfully been unified with the number Expr evaluates to If Expr evaluates to a float that can be represented using an integer i e the value is integer and SWI Prolog 5 0 Reference Manual 104 CHAPTER 4 BUILT IN PREDICATES within the range that can be described by Prolog s integer representation Expr is unified with the integer value Note that normally is 2 will be used with unbound left operand If equality is to be tested 2 should be used For example 1 0 is sin pi 2 Fails sin pi 2 evaluates to 1 0 but is 2 will represent this as the integer 1 after which unify will fail 1 0 is fl
86. 24 CHAPTER 2 OVERVIEW Whe Repeat last query Inr Repeat query numbered nr Istr Repeat last query starting with str Est Repeat last query holding str old new Substitute old into new in last query inr old new Substitute in query numbered nr Istr old new Substitute in query starting with str str old new Substitute in query holding str his Show history list lh Show this list Table 2 1 History commands 1 maplist plus 1 hello X X 105 102 109 109 112 Yes 2 format s7 n SX ifmmp Yes E Figure 2 1 Reusing toplevel bindings 2 7 1 Limitations of the History System History expansion is executed after raw reading This is the first stage of read_term 2 and friends reading the term into a string while deleting comment and canonising blank This makes it hard to use it for correcting syntax errors Command line editing as provided using the GNU readline library is more suitable for this History expansion is first of all useful for executing or combining commands from long ago 2 8 Reuse of toplevel bindings Bindings resulting from the successful execution of a toplevel goal are asserted in a database These values may be reused in further toplevel queries as Var Only the latest binding is available Example Note that variables may be set by executing 2 6 X statistics X statistics Yes T 2 OX SWI Prolog 5 0 Reference Man
87. 51 load_files 1 36 load_files 2 55 load_foreign_library 1 201 load_foreign_library 2 151 load foreign library 1 2 57 130 log 1 107 log10 1 107 logical update view 77 main O 31 make O 9 38 46 51 52 56 make directory l 122 make_library_index l 38 make_library_index 2 38 make_library_index 1 38 make_library index 2 38 manpce 0 41 maplist 3 112 143 200 max 2 105 member 2 26 68 81 108 230 memberchk 2 108 memory layout 41 merge 3 109 merge_set 3 110 SWI Prolog 5 0 Reference Manual INDEX 247 message_hook 3 36 71 message_to_string 2 71 message_hook 3 14 70 71 message_to_string 2 70 71 meta_predicate 1 145 148 meta_predicate 1 146 148 min 2 105 mod 2 104 module 1 146 module 2 58 140 145 module_transparent 1 145 module_transparent 1 80 146 173 218 msort 2 110 multi_file 1 219 multifile 1 60 78 80 207 215 mutex_create l 126 mutex_destroy 1 126 mutex_lock 1 126 mutex_trylock 1 127 mutex_unlock 1 127 mutex_unlock_all 0 127 mutex_create l 126 mutex_create 2 127 mutex_lock 1 127 name 2 96 97 netmask 4 188 netscape library 209 236 n1 0 88 nl1 1 88 nl 0 1 113 nodebug 0 130 nofileerrors O 87 noguitracer 0 51 52 130 nonvar 1 62 noprotocol 0 129 nospy 1 25 37 130 216 nospyall 0 37 130 216 not 1 59 66 225 notrace O 129 notrace 1 130 nth0 3 108 nth1 3 109 nth_clause 3 81 nth_clause 3 81 213
88. 6 THE FOREIGN INCLUDE FILE 171 PL_CHARS const char Unify the argument with an atom constructed from the C char as in PL_unify_atom_chars PL_FUNCTOR functor 1 Unify the argument with a compound term This specification should be followed by exactly as many specifications as the number of arguments of the compound term PL_FUNCTOR_CHARS const char name int arity Create a functor from the given name and arity and then behave as PL_FUNCTOR PL_LIST int length Create a list of the indicated length The following arguments contain the elements of the list For example to unify an argument with the term language dutch the following skeleton may be used static functor_t FUNCTOR_languagel static void init_constants FUNCTOR_languagel PL_new_functor PL_new_atom language 1 foreign_t pl_get_lang term_t r return PL_unify_term r PL_FUNCTOR FUNCTOR_languagel PL_CHARS dutch install_t install PL_register_foreign get_lang 1 pl_get_lang 0 init_constants int PL_chars_to_term const char chars term_t t Parse the string chars and put the resulting Prolog term into t chars may or may not be closed using a Prolog full stop 1 e a dot followed by a blank Returns FALSE if a syntax error was encountered and TRUE after successful completion In addition to returning FALSE the exception term is returned in on a syntax error See also term_to_atom 2
89. CATES noguitracer Reverts back to the textual tracer trace Pred Equivalent to trace Pred all trace Pred Ports Put a trace point on all predicates satisfying the predicate specification Pred Ports is a list of portnames call redo exit fail The atom all refers to all ports If the port is preceded by a sign the trace point is cleared for the port If it is preceded by a the trace point is set The predicate trace 2 activates debug mode see debug 0 Each time a port of the 4 port model is passed that has a trace point set the goal is printed as with trace 0 Unlike trace 0 however the execution is continued without asking for further information Exam ples trace hello Trace all ports of hello with any arity in any mod ule trace foo 2 fail Trace failures of foo 2 in any module trace bar 1 all Stop tracing bar 1 The predicate debugging 0 shows all currently defined trace points notrace Goal Call Goal but suspend the debugger while Goal is executing The current implementation cuts the choicepoints of Goal after successful completion See once 1 Later implementations may have the same semantics as ca11 1 debug Start debugger In debug mode Prolog stops at spy and trace points disables tail recursion optimisation and aggressive destruction of choice points to make debugging information acces sible Implemented by the Prolog flag debug nodebug Stop debugger Implem
90. EDICATES age agc_gained agc_time cputime inferences heap heapused heaplimit local localused locallimit global globalused globallimit trail trailused traillimit atoms functors predicates modules codes threads threads_created threads_cputime Number of atom garbage collections performed Number of atoms removed Time spent in atom garbage collections User CPU time since Prolog was started in seconds Total number of passes via the call and redo ports since Prolog was started Estimated total size of the heap see section 2 16 1 Bytes heap in use by Prolog Maximum size of the heap see section 2 16 1 Allocated size of the local stack in bytes Number of bytes in use on the local stack Size to which the local stack is allowed to grow Allocated size of the global stack in bytes Number of bytes in use on the global stack Size to which the global stack is allowed to grow Allocated size of the trail stack in bytes Number of bytes in use on the trail stack Size to which the trail stack is allowed to grow Total number of defined atoms Total number of defined name arity pairs Total number of predicate definitions Total number of module definitions Total amount of byte codes in all clauses MT version number of active threads MT version number of created threads MT version seconds CPU time used by finished threads Compatibility keys runtime system time real_time memory
91. In practice this problem is small as most final applications have Prolog embedded without direct access to the commandline and therefore without need for libreadline gt This exception is a straight re phrasing of the license used for libgcc the GNU C runtime library facing similar technical issues SWI Prolog 5 0 Reference Manual 224 APPENDIX D SWI PROLOG LICENSE CONDITIONS AND TOOLS This should be the default for software contributed to the SWI Prolog project as it allows the community to prosper both in the free and non free world Still people using SWI Prolog to create non free applications must contribute sources to improvements they make to the community Igpl This is the default license for foreign libraries linked with SWI Prolog Use PL_license to register the condition from foreign code gpl Indicates this module is strictly Free Software which implies it cannot be used together with any module that is incompatible to the GPL Please only use these conditions when forced by other code used in the component license Licenseld Intented as a directive in Prolog source files It takes the current filename and calls license 2 void PL license const char Licenseld const char Component Intended for the install procedure of foreign libraries This call can be made before PL_initialise SWI Prolog 5 0 Reference Manual Summary E 1 Predicates The predicate summary is used by the Prolog predicate apr
92. JECT worry about but this is rarely the case with a large project To improve portability SWI Prolog uses the POSIX notation for filenames which uses the forward slash to separate directories Just before hitting the file system it uses prolog_to_os_filename 2 to convert the filename to the conventions used by the hosting oper ating system It is strongly advised to write paths using the especially on systems using the for this purpose MS Windows Using violates the portability rules and requires you to double the due to the Prolog quoted atom escape rules Portable code should use prolog_to_os_filename 2 to convert computed paths into system paths when constructing commands for she11 1 and friends Sub projects using search paths Thanks to Quintus Prolog adapted an extensible mechanism for searching files using file_search_path 2 This mechanism allows for comfortable and readable specifications Suppose you have extensive library packages on graph algorithms set operations and ui primitives These sub projects are likely candidates for re use in future projects A good choice is to create a directory with sub directories for each of these sub projects Next there are three options One is to add the sub projects to the directory hierarchy of the current project Another is to use a completely dislocated directory and finally the sub project can be added to the SWI Prolog hierarchy Using local installation a typical fi
93. KING EMBEDDED APPLICATIONS USING PLLD 191 plld will first split the options into various groups for both the C compiler and the Prolog compiler Next it will add various default options to the C compiler and call it to create an executable holding the user s C code and the Prolog kernel Then it will call the SWI Prolog compiler to create a saved state from the provided Prolog files and finally it will attach this saved state to the created emulator to create the requested executable Below it is described how the options are split and which additional options are passed help Print brief synopsis pl prolog Select the prolog to use This prolog is used for two purposes get the home directory as well as the compiler linker options and create a saved state of the Prolog code ld linker Linker used to link the raw executable Default is to use the C compiler Win32 link exe cc C compiler Compiler for c files found on the commandline Default is the compiler used to build SWI Prolog see current _prolog_flag 2 Win32 cl exe c C compiler Compiler for C sources extensions cpp cxx cc or C files found on the command line Default is c or g if the C compiler is gcc Win32 cl exe nostate Just relink the kernel do not add any Prolog code to the new kernel This is used to create a new kernel holding additional foreign predicates on machines that do not support the shared library DLL interface o
94. M INTERACTION 121 uses absolute file names to register source files independent of the current working di rectory See also absolute_file_name 3 See also absolute_file_name 3 and expand file name 2 absolute file name Spec Options Absolute Converts the given file specification into an absolute path Option is a list of options to guide the conversion extensions ListOfExtensions List of file extensions to try Default is For each extension absolute_file_name 3 will first add the extension and then verify the condi tions imposed by the other options If the condition fails the next extension of the list is tried Extensions may be specified both as ext or plain ext access Mode Imposes the condition access_file File Mode Mode is on of read write append exist or none See also access_file 2 file type Type Defines extensions Current mapping txt implies prolog implies pl 1 executable implies so qlf implies qlf and di rectory implies file_errors fail error If error default throw and existence error exception if the file cannot be found If fail stay silent solutions first all If first default the predicates leaves no choice point Otherwise a choice point will be left and backtracking may yield more solutions The prolog flag verbose_file_search can be set to true to help debugging Prolog s search for files
95. Manual 7 5 THE RUNTIME ENVIRONMENT 205 user file_ search path gnatdir swi gnat The application should locate all files using absolute file name Suppose gnatdir contains a file con fig pl to define local configuration Then use the code below to load this file configure_gnat absolute_file_name gnatdir config pl ConfigFile gt consult ConfigFile 7 format user_error gnat Cannot lo cate config pl n halt 1 jra 7 4 1 Passing a path to the application Suppose the system administrator has installed the SWI Prolog runtime environment in usr local lib rt pl 3 2 0 A user wants to install gnat but gnat will look for its configuration in usr local lib rt pl 3 2 0 gnat where the user cannot write The user decides to install the gnat runtime files in users bob lib gnat For one time usage the user may decide to start gnat using the command o gnat p gnatdir users bob lib gnat 7 5 The Runtime Environment 7 5 1 The Runtime Emulator The sources may be used to built two versions of the emulator By default the development emulator is built This emulator contains all features for interactive development of Prolog applications If the system is configured using enable runtime make 1 will create a runtime version of the emulator This emulator is equivalent to the development version except for the following features e No input editing The GNU library 1readline that provides EMACS
96. N 109 nth1 Index List Elem Succeeds when the Index th element of List unifies with Elem Counting starts at 1 last Elem List Succeeds if Elem unifies with the last element of List If List is a proper list last 2 is deter ministic If List has an unbound tail backtracking will cause List to grow reverse Listl List2 Reverse the order of the elements in List and unify the result with the elements of List2 flatten List List2 Transform List possibly holding lists as elements into a flat list by replacing each list with its elements recursively Unify the resulting flat list with List2 Example flatten a b c dl ell X X la b c q el length List Int Succeeds if nt represents the number of elements of list List Can be used to create a list holding only variables merge List List2 List3 List and List2 are lists sorted to the standard order of terms see section 4 6 List3 will be unified with an ordered list holding both the elements of List and List2 Duplicates are not removed 4 30 Set Manipulation is_set Sef Succeeds if Set is a list see is_list 1 without duplicates list_to_set List Set Unifies Set with a list holding the same elements as List in the same order If list contains duplicates only the first is retained See also sort 2 Example list_to_set a b al X X a b intersection Set Set2 Set3 Succeeds if Set3 unifie
97. PL_get chars l s CVT_LIST flags provided flags contains no of the CVT_ flags int PL_get_integer term_t t int i If is a Prolog integer assign its value over i On 32 bit machines this is the same as PL_get_long but avoids a warning from the compiler See also PL_get_long int PL get_long term_t t long i If t is a Prolog integer assign its value over i Note that Prolog integers have limited value range If tis a floating point number that can be represented as a long this function succeeds as well int PL_get_pointer term_t t void ptr In the current system pointers are represented by Prolog integers but need some manip ulation to make sure they do not get truncated due to the limited Prolog integer range PL put pointer PL_get pointer guarantees pointers in the range of malloc are handled without truncating int PL_get float term_t t double f If t is a float or integer its value is assigned over f int PL_get functor term_t t functor_t f If t is compound or an atom the Prolog representation of the name arity pair will be assigned over f See also PL_get_name_arity and PL_is_functor int PL get name arity term_t t atom_t name int arity If is compound or an atom the functor name will be assigned over name and the arity over arity See also PL_get_functor andPL_is_functor int PL_get_module term_t t module_t module If tis an atom the system will lookup or create th
98. PL_raise_exception but returns using the C longjmp function to the in nermost PL_next_solution term_t PL_exception qid_t qid IfPL_next_solution fails this can be due to normal failure of the Prolog call or because an exception was raised using throw 1 This function returns a handle to the exception term if an exception was raised or 0 if the Prolog goal simply failed 6 6 10 Foreign code and Prolog threads If SWI Prolog has been build to support multi threading see section 4 39 all foreign code linked to Prolog should be thread safe reentrant or guarded in Prolog using with_mutex 2 from simulta neous access from multiple Prolog threads On Unix systems this generally implies the code should be compiled with the D_REENTRANT flag passed to the compiler Please note that on many Unix systems not all systemcalls and library functions are thread safe Consult your manual for details If you are using SWI Prolog as an embedded engine in a multi threaded application you can access the Prolog engine from multiple threads by creating an engine in each thread from which you call Prolog Without creating an engine a thread can only use functions that do not use the term_t type for example PL_new_atom Please note that the interface below will only work if threading in your application is based on the same thread library as used to compile SWI Prolog int PL_thread_self Returns the integer Prolog identifier of the engine or
99. Predicate Predicate Introduces a directive Introduces a directive DCGrammar rewrite head body separator SWI Prolog 5 0 Reference Manual Bibliography Anjewierden amp Wielemaker 1989 A Anjewierden and J Wielemaker Extensible objects ESPRIT BIM 1989 Bowen amp Byrd 1983 Bratko 1986 Clocksin amp Melish 1987 Deransart et al 1996 Hodgson 1998 Kernighan amp Ritchie 1978 O Keefe 1990 Pereira 1986 Qui 1997 Sterling amp Shapiro 1986 Project 1098 Technical Report UvA C1 TR 006a University of Amsterdam March 1989 BIM Prolog release 2 4 Everberg Belgium 1989 D L Bowen and L M Byrd A portable Prolog compiler In L M Pereira editor Proceedings of the Login Programming Workshop 1983 Lisabon Portugal 1983 Universidade nova de Lisboa I Bratko Prolog Programming for Artificial Intelligence Addison Wesley Reading Massachusetts 1986 W F Clocksin and C S Melish Programming in Prolog Springer Verlag New York Third Revised and Extended edi tion 1987 P Deransart A Ed Dbali and L Cervoni Prolog The Stan dard Springer Verlag New York 1996 Jonathan Hodgson validation suite for con formance with part 1 of the standard 1998 http www sju edu jhodgson pub suite tar gz B W Kernighan and D M Ritchie The C Programming Lan guage Prentice Hall Englewood Cliffs New Jersey 1978 R A O
100. SE NOTES 11 send Self append new D dialog send D append text_item predicate message Self list argl send new view below D list Self From name gt List predicates from specification catch term_to_atom Term From _ fail gt get Self member view V pce_open V write Fd set_output Fd listing Term close Fd send Self report error Syntax error pce_end_class test send new prolog_lister open Its 165 built in classes deal with the meta environment data representation and of course graphics The graphics classes concentrate on direct manipulation of diagrammatic representations Availability XPCE runs on most Unix platforms Windows 95 98 and Windows NT It has been connected to SWI Prolog SICStus and Quintus Prolog as well as some Lisp dialects and C The Quintus version is commercially distributed and supported as ProWindows 3 Info further information is available from http www swi psy uva nl projects xpce or by E mail to xpce request swi psy uva nl There are demo versions for Windows 95 98 NT and 1386 Linux available from the XPCE download page 1 6 Release Notes Collected release notes This section only contains some highlights Smaller changes to especially older releases have been removed For a complete log see the file ChangeLog from the distribution 1 6 1 Version 1 8 Release Notes Version 1 8 of
101. Switch off the debugger while executing the goal This option is used by many calls to hook predicates to avoid tracing the hooks An example is print 1 calling portray 1 from foreign code PL_Q_CATCH_EXCEPTION If an exception is raised while executing the goal do not report it but make it available for PL_exception PL_Q PASS_EXCEPTION As PL Q CATCH EXCEPTION but do not invalidate the exception term while calling PL_close_query This option is experimental The example below opens a query to the predicate is_a 2 to find the ancestor of for some name Do not pass the integer O for normal operation as this is interpreted as PL_Q_NODEBUG for backward compatibility reasons SWI Prolog 5 0 Reference Manual 174 CHAPTER 6 FOREIGN LANGUAGE INTERFACE char ancestor const char me term t a0 PL_new_term_refs 2 static predicate_t p if lp p PL_predicate is_a 2 database PL_put_atom_chars a0 me L_open_query NULL PL_Q NORMAL p a0 FU int PL_next_solution gid_t qid Generate the first next solution for the given query The return value is TRUE if a solution was found or FALSE to indicate the query could not be proven This function may be called repeatedly until it fails to generate all solutions to the query void PL_cut_query qid Discards the query but does not delete any of the data created by the query It just invalidate qid allowing for a new call to PL_open_query
102. The rules and remarks for hexadecimal specifications apply to octal specifications too but the maximum allowed number of octal digits is 3 character Any character immediately preceded by a and not covered by the above escape sequences is copied verbatim Thus AX is an atom consisting of a single and and both describe the atom with a single Character escaping is only available if the current prolog flag character escapes true is active default See current_prolog_flag 2 Character escapes conflict with writef 2 in two ways 40 is interpreted as decimal 40 by writef 2 but character escapes handling by read has already interpreted as 32 40 octal Also 1 is translated to a single 1 It is advised to use the more widely supported format 2 3 predicate instead If you insist upon using writef 2 either switch character_escapes to false or use double asinwritef 1 Syntax for non decimal numbers SWI Prolog implements both Edinburgh and ISO representations for non decimal numbers Accord ing to Edinburgh syntax such numbers are written as radix number where radix is a number between 2 and 36 ISO defines binary octal and hexadecimal numbers using 0 bxo number For example A is 0b100 Ox 00 isa valid expression Such numbers are always unsigned 2 16 System limits 2 16 1 Limits on memory areas SWI Prolog has a number of memory areas which are only enlar
103. URCE FILES 59 The predicate goal_expansion 2 is first called in the module that is being compiled and then on the user module Only goals apearing in the body of clauses when reading a source file are expanded using mech anism and only if they appear literally in the clause or as an argument to the meta predicates not 1 call 1 or fora11 2 A real predicate definition is required to deal with dynami cally constructed calls expand_goal Goall Goal2 This predicate is normally called by the compiler to perform preprocessing First it calls goal_expansion 2 If this fails it returns the first argument at_initialization Goal Register Goal to be run when the system initialises Initialisation takes place after reloading a qlf formerly wic file as well as after reloading a saved state The hooks are run in the order they were registered A warning message is issued if Goal fails but execution continues See also at_halt 1 at_halt Goal Register Goal to be run when the system halts The hooks are run in the order they were regis tered Success or failure executing a hook is ignored These hooks may not call ha1t 0 1 initialization Goal Call Goal and register it using at_initialization 1 Directives that do other things than creating clauses records flags or setting predicate attributes should normally be written using this tag to ensure the initialisation is executed when a saved system starts See also qsave_program
104. University of Amsterdam Dept of Social Science Informatics SWI Roeterstraat 15 1018 WB Amsterdam The Netherlands Tel 31 20 5256121 SWI Prolog 5 0 Reference Manual Updated for version 5 0 0 February 2002 Jan Wielemaker jan swi psy uva nl http www swi prolog org SWI Prolog is a Prolog implementation based on a subset of the WAM Warren Ab stract Machine SWI Prolog was developed as an open Prolog environment providing a powerful and bi directional interface to C in an era this was unknown to other Prolog implementations This environment is required to deal with XPCE an object oriented GUI system developed at SWI XPCE is used at SWI for the development of knowledge intensive graphical applications As SWI Prolog became more popular a large user community provided requirements that guided its development Compatibility portability scalability stability and provid ing a powerful development environment have been the most important requirements Edinburgh Quintus SICStus and the SO standard guide the development of the SWI Prolog primitives This document gives an overview of the features system limits and built in predicates Copyright 1990 2002 University of Amsterdam Contents 1 Introduction 1 1 1 2 1 3 1 4 13 1 6 1 7 a AA tary y a a e es bad eee a bw ee eld a 1 1 1 Other books about Prolog lt o sas a a aa ee ee h e SAUS po ao a ae Ws a E a aa Host wl Sh ak eae AA al we a C
105. Windows message box using a foreign function This example was tested using Windows NT and Microsoft Visual C 2 0 SWI Prolog 5 0 Reference Manual 152 CHAPTER 6 FOREIGN LANGUAGE INTERFACE include lt windows h gt include lt SWI Prolog h gt static foreign_t pl_say_hello term_t to char a if PL_get_atom_chars to amp a MessageBox NULL a DLL test MB _OK MB_TASKMODAL PL_succeed PL fail install _t install PL_register_foreign say_hello 1 pl_say_hello 0 Figure 6 1 MessageBox example in Windows NT 6 4 1 Static Linking Below is an outline of the files structure required for statically linking SWI Prolog with foreign ex tensions ldots p1 refers to the SWI Prolog home directory see current_prolog_flag 2 arch refers to the architecture identifier that may be obtained using current _prolog_flag 2 pl runtime arch libpl a SWI Library ldots pl include SWI Prolog h Include file ldots pl include SWI Stream h Stream I O include file ldots pl include SWI Exports Export declarations AIX only ldots pl include stub c Extension stub The definition of the foreign predicates is the same as for dynamic linking Unlike with dynamic linking however there is no initialisation function Instead the file ldots pl include stub c may be copied to your project and modified to define the foreign extensions Bel
106. _table write_table I IT V VT format da t 8 2f n I V write_table IT VT volatile Name Arity Declare that the clauses of specified predicates should not be saved to the program The volatile declaration is normally used to avoid that the clauses of dynamic predicates that represent data for the current session is saved in the state file 7 1 Limitations of qsave_program There are three areas that require special attention when using gsave_program 1 2 e If the program is an embedded Prolog application or uses the foreign language interface care has to be taken to restore the appropriate foreign context See section 7 2 for details e If the program uses directives goal lines that perform other actions then setting predi cate attributes dynamic volatile etc or loading files consult etc the directive may need to be prefixed with initialization l e Database references as returned by clause 3 recorded 3 etc are not preserved and may thus not be part of the database when saved 7 2 Runtimes and Foreign Code Some applications may need to use the foreign language interface Object code is by definition machine dependent and thus cannot be part of the saved program file To complicate the matter even further there are various ways of loading foreign code e Using the library shlib predicates This is the preferred way of dealing with foreign code It loads quickly
107. _transparent call_with_time_limit 2 call_with_time_limit Goal MaxTime alarm MaxTime catch Goal error signal alrm _ _ fail alarm 0 call_with_time_limit _ _ alarm 0 fail The signal names are defined by the C Posix standards as symbols of the form SIG_ SIGNAME The Prolog name for a signal is the lowercase version of SIGNAME The predicate current _signal 3 may be used to map between names and signals SWI Prolog 5 0 Reference Manual 4 11 THE BLOCK CONTROL STRUCTURE 73 Initially some signals are mapped to throw while all other signals are default The fol lowing signals throw an exception ill fpe segv pipe alrm bus xcpu xfsz and vtalrm current_signal Name Id Handler Enumerate the currently defined signal handling Name is the signal name d is the numerical identifier and Handler is the currently defined handler see on_signal 3 4 10 1 Notes on signal handling Before deciding to deal with signals in your application please consider the following e Portibility On MS Windows the signal interface is severely limited Different Unix brands support differ ent sets of signals and the relation between signal name and number may vary e Safety Signal handling is not completely safe in the current implementation especially if throw is used in combination with external foreign code The system will use the C longjmpO construct to direct control to the
108. _type Char Type Tests or generates alternative Types or Chars The character types are inspired by the standard C lt ctype h gt primitives SBUG Note that is both an atom an empty code character list The predicate atom_length 2 returns 2 for this atom SWI Prolog 5 0 Reference Manual 4 22 CLASSIFYING CHARACTERS 99 alnum Char is a letter upper or lowercase or digit alpha Char is a letter upper or lowercase csym Char is a letter upper or lowercase digit or the underscore _ These are valid C and Prolog symbol characters csymf Char is a letter upper or lowercase or the underscore _ These are valid first characters for C and Prolog symbols ascii Char is a 7 bits ASCII character 0 127 white Char is a space or tab E i white space inside a line entrl Char is an ASCII control character 0 31 digit Char is a digit digit Weigth Char is a digit with value Weigth Le char _type X digit 6 yields X 6 Useful for parsing numbers xdigit Weigth Char is a haxe decimal digit with value Weigth Le char type a xdigit X yields X 10 Useful for parsing numbers graph Char produces a visible mark on a page when printed Note that the space is not included lower Char is a lower case letter lower Upper Char is a lower case version of Upper Only true if Char is lowercase and Upper upper case to lower Upper Char is a lower case version of Upper For non letters
109. a Ba da ba hae eS aa 69 492 Theexcepuonm term oe ee ee a GEO ae ee 69 4 9 5 Printing Messages 1 end ad a a ee we A 70 4 10 Handing signals cios ee ee ee ee bE eee ee 71 4 10 1 Notes on signal handing cea oc ne 42 e 24 na 26 Be ba Pad eas 73 4 11 The block controlbstruct re os e e A oe Re we ee ew h 73 4 12 DOG Grimat fles e oe le ee eka aw Re ee ee ee 74 4 15 Database cea ba cono ba bbe ee ee a A ea 75 SWI Prolog 5 0 Reference Manual AT pe view ic a oe he ee ee es 77 4 13 2 Indexing databases o 0002564 040 a ee ee ee eae 77 4 14 Declaring predicates properties ooa ee 78 4 15 Examining th Program s e se ee ee ee e i a 79 416 Input and output os s iia ra AAA wee 4 82 4 16 1 Input and output using implicit source and destination 82 4 16 2 Explicit Input and Output Streams 4 83 4 16 3 Switching Between Implicit and Explicit VO 86 4 17 SAO OE steams os s isc ds aa e ee oS 87 4 13 Primitive character DO isc or al 88 4 19 Termreading and WINE e oe o e dress ada das 90 4 20 Analysing and Constructing Terms o e 94 4 21 Analysing and Constructing Atoms e e 96 4 22 Classifying CRaraci rS o oa i s eo sacia deaa dr eee eee a nan 98 4 23 Representing text im strings a coo a ee eee ee ER ee o a ee 100 o ap ay d e e el ede ee ee ee Ske Ba doe BE ee ee 101 4 25 Character Conversion ocr eco va e ne ee A a
110. a E 102 ts AMENE ot a a da Soe tad el 2 ee ew oe a a 103 421 Arthmetie PUDCUODS s os s el Pa ah we Oe a 104 4 28 Adding Arithmetic Functions 2 2 ee 107 4 29 List Manipulation acca ue a ae be ew ee ee d a 108 4 30 Set MamipulanGW gt lt io 024 ea eee dake ce POed are d baw Pe ae ea a 109 SL SOM LISS oa ke Cae Ee RRS EHS Ee a 110 4 32 Finding all Solutions toa Goal 2 2 s o so ee ee e d 110 4 33 Invoking Predicates on all Members of a List o 111 Ae FORA o a td BR a Ai E pe eee oe 112 4 35 Formatted Wie oers s bw a a a e eee eo a 112 AAS WEP EE 112 4552 FOMA oc ia sanka ee hw ae e dd ad ee ae 114 4 35 3 Programming Format oc o es corae a 6 bw te o a a eae 116 4 36 Termal Control so sais a ewe ay eee a 116 4 37 Operating System Interaction 2 2 ee 117 4 37 1 Dealing with time and date o s se s c ee ce a ee 119 4 37 2 Handling the menu in programPLWIN EXE 119 4 00 Pile System Interaccion A A A ea 120 4 39 Multi threading alpha code 2 2 2 a de we enseres Oe ee 123 4 39 1 Thread COMUNICACI N ss soisi a eaa a a T e a 125 4 39 2 Thread synchronisation o ss sa ss ecn cea e es 126 4 39 3 Thread support library threadutil a 127 4 39 4 Status of the thread implementation oosa a 128 440 User Toplevel Manipulation gt lt acasa 000 ee Be crer esene nua 128 4 41 Creating a Protocol of the User Interaction ooo e 129 4 42 Debugging and Tracing Pr
111. a POSIX file descriptor unify Integer with the descriptor number SWI Prolog extension used primarily for integration with foreign code See also Sfileno from SWI Stream h buffer Buffering SWI Prolog extension to query the buffering mode of this stream Buffering is one of full line or false See also open 4 current_stream Object Mode Stream The predicate current_stream 3 is used to access the status of a stream as well as to BUG Backtracking does not give other aliases SWI Prolog 5 0 Reference Manual 86 CHAPTER 4 BUILT IN PREDICATES generate all open streams Object is the name of the file opened if the stream refers to an open file an integer file descriptor if the stream encapsulates an operating system stream or the atom if the stream refers to some other object Mode is one of read or write set_stream_position Stream Pos Set the current position of Stream to Pos Pos is a term as returned by stream_property 2 using the posit ion Pos property See also seek 4 seek Stream 0ffset Method NewLocation Reposition the current point of the given Stream Method is one of bof current or eof indicat ing positioning relative to the start current point or end of the underlying object NewLocation is unified with the new offset relative to the start of the stream If the seek modifies the current location the line number and character position in the line are set to 0 If the stream ca
112. a module file These modules have been introduced on facilitate the development of large applications The modules are fully defined at load time of the application and normally will not change during execution Having the notion of a set of predicates as a self contained world can be attractive for other purposes as well For example assume an application that can reason about multiple worlds It is attractive to store the data of a particular world in a module so we extract information from a world simply by invoking goals in this world Dynamic modules can easily be created Any built in predicate that tries to locate a predicate in a specific module will create this module as a side effect if it did not yet exist Example assert world_a consistent world_a unknown _ fail SWI Prolog 5 0 Reference Manual 5 8 MODULE HANDLING PREDICATES 145 These calls create a module called world_a and make the call world_a consistent succeed Unde fined predicates will not start the tracer or autoloader for this module see unknown 2 Import and export from dynamically created world is arranged via the predicates import 1 and export 1 AS world_b export solve _ _ world_c import world_b solve _ _ exports solve 2 from world_b and import it to world_c AS 5 8 Module Handling Predicates This section gives the predicate definitions for the remaining built in predicates that handle modules modu
113. a string it is returned as a Prolog atom Other types are currently not sup ported The default root is HKEY_CURRENT_USER Other roots can be specified explicitely as SWI Prolog 5 0 Reference Manual 118 CHAPTER 4 BUILT IN PREDICATES HKEY_CLASSES_ROOT HKEY_CURRENT_USER HKEY_LOCAL_MACHINE or HKEY_USERS The example below fetches the extension to use for Prolog files see README TXT on the Win dows version win_registry_get_value HKEY_LOCAL_MACHINE Software SWI Prolog Ext pl getenv Name Value fileExtension Ext Get environment variable Fails silently if the variable does not exist Please note that environ ment variable names are case sensitive on Unix systems and case insensitive on Windows setenv Name Value Set environment variable Name and Value should be instantiated to atoms or integers The environment variable will be passed to she 11 0 2 and can be requested using getenv 2 They also influence expand_file_name 2 unsetenv Name Remove environment variable from the environment unix Command This predicate comes from the Quintus compatibility library and provides a partial implementa tion thereof It provides access to some operating system features and unlike the name suggests 1s not operating system specific Currently it is the only way to fetch the Prolog command line arguments Defined Command s are below system Command
114. acter conversion is only executed if the prolog flag char conversion is set SWI Prolog 5 0 Reference Manual 4 26 ARITHMETIC 103 to true and not inside quoted atoms or strings The initial table maps each character onto itself See also current_char_conversion 2 current_char_conversion CharIn CharOut Queries the current character conversion table See char_conversion 2 for details 4 26 Arithmetic Arithmetic can be divided into some special purpose integer predicates and a series of general pred icates for floating point and integer arithmetic as appropriate The integer predicates are as logical as possible Their usage is recommended whenever applicable resulting in faster and more logical programs The general arithmetic predicates are optionally compiled now see set _prolog_flag 2 and the O command line option Compiled arithmetic reduces global stack requirements and improves performance Unfortunately compiled arithmetic cannot be traced which is why it is optional The general arithmetic predicates all handle expressions An expression is either a simple number ora function The arguments of a function are expressions The functions are described in section 4 27 between Low High Value Low and High are integers High gt Low If Value is an integer Low lt Value lt High When Value is a variable it is successively bound to all integers between Low and High suce Intl Int2 Succeeds if nt
115. ading hooks for user extensions to the edit module For example XPCE provides the code below to load library swi edit containing definitions to locate classes and methods as well as to bind this package to the PceEmacs built in editor multifile prolog_edit load 0 prolog_edit load ensure_loaded library swi_edit listing Pred List specified predicates when an atom is given all predicates with this name will be listed The listing is produced on the basis of the internal representation thus losing user s layout and variable name information See also portray_clause 1 SWI Prolog 5 0 Reference Manual 62 CHAPTER 4 BUILT IN PREDICATES listing List all predicates of the database using listing 1 portray _clause Clause Pretty print a clause A clause should be specified as a term Head Body Facts are represented as Head true 4 5 Verify Type of a Term var Term Succeeds 1f Term currently is a free variable nonvar Term Succeeds if Term currently is not a free variable integer Term Succeeds if Term is bound to an integer float Term Succeeds if Term is bound to a floating point number number Term Succeeds if Term is bound to an integer or a floating point number atom Term Succeeds if Term is bound to an atom string Term Succeeds if Term is bound to a string atomic Term Succeeds if Term is bound to an atom string integer or floating poi
116. ading support is experimental and in some areas not safe SWI Prolog multithreading is based on standard C language multithreading support It is not like ParLog or other paralel implementations of the Prolog language Prolog threads have their own stacks and only share the Prolog heap predicates records flags and other global non backtrackable data SWI Prolog thread support is designed with the following goals in mind e Multi threaded server applications Todays computing services often focus on internet server applications Such applications of ten have need for communication between services and or fast non blocking service to multiple concurrent clients The shared heap provides fast communication and thread creation is rela tively cheap A Pentium 11 450 can create and join approx 10 000 threads per second on Linux 2 2 e Interactive applications Interactive applications often need to perform extensive computation If such computations are executed in a new thread the main thread can process events and allow the user to cancel the ongoing computation User interfaces can also use multiple threads each thread dealing with input from a distinct group of windows e Natural integration with foreign code Each Prolog thread runs in a C thread automatically making them cooperate with MT safe foreign code In addition any foreign thread can create its own Prolog engine for dealing with calling Prolog from C code thread_create Goal I
117. age Interface 149 61 Overview of the Interface ocios cewa cuca os eae 149 6 2 Linking For ign Modules lt s se ou copi hae oe OR A ee eed a od 149 6 2 1 What linking is provided 2 65 4 6 Ge he eee a 150 6 2 2 What kind of loading should I be using 4 150 6 3 Dynamic Linking of shared libraries o oo e 150 6 4 Using the library shlib for DLL and sofileS o o 151 GAl State A ad ie Swe Oe ee ee ee ee ee BS 152 6 3 lntertace Datatypes cu ok 4 6 Wk wood eo a ee Dee ee ke Se a 153 6 5 1 Type term_t areference to a Prolog term 153 6 52 Other toreipm interface types ou orcas as da era da a aa eee 155 0 06 The Foreign Include File ou sae woe ee a Geo ae we ee 156 6 6 1 Argument Passing and Control o o 156 6 6 2 Atoms and UnctorS o a s cse o 2 ee 157 6 6 3 Analysing Terms via the Foreign Interface o o 159 GGA Construclio Vertis as ck a a A ia heb 164 0653 Unityine data oo 6 ea a srt e baw ew Wee ee e 168 6 6 6 Calling Prolog irom aea ee ee a ta 172 6 6 Discarding Data 2 oc bw teh ea ee do Ee Le Ed eae 174 6 6 8 Foreign Code and Modules 2 60 ee ee ee ee 175 6 6 9 Prolog exceptions in foreign code 2 ee ee ee 176 6 6 10 Foreign code and Prolog threads 4 4 178 6 6 11 Miscellaneous c sse ac aior a Re ee ee a ee ee eae 179 6 6 12 Catch
118. al Bindings prompt Old New Set prompt associated with read 1 and its derivatives Old is first unified with the current prompt On success the prompt will be set to New if this is an atom Otherwise an error message is displayed A prompt is printed if one of the read predicates is called and the cursor is at the left margin It is also printed whenever a newline is given and the term has not been terminated Prompts are only printed when the current input stream is user prompt1 Prompt Sets the prompt for the next line to be read Continuation lines will be read using the prompt defined by prompt 2 4 20 Analysing and Constructing Terms functor Term Functor Arity Succeeds if Term is a term with functor Functor and arity Arity If Term is a variable it is unified with a new term holding only variables functor 3 silently fails on instantiation faults If Term is an atom or number Functor will be unified with Term and arity will be unified with the integer O zero arg Arg Term Value Term should be instantiated to a term Arg to an integer between 1 and the arity of Term Value is unified with the Arg th argument of Term Arg may also be unbound In this case Value will be unified with the successive arguments of the term On successful unifica tion Arg is unified with the argument number Backtracking yields alternative solutions The predicate arg 3 fails silently if Arg 0 or Arg gt arity and raises the exc
119. al if the parent goal is not owned by a foreign predicate argument Value is unified with the N th slot of the frame Argument 1 is the first argument of the goal Arguments above the arity refer to local variables Fails silently if N is out of range deterministic Succeeds if there are no choicepoints that are more recent than the parent frame B 2 Intercepting the Tracer prolog_trace_interception Port Frame PC Action Dynamic predicate normally not defined This predicate is called from the SWI Prolog debug ger just before it would show a port If this predicate succeeds the debugger assumes the trace action has been taken care of and continues execution as described by Action Otherwise the normal Prolog debugger actions are performed Port is one of call redo exit fail or unify Frame is an integer reference to the current local stack frame PC is the current value of the program counter relative to the start of the current clause or 0 if it is invalid for example because the current frame runs a for eign predicate or no clause has been selected yet Action should be unified with one of the atoms cont inue just continue execution ret ry retry the current goal or fail force the current goal to fail Leaving it a variable is identical to continue Together with the predicates described in section 4 42 and the other predicates of this chapter this predicate enables the Prolog user to define a complete new
120. ams con sists of a mixture of native code source compiled to machine instructions and virtual machine code Prolog source compiled to SWI Prolog virtual machine instructions covering both compiled SWI Prolog libraries and your compiled application For maximal coherence between free licenses we start with the two prime licenses from the Free Software Foundation the GNU General Public License GPL and the Lesser GNU General Public License LGPL after which we add a proven used by the GNU C compiler runtime library as well as the GNU ClassPath project exception to deal with the specific nature of compiled virtual machine code in a saved state D 1 The SWI Prolog Kernel and foreign libraries The SWI Prolog kernel and our foreign libraries are distributed under the LGPL A Prolog executable consists of the combination of these native code components and Prolog virtual machine code The SWI Prolog pl rc utility allows for disassembling and re assembling these parts a process satisfying article 6b of the LGPL Under the LGPL SWI Prolog can be linked to code distributed under arbitrary licenses provided a number of requirements are fullfilled The most important requirement is that if an application replies on a modified version of SWI Prolog the modified sources must be made available D 1 1 The SWI Prolog Prolog libraries Lacking a satisfactory technical solution to handle article 6 of the LGPL this license cannot be u
121. and ensures an accept able level of independence between the versions of the emulator and the foreign code loaded It works on Unix machines supporting shared libraries and library functions to load them Most modern Unixes as well as Win32 Windows 95 NT satisfy this constraint e Static linking This mechanism works on all machines but generally requires the same C compiler and linker to be used for the external code as is used to build SWI Prolog itself To make a runtime executable that can run on multiple platforms one must make runtime checks to find the correct way of linking Suppose we have a source file myextension defining the instal lation function install If this file is compiled into a shared library load_foreign_library 1 will load this library and call the installation function to initialise the foreign code If it is loaded as a static extension define install as the predicate insta11 0 SWI Prolog 5 0 Reference Manual 202 CHAPTER 7 GENERATING RUNTIME APPLICATIONS static foreign_t pl_install install PL_succeed PL_extension PL_extensions name arity function PL_FA_ lt flags gt install 0 pl_install 0 NULL O NULL QO terminat ing line y Now use the following Prolog code to load the foreign library load_foreign_extensions current_predicate install install static loaded install load_foreign_extensions sha
122. andard order of terms Terml Q lt Term2 Succeeds if both terms are equal 2 or Terml is before Term2 in the standard order of terms Terml Q gt Term2 Succeeds if Term is after Term2 in the standard order of terms Terml Q gt Term2 Succeeds if both terms are equal 2 or Terml is after Term2 in the standard order of terms compare Order Terml Term2 Determine or test the Order between two terms in the standard order of terms Order is one of lt gt or with the obvious meaning 4 7 Control Predicates The predicates of this section implement control structures Normally these constructs are translated into virtual machine instructions by the compiler It is still necessary to implement these constructs as true predicates to support meta calls as demonstrated in the example below The predicate finds all currently defined atoms of 1 character long Note that the cut has no effect when called via one of these predicates see 0 one_character_atoms As findall A current_atom A atom_length A 1 As fail Always fail The predicate fai1 0 is translated into a single virtual machine instruction true Always succeed The predicate t rue 0 is translated into a single virtual machine instruction repeat Always succeed provide an infinite number of choice points Cut Discard choice points of parent frame and frames created after the parent frame As of SWI Prolog 3 3 the semantics of the c
123. at also appears in Goal Item and Value are variables that also appear in Goal Item represents the request data as a Prolog atom The example below registers the Prolog current _prolog_flag Z2 predicate to be accessi ble from other applications The request may be given from the same Prolog as well as from another application dde_register_service prolog current_prolog_flag F V current_prolog_flag F V open_dde_conversation prolog current_prolog_flag Handle dde_request Handle home Home 2Upto version 3 4 5 this was a list of character codes As recent versions have atom garbage collection there is no need for this anymore SWI Prolog 5 0 Reference Manual 4 47 MISCELLANEOUS 137 close_dde_conversation Handle Home usr local lib p1 2 0 6 Handling DDE execute requests is very similar In this case the template is of the form Service Topic Item Passing a Value argument is not needed as execute requests either succeed or fail If Goal fails a not processed is passed back to the caller of the DDE request dde_unregister_service Service Stop responding to Service If Prolog is halted it will automatically call this on all open ser vices dde_current_service Service Topic Find currently registered services and the topics served on them dde_current_connection Service Topic Find currently open conversations 4 47 Miscellaneous dwim_match Atom
124. ating of machine independent saved states that load very quickly 1 6 5 Version 2 6 Release Notes Version 2 6 provides a stable implementation of the features added in the 2 5 x releases but at the same time implements a number of new features that may have impact on the system stability e 32 bit integer and double float arithmetic The biggest change is the support for full 32 bit signed integers and raw machine format double precision floats The internal data representation as well as the arithmetic instruction set and interface to the arithmetic functions has been changed for this Embedding for Win32 applications The Win32 version has been reorganised The Prolog kernel is now implemented as Win32 DLL that may be embedded in C applications Two front ends are provided one for window based operation and one to run as a Win32 console application Creating stand alone executables Version 2 6 0 can create stand alone executables by attaching the saved state to the emulator See qsave_program 2 1 6 6 Version 2 7 Release Notes Version 2 7 reorganises the entire data representation of the Prolog data itself The aim is to remove most of the assumption on the machine s memory layout to improve portability in general and enable embedding on systems where the memory layout may depend on invocation or on how the executable is linked The latter is notably a problem on the Win32 platforms Porting to 64 bit architectures is feasible now Fu
125. auses which is identical to call1 1 except when the argument is bound to the cut See 0 call Goal ExtraArgl Append ExtraArgl ExtraArg2 to the argument list of Goal and call the result For example call plus 1 2 X will call plus 3 binding X to 3 The call 2 construct is handled by the compiler which implies that redefinition as a predicate has no effect The predicates ca11 2 6 are defined as true predicates so they can be handled by interpreted code apply Term List Append the members of List to the arguments of Term and call the resulting term For example apply plus 1 2 X willcallplus 1 2 X apply 2is incorporated in the virtual machine of SWI Prolog This implies that the overhead can be compared to the overhead of cal11 1 New code should use call 2 if the length of List is fixed which is more widely supported and faster because there is no need to build and examine the argument list not Goal Succeeds when Goal cannot be proven Retained for compatibility only New code should use 1 once Goal Defined as once Goal Goal once 1 can in many cases be replaced with gt 2 The only difference is how the cut behaves see 0 The following two clauses are identical 1 a once b c d 2 a 2 Bb e gt de ignore Goal Calls Goal as once 1 but succeeds regardless of whether Goal succeeded or not Defined as ignore Goal Goal
126. ay be programmed using portray 1 The format of floating point numbers may be manipulated using the prolog_flag see current_prolog_flag 2 float_format Reading is sensitive to the prolog flag character_escapes which controls the interpretation of the character in quoted atoms and strings write_term 7erm Options The predicate write term 2 is the generic form of all Prolog term write predicates Valid options are quoted t rue or false If t rue atoms and functors that needs quotes will be quoted The default is false SWI Prolog 5 0 Reference Manual 4 19 TERM READING AND WRITING 91 character _escapes t rue or false If true and quoted true is active special characters in quoted atoms and strings are emitted as ISO escape sequences Default is taken from the reference module see below ignore_ops t rue or false If true the generic term representation functor args will be used for all terms Otherwise default operators list notation and 1 will be written using their special syntax module Module Define the reference module default user This defines the default value for the char acter_escapes option as well as the operator definitions to use See also op 3 numbervars t rue or false If true terms of the format VAR N where N is a positive integer will be written as a variable name The default is false portray t rue or false If true the hook portray 1 is called before p
127. be Bae GNU Emacs Taterace oi o ea a eee Dae we ek Se Online Help ooo kd La ew a eRe o bead bee ee ae Query SUDSUTUNONS ios ms da ee ba de a eae ee 2 7 1 Limitations of the History System o o Reuse of toplevel Bindings lt s s se a ke ew ee Se a Overview of the Debugger o sno a ca ee ee eee ES COMPUSO gt Gay a Parke OS 2H ad eG OMS eh eee bees Pad eas 2 10 1 During program development 2 10 2 Forronnine ihe result ou ee kd he we A a a Environment Control Prolog flags o o ee eee eee SWI Prolog 5 0 Reference Manual WN WN 00 00 o 11 11 11 12 12 13 13 13 13 14 14 14 15 16 16 Contents 3 2 12 An overview of hook predicates s ooe cos Sow he Oo ee ee a a a 36 2 13 Automatic loading of libraries sec ca mee en ee eee ees 37 214 Garbage Collecion co 2 24 ea a toaa ege ara a a dad 38 ear SYMON NOS A 39 215 1 ISO Syntax Suppor see a ead ed dade ee Dawe bee oa i 39 216 System S ociosa ee ee we aok a ee ha ed i a 40 216 1 Limits oa Memory areas cua a we a ee a da a ae i 40 DADE SOMES LAH lo eae eo He aR a eo Be wl Kare hy EA gs we a 41 216 3 Reserved Names e meesi a a dd a a 41 3 Initialising and Managing a Prolog Project 43 31 The projectsourcefiles i a age E ia Be ea 43 SLI File Names a d Locations css a ee eed eee ee 43 3 1 2 Project Special Files oa oe A RD ee ee ee ES 44 3a Using modules rer Vand vac eG a 8 bees a
128. below allow for registering license requirements for Prolog files and foreign modules The predicate eval_license 0 reports which components from the currenly configured system are dis tributed under copy left and open source enforcing licenses the GPL and therefore must be replaced before distributing linked applications under non free license conditions eval_license Evaluate the license conditions of all loaded components If the system contains one or more components that are licenced under GPL like restrictions the system indicates this program may only be distributed under the GPL license as well as which components prohibit the use of other license conditions license Licenseld Component Register the fact that Component is distributed under a license identified by Licenseld The most important Licenseld s are swipl Indicates this module is distributed under the GNU General Public License GPL with the SWI Prolog exception As a special exception if you link this library with other files compiled with SWI Prolog to produce an executable this library does not by itself cause the resulting executable to be covered by the GNU General Public License This exception does not however invalidate any other reasons why the executable file might be covered by the GNU General Public License On the Unix version the default toplevel uses the GNU readline library for command line editing This library is distributed under the GPL
129. bility Query set current type in module Declare a module Indicate module based meta predicate Sort do not remove duplicates Indicate distributed definition of predicate Create a thread synchronisation device Destroy a mutex Become owner of a mutex Become owner of a mutex non blocking Release ownership of mutex Release ownership of all mutexes Convert between atom and list of ASCII characters Generate a newline Generate a newline on a stream Disable debugging Disable the graphical debugger Type check for bound term Disable logging of user interaction Remove spy point Remove all spy points Negation by failure argument not provable Same as 1 Stop tracing Do not debug argument goal N th element of a list O based N th element of a list 1 based SWI Prolog 5 0 Reference Manual E 1 PREDICATES 231 nth_clause 3 number 1 number_chars 2 number_codes 2 numbervars 4 on_signal 3 once l op 3 open 3 open 4 open_dde_conversation 3 open_null_stream 1 open_resource 3 open_shared_object 2 open_shared_object 3 peek_byte 1 peek_byte 2 peek_char 1 peek_char 2 peek_code 1 peek_code 2 phrase 2 phrase 3 please 3 plus 3 portray 1 portray clause 1 predicate_property 2 predsort 3 preprocessor 2 print 1 print 2 print_message 2 print_message_lines 3 profile 3 profile _count 3 profiler 2 prolog 0 prolog_current_frame l prolog_edit locate 2 prolog_edit locate 3 prolog_edit ed
130. browse pl to the autoloadable predicates for the XPCE package make_library_index 1 RL y trace browse pl 2 14 Garbage Collection SWI Prolog provides garbage collection last call optimization and atom garbage collection These features are controlled using prolog flags see current prolog flag 2 SWI Prolog 5 0 Reference Manual 2 15 SYNTAX NOTES 39 2 15 Syntax Notes SWI Prolog uses standard Edinburgh syntax A description of this syntax can be found in the Prolog books referenced in the introduction Below are some non standard or non common constructs that are accepted by SWI Prolog e 0 char This construct is not accepted by all Prolog systems that claim to have Edinburgh compatible syntax It describes the ASCII value of char To test whether C is a lower case character one can use between 0 a 0 z C TA E 1 ES The comment statement can be nested This is useful if some code with comment statements in 1t should be commented out 2 15 1 ISO Syntax Support SWI Prolog offers ISO compatible extensions to the Edinburgh syntax Character Escape Syntax Within quoted atoms using single quotes atom special characters are represented using escape sequences An escape sequence is lead in by the backslash 1 character The list of escape sequences 1s compatible with the ISO standard but contains one extension and the interpretation of numerically spec
131. bset 2 110 subtract 3 109 succ 2 103 swi edit library 61 swi_help library 22 swritef 2 113 swritef 3 113 TAB completion 46 tab 1 88 tab 2 88 tan 1 106 tell 1 14 82 83 telling 1 82 83 122 term_expansion 2 36 58 term_to_atom 2 97 term_expansion 2 37 55 58 60 128 term_position 3 85 term_to_atom 2 90 171 thread_at_exit 1 125 thread_create 3 123 thread_exit 1 124 thread_get_message 1 125 thread_join 2 124 thread_peek_message 1 125 thread_self 1 124 thread_send_message 2 125 thread_signal 2 125 thread_exit 1 124 thread_join 2 123 124 thread_peek_message 1 125 SWI Prolog 5 0 Reference Manual 252 INDEX thread_self 1 125 thread_signal 2 125 127 threads 0 127 throw 1 13 25 68 73 124 126 128 177 178 215 time 1 107 133 time_file 2 120 time_file 2 119 tmp_file 2 122 told 0 83 trace 0 25 51 52 126 129 130 182 trace 1 35 130 trace 2 130 tracing O 129 trim_stacks 0 134 trim_stacks 0 32 134 true O 34 64 67 truncate 1 105 tty_get_capability 3 116 tty_goto 2 116 tty_put 2 116 tty_size 2 117 tty_get_capability 2 117 tty_get_capability 3 116 tty_goto 2 117 tty_put 2 117 tty_size 2 117 ttyflush O 88 113 unify_with_occurs_check 2 63 union 3 110 unix 36 unix 1 15 118 unknown 2 37 78 131 145 207 unload_foreign_library 1 151 unsetenv 1 118 update view 77 URL 117 url library 209 210
132. called XPCE Anjewierden amp Wielemaker 1989 XPCE allows you to implement graphical user interfaces that are source code compatible over Unix X11 and Win32 Windows 95 and NT 1 5 The XPCE GUI system for Prolog The XPCE GUI system for dynamically typed languages has been with SWI Prolog for a long time It is developed by Anjo Anjewierden and Jan Wielemaker from the department of SWI University of Amsterdam It aims at a high productive development environment for graphical applications based on Prolog Object oriented technology has proven to be a suitable model for implementing GUIs which typically deal with things Prolog is not very good at event driven control and global state With XPCE we designed a system that has similar characteristics that make Prolog such a powerful tool dynamic typing meta programming and dynamic modification of the running system XPCE is an object system written in the C language It provides for the implementation of meth ods in multiple languages New XPCE classes may be defined from Prolog using a simple natural syntax The body of the method is executed by Prolog itself providing a natural interface between the two systems Below is a very simple class definition pce_begin_class prolog_lister frame List Prolog predicates initialise Self gt As the C constructor send Self send_super initialise Prolog Lister SWI Prolog 5 0 Reference Manual 1 6 RELEA
133. cases The directory name of is itself and the directory name if File does not contain any characters is file base_name File BaseName Extracts the filename part from a path specification If File does not contain any directory separators File is returned same _file File File2 Succeeds if both filenames refer to the same physical file That is if File and File2 are the same string or both names exist and point to the same file due to hard or symbolic links and or relative vs absolute paths exists_directory Directory Succeeds if Directory exists This does not imply the user has read search and or write permis sion for the directory delete _file File Remove File from the file system rename _file File File2 Rename File into File2 Currently files cannot be moved across devices size file File Size Unify Size with the size of File in characters time_file File Time Unify the last modification time of File with Time Time is a floating point number expressing the seconds elapsed since Jan 1 1970 See also convert_time 2 8 and get_time 1 absolute _file_ name File Absolute Expand a local file name into an absolute path The absolute path is canonised ref erences to and are deleted This predicate ensures that expanding a file name it returns the same absolute path regardless of how the file is addressed SWI Prolog SWI Prolog 5 0 Reference Manual 4 38 FILE SYSTE
134. cated thread which can even be the message queue of itself see thread self 1 Any term can be placed in a message queue but note that the term is copied to to receiving thread and variable bindings are thus lost This call returns immediately thread get _message Term Examines the thread message queue and if necessary blocks execution until a term that unifies to Term arrives in the queue After a term from the queue has been unified unified to Term this term is deleted from the queue and this predicate returns Please note that not unifying messages remain in the queue After the following has been executed thread 1 has the term b gnu in its queue and continues execution using A is gnat lt thread 1 gt thread_get_message a A lt thread 2 gt thread_send_message b gnu thread_send_message a gnat See also thread_peek_message 1 thread_peek_message 7Term Examines the thread message queue and compares the queued terms with Term until one unifies or the end of the queue has been reached In the first case the call succeeds possibly instantiat ing Term If no term from the queue unifies this call fails thread signal ThreadId Goal Make thread ThreadId execute Goal at the first opportunity In the current implementation this implies at the first pass through the Call port The predicate thread_signal 2 itself places Goal into the signalled thread s signal queue and returns immediately Signal
135. cation That is a variable only unifies to a term if this term does not contain the variable itself To illustrate this consider the two goals below 1 A f A A E L L f L L L 2 unify_ with_occurs_check A f A No Le the first creates a cyclic term which is printed as an infinitely nested 1 term see the max_depth option of write_term 2 The second executes logically sound unification and thus fails Terml X Term2 Equivalent to Terml Term2 Terml Term2 Succeeds if Term is structurally equal to Term2 Structural equivalence is weaker than equiv alence 2 but stronger than unification 2 Two terms are structurally equal if their tree representation is identical and they have the same pattern of variables Examples Strings might be considered atoms in future versions See also section 4 23 Tn fact the variables are compared on their dereferenced addresses Variables living on the global stack are always lt than variables on the local stack Programs should not rely on the order in which variables are sorted SWI Prolog 5 0 Reference Manual 64 CHAPTER 4 BUILT IN PREDICATES a A false A B true x A A x B C false x A A x B B true x A B x C D true Terml Term2 Equivalent to Terml Term2 Terml Q lt Term2 Succeeds if Term is before Term2 in the st
136. ce to the tail to t int PL_get_nil term_t 1 Succeeds if represents the atom An example defining write 1 in C Figure 6 3 shows a simplified definition of write 1 to illustrate the described functions This sim plified version does not deal with operators It is called display 1 because it mimics closely the behaviour of this Edinburgh predicate 6 6 4 Constructing Terms Terms can be constructed using functions from the PL put_ and PL_cons _ families This approach builds the term inside out starting at the leaves and subsequently creating compound SWI Prolog 5 0 Reference Manual 6 6 THE FOREIGN INCLUDE FILE 165 foreign_t pl_display term_t t t functor t functor int arity len n char s switch PL_term_type t case PL_VARIABLE case PL_ATOM case PL_INTEGER case PL_FLOAT PL_get_chars t amp s CVT_ALL Sprintf Ss s break case PL STRING PL_get_string_chars t amp s len SprintE USES Ss break Case PL_TERM termt a PL _new_term_ref PL_get_name_arity t name amp arity Sprintf Ss PL_atom_chars name for n 1 n lt arity n PL_get_arg n t a if n gt 1 Sprint m7 pl_display a Sprint 3 break default PL_fail should not happen PL_succeed Figure 6 3 A Foreign definition of display 1 SWI Prolog 5 0 Reference Manual 166 CHAPTER 6 FOREIGN LANGUAGE INTERFACE terms Al
137. ceeds if File is a loaded Prolog source file File is the absolute and canonical path to the source file SWI Prolog 5 0 Reference Manual 58 CHAPTER 4 BUILT IN PREDICATES source file Pred File Is true if the predicate specified by Pred was loaded from file File where File is an absolute path name see absolute file name 2 Can be used with any instantiation pattern but the database only maintains the source file for each predicate See also clause_property 2 prolog load_context Key Value Determine loading context The following keys are defined Key Description module Module into which file is loaded file File loaded stream Stream identifier see current _input 1 directory Directory in which File lives term position Position of last term read Term of the form Sstream_position 0 Line 0 0 0 Quintus compatibility predicate See also source_location 2 source location File Line If the last term has been read from a physical file i e not from the file user or a string unify File with an absolute path to the file and Line with the line number in the file New code should use prolog_load_context 2 term_expansion Terml Term2 Dynamic predicate normally not defined When defined by the user all terms read during consulting that are given to this predicate If the predicate succeeds Prolog will assert Term2 in the database rather then the read term Term Term2
138. cense for current file Define license for named module SWI Prolog 5 0 Reference Manual 230 APPENDIX E SUMMARY limit_stack 2 line_count 2 line_position 2 list_to_set 2 listing O listing 1 load_files 2 load_foreign_library 1 load foreign library 2 make O make directory 1 make_fat_filemap 1 make_library _index 1 make library _index 2 maplist 3 member 2 memberchk 2 merge 3 merge_set 3 message _hook 3 message_to_string 2 meta_predicate 1 module 1 module 2 module_transparent 1 msort 2 multifile 1 mutex _create 1 mutex_destroy 1 mutex_lock 1 mutex_trylock 1 mutex _unlock 1 mutex_unlock_all 0 name 2 nl 0 nl 1 nodebug 0 noguitracer O nonvar l noprotocol 0 nospy 1 nospyall 0 not 1 notrace 0 notrace 1 nth0 3 nth1 3 Limit stack expansion Line number on stream Character position in line on stream Remove duplicates List program in current module List predicate Load source files with options library shlib Load shared library so file library shlib Load shared library so file Reconsult all changed source files Create a folder on the file system Win32 Create file containing non FAT filenames Create autoload file INDEX pl Create selective autoload file INDEX pl Transform all elements of a list Element is member of a list Deterministic member 2 Merge two sorted lists Merge two sorted sets Intercept print message 2 Translate message term to string Quintus compati
139. cessary to enable it during debugging abort_with_exception bool changeable Determines how abort 0 is realised See the description of abort 0 for details debug_on_error bool changeable If t rue start the tracer after an error is detected Otherwise just continue execution The goal that raised the error will normally fail See also fileerrors 2 and the prolog flag report_error May be changed Default is t rue except for the runtime version report_error bool changeable If true print error messages otherwise suppress them May be changed See also the debug_on_error prolog flag Default is t rue except for the runtime version verbose Atom changeable This flags is used by print_message 2 If its value is silent messages of type informational and banner are supressed The q switches the value from the initial normal to silent SWI Prolog 5 0 Reference Manual 36 CHAPTER 2 OVERVIEW file name_variables bool changeable If true default false expand varname and in arguments of builtin predicates that accept a file name open 3 exists_file 1 access_file 2 etc The pred cate expand_file_name 2 should be used to expand environment variables and wild card patterns This prolog flag is intended for backward compatibility with older versions of SWI Prolog unix bool If true the operating system is some version of Unix Defined if the C compiler used to compile this version of SWI Prolog either d
140. ch data is referenced by C code As all Prolog data known by C is referenced through term references term_t Prolog has all information necessary to perform its memory management without special precautions from the C programmer 6 5 2 Other foreign interface types atom_t An atom in Prologs internal representation Atoms are pointers to an opaque structure They are a unique representation for represented text which implies that atom A represents the same text as atom B if and only if A and B are the same pointer Atoms are the central representation for textual constants in Prolog The transformation of C a character string to an atom implies a hash table lookup If the same atom is needed often it is advised to store its reference in a global variable to avoid repeated lookup functor_t A functor is the internal representation of a name arity pair They are used to find the name and arity of a compound term as well as to construct new compound terms Like atoms they live for the whole Prolog session and are unique predicate_t Handle to a Prolog predicate Predicate handles live forever although they can loose their definition gid_t Query Identifier Used by PL_open_query PL_next_solution PL_close_query to handle backtracking from C fid_t Frame Identifier Used by PL_open_foreign_frame PL_close_foreign_frame module_t A module is a unique handle to a Prolog module Modules are used only to call predicates in a specif
141. cking option option clears it and option succeeds or fails according to the current setting consult 1 and derivatives resets the style checking options to their value before loading the file If for example a file containing long atoms should be loaded the user can start the file with style_check atom Currently available options are Name Default Description singleton on read_clause 1 used by consult 1 warns on vari ables only appearing once in a term clause which have a name not starting with an underscore atom on o read 1 and derivatives will produce an error message on quoted atoms or strings longer than 5 lines dollar off Accept dollar as a lower case character thus avoiding the need for quoting atoms with dollar signs System mainte nance use only discontiguous on Warn if the clauses for a predicate are not together in the same source file string off Backward compatibility See the prolog flag dou ble_quotes current_prolog_flag 2 4 43 Obtaining Runtime Statistics statistics Key Value Unify system statistics determined by Key with Value The possible keys are given in the ta ble 4 2 The last part of the table contains keys for compatibility to other Prolog implementa tions Quintus for improved portability Note that the ISO standard does not define methods to collect system statistics SWI Prolog 5 0 Reference Manual CHAPTER 4 BUILT IN PR
142. code 1 89 get_code 2 89 get_code 1 2 54 get_single_char 1 21 35 get_time 1 119 120 getenv 2 118 global_url 3 211 GNU Emacs 22 go 0 19 SWI Prolog 5 0 Reference Manual 246 INDEX goal_expansion 2 37 58 goal_expansion 2 58 59 Graphics 10 ground 1 62 78 GUI 10 guitracer 0 16 51 52 129 halt 0 27 128 halt 1 128 182 226 halt O 1 59 hash_term 2 78 hash_term 2 77 help O 22 37 203 216 help 1 22 37 216 helpidx library 22 hooks 36 HTTP 210 http_location 2 211 IDE 43 ignore 1 66 immediate update view 77 import 1 140 141 145 include 1 54 56 index 1 77 78 80 initialization 1 59 150 183 201 install O 201 int_to_atom 2 97 int_to_atom 3 97 integer 1 62 105 interactor 0 86 127 intersection 3 109 is 2 34 103 105 107 is_absolute_file_name 1 121 is_list 1 108 is_set 1 109 is_list 1 109 keysort 2 110 last 2 109 leash 1 25 131 length 2 109 library _directory 1 36 56 library _directory 1 37 38 55 license 1 224 license 2 223 224 likes 2 17 limit_stack 2 134 limit_stack 2 134 line_count 2 87 line_position 2 87 line_count 2 116 line_position 2 116 list_autoload O 208 list_redefined 0 208 list_to_set 2 109 list_undefined O 207 list_autoload O 207 list_redefined 0 207 list_undefined O 207 208 listing O 62 listing 1 26 61 62 load_files 2 55 load_foreign_library 1 151 load_foreign_library 2 1
143. compatible editing of input lines will not be linked to the system e No tracer The tracer and all its options are removed making the system a little faster too e No profiler profile 3 and friends are not supported This saves some space and provides better perfor mance e No interrupt Keyboard interrupt Control C normally is not rebound and will normally terminate the appli cation SWI Prolog 5 0 Reference Manual 206 CHAPTER 7 GENERATING RUNTIME APPLICATIONS e current_prolog_flag runtime true succeeds This may be used to verify your application is running in the runtime environment rather than the development environment e clause 2 3 do not work on static predicates This prolog flag inhibits listing your program It is only a very limited protection however The following fragment is an example for building the runtime environment in env HOME lib rt p1 3 2 0 If possible the shared library interface should be configured to ensure it can serve a large number of applications cd p1 3 2 0 mkdir runtime cd runtime src configure enable runtime prefix SHOME make make rt install AP A A Ae AP The runtime directory contains the components listed below This directory may be tar ed and shipped with your application README RT Info on the runtime environment bin arch pl The emulator itself man pl 1 Manual page for pl swipl pointer to the home directory
144. cts Module Name Arity Refers a predicate module Module Refers to a module file Path Refers to a file source file Path Refers to a loaded source file Ambiguous specifications Name Arity Refers this predicate in any module Name Refers to 1 named predicate in any module with any ar ity 2 a source file or 3 a module edit Specification First exploits prolog_edit locate 3 to translate Specification into a list of Locations If there is more than one hit the user is allows to select from the found locations Finally prolog_edit edit_source 1 is used to invoke the user s preferred editor prolog_edit locate Spec FullSpec Location Where Spec is the specification provided through edit 1 This multifile predicate is used to enumerate locations at with an object satisfying the given Spec can be found FullSpec is unified SWI Prolog 5 0 Reference Manual 4 4 LISTING AND EDITOR INTERFACE 61 with the complete specification for the object This distinction is used to allow for ambiguous specifications For example if Spec is an atom which appears as the base name of a loaded file and as the name of a predicate FullSpec will be bound to i1e Path or Name Arity Location is a list of attributes of the location Normally this list will contain the term file File and if available the term 1ine Line prolog_edit locate Spec Location Same as prolog_edit locate 3 but
145. current prolog flag 2 and set_prolog flag 2 The library library oackcomp provides definitions for feature 2 and set_feature 2 so no source has to be updated Accessing command line arguments This used to be provided by the undocumented argv 1 and Quintus compatible library unix 1 Now there is also documented current_prolog_flag argy Argv e dup_stream 2 Has been deleted New stream aliases can deal with most of the problems for which dup_stream 2 was designed and dup 2 from the clib package can with most others e 0p 3 Operators are now local to modules This implies any modification of the operator table does not influence other modules This is consistent with the proposed ISO behaviour and a necessity to have any usable handling of operators in a multi threaded environment set_prolog flag character_escapes Bool This prolog flag is now an interface to changing attributes on the current source module effec tively making this flag module local as well This is required for consistent handling of sources written with ISO obligatory character escape sequences together with old Edinburgh code e current _stream 3 and stream position These predicates have been moved to library quintus 1 6 12 Version 3 4 Release Notes The 3 4 release is a consolidation release It consolidates the improvements and standard conformance of the 3 3 releases This version is closely compatible with the 3 3 version except for one important
146. d Options Create a new Prolog thread and underlying C thread and start it by executing Goal If the thread is created succesfully the thread identifier of the created thread is unified to Jd Options is a list of options Currently defined options are local K Bytes Set the limit to which the local stack of this thread may grow If omited the limit of the calling thread is used See also the L commandline option global K Bytes Set the limit to which the global stack of this thread may grow If omited the limit of the calling thread is used See also the G commandline option trail K Bytes Set the limit to which the trail stack of this thread may grow If omited the limit of the calling thread is used See also the T commandline option argument K Bytes Set the limit to which the argument stack of this thread may grow If omited the limit of the calling thread is used See also the A commandline option alias AliasName Associate an alias name with the thread This named may be used to refer to the thread and remains valid until the thread is joined see thread_join 2 SWI Prolog 5 0 Reference Manual 124 CHAPTER 4 BUILT IN PREDICATES detached Bool If false default the thread can be waited for using thread_Join 2 thread_join 2 must be called on this thread to reclaim the all resources associated to the thread If t rue the system will reclaim all associated resources automatically af ter the thread fi
147. d See also predicate property 2 SWI Prolog 5 0 Reference Manual 146 CHAPTER 5 USING MODULES default_module Module Default Succesively unifies Default with the module names from which a call in Module attempts to use the definition For the module user this will generate user and system For any other module this will generate the module itself followed by user and system module Module The call module Module may be used to switch the default working module for the inter active toplevel see prolog 0 This may be used to when debugging a module The example below lists the clauses of file_of label 2 in the module tex 1 module tex Yes tex 2 listing file_of_label 2 5 9 Compatibility of the Module System The principles behind the module system of SWI Prolog differ in a number of aspects from the Quin tus Prolog module system e The SWI Prolog module system allows the user to redefine system predicates e All predicates that are available in the system and user modules are visible in all other modules as well e Quintus has the meta_predicate 1 declaration were SWI Prolog has the module_transparent 1 declaration The meta predicate 1 declaration causes the compiler to tag arguments that pass module sensitive information with the module using the 2 operator This approach has some disadvantages e Changing a meta predicate declaration implies all predicates calling the predicate ne
148. d C string flags is a bitwise disjunction from two groups of constants The first specifies which term types should converted and the second how the argument is stored Below is a specification of these constants BUF_RING implies if the data is not static as from an atom the data is copied to the next buffer from a ring of 16 buffers This is a convenient way of converting multiple arguments passed to a foreign predicate to C strings If BUF_MALLOC is used the data must be freed using free when not needed any longer SWI Prolog 5 0 Reference Manual 162 CHAPTER 6 FOREIGN LANGUAGE INTERFACE CVT_ATOM Convert if term is an atom CVT_STRING Convert if term is a string CVT_LIST Convert if term is a list of integers between 1 and 255 CVT_INTEGER Convert if term is an integer using 3d CVT_FLOAT Convert if term is a float using f CVT_NUMBER Convert if term is a integer or float CVT_ATOMIC Convert if term is atomic CVT_VARIABLE Convert variable to print name CVT_WRITE Convert any term that is not converted by any of the other flags using write 1 If no BUF_ is provided BUF _RING is implied CVT_ALL Convert if term is any of the above except for CVT_VARIABLE and CVT_WRITE BUF_DISCARDABLE Data must copied immediately BUF_RING Data is stored in a ring of buffers BUF MALLOC Data is copied to a new buffer returned by malloc 3 int PL_get_list_chars term_t l char s unsigned flags Same as
149. d Value will be a string CF_TEXT data in DDE parlance representing that data if the request is successful If unsuccessful Value will be unified with a term of form error Reason identifying the problem This call uses SWI Prolog string objects to return the value rather then atoms to reduce the load on the atom space See section 4 23 for a discussion on this data type dde_execute Handle Command Request the DDE server to execute the given command string Succeeds if the command could be executed and fails with error message otherwise dde_poke Handle Item Command Issue a POKE command to the server on the specified Item Command is passed as data of type CF TEXT 4 46 2 DDE server mode The autoload library dde defines primitives to realise simple DDE server applications in SWI Prolog These features are provided as of version 2 0 6 and should be regarded prototypes The C part of the DDE server can handle some more primitives so if you need features not provided by this interface please study library dde dde_register_service Template Goal Register a server to handle DDE request or DDE execute requests from other applications To register a service for a DDE request Template is of the form Service Topic Item Value Service is the name of the DDE service provided like progman in the client example above Topic is either an atom indicating Goal only handles requests on this topic or a variable th
150. d using character codes Character codes are integer indices into a specific character set Traditionally the character set was 7 bits US ASCII 8 bit character sets have been allowed for a long time providing support for national character sets of which iso latin 1 ISO 8859 1 is applicable to many western languages Text files are supposed to represent a sequence of character codes ISO Prolog introduces three types two of which are used for characters and one for accessing binary streams see open 4 These types are e code A character code is an integer representing a single character As files may use multi byte encoding for supporting different character sets utf 8 encoding for example reading a code from a text file is in general not the same as reading a byte e char Alternatively characters may be represented as one character atoms This is a very natural rep resentation hiding encoding problems from the programmer as well as providing much easier debugging e byte Bytes are used for accessing binary streams The current version of SWI Prolog does not provide support for multi byte character encoding This implies for example that it is not capable of breaking a multi byte encoded atom into characters For SWI Prolog bytes and codes are the same and one character atoms are simple atoms containing one byte To ease the pain of these multiple representations SWI Prolog s built in predicates dealing with character data work
151. d using the Windows conventions a letter prefixed with amp is underlined and defines the associated accelerator key Before is the label before which this one must be inserted Using adds the new entry at the end right For example the call below adds a Application entry just before the Help menu win_insert_menu amp Application amp Help win_insert_menu_item Pulldown Label Before Goal Add an item to the named Pulldown menu Label and Before are handled as in win_insert_menu 2 but the label inserts a separator Goal is called if the user selects the item SWI Prolog 5 0 Reference Manual 120 CHAPTER 4 BUILT IN PREDICATES 4 38 File System Interaction access_file File Mode Succeeds if File exists and can be accessed by this prolog process under mode Mode Mode is one of the atoms read write append exist none or execute File may also be the name of a directory Fails silently otherwise access_file File none simply succeeds without testing anything If Mode is write or append this predicate also succeeds if the file does not exist and the user has write access to the directory of the specified location exists _file File Succeeds when File exists This does not imply the user has read and or write permission for the file file_directory_name File Directory Extracts the directory part of File The returned Directory name does not end in There are two special
152. de Term references are obtained in any of the following ways e Passed as argument The C functions implementing foreign predicates are passed their arguments as term references These references may be read or unified Writing to these variables causes undefined behaviour e Created by PL_new_term_ref A term created by PL_new_term_ref is normally used to build temporary terms or be written by one of the interface functions For example PL_get_arg writes a reference to the term argument in its last argument e Created by PL_new_term_refs int n This function returns a set of term refs with the same characteristics as PL_new_term_ref See PL_open_query e Created by PL_copy_term_ref term_t t Creates a new term reference to the same term as the argument The term may be written to See figure 6 3 Term references can safely be copied to other C variables of type term_t but all copies will always refer to the same term term t PL new term ref Return a fresh reference to a term The reference is allocated on the local stack Allocating a term reference may trigger a stack shift on machines that cannot use sparse memory manage ment for allocation the Prolog stacks The returned reference describes a variable term_t PL_new_term_refs int n Return n new term references The first term reference is returned The others are t 1 t 2 etc There are two reasons for using this function PL_open_query expects th
153. de Value WwwFormEncoded Translate between a string literal and the x www form encoded representation used in path and search specifications of the HTTP protocol Encoding implies mapping space to preserving alpha numercial characters map newlines to 0D OA and anything else to XX When decoding newlines appear as a single newline 10 character SWI Prolog 5 0 Reference Manual Hackers corner This appendix describes a number of predicates which enable the Prolog user to inspect the Prolog environment and manipulate or even redefine the debugger They can be used as entry points for experiments with debugging tools for Prolog The predicates described here should be handled with some care as it is easy to corrupt the consistency of the Prolog system by misusing them B 1 Examining the Environment Stack prolog_current_frame Frame Unify Frame with an integer providing a reference to the parent of the current local stack frame A pointer to the current local frame cannot be provided as the predicate succeeds deterministi cally and therefore its frame is destroyed immediately after succeeding prolog frame_attribute Frame Key Value Obtain information about the local stack frame Frame Frame is a frame reference as obtained through prolog_current_frame 1 prolog_trace_interception 4 or this predi cate The key values are described below alternative Value is unified with an integer reference to the local stack fram
154. debugger in Prolog Besides this it enables the Prolog programmer monitor the execution of a program The example below records all goals trapped by the tracer in the database prolog_trace_interception Port Frame _PC continue prolog_frame_attribute Frame goal Goal prolog_frame_attribute Frame level Level recordz trace trace Port Level Goal To trace the execution of go this way the following query should be given trace go notrace SWI Prolog 5 0 Reference Manual B 3 HOOKS USING THE EXCEPTION 3 PREDICATE 215 prolog_skip_level Old New Unify Old with the old value of skip level and than set this level according to New New is an integer or the special atom very deep meaning don t skip The skip level is a global variable of the Prolog system that disables the debugger on all recursion levels deeper than the level of the variable Used to implement the trace options skip sets skip level to the level of the frame and up sets skip level to the level of the parent frame i e the level of this frame minus 1 B 3 Hooks using the exception 3 predicate This section describes the predicate except ion 3 which may be defined by the user in the module user as a multifile predicate Unlike the name suggests this is actually a hook predicate Excep tions are handled by the ISO predicates catch 3 and throw 1 They all frames created after the matching catch 3 to b
155. ded database may be used to communicate Prolog terms between threads record_t PL_record term_t t Record the term into the Prolog database as recorda 3 and return an opaque handle to the term The returned handle remains valid until PL_erase is called on it PL_recorded is used to copy recorded terms back to the Prolog stack void PL_recorded record_t record term_t t Copy a recorded term back to the Prolog stack The same record may be used to copy multiple instances at any time to the Prolog stack See also PL_record and PL_erase SWI Prolog 5 0 Reference Manual 180 CHAPTER 6 FOREIGN LANGUAGE INTERFACE void PL_erase record_t record Remove the recorded term from the Prolog database reclaiming all associated memory re sources The second group headed by PL_record_external provides the same functionality but the returned data has properties that enable storing the data on an external device It has been designed to make it possible to store Prolog terms fast an compact in an external database Here are the main features Independent of session Records can be communicated to another Prolog session and made visible using PL_recorded_external e Binary The representation is binary for maximum performance The returned data may contain 0 bytes e Byte order independent The representation can be transferred between machines with different byte order e No alignment restrictions There are no memory
156. ded from the personal initialisation file to pre select the usage of the built in editor Update Prolog after editing Using make 0 all files you have edited are re loaded PceEmacs Offers syntax highlighting and checking based on real time parsing of the editor s buffer layout support and navigation support Using the graphical debugger The predicates guitracer 0 and noguitracer 0 switch between traditional text based and window based debugging The tracer is activated using the trace 0 spy 1 or menu items from PceEmacs or the PrologNavigator The Prolog Navigator Shows the file structure and structure inside the file It allows for loading files editing setting spy points etc 7On Windows this is realised by plwin exe on Unix through the GNU readline library which is included automatically when found by configure SWI Prolog 5 0 Reference Manual Built in predicates 4 1 Notation of Predicate Descriptions We have tried to keep the predicate descriptions clear and concise First the predicate name is printed in bold face followed by the arguments in italics Arguments are preceded by a or sign indicates the argument is input to the predicate denotes output and denotes either input or output Constructs like op 3 refer to the predicate op with arity 3 4 2 Character representation In traditional Edinburgh Prolog characters are represente
157. ding presented in the menu bar above each editor window A complete overview of the bindings for the current mode is provided through Help Show key bindings Control h Control b Edit modes Modes are the heart of Pce Emacs Modes define dedicated editing support for a particular kind of source text For our purpose we want Prolog mode Their are various ways to make PceEmacs use Prolog mode for a file e Using the proper extension If the file ends in p1 or the selected alternative e g pro extension Prolog mode is selected e Using path to pl If the file is a Prolog Script file starting with the line path to pl options s Pro log mode is selected regardless of the extension e Using Prolog If the above sequence appears in the first line of the file inside a Prolog comment Prolog mode is Sequence e Explicit selection Finally using File Mode Prolog y ou can switch to Prolog mode explicitly Frequently used editor commands Below we list a few important commands and how to activate them Decent merging with MS Windows control key conventions is difficult as many conflict with GNU Emacs Expecially the cut copy paste commands conflict with important GNU Emacs commands SWI Prolog 5 0 Reference Manual 48 CHAPTER 3 INITIALISING AND MANAGING A PROLOG PROJECT Cut Copy Paste These commands follow Unix X11 traditions You re best suited with a three button mouse After selecting using the l
158. dit the source possibly switching to other files and making multiple changes After finishing invoke make 0 either through the editor UI Compile Make Cont rol C Control M or on the toplevel and watch the files being reloaded make show compiled into photo_gallery 0 03 sec 3 360 bytes gt Watching these files is a good habit If expected files are not reloaded you may have forgotten to save them from the editor or you may have been editing the wrong file wrong directory SWI Prolog 5 0 Reference Manual 3 4 USING THE PCEEMACS BUILT IN EDITOR 47 3 4 Using the PceEmacs built in editor 3 4 1 Activating PceEmacs Initially edit 1 uses the editor specified in the EDITOR environment variable There are two ways to force it to use the built in editor One is by loading library emacs swi_prolog a source file from the PceEmacs library that installs hooks which e Cause edit 1 to use the built in PceEmacs e Intercept error and warning messages while loading sources providing these messages in a window from which the related source can be found by double clicking the message 3 4 2 Bluffing through PceEmacs PceEmacs closely mimics Richard Stallman s GNU Emacs commands adding features from modern window based editors to make it more acceptable for beginners At the basis PceEmacs maps keyboard sequences to methods defined on the extended editor object Some frequently used commands are with their key bin
159. dy a protocol file open then close it first If File exists it is truncated protocola File Equivalent to protocol 1 but does not truncate the File if it exists noprotocol Stop making a protocol of the user interaction Pending output is flushed on the file protocolling File Succeeds if a protocol was started with protocol 1 or protocola 1 and unifies File with the current protocol output file 4 42 Debugging and Tracing Programs This section is a reference to the debugger interaction predicates A more use oriented overview of the debugger is in section 2 9 If you have installed XPCE you can use the graphical frontend of the tracer This frontend is installed using the predicate guitracer 0 trace Start the tracer t race 0 itself cannot be seen in the tracer Note that the Prolog toplevel treats trace 0 special it means trace the next goal tracing Succeeds when the tracer is currently switched on tracing 0 itself can not be seen in the tracer notrace Stop the tracer notrace 0 itself cannot be seen in the tracer guitracer Installs hooks see prolog_trace_interception 4 into the system that redirects trac ing information to a GUI frontend providing structured access to variable bindings graphical overview of the stack and highlighting of relevant source code 2A similar facility was added to Edinburgh C Prolog by Wouter Jansweijer SWI Prolog 5 0 Reference Manual 130 CHAPTER 4 BUILT IN PREDI
160. e inviting unclear programming by asserting in other modules The predicate assert 1 is supposed to assert in the module it is called from and should do so without being told explicitly For this reason the notion context module has been introduced 5 6 1 Definition and Context Module Each predicate of the program is assigned a module called it s definition module The definition module of a predicate is always the module in which the predicate was originally defined Each active goal in the Prolog system has a context module assigned to it The context module is used to find predicates from a Prolog term By default this module is the definition module of the predicate running the goal For meta predicates however this is the context module of the goal that invoked them We call this module_transparent in SWI Prolog In the using maplist example above the predicate maplist 3 is declared module transparent This implies the context module remains extend the context module of add_extension 3 This way maplist 3 can decide to call extend_atom in module ext end rather than in it s own definition module All built in predicates that refer to predicates via a Prolog term are declared module_transparent Below is the code defining maplist SWI Prolog 5 0 Reference Manual 144 CHAPTER 5 USING MODULES module maplist maplist 3 module_transparent maplist 3 maplist Goal Listl List2 True if Goal can successf
161. e profiler was active Promilage is unified with the relative number of counts the predicate was active cumulative or on top of the stack plain Promilage is an integer between 0 and 1000 4 45 Memory Management Note limit_stack 2andtrim_stacks 0 have no effect on machines that do not offer dynamic stack expansion On these machines these predicates simply succeed to improve portability garbage collect Invoke the global and trail stack garbage collector Normally the garbage collector is in voked automatically 1f necessary Explicit invocation might be useful to reduce the need for garbage collections in time critical segments of the code After the garbage collection trim stacks 0 is invoked to release the collected memory resources garbage_collect_atoms Reclaim unused atoms Normally invoked after agc_margin a prolog flag atoms have been created limit_stack Key Kbytes Limit one of the stack areas to the specified value Key is one of local global or trail The limit is an integer expressing the desired stack limit in K bytes If the desired limit is smaller than the currently used value the limit is set to the nearest legal value above the cur rently used value If the desired value is larger than the maximum the maximum is taken Finally if the desired value is either 0 or the atom unlimited the limit is set to its maximum The maximum and initial limit is determined by the command line options L G and T
162. e 1 discontiguous 1 deterministic 0 dwim_match 2 dwim_match 3 dwim_predicate 2 dynamic 1 edit 1 ensure_loaded 1 erase 1 eval _license 0 exception 3 exists _directory 1 exists_file 1 exit 2 expand_answer 2 expand_file_name 2 expand _file_search_path 2 expand_goal 2 expand_query 4 expand_term 2 explain 1 explain 2 export 1 export_list 2 fail O fail 1 current_prolog_flag 2 file_base_name 2 file_directory_name 2 file name_extension 3 file_search_path 2 fileerrors 2 findall 3 flag 3 flatten 2 float 1 flush_output O flush_output 1 forall 2 format 1 format 2 format 3 format_predicate 2 free_variables 2 Delete all matching members from a list Remove a folder from the file system Remove a file from the file system Indicate distributed definition of a predicate Test deterministicy of current goal Atoms match in Do What I Mean sense Atoms match in Do What I Mean sense Find predicate in Do What I Mean sense Indicate predicate definition may change Edit a file Consult a file if that has not yet been done Erase a database record or clause Evaluate licenses of loaded modules hook Handle runtime exceptions Check existence of directory Check existence of file Exit from named block See block 3 Expand answer of query Wildcard expansion of file names Wildcard expansion of file paths Compiler expand goal in clause body Expanded entered query Compiler expand read term into clause
163. e Manual E 3 ARITHMETIC FUNCTIONS 237 E 3 Arithmetic Functions 2 x 2 2 1 P 12 12 2 lt lt 2 gt gt 2 1 2 1 7 2 2 abs 1 acos 1 asin 1 atan 1 atan 2 ceil 1 ceiling 1 cos 1 cputime 0 e 0 exp 1 float 1 float_fractional_part 1 float_integer_part 1 floor 1 integer 1 log 1 log10 1 max 2 min 2 mod 2 random 1 rem 2 round 1 truncate 1 pi 0 sign 1 sin sqrt 1 tan 1 Multiplication Power function Addition Unary minus Subtraction Division Integer division Bitwise and Bitwise left shift Bitwise right shift List of one character character code Bitwise negation Bitwise or Power function Absolute value Inverse arc cosine Inverse arc sine Inverse arc tangent Rectangular to polar conversion Smallest integer larger than arg Smallest integer larger than arg Cosine Get CPU time Mathematical constant Exponent base e Explicitly convert to float Fractional part of a float Integer part of a float Largest integer below argument Round to nearest integer Natural logarithm 10 base logarithm Maximum of two numbers Minimum of two numbers Remainder of division Generate random number Remainder of division Round to nearest integer Truncate float to integer Mathematical constant Extract sign of value Sine Square root Tangent SWI Prolog 5 0 Reference Manual 238 APPENDIX E SUMMARY xor 2 Bitwise exclusive or SWI Prolog
164. e arguments as a set of consecutive term references and very time critical code requiring a number of term references can be written as pl_mypredicate term_t a0 term_t al term t t0 PL_new_term_refs 2 term_t tl t0 1 SWI Prolog 5 0 Reference Manual 6 5 INTERFACE DATA TYPES 155 term_t PL_copy_term_ref term_t from Create a new term reference and make it point initially to the same term as from This function is commonly used to copy a predicate argument to a term reference that may be written void PL _reset_term_refs term_t after Destroy all term references that have been created after after including after itself Any refer ence to the invalidated term references after this call results in undefined behaviour Note that returning from the foreign context to Prolog will reclaim all references used in the foreign context This call is only necessary if references are created inside a loop that never exits back to Prolog See also PL_open_foreign_frame PL_close_foreign_frame and PL_discard_foreign_frame Interaction with the garbage collector and stack shifter Prolog implements two mechanisms for avoiding stack overflow garbage collection and stack ex pansion On machines that allow for it Prolog will use virtual memory management to detect stack overflow and expand the runtime stacks On other machines Prolog will reallocate the stacks and up date all pointers to them To do so Prolog needs to know whi
165. e corresponding module and assign an opaque pointer to it over module SWI Prolog 5 0 Reference Manual 6 6 THE FOREIGN INCLUDE FILE 163 int PL_get_arg int index term_t t term_t a If tis compound and index is between 1 and arity including assign a with a term reference to the argument int PL get_arg int index term_t t term_t a Same as PL_get_arg but no checking is performed nor whether t is actually a term nor whether index is a valid argument index Exchanging text using length and string All internal text representation of SWI Prolog is represented using char plus length and allow for 0 bytes in them The foreign library supports this by implementing a _nchars function for each applicable _chars function Below we briefly present the signatures of these functions For full documentation consult the _chars function int PL_get_atom_nchars term_t t unsigned int len char s int PL_get_list_nchars term_t t unsigned int len char s int PL_get_nchars term_t t unsigned int len char s unsigned int flags int PL_put_atom_nchars term_t t unsigned int len const char s int PL_ put string_nchars term _t t unsigned int len const char s int PL _put_list_ncodes term_t t unsigned int len const char s int PL_put_list_nchars term_t t unsigned int len const char s int PL_unify_atom_nchars term_t t unsigned int len const char s int PL_unify_string_nchars term_t t unsigned
166. e discarded immediately The predicate exception 3 is called by the kernel on a couple of events allowing the user to alter the behaviour on some predefined events exception Exception Context Action Dynamic predicate normally not defined Called by the Prolog system on run time exceptions Currently except ion 3 is only used for trapping undefined predicates Future versions might handle signal handling floating exceptions and other runtime errors via this mechanism The values for Exception are described below undefined_predicate If Exception is undefined_predicate Context is instantiated to a term Name Arity Name refers to the name and Arity to the arity of the undefined predicate If the definition module of the predicate is not user Context will be of the form Module Name Arity If the predicate fails Prolog will generate an esistence error exception If the predicate succeeds it should instantiate the last argument either to the atom fail to tell Prolog to fail the predicate the atom retry to tell Prolog to retry the predicate or error to make the system generate an exception The action ret ry only makes sense if the exception handler has defined the predicate B 4 Hooks for integrating libraries Some libraries realise an entirely new programming paradigm on top of Prolog An example is XPCE which adds an object system to Prolog as well as an extensive set of graphical primitives SWI Prolog provides several ho
167. e file import all public predicates Otherwise import only the named predicates Each predicate is refered to as name arity This option has no effect 1f the file is not a module file silent Bool If true load the file without printing a message The specified value is the default for all files loaded as a result of loading the specified files autoload Bool If true default false indicate this load is a demand load This implies that depending on the setting of the prolog flag verbose_autoload the load action is printed at level informational or silent See also print message 2 and current_prolog_flag 2 consult File Read File as a Prolog source file File may be a list of files in which case all members are con sulted in turn File may start with the csh 1 special sequences user and var File may also be Library Name in which case the libraries are searched for a file with the specified name See also Library_directory 1 and file_search_path 2 consult 1 may be abbreviated by just typing a number of file names in a list Examples Tt does work for normal loading but not for gcompile 1 SWI Prolog 5 0 Reference Manual 56 CHAPTER 4 BUILT IN PREDICATES consult load consult load or load pl library quintus load Quintus compatibility library Equivalent to load_files Files ensure_loaded File If the file is not already loaded this is equivalent to consult 1 O
168. e in radians cos Expr Result cos Expr Expr is the angle in radians tan Expr Result tan Expr Expr is the angle in radians asin Expr Result arcsin Expr Result is the angle in radians acos Expr Result arccos Expr Result is the angle in radians atan Expr Result arctan Expr Result is the angle in radians atan YExpr XExpr Result arctan ee r Result is the angle in radians The return value is in the range 7 7 Used to convert between rectangular and polar coordinate system SWI Prolog 5 0 Reference Manual 4 28 ADDING ARITHMETIC FUNCTIONS 107 log Expr Result ln Expr log10 Expr Result lg Expr exp Expr Result eExpr Exprl Expr2 Result Expr E P 2 Exprl Expr2 Same as 2 backward compatibility pi Evaluates to the mathematical constant 7 3 141593 e Evaluates to the mathematical constant e 2 718282 cputime Evaluates to a floating point number expressing the CPU time in seconds used by Prolog up till now See also statistics 2 andtime 1 4 28 Adding Arithmetic Functions Prolog predicates can be given the role of arithmetic function The last argument is used to return the result the arguments before the last are the inputs Arithmetic functions are added using the predicate arithmetic_function 1 which takes the head as its argument Arithmetic functions are module sensitive that is they are only visible from the modul
169. e in which execution is resumed if the goal associated with Frame fails Fails if the frame has no alternative frame has_alternatives Value is unified with true if Frame still is a candidate for backtracking false other wise goal Value is unified with the goal associated with Frame If the definition module of the active predicate is not user the goal is represented as module goal Do not instantiate variables in this goal unless you know what you are doing clause Value is unified with a reference to the currently running clause Fails if the current goal is associated with a foreign C defined predicate See also nth_clause 3 and clause property 2 level Value is unified with the recursion level of Frame The top level frame is at level 0 parent Value is unified with an integer reference to the parent local stack frame of Frame Fails if Frame is the top frame SWI Prolog 5 0 Reference Manual 214 APPENDIX B HACKERS CORNER context_module Value is unified with the name of the context module of the environment top Value is unified with t rue if Frame is the top Prolog goal from a recursive call back from the foreign language false otherwise hidden Value is unified with t rue if the frame is hidden from the user either because a parent has the hide childs attribute all system predicates or the system has no trace me attribute pe Value is unified with the program pointer saved on behalve of the parent go
170. e in which the function is defined and declared Global arithmetic functions should be defined and registered from module user Global definitions can be overruled locally in modules The builtin functions described above can be redefined as well arithmetic_function Head Register a Prolog predicate as an arithmetic function see is 2 gt 2 etc The Prolog predi cate should have one more argument than specified by Head which it either a term Name Arity an atom or a complex term This last argument is an unbound variable at call time and should be instantiated to an integer or floating point number The other arguments are the parameters This predicate is module sensitive and will declare the arithmetic function only for the context module unless declared from module user Example 1 user arithmetic_function mean 2 mean A B C C is A B 2 user compiled 0 07 sec 440 bytes SWI Prolog 5 0 Reference Manual 108 CHAPTER 4 BUILT IN PREDICATES Yes 2 A is mean 4 5 A 4 500000 current_arithmetic function Head Successively unifies all arithmetic functions that are visible from the context module with Head 4 29 List Manipulation is_list Term Succeeds if Term is bound to the empty list or a term with functor and arity 2 and the second argument is a list This predicate acts as if defined by the following definition is_list X var X fail is_list is_li
171. e main program It is allowed to create your own argument vector provided argv 0 is constructed according to the rules above For example int main int argc char argv char av 10 int ac 0 av actt argv 0 av actt x avlac mystate avlac NULL if PL_initialise ac av BUG Various fatal errors may cause PL_initialise to call PL_halt 1 preventing it from returning at all SWI Prolog 5 0 Reference Manual 190 CHAPTER 6 FOREIGN LANGUAGE INTERFACE PL_halt 1 Please note that the passed argument vector may be referred from Prolog at any time and should therefore be valid as long as the Prolog engine is used A good setup in Windows is to add SWI Prolog s bin directory to your PATH and either pass a module holding a saved state or 1ibp1 d11 as argv 0 int PL_is_initialised int argc char argv Test whether the Prolog engine is already initialised Returns FALSE if Prolog is not initialised and TRUE otherwise If the engine is initialised and argc is not NULL the argument count used with PL_initialise is stored in argc Same for the argument vector argv void PL install _readline Installs the GNU readline line editor Embedded applications that do not use the Prolog toplevel should normally delete this line shrinking the Prolog kernel significantly int PL_toplevel Runs the goal of the t toplevel switch default prolog 0 and returns 1 if successful 0
172. ed Compound terms are indexed on the combination of their name and arity Indexing is very useful for predicates with many clauses representing facts SWI Prolog 5 0 Reference Manual 4 15 EXAMINING THE PROGRAM 79 Due to the representation technique used at most 4 arguments can be indexed All indexed arguments should be in the first 32 arguments of the predicate If more than 4 arguments are specified for indexing only the first 4 will be accepted Arguments above 32 are ignored for indexing By default all predicates with arity gt 1 are indexed on their first argument It is possible to redefine indexing on predicates that already have clauses attached to them This will initiate a scan through the predicates clause list to update the index summary information stored with each clause If for example one wants to represents sub types using a fact list sub_type Sub Super that should be used both to determine sub and super types one should declare sub_type 2 as follows index sub_type 1 1 sub_type horse animal lt 4 15 Examining the program current_atom Atom Successively unifies Atom with all atoms known to the system Note that current_atom 1 always succeeds if Atom is instantiated to an atom current_functor Name Arity Successively unifies Name with the name and Arity with the arity of functors known to the system current_flag FlagKey Successively unifies FlagKey with all keys
173. ed through trace 0 by hitting a spy point defined by spy 1 or a break point defined using PceEmacs command Prolog Break at Control c b SWI Prolog 5 0 Reference Manual 52 CHAPTER 3 INITIALISING AND MANAGING A PROLOG PROJECT noguitracer 3 6 Disable the hooks installed by guitracer 0 reverting to normal text console based tracing The Prolog Navigator Another tool is the Prolog Navigator This tool can be started from PceEmacs using the command Browse Prolog navigator from the GUI debugger or using the predicate prolog_navigator 1 prolog_navigator DirOrLocation 3 7 Ensure the navigator exists and the indicated location is shown DirOrLocation is either the name of a directory or File Line to open and select the given location Summary of the iDE The SWI Prolog development environment consists of a number of interrelated but not yet integrated tools Here is a list of the most important features and tips Atom completion The console completes a partial atom on the TAB key and shows alternatives on the command Alt Use edit 1 to finding locations The command edit 1 takes the name of a file module predicate or other entity registered through extensions and starts the users preferred editor at the right location Select editor External editors are selected using the EDITOR environment variable or by defining the hook prolog_edit edit_source 1 The library emacs swi_prolog library may be loa
174. ed as C native double precision floats 64 bit IEEE on most machines 2 16 3 Reserved Names The boot compiler see b option does not support the module system As large parts of the sys tem are written in Prolog itself we need some way to avoid name clashes with the user s predicates database keys etc Like Edinburgh C Prolog Pereira 1986 all predicates database keys etc that should be hidden from the user start with a dollar sign see st yle_check 1 SWI Prolog 5 0 Reference Manual 42 CHAPTER 2 OVERVIEW Option Default Area name Description L 2M local stack The local stack is used to store the execution environments of procedure invocations The space for an environment is re claimed when it fails exits with out leaving choice points the alternatives are cut of with the 0 predicate or no choice points have been created since the in vocation and the last subclause is started tail recursion optimi sation G 4M global stack The global stack is used to store terms created during Prolog s execution Terms on this stack will be reclaimed by backtrack ing to a point before the term was created or by garbage col lection provided the term is no longer referenced 4M trail stack The trail stack is used to store as signments during execution En tries on this stack remain alive until backtracking before the point of creation or the garbage collector determines they are nor needed
175. ed fails In the latter case the checklist 2 fails maplist Pred Listl List2 Apply Pred on all successive pairs of elements from List and List2 Fails if Pred can not be applied to a pair See the example above sublist Pred Listl List2 Unify List2 with a list of all elements of List to which Pred applies 4 34 Forall forall Cond Action For all alternative bindings of Cond Action can be proven The example verifies that all arith metic statements in the list L are correct It does not say which is wrong if one proves wrong Formula 2 1 1 4 2 2 Formula forall member Result Resul II 4 35 Formatted Write The current version of SWI Prolog provides two formatted write predicates The first is writef 1 2 which is compatible with Edinburgh C Prolog The second is format 1 2 which is compatible with Quintus Prolog We hope the Prolog community will once define a standard formatted write predicate If you want performance use format 1 2 as this predicate is defined in C Otherwise compatibility reasons might tell you which predicate to use 4 35 1 Writef writeln Term Equivalent to write Term nl writef Atom Equivalent towritef Atom writef Format Arguments Formatted write Format is an atom whose characters will be printed Format may contain certain special character sequences which specify certain formatting and substitution actions Arguments
176. ed from the len chars pair The data will be copied This interface can deal with 0 bytes in the string See also section 6 6 18 int PL_unify integer term_t t long n Unify t with a Prolog integer from n int PL_unify_float term_t t double f Unify with a Prolog float from f int PL_unify_pointer term_t t void ptr Unify with a Prolog integer describing the pointer See also PL_put_pointer and PL_ get pointer int PL unify functor term_t t functor_1 f If t is a compound term with the given functor just succeed If it is unbound create a term and bind the variable else fails Not that this function does not create a term if the argument is already instantiated int PL_unify_list term_t l term_t h term_t t Unify with a list cell 2 If successful write a reference to the head of the list to h and a reference to the tail of the list in This reference may be used for subsequent calls to this function Suppose we want to return a list of atoms from a char We could use the example described by PL_put_list followed by a call to PL_unify or we can use the code below If the predicate argument is unbound the difference is minimal the code based on PL_put_list is probably slightly faster If the argument is bound the code below may fail before reaching the end of the word list but even if the unification succeeds this code avoids a duplicate garbage list and a deep unification
177. ed in N columns Write the next item Left justified in N columns Write the next item Right justified in N columns N is a decimal number with at least one digit The item must be an atom integer float or string swritef String Format Arguments Equivalent to writef 2 but writes the result on String instead of the current output stream Example swritef S S Hello swritef String Format 15LSw Hello Worla World Equivalent to swritef String Format SWI Prolog 5 0 Reference Manual 114 CHAPTER 4 BUILT IN PREDICATES 4 35 2 Format format Format Defined as format Format format Format y format Format Arguments Format is an atom list of ASCII values or a Prolog string Arguments provides the arguments required by the format specification If only one argument is required and this is not a list of ASCII values the argument need not be put in a list Otherwise the arguments are put in a list Special sequences start with the tilde followed by an optional numeric argument followed by a character describing the action to be undertaken A numeric argument is either a sequence of digits representing a positive decimal number a sequence character representing the ASCII value of the character only useful for t or a asterisk in when the numeric argu ment is taken from the next argument of the argument list which should be
178. ed to be reloaded This can cause serious consistency problems It does not help for dynamically defined predicates calling module sensitive predicates It slows down the compiler at least in the SWI Prolog architecture At least within the SWI Prolog architecture the run time overhead is larger than the overhead introduced by the transparent mechanism Unfortunately the transparent predicate approach also has some disadvantages If a predicate A passes module sensitive information to a predicate B passing the same information to a module sensitive system predicate both A and B should be declared transparent Using the Quintus approach only A needs to be treated special i e declared with meta predicate 1 A second problem arises if the body of a transparent predicate uses module sensitive predicates for which it wants to refer to its own module Suppose we want to define finda11 3 using assert 1 and retract 1 The example in figure 5 1 gives the solution Although this would make it impossible to call B directly gt The system version uses recordz 2 and recorded 3 SWI Prolog 5 0 Reference Manual 5 9 COMPATIBILITY OF THE MODULE SYSTEM 147 module findall findall 3 dynamic solution 1 module _transparent findall 3 store 2 findall Var Goal Bag assert findall solution S mark store Var Goal collect Bag store Var Goal Goal refers to context module of
179. een predefined All operators except for the comma can be redefined by the user Some care has to be taken before defining new operators Defining too many operators might make your source natural looking but at the same time lead to hard to understand the limits of your syntax To ease the pain as of SWI Prolog 3 3 0 operators are local to the module in which they are defined The module table of the module user acts as default table for all modules This global table can be modified explictly from inside a module module prove prove 1 DE op 900 xfx user gt Unlike what many users think operators and quoted atoms have no relation defining a atom as an operator does not influence parsing characters into atoms and quoting an atom does not stop it from acting as an operator To stop an atom acting as an operator enclose it in braces like this myop SWI Prolog 5 0 Reference Manual 102 CHAPTER 4 BUILT IN PREDICATES 1200 zfr gt 1200 ful 1150 fx dynamic multifile module _transparent discon tiguous volatile initialization 1100 xfy 7 1050 xfy gt 1000 zfy 954 xfy 900 fy 900 fx 700 rfr lt lt gt gt lt lt gt gt 1s 600 zfy 500 yfr xor 500 fx 400 yfzx lt lt gt gt mod rem 200 xfx 200 fy
180. efines __unix__ or unix windows bool If true the operating system is an implementation of Microsoft Windows 3 1 95 NT etc hwnd integer In plwin exe this refers to the MS Windows window handle of the console window set_prolog flag Xey Value Define a new prolog flag or change its value Key is an atom If the flag is a system defined flag that is not marked changeable above an attempt to modify the flag yields a permission error If the provided Value does not match the type of the flag a type_error is raised In addition to ISO SWI Prolog allows for user defined prolog flags The type of the flag is determined from the initial value and cannot be changed afterwards 2 12 An overview of hook predicates SWI Prolog provides a large number of hooks mainly to control handling messages debugging startup shut down macro expansion etc Below is a summary of all defined hooks with an indication of their portability portray 1 Hook into write_term 3 to alter the way terms are printed ISO message_hook 3 Hook into print message 2 to alter the way system messages are printed Quin tus SICStus library_directory 1 Hook into absolute file _name 3 to define new library directories most Prolog system file search path 2 Hook into absolute_file_name 3 to define new search paths Quintus SICStus term_expansion 2 Hook into load_files 1 to modify read terms before they are compiled macro processin
181. efining all foreign predicate arguments of type term SWI Prolog explicitly uses type functor _t while Quintus and SICStus uses name and arity As the names of the functions differ from Prolog to Prolog a simple macro layer dealing with the names can also deal with this detail For example define QP_put_functor t n a PL_put_functor t PL_new_functor n The PL unify functions are lacking from the Quintus and SICStus interface They can easily be emulated or the put unify approach should be used to write compatible code The PL_open_foreign_frame PL_close_ foreign frame combination is lacking from both other Prologs SICStus has PL_new_term_refs 0 followed by PL_reset_term_refs that allows for discarding term references The Prolog interface for the graphical user interface package XPCE shares about 90 of the code using a simple macro layer to deal with different naming and calling conventions of the interfaces SWI Prolog 5 0 Reference Manual a Generating Runtime Applications This chapter describes the features of SWI Prolog for delivering applications that can run without the development version of the system installed A SWI Prolog runtime executable is a file consisting of two parts The first part is the emulator which is machine dependent The second part is the resource archive which contains the compiled program in a machine independent format startup options and possibly user defined resources
182. eft mouse double click uses word mode and triple line mode the selected text is automatically copied to the clipboard X11 primary selection on Unix Cut is achieved using the DEL key or by typing something else at the location Paste is achieved using the middle mouse or wheel button If you don t have a middle mouse button pressing the left and right button at the same time is interpreted as a middle button click If nothing helps there is the Edit Paste menu entry Text is pasted at the caret location Undo Undo is bound to the GNU Emacs Control _ as well as the MS Windows Control Z sequence e Abort Multi key sequences can be aborted at any stage using Control G Find Find Search is started using Control S forward or Control R backward PceEmacs imple ments incremental search This is difficult to use for novices but very powerful once you get the clue After one of the above start keys the system indicates search mode in the status line As you are typing the search string the system searches for it extending the search with every character you type It illustrates the current match using a green background If the target cannot be found PceEmacs warns you and no longer extends the search string During search some characters have special meaning Typing anything but these characters commits the search re starting normal edit mode Special commands are Control S Search for next forwards Control R Search for ne
183. eign Interface Each argument of a foreign function except for the control argument is of type term_t an opaque handle to a Prolog term Three groups of functions are available for the analysis of terms The first just validates the type like the Prolog predicates var 1 atom 1 etc and are called PL_is_ The second group attempts to translate the argument into a C primitive type These predicates take a term_t and a pointer to the appropriate C type and return TRUE or FALSE depending on successful or unsuccessful translation If the translation fails the pointed to data is never modified Otherwise asynchronous atom garbage collection might detroy the atom before it is used SWI Prolog 5 0 Reference Manual 160 CHAPTER 6 FOREIGN LANGUAGE INTERFACE Testing the type of a term int PL_term_type term_t Obtain the type of a term which should be a term returned by one of the other interface pred icates or passed as an argument The function returns the type of the Prolog term The type identifiers are listed below Note that the extraction functions PL_ge_t also validate the type and thus the two sections below are equivalent if PL_is_atom t char s PL_get_atom_chars t s a or char s if PL_get_atom_chars t amp s le ir PL_VARIABLE An unbound variable The value of term as such is a unique identifier for the variable PL_ATOM A Prolog atom PL_STRING A Prolog string
184. entated by the prolog flag debug See also debug 0 debugging Print debug status and spy points on current output stream See also the prolog flag debug spy Pred Put a spy point on all predicates meeting the predicate specification Pred See section 4 4 nospy Pred Remove spy point from all predicates meeting the predicate specification Pred nospyall Remove all spy points from the entire program SWI Prolog 5 0 Reference Manual 4 43 OBTAINING RUNTIME STATISTICS 131 leash Ports Set query leashing ports which allow for user interaction Ports is one of Name Name Name or a list of these Name enables leashing on that port Name disables it and Name succeeds or fails according to the current setting Recognised ports are call redo exit fail and unify The special shorthand a11 refers to all ports fu11 refers to all ports except for the unify port default half refers to the call redo and fail port visible Ports Set the ports shown by the debugger See leash 1 for a description of the port specification Default is full unknown Old New Edinburgh prolog compatibility predicate interfacing to the ISO prolog flag unknown Val ues are trace meaning error and fail If the unknown flag is set to warning unknown 2 reports the value as trace style_check Spec Set style checking options Spec is either option option option or a list of such options option sets a style che
185. eption domain_error not_less_then_zero Arg if Arg lt 0 setarg Arg Term Value Extra logical predicate Assigns the Arg th argument of the compound term Term with the given ln version 1 2 instantiation faults led to error messages The new version can be used to do type testing without the need to catch illegal instantiations first The instantiation pattern is an extension to standard Prolog SWI Prolog 5 0 Reference Manual 4 20 ANALYSING AND CONSTRUCTING TERMS 95 Value The assignment is undone if backtracking brings the state back into a position before the setarg 3 call This predicate may be used for destructive assignment to terms using them as and extra logical storage bin Term List List is a list which head is the functor of Term and the remaining arguments are the arguments of the term Each of the arguments may be a variable but not both This predicate is called Univ Examples foo hello X List List foo hello X Term baz foo 1 Term baz foo 1 numbervars Term Functor Start End Unify the free variables of Term with a term constructed from the atom Functor with one argu ment The argument is the number of the variable Counting starts at Start End is unified with the number that should be given to the next variable Example numbervars foo A B A this_is_a_variable 0 End A this_is_a_variable 0 B this_i
186. er is prompted for an action All actions are single character commands which are executed without waiting for a return unless the command line option tty is active Tracer options Spy Set a spy point see spy 1 on the current predicate No spy Remove the spy point see nospy 1 from the current predicate Find Search for a port After the the user can enter a line to specify the port to search for This line consists of a set of letters indicating the port type followed by an optional term that should unify with the goal run by the port If no term is specified it is taken as a variable searching for any port of the specified type If an atom is given any goal whose functor has a name equal to that atom matches Examples SWI Prolog 5 0 Reference Manual 26 CHAPTER 2 OVERVIEW 1 visible tall leash exit Yes 2 2 trace min 3 2 X Call 3 min 3 2 G235 creep Unify 3 min 3 2 G235 Call 4 min 2 G244 creep Unify 4 min 2 2 Exit 4 min 2 2 Call 4 min 3 2 G235 creep Unify 4 min 3 2 G235 Call 5 3 lt 2 creep Fail 5 3 lt 2 creep Redo 4 min 3 2 G235 creep Exit 4 min 3 2 2 Exit 3 min 3 2 2 Yes trace 3 Figure 2 2 Example trace Search for any fail port fe solve Search for a fail or exit port of any goal with name solve c solve a Search for a call t
187. erenced by foreign code and thus allows the kernel to perform garbage collection and or stack shifts while foreign code is active for example during a callback from C A term reference is a C unsigned long representing the offset of a variable on the Prolog environment stack A foreign function is passed term references for the predicate arguments one for each argument If references for intermediate results are needed such references may be created using PL_new_term_ref or PL_new_term_refs These references normally live till the foreign function returns control back to Pro log Their scope can be explicitly limited using PL open foreign frame and SWI Prolog 5 0 Reference Manual 154 CHAPTER 6 FOREIGN LANGUAGE INTERFACE PL_close_foreign_frame PL_discard_foreign_frame A term t always refers to a valid Prolog term variable atom integer float or compound term A term lives either until backtracking takes us back to a point before the term was created the garbage collector has collected the term or the term was created after a PL_open_foreign_frame and PL discard foreign frame has been called The foreign interface functions can either read unify or write to term references In the this document we use the following notation for arguments of type term_t term_t t Accessed in read mode The indicates the argument is input termt t Accessed in write mode term_t t Accessed in unify mo
188. ero ISO prolog flag describing rounding by and rem arithmetic functions Value depends on the C compiler used bounded true ISO prolog flag describing integer representation is bound by min_integer and min_integer tty_control bool Determines whether the terminal is switched to raw mode for get_single_char 1 which also reads the user actions for the trace May be set See also the tty command line option unknown fail warning error changeable Determines the behaviour if an undefined procedure is encountered If fail the pred icates fails silently If warn a warning is printed and execution continues as if the predicate was not defined and if error default an existence_error exception is raised This flag is local to each module debug bool changeable Switch debugging mode on off If debug mode is activated the system traps encountered spy points see spy 1 and trace points see trace 1 In addition tail recursion op timisation is disabled and the system is more conservative in destroying choice points to simplify debugging Disabling these optimisations can cause the system to run out of memory on programs that behave correctly if debug mode is off tail_recursion_optimisation bool changeable Determines whether or not tail recursion optimisation is enabled Normally the value of this flag is equal to the debug flag As programs may run out of stack if tail recursion optimisation is omitted it is sometimes ne
189. es of other modules The module declaration also makes explicit which predicates are meant for public usage and which for private purposes Finally using the module information cross reference programs can indicate possible problems much better 5 2 Name based versus Predicate based Modules Two approaches to realize a module system are commonly used in Prolog and other languages The first one is the name based module system In these systems each atom read is tagged normally prefixed with the module name with the exception of those atoms that are defined public In the second approach each module actually implements its own predicate space A critical problem with using modules in Prolog is introduced by the meta predicates that trans form between Prolog data and Prolog predicates Consider the case where we write module extend add_extension 3 add_extension Extension Plain Extended maplist extend_atom Extension Plain Extended extend_atom Extension Plain Extended concat Plain Extension Extended In this case we would like maplist to call extend_atom 3 in the module extend A name based module system will do this correctly It will tag the atom extend_at om with the module and maplist will use this to construct the tagged term extend_atom 3 A name based module however will not only tag the atoms that will eventually be used to refer to a predicate but all atoms that are not declared public So with
190. etermine the key Each key has a chain of terms associated with it New terms can be added either at the head or at the tail of this chain This mechanism is considerably faster than the assert retract mechanism as terms are not compiled but just copied into the heap The third mechanism is a special purpose one It associates an integer or atom with a key which is an atom integer or term Each key can only have one atom or integer associated with it It is faster than the mechanisms described above but can only be used to store simple status information like counters etc abolish Predicatelndicator Removes all clauses of a predicate with functor Functor and arity Arity from the database All predicate attributes dynamic multifile index etc are reset to their defaults Abolishing an imported predicate only removes the import link the predicate will keep its old definition in its definition module According to the ISO standard abolish 1 can only be applied to dynamic procedures This is odd as for dealing with dynamic procedures there is already retract 1 and retractal1l 1 The abolish 1 predicate has been introduced in DEC 10 Prolog pre cisely for dealing with static procedures In SWI Prolog abolish 1 works on static proce dures unless the prolog flag iso is set to true It is advised to use retractall 1 for erasing all clauses of a dynamic predicate abolish Name Arity Same as abolish Name Arity The predicate abolish 2
191. etween a string and an atom At least one of the two arguments must be instantiated Atom can also be an integer or floating point number string_to_list String List Logical conversion between a string and a list of ASCII characters At least one of the two arguments must be instantiated string _length String Length Unify Length with the number of characters in String This predicate is functionally equivalent to atom_length 2 and also accepts atoms integers and floats as its first argument string_concat String String2 String3 Similar to atom_concat 3 but the unbound argument will be unified with a string object rather than an atom Also if both String and String2 are unbound and String3 is bound to text it breaks String3 unifying the start with String and the end with String2 as append does with lists Note that this is not particularly fast on long strings as for each redo the system has to create two entirely new strings while the list equivalent only creates a single new list cell and moves some pointers around sub_string String Start Length After Sub Sub is a substring of String starting at Start with length Length and String has After characters left after the match See also sub_atom 5 4 24 Operators Operators are defined to improve the readibility of source code For example without operators to write 2 3 4 5 one would have to write 2 3 4 5 In Prolog a number of operators have b
192. ext module If a term is referring to a predicate in a module the context module is used to find the target module The context module of a goal is the module in which the predicate is defined unless this predicate is module transparent in which case the context module is inherited from the parent goal See also module_transparent 1 dynamic predicate A dynamic predicate is a predicate to which clauses may be asserted and from which clauses may be retracted while the program is running See also update view exported predicate A predicate is said to be exported from a module if it appears in the public list This im plies that the predicate can be imported into another module to make it visible there See also use _module 1 2 fact Clause without a body This is called a fact because interpreted as logic there is no condition to be satisfied The example below states john is a person person john fail A goal is said to haved failed if it could not be proven float Computers cripled representation of a real number Represented as IEEE double foreign Computer code expressed in other languages than Prolog SWI Prolog can only cooperate directly with the C and C computer languages functor Combination of name and arity of a compound term The term foo a b c is said to be a term belonging to the functor fo0 3 oo 0 is used to refer to the atom foo goal Question stated to the Prolog engine A goal is either an ato
193. f file Create a temporary filename Close current output Start the tracer Set trace point on predicate Set Clear trace point on ports Query status of the tracer Release unused memory resources Succeed Get terminal parameter Goto position on screen Write control string to terminal Get row column size of the terminal Flush output on terminal Union of two sets Logically sound unification OS interaction Trap undefined predicates library sh1 ib Detach shared library so file Delete shell environment variable Import a module Import predicates from a module Type check for unbound variable Ports that are visible in the tracer Predicates that are not saved Wait for input with optional timeout Csh 1 style wildcard match Win32 spawn Windows task plwin exe add menu SWI Prolog 5 0 Reference Manual E 1 PREDICATES 235 win_insert_menu_item 4 win_shell 2 win _registry_get_value 3 with_mutex 2 working _directory 2 write 1 write 2 writeln 1 write_canonical 1 write_canonical 2 write _term 2 write _term 3 writef 1 writef 2 writeq 1 writeq 2 plwin exe add item to menu Win32 open document through Shell Win32 get registry value Run goal while holding mutex Query change CWD Write term Write term to stream Write term followed by a newline Write a term with quotes ignore operators Write a term with quotes ignore operators on a stream Write term with options Write term with options to st
194. fers a stack shifter to provide dynamically expanding stacks on machines that do not offer operating system support for implementing dynamic stacks 1 6 2 Version 1 9 Release Notes Version 1 9 offers better portability including an MS Windows 3 1 version Changes to the Prolog system include SWI Prolog 5 0 Reference Manual 12 CHAPTER 1 INTRODUCTION e Redefinition of system predicates Redefinition of system predicates was allowed silently in older versions Version 1 9 only allows it if the new definition is headed by a redefine _system_predicate 1 directive e Answer reuse The toplevel maintains a table of bindings returned by toplevel goals and allows for reuse of these bindings by prefixing the variables with the sign See section 2 8 e Better source code administration Allows for proper updating of multifile predicates and finding the sources of individual clauses 1 6 3 Version 2 0 Release Notes New features offered e 32 bit Virtual Machine Removes various limits and improves performance e Inline foreign functions Simple foreign predicates no longer build a Prolog stack frame but are directly called from the VM Notably provides a speedup for the test predicates such as var 1 etc e Various compatibility improvements e Stream based I O library All SWI Prolog s I O is now handled by the stream package defined in the foreign include file SwI Stream h Physical I O of Prolog streams may be
195. file to open resides and load this file The normal way to start with the likes p1 file mentioned in section 2 1 1 is by simply double clicking this file in the Windows explorer 2 1 2 Executing a query After loading a program one can ask Prolog queries about the program The query below asks Pro log to prove whether john likes someone and who is liked by john The system responds with X value if it can prove the goal for a certain X The user can type the semi colon if s he wants another solution or RETURN if s he is satisfied after which Prolog will say Yes If Prolog answers No it indicates it cannot find any more answers to the query Finally Prolog can answer using an error message to indicate the query or program contains an error likes john X X mary 2 2 The user s initialisation file After the necessary system initialisation the system consults see consult 1 the user s startup file The base name of this file follows conventions of the operating system On MS Windows it is the file p1 ini and on Unix systems plrc The file is searched using the file search path 2 clauses for user_profile The table below shows the default value for this search path Unix Windows local home SHOME or SHOMEDRIVES SHOMEPATHS global SWI Home directory or SWINDIRS or SYSTEMROOTS After the first startup file is found it is loaded and Prolog stops looking for further startu
196. file_search_path 2 57 expand_goal 2 59 expand_query 4 128 expand term 2 58 expand_answer 2 128 expand _file_ name 2 36 118 121 expand _goal 2 34 58 expand_term 2 58 59 74 explain library 228 explain 1 23 explain 2 23 export 1 145 export_list 2 145 fail O 64 fail 1 74 feature 2 15 file_base_name 2 120 file_directory_name 2 120 file name extension 3 121 file_search_path 2 36 56 file_search_path 2 18 21 34 38 44 55 57 151 194 202 204 fileerrors 0 87 fileerrors 2 35 87 findall 3 110 146 147 flag 3 34 77 79 flatten 2 109 float 1 62 104 105 float_fractional_part 1 105 float_integer_part 1 105 float_integer_part 1 105 floor 1 106 flush_output O 88 flush_output 1 88 flush_output O 88 flush_output 1 70 flush_output 0 1 84 88 foo 0 218 foo 3 218 forall 2 59 112 format 1 70 114 format 2 114 115 format 3 70 71 115 format 1 2 33 90 112 228 format 2 3 40 format _predicate 2 116 free_variables 2 95 free_variables 2 92 FTP 210 functor 3 9 62 94 garbage_collect 0 134 garbage_collect_atoms 0 134 garbage_collect_atoms 0 184 gensym 2 138 get 1 89 get 2 89 get0 1 84 89 90 get0 2 89 get_byte 1 89 get_byte 2 89 get_char 1 89 get_char 2 89 get_code 1 89 get_code 2 89 get_single_char 1 90 get_time 1 119 get_byte 1 89 get_byte 2 89 get_byte 1 2 54 get_char 1 89 get_char 2 89 get_char 1 2 54 get_
197. flag 2 15 20 21 31 37 38 40 54 55 63 69 70 90 91 93 128 131 136 150 152 172 186 191 207 219 current_signal 3 72 current_stream 3 85 current_thread 2 124 125 DCG 55 74 dde_current_connection 2 137 dde_current_service 2 137 dde_execute 2 136 dde poke 4 136 dde_register_service 2 136 dde_request 3 136 dde_unregister_service 1 137 debug 0 25 28 69 130 182 debugging exceptions 69 debugging 0 37 130 216 DEC Alpha 13 default_module 2 146 delete 3 108 delete_directory 1 122 delete_file 1 120 deterministic O 214 Development environment 43 discontiguous 1 78 display 1 113 164 165 display 1 2 13 displayq 1 114 displayq 1 2 13 did 150 dup 2 15 dup _stream 2 15 dup stream 2 15 dwim_match 2 137 dwim_match 3 137 dwim_predicate 2 80 dwim_match 2 81 137 dynamic 1 34 75 78 80 145 207 e 0 107 edit 1 16 37 46 47 51 52 56 60 61 231 edit_source 1 61 editor class 46 47 Emacs 22 emacs prolog_colour library 49 emacs prolog_mode library 50 emacs swi_prolog library 16 47 52 ensure loaded l 56 ensure_loaded 1 28 54 56 141 erase 1 76 77 81 eval_license 0 223 eval_license 0 223 exception 3 37 215 exceptions debugging 69 exists_directory 1 120 exists_file 1 120 SWI Prolog 5 0 Reference Manual INDEX 245 exists_file 1 36 exit 2 73 exp 1 104 107 expand_answer 2 129 expand file name 2 121 expand_
198. following starts Prolog with unlimited stack size on the given source file usr bin pl L0 TO G0 s Note the use of usr bin pl which specifies the interpreter This argument is ignored in the Windows version but required to ensure best cross platform compatibility SWI Prolog 5 0 Reference Manual 30 CHAPTER 2 OVERVIEW Creating a shell script With the introduction of PrologScript see section 2 10 2 using shell scripts as explained in this section has become redundant for most applications Especially on Unix systems and not too large applications writing a shell script that simply loads your application and calls the entry point is often a good choice A skeleton for the script is given below followed by the Prolog code to obtain the program arguments bin sh base lt absolute path to source gt PL pl exec SPL f none g load_files Sbase load silent true A tgo E go current_prolog_flag argv Arguments append _SytemArgs Args Arguments go Args go Args On Windows systems similar behaviour can be achieved by creating a shortcut to Prolog passing the proper options or writing a bat file Creating a saved state For larger programs as well as for programs that are required to run on systems that do not have the SWI Prolog development system installed creating a saved state is the best solution A saved state is created using qsave_program 1 2 or us
199. foreign_t pl_get_environ term_t env term_t 1 PL_copy_term_ref env term_t a PL_new_term_ref extern char environ char e for e environ e ett if PL_unify_list l a 1 PL_unify_atom_chars a e PL_fail return PL_unify_nil 1 int PL_unify_nil term_t 71 Unify with the atom SWI Prolog 5 0 Reference Manual 170 CHAPTER 6 FOREIGN LANGUAGE INTERFACE int PL_unify_arg int index term_t t term_t a Unifies the index th argument 1 based of t with a int PL_unify_term term_t t Unify with a normally compound term The remaining arguments is a sequence of a type identifier followed by the required arguments This predicate is an extension to the Quintus and SICStus foreign interface from which the SWI Prolog foreign interface has been derived but has proved to be a powerful and comfortable way to create compound terms from C Due to the vararg packing unpacking and the required type switching this interface is slightly slower than using the primitives Please note that some bad C compilers have fairly low limits on the number of arguments that may be passed to a function Special attention is required when passing numbers C promotes any integral smaller than int to int Le the types char short and int are all passed as int In addition on most 32 bit platforms int and long are the same Upto version 4 0 5 only PL_INTEGER could be specified which
200. g most Prolog system SWI Prolog 5 0 Reference Manual 2 13 AUTOMATIC LOADING OF LIBRARIES 37 e goal_expansion 2 Same as term_expansion 2 for individual goals SICStus e prolog edit locate 3 Hook into edit 1 to locate objects SWI e prolog edit edit_source 1 Hook into edit 1 to call some internal editor SWI e prolog edit edit_command 2 Hook into edit 1 to define the external editor to use SWD e prolog list goal 1 Hook into the tracer to list the code associated to a particular goal SWI e prolog_trace_interception 4 Hook into the tracer to handle trace events SWD e prolog debug_control_hook 1 Hook in spy 1 nospy 1 nospyall 0 and debugging 0 to extend these control predicates to higher level libraries e prolog help_hook 1 Hook in help 0 help 1 and apropos 1 to extend the help system resource 3 Defines a new resource not really a hook but similar SWD e exception 3 Old attempt to a generic hook mechanism Handles undefined predicates SWI 2 13 Automatic loading of libraries If at runtime an undefined predicate is trapped the system will first try to import the predicate from the module s default module If this fails the auto loader is activated On first activation an index to all library files in all library directories is loaded in core see library_directory 1 If the undefined predicate can be located in the one of the libraries that library file is
201. g current_prolog_flag 2 The prolog 0 predicate is terminated succeeds by typing the end of file character On most systems control D The following two hooks allow for expanding queries and handling the result of a query These hooks are used by the toplevel variable expansion mechanism described in section 2 8 expand query Query Expanded Bindings ExpandedBindings Hook in module user normally not defined Query and Bindings represents the query read from the user and the names of the free variables as obtained using read_term 3 If this predicate succeeds it should bind Expanded and ExpandedBindings to the query and bindings to be executed by the toplevel This predicate is used by the toplevel prolog 0 See also expand_answer 2 andterm_expansion 2 SWI Prolog 5 0 Reference Manual 4 41 CREATING A PROTOCOL OF THE USER INTERACTION 129 expand _answer Bindings ExpandedBindings Hook in module user normally not defined Expand the result of a successfully executed toplevel query Bindings is the query Name Value binding list from the query Expand edBindings must be unified with the bindings the toplevel should print 4 41 Creating a Protocol of the User Interaction SWI Prolog offers the possibility to log the interaction with the user on a file All Prolog interaction including warnings and tracer output are written on the protocol file protocol File Start protocolling on file File If there is alrea
202. g 3 is a very fast mechanism for storing simple facts in the database Example module_transparent succeeds_n_times 2 succeeds_n times Goal Times flag succeeds_n_times Old 0 Goal flag succeeds_n_times N N 1 fail x flag succeeds_n_times Times Old 4 13 1 Update view Traditionally Prolog systems used the immediate update view new clauses became visible to predi cates backtracking over dynamic predicates immediately and retracted clauses became invisible im mediately Starting with SWI Prolog 3 3 0 we adhere the logical update view where backtrackable predicates that enter the definition of a predicate will not see any changes either caused by assert 1 or retract 1 to the predicate This view is the ISO standard the most commonly used and the most safe Logical updates are realised by keeping reference counts on predicates and generation information on clauses Each change to the database causes an increment of the generation of the database Each goal is tagged with the generation in which it was started Each clause is flagged with the generation it was created as well as the generation it was erased Only clauses with created erased interval that encloses the generation of the current goal are considered visible 4 13 2 Indexing databases By default SWI Prolog as most other implementations indexes predicates on their first argument SWI Prolog allows indexing on other and mu
203. ged to a certain limit The default sizes for these areas should suffice for most applications but big applications may require larger ones They are modified by command line options The table below shows these areas The first column gives the option name to modify the size of the area The option character is immediately followed by SWI Prolog 5 0 Reference Manual 2 16 SYSTEM LIMITS 41 a number and optionally by a k or m With k or no unit indicator the value is interpreted in Kbytes 1024 bytes with m the value is interpreted in Mbytes 1024 x 1024 bytes The local global and trail stack are limited to 128 Mbytes on 32 bit processors or more gener ally to 2bits per long 5 bytes The PrologScript facility described in section 2 10 2 provides a mechanism for specifying options with the load file On Windows the default stack sizes are controlled using the Windows registry on the key HKEY_CURRENT_USER Software SWI Prolog using the names localSize globalSize and trailSize The value is a DWORD expressing the default stack size in Kbytes A GUI for modifying these values is provided using the XPCE package To use this start the XPCE manual tools using manpce 0 after which you find Preferences in the File menu The heap With the heap we refer to the memory area used by malloc and friends SWI Prolog uses the area to store atoms functors predicates and their clauses records and other dynamic data As of SWI Prolog 2
204. h SrcDest telling SrcDest Unify the name of the current output stream with SrcDest seen Close the current input stream The new input stream becomes user told Close the current output stream The new output stream becomes user 4 16 2 Explicit Input and Output Streams The predicates below are part of the Quintus compatible stream based I O package In this package streams are explicitly created using the predicate open 3 The resulting stream identifier is then passed as a parameter to the reading and writing predicates to specify the source or destination of the data open SrcDest Mode Stream Options ISO compliant predicate to open a stream SrcDes is either an atom specifying a Unix file or a term pipe Command just like see 1 and tell 1 Mode is one of read write append or update Mode append opens the file for writing positioning the file pointer at the end Mode update opens the file for writing positioning the file pointer at the beginning of the file without truncating the file See also stream_position 3 Stream is either a variable in which case it is bound to an integer identifying the stream or an atom in which case this atom will be the stream identifier The Options list can contain the following options type 7ype Using type text default Prolog will write a text file in an operating system compatible way Using type binary the bytes will be read or written without any translation Note there
205. handler UNIX Call C function in shared so file Prove goal with bounded depth Test for atom or compound term Call goal watching for exceptions Convert between atom and ASCII value Provide mapping of input characters Classify characters Get character index on a stream Compatibility change working directory Invoke goal on all members of a list Get clauses of a predicate Get clauses of a predicate Get properties of a clause Close stream SWI Prolog 5 0 Reference Manual E 1 PREDICATES 227 close 2 close_dde_conversation 1 close_shared_object 1 compare 3 compiling O compound 1 atom_concat 3 code_type 2 concat_atom 2 concat_atom 3 consult 1 context_module 1 convert_time 8 convert_time 2 copy _stream_data 2 copy_stream_data 3 copy_term 2 current_arithmetic _function 1 current_atom 1 current_char_conversion 2 current_flag 1 current_foreign_library 2 current_format_predicate 2 current_functor 2 current_input 1 current_key 1 current_module 1 current_module 2 current_mutex 3 current_op 3 current_output 1 current_predicate 1 current_predicate 2 current_signal 3 current_stream 3 current_thread 2 dde_current_connection 2 dde_current_service 2 dde_execute 2 dde_register_service 2 dde_request 3 dde poke 3 dde_unregister_service 1 debug 0 debug _control_hook 1 debugging 0 default _module 2 Close stream forced Win32 Close DDE channel UNIX Close shared library so file Compare using a p
206. hanged since they were consulted It checks all loaded source files files loaded into a compiled state using p1 c and files loaded using consult or one of its derivatives The predicate make 0 is called after edit 1 automatically reload ing all modified files It the user uses an external editor in a separate window make 0 is normally used to update the program after editing library_directory Atom Dynamic predicate used to specify library directories Default 1ib lib prolog and the system s library in this order are defined The user may add library directories using assert 1 asserta 1 or remove system defaults using retract 1 file search path 4lias Path Dynamic predicate used to specify path aliases This feature is best described using an exam ple Given the definition file_search_path demo usr lib prolog demo SWI Prolog 5 0 Reference Manual 4 3 LOADING PROLOG SOURCE FILES 57 the file specification demo myfile will be expanded to usr lib prolog demo myfile The second argument of file search_path 2 may be another alias Below is the initial definition of the file search path This path implies swi Path refers to a file in the SWI Prolog home directory The alias foreign Path is intended for storing shared libraries so or DLL files See also load_foreign_library 1 2 user file_search_path library X library_directory X user file_search_path swi Home
207. he contents of a SWI Prolog resource file The options are inspired by the Unix ar program The basic command is o plre option resource file member The options are described below l List contents of the archive X Extract named or all members of the archive into the current directory a Add files to the archive If the archive already contains a member with the same name the contents is replaced Anywhere in the sequence of members the options class class and encoding encoding may appear They affect the class and encoding of subsequent files The initial class is data and encoding none d Delete named members from the archive This command is also described in the p1 1 Unix manual page 7 4 Finding Application files If your application uses files that are not part of the saved program such as database files configuration files etc the runtime version has to be able to locate these files The file_search_path 2 mechanism in combination with the palias command line argument is the preferred way to locate runtime files The first step is to define an alias for the toplevel directory of your application We will call this directory gnat dir in our examples A good place for storing data associated with SWI Prolog runtime systems is below the emulator s home directory swi is a predefined alias for this directory The following is a useful default definition for the search path SWI Prolog 5 0 Reference
208. he default is to set this prolog flag to 0 if a commandline editor is provided see prolog flag readline and 15 otherwise gc bool changeable If true default the garbage collector is active If false neither garbage collection nor stack shifts will take place even not on explicit request May be changed agce_margin integer changeable If this amount of atoms has been created since the last atom garbage collection perform atom garbage collection at the first opportunity Initial value is 10 000 May be changed A value of 0 zero disables atom garbage collection See also PL_register_atom iso bool changeable Include some weird ISO compatibility that is incompatible to normal SWI Prolog be haviour Currently it has the following effect e is 2 and evaluation under flag 3 do not automatically convert floats to integers if the float represents an integer e The 2 float division always return a float even if applied to integers that can be divided e In the standard order of terms see section 4 6 1 all floats are before all integers e atom_length 2 yields an instantiation error if the first argument is a number e clause 2 3 raises a permission error when accessing static predicates e abolish 1 2 raises a permission error when accessing static predicates optimise bool changeable If true compile in optimised mode The initial value is t rue if Prolog was started with the O commandline option Currentl
209. he other term For example 2 foo a B foo A b A a B b Unlike assignment which does not exist in Prolog unification is not directed update view How Prolog behaves when a dynamic predicate is changed while it is running There are two models In most older Prolog systems the change becomes immediately visible to the goal in modern systems including SWI Prolog the running goal is not affected Only new goals see the new definition variable A Prolog variable is a value that is not yet bound After binding a variable it cannot be modified Backtracking to a point in the execution before the variable was bound will turn it back into a variable A b A II Q A b true A c A b _G283 A c D See also unify SWI Prolog 5 0 Reference Manual SWI Prolog License Conditions and Tools SWI Prolog licensing aims at a large audience combining ideas from the Free Software Foundation and the less principal Open Source Initiative The license aims at e Make SWI Prolog itself and its libraries are As free as possible e Allow for easy integration of contributions See section D 2 e Free software can build on SWI Prolog without limitations e Non free open or proprietary software can be produced using SWI Prolog although con tributed pure GPL ed components cannot be used To achieve this different parts of the system have different licenses SWI Prolog progr
210. he predicate assertz Term Reference Equivalent to assert 2 recorda Key Term Reference Assert Term in the recorded database under key Key Key is an integer atom or term Reference is unified with a unique reference to the record see erase 1 recorda Key Term Equivalent to recorda Key Value _ recordz Key Term Reference Equivalent to recorda 3 but puts the Term at the tail of the terms recorded under Key recordz Key Term Equivalent to recordz Key Value _ recorded Key Value Reference Unify Value with the first term recorded under Key which does unify Reference is unified with the memory location of the record SWI Prolog 5 0 Reference Manual 4 13 DATABASE 77 recorded Key Value Equivalent to recorded Key Value erase Reference Erase a record or clause from the database Reference is an integer returned by recorda 3 or recorded 3 clause 3 assert 2 asserta 2 or assertz 2 Other integers might conflict with the internal consistency of the system Erase can only be called once on a record or clause A second call also might conflict with the internal consistency of the system flag Key Old New Key is an atom integer or term Unify Old with the old value associated with Key If the key is used for the first time Old is unified with the integer 0 Then store the value of New which should be an integer float atom or arithmetic expression under Key fla
211. he top Number predicates according the percentage CPU time used profiler Old New Query or change the status of the profiler The status is one of of f plain or cumulative plain implies the time used by children of a predicate is not added to the time of the predicate For status cumulative the time of children is added except for recursive calls Cumulative profiling implies the stack is scanned up to the top on each time slice to find all active predicates This implies the overhead grows with the number of active frames on the stack Cumulative profiling starts debugging mode to disable tail recursion optimisation which would otherwise remove the necessary parent environments Switching status from plain to cumulative resets the profiler Switching to and from status of f does not reset the collected statistics thus allowing to suspend profiling for certain parts of the program 3 show profile 1 is defined in Prolog and takes a considerable amount of memory SWI Prolog 5 0 Reference Manual 134 CHAPTER 4 BUILT IN PREDICATES reset_profiler Switches the profiler to of f and clears all collected statistics profile_count Head Calls Promilage Obtain profile statistics of the predicate specified by Head Head is an atom for predi cates with arity O or a term with the same name and arity as the predicate required see current _predicate 2 Calls is unified with the number of calls and redos while th
212. ic module SWI Prolog 5 0 Reference Manual 156 CHAPTER 6 FOREIGN LANGUAGE INTERFACE foreign_t Return type for a C function implementing a Prolog predicate control_t Passed as additional argument to non deterministic foreign functions See PL_retry and PL_foreign_context install_t Type for the install and uninstall functions of shared or dynamic link libraries See se crefshlib 6 6 The Foreign Include File 6 6 1 Argument Passing and Control If Prolog encounters a foreign predicate at run time it will call a function specified in the predicate definition of the foreign predicate The arguments 1 arity pass the Prolog arguments to the goal as Prolog terms Foreign functions should be declared of type foreign_t Deterministic foreign functions have two alternatives to return control back to Prolog void PL_succeed Succeed deterministically PL_succeed is defined as return TRUE void PL _failQ Fail and start Prolog backtracking PL _fail is defined as return FALSE Non deterministic Foreign Predicates By default foreign predicates are deterministic Using the PL_FA NONDETERMINISTIC attribute see PL_register_foreign it is possible to register a predicate as a non deterministic predi cate Writing non deterministic foreign predicates is slightly more complicated as the foreign function needs context information for generating the next solution Note that the same foreign function should be prepared to
213. icense 2 Get name and arity of a term or construct a term Invoke the garbage collector Invoke the atom garbage collector Generate unique atoms from a base Read first non blank character Read first non blank character from a stream Read next character Read next character from a stream Read next byte ISO Read next byte from a stream ISO Read next character as an atom ISO Read next character from a stream ISO Read next character ISO Read next character from a stream ISO Read next character from the terminal Get current time Get shell environment variable Hook for macro expanding goals Verify term holds no unbound variables Install hooks for the graphical debugger Exit from Prolog Exit from Prolog with status Hash value of ground term Give help on help Give help on predicates and show parts of manual hook User hook in the help system Call the argument but always succeed Import a predicate from a module Include a file with declarations Change clause indexing Initialization directive Convert from integer to atom Convert from integer to atom non decimal Type check for integer Start new thread with console and toplevel Set intersection Evaluate arithmetic expression True if arg defines an absolute path Type check for a list Type check for a set Sort using a key Last element of a list Change ports visited by the tracer Length of a list hook Directories holding Prolog libraries Define li
214. ified characters is slightly more flexible to improve compatibility Va Alert character Normally the ASCII character 7 beep Wo Backspace character c No output All input characters up to but not including the first non layout character are skipped This allows for the specification of pretty looking long lines For compatibility with Quintus Prolog Not supported by ISO Example format This is a long line that would look better if it was c split across multiple physical lines in the input RETURN No output Skips input till the next non layout character or to the end of the next line Same intention as c but ISO compatible Form feed character n Next line character SWI Prolog 5 0 Reference Manual 40 CHAPTER 2 OVERVIEW Vr Carriage return only i e go back to the start of the line t Horizontal tab character v Vertical tab character ASCII 11 x23 Hexadecimal specification of a character 23 is just an example The x may be followed by a maximum of 2 hexadecimal digits The closing is optional The code xa 3 emits the character 10 hexadecimal a followed by 3 The code x201 emits 32 hexadecimal 20 followed by 1 According to ISO the closing is obligatory and the number of digits is un limited The SWI Prolog definition allows for ISO compatible specification but is compatible with other implementations 40 Octal character specification
215. ign_context_address 157 PL_foreign_control 157 PL functor_arityO 159 PL _functor_name 159 PL get argO 163 PL_get_atom 161 PL_get_ atom chars 161 PL_get_atom_nchars 163 PL_get chars 161 PL_get float 162 PL_get functor 162 PL_get_head 164 PL_get integer 162 PL _get list 164 PL_get_list_chars 162 PL _get list _nchars 163 PL_get_long 162 PL_get_module 162 PL_get_name_arity 162 PL_get nchars 163 PL_get_nild 164 PL_get_pointer 162 PL_get_string_chars 161 PL_get_tail 164 PL halt 190 PL_initialiseQ 189 PL_install readline 190 PL_is_atom 160 PL_is_atomic 161 PL is compound 161 PL_is_float 161 PL is functor 161 PL_is_initialised 190 PL is integer 160 PL is list 161 PL_is_number 161 PL_is_string 160 PL_is_variable 160 PL_license 224 PL_load_extensions 183 PL_module_name 176 PL_new_atom 157 PL_new_atom_nchars 163 PL_new_functor 159 PL_new_module 176 PL_new_term ref 154 PL_new_term refs 154 PL_next_solution 174 PL_on_halt 184 PL_open_foreign_frame 174 PL_open_query 173 PL_predQ 172 PL_predicate 172 PL_predicate_info 173 PL_put_atom 166 PL_put_atom_chars 166 PL_put_atom_nchars 163 PL_put_float 166 PL_put_functor 166 PL_put_integer 166 PL_put_listQ 166 PL_put_list_charsQ 166 PL_put_list_nchars 163 PL_put_list_ncodes 163 PL_put_nil 166 PL_pu
216. iles directly for some operating systems notably Unix systems using the BSD a out executable format As the number of Unix platforms supporting this gets quickly smaller and this interface is difficult to port and slow it is no longer described in this manual The best alternatively would be to use the dld package on machines do not have shared libraries SWI Prolog 5 0 Reference Manual 6 4 USING THE LIBRARY SHLIB FOR DLL AND so FILES 151 close_shared_object Handle Detach the shared object identified by Handle call_shared_object_function Handle Function Call the named function in the loaded shared library The function is called without arguments and the return value is ignored Normally this function installs foreign language predicates using calls to PL_register_foreign 6 4 Using the library shlib for DLL and so files This section discusses the functionality of the autoload library shlib p1 providing an interface to shared libraries This library can only be used if the prolog flag open_shared_object is enabled load foreign library ib Entry Search for the given foreign library and link it to the current SWI Prolog instance The library may be specified with or without the extension First absolute_file_name 3 is used to lo cate the file If this succeeds the full path is passed to the low level function to open the library Otherwise the plain library name is passed exploiting the operating sys
217. ine option is given this goal is started instead of entering the default interactive top level prolog 0 abort Abort the Prolog execution and restart the top level If the t toplevel command line options is given this goal is started instead of entering the default interactive top level There are two implementations of abort 0 The default one uses the exception mechanism see throw 1 throwing the exception Saborted The other one uses the C construct longjmp to discard the entire environment and rebuild a new one Using exceptions allows for proper recovery of predicates exploiting exceptions Rebuilding the environment is safer if the Prolog stacks are corrupt Therefore the system will use the rebuild strategy if the abort was generated by an internal consistency check and the exception mechanism otherwise Prolog can be forced to use the rebuild strategy setting the prolog flag abort _with_exception to false halt Terminate Prolog execution Open files are closed and if the command line option tty is not active the terminal status see Unix stty 1 is restored Hooks may be registered both in Prolog and in foreign code Prolog hooks are registered using at_halt 1 halt 0 is equivalent to halt 0 halt Status Terminate Prolog execution with given status Status is an integer See also halt 0 prolog This goal starts the default interactive top level Queries are read from the stream user_input See also the history prolog fla
218. ing Signals Software Interrupts o o 181 6 6 13 Errors and wamings lt s o ca A ia e h 181 6 6 14 Environment Control from Foreign Code oo o 181 6 6 15 Querying Prolog uuu era iia ed ad a a e 181 SWI Prolog 5 0 Reference Manual 6 6 16 Registering Foreign Predicates ocu a a a 183 6617 Foreign Code HOOKS e s s cd ee ew a Ee o h 184 6 6 18 Storing foreign data er wa oa aa we a eR oa ee a Sa ee 185 6 6 19 Embedding SWI Prolog inaC program 188 6 7 Linking embedded applications using plld 4 190 671 Asimple example coce aon oe ke a Se ee a a eS 192 6 8 TheFrolog home directory oc s oo Bade da ed Pe erea eee datas 194 6 9 Example of Using the Foreign Interface o o e 194 6 10 Notes on Using Foreign Code cios a we 197 610 1 Memory Allocatigi gt s ca 345 2a Bae ee BS dee a ee Bad 197 6102 Debusgme Foreign Code s ca cia caca tanco or ee taled anat 197 6 10 3 Name Conflicts in C modules o o e 00005 197 6 10 4 Compatibility of the Foreign Interface o o o 197 7 Generating Runtime Applications 199 TA Limitations 0 qsave program 2204 4464 ora a wa ea Pea oars 201 7 2 Runtimes and Foreign Code oo o ccoo oe aea oaoa oka Ca eR eee ee eae 201 To Usine program resources oc a RA a 202 Tad Predicates Defnitons oe se s moe os hoy Bi dk e EEE ea ee Rw SY 203 Tal Theplee pofa caida
219. ing the linker plld 1 A saved state is a file containing machine independent intermediate code in a format dedicated for fast loading Optionally the emu lator may be integrated in the saved state creating a single file but machine dependent executable This process is described in chapter 7 Compilation using the c commandline option This mechanism loads a series of Prolog source files and then creates a saved state as qsave_program 2 does The command syntax is pl option o output c file The options argument are options to gsave_program Z2 written in the format below The option names and their values are described with qsave_program 2 option name option value SWI Prolog 5 0 Reference Manual 2 11 ENVIRONMENT CONTROL PROLOG FLAGS 31 For example to create a stand alone executable that starts by executing main 0 and for which the source is loaded through load p1 use the command pl goal main stand_alone true o myprog c load pl This performs exactly the same as executing pl lt banner gt load qsave_program myprog goal main stand_alone true halt 2 11 Environment Control Prolog flags The predicates current _prolog_flag 2 and set _prolog_flag 2 allow the user to examine and modify the execution environment It provides access to whether optional features are available on this version operating system foreign code environment
220. ion plversion Copyright c 1993 1996 University of Amsterdam All rights reserved For help use help Topic or apropos Word load_foreign_library lowercase lt type Control C gt gdb shared loads symbols for shared objects gdb break pl_lowercase gdb continue lowercase HELLO X 6 10 3 Name Conflicts in C modules In the current version of the system all public C functions of SWI Prolog are in the symbol table This can lead to name clashes with foreign code Someday I should write a program to strip all these symbols from the symbol table why does Unix not have that For now I can only suggest to give your function another name You can do this using the C preprocessor If for example your foreign package uses a function warning which happens to exist in SWI Prolog as well the following macro should fix the problem define warning warning_ Note that shared libraries do not have this problem as the shared library loader will only look for symbols in the main executable for symbols that are not defined in the library itself 6 10 4 Compatibility of the Foreign Interface The term reference mechanism was first used by Quintus Prolog version 3 SICStus Prolog version 3 is strongly based on the Quintus interface The described SWI Prolog interface is similar to using the SWI Prolog 5 0 Reference Manual 198 CHAPTER 6 FOREIGN LANGUAGE INTERFACE Quintus or SICStus interfaces d
221. ion 6 4 for loading Windows DLL s into SWI Prolog 4 46 1 DDE client interface The DDE client interface allows Prolog to talk to DDE server programs We will demonstrate the use of the DDE interface using the Windows PROGMAN Program Manager application 1 open_dde_conversation progman progman C c 0 2 dde _request 0 groups X gt Unifies X with description of groups 3 dde_execute 0 CreateGroup DDE Demo Yes 4 close_dde conversation 0 Yes For details on interacting with progman use the SDK online manual section on the Shell DDE interface See also the Prolog library progman which may be used to write simple Windows setup scripts in Prolog open_dde_conversation Service Topic Handle Open a conversation with a server supporting the given service name and topic atoms If successful Handle may be used to send transactions to the server If no willing server is found this predicate fails silently 4This interface is contributed by Don Dwiggins SWI Prolog 5 0 Reference Manual 136 CHAPTER 4 BUILT IN PREDICATES close_dde_conversation Handle Close the conversation associated with Handle All opened conversations should be closed when they re no longer needed although the system will close any that remain open on process termination dde_request Handle Item Value Request a value from the server Item is an atom that identifies the requested data an
222. iscusses the generation of runtime executables Runtime executables are a mean to deliver executables that do not require the Prolog system 2 4 Command line options The full set of command line options is given below help When given as the only option it summarises the most important options V When given as the only option it summarises the version and the architecture identifier arch When given as the only option it prints the architecture identifier see current_prolog_flag arch Arch and exits See also dump runtime variables dump runtime variables When given as the only option it prints a sequence of variable settings that can be used in shell scripts to deal with Prolog parameters This feature is also used by p1lld see section 6 7 Below is a typical example of using this feature eval pl dump runtime variables cc ISPLBASE include LSPLBASE runtime PLARCH SWI Prolog 5 0 Reference Manual 20 CHAPTER 2 OVERVIEW q Set the prolog flag verbose to silent supressing informational and banner messages Lsize km Give local stack limit 2 Mbytes default Note that there is no space between the size option and its argument By default the argument is interpreted in Kbytes Postfixing the argument with m causes the argument to be interpreted in Mbytes The following example specifies 32 Mbytes local stack pl L32m A maximum is useful to stop buggy programs from claiming all memory re
223. ise make_library_index 1 is called creating an index for all p1 files containing a module Below is an example creating a completely indexed library directory mkdir lib prolog cd IS pl g true t make_library_index A o If there are more than one library files containing the desired predicate the following search schema 1s followed 1 If there is a library file that defines the module in which the undefined predicate is trapped this file is used 2 Otherwise library files are considered in the order they appear in the Library_directory 1 predicate and within the directory alphabetically make library_index Directory Create an index for this directory The index is written to the file INDEX pl in the specified directory Fails with a warning if the directory does not exist or is write protected make _library_index Directory ListOfPatterns Normally used in MKINDEX p1 this predicate creates INDEX p1 for Directory indexing all files that match one of the file patterns in ListOfPatterns Sometimes library packages consist of one public load file and a number of files used by this load file exporting predicates that should not be used directly by the end user Such a library can be placed in a sub directory of the library and the files containing public functionality can be added to the index of the library As an example we give the XPCE library s MKINDEX pl including the public functionality of trace
224. it_source 1 prolog_edit edit_command 2 prolog edit load 0 prolog file type 2 prolog_frame_attribute 3 prolog_list_goal 1 N th clause of a predicate Type check for integer or float Convert between number and one char atoms Convert between number and ASCII values Enumerate unbound variables of a term using a given base Handle a software signal Call a goal deterministically Declare an operator Open a file creating a stream Open a file creating a stream Win32 Open DDE channel Open a stream to discard output Open a program resource as a stream UNIX Open shared library so file UNIX Open shared library so file Read byte without removing Read byte without removing Read character without removing Read character without removing Read character code without removing Read character code without removing Activate grammar rule set Activate grammar rule set returning rest Query change environment parameters Logical integer addition hook Modify behaviour of print 1 Pretty print a clause Query predicate attributes Sort using a predicate to determine the order Install a preprocessor before the compiler Print a term Print a term on a stream Print message from exception term Print message to stream Obtain execution statistics Obtain profile results on a predicate Obtain change status of the profiler Run interactive toplevel Reference to goal s environment stack Locate targets for edit 1 L
225. ith default permissions defined by the process umask setting delete_directory Directory Delete directory folder from the filesystem Raises an exception on failure Please note that in general it will not be possible to delete a non empty directory working _directory Old New Unify Old with an absolute path to the current working directory and change working directory to New Use the pattern working_directory CWD CWD to get the current directory See also absolute_file_name 2 and chdir 1 chdir Path Compatibility predicate New code should use working_directory 2 20n Windows the home directory is determined as follows if the environment variable HOME exists this is used If the variables HOMEDRIVE and HOMEPATH exist Windows NT these are used At initialisation the system will set the environment variable HOME to point to the SWI Prolog home directory if neither HOME nor HOMEPATH and HOMEDRIVE are defined 2IBUG Some of the file I O predicates use local filenames Changing directory while file bound streams are open causes wrong results on telling 1 seeing 1 and current_stream 3 SWI Prolog 5 0 Reference Manual 4 39 MULTI THREADING ALPHA CODE 123 4 39 Multi threading alpha code The features described in this section are only enabled on Unix systems providing POSIX threads and if the system is configured using the enable mt option SWI Prolog multi the
226. k over the alternatives of these free variables unifying Bag with the corresponding alternatives of Var The construct Var Goal tells bagof not to bind Var in Goal bagof 3 fails if Goal has no solutions The example below illustrates bagof 3 and the operator The variable bindings are printed together on one line to save paper 2 listing foo foo a foo a foo b foo b foo c b b C C C anheoaana Yes 3 bagof C foo A B A a B b C A C A c B C C G308 G308 G308 Cs Cs Cs Q II O ll Q No 4 bagof C A foo A B C Cs Cs A G324 B A G324 B Dr CoS Er G326 G326 Q II O No a 2 setof Var Goal Set Equivalent to bagof 3 but sorts the result using sort 2 to get a sorted list of alternatives without duplicates 4 33 Invoking Predicates on all Members of a List All the predicates in this section call a predicate on all members of a list or until the predicate called fails The predicate is called via call 2 which implies common arguments can be put in front of the arguments obtained from the list s For example 0 1 2 maplist plus 1 X we will phrase this as Predicate is applied on SWI Prolog 5 0 Reference Manual 112 CHAPTER 4 BUILT IN PREDICATES checklist Pred List Pred is applied successively on each element of List until the end of the list or Pr
227. l mechanism used by the binary distribution 4 If the precompiled path exists use 1t This is only useful for a source installation If all fails and there is no state attached to the executable or provided Windows module see PL initialise SWI Prolog gives up If a state is attached the current working directory is used The file_search_path 2 alias swi is set to point to the home directory located 6 9 Example of Using the Foreign Interface Below is an example showing all stages of the declaration of a foreign predicate that transforms atoms possibly holding uppercase letters into an atom only holding lower case letters Figure 6 6 shows the C source file figure 6 7 illustrates compiling and loading of foreign code SWI Prolog 5 0 Reference Manual 6 9 EXAMPLE OF USING THE FOREIGN INTERFACE 195 Include file depends on local installation include lt SWI Prolog h gt include lt stdlib h gt include lt ctype h gt foreign_t pl_lowercase term_t u term t 1 char copy char s Q int rval if PL_get_atom_chars u s return PL_warning lowercase 2 instantiation fault copy malloc strlen s 1 for gq copy s qtt stt q isupper s tolower s s q TOT rval PL_unify_atom_chars l copy free copy return rval install t install PL_register_foreign lowercase 2 pl_lowercase 0 Figure 6 6 Lowerca
228. l time which predicates are not used or not defined Using modules is generally easy Only if you write meta predicates predicates reasoning about other predicates that are exported from a module good understanding of resolution of terms to predi cates inside a module is required Here is a typical example from library readut il module read_util read_file_to_codes 3 read_file_to_terms 3 File Codes Options ile Terms Options read_line_to_codes 2 Fd Codes read_line_to_codes 3 Fd Codes Tail read_stream_to_codes 2 Fd Codes read_stream_to_codes 3 Fd Codes Tail SWI Prolog 5 0 Reference Manual 46 CHAPTER 3 INITIALISING AND MANAGING A PROLOG PROJECT 3 3 The test edit reload cycle SWI Prolog does not enforce the use of a particular editor for writing down Prolog source code Editors are complicated programs that must be mastered in detail for real productive program ming and if you are familiar with a specific editor you should not be forced to change You may specify your favourite editor using the environment variable EDITOR or by defining rules for prolog_edit edit_source 1 see section 4 4 The use of a built in editor however has advantages The XPCE editor object around which the built in PceEmacs is built can be opened as a Prolog stream allowing analysis of your source by the real Prolog system 3 3 1 Locating things to edit The central predica
229. le Module PublicList This directive can only be used as the first term of a source file It declares the file to be a module file defining Module and exporting the predicates of PublicList PublicList is a list of name arity pairs module_transparent Preds Preds is a comma separated list of name arity pairs like dynamic 1 Each goal associated with a transparent declared predicate will inherit the context module from its parent goal meta_predicate Heads This predicate is defined in library quintus and provides a partial emulation of the Quintus predicate See section 5 9 1 for details current_module Module Generates all currently known modules current_module Module File Is true if File is the file from which Module was loaded File is the internal canonical filename See also source_file 1 2 context_module Module Unify Module with the context module of the current goal context_module 1 itself is transparent export Head Add a predicate to the public list of the context module This implies the predicate will be imported into another module if this module is imported with use_module 1 2 Note that predicates are normally exported using the directive module 2 export 1 is meant to handle export from dynamically created modules export_list Module Exports Unifies Exports with a list of terms Each term has the name and arity of a pub lic predicate of Module The order of the terms in Exports is not define
230. le_search_path 2 is prolog_load_context directory Dir asserta user file_search_path myapp Dir user file_search_path graph myapp graph user file_search_path ui myapp ul For using sub projects in the SWI Prolog hierarchy one should use the path alias swi as basis For a system wide installation use an absolute path Extensive sub projects with a small well defined API should define a load file using use _module 1 calls to import the various library components and export the API 3 1 2 Project Special Files There are a number of tasks you typically carry out on your project such as loading it creating a saved state debugging it etc Good practice on large projects is to define small files that hold the commands to execute such a task name this file after the task and give it a file extension that makes starting easy see section 3 1 1 The task load is generally central to these tasks Here is a tentative list e load pl Use this file to set up the environment prolog flags and file search paths and load the sources Quite commonly this file also provides convenient predicates to parse command line options and start the application e run pl Use this file to start the application Normally it loads load p1 in silent mode and calls one of the starting predicates from load pl SWI Prolog 5 0 Reference Manual 3 2 USING MODULES 45 3 2 save pl Use this file to create a saved state of the applica
231. led as many times as PL_thread_attach_engine in this thread Returns TRUE on success and FALSE if the calling thread has no engine or this Prolog does not support threads Please note that construction and destruction of engines are relatively expensive operations Only destroy an engine if performance is not critical and memory is a critical resource The engine is automatically destroyed if the thread finishes regardless how many times PL_thread_attach_engine has been called 6 6 11 Miscellaneous Term Comparison int PL_compare term_t tl term_t t2 Compares two terms using the standard order of terms and returns 1 0 or 1 See also compare 3 int PL same compound term t tl term_t t2 Yields TRUE if t and t2 refer to physically the same compound term and FALSE otherwise Recorded database In some applications it is useful to store and retreive Prolog terms from C code For example the XPCE graphical environment does this for storing arbitrary Prolog data as slot data of XPCE objects Please note that the returned handles have no meaning at the Prolog level and the recorded terms are not visible from Prolog The functions PL_recorded and PL_erase are the only func tions that can operate on the stored term Two groups of functions are provided The first group PL_record and friends store Prolog terms on the Prolog heap for retrieval during the same session These functions are also used by recorda 3 and friends The recor
232. lib directory for shared libraries 1ib arch machine specific shared libraries SWI Prolog 5 0 Reference Manual The SWI Prolog library This chapter documents the SWI Prolog library As SWI Prolog provides auto loading there is little difference between library predicates and built in predicates Part of the library is therefore docu mented in the rest of the manual Library predicates differ from built in predicates in the following ways e User definition of a built in leads to a permission error while using the name of a library pred icate is allowed e If autoloading is disabled explicitely or because trapping unknown predicates is disabled see unknown 2 and current _prolog_flag 2 library predicates must be loaded explicitely e Using libraries reduced the footprint of applications that don t need them The documentation of the library is just started Material from the standard packages should be moved here some material from other parts of the manual should be moved too and various libraries are not documented at all A 1 library check Elementary completeness checks This library defines the predicate check 0 and a few friends that allow for a quick and dirty cross referencing check Performs the three checking passes implemented by list_undefined 0 list_autoload 0 and list_redefined 0 Please check the definition of these predicates for details The typical usage of this predicate is right afte
233. lowed to use assert 1 retract 1 or any other database predicate in term_expansion 2 other than for local computational purposes Directives may be placed anywhere in a source file invoking any predicate They are executed when encountered If the directive fails a warning is printed Directives are specified by 1 or 1 There is no difference between the two SWI Prolog does not have a separate reconsult 1 predicate Reconsulting is implied auto matically by the fact that a file is consulted which is already loaded load_files Files Options The predicate load_files 2 is the parent of all the other loading predicates It currently supports a subset of the options of Quintus load_files 2 Files is either specifies a single or a list of source files The specification for a source file is handled absolute_file_name 2 See this predicate for the supported expansions Options is a list of options using the format OptionName OptionValue The following options are currently supported if Condition Load the file only if the specified condition is satisfied The value t rue loads the file unconditionally changed loads the file if it was not loaded before or has been modified since it was loaded the last time not_loaded loads the file if it was not loaded before must_be_module Boo If t rue raise an error if the file is not a module file Used by use module 1 2 imports ListOrAll If all and the file is a modul
234. lp the programmer while debugging In its most generic form this is a term of the form context Name Arity Message where Name Arity describes the built in predicate that raised the error and Message provides an additional description of the error Any part of this structure may be a variable if no information was present ST d like to acknowledge Bart Demoen for his clarifications on these matters SWI Prolog 5 0 Reference Manual 70 CHAPTER 4 BUILT IN PREDICATES 4 9 3 Printing messages The predicate print _message 2 may be used to print a message term in a human readable for mat The other predicates from this section allow the user to refine and extend the message system The most common usage of print _message 2 is to print error messages from exceptions The code below prints errors encountered during the execution of Goal without further propagating the exception and without starting the debugger se cae catch Goal E print_message error E fail Another common use is to defined message_hook 3 for printing messages that are normally silent suppressing messages redirecting messages or make something happen in addition to printing the message print_message Kind Term The predicate print message 2 is used to print messages notably from exceptions in a human readable format Kind is one of informational banner warning error help or silent A human readable message is printed to the stream user_error
235. lp_hook Action Hook into help 0 and help 1 If the hook succeeds the built in actions are not executed For example help picture is caught by the XPCE help hook to give help on the class picture Defined actions are help User entered plain hel p 0 to give default help The default performs help help 1 giving help on help help What Hook in he1p 1 on the topic What apropos What Hook in apropos 1 on the topic What B 5 Readline Interaction The following predicates are available if current_prolog_flag readline true suc ceeds They allow for direct interaction with the GNU readline library See also readline 3 rl_read init file File Read a readline initialisation file Readline by default reads input rc This predicate may be used to read alternative readline initialisation files rl_add_history Line Add a line to the Control P Control N history system of the readline library SWI Prolog 5 0 Reference Manual Glossary of Terms anonymous variable The variable _ is called the anonymous variable Multiple occurrences of _ in a single term are not shared arguments Arguments are terms that appear in a compound term Al and a2 are the first and second argument of the term myterm A J a2 arity Argument count is number of arguments of a compound term assert Add a clause to a predicate Clauses can be added at either end of the clause list of a predicate See assert 1 and assertz 1 at
236. ltiple arguments using the declaration index 1 For advanced database indexing it defines hash_term 2 BUG The system should have a special type for pointers thus avoiding the Prolog user having to worry about consis tency matters Currently some simple heuristics are used to determine whether a reference is valid SFor example using the immediate update view no call to a dynamic predicate is deterministic SWI Prolog 5 0 Reference Manual 78 CHAPTER 4 BUILT IN PREDICATES hash_term Term HashKey If Term is a ground term see ground 1 HashKey is unified with a positive integer value that may be used as a hash key to the value If Term is not ground the predicate succeeds immediately leaving HashKey an unbound variable This predicate may be used to build hash tables as well as to exploit argument indexing to find complex terms more quickly The hash key does not rely on temporary information like addresses of atoms and may be as sumed constant over different invocations of SWI Prolog 4 14 Declaring predicates properties This section describes directives which manipulate attributes of predicate definitions The functors dynamic 1 multifile 1 and discontiguous 1 are operators of priority 1150 see op 3 which implies the list of predicates they involve can just be a comma separated list dynamic foo 0 baz 2 On SWI Prolog all these directives are just predicates This implies they can also be called by
237. m or a compound term A goal succeeds in which case the variables in the compound terms have a binding or fails if Prolog fails to prove the goal SWI Prolog 5 0 Reference Manual 219 hashing Indexing technique used for quick lookup head Part of a clause before the neck instruction This is an atom or compound term imported predicate A predicate is said to be imported into a module if it is defined in another module and made available in this module See also chapter 5 indexing Indexing is a technique used to quickly select candidate clauses of a predicate for a specific goal In most Prolog systems including SWI Prolog indexing is done on the first argument of the head If this argument is instantiated to an atom integer float or compound term with functor hashing is used quickly select all clauses of which the first argument may unify with the first argument of the goal integer Whole number On most current machines SWI Prolog integers are represented as 32 bit signed values ranging from 2147483648 to 2147483647 See also current_prolog_flag 2 interpreted As opposed to compiled interpreted means the Prolog system attempts to prove a goal by directly reading the clauses rather than executing instructions from an abstract instruction set that is not or only indirectly related to Prolog meta predicate A predicate that reasons about other predicates either by calling them re defining them or quer
238. macros and extract the handle from the extra argument using the PL_foreign_context macro void PL _retry long The foreign function succeeds while leaving a choice point On backtracking over this goal the foreign function will be called again but the control argument now indicates it is a Redo call and the macro PL_foreign_context will return the handle passed via PL_retry This handle is a 30 bits signed value two bits are used for status indication void PL_retry_address void As PL_retry but ensures an address as returned by malloc is correctly recovered by PL_foreign_context_address int PL_foreign_control control_t Extracts the type of call from the control argument The return values are described above Note that the function should be prepared to handle the PL_CUTTED case and should be aware that the other arguments are not valid in this case long PL_foreign_context control_t Extracts the context from the context argument In the call type is PL_FIRST_CALL the context value is OL Otherwise it is the value returned by the last PL_ret ry associated with this goal both if the call type is PL_REDO as PL_CUTTED void PL_foreign_context_address control_t Extracts an address as passed in by PL_retry address Note If a non deterministic foreign function returns using PL_succeed or PL_fail Prolog assumes the foreign function has cleaned its environment No call with control argument PL_CUTTED
239. manual Module system has no default module assigned to it The second special module is the module user This module forms the initial working space of the user Initially it is empty The default module of module user is system making all built in predicate definitions available as defaults Built in predicates thus can be overruled by defining them in module user before they are used All other modules default to module user This implies they can use all predicates imported into user without explicitly importing them 5 5 Using the Module System The current structure of the module system has been designed with some specific organisations for large programs in mind Many large programs define a basic library layer on top of which the actual program itself is defined The module user acting as the default module for all other modules of the program can be used to distribute these definitions over all program module without introducing the need to import this common layer each time explicitly It can also be used to redefine built in predicates if this is required to maintain compatibility to some other Prolog implementation Typically the loadfile of a large application looks like this SWI Prolog 5 0 Reference Manual 142 CHAPTER 5 USING MODULES AS use_module compatibility load XYZ prolog compatibility use_module error goodies brary extensions debug virtual_machine load generic parts errors and warni
240. mat Runtime t 2 734 Inferences t D 72 n RunT Inf t 0 Will output Statistics RUDEIMOS sierra celts s 3245 IN SECENCESI emmm 60 345 format Stream Format Arguments As format 2 but write the output on the given Stream sformat String Format Arguments Equivalent to format 2 but writes the result on String instead of the current output stream Example S sformat S w t 15 w Hello Worlda Hello World sformat String Format Equivalent to sformat String Format SWI Prolog 5 0 Reference Manual 116 CHAPTER 4 BUILT IN PREDICATES 4 35 3 Programming Format format_predicate Char Head If a sequence c tilde followed by some character is found the format derivatives will first check whether the user has defined a predicate to handle the format If not the built in format ting rules described above are used Char is either an ASCII value or a one character atom specifying the letter to be re defined Head is a term whose name and arity are used to de termine the predicate to call for the redefined formatting character The first argument to the predicate is the numeric argument of the format command or the atom default if no argu ment is specified The remaining arguments are filled from the argument list The example below redefines n to produce Arg times return followed by linefeed so a Grr
241. may be a term of a the form Goal or Goal Goal is then treated as a directive If Term2 is a list all terms of the list are stored in the database or called for directives If Term2 is of the form below the system will assert Clause and record the indicated source location with it Ssource_location File Line Clause When compiling a module see chapter 5 and the directive module 2 expand_term 2 will first try term_expansion 2 in the module being compiled to allow for term expansion rules that are local to a module If there is no local definition or the local definition fails to translate the term expand_term 2 will try term_expansion 2 in module user For compatibility with SICStus and Quintus Prolog this feature should not be used See also expand_term 2 goal_expansion 2 and expand_goal 2 expand_term 7erm Term2 This predicate is normally called by the compiler to perform preprocessing First it calls term_expansion 2 If this predicate fails it performs a grammar rule translation If this fails it returns the first argument goal expansion Goall Goal2 Like term_expansion 2 goal expansion 2 provides for macro expansion of Prolog source code Between expand_term 2 and the actual compilation the body of clauses anal ysed and the goals are handed to expand_goal 2 which uses the goal_expansion 2 hook to do user defined expansion SWI Prolog 5 0 Reference Manual 4 3 LOADING PROLOG SO
242. mentation in this library covers only a small portion of the defined protocols Though the initial implementation followed RFC 1738 strictly the current is more relaxed to deal with frequent violations of the standard encountered in practical use This library contains code by Jan Wielemaker who wrote the initial version and Lukas Faulstich who added various extensions parse_url URL Parts Construct or analyse a URL URL is an atom holding a URL or a variable Parts is a list of components Each component is of the format Name Value Defined components are SWI Prolog 5 0 Reference Manual A 5 LIBRARY URL ANALYSING AND CONSTRUCTING URL 211 protocol Protocol The used protocol This is after the optional url an identifier separated from the remainder of the URL using parse_url 2 assumes the http protocol if no protocol is specified and the URL can be parsed as a valid HTTP url In addition to the RFC 1738 specified protocols the file protocol is supported as well host Host Host name or IP address on which the resource is located Supported by all network based protocols port Port Integer port number to access on the Host This only appears if the port is explicitly specified in the URL Implicit default ports e g 80 for HTTP do not appear in the part list path Path File path addressed by the URL This is supported for the ftp http and file pro tocols If no path appears the library generates the pa
243. mented yet Give the next argument to print 1 q Give the next argument to writeq l Print integer in radix the numeric argument notation Thus 16r prints its argument hexadecimal The argument should be in the range 2 36 Lower case letters are used for digits above 9 SWI Prolog 5 0 Reference Manual 4 35 FORMATTED WRITE 115 Same as r but uses upper case letters for digits above 9 Output a string of ASCII characters or a string see string 1 and section 4 23 from the next argument All remaining space between 2 tabs tops is distributed equally over t statements between the tabs tops This space is padded with spaces by default If an argument is supplied this is taken to be the ASCII value of the character used for padding This can be used to do left or right alignment centering distributing etc See also and to set tab stops A tabs top is assumed at the start of each line Set a tabs top on the current position If an argument is supplied set a tabs top on the position of that argument This will cause all t s to be distributed between the previous and this tabs top Set a tabs top relative to the current position Further the same as w Give the next argument to write 1 W Give the next two argument to write_term 2 This option is SWI Prolog specific Example simple_statistics lt obtain statistics gt left to the user format tStatistics t 72 nn for
244. metic_function 1 107 asin 1 106 assert 1 55 56 75 78 143 146 217 assert 2 76 77 81 asserta 1 21 56 76 asserta 2 76 77 assertz 1 76 217 assertz 2 76 77 at_end_of_stream 0 90 at_end_of_stream 1 90 INDEX 243 at_halt 1 59 at_initialization 1 59 at_end_of_stream 0 1 85 at_halt 1 59 125 128 184 190 at_initialization 1 59 189 atan 1 106 atan 2 106 atom 1 62 159 atom _char 2 96 atom_chars 2 14 96 atom_codes 2 96 atom_concat 3 97 233 atom_length 2 98 atom_prefix 2 98 atom_to_term 3 97 atom_chars 2 33 54 89 96 100 atom_codes 2 15 33 54 96 100 atom_concat 3 97 101 atom_length 2 34 101 atom_to_term 3 90 atomic l 62 attach_console 0 127 attach_console 0 127 autoload 0 56 199 200 208 backcomp library 13 15 bagof 3 110 111 225 between 3 103 block 3 73 225 228 break O 21 26 128 182 call 1 14 59 62 66 68 130 172 call 2 66 call 2 6 66 call_cleanup 2 68 call_cleanup 3 67 call_shared_object function 2 151 call_with_depth_limit 3 67 call_cleanup 2 68 call_cleanup 3 68 call_with_depth limit 3 67 callable 1 62 catch 3 13 14 68 69 73 92 124 215 234 ceil 1 106 ceiling 1 106 char_code 2 96 char_conversion 2 102 char_type 2 98 char_code 2 54 char_conversion 2 34 103 char type 2 100 character_count 2 87 chdir 1 122 check library 207 236 check O 56 207 check_old_select 0 15 checklist 2 112
245. ms 7 fidt frid PL term_t goal term_t al term_t a2 functor_t s2 int atoms pen_foreign_frame L_new_term_ref L_new_term_ref L_new_term_ref L new_functor PL_new_atom statistics 2 0 P P P P PL_put_atom_chars al atoms PL_cons_functor goal s2 al a2 L_call goal NULL call it in current module FU PL_get_integer a2 satoms L_discard_foreign_frame fid FU return atoms Figure 6 4 Calling Prolog void PL_close foreign frame fid_t id Discard all term references created after the frame was opened All other Prolog data is retained This function is called by the kernel whenever a foreign function returns control back to Prolog void PL discard foreign frame fid_t id Same as PL_close_foreign_frame but also undo all bindings made since the open and destroy all Prolog data void PL_rewind foreign frame fid_t id Undo all bindings and discard all term references created since the frame was created but does not pop the frame Le the same frame can be rewinded multiple times and must eventually be closed or discarded It is obligatory to call either of the two closing functions to discard a foreign frame Foreign frames may be nested 6 6 8 Foreign Code and Modules Modules are identified via a unique handle The following functions are available to query and ma nipulate modules module_t PL_context Return the module identifier of the c
246. n There are a couple of possibilities for representing the handle The choice depends on respon sibilities and debugging facilities The simplest aproach is to using PL unify pointer and PL_get pointer This approach is fast and easy but has the drawbacks of untyped point ers there is no reliable way to detect the validity of the pointer not to verify it is pointing to a structure of the desired type The pointer may be wrapped into a compound term with arity 1 Le dde_channel Pointer making the type problem less serious Alternatively used in the DDE interface the interface code can maintain a preferably variable length array of pointers and return the index in this array This provides better protection Especially for debugging purposes wrapping the handle in a compound is a good suggestion 6 6 19 Embedding SWI Prolog in a C program As of version 2 1 0 SWI Prolog may be embedded in a C program To reach at a compiled C program with SWI Prolog as an embedded application is very similar to creating a statically linked SWI Prolog executable as described in section 6 4 1 The file ldots pl include stub c defines SWI Prologs default main program int main int argc char argv SWI Prolog 5 0 Reference Manual 6 6 THE FOREIGN INCLUDE FILE 189 if PL_initialise argc argv PL_halt 1 PL_install_readline delete if you don t want read line PL_halt PL_toplevel 0 1
247. n Counting starts at 0 line_count Stream Count Unify Count with the number of lines read or written Counting starts at 1 line_position Stream Count Unify Count with the position on the current line Note that this assumes the position is O after the open Tabs are assumed to be defined on each 8 th character and backspaces are assumed to reduce the count by one provided it is positive fileerrors Old New Define error behaviour on errors when opening a file for reading or writing Valid values are the atoms on default and off First Old is unified with the current value Then the new value is set to New Note that Edinburgh Prolog defines fileerrors 0 and nofileerrors 0 As this does not allow you to switch back to the old mode I think this definition is better SWI Prolog 5 0 Reference Manual 88 CHAPTER 4 BUILT IN PREDICATES 4 18 Primitive character I O See section 4 2 for an overview of supported character representations nl Write a newline character to the current output stream On Unix systems n1 0 is equivalent to put 10 nl Stream Write a newline to Stream put Char Write Char to the current output stream Char is either an integer expression evaluating to an ASCII value 0 lt Char lt 255 or an atom of one character put Stream Char Write Char to Stream put_byte Byte Alias for put 1 put_byte Stream Byte Alias for put 2 put_char Char Alias for
248. n They are normally loaded using consult 1 or ensure_loaded 1 A module Prolog source file starts with a module declaration The subsequent Prolog code is loaded into the specified module and only the public predicates are made available to the context load ing the module Module files are normally loaded using use_module 1 2 See chapter 5 for details An include Prolog source file is loaded using the include 1 directive and normally contains only directives Prolog source files are located using absolute file name 3 with the following options locate_prolog_file Spec Path absolute_file_name Spec file_type prolog access read ly Path The file_type prolog option is used to determine the extension of the file using prolog_file_type 2 The default extension is pl Spec allows for the path alias con struct defined by absolute_file_name 3 The most commonly used path alias is li brary LibraryFile The example below loads the library file oset p1 containing predicates for manipulating ordered sets use_module library oset SWI Prolog 5 0 Reference Manual 4 3 LOADING PROLOG SOURCE FILES 55 SWI Prolog recognises grammar rules DCG as defined in Clocksin amp Melish 1987 The user may define additional compilation of the source file by defining the dynamic predicate term_expansion 2 Transformations by this predicate overrule the systems grammar rule trans formations It is not al
249. n walk up the stack to a catch 3 call backtrack and try to unify the copy of Exception with Catcher SWI Prolog delays making a copy of Exception and backtracking until it actually found a matching catch 3 goal The advantage is that we can start the debugger at the first possible location while preserving the entire exception context if there is no matching catch 3 goal This aproach can lead to SWI Prolog 5 0 Reference Manual 4 9 ISO COMPLIANT EXCEPTION HANDLING 69 different behaviour if Goal and Catcher of catch 3 call share variables We assume this to be highly unlikely and could not think of a scenario where this is useful If an exception is raised in a callback from C see chapter 6 and not caught in the same call back PL_next_solution fails and the exception context can be retrieved using PL_exception 4 9 1 Debugging and exceptions Before the introduction of exceptions in SWI Prolog a runtime error was handled by printing an error message after which the predicate failed If the prolog_flag see current _prolog_flag 2 debug_on_error was in effect default the tracer was switched on The combination of the error message and trace information is generally sufficient to locate the error With exception handling things are different A programmer may wish to trap an exception using catch 3 to avoid it reaching the user If the exception is not handled by user code the interactive toplevel will trap it to prevent te
250. n atom of Length characters long This predicate also works for strings see section If the prolog flag iso is not set it also accepts integers and floats expressing the number of characters output when given to write 1 as well as code lists and character lists expressing the length of the list atom_prefix Atom Prefix Succeeds if Atom starts with the characters from Prefix Its behaviour is equivalent to concat Prefix Atom but avoids the construction of an atom for the remain der sub_atom Atom Before Len After Sub ISO predicate for breaking atoms It maintains the following relation Sub is a sub atom of Atom that starts at Before has Len characters and Atom contains After characters after the match 2 sub_atom abc 1 1 A S The implementation minimalises non determinism and creation of atoms This is a very flexible predicate that can do search prefix and suffix matching etc 4 22 Classifying characters SWI Prolog offers two comprehensive predicates for classifying characters and character codes These predicates are defined as built in predicates to exploit the C character classification s handling of locale handling of local character sets These predicates are fast logical and deterministic if applicable In addition there is the library library ct ype providing compatibility to some other Prolog systems The predicates of this library are defined in terms of code_type 2 char
251. n running in non debug mode gt The sign can be the legal start of a normal Prolog clause In the unlikely case this is required leave the first line blank or add a header comment SWI Prolog 5 0 Reference Manual 2 10 COMPILATION 29 Prolog recognises this starting sequence and causes the interpreter to receive the following argument list path to pl options s script ScriptArguments Instead of s the user may use f to stop Prolog from looking for a personal initialisation file Here is a simple script doing expression evaluation usr bin pl q t main f eval current_prolog_flag argv Argv append _ Args Argv concat_atom Args SingleArg term_to_atom Term SingleArg Val is Term format w n Val main catch eval E print_message error E fail halt main halt 1 And here are two example runs AS eval 1 2 Ww eval foo ERROR Arithmetic foo 0 is not a function 2 o The Windows version supports the construct too but here it serves a rather different role The Windows shell already allows the user to start Prolog source files directly through the Windows file type association Windows however makes it rather complicated to provide additional parameters such as the required stack size for an individual Prolog file The line provides for this providing a more flexible approach then changing the global defaults The
252. ncat 3 string length 2 string to_atom 2 string to_list 2 style_check 1 sub_atom 5 sublist 3 subset 2 sub_string 5 subtract 3 succ 2 swritef 2 swritef 3 Modify the current position in a stream Close the current input stream Select element of a list Set current input stream from a stream Set current output stream from a stream Define a system feature Set stream attribute Seek stream to position Set tty stream Destructive assignment on term Set shell environment variable Find all unique solutions to a goal Format on a string Format on a string Execute interactive subshell Execute OS command Execute OS command Show results of the profiler Get size of a file in characters Skip to character in current input Skip to character on stream Add line to readline 3 history Read readline 3 init file Suspend execution for specified time Sort elements in a list Examine currently loaded source files Obtain source file of predicate Location of last read term Force tracer on specified predicate Some systems Query Set runtime stack parameter Show execution statistics Obtain collected statistics Get stream properties Type check for string atom_concat 3 for strings Determine length of a string Conversion between string and atom Conversion between string and list of ASCII Change level of warnings Take a substring from an atom Determine elements that meet condition Check subset relation for unordered sets
253. nd 1 backward compatibility float Expr Translate the result to a floating point number Normally Prolog will use integers whenever possible When used around the 2nd argument of is 2 the result will be returned as a floating point number In other contexts the operation has no effect float_fractional_part Expr Fractional part of a floating point number Negative if Expr is negative 0 if Expr is integer float_integer _part Expr Integer part of floating point number Negative if Expr is negative Expr if Expr is integer truncate Expr Truncate Expr to an integer Same as float_integer_part 1 SWI Prolog 5 0 Reference Manual 106 CHAPTER 4 BUILT IN PREDICATES floor Expr Evaluates Expr and returns the largest integer smaller or equal to the result of the evaluation ceiling Expr Evaluates Expr and returns the smallest integer larger or equal to the result of the evaluation ceil Expr Same as ceiling 1 backward compatibility IntExpr gt gt IntExpr Bitwise shift IntExprl by IntExpr2 bits to the right IntExpr lt lt IntExpr Bitwise shift IntExpr by IntExpr2 bits to the left IntExpr IntExpr Bitwise or IntExprl and IntExpr2 IntExpr IntExpr Bitwise and IntExprl and IntExpr2 IntExpr xor IntExpr Bitwise exclusive or IntExpr1 and IntExpr2 IntExpr Bitwise negation sqrt Expr Result y Expr sin Expr Result sin Expr Expr is the angl
254. ng Ed inburgh C Prolog code grammar rule compilation and writef 2 Also some of the C code orig inates from C Prolog finding the path of the currently running executable and the code underlying absolute_file_name 2 Ideas on programming style and techniques originate from C Prolog and Richard O Keefe s thief editor An important source of inspiration are the programming tech niques introduced by Anjo Anjewierden in PCE version 1 and 2 I also would like to thank those who had the fade of using the early versions of this system sug gested extensions or reported bugs Among them are Anjo Anjewierden Huub Knops Bob Wielinga Wouter Jansweijer Luc Peerdeman Eric Nombden Frank van Harmelen Bert Rengel Martin Jansche jansche novelll gs uni heidelberg de has been so kind to reor ganise the sources for version 2 1 3 of this manual Horst von Brand has been so kind to fix many typos in the 2 7 14 manual Thanks SWI Prolog 5 0 Reference Manual Overview 2 1 Getting started quickly 2 1 1 Starting SWI Prolog Starting SWI Prolog on Unix By default SWI Prolog is installed as pl though some administrators call it swipl or swi prolog The command line arguments of SWI Prolog itself and its utility programs are documented using standard Unix man pages SWI Prolog is normally operated as an interactive application simply by starting the program machines pl Welcome to SWI Prolog Version 5 0 0 Copyright
255. ngs general goodies li A Ae NP application specific debugging virtual machine of application A Ae ae more generic stuff ensure_loaded Doa ie ae AS the application itself The use_module declarations will import the public predicates from the generic modules into the user module The ensure_loaded directive loads the modules that constitute the actual application It is assumed these modules import predicates from each other using use module 1 2 as far as necessary In combination with the object oriented schema described below it is possible to define a neat modular architecture The generic code defines general utilities and the message passing predicates invoke 3 in the example below The application modules define classes that communicate using the message passing predicates 5 5 1 Object Oriented Programming Another typical way to use the module system is for defining classes within an object oriented paradigm The class structure and the methods of a class can be defined in a module and the explicit module boundary overruling describes in section 5 6 2 can by used by the message passing code to invoke the behaviour An outline of this mechanism is given below Define class point module point class point no exports name type default access value variable x integer o both variable y integer Q both method name predicate name argumen
256. nishes Please not that thread identifiers are freed for reuse after a detached thread finishes or a normal thread has been joined The Goal argument is copied to the new Prolog engine This implies further instantiation of this term in either thread does not have consequences for the other thread Prolog threads do not share data from their stacks thread_self d Get the Prolog thread identifier of the running thread If the thread has an alias the alias name is returned current_thread d Status Enumerates identifiers and status of all currently known threads Calling current thread 2 does not influence any thread See also thread_join 2 For threads that have an alias name this name is returned in d instead of the numerical thread identifier Status is one of running The thread is running This is the initial status of a thread Please note that threats waiting for something are considered running too false The Goal of the thread has been completed and failed true The Goal of the thread has been completed and succeeded exited Term The Goal of the thread has been terminated using thread_exit 1 with Term as argu ment exception Term The Goal of the thread has been terminated due to an uncaught exception see throw 1 and catch 3 thread_join d Status Wait for the termination of thread with given d Then unify the result status see thread_exit 1 of the thread with Status After this call Id becomes invalid
257. nnot be repostioned a reposition error is raised The predicate seek 4 is compatible to Quintus Prolog though the error conditions and signalling is ISO compliant See also stream_position 3 set_stream Stream Attribute Modify an attribute of an existing stream Attribute specifies the stream property to set See also stream_property 2 and open 4 alias AliasName Set the alias of an already created stream If AliasName is the name of one of the standard streams is used this stream is rebound Thus set_stream S current_input is the same as set _input 1 and by setting the alias of a stream to user_input etc all user terminal input is read from this stream See also interactor 0 buffer Buffering Set the buffering mode of an already created stream Buffering is one of full line or false eof_action Action Set end of file handling to one of eof_code reset or error close_on_abort Bool Determine whether or not the stream is closed by abort 0 By default streams are closed 4 16 3 Switching Between Implicit and Explicit I O The predicates below can be used for switching between the implicit and the explicit stream based T O predicates set_input Stream Set the current input stream to become Stream Thus open file read Stream set_input Stream is equivalent to see file set_output Stream Set the current output stream to become Stream SWI Prolog 5 0 Reference Manual 4 17 STATUS OF STREAMS 87
258. not detached nor waited for are joined to reclaim their resources interactor Create a new console and run the Prolog toplevel in this new console See also attach console 0 attach_console If the current thread has no console attached yet attach one and redirect the user streams input output and error to the new console window The console is an xterm application For this to work you should be running X windows and your xterm should know the Sccn This predicate has a couple of useful applications One is to separate debugging I O of differ ent threads Another is to start debugging a thread that is running in the background If thread 10 is running the following sequence starts the tracer on this thread thread_signal 10 attach_console trace SWI Prolog 5 0 Reference Manual 128 CHAPTER 4 BUILT IN PREDICATES 4 39 4 Status of the thread implementation It is assumed that the basic Prolog execution is thread safe Various problems are to be expected though both dead locks as well as not thread safe code in builtin predicates 4 40 User Toplevel Manipulation break Recursively start a new Prolog top level This Prolog top level has its own stacks but shares the heap with all break environments and the top level Debugging is switched off on entering a break and restored on leaving one The break environment is terminated by typing the system s end of file character control D If the t toplevel command l
259. nough memory SWI Prolog 5 0 Reference Manual 188 CHAPTER 6 FOREIGN LANGUAGE INTERFACE PL_fail install_t install PL_register_foreign bitvector_union 3 pl_bitvector_union 0 FUNCTOR_bitvectorl PL _new_functor PL_new_atom bitvector 1 Netmask s are used with TCP IP configuration Suppose we have an application dealing with rea soning about a network configuration Such an application requires communicating netmask struc tures from the operating system reasoning about them and possibly communicate them to the user A netmask consists of 4 bitmasks between 0 and 255 C application normally see them as an 4 byte wide unsigned integer SWI Prolog cannot do that as integers are always signed We could use the string approach outlined above but this makes it hard to handle these terms in Prolog A better choice is a compound term netmask 4 holding the 4 submasks as integer arguments As the implementation is trivial we will omit this here The DDE interface see section 4 46 represents another common usage of the foreign interface providing communication to new operating system features The DDE interface requires knowledge about active DDE server and client channels These channels contains various foreign data types Such an interface is normally achieved using an open close protocol that creates and destroys a handle The handle is a reference to a foreign data structure containing the relevant informatio
260. ns on the registry available through the Prolog user The underlying DLL provides a more complete coverage of the Windows registry API Please consult the sources in p1 src win32 foreign plregtry c for further details In all these predicates Path refers to a separated path into the registry This is not an atom containing characters as used for filenames but a term using the functor 2 Windows defines the following roots for the registry classes_root current_user local_machine and users registry _get_key Path Value Get the principal default value associated to this key Fails silently of the key does not exist registry_get_key Path Name Value Get a named value associated to this key registry_set_key Path Value Set the principal default value of this key Creates a path to the key 1f this does not already exist registry _set_key Path Name Value Associated a named value to this key Creates a path to the key if this does not already exist SWI Prolog 5 0 Reference Manual 210 APPENDIX A THE SWI PROLOG LIBRARY registry _delete_key Path Delete the indicated key shell_register_file_type Ext Type Name OpenAction Register a file type Ext is the extension to associate Type is the type name often something link prolog type Name is the name visible in the Windows file type browser Finally Ope nAction defines the action to execute when a file with this extension is
261. nt number compound Term Succeeds if Term is bound to a compound term See also functor 3 and 2 callable Term Succeeds if Term is bound to an atom or a compound term so it can be handed without type error to call 1 functor 3 and 2 ground Term Succeeds if Term holds no free variables 4 6 Comparison and Unification or Terms 4 6 1 Standard Order of Terms Comparison and unification of arbitrary terms Terms are ordered in the so called standard order This order is defined as follows SWI Prolog 5 0 Reference Manual 4 6 COMPARISON AND UNIFICATION OR TERMS 63 1 Variables lt Atoms lt Strings lt Numbers lt Terms 2 Old Variable lt New Variable 3 Atoms are compared alphabetically 4 Strings are compared alphabetically 5 Numbers are compared by value Integers and floats are treated identically 6 Compound terms are first checked on their arity then on their functor name alphabetically and finally recursively on their arguments leftmost argument first If the prolog flag see current _prolog_flag 2 iso is defined all floating point numbers precede all integers Terml Term2 Succeeds if Term is equivalent to Term2 A variable is only identical to a sharing variable Terml Term2 Equivalent to X Terml Term2 Terml Term2 Unify Terml with Term2 Succeeds if the unification succeeds unify_with_occurs_check Terml Term2 As 2 but using sound unifi
262. ntaining icon files The following definition makes all these images available as resources resource Name image icons XpmName atom Name file_name_extension Name xpm XpmName resource Name image XpmFile var Name absolute_file_name icons type directory Dir concat Dir xpm Pattern expand_file_name Pattern XpmFiles member XpmFile XpmFiles SWI Prolog 5 0 Reference Manual 204 CHAPTER 7 GENERATING RUNTIME APPLICATIONS open_resource Name Class Stream Opens the resource specified by Name and Class If the latter is a variable it will be unified to the class of the first resource found that has the specified Name If successful Stream becomes a handle to a binary input stream providing access to the content of the resource The predicate open_resource 3 first checks resource 3 When succesful it will open the returned resource source file Otherwise it will look in the programs resource database When creating a saved state the system normally saves the resource contents into the resource archive but does not save the resource clauses This way the development environment uses the files and modifications to the resource 3 declarations and or files containing resource info thus immediately affect the running environ ment while the runtime system quickly accesses the system resources 7 3 2 The plrc program The utility program plrc can be used to examine and manipulate t
263. nual 32 CHAPTER 2 OVERVIEW executable atom Path name of the running executable Used by gsave_program 2 as default emulator argv list List is a list of atoms representing the command line arguments used to invoke SWI Prolog Please note that all arguments are included in the list returned pipe bool changeable If true open pipe command mode Stream etc are supported Can be changed to disable the use of pipes in applications testing this feature Not recommended open_shared_object bool If true open_shared_object 2 and friends are implemented providing access to shared libraries so files or dynamic link libraries DLL files shared_object_extension atom Extension used by the operating system for shared objects so for most Unix systems and d11 for Windows Used for locating files using the file_type executable See also absolute_file_name 3 dynamic_stacks bool If t rue the system uses some form of sparse memory management to realise the stacks If false malloc realloc are used for the stacks In earlier days this had consequenses for foreign code As of version 2 5 this is no longer the case Systems using sparse memory management are a bit faster as there is no stack shifter and checking the stack boundary is often realised by the hardware using a guard page Also memory is actually returned to the system after a garbage collection or call to trim_stacks 0 called by
264. number Counting starts at 1 If Reference is specified it unifies Pred with the most general term with the same name arity as the predicate and Index with the index number of the clause Otherwise the name and arity of Pred are used to determine the predicate If Index is provided Reference will be unified with the clause reference If Index is unbound backtracking will yield both the indices and the references of all clauses of the predicate The following example finds the 2nd clause of member 2 nth_clause member _ _ 2 Ref clause Head Body Ref Ref 160088 Head system member G575 G578 G579 Body member G575 G579 clause_property ClauseRef Property Queries properties of a clause ClauseRef is a reference to a clause as produced by clause 3 nth_clause 3 or prolog_frame_attribute 3 Property is one of the following file FileName Unify FileName with the name of the source file in which the clause is defined Fails 1f the clause is not associated to a file line_count LineNumber Unify LineNumber with the line number of the clause Fails if the clause is not associated to a file fact True if the clause has no body erased True if the clause has been erased but not yet reclaimed because it is referenced SWI Prolog 5 0 Reference Manual 82 CHAPTER 4 BUILT IN PREDICATES 4 16 Input and output SWI Prolog provides two different packages for input and output One confirms to the Edinburgh s
265. number l 62 number_chars 2 15 96 number_codes 2 97 number_chars 2 15 54 97 number_codes 2 15 54 96 numbervars 4 95 on signal 3 71 on_signal 3 14 71 73 once 1 66 67 127 130 133 174 online_help library 226 op 3 15 53 78 91 102 open 3 36 83 84 open 4 12 53 83 86 90 208 209 open_dde_conversation 3 135 open_null_stream 1 84 open_resource 3 204 open_shared_object 2 150 open_shared_object 3 150 open_resource 3 14 199 202 204 open_shared_object 2 32 150 operator and modules 101 package clib 190 parse_url 2 210 parse_url 3 211 parse_url 2 211 peek_byte 1 89 peek_byte 2 89 peek_char l 89 peek_char 2 89 peek_code 1 89 peek_code 2 89 peek_byte 1 2 54 peek_char 1 2 54 peek_code 1 2 54 phrase 2 74 phrase 3 74 75 pi O 107 PL_abort_hook 184 PL_abort_unhook 184 PL_action 181 PL_agc_hook 184 SWI Prolog 5 0 Reference Manual 248 INDEX PL_atom_chars 157 PL_atom_nchars 164 PL_call 174 PL_call_predicate 174 PL_chars_to_term 171 PL_cleanup 190 PL close foreign frame 175 PL_close_query 174 PL_compare 179 PL_cons functor 167 PL_cons_functor_v 167 PL_cons_list 167 PL_context 175 PL_copy_term_ref 155 PL_cut_query 174 PL _discard foreign frame 175 PL_dispatch_hook 184 PL_erase 180 PL_erase_external 180 PL exception 178 PL_failQ 156 PL _foreign_context 157 PL fore
266. number of seconds that elapsed since the epoch of the POSIX tim representation January 1970 O hours Time is a floating point number The granularity is system dependent convert_time Time Year Month Day Hour Minute Second MilliSeconds Convert a time stamp provided by get_time 1 time_file 2 etc Year is unified with the year Month with the month number January is 1 Day with the day of the month starting with 1 Hour with the hour of the day 0 23 Minute with the minute 0 59 Second with the second 0 59 and MilliSecond with the milliseconds 0 999 Note that the latter might not be accurate or might always be 0 depending on the timing capabilities of the system See also convert_time 2 convert_time Time String Convert a time stamp as obtained though get _t ime 1 into a textual representation using the C library function ctime The value is returned as a SWI Prolog string object see sec tion 4 23 See also convert_time 8 4 37 2 Handling the menu in programPLWIN EXE The Windows executable PLWIN EXE has a menu bar displayed at the top that can be programmed from Prolog Being totally non portable we do not advice using it for your own application but use XPCE or another portable GUI platform instead We give the predicates for reference here win_insert_menu Label Before Insert a new entry pulldown in the menu If the menu already contains this entry nothing is done The Label is the label an
267. o solve 2 whose first argument is a variable or the atom a a member Search for any port on member 2 This is equiv alent to setting a spy point on member 2 Repeat find Repeat the last find command see A Alternatives Show all goals that have alternatives C Context Toggle Show Context If on the context module of the goal is displayed between square brackets see section 5 Default is of f L Listing List the current predicate with 1isting 1 a Abort Abort Prolog execution see abort 0 b Break Enter a Prolog break environment see break 0 SWI Prolog 5 0 Reference Manual 2 9 OVERVIEW OF THE DEBUGGER 27 c Creep Continue execution stop at next port Also return space d Display Set the max_depth Depth option of debugger_print_options limiting the depth to which terms are printed See also the w and p options e Exit Terminate Prolog see halt 0 f Fail Force failure of the current goal g Goals Show the list of parent goals the execution stack Note that due to tail recursion optimization a number of parent goals might not exist any more h Help Show available options also i Ignore Ignore the current goal pretending it succeeded 1 Leap Continue execution stop at next spy point n No debug Continue execution in no debug mode p Print Set the prolog flag debugger_print_options to quoted true por
268. o true if the TERM variable equals xterm and false otherwise If this default does not satisfy you add the following line to your personal startup file see section 2 2 set_prolog_flag write_help_with_overstrike true help Equivalent to help help 1 help What Show specified part of the manual What is one of SWI Prolog 5 0 Reference Manual 2 7 QUERY SUBSTITUTIONS 23 Name Arity Give help on specified predicate Name Give help on named predicate with any arity or C interface function with that name Section Display specified section Section numbers are dash separated numbers 2 3 refers to section 2 3 of the man ual Section numbers are obtained using apropos 1 Examples help assert Give help on predicate assert help 3 4 Display section 3 4 of the manual help PL_retry Give help on interface function PL_ret ry See also apropos 1 and the SWI Prolog home page at http www swi psy uva nl projects SWI Prolog which provides a FAQ an HTML version of manual for online browsing and HTML and PDF versions for downloading apropos Pattern Display all predicates functions and sections that have Pattern in their name or summary de scription Lowercase letters in Pattern also match a corresponding uppercase letter Example apropos file Display predicates functions and sections that have file or File etc in their summary description explain 70E
269. oat sin pi 2 Succeeds as the float 1 function forces the result to be float 1 0 sin pi 2 Succeeds as expected 4 27 Arithmetic Functions Arithmetic functions are terms which are evaluated by the arithmetic predicates described above SWI Prolog tries to hide the difference between integer arithmetic and floating point arithmetic from the Prolog user Arithmetic is done as integer arithmetic as long as possible and converted to floating point arithmetic whenever one of the arguments or the combination of them requires it If a function returns a floating point value which is whole it is automatically transformed into an integer There are three types of arguments to functions Expr Arbitrary expression returning either a floating point value or an integer IntExpr Arbitrary expression that should evaluate into an integer Int An integer In case integer addition subtraction and multiplication would lead to an integer overflow the operands are automatically converted to floating point numbers The floating point functions sin 1 exp 1 etc form a direct interface to the corresponding C library functions used to compile SWI Prolog Please refer to the C library documentation for details on precision error handling etc Expr Result Expr Exprl Expr2 Result Exprl Expr2 Exprl Expr2 Result Exprl Expr2 Expri Expr2 Result Exprl x Expr2 Exprl Expr2 _ Exprl Result Expr2 IntExp
270. object file are linked together to form a new executable Using dynamic linking the extensions are linked to a shared library so file on most Unix systems SWI Prolog 5 0 Reference Manual 150 CHAPTER 6 FOREIGN LANGUAGE INTERFACE or dynamic link library DLL file on Microsoft platforms and loaded into the the running Prolog process 6 2 1 What linking is provided The static linking schema can be used on all versions of SWI Prolog Whether or not dy namic linking is supported can be deduced from the prolog flag open shared object see current_prolog_flag 2 If this prolog flag yields true open shared_object 2 and re lated predicates are defined See section 6 4 for a suitable high level interface to these predicates 6 2 2 What kind of loading should I be using All described approaches have their advantages and disadvantages Static linking is portable and allows for debugging on all platforms It is relatively cumbersome and the libraries you need to pass to the linker may vary from system to system though the utility program p11d described in section 6 7 often hides these problems from the user Loading shared objects DLL files on Windows provides sharing and protection and is generally the best choice If a saved state is created using qsave_program 1 2 an initialization 1 directive may be used to load the appropriate library at startup Note that the definition of the foreign predicates is the same regardless
271. ocate targets for edit 1 Call editor for edit 1 Specify editor activation Load edit 1 extensions Define meaning of file extension Obtain information on a goal environment Hook Intercept tracer L command SWI Prolog 5 0 Reference Manual 232 APPENDIX E SUMMARY prolog_load_context 2 prolog_navigator l prolog_skip level 2 prolog_to_os_filename 2 prolog trace interception 4 promptl 1 prompt 2 protocol 1 protocola 1 protocolling 1 put 1 put 2 put_byte 1 put_byte 2 put_char 1 put_char 2 put_code 1 put_code 2 qcompile 1 qsave_program 1 qsave_program 2 read 1 read 2 read_clause 1 read_clause 2 read_history 6 read_link 3 read_term 2 read_term 3 recorda 2 recorda 3 recorded 2 recorded 3 recordz 2 recordz 3 redefine _system_predicate 1 rename _file 2 repeat 0 require 1 reset_profiler 0 resource 3 retract 1 retractall 1 reverse 2 same_file 2 see l seeing l Context information for directives Graphical overview of project Indicate deepest recursion to trace Convert between Prolog and OS filenames library user Intercept the Prolog tracer Change prompt for 1 line Change the prompt used by read 1 Make a log of the user interaction Append log of the user interaction to file On what file is user interaction logged Write a character Write a character on a stream Write a byte Write a byte on a stream Write a character Write a character on a stream Write a character code Write
272. ode for GNU Emacs can be activated by adding the following rules to your Emacs initialisation file setq auto mode alist append r pl prolog mode auto mode alist setq prolog program name pl setq prolog consult string user n If you want this Indentation is either poor or I don t use jit as intended setq prolog indent width 8 Unfortunately the default Prolog mode of GNU Emacs is not very good An alternative prolog el file for GNU Emacs 20 is available from http www freesoft cz pdm software emacs prolog mode and for GNU Emacs 19 from http w1 858 telia com u85810764 Prolog mode index html 2 6 Online Help Online help provides a fast lookup and browsing facility to this manual The online manual can show predicate definitions as well as entire sections of the manual The online help is displayed from the file library MANUAL The file library helpidx pro vides an index into this file library MANUAL is created from the XIX sources with a modified version of dvitty using overstrike for printing bold text and underlining for rendering italic text XPCE is shipped with library swi_help presenting the information from the online help in a hyper text window The prolog flag write_help_with_overstrike controls whether or not help 1 writes its output using overstrike to realise bold and underlined output or not If this prolog flag is not set it is initialised by the help library t
273. of the linking type used 6 3 Dynamic Linking of shared libraries The interface defined in this section allows the user to load shared libraries so files on most Unix systems d11 files on Windows This interface is portable to Windows as well as to Unix machines providing dlopen 2 Solaris Linux FreeBSD Irix and many more or shl_open 2 HP UX It is advised to use the predicates from section 6 4 in your application open_shared_object File Handle File is the name of a so file see your C programmers documentation on how to create a so file This file is attached to the current process and Handle is unified with a handle to the shared object Equivalent to open_shared_object File global Handle See also load_foreign_library 1 2 On errors an exception shared_object Action Message is raised Message is the return value from dlerror open_shared_object File Options Handle As open_shared_ob ject 2 but allows for additional flags to be passed Options is a list of atoms now implies the symbols are resolved immediately rather than lazy default global implies symbols of the loaded object are visible while loading other shared objects by default they are local Note that these flags may not be supported by your operating system Check the documentation of dlopen or equivalent on your operating system Unsupported flags are silently ignored The system also contains code to load o f
274. of the predicate short arity Arity of the predicate pl_function_t function Implementing functions short flags Or of PL_FA_ PL_extension void PL_register_extensions PL_extension e The function PL_register_extensions behaves as PL_load_extensions but is the only PL_ function that may be called before PL_initialise The predicates are registered into the module user after registration of the SWI Prolog builtin foreign predicates and before loading the initial saved state This implies that initialization 1 directives can refer to them Here is an example of its usage static PL_extension predicates Ego 1 pl_foo 0 Es bar 2 pl_bar PL_FA_NONDETERMINISTIC NULL 0 NULL O y main int argc char argv PL_register_extensions predicates if PL_initialise argc argv PL_halt 1 SWI Prolog 5 0 Reference Manual 184 CHAPTER 6 FOREIGN LANGUAGE INTERFACE 6 6 17 Foreign Code Hooks For various specific applications some hooks re provided PL_dispatch_hook_t PL_dispatch_hook PL_dispatch_hook_t If this hook is not NULL this function is called when reading from the terminal It is sup posed to dispatch events when SWI Prolog is connected to a window environment It can re turn two values PL_DISPATCH_INPUT indicates Prolog input is available on file descriptor 0 or PL_DISPATCH_TIMEOUT to indicate a timeout The old hook is returned
275. ograms o so sc o e 129 4 43 Obtaining Runtime Statistics oaa ee 131 4 44 Finding Performance Bottlenecks 0 0 0 e eee 133 4 45 Memory Management 2 0 ee we ee ee as 134 4 46 Windows DDE interface oo soc ee ee ee es 135 SWI Prolog 5 0 Reference Manual Contents 5 mao DDE chent interlace a co ecb od Sw ow Oe we ae Pe A a a 135 4462 DDE server mod e ca a an Ss Be ee ee a A 136 447 Miscellaneous o sec eaey aa Owe Dead ee ka Ce eae baw Bok 137 5 Using Modules 139 SL Way Using Modules so a c 4 eae oe bdiwk ede bead Lara la a 24 3 139 5 2 Name based versus Predicate based Modules o o 139 33 DEIS a Module s s esera A Bee a OR AA 140 5 4 Importing Predicates into a Module o e e 140 54 1 Reserved Modules o oo o coros roca da 141 5 5 Usimg the Module System soss 04 gu See ee ea ala a a 141 5 5 1 Object Oriented Programming o e 142 5 0 Meta Predicates in Modules os o cei aoc awd cae we e a Aa 143 5 6 1 Definition and Context Module o oo e 143 5 6 2 Overruling Module Boundaries o o e 144 So Dynami Modules ocio be a 8 Bd eh ee ee ee HRY 144 5 8 Module Handling Predicates 2 o e e eee ee eee 145 5 9 Compatibility of the Module System o o o e 0 004 146 5 9 1 Emulatingmeta predicate l o 148 6 Foreign Langu
276. oks to improve the integration of such libraries See also section 4 4 for editing hooks and section 4 9 3 for hooking into the message system prolog_list_goal Goal Hook normally not defined This hook is called by the L command of the tracer in the module user to list the currently called predicate This hook may be defined to list only relevant clauses of the indicated Goal and or show the actual source code in an editor See also portray 1 and multifile l SWI Prolog 5 0 Reference Manual 216 APPENDIX B HACKERS CORNER prolog debug_control_hook Action Hook for the debugger control predicates that allows the creator of more high level program ming languages to use the common front end predicates to control de debugger For example XPCE uses these hooks to allow for spying methods rather then predicates Action is one of spy Spec Hook in spy 1 If the hook succeeds spy 1 takes no further action nospy Spec Hook in nospy 1 If the hook succeeds spy 1 takes no further action If spy 1 is hooked it is advised to place a complementary hook for nospy 1 nospyall Hook in nospyall 0 Should remove all spy points This hook is called in a failure driven loop debugging Hook in debugging 0 It can be used in two ways It can report the status of the additional debug points controlled by the above hooks and fail to let the system report the others or it succeed overruling the entire behaviour of debugging 0 prolog he
277. olog D__ SWI_EMBEDDED__ Indicates the creation of an embedded program ole alas cpp Passed as input files to the C compiler pl qif Passed as input files to the Prolog compiler to create the saved state Le all other options These are passed as linker options to the C compiler 6 7 1 A simple example The following is a very simple example going through all the steps outlined above It provides an arithmetic expression evaluator We will call the application calc and define it in the files calc c and calc pl The Prolog file is simple calc Atom term_to_atom Expr Atom A is Expr write A nl The C part of the application parses the command line options initialises the Prolog engine locates the calc 1 predicate and calls it The coder is in figure 6 5 The application is now created using the following command line plld o calc calc c calc pl The following indicates the usage of the application calc pi 2 1 5708 SWI Prolog 5 0 Reference Manual 6 7 LINKING EMBEDDED APPLICATIONS USING PLLD 193 include lt stdio h gt include lt SWI Prolog h gt define MAXLINE 1024 int main int argc char argv char expression MAXLINE char e expression char program argv 0 char plav 2 int n combine all the arguments in a single string for n 1 n lt argc n if n 1 Ka ee ES strcpy e argv n e strlen e make the arg
278. olog warning message to the standard error user_error stream Please note that new code should consider using PL_raise_exception to raise a Prolog exception See also section 4 9 int PL_warning format al Print an error message starting with WARNING followed by the output from format followed by a and a newline Then start the tracer format and the arguments are the same as for printf 2 Always returns FALSE 6 6 14 Environment Control from Foreign Code int PL action int Perform some action on the Prolog system int describes the action Remaining arguments depend on the requested action The actions are listed in table 6 1 6 6 15 Querying Prolog C_type PL_query int Obtain status information on the Prolog system The actual argument type depends on the infor mation required int describes what information is wanted The options are given in table 6 2 SWI Prolog 5 0 Reference Manual 182 CHAPTER 6 FOREIGN LANGUAGE INTERFACE PL_ACTION_TRACE PL ACTION _DEBUG PL_ACTION_BACKTRACE PL_ACTION_HALT PL_ACTION_ABORT PL_ACTION_BREAK PL ACTION _GUIAPP PL_ACTION_WRITE PL_ACTION_FLUSH Start Prolog tracer trace 0 Requires no arguments Switch on Prolog debug mode debug 0 Requires no arguments Print backtrace on current output stream The argument an int is the number of frames printed
279. om Textual constant Used as name for compound terms to represent constants or text backtracking Searching process used by Prolog If a predicate offers multiple clauses to solve a goal they are tried one by one until one succeeds If a subsequent part of the prove is not satisfied with the resulting variable binding 1t may ask for an alternative solution binding of the variables causing Prolog to reject the previously chosen clause and try the next one binding of a variable Current value of the variable See also backtracking and query built in predicate Predicate that is part of the Prolog system Built in predicates cannot be redefined by the user unless this is overruled using redefine_system_predicate 1 body Part of a clause behind the neck operator clause Sentence of a Prolog program A clause consists of a head and body separated by the neck operator or it is a fact For example parent X father X _ SWI Prolog 5 0 Reference Manual 218 APPENDIX C GLOSSARY OF TERMS Expressed X is a parent if X is a father of someone See also variable and predicate compile Process where a Prolog program is translated to a sequence of instructions See also interpreted SWI Prolog always compiles your program before executing it compound term Also called structure It consists of a name followed by N arguments each of which are terms Nis called the arity of the term cont
280. ompleting this it re reads the file and colours all clauses and calls with valid syntax e After typing Control Control The Control l commands re centers the window scrolls the window to make the caret the center of the window Hitting this command twice starts the same process as above The colour schema itself is defined in library emacs prolog_colour The colouring can be extended and modified using multifile predicates Please check this source file for details In general underlined objects have a popup right mouse button associated for common commands such as viewing the documentation or source Bold text is used to indicate the definition of objects typically predicates when using plain Prolog Other colours follow intuitive conventions See table 3 4 3 gt In most cases the location where the parser cannot proceed is further down the file than the actual error location SWI Prolog 5 0 Reference Manual 50 CHAPTER 3 INITIALISING AND MANAGING A PROLOG PROJECT Clauses Blue bold Red bold Black Bold Head of an exported predicate Head of a predicate that is not called Head of remaining predicates Calls in the clause body Blue Red Purple Call to built in or imported predicate Call to not defined predicate Call to dynamic predicate Other entities Dark green Dark blue Brown Comment Quoted atom or string Variable Table 3 1 Colour conventions Layout support La
281. ompliance to the ISO standard naaa o o e eee Should you be using SWI Prolog o o e The XPCE GUI system for Prolog i ce o sso sacs ee ee e Release Notes o ie as Re wo a et a A He a ea A LOI Version 1 8 Release Notes 2 0 cereri ee es ee le he ote we Be a 116 2 Version 1 9 Release Notes a a4 daca kena aaa aaa 16 3 Version 2 0 Release Notes 6 bk ek Be ee ee ee h 1 6 4 Version 2 5 Release Notes LG S Versi n 2 6 Release Notes io ch a eh RO ba fi ee 1 66 Version 2 7 Release Notes co coc ba ea ee ba wa Ce aa 1 6 7 Version 2 8 Release Notes 2 0 2 1 6 8 Version 2 9 Release Notes o ocs cocoa aoc aawa a LOO Version 3 0 Release Notes soona en oe ke a ee ee a 1 6 10 Version 3 1 Release Notes olor Ha ea Ra Ha OER aS 16 117 Version 3 3 Release Notes a osco eonan we we eG ee ee ae 1 6 12 Version 3 4 Release Notes o o a sosoo aca aoa Ge Be ee ew ww 16 13 Version 4 0 Release Notes oi occa ee be eee ee a Acknowledgements o noia ca es ke eee ae eee ee taba a es 2 Overview 21 2 2 23 2 4 25 2 6 20 2 8 2 9 2 10 2 11 Getting started quickly coros car da ar ad ee oS 211 Starting SWI Prolog eso pe ni ea a nera a 7 4 2 Executar AUREA o me db ack a eek ee A re a a The user s initialisation fle os e otea 0858 ee ee ee ee Imitialisation files and Goals oan oe ae ee ara Ee ed ede Sas Command Ine OPtlOHS ciacosdco a al o e ee le ee
282. oms for debug ging purposes include lt SWI Stream h gt include lt SWI Prolog h gt SWI Prolog 5 0 Reference Manual 6 6 THE FOREIGN INCLUDE FILE 185 static int atom_hook atom_t a Sdprintf AGC deleting s n PL_atom_chars a return TRUE static PL_agc_hook_t old install E install old PL_agc_hook atom_hook install_t uninstall PL_agc_hook old 6 6 18 Storing foreign data This section provides some hints for handling foreign data in Prolog With foreign data we refer to data that is used by foreign language predicates and needs to be passed around in Prolog Excluding combinations there are three principal options for storing such data Natural Prolog data E i using the representation one would choose if there was no foreign interface required Opaque packed Prolog data Data can also be represetented in a foreign structure and stored on the Prolog stacks using PL_put_string_nchars and retrieved using PL_get_string_chars It is gener ally good practice to wrap the string in a compound term with arity 1 so Prolog can identify the type portray 1 rules may be used to streamline printing such terms during development Natural foreign data passing a pointer An alternative is to pass a pointer to the foreign data Again this functor may be wrapped in a compound term The choice may be guided using the following distinctions Is the data opaque to
283. only deals with fully sepecified objects prolog_edit edit_source Location Start editor on Location See prolog_edit locate 3 for the format of a location term This multi file predicate is normally not defined If it succeeds edit 1 assumes the editor is started If it fails edit 1 will invoke an external editor The editor to be invoked is determined from the evironment variable EDITOR which may be set from the operating system or from the Prolog initialisation file using setenv 2 If no editor is defined vi is the default in Unix systems and notepad on Windows The predicate prolog_edit edit_command 2 defines how the editor will be invoked prolog_edit edit_command Editor Command Determines how Editor is to be invoked using she11 1 Editor is the determined editor see edit_source 1 without the full path specification and without possible exe extension Command is an atom describing the command The pattern is replaced by the full file name of the location and d by the line number If the editor can deal with starting at a specified line two clauses should be provided one holding only the f pattern and one holding both patterns The default contains definitions for vi emacs emacsclient vim and notepad latter without line number version Please contribute your specifications to janet swi psy uva nl prolog_edit load Normally not defined multifile predicate This predicate may be defined to provide lo
284. ontext module of the currently active foreign predicate int PL_strip_module term_t raw module_t m term_t plain Utility function If raw is a term possibly holding the module construct module rest this function will make plain a reference to rest and fill module with module For further SWI Prolog 5 0 Reference Manual 176 CHAPTER 6 FOREIGN LANGUAGE INTERFACE nested module constructs the inner most module is returned via module If raw is not a module construct arg will simply be put in plain If module is NULL it will be set to the context module Otherwise it will be left untouched The following example shows how to obtain the plain term and module if the default module is the user module module m PL_new_module PL_new_atom user term_t plain PL_new_term_ref PL_strip_module term amp m plain atom_t PL_module_name module_t Return the name of module as an atom module_t PL_new_module atom_t name Find an existing or create a new module with name specified by the atom name 6 6 9 Prolog exceptions in foreign code This section discusses PL_exception PL_throw and PL_raise_exception the interface functions to detect and generate Prolog exceptions from C code PL_throw and PL_raise_exception from the C interface to raise an exception from foreign code PL_throw exploits the C function longjmpQ to return immediately to the innermost PL_next_solution PL_raise_exception regis
285. ook 7erm Kind Lines Hook predicate that may be define in the module user to intercept messages from print_message 2 Term and Kind are the same as passed to print_message 2 Lines is a list of format statements as described with print message _lines 3 See also message_to_string 2 This predicate should be defined dynamic and multifile to allow other modules defining clauses for it too message_to_string Term String Translates a message term into a string object see section 4 23 Primarily intended to write messages to Windows in XPCE see section 1 5 or other GUI environments 4 10 Handling signals As of version 3 1 0 SWI Prolog is capable to handle software interrupts signals in Prolog as well as in foreign C code see section 6 6 12 Signals are used to handle internal errors execution of a non existing CPU intruction arithmetic domain errors illegal memory access resource overflow etc as well as for dealing asynchronous inter process communication Signals are defined by the Posix standard and part of all Unix machines The MS Windows Win32 provides a subset of the signal handling routines lacking the vital funtionality to raise a signal in another thread for achieving asynchronous inter process or inter thread communication Unix killO function on_signal Signal Old New Determines the reaction on Signal Old is unified with the old behaviour while the behaviour is switched to New As with similar en
286. operator declarations stand_alone bool Include the emulator in the state emulator file Emulator attached to the stand alone executable Default is the running emulator Table 7 1 Key Value pairs for gsave program 2 This predicate is used by qsave_program 1 2 to ensure the saved state will not depend on one of the libraries The predicate autoload 0 will find all direct references to predicates It does not find predicates referenced via meta predicates The predicate log 2 is defined in the library quintus to provide a quintus compatible means to compute the natural logarithm of a number The following program will behave correctly if its state is executed in an environment where the library quintus is not available logtable From To From gt To logtable From To log From Value format d t 8 2f n From Value F is From 1 logtable F To However the following implementation refers to log 2 through the meta predicate maplist 3 Autoload will not be able to find the reference This problem may be fixed either by loading the module libtary quintus explicitly or use require 1 to tell the system that the predicate log 2 is required by this module logtable From To i findall X between From To X Xlist SWI Prolog 5 0 Reference Manual 7 1 LIMITATIONS OF OSAVE PROGRAM 201 maplist log Xlist SineList write _table Xlist SineList write
287. opos 1 to suggest predicates from a keyword 1 0 Cut discard choicepoints 1 Cut block See block 3 712 Conjunction of goals gt 2 If then else gt 2 Soft cut 2 Consult Also list constructor 7 2 Disjunction of goals Same as 2 lt 2 Arithmetic smaller 2 Unification 2 Univ Term to list conversion 2 Arithmetic equal lt 2 Arithmetic smaller or equal 2 Identical 2 Structural identical 2 Arithmetic not equal gt 2 Arithmetic larger gt 2 Arithmetic larger or equal lt 2 Standard order smaller lt 2 Standard order smaller or equal gt 2 Standard order larger gt 2 Standard order larger or equal x 1 Negation by failure Same as not 1 2 Not unifyable 2 Not identical 2 Not structural identical 12 Existential quantification bagof 3 setof 3 1 2 Disjunction of goals Same as 2 abolish 1 Remove predicate definition from the database abolish 2 Remove predicate definition from the database abort 0 Abort execution return to top level absolute_file_name 2 absolute_file_name 3 access_file 2 Get absolute path name Get absolute path name with options Check access permissions of a file SWI Prolog 5 0 Reference Manual 226 APPENDIX E SUMMARY append 1 Append to a file append 3 Concatenate lists apply 2 Call goal with additional arguments apropos 1 library online_help Search manual arg 3 Access argument of a term arithmetic_function
288. or the entire Prolog session atom_t PL _functor_name functor_t f Return an atom representing the name of the given functor int PL functor _arity functor t f Return the arity of the given functor Atoms and atom garbage collection With the introduction of atom garbage collection in version 3 3 0 atoms no longer have live as long as the process Instead their lifetime is guaranteed only as long as they are referenced In the single threaded version atom garbage collections are only invoked at the call port In the multi threaded version see section 4 39 they appear asynchronously except for the invoking thread For dealing with atom garbage collection two additional functions are provided void PL_register_atom atom_t atom Increment the reference count of the atom by one PL_new_atom performs this automati cally returning an atom with a reference count of at least one void PL_unregister_atom atom_t atom Decrement the reference count of the atom If the reference count drops below zero an assertion error is raised Please note that the following two calls are different with respect to atom garbage collection PL_unify_atom_chars t text PL_unify_atom t PL_new_atom text The latter increments the reference count of the atom text which effectively ensures the atom will never be collected It is advised to use the _chars or _nchars functions whenever applicable 6 6 3 Analysing Terms via the For
289. or letter without case Char and Lower are the same upper Char is an upper case letter upper Lower Char is an upper case version of Lower Only true if Char is uppercase and Lower lower case to_upper Lower Char is an upper case version of Lower For non letters or letter without case Char and Lower are the same SWI Prolog 5 0 Reference Manual 100 CHAPTER 4 BUILT IN PREDICATES punct Char is a punctuation character This is a graph character that is not a letter or digit space Char is some form of layout character tab vertical tab newline etc end_of file Char is 1 end_of_line Char ends a line ASCII 10 13 newline Char is a the newline character 10 period Char counts as the end of a sentence quote Char is a quote character paren Close Char is an open parenthesis and Close is the corresponding close parenthesis code _type Code Type As char_type 2 but uses character codes rather than one character atoms Please note that both predicates are as flexible as possible They handle either representation if the argument is instantiated and only will instantiate with an integer code or one character atom depend ing of the version used See also the prolog flag double quotes atom_chars 2 and atom_codes 2 4 23 Representing text in strings SWI Prolog supports the data type string Strings are a time and space efficient mechanism to handle text text in Prolog
290. ore powerful but also more complicated to use Predicate references This section discusses the functions used to communicate about predicates Though a Prolog predicate may defined or not redefined etc a Prolog predicate has a handle that is not destroyed nor moved This handle is known by the type predicate t predicate_t PL_pred functor_t f module_t m Return a handle to a predicate for the specified name arity in the given module This function always succeeds creating a handle for an undefined predicate if no handle was available predicate_t PL_predicate const char name int arity const char module Same a PL_pred but provides a more convenient interface to the C programmer SWI Prolog 5 0 Reference Manual 6 6 THE FOREIGN INCLUDE FILE 173 void PL_predicate_info predicate_t p atom_t n int a module_t m Return information on the predicate p The name is stored over n the arity over a while m receives the definition module Note that the latter need not be the same as speci fied with PL_predicate If the predicate was imported into the module given to PL predicate this function will return the module where the predicate was defined Initiating a query from C This section discusses the functions for creating and manipulating queries from C Note that a foreign context can have at most one active query This implies it is allowed to make strictly nested calls between C and Prolog Prolog calls C calls
291. ot be found and underlined blue if the file can be loaded A popup allows for opening the referenced file 3 5 The Graphical Debugger SWI Prolog offers two debuggers One is the traditional text console based 4 port Prolog tracer and the other is a window based source level debugger The window based debugger requires XPCE installed It operates based on the prolog_trace_interception 4 hook and other low level functionality described in chapter B Window based tracing provides much better overview due to the eminent relation to your source code a clear list of named variables and their bindings as well as a graphical overview of the call and choice point stack There are some drawbacks though Using a textual trace on the console one can scroll back and examine the past while the graphical debugger just presents a much better overview of the current state 3 5 1 Invoking the window based debugger Whether the text based or window based debugger is used is controlled using the predicates guitracer 0 and noguitracer 0 Entering debug mode is controlled using the normal pred icates for this trace 0 and spy 1 In addition PceEmacs prolog mode provides the command Prolog Break at Control c b to insert a break point at a specific location in the source code guitracer This predicate installs the above mentioned hooks that redirect tracing to the window based environment No window appears The debugger window appears as actual tracing is start
292. otherwise void PL _cleanup int status This function performs the reverse of PL_initialise It runs the PL_on_halt and at_halt 1 handlers closes all streams except for the standard I O streams which are flushed only deallocates all memory and restores all signal handlers The status argument is passed to the various termination hooks and indicates the exit status This function allows deleting and restarting the Prolog system in the same process Use it with care as PL_initialise is a costly function Unix users should consider using exec available as part of the clib package void PL _halt int status Cleanup the Prolog environment using PL_cleanup and calls exit with the status argu ment 6 7 Linking embedded applications using plld The utility program p11d Win32 plld exe may be used to link a combination of C files and Prolog files into a stand alone executable p11d automates most of what is described in the previous sections In the normal usage a copy is made of the default embedding template A1dots p1 include stub c The main routine is modified to suit your application PL initialise must be passed the program name argv 0 Win32 the executing program can be obtained using GetModuleFileName The other elements of the command line may be modified Next p11d is typically invoked as plld o output stubfile c other c or o files plfiles SWI Prolog 5 0 Reference Manual 6 7 LIN
293. ource_file 2 number_of_clauses ClauseCount Unify ClauseCount to the number of clauses associated with the predicate Fails for for eign predicates dwim_predicate Term Dwim Do What I Mean dwim support predicate Term is a term which name and arity are used as a predicate specification Dwim is instantiated with the most general term built from Name and SWI Prolog 5 0 Reference Manual 4 15 EXAMINING THE PROGRAM 81 the arity of a defined predicate that matches the predicate specified by Term in the Do What I Mean sense See dwim_match 2 for Do What I Mean string matching Internal sys tem predicates are not generated unless style check dollar is active Backtracking provides all alternative matches clause Head Body Succeeds when Head can be unified with a clause head and Body with the corresponding clause body Gives alternative clauses on backtracking For facts Body is unified with the atom true Normally clause 2 is used to find clause definitions for a predicate but it can also be used to find clause heads for some body template clause Head Body Reference Equivalent to clause 2 but unifies Reference with a unique reference to the clause see also assert 2 erase 1 If Reference is instantiated to a reference the clause s head and body will be unified with Head and Body nth_clause Pred Index Reference Provides access to the clauses of a predicate using their index
294. ow is stub c modified to link the lowercase example described later in this chapter Copyright c 1991 Jan Wielemaker All rights reserved jan swi psy uva nl Purpose Skeleton for extensions E include lt stdio h gt SWI Prolog 5 0 Reference Manual 6 5 INTERFACE DATA TYPES 153 include lt SWI Prolog h gt extern foreign_t pl_lowercase term term PL_extension predicates 1 name arity function PL_FA_ lt flags gt lowercase 2 pl_lowercase 0 NULL 0 NULL O terminat ing line y int main int argc char argv PL _register_extensions predicates if PL_initialise argc argv PL_halt 1 PL_install_readline delete if not re quired PL_halt PL_toplevel 0 1 Now a new executable may be created by compiling this file and linking it to libpl a from the runtime directory and the libraries required by both the extensions and the SWI Prolog kernel This may be done by hand or using the p11d utility described in secrefplld 6 5 Interface Data types 6 5 1 Type term_t a reference to a Prolog term The principal data type is term_t Type term_t is what Quintus calls OP_term_ref This name indicates better what the type represents it is a handle for a term rather than the term itself Terms can only be represented and manipulated using this type as this is the only safe way to ensure the Prolog kernel is aware of all terms ref
295. ower bound of the vector is O and the upperbound is not defined an implemen tation for getting and putting the setes as well as the union predicate for it is below include lt SWI Prolog h gt define max a b a gt b a b define min a b a lt b a b static functor_t FUNCTOR_bitvectorl static int get_bitvector term_t in int len unsigned char data if PL is functor in FUNCTOR_bitvectorl term t a PL_new_term_ref SWI Prolog 5 0 Reference Manual 6 6 THE FOREIGN INCLUDE FILE 187 PL_get_arg 1 in a return PL_get_string a char data len PL fail static int unify_bitvector term_t out int len const unsigned char data if PL_unify_functor out FUNCTOR_bitvectorl term_t a PL_new_term_ref PL_get_arg 1 out a return PL_unify_string_nchars a len const char data PL_fail static foreign_t pl_bitvector_union term_t tl term_t t2 term_t u unsigned char sl s2 at ld 2 11 amp S1 amp amp amp 12 amp s2 if get_bitvector t1 get_bitvector t2 Loy int 1 max 11 12 unsigned char s3 alloca 1 if s3 int n int ml min 11 12 for n 0 n lt ml n s3 n s1 n s2 n for 7 nm lt 11 n s3 n s1 n for n lt 12 n s3 n s2 n return unify_bitvector u l s3 return PL_warning Not e
296. p files The name of the startup file can be changed with the file option If File denotes an absolute path this file is loaded otherwise the file is searched for using the same conventions as for the default startup file Finally if file is none no file is loaded SWI Prolog 5 0 Reference Manual 2 3 INITIALISATION FILES AND GOALS 19 2 3 Initialisation files and goals Using commandline arguments see section 2 4 SWI Prolog can be forced to load files and execute queries for initialisation purposes or non interactive operation The most commonly used options are f fileor s file to make Prolog load a file g goal to define an initialisation goal and t goal to define the toplevel goal The following is a typical example for starting an application directly from the commandline machines pl f load pl g go t halt It tells SWI Prolog to load load p1 start the application using the entry point go 0 and instead of entering the interactive toplevel exit after completing go 0 The q may be used to supress all informational messages In MS Windows the same can be achieved using a short cut with appropriately defined comman dline arguments A typically seen alternative is to write a file run p1 with content as illustrated below Double clicking run p1 will start the application load load program O run it z hale and exit Section 2 10 2 discusses further scripting options and chapter 7 d
297. perator declarations confirm to the Edinburgh standard Most built in predicates are compatible with those described in Clocksin amp Melish 1987 SWI Prolog also offers a number of primitive predicates compatible with Quintus Prolog Qui 1997 and BIM Prolog BIM 1989 ISO compliant predicates are based on Prolog The Standard Deransart et al 1996 validated using Hodgson 1998 Quintus is a trademark of Quintus Computer Systems Inc USA 2BIM is a trademark of BIM sa nv Belgium SWI Prolog 5 0 Reference Manual 1 2 STATUS 9 1 2 Status This manual describes version 5 0 of SWI Prolog SWI Prolog has been used now for many years The application range includes Prolog course material meta interpreters simulation of parallel Pro log learning systems natural language processing and two large workbenches for knowledge en gineering Although we experienced rather obvious and critical bugs can remain unnoticed for a remarkable long period we assume the basic Prolog system is fairly stable Bugs can be expected in infrequently used built in predicates Some bugs are known to the author They are described as footnotes in this manual 1 3 Compliance to the ISO standard SWI Prolog 3 3 0 implements all predicates described in Prolog The Standard Deransart et al 1996 Exceptions and warning are still weak Some SWI Prolog predicates silently fail on conditions where the ISO specification requi
298. project as a collection of source files and a load file a Prolog file containing only use_module 1 2 or ensure_loaded 1 directives possibly with a definition of the entry point of the program the predicate that is normally used to start the program This file is often called 1o0ad p1 If the entry point is called go a typical session starts as pl lt banner gt 1 load lt compilation messages gt Yes 2 go lt program interaction gt When using Windows the user may open load pl from the Windows explorer which will cause plwin exe to be started in the directory holding load p1 Prolog loads load p1 before entering the toplevel 2 10 2 For running the result There are various options if you want to make your program ready for real usage The best choice depends on whether the program is to be used only on machines holding the SWI Prolog development system the size of the program and the operating system Unix vs Windows Using PrologScript New in version 4 0 5 is the possibility to use a Prolog source file directly as a Unix script file the same mechanism is useful to specify additional parameters for running a Prolog file on Windows If the first letter of a Prolog file is the first line is treated as comment To create a Prolog script make the first line start like this path to pl options s This implies the system can run out of local stack in debug mode while no problems arise whe
299. prolog 0 after finishing a user query c_libs atom Libraries passed to the C linker when SWI Prolog was linked May be used to determine the libraries needed to create statically linked extensions for SWI Prolog See section 6 7 ccc atom Name of the C compiler used to compile SWI Prolog Normally either gcc or cc See section 6 7 c_Idflags atom Special linker flags passed to link SWI Prolog See section 6 7 readline bool If true SWI Prolog is linked with the readline library This is done by default if you have this library installed on your system It is also true for the Win32 plwin exe version of SWI Prolog which realises a subset of the readline functionality saved _ program bool If true Prolog is started from a state saved with qsave_program 1 2 runtime bool If true SWI Prolog is compiled with DO_RUNTIME disabling various useful develop ment features currently the tracer and profiler max _integer integer Maximum integer value Most arithmetic operations will automatically convert to floats if integer values above this are returned SWI Prolog 5 0 Reference Manual 2 11 ENVIRONMENT CONTROL PROLOG FLAGS 33 min_integer integer Minimum integer value max_tagged_integer integer Maximum integer value represented as a tagged value Tagged integers require 4 bytes storage and are used for indexing Larger integers are represented as indirect data and require 16 bytes on the
300. providing the possibility of program resources See resource 3 open_resource 3 and qsave program 1 2 1 6 10 Version 3 1 Release Notes Improvements on exception handling Allows relating software interrupts signals to exceptions handling signals in Prolog and C see on_signal 3 and PL_signal Prolog stack overflows now raise the resource_error exception and thus can be handled in Prolog using cat ch 3 1 6 11 Version 3 3 Release Notes Version 3 3 is a major release changing many things internally and externally The highlights are a complete redesign of the high level I O system which is now based on explicit streams rather then current input output The old Edinburgh predicates see 1 te11 1 etc are now defined on top of this layer instead of the other way around This fixes various internal problems and removes Prolog limits on the number of streams Much progress has been made to improve ISO compliance handling strings as lists of one character atoms is now supported next to character codes as integers Many more exceptions have been added and printing of exceptions and messages is rationalised using Quintus and SICStus Pro log compatible print_message 2 message_hook 3 and print_message_lines 3 All predicates descriped in Deransart et al 1996 are now implemented As of version 3 3 SWI Prolog adheres the ISO logical update view for dynamic predicates See section 4 13 1 for details SWI Prolog 3 3 includes ga
301. put_ char 1 put Stream Char Alias for put 2 put_code Code Alias for put 1 put_code Stream Code Alias for put 2 tab Amount Writes Amount spaces on the current output stream Amount should be an expression that eval uates to a positive integer see section 4 26 tab Stream Amount Writes Amount spaces to Stream flush_output Flush pending output on current output stream flush_output 0 is automatically generated by read 1 and derivatives if the current input stream is user and the cursor is not at the left margin flush_output Stream Flush output on the specified stream The stream must be open for writing ttyflush Flush pending output on stream user See also flush_output 0 1 SWI Prolog 5 0 Reference Manual 4 18 PRIMITIVE CHARACTER I O 89 get_byte Byte Read the current input stream and unify the next byte with Byte an integer between 0 and 255 Byte is unified with 1 on end of file get_byte Stream Byte Read the next byte from Stream get_code Code Read the current input stream and unify Code with the character code of the next character Char is unified with 1 on end of file See also get_char 1 get_code Stream Code Read the next character code from Stream get_char Char Read the current input stream and unify Char with the next character as a one character atom See also atom_chars 2 On end of file Char is unified to the atom end_of_file get_char
302. r but lacks the tracer If the option stand_alone on is present the emulator is the first part of the state If the emulator is started it will test whether a boot file state is attached to the emulator itself and load this state Provided the application has all libraries loaded the resulting executable is completely independent of the runtime environment or location where it was build See also section 5 qsave_program File Equivalent to gsave_program File autoload Check the current Prolog program for predicates that are referred to are undefined and have a definition in the Prolog library Load the appropriate libraries SWI Prolog 5 0 Reference Manual 200 CHAPTER 7 GENERATING RUNTIME APPLICATIONS Key Option Type Description local L K bytes Size Limit of local stack global G K bytes Size Limit of global stack trail T K bytes Size Limit of trail stack argument A K bytes Size Limit of argument stack goal g atom Initialisation goal toplevel t atom Prolog toplevel goal init_file f atom Personal initialisation file class atom If runtime only read resources from the state default If kernel lock all predicates as sys tem predicates If development save the pred icates in their current state and keep reading re sources from their source if present See also resource 3 autoload bool If true run autoload 0O first map file File to write info on dump op save standard Save
303. r if building the state cannot be handled by the default procedure used by plld In the latter case the state is created seperately and appended to the kernel using cat kernel state gt out Win32 copy b kernel state out pl options Additional options passed to Prolog when creating the saved state The first character immedi ately following p1 options is used as separator and translated to spaces when the argument is built Example p1 options F xpce passed F xpce as additional flags to Prolog Id options Passes options to the linker similar to p1 options cc options Passes options to the C C compiler similar to pl options V Select verbose operation showing the various programs and their options 0 outfile Reserved to specify the final output file Library Specifies a library for the C compiler By default 1p1 Win32 libpl lib and the libraries needed by the Prolog kernel are given SWI Prolog 5 0 Reference Manual 192 CHAPTER 6 FOREIGN LANGUAGE INTERFACE Llibrary directory Specifies a library directory for the C compiler By default the directory containing the Prolog C library for the current architecture is passed g Iinclude directory Ddefinition These options are passed to the C compiler By default the include directory containing SWI Prolog his passed p11d adds two additional Ddef flags D__SWI_PROLOG__ Indicates the code is to be connected to SWI Pr
304. r loading your program to get a quick overview on the completeness and possible conflicts in your program list_undefined Scans the database for predicates that have no definition A predicate is considered defined if it has clauses is declared using dynamic 1 ormultifile 1 Asa program is compiled calls are translated to predicates If the called predicate is not yet defined it is created as a predicate without definition The same happens with runtime generated calls This predicate lists all such undefined predicates that are not defined in the library See also List_autoload 0 Note undefined predicates are never removed from the database For proper results it is there fore adviced to run check 0 right after loading your program SWI Prolog 5 0 Reference Manual 208 APPENDIX A THE SWI PROLOG LIBRARY list_autoload Lists all undefined see 1ist_undefined 0 predicates that have a definition in the library along with the file from which they will be autoloaded when accessed See also autoload 0 list redefined Lists predicates that are defined in the global module user as well as in a normal module Le predicates for which the local definition overrules the global default definition A 2 library readutil Reading lines streams and files This library contains primitives to read lines files multiple terms etc read_line_to_codes Stream Codes Read the next line of input from Stream and unify the result with Codes after
305. r that operates on single key strokes Interfaces to some standard editors are provided and can be extended as well as a facility to maintain programs see make 0 SWI Prolog 5 0 Reference Manual 10 CHAPTER 1 INTRODUCTION Very fast compiler Even very large applications can be loaded in seconds on most machines If this is not enough there is a Quick Load Format that is slightly more compact and loading is almost always I O bound Transparent compiled code SWI Prolog compiled code can be treated just as interpreted code you can list it trace it etc This implies you do not have to decide beforehand whether a module should be loaded for debugging or not Also performance is much better than the performance of most interpreters Profiling SWI Prolog offers tools for performance analysis which can be very useful to optimise pro grams Unless you are very familiar with Prolog and Prolog performance considerations this might be more helpful than a better compiler without these facilities Flexibility SWI Prolog can easily be integrated with C supporting non determinism in Prolog calling C as well as C calling Prolog see section 6 It can also be embedded embedded in external programs see section 6 7 System predicates can be redefined locally to provide compatibility with other Prolog systems Integration with XPCE SWI Prolog offers a tight integration to the Object Oriented Package for User Interface De velopment
306. ra Pa ede dade a 45 33 The fest edit reload Cycle 6c e coe ee i ee ee e e e 46 Sol Locating things TO edit conca O ee Se 46 3 3 2 Editing and incremental compilation 46 3 4 Using the PceEmacs built in editor 2 ee ee ee ee 47 Sl Ac va ng PeeEma s aa ng ek A ee ae eS 47 S42 Bl ffng through PesEmacs siesta a do aa 47 34 3 Prolog Mode cidos 284 G4 a whe ee ee eS hee OES 49 39 The Graphical Debugger sora ead oa OMe eh ee Be ee Pade es 51 3 5 1 Invoking the window based debugger o 51 ao The Prolos Navigator o o lod s e eek do we Pee lee Ee BS N 52 or SUMA OLER oo ee OR a ee DA a Se 52 4 Built in predicates 53 4 1 Notation of Predicate Descriptions e e eee 53 4 2 Character tepresemtation lt o oc ce ee wee ee ed be ed eas 53 4 3 Loading Prolog source files 0 5 4 0828686 da ee bade a A 54 OSA Orc load HES ooo as oe ee ae ds EA es wl eh ee da 59 4 4 Listing and Editor Interface o o e ee 60 45 Very Iype or a Temm os eso sa aa as a eee EES 62 4 6 Comparison and Unification or Terms 2 2 06 44 2s be be ba Bae eee 62 4 6 1 Standard Order or Terms os sa os ee ee ER oe ee eS 62 4 7 Control Predicates osea a oe a eR Oe ee a a ee 64 4 3 Meta Call Predicates o lt ca 04404442 bee eR RED eee A 66 4 9 ISO compliant Exception handling o o e 68 4 9 1 Debugeme and exceptions lt ia aaa a na a
307. ram 2 13 30 32 45 199 202 qsave_program 1 2 13 14 21 30 32 59 150 189 194 200 201 quiet 20 70 quintus library 15 145 148 random 1 105 read 1 33 41 84 88 92 94 131 232 read 2 92 read_clause 1 92 read_clause 2 92 read_file_to_codes 3 208 read_file_to_terms 3 209 read_history 6 94 read_line_to_codes 2 208 read_line_to_codes 3 208 read_link 3 122 read_stream_to_codes 2 208 read_stream_to_codes 3 208 read_term 2 92 read_term 3 94 read_clause 1 92 131 read_history 6 94 read_line_to_codes 2 208 read_line_to_codes 3 208 read_stream_to_codes 2 208 read_term 2 24 33 92 94 97 read_term 3 93 102 128 read_term 2 3 93 readutil library 45 208 236 reconsult 1 55 recorda 2 76 recorda 3 76 77 79 179 180 recorded 2 77 recorded 3 76 77 146 201 recordz 2 76 146 recordz 3 76 redefine _system_predicate 1 76 redefine_system_predicate 1 12 217 registry 41 registry library 209 236 registry _delete_key 1 210 registry _get_key 2 209 registry get _key 3 209 registry_set_key 2 209 registry_set_key 3 209 rem 2 105 rename file 2 120 repeat O 64 67 require 1 56 200 reset_profiler O 134 reset_profiler O 133 resource 3 14 37 199 200 202 204 retract 1 55 56 75 78 146 retractall 1 75 76 reverse 2 109 140 RFC 1738 210 rl_add_history 1 216 rl_read_init_file 1 216 round 1 105 same_file 2 120 see 1 14 82 83 seeing 1 82 83
308. rbage collection on atoms removing the last serious memory leak especially in text manipulation applications See section 6 6 2 In addition both the user level and foreign interface supports atoms holding 0 bytes Finally an alpha version of a multi threaded SWI Prolog for Linux is added This version is still much slower than the single threaded version due to frequent access to thread local data as well as some too detailed mutex locks The basic thread API is ready for serious use and testing however See section 4 39 Incompatible changes A number of incompatible changes result from this upgrade They are all easily fixed however e 0 call 1 The cut now behaves according to the ISO standard This implies it works in compound goals passed to ca11 1 and is local to the condition part of if then else as well as the argument of x 1 e atom_chars 2 This predicate is now ISO compliant and thus generates a list of one character atoms The SWI Prolog 5 0 Reference Manual 1 6 RELEASE NOTES 15 behaviour of the old predicate is available in the also ISO compliant at om_codes 2 predicate Safest repair is a replacement of all atom_chars into atom_codes If you do not want to change any souce code you might want to use user goal_expansion atom_chars A B atom_codes A B e number_chars 2 Same applies for number_chars 2 and number_codes 2 e feature 2 set_feature 2 These are replaced by the ISO compliant
309. re the most commonly used commands In section section 3 4 3 we discuss specific support for dealing with Prolog source code 3 4 3 Prolog Mode In the previous section section 3 4 2 we explained the basics of PceEmacs Here we continue with Prolog specific functionality Possibly the most interesting is Syntax highlighting Unlike most editors where this is based on simple patterns PceEmacs syntax highlighting is achieved by Prolog itself ac tually reading and interpreting the source as you type it There are three moments at which PceEmacs checks part of the syntax e After typinga After typing a that is not preceeded by a symbol character the system assumes you completed a clause tries to find the start of this clause and verifies the syntax If this process succeeds it colours the elements of the clause according to the rules given below Colouring is done using information from the last full check on this file If it fails the syntax error is displayed in the status line and the clause is not coloured e After the command Control c Control s Acronym for Ccheck Syntax it performs the same checks as above for the clause surrounding the caret On a syntax error however the caret is moved to the expected location of the error e After pausing for two seconds After a short pause 2 seconds PceEmacs opens the edit buffer and reads it as a whole creating an index of defined called dynamic imported and exported predicates After c
310. ream Formatted write Formatted write on stream Write term insert quotes Write term insert quotes on stream SWI Prolog 5 0 Reference Manual 236 APPENDIX E SUMMARY E 2 Library predicates E 2 1 library check check 0 Program completeness and consistency list undefined O List undefined predicates list_autoload O List predicates that require autoload list redefined 0O List locally redefined predicates E 2 2 library readutil read_line_to_codes 2 Read line from a stream read_line_to_codes 3 Read line from a stream read_stream_to_codes 2 Read contents of stream read_stream_to_codes 3 Read contents of stream read_file_to_codes 3 Read contents of file read file_to_terms 3 Read contents of file to Prolog terms E 2 3 library netscape www_open_url l Open a web page in a browser E 2 4 library registry registry _get_key 2 Get principal value of key registry_get_key 3 Get associated value of key registry_set_key 2 Set principal value of key registry _set_key 3 Set associated value of key registry_delete_key 1 Remove a key shell register file type 4 Register a file type shell _register_dde 6 Register DDE action shell register _prolog 1 Register Prolog E 2 5 library ur1 parse_url 2 Analyse or construct a URL parse_url 3 Analyse or construct a relative URL global_url 3 Make relative URL global http_location 2 Analyse or construct location www form_encode 2 Encode or decode form data SWI Prolog 5 0 Referenc
311. red and possibly choicepoints it created are destroyed as once 1 If cleanup throws an exception this is executed as normal Catcher is unified with a term describing how the call has finished If this unification fails Cleanup is not called exit Goal succeeded without leaving any choicepoints fail Goal failed Goal succeeded with choicepoints and these are now discarded by the execution of a cut or orther pruning of the search tree such as if then else exception Exception Goal raised the given Exception Typical use of this predicate is cleanup of permanent data storage required to execute Goal close file descriptors etc The example below provides a non deterministic search for a term in a file closing the stream as needed term_in_file Term File open File read In SWI Prolog 5 0 Reference Manual 68 CHAPTER 4 BUILT IN PREDICATES call_cleanup term_in_stream Term In _ close In term_in_stream Term In repeat read In T T end_of_file gt fail 7 T Term Note that this predicate is impossible to implement in Prolog other then reading all terms into a list close the file and call member 2 because without call_cleanup 3 there is no way to gain control if the choicepoint left by repeat is killed by a cut This predicate is a SWI Prolog extension See also call_cleanup 2 for compatibility to other Prolog implementations call_cleanup Goal Cleanup This predicate i
312. red library load_foreign_library foreign myextension initialization load_foreign_extensions The path alias foreign is defined by file_search_path 2 By default it searches the di rectories home 1ib arch and home 1ib The application can specify additional rules for file_search_path 2 7 3 Using program resources A resource is very similar to a file Resources however can be represented in two different formats on files as well as part of the resource archive of a saved state see gsave_program 2 A resource has a name and a class The source data of the resource is a file Resources are declared by declaring the predicate resource 3 They are accessed using the predicate open_resource 3 Before going into details let us start with an example Short texts can easily be expressed in Prolog sourcecode but long texts are cumbersome Assume our application defines a command help that prints a helptext to the screen We put the content of the helptext into a file called help txt The following code implements our help command such that help txt is incorperated into the runtime executable resource help text help txt help open_resource help text In SWI Prolog 5 0 Reference Manual 7 3 USING PROGRAM RESOURCES 203 copy_stream In user_output close In copy_stream In Out get0 In C copy_stream C In Out copy_stream 1 _ _ copy_stream C In Out put O
313. redicate to determine the order Is this a compilation run Test for compound term Append two atoms Classify a character code Append a list of atoms Append a list of atoms with separator Read compile a Prolog source file Get context module of current goal Break time stamp into fields Convert time stamp to string Copy all data from stream to stream Copy n bytes from stream to stream Make a copy of a term Examine evaluable functions Examine existing atoms Query input character mapping Examine existing flags library sh11b Examine loaded shared libraries so files Enumerate user defined format codes Examine existing name arity pairs Get current input stream Examine existing database keys Examine existing modules Examine existing modules Examine existing mutexes Examine current operator declarations Get the current output stream Examine existing predicates ISO Examine existing predicates Current software signal mapping Examine open streams Examine Prolog threads Win32 Examine open DDE connections Win32 Examine DDE services provided Win32 Execute command on DDE server Win32 Become a DDE server Win32 Make a DDE request Win32 POKE operation on DDE server Win32 Terminate a DDE service Test for debugging mode hook Extend spy 1 etc Show debugger status Get the default modules of a module SWI Prolog 5 0 Reference Manual 228 APPENDIX E SUMMARY delete 3 delete_directory 1 delete_fil
314. res an exception unctor 3 for example Many predicates print warnings rather than raising an exception All predicates where exceptions may be caused due to a correct program operating in an imperfect world I O arithmetic resource overflows should behave according to the ISO standard In other words SWI Prolog should be able to execute any program conforming to Deransart et al 1996 that does not rely on exceptions generated by errors in the program 1 4 Should you be using SWI Prolog There are a number of reasons why you better choose a commercial Prolog system or another aca demic product SWI Prolog is not supported Although I usually fix bugs shortly after a bug report arrives I cannot promise anything Now that the sources are provided you can always dig into them yourself e Memory requirements and performance are your first concerns A number of commercial compilers are more keen on memory and performance than SWI Prolog I do not wish to sacrifice some of the nice features of the system nor its portability to compete on raw performance You need features not offered by SWI Prolog In this case you may wish to give me suggestions for extensions If you have great plans please contact me you might have to implement them yourself however On the other hand SWI Prolog offers some nice facilities e Nice environment This includes Do What I Mean automatic completion of atom names history mechanism and a trace
315. rint 1 2 90 print_message 2 70 230 print_message_lines 3 70 print_message 2 14 35 36 55 70 71 93 print_message_lines 3 14 70 71 profile file 18 profile 3 133 205 profile_count 3 134 profiler 2 133 prolog 0 21 32 128 146 190 prolog debug_control_hook 1 37 216 prolog help_hook 1 37 216 prolog_current_frame 1 213 prolog_edit edit_command 2 37 61 prolog _edit edit_source 1 37 61 prolog_edit load O 61 prolog edit locate 2 61 prolog_edit locate 3 37 60 prolog file_type 2 57 prolog frame_attribute 3 213 prolog_list_goal 1 37 215 prolog load_context 2 58 prolog_navigator 1 52 prolog skip level 2 215 prolog_to_os_filename 2 122 prolog trace interception 4 37 214 prolog_current_frame 1 213 prolog _edit edit command 2 61 prolog_edit edit_source 1 46 52 60 prolog edit locate 3 60 61 prolog_file_type 2 54 57 prolog _frame_attribute 3 81 prolog load_context 2 58 prolog_navigator 1 52 prolog_to_os_filename 2 44 121 prolog_trace_interception 4 51 129 213 prompt 2 94 prompt1 1 94 proper _list 1 108 protocol 1 129 protocola 1 129 protocolling 1 129 SWI Prolog 5 0 Reference Manual 250 INDEX prove 3 46 put 1 88 put 2 88 put_byte 1 88 put_byte 2 88 put_char 1 88 put_code 1 88 put_code 2 88 put_byte 1 2 54 put_char 1 88 put_char 1 2 54 put_code 1 2 54 qcompile 1 55 60 qsave_program 1 199 qsave_program 2 199 200 qsave_prog
316. rinting a term that is not a variable If portray 1 succeeds the term is considered printed See also print 1 The default is false This option is an extension to the ISO write_term options max _depth nteger If the term is nested deeper than Integer print the remainder as eclipse A O zero value default imposes no depth limit This option also delimits the number of printed for a list Example write_term a s s s s 0 la b c d e f max_depth 3 a s s a bl Yes Used by the toplevel and debugger to limit screen output See also the prolog flags toplevel_print_options and debugger_print_options write_term Stream Term Options As write term 2 but output is sent to Stream rather than the current output write_canonical 7erm Write Term on the current output stream using standard parenthesised prefix notation i e ig noring operator declarations Atoms that need quotes are quoted Terms written with this predicate can always be read back regardless of current operator declarations Equivalent to write term 2 using the options ignore_ops and quoted write_canonical Stream Term Write Term in canonical form on Stream write Term Write Term to the current output using brackets and operators where appropriate See current_prolog_flag 2 for controlling floating point output format write Stream Term Write Term to Stream SWI Prolog 5 0 Reference Manual 92 CHAPTER 4 BUILT
317. rl mod IntExpr2 Modulo Result IntExprl IntExprl IntExpr2 x IntExpr2 The function mod 2 is imple mented using the C operator It s behaviour with negtive values is illustrated in the table below SWI Prolog 5 0 Reference Manual 4 27 ARITHMETIC FUNCTIONS 105 2 17 mod 5 2 17 mod 5 2 17 mod 5 2 17 mod 5 IntExprl rem IntExpr2 Remainder of division Result float_fractional_partUntExpr1 IntExpr2 t IntExpr1 IntExpr2 Integer division Result truncate Exprl Expr2 abs Expr Evaluate Expr and return the absolute value of it sign Expr Evaluate to 1 if Expr lt 0 1 if Expr gt 0 and 0 if Expr 0 max Exprl Expr2 Evaluates to the largest of both Expr and Expr2 min Exprl Expr2 Evaluates to the smallest of both Expr1 and Expr2 Int A list of one element evaluates to the element This implies a evaluates to the ASCII value of the letter a 97 This option is available for compatibility only It will not work if style_check string is active as a will then be transformed into a string object The recommended way to specify the ASCII value of the letter a is 0 a random n1 Evaluates to a random integer i for which 0 lt 7 lt Int The seed of this random generator is determined by the system clock when SWI Prolog was started round xpr Evaluates Expr and rounds the result to the nearest integer integer Expr Same as rou
318. rmination If we do not take special precautions the context information associated with an unexpected exception i e a programming error is lost Therefore if an exception is raised which is not caught using catch 3 and the toplevel is running the error will be printed and the system will enter trace mode If the system is in an non interactive callback from foreign code and there is no catch 3 active in the current context it cannot determine whether or not the exception will be caught by the external routine calling Prolog It will then base its behaviour on the prolog_flag debug_on error e current prolog flag debug_on_error false The exception does not trap the debugger and is returned to the foreign routine calling Prolog where it can be accessed using PL_exception This is the default e current_prolog flag debug_on_error true If the exception is not caught by Prolog in the current context it will trap the tracer to help analysing the context of the error While looking for the context in which an exception takes place it is advised to switch on debug mode using the predicate debug 0 4 9 2 The exception term Builtin predicates generates exceptions using a term error Formal Context The first argument is the formal description of the error specifying the class and generic defined context information When applicable the ISO error term definition is used The second part describes some additional context to he
319. rthermore 2 7 lifts the limits on arity of predicates and number of variables in a clause consid erably and allow for further expansion at minimal cost 1 6 7 Version 2 8 Release Notes With version 2 8 we declare the data representation changes of 2 7 x stable Version 2 8 exploits the changes of 2 7 to support 64 bit processors like the DEC Alpha As of version 2 8 5 the representation of recorded terms has changed and terms on the heap are now represented in a compiled format SWI Prolog no longer limits the use of malloc or uses assumptions on the addresses returned by this function 1 6 8 Version 2 9 Release Notes Version 2 9 is the next step towards version 3 0 improving ISO compliance and introducing ISO com pliant exception handling New are catch 3 throw 1 abolish 1 write_term 2 3 write_canonical 1 2 and the C functions PL_exception and PL_throw The predicates display 1 2 and displayq 1 2 have been moved to library oackcomp so old code referring to them will autoload them SWI Prolog 5 0 Reference Manual 14 CHAPTER 1 INTRODUCTION The interface to PL_open_query has changed The debug argument is replaced by a bitwise or ed flags argument The values FALSE and TRUE have their familiar meaning making old code using these constants compatible Non zero values other than TRUE 1 will be interpreted different 1 6 9 Version 3 0 Release Notes Complete redesign of the saved state mechanism
320. s interrupts do not cooperate well with the world of multi threading mainly because the status of mutexes cannot be guaranteed easily At the call port the Prolog virtual machine holds no locks and therefore the asynchronous execution is safe SWI Prolog 5 0 Reference Manual 126 CHAPTER 4 BUILT IN PREDICATES Goal can be any valid Prolog goal including throw 1 to make the receiving thread generate an exception and t race 0 to start tracing the receiving thread 4 39 2 Thread synchronisation All internal Prolog operations are thread safe This implies two Prolog threads can operate on the same dynamic predicate without corrupting the consistency of the predicate This section deals with user level mutexes called monitors in ADA or critical sections by Microsoft A mutex is a MUTual EXclusive device which implies at most one thread can hold a mutex Mutexes are used to realise related updates to the Prolog database With related we refer to the situation where a transaction implies two or more changes to the Prolog database For example we have a predicate address 2 representing the address of a person and we want to change the address by retracting the old and asserting the new address Between these two operations the database is invalid this person has either no address or two addresses depending on the assert retract order Here is how to realise a correct update initialization mutex_create addressbook
321. s an aid to find performance pigs in programs It provides information on the time spent in the various Prolog predicates The profiler is based on the assumption that if we monitor the functions on the execution stack on time intervals not correlated to the program s execution the number of times we find a procedure on the environment stack is a measure of the time spent in this procedure It is implemented by calling a procedure each time slice Prolog is active This procedure scans the local stack and either just counts the procedure on top of this stack plain profiling or all procedures on the stack cumulative profiling To get accurate results each procedure one is interested in should have a reasonable number of counts Typically a minute runtime will suffice to get a rough overview of the most expensive procedures profile Goal Style Number Execute Goal just like time 1 Collect profiling statistics according to style see profiler 2 and show the top Number procedures on the current output stream see show profile 1 The results are kept in the database until reset _profiler 0 or profile 3 is called and can be displayed again with show profile 1l profile 3 1s the normal way to invoke the profiler The predicates below are low level predicates that can be used for special cases show_profile Number Show the collected results of the profiler Stops the profiler first to avoid interference from show profile 1 It shows t
322. s below we will call the source destination argument SrcDest Below are some examples of source destination specifications see data Start reading from file data tell user error Start writing on the error stream tell pipe lpr Start writing to the printer Another example of using the pipe 1 construct is shown below Note that the pipe 1 construct is not part of Prolog s standard I O repertoire getwd Wd seeing Old see pipe pwd collect_wd String seen see Old atom_codes Wd String collect_wd CI R get0 C C 1 collect_wd R collect_wd SWI Prolog 5 0 Reference Manual 4 16 INPUT AND OUTPUT 83 see SrcDest Make SrcDest the current input stream If SrcDest was already opened for reading with see 1 and has not been closed since reading will be resumed Otherwise SrcDest will be opened and the file pointer is positioned at the start of the file tell SrcDest Make SrcDest the current output stream If SrcDest was already opened for writing with tel1 1 or append 1 and has not been closed since writing will be resumed Otherwise the file is created or when existing truncated See also append 1 append File Similar to te11 1 but positions the file pointer at the end of File rather than truncating an existing file The pipe construct is not accepted by this predicate seeing SrcDest Unify the name of the current input stream wit
323. s equivalent to call_cleanup Goal Cleanup calling Cleanup regard less of the reason for termination and without providing information This predicate provides compatibility to a number of other Prolog implementations 4 9 ISO compliant Exception handling SWI Prolog defines the predicates cat ch 3 and throw 1 for ISO compliant raising and catching of exceptions In the current implementation 4 0 6 most of the built in predicates generate exceptions but some obscure predicates merely print a message start the debugger and fail which was the normal behaviour before the introduction of exceptions catch Goal Catcher Recover Behaves as ca11 1 if no exception is raised when executing Goal If a exception is raised using throw 1 while Goal executes and the Goal is the innermost goal for which Catcher unifies with the argument of throw 1 all choicepoints generated by Goal are cut the system backtracks to the start of catch 3 while preserving the thrown exception term and Recover is called as in ca11 1 The overhead of calling a goal through catch 3 is very comparable to ca11 1 Recovery from an exception is much slower especially if the exception term is large due to the copying thereof throw Exception Raise an exception The system looks for the innermost cat ch 3 ancestor for which Exception unifies with the Catcher argument of the catch 3 call See catch 3 for details ISO demands throw 1 to make a copy of Exceptio
324. s less term references Consider the case where we want a foreign function to return the host name of the machine Prolog is running on Using the PL_get_ and PL_put_ functions the code becomes foreign_t pl_hostname term_t name char buf 100 if gethostname buf sizeof buf term_t tmp PL_new_term_ref PL_put_atom_chars tmp buf return PL_unify name buf PL_fail Using PL_unify_atom_chars this becomes foreign_t pl_hostname term_t name char buf 100 if gethostname buf sizeof buf return PL_unify_atom_chars name buf PL_ fail int PL unify term_t tl term_t 712 Unify two Prolog terms and return non zero on success int PL_unify_atom term_t t atom_t a Unify t with the atom a and return non zero on success int PL_unify_atom_chars term_t t const char chars Unify with an atom created from chars and return non zero on success int PL_unify_list_chars term_t t const char chars Unify with a list of ASCII characters constructed from chars void PL_unify_string_chars term_t t const char chars Unify t with a Prolog string object created from the zero terminated string chars The data will be copied See also PL_unify_string_nchars SWI Prolog 5 0 Reference Manual 6 6 THE FOREIGN INCLUDE FILE 169 void PL_unify_string_nchars term_t t unsigned int len const char chars Unify with a Prolog string object created from the string creat
325. s not imply the Windows command interpreter command exe on Windows 95 98 and cmd exe on Windows NT and therefore commands built in to the command interpreter can only be activated using the com mand interpreter For example command exe C copy filel txt file2 txt shell Command Equivalent to shell Command 0 shell Start an interactive Unix shell Default is bin sh the environment variable SHELL overrides this default Not available for Win32 platforms win_exec Command Show Win32 systems only Spawns a Windows task without waiting for its completion Show is either iconic or normal and dictates the initial status of the window The iconic option is notably handy to start DDE servers win_shell Operation File Win32 systems only Opens the document File using the windows shell rules for doing so Op eration is one of open print or explore or another operation registered with the shell for the given document type On modern systems it is also possible to pass a URL as File opening the URL in Windows default browser This call interfaces to the Win32 API ShellExecute win registry get _value Xey Name Value Win32 systems only Fetches the value of a Win32 registry key Key is an atom formed as a path name describing the desired registry key Name is the desired attribute name of the key Value is unified with the value If the value is of type DWORD the value is returned as an integer If the value is
326. s the only option Called this way any resource error such as write errors while flushing the output buffer are ignored stream_property Stream StreamProperty ISO compatible predicate for querying status of open I O streams StreamProperty is one of file name Atom If Stream is associated to a file unify Atom to the name of this file mode 1 OMode Unify OMode to the mode given to open 4 for opening the stream Values are read write append and the SWI Prolog extension update input True if Stream has mode read output True if Stream has mode write append or update alias Atom If Atom is bound test of the stream has the specified alias Otherwise unify Atom with the first alias of the stream position Term Unify Term with the current stream position A stream position is a term of format Sstream_position CharIndex LineNo LinePos See also term position 3 end_of stream E If Stream is an input stream unify E with one of the atoms not at or past See also at_end_of_stream 0 1 eof_action A Unify A with one of eof_code reset or error See open 4 for details reposition Bool Unify Bool with true if the position of the stream can be set see seek 4 It is assumed the position can be set if the stream has a seek function and is not based on a POSIX file descriptor that is not associated to a regular file type 7 Unify Bool with text or binary file no nteger If the stream is associated with
327. s with the intersection of Set and Set2 Set and Set2 are lists without duplicates They need not be ordered subtract Set Delete Result Delete all elements of set Delete from Set and unify the resulting set with Result SWI Prolog 5 0 Reference Manual 110 CHAPTER 4 BUILT IN PREDICATES union Set Set2 Set3 Succeeds if Sef3 unifies with the union of Set and Set2 Set and Set2 are lists without dupli cates They need not be ordered subset Subset Set Succeeds if all elements of Subset are elements of Set as well merge set Set Set2 Set3 Set and Set2 are lists without duplicates sorted to the standard order of terms Set3 is unified with an ordered list without duplicates holding the union of the elements of Set and Set2 4 31 Sorting Lists sort List Sorted Succeeds if Sorted can be unified with a list holding the elements of List sorted to the standard order of terms see section 4 6 Duplicates are removed Implemented by translating the input list into a temporary array calling the C library function qsort 3 using PL_compare for comparing the elements after which the result is translated into the result list msort List Sorted Equivalent to sort 2 but does not remove duplicates keysort List Sorted List is a proper list whose elements are Key Value that is terms whose principal functor is 3 2 whose first argument is the sorting key and whose second
328. s_a_variable 1 End 2 In Edinburgh Prolog the second argument is missing It is fixed to be VAR free_variables Term List Unify List with a list of variables each sharing with a unique variable of Term For example free_variables a X b Y X Z L G367 G366 G371 G367 G366 G371 NK xp II copy_term Jn Out Make a copy of term Jn and unify the result with Out Ground parts of In are shared by Out Provided Jn and Out have no sharing variables before this call they will have no sharing variables afterwards copy_term 2 is semantically equivalent to SWI Prolog 5 0 Reference Manual 96 CHAPTER 4 BUILT IN PREDICATES copy_term In Out recorda copy_key In Ref recorded copy_key Out Rel erase Ref Fh 4 21 Analysing and Constructing Atoms These predicates convert between Prolog constants and lists of ASCII values The predicates atom_codes 2 number_codes 2 and name 2 behave the same when converting from a con stant to a list of ASCII values When converting the other way around atom_codes 2 will generate an atom number_codes 2 will generate a number or exception and name 2 will return a number if possible and an atom otherwise The ISO standard defines atom_chars 2 to describe the broken up atom as a list of one character atoms instead of a list of codes Upto version 3 2 x SWI Prolog s atom_chars 2 behaved compatible to Quintus and SICStus Prolog like a
329. se source file SWI Prolog 5 0 Reference Manual 196 CHAPTER 6 FOREIGN LANGUAGE INTERFACE gcc I usr local lib pl plversion include fpic c lowercase c gcc shared o lowercase so lowercase o pl Welcome to SWI Prolog Version plversion Copyright c 1993 1996 University of Amsterdam All rights reserved For help use help Topic or apropos Word 1 load_foreign_library lowercase Yes 2 lowercase Hello World L L hello world Yes Figure 6 7 Compiling the C source and loading the object file SWI Prolog 5 0 Reference Manual 6 10 NOTES ON USING FOREIGN CODE 197 6 10 Notes on Using Foreign Code 6 10 1 Memory Allocation SWI Prolog s memory allocation is based on the malloc 3 library routines Foreign applications can safely use malloc 3 realloc 3 and free 3 Memory allocation using brk 2 or sbrk 2 is not allowed as these calls conflict with malloc 3 6 10 2 Debugging Foreign Code Statically linked foreign code or embedded systems can be debugged normally Most modern envi ronments provide debugging tools for dynamically loaded shared objects or dynamic load libraries The following example traces the code of lowercase using gdb 1 in a Unix environment gece I usr local lib p1 2 2 0 includ fpic c g lowercase c gcc shared o lowercase so lowercase o gdb p gdb r Welcome to SWI Prolog Vers
330. sed for the Prolog source code that is part of the SWI Prolog system both libraries and kernel code This situation is comparable to 1ibgcc the runtime library used with the GNU C compiler Therefore we use the same proven license terms as this library The libgcc license is the with a special exception Below we rephrased this exception adjusted to our needs SWI Prolog 5 0 Reference Manual D 2 CONTRIBUTING TO THE SWI PROLOG PROJECT 223 As a special exception if you link this library with other files compiled with a Free Software compiler to produce an executable this library does not by itself cause the resulting executable to be covered by the GNU General Public License This exception does not however invalidate any other reasons why the executable file might be covered by the GNU General Public License D 2 Contributing to the SWI Prolog project To achieve maximal coherence using SWI Prolog for Free and Non Free software we advice the use of the LGPL for contributed foreign code and the use of the GPL with SWI Prolog exception for Prolog code for contributed modules As a rule of thumb it is advised to use the above licenses whenever possible and only use a strict GPL compliant license only if the module contains other code under strict GPL compliant licenses D 3 Software support to keep track of license conditions Given the above it is possible that SWI Prolog packages and extensions will rely on the GPL The predicates
331. see resource 3 and open_resource 3 These two parts can be connected in various different ways The most common way for distributed runtime applications is to concatenate the two parts This can be achieved using external commands Unix cat Windows copy or using the stand alone option to qsave_program 2 The second option is to attach a startup script in front of the resource that starts the emulator with the proper options This is the default under Unix Finally an emulator can be told to use a specified resource file using the x commandline switch qsave_program File ListOfOptions Saves the current state of the program to the file File The result is a resource archive contain ing a saved state that expresses all Prolog data from the running program and all user defined resources Depending on the st and_alone option the resource is headed by the emulator a Unix shell script or nothing ListOfOptions is a list of Key Value or Key Value pairs The available keys are described in table 7 1 Before writing the data to file qsave_program 2 will run autoload 0 to all required autoloading the system can discover See autoload 0 Provided the application does not require any of the Prolog libraries to be loaded at runtime the only file from the SWI Prolog development environment required is the emulator itself The emulator may be built in two flavours The default is the development emulator The runtime emulator is simila
332. sources LO sets the limit to the highest possible value See section 2 16 Gsize km Give global stack limit 4 Mbytes default See L for more details Tsize km Give trail stack limit 4 Mbytes default This limit is relatively high because trail stack over flows are not often caused by program bugs See L for more details Asize km Give argument stack limit 1 Mbytes default The argument stack limits the maximum nesting of terms that can be compiled and executed SWI Prolog does last argument optimisation to avoid many deeply nested structure using this stack Enlarging this limit is only necessary in extreme cases See L for more details c file Compile files into an intermediate code file See section 2 10 0 output Used in combination with c or b to determine output file for compilation O Optimised compilation See current prolog flag 2 s file Use file as a script file The script file is loaded after the initialisation file specified with the f fileoption Unlike f file using s d oes not stop Prolog from loaded the personal initialisation file f file Use file as initialisation file instead of the default plrc Unix or pl ini Windows none stops SWI Prolog from searching for a startup file This option can be used as an alternative to s file that stops Prolog from loading the personal initialisation file See also section 2 2 SWI Prolog 5
333. st _ T is list T append List List2 List3 Succeeds when List3 unifies with the concatenation of List and List2 The predicate can be used with any instantiation pattern even three variables member Elem List Succeeds when Elem can be unified with one of the members of List The predicate can be used with any instantiation pattern memberchk Elem List Equivalent to member 2 but leaves no choice point delete List1 Elem List2 Delete all members of List that simultaneously unify with Elem and unify the result with List2 select Elem List Rest Select Elem from List leaving Rest It behaves as membe r 2 returning the remaining elements in Rest Note that besides selecting elements from a list it can also be used to insert elements 7 nth0 Index List Elem Succeeds when the Index th element of List unifies with Elem Counting starts at 0 6Tn versions before 5 0 1 is_list 1 just checked for or _ _ and proper_list 1 had the role of the current is_list 1 The current definition is conform the de facto standard Assuming proper coding standards there should only be very few cases where a quick and dirty is_list 1 is a good choice Richard O Keefe pointed at this issue BUG Upto SWI Prolog 3 3 10 the definition of this predicate was not according to the de facto standard The first two arguments were in the wrong order SWI Prolog 5 0 Reference Manual 4 30 SET MANIPULATIO
334. stacks though a copy requires only 4 additional bytes min_tagged integer integer Start of the tagged integer value range float_format atom changeable C printf format specification used by write 1 and friends to determine how float ing point numbers are printed The default is sg The specified value is passed to printf without further checking For example if you want more digits printed 12g will print all floats using 12 digits instead of the default 6 See also format 1 2 write 1 print 1 and portray l1 toplevel_print_options term changeable This argument is given as option list to write_term 2 for printing results of queries Default is quoted true portray true max_depth 10 debugger_print_options term changeable This argument is given as option list to write term 2 for printing goals by the de bugger Modified by the w p and N d commands of the debugger Default is quoted true portray true max_depth 10 debugger_show_context bool changeable If t rue show the context module while printing a stack frame in the tracer Normally controlled using the C option of the tracer compiled_at atom Describes when the system has been compiled Only available if the C compiler used to compile SWI Prolog provides the DATE and _TIME__ macros character escapes bool changeable If true default read 1 interprets escape sequences in quoted atoms and strings May be
335. t a single character from input stream user regardless of the current input stream Unlike get0 1 this predicate does not wait for a return The character is not echoed to the user s terminal This predicate is meant for keyboard menu selection etc If SWI Prolog was started with the tty option this predicate reads an entire line of input and returns the first non blank character on this line or the ASCII code of the newline 10 if the entire line consisted of blank characters at_end_of stream Succeeds after the last character of the current input stream has been read Also succeeds if there is no valid current input stream at_end_of_stream Stream Succeeds after the last character of the named stream is read or Stream is not a valid input stream The end of stream test is only available on buffered input stream unbuffered input streams are rarely used see open 4 copy stream _data Streamin StreamOut Len Copy Len bytes from stream StreamIn to StreamOut copy stream_data Streamin StreamOut Copy data all remaining data from stream StreamIn to StreamOut 4 19 Term reading and writing This section describes the basic term reading and writing predicates The predicates term_to_atom 2 atom_to_term 3 and sformat 3 provide means for translating atoms and strings to terms The predicates format 1 2 and writef 2 provide formatted output There are two ways to manipulate the output format The predicate print 1 2 m
336. t can normally not be seen in the tracer foreign Is true if the predicate is defined in the C language dynamic Is true if the predicate is declared dynamic using the dynamic 1 declaration multifile Is true if the predicate is declared multifile using the mult ifile 1 declaration undefined Is true if a procedure definition block for the predicate exists but there are no clauses in it and it is not declared dynamic This is true if the predicate occurs in the body of a loaded predicate an attempt to call it has been made via one of the meta call predicates or the predicate had a definition in the past See the library package check for example usage transparent Is true if the predicate is declared transparent using the module_transparent 1 dec laration exported Is true if the predicate is in the public list of the context module imported from Module Is true if the predicate is imported into the context module from module Module indexed Head Predicate is indexed see index 1 according to Head Head is a term whose name and arity are identical to the predicate The arguments are unified with 1 for indexed arguments 0 otherwise file FileName Unify FileName with the name of the source file in which the predicate is defined See also source_file 2 line_count LineNumber Unify LineNumber with the line number of the first clause of the predicate Fails if the predicate is not associated with a file See also s
337. t connected to a terminal or it is running as a GNU Emacs inferior process This flag is sometimes required for smooth interaction with other applications x bootfile Boot from bootfile instead of the system s default boot file A bootfile is a file result ing from a Prolog compilation using the b or c option or a program saved using qsave_program 1 2 p alias pathI path2 Define a path alias for file_search_path alias is the name of the alias path isa separated list of values for the alias A value is either a term of the form alias value or pathname The computed aliases are added to file_search_path 2 using asserta 1 so they precede predefined values for the alias See file search path 2 for details on using this file location mechanism Stops scanning for more arguments so you can pass arguments for your application after this one See current _prolog flag 2 using the flag argv for obtaining the commandline arguments The following options are for system maintenance They are given for reference only b initfile c file Boot compilation initfile are compiled by the C written bootstrap compiler file by the normal Prolog compiler System maintenance only SWI Prolog 5 0 Reference Manual 22 CHAPTER 2 OVERVIEW d level Set debug level to level Only has effect if the system is compiled with the DO_DEBUG flag System maintenance only 2 5 GNU Emacs Interface The default Prolog m
338. t_pointer 166 PL put string chars 166 PL_put_string_nchars 163 166 PL_put_term 167 PL_put_variable 166 PL_query Q 181 PL_quote 172 SWI Prolog 5 0 Reference Manual INDEX 249 PL_raise_exception 177 PL_record 179 PL_record_external 180 PL_recorded 179 PL_recorded_external 180 PL_register_atom 159 PL register_extensions 183 PL _register_foreign 183 PL_reset_term_refs 155 PL_retry 157 PL retry_address 157 PL_rewind foreign frame 175 PL_same_compound 179 PL signalO 181 PL_strip_module 175 PL_succeed 156 PL_term_type 160 PL_thread_attach_engine 178 PL_thread_destroy_engine 179 PL_thread_selfQ 178 PL_throwQ 178 PL_toplevel 190 PL_unifyQ 168 PL_unify_arg 170 PL_unify_atom 168 PL_unify_atom_chars 168 PL_unify_atom_nchars 163 PL_unify_floatQ 169 PL_unify functor 169 PL_unify_integer 169 PL_unify_list 169 PL_unify_list_chars 168 PL_unify_list_nchars 163 PL_unify_list_ncodes 163 PL_unify_nilO 169 PL_unify_pointer Q 169 PL_unify_string_chars 168 PL_unify_string nchars 163 169 PL_unify_term 170 PL_unregister_atom 159 PL_warning 181 plus 3 66 103 portray 1 27 33 36 45 90 92 173 185 215 portray _clause 1 62 portray _clause 1 61 predicate_property 2 79 predicate_property 2 145 predsort 3 110 preprocessor 2 59 print 1 33 91 92 113 114 173 231 print 2 92 p
339. ta using native foreign representation and passing a pointer to it is a sensible choice 3 The data lives as during the lifetime of a foreign predicate If the predicate is deterministic foreign automatic variables are suitable if the predicate is non deterministic the data may be allocated using malloc and a pointer may be passed See section 6 6 1 Examples for storing foreign data In this section we wull outline some examples covering typical cases In the first example we will deal with extending Prolog s data representation with integer sets represented as bit vectors In the second example we look at handling a netmask Finally we discuss the outline of the DDE interface Integer sets with not to far apart upper and lower bounds can be represented using bit vectors Common set operations such as union intersection etc are reduced to simple and ing and or ing the bitvectors This can be done in Prolog using a compound term holding integer arguments Especially if the integers are kept below the maximum tagged integer value see current_prolog_flag 2 this representation is fairly space efficient wasting 1 word for the functor and and 7 bits per integer for the tags Arithmetic can all be performed in Prolog too For really demanding applications foreign representation will perform better especially time wise Bit vectors are natrually expressed using string objects If the string is wrapped in bitvector 1 l
340. tandard This package has a notion of current input and current output The reading and writing predicates implicitly refer to these streams In the second package streams are opened explicitly and the resulting handle is used as an argument to the reading and writing predicate to specify the source or destination Both packages are fully integrated the user may switch freely between them 4 16 1 Input and output using implicit source and destination The package for implicit input and output destination is upwards compatible to DEC 10 and C Prolog The reading and writing predicates refer to resp the current input and output stream Initially these streams are connected to the terminal The current output stream is changed using tel1 1 or append 1 The current input stream is changed using see 1 The streams current value can be obtained using telling 1 for output and seeing 1 for input streams The table below shows the valid stream specifications The reserved names user_input user_output and user_error are for neat integration with the explicit streams user This reserved name refers to the terminal user_input Input from the terminal user_output Output to the terminal user_error Unix error stream output only Atom Name of a Unix file pipe Atom Name of a Unix command Source and destination are either a file one of the reserved words above or a term pipe Command In the predicate description
341. tart with an underscore if style_check Singleton is active default Used to read Prolog source files see consult 1 New code should use read_term 2 with the option singletons warning read_clause Stream Term Read a clause from Stream See read_clause 1 read_term 7erm Options Read a term from the current input stream and unify the term with Term The reading is con trolled by options from the list of Options If this list is empty the behaviour is the same as for read 1 The options are upward compatible to Quintus Prolog The argument order is ac cording to the ISO standard Syntax errors are always reported using exception handling see catch 3 Options variables Vars Unify Vars with a list of variables in the term The variables appear in the order they have been read See also free_variables 2 ISO SWI Prolog 5 0 Reference Manual 4 19 TERM READING AND WRITING 93 variable_names Vars Unify Vars with a list of Name Var where Name is an atom describing the variable name and Var is a variable that shares with the corresponding variable in Term ISO singletons Vars As variable names but only reports the variables occurring only once in the Term read Variables starting with an underscore _ are not included in this list ISO syntex_errors Atom If error default throw and exception on a syntax error Other values are fail which causes a message to be printed using print message 2
342. te for editing something is edit 1 an extensible front end that searches for objects files predicates modules as well as XPCE classes and methods in the Prolog database If multiple matches are found it provides a choice Together with the built in completion on atoms bound to the TAB key this provides a quick way to edit objects edit country Please select item to edit 1 chat country 10 staff jan lib prolog chat countr pl 16 2 chat country 1 staff jan lib prolog chat world0 pl 72 Your choice 3 3 2 Editing and incremental compilation One of the nice features of Prolog is that the code can be modified while the program is running Using pure Prolog you can trace a program find it is misbehaving enter a break environment modify the source code reload it and finally do retry on the misbehaving predicate and try again This sequence is not uncommon for long running programs For faster programs one normally aborts after understanding the misbehaviour edit the source reload it and try again One of the nice features of SWI Prolog is the availability of make 0 a simple predicate that checks all loaded source files to see which ones you have modified It then reloads these files consid ering the module from which the file was loaded originally This greatly simplifies the trace edit verify development cycle After the tracer reveals there is something wrong with prove 3 you do edit prove Now e
343. tem defined search mechanism for the shared library The file_search_path 2 alias mechanism defines the alias foreign which refers to the directories plhome 1ib arch and plhome 1ib in this order If the library can be loaded the function called Entry will be called without arguments The return value of the function is ignored The Entry function will normally call PL_register_foreign to declare functions in the library as foreign predicates load _foreign_library Lib Equivalent to load_foreign_library 2 For the entry point this function first identifies the base name of the library which is defined to be the file name with path nor extension It will then try the entry point install base On failure it will try to function install Otherwise no install function will be called unload foreign library Lib If the foreign library defines the function uninstall_ base or uninstall this function will be called without arguments and its return value is ignored Next abolish 2 is used to remove all known foreign predicates defined in the library Finally the library itself is detached from the process current_foreign_library Lib Predicates Query the currently loaded foreign libraries and their predicates Predicates is a list with elements of the form Module Head indicating the predicates installed with PL_register_foreign when the entry point of the library was called Figure 6 1 connects a
344. terms convert them to basic C types as well as to instantiate arguments using unification Non deterministic foreign predicates are supported providing the foreign function with a handle to control backtracking C can call Prolog predicates providing both an query interface and an interface to extract multiple solutions from an non deterministic Prolog predicate There is no limit to the nesting of Prolog calling C calling Prolog etc It is also possible to write the main in C and use Prolog as an embedded logical engine 6 1 Overview of the Interface A special include file called SWI Prolog h should be included with each C source file that is to be loaded via the foreign interface The installation process installs this file in the directory include in the SWI Prolog home directory current prolog flag home Home This C header file defines various data types macros and functions that can be used to communicate with SWI Prolog Functions and macros can be divided into the following categories Analysing Prolog terms Constructing new terms Unifying terms Returning control information to Prolog Registering foreign predicates with Prolog Calling Prolog from C Recorded database interactions Global actions on Prolog halt break abort etc 6 2 Linking Foreign Modules Foreign modules may be linked to Prolog in three ways Using static linking the extensions a small description file and the basic SWI Prolog
345. ternatively terms may be created top down first creating a compound holding only vari ables and subsequently unifying the arguments This section discusses functions for the first approach This approach is generally used for creating arguments for PL_ca11 and PL_open_query void PL_put_variable term_t 1 Put a fresh variable in the term The new variable lives on the global stack Note that the initial variable lives on the local stack and is lost after a write to the term references After using this function the variable will continue to live void PL_put_atom term_t t atom_t a Put an atom in the term reference from a handle See also PL_new_atom and PL_atom_chars void PL_put_atom_chars term_t t const char chars Put an atom in the term reference constructed from the 0 terminated string The string itself will never be references by Prolog after this function void PL_put_string_chars term_t t const char chars Put a zero terminated string in the term reference The data will be copied See also PL_put_string_nchars void PL_put_string_nchars term_t t unsigned int len const char chars Put a string represented by a length start pointer pair in the term reference The data will be copied This interface can deal with 0 bytes in the string See also section 6 6 18 void PL_put_list_chars term_t t const char chars Put a list of ASCII values in the term reference void PL_put_integer term_t t long i
346. ters the exception term and returns FALSE If a foreign predicate returns FALSE while and exception term is registered a Prolog ex ception will be raised by the virtual machine Calling these functions outside the context of a function implementing a foreign predicate results in undefined behaviour PL_exception may be used after a call to PL_next_solution fails and returns a term reference to an exception term if an exception was raised and O otherwise If a C function implementing a predicate calls Prolog and detects an exception us ing PL_exception it can handle this exception or return with the exception Some caution is required though It is not allowed to call PL close query or PL_discard_foreign_frame afterwards as this will invalidate the exception term Below is the code that calls a Prolog defined arithmetic function see arithmethic_function 1 If PL_next_solution succeeds the result is analysed and translated to a number after which the query is closed and all Prolog data created after PL open foreign frame is de stroyed On the other hand if PL_next_solution fails and if an exception was raised just pass it Otherwise generate an exception PL_error is an internal call for building the standard error terms and calling PL_raise_exception After this the Prolog environment should be discarded using PL_cut_query and PL_close_foreign_frame to avoid invalidating the exception term static int
347. th search ListOfName Value Search specification of HTTP URL This is the part after the normally used to transfer data from HTML forms that use the GET protocol In the URL it consists of a www form encoded list of Name Value pairs This is mapped to a list of Prolog Name Value terms with decoded names and values fragment Fragment Fragment specification of HTTP URL This is the part after the character The example below illustrates the all this for an HTTP UTL parse_url http swi psy uva nl message cgi msg HellotWorld 21 x P P protocol http host swi psy uva nl fragment x search msg Hello World 1 path message cgi By instantiating the parts list this predicate can be used to create a URL parse_url URL BaseURL Parts Same as parse url 2 but dealing a url that is relative to the given BaseURL This is used to analyse or construct a URI found in the document behind BaseURL global_url URL Base URL Absolute Url Transform a possibly relative URL into a global one http location Parts Location Similar to parse url 2 but only deals with the location part of an HTTP URL That is the path search and fragment specifiers In the HTTP protocol the first line of a message is SWI Prolog 5 0 Reference Manual 212 APPENDIX A THE SWI PROLOG LIBRARY Action Location HTTP AttpVersion Location is either an atom or a code list www_form_enco
348. the file The value read or shared means other processes may read the file but not write it The value write or exclusive means no other process may read or write the file Locks are acquired through the POSIX function fentl using the command F_SETLKW which makes a blocked call wait for the lock to be released Please note that fcntl locks are advisory and therefore only other applications using the same advisory locks honour your lock As there are many issues around locking in Unix expecially related to NFS network file system please study the fcntl manual page before trusting your locks The lock option is a SWI Prolog extension The option reposition is not supported in SWI Prolog All streams connected to a file may be repositioned open SrcDest Mode Stream Equivalent to open 4 with an empty option list open_null_stream Stream Open a stream that produces no output All counting functions are enabled on such a stream An attempt to read from a null stream will immediately signal end of file Similar to Unix dev null Stream can be an atom giving the null stream an alias name close Stream Close the specified stream If Stream is not open an error message is displayed If the closed stream is the current input or output stream the terminal is made the current input or output SWI Prolog 5 0 Reference Manual 4 16 INPUT AND OUTPUT 85 close Stream Options Provides close Stream force true a
349. the line has been read A line is ended by a newline character or end of file Unlike read_line_to_codes 3 this predicate removes trailing newline character read line to_codes Stream Codes Tail Diference list version to read an input line to a list of character codes Reading stops at the newline or end of file character but unlike read_line_to_codes 2 the newline is retained in the output This predicate is especially useful for readine a block of lines upto some delimiter The following example reads an HTTP header ended by a blank line read_header_data Stream Header read_line_to_codes Stream Header Tail read_header_data Header Stream Tail read_header_data r n _ _ read_header_data n _ _ read_header_data _ _ read_header_data _ Stream Tail read_line_to_codes Stream Tail NewTail read_header_data Tail Stream NewTail read _stream_to_codes Stream Codes Read all input until end of file and unify the result to Codes read_stream_to_codes Stream Codes Tail Difference list version of read_st ream_to_codes 2 read_file_to_codes Spec Codes Options Read a file to a list of character codes Spec is a file specification for absolute_file_name 3 Codes is the resulting code list Options is a list of op tions for absolute_file_name 3 and open 4 In addition the option tail Zail is defined forming a difference list SWI Prolog 5 0 Reference Manual
350. then provides all the terms required to be output Escape sequences to generate a single special character SWI Prolog 5 0 Reference Manual 4 35 FORMATTED WRITE 113 n Sl Vr t nnn Output a nemline character see also n1 0 1 Output a line separator same as n Output a carriage return character ASCII 13 Output the ASCII character TAB 9 The character is output The character is output where nnn is an integer 1 3 digits the character with ASCII code nnn is output NB nnn is read as deci mal Note that 1 nnn and are interpreted differently when character escapes are in effect See section 2 15 1 Escape sequences to include arguments from Arguments Each time a escape sequence is found in Format the next argument from Arguments is formatted according to the specification AS t o A A Ao o o o n K 5 Ko Qa Q Kh Z AP A A a Z Q Z K print 1 the next item mnemonic term write 1 the next item writeq 1 the next item Write the term ignoring operators See also write_term 2 Mnemonic old Edinburgh display 1 print 1 the next item identical to t Put the next item as a character i e it is an ASCII value Write the next item N times where N is the second item an integer Write the next item as a String so it must be a list of char acters Perform a tt yflush 0 no items used Write the next item Center
351. therwise if the file defines a module import all public predicates Finally if the file is already loaded is not a module file and the context module is not the global user module ensure_loaded 1 will call consult 1 With the semantics we hope to get as closely possible to the clear semantics without the presence of a module system Applications using modules should consider using use_module 1 2 Equivalent to load_files Files if changed include File Pretend the terms in File are in the source file in which include File appears The include construct is only honnoured if it appears as a directive in a source file Normally File contains a sequence of directives require ListOfNameAndArity make Declare that this file module requires the specified predicates to be defined with their com monly accepted definition This predicate originates from the Prolog portability layer for XPCE It is intended to provide a portable mechanism for specifying that this module requires the specified predicates The implementation normally first verifies whether the predicate is already defined If not it will search the libraries and load the required library SWI Prolog having autoloading does not load the library Instead it creates a procedure header for the predicate if it does not exist This will flag the predicate as undefined See also check 0 and autoload 0 Consult all source files that have been c
352. tion by loading load pl and call qsave program 2 to generate a saved state with the proper options debug pl Loads the program for debugging In addition to loading load pl this file defines rules for port ray 1 to modify printing rules for complex terms and customisation rules for the debug ger and editing environment It may start some of these tools Using modules Modules have been debated fiercely in the Prolog world Despite all counter arguments we feel they are extremely useful because They hide local predicates This is the reason they have been invented in the first place Hiding provides two features They allow for short predicate names without worrying about conflicts Given the flat name space introduced by modules they still require meaningful module names as well as meaningful names for exported predicates They document the interface Possibly more important then avoiding name conflicts is their role in documenting which part of the file is for public usage and which is private When editing a module you may assume you can reorganise anything but the name and semantics of the exported predicates without worrying They help the editor The PceEmacs built in editor does on the fly cross referencing of the current module colouring predicates based on their origin and usage Using modules the editor can quickly find out what is provided by the imported modules by reading just the first term This allows it to indicate rea
353. tom via the termcap library function tputs This function decodes padding informa tion in the strings returned by tt y_get_capability 3 and should be used to output these strings Lines is the number of lines affected by the operation or 1 1f not applicable as in almost all cases SWI Prolog 5 0 Reference Manual 4 37 OPERATING SYSTEM INTERACTION 117 set_tty OldStream NewStream Set the output stream used by tt y_put 2 and tty_goto 2 to a specific stream Default is user_output tty_size Rows Columns Determine the size of the terminal If the system provides ioctl calls for this these are used and tty size 2 properly reflects the actual size after a user resize of the window As a fallback the system uses tty_get_capability 2 using li and co capabilities In this case the reported size reflects the size at the first call and is not updated after a user initiated resize of the terminal 4 37 Operating System Interaction shell Command Status Execute Command on the operating system Command is given to the Bourne shell bin sh Status is unified with the exit status of the command On Win32 systems she11 1 2 executes the command using the CreateProcess API and waits for the command to terminate If the command ends with a amp sign the command is handed to the WinExec API which does not wait for the new task to terminate See also win_exec 2 and win_shel1 2 Please note that the CreateProcess API doe
354. tom_codes As of 3 3 x SWI Prolog atom_codes 2 and atom_chars 2 are compliant to the ISO standard To ease the pain of all variations in the Prolog community all SWI Prolog predicates behave as flexible as possible This implies the list side accepts either a code list or a char list and the atom side accept all atomic types atom number and string atom_codes Atom String Convert between an atom and a list of ASCII values If Atom is instantiated if will be translated into a list of ASCII values and the result is unified with String If Atom is unbound and String is a list of ASCII values it will Atom will be unified with an atom constructed from this list atom_chars Atom CharList As atom_codes 2 but CharList is a list of one character atoms rather than a list of ASCII values atom_chars hello X xX Ay e a ly o char_code Atom ASCID Convert between character and ASCII value for a single character 4 number_chars Number CharList Similar to atom_chars 2 but converts between a number and its representation as a list of one character atoms Fails with a representation_error if Number is unbound and CharList does not describe a number 13 Upto version 3 2 x atom_chars 2 behaved as the current atom_codes 2 The current definition is compliant with the ISO standard This is also called atom_char 2 in older versions of SWI Prolog as well as some other Prolog implementations atom_char
355. ts behaviour mirror mirror I mirror P fetch P x X SWI Prolog 5 0 Reference Manual 5 6 META PREDICATES IN MODULES 143 fetch P Yr Y store P y X store P x Y The predicates fetch 3 and store 3 are predicates that change instance variables of instances The figure below indicates how message passing can easily be implemented invoke Instance Selector ArgumentList send a message to an instance A ol invoke I S Args class_of_instance I Class Class behaviour S P ArgCheck convert_arguments ArgCheck Args ConvArgs Goal P ConvArgs Class Goal The construct Module Goal explicitly calls Goal in module Module It is discussed in more detail in section 4 8 5 6 Meta Predicates in Modules As indicated in the introduction the problem with a predicate based module system lies in the dif ficulty to find the correct predicate from a Prolog term The predicate solution Solution can exist in more than one module but assert solution 4 in some module is supposed to refer to the correct version of solution 1 Various approaches are possible to solve this problem One is to add an extra argument to all predicates e g assert Module Term Another is to tag the term somehow to indicate which mod ule is desired e g assert Module Term Both approaches are not very attractive as they make the user responsible for choosing the correct modul
356. ual 2 9 OVERVIEW OF THE DEBUGGER 25 28 00 seconds cpu time for 183 128 inferences 4 016 atoms 1 904 functors 2 042 predicates 52 modules 55 915 byte codes 11 239 external references Limit Allocated In use Heap 624 820 Bytes Local stack 2 048 000 8 192 404 Bytes Global stack 4 096 000 16 384 968 Bytes Trail stack 4 096 000 8 192 432 Bytes Yes 8 2 9 Overview of the Debugger SWI Prolog has a 6 port tracer extending the standard 4 port tracer Clocksin amp Melish 1987 with two additional ports The optional unify port allows the user to inspect the result after unification of the head The exception port shows exceptions raised by throw 1 or one of the built in predicates See section 4 9 The standard ports are called call exit redo fail and unify The tracer is started by the trace 0 command when a spy point is reached and the system is in debugging mode see spy 1 and debug 0 or when an exception is raised The interactive toplevel goal trace 0 means trace the next query The tracer shows the port displaying the port name the current depth of the recursion and the goal The goal is printed using the Prolog predicate write_term 2 The style is defined by the prolog flag debug ger print options and can be modified using this flag or using the w p and d commands of the tracer On leashed ports set with the predicate leash 1 default are call exit redo and fail the us
357. ully be applied to all succes A Ae n ive pairs of elements of Listl and List2 AS maplist _ Igo TINS maplist Goal Elem1 Tail1 Elem2 Tail2 apply Goal Eleml Elem2 maplist Goal Taill Tail2 m 5 6 2 Overruling Module Boundaries The mechanism above is sufficient to create an acceptable module system There are however cases in which we would like to be able to overrule this schema and explicitly call a predicate in some module or assert explicitly in some module The first is useful to invoke goals in some module from the user s toplevel or to implement a object oriented system see above The latter is useful to create and modify dynamic modules see section 5 7 For this purpose the reserved term 2 has been introduced All built in predicates that transform a term into a predicate reference will check whether this term is of the form Module Term If so the predicate is searched for in Module instead of the goal s context module The operator may be nested in which case the inner most module is used The special calling construct Module Goal pretends Goal is called from Module instead of the context module Examples assert world done asserts done 0 into module world world assert done world done the same calls done 0 in module world Ad A ol 5 7 Dynamic Modules So far we discussed modules that were created by loading
358. ument vector for Prolog plav 0 program plav 1 NULL initialise Prolog if PL_initialise 1 plav PL_halt 1 Lookup calc 1 and make the arguments and call predicate_t pred PL_predicate calc 1 user term_t h0 PL_new_term_refs 1 int rval PL_put_atom_chars h0 expression rval PL_call_predicate NULL PL_Q NORMAL pred h0 PL_halt rval 0 1 return 0 Figure 6 5 C source for the calc application SWI Prolog 5 0 Reference Manual 194 CHAPTER 6 FOREIGN LANGUAGE INTERFACE 6 8 The Prolog home directory Executables embedding SWI Prolog should be able to find the home directory of the devel opment environment unless a self contained saved state has been added to the executable see qsave_program 1 2 and section 6 7 If Prolog starts up it will try to locate the development environment To do so it will try the following steps until one succeeds 1 If the environment variable SWI_HOME_DIR is defined and points to an existing directory use this 2 If the environment variable SWIPL is defined and points to an existing directory use this 3 Locate the primary executable or Windows only a component module thereof and check whether the parent directory of the directory holding this file contains the file swip1 If so this file contains the relative path to the home directory If this directory exists use this This is the norma
359. used for flags see f lag 3 current_key Key Successively unifies Key with all keys used for records see recorda 3 etc current_predicate Name Head Successively unifies Name with the name of predicates currently defined and Head with the most general term built from Name and the arity of the predicate This predicate succeeds for all predicates defined in the specified module imported to it or in one of the modules from which the predicate will be imported if it is called current_predicate Name Arity ISO compliant implementation of current predicate 2 Unlike current _predicate 2 the current implementation of current_predicate 1 does not consider predicates that can be autoloaded current predicate_property Head Property Succeeds if Head refers to a predicate that has property Property Can be used to test whether a predicate has a certain property obtain all properties known for Head find all predicates having SWI Prolog 5 0 Reference Manual 80 CHAPTER 4 BUILT IN PREDICATES property or even obtaining all information available about the current program Property is one of interpreted Is true if the predicate is defined in Prolog We return true on this because although the code is actually compiled it is completely transparent just like interpreted code built_in Is true if the predicate is locked as a built in predicate This implies it cannot be redefined in its definition module and i
360. ut C get0 In C2 copy_stream C2 In Out The predicate he1lp 0 opens the resource as a Prolog stream If we are executing this from the development environment this will actually return a stream to the gelp txt itself When executed from the saved state the stream will actually be a stream opened on the program resource file taking care of the offset and length of the resource 7 3 1 Predicates Definitions resource Name Class FileSpec This predicate is defined as a dynamic predicate in the module user Clauses for it may be defined in any module including the user module Name is the name of the resource an atom A resource name may contain any character except for and which are reserved for internal usage by the resource library Class describes the what kind of object is stored in the resource In the current implementation it is just an atom FileSpec is a file specification that may exploit file_search_path 2 see absolute_file_name 2 Normally resources are defined as unit clauses facts but the definition of this predicate also allows for rules For proper generation of the saved state it must be possible to enumerate the available resources by calling this predicate with all its arguments unbound Dynamic rules are useful to turn all files in a certain directory into resources without specifying a resources for each file For example assume the file_search_path 2 icons refers to the resource directory co
361. ut are compliant with the ISO standard This implies that SWI Prolog 5 0 Reference Manual 4 7 CONTROL PREDICATES 65 the cut is transparent to 2 gt 2 and gt 2 Cuts appearing in the condition part of gt 2 and gt 2 as well as in 1 are local to the condition ti a fail b cuts a 0 and t1 0 t2 a gt b ec cuts b 0 and t2 0 t3 call a fail b cuts a 0 t4 a fail b cuts a 0 Goall Goal2 Conjunction Succeeds if both Goall and Goal can be proved It is defined as this defini tion does not lead to a loop as the second comma is handled by the compiler Goall Goal2 Goall Goal2 Goall Goal2 The or predicate is defined as Goall _Goal2 Goall _Goall Goal2 Goal2 Goall Goal2 Equivalent to 2 Retained for compatibility only New code should use 2 Condition gt Action If then and If Then Else The gt 2 construct commits to the choices made at its left hand side destroying choice points created inside the clause by 2 or by goals called by this clause Unlike 0 the choicepoint of the predicate as a whole due to multiple clauses is not destroyed The combination 2 and gt 2 is defines as If gt Then _Else If Then If gt _Then Else Else If gt Then If Then Note that the operator precedence relation
362. vironment control predicates the current value is retrieved using on signal Signal Current Current The action description is an atom denoting the name of the predicate that will be called if Signal arrives on signal 3 is a meta predicate which implies that Module Name refers the Name 1 in the module Module Two predicate names have special meaning throw implies Prolog will map the signal onto a Prolog exception as described in section 4 9 default resets the handler to the settings active before SWI Prolog manipulated the handler Signals bound to a foreign function through PL_signal are reported using the term for eign_function Address After receiving a signal mapped to throw the exception raised has the structure error signal SigName SigNum Context SWI Prolog 5 0 Reference Manual 72 CHAPTER 4 BUILT IN PREDICATES One possible usage of this is for example to limit the time spent on proving a goal This requires a little C code for setting the alarm timer see chapter 6 include lt SWI Prolog h gt include lt unistd h gt foreign_t pl_alarm term_t time double t if PL_get_float time amp t alarm long t 0 5 PL_succeed PL_fail install_t install PL_register_foreign alarm 1 pl_alarm 0 Next we can define the following Prolog code load_foreign_library alarm on_signal alrm throw module
363. was taken from the stack as Long Such code fails when passing small integral types on machines where int is smaller than long It is advised to use PL_SHORT PL_INT or PL_LONG as appropriate Similar C compilers promote float to double and therefore PL_FLOAT and PL_DOUBLE are synonyms The type identifiers are PL_VARIABLE none No op Used in arguments of PL_FUNCTOR PL_ATOM atom t Unify the argument with an atom as in PL_unify_atom PL_SHORT short Unify the argument with an integer as in PL unify integer As short is pro moted to int PL_SHORT is a synonym for PL_INT PL_INT int Unify the argument with an integer as in PL_unify_integer PL_LONG long Unify the argument with an integer as in PL _unify integer PL_INTEGER long Unify the argument with an integer as in PL_unify_integer PL_DOUBLE double Unify the argument with a float as in PL_unify_float Note that as the argument is passed using the C vararg conventions a float must be casted to a double explicitly PL_FLOAT double Unify the argument with a float as in PL_unify_float PL_POINTER void Unify the argument with a pointer as in PL_unify_pointer PL_STRING const char Unify the argument with a string object as in PL unify_string_chars PL_TERM term Unify a subterm Note this may the return value of a PL_new_term_ref call to get access to a variable SWI Prolog 5 0 Reference Manual 6
364. xplain Give an explanation on the given object The argument may be any Prolog data object If the argument is an atom a term of the form Name Arity or a term of the form Module Name Arity explain will try to explain the predicate as well as possible references to it explain 70Explain Explanation Unify Explanation with an explanation for ToExplain Backtracking yields further explanations 2 7 Query Substitutions SWI Prolog offers a query substitution mechanism similar to that of Unix csh csh 1 called his tory The availability of this feature is controlled by set _prolog_flag 2 using the history prolog flag By default history is available if the prolog flag readline is false To enable this feature remembering the last 50 commands put the following into your startup file see section 2 2 set_prolog_flag history 50 The history system allows the user to compose new queries from those typed before and remembered by the system It also allows to correct queries and syntax errors SWI Prolog does not offer the Unix csh capabilities to include arguments This is omitted as it is unclear how the first second etc argument should be defined The available history commands are shown in table 2 1 One could choose words defining words as a sequence of alpha numeric characters and the word separators as anything else but one could also choose Prolog arguments SWI Prolog 5 0 Reference Manual
365. xt backwards Control W Extend search to next word boundary Control G Cancel search go back to where it started ESC Commit search leaving caret at found location Backspace Remove a character from the search string Dynamic Abbreviation Also called dabbrev is an important feature of Emacs clones to support programming After typing the first few letters of an identifier you may hit Alt causing PceEmacs to search back wards for identifiers that start the same and using it to complete the text you typed A second Alt searches further backwards If there are no hits before the caret it starts searching forwards With some practice this system allows for very fast entering code with nice and readable iden tifiers or other difficult long words 4GNU Emacs keeps extending the string but why Adding more text will not make it match SWI Prolog 5 0 Reference Manual 3 4 USING THE PCEEMACS BUILT IN EDITOR 49 e Open a file Is called File Find file Control x Control f By default the file is loaded into the current window If you want to keep this window Hit Alt s or click the little icon at the bottom left to make the window sticky e Split view Sometimes you want to look at two places of the same file To do this use Control x 2 to create a new window pointing to the same file Do not worry you can edit as well as move around in both Control x 1 kills all other windows running on the same file These we
366. y optimise compilation implies compilation of arithmetic and deletion of redun dant t rue 0 that may result from expand_goal 2 Later versions might imply various other optimisations such as integrating small predi cates into their callers eliminating constant expressions and other predictable constructs Source code optimisation is never applied to predicates that are declared dynamic see dynamic 1 char_conversion bool changeable Determines whether character conversion takes place while reading terms See also char_conversion 2 autoload bool changeable If t rue default autoloading of library functions is enabled See section 2 13 verbose_autoload bool changeable If true the normal consult message will be printed if a library is autoloaded By default this message is suppressed Intended to be used for debugging purposes verbose_file_search bool changeable If true default false print messages indicating the progress of absolute_file_name 2 3 in locating files Intended for debugging com plicated file search paths See also file _ search path 2 SWI Prolog 5 0 Reference Manual 2 11 ENVIRONMENT CONTROL PROLOG FLAGS 35 trace_ge bool changeable If true false is the default garbage collections and stack shifts will be reported on the terminal May be changed max_arity unbounded ISO prolog flag describing there is no maximum arity to compound terms integer_rounding function down toward_z
367. ying properties module Collection of predicates Each module defines a name space for predicates built in predicates are accessible from all modules Predicates can be published exported and imported to make their definition available to other modules module transparent predicate A predicate that does not change the context module Sometimes also called a meta predicate multifile predicate Predicate for which the definition is distributed over multiple source files See multi_file l neck Operator separating head from body in a clause operator Symbol atom that may be placed before its operant prefix after its operant postfix or between its two operants infix In Prolog the expression a b is exactly the same as the canonical term a b SWI Prolog 5 0 Reference Manual 220 APPENDIX C GLOSSARY OF TERMS operant Argument of an operator precedence The priority of an operator Operator precedence is used to interpret a b c as a b c predicate Collection of clauses with the same functor name arity If a goal is proved the system looks for a predicate with the same functor then used indexing to select candidate clauses and then tries these clauses one by one See also backtracking priority In the context of operators a synonym for precedence program Collection of predicates property Attribute of an object SWI Prolog defines various _property predicates to query the status
368. yout is not just particular style for layout Below are head argl arg2 head argl arg2 Ds head Argl arg2 1 calll Argl head Argl e gt arg2 if Argl then else T head Arg1 w a many long arguments with many more and a nice it is essential for writing readable code There is much debate on the proper layout of Prolog PceEmacs being a rather small project supports only one examples of typical constructs Defined in Prolog in the file library emacs prolog mode you may wish to extend this Please contribute your extensions SWI Prolog 5 0 Reference Manual 3 5 THE GRAPHICAL DEBUGGER 51 PceEmacs uses the same conventions as GNU Emacs The TAB key indents the current line according to the syntax rules Alt q indents all lines of the current clause It provides support for head calls indented 1 tab if then else disjunction and argument lists broken across multiple lines as illustrated above Finding your way around The command Alt extracts name and arity from the caret location and jumps after conformation or edit to the definition of the predicate It does so based on the source location database of loaded predicates also used by edit 1 This makes locating predicates reliable if all sources are loaded and up to date see make 0 In addition references to files in use_module 1 2 consult 1 etc are red if the file can n

SWI-Prolog 5.0 Reference Manual

Contents

Download Pdf Manuals

Related Search

Related Contents