def-external-format

Macro

Package: excl

Arguments: name &key nicknames size

name should be a symbol, nicknames a list of symbols, and size should be 1 (which is the default).

This macro defines name as an external-format. If name already names an existing external-format, then that external-format is modified to have its nicknames and/or size slots set to nicknames and size specified in the call to def-external-format. A slot is only modified in this call if it is specified in the call to def-external-format.

In Allegro CL 6.0, the size argument should be 1 (the default). The argument is here for future use. The only external format with a larger size supported in Allegro CL is :fat/:unicode, which is already defined.

An error is signaled if any of the symbols specified in nicknames is a nickname to an external-format other than that being defined or modified.

Example:

(def-external-format :utf-8 :nicknames '(:utf8))

Here is an overview of how external-formats are used:

The main purpose for the external-format object is as a place to store Lisp coded procedures for translating octets in external representation to/from lisp strings. In order to use these routines as efficiently as possible, the translation procedures are defined as macros. The effect is that with these macros, the code to translate octets to and from characters is directly mixed in with the code to retrieve/store octets/characters. The macros themselves take as arguments expressions to get/put the next octet or character to translate. The return value of the macros' expansions are the number of octets or characters translated. (See def-char-to-octets-macro and def-octets-to-char-macro.)

Some external-formats may be composed with other external-formats to form new external-formats. For example, a wrapper external-format may be defined which combines external bytes representing 'f' and 'i' to create #\latin_small_ligature_fi. This wrapper external-format could be composed with the utf8 external-format to create a ligature-utf8 external-format. The wrapper external-format could also be composed with the euc external-format to create a ligature-euc external-format. Wrapped or composed external-formats are created using the compose-external-formats operator.

See iacl.htm for more information on international character support in Allegro CL.

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

Created 2000.10.5.