Loading Prolog source files

This section deals with loading Prolog source-files. A Prolog source file is a text-file (often referred to as ASCII-file) containing a Prolog program or part thereof. Prolog source files come in three flavours:

A traditional

Prolog source file contains a Prolog clauses and directives, but no module-declaration. They are normally loaded using consult1 or ensure_loaded1.

A module

Prolog source file starts with a module declaration. The subsequent Prolog code is loaded into the specified module and only the public predicates are made available to the context loading the module. Module files are normally loaded using use_module[1,2]. See modules for details.

A include

Prolog source file is loaded using the include1 directive and normally contains only directives.

Prolog source-files are located using absolute_file_name3 with the following options:

The file_typeprolog option is used to determine the extension of the file using prolog_file_type2. The default extension is pl. Spec allows for the path-alias construct defined by absolute_file_name3. The most commonly used path-alias is libraryLibraryFile. The example below loads the library file oset.pl (containing predicates for manipulating ordered sets).

SWI-Prolog recognises grammar rules (DCG) as defined in [Clocksin & Melish, 1987]. The user may define additional compilation of the source file by defining the dynamic predicate term_expansion2. Transformations by this predicate overrule the systems grammar rule transformations. It is not allowed to use assert1, retract1 or any other database predicate in term_expansion2 other than for local computational purposes.^2.2

Directives may be placed anywhere in a source file, invoking any predicate. They are executed when encountered. If the directive fails, a warning is printed. Directives are specified by :-/1 or ?-/1. There is no difference between the two.

SWI-Prolog does not have a separate reconsult1 predicate. Reconsulting is implied automatically by the fact that a file is consulted which is already loaded.

load_files2+Files, +Options The predicate load_files2 is the parent of all the other loading predicates. It currently supports a subset of the options of Quintus load_files2. Files is either specifies a single, or a list of source-files. The specification for a source-file is handled absolute_file_name2. See this predicate for the supported expansions. Options is a list of options using the format

OptionName(OptionValue)

The following options are currently supported:

ifCondition Load the file only if the specified condition is satisfied. The value true loads the file unconditionally, changed loads the file if it was not loaded before, or has been modified since it was loaded the last time, not_loaded loads the file if it was not loaded before. must_be_moduleBool If true, raise an error if the file is not a module file. Used by use_module[1,2]. importsListOrAll If all and the file is a module file, import all public predicates. Otherwise import only the named predicates. Each predicate is refered to as name/arity. This option has no effect if the file is not a module file. silentBool If true, load the file without printing a message. The specified value is the default for all files loaded as a result of loading the specified files.

consult1+File Read File as a Prolog source file. File may be a list of files, in which case all members are consulted in turn. File may start with the csh(1) special sequences  ,  user and $var. File may also be library(Name), in which case the libraries are searched for a file with the specified name. See also library_directory1 and file_search_path2. consult1 may be abbreviated by just typing a number of file names in a list. Examples:

?- consult(load).	% consult load or load.pl
?- [library(quintus)].	% load Quintus compatibility library

Equivalent to load_files(Files, []). ensure_loaded1+File If the file is not already loaded, this is equivalent to consult1. Otherwise, if the file defines a module, import all public predicates. Finally, if the file is already loaded, is not a module file and the context module is not the global user module, ensure_loaded1 will call consult1.

With the semantics, we hope to get as closely possible to the clear semantics without the presence of a module system. Applications using modules should consider using use_module[1,2].

Equivalent to load_files(Files, [if(changed)]). include1+File Pretend the terms in File are in the source-file in which :- include(File) appears. The include construct is only honnoured if it appears as a directive in a source-file. Normally File contains a sequence of directives.

require1+ListOfNameAndArity Declare that this file/module requires the specified predicates to be defined ``with their commonly accepted definition''. This predicate originates from the Prolog portability layer for XPCE. It is intended to provide a portable mechanism for specifying that this module requires the specified predicates.

The implementation normally first verifies whether the predicate is already defined. If not, it will search the libraries and load the required library.

SWI-Prolog, having autoloading, does not load the library. Instead it creates a procedure header for the predicate if this does not exist. This will flag the predicate as `undefined'. See also check0 and autoload0.

make0 Consult all source files that have been changed since they were consulted. It checks all loaded source files: files loaded into a compiled state using pl -c ... and files loaded using consult or one of its derivatives. The predicate make0 is called after edit1, automatically reloading all modified files. It the user uses an external editor (in a separate window), make0 is normally used to update the program after editing.

library_directory1?Atom Dynamic predicate used to specify library directories. Default ./lib,  /lib/prolog and the system's library (in this order) are defined. The user may add library directories using assert1, asserta1 or remove system defaults using retract1.

file_search_path2+Alias, ?Path Dynamic predicate used to specify `path-aliases'. This feature is best described using an example. Given the definition

