\ignore{
\documentstyle[11pt]{report}
\textwidth 13.7cm
\textheight 21.5cm
\newcommand{\myimp}{\verb+ :- +}
\newcommand{\ignore}[1]{}
\def\definitionname{Definition}

\makeindex
\begin{document}
}
\chapter{Modules}
A module is a bundle of predicate and function definitions that are stored in one file. A module forms a name space.  Two definitions can have the same name if they reside in different modules. Because modules avoid name clashes, they are very useful for managing source files of large programs.

\section{Module and Import Declarations}
In Picat, source files must have the extension name \texttt{".pi"}.  A module is a source file that begins with a module name declaration in the form:
\begin{tabbing}
aa \= aaa \= aaa \= aaa \= aaa \= aaa \= aaa \kill
\> \texttt{module $Name$}\index{\texttt{module}}.
\end{tabbing}
where $Name$ must be the same as the main file name\index{file name}. A file that does not begin with a module declaration is assumed to belong to the default \emph{global} module\index{global module}. The following names are reserved for system modules and should not be used to name user modules: \texttt{basic}, \texttt{bp}, \texttt{cp}, \texttt{datetime}, \texttt{glb},  \texttt{io}, \texttt{math}, \texttt{mip}, \texttt{nn}, \texttt{ordset}, \texttt{os}, \texttt{planner}, \texttt{sat}, \texttt{smt}, \texttt{sys},  and \texttt{util}.

In order to use symbols that are defined in another module, users must explicitly import them with an import declaration in the form:
\begin{tabbing}
aa \= aaa \= aaa \= aaa \= aaa \= aaa \= aaa \kill
\> \texttt{import $Name_1$, $\ldots$, $Name_n$}\index{\texttt{import}}.
\end{tabbing}
where each imported $Name_i$ is a module name. For each imported module, the compiler first searches for it in the search path that is specified by the environment variable PICATPATH. If no module is found, the compiler gives an error message. Several modules are imported by default, including  \texttt{basic}, \texttt{io}, \texttt{math},  and \texttt{sys}.

The import relation is not transitive. Suppose that there are three modules: $A$, $B$, and $C$. If $A$ imports $B$ and $B$ imports $C$, then $A$ still needs to import $C$ in order to reference $C$'s symbols.

The built-in command \texttt{cl("xxx")}\index{\texttt{cl/1}} compiles the file \texttt{xxx.pi} and loads the generated code into the interpreter. The built-in command \texttt{load("xxx")} loads the bytecode file \texttt{xxx.qi}. It compiles the source file \texttt{xxx.pi} only when necessary. The \texttt{load}\index{\texttt{load/1}} command  also imports the public symbols defined in the module to the interpreter.  This allows users to use these symbols on the command line without explicitly importing the symbols. If the file \texttt{xxx.pi} imports modules, those module files will be compiled and loaded when necessary. 

A program file can contain \texttt{include} directives of the form:\index{\texttt{include} directive}
\begin{tabbing}
aa \= aaa \= aaa \= aaa \= aaa \= aaa \= aaa \kill
\> \texttt{include $Name$}.
\end{tabbing}
where $Name$ is a string indicating a file name relative to the program file. The \texttt{include} directive causes the content of the file named $Name$ to be copied verbatim to where the directive occurs. The \texttt{include} directive allows users to split a large program into several source files. Note that the included source files cannot contain module or import declarations, and no definitions can span multiple files.

\section{Binding Calls to Definitions}
The Picat system has a global symbol table\index{symbol table} for atoms, a global symbol table\index{symbol table} for structure names, and a global symbol table\index{symbol table} for modules. For each module, Picat maintains a symbol table\index{symbol table} for the public predicate and function symbols defined in the module. Private symbols that are defined in a module are compiled away, and are never stored in the symbol table\index{symbol table}. While predicate and function symbols can be local to a module, atoms and structures are always global.

The Picat module system is static, meaning that the binding of normal (or non-higher-order) calls to their definitions takes place at compile time. For each call, the compiler first searches the default modules for a definition that has the same name as the call. If no definition is found, then the compiler searches for a definition in the enclosing module. If no definition is found, the compiler searches the imported modules in the order that they were imported. If no definition is found in any of these modules, then the compiler will issue an warning\footnote{A warning is issued instead of an error.  This allows users to test incomplete programs with missing definitions.}, assuming the symbol is defined in  the global module.

It is possible for two imported modules to contain different definitions that have the same name. When multiple names match a call, the order of the imported items determines which definition is used. Picat allows users to use qualified names to explicitly select a definition. A module-qualified call is a call preceded by a module name and '.' without intervening whitespace. 

