4.5.1.1 Defining File Search Paths

The information about which directories to search when an alias is encountered is extended by clauses for the hook predicate user:file_search_path/2, of the following form:

     user: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.

     user:file_search_path(home, '/usr/jackson'). (A)
     
     user: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, 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.

     user:file_search_path(home, '/usr/jackson'). (E)
     user: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 user: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 sp_directory represents the search path /usr/jackson/prolog/sp followed by /u/jackson/prolog/sp. Then, the file specification (I) refers to the file (J), if it exists. Otherwise, it refers to the file (K), if it exists.

     user:file_search_path(sp_directory, home('prolog/sp')). (H)
     
     sp_directory(test) (I)
     
     /usr/jackson/prolog/sp/test (J)
     
     /u/jackson/prolog/sp/test (K)

Aliases such as home or sp_directory are useful because even if the home directory changes, or the sp_directory is moved to a different location, only the appropriate user: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 sp_directory(file).

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

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

Note: The user: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.