"Fossies" - the Fresh Open Source Software Archive

Member "emacs-25.3/doc/lispref/symbols.texi" (14 Apr 2017, 22404 Bytes) of package /linux/misc/emacs-25.3.tar.xz:


Caution: As a special service "Fossies" has tried to format the requested Texinfo source page into HTML format but that may be not always succeeeded perfectly. Alternatively you can here view or download the uninterpreted Texinfo source code. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the last Fossies "Diffs" side-by-side code changes report for "symbols.texi": 25.1_vs_25.2.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 Symbols

A symbol is an object with a unique name. This chapter describes symbols, their components, their property lists, and how they are created and interned. Separate chapters describe the use of symbols as variables and as function names; see @ref{Variables}, and @ref{Functions}. For the precise read syntax for symbols, see @ref{Symbol Type}.

You can test whether an arbitrary Lisp object is a symbol with symbolp:

Function: symbolp object

This function returns t if object is a symbol, nil otherwise.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.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 section Creating and Interning Symbols).

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. @xref{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). @xref{Constant Variables}.

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 (@pxref{Functions}) or a macro (@pxref{Macros}). However, it can also be used to hold a symbol (@pxref{Function Indirection}), keyboard macro (@pxref{Keyboard Macros}), keymap (@pxref{Keymaps}), or autoload object (@pxref{Autoloading}). To get the contents of a symbol’s function cell, use the function symbol-function (@pxref{Function Cells}).

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 section Symbol Properties.

The function cell or 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 function or 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, variables names and function names 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>

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.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. @xref{Variables}, for details about variables. To define a customizable variable, use the defcustom macro, which also calls defvar as a subroutine (@pxref{Customization}).

