/usr/share/doc/swi-prolog-doc/Manual/autoload.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<HTML>
<HEAD>
<TITLE>SWI-Prolog 5.6.59 Reference Manual: Section 2.13</TITLE><LINK REL=home HREF="index.html">
<LINK REL=contents HREF="Contents.html">
<LINK REL=index HREF="DocIndex.html">
<LINK REL=previous HREF="hooks.html">
<LINK REL=next HREF="gc.html">
<STYLE type="text/css">
/* Style sheet for SWI-Prolog latex2html
*/

dd.defbody
{ margin-bottom: 1em;
}

dt.pubdef
{ background-color: #c5e1ff;
}

pre.code
{ margin-left: 1.5em;
margin-right: 1.5em;
border: 1px dotted;
padding-top: 5px;
padding-left: 5px;
padding-bottom: 5px;
background-color: #f8f8f8;
}

div.navigate
{ text-align: center;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
}

div.title
{ text-align: center;
padding-bottom: 1em;
font-size: 200%;
font-weight: bold;
}

div.author
{ text-align: center;
font-style: italic;
}

div.abstract
{ margin-top: 2em;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
margin-left: 10%; margin-right:10%;
}

div.abstract-title
{ text-align: center;
padding: 5px;
font-size: 120%;
font-weight: bold;
}

div.toc-h1
{ font-size: 200%;
font-weight: bold;
}

div.toc-h2
{ font-size: 120%;
font-weight: bold;
margin-left: 2em;
}

div.toc-h3
{ font-size: 100%;
font-weight: bold;
margin-left: 4em;
}

div.toc-h4
{ font-size: 100%;
margin-left: 6em;
}

span.sec-nr
{ 
}

span.sec-title
{ 
}

span.pred-ext
{ font-weight: bold;
}

span.pred-tag
{ float: right;
font-size: 80%;
font-style: italic;
color: #202020;
}

/* Footnotes */

sup.fn { color: blue; text-decoration: underline; }
span.fn-text { display: none; }
sup.fn span {display: none;}
sup:hover span 
{ display: block !important;
position: absolute; top: auto; left: auto; width: 80%;
color: #000; background: white;
border: 2px solid;
padding: 5px; margin: 10px; z-index: 100;
font-size: smaller;
}
</STYLE>
</HEAD>
<BODY BGCOLOR="white">
<DIV class="navigate"><A class="nav" href="index.html"><IMG SRC="home.gif" BORDER=0 ALT="Home"></A>
<A class="nav" href="Contents.html"><IMG SRC="index.gif" BORDER=0 ALT="Contents"></A>
<A class="nav" href="DocIndex.html"><IMG SRC="yellow_pages.gif" BORDER=0 ALT="Index"></A>
<A class="nav" href="hooks.html"><IMG SRC="prev.gif" BORDER=0 ALT="Previous"></A>
<A class="nav" href="gc.html"><IMG SRC="next.gif" BORDER=0 ALT="Next"></A>
</DIV>

<H2><A NAME="sec:2.13"><SPAN class="sec-nr">2.13</SPAN> <SPAN class="sec-title">Automatic 
loading of libraries</SPAN></A></H2>

<A NAME="sec:autoload"></A>

<P>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 <EM>auto loader</EM> is activated. On first activation an 
index to all library files in all library directories is loaded in core 
(see <A NAME="idx:librarydirectory1:189"></A><A class="pred" href="consulting.html#library_directory/1">library_directory/1</A> 
and <A NAME="idx:filesearchpath2:190"></A><A class="pred" href="consulting.html#file_search_path/2">file_search_path/2</A>). 
If the undefined predicate can be located in one of the libraries that 
library file is automatically loaded and the call to the (previously 
undefined) predicate is restarted. By default this mechanism loads the 
file silently. The <A NAME="idx:currentprologflag2:191"></A><A class="pred" href="flags.html#current_prolog_flag/2">current_prolog_flag/2</A> <A class="flag" href="flags.html#flag:verbose_autoload">verbose_autoload</A> 
is provided to get verbose loading. The Prolog flag <A class="flag" href="flags.html#flag:autoload">autoload</A> 
can be used to enable/disable the entire auto load system.

<P>The auto-loader only works if the unknown flag (see <A NAME="idx:unknown2:192"></A><A class="pred" href="debugger.html#unknown/2">unknown/2</A>) 
is set to
<CODE>trace</CODE> (default). A more appropriate interaction with this 
flag should be considered.

