(make-char): Doc-string modified.

[gnu-emacs] / lispref / symbols.texi

diff --git a/lispref/symbols.texi b/lispref/symbols.texi
index f3d13ebdad71fff00f06a7429016c13a89f1a00c..9c20df9c4aea2c5ecaa0e4903f970a93a799103d 100644 (file)
--- a/lispref/symbols.texi
+++ b/lispref/symbols.texi
@@ -151,7 +151,8 @@ 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
 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.)  @xref{Functions}.
+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
 
   @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


@@ -160,8 +161,8 @@ 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}.
 
 that cell can hold only one Lisp object at any given time.
 @xref{Macros}.
 

-  In GNU 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
+  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
 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


@@ -310,12 +311,18 @@ value of the global variable @code{obarray} is used.
      @result{} nil
 (make-symbol "frazzle")        ; @r{Create an uninterned one.}
      @result{} frazzle
      @result{} nil
 (make-symbol "frazzle")        ; @r{Create an uninterned one.}
      @result{} frazzle

+@group

 (intern-soft "frazzle")        ; @r{That one cannot be found.}
      @result{} nil
 (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
 (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
 (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
 @group
 (eq sym 'frazzle)              ; @r{And it is the same one.}
      @result{} t


@@ -350,6 +357,20 @@ See @code{documentation} in @ref{Accessing Documentation}, for another
 example using @code{mapatoms}.
 @end defun
 
 example using @code{mapatoms}.
 @end defun
 

+@defun unintern symbol &optional obarray
+This function deletes @var{symbol} from the obarray @var{obarray}.  If
+@code{symbol} 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,
+@code{unintern} does nothing.
+
+If @code{unintern} does delete a symbol, it returns @code{t}.  Otherwise
+it returns @code{nil}.
+@end defun
+

 @node Property Lists,, Creating Symbols, Symbols
 @section Property Lists
 @cindex property list
 @node Property Lists,, Creating Symbols, Symbols
 @section Property Lists
 @cindex property list


@@ -379,6 +400,16 @@ objects, but the names are usually symbols.  They are compared using
 Here @code{lisp-indent-function} and @code{byte-compile} are property
 names, and the other two elements are the corresponding values.
 
 Here @code{lisp-indent-function} and @code{byte-compile} are property
 names, 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 to
 property lists.  In contrast to association lists, the order of the
 @cindex 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


@@ -408,12 +439,15 @@ name.)  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.
 
 are pushed on the front of the list and later discarded; this is not
 possible with a property list.
 

+@node Symbol Plists
+@subsection Property List Functions for Symbols
+

 @defun symbol-plist symbol
 This function returns the property list of @var{symbol}.
 @end defun
 
 @defun setplist symbol plist
 @defun symbol-plist symbol
 This function returns the property list of @var{symbol}.
 @end defun
 
 @defun setplist symbol plist

-  This function sets @var{symbol}'s property list to @var{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.
 
 Normally, @var{plist} should be a well-formed property list, but this is
 not enforced.
 


@@ -458,3 +492,37 @@ The @code{put} function returns @var{value}.
      @result{} (verb transitive noun (a buzzing little bug))
 @end smallexample
 @end defun
      @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 lists
+that are stored in places other than symbols:
+
+@defun plist-get plist property
+This returns the value of the @var{property} property
+stored 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 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,
+
+@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
+