In principle, you can assign a variable value to any symbol with setq, whether 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 (@pxref{Variable Scoping}).

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. @xref{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. @xref{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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.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 set of characters. Failure to do so would cause complete confusion.

When the Lisp reader encounters a symbol, it reads all the characters of the name. Then it hashes those characters to find an index in a table called an obarray. Hashing is an efficient method of looking something up. For example, instead of searching a telephone book cover to cover when looking up Jan Jones, you start with the J’s and go from there. That is a simple version of hashing. Each element of the obarray is a bucket which holds all the symbols with a given hash code; to look for a given name, it is sufficient to look through all the symbols in the bucket for that name’s hash code. (The same idea is used for general Emacs hash tables, but they are a different data type; see @ref{Hash Tables}.)

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 need 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.

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.

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.

In Emacs Lisp, an obarray is actually a vector. Each element of the vector is a bucket; its value is either an interned symbol whose name hashes to that bucket, or 0 if the bucket is empty. Each interned symbol has an internal link (invisible to the user) to the next symbol in the bucket. Because these links are invisible, there is no way to find all the symbols in an obarray except using mapatoms (below). The order of symbols in a bucket is not significant.

In an empty obarray, every element is 0, so you can create an obarray with (make-vector length 0). This is the only valid way to create an obarray. Prime numbers as lengths tend to result in good hashing; lengths one less than a power of two are also good.

Do not try to put symbols in an obarray yourself. This does not work—only intern can enter a symbol in an obarray properly.

Common Lisp note: Unlike Common Lisp, Emacs Lisp does not provide for interning a single symbol in several obarrays.

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 a vector.

Function: symbol-name symbol

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

(symbol-name 'foo)
     ⇒ "foo"

Warning: Changing the string by substituting characters does change the name of the symbol, but fails to update the obarray, so don’t do it!

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: 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 @ref{Accessing Documentation}, 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.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 (@pxref{File Local Variables}).

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.1 Accessing Symbol Properties

The following functions can be used to access symbol properties.

Function: get symbol property

This function returns the value of the property named property in symbol’s property list. If there is no such property, it returns nil. Thus, there is no distinction between a value of nil and the absence of the property.

The name property is compared with the existing property names using eq, so any object is a legitimate property.

See put for an example.

Function: put symbol property value

This function puts value onto symbol’s property list under the property name property, replacing any previous property value. The put function returns value.

(put 'fly 'verb 'transitive)
     ⇒'transitive
(put 'fly 'noun '(a buzzing little bug))
     ⇒ (a buzzing little bug)
(get 'fly 'verb)
     ⇒ transitive
(symbol-plist 'fly)
     ⇒ (verb transitive noun (a buzzing little bug))
Function: symbol-plist symbol

This function returns the property list of symbol.

Function: setplist symbol plist

This function sets symbol’s property list to plist. Normally, plist should be a well-formed property list, but this is not enforced. The return value is plist.

(setplist 'foo '(a 1 b (2 3) c nil))
     ⇒ (a 1 b (2 3) c nil)
(symbol-plist 'foo)
     ⇒ (a 1 b (2 3) c nil)

For symbols in special obarrays, which are not used for ordinary purposes, it may make sense to use the property list cell in a nonstandard fashion; in fact, the abbrev mechanism does so (@pxref{Abbrevs}).

You could define put in terms of setplist and plist-put, as follows:

(defun put (symbol prop value)
  (setplist symbol
            (plist-put (symbol-plist symbol) prop value)))
Function: function-get symbol property &optional autoload

This function is identical to get, except that if symbol is the name of a function alias, it looks in the property list of the symbol naming the actual function. @xref{Defining Functions}. If the optional argument autoload is non-nil, and symbol is auto-loaded, this function will try to autoload it, since autoloading might set property of symbol. If autoload is the symbol macro, only try autoloading if symbol is an auto-loaded macro.

Function: function-put function property value

This function sets property of function to value. function should be a symbol. This function is preferred to calling put for setting properties of a function, because it will allow us some day to implement remapping of old properties to new ones.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.2 Standard Symbol Properties

Here, we list the symbol properties which are used for special purposes in Emacs. In the following table, whenever we say “the named function”, that means the function whose name is the relevant symbol; similarly for “the named variable” etc.

:advertised-binding

This property value specifies the preferred key binding, when showing documentation, for the named function. @xref{Keys in Documentation}.

char-table-extra-slots

The value, if non-nil, specifies the number of extra slots in the named char-table type. @xref{Char-Tables}.

customized-face
face-defface-spec
saved-face
theme-face

These properties are used to record a face’s standard, saved, customized, and themed face specs. Do not set them directly; they are managed by defface and related functions. @xref{Defining Faces}.

customized-value
saved-value
standard-value
theme-value

These properties are used to record a customizable variable’s standard value, saved value, customized-but-unsaved value, and themed values. Do not set them directly; they are managed by defcustom and related functions. @xref{Variable Definitions}.

disabled

If the value is non-nil, the named function is disabled as a command. @xref{Disabling Commands}.

face-documentation

The value stores the documentation string of the named face. This is set automatically by defface. @xref{Defining Faces}.

history-length

The value, if non-nil, specifies the maximum minibuffer history length for the named history list variable. @xref{Minibuffer History}.

interactive-form

The value is an interactive form for the named function. Normally, you should not set this directly; use the interactive special form instead. @xref{Interactive Call}.

menu-enable

The value is an expression for determining whether the named menu item should be enabled in menus. @xref{Simple Menu Items}.

mode-class

If the value is special, the named major mode is special. @xref{Major Mode Conventions}.

permanent-local

If the value is non-nil, the named variable is a buffer-local variable whose value should not be reset when changing major modes. @xref{Creating Buffer-Local}.

permanent-local-hook

If the value is non-nil, the named function should not be deleted from the local value of a hook variable when changing major modes. @xref{Setting Hooks}.

pure

If the value is non-nil, the named function is considered to be side-effect free. Calls with constant arguments can be evaluated at compile time. This may shift run time errors to compile time.

risky-local-variable

If the value is non-nil, the named variable is considered risky as a file-local variable. @xref{File Local Variables}.

safe-function

If the value is non-nil, the named function is considered generally safe for evaluation. @xref{Function Safety}.

safe-local-eval-function

If the value is non-nil, the named function is safe to call in file-local evaluation forms. @xref{File Local Variables}.

safe-local-variable

The value specifies a function for determining safe file-local values for the named variable. @xref{File Local Variables}.

side-effect-free

A non-nil value indicates that the named function is free of side-effects, for determining function safety (@pxref{Function Safety}) as well as for byte compiler optimizations. Do not set it.

variable-documentation

If non-nil, this specifies the named variable’s documentation string. This is set automatically by defvar and related functions. @xref{Defining Faces}.


[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on September 28, 2017 using texi2html.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ < ] Back Previous section in reading order 1.2.2
[ Up ] Up Up section 1.2
[ > ] Forward Next section in reading order 1.2.4
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:


This document was generated on September 28, 2017 using texi2html.