11.3.117 load_files/[1,2]

Synopsis

load_files(+Files)

load_files(+Files, +Options)

[+Files]

Loads the specified Prolog source and/or object file(s) into memory. Subsumes all other load predicates.

Arguments

:Files

file_spec or list of file_spec, must be ground

A file specification or a list of file specifications; extensions optional.

Options

list of term, must be ground

A list of zero or more options of the form:

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 specification 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 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, or latest (the default) to load any type of file, whichever is newest. If the file specification is user, then 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 a PO 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 file.

In addition the open/4 options encoding/1, encoding_signature/1 and eol/1 can be specified. These will be used if the Prolog code is loaded from a source file. See mpg-ref-open, for details.

Description

load_files/[1,2] reads Prolog clauses, in source or precompiled form, and adds them to the Prolog database, after first deleting any previous versions of the predicates they define. Clauses for a single predicate must all be in the same file unless that predicate is declared to be multifile.

If a source file contains directives, that is, terms with principal functor :-/1 or ?-/1, then these are executed as they are encountered. Initialization goals specified with initialization/1 are executed after the load.

A non-module source file can be loaded into any module by load_files/[1,2], but the module of the predicates in a precompiled file is fixed at the time it is created.

Exceptions

instantiation_error

Files or Options is not ground.

type_error

In Files or Options.

domain_error

Illegal option in Options.

existence_error

A specified file does not exist. If the fileerrors flag is off, then the predicate fails instead of raising this exception.

permission_error

A specified file not readable. If the fileerrors flag is off, then the predicate fails instead of raising this exception.

While loading clauses from a PO file, clauses for an existing multifile predicate were encountered, but were compiled in a way different from the existing clauses. In this case, the existing clauses remain untouched, the multifile clauses from the PO file are simply ignored, the load continues, and an exception is raised at the end.

Examples

Several of the other built-in predicates of this category could be defined in terms of load_files/2:

[File|Files] :-
    load_files([File|Files]).

consult(Files) :- 
    load_files(Files, [load_type(source),compilation_mode(consult)]).

ensure_loaded(Files) :- 
        load_files(Files, [if(changed)]).

use_module(File) :-
    load_files(File, [if(changed)]).

use_module(File, Imports) :-
    load_files(File, [if(changed),imports(Imports)]).

Code that is only needed at compile-time, e.g. for operator declarations or compile-time expansion, is conveniently loaded with the following idiom:

:- load_files(library(obj_decl), [when(compile_time), if(changed)]).

See Also

ref-lod-lod.