The following is a list of the directives most commonly used in source files:
- :- module(Name).
- Beginning of a module.
- :- module(Name, Exports, Dialect).
- Beginning of a module in a given dialect.
- :- local Specs.
- Declaration of local items, e.g., syntax settings, operators, global storage, etc.
- :- export Specs.
- Declaration of exported items, e.g., predicates, syntax settings, operators, etc.
- :- reexport Specs.
- Declaration of reexported items.
- :- import Specs.
- Declaration of imported modules or predicates.
- :- use_module(Mods).
- Loading and importing of modules or libraries.
- :- lib(Libs).
- Loading and importing of libraries.
- :- meta_attribute(Name, Handlers)
- Declare a variable attribute.
- :- comment(Type, Info)
- Structured program documentation.
The compiler and other source-processing tools recognise the conditional compilation directives if/1, elif/1, else/0 and endif/0. The first two take a goal as their argument, and parts of the program source can be included or excluded depending of the satisfiability of that goal. For example,
:- if(get_flag(hostarch, "i386_nt")).
...Windows-specific code...
:- elif( (get_flag(version_as_list,Version), Version @>= [6,0]) ).
...code for version 6.0 and later...
:- else.
...alternative code...
:- endif.
Note however, that only complete clauses or directives can be conditionally included.
Generally, it is best to use the module system to structure ECLiPSe applications, and to use one module per file. The modules then refer to each other via use_module/1, lib/1, or import/1 directives. In rare cases it can make sense to split a single module into several files, which can then be pulled together using the following include directives:
- :- include(Files).
- The contents of the given Files are treated as if they occurred in place of the include directive. Files is a single file name or a list of them.
- :- [Files].
- A synonym for the include/1 directive. Note that the semantics of this construct when used as a directive (include semantics) differs slightly from its use as a goal or query (compiler/loader invocation).
Included files can contain clauses, directives and queries, but should not contain module/1,3 directives, since they would be interpreted as occurring within the including file, and the included module would not end at the end of the included file.
Compiler pragmas are compiler directives which instruct the compiler to emit a particular code type, overriding the options given to the compiler. Their syntax is similar to directives:
:- pragma(Option).
It is not possible to have several pragmas grouped together and separated by commas, every pragma must be specified separately. Option can be one of the following:
- debug
- - generate code which can be inspected with the debugger. This overrides the global setting of the debug_compile flag, and any debug-option given to the compiler.
- nodebug
- - generate optimized code with no debugger support. This overrides the global setting of the debug_compile flag, and any debug-option given to the compiler.
- expand
- - do in-line expansion of built-ins like is/2 and user-defined inline predicates. This code can still be inspected with the debugger but the expanded subgoals look differently than in the normal debugged code, or their arguments cannot be seen. This pragma overrides the global setting of the goal_expansion flag, and any expand-option given to the compiler.
- noexpand
- - inhibit the in-line goal expansion. This pragma overrides the global setting of the goal_expansion flag, and any expand-option given to the compiler.
- opt_level(Level)
- - override the opt_level option given to the compiler. Level is an integer greater or equal to 0. A zero setting disables all optional optimization.
- skip
- - set the skip flag of all following predicates to on.
- noskip
- - set the skip flag of all following predicates to off.
- system
- - set the type flag of all following predicates to built_in. Moreover, all following predicates will have unspecified source_file and source_line flags.
- warnings
- - enable compiler warnings, overriding any warnings-option given to the compiler.
- nowarnings
- - disable compiler warnings, overriding any warnings-option given to the compiler.
A pragma is active from its specification in the file until the file end or until it is disabled by another pragma. Recursive compilations or calls to other compiling predicates are not affected by the pragma.
The pragmas are useful mainly for libraries and other programs that should be always compiled in a particular mode independently of the global flags or compiler option settings.