PCE version 4C man_modulenamespaceid_tablemodified current_idOIxN class/fileN referenceC hash_tablerefersizeOIxNbothI%sNM.file.S.removeCman_method_card identifiermodule last_modifiednamesummary descriptionsee_alsoinherit diagnosticsdefaultsbugsOIxNM.file.S.removeRICdateOIx<ä+NremovenCstringOIxGRemove the file from the disk. The file is first closed using ->close.nnOIxyFails silently if the file did not exist. Fails with an error message if the file is still present after this operation.nnsNM.file.G.base_nameOIxNM.file.G.base_nameRIOIx,VfļN base_namenOI xĩReturns <-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'CchainsizeOI xIeNM.file.G.directory_nameEN V.file.nameXnnnnsNM.file.S.absolute_pathOI xNM.file.S.absolute_pathRIOI x-^J N absolute_pathnOI xwDetermine the absolute-path described by <-name and store the result in <-path. First expands `~' and $var constructs.nnnnnsNM.file.S.check_objectOIxNM.file.S.check_objectRIOIx*Ā† N check_objectnOIx…Checks whether the represented file contains a PCE instance saved with `object ->save_in_file' and thus can be loaded using <-object.OIxIeN%$class/object$M.object.S.save_in_fileENM.file.G.objectXnOIx[Fails with message on file errors. Fails silently if the file's magic code does not match.nnsNM.file.G.convertOIxNM.file.G.convertRIOIx*Ā†˛NconvertnOIx>Converts a name into a file with that name. See ->initialise.nnnnnsN M.file.S.copyOIxN M.file.S.copyRIOIxcopy operations in XPCE. The example below defines an obvious Prolog predicate using this method. copy_file(From, To) :- send(file(To), copy, from).nnnnOIx&Does not yet copy the mode attributes.sNM.file.S.accessOIxNM.file.S.accessRIOIx*ĀņNaccessnOIx´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 ->open.OIxIeNM.file.S.existseN M.file.S.openEN%$class/directory$M.directory.S.accessXnOIx7Fails silently when the user has not the tested access.nnsNM.file.S.newlineOIxNM.file.S.newlineRIOI x*ĀŒ¤NnewlinenOI!xEquivalent to ->format: '\n'.OI"xIENM.file.S.formatXnnnnsNM.file.G.characterOI#xNM.file.G.characterRIOI$x*Ā…rN characternOI%xHReads the next character and returns it as an integer between 0 and 255.nnOI&xIFails with message on I/O error. Fails silently on reaching end-of-file.nnsNM.file.S.existsOI'xNM.file.S.existsRIOI(x0ĩÂENexistsnOI)xĩSucceeds if the file exists. Note that this does not imply the user has read or write permission for this file. Use ->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.OI*xIENM.file.S.accessXnOI+x7Always fails silently if the file could not be located.nnsN M.file.G.timeOI,xN M.file.G.timeRIOI-x0Y1INtimenOI.x˛Returns a new date object holding the last access or modification time. Date objects may be converted to a string (`date <-string') or compared. See also `directory ->modified'.OI/xIEN M.file.G.sizeXnnOI0x1By default returns the time of last modification.nsN M.file.S.findOI1xN M.file.S.findRIOI2x0ĩŽxNfindnOI3xÖFind a file in the specified search-path that has the specified access. The path is a colon (:) separated list of directories. When <-name does not start with a '.' or '/', ->find will loop through the directories of the path, append the <-name of the file and check whether the resulting file has ->access. When successful, it will set ->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).nnOI4x@Fails silently if the file cannot be found in the provided path.OI5x6The default access is `read'. The default path is '.'nsN V.file.fdCman_variable_card identifiermodule last_modifiednamesummary descriptionsee_alsoinheritdefaultsOI6xN V.file.fdRIOI7x*ĀxNfdnOI8x0Pointer to the C stream associated to this file.nnnsN M.file.G.readOI9xN M.file.G.readRIOI:x*Ā—˜NreadnOI;xdReturns a new string object with the next characters or as many as there are left in the file.OIx.The default amount to read is the entire file.OI?x€Unlike Unix read(), this function cannot deal with files holding 0 (EOS) characters as strings cannot represent such characters.sN M.file.S.openOI@xN M.file.S.openRIOIAx,Vg¨NopennOIBx 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, ->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, ->open appends the extension to <-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.OICxIeN$class/process$C.processeN V.file.filtereNM.file.S.closeENM.file.S.accessXnnnnsNM.file.S.closeOIDxNM.file.S.closeRIOIEx,VgINclosenOIFxpClose file when open. Flushes possible pending output. Succeeds without side-effects if the file is not opened.OIGxIEN M.file.S.openXnnnnsN M.file.G.sizeOIHxN M.file.G.sizeRIOIIx*Āš?NsizenOIJxLReturns the number of characters in the file. The file needs not be opened.OIKxIEN M.file.G.timeXnnnnsN V.file.filterOILxN V.file.filterRIOIMx+īĸüNfilternOINxLName of the filter used as input- or output filter. See ->open for details.OIOxIEN M.file.S.openXnnsN V.file.bomOIPxN V.file.bomRIOIQxBVŸ‡NbomnOIRx{BOM (Byte Order Mark) handling of the file. Initial @default. If the file is opened for reading in text-mode and <-bom is not @off, the file is checked for a UNICODE BOM signature. If found, <-bom is set to @on and the <-encoding is set accordingly. If the file is opened for writing and <-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).nnnsNM.file.G.directory_nameOISxNM.file.G.directory_nameRIOITx*Ā‡ŽNdirectory_namenOIUxƒReturns a name representing the directory name for this file. Computed by deleting all text after the last '/' including this '/'.OIVxIeNM.file.G.base_nameEN V.file.nameXnnnnsN V.file.statusOIWxN V.file.statusRIOIXx,V’áNstatusnOIYxāCurrent status of the file: # closed Currently not open (-fd is 0). See ->close. # read Currently open for reading. See ->open. # write Currently open for writing. May be opened `write' or `append'. See ->open.nnnsNV.file.newline_modeOIZxNV.file.newline_modeRIOI[xG dN newline_modenOI\xuDefines newline representation similar to SWI-Prolog's newline property on streams. In read mode, posix read untranslated. Both dos and detect delete \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'.nnnsNM.file.S.flushOI]xNM.file.S.flushRIOI^x,VifNflushnOI_x§Output to a file is normally buffered. The buffer is automatically emptied by ->close. If the buffer is to be written to file without closing the file, use ->flush.nnnnnsNM.file.G.read_lineOI`xNM.file.G.read_lineRIOIax*Ā˜žN read_linenOIbxReads the next line of input from the file and returns this in a string object. The string contains the trailing newline character of the line. See `string ->strip'. If the last line is not closed with a newline, a string *without* trailing newline is returned.OIcxIEN M.file.G.readXnOIdx]Fails with error message on file errors. Fails silently when the end of the file is reached.nnsNM.file.S.is_absoluteOIexNM.file.S.is_absoluteRIOIfx0ĸ.™N is_absolutenOIgxčTest if <-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 :. For Unix systems if it starts with '/'.nnnnnsNM.file.G.objectOIhxNM.file.G.objectRIOIix.‡ãōNobjectnOIjx×Load object from file created with `object ->save_in_file'. Whether a file contains a saved object may be tested using `file ->check_object'. Loading objects from a file is an alternative way of creating objects and thus activates the classes mechanism to keep track of created instances. See `class <-created_messages'. The object may have been saved with an older version of PCE with an incompatible data definition (i.e. other classes or classes with different slots). The method `object ->save_in_file' saves -before saving any instances of a class- a description of the class. This description contains the name of the class and the attribute-names stored. When the object-base is reloaded, the following checks are made: * If the `pce <-save_version' does not match the file's save version, a message will be printed and the system enters a `careful' loading-mode. Careful loading is also enabled if `pce <-debugging' is @on. * When careful loading is enabled, each loaded slot value is given to the type-checker, which will print a message when it failed to convert the type. * if a slot cannot be found a diagnostic message is printed. For each instance loaded, the new instance will be sent a message `object ->convert_old_slot: name, any', where `name' is the name of the deleted slot and any is the saved value of the slot. * If a class cannot be found, a diagnostic message is printed and each instance of this class found will be translated to a sheet object with attributes for the defined slots. The attribute `class_name' is added and filled with the name of the disappeared class. * If the entire object is loaded and careful loading is enabled, the loaded object is verified: * First `object ->convert_loaded_object: int, int' is sent to the object where the integers represent the old and new save-version. * For each slot that has an unsatisfactory value (according to its type declaration), a message `object ->initialise_new_slot: variable' will be send where variable is the variable object from the class. * Finally the system print a diagnostics message when the object is still not satisfying its class definition. The verification process may be compared to `object ->_check'.OIkxIeN$errors$!.bad_fileeNM.file.S.check_objectEN%$class/object$M.object.S.save_in_fileXnOIlx!Many, hopefully self-explanatory.nOImxŗWhen loading old version, the system easily crashes. Various standard operations should be added to the conversion mechanism. For example renamed classes and instance variables.sNM.file.S.backupOInxNM.file.S.backupRIOIox,VhŪNbackupnOIpxMIf the file ->exists, it is copied to a file named <-name concatenated with `extension' (default `~'). The file object itself is not affected. This method may be used in combination with ->open: write or `object ->save_in_file'. save_diagram(Picture, File) :- send(File, backup), send(Picture?graphicals, save_in_file, File).OIqxIEN$errors$!.backup_fileXnnnnsNM.file.S.formatOIrxNM.file.S.formatRIOIsx*Ā‹ũNformatnOItxŠCreate a string by formatting the arguments and ->append the result to the file. See `string ->format' for a specification of the format.OIuxIeNM.file.S.newlineENM.file.S.appendXnnnOIvxQIf the total output exceeds FORMATSIZE (currently 10000) characters, PCE crashes.sN V.file.pathOIwxN V.file.pathRIOIxx-^J`NpathnOIyxīThis variable holds the full path name of the file after ->absolute_path or ->find. The Unix file opened is the name of this variable when not @default and <-name after expansion of `~' and $var constructs if this variable holds @defaultnnnsN M.file.S.seekOIzxN M.file.S.seekRIOI{x,VjŽNseeknOI|xėMoves the file-pointer to the indicated location. The argument is relative to the start of the file, the current position (<-index) or the end of the file. The file must be open and must be a regular file not opened through a <-filter.OI}xIENM.file.G.indexXnnnnsN M.file.S.sameOI~xN M.file.S.sameRIOIx:­<ÕNsamenOI€xĶ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. See also `directory->same'.nnnnnsN V.file.nameOIxN V.file.nameRIOI‚x-^JÉNnamenOIƒxÖName of the (Unix) file. Filled from the first argument of ->initialise . When the name is changed and the file already exists, the Unix file is renamed accordingly. ->name cannot move files across file-systems.OI„xIeNM.file.G.base_nameeNM.file.G.directory_nameEN M.file.S.nameXnnsNC.fileCman_class_card identifiermodule last_modifiednamesummary descriptionsee_alsoinherituser_interfacebugsOI…xNC.fileRIOI†x0oôÂNfilenOI‡x*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 <-name, which may hold the Unix constructs `~', `~loginname' and $var. A file can be searched in a `search-path' using ->find. It may be translated to an absolute filename using ->absolute_path, which writes the variable <-path after successful translation. Class file defines the `class->has_feature's 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.OIˆxIeN$class/directory$C.directoryEN$class/date$C.dateXnnnsNM.file.G.indexOI‰xNM.file.G.indexRIOIŠx5Ŗo=NindexnOI‹x`Returns the current value of the read- or write-pointer. This pointer may be set using ->seek.OIŒxIEN M.file.S.seekXnOIx*Gives a warning if the file is not opened.nnsNM.file.S.initialiseOIŽxNM.file.S.initialiseRIOIxAŪvÚN initialisenOIxœ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: var' `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 ->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.nnnnnsN M.file.S.nameOI‘xN M.file.S.nameRIOI’x*Ā~NnamennOI“xIEN V.file.nameXnnnnsNM.file.S.appendOI”xNM.file.S.appendRIOI•x*Ā‚aNappendnOI–xaAppend the argument text to the file. The argument text is not interpreted. See also ->format.OI—xIENM.file.S.formatXnnnnXaCnumber O I˜xx