16.2 Obarrays

The identity of symbols with their names is accomplished through a structure called an obarray, which is just a poorly-implemented hash table mapping from strings to symbols whose name is that string. (I say “poorly implemented” because an obarray appears in Lisp as a vector with some hidden fields rather than as its own opaque type. This is an Emacs Lisp artifact that should be fixed.)

Obarrays are implemented as a vector of some fixed size (which should be a prime for best results), where each “bucket” of the vector contains one or more symbols, threaded through a hidden next field in the symbol. Lookup of a symbol in an obarray, and adding a symbol to an obarray, is accomplished through standard hash-table techniques.

The standard Lisp function for working with symbols and obarrays is intern. This looks up a symbol in an obarray given its name; if it’s not found, a new symbol is automatically created with the specified name, added to the obarray, and returned. This is what happens when the Lisp reader encounters a symbol (or more precisely, encounters the name of a symbol) in some text that it is reading. There is a standard obarray called obarray that is used for this purpose, although the Lisp programmer is free to create his own obarrays and intern symbols in them.

Note that, once a symbol is in an obarray, it stays there until something is done about it, and the standard obarray obarray always stays around, so once you use any particular variable name, a corresponding symbol will stay around in obarray until you exit SXEmacs.

Note that obarray itself is a variable, and as such there is a symbol in obarray whose name is "obarray" and which contains obarray as its value.

Note also that this call to intern occurs only when in the Lisp reader, not when the code is executed (at which point the symbol is already around, stored as such in the definition of the function).

You can create your own obarray using make-vector (this is horrible but is an artifact) and intern symbols into that obarray. Doing that will result in two or more symbols with the same name. However, at most one of these symbols is in the standard obarray: You cannot have two symbols of the same name in any particular obarray. Note that you cannot add a symbol to an obarray in any fashion other than using intern: i.e. you can’t take an existing symbol and put it in an existing obarray. Nor can you change the name of an existing symbol. (Since obarrays are vectors, you can violate the consistency of things by storing directly into the vector, but let’s ignore that possibility.)

Usually symbols are created by intern, but if you really want, you can explicitly create a symbol using make-symbol, giving it some name. The resulting symbol is not in any obarray (i.e. it is uninterned), and you can’t add it to any obarray. Therefore its primary purpose is as a symbol to use in macros to avoid namespace pollution. It can also be used as a carrier of information, but cons cells could probably be used just as well.

You can also use intern-soft to look up a symbol but not create a new one, and unintern to remove a symbol from an obarray. This returns the removed symbol. (Remember: You can’t put the symbol back into any obarray.) Finally, mapatoms maps over all of the symbols in an obarray.