[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to symbols.texi
From: |
Glenn Morris |
Subject: |
[Emacs-diffs] Changes to symbols.texi |
Date: |
Thu, 06 Sep 2007 04:14:31 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Glenn Morris <gm> 07/09/06 04:14:31
Index: symbols.texi
===================================================================
RCS file: symbols.texi
diff -N symbols.texi
--- symbols.texi 8 Apr 2007 16:50:52 -0000 1.35
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,598 +0,0 @@
address@hidden -*-texinfo-*-
address@hidden This is part of the GNU Emacs Lisp Reference Manual.
address@hidden Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
2001,
address@hidden 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation,
Inc.
address@hidden See the file elisp.texi for copying conditions.
address@hidden ../info/symbols
address@hidden Symbols, Evaluation, Hash Tables, Top
address@hidden Symbols
address@hidden symbol
-
- A @dfn{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
address@hidden For the precise read syntax for symbols, see
address@hidden Type}.
-
- You can test whether an arbitrary Lisp object is a symbol
-with @code{symbolp}:
-
address@hidden symbolp object
-This function returns @code{t} if @var{object} is a symbol, @code{nil}
-otherwise.
address@hidden defun
-
address@hidden
-* Symbol Components:: Symbols have names, values, function definitions
- and property lists.
-* Definitions:: A definition says how a symbol will be used.
-* Creating Symbols:: How symbols are kept unique.
-* Property Lists:: Each symbol has a property list
- for recording miscellaneous information.
address@hidden menu
-
address@hidden Symbol Components, Definitions, Symbols, Symbols
address@hidden Symbol Components
address@hidden symbol components
-
- Each symbol has four components (or ``cells''), each of which
-references another object:
-
address@hidden @asis
address@hidden Print name
address@hidden print name cell
-The @dfn{print name cell} holds a string that names the symbol for
-reading and printing. See @code{symbol-name} in @ref{Creating Symbols}.
-
address@hidden Value
address@hidden value cell
-The @dfn{value cell} holds the current value of the symbol as a
-variable. When a symbol is used as a form, the value of the form is the
-contents of the symbol's value cell. See @code{symbol-value} in
address@hidden Variables}.
-
address@hidden Function
address@hidden function cell
-The @dfn{function cell} holds the function definition of the symbol.
-When a symbol is used as a function, its function definition is used in
-its place. This cell is also used to make a symbol stand for a keymap
-or a keyboard macro, for editor command execution. Because each symbol
-has separate value and function cells, variables names and function names do
-not conflict. See @code{symbol-function} in @ref{Function Cells}.
-
address@hidden Property list
address@hidden property list cell
-The @dfn{property list cell} holds the property list of the symbol. See
address@hidden in @ref{Property Lists}.
address@hidden table
-
- The print name cell always holds a string, and cannot be changed. The
-other three cells can be set individually to any specified Lisp object.
-
- The print name cell holds the string that is the name of the 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. (In GNU Emacs Lisp,
-this lookup uses a hashing algorithm and an obarray; see @ref{Creating
-Symbols}.)
-
- The value cell holds the symbol's value as a variable
-(@pxref{Variables}). That is what you get if you evaluate the symbol as
-a Lisp expression (@pxref{Evaluation}). Any Lisp object is a legitimate
-value. Certain symbols have values that cannot be changed; these
-include @code{nil} and @code{t}, and any symbol whose name starts with
address@hidden:} (those are called @dfn{keywords}). @xref{Constant Variables}.
-
- We often refer to ``the function @code{foo}'' when we really mean
-the function stored in the function cell of the symbol @code{foo}. We
-make the distinction explicit only when necessary. In normal
-usage, the function cell usually contains a function
-(@pxref{Functions}) or a macro (@pxref{Macros}), as that is what the
-Lisp interpreter expects to see there (@pxref{Evaluation}). Keyboard
-macros (@pxref{Keyboard Macros}), keymaps (@pxref{Keymaps}) and
-autoload objects (@pxref{Autoloading}) are also sometimes stored in
-the function cells of symbols.
-
- The property list cell normally should hold a correctly formatted
-property list (@pxref{Property Lists}), as a number of functions expect
-to see a property list there.
-
- The function cell or the value cell may be @dfn{void}, which means
-that the cell does not reference any object. (This is not the same
-thing as holding the symbol @code{void}, nor the same as holding the
-symbol @code{nil}.) Examining a function or value cell that is void
-results in an error, such as @samp{Symbol's value as variable is void}.
-
- The four functions @code{symbol-name}, @code{symbol-value},
address@hidden, and @code{symbol-function} return the contents of
-the four cells of a symbol. Here as an example we show the contents of
-the four cells of the symbol @code{buffer-file-name}:
-
address@hidden
-(symbol-name 'buffer-file-name)
- @result{} "buffer-file-name"
-(symbol-value 'buffer-file-name)
- @result{} "/gnu/elisp/symbols.texi"
-(symbol-function 'buffer-file-name)
- @result{} #<subr buffer-file-name>
-(symbol-plist 'buffer-file-name)
- @result{} (variable-documentation 29529)
address@hidden example
-
address@hidden
-Because this symbol is the variable which holds the name of the file
-being visited in the current buffer, the value cell contents we see are
-the name of the source file of this chapter of the Emacs Lisp Manual.
-The property list cell contains the list @code{(variable-documentation
-29529)} which tells the documentation functions where to find the
-documentation string for the variable @code{buffer-file-name} in the
address@hidden@var{version}} file. (29529 is the offset from the beginning
-of the @address@hidden file to where that documentation string
-begins---see @ref{Documentation Basics}.) The function cell contains
-the function for returning the name of the file.
address@hidden names a primitive function, which has no read
-syntax and prints in hash notation (@pxref{Primitive Function Type}). A
-symbol naming a function written in Lisp would have a lambda expression
-(or a byte-code object) in this cell.
-
address@hidden Definitions, Creating Symbols, Symbol Components, Symbols
address@hidden Defining Symbols
address@hidden definitions of symbols
-
- A @dfn{definition} in Lisp is a special form that announces your
-intention to use a certain symbol in a particular way. In Emacs Lisp,
-you can define a symbol as a variable, or define it as a function (or
-macro), or both independently.
-
- A definition construct 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.
-
- @code{defvar} and @code{defconst} are special forms that define a
-symbol as a global variable. They are documented in detail in
address@hidden Variables}. For defining user option variables that can
-be customized, use @code{defcustom} (@pxref{Customization}).
-
- @code{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 @code{defun} gives the symbol its
-definition as a function.) @code{defsubst} and @code{defalias} are two
-other ways of defining a function. @xref{Functions}.
-
- @code{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.
address@hidden
-
- In Emacs Lisp, a definition is not required in order to use a symbol
-as a variable or function. Thus, you can make a symbol a global
-variable with @code{setq}, whether you define it first or not. The real
-purpose of definitions is to guide programmers and programming tools.
-They inform programmers who read the code that certain symbols are
address@hidden to be used as variables, or as functions. In addition,
-utilities such as @file{etags} and @file{make-docfile} recognize
-definitions, and add appropriate information to tag tables and the
address@hidden@var{version}} file. @xref{Accessing Documentation}.
-
address@hidden Creating Symbols, Property Lists, Definitions, Symbols
address@hidden Creating and Interning Symbols
address@hidden reading 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.
-
address@hidden symbol name hashing
address@hidden hashing
address@hidden obarray
address@hidden bucket (in obarray)
- 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 @dfn{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 @dfn{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}.)
-
address@hidden interning
- 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 @dfn{interning} it, and the
-symbol is then called an @dfn{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 @kbd{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.
-
address@hidden symbol equality
address@hidden uninterned symbol
- No obarray contains all symbols; in fact, some symbols are not in any
-obarray. They are called @dfn{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 @code{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 @code{(make-vector @var{length} 0)}. @strong{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.
-
- @strong{Do not try to put symbols in an obarray yourself.} This does
-not work---only @code{intern} can enter a symbol in an obarray properly.
-
address@hidden CL note---symbol in obarrays
address@hidden
address@hidden Lisp note:} In Common Lisp, a single symbol may be interned in
-several obarrays.
address@hidden quotation
-
- Most of the functions below take a name and sometimes an obarray as
-arguments. A @code{wrong-type-argument} error is signaled if the name
-is not a string, or if the obarray is not a vector.
-
address@hidden symbol-name symbol
-This function returns the string that is @var{symbol}'s name. For example:
-
address@hidden
address@hidden
-(symbol-name 'foo)
- @result{} "foo"
address@hidden group
address@hidden example
-
address@hidden:} Changing the string by substituting characters does
-change the name of the symbol, but fails to update the obarray, so don't
-do it!
address@hidden defun
-
address@hidden make-symbol name
-This function returns a newly-allocated, uninterned symbol whose name is
address@hidden (which must be a string). Its value and function definition
-are void, and its property list is @code{nil}. In the example below,
-the value of @code{sym} is not @code{eq} to @code{foo} because it is a
-distinct uninterned symbol whose name is also @samp{foo}.
-
address@hidden
-(setq sym (make-symbol "foo"))
- @result{} foo
-(eq sym 'foo)
- @result{} nil
address@hidden example
address@hidden defun
-
address@hidden intern name &optional obarray
-This function returns the interned symbol whose name is @var{name}. If
-there is no such symbol in the obarray @var{obarray}, @code{intern}
-creates a new one, adds it to the obarray, and returns it. If
address@hidden is omitted, the value of the global variable
address@hidden is used.
-
address@hidden
-(setq sym (intern "foo"))
- @result{} foo
-(eq sym 'foo)
- @result{} t
-
-(setq sym1 (intern "foo" other-obarray))
- @result{} foo
-(eq sym1 'foo)
- @result{} nil
address@hidden example
address@hidden defun
-
address@hidden CL note---interning existing symbol
address@hidden
address@hidden 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 @code{intern} must be a string, not a symbol.
address@hidden quotation
-
address@hidden intern-soft name &optional obarray
-This function returns the symbol in @var{obarray} whose name is
address@hidden, or @code{nil} if @var{obarray} has no symbol with that name.
-Therefore, you can use @code{intern-soft} to test whether a symbol with
-a given name is already interned. If @var{obarray} is omitted, the
-value of the global variable @code{obarray} is used.
-
-The argument @var{name} may also be a symbol; in that case,
-the function returns @var{name} if @var{name} is interned
-in the specified obarray, and otherwise @code{nil}.
-
address@hidden
-(intern-soft "frazzle") ; @r{No such symbol exists.}
- @result{} nil
-(make-symbol "frazzle") ; @r{Create an uninterned one.}
- @result{} frazzle
address@hidden
-(intern-soft "frazzle") ; @r{That one cannot be found.}
- @result{} nil
address@hidden group
address@hidden
-(setq sym (intern "frazzle")) ; @r{Create an interned one.}
- @result{} frazzle
address@hidden group
address@hidden
-(intern-soft "frazzle") ; @r{That one can be found!}
- @result{} frazzle
address@hidden group
address@hidden
-(eq sym 'frazzle) ; @r{And it is the same one.}
- @result{} t
address@hidden group
address@hidden smallexample
address@hidden defun
-
address@hidden obarray
-This variable is the standard obarray for use by @code{intern} and
address@hidden
address@hidden defvar
-
address@hidden mapatoms function &optional obarray
address@hidden of mapatoms}
-This function calls @var{function} once with each symbol in the obarray
address@hidden Then it returns @code{nil}. If @var{obarray} is
-omitted, it defaults to the value of @code{obarray}, the standard
-obarray for ordinary symbols.
-
address@hidden
-(setq count 0)
- @result{} 0
-(defun count-syms (s)
- (setq count (1+ count)))
- @result{} count-syms
-(mapatoms 'count-syms)
- @result{} nil
-count
- @result{} 1871
address@hidden smallexample
-
-See @code{documentation} in @ref{Accessing Documentation}, for another
-example using @code{mapatoms}.
address@hidden defun
-
address@hidden unintern symbol &optional obarray
-This function deletes @var{symbol} from the obarray @var{obarray}. If
address@hidden is not actually in the obarray, @code{unintern} does
-nothing. If @var{obarray} is @code{nil}, the current obarray is used.
-
-If you provide a string instead of a symbol as @var{symbol}, it stands
-for a symbol name. Then @code{unintern} deletes the symbol (if any) in
-the obarray which has that name. If there is no such symbol,
address@hidden does nothing.
-
-If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise
-it returns @code{nil}.
address@hidden defun
-
address@hidden Property Lists,, Creating Symbols, Symbols
address@hidden Property Lists
address@hidden property list
address@hidden plist
-
- A @dfn{property list} (@dfn{plist} for short) is a list of paired
-elements stored in the property list cell of a symbol. Each of the
-pairs associates a property name (usually a symbol) with a property or
-value. Property lists are generally used to record information about a
-symbol, such as its documentation as a variable, the name of the file
-where it was defined, or perhaps even the grammatical class of the
-symbol (representing a word) in a language-understanding system.
-
- Character positions in a string or buffer can also have property lists.
address@hidden Properties}.
-
- The property names and values in a property list can be any Lisp
-objects, but the names are usually symbols. Property list functions
-compare the property names using @code{eq}. Here is an example of a
-property list, found on the symbol @code{progn} when the compiler is
-loaded:
-
address@hidden
-(lisp-indent-function 0 byte-compile byte-compile-progn)
address@hidden example
-
address@hidden
-Here @code{lisp-indent-function} and @code{byte-compile} are property
-names, and the other two elements are the corresponding values.
-
address@hidden
-* Plists and Alists:: Comparison of the advantages of property
- lists and association lists.
-* Symbol Plists:: Functions to access symbols' property lists.
-* Other Plists:: Accessing property lists stored elsewhere.
address@hidden menu
-
address@hidden Plists and Alists
address@hidden Property Lists and Association Lists
address@hidden plist vs. alist
address@hidden alist vs. plist
-
address@hidden property lists vs association lists
- Association lists (@pxref{Association Lists}) are very similar to
-property lists. In contrast to association lists, the order of the
-pairs in the property list is not significant since the property names
-must be distinct.
-
- Property lists are better than association lists for attaching
-information to various Lisp function names or variables. If your
-program keeps all of its associations in one association list, it will
-typically need to search that entire list each time it checks for an
-association. This could be slow. By contrast, if you keep the same
-information in the property lists of the function names or variables
-themselves, each search will scan only the length of one property list,
-which is usually short. This is why the documentation for a variable is
-recorded in a property named @code{variable-documentation}. The byte
-compiler likewise uses properties to record those functions needing
-special treatment.
-
- However, association lists have their own advantages. Depending on
-your application, it may be faster to add an association to the front of
-an association list than to update a property. All properties for a
-symbol are stored in the same property list, so there is a possibility
-of a conflict between different uses of a property name. (For this
-reason, it is a good idea to choose property names that are probably
-unique, such as by beginning the property name with the program's usual
-name-prefix for variables and functions.) An association list may be
-used like a stack where associations are pushed on the front of the list
-and later discarded; this is not possible with a property list.
-
address@hidden Symbol Plists
address@hidden Property List Functions for Symbols
-
address@hidden symbol-plist symbol
-This function returns the property list of @var{symbol}.
address@hidden defun
-
address@hidden setplist symbol plist
-This function sets @var{symbol}'s property list to @var{plist}.
-Normally, @var{plist} should be a well-formed property list, but this is
-not enforced. The return value is @var{plist}.
-
address@hidden
-(setplist 'foo '(a 1 b (2 3) c nil))
- @result{} (a 1 b (2 3) c nil)
-(symbol-plist 'foo)
- @result{} (a 1 b (2 3) c nil)
address@hidden smallexample
-
-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}).
address@hidden defun
-
address@hidden get symbol property
-This function finds the value of the property named @var{property} in
address@hidden's property list. If there is no such property, @code{nil}
-is returned. Thus, there is no distinction between a value of
address@hidden and the absence of the property.
-
-The name @var{property} is compared with the existing property names
-using @code{eq}, so any object is a legitimate property.
-
-See @code{put} for an example.
address@hidden defun
-
address@hidden put symbol property value
-This function puts @var{value} onto @var{symbol}'s property list under
-the property name @var{property}, replacing any previous property value.
-The @code{put} function returns @var{value}.
-
address@hidden
-(put 'fly 'verb 'transitive)
- @result{}'transitive
-(put 'fly 'noun '(a buzzing little bug))
- @result{} (a buzzing little bug)
-(get 'fly 'verb)
- @result{} transitive
-(symbol-plist 'fly)
- @result{} (verb transitive noun (a buzzing little bug))
address@hidden smallexample
address@hidden defun
-
address@hidden Other Plists
address@hidden Property Lists Outside Symbols
-
- These functions are useful for manipulating property lists
-that are stored in places other than symbols:
-
address@hidden plist-get plist property
-This returns the value of the @var{property} property
-stored in the property list @var{plist}. For example,
-
address@hidden
-(plist-get '(foo 4) 'foo)
- @result{} 4
-(plist-get '(foo 4 bad) 'foo)
- @result{} 4
-(plist-get '(foo 4 bad) 'bar)
- @result{} @code{wrong-type-argument} error
address@hidden example
-
-It accepts a malformed @var{plist} argument and always returns @code{nil}
-if @var{property} is not found in the @var{plist}. For example,
-
address@hidden
-(plist-get '(foo 4 bad) 'bar)
- @result{} nil
address@hidden example
address@hidden defun
-
address@hidden plist-put plist property value
-This stores @var{value} as the value of the @var{property} property in
-the property list @var{plist}. It may modify @var{plist} destructively,
-or it may construct a new list structure without altering the old. The
-function returns the modified property list, so you can store that back
-in the place where you got @var{plist}. For example,
-
address@hidden
-(setq my-plist '(bar t foo 4))
- @result{} (bar t foo 4)
-(setq my-plist (plist-put my-plist 'foo 69))
- @result{} (bar t foo 69)
-(setq my-plist (plist-put my-plist 'quux '(a)))
- @result{} (bar t foo 69 quux (a))
address@hidden example
address@hidden defun
-
- You could define @code{put} in terms of @code{plist-put} as follows:
-
address@hidden
-(defun put (symbol prop value)
- (setplist symbol
- (plist-put (symbol-plist symbol) prop value)))
address@hidden example
-
address@hidden lax-plist-get plist property
-Like @code{plist-get} except that it compares properties
-using @code{equal} instead of @code{eq}.
address@hidden defun
-
address@hidden lax-plist-put plist property value
-Like @code{plist-put} except that it compares properties
-using @code{equal} instead of @code{eq}.
address@hidden defun
-
address@hidden plist-member plist property
-This returns address@hidden if @var{plist} contains the given
address@hidden Unlike @code{plist-get}, this allows you to distinguish
-between a missing property and a property with the value @code{nil}.
-The value is actually the tail of @var{plist} whose @code{car} is
address@hidden
address@hidden defun
-
address@hidden
- arch-tag: 8750b7d2-de4c-4923-809a-d35fc39fd8ce
address@hidden ignore
- [Emacs-diffs] Changes to symbols.texi,
Glenn Morris <=