[ Operating System | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

existing_file(++Base, ++Completions, ++Permissions, ?MatchedFile)

Finds any existing file subject to the specified conditions.

Base: The start of a filename (non-empty atom or string (possibly with a library/1 wrapper))
Completions: Possible completions for Base (list of atomic elements)
Permissions: Permissions (list of readable,writable,executable)
MatchedFile: An existing file that matches the specification.

Description

This file will search for any existing files that matches the specifications given in the first three arguments: the file starts with Base, which is a partial filepath name. Base may have a library/1 wrapper around the name. A list of possible completions (usually suffixes) given in Completions is appended to Base, in the order they are given, to give a complete name. If a proper file (i.e. non-directory) with this name exists, the ECLiPSe process's permission for this file are checked against the Permissions list -- the list can contain the atoms readable, writable, executable; each specifying that the corresponding permission should be checked. If the permissions match, then the filename is returned in MatchedFile.

If the library/1 wrapper is used, then the file is searched for in the paths specified in library path (including any subdirectory with the same name as given in the library/1 wrapper). Otherwise, the search is relative to the current working directory. All matching names can be returned via backtracking. The search order is that if library/1 wrapper is used, then the library path is tried in the order in which they appear in the library_path flag of get_flag/2, and for each path, the completions are tried in the order in which they appeared in Completions.

MatchedFile is in the same form as Base, except that if library(...) is used, the proper library path is substituted. Also, any leading '~' and enviroment variables (specified with a leading '$') are replaced.

The predicates canonical_path_name/2 and existing_file/4 are intended as replacement for absolute_file_name/2 in previous releases. The functionality of completing an incomplete name and returning an absolute path of absolute_file_name/2 has been separated. The following approximately implements the old absolute_file_name/2:

    absolute_file_name(Rel, Abs) :-
	(Rel == user ->
	    Abs == user
	; get_flag(prolog_suffix, Sufs),
	  (existing_file(Rel, Sufs, [], ExtRel) -> true ; ExtRel = Rel),
	  canonical_path_name(ExtRel, Abs)
        ).

Fail Conditions

MatchedFile cannot be found.

Resatisfiable

yes

Exceptions

(5) type error: Base, Completions, Permissions not of right type.
(6) out of range: Base is an empty atom or string.

Examples