Next: Defining Symbols, Up: Symbols   [Contents][Index]

9.1 Symbol Components ¶

Each symbol has four components (or “cells”), each of which references another object:

Print name ¶

The symbol’s name.

Value ¶

The symbol’s current value as a variable.

Function ¶

The symbol’s function definition. It can also hold a symbol, a keymap, or a keyboard macro.

Property list ¶

The symbol’s property list.

The print name cell always holds a string, and cannot be changed. Each of the other three cells can be set to any Lisp object.

The print name cell holds the string that is the name of a symbol. Since symbols are represented textually by their names, it is important not to have two symbols with the same name. The Lisp reader ensures this: every time it reads a symbol, it looks for an existing symbol with the specified name before it creates a new one. To get a symbol’s name, use the function symbol-name (see Creating and Interning Symbols). However, although each symbol has only one unique print name, it is nevertheless possible to refer to that same symbol via different alias names called “shorthands” (see Shorthands).

The value cell holds a symbol’s value as a variable, which is what you get if the symbol itself is evaluated as a Lisp expression. See Variables, for details about how values are set and retrieved, including complications such as local bindings and scoping rules. Most symbols can have any Lisp object as a value, but certain special symbols have values that cannot be changed; these include nil and t, and any symbol whose name starts with ‘:’ (those are called keywords). See Variables that Never Change.

The function cell holds a symbol’s function definition. Often, we refer to “the function foo” when we really mean the function stored in the function cell of foo; we make the distinction explicit only when necessary. Typically, the function cell is used to hold a function (see Functions) or a macro (see Macros). However, it can also be used to hold a symbol (see Symbol Function Indirection), keyboard macro (see Keyboard Macros), keymap (see Keymaps), or autoload object (see Autoloading). To get the contents of a symbol’s function cell, use the function symbol-function (see Accessing Function Cell Contents).

The property list cell normally should hold a correctly formatted property list. To get a symbol’s property list, use the function symbol-plist. See Symbol Properties.

The value cell may be void, which means that the cell does not reference any object. (This is not the same thing as holding the symbol void, nor the same as holding the symbol nil.) Examining a value cell that is void results in an error, such as ‘Symbol's value as variable is void’.

Because each symbol has separate value and function cells, the names of variables and functions do not conflict. For example, the symbol buffer-file-name has a value (the name of the file being visited in the current buffer) as well as a function definition (a primitive function that returns the name of the file):

buffer-file-name
     ⇒ "/gnu/elisp/symbols.texi"