the file specification demo(myfile) will be expanded to /usr/lib/prolog/demo/myfile. The second argument of file_search_path2 may be another alias.

Below is the initial definition of the file search path. This path implies swi(Path) refers to a file in the SWI-Prolog home directory. The alias foreign(Path) is intended for storing shared libraries (so or DLL files). See also load_foreign_library[1,2].

The file_search_path2 expansion is used by all loading predicates as well as by absolute_file_name[2,3].

expand_file_search_path2+Spec, -Path Unifies Path will all possible expansions of the file name specification Spec. See also absolute_file_name3.

prolog_file_type2?Extension, ?Type This dynamic multifile predicate defined in module user determines the extensions considered by file_search_path2. Extension is the filename extension without the leading dot, Type denotes the type as used by the file_typeType option of file_search_path2. Here is the initial definition of prolog_file_type2:

Users may wish to change the extension used for Prolog source files to avoid conflicts (for example with perl) as well as to be compatible with some specific implementation. The preferred alternative extension is pro.

source_file1?File Succeeds if File is a loaded Prolog source file. File is the absolute and canonical path to the source-file.

source_file2?Pred, ?File Is true if the predicate specified by Pred was loaded from file File, where File is an absolute path name (see absolute_file_name2). Can be used with any instantiation pattern, but the database only maintains the source file for each predicate. See also clause_property2. prolog_load_context2?Key, ?Value Determine loading context. The following keys are defined:

Key	Description
module	Module into which file is loaded
file	File loaded
stream	Stream identifier (see current_input1)
directory	Directory in which File lives.
term_position	Position of last term read. Term of the form '$stream_position'(0,Line,0,0,0)

Quintus compatibility predicate. See also source_location2.

source_location2-File, -Line If the last term has been read from a physical file (i.e. not from the file user or a string), unify File with an absolute path to the file and Line with the line-number in the file. New code should use prolog_load_context2.

term_expansion2+Term1, -Term2 Dynamic predicate, normally not defined. When defined by the user all terms read during consulting that are given to this predicate. If the predicate succeeds Prolog will assert Term2 in the database rather then the read term (Term1). Term2 may be a term of a the form `?- Goal' or `:- Goal'. Goal is then treated as a directive. If Term2 is a list all terms of the list are stored in the database or called (for directives). If Term2 is of the form below, the system will assert Clause and record the indicated source-location with it.

'$source_location'(File, Line):Clause

When compiling a module (see modules and the directive module2), expand_term2 will first try term_expansion2 in the module being compiled to allow for term-expansion rules that are local to a module. If there is no local definition, or the local definition fails to translate the term, expand_term2 will try term_expansion2 in module user. For compatibility with SICStus and Quintus Prolog, this feature should not be used. See also expand_term2, goal_expansion2 and expand_goal2.

expand_term2+Term1, -Term2 This predicate is normally called by the compiler to perform preprocessing. First it calls term_expansion2. If this predicate fails it performs a grammar-rule translation. If this fails it returns the first argument.

goal_expansion2+Goal1, -Goal2 Like term_expansion2, goal_expansion2 provides for macro-expansion of Prolog source-code. Between expand_term2 and the actual compilation, the body of clauses analysed and the goals are handed to expand_goal2, which uses the goal_expansion2 hook to do user-defined expansion.

The predicate goal_expansion2 is first called in the module that is being compiled, and then on the user module.

Only goals apearing in the body of clauses when reading a source-file are expanded using mechanism, and only if they appear literally in the clause, or as an argument to the meta-predicates not1, call1 or forall2. A real predicate definition is required to deal with dynamically constructed calls.

expand_goal2+Goal1, -Goal2 This predicate is normally called by the compiler to perform preprocessing. First it calls goal_expansion2. If this fails it returns the first argument.

at_initialization1+Goal Register Goal to be ran when the system initialises. Initialisation takes place after reloading a .qlf (formerly .wic) file as well as after reloading a saved-state. The hooks are run in the order they were registered. A warning message is issued if Goal fails, but execution continues. See also at_halt1

at_halt1+Goal Register Goal to be ran when the system halts. The hooks are run in the order they were registered. Success or failure executing a hook is ignored. These hooks may not call halt[0,1]. initialization1+Goal Call Goal and register it using at_initialization1. Directives that do other things that creating clauses, records, flags or setting predicate attributes should normally be written using this tag to ensure the initialisation is executed when a saved system starts. See also qsave_program[1,2].

compiling0 Succeeds if the system is compiling source files with the -c option into an intermediate code file. Can be used to perform code optimisations in expand_term2 under this condition. preprocessor2-Old, +New Read the input file via a Unix process that acts as preprocessor. A preprocessor is specified as an atom. The first occurrence of the string `%f' is replaced by the name of the file to be loaded. The resulting atom is called as a Unix command and the standard output of this command is loaded. To use the Unix C preprocessor one should define: