find-external-format

Function

Package: excl

Arguments: name &key (errorp t) (load-prebuilt t) try-variant

name should be a symbol. This function returns the external format object whose name or one of whose nicknames is name. If no such external-format exists, then an attempt is made to autoload the external-format by performing the following:

(ignore-errors (require :ef-[name]))

where [name] is name.

When name is :default, find-external-format returns the external-format associated with *locale* (the current locale, see Locales in iacl.htm).

If the attempt to autoload fails, the behavior is controlled by the errorp keyword argument. If its value is true (which is the default), then if the attempt to autoload fails, an error, of condition type no-external-format-error, is signaled. If errorp is false, then find-external-format returns nil if the attempt to autoload fails.

If the value of the load-prebuilt is true (which is the default), then if an external-format matching name is located and/or successfully loaded, find-external-format will also autoload Allegro CL system code corresponding to the external-format. Such code is referred to as prefilled-ef-template code (see generate-filled-ef-templates), and its inclusion in the lisp eliminates the need for the external-format convertors. If the prefilled-ef-template code is successfully loaded by find-external-format, then find-external-format calls switch-ef-to-runtime on the external-format to discard the external-format's convertor macros as well as structures needed by the convertors.

If the value of the try-variant is true (the default is nil), then if find-external-format is unable to find an external-format that exactly matches the passed in name argument, or if find-external-format is unable to find an external-format whose nickname includes the specified name argument, then it will try variants on the specified name argument. See the example below. Note that we do not document the rules for try-variant and updates and/or patches may change them.

Examples:

(def-external-format :utf-8 :nicknames '(:utf8))
(find-external-format :utf8) --> #<external-format :utf-8 @ #x208662d>>
(find-external-format :utf-8) --> #<external-format :utf-8 @ #x208662d2>>

Here is an example using the try-variant argument.

;; This example assumes that only those external-formats 
;; included with the release are available

(find-external-format :iso-8859_1 :try-variant nil)
-> nil
;; returns false when :iso-8859_1 doesn't match an existing or
;; autoloadable external-format. But 

(find-external-format :iso-8859_1 :try-variant t)
-><the iso8859-1 external-format>
;; returns the iso8859-1 external-format since 
;; find-external-format tries some known variants to produce 
;; possible matching external-format names.

See iacl.htm for more information on international character support in Allegro CL. See particularly External-Format Overview and Retrieving Existing External-Formats in that document.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.