Quintus Prolog Manual

k-11: Miscellaneous Packages

k-11-1: ctr.{pl,c}

}) library(ctr) provides an array of 32 global integer variables. It was written some time ago for compatibility with another dialect of Prolog. The operations provided on these variables are

ctr_set(+Ctr, +N): ctr[Ctr] := N
ctr_set(+Ctr, +N, ?Old): Old is ctr[Ctr], ctr[Ctr] := N
ctr_inc(+Ctr): ctr[Ctr] := ctr[Ctr] + 1
ctr_inc(+Ctr, +N): ctr[Ctr] := ctr[Ctr] + N
ctr_inc(+Ctr, +N, ?Old): Old is ctr[Ctr], ctr[Ctr] := ctr[Ctr] + N
ctr_dec(+Ctr): ctr[Ctr] := ctr[Ctr] - 1
ctr_dec(+Ctr, +N): ctr[Ctr] := ctr[Ctr] - N
ctr_dec(+Ctr, +N, ?Old): Old is ctr[Ctr], ctr[Ctr] := ctr[Ctr] - N
ctr_is(+Ctr, ?Old): Old is ctr[Ctr]

If you want to use these counters in a nestable construct, remember to reset them properly; for example,


count_solutions(Goal, Count) :-

        ctr_set(17, 0, Old),

        (call(Goal), ctr_inc(17), fail ; true),

        ctr_set(17, Old, X),

        Count = X.

This will work even if Goal contains a call to count_solutions/2, because the old counter value is saved on entry to the clause, and restored on exit. Contrast this with the following example:


count_solutions(Goal, Count) :-

        ctr_set(17, 0),

        (call(Goal), ctr_inc(17), fail ; true),

        ctr_set(17, X),

        Count = X.

In this example, if Goal contains a call to count_solutions/2, the inner call will clobber the counter of the outer call, and the predicate will not work. This file is provided mainly to allow you to experience (by doing your own timing tests) that the foreign interface, not the data base, is the tool for hacking global variables in Prolog, provided that the global variables take only constants as values.

k-11-2: date.{c,pl}

}) library(date) is a time-stamp package.

Dates are records of the form date(Year, Month, Day).
Times are records of the form time(Hour, Minute, Second).
Datimes are records of the form date(Year, Month, Day, Hour, Minute, Second).
"When" values are 32-bit UNIX time-stamps representing the number of seconds since the beginning of January 1st 1970. Since Prolog currently limits integers to 29 bits, the time-stamps are represented as xwd(Hi,Lo), in which Hi and Lo are both 16-bit integers.

The parameter ranges are

Year            year-1900       (e.g. 1987 -> 87)

Month           0..11           (e.g. January -> 0, September -> 8)

Day             1..31           (e.g. 27 -> 27)

Hour            0..23           (e.g. midnight -> 0, noon -> 12)

Minute          0..59

Second          0..59

These parameter ranges are compatible with the UNIX library function localtime(3). Note that the range for months is not what you might expect. The predicates provided are:

now(?When)
date(-DateNow)
date(+When, -DateThen)
time(-TimeNow)
time(+When, -TimeThen)
datime(-DatimeNow)
datime(+When, -DatimeThen)
datime(?Datime, ?Date, ?Time)
date_and_time(-DateNow, -TimeNow)
date_and_time(+When, -DateThen, -TimeThen)
portray_date(+TimeStamp)
time_stamp(+Format, -TimeStamp)
time_stamp(+When, +Format, -TimeStamp)

For example,


        | ?- date(X), portray_date(X).

        11-Jan-90

        X = date(90,0,11)

Note that if you want both the current date and time, you should call either datime/1 or date_and_time/2. It is an error to obtain the date and time in separate calls, because midnight could intervene and put you nearly 24 hours out. Dates and datimes are also returned by directory_property/3 and file_property/3 (see library(directory)). All these records can be compared using term comparison. The predicates time_stamp/[2,3] provide a way of creating a time-stamp atom using a special kind of format string. For example,


        | ?- time_stamp('%W, %d %M %y',Date).



        Date = 'Thursday, 11 January 1990'

The details of the format strings are explained in a comment in the sources. Please note that, in the interests of internationalization, time_stamp/[2,3] are likely to be superseded in a future release by something based on the ANS C operation strftime(). The other predicates in this package will NOT change at that time.

k-11-3: Arbitrary Expressions -- library(activeread)

