[ Modules | Reference Manual | Alphabetic Index ]

local +SpecList

Declare all items specified by SpecList as local to the caller module.
SpecList
One or a comma-separated sequence of valid local specifications

Description

This declaration is used to declare the visibility of procedures and other items as local to the caller module. SpecList is a comma-separated sequence of one or more items of the following form:
Name/Arity
procedure specification
domain(Spec)
domain declaration
struct(Prototype)
structure declaration
variable(Name)
non-logical variable declaration
variable(Name,InitialValue)
non-logical variable declaration with initial value
reference(Name)
reference declaration
reference(Name,InitialValue)
reference declaration with initial value (ground term)
array(Name)
untyped non-logical array declaration
array(Name,Type)
typed non-logical array declaration
record(Name)
record key declaration
shelf(Name,InitialValue)
shelf name declaration with initial value
store(Name)
store name declaration
op(Prec,Assoc,Name)
operator declaration
chtab(Char,Class)
character class declaration
syntax_option(Option)
syntax option setting
macro(Functor,Transformation,Options)
macro (input transformation) declaration
portray(Functor,Transformation,Options)
portray (output transformation) declaration
initialization(Goal)
goal to be executed just after the module has been loaded
finalization(Goal)
goal to be executed just before the module is erased (whether explicitly, or implicitly during recompilation or exiting ECLiPSe)
The effect of the local-declaration is that the declared items are only visible inside the module where they have been declared.

Local Procedures

For procedures, the local-declaration is normally redundant because local visibility is the default. However, it might be necessary to explicitly declare a procedure as local to resolve a name conflict when an imported module exports a procedure of the same name.

Local declarations should be placed at the beginning of a module text. They must occur before the first reference to the declared prodecure:

A procedure can have four kinds of visibility in a given module: local, exported, imported or reexported. A local-declaration is silently ignored if the procedure has already been exported before. If a procedure of the given name has already been imported or reexported, the local-declaration raises an error 94. If there is one or more imported modules which export a procedure of the same name, these all get hidden silently by the local declaration.

A local procedure can only be called from within the module where it is defined, even when explicit module qualification via :/2 is used.

Local Initialization and Finalization

The local initialization declaration is used to specify an initialization goal. All initialization goals which occur within a compilation unit (file or module), will be executed just after this compilation unit has been loaded by the system.

A finalization goal will be executed just before the module containing the declaration gets erased. This can happen either explicitly through erase_module/1, or implicitly when the module gets recompiled or when ECLiPSe exits. Finalisation goals should not do any I/O because in the case of an embedded ECLiPSe, I/O may no longer be available at finalisation time.

Other Local Items

All other local declarations also have an effect only in the module where they occur. Some of them have corresponding export-variants.

Further Hints

The local/1 primitive can not only occur as a directive but can also be called at runtime.

Duplicate local declarations are accepted silently.

Modes and Determinism

Modules

This predicate is sensitive to its module context (tool predicate, see @/2).

Exceptions

(4) instantiation fault
SpecList is not instantiated.
(5) type error
SpecList is instantiated, but not to a sequence of valid local specifications.
(94) trying to redefine an existing imported procedure
SpecList is already imported.

Examples

% Normally, local declarations for predicates are redundant:
  :- module(m).

  :- local p/1.         % can be omitted since the default is local
  p(99).


% Redefining a built-in predicate:

    :- module(m)
    :- local writeln/1.   % stop writeln/1 from being imported

    main :-
       writeln(hello).    % local-declaration must be before this use!

    writeln(X) :-         % the local version
       printf("I don't like the normal writeln/1 predicate: %w%n",[X]).


% Redefining an imported predicate:

    :- module(m)
    :- lib(lists).        % module 'lists' defines a predicate subtract/3
    :- local subtract/3.  % stop subtract/3 being imported from 'lists'

    decr(N, N1) :-
       subtract(N,1,N1).  % local-declaration must be before this use!

    subtract(X,Y,Z) :-    % the local version of subtract/3
       Z is X-Y.


% Other local declarations:

   :- local
   	op(500, xfx, before),
	struct(book(author,title,publisher)).

   :- local initialization(writeln("I am being initialized!")).


% Error cases:

  :- local P.                           (Error 4).
  :- local p/a.                         (Error 5).
  :- (import p/0 from m), local(p/0)    (Error 94).

See Also

export / 1, reexport / 1, import / 1, module / 1, array / 1, array / 2, domain / 1, macro / 3, op / 3, portray / 3, reference / 1, reference / 2, set_flag / 2, store / 1, struct / 1, variable / 1, variable / 2