Getting Started

## 7.2 Getting Started

- Creating a Module
- Exporting
- Importing
- Definitions, Visibility and Accessibility

### 7.2.1 Creating a Module

You create a module simply by starting your program code with a module/1 directive. This should usually be placed at the beginning of the source file and looks like

>     :- module(mymodule).

As a rule, the module name should be chosen to be the same as the file's base name (the filename without directory/folder and suffix/extension part). E.g. the module `mymodule` might be contained in a file `mymodule.ecl`.
Anything you define in your module is by default local to that module.

### 7.2.2 Exporting

A definition is made available to the outside world by exporting it. All the exports of a module together form the module's interface. Exporting is done with the export/1 directive, which can take different forms depending on the kind of the exported item.
Predicates are exported as follows:

>     :- export p/2.

>     p(X,Y) :-
>             ...

Structures are exported by defining them with an export/1 instead of a local/1 directive, e.g.

>     :- export struct(book(author,title,publisher)).

And the same holds for operators and other syntax settings:

>     :- export op(500, xfx, before).
>     :- export chtab(0'$, lower_case).
>     :- export syntax_option(no_array_subscripts).
>     :- export macro(pretty/1, tr_pretty/2, []).

All these declarations are valid locally in the module where they appear and in every module that imports them.
Initialization goals are exported as follows:

>     :- export initialization(writeln("I have been imported")).

Unlike the other declarations above, an exported initialization/1 directive is not executed locally in they module where it appears, but only in the context of the module where it gets imported1.

### 7.2.3 Importing

In order to use a definition that has been exported elsewhere, it has to be imported. Often it is desirable to import another module's interface as a whole, i.e. everything it exports. This is achieved by an import/1 directive of the form

>     :- import amodule.

If the module is in a file and has to be compiled first, then use_module/1 can be used, which is a combination of ensure_loaded/1 (see chapter 6) and import/1:

>     :- use_module("/home/util/amodule").

If the module is a library in one of ECLiPSe's library directories, then it can be loaded and imported by

>     :- use_module(library(hash)).

or simply using lib/1 as in

>     :- lib(hash).

It is also possible to import only a part of another module's interface, using an import-from directive

>     :- import p/2 from amodule.

Note that this is the only form of import that can refer to a module that has not yet been loaded, and therefore allows a restricted form of circularity in the import structure.

### 7.2.4 Definitions, Visibility and Accessibility

For a given predicate name and arity the following rules hold:

- Every module can contain at most one definition
  - this definition may be local or exported
- In every module, at most one definition is visible
  - if there is a definition in the module itself, this is also the visible one in the module
  - otherwise, if there is an (unambiguous) import or reexport, this is the visible one
  - otherwise no definition is visible
- All exported definitions are accessible everywhere
  - this might require explicit module qualification (see 7.3.2)