Languages such as Lisp allow you to read an expression and to evaluate it, returning a data structure. Prolog provides "evaluation" only for arithmetic expressions, and then only in certain argument positions. activeread.pl provides a new experimental facility for reading an arbitrary "expression" and "evaluating" it.


        | ?- active_read(InputTerm).

reads a term from the current input stream. If this term has the form


        X | Goal.

then Goal is called and InputTerm is unified with X. Otherwise, InputTerm is unified with the term which was read. Note that Goal may backtrack, in which case active_read/1 will also backtrack. EXAMPLES:


        | ?- active_read(X).

        |: T | append([1,2],[3,4], T).

        X = [1,2,3,4]

        yes



        | ?- active_read(X).

        |: Front+Back | append(Front, Back, [1,2,3,4]).

        X = []+[1,2,3,4] ;

        X = [1]+[2,3,4] ;

        X = [1,2]+[3,4] ;

        X = [1,2,3]+[4] ;

        X = [1,2,3,4]+[] ;

        no



        | ?- active_read(X).

        |: abort.

        X = abort

        yes

NOTE: activeread.pl is not a module-file, but it is sufficiently small that there should be no problem with including a separate copy in each module where it is required.

k-11-4: addportray.pl

library(addportray) makes the use of portray/1 more convenient. In DEC-10 Prolog and C Prolog, a program could contain clauses like


        portray(X) :-

                should_be_handled_here(X),

                print_it_this_way

scattered through any number of files. In Quintus Prolog, this does not work, because each file will wipe out every other file's clauses for portray/1; in any case, a clause for portray/1 in a module will do nothing at all, because it is user:portray/1 which you must define. DEC-10 Prolog and C Prolog had a similar problem in that if you reconsulted a file containing such clauses, you lost all the other clauses for portray/1. Now, in order to add a link to portray/1 clauses to your program, you can do the following:


        :- use_module(library(add_portray)).



        local_portray(X) :-

                should_be_handled_here(X),

                print_it_this_way(X).



        :- add_portray(local_portray).

To cancel such a link, you can call


        :- del_portray(local_portray).

Note that if you use this package, you should not define portray/1 in any other way; otherwise, these links will be lost. You can link to other user-defined predicates (such as term_expansion/2) this way too. Suppose the other predicate to be linked to is user:Pred/Arity. Then


        :- add_linking_clause(Link, Pred, Arity).

ensures that there is a clause


        Pred(X1,...,XArity) :- Link(X1,...,XArity).

in module user:, where Link/Arity is called in the module from which add_linking_clause/3 is called, and


        :- del_linking_clause(Link, Pred, Arity).

ensures that there is no such clause. For example, you can add a case to term_expansion/2 by adding the following directive to a module:


        :- add_linking_clause(local_expander, term_expansion, 2).

k-12: Abstracts

The following abstracts are meant to describe the functionality of each package, not to serve as documentation. Whatever documentation exists is included in comments within each package. Refer to {manual(k-1-3-1)} to find out how to locate the source files if you wish to read the code comments. All the files abstracted in the following pages are found in the 'library' subdirectory of 'qplib3.3'.

