SWI-Prolog -- Send methods

1.59.2 Send methods

Determine the absolute-path described by file<-name and store the result in file<-path. First expands _~_ and $var constructs.

file ->access: mode={read,write,append,execute}

Test if the file has specified access. Access write and append have the same meaning, but they allow programmers to test the access with the same argument as passed to file->open.

Diagnostics: Fails silently when the user has not the tested access.

See also: - file->exists
- file->open
- directory->access

file ->append: text=char_array

Append the argument text to the file. The argument text is not interpreted. See also file->format.

See also: file->format

file ->backup: extension=[name]

If the file file->exists, it is copied to a file named file<-name concatenated with extension (default _~_). The file object itself is not affected.

This method may be used in combination with file->open: write or object->save_in_file.

save_diagram(Picture, File) :-
        send(File, backup),
        send(Picture?graphicals, save_in_file, File).

See also: !backup_file

file ->close:

Close file when open. Flushes possible pending output. Succeeds without side-effects if the file is not opened.

See also: file->open

file ->copy: from=file

Copy the contents of the argument-file to this file. Argument ordering may look strange, but is consistent to all other file->copy operations in XPCE. The example below defines an obvious Prolog predicate using this method.

copy_file(From, To) :-
        send(file(To), copy, from).

Bugs: Does not yet copy the mode attributes.

file ->exists: must_be_file=[bool]

Succeeds if the file exists. Note that this does not imply the user has read or write permission for this file. Use file->access to obtain this information.

If must_be_file equals @on or @default this test only succeeds if the file exists and is a regular file or a link to a regular file. If must_be_file equals @off this test succeeds if there is an entry in the file-system with this name regardless of the type of the object there.

Diagnostics: Always fails silently if the file could not be located.

See also: file->access

file ->find: path=[char_array], access=[{read,write,append,execute}]

Find a file in the specified search-path that has the specified access. The path is a colon (:) separated list of directories.

When file<-name does not start with a’.’or’/’, file->find will loop through the directories of the path, append the file<-name of the file and check whether the resulting file has file->access. When successful, it will set file->name to the full pathname of the file.

This method is used by image->load and bitmap->load to locate bitmap files.

The example below is a PCE/Prolog implementation of the Unix utility which for locating executable files.

which(Name, File) :-
        get(@pce, environment_variable, 'PATH', Path),
        new(F, file(Name)),
        send(F, find, Path, execute),
        get(F, absolute_path, File).

Defaults: The default access is read. The default path is’.’

Diagnostics: Fails silently if the file cannot be found in the provided path.

file ->flush:

Output to a file is normally buffered. The buffer is automatically emptied by file->close. If the buffer is to be written to file without closing the file, use file->flush.

file ->format: format=char_array, argument=any ...

Create a string by formatting the arguments and file->append the result to the file. See string->format for a specification of the format.

Bugs: If the total output exceeds FORMATSIZE (currently 10000) characters, PCE crashes.

See also: - file->newline
- file->append

file ->initialise: path=[name], encoding=[{text,binary,iso_latin_1,utf8,unicode_be,unicode_le}]

Create a file from a specification. The given path is expanded using the following rules:

~user Expands the the home directory of user

~ Expands the the current user's home ($HOME)

$var Expands to pce<-environment_variable

pce<-environment_variable is an interface to Unix getenv, but the variable PCEHOME is expanded to PCE's home directory even if it does not exists in the Unix environment.

This class may be used to create a temporary file by omiting path. On systems providing mkstemp(), this function is used to generate a unique file in $TMPDIR or /tmp that is immediately opened for write and not accessible for other users. For compatibility, the file object gets the status tmp_write. A subsequent file->open in mode write or append simply sets the status to write. On other systems, tmpnam() is used to generate the filename. The mkstemp() approach is preferred for security reasons as it avoids race-conditions and access by others than the current user.

The encoding argument specifies whether the file contains an octed stream or a stream of character codes. See source_sink->encoding for details on character encoding issues.

file ->is_absolute:

Test if file<-name specifies an absolute path. First variables and ~ in the name specification is expanded. Next, for Win32 versions the path is considered absolute if it starts with <letter>:. For Unix systems if it starts with’/’.

file ->name: name=name

@see file-name

file ->newline:

Equivalent to file->format:’\n’.

See also: file->format

file ->open: mode={read,write,append}, filter=[name], extension=[char_array]

Open the file for reading or writing. Mode append is like write, but does not truncate the file to zero characters.

If a filter is specified, file->open will not open the file itself, but read or write the file through the filter. The argument is the Unix command string. Example:

?- new(F, file('data.Z')),
   send(F, open, read, uncompress).

This example opens the file data.Z using the Unix command

`uncompress < data.Z`

and reads the output of this command.

When extension is specified, file->open appends the extension to file<-name before passing the name to Unix. This implies the file above could also have been opened using:

?- new(F, file(data)),
   send(F, open, read, uncompress, '.Z').

Class process provides another way to interact with Unix processes.

See also: - class process
- file-filter
- file->close
- file->access

file ->remove:

Remove the file from the disk. The file is first closed using file->close.

Diagnostics: Fails silently if the file did not exist. Fails with an error message if the file is still present after this operation.

file ->same: file=file

Test if two paths refer to the same physical file. Both the reason and implementation of this call is highly system dependent:

Unix

Multiple paths may refer to the same phyical objects due to hard- and soft links. Equivalence testing is achieved comparing the the inode and device identifier as returned by the stat() call.

WIndows

Without links life looks easier, but isn't. Windows files are case-insensitive, on "8+3" filesystems the names are truncated and on VFAT/FAT32 systems both the long and short version exist.

The handling of long and short filenames is a bit buggy. If someone knows an efficient and correct solution to test equivalence, please let us know.

`~`user	Expands the the home directory of `user`
`~`	Expands the the current user's home ($HOME)
$var	Expands to pce`<-`environment_variable