(symbol-function 'buffer-file-name)
     ⇒ #<subr buffer-file-name>

Next: Creating and Interning Symbols, Previous: Symbol Components, Up: Symbols   [Contents][Index]

9.2 Defining Symbols ¶

A definition is a special kind of Lisp expression that announces your intention to use a symbol in a particular way. It typically specifies a value or meaning for the symbol for one kind of use, plus documentation for its meaning when used in this way. Thus, when you define a symbol as a variable, you can supply an initial value for the variable, plus documentation for the variable.

defvar and defconst are special forms that define a symbol as a global variable—a variable that can be accessed at any point in a Lisp program. See Variables, for details about variables. To define a customizable variable, use the defcustom macro, which also calls defvar as a subroutine (see Customization Settings).

In principle, you can assign a variable value to any symbol with setq, whether or not it has first been defined as a variable. However, you ought to write a variable definition for each global variable that you want to use; otherwise, your Lisp program may not act correctly if it is evaluated with lexical scoping enabled (see Scoping Rules for Variable Bindings).

defun defines a symbol as a function, creating a lambda expression and storing it in the function cell of the symbol. This lambda expression thus becomes the function definition of the symbol. (The term “function definition”, meaning the contents of the function cell, is derived from the idea that defun gives the symbol its definition as a function.) defsubst and defalias are two other ways of defining a function. See Functions.

defmacro defines a symbol as a macro. It creates a macro object and stores it in the function cell of the symbol. Note that a given symbol can be a macro or a function, but not both at once, because both macro and function definitions are kept in the function cell, and that cell can hold only one Lisp object at any given time. See Macros.

As previously noted, Emacs Lisp allows the same symbol to be defined both as a variable (e.g., with defvar) and as a function or macro (e.g., with defun). Such definitions do not conflict.

These definitions also act as guides for programming tools. For example, the C-h f and C-h v commands create help buffers containing links to the relevant variable, function, or macro definitions. See Name Help in The GNU Emacs Manual.

Next: Symbol Properties, Previous: Defining Symbols, Up: Symbols   [Contents][Index]

9.3 Creating and Interning Symbols ¶

To understand how symbols are created in GNU Emacs Lisp, you must know how Lisp reads them. Lisp must ensure that it finds the same symbol every time it reads the same sequence of characters in the same context. Failure to do so would cause complete confusion.

When the Lisp reader encounters a name that references a symbol in the source code, it looks up that name in a table called an obarray to find the symbol that the programmer meant. An obarray is an unordered container of symbols, indexed by name.

The Lisp reader also considers “shorthands”. If the programmer supplied them, this allows the reader to find a symbol even if its name isn’t present in its full form in the source code. See Shorthands.

If a symbol with the desired name is found, the reader uses that symbol. If the obarray does not contain a symbol with that name, the reader makes a new symbol and adds it to the obarray. Finding or adding a symbol with a certain name is called interning it, and the symbol is then called an interned symbol.

Interning ensures that each obarray has just one symbol with any particular name. Other like-named symbols may exist, but not in the same obarray. Thus, the reader gets the same symbols for the same names, as long as you keep reading with the same obarray.

Interning usually happens automatically in the reader, but sometimes other programs may want to do it. For example, after the M-x command obtains the command name as a string using the minibuffer, it then interns the string, to get the interned symbol with that name. As another example, a hypothetical telephone book program could intern the name of each looked up person’s name as a symbol, even if the obarray did not contain it, so that it could attach information to that new symbol, such as the last time someone looked it up.

No obarray contains all symbols; in fact, some symbols are not in any obarray. They are called uninterned symbols. An uninterned symbol has the same four cells as other symbols; however, the only way to gain access to it is by finding it in some other object or as the value of a variable. Uninterned symbols are sometimes useful in generating Lisp code, see below.

Common Lisp note: Unlike Common Lisp, Emacs Lisp does not provide for interning the same name in several different “packages”, thus creating multiple symbols with the same name but different packages. Emacs Lisp provides a different namespacing system called “shorthands” (see Shorthands).

Function: obarray-make &optional size ¶

This function creates and returns a new obarray. The optional size may be used to specify the number of symbols that it is expected to hold, but since obarrays grow automatically as needed, this rarely provides any benefit.

Function: obarrayp object ¶

This function returns t if object is an obarray, nil otherwise.

Most of the functions below take a name and sometimes an obarray as arguments. A wrong-type-argument error is signaled if the name is not a string, or if the obarray is not an obarray object.

Function: symbol-name symbol ¶

This function returns the string that is symbol’s name. For example:

(symbol-name 'foo)
     ⇒ "foo"

Warning: Never alter the string returned by that function. Doing that might make Emacs dysfunctional, and might even crash Emacs.

Creating an uninterned symbol is useful in generating Lisp code, because an uninterned symbol used as a variable in the code you generate cannot clash with any variables used in other Lisp programs.

Function: make-symbol name ¶

This function returns a newly-allocated, uninterned symbol whose name is name (which must be a string). Its value and function definition are void, and its property list is nil. In the example below, the value of sym is not eq to foo because it is a distinct uninterned symbol whose name is also ‘foo’.

(setq sym (make-symbol "foo"))
     ⇒ foo
(eq sym 'foo)
     ⇒ nil

Function: gensym &optional prefix ¶

This function returns a symbol using make-symbol, whose name is made by appending gensym-counter to prefix and incrementing that counter, guaranteeing that no two calls to this function will generate a symbol with the same name. The prefix defaults to "g".

To avoid problems when accidentally interning printed representation of generated code (see Printed Representation and Read Syntax), it is recommended to use gensym instead of make-symbol.

Function: intern name &optional obarray ¶

This function returns the interned symbol whose name is name. If there is no such symbol in the obarray obarray, intern creates a new one, adds it to the obarray, and returns it. If obarray is omitted, the value of the global variable obarray is used.

(setq sym (intern "foo"))
     ⇒ foo
(eq sym 'foo)
     ⇒ t

(setq sym1 (intern "foo" other-obarray))
     ⇒ foo
(eq sym1 'foo)
     ⇒ nil

Common Lisp note: In Common Lisp, you can intern an existing symbol in an obarray. In Emacs Lisp, you cannot do this, because the argument to intern must be a string, not a symbol.

Function: intern-soft name &optional obarray ¶

This function returns the symbol in obarray whose name is name, or nil if obarray has no symbol with that name. Therefore, you can use intern-soft to test whether a symbol with a given name is already interned. If obarray is omitted, the value of the global variable obarray is used.

The argument name may also be a symbol; in that case, the function returns name if name is interned in the specified obarray, and otherwise nil.

(intern-soft "frazzle")        ; No such symbol exists.
     ⇒ nil
(make-symbol "frazzle")        ; Create an uninterned one.
     ⇒ frazzle

(intern-soft "frazzle")        ; That one cannot be found.
     ⇒ nil

(setq sym (intern "frazzle"))  ; Create an interned one.
     ⇒ frazzle

(intern-soft "frazzle")        ; That one can be found!
     ⇒ frazzle

(eq sym 'frazzle)              ; And it is the same one.
     ⇒ t

Variable: obarray ¶

This variable is the standard obarray for use by intern and read.

Function: mapatoms function &optional obarray ¶

This function calls function once with each symbol in the obarray obarray. Then it returns nil. If obarray is omitted, it defaults to the value of obarray, the standard obarray for ordinary symbols.

(setq count 0)
     ⇒ 0
(defun count-syms (s)
  (setq count (1+ count)))
     ⇒ count-syms
(mapatoms 'count-syms)
     ⇒ nil
count
     ⇒ 1871

See documentation in Access to Documentation Strings, for another example using mapatoms.

Function: unintern symbol obarray ¶

This function deletes symbol from the obarray obarray. If symbol is not actually in the obarray, unintern does nothing. If obarray is nil, the current obarray is used.

If you provide a string instead of a symbol as symbol, it stands for a symbol name. Then unintern deletes the symbol (if any) in the obarray which has that name. If there is no such symbol, unintern does nothing.

If unintern does delete a symbol, it returns t. Otherwise it returns nil.

Function: obarray-clear obarray ¶

This function removes all symbols from obarray.

Next: Shorthands, Previous: Creating and Interning Symbols, Up: Symbols   [Contents][Index]

9.4 Symbol Properties ¶

A symbol may possess any number of symbol properties, which can be used to record miscellaneous information about the symbol. For example, when a symbol has a risky-local-variable property with a non-nil value, that means the variable which the symbol names is a risky file-local variable (see File Local Variables).

Each symbol’s properties and property values are stored in the symbol’s property list cell (see Symbol Components), in the form of a property list (see Property Lists).

• Accessing Symbol Properties
• Standard Symbol Properties

Next: Symbols with Position, Previous: Symbol Properties, Up: Symbols   [Contents][Index]

9.5 Shorthands ¶

The symbol shorthands, sometimes known as “renamed symbols”, are symbolic forms found in Lisp source. They’re just like regular symbolic forms, except that when the Lisp reader encounters them, it produces symbols which have a different and usually longer print name (see Symbol Components).

It is useful to think of shorthands as abbreviating the full names of intended symbols. Despite this, do not confuse shorthands with the Abbrev system (see Abbrevs and Abbrev Expansion).

Shorthands make Emacs Lisp’s namespacing etiquette easier to work with. Since all symbols are stored in a single obarray (see Creating and Interning Symbols), programmers commonly prefix each symbol name with the name of the library where it originates. For example, the functions text-property-search-forward and text-property-search-backward both belong to the text-property-search.el library (see Loading). By properly prefixing symbol names, one effectively prevents clashes between similarly named symbols which belong to different libraries and thus do different things. However, this practice commonly originates very long symbols names, which are inconvenient to type and read after a while. Shorthands solve these issues in a clean way.

Variable: read-symbol-shorthands ¶

This variable’s value is an alist whose elements have the form (shorthand-prefix . longhand-prefix). Each element instructs the Lisp reader to read every symbol form which starts with shorthand-prefix as if it started with longhand-prefix instead.

This variable may only be set in file-local variables (see Local Variables in Files in The GNU Emacs Manual).

Here’s an example of shorthands usage in a hypothetical string manipulating library some-nice-string-utils.el.

(defun some-nice-string-utils-split (separator s &optional omit-nulls)
  "A match-data saving variant of `split-string'."
  (save-match-data (split-string s separator omit-nulls)))

(defun some-nice-string-utils-lines (s)
  "Split string S at newline characters into a list of strings."
  (some-nice-string-utils-split "\\(\r\n\\|[\n\r]\\)" s))

As can be seen, it’s quite tedious to read or develop this code since the symbol names to type are so long. We can use shorthands to alleviate that.

(defun snu-split (separator s &optional omit-nulls)
  "A match-data saving variation on `split-string'."
  (save-match-data (split-string s separator omit-nulls)))

(defun snu-lines (s)
  "Split string S into a list of strings on newline characters."
  (snu-split "\\(\r\n\\|[\n\r]\\)" s))

;; Local Variables:
;; read-symbol-shorthands: (("snu-" . "some-nice-string-utils-"))
;; End:

Even though the two excerpts look different, they are quite identical after the Lisp reader processes them. Both will lead to the very same symbols being interned (see Creating and Interning Symbols). Thus loading or byte-compiling any of the two files has equivalent results. The shorthands snu-split and snu-lines used in the second version are not interned in the obarray. This is easily seen by moving point to the location where the shorthands are used and waiting for ElDoc (see Local Variables in Files in The GNU Emacs Manual) to hint at the true full name of the symbol under point in the echo area.

Since read-symbol-shorthands is a file-local variable, it is possible that multiple libraries depending on some-nice-string-utils-lines.el refer to the same symbols under different shorthands, or not using shorthands at all. In the next example, the my-tricks.el library refers to the symbol some-nice-string-utils-lines using the sns- prefix instead of snu-.

(defun t-reverse-lines (s) (string-join (reverse (sns-lines s)) "\n")

;; Local Variables:
;; read-symbol-shorthands: (("t-" . "my-tricks-")
;;                          ("sns-" . "some-nice-string-utils-"))
;; End:

Note that if you have two shorthands in the same file where one is the prefix of the other, the longer shorthand will be attempted first. This happens regardless of the order you specify shorthands in the local variables section of your file.

'(
  t//foo ; reads to 'my-tricks--foo', not 'my-tricks-/foo'
  t/foo  ; reads to 'my-tricks-foo'
  )

;; Local Variables:
;; read-symbol-shorthands: (("t/" . "my-tricks-")
;;                          ("t//" . "my-tricks--"))
;; End:

• Exceptions

Previous: Shorthands, Up: Symbols   [Contents][Index]

9.6 Symbols with Position ¶

A symbol with position is a symbol, called the bare symbol, together with a nonnegative fixnum called the position. Even though a symbol with position often acts like its bare symbol, it is not a symbol: instead, it is an object that has both a bare symbol and a position. Because symbols with position are not symbols, they don’t have entries in the obarray, though their bare symbols typically do (see Creating and Interning Symbols).

The byte compiler uses symbols with position, records in them the position of each symbol occurrence, and uses those positions in warning and error messages. They shouldn’t normally be used otherwise. Doing so can cause unexpected results with basic Emacs functions such as eq and equal.

The printed representation of a symbol with position uses the hash notation outlined in Printed Representation and Read Syntax. It looks like ‘#<symbol foo at 12345>’. It has no read syntax. You can cause just the bare symbol to be printed by binding the variable print-symbols-bare to non-nil around the print operation. The byte compiler does this before writing its output to the compiled Lisp file.

When the flag variable symbols-with-pos-enabled is non-nil, a symbol with position ordinarily behaves like its bare symbol. For example, ‘(eq (position-symbol 'foo 12345) 'foo)’ yields t, and equal likewise treats a symbol with position as its bare symbol.

When symbols-with-pos-enabled is nil, symbols with position behave as themselves, not as symbols. For example, ‘(eq (position-symbol 'foo 12345) 'foo)’ yields nil, and equal likewise treats a symbol with position as not equal to its bare symbol.

Most of the time in Emacs symbols-with-pos-enabled is nil, but the byte compiler and the native compiler bind it to t when they run and Emacs runs a little more slowly in this case.

Typically, symbols with position are created by the byte compiler calling the reader function read-positioning-symbols (see Input Functions). One can also be created with the function position-symbol.

Variable: symbols-with-pos-enabled ¶

This variable affects the behavior of symbols with position when they are not being printed and are not arguments to one of the functions defined later in this section. When this variable is non-nil, such a symbol with position behaves like its bare symbol; otherwise it behaves as itself, not as a symbol.

Variable: print-symbols-bare ¶

When bound to non-nil, the Lisp printer prints only the bare symbol of a symbol with position, ignoring the position. Otherwise a symbol with position prints as itself, not as a symbol.

Function: symbol-with-pos-p object ¶

This function returns t if object is a symbol with position, nil otherwise. Unlike symbolp, this function ignores symbols-with-pos-enabled.

Function: bare-symbol sym ¶

This function returns the bare symbol of the symbol with position sym, or sym itself if it is already a symbol. For any other type of object, it signals an error. This function ignores symbols-with-pos-enabled.

Function: symbol-with-pos-pos sympos ¶

This function returns the position, a nonnegative fixnum, from the symbol with position sympos. For any other type of object, it signals an error. This function ignores symbols-with-pos-enabled.

Function: position-symbol sym pos ¶

Make a new symbol with position. The new object’s bare symbol is taken from sym, which is either a symbol, or a symbol with position whose bare symbol is used. The new object’s position is taken from pos, which is either a nonnegative fixnum, or a symbol with position whose position is used. Emacs signals an error if either argument is invalid. This function ignores symbols-with-pos-enabled.