### 8.26 File name processing

- absolute_file_name/2
- is_absolute_file_name/1, is_relative_file_name/1
- decompose_file_name/4
- prolog_file_name/2

#### 8.26.1 absolute_file_name/2

Templates

  absolute_file_name(+atom, atom)

Description

absolute_file_name(File1, File2) succeeds if File2 is the absolute pathname associated with the relative file name File1. File1 can contain $VAR_NAME sub-strings. When such a sub-string is encountered, it is expanded with the value of the environment variable whose name is VAR_NAME if exists (otherwise no expansion is done). File1 can also begin with a sub-string ~USER_NAME/, this is expanded as the home directory of the user USER_NAME. If USER_NAME does not exist File1 is an invalid pathname. If no USER_NAME is given (i.e. File1 begins with ~/) the ~ character is expanded as the value of the environment variable HOME. If the HOME variable is not defined File1 is an invalid pathname. Relative references to the current directory (/./ sub-string) and to the parent directory (/../ sub-strings) are removed and no longer appear in File2. File1 is also invalid if it contains too many /../ consecutive sub-strings (i.e. parent directory relative references). Finally if File1 is user then File2 is also unified with user to allow this predicate to be called on Prolog file names (since user in DEC-10 input/output predicates denotes the current input/output stream).

Under Windows the following applies:

- an alternate recognized form for $VAR_NAME is %VAR_NAME%.
- when ~ is expanded, if the HOME variable is not defined, ~ is expanded using HOMEDIR and HOMEPATH (if HOMEPATH is not defined then File1 is an invalid pathname).

Most predicates using a file name implicitly call this predicate to obtain the desired file, e.g. open/4.

Errors

File1 is a variable |  | instantiation_error
File1 is neither a variable nor an atom |  | type_error(atom, File1)
File2 is neither a variable nor an atom |  | type_error(atom, File2)
File1 is an atom but not a valid pathname |  | domain_error(os_path, File1)

Portability

GNU Prolog predicate.

#### 8.26.2 is_absolute_file_name/1, is_relative_file_name/1

Templates

  is_absolute_file_name(+atom)
  is_relative_file_name(+atom)

Description

is_absolute_file_name(PathName) succeeds if PathName is an absolute file name.

Conversely, is_relative_file_name(PathName) succeeds if PathName is not an absolute file name.

See absolute_file_name/2 for information about the syntax of PathName (section 8.26.1).

The current implementation does not check the validity of PathName. If PathName starts with a / (slash) it is considered as absolute. Under Windows, PathName can also start with a \ (backslash) or a drive specification.

Errors

PathName is a variable |  | instantiation_error
PathName is neither a variable nor an atom |  | type_error(atom, PathName)

Portability

GNU Prolog predicates.

#### 8.26.3 decompose_file_name/4

Templates

  decompose_file_name(+atom, ?atom, ?atom, ?atom)

Description

decompose_file_name(File, Directory, Prefix, Suffix) decomposes the pathname File and extracts the Directory part (characters before the last /), the Prefix part (characters after the last / and before the last . or until the end if there is no suffix) and the Suffix part (characters from the last . to the end of the string).

Errors

File is a variable |  | instantiation_error
File is neither a variable nor an atom |  | type_error(atom, File)
Directory is neither a variable nor an atom |  | type_error(atom, Directory)
Prefix is neither a variable nor an atom |  | type_error(atom, Prefix)
Suffix is neither a variable nor an atom |  | type_error(atom, Suffix)

Portability

GNU Prolog predicate.

#### 8.26.4 prolog_file_name/2

Templates

  prolog_file_name(+atom, ?atom)

Description

prolog_file_name(File1, File2) unifies File2 with the Prolog file name associated with File1. More precisely File2 is computed as follows:

- if File1 has a suffix or if it is user then File2 is unified with File1.
- else if the file whose name is File1 + ’.pl’ exists then File2 is unified with this name.
- else if the file whose name is File1 + ’.pro’ exists then File2 is unified with this name.
- else if the file whose name is File1 + ’.prolog’ exists then File2 is unified with this name.
- else File2 is unified with the name File1 + ’.pl’.

This predicate uses absolute_file_name/2 to check the existence of a file (section 8.26.1).

Errors

File1 is a variable |  | instantiation_error
File1 is neither a variable nor an atom |  | type_error(atom, File1)
File2 is neither a variable nor an atom |  | type_error(atom, File2)
File1 is an atom but not a valid pathname |  | domain_error(os_path, File1)

Portability

GNU Prolog predicate.

Copyright (C) 1999-2021 Daniel Diaz Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved. More about the copyright