find-external-format

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

name should be either a symbol naming an external-format or a list of (possibly nested) external-format names. 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 External formats and 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.

verbose binds *load-verbose* and defaults to t. When an external-format is switched to runtime mode a message is printed or not based on this variable.

Examples:

(pushnew ':new-utf8-nickname
         (ef-nicknames (find-external-format ':utf-8)))
(eq (find-external-format :utf-8) 
    (find-external-format :new-utf8-nickname)) --> t

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 :errorp 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. Note that you may
;; see a different external format identifier.

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.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.