<HTML>
<HEAD>
<!-- Created by texi2html 1.56k + clip patches and <A href="http://www.clip.dia.fi.upm.es/Software">lpdoc</A> from ciao.texi on 28 January 2007 -->
<LINK rel="stylesheet" href="ciao.css" type="text/css">
<TITLE>The Ciao Prolog System - The module system</TITLE>
</HEAD>
<BODY>
Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_13.html">previous</A>, <A HREF="ciao_15.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>.
<P><HR><P>
<H1><A NAME="SEC122" HREF="ciao_toc.html#TOC122">The module system</A></H1>
<P>
<A NAME="IDX1152"></A>
<P>
<STRONG>Author(s):</STRONG> Daniel Cabeza and the CLIP Group.
<P>
<STRONG>Version:</STRONG> 1.10#7 (2006/4/26, 19:22:13 CEST)
<P>
<STRONG>Version of last change:</STRONG> 1.9#28 (2002/11/20, 14:3:5 CET)
<P>
Modularity is a basic notion in a modern computer language. Modules allow dividing programs in several parts, which have its own independent name spaces. The module system in Ciao [CH00a], as in many other Prolog implementations, is procedure based. This means that predicate names are local to a module, but functor/atom names in data are shared.
<P>
The predicates visible in a module are the predicates defined in that module, plus the predicates imported from other modules. Only predicates exported by a module can be imported from other modules. The default module of a given predicate name is the local one if the predicate is defined locally, else the last module from which the predicate is imported, having explicit imports priority (that is, a predicate imported by an <CODE>use_module/2</CODE> declaration is always preferred above a predicate imported by an <CODE>use_module/1</CODE> declaration). To refer to a predicate from a module which is not the default for that predicate the name has to be module
<A NAME="IDX1153"></A>
<A NAME="IDX1154"></A>
qualified. A module qualified predicate name has the form <CODE>Module</CODE>:<CODE>Predicate</CODE> as in the call <CODE>debugger:debug_module(M)</CODE>. Note that this does not allow having access to predicates not imported, nor defining clauses of other modules.
<P>
All predicates defined in files with no module declaration belong to a special module called
<A NAME="IDX1155"></A>
<A NAME="IDX1156"></A>
<CODE>user</CODE>, and all are implicitly exported. This allows dividing programs in several files without being aware of the module system at all. Note that this feature is only supported for compatibility reasons, being its use discouraged. Many attractive compilation features of Ciao cannot be performed in <CODE>user</CODE> modules.
<P>
The case of multifile predicates (defined with the declaration
<A NAME="IDX1157"></A>
<CODE>multifile/1</CODE>) is also special. Multifile predicates can be defined by clauses distributed in several modules, and all modules which define a predicate as multifile can use that predicate. The name space of multifile predicates is independent, as if they belonged to special module <CODE>multifile</CODE>.
<P>
Every <CODE>user</CODE> or module file imports implicitly a number of modules called
<A NAME="IDX1158"></A>
builtin modules. They are imported before all other importations of the module, allowing thus redefining any of their predicates (with the exception of
<A NAME="IDX1159"></A>
<CODE>true/0</CODE>) by defining local versions or importing them from other modules. Importing explicitly from a builtin module, however, disables the implicit importation of the rest (this feature is used by package
<A NAME="IDX1160"></A>
<CODE>library(pure)</CODE> to define pure prolog code).
<UL>
<LI><A HREF="ciao_14.html#SEC123">Usage and interface (modules)</A>
<LI><A HREF="ciao_14.html#SEC124">Documentation on internals (modules)</A>
</UL>
<H2><A NAME="SEC123" HREF="ciao_toc.html#TOC123">Usage and interface (<CODE>modules</CODE>)</A></H2>
<div class="cartouche">
<UL>
<LI><STRONG>Library usage:</STRONG>
Modules are an intrinsic feature of Ciao, so nothing special has to be done to use them.
</UL>
</div class="cartouche">
<H2><A NAME="SEC124" HREF="ciao_toc.html#TOC124">Documentation on internals (<CODE>modules</CODE>)</A></H2>
<P>
<A NAME="IDX1161"></A>
<A NAME="IDX1162"></A>
<DL>
<DT><span class="define">DECLARATION:</span> <B>module/3:</B>
<DD><A NAME="IDX1163"></A>
<P>
<STRONG>Usage:</STRONG> :- <CODE>module(Name, Exports, Packages)</CODE>.
<UL>
<LI><EM>Description:</EM> Declares a module of name <CODE>Name</CODE> which exports the predicates in <CODE>Exports</CODE>, and uses the packages in <CODE>Packages</CODE>. <CODE>Name</CODE> must match with the name of the file where the module resides, without extension. For each source in <CODE>Packages</CODE>, a
<A NAME="IDX1164"></A>
package file is included, as if by an
<A NAME="IDX1165"></A>
<CODE>include/1</CODE> declaration. If the source is specified with a
<A NAME="IDX1166"></A>
path alias, this is the file included, if it is an atom, the library paths are searched. Package files provide functionalities by declaring imports from other modules, defining operators, new declarations, translations of code, etc.
This directive must appear the first in the file.
Also, if the compiler finds an unknown declaration as the first term in a file, the name of the declaration is regarded as a package library to be included, and the arguments of the declaration (if present) are interpreted like the arguments of
<A NAME="IDX1167"></A>
<CODE>module/3</CODE>.
<LI><EM>The following properties hold at call time:</EM>
<CODE>Name</CODE> is a module name (an atom).
(<CODE>modules:modulename/1</CODE>)
<CODE>Exports</CODE> is a list of <CODE>predname</CODE>s.
(<CODE>basic_props:list/2</CODE>)
<CODE>Packages</CODE> is a list of <CODE>sourcename</CODE>s.
(<CODE>basic_props:list/2</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX1168"></A>
<A NAME="IDX1169"></A>
<DL>
<DT><span class="define">DECLARATION:</span> <B>module/2:</B>
<DD><A NAME="IDX1170"></A>
<P>
<STRONG>Usage:</STRONG> :- <CODE>module(Name, Exports)</CODE>.
<UL>
<LI><EM>Description:</EM> Same as directive
<A NAME="IDX1171"></A>
<CODE>module/3</CODE>, with an implicit package <CODE>default</CODE>.
<LI><EM>The following properties hold at call time:</EM>
<CODE>Name</CODE> is a module name (an atom).
(<CODE>modules:modulename/1</CODE>)
<CODE>Exports</CODE> is a list of <CODE>predname</CODE>s.
(<CODE>basic_props:list/2</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX1172"></A>
<A NAME="IDX1173"></A>
<DL>
<DT><span class="define">DECLARATION:</span> <B>export/1:</B>
<DD><A NAME="IDX1174"></A>
<P>
<STRONG>Usage 1:</STRONG> :- <CODE>export(Pred)</CODE>.
<UL>
<LI><EM>Description:</EM> Adds <CODE>Pred</CODE> to the set of exported predicates.
<LI><EM>The following properties hold at call time:</EM>
<CODE>Pred</CODE> is a Name/Arity structure denoting a predicate name:
<PRE>
predname(P/A) :-
atm(P),
nnegint(A).
</PRE>
(<CODE>basic_props:predname/1</CODE>)
</UL>
<P>
<STRONG>Usage 2:</STRONG> :- <CODE>export(Exports)</CODE>.
<UL>
<LI><EM>Description:</EM> Adds <CODE>Exports</CODE> to the set of exported predicates.
<LI><EM>The following properties hold at call time:</EM>
<CODE>Exports</CODE> is a list of <CODE>predname</CODE>s.
(<CODE>basic_props:list/2</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX1175"></A>
<A NAME="IDX1176"></A>
<DL>
<DT><span class="define">DECLARATION:</span> <B>use_module/2:</B>
<DD><A NAME="IDX1177"></A>
<P>
<STRONG>Usage:</STRONG> :- <CODE>use_module(Module, Imports)</CODE>.
<UL>
<LI><EM>Description:</EM> Specifies that this code imports from the module defined in <CODE>Module</CODE> the predicates in <CODE>Imports</CODE>. The imported predicates must be exported by the other module.
<LI><EM>The following properties hold at call time:</EM>
<CODE>Module</CODE> is a source name.
(<CODE>streams_basic:sourcename/1</CODE>)
<CODE>Imports</CODE> is a list of <CODE>predname</CODE>s.
(<CODE>basic_props:list/2</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX1178"></A>
<A NAME="IDX1179"></A>
<DL>
<DT><span class="define">DECLARATION:</span> <B>use_module/1:</B>
<DD><A NAME="IDX1180"></A>
<P>
<STRONG>Usage:</STRONG> :- <CODE>use_module(Module)</CODE>.
<UL>
<LI><EM>Description:</EM> Specifies that this code imports from the module defined in <CODE>Module</CODE> all the predicates exported by it. The previous version with the explicit import list is preferred to this as it minimizes the chances to have to recompile this code if the other module changes.
<LI><EM>The following properties hold at call time:</EM>
<CODE>Module</CODE> is a source name.
(<CODE>streams_basic:sourcename/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX1181"></A>
<A NAME="IDX1182"></A>
<DL>
<DT><span class="define">DECLARATION:</span> <B>import/2:</B>
<DD><A NAME="IDX1183"></A>
<P>
<STRONG>Usage:</STRONG> :- <CODE>import(Module, Imports)</CODE>.
<UL>
<LI><EM>Description:</EM> Declares that this code imports from the module with name <CODE>Module</CODE> the predicates in <CODE>Imports</CODE>.
<STRONG>Important note:</STRONG> this declaration is intended to be used when the current module or the imported module is going to be dynamically loaded, and so the compiler does not include the code of the imported module in the current executable (if only because the compiler cannot know the location of the module file at the time of compilation). For the same reason the predicates imported are not checked to be exported by <CODE>Module</CODE>. Its use in other cases is strongly discouraged, as it disallows many compiler optimizations.
<LI><EM>The following properties hold at call time:</EM>
<CODE>Module</CODE> is a module name (an atom).
(<CODE>modules:modulename/1</CODE>)
<CODE>Imports</CODE> is a list of <CODE>predname</CODE>s.
(<CODE>basic_props:list/2</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX1184"></A>
<A NAME="IDX1185"></A>
<DL>
<DT><span class="define">DECLARATION:</span> <B>reexport/2:</B>
<DD><A NAME="IDX1186"></A>
<P>
<STRONG>Usage:</STRONG> :- <CODE>reexport(Module, Preds)</CODE>.
<UL>
<LI><EM>Description:</EM> Specifies that this code reexports from the module defined in <CODE>Module</CODE> the predicates in <CODE>Preds</CODE>. This implies that this module imports from the module defined in <CODE>Module</CODE> the predicates in <CODE>Preds</CODE>, an also that this module exports the predicates in <CODE>Preds</CODE> .
<LI><EM>The following properties hold at call time:</EM>
<CODE>Module</CODE> is a source name.
(<CODE>streams_basic:sourcename/1</CODE>)
<CODE>Preds</CODE> is a list of <CODE>predname</CODE>s.
(<CODE>basic_props:list/2</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX1187"></A>
<A NAME="IDX1188"></A>
<DL>
<DT><span class="define">DECLARATION:</span> <B>reexport/1:</B>
<DD><A NAME="IDX1189"></A>
<P>
<STRONG>Usage:</STRONG> :- <CODE>reexport(Module)</CODE>.
<UL>
<LI><EM>Description:</EM> Specifies that this code reexports from the module defined in <CODE>Module</CODE> all the predicates exported by it. This implies that this module imports from the module defined in <CODE>Module</CODE> all the predicates exported by it, an also that this module exports all such predicates .
<LI><EM>The following properties hold at call time:</EM>
<CODE>Module</CODE> is a source name.
(<CODE>streams_basic:sourcename/1</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX1190"></A>
<A NAME="IDX1191"></A>
<DL>
<DT><span class="define">DECLARATION:</span> <B>meta_predicate/1:</B>
<DD><A NAME="IDX1192"></A>
<P>
<STRONG>Usage:</STRONG> :- <CODE>meta_predicate MetaSpecs</CODE>.
<UL>
<LI><EM>Description:</EM> Specifies that the predicates in <CODE>MetaSpecs</CODE> have arguments which represent predicates and thus have to be module expanded. The directive is only mandatory for exported predicates (in modules). This directive is defined as a prefix operator in the compiler.
<LI><EM>The following properties hold at call time:</EM>
<CODE>MetaSpecs</CODE> is a sequence of <CODE>metaspec</CODE>s.
(<CODE>basic_props:sequence/2</CODE>)
</UL>
</DL>
<P>
<A NAME="IDX1193"></A>
<A NAME="IDX1194"></A>
<DL>
<DT><span class="define">REGTYPE:</span> <B>modulename/1:</B>
<DD><A NAME="IDX1195"></A>
<P>
A module name is an atom, not containing characters `:' or `$'. Also, <CODE>user</CODE> and <CODE>multifile</CODE> are reserved, as well as the module names of all builtin modules (because in an executable all modules must have distinct names).
<P>
<STRONG>Usage:</STRONG> <CODE>modulename(M)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>M</CODE> is a module name (an atom).
</UL>
</DL>
<P>
<A NAME="IDX1196"></A>
<A NAME="IDX1197"></A>
<DL>
<DT><span class="define">REGTYPE:</span> <B>metaspec/1:</B>
<DD><A NAME="IDX1198"></A>
<P>
A meta-predicate specification for a predicate is the functor of that predicate applied to atoms which represent the kind of module expansion that should be done with the arguments. Possible contents are represented as:
<DL COMPACT>
<DT><CODE>goal</CODE>
<DD>
This argument will be a term denoting a goal (either a simple or complex one) which will be called. For commpatibility reasons it can be named as <CODE>:</CODE> as well.
<DT><CODE>clause</CODE>
<DD>
This argument will be a term denoting a clause.
<DT><CODE>fact</CODE>
<DD>
This argument should be instantiated to a term denoting a fact (head-only clause).
<DT><CODE>spec</CODE>
<DD>
This argument should be instantiated to a predicate name, as Functor/Arity.
<DT><CODE>pred(<EM>N</EM>)</CODE>
<DD>
This argument should be instantiated to a predicate construct to be called by means of a <CODE>call/<EM>N</EM></CODE> predicate call (see
<A NAME="IDX1199"></A>
<CODE>call/2</CODE>).
<DT><CODE>addmodule</CODE>
<DD>
This is in fact is not a real meta-data specification. It specifies that in an argument added after this one will be passed the calling module, to allow handling more involved meta-data (e.g., lists of goals) by using conversion builtins.
<DT><CODE>?,+,-,_</CODE>
<DD>
These other values denote that this argument is not module expanded.
</DL>
<P>
<STRONG>Usage:</STRONG> <CODE>metaspec(M)</CODE>
<UL>
<LI><EM>Description:</EM> <CODE>M</CODE> is a meta-predicate specification.
</UL>
</DL>
<P><HR><P>
Go to the <A HREF="ciao_1.html">first</A>, <A HREF="ciao_13.html">previous</A>, <A HREF="ciao_15.html">next</A>, <A HREF="ciao_241.html">last</A> section, <A HREF="ciao_toc.html">table of contents</A>.
</BODY>
</HTML>