\section*{Example}
\begin{verbatim}
% qsort.pi
module qsort.

sort([]) = [].
sort([H|T]) = 
    sort([E : E in T, E =< H]) ++ [H] ++ sort([E : E in T, E > H]).

% isort.pi
module isort.

sort([]) = [].
sort([H|T]) = insert(H,sort(T)).

private
insert(X,[]) = [X].
insert(X,Ys@[Y|_]) = Zs, X =< Y => Zs = [X|Ys].
insert(X,[Y|Ys]) = [Y|insert(X,Ys)].
\end{verbatim}
The module \texttt{qsort.pi} defines a function named \texttt{sort} using quick sort, and the module \texttt{isort} defines a function of the same name using insertion sort. In the following session, both modules are used.
\begin{verbatim}
picat> load("qsort")
picat> load("isort")
picat> L = sort([2,1,3])
L = [1,2,3]
picat> L = qsort.sort([2,1,3])
L = [1,2,3]
picat> L = isort.sort([2,1,3])
L = [1,2,3]
\end{verbatim}
As \texttt{sort} is also defined in the \texttt{basic} module, which is preloaded, that function is used for the command \texttt{L = sort([2,1,3])}.

Module names are just atoms. Consequently, it is possible to bind a variable to a module name. Nevertheless, in a module-qualified call $M.C$, the module name can never be a variable. Recall that the dot notation is also used to access attributes and to call predicates and functions. The notation $M.C$ is treated as a call or an attribute if $M$ is not an atom.

Suppose that users want to define a function named \texttt{generic\_sort(M,L)} that sorts list \texttt{L} using the \texttt{sort} function defined in module \texttt{M}. Users cannot just call \texttt{M.sort(L)}, since \texttt{M} is a variable. Users can, however, select a function based on the value held in \texttt{M} by using function facts\index{function fact} as follows:
\begin{verbatim}
generic_sort(qsort,L) = qsort.sort(L).
generic_sort(isort,L) = isort.sort(L).
\end{verbatim}

\section{Binding Higher-Order Calls}\index{higher-order call}
Because Picat forbids variable module qualifiers and terms in dot notations, it is impossible to create module-qualified higher-order terms. For a higher-order call, if the compiler knows the name of the higher-order term, as in \texttt{findall(X,$member(X,L)$)}\index{\texttt{findall}}\index{\texttt{member/2}}, then it searches for a definition for the name, just like it does for a normal call. However, if the name is unknown, as in \texttt{apply(F,X,Y)}\index{\texttt{apply}}, then the compiler generates code to search for a definition. For a higher-order call to \texttt{call/N} or \texttt{apply/N}, the runtime system searches modules in the following order:
\begin{enumerate}
\item The implicitly imported built-in modules \texttt{basic}, \texttt{io}, \texttt{math},  and \texttt{sys}.
\item The current list of loaded modules that is returned by the built-in function call \texttt{loaded\_modules()}, excluding the pre-imported built-in modules.
\item The global module.
\end{enumerate}
As private symbols are compiled away at compile time, higher-order terms can never reference private symbols. Due to the overhead of runtime search, the use of higher-order calls is discouraged.

\ignore{
\section{Accessing Attributes of Modules}
A function with no argument that is defined with one function fact\index{function fact} in a module is called an \emph{attribute} of the module. For example, the \texttt{math} module contains a function named \texttt{pi}\index{\texttt{pi}}, where
\begin{verbatim}
pi = 3.14159.    
\end{verbatim}
The advantage of treating no-arg functions as attribute-value pairs is that users can use the dot notation to access values. For example, users can use \texttt{math.pi}\index{\texttt{pi}} to retrieve the value that is associated with \texttt{pi}\index{\texttt{pi}} in the module \texttt{math}. 

Users can use no-argument functions in order to simulate C-style enum types. 

\section*{Example}
\begin{verbatim}
module color.

black = 0.
red = 1.
blue = 2.
green = 3.
white = 4.
cyan = 5.
yellow = 6.
magenta = 7.
\end{verbatim}
For a color, say \texttt{red}, users can retrieve the integer that is associated with it by using \texttt{color.red}. Note that a dot notation is an expression, but is not a valid term.  Therefore, a dot notation cannot occur in a head pattern. 

}
\section{Library Modules}
Picat comes with a library of standard modules, described in separate chapters. The function \texttt{sys.loaded\_modules()}\index{\texttt{loaded\_modules/0}} returns a list of modules that are currently in the system.
\ignore{
\end{document}
}
