[ 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 predicate 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. Note that the executable permission for Windows may be approximate, because Windows (especially Vista) have a different system for dealing with execute permission.

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)
            ).

### Modes and Determinism

- existing_file(++, ++, ++, -) is nondet
- existing_file(++, ++, ++, +) is semidet

### Fail Conditions

MatchedFile cannot be found.

### Exceptions

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

## Examples

    Success:

          [eclipse 1]:  existing_file(library(fd), [".eco"], [readable], File).

          File = "/homes/ks15/Eclipse/lib/fd.eco"     More? (;)

          % test1 and test3 exists in current working directory
          [eclipse 1]: existing_file(test, [1,2,3], [], File).

          File = test1     More? (;)

          File = test3     More? (;)

          no (more) solution.

    Failure:

          [eclipse 1]:  existing_file(library(fd), [], [readable], File).
          % no Completions at all; will always fail

          [eclipse 1]:  existing_file(library(fd), [""], [readable], File).
          % no library file with just 'fd' as the name (file has a suffix)

## See Also

canonical_path_name / 2, get_flag / 2, os_file_name / 2, pathname / 4