external-format-for-save

Arguments: text-edit-pane

This function is meaningful only on the Windows platform, and will return nil elsewhere.

If load-file has been used to load a file into a text-edit-pane, then this function will return the name of the external format that the file was deemed to have, if any, or otherwise the keyword :default. If load-file has not been called on text-edit-pane, then nil is returned.

If load-file has been called on text-edit-pane, then save-file will save the file in this same format, unless the external-format-for-saved-files configuration option is :ask-always (in which case save-file will always ask the user for the format to use).

The only base external format names that might be returned are :unicode (for little-endian 16-bit Unicode), :utf8, :default, or nil when no file has been loaded. These are determined by load-file by checking the byte order marker (BOM) at the beginning of the file, if there is one. If there is no BOM, then :unicode will still be returned if there were any embedded zero bytes in the file, on the assumption that this indicates a Unicode file that has no BOM (though such a file wouldn't necessarily contain any zero bytes.)

When :default is returned, it means that the file was not determined to have either Unicode or UTF8 encoding, and so load-file simply assumed that the file's format matches the external format of the locale with which the Windows operating system is currently booted, and load-file therefore read the file using that external format even though it may not have matched the file's actual format.

The setf of this function could be called to change the external format that save-file would later use. In particular, if a text-edit-pane is reused to begin editing text for a new file, as with a File | New command in an application, then you could set the value to nil to make save-file treat the text as it would the text in a new text-edit-pane.

In the IDE's source code editor, this value can be changed for a particular buffer by typing Control-Shift-CloseSquareBracket, which will display a pop-up menu for selecting either Default, Unicode, or UTF8. (This keystroke is listed in the Help | Shortcut Keys dialog as select-external-format-for-save.) Also, the IDE's status bar will indicate the current format for a buffer when you open a file or switch to a different editor buffer.

See also external-format-for-saved-files and excl:*use-unicode-winapi-for-cg*. The configuration option write-bom-to-utf8-files controls whether save-file will write UTF8 byte order marker (BOM) bytes at the beginning of the file, if the file is being saved in UTF8 format.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page is new in the 9.0 release.
Created 2019.8.20.