1% BEGIN LICENSE BLOCK 2% Version: CMPL 1.1 3% 4% The contents of this file are subject to the Cisco-style Mozilla Public 5% License Version 1.1 (the "License"); you may not use this file except 6% in compliance with the License. You may obtain a copy of the License 7% at www.eclipse-clp.org/license. 8% 9% Software distributed under the License is distributed on an "AS IS" 10% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 11% the License for the specific language governing rights and limitations 12% under the License. 13% 14% The Original Code is The ECLiPSe Constraint Logic Programming System. 15% The Initial Developer of the Original Code is Cisco Systems, Inc. 16% Portions created by the Initial Developer are 17% Copyright (C) 2006 Cisco Systems, Inc. All Rights Reserved. 18% 19% Contributor(s): 20% 21% END LICENSE BLOCK 22%---------------------------------------------------------------------- 23\chapter{The Module System}% 24\label{modules}% 25\label{chapmodules}% 26\index{modules} 27%HEVEA\cutdef[1]{section} 28%---------------------------------------------------------------------- 29 30%---------------------------------------------------------------------- 31\section{Basics} 32\subsection{Purpose of Modules} 33%---------------------------------------------------------------------- 34 35The purpose of the module system is to provide a way to package 36a piece of code in such a way that 37\begin{itemize} 38\item internals are hidden; 39\item it has a clearly defined interface; 40\item naming conflicts are avoided. 41\end{itemize} 42In particular, this helps with 43\begin{itemize} 44\item Structuring of large applications: 45 Modules should be used to break application programs into 46 natural components and to define the interfaces between them. 47\item Provision of libraries: 48 All {\eclipse} libraries are modules. Their interfaces are 49 defined in terms of what the module makes visible to the world. 50\item Different implementations of the same predicate: 51 In constraint programming it is quite common to have different 52 implementations of a constraint, which all have the same declarative 53 meaning but different operational behaviour (e.g., different amount of 54 propagation, using different algorithms, exhibiting different 55 performance characteristics). The module system supports that by 56 allowing users to specify easily which version(s) of a predicate should 57 be used in a particular context. 58\end{itemize} 59 60 61%---------------------------------------------------------------------- 62\subsection{What is under Visibility Control?} 63%---------------------------------------------------------------------- 64 65The {\eclipse} module system governs the visibility of the following 66entities: 67\begin{quote} 68\begin{description} 69\item[Predicate names] 70 Predicates can always be used in the module where they are defined 71 and optionally in other modules when they are made available. 72\item[Structure names\index{structure}] 73 Structure declarations can be valid only locally within a module, or 74 shared between several modules. 75\item[Syntax settings\index{syntax}] 76 These include operator declarations (see 77 \bipref{op/3}{../bips/kernel/syntax/op-3.html}), 78 syntax options and 79 character classes. 80 This means in particular that different modules can use different 81 language dialects (e.g., {\eclipse} vs.\ ISO-Prolog). 82\item[Container names\index{container}] 83 These include the names of record keys, non-logical variables and 84 references. 85 They are always local to the module where they are declared. 86\item[Initialization and finalization goals] 87 Modules can have initialization and finalization goals attached, 88 see section \ref{initfini}. 89\end{description} 90\end{quote} 91 92Note that every definition (predicate, structure etc.) is in some module, 93\index{definition} 94there is no space outside the modules. When you don't explicitly 95specify a module, you inherit the module from the context in which 96you do an operation. When you are using an interactive {\eclipse} 97toplevel, a prompt will tell you in which module your input is 98read and interpreted. 99 100%---------------------------------------------------------------------- 101\subsection{What Modules are There?} 102%---------------------------------------------------------------------- 103 104The module system is flat, i.e., no module is part of another module, 105and module names must be unique. There are 106\begin{itemize} 107 \item a few basic modules that are part of the {\eclipse} 108 \Index{runtime system} and are always there. The most important one is 109 called \notationidx{eclipse_language} and is by default imported 110 into all other modules. 111 \item the library modules: every library consists of at least one 112 \index{libraries} 113 module. By convention, that module name is the library name 114 and same as the base part of the library file name. 115 \item the application-defined modules: these are created by the 116 application programmer. 117 \item in an interactive {\eclipse} toplevel there is one module 118 \index{toplevel module}\index{module!toplevel} 119 in which queries entered by the user are read and executed. 120 That module name is displayed in a prompt. 121\end{itemize} 122 123 124%---------------------------------------------------------------------- 125\section{Getting Started} 126\subsection{Creating a Module} 127%---------------------------------------------------------------------- 128 129You create a module simply by starting your program code with a 130\bipref{module/1}{../bips/kernel/modules/module-1.html} 131directive. This should usually be placed at the beginning of the source file 132and looks like 133\begin{quote} 134\begin{verbatim} 135:- module(mymodule). 136\end{verbatim} 137\end{quote} 138As a rule, the module name should be chosen to be the same as the 139file's base name (the file name without directory/folder and 140suffix/extension part). For example, the module \notation{mymodule} might be 141contained in a file \notation{mymodule.ecl}. 142 143Anything you define in your module is by default \defnotion{local} to that 144module. 145 146 147%---------------------------------------------------------------------- 148\subsection{Exporting}\index{exporting} 149%---------------------------------------------------------------------- 150 151A definition is made available to the outside world by \defnotion{exporting} it. 152All the exports of a module together form the module's \defnotion{interface}. 153Exporting is done with the 154\bipref{export/1}{../bips/kernel/modules/export-1.html} 155directive, which can take 156different forms depending on the kind of the exported item. 157 158Predicates are exported as follows: 159\begin{quote} 160\begin{verbatim} 161:- export p/2. 162 163p(X,Y) :- 164 ... 165\end{verbatim} 166\end{quote} 167 168Structures are exported by defining them with an 169\bipref{export/1}{../bips/kernel/modules/export-1.html} 170instead of a 171\bipref{local/1}{../bips/kernel/modules/local-1.html} 172directive, e.g., 173\begin{quote} 174\begin{verbatim} 175:- export struct(book(author,title,publisher)). 176\end{verbatim} 177\end{quote} 178 179And the same holds for operators and other syntax settings: 180\begin{quote} 181\begin{verbatim} 182:- export op(500, xfx, before). 183:- export chtab(0'$, lower_case). 184:- export syntax_option(no_array_subscripts). 185:- export macro(pretty/1, tr_pretty/2, []). 186\end{verbatim} 187\end{quote} 188All these declarations are valid locally in the module where they appear 189\emph{and} in every module that imports them. 190 191Initialization goals are exported as follows: 192\begin{quote} 193\begin{verbatim} 194:- export initialization(writeln("I have been imported")). 195\end{verbatim} 196\end{quote} 197Unlike the other declarations above, an exported 198\bipref{initialization/1}{../bips/kernel/modules/export-1.html} directive is 199\emph{not} executed locally in 200they module where it appears, but \emph{only} in the context of the 201module where it gets imported.\footnote{% 202 For local initialization use 203 \notation{:- local initialization(\pattern{...}).}} 204 205 206%---------------------------------------------------------------------- 207\subsection{Importing}\index{importing} 208%---------------------------------------------------------------------- 209 210In order to use a definition that has been exported elsewhere, it has 211to be \defnotion{imported}. Often it is desirable to import another module's 212interface as a whole, i.e., everything it exports. 213This is achieved by an 214\bipref{import/1}{../bips/kernel/modules/import-1.html} 215directive of the form 216\begin{quote} 217\begin{verbatim} 218:- import amodule. 219\end{verbatim} 220\end{quote} 221If the module is in a file and has to be compiled first, then 222\bipref{use_module/1}{../bips/kernel/modules/use_module-1.html} 223can be used, which is a combination of 224\bipref{ensure_loaded/1}{../bips/kernel/compiler/ensure_loaded-1.html} 225(see chapter \ref{chapcompiler}) and 226\bipref{import/1}{../bips/kernel/modules/import-1.html}: 227\begin{quote} 228\begin{verbatim} 229:- use_module("/home/util/amodule"). 230\end{verbatim} 231\end{quote} 232If the module is a library in one of {\eclipse}'s library directories, 233then it can be loaded and imported by 234\begin{quote} 235\begin{verbatim} 236:- use_module(library(hash)). 237\end{verbatim} 238\end{quote} 239or simply using 240\bipref{lib/1}{../bips/kernel/compiler/lib-1.html} as in 241\begin{quote} 242\begin{verbatim} 243:- lib(hash). 244\end{verbatim} 245\end{quote} 246 247It is also possible to import only a part of another module's 248interface, using an 249\biptxtref{import-from directive}{import/1}{../bips/kernel/modules/import-1.html} 250\begin{quote} 251\begin{verbatim} 252:- import p/2 from amodule. 253\end{verbatim} 254\end{quote} 255Note that this is the only form of import that can refer to a module 256that has not yet been loaded, and therefore allows a restricted form 257of circularity in the import structure. 258 259 260%---------------------------------------------------------------------- 261\subsection{Definitions, Visibility and Accessibility} 262%---------------------------------------------------------------------- 263 264For a given predicate name and arity the following rules hold: 265 266\begin{itemize} 267\item Every module can contain at most one \defnotion{definition}: 268 \begin{itemize} 269 \item this definition may be local or exported. 270 \end{itemize} 271\item In every module, at most one definition is 272 \defnotionni{visible}:\index{visible definition}\index{definition!visible} 273 \begin{itemize} 274 \item if there is a definition in the module itself, 275 this is also the visible one in the module; 276 \item otherwise, if there is an (unambiguous) import or reexport, 277 this is the visible one; 278 \item otherwise no definition is visible. 279 \end{itemize} 280\item All exported definitions are 281 \defnotionni{accessible}% 282\index{accessible definition}\index{definition!accessible} 283 everywhere: 284 \begin{itemize} 285 \item this might require explicit module qualification 286 (see~\ref{qualifiedaccess}). 287 \end{itemize} 288\end{itemize} 289 290 291%---------------------------------------------------------------------- 292\section{Advanced Topics} 293%---------------------------------------------------------------------- 294%---------------------------------------------------------------------- 295\subsection{Solving Name Conflicts} 296%---------------------------------------------------------------------- 297 298Name conflicts occur in two flavours: 299\index{name conflict} 300\begin{quote} 301\begin{description} 302\item[Import/Import conflict:] 303 this is the case when two or more imported modules provide a 304 predicate of the same name. 305\item[Import/Local conflict:] 306 this is the case when a local (or exported) predicate has the 307 same name as a predicate provided from an imported module. 308\end{description} 309\end{quote} 310Conflicts of the first type are accepted silently by the system as 311long as there is no reference to the conflict predicate. Only when an attempt 312\index{ambiguity warning} 313is made to access the conflict predicate is an error raised. 314The conflict can be resolved by explicitly importing one of the versions, e.g., 315\begin{quote} 316\begin{verbatim} 317:- lib(ria). % exports #>= / 2 318:- lib(eplex). % exports #>= / 2 319:- import (#>=)/2 from ria. % resolves the conflict 320\end{verbatim} 321\end{quote} 322Alternatively, the conflict can remain unresolved and qualified access can 323be used whenever the predicates are referred to (see~\ref{qualifiedaccess}). 324 325Conflicts of the second type give rise to an error or warning message 326\index{redefinition error} 327\index{redefinition warning} 328when the compiler encounters the local (re)definition. To avoid that, 329an explicit 330\bipref{local/1}{../bips/kernel/modules/local-1.html} 331declaration has to be used: 332\begin{quote} 333\begin{verbatim} 334:- local write/1. 335write(X) :- % my own version of write/1 336 ... 337\end{verbatim} 338\end{quote} 339Note that the \bipref{local/1}{../bips/kernel/modules/local-1.html}-declaration 340must occur textually before any use of the predicate inside the module. 341 342 343%---------------------------------------------------------------------- 344\subsection{Qualified Access via :/2\label{qualifiedaccess}}% 345\index{qualified acccess} 346%---------------------------------------------------------------------- 347 348Normally, it is convenient to import predicates which are needed. 349By importing, they become 350visible\index{visible definition}\index{definition!visible} 351and can be used within 352the module in the same way as local definitions. 353However, sometimes it is preferable to explicitly specify from 354which module a definition is meant to be taken. This is the case for 355example when multiple versions of the predicate are needed, 356or when the presence of a local definition makes it impossible 357to import a predicate of the same name from elsewhere. 358A call with explicit module qualification is done using 359\txtbipref{:/2}{(:)/2}{../bips/kernel/control/N-2.html} 360and looks like this: 361\begin{quote} 362\begin{verbatim} 363lists:print_list([1,2,3]) 364\end{verbatim} 365\end{quote} 366Here, the module where the definition of \predspec{print_list/1} is looked up 367(the \defnotion{lookup module}) is explicitly specified. To call 368\predspec{print_list/1} 369like this, it is not necessary to make \predspec{print_list/1} visible. 370The only requirement is that it is exported (or reexported) from 371the module \notation{lists}. 372 373Note that, if the called predicate is in operator notation, it will 374often be necessary to use brackets, e.g., in 375\begin{quote} 376\begin{verbatim} 377..., ria:(X #>= Y), ... 378\end{verbatim} 379\end{quote} 380 381The \txtbipref{:/2}{(:)/2}{../bips/kernel/control/N-2.html} primitive can be used to 382resolve import conflicts, 383i.e., the case where the same name is exported from more than one 384module and both are needed. In this case, none of the conflicting 385predicates is imported - an attempt to call the unqualified predicate 386raises an error. 387The solution is to qualify every reference with the module name: 388\begin{quote} 389\begin{verbatim} 390:- lib(ria). % exports #>= / 2 391:- lib(eplex). % exports #>= / 2 392 393..., ria:(X #>= Y), ... 394..., eplex:(X #>= Y), ... 395\end{verbatim} 396\end{quote} 397 398Another case is the situation that a module wants to define a 399predicate of a given name but at the same time use a predicate 400of the same name from another module. It is not possible to 401import the predicate because of the name conflict with the local 402definition. Explicit qualification must be used instead: 403\begin{quote} 404\begin{verbatim} 405:- lib(lists). 406 407print_list(List) :- 408 writeln("This is the list"), 409 lists:print_list(List). 410\end{verbatim} 411\end{quote} 412 413 414A more unusual feature, which is however very appropriate for 415constraint programming, is the possibility to call several versions 416of the same predicate by specifying several lookup modules: 417\begin{quote} 418\begin{verbatim} 419..., [ria,eplex]:(X #>= Y), ... 420\end{verbatim} 421\end{quote} 422which has exactly the same meaning as 423\begin{quote} 424\begin{verbatim} 425..., ria:(X #>= Y), eplex:(X #>= Y), ... 426\end{verbatim} 427\end{quote} 428Note that the modules do not have to be known at compile time, i.e., it 429is allowed to write code like 430\begin{quote} 431\begin{verbatim} 432after(X, Y, Solver) :- 433 Solver:(X #>= Y). 434\end{verbatim} 435\end{quote} 436However, this is likely to be less efficient because it prevents 437compile-time optimizations. 438 439 440%---------------------------------------------------------------------- 441\subsection{Reexport - Making Modules from Modules} 442%---------------------------------------------------------------------- 443 444To allow more flexibility in the design of module interfaces, and to 445avoid duplication of definitions, it is possible to re-export definitions. 446A reexport is an import combined with an export. 447That means that a reexported definition becomes visible inside the 448reexporting module and is at the same time exported again. 449The only difference between exported and reexported definitions is that 450reexported predicates retain their original definition module. 451 452There are 3 forms of the 453\bipref{reexport/1}{../bips/kernel/modules/reexport-1.html} 454directive. To reexport the complete 455module interface of another module, use 456\begin{quote} 457\begin{verbatim} 458:- reexport amodule. 459\end{verbatim} 460\end{quote} 461To reexport only an explicitly enumerated selection, use 462\begin{quote} 463\begin{verbatim} 464:- reexport p/1,q/2 from amodule. 465\end{verbatim} 466\end{quote} 467To reexport everything except some explicitly enumerated items, use 468\begin{quote} 469\begin{verbatim} 470:- reexport amodule except p/2,q/3. 471\end{verbatim} 472\end{quote} 473 474These facilities make it possible to extend, modify, restrict or 475combine modules into new modules, as illustrated in figure~\ref{reexport}. 476 477\begin{figure}[hbt] 478\begin{center} 479\includegraphics{reexport.eps} 480\end{center} 481\caption{Making modules from modules with reexport} 482\label{reexport} 483\end{figure} 484 485 486%---------------------------------------------------------------------- 487\subsection{Modules and Source Files}\index{source files} 488%---------------------------------------------------------------------- 489 490When a source file contains no module directives, it becomes part of 491the module from which its compilation was invoked. This makes it 492possible to write small programs without caring about modules. 493However, serious applications should be structured into modules. 494 495Often it is the most appropriate to have one file per module and to 496have the file name match the module name. 497 498It is however possible to have several modules in one file, e.g., a 499main module and one or more auxiliary modules - in that 500case the name of the main module should match the file name. 501Every module-directive in the file marks the end of the previous 502module and the start of the next one. 503 504It is also possible to spread the contents of a module over several 505files. In this case, there should be a main file whose file name 506matches the module name, and the other files should be referenced 507from the main file using the 508\bipref{include/1}{../bips/kernel/directives/include-1.html} directive, e.g., 509\begin{quote} 510\begin{verbatim} 511:- module(bigmodule). 512:- include(part1). 513:- include(part2). 514\end{verbatim} 515\end{quote} 516 517 518 519%---------------------------------------------------------------------- 520\subsection{Tools and Caller Modules} 521%---------------------------------------------------------------------- 522 523\subsubsection{Tools\label{tools}}\index{Tools}\index{procedure!tool} 524 525There are predicates in a modular system that must be able to determine from 526which 527module they were called (since this may be different from the module 528in which they were defined). 529The most common case is where a predicate is a \Index{meta-predicate}, 530i.e., a predicate that has another goal or predicate name as an argument. 531Other cases are I/O predicates---they must be executed in a 532certain module context in order to obey the correct syntax of this module. 533In {\eclipse}, predicates that must be able to determine their caller module 534are called \defnotion{tool} predicates.\footnote{ 535 Many Prolog systems call them \about{meta-predicates}.} 536 537Tool predicates must be declared. As a consequence, the system will 538automatically add a \defnotion{caller module} argument whenever such a tool 539predicate is called. 540 541Consider for example a predicate that calls another predicate twice. 542\indextt{twice/1} 543The naive version of this predicate looks like 544\begin{quote} 545\begin{verbatim} 546twice(Goal) :- 547 call(Goal), 548 call(Goal). 549\end{verbatim} 550\end{quote} 551As long as no modules are involved, this works fine. 552Now consider the situation where the definition of \predspec{twice/1} and a 553call of \predspec{twice/1} are in two different modules: 554\begin{quote} 555\begin{verbatim} 556:- module(stuff). 557:- export twice/1. 558twice(Goal) :- 559 call(Goal), 560 call(Goal). 561 562:- module(main). 563:- import stuff. 564 565top :- twice(hello). 566 567hello :- writeln(hi). 568\end{verbatim} 569\end{quote} 570This will not work because \predspec{hello/0} is only visible in module main 571and an attempt to call it from within \predspec{twice/1} in module stuff will 572raise an error. The solution is to declare \predspec{twice/1} as a tool and 573change the code as follows: 574\begin{quote} 575\begin{verbatim} 576:- module(stuff). 577:- export twice/1. 578:- tool(twice/1, twice/2). 579twice(Goal, Module) :- 580 call(Goal)@Module, 581 call(Goal)@Module. 582\end{verbatim} 583\end{quote} 584What happens now is that the call to \predspec{twice/1} in module main 585\begin{quote} 586\begin{verbatim} 587..., twice(hello), ... 588\end{verbatim} 589\end{quote} 590is effectively replaced by the system with a call to \predspec{twice/2} where 591the additional argument is the module in which the call occurs: 592\begin{quote} 593\begin{verbatim} 594..., twice(hello, main), ... 595\end{verbatim} 596\end{quote} 597This caller module is then used by \predspec{twice/2} to execute 598\begin{quote} 599\begin{verbatim} 600..., call(hello)@main, ... 601\end{verbatim} 602\end{quote} 603The 604\biptxtrefni{call(Goal)@Module}{(@)/2}{../bips/kernel/control/A-2.html}% 605\index{\atsym/2@\notation{"@/2}} construct means that the call is supposed 606to happen \emph{in the context} of module main. 607 608 609The debugger trace shows what happens: 610\begin{quote} 611\begin{verbatim} 612[main 5]: top. 613 (1) 1 CALL top 614 (2) 2 CALL twice(hello) 615 (3) 3 CALL twice(hello, main) 616 (4) 4 CALL call(hello) @ main 617 (5) 5 CALL call(hello) 618 (6) 6 CALL hello 619S (7) 7 CALL writeln(hi) 620hi 621S (7) 7 EXIT writeln(hi) 622 (6) 6 EXIT hello 623 ... 624\end{verbatim} 625\end{quote} 626 627One complication that can arise when you use tools is that the compiler 628must know that a predicate is a tool in order to properly compile 629a call to the tool. 630If the call occurs textually before the tool 631declaration, this will therefore give rise to an 632\emph{inconsistent tool redefinition} error. 633The 634\bipref{tool/2}{../bips/kernel/modules/tool-2.html} 635declaration must therefore occur before any call to the tool. 636 637 638\subsubsection{System Tools} 639\index{tool!system}\index{system tool} 640Many of the system built-in predicates are in fact tools, e.g., 641\bipref{read/1}{../bips/kernel/ioterm/read-1.html}, 642\bipref{write/1}{../bips/kernel/ioterm/write-1.html}, 643\bipref{record/2}{../bips/kernel/record/record-2.html}, 644\bipref{compile/1}{../bips/kernel/compiler/compile-1.html}, etc. 645All predicates which handle modular items must be tools 646so that they know from which module they have been called. 647In case that the built-in predicate has to be executed in 648a different module (this is very often the case inside 649user tool predicates), the 650\txtbipref{@/2}{(@)/2}{../bips/kernel/control/A-2.html}% 651\index{\atsym/2@\notation{"@/2}} 652construct must be used, e.g., 653\begin{quote} 654\begin{verbatim} 655current_predicate(P) @ SomeModule 656\end{verbatim} 657\end{quote} 658 659 660%---------------------------------------------------------------------- 661\subsection{Lookup Module vs Caller Module} 662\index{lookup module}\index{module!lookup} 663\index{caller module}\index{module!caller} 664%---------------------------------------------------------------------- 665 666The following table summarises the different call patterns with and 667without module specifications. 668There are only two basic rules to remember: 669\begin{quote} 670\begin{itemize} 671\item \txtbipref{:/2}{(:)/2}{../bips/kernel/control/N-2.html} 672 specifies the lookup module (to find the definition) 673\item \biptxtrefni{@/2}{(@)/2}{../bips/kernel/control/A-2.html}% 674% need a separate index entry because latex evaluates \atsym too early 675% inside \bipref 676\index{\atsym/2@\notation{"@/2}} 677 specifies the caller module (to know the context) 678\end{itemize} 679\end{quote} 680 681\begin{center} 682\begin{tabular}{|p{5cm}|p{4cm}|p{4cm}|} 683\hline 684Call inside module (m) 685 & Module where definition of \predspec{twice/1} is looked up 686 & Caller module argument added to \predspec{twice/1} \\ 687\hline 688..., twice(X), ... & m & m \\ 689..., lm : twice(X), ... & lm & m \\ 690..., twice(X) @ cm, ... & m & cm \\ 691..., lm : twice(X) @ cm, ... & lm & cm \\ 692..., call(twice(X)) @ cm, ... & cm & cm \\ 693\hline 694\end{tabular} 695\end{center} 696 697 698%---------------------------------------------------------------------- 699\subsection{The Module Interface} 700%---------------------------------------------------------------------- 701The primitive 702\bipref{current_module/1}{../bips/kernel/modules/current_module-1.html} 703can be used to check for the existence of a module, or to enumerate 704all currently defined modules. 705 706Further details about existing modules can be retrieved using 707\index{properties!module}\index{module properties} 708\bipref{get_module_info/3}{../bips/kernel/modules/get_module_info-3.html}, 709in particular information about the module's interface, what other 710modules it uses and whether it is locked (see~\ref{locking}). 711 712 713%---------------------------------------------------------------------- 714\subsection{Module-related Predicate Properties} 715%---------------------------------------------------------------------- 716Information about a predicate's properties can be retrieved using the 717\index{properties!predicate}\index{predicate properties} 718\bipref{get_flag/3}{../bips/kernel/compiler/get_flag-3.html} primitive 719or printed using \bipref{pred/1}{../bips/kernel/env/pred-1.html}. 720The module-related predicate properties are: 721\begin{quote} 722\begin{description} 723\item[defined] 724 (\notation{on}/\notation{off}) 725 indicates whether code for the predicate has already 726 been compiled. If not, only a declaration was encountered. 727\item[definition_module] 728 (an atom) the module where the predicate is defined. 729\item[visibility] 730(\notation{local}/\notation{exported}/\notation{reexported}/\notation{imported}) 731 indicates the visibility 732 of the predicate in the caller module. 733\item[tool] 734 (\notation{on}/\notation{off}) indicates whether the predicate has been 735 declared a tool. 736\end{description} 737\end{quote} 738For tool predicates, 739\bipref{tool_body/3}{../bips/kernel/modules/tool_body-3.html} 740can be used to retrieve the predicate it maps to when the module 741argument is added. 742 743To get information about a predicate visible in a different module, 744use for instance 745\begin{quote} 746\begin{verbatim} 747get_flag(p/3, visibility, V) @ othermodule 748\end{verbatim} 749\end{quote} 750 751%---------------------------------------------------------------------- 752\section{Less Common Topics} 753%---------------------------------------------------------------------- 754 755%---------------------------------------------------------------------- 756\subsection{Modules That Use Other Languages} 757%---------------------------------------------------------------------- 758 759Modules created with \bipref{module/1}{../bips/kernel/modules/module-1.html} 760automatically import the module 761\notationidx{eclipse_language}\index{language}, which provides the standard 762set of {\eclipse} built-in predicates. 763To create a module that uses a different language dialect, use 764\bipref{module/3}{../bips/kernel/modules/module-3.html}. 765For instance 766\begin{quote} 767\begin{verbatim} 768:- module(mystdcode, [], iso). 769\end{verbatim} 770\end{quote} 771creates a module in which you can use ISO Standard Prolog,\footnote{% 772 To the extent implemented by {\eclipse}'s compatibility library.} 773but not all of {\eclipse}'s usual language features. 774Note that the third argument (here \notation{iso}) simply 775specifies a library which implements the desired language, 776so new languages can be added easily. 777 778 779%---------------------------------------------------------------------- 780\subsection{Creating and Erasing Modules at Runtime} 781%---------------------------------------------------------------------- 782\begin{sloppypar} 783A module can also be created explicitly by a running program with 784\bipref{create_module/1}{../bips/kernel/modules/create_module-1.html} or 785\bipref{create_module/3}{../bips/kernel/modules/create_module-3.html} 786and erased with 787\bipref{erase_module/1}{../bips/kernel/modules/erase_module-1.html}. 788The latter should be used with care, erasing a module while a 789predicate defined in that module is being executed can provoke 790unpredictable results. The same holds for trying to erase essential 791system modules. 792\end{sloppypar} 793 794 795%---------------------------------------------------------------------- 796\subsection{Initialization and Finalization\label{initfini}} 797\index{initialization} 798\index{finalization} 799%---------------------------------------------------------------------- 800Sometimes modules have global state which must be initialised 801or finalised. For this purpose, modules can have 802\begin{description} 803\item[Local Initialization Goals:] 804these are specified as 805\begin{quote} 806\begin{verbatim} 807:- local initialization(Goal). 808\end{verbatim} 809\end{quote} 810and are executed just after the module containing them has been loaded. 811\item[Exported Initialization Goals:] 812these are specified as 813\begin{quote} 814\begin{verbatim} 815:- export initialization(Goal). 816\end{verbatim} 817\end{quote} 818and are executed whenever the module containing the declaration gets 819imported into another module. The call will happen in the context of 820the importing module. 821\item[Finalization Goals:] 822these are specified as 823\begin{quote} 824\begin{verbatim} 825:- local finalization(Goal). 826\end{verbatim} 827\end{quote} 828and are executed just before the module containing them gets erased. 829Modules can get erased either explicitly through 830\bipref{erase_module/1}{../bips/kernel/modules/erase_module-1.html} 831or implicitly when the module is re-compiled, or when the {\eclipse} 832session is exited. Finalization goals should not do any I/O because 833in the case of an embedded ECLiPSe, I/O may no longer be available at 834finalization time. 835 836\end{description} 837 838%---------------------------------------------------------------------- 839\subsection{Locking Modules\label{locking}} 840\index{locking} 841%---------------------------------------------------------------------- 842By default, {\eclipse} does not strictly enforce the hiding of 843module internals. This facilitates program development, as it allows the user 844to inspect and trace without being too concerned about module 845boundaries. For example, you can set a spy point on a local predicate 846\predspec{p/3} 847in module \about{othermod} by calling: 848\begin{quote} 849\begin{verbatim} 850:- spy(p/3)@othermod. 851\end{verbatim} 852\end{quote} 853Once a module implementation is stable and there is a need for privacy, 854it is possible to \emph{lock} a module. Locking makes it impossible 855to access internal, local items from outside the module. Of course, 856the module can still be used though its interface. 857The built-in predicates related to locking are 858\bipref{lock/0}{../bips/kernel/modules/lock-0.html} which provides 859a definitive lock, 860\bipref{lock_pass/1}{../bips/kernel/modules/lock_pass-1.html} 861which allows subsequent unlocking using a password ( 862\bipref{unlock/2}{../bips/kernel/modules/unlock-2.html}), 863and 864\bipref{get_module_info/3}{../bips/kernel/modules/get_module_info-3.html} 865which allows to check whether a module is locked. 866\bipref{lock/0}{../bips/kernel/modules/lock-0.html} and 867\bipref{lock_pass/1}{../bips/kernel/modules/lock_pass-1.html} are 868usually used as a directive in the source file of the module to be locked. 869 870%HEVEA\cutend 871