A file object is a wrapper around a Unix file. Files are used internally for the various disk read and write operations supported by PCE.
File objects can be used to query the status of a Unix file, read/write from/to it, rename it, remove it, etc.
A file is represented by its file<-name,
which may hold the Unix constructs _~_, _~loginname_
and $var. A file can be searched in a search-path using file->find.
It may be translated to an absolute filename using file->absolute_path,
which writes the variable file<-path
after successful translation.
Class file defines
the class->has_features listed below.
These features are defined for the various MS-Windows based versions of
XPCE. If XPCE is running on any of the MS-Windows based platforms,
case_sensitive yields
@off.
case_preserving is @on
on -NT and’95 and @off
on win32s. 8plus3names is @on
on win32s and @off
on the other systems. All Unix versions are case_sensitive,
case_preserving have 8plus3names set to @off.
case_sensitive bool case_preserving bool 8plus3names bool
See also class directory.
<-bom
is not @off,
the file is checked for a UNICODE BOM signature. If found, file<-bom
is set to @on
and the source_sink<-encoding is set
accordingly.
If the file is opened for writing and file<-bom
= @on and the
encoding is a UNICODE encoding, a BOM marker is written to the file.
Note that this default behaviour returns consistent results on the sequence below. If a BOM is detected on reading, one will be added on writing the file and the encoding of the file will not be changed.
send(View, load, File), ... send(View, save).
->open
for details.
->initialise
. When the name is changed and the file already exists, the Unix file is
renamed accordingly. file->name
cannot move files across file-systems.
\r from the input. The detect mode sets the mode of
the file to dos or posix. In write mode posix does not perform
translation, while dos emits \n as \r\n.
BUG: detection is only provided by text_buffer->insert_file.
->absolute_path
or file->find.
The Unix file opened is the name of this variable when not @default
and file<-name
after expansion of _~_ and
$var constructs if this variable holds @default
->close.
->open.
write or
append. See file->open.
<-name
and store the result in file<-path.
First expands _~_ and $var constructs.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.
->format.
->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).
->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.
->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.
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.
->close.
If the buffer is to be written to file without closing the file, use file->flush.->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.
path is
expanded using the following rules:
~userExpands 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.
<-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’/’.-name->format:’\n’.
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.
->close.
Diagnostics: Fails silently if the file did not exist. Fails with an error message if the file is still present after this operation.
stat() call.
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.
See also directory->same.
<-index)
or the end of the file. The file must be open and must be a regular file
not opened through a file<-filter.
<-name
without the possible directory specification:
?- new(F, file('/staff/jan/src/xpce/src/unx-file.c')),
get(F, base_name, Base).
F = @634787
Base = 'unx-file.c'
Diagnostics: Fails with message on I/O error. Fails silently on reaching end-of-file.
->initialise.->seek.
Diagnostics: Gives a warning if the file is not opened.
Defaults: The default amount to read is the entire file.
Diagnostics: Standard file diagnostics.
Bugs: Unlike Unix read(), this function cannot
deal with files holding 0 (EOS) characters as strings cannot represent
such characters.
->strip.
If the last line is not closed with a newline, a string without
trailing newline is returned.
Diagnostics: Fails with error message on file errors. Fails silently when the end of the file is reached.
<-string)
or compared.
See also directory->modified.
Defaults: By default returns the time of last modification.