This section contains details of commands used for file handling.
The first section provides details on commands used to copy the contents of a file into a buffer for editing, while the second deals with copying the contents of buffers to files.
You may at some point have seen file names either enclosed in
# characters or followed by a
~ character. These files are created by the editor as backups for the file named. The third section deals with periodic backups (producing file names enclosed in
#) and the fourth with backups on file saving (producing files followed by
There are many file handling commands which cannot be pigeon-holed so neatly and these are found in the section Miscellaneous file operations. Commands use to print, insert, delete and rename files are covered here, along with many others.
editor:find-file-command p &optional pathname
Finds a new buffer with the same name as pathname (where pathname is the name of the file to be found, including its directory relative to the current directory), creating it if necessary, and inserts the contents of the file into the buffer. The contents of the buffer are displayed in an editor pane and may then be edited.
The file is initially read in the external format (encoding) given by the editor variable input-format-default. If the value of this is
cl:open chooses the external format to use. The external format is remembered for subsequent reading and writing of the buffer.
If a file with the specified name does not exist, an empty buffer with that file name is created for editing purposes, but the new file is not created until the appropriate save file command is issued.
Another version of this command is Wfind File
editor:wfind-file-command p &optional pathname
Calls Find File with a prefix argument (that is, the new file is opened in the existing window).
editor:visit-file-command p &optional pathname buffer
Does the same as Find Alternate File, and then sets the buffer to be writable.
editor:find-alternate-file-command p &optional pathname buffer
Does the same as Find File with a prefix argument, but kills the current buffer and replaces it with the newly created buffer containing the file requested. If the contents of the buffer to be killed have been modified, the user is asked if the changes are to be saved to file.
editor:save-file-command p &optional buffer
Saves the contents of the current buffer to the associated file. If there is no associated file, one is created with the same name as the buffer, and written in the same encoding as specified by the editor variable output-format-default, or as defaulted by
open if this is
Without a prefix argument, a Select Buffers To Save: dialog is displayed asking whether each modified buffer is to be saved. If a buffer has no associated file it is ignored, even if it is modified. The selected buffers are saved.
With a non-nil prefix argument, no such dialog is displayed and all buffers that need saving are saved. You can also prevent the Select Buffers To Save: dialog from being displayed by setting the value of the editor variable save-all-files-confirm.
When the value is true, Save All Files prompts for confirmation before writing the modified buffers, when used without a prefix argument.
editor:write-file-command p &optional pathname buffer
Writes the contents of the current buffer to the file defined by pathname. If the file already exists, it is overwritten. If the file does not exist, it is created. The buffer then becomes associated with the new file.
editor:write-region-command p &optional pathname
In contrast with Write File, no change is made concerning the file associated with the current buffer as this command is only intended to be used to write the contents of the current buffer to a backup file.
A Select Buffers To Save: dialog is displayed asking whether each modified buffer is to be saved. If a buffer has no associated file it is ignored, even if it is modified (this operates just like Save All Files). When all the required buffers have been saved LispWorks exits, prompting for confirmation first.
The editor supports the entire Unicode range, and provided that the system has suitable fonts it should be able to display all the characters correctly. Normally you should not be able to have a character object corresponding to a surrogate code point (these codes are the exclusive range
(#xd800, #xdfff)). If such an object is inserted, the editor displays its hexadecimal value.
An editor buffer ideally should have an appropriate external format (or encoding) set before you write it to a file. Otherwise an external format specified in the value of the editor variable output-format-default is used. If the value of output-format-default is not an external format specifier, then the external format is chosen similarly to the way
cl:open does it. By default this chosen external format will be the Windows code page on Microsoft Windows, and Latin-1 on other platforms.
When using the Editor tool, use Set External Format to set interactively the external format for the current buffer, or set Preferences... > Environment > File Encodings > Output (which in turn sets the editor variable output-format-default) to provide a global default value. You can also use Find File With External Format to specify the external format before reading a file.
In situations where you want to open a file in a 16-bit encoding but the file is not actually encoded properly (for example it is actually a binary containing some strings encoded in
:utf-16), use one of the
:bmp external formats with the parameter
:use-replacement t, for example:
(:utf-16 :use-replacement t)
These external formats will replace any input that causes errors by the replacement character (code point
#xfffd), and should successfully read correctly encoded
:utf-16 strings including supplementary characters.
If you need to edit a file that is not properly encoded, the only external format that can do this is
:latin-1. To insert a multi-byte character, you will have to insert the
:latin-1 characters matching the individual bytes in the right order.
In LispWorks 6.1 and earlier versions,
:unicode is the best choice of external format for opening an incorrectly-encoded file. However, in LispWorks 7.0 and later versions
:unicode maps to
:utf-16 which is quite likely to give an error trying to read a binary file, unless you supply
:use-replacement t as described above. The error would occur when it sees a 16-bit value which is a surrogate code point.
Find File With External Format prompts for an external format, and then opens the file as as if by Wfind File, with the supplied external format.
Prompts for an external format specification, providing a default which is the buffer's current external format if set, or the value of output-format-default. Sets the buffer's external format, so that this is used for subsequent file writing and reading.
If a non-nil prefix argument is supplied, the buffer's external format is set to the value of output-format-default without prompting.
If the buffer already has an external format (either it has previously been read from a file, or Set External Format has been used to specify an external format) then
input-format-default is ignored. If the value is
nil and the buffer does not have an external format,
cl:open chooses the external format to use.
If the buffer already has an external format (either it has been read from a file, or Set External Format has been used to specify an external format) then
output-format-default is ignored. If the value is
nil and the buffer does not have an external format,
cl:open chooses the external format to use.
If your buffer contains a character char which cannot be encoded in the buffer's external format (or the defaulted external format) then attempts to save the buffer will signal an error giving the character name, its offset in the buffer and explaining that char is unwritable in the external format.
You may want a file which is Unicode UTF-16 encoded (external format
:unicode), UTF-8 encoding (
:utf-8) or a language-specific encoding such as
:gbk. Or you may want a Latin-1 encoded file, in which case you could supply
This feature is useful if the LispWorks editor is killed in some way (for example, in the case of a system crash or accidental killing of the editor process) before a file is explicitly saved. If automatic backups are being made, the state of a file when it was last auto-saved can subsequently be recovered.
By default, auto-saved files are in the same directory as the original file, with the name of the auto-save file (or "checkpoint file") being the name of the original file enclosed within
With a positive prefix argument, auto-save is switched on. With a negative or zero prefix argument, auto-save is switched off. Using prefix arguments with
Toggle Auto Save disregards the current state of auto-save.
auto-save is initially on or off in a new buffer according to the value of the editor variable default-auto-save-on.
This is a
format control string used to make the filename of the checkpoint file.
format is called with two arguments, the first being the directory namestring and the second being the file namestring of the default buffer pathname.
When a file is explicitly saved in the editor, a backup is automatically made by writing the old contents of the file to a backup before saving the new version of the file. The backup file appears in the same directory as the original file. By default its name is the same as the original file followed by a
This control string is used with the Common Lisp
format function to create the filename of the backup file.
format is called with three arguments, the first being the directory name-string and the second being the file name-string of the pathname associated with the buffer. The third is the value of the editor variable backup-filename-suffix.
If the current buffer is associated with a file, its contents revert to the state when it was last saved. If the buffer is not associated with a file, it is not possible for a previous state to be recovered.
If auto-save is on for the current buffer, the version of the file that is recovered is either that derived by means of an automatic save or by means of an explicit save, whichever is the most recent. If auto-save is off, the buffer reverts to its state when last explicitly saved.
If the buffer has been modified and the value of the variable
Revert Buffer asks for confirmation before reverting to a previous state.
When the command Revert Buffer is invoked, if the value of this variable is
t and the buffer has been modified then confirmation is requested before the revert operation is performed. If its value is
nil, no confirmation is asked for.
The attribute line at the top of the file is reprocessed, as if the file had just been read from disk. If no major mode is specified in the attribute line, the type of the file is used to determine the major mode. See Modes.
editor:insert-file-command p &optional pathname buffer
editor:delete-file-and-kill-buffer-command p &optional buffer
If you are currently editing the file to be renamed, the buffer remains unaltered, retaining the name associated with the old file even after renaming has taken place. If you then save the current buffer, it is saved to a file with the name of the buffer, that is, to a file with the old name.
See Directory mode for detailed information about Directory mode.
Pushes the namestring of the pathname of the current buffer onto the kill ring. This namestring can then be inserted elsewhere by commands which access the kill ring, described in Inserting text.
LispWorks Editor User Guide (Unix version) - 17 Aug 2017