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 3.5.6 Miscellaneous file operations. Commands use to print, insert, delete and rename files are covered here, along with many others.
Arguments: pathname
Key sequence: None
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 nil, cl:open chooses the external format to use. The external format is remembered for subsequent reading and writing of the buffer, and its name is displayed in the mode line.
If the file is already being visited a new buffer is not created, but the buffer already containing the contents of that file is displayed instead.
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.
If there is no prefix argument, a new Editor window is created for the file. With any prefix argument, the file is shown in the current window.
Another version of this command is Wfind File which is usually used for finding files.
Arguments: pathname
Key sequence: Ctrl+X Ctrl+F pathname
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).
Arguments: pathname
Key sequence: None
editor:visit-file-command p &optional pathname buffer
Does the same as Find Alternate File, and then sets the buffer to be writable.
Find Alternate File Editor Command
Arguments: pathname
Key sequence: Ctrl+X Ctrl+V pathname
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.
The argument buffer is the buffer in which the contents of the file are to be displayed. buffer defaults to the current buffer.
The prefix argument is ignored.
Arguments: None
Key sequence: Ctrl+X Ctrl+S
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 nil.
The argument buffer is the buffer to be saved in its associated file. The default is the current buffer.
Arguments: None
Key sequence: Ctrl+X S
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.
save-all-files-confirm Editor Variable
Default value: t
When the value is true, Save All Files prompts for confirmation before writing the modified buffers, when used without a prefix argument.
Arguments: pathname
Key sequence: Ctrl+X Ctrl+W pathname
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.
The argument buffer is the name of the buffer whose contents are to be written. The default is the current buffer.
Arguments: pathname
Key sequence: None
editor:write-region-command p &optional pathname
Writes the region between the mark and the current point to the file defined by pathname. If the file already exists, it is overwritten. If the file does not exist, it is created.
Arguments: pathname
Key sequence: None
Appends the region between the mark and the current point to the file defined by pathname. If the file does not exist, it is created.
Arguments: pathname
Key sequence: None
Writes the contents of the current buffer to the file defined by pathname. If the file already exists, it is overwritten. If it does not exist, it is created.
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.
Save All Files and Exit Editor Command
Arguments: None
Key sequence: Ctrl+X Ctrl+C
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.
add-newline-at-eof-on-writing-file Editor Variable
Default value: :ask-user
Controls whether the commands Save File and Write File add a newline at the end of the file if the last line is non-empty.
If the value of this variable is t then the commands add a newline and tell the user.
If the value is nil the commands never add a newline.
If the value is :ask-user, the commands ask whether to add a newline.
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 :utf-16 or :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.
See 26.6 External Formats to translate Lisp characters from/to external encodings in the LispWorks® User Guide and Reference Manual for a description of external format specifications.
Compatibility Note: 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 Editor Command
Arguments: None
Key sequence: None
The command 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.
This external format is also used when subsequently saving the file.
Set External Format Editor Command
Arguments: buffer
Key sequence: None
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.
input-format-default Editor Variable
Default value: nil
The default external format used by Find File, Wfind File and Visit File for reading files into buffers.
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.
The value should be nil or an external format specification. See 26.6 External Formats to translate Lisp characters from/to external encodings in the LispWorks® User Guide and Reference Manual for a description of these and of how cl:open chooses an external format.
If you have specified an input encoding via the Editor tool's Preferences dialog, then input-format-default is initialized to that value on startup.
output-format-default Editor Variable
Default value: nil
The default external format used for writing buffers to files.
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.
The value should be nil or an external format specification. See 26.6 External Formats to translate Lisp characters from/to external encodings in the LispWorks® User Guide and Reference Manual for a description of these and of how cl:open chooses an external format.
If you have specified an output encoding via the Editor tool's Preferences dialog, then output-format-default is initialized to that value on startup.
The default value of output-format-default is nil.
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.
In particular if your buffer contains a cl:extended-char char then Latin-1 and other encodings which support only cl:base-char are not appropriate.
There are two ways to resolve this:
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 :shift-jis or :gbk. Or you may want a Latin-1 encoded file, in which case you could supply :latin-1-safe.
Find Unwritable Character Editor Command
Arguments: None
Key sequence: None
Finds the next occurrence of a character in the current buffer that cannot be written using the buffer external format. The prefix argument is ignored.
List Unwritable Characters Editor Command
Arguments: None
Key sequence: None
Lists the characters in the current buffer that cannot be written with the buffer external format. The prefix argument is ignored.
Find Non-Base-Char Editor Command
Arguments: None
Key sequence: None
The command Find Non-Base-Char finds the next character in the current buffer that is not a cl:base-char, starting from the current point.
The auto-save feature allows for periodic backups of the file associated with the current buffer. These backups are only made if auto-save is switched on.
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, automatic backups are made both after a predefined number of key strokes, and also after a predefined amount of time has elapsed.
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 # characters.
Toggle Auto Save Editor Command
Arguments: None
Key sequence: None
Switches auto-save on if it is currently off, and off if it is currently on.
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 Toggle is a synonym for Toggle 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.
default-auto-save-on Editor Variable
Default value: t
The default auto-save state of new buffers.
auto-save-filename-pattern Editor Variable
Default value: "~A#~A#"
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.
The default value causes the auto-save file to be created in the same directory as the file for which it is a backup, and with the name surrounded by # characters.
auto-save-key-count-threshold Editor Variable
Default value: 256
Specifies the number of destructive/modifying keystrokes that automatically trigger an auto-save of a buffer. If the value is nil, this feature is turned off.
auto-save-checkpoint-frequency Editor Variable
Default value: 300
Specifies the time interval in seconds after which all modified buffers which are in "Save" mode are auto-saved. If the value is nil, zero or negative, this feature is turned off.
auto-save-cleanup-checkpoints Editor Variable
Default value: t.
This variable controls whether an auto-save function will cleanup by deleting the checkpoint file for a buffer after it is saved. If the value is true then this cleanup will occur.
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 ~ character.
backups-wanted Editor Variable
Default value: t
Controls whether to make a backup copy of a file the first time it is modified. If the value is t, a backups is automatically made on first saving. If the value is nil, no backup is made.
backup-filename-suffix Editor Variable
Default value: #\~
This variable contains the character used as a suffix for backup files. By default, this is the tilde (~) character.
backup-filename-pattern Editor Variable
Default value: "~A~A~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.
The backup file is created in the same directory as the file for which it is a backup, and it has the same name, followed by the backup-filename-suffix.
Note that the backup-suffix can be changed functionally as well as by interactive means. For example, the following code changes the suffix to the @ character:
(setf (editor:variable-value `editor:backup-filename-suffix
:current nil) #\@)
Arguments: file
Key sequence: None
Prints file, using capi:print-file. See the CAPI User Guide and Reference Manual for details of this function.
Arguments: None
Key sequence: None
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-confirm is t then Revert Buffer asks for confirmation before reverting to a previous state.
Any prefix argument forces Revert Buffer to use the last explicitly saved version.
Revert Buffer With External Format Editor Command
Arguments: None.
Key sequence: None.
Sets the external format of the current buffer and then revert it to the state when it was last saved. This command is equivalent to doing Set External Format followed by Revert Buffer, but it checks if the buffer has been modified and that the file exists before setting the external format.
The prefix is used the same way as in Revert Buffer.
revert-buffer-confirm Editor Variable
Default value: t
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.
Process File Options Editor Command
Arguments: None
Key sequence: None
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 3.26 Modes.
Arguments: pathname
Key sequence: Ctrl+X I pathname
editor:insert-file-command p &optional pathname buffer
Inserts the file defined by pathname into the current buffer at the current point.
The argument buffer is the buffer in which the file is to be inserted.
Arguments: pathname
Key sequence: None
Deletes the file defined by pathname. The user is asked for confirmation before the file is deleted.
Delete File and Kill Buffer Editor Command
Arguments: buffer
Key sequence: None
editor:delete-file-and-kill-buffer-command p &optional buffer
After confirmation from the user, this deletes the file associated with buffer and then kills the buffer.
Arguments: file new-file-name
Key sequence: None
Changes the name of file to new-file-name.
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.
Arguments: None
Key sequence: None
Prompts the user for a directory name and makes it in the filesystem.
The prefix argument is ignored.
Arguments: None
Key sequence: Ctrl+X D
The command List Directory prompts for a directory or wild filename and finds or creates a buffer which lists files and allows you to operate on them easily.
See 3.7 Directory mode for detailed information about Directory mode.
Save Buffer Pathname Editor Command
Arguments: None
Key sequence: None
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 3.12 Inserting text.
Editor User Guide (Macintosh version) - 01 Dec 2021 19:35:09