
% Copyright (c) 1991-2002, The Numerical ALgorithms Group Ltd.
% All rights reserved.
%
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions are
% met:
%
%     - Redistributions of source code must retain the above copyright
%       notice, this list of conditions and the following disclaimer.
%
%     - Redistributions in binary form must reproduce the above copyright
%       notice, this list of conditions and the following disclaimer in
%       the documentation and/or other materials provided with the
%       distribution.
%
%     - Neither the name of The Numerical ALgorithms Group Ltd. nor the
%       names of its contributors may be used to endorse or promote products
%       derived from this software without specific prior written permission.
%
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
% IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
% TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
% PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
% OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
% EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
% PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES-- LOSS OF USE, DATA, OR
% PROFITS-- OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
% LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.



Symbols are one of the basic types manipulated by \Language{}.
The \spadtype{Symbol} domain provides ways to create
symbols of many varieties.
\showBlurb{Symbol}

\xtc{
The simplest way to create a symbol is to ``single quote'' an identifier.
\index{quote}
}{
\spadcommand{X: Symbol := 'x \bound{X}}
}
\xtc{
This gives the symbol even if \spad{x} has been assigned a value.
If \spad{x} has not been assigned a value, then it is possible to omit
the quote.
}{
\spadcommand{XX: Symbol := x}
}
\xtc{
Declarations must be used when working
with symbols, because otherwise the interpreter tries to place
values in a more specialized type \spadtype{Variable}.
}{
\spadcommand{A := 'a}
}
\xtc{
}{
\spadcommand{B := b}
}
\xtc{
The normal way of entering polynomials uses this fact.
}{
\spadcommand{x^2 + 1}
}

\xtc{
Another convenient way to create symbols is to convert a string.
This is useful when the name is to be constructed by a program.
}{
\spadcommand{"Hello"::Symbol}
}
\xtc{
Sometimes it is necessary to generate new unique symbols, for example, to
name constants of integration.
The expression \spad{new()} generates a symbol starting with \spad{%}.
}{
\spadcommand{new()\$Symbol}
}
\xtc{
Successive calls to \spadfunFrom{new}{Symbol} produce different symbols.
}{
\spadcommand{new()\$Symbol}
}
\xtc{
The expression \spad{new("s")} produces a symbol starting with \spad{%s}.
}{
\spadcommand{new("xyz")\$Symbol}
}

\xtc{
A symbol can be adorned in various ways.
The most basic thing is applying a symbol to a list
of subscripts.
}{
\spadcommand{X[i,j] \free{X}}
}

\xtc{
Somewhat less pretty is to attach subscripts, superscripts or arguments.
}{
\spadcommand{U := subscript(u, [1,2,1,2]) \bound{U}}
}
\xtc{
}{
\spadcommand{V := superscript(v, [n]) \bound{V}}
}
\xtc{
}{
\spadcommand{P := argscript(p, [t]) \bound{P}}
}

\xtc{
It is possible to test whether a symbol has scripts using the
\spadfunFrom{scripted?}{Symbol} test.
}{
\spadcommand{scripted? U \free{U}}
}
\xtc{
}{
\spadcommand{scripted? X \free{X}}
}
\xtc{
If a symbol is not scripted, then it may be converted to a string.
}{
\spadcommand{string X \free{X}}
}
\xtc{
The basic parts can always be extracted using the
\spadfunFrom{name}{Symbol} and \spadfunFrom{scripts}{Symbol} operations.
}{
\spadcommand{name U \free{U}}
}
\xtc{
}{
\spadcommand{scripts U \free{U}}
}
\xtc{
}{
\spadcommand{name X \free{X}}
}
\xtc{
}{
\spadcommand{scripts X \free{X}}
}

\xtc{
The most general form is obtained using the \spadfunFrom{script}{Symbol}
operation.
This operation takes an argument which is a list containing, in this order,
lists of subscripts, superscripts, presuperscripts, presubscripts and
arguments to a symbol.
}{
\spadcommand{M := script(Mammoth, [[i,j],[k,l],[0,1],[2],[u,v,w]]) \bound{M}}
}
\xtc{
}{
\spadcommand{scripts M \free{M}}
}
\xtc{
If trailing lists of scripts are omitted, they are assumed to be empty.
}{
\spadcommand{N := script(Nut, [[i,j],[k,l],[0,1]]) \bound{N}}
}
\xtc{
}{
\spadcommand{scripts N \free{N}}
}