<P>Autoloading only handles (library) source files that use the module 
mechanism described in <A class="sec" href="modules.html">chapter 5</A>. 
The files are loaded with <A NAME="idx:usemodule2:193"></A><A class="pred" href="import.html#use_module/2">use_module/2</A> 
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 <CODE>INDEX.pl</CODE> that contains an index to all library 
files in the directory. This file consists of lines of the following 
format:

<PRE class="code">
index(Name, Arity, Module, File).
</PRE>

<P>The predicate <A NAME="idx:make0:194"></A><A class="pred" href="consulting.html#make/0">make/0</A> 
updates the autoload index. It searches for all library directories (see <A NAME="idx:librarydirectory1:195"></A><A class="pred" href="consulting.html#library_directory/1">library_directory/1</A> 
and <A NAME="idx:filesearchpath2:196"></A><A class="pred" href="consulting.html#file_search_path/2">file_search_path/2</A>) 
holding the file <CODE>MKINDEX.pl</CODE> or <CODE>INDEX.pl</CODE>. If 
the current user can write or create the file <CODE>INDEX.pl</CODE> 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 <CODE>MKINDEX.pl</CODE> 
exists updating is achieved by loading this file, normally containing a 
directive calling
<A NAME="idx:makelibraryindex2:197"></A><A class="pred" href="autoload.html#make_library_index/2">make_library_index/2</A>. 
Otherwise <A NAME="idx:makelibraryindex1:198"></A><A class="pred" href="autoload.html#make_library_index/1">make_library_index/1</A> 
is called, creating an index for all <CODE>*.pl</CODE> files containing 
a module.

<P>Below is an example creating a completely indexed library directory.

<PRE class="code">
% mkdir ~/lib/prolog
% cd !$
% pl -g true -t 'make_library_index(.)'
</PRE>

<P>If there are more than one library files containing the desired 
predicate the following search schema is followed:

<P><OL>
<LI>If there is a library file that defines the module in which the 
undefined predicate is trapped, this file is used.
<LI>Otherwise library files are considered in the order they appear in 
the <A NAME="idx:librarydirectory1:199"></A><A class="pred" href="consulting.html#library_directory/1">library_directory/1</A> 
predicate and within the directory alphabetically.
</OL>

<DL>
<DT class="pubdef"><A NAME="make_library_index/1"><STRONG>make_library_index</STRONG>(<VAR>+Directory</VAR>)</A></DT>
<DD class="defbody">
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.</DD>
<DT class="pubdef"><A NAME="make_library_index/2"><STRONG>make_library_index</STRONG>(<VAR>+Directory, 
+ListOfPatterns</VAR>)</A></DT>
<DD class="defbody">
Normally used in <CODE>MKINDEX.pl</CODE>, this predicate creates <CODE>INDEX.pl</CODE> 
for <VAR>Directory</VAR>, indexing all files that match one of the 
file-patterns in <VAR>ListOfPatterns</VAR>.

<P>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 <CODE>MKINDEX.pl</CODE>, including the public 
functionality of <CODE>trace/browse.pl</CODE> to the autoloadable 
predicates for the XPCE package.

<PRE class="code">
:- make_library_index('.',
                      [ '*.pl',
                        'trace/browse.pl'
                      ]).
</PRE>

</DD>
<DT class="pubdef"><A NAME="reload_library_index/0"><STRONG>reload_library_index</STRONG></A></DT>
<DD class="defbody">
Force reloading the index after modifying the set of library directories 
by changing the rules for <A NAME="idx:librarydirectory1:200"></A><A class="pred" href="consulting.html#library_directory/1">library_directory/1</A>, <A NAME="idx:filesearchpath2:201"></A><A class="pred" href="consulting.html#file_search_path/2">file_search_path/2</A>, 
adding or deleting <CODE>INDEX.pl</CODE> files. This predicate does <EM>not</EM> 
update the <CODE>INDEX.pl</CODE> files. Check <A NAME="idx:makelibraryindex12:202"></A><A class="pred" href="autoload.html#make_library_index/1">make_library_index/[1,2]</A> 
and
<A NAME="idx:make0:203"></A><A class="pred" href="consulting.html#make/0">make/0</A> 
for updating the index files.

<P>Normally, the index is reloaded automatically if a predicate cannot 
be found in the index and the set of library directories has changed. 
Using
<A NAME="idx:reloadlibraryindex0:204"></A><A class="pred" href="autoload.html#reload_library_index/0">reload_library_index/0</A> 
is necessary if directories are removed or the order of the library 
directories is changed.
</DD>
</DL>

<P></BODY></HTML>
swi-prolog-doc 5.6.59-2 / usr / share / doc / swi-prolog-doc / Manual / autoload.html
