Node:Read In, Next:Definite, Previous:Input Output, Up:Input Output

Reading-in Programs

When the predicates discussed in this section are invoked, filenames are treated as relative to the current working directory. While loading code, however, filenames are treated as relative to the directory containing the file being read in. This has the effect that if one of these predicates is invoked recursively, the filename of the recursive load is relative to the directory of the enclosing load. See Load Intro, for an introduction to these predicates.

Directives will be executed in order of occurrence. Be aware of the rules governing relative filenames as they could have an effect on the semantics of directives. Only the first solution of directives is produced, and variable bindings are not displayed. Directives that fail or raise exceptions give rise to warning or error messages, but do not terminate the load. However, these warning or error messages can be intercepted by the hook user:portray_message/2 which can call abort/0 to terminate the load, if that is the desired behavior.

Predicates loading source code are affected by the character-conversion mapping, cf. char_conversion/2; see Term I/O.

Most of the predicates listed below take an argument Files which is a single file name or a list of file names. Source, object and QL files usually end with a .pl, .po and .ql suffix respectively. These suffixes are optional. Each file name may optionally be prefixed by a module name. The module name specifies where to import the exported predicates of a module-file, or where to store the predicates of a non-module-file. The module is created if it doesn't exist already.

absolute_file_name/3 (see Stream Pred) is used to look up the files. The file name user is reserved and denotes the standard input stream.

These predicates are available in runtime systems with the following limitations:

• The compiler is not available, so compiling is replaced by consulting.
• The Prolog flags discontiguous_warnings, redefine_warnings and single_var_warnings have no effect.
• Informational messages are suppressed.
• The user is not prompted in the event of name clashes etc.

load_files(:Files)

load_files(:Files, +Options)

A generic predicate for loading files with a list of options to provide extra control. This predicate in fact subsumes the other predicates except use_module/3 which also returns the name of the loaded module, or imports a set of predicates from an existing module. Options is a list of zero or more of the following:

if(X)

true (the default) to always load, or changed to load only if the file has not yet been loaded or if it has been modified since it was last loaded. A non-module-file is not considered to have been previously loaded if it was loaded into a different module. The file user is never considered to have been previously loaded.

when(When)

always (the default) to always load, or compile_time to load only if the goal is not in the scope of another load_files/[1,2] directive occurring in a .po or .ql file.

The latter is intended for use when the file only defines predicates that are needed for proper term or goal expansion during compilation of other files.

load_type(LoadType)

source to load source files only, object to load object (.po) files only, ql (obsolescent) to load .ql files only, or latest (the default) to load any type of file, whichever is newest. If the file is user, source is forced.

imports(Imports)

all (the default) to import all exported predicates if the file is a module-file, or a list of predicates to import.

compilation_mode(Mode)

compile to translate into compiled code, consult to translate into static, interpreted code, or assert_all to translate into dynamic, interpreted code.

The default is the compilation mode of any ancestor load_files/[1,2] goal, or compile otherwise. Note that Mode has no effect when an .po or .ql file is loaded, and that it is recommended to use assert_all in conjunction with load_type(source), to ensure that the source file will be loaded even in the presence of a .po or .ql file.

wcx(Wcx)

To pass the term Wcx to the wide character extension component; see Prolog Level WCX Features.

consult(:Files)

reconsult(:Files) [Obsolescent]

[]

[:File|+Files]

Consults the source file or list of files specified by File and Files. Same as load_files(Files, [load_type(source),compilation_mode(consult)]).

compile(:Files)

Compiles the source file or list of files specified by Files. The compiled code is placed in-core, i.e. is added incrementally to the Prolog database. Same as load_files(Files, [load_type(source),compilation_mode(compile)]).

load(:Files) [Obsolescent]

Loads the .ql file or list of files specified by Files. Same as load_files(Files, [load_type(ql)]).

ensure_loaded(:Files) [ISO]

Compiles or loads the file or files specified by Files that have been modified after the file was last loaded, or that have not yet been loaded. The recommended style is to use this predicate for non-module-files only, but if any module-files are encountered, their public predicates are imported. Same as load_files(Files, [if(changed)]).

use_module(:File)

Compiles or loads the module-file specified by File if it has been modified after it was last loaded, or not yet been loaded. Its public predicates are imported. The recommended style is to use this predicate for module-files only, but any non-module-files encountered are simply compiled or loaded. Same as load_files(File, [if(changed)]).

use_module(:File, +Imports)

Loads the module-file File like ensure_loaded/1 and imports the predicates in Imports. If any of these are not public, a warning is issued. Imports may also be set to the atom all in which case all public predicates are imported. Same as load_files(File, [if(changed),imports(Imports)]).

use_module(-Module, :File, +Imports)

use_module(+Module, :File, +Imports)

If used with +Module, and that module has already been loaded, this merely imports Imports from that module. Otherwise, this is equivalent to use_module(File, Imports) with the addition that Module is unified with the loaded module.

fcompile(:Files) [Obsolescent]

Compiles the source file or list of files specified by Files. If Files are prefixed by a module name, that module name will be used for module name expansion during the compilation (see Considerations). The suffix .pl is added to the given filenames to yield the real source filenames. The compiled code is placed on the .ql file or list of files formed by adding the suffix .ql to the given filenames. (This predicate is not available in runtime systems.)

source_file(?File)

File is the absolute name of a source file currently in the system.

source_file(:Head,?File)

source_file(-Head,?File)

Head is the most general goal for a predicate loaded from File.

require(:PredSpecOrSpecs)

PredSpecOrSpecs is a predicate spec or a list or a conjunction of such. The predicate will check if the specified predicates are loaded and if not, will try to load or import them using use_module/2. The file containing the predicate definitions will be located in the following way:

• The directories specified with user:library_directory/1 are searched for a file INDEX.pl. This file is taken to contain relations between all exported predicates of the module-files in the library directory and its subdirectories. If an INDEX.pl is not found, require/1 will try to create one by loading the library package mkindex and calling make_index:make_library_index(Directory) (see The Prolog Library).
• The first index entry for the requested predicate will be used to determine the file to load. An exception is raised if the predicate can't be located.
• Once an INDEX.pl is read, it is cached internally for use in subsequent calls to require/1.
• Not available in runtime systems.