
SRC Interactive Computing Facility                       Prolog Program Library
SIG Artificial Intelligence                                                XREF



                     Department of Artificial Intelligence
                            University of Edinburgh


                        PROLOG CROSS REFERENCE PROGRAM

                               Source:    Dave Bowen, Chris Mellish et alia
                       Program Issued:    July 1982
                        Documentation:    July 1982
                     Updated for UNIX:    November 1983 (D.L. Bowen)
	       Updated for UvApsy VAX:    December 1984 (Jan Wielemaker)

1. Description

Xref is a cross-reference program which produces an alphabetically ordered list
of  predicates,  giving the file in which each is defined and a list of all the
predicates which call it.  If required, it also gives a list of all the imports
and exports for each file, i.e. the global predicates used and defined in  each
file.

The  user  may  extend the program by providing a definition file.  This can be
used to supply xref with additional information.  For example  it  can  specify
that  certain  predicates  are  built-in, and these predicates are then omitted
from the cross-reference.  Also, it can be used to answer  in  advance  various
questions which would otherwise require user interaction at run time.


2. How to Use the Program

First load the program by typing

	    | ?- lib(xref).

Then the predicate go/0 may be used to start, at which point the prompt

	    Next file: 

will appear and a file name should be typed in, followed  by  a  carriage-return
(not a full-stop).  The prompt is repeated so that as many file names as desired
may be entered.  E.g.

            Next file: myfile
            Next file:

When all the required files have been entered, this input phase  is  terminated
by just typing a carriage-return by itself.

The user is subsequently prompted for an output file name, and a title.   He  is
then  asked  whether  lists of imports and exports are required, and should type
the letter "y" (or "yes") if they  are.   If  the  answer  is  no,  the  program
terminates;  otherwise  there  follows  a  request  for a file name to which the
import/export lists are to be written.

2.1. Definition Files

The  predicate  go/0  prevents  cross-referencing  of  built-in  predicates   by
"loading" the definition file xref.def, either from your area if you have such a
file or else from the xref.d directory in the library (xref.def from the library
is  defualt  loaded in this version).  The definitions in this file should be of
the form:

            sys_pred(fail).
            sys_pred(length(_,_)).

which indicate that fail/0 and length/2 are built-in predicates.

The user may provide additional definition file(s).  A  definition  file  called
mydefs can be loaded into xref by preceding the filename with "*", thus:

            Next file: *mydefs

The asterisk may be omitted if the file has the extension "def"; e.g.  

            Next file: mydefs.def

Apart  from  the  definition of system predicates, several other kinds of terms
are allowed in a definition file:

op(<priority>, <associativity>, <operator symbol list>).
                These terms simply declare  operators  as  in  the  normal  way
                except  that they take the form of assertions rather than goals
                (the preceding ':-' is  omitted).    It  is  not  necessary  to
                declare  operators  in  the  definition  file  unless their use
                precedes their declaration in the files to be processed.

known(<predicate>, <where defined>).
                This  is  useful  for  utility  predicates   for   which   full
                cross-referencing is not required.  It simply tells the program
                where  a  particular  procedure  is  defined, so that it is not
                necessary to process the module which contains  the  definition
                of that procedure.

applies(<term>, <term>).
                This  can be used to indicate that a given predicate takes some
                other predicate as an argument and causes that predicate to  be
                called.  For example, suppose there is a user-defined predicate
                maplist/3  which  takes  a predicate and two lists as arguments
                e.g.  

                            :- maplist(foo,[X1,X2,X3],[Y1,Y2,Y3]).

                and successively applies the predicate to the i-th elements  of
                each of the lists.  I.e. the above goal clause is equivalent to
                

                            :- foo(X1,Y1), foo(X2,Y2), foo(X3,Y3).

                The appropriate entry in the definition file is 

                            applies( maplist(Pred,L1,L2), Pred+2 ).

                This expresses the fact that the first argument of maplist is a
                predicate  and  that  it  is  to  be called with two additional
                arguments, i.e. the above call of maplist/3  results  in  calls
                foo/2.  The '+2' would be omitted if maplist/3 caused foo to be
                called  with  no  additional arguments, i.e. if foo/0 was to be
                referenced.  Note that if maplist is called with a variable  as
                its  first argument, the cross-referencer cannot determine what
                predicate(s) are to be called  and  so  no  special  action  is
                taken.

called(<predicate>).
                This  informs  xref that <predicate> is called.  This is useful
                both for top level routines which are to be called by the user,
                and also for predicates which  are  entered  via  the  built-in
                predicate call/1.  In both cases it avoids the possibility of a
                warning  message claiming that the predicate is not called.  It
                also ensures that the predicate is included in the exports list
                for  the  file.

called(<predicate>,<calling predicate>,<arity cal. pred.>,<file cal. pred.>).
		Tell xref that <predicate> is called  by  <calling  predicate>,
		which  has  arity  <arity  cal.   pred.> and is defined on file
		<file cal.  pred.>.

The following can be used to save having to repeatedly type the same answers to
the questions asked by xref at run time.

cross_ref_file(<file name>).
                This defines the filename for the cross-reference listing.

title(<atom or string>).
                This defines the title for the cross-reference listing.

width(<text width>).
                This   defines   the   text   width   (in  characters)  of  the
                cross-reference listing (In this version the default is 78).

globals_file(<file name>).
                This defines the filename for the imports/exports listings.  If
                it is 'no' then no globals listings will be produced.



2.2. Indirect Files

If a number of file names are listed on a file called foo, say, then  they  can
all  be  entered  at  once simply by typing the file name preceded by an "@" in
response to the prompt "Next file: ", thus:  

            Next file: @foo

If the file names were listed instead in foo.ccl, then the "@" could be omitted
since the extension "ccl" is assumed to indicate that the file is  an  indirect
one.  I.e.  

            Next file: foo.ccl

would have the desired effect.

The indirect file should contain valid unix file names, separated  by  linefeeds
or  returns.  Comment lines may be added by putting a '%' on the first positionn
of the line.

If a file (re)consults other files using :-[...],  ?-[...],  :-(re)consult(...)
or ?-(re)consult(...) these files will be processed as well.


2.3. Procedures Provided

The top level procedures provided are as follows:

go/0		first loads xref.def from your area or the xref.d  directory  of
		the library, and then calls start/0.

load/1          takes either a list of file names or a single  file  name as its
                argument.  The files are loaded as definition files.

start/0		starts the cross-reference program which then runs as  described
		above.  That is, the prompt "Next file: " appears on the screen.

