Putting Keyboard Events in Strings

In most of the places where strings are used, we conceptualize the string as containing text characters--the same kind of characters found in buffers or files. Occasionally Lisp programs use strings that conceptually contain keyboard characters; for example, they may be key sequences or keyboard macro definitions. There are special rules for how to put keyboard characters into a string, because they are not limited to the range of 0 to 255 as text characters are.

A keyboard character typed using the META key is called a meta character. The numeric code for such an event includes the $2^{27}$ bit; it does not even come close to fitting in a string. However, earlier Emacs versions used a different representation for these characters, which gave them codes in the range of 128 to 255. That did fit in a string, and many Lisp programs contain string constants that use `\M-' to express meta characters, especially as the argument to define-key and similar functions.

We provide backward compatibility to run those programs using special rules for how to put a keyboard character event in a string. Here are the rules:

• If the keyboard character value is in the range of 0 to 127, it can go in the string unchanged.
• The meta variants of those characters, with codes in the range of $2^{27}$ to $2^{27} + 127$, can also go in the string, but you must change their numeric values. You must set the $2^{7}$ bit instead of the $2^{27}$ bit, resulting in a value between 128 and 255.
• Other keyboard character events cannot fit in a string. This includes keyboard events in the range of 128 to 255.

Functions such as read-key-sequence that can construct strings of keyboard input characters follow these rules. They construct vectors instead of strings, when the events won't fit in a string.

When you use the read syntax `\M-' in a string, it produces a code in the range of 128 to 255--the same code that you get if you modify the corresponding keyboard event to put it in the string. Thus, meta events in strings work consistently regardless of how they get into the strings.

The reason we changed the representation of meta characters as keyboard events is to make room for basic character codes beyond 127, and support meta variants of such larger character codes.

New programs can avoid dealing with these special compatibility rules by using vectors instead of strings for key sequences when there is any possibility that they might contain meta characters, and by using listify-key-sequence to access a string of events.

Function: listify-key-sequence key

This function converts the string or vector key to a list of events, which you can put in unread-command-events. Converting a vector is simple, but converting a string is tricky because of the special representation used for meta characters in a string.

Go to the first, previous, next, last section, table of contents.