FunctionPackage: exclToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 10.1
Unrevised from 10.0 to 10.1.
10.0 version


Arguments: new-mode &key (adjust-readtables-case t)

This function sets the case mode of Lisp to that specified by the new-mode argument. The value of that argument must be one of the following three keywords:

set-case-mode converts the running Lisp to use the new mode for subsequent reading and returns a keyword denoting the previous mode. This function must do quite a bit of consistency checking when changing between modes with different case preferences, and may take as long as several minutes to complete. As we say below, it is much better to use an image with the desired case mode rather than changing the case mode after the image has started.

Note that the typical case mode is :case-sensitive-lower. Allegro CL is distributed with modern (:case-sensitive-lower) images (named mlisp and mlisp8) and ANSI (:case-insensitive-upper) images (named alisp and alisp8). Rather than changing case mode after starting, it is best to start the image with the desired case mode.

The :adjust-readtables-case argument

In releases prior to 6.1, Allegro CL ignored readtable-case in all case modes except :case-insensitive-upper (the ANSI mode). Starting in release 6.1 of Allegro CL, readtable-case is not ignored unless set-case-mode is called with a case-mode other than :case-insensitive-upper and adjust-readtables-case specified nil.

The adjust-readtables-case keyword argument to set-case-mode allows control of ignoring or not ignoring readtable-case in non-ANSI modes.

The default setting of adjust-readtables-case is t. The value t has two effects: (1) it ensures that readtable-case is not ignored; and (2) it modifies the readtable-case of existing readtables as described next.

When adjust-readtables-case is true, set-case-mode sets the readtable-case of the Lisp standard readtable and other readtables listed below to the appropriate value for the new case-mode, which is shown in the table below. Along with the Lisp standard readtable, all existing readtables except for those readtables which have previously been modified by (setf readtable-case) are affected.

This table shows the set-case-mode effect when adjust-readtables-case is true (the action on symbol names assumes that mixed-case symbols are converted, which they are by default. See convert-mixed-case-symbols).

new-mode action on symbol-names readtable-case setting
:case-insensitive-upper (ANSI mode) symbol names are upcased :upcase
:case-sensitive-lower (Modern mode) symbol names are downcased :preserve
:case-insensitive-lower symbol names are downcased :downcase

In rare cases, some code's behavior may be affected by the updated casemode behavior. For such code, the previous Allegro CL behavior can be restored with the following call:

(excl:set-case-mode excl:*current-case-mode* :adjust-readtables-case nil)

As described above, that call causes readtable-case to be ignored in non-ANSI modes.

The code most likely to be affected will be that which depends on prior symbol printing while in the less frequently used case-insensitive-lower casemode. While specific code instances may need further analysis, generally adding *print-case* bindings in such places is a completely adequate and portable fix; and is preferable to using set-case-mode for restoring prior Allegro CL behavior.

Issues with changing the case mode after startup

If CLX has been loaded into Lisp, you cannot change the case mode at all with this function. Unfortunately, no error is signaled but problems will occur later. Note that both Allegro Composer and Allegro Common Windows (both only available on Unix) use CLX.

This function can be called at any time but should, if possible, be called as the first action in a fresh invocation of Lisp (and better would be to use the image with the desired case mode and do not use this function at all). This function takes a lot of time and uses a lot of space, so should never be called in a loop.

Note that the system will not be able to resolve conflicts if case mode is changed after Lisp has been running for some time. However, sometimes it is necessary to change case modes more than once. Suppose you want to work in case-sensitive, lowercase preferred mode but need to load files written for a standard (case-insensitive, uppercase) Lisp. You might first set the mode to :case-insensitive-lower, load the files, and then set the mode to the desired :case-sensitive-lower.

Since set-case-mode alters the names of symbols in the currently running lisp environment, users are advised not to use this function lightly as it may introduce subtle problems. The following Lisp session illustrates:

The initial set of commands establishes state and demonstrates that case is preserved by the reader in a case-sensitive-lower (modern-mode) lisp:

cl-user(1): (defparameter mixed-sym-name "aBc")
cl-user(2): (defparameter mixed-sym (read-from-string mixed-sym-name))
cl-user(3): mixed-sym
cl-user(4): (eq mixed-sym (read-from-string mixed-sym-name))

The subsequent set of commands demonstrates that taking a round-trip through case-mode conversions (from modern-mode to ansi-mode back to modern-mode) affects the lisp environment. We assume convert-mixed-case-symbols returns true.

cl-user(5): (set-case-mode :case-insensitive-upper)
CL-USER(6): (set-case-mode :case-sensitive-lower)
cl-user(7): mixed-sym
cl-user(8): (eq mixed-sym (read-from-string mixed-sym-name))

See also case.htm, *current-case-mode*, *ignore-package-name-case*, and convert-mixed-case-symbols.

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

Allegro CL version 10.1
Unrevised from 10.0 to 10.1.
10.0 version