Quintus Prolog

Defining File Search Paths

The information about which directories to search when an alias is encountered, is defined by the dynamic, multifile predicate file_search_path/2. The clauses for this predicate are located in module user, and have the following form:

     file_search_path(PathAlias, DirectorySpec).

PathAlias: must be an atom. It can be used as an alias for DirectorySpec
DirectorySpec: Can either be an atom, spelling out the name of a directory, or a compound term using other path aliases to define the location of the directory.

The directory path may be absolute, as in (A) or relative as in (B), which defines a path relative to the current working directory.

Then, files may be referred to by using file specifications of the form similar to library(file). For example, (C), names the file /usr/jackson/.login, while (D) specifies the path etc/demo/my_demo relative to the current working directory.

     file_search_path(home, '/usr/jackson'). (A)
     
     file_search_path(demo, 'etc/demo'). (B)
     
     home('.login') (C)
     
     demo(my_demo) (D)

As mentioned above, it is also possible to have multiple definitions for the same alias. If clauses (E) and (F) define the home alias, then to locate the file specified by (G) each home directory is searched in sequence for the file .login. If /usr/jackson/.login exists, it is used. Otherwise, /u/jackson/.login is used if it exists.

     file_search_path(home, '/usr/jackson'). (E)
     file_search_path(home, '/u/jackson'). (F)
     
     home('.login') (G)

The directory specification may also be a term of arity 1, in which case it specifies that the argument of the term is relative to the file_search_path/2 defined by its functor. For example, (H) defines a directory relative to the directory given by the home alias. Therefore, the alias qp_directory represents the search path /usr/jackson/prolog/qp followed by /u/jackson/prolog/qp. Then, the file specification (I) refers to the file (J), if it exists. Otherwise, it refers to the file (K), if it exists.

     file_search_path(qp_directory, home('prolog/qp')). (H)
     
     qp_directory(test) (I)
     
     /usr/jackson/prolog/qp/test (J)
     
     /u/jackson/prolog/qp/test (K)

Aliases such as home or qp_directory are useful because even if the home directory changes, or the qp_directory is moved to a different location, only the appropriate file_search_path/2 facts need to be changed. Programs relying on these paths are not affected by the change of directories because they make use of file specifications of the form home(file) and qp_directory(file).

All built-in predicates that take file specification arguments allow these specifications to include path aliases defined by file_search_path/2 facts. These predicates are:

absolute_file_name/[2,3]
compile/1
consult/1
ensure_loaded/1
load_files/[1,2]
open/[2,3]
restore/1
save_module/2
save_predicates/2
save_program/[1,2]
see/1
tell/1
use_module/[1,2,3]

Notes:

The file_search_path/2 database may contain directories that do not exist or are syntactically invalid (as far as the operating system is concerned). If an invalid directory is part of the database, the system will fail to find any files in it, and the directory will effectively be ignored.
This facility is provided so that one can load library or other files without knowing their absolute file names, but this does not restrict the way a file can be accessed. It is strongly suggested that writing to a file not be done using the PathAlias(FileSpec) facility. (One could write to PathAlias(FileSpec) but this may not have the desired effect, since the system will write to one of possibly many files depending upon the current order of the clauses in the file_search_path/2 predicate.) The absolute name of the file to which one is writing should be known. To find the absolute name of a library file, for example, one can type
```
           | ?- absolute_file_name(library(FileSpec), AbsFileName).
          
```
file_search_path/2 must be defined in the default module user -- definitions in any other module will not be found.