* etags.c (lowcase): Use the standard tolower function.
(substitute): Remove some wrong and some useless code related with
escape `\` character in regexp replacement string.
(TEX_defenv): Added part, appendix, entry, index. Removed typeout.
(lang_suffixes): New suffixes: .hpp for C++; .f90 for Fortran;
.bib, .ltx, .TeX for TeX (.bbl, .dtx removed); .ml for Lisp;
.prolog for prolog (.pl removed).
(massage_name, etags_getcwd): Use lowcase instead of tolower.
(regex.h): Don't include it if REGEX_IN_LIBC is defined.
(C_entries, find_entries): Added comments about memory leakage.
(add_node): Dead code removed.
@c -*-texinfo-*-@c This is part of the GNU Emacs Lisp Reference Manual.@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions.@setfilename ../info/symbols@node Symbols, Evaluation, Sequences Arrays Vectors, Top@chapter Symbols@cindex symbol A @dfn{symbol} is an object with a unique name. This chapterdescribes symbols, their components, their property lists, and how theyare created and interned. Separate chapters describe the use of symbolsas 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 symbolwith @code{symbolp}:@defun symbolp objectThis function returns @code{t} if @var{object} is a symbol, @code{nil}otherwise.@end defun@menu* 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.@end menu@node Symbol Components, Definitions, Symbols, Symbols@section Symbol Components@cindex symbol components Each symbol has four components (or ``cells''), each of whichreferences another object:@table @asis@item Print name@cindex print name cellThe @dfn{print name cell} holds a string that names the symbol forreading and printing. See @code{symbol-name} in @ref{Creating Symbols}.@item Value@cindex value cellThe @dfn{value cell} holds the current value of the symbol as avariable. When a symbol is used as a form, the value of the form is thecontents of the symbol's value cell. See @code{symbol-value} in@ref{Accessing Variables}.@item Function@cindex function cellThe @dfn{function cell} holds the function definition of the symbol.When a symbol is used as a function, its function definition is used inits place. This cell is also used to make a symbol stand for a keymapor a keyboard macro, for editor command execution. Because each symbolhas separate value and function cells, variables and function names donot conflict. See @code{symbol-function} in @ref{Function Cells}.@item Property list@cindex property list cellThe @dfn{property list cell} holds the property list of the symbol. See@code{symbol-plist} in @ref{Property Lists}.@end table The print name cell always holds a string, and cannot be changed. Theother 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 importantnot to have two symbols with the same name. The Lisp reader ensuresthis: every time it reads a symbol, it looks for an existing symbol withthe specified name before it creates a new one. (In GNU Emacs Lisp,this lookup uses a hashing algorithm and an obarray; see @ref{CreatingSymbols}.) In normal usage, the function cell usually contains a function ormacro, 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}) arealso sometimes stored in the function cell of symbols. We often referto ``the function @code{foo}'' when we really mean the function storedin the function cell of the symbol @code{foo}. We make the distinctiononly when necessary. The property list cell normally should hold a correctly formattedproperty list (@pxref{Property Lists}), as a number of functions expectto see a property list there. The function cell or the value cell may be @dfn{void}, which meansthat the cell does not reference any object. (This is not the samething as holding the symbol @code{void}, nor the same as holding thesymbol @code{nil}.) Examining a 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},@code{symbol-plist}, and @code{symbol-function} return the contents ofthe four cells of a symbol. Here as an example we show the contents ofthe four cells of the symbol @code{buffer-file-name}:@example(symbol-name 'buffer-file-name) @result{} "buffer-file-name"(symbol-value 'buffer-file-name) @result{} "/gnu/elisp/symbols.texi"(symbol-plist 'buffer-file-name) @result{} (variable-documentation 29529)(symbol-function 'buffer-file-name) @result{} #<subr buffer-file-name>@end example@noindentBecause this symbol is the variable which holds the name of the filebeing visited in the current buffer, the value cell contents we see arethe name of the source file of this chapter of the Emacs Lisp Manual.The property list cell contains the list @code{(variable-documentation29529)} which tells the documentation functions where to find thedocumentation string for the variable @code{buffer-file-name} in the@file{DOC} file. (29529 is the offset from the beginning of the@file{DOC} file to where that documentation string begins.) Thefunction cell contains the function for returning the name of the file.@code{buffer-file-name} names a primitive function, which has no readsyntax and prints in hash notation (@pxref{Primitive Function Type}). Asymbol naming a function written in Lisp would have a lambda expression(or a byte-code object) in this cell.@node Definitions, Creating Symbols, Symbol Components, Symbols@section Defining Symbols@cindex definition of a symbol A @dfn{definition} in Lisp is a special form that announces yourintention 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 (ormacro), or both independently. A definition construct typically specifies a value or meaning for thesymbol for one kind of use, plus documentation for its meaning when usedin this way. Thus, when you define a symbol as a variable, you cansupply an initial value for the variable, plus documentation for thevariable. @code{defvar} and @code{defconst} are special forms that define asymbol as a global variable. They are documented in detail in@ref{Defining Variables}. @code{defun} defines a symbol as a function, creating a lambdaexpression and storing it in the function cell of the symbol. Thislambda expression thus becomes the function definition of the symbol.(The term ``function definition'', meaning the contents of the functioncell, is derived from the idea that @code{defun} gives the symbol itsdefinition as a function.) @code{defsubst} and @code{defalias} are twoother ways of defining a function. @xref{Functions}. @code{defmacro} defines a symbol as a macro. It creates a macroobject and stores it in the function cell of the symbol. Note that agiven symbol can be a macro or a function, but not both at once, becauseboth macro and function definitions are kept in the function cell, andthat cell can hold only one Lisp object at any given time.@xref{Macros}. In Emacs Lisp, a definition is not required in order to use a symbolas a variable or function. Thus, you can make a symbol a globalvariable with @code{setq}, whether you define it first or not. The realpurpose of definitions is to guide programmers and programming tools.They inform programmers who read the code that certain symbols are@emph{intended} to be used as variables, or as functions. In addition,utilities such as @file{etags} and @file{make-docfile} recognizedefinitions, and add appropriate information to tag tables and the@file{emacs/etc/DOC-@var{version}} file. @xref{Accessing Documentation}.@node Creating Symbols, Property Lists, Definitions, Symbols@section Creating and Interning Symbols@cindex reading symbols To understand how symbols are created in GNU Emacs Lisp, you must knowhow Lisp reads them. Lisp must ensure that it finds the same symbolevery time it reads the same set of characters. Failure to do so wouldcause complete confusion.@cindex symbol name hashing@cindex hashing@cindex obarray@cindex bucket (in obarray) When the Lisp reader encounters a symbol, it reads all the charactersof the name. Then it ``hashes'' those characters to find an index in atable called an @dfn{obarray}. Hashing is an efficient method oflooking something up. For example, instead of searching a telephonebook cover to cover when looking up Jan Jones, you start with the J'sand go from there. That is a simple version of hashing. Each elementof the obarray is a @dfn{bucket} which holds all the symbols with agiven hash code; to look for a given name, it is sufficient to lookthrough all the symbols in the bucket for that name's hash code.@cindex interning If a symbol with the desired name is found, the reader uses thatsymbol. If the obarray does not contain a symbol with that name, thereader makes a new symbol and adds it to the obarray. Finding or addinga symbol with a certain name is called @dfn{interning} it, and thesymbol is then called an @dfn{interned symbol}. Interning ensures that each obarray has just one symbol with anyparticular name. Other like-named symbols may exist, but not in thesame obarray. Thus, the reader gets the same symbols for the samenames, as long as you keep reading with the same obarray.@cindex symbol equality@cindex uninterned symbol No obarray contains all symbols; in fact, some symbols are not in anyobarray. They are called @dfn{uninterned symbols}. An uninternedsymbol has the same four cells as other symbols; however, the only wayto gain access to it is by finding it in some other object or as thevalue of a variable. In Emacs Lisp, an obarray is actually a vector. Each element of thevector is a bucket; its value is either an interned symbol whose namehashes to that bucket, or 0 if the bucket is empty. Each internedsymbol has an internal link (invisible to the user) to the next symbolin the bucket. Because these links are invisible, there is no way tofind 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, and you can create an obarraywith @code{(make-vector @var{length} 0)}. @strong{This is the onlyvalid way to create an obarray.} Prime numbers as lengths tendto result in good hashing; lengths one less than a power of two are alsogood. @strong{Do not try to put symbols in an obarray yourself.} This doesnot work---only @code{intern} can enter a symbol in an obarray properly.@strong{Do not try to intern one symbol in two obarrays.} This wouldgarble both obarrays, because a symbol has just one slot to hold thefollowing symbol in the obarray bucket. The results would beunpredictable. It is possible for two different symbols to have the same name indifferent obarrays; these symbols are not @code{eq} or @code{equal}.However, this normally happens only as part of the abbrev mechanism(@pxref{Abbrevs}).@cindex CL note---symbol in obarrays@quotation@b{Common Lisp note:} In Common Lisp, a single symbol may be interned inseveral obarrays.@end quotation Most of the functions below take a name and sometimes an obarray asarguments. A @code{wrong-type-argument} error is signaled if the nameis not a string, or if the obarray is not a vector.@defun symbol-name symbolThis function returns the string that is @var{symbol}'s name. For example:@example@group(symbol-name 'foo) @result{} "foo"@end group@end exampleChanging the string by substituting characters, etc, does change thename of the symbol, but fails to update the obarray, so don't do it!@end defun@defun make-symbol nameThis function returns a newly-allocated, uninterned symbol whose name is@var{name} (which must be a string). Its value and function definitionare 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 adistinct uninterned symbol whose name is also @samp{foo}.@example(setq sym (make-symbol "foo")) @result{} foo(eq sym 'foo) @result{} nil@end example@end defun@defun intern name &optional obarrayThis function returns the interned symbol whose name is @var{name}. Ifthere is no such symbol in the obarray @var{obarray}, @code{intern}creates a new one, adds it to the obarray, and returns it. If@var{obarray} is omitted, the value of the global variable@code{obarray} is used.@example(setq sym (intern "foo")) @result{} foo(eq sym 'foo) @result{} t(setq sym1 (intern "foo" other-obarray)) @result{} foo(eq sym 'foo) @result{} nil@end example@end defun@defun intern-soft name &optional obarrayThis function returns the symbol in @var{obarray} whose name is@var{name}, or @code{nil} if @var{obarray} has no symbol with that name.Therefore, you can use @code{intern-soft} to test whether a symbol witha given name is already interned. If @var{obarray} is omitted, thevalue of the global variable @code{obarray} is used.@smallexample(intern-soft "frazzle") ; @r{No such symbol exists.} @result{} nil(make-symbol "frazzle") ; @r{Create an uninterned one.} @result{} frazzle@group(intern-soft "frazzle") ; @r{That one cannot be found.} @result{} nil@end group@group(setq sym (intern "frazzle")) ; @r{Create an interned one.} @result{} frazzle@end group@group(intern-soft "frazzle") ; @r{That one can be found!} @result{} frazzle@end group@group(eq sym 'frazzle) ; @r{And it is the same one.} @result{} t@end group@end smallexample@end defun@defvar obarrayThis variable is the standard obarray for use by @code{intern} and@code{read}.@end defvar@defun mapatoms function &optional obarrayThis function calls @var{function} for each symbol in the obarray@var{obarray}. It returns @code{nil}. If @var{obarray} is omitted, itdefaults to the value of @code{obarray}, the standard obarray forordinary symbols.@smallexample(setq count 0) @result{} 0(defun count-syms (s) (setq count (1+ count))) @result{} count-syms(mapatoms 'count-syms) @result{} nilcount @result{} 1871@end smallexampleSee @code{documentation} in @ref{Accessing Documentation}, for anotherexample using @code{mapatoms}.@end defun@defun unintern symbol &optional obarrayThis function deletes @var{symbol} from the obarray @var{obarray}. If@code{symbol} is not actually in the obarray, @code{unintern} doesnothing. If @var{obarray} is @code{nil}, the current obarray is used.If you provide a string instead of a symbol as @var{symbol}, it standsfor a symbol name. Then @code{unintern} deletes the symbol (if any) inthe obarray which has that name. If there is no such symbol,@code{unintern} does nothing.If @code{unintern} does delete a symbol, it returns @code{t}. Otherwiseit returns @code{nil}.@end defun@node Property Lists,, Creating Symbols, Symbols@section Property Lists@cindex property list@cindex plist A @dfn{property list} (@dfn{plist} for short) is a list of pairedelements stored in the property list cell of a symbol. Each of thepairs associates a property name (usually a symbol) with a property orvalue. Property lists are generally used to record information about asymbol, such as its documentation as a variable, the name of the filewhere it was defined, or perhaps even the grammatical class of thesymbol (representing a word) in a language-understanding system. Character positions in a string or buffer can also have property lists.@xref{Text Properties}. The property names and values in a property list can be any Lispobjects, but the names are usually symbols. They are compared using@code{eq}. Here is an example of a property list, found on the symbol@code{progn} when the compiler is loaded:@example(lisp-indent-function 0 byte-compile byte-compile-progn)@end example@noindentHere @code{lisp-indent-function} and @code{byte-compile} are propertynames, and the other two elements are the corresponding values.@menu* 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.@end menu@node Plists and Alists@subsection Property Lists and Association Lists@cindex property lists vs association lists Association lists (@pxref{Association Lists}) are very similar toproperty lists. In contrast to association lists, the order of thepairs in the property list is not significant since the property namesmust be distinct. Property lists are better than association lists for attachinginformation to various Lisp function names or variables. If all theassociations are recorded in one association list, the program will needto search that entire list each time a function or variable is to beoperated on. By contrast, if the information is recorded in theproperty lists of the function names or variables themselves, eachsearch will scan only the length of one property list, which is usuallyshort. This is why the documentation for a variable is recorded in aproperty named @code{variable-documentation}. The byte compilerlikewise uses properties to record those functions needing specialtreatment. However, association lists have their own advantages. Depending onyour application, it may be faster to add an association to the front ofan association list than to update a property. All properties for asymbol are stored in the same property list, so there is a possibilityof a conflict between different uses of a property name. (For thisreason, it is a good idea to choose property names that are probablyunique, such as by including the name of the library in the propertyname.) An association list may be used like a stack where associationsare pushed on the front of the list and later discarded; this is notpossible with a property list.@node Symbol Plists@subsection Property List Functions for Symbols@defun symbol-plist symbolThis function returns the property list of @var{symbol}.@end defun@defun setplist symbol plistThis function sets @var{symbol}'s property list to @var{plist}.Normally, @var{plist} should be a well-formed property list, but this isnot enforced.@smallexample(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)@end smallexampleFor symbols in special obarrays, which are not used for ordinarypurposes, it may make sense to use the property list cell in anonstandard fashion; in fact, the abbrev mechanism does so(@pxref{Abbrevs}).@end defun@defun get symbol propertyThis function finds the value of the property named @var{property} in@var{symbol}'s property list. If there is no such property, @code{nil}is returned. Thus, there is no distinction between a value of@code{nil} and the absence of the property.The name @var{property} is compared with the existing property namesusing @code{eq}, so any object is a legitimate property.See @code{put} for an example.@end defun@defun put symbol property valueThis function puts @var{value} onto @var{symbol}'s property list underthe property name @var{property}, replacing any previous property value.The @code{put} function returns @var{value}.@smallexample(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))@end smallexample@end defun@node Other Plists@subsection Property Lists Outside Symbols These two functions are useful for manipulating property liststhat are stored in places other than symbols:@defun plist-get plist propertyThis returns the value of the @var{property} propertystored in the property list @var{plist}. For example,@example(plist-get '(foo 4) 'foo) @result{} 4@end example@end defun@defun plist-put plist property valueThis stores @var{value} as the value of the @var{property} property inthe property list @var{plist}. It may modify @var{plist} destructively,or it may construct a new list structure without altering the old. Thefunction returns the modified property list, so you can store that backin the place where you got @var{plist}. For example,@example(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{} (quux (a) bar t foo 5)@end example@end defun