File name processing

### 7.26 File name processing

- `absolute_file_name/2`
- `decompose_file_name/4`
- `prolog_file_name/2`

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

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.

#### 7.26.2 `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.

#### 7.26.3 `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 `File2` is unified with the name `File1` + `’.pl’`.

This predicate uses `absolute_file_name/2` to check the existence of a file (section 7.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-2009 Daniel Diaz Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved. More about the copyright