aggregate.pl: library(aggregate) defines aggregate/3, an operation similar to bagof/3 which lets you calculate sums. For example, given a table pupil(Name, Class, Age), to calculate the average age of the pupils in each class, one would write
anti_unify.pl: Anti-unification is the mathematical dual of unification: given two terms T1 and T2 it returns the most specific term which generalizes them, T. T is the most specific term which unifies with both T1 and T2. A common use for this is in learning; the idea of using it that way comes from Gordon Plotkin. The code here is based on a routine called 'generalise/5' written by Fernando Pereira. The name was changed because there are other ways of generalizing things, but there is only one dual of unification.
arity.pl: Provides support for Arity code translated by arity2quintus.
aritystring.pl: provides support for Arity's string operations.
arrays.pl: library(arrays) provides constant-time access and update to arrays. It involves a fairly unpleasant hack. You would be better off using library(logarr) or library(trees).
assoc.pl: library(assoc) A binary tree implementation of "association lists".
avl.pl: AVL trees in Prolog.
bags.pl: library(bags) provides support for the data type 'bag'.
benchmark.pl: Users can easily obtain information about the performance of goals: time and memory requirements.
between.pl: library(between) provides routines for generating integers on backtracking.
big_text.{pl,c}: Defines a 'big_text' data type and several operations on it. The point of this module is that when writing an interactive program you often want to display to (or acquire from) the user large amounts of text. It would be inadvisable (though possible) to store the text in Prolog's data base. With this package you can store text in a file, copy text to a stream, acquire new text from a stream, and/or have Emacs edit a big text file. See the file big_text.txt in the library area for more details.
bitsets.pl: Operations on sets of integers (bitsets). Contains analogs for most operations in library(ordsets).
break.pl: Prints an error message and enters a break level (if possible), avoiding the problem of break/0 in QPC.
call.pl: library(call) provides a number of predicates which are useful in programs which pass goals as arguments.
caseconv.pl: library(caseconv) is mainly intended as an example of the use of library(ctypes). Here you'll find predicates to test whether text is in all lowercase, all uppercase, or mixed-case, and to convert from one case to another.
charsio.{pl,c}: library(charsio) lets you open a list of character codes for input as a Prolog stream and, having written to a Prolog stream, collect the output as a list of character codes. There are three things you can do with library(charsio):
clump.pl: Group adjacent related elements of lists.
count.pl: The purpose is to count predicate calls. Instead of loading a program by calling compile/1, use count/1. The program will do what it always used to, except that it may run twice as slowly. The output of library(count) is a file which contains a record of predicate calls, and is suitable for processing by awk(1) and all other UNIX utilities.
critical.{pl,c}: library(critical) provides a critical-region facility.
crypt.{pl,c} and encrypt.c: library(crypt) defines two operations similar to open/3: crypt_open(+FileName[, +Password], +Mode, -Stream) If you do not supply a Password, crypt_open/3 will prompt you for it. Note that the password will be echoed. If there is demand, this can be changed. The Stream will be clear text as far as Prolog is concerned, yet encrypted as far as the file system is concerned. encrypt.c is a stand-alone program (which is designed to have its object code linked to 3 names: encrypt, decrypt, and recrypt), and can be used to read and write files using this encryption method. This encryption method was designed, and the code was published, in Edinburgh, so it is available outside the USA.
decons.pl: library(decons) provides a set of routines for recognizing and building Prolog control structures. The only predicate which is likely to be useful is prolog_clause(Clause, Head, Body).
environ.pl: library(environ) provides access to the UNIX "environment variables". environ(?Varname, ?Value) is a genuine relation. Note that if you include this file in a saved state, the values of environment variables are those current when the saved state was run, not when it was saved. There is also an argv/1 in this file, which is superseded by unix(argv(_)).
demo.pl: Defines demo file_search_path.
det.pl: Aids in determinacy checking by locating places where cuts are really necessary.
environment.pl: Portability aid for Unix (BSD, System V), VMS, VM/SP (CMS), MVS, MS-DOS, Macintosh.
This library "takes over" term_expansion/2 and provides more: powerful hooks that enable multiple, "simultaneously active" and recursive program transformations to be achieved in an effcient manner.
filename.{pl, cms, mac, msdos, vms}: Portable file name manipulation. Documentation on filename.txt.
fft.pl: Performs a fast fourier transform in Prolog. This file was written to demonstrate that a FFT could be written in Prolog with the same O(N*log(N)) _asymptotic_ cost as in Fortran. There are several easy things that could be done to make it faster, but you would be better off for numerical calculations like this using library(vectors) to call a Fortran subroutine.
flatten.pl: library(flatten) provides predicates for flattening binary trees into lists.
foreach.pl: library(foreach) defines two iteration forms.
freevars.pl: This is an internal support package. Users will probably have no direct use for it.
fromonto.pl: library(fromonto) defines some "pretty" operators for input/output redirection. Examples:
gauss.pl: Gaussian elimination.
getfile.pl: defines get_file(+FileName, -ListOfLines) which reads an entire file into memory in one go.
graphs.pl: a collection of utilities for manipulating mathematical graphs. The collection is incomplete. Please let Quintus know which operations in this collection are most useful to you, and which operations that you would find useful have not been included. The P-representation of a graph is a list of (from-to) vertex pairs, where the pairs can be in an arbitrary order. This form is convenient for input and output. The S-representation of a graph is a list of (vertex-neighbors) pairs, where the pairs are in standard order (as produced by keysort/2) and the neighbors of each vertex are also in standard order (as produced by sort/2). This form is convenient for many calculations. See also library(mst) ({manual(k-12)}), which is soon to be merged into library(graphs).
heaps.pl: library(heaps) provides support for the data type 'heap' (heaps are also known as priority queues).
ibm2iso.c: Character code mapping (IBM PC & Mac)
knuth_b_1.pl: library(knuth_b_1) is a table of constants taken from Appendix B1 of D.E.Knuth's The Art of Computer Programming, Volume 1. The point is not to provide the constants -- you could have calculated them yourselves easily enough -- but to illustrate the recommended way of building such constants into your programs.
listparts.pl: library(listparts) exists to establish a common vocabulary for names of parts of lists among Prolog programmers.
lpa.pl: Compatibility library for LPA Prologs. See also quintus.mac, quintus.dec.
logarr.pl: library(logarr) is an implementation of "arrays" as 4-way trees. See also library(trees).
long.pl: This is a rational arithmetic package. rational(N) recognizes arbitrary-precision rational numbers: this includes integers, 'infinity', 'neginfinity', & 'undefined'. whole(N) recognizes arbitrary precision integers. eval(Expr, Result) evaluates an expression using arbitrary precision rational arithmetic; it does not accept floats at all. {eq,ge,gt,le,lt,ne}/2 are infix predicates like '<'/2 that compare rationals (or integers, not expressions). succ/2, plus/3, and times/3 are relational forms of arithmetic which work on rational numbers (not floats). To have rational numbers printed nicely, put the command
mapand.pl: library(mapand) provides mapping routines over &-trees. See also maplist.pl.
maplist.pl: library(maplist) is built on top of library(call), and provides a collection of meta-predicates for applying predicates to elements of lists.
maps.pl: library(maps) implements functions over finite domains, which functions are represented by an explicit data structure.
mst.pl: library(mst) is a preliminary version of a minimal spanning tree package, that will eventually be merged into library(graphs). library(mst) currently provides two predicates:
menu.pl: library(menu) illustrates how to drive the Emacs interface from Prolog. The sample application involves choosing items from a menu. See also the menu_example.pl program in the demo subdirectory of the installation directory.
multil.pl: library(multil) provides multiple-list routines.
newqueues.pl: library(newqueues) provides support for the 'queue' data type. The library(newqueues) package replaces library(queues), and should be used in new programs. })
note.pl: The built-in predicates and commands pertaining to the "recorded" (or "internal" data base) have an argument called the "key". All that matters about this key is its principal functor. That is, fred(a, b) and fred(97, 46) are regarded as the same key. library(note) defines a complete set of storing, fetching, and deleting commands where the "key" is a ground term all of which is significant, using the existing recorded data base. Note that this package is no better indexed than the existing recorded data base.
nlist.{pl, c}: Interface to the Unix library function nlist(3).
order.pl: The usual convention for Prolog operations is INPUTS before OUTPUTS. The built-in predicate compare/3 violates this. This package provides an additional interface to provide comparison predicates with the usual order. The package contains predicates to compare numbers, terms, sets and ordered lists.
ordered.pl: library(ordered) is a collection of predicates for doing things with a list and an ordering predicate. See also library(ordsets) ({manual(k-2-7)}, library(ordprefix) below, and library(samsort) ({manual(k-12)}).
ordprefix.pl: library(ordprefix) is for extracting initial runs from lists, perhaps with a user-supplied ordering predicate. See also library(ordered) above.
quintus.mac: version of lpa.pl to be used on Mac.
quintus.dec: version of lpa.pl to be used on DEC.
pipe.pl: Quintus streams may be connected to pipes using library(pipe), which provides a single predicate:
plot.pl: This package generates UNIX plot(5)files.
pptree.pl: This file defines pretty-printers for (parse) trees represented in the form
printchars.pl: library(print_chars) is not a module, and it would be pointless to load it into any module but 'user'. It extends portray/1 (using library(add_portray)) so that lists of character codes are written by print/1, by the top level, and by the debugger, between double quotes.
printlength.pl: library(print_length) provides predicates for determining how wide a term would be if written.
putfile.c: Uses C stream functions to copy the contents of a file to the the current output stream. This is the fastest known method for copying the contents of a Unix or VMS file to the current output stream.
qerrno.h: Defines error codes specific to Quintus Prolog which do not have any standard assignment among the UNIX errnos.
qsort.pl: library(qsort) provides a stable version of quicksort. Note that quicksort is NOT a good sorting method for a language like Prolog. If you want a good sorting method, see library(samsort) below.
queues.pl: library(queues) provides support for the 'queue' data type. This library has been made obsolete in Release 3 by the introduction of library(newqueues). It is retained for backward compatibility, but should not be used in new programs.
random.{pl,c,o}: library(random) provides a random number generator and several handy interface routines. The random number generators supplied by various operating systems are all different. It is useful to have a random number generator which will give the same results in all versions of Quintus Prolog, and this is the one.
ranstk.pl: This is a Prolog implementation of the algorithms in Eugene W. Myers' "An Applicative Random-Access Stack".
read.pl: This code was originally written at the University of Edinburgh. David H. D. Warren wrote the first version of the parser. Richard A. O'Keefe extracted it from the Dec-10 Prolog system and made it use only user-visible operations. He also added the feature whereby P(X,Y,Z) is read as call(P,X,Y,Z). Alan Mycroft reorganized the code to regularize the functor modes. This is easier to understand (there are no more '?'s), and it also fixes bugs concerning the curious interaction of cut with the state of parameter instantiation. O'Keefe then took it over again and made a number of other changes. There are three intentional differences between this library and the Dec-10 Prolog parser:
retract.pl: This file adds more predicates for accessing dynamic clauses and the recorded data base. The built-in predicate retract/1 will backtrack through a predicate, expunging each matching clause until the caller is satisfied. This is not a bug. That is the way retract/1 is supposed to work. But it is also useful to have a version that does not backtrack. library(retract) defines, among many other commands, retract_first/1, which is identical to retract/1 except that it expunges only the first matching clause, and fails if asked for another solution.
samsort.pl: library(samsort) provides a stable sorting routine which exploits existing order, both ascending and descending. (It is a generalization of the natural merge.) samsort(Raw, Sorted) is like sort(Raw, Sorted) except that it does not discard duplicate elements. samsort(Order, Raw, Sorted) lets you specify your own comparison predicate, which the built-in sorting predicates sort/2 and keysort/2 do not. This file also exports two predicates for merging already-sorted lists: merge/3 and merge/4. See also library(ordered) and library(qsort).
setof.pl: library(setof) provides additional predicates related to the built-in predicate setof/3. Note that the built-in predicates bagof/3 and setof/3 are much more efficient than the predicates in this file. See also library(findall).
show.pl: The built-in command listing/1 displays dynamic predicates. But there is no built-in command for displaying the terms recorded under a given key. library(show) defines two predicates: show(Key) displays all the terms recorded under the given Key, and show/0 displays all the Keys and terms in the recorded data base.
showmodule.pl: library(show_module) provides a command for displaying information about a loaded module. show_module(Module) prints a description of the Module, what it exports, and what it imports. The command
statistics.pl: The full_statistics/[0,2] predicates are exactly like the built-in statistics/[0,2] predicates except that
stchk.pl: This package allows local style-check modifications in a file. This module provides an alternative interface to the style check flags. The idea is that a file which uses it will look like <usual heading> :- push_style. :- set_style(StyleFlag, Value). ... <clauses> :- pop_style. Some combination of this with the existing style check interface will be safe: no matter what style check changes are made, the original values will be restored. The initial state (assumed) is that all checks are ON.
terms.{pl,c,h}: The foreign code interface provides means of passing constants between Prolog and C, FORTRAN, Pascal, etc. library(terms) lets you pass copies of terms from Prolog to C, and receive copies of terms from C. For example, the new built-in predicate copy_term/2 could have been defined this way:
termdepth.pl: Many resolution-based theorem provers impose a depth bound on the terms they create -- not least to prevent infinite loops. library(term_depth) provides predicates that find the depth, length and size of a term, which can even be used on cyclic terms.
tokens.pl: This package is a public-domain tokeniser in reasonably standard Prolog. It is meant to complement the library READ routine. It recognizes Dec-10 Prolog with the following exceptions:
trees.pl: library(trees) is an implementation of arrays as binary trees.
types.pl: This file is support for the rest of the library, and is not really meant for general use. The type tests it defines are almost certain to remain in the library or to migrate to the system. The error checking and reporting code is certain to change. The library predicates must_be_compound/3, must_be_proper_list/3, must_be_var/3, and proper_list/1 are new in this release.

update.pl: library(update) provides utilities for updating "data base" relations.
vectors.{pl,c}: The Quintus Prolog foreign code interface provides means of passing scalars between Prolog and C, FORTRAN, Pascal, etc. library(vectors) provides routines you can use to pass one-dimensional numeric arrays between Prolog and C, Pascal, or FORTRAN. See the comments in the code. Briefly,
writetokens.pl: This package converts a term to a list of tokens. This is essentially the same as the public-domain write.pl, except that instead of writing characters to the current output stream, it returns a list of tokens. There are three kinds of tokens: punctuation marks, constants, and atoms. There is nothing to indicate spacing; the point of this package is to let the caller do such formatting.

l: Prolog Reference Pages

contact: product support sales information