.c	Tuesday  Nov 29,1983  3:30  LQ+1D.21H.37M.12S.  -*- Bolio -*-


.chapter "Symbols"


.section "The Property List"

.defun symbol-plist symbol
Returns the property list of 2symbol*. Unlike the lan{maclisp}
3plist* function, this only works on symbols, not disembodied
property lists.

3symbol-plist* may be used with 3setf* to change the property
list of a symbol.  This is generally not recommended practice,
however, because doing so might cause properties essential to the
lan{nil} system to be lost.
.end_defun

.defun get symbol indicator
Standard lan{maclisp} fun{get}.  The value stored under
2indicator* on the property list of 2symbol* is returned;  if
there is no such value, 3nil* is returned.  As in lan{maclisp},
2symbol* may also be a disembodied property list.  Unlike in
lan{maclisp}, 3get* does not arbitrarily check the type and then
return 3nil* if it is neither a symbol nor a list; in lan{nil}
one gets an error for an invalid type.

For both lan{maclisp} compatibility and convenience, 3get* is
not going to disappear in the future.
.end_defun

.defun get-properties plist indicator-list
This searches 2plist* for any indicator in
the list 2indicator-list*.  If one is found, then three values are
returned:  the value of that property, the indicator under which it
was found, and the subpart of the property list whose 3car* is
that indicator.  If it is not found, the three values returned are all
3nil*.  Thus, to find either the 3known-compilation* or
3predicate-compilation* properties on the property list of
2symbol*, one would write
.lisp
(get-properties (symbol-plist 2symbol*)
		'(known-compilation predicate-compilation))
.end_lisp
.end_defun

.defun putprop symbol value indicator
Standard lan{maclisp} fun{putprop}.  If 2symbol* already has
an 2indicator* property, this replaces it with 2value*,
otherwise puts a new one.  As in lan{maclisp}, 2symbol* may also
be a disembodied property list.

lan{Common lisp} does not define 3putprop*;  rather, one uses
3setf* with 3getf* ((getf-fun)).  3putprop* is not going
to be flushed
from lan{nil}, however.  Note also that 3putprop* takes its
arguments in a different order from the "standard 3setf* order" in
which the value being stored comes last.
.end_defun

.defun remprop symbol indicator
Standard lan{maclisp} fun{remprop}.  If 2symbol* has an
2indicator* property, then that is removed by being spliced out of
the property list, and the sublist of the property list whose
fun{car} is the value (being removed) is returned.  If there is no
such property, 3nil* is returned.  For instance, if one does
.lisp
(putprop 'kitty 'yu-shiang 'flavor)
.end_lisp
then
.lisp
(remprop 'kitty 'flavor)
  =>  (yu-shiang 2and maybe some sublist of the property list*)
.end_lisp

See also the 3remf* macro, (remf-fun), for removing properties
from property lists stored in arbitrary places.

Note:  lan{common lisp} does not define the actual value returned by
3remprop*, only that it will be null if the property was not
found, non-null if it was.  The value returned by lan{nil}
3remprop* is compatible with lan{maclisp}, and will be retained
for that compatibility.
.end_defun

.section "The Print Name"

.defun symbol-name symbol
Returns the name of 2symbol*, which is a string.

Note that a string which is a symbol name should never be modified;
neither should the name of a symbol be changed.

In lan{nil}, the name of a symbol will always be a simple string.

The name of a symbol has variously been called a term_i{print
name} and a term_i{pname}, terms which are being phased out but
still pervade the lan{nil} implementation.
.end_defun

.defun samepnamep sym1 sym2
Returns (true) if 2sym1* and 2sym2* have fun{equal} print
names.  Case 2is* significant.  2sym1* and 2sym2* may be
strings too.  Either (or both) of the symbols may be specified as
strings instead.
.end_defun


.section "Creating Symbols"

.defun make-symbol pname
Makes a new uninterned symbol whose print-name is the string
2pname*.  It will have no value or function bindings, no package,
and an empty property list.

That the print-name (as returned by fun{symbol-print-name}) of the
returned symbol will be fun{eq} to 2pname* should not be
depended upon.
.end_defun

.defun copy-symbol sym &optional copy-props
If 2copy-props* is 3nil*, then this is the same as
3(make-symbol (symbol-name 2sym*))*;  that is, it returns a
virgin symbol with the same print-name as 2sym*.  If
2copy-props* is not 3nil*, then the value and function
definition and property-list and package of 2sym* will be copied
to the new symbol.

Actually, the current dynamic bindings (value and function) of
2sym* are copied to the new global dynamic bindings of the new
symbol.

3copy-symbol* with a null 2copy-props* argument is a
reasonable way to generate a unique symbol which is somewhat mnemonic
although not completely visually unique.  The lan{nil} compiler
copies symbols like 3if-false* to generate tags, for instance;  no
new print name is created, just the basic symbol structure, on which
properties can be placed.
.end_defun

.defun gensym &optional x
Standard inherited-from-lan{maclisp} fun{gensym}.  3gensym*
creates new uninterned symbols.  The print name of the symbol is
constructed by prepending a single character prefix to the decimal
representation of a counter which gets incremented every time
3gensym* is called.  The name has been around for so long that
automatically generated names are commonly refered to as
term_i{gensyms}, and the act of doing so as term_i{gensyming}.

3(gensym)* returns such a constructed symbol.

3(gensym 2name*)* sets the prefix to be 2name*, which must
be a string or a symbol, and then makes a 3gensym*.  (In
lan{maclisp}, only the first character of 2name* is used;  in
lan{nil}, the entire name is.)

3(gensym 2integer*)* sets the counter to 2integer*, and
then makes a 3gensym*.  2integer* must not be negative.
.end_defun

.defun gentemp &optional prefix package
3gensym* creates a symbol in a manner similar to 3gensym*, but
interns it in 2package* (which defaults to the current package).
Additionally, 3gentemp* guarantees that the symbol is unique by
continuing to increment its internal counter until it succeeds in
constructing a symbol which has 2not* already been interned in
2package*.

Unlike 3gensym*, the prefix argument to 3gentemp* must be
specified in every call (it defaults to 3t*), and there is no
provision for resetting the internal counter.

Use this for creating variables for use in macro expansions, because
the symbol can be typed in.
.end_defun

.defun symbol-package symbol
This returns the "home package" of 2symbol*, or 3nil* if
2symbol* does not have one (it is not interned).
.end_defun


.section "The Value and Function Cells"

See also (scope-extent-and-binding-section-page) for discussion
about scope, extent, and binding, and
(nil-value-cell-and-bindings-section-page) for a description of the
lan{nil} internal mechanism for performing variable and function
binding.

Special implementation qualification:  because of the hairy value cell
mechanism in lan{nil}, value cells are not just allocated in the
heap, so (due to lack of code to do some relocation right now) there
is an assembly-time limitation on how many may be created.  Thus,
generating symbols and using the value cells to store things may not
work as well as you expected (an error complaining 7NEW_SLINK wants
to grow the SLINK* occurs).  This limitation is not a function of
the mechanism but rather of the lack of garbage-collector, however.

.defun symbol-value symbol
Returns the current dynamic (special) binding of 2symbol*.

3symbol-value* may be used with 3setf*.
.end_defun

.defun boundp symbol
Returns (true) if 2symbol* has a defined binding, 3nil*
otherwise.  Note that
.lisp
(setq *foo* 1)   =>   1
(let ((*foo* 3))
   (declare (special *foo*))
   (makunbound '*foo*)
   (boundp '*foo*))
 => 3nil*
*foo*   =>   1
.end_lisp
.end_defun

.defun makunbound symbol
"Undefines" the current dynamic value binding of 2symbol*.

An error is signalled if 2symbol* is a constant (as defined by
3defconstant*).
.end_defun

.defun symbol-function symbol
Returns the current dynamic (special) function binding of
2symbol*.

3symbol-function* may be used with 3setf*.
.end_defun

.defun fboundp symbol
Returns (true) if 2symbol* has a defined dynamic function
binding, 3nil* otherwise.  (Like 3boundp*.)
.end_defun

.defun fmakunbound symbol
Analogous to fun{makunbound}.
.end_defun

.section "Additional Names"

Some other lan{maclisp}-compatible, lan{lispm}-compatible, and
older lan{nil}-compatible names.

.defun symeval symbol
Same as 3symbol-value*, (symbol-value-fun).
.end_defun

.defun set symbol value
Same as 3(setf (symbol-value 2symbol*) 2value*)*.
.end_defun

.defun fsymeval symbol
Same as 3symbol-function*, (symbol-function-page).
.end_defun

.defun fset symbol function
Same as 3(setf (symbol-function 2symbol*) 2function*)*.
.end_defun

.defun get-pname symbol
Same as 3symbol-name*, (symbol-name-fun).
.end_defun

.defun plist symbol
Same as 3symbol-plist*, (symbol-plist-fun).  Note that this is
2not* exactly the same as the lan{maclisp} 3plist* function
(maybe it should be made to be?).  The lan{maclisp} 3plist*
function "works" on disembodied property lists (specifically, it takes
the 3cdr* of a list) -- this is sort of an artifact of the
lan{maclisp} implementation.
.end_defun

.defun setplist symbol new-plist
The same as 3(setf (symbol-plist 2symbol*) 2new-plist*)*.
The same lan{maclisp}-compatibility qualifications hold as for
3plist*.
.end_defun

.defun getl symbol indicator-list
Standard lan{maclisp} fun{getl}.  Returns the subpart of the
property list of 2symbol* beginning with the first indicator found
in the list 2indicator-list*, or 3nil* if none was found.  As
in lan{maclisp}, 2symbol* may also be a disembodied property list.
Essentially, this is the third value returned by
.lisp
(get-properties
  (if (symbolp symbol) (symbol-plist symbol) (cdr symbol))
  indicator-list)
.end_lisp
.end_defun

.defun copysymbol symbol &optional copy-props
lan{Maclisp} name for 3copy-symbol* ((copy-symbol-fun)).  Note
that in lan{maclisp}, however, 2copy-props* is a required
argument.
.end_defun


.section "Symbol Concatentation"

The following routines are not defined by lan{common lisp}, but are
fairly useful in their own right by macros etc.

.defun symbolconc &rest frobs
3symbolconc* returns a new symbol (interned in the current
package) whose name is the concatenation of the names of 2frobs*.
Typically, each 2frob* is a symbol, however 3symbolconc* also
allows it to be a fixnum (in which case its decimal printed
representation is used), a string, or a character (which must be
convertible to a string, i.e., satisfy 3string-char-p*).
.end_defun

.defun si:package-symbolconc package-spec &rest frobs
Similar to 3symbolconc*, but uses the package specified by
2package-spec* as the package in which the resultant symbol is
interned.  2package-spec* may be either a package or the name of a
package.
.end_defun

.section "Internal Routines"

.defun %symbol-cons string
Internal symbol conser.  Creates a symbol with 2string* as its
name.  (Note there is no mechanism provided for modifying the
name of a symbol.)  2string* must be a simple string.
.end_defun

The following routines are the primitives from which the earlier
routines could be built.  They are open-coded by the compiler, and
work on all symbols including 3nil*.  They are intended for
low-level code like that which might be found in 3intern*.
However, they are (for the most part) now being phased out in favor of
just using the ordinary functions (e.g., 3symbol-name*) and the
3optimize* declaration (see
(compilation-declarations-section-page)).

.defun %symbol-name symbol
Returns the print name of the symbol 2symbol*.
.end_defun


.defun %symbol-package symbol
Returns the contents of the package cell of 2symbol*.  May be used
with 3setf*.
.end_defun

.defun %symbol-plist symbol
Returns the property list of 2symbol*.  May be used with 3setf*.
.end_defun

.defun %symbol-link symbol
This returns the contents of the term_i{link cell} of 2symbol*.
This is the thing used to implement the totally hairy lan{nil} value
cell scheme, which is not actually described in this manual.
.end_defun

