










			XLISP 2.0 LANGUAGE REFERENCE


				     by 

			       Tim I Mikkelsen


			      December 11, 1989








	Copyright  (c) 1989 by Tim I.  Mikkelsen.  All Rights  Reserved.
	No part of this document may be copied, reproduced or translated
	for commercial use without prior written  consent of the author.
	Permission  is granted  for  non-commercial  use as long as this
	notice is left intact.


	________________________________________________________________


	This document is intended to serve as a reference  for the XLISP
	2.0 dialect of LISP.  It includes a description  of each symbol,
	function,  special  form and keyword  available  in XLISP.  This
	reference is not a complete and extensive  introduction  to LISP
	programming.

	If you find problems with the reference or find that I have left
	something out, drop me a line.  If you find this useful, I would
	be interested in hearing that as well.  If you are into 'pretty'
	looking  documents  (as  oppossed to plain ASCII text), I have a
	TeX version of the reference.


			Tim Mikkelsen
			4316 Picadilly Drive
			Fort Collins, Colorado  80526


Each  entry is a symbol  of some  variety  that the  XLISP  system  will
recognize.  The parts of each reference entry include:

	Name            This top line  gives  the name or  symbol of the
			entry.  The   reference   has  the   entries  in
			alphabetical  order.  

	Type            The entry type may be one of the following:

				- function (subr) 
				- predicate function (subr) 
				- special form (fsubr) 
				- reader expansion 
				- defined function (closure) 
				- defined macro (closure) 
				- system variable 
				- system constant 
				- keyword 
				- object 
				- message selector 

	Location        This line  specifies if the entry is built-in to
			the system or an extension.

	Source file     This line  specifies  the source  file where the
			routine  or  code   associated  with  the  entry
			resides.  If  the  entry  is  an  extension,  it
			specifies the source file (usually "init.lsp").

	Common LISP	This  line   specifies   whether  the  entry  is
	compatable	compatable  with the  defintion  of Common LISP.
			There are four levels:

				yes 	- compatable with Common LISP.
				similar	- compatable, some differences.
				related	- related, major differences. 
				no 	- not compatable. 

	Supported on    This line specifies machine dependencies.  A few
			features  are  available   only  on  PCs  or  on
			Macintoshes.  (Note that I have not included the
			Macintosh specific graphics commands.)

	Syntax          This area  defines  the  syntax  or usage of the
			entry.  It  is  also   used   to   specify   the
			arguments.  Items that are enclosed  between a <
			and a > are arguments.  Items enclosed between [
			and ] are optional entries.  Items that have ...
			(elipses) indicate that there can be one or many
			of the  item.  Items  enclosed  between  { and }
			which are  separated  by | indicate  that one of
			the items should be included.

	Description     This  defines the entry,  necessary  conditions,
			results, defaults, etc.

	Examples 	This area shows example uses of the entry.

	Comments        This area includes  additional  information such
			as  compatability   notes,  bugs,  usage  notes,
			potential problems, keystroke equivalences, etc.

*
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(* <expr1> ... )
	<exprN>		-	integer or floating point number/expression

DESCRIPTION

The multiply  (*)  function  multiplies a list of numbers  together  and
returns the result.

EXAMPLES

	(* 1)					; returns 1
	(* 1 2)					; returns 2
	(* 1 2 3)				; returns 6
	(* 1 2 3 4)				; returns 24

	(print (+ 1 2 (* 3.5 (/ 3.9 1.45))))	; returns and prints 12.4138


*
________________________________________________________________________

type: variable
location: built-in
source file: xlinit.c  xlisp.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

*


DESCRIPTION

The *  variable  is  set  to the  result  of  the  previously  evaluated
expression.

EXAMPLES

	(setq a 'b)				; returns B
	*					; returns B
	*					; returns B

NOTE:
It is best not to use this variable in a program.  


**
________________________________________________________________________

type: variable
location: built-in
source file: xlinit.c  xlisp.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

**


DESCRIPTION

The **  variable is set to the result of the next to the last  evaluated
expression.

EXAMPLES

	(setq fee 'fi)				; returns FI
	(setq fo 'fum)				; returns FUM
	**					; returns FI
	**					; returns FUM
	**					; returns FI

NOTE:
It is best not to use this variable in a program.  


***
________________________________________________________________________

type: variable
location: built-in
source file: xlinit.c  xlisp.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

***


DESCRIPTION

The  ***  variable  is set  to the  result  of the  second  to the  last
evaluated expression.

EXAMPLES

	(setq a 'eenie)				; returns EENIE
	(setq b 'meenie)			; returns MEENIE
	(setq c 'beanie)			; returns BEANIE
	***					; returns EENIE
	***					; returns MEENIE
	***					; returns BEANIE
	***					; returns EENIE

NOTE:
It is best not to use this variable in a program.  


+
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(+ <expr1> ... )
	<exprN>		-	integer or floating point number/expression

DESCRIPTION

The add (+)  function  adds a list of numbers  together  and returns the
result.

EXAMPLES

	(+ 1)					; returns 1
	(+ 1 2)					; returns 3
	(+ 1 2 3)				; returns 6
	(+ 1 2 3 4)				; returns 10

	(print (+ 1 2 (* 3.5 (/ 3.9 1.45))))	; returns and prints 12.4138


+
________________________________________________________________________

type: variable
location: built-in
source file: xlinit.c  xlisp.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

+


DESCRIPTION

The + variable is set to the most recent input expression.

EXAMPLES

	(setq hi 'there)			;returns THERE
	+					;returns (SETQ HI (QUOTE THERE))
	+					;returns +

NOTE:
It is best not to use this variable in a program.  


++
________________________________________________________________________

type: variable
location: built-in
source file: xlinit.c  xlisp.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

++


DESCRIPTION

The ++ variable is set to the next to the last input expression.

EXAMPLES

	(setq fee 'fi)				; returns FI
	(setq fo 'fum)				; returns FUM
	++					; returns (SETQ FEE (QUOTE FI))
	++					; returns (SETQ FO (QUOTE FUM))
	++					; returns ++

NOTE:
It is best not to use this variable in a program.  


+++
________________________________________________________________________

type: variable
location: built-in
source file: xlinit.c  xlisp.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

+++


DESCRIPTION

The +++ variable is set to the second to the last input expression.

EXAMPLES

	(setq a 'eenie)				;returns EENIE
	(setq b 'meenie)			;returns MEENIE
	(setq c 'beanie)			;returns BEANIE
	+					;returns (SETQ C (QUOTE BEANIE))
	++					;returns (SETQ C (QUOTE BEANIE))
	+++					;returns (SETQ C (QUOTE BEANIE))
	+					;returns +

NOTE:
It is best not to use this variable in a program.  


-
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(- <expr1> ... )
	<exprN>		-	integer or floating point number/expression

DESCRIPTION

The  subtract  (-) function  subtracts a list of numbers  from the first
number in the list and returns the  result.  If there is only one number
as an argument, it is negated.

EXAMPLES

	(- 1)					; returns -1
	(- 1 2)					; returns -1
	(- 1 2 3)				; returns -4
	(- 1 2 3 4)				; returns -8

	(print (+ 1 2 (* 3.5 (/ 3.9 1.45))))	; returns and prints 12.4138


-
________________________________________________________________________

type: variable
location: built-in
source file: xlinit.c  xlisp.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

-


DESCRIPTION

The - variable is set to the expression currently being evaluated.

EXAMPLES

	-					; returns -
	(setq a -)				; returns (SETQ A -)
	a					; returns (SETQ A -)

NOTE:
It is best not to use this variable in a program.  


/
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(/ <expr1> ... )
	<exprN>		-	integer or floating point number/expression

DESCRIPTION

The divide (/) function divides the first number in the list by the rest
of the  numbers  in  the  list  and  returns  the  result.  If  all  the
expressions  are  integers,  the  division is integer  division.  If any
expression  is a  floating  point  number,  then  the  division  will be
floating point division.

EXAMPLES

	(/ 1)					; returns 1
	(/ 1 2)					; returns 0 (integer division)
	(float (/ 1 2))				; returns 0 (integer division)
	(/ (float 1) 2)				; returns 0.5
	(/ 1 1.0 2)				; returns 0.5     (short cut)
	(/ (float 1) 2 3)			; returns 0.166667
	(/ 1 1.0 2 3 4)				; returns 0.0416667

	(print (+ 1 2 (* 3.5 (/ 3.9 1.45))))	; returns and prints 12.4138

COMMON LISP COMPATABILITY:
Common LISP  supports a ratio data type.  This means that (/ 3 4 5) will
result in the value  3/20.  In XLISP (/ 3 4 5) will result in 0 (because
of integer  values).  (/ 3.0 4 5) will result in 0.15 for both XLISP and
Common LISP.

NOTE:
An easy way to force a sequence  of  integers to be divided as  floating
point  numbers is to insert the number 1.0 after the first  argument  in
the list of arguments to the divider function.


/=
________________________________________________________________________

type: function (subr)
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(/= <expr1> <expr2> ... )
	<exprN>		-	a numeric expression

DESCRIPTION

The /=  (NOT-EQUAL)  operation  takes an  arbitrary  number  of  numeric
arguments.  It checks to see if all the numeric arguments are different.
T is returned if the arguments are  numerically not  equivalent,  NIL is
returned otherwise.

EXAMPLES

	(/= 1 1)				; returns NIL
	(/= 1 2)				; returns T
	(/= 1 1.0)				; returns NIL
	(/= 1 2 3)				; returns T
	(/= 1 2 2)				; returns NIL

	(/= "a" "b")				; error: bad argument type
	(setq a 1) (setq b 12.4)		; set up A and B with values
	(/= a b)				; returns NIL

BUG:
The XLISP /= (NOT-EQUAL)  function checks to see if the each argument is
different from the next in the list.  This means that (/= 1 2 3) returns
T as it is supposed to, but that (/= 1 2 3 2 1) returns T when it should
return NIL.  This is only a problem for the /= (NOT-EQUAL) function.


1+
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(1+ <expr> )
	<expr>		-	integer or floating point number/expression

DESCRIPTION

The increment (1+) function adds one to a number and returns the result.

EXAMPLES

	(1+ 1)					; returns 2
	(1+ 99.1)				; returns 100.1
	(1+ 1 2)				; error: too many arguments


1-
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(1- <expr> )
	<expr>		-	integer or floating point number/expression

DESCRIPTION

The decrement (1-) function  subtracts one from a number and returns the
result.

EXAMPLES

	(1- 1)					; returns 0
	(1- 99.6)				; returns 98.6
	(1- 1 2)				; error: too many arguments


<
________________________________________________________________________

type: function (subr)
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(< <expr1> <expr2> ... )
	<exprN>		-	a numeric expression

DESCRIPTION

The <  (LESS-THAN)  operation  takes  an  arbitrary  number  of  numeric
arguments.  It  checks  to see if  all  the  numbers  are  monotonically
increasing.  T  is   returned   if  the   arguments   are   numerically,
monotonically  increasing, , NIL is returned  otherwise.  In the case of
two  arguments,  this has the effect of  testing if <expr1> is less than
<expr2>.

EXAMPLES

	(< 1 2)					; returns T
	(< 1 1)					; returns NIL
	(< -1.5 -1.4)				; returns T
	(< 1 2 3 4)				; returns T
	(< 1 2 3 2)				; returns NIL

	(< "a" "b")				; error: bad argument type
	(setq a 12) (setq b 13.99)		; set up A and B with values
	(< a b)					; returns T
	(< b a)					; returns NIL


<=
________________________________________________________________________

type: function (subr)
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(<= <expr1> <expr2> ... )
	<exprN>		-	a numeric expression

DESCRIPTION

The <=  (LESS-THAN-OR-EQUAL)  operation  takes an  arbitrary  number  of
numeric   arguments.  It   checks  to  see  if  all  the   numbers   are
monotonically  non-decreasing.  T  is  returned  if  the  arguments  are
numerically,  monotonically  non-decreasing, NIL is returned  otherwise.
For two  arguments,  this has the effect of  testing  if <expr1> is less
than or equal to <expr2>.

EXAMPLES

	(<= 1 1)				; returns T
	(<= 1 2)				; returns T
	(<= 2.0 1.99)				; returns NIL
	(<= 1 2 3 3)				; returns T
	(<= 1 2 3 3 2)				; returns NIL

	(<= "aa" "aa")				; error: bad argument type
	(setq a 12) (setq b 999.999)		; set up A and B with values
	(<= a b)				; returns T
	(<= b a)				; returns NIL


=
________________________________________________________________________

type: function (subr)
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(= <expr1> <expr2> ... )
	<exprN>		-	a numeric expression

DESCRIPTION

The  =  (EQUALITY)  operation  takes  an  arbitrary  number  of  numeric
arguments.  It  checks  to  see if  all  the  numbers  are  equal.  T is
returned if all of the  arguments are  numerically  equal to each other,
NIL is returned otherwise.

EXAMPLES

	(= 1 1)					; returns T
	(= 1 2)					; returns NIL
	(= 1 1.0)				; returns T
	(= 1 1.0 1 (+ 0 1))			; returns T
	(= 1 1.0 1.00001)			; returns NIL

	(= "a" "b")				; error: bad argument type
	(setq a 1) (setq b 1.0)			; set up A and B with values
	(= a b)					; returns T


>
________________________________________________________________________

type: function (subr)
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(> <expr1> <expr2> ... )
	<exprN>		-	a numeric expression

DESCRIPTION

The >  (GREATER-THAN)  operation  takes an  arbitrary  number of numeric
arguments.  It  checks  to see if  all  the  numbers  are  monotonically
decreasing.  T  is   returned   if  the   arguments   are   numerically,
monotonically decreasing, NIL is returned otherwise.  For two arguments,
this has the effect of testing if <expr1> is greater than <expr2>.

EXAMPLES

	(> 1 1)					; returns NIL
	(> 1 2)					; returns NIL
	(> 2.0 1.99)				; returns T
	(> 3 2 1)				; returns T
	(> 3 2 2)				; returns NIL

	(> "aa" "aa")				; error: bad argument type
	(setq a 12) (setq b 999.999)		; set up A and B with values
	(> a b)					; returns NIL
	(> b a)					; returns T


>=
________________________________________________________________________

type: function (subr)
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(>= <expr1> <expr2> ... )
	<exprN>		-	a numeric expression

DESCRIPTION

The >=  (GREATER-THAN-OR-EQUAL)  operation takes an arbitrary  number of
numeric   arguments.  It   checks  to  see  if  all  the   numbers   are
monotonically non-increasing.  T is returned if <expr1> is the arguments
are   numerically,   monotonically   non-increasing,   NIL  is  returned
otherwise.  For two arguments, this has the effect of testing if <expr1>
is greater than or equal to <expr2>.

EXAMPLES

	(>= 1 2)				; returns NIL
	(>= 1 1)				; returns T
	(>= -1.5 -1.4)				; returns NIL
	(>= 3 2 1)				; returns T
	(>= 3 2 2)				; returns T
	(>= 3 2 3)				; returns NIL

	(>= "aa" "abc")				; error: bad argument type
	(setq a 12) (setq b 13.99)		; set up A and B with values
	(>= a b)				; returns NIL
	(>= b a)				; returns T


abs
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(abs <expr> )
	<expr>		-	integer or floating point number/expression

DESCRIPTION

The ABS  function  finds the absolute  value of a number and returns the
result.

EXAMPLES

	(abs 1)					; returns 1
	(abs -99)				; returns 99
	(abs -99.9)				; returns 99.9
	(abs -32768)				; returns 32768

COMMON LISP COMPATABILITY:
Common LISP supports a complex  number data type which is not  supported
in XLISP.


address-of
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlsys.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(address-of <expr> )
	<expr>		-	an expression

DESCRIPTION

The ADDRESS-OF function returns the internal memory address of the XLISP
node that corresponds to <expr>.  The value returned is an integer.

EXAMPLES

	(setq var 0)				; set up VAR with 0
	(address-of var)			; returns 123224
	(address-of 'var)			; returns 182638
	(peek (address-of var))			; returns 83951616
	(peek (1+ (address-of var)))		; returns 16777216
	(peek (+ 2 (address-of var)))		; returns 0  <-- value of VAR
	(setq var 14)				; change the value to 14
	(peek (+ 2 (address-of var)))		; returns 14
	(setq var 99)				; change the value to 99
	(peek (+ 2 (address-of var)))		; returns 99

CAUTION:
Be careful  when  modifying  the  internal  state of XLISP.  If you have
modified it, it would be a good idea to exit XLISP and  re-enter  before
doing any work you really want to retain.


alloc
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xldmem.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(alloc  <size> )
	<size>		-	an integer expression

DESCRIPTION

The ALLOC  function  changes the number of memory  nodes  allocated  per
segment  whenever  memory is  expanded.  The  previous  number  of nodes
allocated per segment is the value returned as the result.  The power up
default if 1000 nodes per  segment.  Note that  ALLOC does not,  itself,
expand memory.  You need to execute the EXPAND function to do the expand
operation.

EXAMPLES

	(room)					; prints  Nodes:       4000
						;	  Free nodes:  1669
						;	  Segments:    4
						;         Allocate:    1000
						;	  Total:       52570
						;	  Collections: 8
						; returns NIL
	(alloc 2000)				; returns 1000
	(room)					; prints  Nodes:       4000
						;	  Free nodes:  1655
						;	  Segments:    4
						;	  Allocate:    2000
						;	  Total:       52570
						;	  Collections: 8
						; returns NIL


and
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(and  [ <expr1> ... ] )
	<exprN>		-	an expression

DESCRIPTION

The AND special form evaluates a sequence of expressions and returns the
effect  of a  logical  AND on  the  expressions.  If, at any  point,  an
expression  is NIL,  NIL is  returned  as  AND's  result.  If all of the
expressions  have a  non-NIL  value,  the  last  expression's  value  is
returned as the result.  Evaluation of the expressions will stop when an
expression evaluates to NIL, none of the subsequent  expressions will be
evaluated.  If there are no expressions, AND returns T as its result.

EXAMPLES

	(and T "boo" "hiss" T "rah")		; returns "rah"
	(and T T T T)				; returns T
	(and)					; returns T
	(and (princ "hi") NIL (princ "ho"))	; prints  hi and returns NIL
	(and (princ "hi") (princ " de ") 	; prints  hi de ho
			  (princ "ho"))		;   returns "ho"

	(setq a 5)   (setq b 6)			; set up A and B
	(if (and (numberp a) 			; if      A is a number
		 (numberp b) 			;     and B is a number
		 (< a b) )			;     and A<B
	  (print "A is less than B")		;   THEN do this
	  (print "something else happened"))	;   ELSE do this
						; prints "A is less than B"


:answer
________________________________________________________________________

type: message selector
location: built-in
source file: xlobj.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(send <class> :answer <message> <args> <code> )
	<class>		- 	an existing class
	<message>	- 	the message symbol
	<args>		-	formal argument list to the <msg> method
				of the same form as a lambda argument list
	<code>		-	a list containing the method code

DESCRIPTION

The :ANSWER  message  selector adds or changes a method in the specified
<class>.  This method  consists of the  <message>  selector  symbol, the
<arg> formal  argument list and the executable code associated  with the
<message>.

EXAMPLES
	(setq myclass (send class :new '(var)))	; create MYCLASS with VAR
	(send myclass :answer :isnew '()	; set up initialization
		'((setq var nil) self))
	(send myclass :answer :set-it '(value)	; create :SET-IT message
		'((setq var value)))	
	(send myclass :answer :mine '() 	; create :MINE message
		'((print "hi there")))		
	(setq my-obj (send myclass :new))	; create MY-OBJ of MYCLASS
	(send my-obj :set-it 5)			; VAR is set to 5
	(send my-obj :mine)			; prints  "hi there"

NOTE:
When you define a <message> in a <class>,  the  <message>  is only valid
for instances of the <class> or its  sub-classes.  You will get an error
if you try to send the  <message>  to the  <class>  where  it was  first
defined.  If you wish to add a  <message>  to the  <class>,  you need to
define it in the super-class of <class>.

MESSAGE STRUCTURE:
The normal XLISP  convention  for a <message> is to have a valid  symbol
preceeded  by a  colon  like  :ISNEW  or  :MY-MESSAGE.  However,  it  is
possible  to define a  <message>  that is a symbol  without a colon, but
this makes the code less readable.


append
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(append [ <expr1> ... ] )
	<exprN>		-	a list or list expression

DESCRIPTION

The APPEND function takes an arbitrary  number of lists and splices them
together into a single list.  This single list is returned.  If an empty
list NIL is appended, it has no effect - it does not appear in the final
list.  (Remember  that  '(NIL) is not an empty  list.)  If an atom is is
appended, it also has no effect and will not appear in the final list.

EXAMPLES

	(append)				; returns NIL
	(append 'a 'b)				; returns B
	(append '(a) '(b))			; returns (A B)
	(append 'a '(b))			; returns (B)
	(append '(a) 'b)			; returns (A . B)
	(append '(a) nil)			; returns (A)
	(append (list 'a 'b) (list 'c 'd))	; returns (A B C D)
	(append '(a (b)) '(c (d)))		; returns (A (B) C (D))
	(append '(a) nil nil nil '(b))		; returns (A B)
	(append '(a) '(nil) '(b))		; returns (A NIL B)


apply
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(apply <function> <args> )
	<function>	-	the function or symbol to be applied to <args>
	<args>		-	a list that contains the arguments to be passed 
				to <function>

DESCRIPTION

APPLY causes  <function> to be evaluated with <args> as the  parameters.
APPLY returns the result of <function>.  <args> must be in the form of a
list.

EXAMPLES

	(defun my-add (x y)			; create MY-ADD function
		(print "my add")
		(+ x y))
	(my-add 1 2)				; prints "my add" returns 3
	(apply 'my-add '(2 4))			; prints "my add" returns 6
	(apply 'my-add 1 2)			; error: bad argument type 
	(apply 'my-add '(1 2 3))		; error: too many arguments 

	(apply (function +) '(9 10))		; returns 19
	(apply '+ '(4 6))			; returns 10
	(apply 'print '("hello there"))		; prints/returns "hello there"
	(apply 'print "hello there")		; error: bad argument type

NOTE:
Note that when using APPLY to cause the evaluation of a system function,
you  can  use the  quoted  name  of the  function  (like  'PRINT  in the
examples).  You can also use the actual  function (like  (FUNCTION +) in
the examples).


*applyhook*
________________________________________________________________________

type: system variable 
location: built-in
source file: xlglob.c  (not implemented)
Common LISP compatible: similar
supported on: all machines

SYNTAX

*applyhook*


DESCRIPTION

*APPLYHOOK* is a system  variable that exists and is initialized to NIL.
It is a hook that is intended to contain a user  function  that is to be
called  whenever  a function  is applied to a list of  arguments.  It is
not, however, implemented in XLISP 2.0 - it only exists as a dummy hook.

EXAMPLES
	*applyhook*				; returns NIL

COMMON LISP COMPATABILITY:
*APPLYHOOK*  is  defined in Common  LISP and is often used to  implement
function stepping functionality in a debugger.


aref
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(aref <array> <element> )
	<array> 	- 	specified array
	<element>	-	the element number to be retrieved

DESCRIPTION

AREF returns the specified  element out of a previously  created  array.
Array  elements  may be any valid  lisp data type -  including  lists or
arrays.  Arrays  made by  MAKE-ARRAY  and  accessed  by AREF are base 0.
This means the first  element is  accessed  by element  number 0 and the
last  element is  accessed  by element  number n-1 (where n is the array
size).  Array elements are initialized to NIL.

EXAMPLES
	(setq my-array '#(0 1 2 3 4))		; make the array
	(aref my-array 0)			; return 0th (first) element
	(aref my-array 4)			; return 4th (last)  element
	(aref my-array 5)			; error: non existant element
	my-array				; look at array 

	(setq new (make-array 4))		; make another array
	(setf (aref new 0) (make-array 4))	; make new[0] an array of 4
	(setf (aref (aref new 0) 1) 'a)		; set new[0,1] = 'a
	(setf (aref new 2) '(a b c))		; set new[2] = '(a b c)
	new					; look at array

READ MACRO:
There is a built-in  read-macro  for arrays - # (the hash symbol).  This
allows you to create  arbitrary arrays with initial values without going
through a MAKE-ARRAY function.

NOTE:
This function  returns the value of an array element.  However, there is
no  equivalent  direct  function to set the value of an array element to
some  value.  To set an element  value, you must use the SETF  function.
The SETF function is a  generalized  function that allows you to set the
value of arbitrary lisp entities.

COMMON LISP COMPATABILITY:
XLISP  only  supports   one-dimensional  arrays.  Common  LISP  supports
multi-dimension arrays.


arrayp
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(arrayp <expr> )
	<expr>		-	the expression to check

DESCRIPTION

The ARRAYP predicate  checks if an <expr> is an array.  T is returned if
<expr> is an array, NIL is returned otherwise.

EXAMPLES

	(arrayp #(0 1 2))			; returns T - array 
	(setq a #(a b c))			; 
	(arrayp a)				; returns T - evaluates to array

	(arrayp '(a b c))			; returns NIL - list
	(arrayp 1)				; returns NIL - integer
	(arrayp 1.2)				; returns NIL - float
	(arrayp 'a)				; returns NIL - symbol
	(arrayp #\a)				; returns NIL - character
	(arrayp NIL)				; returns NIL - NIL


assoc
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(assoc <expr> <a-list> [ { :test | :test-not } <test> ] )
	<expr>		-	the expression to find - an atom or list
	<a-list>	-	the association list to search
	<test>		-	optional test function (default is EQL)

DESCRIPTION

An  association  list is a collection  of list pairs of the form ( (key1
item1)  (key2  item2) ...  (keyN  itemN) ).  ASSOC  searches  through an
association  list <a-list>  looking for the key (a CAR in an association
pair)  that  matches  the  search  <expr>.  If a match  is  found,  that
association pair (keyN itemN) is returned as the result.  If no match is
found, a NIL is  returned.  You may specify your own test with the :TEST
and :TEST-NOT keywords followed by the test you which to perform.

EXAMPLES

	(setq mylist '((a . my-a)  (b . his-b) 	; set up an association
		       (c . her-c) (d . end)))	;   list
	(assoc 'a mylist)			; returns (A . MY-A)
	(assoc 'b mylist)			; returns (B . HIS-B)
	(assoc 1 mylist)			; returns NIL

	(setq agelist '((1 (bill bob)) 		; set up another 
			(2 (jane jill)) 	;   association list
			(3 (tim tom))		; 
			(5 (larry daryl daryl))	;
		       ))			;
	(assoc 1 agelist)			; returns (1 (BILL BOB))
	(assoc 3 agelist :test '>=)		; returns (1 (BILL BOB))
	(assoc 3 agelist :test '<)		; returns (5 (LARRY DARYL DARYL))
	(assoc 3 agelist :test '<=)		; returns (3 (TIM TOM))
	(assoc 3 agelist :test-not '>=)		; returns (5 (LARRY DARYL DARYL))

	(assoc '(a b) '( ((c d) e) ((a b) x) )	; use a list as the search 
		      :test 'equal)		;   note the use of EQUAL
						;   returns ((A B) X)

NOTE:
The  ASSOC  function  can  work  with a list or  string  as the  <expr>.
However, the default EQL test does not work with lists or strings,  only
symbols  and  numbers.  To make  this  work,  you need to use the  :TEST
keyword along with EQUAL for <test>.

COMMON LISP COMPATABILITY:
Common  LISP  supports  the use of the :KEY  keyword  which  specifies a
function  that is  applied  to each  element  of  <a-list>  before it is
tested.  XLISP does not support this.


atom
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(atom <expr> )
	<expr>		-	the expression to check

DESCRIPTION

The ATOM  predicate  checks if the <expr> is an atom.  T is  returned if
<expr> is an atom, NIL is returned otherwise.

EXAMPLES

	(atom 'a)				; returns T - symbol
	(atom #'atom)				; returns T - subr - function 
	(atom "string")				; returns T - string
	(atom 4)				; returns T - integer
	(atom 4.5)				; returns T - float
	(atom object)				; returns T - object
	(atom #(1 2 3))				; returns T - array
	(atom #'quote)				; returns T - fsubr
	(atom *standard-output*)		; returns T - stream
	(atom '())				; returns T - NIL is an atom 
	(atom #'defvar)				; returns T - closure - macro
	(atom (lambda (x) (print x)))		; returns T - closure - lambda

	(atom '(a b c))				; returns NIL - list 

	(setq a '(a b))				; set up A with value (A B)
	(atom a)				; returns NIL - 
						;   value of A is not an atom

NOTE:
NIL or '()  is  used  in  many  places  as a  list-class  or  atom-class
expression.  Both ATOM and LISTP, when applied to NIL, return T.


&aux
________________________________________________________________________

type: keyword
location: built-in
source file: xleval.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

&aux [ <aux-var> | ( <aux-var> <aux-value> ) ] ...
	<aux-var>	-	auxiliary variable 
	<aux-value>	-	auxiliary variable initialization

DESCRIPTION

In XLISP, there are several times that you define a formal argument list
for a body of code (like  DEFUN,  DEFMACRO,  :ANSWER  and  LAMBDA).  The
<aux-var> variables are a mechanism for you to define variables local to
the  function  or   operation   definition.  If  there  is  an  optional
<aux-value>,  they  will be set to that  value on  entry  to the body of
code.  Otherwise,  they  are  initialized  to  NIL.  At the  end of  the
function or operation  execution,  these local  symbols and their values
are are removed.

EXAMPLES

	(defun my-add 				; define function MY-ADD
	  (num1 &rest num-list &aux sum)	;   with 1 arg, rest, 1 aux var
	  (setq sum num1)			;   clear SUM
	  (dotimes (i (length num-list) )	;   loop through rest list
	     (setq sum (+ sum (car num-list)))  ;      add the number to sum
	     (setq num-list (cdr num-list)))	;      and remove num from list
	  sum)					;   return sum when finished
	(my-add 1 2 3 4)			; returns 10
	(my-add 5 5 5 5 5)			; returns 25

	(defun more-keys 			; define MORE-KEYS
		( a 				;   with 1 parameter A		
		  &aux b 			;   with local var B
		       (c 99) 			;        local var C= 99
		       (d T)  )			;        local var D= T
		(format T "a=~a " a)		;   body of the function
		(format T "b=~a " b)		;
		(format T "c=~a " c)		;
		(format T "d=~a " d))		;
	(more-keys "hi")			; prints a=hi b=NIL c=99 d=T


backquote
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c  and  xlread.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(backquote <expr> )
	<expr>		-	an expression which is not evaluated 
				except for comma and comma-at portions

DESCRIPTION

BACKQUOTE  returns the <expr>  unevaluated - like QUOTE.  The difference
is that portions of the <expr> may be evaluated  when they are preceeded
by a COMMA (,) or COMMA-AT (,@).  COMMA will evaluate the portion of the
expression the comma  preceeds.  If the portion is an atom or a list, it
is  placed as is within  the  expression.  COMMA-AT  will  evaluate  the
portion of the expression that the comma-at preceeds.  The portion needs
to be a list.  The list is spliced into the  expression.  If the portion
is not a list, COMMA-AT will splice in nothing.

EXAMPLES

	(setq box 'stuff-inside)		; BOX contains STUFF-INSIDE
	(print box)				; prints STUFF-INSIDE
	(quote (i have the box))		; returns (I HAVE THE BOX)
	(backquote (i have the box))		; returns (I HAVE THE BOX)
	(backquote (I have (comma box)))	; returns (I HAVE STUFF-INSIDE)
	(backquote (I have the ,@box))		; returns (I HAVE THE)

	(setq automobile '(a van))		; set up AUTOMOBILE 
	(backquote (I have automobile))		; returns (I HAVE AUTOMOBILE)
	(backquote (I have (comma automobile)))	; returns (I HAVE (A VAN))
	(backquote (I have ,@automobile))	; returns (I HAVE A VAN)
	`(I have ,@automobile)			; returns (I HAVE A VAN)

READ MACRO:
XLISP  supports the normal read macro of a single reverse quote (`) as a
short-hand method of writing the BACKQUOTE special form.

NOTE: 
BACKQUOTE and COMMA and COMMA-AT are very useful in defining  macros via
DEFMACRO.


baktrace
________________________________________________________________________

type: function (subr)
location: built-in
source file: xldbug.c  and  xlsys.c
Common LISP compatible: related
supported on: all machines

SYNTAX

(baktrace  [ <level> ]  )
	<level>		-	an optional integer expression

DESCRIPTION

The BAKTRACE function is used to examine the system execution stack from
within the break look.  It shows the nested forms that got the system to
the  current  state.  The break loop can be entered  by a system  error,
ERROR,  CERROR or BREAK  functions.  If the  <levels>  parameter  is not
specified, all the nested forms will be shown back to the main loop form
that  started the  execution.  If <level> is  specified  the most recent
<level> nested forms will be shown.

EXAMPLES

	(defun out (x) (print x) (mid 99))	; define OUT
	(defun mid (x) (print x) (in 999))	; define MID
	(defun in (x) (print x) (break "in" x))	; define IN with a BREAK
	(out 9)					; prints  9
						;         99
						;         999
						; break: in - 999
	(baktrace)		; this is done from within break loop
				; prints  Function: #<Subr-BAKTRACE: #22cb4>
				;         Function: #<Subr-BREAK 
				;         Arguments: 
				;	    "in"
				;	    999
				;         Function: #<Closure-IN: #2bc44>
				;         Arguments: 
				;	    999
				;         Function: #<Closure-MID: #2bd20>
				;         Arguments: 
				;           99
				;         Function: #<Closure-OUT: #2bec4>
				;         Arguments: 
				;           9
				;         NIL

COMMON LISP COMPATABILITY:
Common  LISP  has  a  similar  function  called  BACKTRACE.  For  XLISP,
BAKTRACE is spelled with no 'c'.


block
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(block  <name> [ <body> ... ] )
	<name>		-	an unevaluated symbol for the block name
	<body>		-	a series of expressions

DESCRIPTION

The BLOCK special form  specifies a  'named-block'  construct.  The last
expression  in <body>  will be  returned by the BLOCK  construct  as its
result unless a RETURN or  RETURN-FROM  is executed  within  BLOCK.  The
RETURN exit will exit the nearest  (inner-most)  BLOCK.  The RETURN-FROM
exit will exit the specified block.

EXAMPLES

	(block out 				; outer BLOCK
	   (print "outer")			; 
	   (block in 				; inner BLOCK
		(print "inner")			;
		(return-from out "all done")	;
		(print "won't get here")	;
	   )					;
	)					; prints "outer"
						; prints "inner"
						; returns "all done"


both-case-p
________________________________________________________________________

type: predicate function (subr) 
location: built-in
source file: xlstr.c 
Common LISP compatible: yes
versions: all machines

SYNTAX

(both-case-p <char> )
	<char>		-	a character expression

DESCRIPTION

The  BOTH-CASE-P  predicate  checks  if  the  <char>  expression  is  an
alphabetic  character.  If <char> is an  alphabetic  (either an upper or
lower  case)  character a T is  returned,  otherwise a NIL is  returned.
Upper case  characters  are 'A' (ASCII  decimal  value 65)  through  'Z'
(ASCII decimal value 90).  Lower case  characters are 'a' (ASCII decimal
value 97) through 'z' (ASCII decimal value 122).

EXAMPLES

	(both-case-p #\A)			; returns T
	(both-case-p #\a)			; returns T
	(both-case-p #\1)			; returns NIL
	(both-case-p #\[)			; returns NIL


boundp
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(boundp <symbol> )
	<symbol>	-	the symbol expression to check for a value

DESCRIPTION

The BOUNDP  predicate checks to see if <symbol> is a symbol with a value
bound to it.  T is  returned if  <symbol>  has a value, NIL is  returned
otherwise.  Note that <symbol> is a symbol  expression - it is evaluated
and the resulting expression is the one that is checked.

EXAMPLES

	(setq a 1)				; set up A with value 1
	(boundp 'a)				; returns T - value is 1

	(defun foo (x) (print x))		; set up function FOO
	(boundp 'foo)				; returns NIL - value is closure
	(boundp 'defvar)			; returns NIL - value is closure
	(boundp 'car)				; returns NIL - value is closure

	(print myvar)				; error: unbound variable
	(BOUNDP 'myvar)				; returns NIL 
	(setq myvar 'abc)			; set up MYVAR with a value
	(BOUNDP 'myvar)				; returns T - because of SETQ

	(setq myvar 'qq)			; set up MYVAR to have value QQ
	(BOUNDP myvar)				; returns NIL - because QQ has
						;               no value yet
	(setq qq 'new-value)			; set QQ to have value NEW-VALUE
	(BOUNDP myvar)				; returns T


break
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c  and  xldbug.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(break  [ <err-msg>  [ <arg> ] ]  )
	<err-msg>	-	a string expression for the error message
	<arg>		-	an optional expression 

DESCRIPTION

The  BREAK  function  allows  the  entry  into  the  break  loop  with a
continuable  error.  The continuable  error  generated by BREAK does not
require any corrective action.  The form of the message generated is:

	break: <err-msg> - <arg>
	if continued: return from BREAK

The default for <err-msg> is  "**BREAK**".  From within the  break-loop,
if a CONTINUE form is evaluated  then a NIL is returned  from BREAK.  If
desired, the CLEAN-UP and TOP-LEVEL  functions may be evaluated to abort
out of the break loop.

EXAMPLES

	(break)					; break: **BREAK**

	(break "out")				; break: out

	(break "it" "up")			; break: it - "up"

COMMON LISP COMPATIBILITY:
Common  LISP and XLISP  have the same  basic  form and style for  BREAK.
However, the <err-msg>  string in Common LISP is sent to FORMAT.  FORMAT
is a output  function that takes in format strings that include  control
information.  Although,  XLISP does have the FORMAT  function, it is not
used for error  messages.  Porting  from XLISP to Common  LISP will work
fine.  When  porting  from Common  LISP to XLISP, you will need to check
for this embedded control information in the messages.


*breakenable*
________________________________________________________________________

type: system variable
location: built-in
source file: xldbug.c
Common LISP compatible: no
supported on: all machines

SYNTAX

*breakenable*


DESCRIPTION

*BREAKENABLE* is a system variable that controls entry to the break loop
and the  trapping  of errors.  If  *BREAKENABLE*  is set to NIL, then no
errors  from  the   system,   ERROR  and  CERROR  will  be  trapped.  If
*BREAKENABLE*  is non-NIL, the break loop will handle these errors.  The
BREAK  function is not affected by  *BREAKENABLE*  and will always force
entry  to  the  break  loop.  The  INIT.LSP   initialization  file  sets
*BREAKENABLE* to T, which allows errors to be trapped by the break loop.

The DEBUG function causes  *BREAKENABLE* to be set to T.  NODEBUG causes
*BREAKENABLE* to be set to NIL.

EXAMPLES

	(setq *breakenable* NIL)		; disable break loop
	(defun foo (x) (+ x x))			; define FOO
	(foo "a")				; error: bad argument type 
						;   but did NOT enter break loop
	(setq *breakenable* T)			; enable break loop
	(foo "a")				; error: bad argument type 
						;   entered break loop


car
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(car <expr> )
	<expr>		-	a list or list expression

DESCRIPTION

CAR  returns  the  first  element  of  the   expression.  If  the  first
expression  is itself a list, then the sublist is returned.  If the list
is NIL, NIL is returned.

EXAMPLES
	(car '(a b c))				; returns A
	(car '((a b) c d))			; returns (A B)
	(car NIL)				; returns NIL
	(car 'a)				; error: bad argument type

	(setq bob '(1 2 3))			; set up variable BOB
	(car bob)				; returns 1

caar cadr
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(caar <expr> )
(cadr <expr> )
	<expr>		-	a list or list expression

DESCRIPTION

The CAAR and CADR functions go through the list expression and perform a
sequence of CAR/CDR operations.  The sequence of operations is performed
from right to left.  So CADR does a CDR on the expression, followed by a
CAR.  If at any point the list is NIL, NIL is returned.  If at any point
a CAR  operation is performed on an atom (as opposed to a list) an error
is reported - "error:  BAD ARGUMENT".

EXAMPLES
	(setq mylist '( (a1 a2) 		; make a 2-level list
			(b1 b2) 
			(c1 c2) 
			(d1 d2) ) )
	(caar mylist)				; returns A1
	(cadr mylist)				; returns (B1 B2)
	(cdar mylist)				; returns (A2)
	(cddr mylist)				; returns ((C1 C2) (D1 D2))

	(caar 'a)				; error: bad argument
	(caar nil)				; returns NIL
	(cadr nil)				; returns NIL
	(cdar nil)				; returns NIL
	(cddr nil)				; returns NIL

caaar caadr cadar caddr 
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(caaar <expr> )
(caadr <expr> )
(cadar <expr> )
(caddr <expr> )
	<expr>		-	a list or list expression

DESCRIPTION

The  CAAAR,  CAADR,  CADAR  and  CADDR  functions  go  through  the list
expression  and perform a sequence of CAR/CDR  operations.  The sequence
of operations  is performed  from right to left.  So CADDR does a CDR on
the  expression,  followed by a CDR, followed by a CAR.  If at any point
the list is NIL, NIL is  returned.  If at any point a CAR  operation  is
performed  on an atom  (as  opposed  to a list) an error is  reported  -
"error:  BAD ARGUMENT".

EXAMPLES
	(setq mylist '( ( (a b) (c d) (e f) )	; make a 3-level list
        	        ( (g h) (i j) (k l) )
                	( (m n) (o p) (q r) )
	                ( (s t) (u v) (w x) )
			) )
	(caaar mylist)				; returns A
	(caadr mylist)				; returns (G H)
	(cadar mylist)				; returns (C D)
	(caddr mylist)				; returns ((M N) (O P) (Q R))
	(cdaar mylist)				; returns (B)
	(cdadr mylist)				; returns ((I J) (K L))
	(cddar mylist)				; returns ((E F))
	(cdddr mylist)				; returns (((S T) (U V) (W X)))

caaaar caaadr ... caddar cadddr
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(caaaar <expr> )
(caaadr <expr> )
(caadar <expr> )
...
(caddar <expr> )
(cadddr <expr> )
	<expr>		-	a list or list expression

DESCRIPTION

The CAAAAR,  CAAADR ...  CADDAR,  CADDDR  functions  go through the list
expression  and perform a sequence of CAR/CDR  operations.  The sequence
of operations is performed  from right to left.  So CAADDR does a CDR on
the  expression,  followed  by a CDR,  followed  by a CAR,  followed  by
another  CAR.  If at any point the list is NIL, NIL is  returned.  If at
anypoint a CAR  operation is performed on an atom (as opposed to a list)
an error is reported - "error:  BAD ARGUMENT".

EXAMPLES
	(setq mylist '( ( (a b) (c d) (e f) )	; make a 3-level list
        	        ( (g h) (i j) (k l) )
                	( (m n) (o p) (q r) )
	                ( (s t) (u v) (w x) )
			) )
	(caaadr mylist)				; returns G
	(caadar mylist)				; returns C
	(cdadar mylist)				; returns (D)
	(cadadr mylist)				; returns (I J)
	(cdaddr mylist)				; returns ((O P) (Q R))
	(cadddr mylist)				; returns ((S T) (U V) (W X))

case
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(case  <expr>  [ ( <value> <action> ) ... ]  )
	<expr>		-	an expression
	<value>		-	an unevaluated expression or list of unevaluated
				expressions to compare against <expr>
	<action>	-	an expression 

DESCRIPTION

The CASE  special  form is a  selection  control  form.  CASE  evaluates
<expr>.  This value is then  compared  against all the <value>  entries.
If <value> is a single  atom, the atom is compared  against  <expr>.  If
<value> is a list, each of the elements of the list are compared against
<expr>.  The <action>  associated  with the first  <value> that  matches
<expr>  is  evaluated  and  returned  as CASE's  result.  If no  <value>
matches, a NIL is returned.  If the last  <value> is the T symbol and no
other  <value> has matched  <expr>, then CASE will evaluate the <action>
associated  with T.  If there  are  multiple  T  entries,  the  first is
considered to be the end of the CASE.

EXAMPLES

	(case 'a ('a "a"))			; returns "a"
	(case 'a ('b "b"))			; returns NIL
	(case 9 ( 1 "num") (t "ho") (t "hi"))	; returns "ho"
	(case 'a ((1 2 3 4) "number")		; 
		( (a b c d) "alpha"))		; returns "alpha"
	
	(case 'a)				; returns NIL
	(case)					; returns NIL

	(defun print-what (parm)		; define a function
	  (case (type-of parm)			;  check PARM type
		( flonum   (print "float"))	;
		( fixnum   (print "integer"))	;
		( string   (print "string"))	;
		( cons     (print "list"))	;
		( T        (print "other")))	;  otherwise 
	  NIL)					;  and always return NIL
	(print-what 1.2)			; prints  "float"   returns NIL
	(print-what 3)				; prints  "integer" returns NIL
	(print-what "ab")			; prints  "string"  returns NIL
	(print-what '(a b))			; prints  "list"    returns NIL
	(print-what 'a)				; prints  "other"   returns NIL

NOTE:
The CASE special form does not work with a list or string as the <expr>.
This is because CASE defines the test used to be the EQL test which does
not work with lists or strings, only symbols and numbers.

COMMON LISP COMPATABILITY:
In XLISP, you can use the value T as the last value to get the effect of
'otherwise'.  Common LISP uses the symbol  OTHERWISE and T for this.  If
you are  porting in code from Common  LISP, be careful to make sure T is
used instead of OTHERWISE in CASE  statements.  (Note that no error will
be generated, XLISP will just try to match the <expr> to OTHERWISE.


catch
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(catch  <tag-symbol>  [ <expr> ... ]  )
	<tag-symbol>	-	an expression that evaluates to a symbol
	<expr>		-	an optional series of expressions to be 
				evaluated

DESCRIPTION

The CATCH and THROW  special  forms allow for non-local  exits and traps
without going through the intermediate evaluations and function returns.
If there is a CATCH for a <sym-tag>  that has no THROW  performed to it,
CATCH returns the value  returned from <expr>.  If there is no <expr>, a
NIL is returned.  If a THROW is evaluated with no  corresponding  CATCH,
an error is  generated  -  "error:  no  target  for  THROW".  If, in the
calling   process,   more  than  one  CATCH  is  set  up  for  the  same
<tag-symbol>, the most recently  evaluated  <tag-symbol> will be the one
that does the actual catching.

EXAMPLES

	(catch 'mytag)				; returns NIL	- no THROW
	(catch 'mytag (+ 1 (+ 2 3)))		; returns 6 	- no THROW
	(catch 'mytag (+ 1 (throw 'mytag)))	; returns NIL	- caught it
	(catch 'mytag (+ 1 (throw 'mytag 55)))	; returns 55	- caught it
	(catch 'mytag (throw 'foo))		; error: no target for THROW

	(defun in (x) 				; define IN
	   (if (numberp x) (+ x x)		;   if number THEN double
        		   (throw 'math 42)))	;             ELSE throw 42
	(defun out (x)				; define OUT
	  (princ "<")				;   
	  (princ  (* (in x) 2))			;   double via multiply
	  (princ ">") "there")			;
	(defun main (x)				; define MAIN
	  (catch 'math (out x)))		;   with CATCH
	(in 5)					; returns 10
	(out 5)					; prints  <20>   returns "there"
	(main 5)				; prints  <20>   returns "there"
	(main 'a)				; prints  <	 returns 42

NOTE:
Although  CATCH  and  THROW  will  accept a  <tag-symbol>  that is not a
symbol, it will not find this  improper  <tag-symbol>.  An error will be
generated - "error:  no target for THROW".


cdr
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(cdr <expr> )
	<expr>		-	a list or list expression

DESCRIPTION

CDR returns  the  remainder  of a list or list  expression  after  first
element of the list is removed.  If the list is NIL, NIL is returned.

EXAMPLES
	(cdr '(a b c))				; returns (B C)
	(cdr '((a b) c d))			; returns (C D)
	(cdr NIL)				; returns NIL
	(cdr 'a)				; error: bad argument type
	(cdr '(a))				; returns NIL

	(setq ben '(a b c))			; set up variable BEN
	(cdr ben)				; returns (B C)

cdar cddr
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(cdar <expr> )
(cddr <expr> )
	<expr>		-	a list or list expression

DESCRIPTION

The CDAR and CDDR functions go through the list expression and perform a
sequence of CAR/CDR operations.  The sequence of operations is performed
from right to left.  So CDAR does a CAR on the expression, followed by a
CDR.  If at any point the list is NIL, NIL is returned.  If at any point
a CAR  operation is performed on an atom (as opposed to a list) an error
is reported - "error:  BAD ARGUMENT".

EXAMPLES
	(setq mylist '( (a1 a2) 		; make a 2-level list
			(b1 b2) 
			(c1 c2) 
			(d1 d2) ) )
	(cdar mylist)				; returns (A2)
	(cddr mylist)				; returns ((C1 C2) (D1 D2))
	(caar mylist)				; returns A1
	(cadr mylist)				; returns (B1 B2)

	(caar 'a)				; error: bad argument
	(caar nil)				; returns NIL
	(cadr nil)				; returns NIL
	(cdar nil)				; returns NIL
	(cddr nil)				; returns NIL

cdaar cdadr cddar cdddr
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(cdaar <expr> )
(cdadr <expr> )
(cddar <expr> )
(cdddr <expr> )
	<expr>		-	a list or list expression

DESCRIPTION

The  CDAAR,  CDADR,  CDDAR  and  CDDDR  functions  go  through  the list
expression  and perform a sequence of CAR/CDR  operations.  The sequence
of operations  is performed  from right to left.  So CDDAR does a CAR on
the  expression,  followed by a CDR, followed by another CDR.  If at any
point the list is NIL, NIL is returned.  If at any point a CAR operation
is  performed  on an atom (as opposed to a list) an error is  reported -
"error:  BAD ARGUMENT".

EXAMPLES
	(setq mylist '( ( (a b) (c d) (e f) )	; make a 3-level list
        	        ( (g h) (i j) (k l) )
                	( (m n) (o p) (q r) )
	                ( (s t) (u v) (w x) )
			) )
	(cdaar mylist)				; returns (B)
	(cdadr mylist)				; returns ((I J) (K L))
	(cddar mylist)				; returns ((E F))
	(cdddr mylist)				; returns (((S T) (U V) (W X)))
	(caaar mylist)				; returns A
	(caadr mylist)				; returns (G H)
	(cadar mylist)				; returns (C D)
	(caddr mylist)				; returns ((M N) (O P) (Q R))

cdaaar cdaadr ... cdddar cddddr
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(cdaaar <expr> )
(cdaadr <expr> )
...
(cdddar <expr> )
(cddddr <expr> )
	<expr>		-	a list or list expression

DESCRIPTION

The CDAAAR,  CDAADR ....  CDDDAR,  CDDDDR  functions go through the list
expression  and perform a sequence of CAR/CDR  operations.  The sequence
of operations is performed  from right to left.  So CDDAAR does a CAR on
the  expression,  followed  by a CAR,  followed  by a CDR,  followed  by
another  CDR.  If at any point the list is NIL, NIL is  returned.  If at
anypoint a CAR  operation is performed on an atom (as opposed to a list)
an error is reported - "error:  BAD ARGUMENT".

EXAMPLES
	(setq mylist '( ( (a b) (c d) (e f) )	; make a 3-level list
        	        ( (g h) (i j) (k l) )
                	( (m n) (o p) (q r) )
	                ( (s t) (u v) (w x) )
			) )
	(cdadar mylist)				; returns (D)
	(cdaddr mylist)				; returns ((O P) (Q R))
	(caaadr mylist)				; returns G
	(cadadr mylist)				; returns (I J)
	(caadar mylist)				; returns C
	(cadddr mylist)				; returns ((S T) (U V) (W X))

cerror
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c  and  xldbug.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(cerror  <cont-msg> <err-msg>  [ <arg> ] )
	<cont-msg>	-	a string expression for the continue message
	<err-msg>	-	a string expression for the error message
	<arg>		-	an optional expression 

DESCRIPTION

The CERROR  function  allows the  generation of a continuable  error.  A
continuable error is one that can be corrected by some action within the
XLISP break loop.  The form of the message generated is:

	error: <err-msg> - <arg>
	if continued: <cont-msg>	

From within the  break-loop,  if a CONTINUE form is evaluated then a NIL
is  returned  from  CERROR.  From  within the break  loop,  forms can be
evaluated to correct the error.  If desired, the CLEAN-UP and  TOP-LEVEL
forms may be evaluated to abort out of the break loop.

EXAMPLES

	(cerror "fee" "fi" "fo")		; CERROR generates the message -
						; error: fi - "fo"
						; if continued: fee

	(cerror "I will do better" 		; CERROR generates the message -
		"There's a problem, Dave")	;
						; error: There's a problem, Dave
						; if continued: I will do better

						; example of system generated
						; correctable error -
	(symbol-value 'f)			; error: unbound variable - F
						; if continued: 
						;   try evaluating symbol again

COMMON LISP COMPATIBILITY:
Common  LISP and XLISP  have the same  basic form and style for  CERROR.
However, the <err-msg> and  <cont-msg>  string in Common LISP is sent to
FORMAT.  FORMAT is a output  function that takes in format  strings that
include  control  information.  Although,  XLISP  does  have the  FORMAT
function,  it does not print  the  CERROR  <err-msg>  with  FORMAT.  So,
Porting  from XLISP to Common  LISP will work fine.  When  porting  from
Common LISP to XLISP, you will need to check for this  embedded  control
information in the error messages.

NOTE:
In the XLISP system, the only correctable  system errors have to do with
the value of a symbol being  unbound.  In these cases, you can do a SETQ
or SET from within the break loop and then CONTINUE.

NOTE:
Remember  that  *BREAKENABLE*  needs to non-NIL for ERROR and CERROR and
system  errors  to be  caught  by  the  normal  system  break  loop.  If
*BREAKENABLE*  is NIL, ERROR and CERROR and system  errors can be caught
by an ERRSET form.  If there is no surrounding  ERRSET, no error message
is generated and the break loop is not entered.


char
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(char <string> <position> )
	<string>	-	a string expression
	<position>	-	an integer expression

DESCRIPTION

The CHAR  function  returns the ASCII  numeric value of the character at
the  specified  <position>  in the  <string>.  A <position>  of 0 is the
first character in the string.

EXAMPLES

	(char "12345" 0)			; returns #\1
	(char "12 45" 2)			; returns #\Space

	(string (char "1234" 3))		; returns "4"
	(char "1234" 9)				; error: index out of range


char/=
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(char/= <char1> <charN> ... )
	<char1>		-	a character expression
	<charN>		-	character expression(s) to compare

DESCRIPTION

The CHAR/=  (character-NOT-EQUAL)  function  takes one or more character
arguments.  It  checks  to  see  if  all  the  character  arguments  are
different values.  T is returned if the arguments are of different ASCII
value.  In the case of two arguments,  this has the effect of testing if
<char1>  is not  equal to  <char2>.  This test is case  sensitive  - the
character #\a is different (and of greater ASCII value) than #\A.

EXAMPLES

	(char/= #\a #\b)			; returns T
	(char/= #\a #\b #\c)			; returns T
	(char/= #\a #\a)			; returns NIL 
	(char/= #\a #\b #\b)			; returns NIL
	(char/= #\A #\a)			; returns T
	(char/= #\a #\A)			; returns T

NOTE:
Be sure that the CHAR/=  function  is  properly  typed in.  The '/' is a
forward  slash.  It is possible to  mistakenly  type a '\'  (backslash).
This is especially  easy because the  character  mechanism is '#\a'.  If
you do use the backslash, no error will be reported because backslash is
the single escape  character and the LISP reader will evaluate  'CHAR\='
as  'CHAR='.  No error  will be  reported,  but the sense of the test is
reversed.


char<
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(char< <char1> <charN> ... )
	<char1>		-	a character expression
	<charN>		-	character expression(s) to compare

DESCRIPTION

The CHAR<  (character-LESS-THAN)  function  takes one or more  character
arguments.  It  checks  to  see  if  all  the  character  arguments  are
monotonically  increasing.  T  is  returned  if  the  arguments  are  of
increasing  ASCII  value.  In the case of two  arguments,  this  has the
effect of testing  if <char1>  is less than  <char2>.  This test is case
sensitive - the character #\a is different  (and of greater ASCII value)
than #\A.

EXAMPLES

	(char< #\a #\b)				; returns T
	(char< #\b #\a)				; returns NIL
	(char< #\a #\b #\c)			; returns T
	(char< #\a #\a)				; returns NIL 
	(char< #\a #\b #\b)			; returns NIL
	(char< #\A #\a)				; returns T
	(char< #\a #\A)				; returns NIL


char<=
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(char<= <char1> <charN> ... )
	<char1>		-	a character expression
	<charN>		-	character expression(s) to compare

DESCRIPTION

The  CHAR<=  (character-LESS-THAN-OR-EQUAL)  function  takes one or more
character  arguments.  It checks to see if all the  character  arguments
are monotonically non-decreasing.  T is returned if the arguments are of
non-decreasing  ASCII value.  In the case of two arguments, this has the
effect of  testing  if  <char1> is less than or equal to  <char2>.  This
test is case  sensitive - the character #\a is different (and of greater
ASCII value) than #\A.

EXAMPLES

	(char<= #\a #\b)			; returns T
	(char<= #\b #\a)			; returns NIL
	(char<= #\a #\b #\c)			; returns T
	(char<= #\a #\a)			; returns T 
	(char<= #\a #\b #\b)			; returns T
	(char<= #\A #\a)			; returns T
	(char<= #\a #\A)			; returns NIL


char=
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(char= <char1> <charN> ... )
	<char1>		-	a character expression
	<charN>		-	character expression(s) to compare

DESCRIPTION

The CHAR=  (character-EQUALITY)  function  takes  one or more  character
arguments.  It  checks  to  see  if  all  the  character  arguments  are
equivalent.  T is returned if the arguments are of the same ASCII value.
In the case of two arguments,  this has the effect of testing if <char1>
is equal to <char2>.  This test is case sensitive - the character #\a is
different (and of greater ASCII value) than #\A.

EXAMPLES

	(char= #\a #\b)				; returns NIL
	(char= #\b #\a)				; returns NIL
	(char= #\a #\b #\c)			; returns NIL
	(char= #\a #\a)				; returns T 
	(char= #\a #\a #\a)			; returns T 
	(char= #\a #\a #\b)			; returns NIL
	(char= #\A #\a)				; returns NIL
	(char= #\a #\A)				; returns NIL


char>
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(char> <char1> <charN> ... )
	<char1>		-	a character expression
	<charN>		-	character expression(s) to compare

DESCRIPTION

The CHAR> (character-GREATER-THAN)  function takes one or more character
arguments.  It  checks  to  see  if  all  the  character  arguments  are
monotonically  decreasing.  T  is  returned  if  the  arguments  are  of
monotonically  decreasing  ASCII  value.  In the case of two  arguments,
this has the effect of testing if <char1> is greater than <char2>.  This
test is case  sensitive - the character #\a is different (and of greater
ASCII value) than #\A.

EXAMPLES

	(char> #\a #\b)				; returns NIL
	(char> #\b #\a)				; returns T
	(char> #\c #\b #\a)			; returns T
	(char> #\a #\a)				; returns NIL 
	(char> #\c #\a #\b)			; returns NIL
	(char> #\A #\a)				; returns NIL
	(char> #\a #\A)				; returns T


char>=
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(char>= <char1> <charN> ... )
	<char1>		-	a character expression
	<charN>		-	character expression(s) to compare

DESCRIPTION

The CHAR>= (character-GREATER-THAN-OR-EQUAL)  function takes one or more
character  arguments.  It checks to see if all the  character  arguments
are monotonically non-increasing.  T is returned if the arguments are of
monotonically non-increasing ASCII value.  In the case of two arguments,
this has the  effect of testing  if <char1> is greater  than or equal to
<char2>.  This test is case  sensitive - the  character #\a is different
(and of greater ASCII value) than #\A.

EXAMPLES

	(char>= #\a #\b)			; returns NIL
	(char>= #\b #\a)			; returns T
	(char>= #\c #\b #\a)			; returns T
	(char>= #\a #\a)			; returns T 
	(char>= #\c #\a #\b)			; returns NIL
	(char>= #\A #\a)			; returns NIL
	(char>= #\a #\A)			; returns T


characterp
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(characterp <expr> )
	<expr>		-	the expression to check

DESCRIPTION

The  CHARACTERP  predicate  checks if an  <expr>  is a  character.  T is
returned if <expr> is a character, NIL is returned otherwise.

EXAMPLES

	(characterp #\a)			; returns T - character
	(setq a #\b)				; 
	(characterp a)				; returns T - evaluates to char

	(characterp "a")			; returns NIL - string
	(characterp '(a b c))			; returns NIL - list
	(characterp 1)				; returns NIL - integer
	(characterp 1.2)			; returns NIL - float
	(characterp 'a)				; returns NIL - symbol
	(characterp #(0 1 2))			; returns NIL - array 
	(characterp NIL)			; returns NIL - NIL


char-code
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c 
Common LISP compatible: similar
versions: all machines

SYNTAX

(char-code <char> )
	<char>		-	a character expression

DESCRIPTION

The CHAR-CODE function returns the value of the <char> expression.

EXAMPLES

	(char-code #\0)				; returns 48
	(char-code #\A)				; returns 65
	(char-code #\a)				; returns 97
	(char-code #\[)				; returns 91
	(char-code #\newline)			; returns 10

	(char-code (code-char 127))		; returns 127
	(char-code (int-char 255))		; returns 255

COMMON LISP COMPATABILITY:
Common LISP supports the concept of a complex  character  that  includes
not only the ASCII code  value, but also fonts and bits.  The bits allow
for more  than 8 bits per  character  (16 bits is  especially  useful in
oriental  languages).  The fonts  allow for up to 128  different  fonts.
This is  interesting  and neat stuff,  however,  XLISP does not  support
fonts and bits.

NOTE:
Because  XLISP does not  support  fonts and bits (as  discussed  above),
CHAR-CODE and CHAR-INT are identical in use.


char-downcase
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c 
Common LISP compatible: yes
versions: all machines

SYNTAX

(char-downcase <char> )
	<char>		-	a character expression

DESCRIPTION

The CHAR-DOWNCASE function converts the <char> expression to lower case.
The lower case  equivalent  of <char> is returned.  If the <char> is not
alphabetic  ('a' thru 'z' or 'A' thru 'Z'), the  character  is  returned
unchanged.

EXAMPLES

	(char-downcase #\0)			; returns #\0
	(char-downcase #\A)			; returns #\a
	(char-downcase #\a)			; returns #\a
	(char-downcase #\[)			; returns #\[
	(char-downcase #\+)			; returns #\+


char-equal
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(char-equal <char1> <charN> ... )
	<char1>		-	a character expression
	<charN>		-	character expression(s) to compare

DESCRIPTION

The  CHAR-EQUAL  function  takes  one or more  character  arguments.  It
checks  to see if all  the  character  arguments  are  equivalent.  T is
returned if the  arguments  are of the same ASCII value.  In the case of
two  arguments,  this has the effect of testing if  <char1>  is equal to
<char2>.  This  test  is  case   insensitive  -  the  character  #\a  is
considered to be the same ASCII value as #\A.

EXAMPLES

	(char-equal #\a #\b)			; returns NIL
	(char-equal #\b #\a)			; returns NIL
	(char-equal #\a #\b #\c)		; returns NIL
	(char-equal #\a #\a)			; returns T 
	(char-equal #\a #\a #\a)		; returns T 
	(char-equal #\a #\a #\b)		; returns NIL
	(char-equal #\A #\a)			; returns T
	(char-equal #\a #\A)			; returns T

NOTE:
The CHAR-EQUAL function is listed in the documentation that
comes with XLISP as CHAR-EQUALP.


char-greaterp
________________________________________________________________________

type: predicate function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(char-greaterp <char1> <charN> ... )
	<char1>		-	a character expression
	<charN>		-	character expression(s) to compare

DESCRIPTION

The  CHAR-GREATERP  function takes one or more character  arguments.  It
checks  to  see  if  all  the  character   arguments  are  monotonically
decreasing.  T  is  returned  if  the  arguments  are  of  monotonically
decreasing  ASCII  value.  In the case of two  arguments,  this  has the
effect of testing if <char1> is greater than <char2>.  This test is case
insensitive - the character #\a is considered to be the same ASCII value
as #\A.

EXAMPLES

	(char-greaterp #\a #\b)			; returns NIL
	(char-greaterp #\b #\a)			; returns T
	(char-greaterp #\c #\b #\a)		; returns T
	(char-greaterp #\a #\a)			; returns NIL 
	(char-greaterp #\c #\a #\b)		; returns NIL
	(char-greaterp #\A #\a)			; returns NIL
	(char-greaterp #\a #\A)			; returns NIL


char-int
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c 
Common LISP compatible: yes
versions: all machines

SYNTAX

(char-int <char> )
	<char>		-	a character expression

DESCRIPTION

The CHAR-INT function returns the ASCII value of the <char> expression.

EXAMPLES

	(char-int #\0)				; returns 48
	(char-int #\A)				; returns 65
	(char-int #\a)				; returns 97
	(char-int #\[)				; returns 91
	(char-int #\newline)			; returns 10

	(char-int (code-char 127))		; returns 127
	(char-int (int-char 255))		; returns 255

NOTE:
CHAR-CODE  and  CHAR-INT  are  identical  in  use.  See   CHAR-CODE  for
additional information.


char-lessp
________________________________________________________________________

type: predicate function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(char-lessp <char1> <charN> ... )
	<char1>		-	a character expression
	<charN>		-	character expression(s) to compare

DESCRIPTION

The  CHAR-LESSP  function  takes  one or more  character  arguments.  It
checks  to  see  if  all  the  character   arguments  are  monotonically
increasing.  T is  returned if the  arguments  are of  increasing  ASCII
value.  In the case of two arguments,  this has the effect of testing if
<char1>  is less  than  <char2>.  This  test is case  insensitive  - the
character #\a is considered to be the same ASCII value as #\A.

EXAMPLES

	(char-lessp #\a #\b)			; returns T
	(char-lessp #\b #\a)			; returns NIL
	(char-lessp #\a #\b #\c)		; returns T
	(char-lessp #\a #\a)			; returns NIL 
	(char-lessp #\a #\b #\b)		; returns NIL
	(char-lessp #\A #\a)			; returns NIL
	(char-lessp #\a #\A)			; returns NIL


char-not-equal
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(char-not-equal <char1> <charN> ... )
	<char1>		-	a character expression
	<charN>		-	character expression(s) to compare

DESCRIPTION

The CHAR-NOT-EQUAL  function takes one or more character  arguments.  It
checks to see if all the character arguments are different values.  T is
returned if the arguments are of different  ASCII value.  In the case of
two arguments, this has the effect of testing if <char1> is not equal to
<char2>.  This  test  is  case   insensitive  -  the  character  #\a  is
considered to be the same ASCII value as #\A.

EXAMPLES

	(char-not-equal #\a #\b)		; returns T
	(char-not-equal #\a #\b #\c)		; returns T
	(char-not-equal #\a #\a)		; returns NIL 
	(char-not-equal #\a #\b #\b)		; returns NIL
	(char-not-equal #\A #\a)		; returns NIL
	(char-not-equal #\a #\A)		; returns NIL

NOTE:
The  CHAR-NOT-EQUAL  function is listed in the documentation  that comes
with XLISP as  CHAR-NOT-EQUALP.  It functions properly in the XLISP code
as CHAR-NOT-EQUAL.


char-not-greaterp
________________________________________________________________________

type: predicate function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(char-not-greaterp <char1> <charN> ... )
	<char1>		-	a character expression
	<charN>		-	character expression(s) to compare

DESCRIPTION

The  CHAR-NOT-GREATERP  function takes one or more character  arguments.
It  checks  to see if all  the  character  arguments  are  monotonically
non-decreasing.  T is returned if the  arguments  are of  non-decreasing
ASCII  value.  In the case of two  arguments,  this  has the  effect  of
testing if <char1> is less than or equal to  <char2>.  This test is case
insensitive - the character #\a is considered to be the same ASCII value
as #\A.

EXAMPLES

	(char-not-greaterp #\a #\b)		; returns T
	(char-not-greaterp #\b #\a)		; returns NIL
	(char-not-greaterp #\a #\b #\c)		; returns T
	(char-not-greaterp #\a #\a)		; returns T 
	(char-not-greaterp #\a #\b #\b)		; returns T
	(char-not-greaterp #\A #\a)		; returns T
	(char-not-greaterp #\a #\A)		; returns T


char-not-lessp
________________________________________________________________________

type: predicate function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(char-not-lessp <char1> <charN> ... )
	<char1>		-	a character expression
	<charN>		-	character expression(s) to compare

DESCRIPTION

The CHAR-NOT-LESSP  function takes one or more character  arguments.  It
checks  to  see  if  all  the  character   arguments  are  monotonically
non-increasing.  T is  returned if the  arguments  are of  monotonically
non-increasing  ASCII value.  In the case of two arguments, this has the
effect of testing if <char1> is greater  than or equal to <char2>.  This
test is case  insensitive - the  character #\a is  considered  to be the
same ASCII value as #\A.

EXAMPLES

	(char-not-lessp #\a #\b)		; returns NIL
	(char-not-lessp #\b #\a)		; returns T
	(char-not-lessp #\c #\b #\a)		; returns T
	(char-not-lessp #\a #\a)		; returns T 
	(char-not-lessp #\c #\a #\b)		; returns NIL
	(char-not-lessp #\A #\a)		; returns T
	(char-not-lessp #\a #\A)		; returns T


char-upcase
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c 
Common LISP compatible: yes
versions: all machines

SYNTAX

(char-upcase <char> )
	<char>		-	a character expression

DESCRIPTION

The CHAR-UPCASE  function converts the <char>  expression to upper case.
The upper case  equivalent  of <char> is returned.  If the <char> is not
alphabetic  ('a' thru 'z' or 'A' thru 'Z'), the  character  is  returned
unchanged.

EXAMPLES

	(char-upcase #\0)			; returns #\0
	(char-upcase #\A)			; returns #\A
	(char-upcase #\a)			; returns #\A
	(char-upcase #\[)			; returns #\[
	(char-upcase #\+)			; returns #\+


class
________________________________________________________________________

type: object
location: built-in
source file: xlobj.c
Common LISP compatible: no
supported on: all machines

SYNTAX

class 


DESCRIPTION

CLASS is the built-in  object class that is used to build other classes.
Classes are, essentially, the template for defining object instances.

EXAMPLES
	(setq myclass (send class :new '(var)))	; create MYCLASS with VAR
	(send myclass :answer :isnew '()	; set up initialization
		'((setq var nil) self))
	(send myclass :answer :set-it '(value)	; create :SET-IT message
		'((setq var value)))	
	(setq my-obj (send myclass :new))	; create MY-OBJ of MYCLASS
	(send my-obj :set-it 5)			; VAR is set to 5

CLASS DEFINITION:
The internal definition of the CLASS object instance looks like:

	Object is #<Object: #23fe2>, Class is #<Object: #23fe2>
	  MESSAGES = ((:ANSWER . #<Subr-: #23e48>) 
	  	      (:ISNEW . #<Subr-: #23e84>) 
		      (:NEW . #<Subr-: #23ea2>))
	  IVARS = (MESSAGES IVARS CVARS CVALS SUPERCLASS IVARCNT IVARTOTAL)
	  CVARS = NIL
	  CVALS = NIL
	  SUPERCLASS = #<Object: #23fd8>
	  IVARCNT = 7
	  IVARTOTAL = 7
	#<Object: #23fe2>

The class of CLASS is CLASS, itself.  The superclass of CLASS is OBJECT.
Remember that the location  information (like #23fe2) varies from system
to system, yours will probably look different.

BUILT-IN METHODS:
The built in methods in XLISP include:

		<message>	operation
		-------------------------------------------------------
		:ANSWER		Add a method to an object.
		:CLASS		Return the object's class.
		:ISNEW		Run initialization code on object.
		:NEW		Create a new object (instance or class).
		:SHOW		Show the internal state of the object.

MESSAGE STRUCTURE:
The normal XLISP  convention  for a <message> is to have a valid  symbol
preceeded  by a  colon  like  :ISNEW  or  :MY-MESSAGE.  However,  it  is
possible  to define a  <message>  that is a symbol  without a colon, but
this makes the code less readable.


:class
________________________________________________________________________

type: message selector
location: built-in
source file: xlobj.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(send <object> :class)
	<object>	-	an existing object

DESCRIPTION

The :CLASS message  selector will cause a method to run that will return
the object which is the class of the specified  <object>.  Note that the
returned  value is an object which will look like  "#<Object:  #18d8c>".
The  <object>  must exist or an error will be  generated  - "error:  bad
argument type".

EXAMPLES
	(send object :class)			; returns the CLASS object
	(send class :class)			; returns the CLASS object
	(setq new-cls (send class :new '(var)))	; create NEW-CLS
	(setq new-obj (send new-cls :new))	; create NEW-OBJ of NEW-CLS
	(send new-obj :class)			; returns the NEW-CLS object
	(send new-cls :class)			; returns the CLASS object

clean-up
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c  and  xldbug.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(clean-up)


DESCRIPTION

The CLEAN-UP function aborts one level of the break loop.  This is valid
for BREAKs,  ERRORs and CERRORs  (continuable  errors).  If CLEAN-UP  is
evaluated  while not in a break  loop, an error is  generated  - "error:
not in a break  loop".  This  error  does not  cause  XLISP to go into a
break loop.  CLEAN-UP never actually returns a value.

EXAMPLES

	(clean-up)				; [back to previous break level]

	(break "out")				; break: out
	(clean-up)				; to exit out of break loop 

KEYSTROKE EQUIVALENT:
In the IBM PC and MS-DOS  versions of XLISP, a CTRL-g key  sequence  has
the same  effect  as doing a  (CLEAN-UP).  On a  Macintosh,  this can be
accomplished by a pull-down menu or a COMMAND-g.


close
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(close  <file-ptr> )
	<file-ptr>	-	a file pointer expression 

DESCRIPTION

The CLOSE function closes the file specified through <file-ptr>.  If the
file close was  successful,  then a NIL is returned as the  result.  For
the file close to be successful,  the <file-ptr> has to point to a valid
file.  If the file close was not  successful,  an error is  generated  -
"error:  file not open").

EXAMPLES

	(close (open 'f :direction :output))	; returns NIL

	(setq myfile 				; create MYFILE
	   (open 'mine :direction :output))	;
	(print "hi" myfile)			; returns "hi"
	(close myfile)				; returns NIL
						; file contains <hi>   <NL>
	(setq myfile 				; open MYFILE for input
	   (open 'mine :direction :input))	;
	(read myfile)				; returns "hi"	
	(close myfile)				; returns NIL

COMMON LISP COMPATABILITY:
Common LISP has an XLISP  compatable  CLOSE  function.  Common LISP does
support an :ABORT keyword, which is not supported in XLISP.


code-char
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c 
Common LISP compatible: similar
versions: all machines

SYNTAX

(code-char <code> )
	<code>		-	a numeric expression

DESCRIPTION

The  CODE-CHAR  function  returns  a  character  which is the  result of
turning <code>  expression into a character.  If a <code> cannot be made
into a  character,  NIL is  returned.  The range that <code>  produces a
valid character is 0 through 127.

EXAMPLES

	(code-char 48)				; returns #\0
	(code-char 65)				; returns #\A
	(code-char 97)				; returns #\a
	(code-char 91)				; returns #\[
	(code-char 10)				; returns #\Newline
	(code-char 128)				; returns NIL
	(code-char 999)				; returns NIL

COMMON LISP COMPATABILITY:
Common LISP allows for some optional  arguments in CODE-CHAR  because it
supports the concept of a complex  character  that includes not only the
ASCII code value, but also fonts and bits.  The bits allow for more than
8  bits  per  character  (16  bits  is  especially  useful  in  oriental
languages).  The  fonts  allow for up to 128  different  fonts.  This is
interesting  and neat stuff,  however,  XLISP does not support fonts and
bits or the optional parameters associated with them.

NOTE:
Unlike the CHAR-CODE and CHAR-INT functions,  CODE-CHAR and INT-CHAR are
not identical in use.  CODE-CHAR  accepts  0..127 for its range and then
produces NIL  results.  INT-CHAR  accepts  0..255 for its range and then
produces errors.


comma
________________________________________________________________________

type: reader expansion
location: built-in
source file: xlcont.c  and  xlread.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(comma <expr> )
	<expr>		-	an expression which is evaluated within
				a BACKQUOTEd expression

DESCRIPTION

A BACKQUOTE special form returns an expression  unevaluated, except that
portions of the expression may be evaluated when they are preceeded by a
COMMA (,) or  COMMA-AT  (,@).  COMMA will  evaluate  the  portion of the
expression the comma  preceeds.  If the portion is an atom or a list, it
is placed as is within the expression.

EXAMPLES

	(setq box 'stuff-inside)		; BOX contains STUFF-INSIDE
	(print box)				; prints STUFF-INSIDE
	(quote (i have the box))		; returns (I HAVE THE BOX)
	(backquote (i have the box))		; returns (I HAVE THE BOX)
	(backquote (I have (comma box)))	; returns (I HAVE STUFF-INSIDE)
	(backquote (I have the ,@box))		; returns (I HAVE THE)

	(setq automobile '(a van))		; set up AUTOMOBILE 
	(backquote (I have automobile))		; returns (I HAVE AUTOMOBILE)
	(backquote (I have ,automobile))	; returns (I HAVE (A VAN))
	(backquote (I have ,@automobile))	; returns (I HAVE A VAN)
	`(I have ,@automobile)			; returns (I HAVE A VAN)

READ MACRO:
XLISP  supports  the normal  read  macro of a comma (,) as a  short-hand
method of writing the COMMA read-expansion.

NOTE: 
BACKQUOTE and COMMA and COMMA-AT are very useful in defining  macros via
DEFMACRO.


comma-at
________________________________________________________________________

type: reader expansion
location: built-in
source file: xlcont.c  and  xlread.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(comma-at <expr> )
	<expr>		-	an expression which is evaluated within
				a BACKQUOTEd expression

DESCRIPTION

A BACKQUOTE special form returns an expression  unevaluated, except that
portions of the expression may be evaluated when they are preceeded by a
COMMA (,) or COMMA-AT  (,@).  COMMA-AT will  evaluate the portion of the
expression that the comma-at  preceeds.  The portion needs to be a list.
The list is spliced into the  expression.  If the portion is not a list,
COMMA-AT will splice in nothing.

EXAMPLES

	(setq box 'stuff-inside)		; BOX contains STUFF-INSIDE
	(print box)				; prints STUFF-INSIDE
	(quote (i have the box))		; returns (I HAVE THE BOX)
	(backquote (i have the box))		; returns (I HAVE THE BOX)
	(backquote (I have (comma box)))	; returns (I HAVE STUFF-INSIDE)
	(backquote (I have the ,@box))		; returns (I HAVE THE)

	(setq automobile '(a van))		; set up AUTOMOBILE 
	(backquote (I have automobile))		; returns (I HAVE AUTOMOBILE)
	(backquote (I have (comma automobile)))	; returns (I HAVE (A VAN))
	(backquote (I have ,@automobile))	; returns (I HAVE A VAN)
	`(I have ,@automobile)			; returns (I HAVE A VAN)

READ MACRO:
XLISP  supports  the normal  read macro of a comma (,@) as a  short-hand
method of writing the COMMA-AT read-expansion.

NOTE: 
BACKQUOTE and COMMA and COMMA-AT are very useful in defining  macros via
DEFMACRO.


cond
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(cond  [ ( <pred1> <expr1> ) [ ( <pred2> <expr2> ) ... ] ] )
	<predN>		-	a predicate (NIL/non-NIL) expression
	<exprN>		-	an expression

DESCRIPTION

The COND  special  form  evaluates  a series of  predicate /  expression
pairs.  COND will evaluate each  predicate in sequential  order until it
finds  one  that  returns  a  non-NIL  value.  The  expression  that  is
associated with the non-NIL value is evaluated.  The resulting  value of
the  evaluated   expression  is  returned  by  COND.  If  there  are  no
predicates  that return a non-NIL  value, NIL is returned by COND.  Only
one  expression  is evaluated - the first one with a non-NIL  predicate.
Note that the predicate can be a symbol or expression.

EXAMPLES

	(cond 					; sample CONDitional
	  ((not T) (print "this won't print"))	;
	  ( NIL    (print "neither will this"))	;
	  ( T      (print "this will print"))	;
	  ( T      (print "won't get here")))	; prints "this will print"

	(defun print-what (parm)
	 (cond 					; start of COND
	  ((numberp parm) (print "numeric"))	;  check for number
	  ((consp parm)   (print "list"))	;  check for list
	  ((null parm) 	  (print "nil"))	;  check for NIL
	  (T 		  (print "something"))) ;  catch-all
	 NIL)					;  always return 
						;
	(print-what 'a)				; prints "something"
	(print-what 12)				; prints "numeric"
	(print-what NIL)			; prints "nil"
	(print-what '(a b))			; prints "list"


cons
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(cons <expr-car> <expr-cdr> )
	<arg>		-	description
	<expr-car>	-	an expression 
	<expr-cdr>	-	an expression 

DESCRIPTION

The CONS function takes two  expressions  and constructs a new list from
them.  If the  <expr-cdr>  is not a  list,  then  the  result  will be a
'dotted-pair'.

EXAMPLES

	(cons 'a 'b)				; returns (A . B)
	(cons 'a nil)				; returns (A)
	(cons 'a '(b))				; returns (A B)
	(cons '(a b) '(c d))			; returns ((A B) C D)
	(cons '(a b) 'c)			; returns ((A B) . C)

	(cons (- 4 3) '(2 3))			; returns (1 2 3)


consp
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(consp <expr> )
	<expr>		-	the expression to check

DESCRIPTION

The CONSP  predicate  checks if the  <expr> is a  non-empty  list.  T is
returned if <expr> is a list, NIL is  returned  otherwise.  Note that if
the <expr> is NIL, NIL is returned.

EXAMPLES

	(consp '(a b))				; returns T - list
	(consp '(a . b))			; returns T - dotted pair list

	(consp #'defvar)			; returns NIL - closure - macro
	(consp (lambda (x) (print x)))		; returns NIL - closure - lambda
	(consp NIL)				; returns NIL - NIL	
	(consp #(1 2 3))			; returns NIL - array
	(consp *standard-output*)		; returns NIL - stream
	(consp 1.2)				; returns NIL - float
	(consp #'quote)				; returns NIL - fsubr
	(consp 1)				; returns NIL - integer
	(consp object)				; returns NIL - object
	(consp "str")				; returns NIL - string
	(consp #'car)				; returns NIL - subr
	(consp 'a)				; returns NIL - symbol

NOTE:
When applied to CONSP, NIL - the empty list - returns a NIL.  NIL or '()
is used in many places as a list-class  or atom-class  expression.  Both
ATOM and LISTP, when applied to NIL, return T.  If you wish to check for
a list where an empty  list is still  considered  a valid  list, use the
LISTP predicate.


:constituent
________________________________________________________________________

type: keyword
location: built-in
source file: xlread.c
Common LISP compatible: no
supported on: all machines

SYNTAX

:constituent


DESCRIPTION

:CONSTITUENT  is an entry that is used in the  *READTABLE*.  *READTABLE*
is a system variable that contains  XLISP's data structures  relating to
the  processing of  characters  from the user (or files) and  read-macro
expansions.  The existance of the  :CONSTITUENT  keyword  means that the
specified  character  is to be used, as is, with no further  processing.
The  system  defines  that the  following  characters  are  :CONSTITUENT
characters:

	0123456789  !$%&*+-./  :<=>?@[]^_{}~
	ABCDEFGHIJKLMNOPQRSTUVWXYZ  abcdefghijklmnopqrstuvwxyz

EXAMPLES

	(defun look-at (table)			; define a function to 
	 (dotimes (ch 127)			;   look in a table
	  (prog ( (entry (aref table ch)) )	;   and print out any	  
	    (case entry 			;   entries with a function
	      (:CONSTITUENT 			;
	          (princ (int-char ch)))	;
	      (T	    NIL))))		;
	 (terpri))				;
	(look-at *readtable*)			;  prints  !$%&*+-./0123456789
						;	   :<=>?@ABCDEFGHIJKLM
						;	   NOPQRSTUVWXYZ[]^_ab
						;	   cdefghijklmnopqrstu
						;	   vwxyz{}~

CAUTION:
If you experiment  with  *READTABLE*, it is useful to save the old value
in a variable, so that you can restore the system state.


continue
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c  and  xldbug.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(continue)


DESCRIPTION

The CONTINUE function attempts to continue from the break loop.  This is
valid only for CERRORs  (continuable  errors).  If CONTINUE is evaluated
while not in a break  loop, an error is  generated  -  "error:  not in a
break  loop".  This error does not cause XLISP to go into a break  loop.
CONTINUE never actually returns a value.

EXAMPLES

	(continue)				; error: not in a break loop

	(break "out")				; break: out
	(continue)				; to continue from break loop 
						; BREAK returns NIL

KEYSTROKE EQUIVALENT:
In the IBM PC and MS-DOS  versions of XLISP, a CTRL-p key  sequence  has
the same  effect  as doing a  (CONTINUE).  On a  Macintosh,  this can be
accomplished by a pull-down menu or a COMMAND-p.


cos
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(cos <expr> )
	<expr>		-	floating point number/expression

DESCRIPTION

The cos  function  returns  the cosine of the  <expr>.  The <expr> is in
radians.

EXAMPLES

	(cos 0.0)				; returns 1
	(cos (/ 3.14159 2))			; returns 1.32679e-06 (almost 0)
	(cos .5)				; returns 0.877583
	(cos 0)					; error: bad integer operation
	(cos 1.)				; error: bad integer operation


debug
________________________________________________________________________

type: defined function (closure) 
location: extension
source file: init.lsp
Common LISP compatible: no
supported on: all machines

SYNTAX

(debug)


DESCRIPTION

The DEBUG  function  sets  *BREAKENABLE*  to T.  This has the  effect of
turning on the break  loop for  errors.  DEBUG  always  returns  T.  The
default is DEBUG enabled.

EXAMPLES

	(debug)					; returns T
	(+ 1 "a")				; error: bad argument type
						; enters break-loop
	(clean-up)				; from within the break-loop
	(nodebug)				; returns NIL
	(+ 1 "a")				; error: bad argument type
						; but doesn't enter break-loop

NOTE:
The  functions  DEBUG and NODEBUG are created in the INIT.LSP  file.  If
they do not exist in your  XLISP  system,  you might be having a problem
with  INIT.LSP.  Before you start XLISP, look in the  directory  you are
currently in, and check to see if there is an INIT.LSP.


*debug-io*
________________________________________________________________________

type: system variable 
location: built-in
source file: xlinit.c  xlio.c  xldbug.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

*debug-io*


DESCRIPTION

*DEBUG-IO* is a system variable that contains a file pointer that points
to the  stream  where  all  debug  input/output  goes to and  from.  The
default  file for  *DEBUG-IO*  is the  system  standard  error  device -
normally the keyboard and screen.

EXAMPLES
	*debug-io*				; returns #<File-Stream: #243de>

NOTE:
*TRACE-OUTPUT*,  *DEBUG-IO* and  *ERROR-OUTPUT*  are normally all set to
the same file stream - STDERR.


defconstant
________________________________________________________________________

type: defined macro (closure)
location: extension
source file: init.lsp
Common LISP compatible: similar
supported on: all machines

SYNTAX

(defconstant  <symbol>  <init-value> )
	<symbol>	-	an expression evaluating to a symbol
	<init-value>	-	an initial value expression 

DESCRIPTION

The  DEFCONSTANT  macro defines a user constant with the name  <symbol>.
The <symbol> is created with the initial value <init-value>  expression.
If  <symbol>  did  exist,  its  previous  value  will  be   overwritten.
DEFCONSTANT returns the <symbol> as its result.

EXAMPLES

	(boundp 'mvyar)				; returns NIL - doesn't exist
	(defconstant myvar 7)			; returns MYVAR
	(boundp 'myvar)				; returns T
	myvar					; returns 7

BUG:
In Common LISP, the  definition of  DEFCONSTANT  is such that it returns
the <symbol> as its result.  XLISP returns the value of <symbol>.

COMMON LISP COMPATABILITY:
In Common LISP, any change to the value of the  DEFCONSTANT  <symbol> is
supposed to generate an error.  XLISP treats it like any user symbol and
allows it to change.

COMMON LISP COMPATABILITY:
Common LISP supports an additional  optional  parameter.  This parameter
is a documentation string.  XLISP does not support this.

NOTE:
The functions  DEFVAR,  DEFPARAMETER  and DEFCONSTANT are created in the
INIT.LSP  file.  If it does not exist in your XLISP system, you might be
having a problem  with  INIT.LSP.  Before you start  XLISP,  look in the
directory  you  are  currently  in,  and  check  to see if  there  is an
INIT.LSP.


defmacro
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(defmacro <symbol> <arg-list> <body> )
	<symbol>	-	The name of the macro being defined
	<arg-list>	-	A list of the formal arguments to the macro
				of the form:	( [ <arg1> ... ]
						  [ &optional <oarg1> ... ]
					  	  [ &rest <rarg> ]
						  [ &key ... ]
					  	  [ &aux <aux1> ... ] )
	<body>		-	A series of LISP forms (expressions) 

DESCRIPTION

DEFMACRO defines a macro expansion.  When the <symbol> name of the macro
expansion is encountered (similar to a function  invocation), the <body>
of code that was defined in the DEFMACRO is expanded  and  replaces  the
macro invocation.

All of the <argN>  formal  arguments  that are  defined are  required to
appear  in the  invocation  of the  macro  expansion.  If there  are any
&OPTIONAL  arguments defined, they will be filled in order.  If there is
a &REST  argument  defined, and all the required  formal  arguments  and
&OPTIONAL  arguments are filled, any and all further  parameters will be
passed into the function  via the <rarg>  argument.  Note that there can
be only  one  <rarg>  argument  for  &REST.  If there  are  insufficient
parameters  for any of the  &OPTIONAL  or  &REST  arguments,  they  will
contain  NIL.  The &AUX  variables  are a  mechanism  for you to  define
variables  local to the DEFMACRO  execution.  At the end of the function
execution, these local symbols and their values are are removed.

EXAMPLES

	(defmacro plus (num1 num2)		; define PLUS macro
	  `(+ ,num1 ,num2))			;   which is a 2 number add
	(plus 1 2)				; returns 3
	(setq x 10)				; set x to 10
	(setq y 20)				; set y to 20
	(plus x y)				; returns 30

	(defmacro betterplus (num &rest nlist)	; define a BETTERPLUS macro
	  `(+ ,num ,@nlist))			;   which can take many numbers
	(betterplus 1)				; returns 1
	(betterplus 1 2 3)			; returns 6
	(betterplus 1 2 3 4 5)			; returns 15


	(defmacro atest (x &optional y &rest z) ; define ATEST macro
	  (princ " x: ") (princ x)		;   \
	  (princ " y: ") (princ y)		;    print out the parameters
	  (princ " z: ") (princ z) (terpri) 	;   /      (un-evaluated)
	  `(print (+ ,x ,y ,@z)) )		;   add them together (eval'ed)
						;
	(atest 1) 				; prints - x: 1 y: NIL z: NIL
						;   error: bad argument type 
						; because (+ 1 NIL) isn't valid
	(atest 1 2) 				; prints - x: 1 y: 2 z: NIL
						;   returns 3
	(atest 1 2 3) 				; prints - x: 1 y: 2 z: (3)
						;   returns 6
	(atest 1 2 3 4 5) 			; prints - x: 1 y: 2 z: (3 4 5)
						;   returns 15
						;
	(setq a 99)				; set A to 99
	(setq b 101)				; set B to 101
	(atest a b) 				; prints - x: A y: B z: NIL
						;   returns 200
	(atest a b 9 10 11) 			; prints - x: A y: B z: (9 10 11)
						;   returns 230

COMMON LISP COMPATABILITY:
Common LISP supports an optional  documentation string as the first form
in the <body> of a DEFMACRO or DEFUN.  XLISP will accept this  string as
a valid form, but it will not do anything special with it.


defparameter
________________________________________________________________________

type: defined macro (closure)
location: extension
source file: init.lsp
Common LISP compatible: similar
supported on: all machines

SYNTAX

(defparameter  <symbol>  <init-value> )
	<symbol>	-	an expression evaluating to a symbol
	<init-value>	-	an initial value expression 

DESCRIPTION

The DEFPARAMETER macro defines a user parameter (variable) with the name
<symbol>.  A user parameter is supposed to be a variable that should not
change  but is allowed  to change.  The  <symbol>  is  created  with the
initial  value  <init-value>  expression.  If  <symbol>  did  exist, its
previous value will be  overwritten.  DEFPARAMETER  returns the <symbol>
as its result.

EXAMPLES

	(boundp 'mvyar)				; returns NIL - doesn't exist
	(defparameter myvar 7)			; returns MYVAR
	(boundp 'myvar)				; returns T
	myvar					; returns 7

BUG:
In Common LISP, the definition of  DEFPARAMETER  is such that it returns
the <symbol> as its result.  XLISP returns the value of <symbol>.

COMMON LISP COMPATABILITY:
Common LISP supports an additional  optional  parameter.  This parameter
is a documentation string.  XLISP does not support this.

NOTE:
The functions  DEFVAR,  DEFPARAMETER  and DEFCONSTANT are created in the
INIT.LSP  file.  If it does not exist in your XLISP system, you might be
having a problem  with  INIT.LSP.  Before you start  XLISP,  look in the
directory  you  are  currently  in,  and  check  to see if  there  is an
INIT.LSP.


defun
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(defun <symbol> <arg-list> <body> )
	<symbol>	-	The name of the function being defined
	<arg-list>	-	A list of the formal arguments to the function
				of the form:	( [ <arg1> ... ]
						  [ &optional <oarg1> ... ]
					  	  [ &rest <rarg> ]
						  [ &key ... ]
					  	  [ &aux <aux1> ... ] )
	<body>		-	A series of LISP forms (expressions) that
				are executed in order.  

DESCRIPTION

DEFUN defines a new function or  re-defines an exisiting  function.  The
last form in <body> that is evaluated is the value that is returned when
the function is executed.

All of the <argN>  formal  arguments  that are  defined are  required to
appear in a call to the  defined  function.  If there are any  &OPTIONAL
arguments  defined,  they will be filled  in order.  If there is a &REST
argument  defined, and all the required  formal  arguments and &OPTIONAL
arguments are filled, any and all further parameters will be passed into
the function  via the <rarg>  argument.  Note that there can be only one
<rarg> argument for &REST.  If there are insufficient parameters for any
of the  &OPTIONAL or &REST  arguments,  they will contain NIL.  The &AUX
variables  are a  mechanism  for you to  define  variables  local to the
function  definition.  At the end of the function execution, these local
symbols and their values are are removed.

EXAMPLES

	(defun my-add 				; define function MY-ADD 
	  (num1 num2)				;   with 2 formal parameters
	  (+ num1 num2))			;   that adds the two paramters
	(my-add 1 2)				; returns 3

	(defun foo 				; define function FOO
	  (a b &optional c d &rest e)		;   with some of each argument
	  (print a) (print b) 			;
	  (print c) (print d) 			;   print out each
	  (print e))				;
	(foo)					; error: too few arguments 
	(foo 1)					; error: too few arguments 
	(foo 1 2)				; prints 1 2 NIL NIL NIL
	(foo 1 2 3)				; prints 1 2 3 NIL NIL
	(foo 1 2 3 4)				; prints 1 2 3 4 NIL
	(foo 1 2 3 4 5)				; prints 1 2 3 4 (5)
	(foo 1 2 3 4 5 6 7 8 9)			; prints 1 2 3 4 (5 6 7 8 9)

	(defun my-add 				; define function MY-ADD
	  (num1 &rest num-list &aux sum)	;   with 1 arg, rest, 1 aux var
	  (setq sum num1)			;   clear SUM
	  (dotimes (i (length num-list) )	;   loop through rest list
	     (setq sum (+ sum (car num-list)))  ;      add the number to sum
	     (setq num-list (cdr num-list)))	;      and remove num from list
	  sum)					;   return sum when finished
	(my-add 1 2 3 4)			; returns 10
	(my-add 5 5 5 5 5)			; returns 25


COMMON LISP COMPATABILITY:
Common LISP supports an optional  documentation string as the first form
in the <body> of a DEFMACRO or DEFUN.  XLISP will accept this  string as
a valid form, but it will not do anything special with it.


defvar
________________________________________________________________________

type: defined macro (closure)
location: extension
source file: init.lsp
Common LISP compatible: similar
supported on: all machines

SYNTAX

(defvar  <symbol>  [ <init-value> ] )
	<symbol>	-	an expression evaluating to a symbol
	<init-value>	-	an optional initial value expression 

DESCRIPTION

The DEFVAR macro  defines a user  variable  with the name  <symbol>.  If
<symbol> did not already exist, the <symbol> is created with the initial
value NIL.  If the optional <init-value>  expression is present, the new
<symbol>  will be set to the  <init-value>.  If <symbol>  did exist, its
previous value will be left  untouched.  DEFVAR  returns the <symbol> as
its result.

EXAMPLES

	(boundp 'mvyar)				; returns NIL - doesn't exist
	(defvar myvar)				; returns MYVAR
	(boundp 'myvar)				; returns T
	(setq myvar 7)				; returns 7
	(defvar myvar)				; returns MYVAR
	myvar					; returns 7 - was not initialized
	(defvar myvar 99)			; returns MYVAR
	myvar					; returns 7 - was not initialized

BUG:
In Common  LISP, the  definition  of DEFVAR is such that it returns  the
<symbol> as its result.  XLISP returns the value of <symbol>.

COMMON LISP COMPATABILITY:
Common LISP supports an additional  optional  parameter.  This parameter
is a documentation string.  XLISP does not support this.

NOTE:
The functions  DEFVAR,  DEFPARAMETER  and DEFCONSTANT are created in the
INIT.LSP  file.  If it does not exist in your XLISP system, you might be
having a problem  with  INIT.LSP.  Before you start  XLISP,  look in the
directory  you  are  currently  in,  and  check  to see if  there  is an
INIT.LSP.


delete
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(delete <expr> <list>  [ { :test | :test-not } <test> ] )
	<expr>		-	the expression to delete from <list>
	<list>		-	the list to DESTRUCTIVELY modify
	<test>		-	optional test function (default is EQL)

DESCRIPTION

DELETE  destructively  modifies  the <list> by removing the <expr>.  The
destructive  aspect of this operation means that the actual symbol value
is  used  in the  list-modifying  operations  - not a  copy.  If  <expr>
appears  multiple times in the <list>, all  occurances  will be removed.
<list> must evaluate to a valid list.  An atom for <list> will result in
an error.  Having NIL for <list>  will return a NIL as the  result.  You
may specify your own test with the :TEST and :TEST-NOT keywords.

EXAMPLES

	(delete 'b NIL)				; returns NIL
	(delete 'b '(a b b c b))		; returns (A C)

	(setq a '(1 2 3)) (setq b a)		; set up A and B
	(delete '2 a)				; returns (1 3)
	(print a)				; prints (1 3)    A IS MODIFIED!
	(print b)				; prints (1 3)    B IS MODIFIED!

	(delete '(b) '((a)(b)(c)))		; returns ((A) (B) (C))
						;   EQL doesn't work on lists
	(delete '(b) '((a)(b)(c)) :test 'equal)	; returns ((A) (C))

NOTE:
The  DELETE  function  can work  with a list or  string  as the  <expr>.
However, the default EQL test does not work with lists or strings,  only
symbols  and  numbers.  To make  this  work,  you need to use the  :TEST
keyword along with EQUAL for <test>.

COMMON LISP COMPATABILITY:
XLISP does not support  the  :FROM-END,  :START,  :END,  :COUNT and :KEY
keywords which Common LISP does.


delete-if
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(delete-if <test> <list> )
	<test>		-	the test function to be performed
	<list>		-	the list to delete from 

DESCRIPTION

DELETE-IF  destructively modifies the <list> by removing the elements of
the  <list>  that  pass  the  <test>.  The  destructive  aspect  of this
operation   means  that  the  actual   symbol   value  is  used  in  the
list-modifying operations - not a copy.  <list> must evaluate to a valid
list.  An atom for  <list>  will  result  in an  error.  Having  NIL for
<list> will return a NIL as the result.

EXAMPLES

	(setq mylist '(1 2 3 4 5 6 7 8))	; set up a list
	(delete-if 'oddp mylist)		; returns (2 4 6 8)
	(print mylist)				; prints  (2 4 6 8)
						;   note that MYLIST is affected

	(setq mylist '(a nil b nil c))		; set up a list
	(delete-if 'null mylist)		; returns (A B C)

BUG:
DELETE-IF will return the proper value, but it does not always  properly
modify the  symbol  containing  the value.  This seems to be true if the
first element of the <list> passes the test (and should be deleted).

COMMON LISP COMPATABILITY:
XLISP does not support  the  :FROM-END,  :START,  :END,  :COUNT and :KEY
keywords which Common LISP does.


delete-if-not
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(delete-if-not <test> <list> )
	<test>		-	the test function to be performed
	<list>		-	the list to delete from 

DESCRIPTION

DELETE-IF-NOT destructively modifies the <list> by removing the elements
of the  <list>  that fail the  <test>.  The  destructive  aspect of this
operation   means  that  the  actual   symbol   value  is  used  in  the
list-modifying operations - not a copy.  <list> must evaluate to a valid
list.  An atom for  <list>  will  result  in an  error.  Having  NIL for
<list> will return a NIL as the result.

EXAMPLES

	(setq mylist '(1 2 3 4 5 6 7 8))	; set up a list
	(delete-if-not 'oddp mylist)		; returns (1 3 5 7)
	(print mylist)				; prints  (1 3 5 7)
						;   note that MYLIST is affected

	(setq mylist '(a nil b nil c))		; set up a list
	(delete-if-not 'null mylist)		; returns (NIL NIL)

BUG:
DELETE-IF-NOT  will  return  the proper  value,  but it does not  always
properly modify the symbol  containing the value.  This seems to be true
if the first  element  of the  <list>  fails  the test  (and  should  be
deleted).

COMMON LISP COMPATABILITY:
XLISP does not support  the  :FROM-END,  :START,  :END,  :COUNT and :KEY
keywords which Common LISP does.


digit-char
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c 
Common LISP compatible: similar
versions: all machines

SYNTAX

(digit-char <int> )
	<int>		-	an integer expression

DESCRIPTION

The DIGIT-CHAR  function takes an integer  expression <int> and converts
it into a decimal  digit  character.  So, an integer value of 0 produces
the character #\0.  An integer value of 1 produces the character #\1 and
so on.  If a valid character can be produce it is returned,  otherwise a
NIL is returned.

EXAMPLES

	(digit-char 0)				; returns #\0
	(digit-char 9)				; returns #\9
	(digit-char 10)				; returns NIL

COMMON LISP COMPATABILITY:
Common  LISP  supports  the use of an  optional  radix  parameter.  This
option  specifies  numeric base.  This allows the DIGIT-CHAR to function
properly for hexadecimal  digits (for example).  Common LISP supports up
to base 36 radix systems.  XLISP does not support this radix  parameter.
Common LISP also supports a font parameter which XLISP does not.


digit-char-p
________________________________________________________________________

type: predicate function (subr) 
location: built-in
source file: xlstr.c 
Common LISP compatible: similar
versions: all machines

SYNTAX

(digit-char-p <char> )
	<char>		-	a character expression

DESCRIPTION

The DIGIT-CHAR-P  predicate checks if the <char> expression is a numeric
digit.  If <char> is numeric  digit a T is returned,  otherwise a NIL is
returned.  Decimal  digits are '0' (ASCII  decimal value 48) through '9'
(ASCII decimal value 57).

EXAMPLES

	(digit-char-p #\0)			; returns T
	(digit-char-p #\9)			; returns T
	(digit-char-p #\A)			; returns NIL
	(digit-char-p #\a)			; returns NIL
	(digit-char-p #\.)			; returns NIL
	(digit-char-p #\-)			; returns NIL
	(digit-char-p #\+)			; returns NIL

NOTE:
Other non-digit  characters used in numbers are NOT included:  plus (+),
minus (-), exponent (e or E) and decimal point (.).

COMMON LISP COMPATABILITY:
Common  LISP  supports  the use of an  optional  radix  parameter.  This
option specifies numeric base.  This allows the DIGIT-CHAR-P to function
properly for hexadecimal  digits (for example).  Common LISP supports up
to base 36 radix systems.  XLISP does not support this radix  parameter.


do
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(do  ( [ <binding> ... ]  ) ( <test-expr> [ <result> ] ) [ <expr> ... ]  )
	<binding>	-	a variable binding which is can take one of 
				the following forms:
					<symbol>   
					( <symbol> <init-expr> [<step-expr>] )
	<symbol>	-	a symbol
	<init-expr>	-	an initialization expression for <symbol>
	<step-expr>	-	an expression that <symbol> symbol is updated
				at the end of each loop
	<test-expr>	-	an expression to test for loop termination 
	<result>	-	an optional expression for the returned result
	<expr>		-	expressions comprising the body of the loop
				which may contain RETURNs, GOs or tags for GO  

DESCRIPTION

The DO  special  form is  basically  a 'while'  looping  construct  that
contains  symbols (with  optional  initializations  and updates), a loop
test (with an optional  return value) and a block of code  (expressions)
to evaluate.  The DO form evaluates its  initializations  and updates in
no  specified  order (as  opposed  to DO*  which  does it in  sequential
order).  The sequence of these events is:

		<init-expr> execution
		while <test-expr> do
			loop code execution
			<step-expr> execution
		end-while
		return <result>

The first form after the DO is the 'binding' form.  It contains a series
of <symbol>'s or  <binding>'s.  The <binding> is a <symbol>  followed by
an initialization  expression  <init-expr> and an optional  <step-expr>.
If there is no  <init-expr>,  the <symbol> will be  initialized  to NIL.
There is no  specification  as to the order of execution of the bindings
or the step expressions - except that they happen all together.

The DO form will go through and create and initialize the symbols.  This
is followed by evaluating  the  <test-expr>.  If  <test-expr>  returns a
non-NIL  value, the loop will  terminate.  If <test-expr>  returns a NIL
value  then  the  DO  will  sequentially  execute  the  <expr>'s.  After
execution  of  the  loop   <expr>'s,  the  <symbol>'s  are  set  to  the
<step-expr>'s  (if the  <step-expr>'s  exist).  Then, the <test-expr> is
re-evaluated,  and so on....  The value of the  <result>  expression  is
evaluated and  returned.  If no <result> is specified,  NIL is returned.
When the DO is finished execution, the <symbol>'s that were defined will
no longer exist or retain their values.

EXAMPLES

	(do (i) 				; DO loop with var I
	  ((eql i 0) "done") 			;   test and result
	  (print i) (setq i 0) (print i))	;   prints 	NIL     0
						;   returns "done"
						
	(do (i) 				; DO loop with var I
	  ((eql i 0)) 				;   test but no result
	  (print i) (setq i 0) (print i))	;   prints 	NIL     0
						;   returns NIL

	(do 					; DO loop
	   ((i 0 (setq i (1+ i)))		;   var I=0  increment by 1
	    (j 10 (setq j (1- j))) 	)	;   var J=10 decrement by 1
	   ((eql i j)  "met in the middle" )	;   test and result
	   (princ i) (princ " ") 		;   prints  0 10
	   (princ j) (terpri))			;	    1 9
						;	    2 8
						;	    3 7
						;	    4 6
						;   returns "met in the middle"


do*
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(do*  ( [ <binding> ... ]  ) ( <test-expr> [ <result> ] ) [ <expr> ... ]  )
	<binding>	-	a variable binding which is can take one of 
				the following forms:
					<symbol>    
					( <symbol> <init-expr> [<step-expr>] )
	<symbol>	-	a symbol
	<init-expr>	-	an initialization expression for <symbol>
	<step-expr>	-	an expression that <symbol> symbol is updated
				at the end of each loop
	<test-expr>	-	an expression to test for loop termination 
	<result>	-	an optional expression for the returned result
	<expr>		-	expressions comprising the body of the loop
				which may contain RETURNs, GOs or tags for GO  

DESCRIPTION

The DO* special  form is  basically  a 'while'  looping  construct  that
contains  symbols (with  optional  initializations  and updates), a loop
test (with an optional  return value) and a block of code  (expressions)
to evaluate.  The DO* form evaluates its  initializations and updates in
sequential  order (as  opposed to DO which  doesn't).  The  sequence  of
these events is:

		<init-expr> execution
		while <test-expr> do
			loop code execution
			<step-expr> execution
		end-while
		return <result>

The first  form  after the DO* is the  'binding'  form.  It  contains  a
series  of  <symbol>'s  or  <binding>'s.  The  <binding>  is a  <symbol>
followed by an  initialization  expression  <init-expr>  and an optional
<step-expr>.  If  there  is  no   <init-expr>,   the  <symbol>  will  be
initialized  to  NIL.  There  is no  specification  as to the  order  of
execution  of the  bindings or the step  expressions  - except that they
happen all together.

The DO* form will go through  and create  and  initialize  the  symbols.
This is followed by evaluating the <test-expr>.  If <test-expr>  returns
a non-NIL value, the loop will terminate.  If <test-expr>  returns a NIL
value  then  the DO*  will  sequentially  execute  the  <expr>'s.  After
execution  of  the  loop   <expr>'s,  the  <symbol>'s  are  set  to  the
<step-expr>'s  (if the  <step-expr>'s  exist).  Then, the <test-expr> is
re-evaluated,  and so on....  The value of the  <result>  expression  is
evaluated and  returned.  If no <result> is specified,  NIL is returned.
When the DO* is finished  execution,  the  <symbol>'s  that were defined
will no longer exist or retain their values.

EXAMPLES

	(do  					; DO example - won't work
	  ((i 0)				;   var I=0
	     (j i) )				;   var J=I (won't work)
	  ( (eql i j) "done")			;   test and result
	  (print "looping"))			; error: unbound variable - I
						;
	(do*  					; DO* example - will work
	  ((i 0)				;   var I=0
	     (j i) )				;   var J=I (proper exec. order)
	  ( (eql i j) "done")			;   test and result
	  (print "looping"))			;   returns "done"
	
	(do* (i) 				; DO* loop with var I
	  ((eql i 0) "done") 			;   test and result
	  (print i) (setq i 0) (print i))	;   prints 	NIL     0
						;   returns "done"
						
	(do* (i) 				; DO* loop with var I
	  ((eql i 0)) 				;   test but no result
	  (print i) (setq i 0) (print i))	;   prints 	NIL     0
						;   returns NIL

	(do* 					; DO* loop
	   ((i 0 (setq i (1+ i)))		;   var I=0  increment by 1
	    (j 10 (setq j (1- j))) 	)	;   var J=10 decrement by 1
	   ((eql i j)  "met in the middle" )	;   test and result
	   (princ i) (princ " ") 		;   prints  0 10
	   (princ j) (terpri))			;	    1 9
						;	    2 8
						;	    3 7
						;	    4 6
						;   returns "met in the middle"


dolist
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(dolist  ( <symbol> <list-expr> [ <result> ] ) [ <expr> ... ]  )
	<symbol>	-	a symbol
	<list-expr>	-	a list expression 
	<result>	-	an optional expression for the returned result
	<expr>		-	expressions comprising the body of the loop
				which may contain RETURNs, GOs or tags for GO  

DESCRIPTION

The DOLIST  special  form is  basically a  list-oriented  'for'  looping
construct  that contains a loop  <symbol>, a <list-expr>  to draw values
from, an  optional  return  value and a block of code  (expressions)  to
evaluate.  The sequence of execution is:

		<symbol>  := CAR of <list-expr>
		temp-list := CDR of <list-expr>
		while  temp-list is not empty
			loop code execution
			<symbol>  := CAR of temp-list
			temp-list := CDR of temp-list
		end-while
		return <result>

The main loop <symbol> will take on successive values from  <list-expr>.
The DOLIST form will go through and create and  initialize the <symbol>.
After  execution of the loop  <expr>'s,  the <symbol> is set to the next
value in the <list-expr>.  This continues until the <list-expr> has been
exhausted.  The  value  of the  <result>  expression  is  evaluated  and
returned.  If no  <result>  is  specified,  NIL is  returned.  When  the
DOLIST is finished  execution,  the  <symbol>  that was defined  will no
longer exist or retain its value.  If the  <list-expr> is an empty list,
then no loop execution takes place and the <result> is returned.

EXAMPLES

	(dolist (i () "done")			; DOLIST with I loop variable
		(print "here"))			;   an empty list 
						;   and a return value
	        				;   returns "done"	

	(dolist (x '(a b c) "fini") 		; DOLIST with X loop variable
		(princ x))			;   a list with (A B C)
						;   and a return value
	        				;   prints  ABC   returns "fini"

	(dolist (y '(1 2 3)) 			; DOLIST with Y loop variable
		(princ (* y y)))		;   a list with (1 2 3)
						;   and no return value
						;   prints  149   returns NIL
						;   returns "met in the middle"


dotimes
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(dotimes  ( <symbol> <end-expr> [ <result> ] ) [ <expr> ... ]  )
	<symbol>	-	a symbol
	<end-expr>	-	an integer expression 
	<result>	-	an optional expression for the returned result
	<expr>		-	expressions comprising the body of the loop
				which may contain RETURNs, GOs or tags for GO  

DESCRIPTION

The DOTIMES  special form is basically a 'for'  looping  construct  that
contains a loop  <symbol>, an <end-expr>  to specify the final value for
<symbol>, an optional return value and a block of code  (expressions) to
evaluate.  The sequence of execution is:

		<symbol>  := 0
		while  <symbol> value is not equal to <end-expr> value
			loop code execution
			<symbol>  := <symbol> + 1
		end-while
		return <result>

The main loop  <symbol>  will take on  successive  values  from  zero to
(<end-expr>  - 1).  The  DOTIMES  form will go through  and  create  and
initialize the <symbol> to zero.  After  execution of the loop <expr>'s,
the <symbol>  value is  incremented.  This continues  until the <symbol>
value is equal to  <end-expr>.  The value of the <result>  expression is
evaluated and  returned.  If no <result> is specified,  NIL is returned.
When the DOTIMES is finished  execution,  the <symbol>  that was defined
will no longer exist or retain its value.  If the  <end-expr> is zero or
less, then there will be no execution of the loop body's code.

EXAMPLES

	(dotimes (i 4 "done") (princ i))	; prints  0123   returns "done"
	(dotimes (i 4)        (princ i))	; prints  0123   returns NIL
	(dotimes (i 1)        (princ i))	; prints  0      returns NIL
	(dotimes (i 0)        (princ i))	; returns NIL
	(dotimes (i -9)       (princ i))	; returns NIL


dribble
________________________________________________________________________

type: function (subr)  
location: built-in
source file: xlisp.c  xlsys.c  msstuff.c 
Common LISP compatible: yes
supported on: all machines

SYNTAX

(transcript [ <file-str> ] )
	<file-str>	-	a string expression for a file name

DESCRIPTION

The DRIBBLE function, when called with a <file-str>  argument, opens the
specified  file and  records a  transcript  of the XLISP  session.  When
DRIBBLE is called with no  <file-str>  argument,  it closes the  current
transcript  file  (if  any).  DRIBBLE  will  return  T if the  specified
<file-str>  was  successfully  opened.  It  will  return  a NIL  if  the
<file-str>  was not opened  successfully  or if DRIBBLE was evaluated to
close a transcript.

EXAMPLES

	(dribble "my-trans-file")		; open file "my-trans-file"
						; for a session transcript
	(+ 2 2)					
	(dribble)				; close the transcript

NOTE:
It is also possible to start a transcript when invoking XLISP.  To start
xlisp with a transcript file of 'myfile' type in "xlisp -tmyfile".

NOTE:
The DRIBBLE  function  works in XLISP 2.0 for MS-DOS  systems.  However,
depending  on the  sources  you use - or where  you got  XLISP  2.0, the
generic  (non-DOS)  systems  might  not have the  appropriate  code  for
DRIBBLE to work properly.


endp
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(endp <list> )
	<list>		-	the list to check

DESCRIPTION

The ENDP  predicate  checks  to see if  <list>  is an empty  list.  T is
returned  if the list is empty,  NIL is  returned  if the  <list> is not
empty.  The <list> has to be a valid  list.  An error is returned  if it
is not a list.

EXAMPLES

	(endp '())				; returns T - empty list
	(endp ())				; returns T - still empty
	(endp '(a b c))				; returns NIL

	(setq a NIL)				; set up a variable
	(endp a)				; returns T - value = empty list

	(endp "a")				; error: bad argument type - "a"
	(endp 'a)				; error: bad argument type - A

NOTE:
The ENDP predicate is different from the NULL and NOT predicates in that
it requires a valid list.


eq
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xllist.c and xlsubr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(eq <expr1> <expr2> )
	<exprN>		-	an expression to compare

DESCRIPTION

The EQ predicate  checks to see if <expr1> and <expr2> are identical.  T
is returned if they are exactly the same internal value, NIL is returned
otherwise.

EXAMPLES

	(eq 'a 'a)				; returns T
	(eq 1 1)				; returns T
	(eq 1 1.0)				; returns NIL
	(eq 1.0 1.0)				; returns NIL
	(eq "a" "a")				; returns NIL
	(eq '(a b) '(a b))			; returns NIL
	(eq 'a 34)				; returns NIL

	(setq a '(a b))				; set value of A to (A B)
	(setq b a)				; set B to point to A's value
	(setq c '(a b))				; set value of C to dif. (A B)
	(eq a b)				; returns T
	(eq a c) 				; returns NIL 


eql
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xllist.c and xlsubr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(eql <expr1> <expr2> )
	<exprN>		-	an expression to compare

DESCRIPTION

The EQL predicate checks to see if <expr1> and <expr2> are identical (in
the EQ test sense - the expression  values being the same exact internal
values) or if they have the same value when the expressions are numbers.
T is returned if they are identical or have the same numeric  value, NIL
is returned otherwise.

EXAMPLES

	(eql 'a 'a)				; returns T
	(eql 1 1)				; returns T
	(eql 1 1.0)				; returns NIL
	(eql 1.0 1.0)				; returns T
	(eql "a" "a")				; returns NIL
	(eql '(a b) '(a b))			; returns NIL
	(eql 'a 34)				; returns NIL

	(setq a '(a b))				; set value of A to (A B)
	(setq b a)				; set B to point to A's value
	(setq c '(a b))				; set value of C to dif. (A B)
	(eql a b)				; returns T
	(eql a c) 				; returns NIL 


equal
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xllist.c and xlsubr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(equal <expr1> <expr2> )
	<exprN>		-	an expression to compare

DESCRIPTION

The  EQUAL   predicate   checks  to  see  if  <expr1>  and  <expr2>  are
structurally  equivalent.  T is returned if they are equivalent,  NIL is
returned otherwise.

EXAMPLES

	(equal 'a 'a)				; returns T
	(equal 1 1)				; returns T
	(equal 1 1.0)				; returns NIL
	(equal 1.0 1.0)				; returns T
	(equal "a" "a")				; returns T
	(equal '(a b) '(a b))			; returns T
	(equal 'a 34)				; returns NIL

	(setq a '(a b))				; set value of A to (A B)
	(setq b a)				; set B to point to A's value
	(setq c '(a b))				; set value of C to dif. (A B)
	(equal a b)				; returns T
	(equal a c) 				; returns T

	(equal '(a b) '(A B))			; returns T
	(equal '(a b) '(c d))			; returns NIL
	(equal "a" "A")				; returns NIL
	(equal "abc" "abcD")			; returns NIL

NOTE:
A way to view EQUAL is that if <expr1> and  <expr2>  were  printed  (via
PRINT or PRINC), if they look the same, then EQUAL will return T.


error
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c  and  xldbug.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(error  <err-msg>  [ <arg> ] )
	<err-msg>	-	a string expression for the error message
	<arg>		-	an optional expression 

DESCRIPTION

The ERROR function allows the generation of a non-correctable  error.  A
non-correctable  error  requires  evaluation  of a CLEAN-UP or TOP-LEVEL
function from within the XLISP break loop to return to normal execution.
The form of the message generated is:

	error: <err-msg> - <arg>

From within the  break-loop, if a CONTINUE  function is evaluated then a
an error message is generated - "error:  this error can't be continued".
There is no return from the ERROR function.

EXAMPLES

	(error "fee" "fi")			; ERROR generates the message -
						; error: fee - "fi"
	(error "can't get" "there")		; ERROR generates the message -
						; error: Can't get - "there"

COMMON LISP COMPATIBILITY:
Common  LISP and XLISP  have the same  basic  form and style for  ERROR.
However, the <err-msg>  string in Common LISP is sent to FORMAT.  FORMAT
is a output  function that takes in format strings that include  control
information.  Although,  XLISP does have the FORMAT  function, it is not
used with error  messages.  Porting  from XLISP to Common LISP will work
fine.  When  porting  from Common  LISP to XLISP, you will need to check
for this embedded control information in the error messages.

NOTE:
Remember  that  *BREAKENABLE*  needs to non-NIL for ERROR and CERROR and
system  errors  to be  caught  by  the  normal  system  break  loop.  If
*BREAKENABLE*  is NIL, ERROR and CERROR and system  errors can be caught
by an ERRSET form.  If there is no surrounding  ERRSET, no error message
is generated and the break loop is not entered.


*error-output*
________________________________________________________________________

type: system variable 
location: built-in
source file: xlinit.c  xlio.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

*error-output*


DESCRIPTION

*ERROR-OUTPUT*  is a system  variable  that contains a file pointer that
points to the file where all error output goes to.  The default file for
*ERROR-OUTPUT*  is the  system  standard  error  device -  normally  the
screen.

EXAMPLES
	*error-output*				; returns #<File-Stream: #243de>

NOTE:
*TRACE-OUTPUT*,  *DEBUG-IO* and  *ERROR-OUTPUT*  are normally all set to
the same file stream - STDERR.


errset
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(errset  <expr> [ <print-flag> ]  )
	<expr>		-	an expression to be evaluated
	<print-flag>	-	an optional expression ( NIL or non-NIL )

DESCRIPTION

The ERRSET  special  form is a  mechanism  that allows the  trapping  of
errors within the execution of <expr>.  *BREAKENABLE* must be set to NIL
for the ERRSET  form to  function.  If  *BREAKENABLE*  is  non-NIL,  the
normal break loop will handle the error.  For ERRSET, if no error occurs
within <expr>, the value of the last  expression is CONSed with NIL.  If
an error occurs  within  <expr>, the error is caught by ERRSET and a NIL
is returned  from  ERRSET.  If  <print-flag>  is NIL, the error  message
normally  generated by <expr> will not be printed.  If  <print-flag>  is
non-NIL or not  present in the ERRSET  form, the error  message  will be
printed.

Errors  from  ERROR and CERROR and  system  errors  will be  handled  by
ERRSET.  Note  that the  CERROR  message  will only  include  the  error
message  portion,  not  the  continue  message  portion.  BREAK  is  not
intercepted by ERRSET.

EXAMPLES

	(nodebug)				; sets *BREAKENABLE* to NIL
	(errset (error "hi" "ho"))		; prints  error: hi - "ho"
						; returns NIL
	(errset (cerror "hi" "ho" "he"))	; prints  error: ho - "he"
						; returns NIL
	(errset (error "hey" "ho") NIL)		; returns NIL
	(errset (break "hey"))			; break: hey
	(errset (+ 1 5) )			; returns (6)
	(errset (+ 1 "a") NIL )			; returns NIL
	(debug)					; re-enable break-loop on errors

NOTE:
Be sure to set  *BREAKENABLE*  to NIL before using ERRSET and to non-NIL
after using ERRSET.  If you don't reset *BREAKENABLE*, no errors will be
reported.


eval
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c  and  xleval.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(eval <expression> )
	<expression>	-	An arbitrary expression

DESCRIPTION

EVAL evaluates the <expression> and returns the resulting value.

EXAMPLES

	(eval '(+ 2 2))				; returns 4
	(eval (cons '+ '(2 2 2)))		; returns 6
	(eval (list '+ '2 '3 ))			; returns 5

	(setq a 10)				; set up A with value 10	
	(setq b 220)				; set up B with value 220
	(eval (list '+ a b ))			; returns 230 because
						;  (list '+ a b) => '(+ 10 220)
	(eval (list '+ 'a b))			; returns 230 because
						;  (list '+ 'a b) => '(+ A 220)
						;  and A has the value 10


evalhook
________________________________________________________________________

type: function (subr)
location: built-in
source file: xlbfun.c  and  xleval.c
Common LISP compatible: related
supported on: all machines

SYNTAX

(evalhook  <expr> <eval-expr> <apply-expr> [ <env> ] )
	<expr>		-	an expression to evaluate
	<eval-expr>	-	an expression for the evaluation routine
	<apply-expr>	-	an expression for APPLY - not used
	<env>		-	an environment expression - default is NIL

DESCRIPTION

EVALHOOK is a function that performs  evaluation.  The routine specified
by  <eval-expr>  is called  with the  <expr>  and <env>  parameters.  If
<eval-expr>  is NIL, then the normal  system  evaluator  is called.  The
<apply-hook> is a dummy  parameter that is not used in the current XLISP
system.  The <expr>  contains the  expression  to be  evaluated.  If the
<env>  argument  to  EVALHOOK  is not  specified,  NIL  is  used,  which
specifies  to  use  the  current  global   environment.  The  <env>,  if
specified, is a structure  composed of dotted pairs  constructed  of the
symbol and its value which have the form ((( (<sym1> .  <val1> ) (<sym2>
.  <val2> ) ...  ))).

EXAMPLES

	(setq a 100)	(setq b 200)		; set up global values
	(evalhook '(+ a b) NIL NIL)		; returns 300	- no <env>
	(evalhook '(+ a b) NIL NIL 		; eval with a=1 and b=2
		  '((((a . 1)(b . 2)))))	;   returns 3


	(defun myeval (exp env)			; define MYEVAL routine
	   (princ "exp: ") (print exp)		; 
	   (princ "env: ") (print env)		;
	   (evalhook exp #'myeval NIL env))	;
	(defun foo (a) (+ a a))			; create simple function
	(setq *evalhook* #'myeval)		; and install MYEVAL as hook
	(foo 1)					; prints  
						; exp: (FOO 1) env:NIL
						; exp: 1       env:NIL
						; exp: (+ A A) env:((((A . 1))))
						; exp: A       env:((((A . 1))))
						; exp: A       env:((((A . 1))))
						; returns 2
	(top-level)				; to clean up *evalhook*)

NOTE:
The EVALHOOK  function and *EVALHOOK* system variable are very useful in
the  construction of debugging  facilities  within XLISP.  The TRACE and
UNTRACE  functions  use  EVALHOOK  and  *EVALHOOK*  to  implement  their
functionality.  The other useful aspect of EVALHOOK and *EVALHOOK* is to
help in  understanding  how XLISP  works to see the  expressions,  their
environment and how they are evaluated.

CAUTION:
Be careful when using  *EVALHOOK*  and  EVALHOOK.  If you put in a 'bad'
definition  into  *EVALHOOK*,  you might not be able to do anything  and
will need to exit XLISP.

UNUSUAL BEHAVIOUR:
The EVALHOOK  function and *EVALHOOK*  system variable, by their nature,
cause some unusual  things to happen.  After you have set  *EVALHOOK* to
some non-NIL value, your function will be called.  However, when you are
all done and set  *EVALHOOK*  to NIL or some other new  routine, it will
never be set.  This is because the  XEVALHOOK  function (in the xlbfun.c
source  file)  saves the old value of  *EVALHOOK*  before  calling  your
routine, and then  restores it after the  evaluation.  The  mechanism to
reset  *EVALHOOK*  is to execute  the  TOP-LEVEL  function,  which  sets
*EVALHOOK* to NIL.


*evalhook*
________________________________________________________________________

type: system variable 
location: built-in
source file: xleval.c
Common LISP compatible: related
supported on: all machines

SYNTAX

*evalhook*


DESCRIPTION

*EVALHOOK*  is a system  variable  whose  value is user  code  that will
intercept evaluations either through normal system evaluation or through
calls to  EVALHOOK.  The  default  value for  *EVALHOOK*  is NIL,  which
specifies  to use the  built  in  system  evaluator.  If  *EVALHOOK*  is
non-NIL,  the  routine  is  called  with   expression  and   environment
parameters.  If the  environment  argument is NIL, then the the  current
global environment is used.  The environment, if non-NIL, is a structure
composed of dotted pairs  constructed  of the symbol and its value which
have the form ((( (<sym1> .  <val1> ) (<sym2> .  <val2> ) ...  ))).

EXAMPLES
	(defun myeval (exp env)			; define MYEVAL routine
	   (princ "exp: ") (print exp)		; 
	   (princ "env: ") (print env)		;
	   (evalhook exp #'myeval NIL env))	;
	(defun foo (a) (+ a a))			; create simple function
	(setq *evalhook* #'myeval)		; and install MYEVAL as hook
	(foo 1)					; prints  
						; exp: (FOO 1) env:NIL
						; exp: 1       env:NIL
						; exp: (+ A A) env:((((A . 1))))
						; exp: A       env:((((A . 1))))
						; exp: A       env:((((A . 1))))
						; returns 2
	(top-level)				; to clean up *evalhook*)

NOTE:
The EVALHOOK  function and *EVALHOOK* system variable are very useful in
the  construction of debugging  facilities  within XLISP.  The TRACE and
UNTRACE  functions  use  EVALHOOK  and  *EVALHOOK*  to  implement  their
functionality.  The other useful aspect of EVALHOOK and *EVALHOOK* is to
help in  understanding  how XLISP  works to see the  expressions,  their
environment and how they are evaluated.

CAUTION:
Be careful when using  *EVALHOOK*  and  EVALHOOK.  If you put in a 'bad'
definition  into  *EVALHOOK*,  you might not be able to do anything  and
will need to exit XLISP.

UNUSUAL BEHAVIOUR:
The EVALHOOK  function and *EVALHOOK*  system variable, by their nature,
cause some unusual  things to happen.  After you have set  *EVALHOOK* to
some non-NIL value, your function will be called.  However, when you are
all done and set  *EVALHOOK*  to NIL or some other new  routine, it will
never be set.  This is because the  XEVALHOOK  function (in the xlbfun.c
source  file)  saves the old value of  *EVALHOOK*  before  calling  your
routine, and then  restores it after the  evaluation.  The  mechanism to
reset  *EVALHOOK*  is to execute  the  TOP-LEVEL  function,  which  sets
*EVALHOOK* to NIL.


evenp
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(evenp <expr> )
	<expr>		-	the integer numeric expression to check

DESCRIPTION

The EVENP  predicate  checks to see if the number  <expr> is even.  T is
returned  if the  number  is  even,  NIL is  returned  otherwise.  A bad
argument  type  error  is  generated  if the  <expr>  is  not a  numeric
expression.  A bad floating  point  operation is generated if the <expr>
is a floating point number.  Zero is an even number.

EXAMPLES

	(evenp 0)				; returns T
	(evenp 1)				; returns NIL
	(evenp 2)				; returns T
	(evenp -1)				; returns NIL
	(evenp -2)				; returns T

	(evenp 14.0)				; error: bad flt. pt. op.
	(evenp 'a)				; error: bad argument type
	(setq a 2)				; set value of A to 2
	(evenp a)				; returns T


exit
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlsys.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(exit)


DESCRIPTION

The EXIT function causes the current XLISP session to be terminated.  It
never returns.

EXAMPLES

	(exit)					; never returns

KEYSTROKE EQUIVALENT:
In the IBM PC and MS-DOS  versions of XLISP, a CTRL-z key  sequence  has
the  same  effect  as  doing  a  (EXIT).  On a  Macintosh,  this  can be
accomplished by a pull-down menu or a COMMAND-q.

NOTE:
When  XLISP is EXITed,  any  TRANSCRIPT  file is  automatically  closed.
However,  other  open  files  are  not  closed,  and  so may  lose  some
information.


exp
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(exp <power> )
	<power>		-	floating point number/expression

DESCRIPTION

The EXP function  calculates e (2.7128) raised to the specified  <power>
and returns the result.

EXAMPLES

	(exp 0.0)				; returns 1
	(exp 1.0)				; returns 2.71828  (e)
	(exp 2.0)				; returns 7.38906
	(exp 10.0)				; returns 22026.5
	(exp 0)					; error: bad integer operation

NOTE:
EXP with a large  <power> like 1000.0  causes an  incorrect  value to be
generated,  with no  error.  The  returned  value  will be a very  large
floating  point  number  near  the  computer's   limit  (something  like
1.79000e+308).


expand
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlsys.c  and  xldmem.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(expand  <segments> )
	<segments>	-	an integer expression

DESCRIPTION

The  EXPAND  function   expands  memory  by  the  specified   number  of
<segments>.  The  expression  <segments> is returned as the result.  The
power up default is 1000 nodes per segment.  Note that ALLOC  allows you
to change the number of nodes per segment.

EXAMPLES

	(room)					; prints  Nodes:       8000
						;	  Free nodes:  5622
						;	  Segments:    6
						;	  Allocate:    1000
						;	  Total:       92586
						;	  Collections: 8
						; returns NIL
	(expand 2)				; add more nodes
	(room)					; prints  Nodes:       10000
						;	  Free nodes:  7608
						;	  Segments:    8
						;	  Allocate:    1000
						;	  Total:       112602
						;	  Collections: 8
						; returns NIL

NOTE:
When GC is called or an  automatic  garbage  collection  occurs,  if the
amount of free  memory is still low after the  garbage  collection,  the
system attempts to add more segments (an automatic EXPAND).


expt
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(expt <expr> [ <power> ... ] )
	<expr>		-	floating point number/expression
	<power>		-	integer or floating point number/expression

DESCRIPTION

The EXPT function raises the <expr> to the specified <power> and returns
the result.  If there is no <power>  specified,  the <expr> is returned.
If there are multiple  <power>'s, they will be applied  sequentially  to
<expr>.

EXAMPLES

	(expt 2.0 2)				; returns 4
	(expt 2.0 10)				; returns 1024
	(expt 2 2)				; error: bad integer operation
	(expt 99.9)				; returns 99.9
	(expt 2.0 2.0 2.0)			; returns 16

NOTE:
EXPT with a large  values like (expt 999.9  999.9)  causes an  incorrect
value to be generated, with no error.  The returned value will be a very
large floating point number near the computer's  limit  (something  like
1.79000e+308).


fboundp
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(fboundp <symbol> )
	<symbol>	-	the symbol expression to check for a value

DESCRIPTION

The  FBOUNDP  predicate  checks to see if  <symbol>  is a symbol  with a
function  definition  (closure)  bound to it.  T is returned if <symbol>
has a function value, NIL is returned  otherwise.  Note that <symbol> is
a symbol  expression - it is evaluated and the  resulting  expression is
the one that is checked.

EXAMPLES

	(defun foo (x) (print x))		; set up function FOO
	(fboundp 'foo)				; returns T - value is closure
	(fboundp 'defvar)			; returns T - value is closure
	(fboundp 'car)				; returns T - value is closure

	(setq myvar 'goo)			; set up MYVAR to have value GOO
	(FBOUNDP myvar)				; returns NIL - because GOO has
						;               no value yet
	(defmacro goo () (print "hi"))		; define GOO macro
	(FBOUNDP myvar)				; returns T

	(fboundp 'a)				; returns NIL 
	(fboundp '1)				; error: bad argument type - 1
	(fboundp "hi")				; error: bad argument type - "hi"


first
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlinit.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(first <expr> )
	<expr>		-	a list or list expression

DESCRIPTION

FIRST  returns  the  first  element  of the  expression.  If  the  first
expression  is itself a list, then the sublist is returned.  If the list
is NIL, NIL is returned.

EXAMPLES
	(first '(a b c))			; returns A
	(first '((a b) c d))			; returns (A B)
	(first NIL)				; returns NIL
	(first 'a)				; error: bad argument type

	(setq children '(amanda ben))		; set up variable CHILDREN
	(first children)			; returns AMANDA

flatc
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c  and  xlprin.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(flatc  <expr> )
	<expr>		-	an expression

DESCRIPTION

The FLATC function determines the character length that would be printed
if the  <expr>  were  printed  using  PRINC.  This means that the <expr>
would be  printed  without a  new-line.  If <expr> is a string, it would
not be printed  with  quotes  around  the  string.  The print  character
length is returned as the result.

EXAMPLES

	(flatc 1234)				; returns 4
	(flatc '(a b c))			; returns 7
	(flatc "abcd")				; returns 4
	(flatc 'mybigsymbol)			; returns 11


flatsize
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c  and  xlprin.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(flatsize  <expr> )
	<expr>		-	an expression

DESCRIPTION

The FLATSIZE  function  determines  the  character  length that would be
printed if the <expr>  were  printed  using  PRIN1.  This means that the
<expr>  would be printed  without a new-line.  If <expr> is a string, it
would be printed  with quotes  around the  string.  The print  character
length is returned as the result.

EXAMPLES

	(flatsize 1234)				; returns 4
	(flatsize '(a b c))			; returns 7
	(flatsize "abcd")			; returns 6
	(flatsize 'mybigsymbol)			; returns 11


flet
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(flet  ( [ <function> ... ]  ) <expr> ... )
	<function>	-	a function definition binding which is of the 
				form  ( <symbol> <arg-list> <body> )
	<symbol>	-	the symbol specifying the function name
	<arg-list>	-	the argument list for the function 
	<body>		-	the body of the function
	<expr>		-	an expression

DESCRIPTION

The FLET special form is basically a local block  construct  that allows
local  <function>  definitions  followed by a block of code to evaluate.
The first form  after the FLET is the  'binding'  form.  It  contains  a
series of  <functions>.  The FLET form will go  through  and  define the
<symbol>s of the <functions> and then sequentially execute the <expr>'s.
The value of the last <expr>  evaluated  is  returned.  When the FLET is
finished  execution,  the  <symbol>'s  that were defined  will no longer
exist.

EXAMPLES

	(flet ( (fozz (x) (+ x x) ))		; an FLET with FOZZ local func.
	    (fozz 2))				; returns 4
						; FOZZ no longer exists
	(fozz 2)				; error: unbound function - FOZZ

						; an empty flet
	(flet () (print 'a))			; prints A

NOTE:
FLET  does not allow  recursive  definitions  of  functions.  The  LABEL
special form does allow this.


float
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(float <expr> )
	<expr>		-	integer or floating point number/expression

DESCRIPTION

The FLOAT  function  takes a numeric  expression  and returns the result
which is forced to be a floating point number.

EXAMPLES

	(/ 1 2)					; returns 0 (integer division)
	(/ (float 1) 2)				; returns 0.5
	(float (/ 1 2))				; returns 0 (integer division)
	(/ 1 2 3)				; returns 0 (integer division)
	(/ (float 1) 2 3)			; returns 0.166667


*float-format*
________________________________________________________________________

type: system variable 
location: built-in
source file: xlprin.c
Common LISP compatible: no
supported on: all machines

SYNTAX

*float-format*


DESCRIPTION

*FLOAT-FORMAT*  is a system  variable  that allows a user to specify how
floating  point  numbers  are to be  printed  by  XLISP.  The  value  of
*FLOAT-FORMAT* should be set to one of the string expressions "%e", "%f"
or "%g".  These format strings are similar to C-language  floating point
specifications.

	format	name		description
	----------------------------------------------------------------
	%e      exponential     The  number  is  converted   to  decimal
				notation of the form [-]m.nnnnnnE[+-]xx.
				There is one leading digit.  There are 6
				digits after the decimal point.

	%f      decimal         The  number  is  converted   to  decimal
				notation of the form  [-]mmmmmm.nnnnnn .
				There  are as  many  digits  before  the
				decimal point as necessary.  There are 6
				digits after the decimal point.

	%g      shortest        The number is  converted  to either  the
				form of %e or %f, whichever produces the
				shortest output string.  Non-significant
				zeroes are not printed.

The default value for *FLOAT-FORMAT* is the string "%g".  

EXAMPLES
	(setq *float-format* "%e")		; exponential notation
	(print 1.0)				; prints 1.000000e+00
	(print -9e99)				; prints -9.000000e+99

	(setq *float-format* "%f")		; decimal notation
	(print 1.0)				; prints 1.000000
	(print 1.0e4)				; prints 10000.000000
	(print -999.99e-99)			; prints -0.000000

	(setq *float-format* "%g")		; shortest notation
	(print 1.0)				; prints 1
	(print 1.0e6)				; prints 1000000
	(print 1.0e7)				; prints 1e+07
	(print -999.999e99)			; prints -9.99999e+101

	(setq *float-format* "SOMETHING")	; bad notation
	(print 1.0)				; prints SOMETHING
	(setq *float-format* "%g")		; reset to shortest notation

NOTE:
There can be other  characters  put in the string, but in general,  this
will not produce  particularly  desirable  behaviour.  There is no error
checking performed on the format string.


floatp
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(floatp <expr> )
	<expr>		-	the expression to check

DESCRIPTION

The FLOATP predicate  checks if an <expr> is a floating point number.  T
is  returned  if <expr> is a  floating  point  number,  NIL is  returned
otherwise.

EXAMPLES

	(floatp 1.2)				; returns T - float
	(floatp '1.2)				; returns T - still a float
	(setq a 1.234)				; 
	(floatp a)				; returns T - evaluates to float
	(floatp 0.0)				; returns T - float zero

	(floatp 0)				; returns NIL - integer zero
	(floatp 1)				; returns NIL - integer
	(floatp #x034)				; returns NIL - integer readmacro 
	(floatp 'a)				; returns NIL - symbol
	(floatp #\a)				; returns NIL - character
	(floatp NIL)				; returns NIL - NIL
	(floatp #(0 1 2))			; returns NIL - array 


fmakunbound
________________________________________________________________________

type: defined function (closure)
location: extension
source file: init.lsp
Common LISP compatible: yes
supported on: all machines

SYNTAX

(fmakunbound  <symbol> )
	<symbol>	-	an expression evaluating to a symbol

DESCRIPTION

The FMAKUNBOUND  function makes a symbol's function definition  unbound.
The  <symbol>  must be a valid  symbol,  but it does  not need to have a
definition.  The FMAKUNBOUND  function returns the symbol as its result.

EXAMPLES

	(defun myfn () (print "hi"))		; define MYFN
	(myfn)					; prints "hi"
	(fmakunbound 'myfn)			; returns MYFN
	(myfn)					; error: unbound function - MYFN

NOTE:
FMAKUNBOUND is not misspelled - there is no 'e' in it.

NOTE:
The  FMAKUNBOUND  works on  functions  (closures)  in the same way  that
MAKUNBOUND  works on variables.  Be sure to use the correct one for what
you are unbinding.  These  functions do not generate an error if you try
to unbind the wrong  type.  This is because of the  definition  of these
functions  and the fact that the function and  variable  name spaces are
separate.  You can have both a function called FOO and a variable called
FOO.

NOTE:
The function  FMAKUNBOUND  is created in the INIT.LSP  file.  If it does
not  exist in your  XLISP  system,  you  might be having a problem  with
INIT.LSP.  Before  you  start  XLISP,  look  in the  directory  you  are
currently in, and check to see if there is an INIT.LSP.


format
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(format <destination> <format>  [ <expr1> ... ]  )
	<destination> 	-	a required destination - must be a file 
				pointer, a stream, NIL (to create a string) 
				or T (to print to *standard-output*)
	<format>	-	a format string
	<exprN>		-	an expression

DESCRIPTION

The FORMAT  function  prints the specified  expressions  (if any) to the
specified  <destination>  using the <format> string to control the print
format.  If the  <destination>  is NIL, a string is created and returned
with  the  contents  of  the  FORMAT.  If  the  <destination>  is T, the
printing  occurs  to  *STANDARD-OUTPUT*.  FORMAT  returns  a NIL, if the
<destination> was non-NIL.  The <format> string is a string  (surrounded
by  double-quote  characters).  This  string  contains  ASCII text to be
printed along with  formatting  directives  (identified  by a preceeding
tilde ~ character).  The character  following the tilde character is not
case sensitive (~a and ~A will function equivalently).

EXAMPLES

	(format T "Now is the time for")	; prints  Now is the time for
	(format T "all ~A ~S to" 'good 'men)	; prints  all GOOD MEN to 
	(format T "come to the")		; prints  come to the
	(format T "~A of their ~S" 		; prints  aid of their "party"
		"aid" "party")			;

	(format *standard-ouput* "Hello there")	; prints  Hello there
	(format nil "ho ho ~S" 'ho)		; returns "ho ho HO"

	(format T "this is ~%a break")		; prints  this is
						;         a break 
	(format T "this is a long ~
             	   string")			; prints  this is a long string

SUPPORTED FORMAT DIRECTIVES:
The <format> string in XLISP supports the following format directives:

	directive	name		action
	----------------------------------------------------------------
	~A		ASCII		Print the <expr>. 

					If  it  is  a  string  print  it
					without  quotes.  This  is  like
					the PRINC function.

	~S		S-EXPR		Print the <expr>. 

					If it is a string  print it with
					quotes.  This is like the  PRIN1
					function.

	~%		NEW-LINE	Print a new line. 

	~~		TILDE		Print a single tilde ~ character. 

	~<new-line>     CONTINUE        Continue the <format>  string on
					the next line.

					This signals a line break in the
					format.  The FORMAT will  ignore
					all  white-space  (blanks, tabs,
					newlines).  This is useful  when
					the  <format>  string is  longer
					than a program  line.  Note that
					the  new-line   character   must
					immediately   follow  the  tilde
					character.

COMMON LISP COMPATABILITY:
The FORMAT function in Common LISP is quite  impressive.  It includes 26
different  formatting  directives.  XLISP,  as  shown  above,  does  not
include most of these.  The more difficult ones that you might encounter
are the Decimal, Octal,  heXidecimal,  Fixed-format  floating-point  and
Exponential  floating-point.  It is  possible  to  print  in  octal  and
hexadecimal  notation  by setting  *INTEGER-FORMAT*.  It is  possible to
print  in  fixed  format  and  exponential  by  setting  *FLOAT-FORMAT*.
However,  neither of these system variables are supported in Common LISP
and neither gives control over field size.


fourth
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlinit.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(fourth <expr> )
	<expr>		-	a list or list expression

DESCRIPTION

FOURTH returns the fourth element of a list or list  expression.  If the
list is NIL, NIL is returned.

EXAMPLES
	(fourth '(1 2 3 4 5))			; returns 4
	(fourth NIL)				; returns NIL

	(setq kids '(junie vickie cindy chris))	; set up variable KIDS
	(first kids)				; returns JUNIE
	(second kids)				; returns VICKIE
	(third kids)				; returns CINDY
	(fourth kids)				; returns CHRIS
	(rest kids)				; returns (VICKIE CINDY CHRIS)

NOTE:
This  function is set to the same  code as CADDDR.  


funcall
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(funcall <function> [<arg1> ... ] )
	<function>	-	the function or symbol to be called
	<argN>		-	an argument to be passed to <function>

DESCRIPTION

FUNCALL  calls a function with a series of  arguments.  FUNCALL  returns
the result from <function>.

EXAMPLES

	(funcall '+ 1 2 3 4)			; returns 10
	(funcall #'+ 1 2 3 4)			; returns 10
	(funcall '+ '1 '2 '3)			; returns 6

	(setq sys-add (function +))		; returns #<Subr-+: #22c32>
	(setq a 99)				;
	(funcall sys-add 1 a)			; 100
	(funcall sys-add 1 'a)			; error: bad argument type
						;   you can't add a symbol
						;   only it's value

	(setq a 2)	(setq b 3)		; set A and B values
	(funcall (if (< a b) (function +)	; <function> can be computed
			     (function -))	;
		 a b)				; returns 5

	(defun add-to-list (arg list)		; add a list or an atom
	   (funcall (if (atom arg) 'cons 	;   to the front of a list
	                           'append)	;
                    arg list))			;
	(add-to-list 'a '(b c))			; returns (A B C)
	(add-to-list '(a b) '(b c))		; returns (A B B C)


function
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c 
Common LISP compatible: yes
supported on: all machines

SYNTAX

(function <expr> )
	<expr>		-	an expression that evaluates to a function

DESCRIPTION

FUNCTION  returns the function  definition  of the <expr>.  Execution of
the <expr>  form does not occur.  FUNCTION  will  operate on  functions,
special forms, lambda-expressions and macros.

EXAMPLES

	(function car)				; returns #<Subr-CAR: #23ac4>
	(function quote)			; returns #<FSubr-QUOTE: #23d1c>
	#'quote					; returns #<FSubr-QUOTE: #23d1c>
	(function 'cdr)				; error: not a function 

	(defun foo (x) (+ x x))			; define FOO function
	(function foo)				; returns #<Closure-FOO: #2cfb6>
	(defmacro bar (x) (+ x x))		; define FOOMAC macro
	(function bar)				; returns #<Closure-BAR: #2ceee>

	(setq my 99)				; define a variable
	(function my)				; error: unbound function
	(defun my (x) (print x))		; define a function
	(function my)				; returns #<Closure-MY: #2cdd6>
						;
						; NOTE THAT THERE ARE 2 SYMBOLS
						; A VARIABLE my AND A FUNCTION
						; my.

READ MACRO:
XLISP  supports  the  normal  read  macro of a hash and quote  (#') as a
short-hand method of writing the FUNCTION special form.


gc
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xldmem.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(gc)


DESCRIPTION

The GC  function  forces a garbage  collection  of the unused  memory of
XLISP.  NIL is always returned.

EXAMPLES

	(gc)					; force a garbage collection

NOTE:
The system will cause an automatic garbage  collection if it runs out of
free memory.

NOTE:
When GC is called or an  automatic  garbage  collection  occurs,  if the
amount of free  memory is still low after the  garbage  collection,  the
system attempts to add more segments (an automatic EXPAND).


gcd
________________________________________________________________________

type: function (subr)
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(gcd [ <int> ... ] )
	<int>		-	an integer expression


DESCRIPTION

The GCD  function  returns the  greatest  common  divisor of a series of
integers.  If no  arguments  are given, a zero is returned.  If only one
argument is given, the absolute  value of the argument is returned.  The
successful result is always a positive integer.

EXAMPLES
	(gcd 51 34)				; returns 17
	(gcd 99 66 22)				; returns 11
	(gcd -99 66 -33)			; returns 33
	(gcd -14)				; returns 14
	(gcd 0)					; returns 0
	(gcd)					; returns 0
	(gcd .2)				; error: bad argument type - 0.2

*gc-flag*
________________________________________________________________________

type: system variable 
location: built-in
source file: xldmem.c
Common LISP compatible: no
supported on: all machines

SYNTAX

*gc-flag*


DESCRIPTION

*GC-FLAG* is a system  variable that  controls the printing of a garbage
collection message.  If *GC-FLAG* is NIL, no garbage collection messages
will be printed.  If *GC-FLAG* is non-NIL, a garbage collection  message
will be  printed  whenever  a GC takes  place.  The  default  value  for
*GC-FLAG* is NIL.  The message will be of the form:

	[ gc: total 4000, 2497 free ]


EXAMPLES
	*gc-flag*				; returns NIL
	(gc)					; returns NIL
	(setq *gc-flag* T)			; set up for message
	(gc)					; prints a gc message


*gc-hook*
________________________________________________________________________

type: system variable 
location: built-in
source file: xldmem.c
Common LISP compatible: no
supported on: all machines

SYNTAX

*gc-hook*


DESCRIPTION

*GC-HOOK*  is a  system  variable  that  allows  a user  function  to be
performed  everytime garbage is collected (either  explicitly with GC or
automatically).  The default value for *GC-HOOK* is NIL.  When *GC-HOOK*
is set to a non-NIL  symbol, it is enabled to execute the specified user
routine.  The user  routine can be a quoted  symbol or a closure.  There
are two  parameters  to the user routine - the total number of nodes and
current free nodes after the garbage collection.

EXAMPLES
	*gc-hook*				; returns NIL
	(gc)					; returns NIL

	(defun mygchook (&rest stuff) 		; define the hook 
		(print stuff) 			;
		(print "my hook"))		;
	(setq *gc-hook* 'mygchook)		; set up *GC-HOOK*
	(gc)					; prints (2640 232)
						;        "my hook"
						; returns NIL
	(setq *gc-flag* T)			; turn on the system GC message
	(gc)					; prints 
						;   [ gc: total 2640, (2640 241)
						;   "my hook"
						;   236 free ]
						; returns NIL
	(setq *gc-flag* NIL)			; turn off GC message	

	(setq *gc-hook* (lambda (x y) 		; enable user routine
			    (princ "\007")))	;   that beeps at every GC
	(gc)					; beeps

	(defun expand-on-gc (total free)	; define EXPAND-ON-GC
	  (if (< (/ free 1.0 total) .1)		; IF free/total < .10
	      (progn (expand 2)			;    THEN expand memory
	             (princ "\007") )		;         and beep
	      )					;    ELSE do nothing
	  )					; NOTE: XLISP already gets more
	  					;       nodes automatically,
						;       this is just an example.
	(setq *gc-hook* 'expand-on-gc)		; enable EXPAND-ON-GC
	(gc)					; beeps when low on nodes

NOTE:
The *GC-HOOK* and *GC-FLAG* facilities can interact.  If you do printing
in the *GC-HOOK* user form and enable *GC-FLAG*, the *GC-HOOK*  printing
will come out in the middle of the *GC-FLAG* message.

NOTE:
The *GC-HOOK*  user form is evaluated  after the execution of the actual
garbage  collection  code.  This means  that if the user form  causes an
error, it does not prevent a garbage collection.

NOTE:
Since *GC-HOOK* is set to a symbol, the user defined form can be changed
by doing  another DEFUN (or whatever) to the symbol in  *GC-HOOK*.  Note
also that you should  define the symbol first and then set  *GC-HOOK* to
the symbol.  If you don't, an automatic  garbage  collection might occur
before  you set  *GC-HOOK*  -  generating  an error  and  stopping  your
program.


gensym
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(gensym [<tag>])
	<tag>		-	an optional integer or string 

DESCRIPTION

GENSYM generates and returns a symbol.  

The default  symbol  form is as a character G followed by a number - Gn.
The default  numbering  starts at 1.  You can change what the  generated
symbol looks like.  By calling  GENSYM with a string  <tag>, the default
string is set to string  parameter.  If an integer  number is the <tag>,
the current number is set to the integer parameter.

EXAMPLES
	(gensym)				; first time => G1
	(gensym 100)				; returns G100
	(gensym "MYGENSYM")			; returns MYGENSYM101
	(gensym 0)				; returns MYGENSYM0
	(gensym)				; returns MYGENSYM1
	(gensym "G")				; \
	(gensym 0)				; /  put it back to 'normal'
	(gensym)				; just like first time => G1

NOTE:
It takes 2 calls to GENSYM to set both portions of the GENSYM symbol.

NOTE:
Although it is possible to call GENSYM with numbers in the string  (like
"AB1"),  this does  generate an odd  sequence.  What will  happen is you
will get a sequence of symbols like .....AB18 AB19 AB110 AB111.....


get
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(get <symbol> <property> )
	<symbol>	-	the symbol with a property list
	<property>	-	the property name being retrieved

DESCRIPTION

GET  returns  the  value of the  <property>  from the  <symbol>.  If the
<property>  does not exist, a NIL is returned.  The <symbol>  must be an
existing symbol.  The returned value may be a single value or a list.

Property  lists are lists  attached to any user defined  variables.  The
lists are in the form of (name1  val1 name2 val2  ....).  Any  number of
properties may be attached to a single variable.

EXAMPLES

	(setq person 'bobby)			; create a var with a value
	(putprop person 'boogie 'last-name)	; add a LAST-NAME property
	(putprop person 'disc-jockey 'job)	; add a JOB property
	(get person 'last-name)			; retrieve LAST-NAME - boogie
	(get person 'job)			; retrieve JOB - disc-jockey
	(get person 'height)			; non-existant - returns NIL
	(putprop person '(10 20 30) 'stats)	; add STATS - a list 
	(get person 'stats)			;

NOTE:
You can set a  property  to the value  NIL.  However,  this NIL value is
indistinguishable  from the NIL returned when a property does not exist.

COMMON LISP COMPATABILITY:
Common LISP allows for an optional  default  value, which XLISP does not
support.


get-key
________________________________________________________________________

type: function (subr) 
location: built-in 
source file: msstuff.c and osdefs.h and osptrs.h
Common LISP compatible: no
supported on: MS-DOS compatibles

SYNTAX

(get-key)


DESCRIPTION

The  GET-KEY  function  gets a single key stroke from the  keyboard  (as
opposed to an entire line - as READ does).

EXAMPLES

	(setq mychar (get-key))			; get a character

NOTE:
This  function is an  extension of the XLISP  system.  It is provided in
the  MSSTUFF.C  source code file.  If your XLISP  system is built for an
IBM PC and  compatibles  or MS-DOS,  this  function  will work.  If your
system is built on UNIX or some other  operating  system, it is unlikely
that these functions will work unless you extend STUFF.C.


get-lambda-expression
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlcont.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(get-lambda-expression <closure> )
	<closure>	-	a closure object from a previously defined 
				function.

DESCRIPTION

The  GET-LAMBDA-EXPRESSION  function  takes  the  <closure>  object  and
returns a reconstruction  of a LAMBDA or a MACRO expression that defines
the <closure>.  The parameter must be a <closure> expression (of the the
form #<Closure-FUNC #277e2> ).

EXAMPLES

	(defun mine (a b) (print (+ a b)))	; define MINE defun
	(get-lambda-expression (function mine))	; returns (LAMBDA (A B) 
						;	    (PRINT (+ A B)))

	(get-lambda-expression 			;
		(lambda (a) (print a))		; returns (LAMBDA (A) (PRINT A))

	(defmacro plus (n1 n2) `(+ ,n1 ,n2))	; define PLUS macro
	(get-lambda-expression (function plus))	; returns 
						;  (MACRO (N1 N2) 
						;    (BACKQUOTE (+ (COMMA N1) 
						;		   (COMMA N2))))


get-macro-character
________________________________________________________________________

type: defined function (closure) 
location: extension
source file: init.lsp
Common LISP compatible: related
supported on: all machines

SYNTAX

(get-macro-character <char-num> )
	<char-num>	-	an integer expression

DESCRIPTION

The GET-MACRO-CHARACTER  function returns the code that will be executed
when the specified  character  <char-num>  is  encountered  by the XLISP
reader.  The  returned  value  is  taken  from  the  *READTABLE*  system
variable  which  contains  the  reader  table  array.  The  table is 128
entries  (0..127) for each of the 7-bit ASCII  characters that XLISP can
read.  Each  entry  in  the  table  must  be one of  NIL,  :CONSTITUENT,
:SESCAPE,  :MESCAPE,  :WHITE-SPACE,  a :TMACRO  dotted pair or a :NMACRO
dotted pair.  The  GET-MACRO-CHARACTER  function will return a NIL value
if  the  table  entry  is  NIL,  :CONSTITUENT,   :SESCAPE,  :MESCAPE  or
:WHITE-SPACE.  If the table entry is :TMACRO or  :NMACRO,  then the code
associated   with  the  entry  is   returned.  :TMACRO  is  used  for  a
terminating   read-macro.  :NMACRO   is  used   for  a   non-terminating
read-macro.  GET-MACRO-CHARACTER does not differentiate whether the code
returned  is a :TMACRO or an :NMACRO.  The  function  returned  may be a
built-in  read-macro  function or a user defined lambda expression.  The
function  takes two  parameters, an input stream  specification,  and an
integer that is the character  value.  The <function>  should return NIL
if the character is  'white-space'  or a value CONSed with NIL to return
the value.

EXAMPLES

	(get-macro-character #\( )		; returns #<Subr-: #2401e> 
	(get-macro-character #\# )		; returns #<Subr-: #24082>
	(get-macro-character #\Space )		; returns NIL

NOTE:
In the normal XLISP system the following characters have code associated
with them in the *READTABLE*:

		" # ' ( ) , ; `

NOTE:
The functions GET-MACRO-CHARACTER and SET-MACRO-CHARACTER are created in
the INIT.LSP file.  If they do not exist in your XLISP system, you might
be having a problem with  INIT.LSP.  Before you start XLISP, look in the
directory  you  are  currently  in,  and  check  to see if  there  is an
INIT.LSP.

COMMON LISP COMPATABILITY:
The GET-MACRO-CHARACTER  function is somewhat related to the Common LISP
GET-DISPATCH-MACRO-CHARACTER function.


get-output-stream-list
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(get-output-stream-list <source> )
	<source>	-	an output stream expression

DESCRIPTION

The  GET-OUTPUT-STREAM-LIST  function empties the specified <source> and
returns  this data as a list.  The  output  stream  is  emptied  by this
operation.

EXAMPLES

	(setq out (make-string-output-stream))	; returns #<Unnamed-Stream: #2d2cc>
	(format out "123")			; add some data to output stream
	(get-output-stream-list out)		; returns (#\1 #\2 #\3)
	(format out "123")			; add some data to output stream
	(read out)				; returns 123
	(get-output-stream-list out)		; returns NIL


get-output-stream-string
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(get-output-stream-string <source> )
	<source>	-	an output stream expression

DESCRIPTION

The GET-OUTPUT-STREAM-STRING function empties the specified <source> and
returns this data as a single  string.  The output  stream is emptied by
this operation.

EXAMPLES

	(make-string-output-stream)		; returns #<Unnamed-Stream: #2d9c0>
	(setq out (make-string-output-stream))	; returns #<Unnamed-Stream: #2d95c>
	(format out "fee fi fo fum ")		; \
	(format out "I smell the blood of ")	;  fill up output stream
	(format out "Elmer Fudd")		; /
	(get-output-stream-string out)		; returns 
						;	"fee fi fo fum I smell
						;       the blood of Elmer Fudd"
	(format out "~%now what")		; add more to output stream
	(get-output-stream-string out)		; returns "\nnow what"
	(get-output-stream-string out)		; returns ""
	(format out "hello")			; add more to output stream
	(read out)				; returns HELLO


go
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(go <tag-symbol> )
	<tag-symbol>	-	a symbol 

DESCRIPTION

The GO special  form  allows  'go-to'  style  branching  within  'block'
constructs  (DO, DO*, DOLIST,  DOTIMES,  TAGBODY, LOOP, PROG and PROG*).
The  <tag-symbol>  is the  'label' and must exist  somewhere  within the
'block' that the GO occurs within.  Otherwise an error will be generated
-  "error:  no  target  for  GO".  GO  never  returns  a  value.  If the
<tag-symbol>  exists, then the execution will continue immediately after
the <tag-symbol>.

EXAMPLES

	(defun foo (i j)			; define FOO
	  (prog ()				; with a PROG
		 (print "begin")		;
           start (print j)			; tag - START
		 (setq j (1- j))		;
		 (if (eql i j) (GO start) 	; 2-way branch
			       (GO end))	; 
		 (print "hello")		; won't ever be reached
	   end   (print "done")			; tag - END
		 (return 42)))			; 
	(foo 1 2)				; prints  "begin" 2 1 "done"
						;   returns 42
	(foo 2 1)				; prints  "begin" 1 "done"
						;   returns 42

NOTE:
Although GO will accept a <tag-symbol> that is not a symbol, it will not
find this  improper  <tag-symbol>.  An error will be generated - "error:
no target for GO".


hash
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c  and  xlsym.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(hash <name> <table-size> )
	<name>		-	a symbol or string expression
	<table-size>	-	an integer expression 

DESCRIPTION

The HASH  function  computes  and  returns an integer  index for a given
symbol  <name>  and  a  given  size  of  hash  table  <table-size>.  The
intention  is for HASH to be used with  tables  made by  MAKE-ARRAY  and
accessed by AREF.

EXAMPLES

	(hash "zzzz" 1000)			; returns index 322
	(hash "ZZZZ" 1000)			; returns index 626
	(hash 'ZZZZ  1000)			; returns index 626

	(hash "hiho" 1000)			; returns index 519
	(hash 'hiho  1000)			; returns index 143
	(hash "abcd" 1000)			; returns index 72

	(defun lookin (sym) 			; create a function to 
	   (aref *obarray* 			;   look inside *OBARRAY*
	         (hash sym (length *obarray*))));   and look for a specific
						;   symbol - returns a list
	(lookin 'caar)				; returns the hash table entry
						;   (ZEROP CDDDDR CAAR HASH)

NOTE:
This is a useful function for creating and accessing tables.  It is also
useful for looking inside of XLISP's own symbol table *OBARRAY*.


if
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(if <test-expr>  <then-expr>   [ <else-expr> ]  )
	<test-expr>	-	an expression 
	<then-expr>	-	the THEN-CLAUSE, an expression
	<else-expr>	-	the ELSE-CLAUSE, an optional expression

DESCRIPTION

The IF special form evaluates the <test-expr>.  If <test-expr> evaluates
to a non-NIL  value, then  <then-expr>  is evaluated and returned as the
result.  If  <test-expr>  evaluates to NIL and there is an  <else-expr>,
then the  <else-expr> is evaluated and its result is returned.  If there
is no <else-expr> and <test-expr> evaluates to NIL, then NIL is returned
as a result.

EXAMPLES

	(if T (print "will print")		; prints  "will print"
	      (print "won't print"))		;

	(if NIL (print "won't print")		;
	        (print "will print"))		; prints  "will print"

	(if 'a T NIL)				; returns T
	(if NIL 'nope 'yep)			; returns YEP


int-char
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c 
Common LISP compatible: similar
versions: all machines

SYNTAX

(int-char <int> )
	<int>		-	an integer numeric expression

DESCRIPTION

The INT-CHAR function returns a character which is the result of turning
the <int> expression into a character.  If a <int> cannot be made into a
character, an error is signalled.  The range that <int> produces a valid
character is 0 through 255.

EXAMPLES

	(int-char 48)				; returns #\0
	(int-char 65)				; returns #\A
	(int-char 97)				; returns #\a
	(int-char 91)				; returns #\[
	(int-char 10)				; returns #\Newline
	(int-char 999)				; error - character code out of
						;	  range - 999

COMMON LISP COMPATABILITY:
Common LISP specifies that INT-CHAR should return a NIL when there is no
valid character for the integer value being passed in.  XLISP  generates
an error in these cases.  In some cases it is possible to substitue  the
CODE-CHAR function for INT-CHAR.

NOTE:
Unlike the CHAR-CODE and CHAR-INT functions,  CODE-CHAR and INT-CHAR are
not identical in use.  CODE-CHAR  accepts  0..127 for its range and then
produces NIL  results.  INT-CHAR  accepts  0..255 for its range and then
produces errors.


*integer-format*
________________________________________________________________________

type: system variable 
location: built-in
source file: xlprin.c
Common LISP compatible: no
supported on: all machines

SYNTAX

*integer-format*


DESCRIPTION

*INTEGER-FORMAT*  is a system variable that allows a user to specify how
integer   numbers   are  to  be   printed   by   XLISP.  The   value  of
*INTEGER-FORMAT*  should be set to one of the string  expressions "%ld",
"%lo" or  "%lx".  The  character  after  the  percent  character  is the
alphabetic   'ell'  character.  These  format  strings  are  similar  to
C-language floating point specifications.

		format		description
		---------------------------------------------------
		"%ld"		decimal
		"%lu"		unsigned decimal
		"%lo"		unsigned octal
		"%lx"		unsigned hexadecimal

The default value for *INTEGER-FORMAT* is the string "%ld".

EXAMPLES
	*integer-format*			; returns "%ld"

	(setq *integer-format* "%ld")		; signed decimal
	(print 1)				; prints 1
	(print 1234)				; prints 1234
	(print -1)				; prints -1
	(print -1234)				; prints -1234

	(setq *integer-format* "%lo")		; octal notation
	(print 1)				; prints 1
	(print 1234)				; prints 2322
	(print -1)				; prints 37777777777
	(print -1234)				; prints 37777775456

	(setq *integer-format* "%lx")		; hexadecimal notation
	(print 1)				; prints 1
	(print -1)				; prints ffffffff
	(print 1234)				; prints 4d2
	(print -1234)				; prints fffffb2e

	(setq *integer-format* "%u")		; unsigned decimal
	(print 1)				; prints 1
	(print 1234)				; prints 1234
	(print -1)				; prints 4294967295
	(print -1234)				; prints 4294966062

	(setq *integer-format* "hi")		; a bad notation
	(print 1)				; prints hi
	(print 9999)				; prints hi

	(setq *integer-format* "%ld")		; reset to original "%ld"

NOTE:
There can be other  characters  put in the string, but in general,  this
will not produce  particularly  desirable  behaviour.  There is no error
checking performed on the format string.


integerp
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(integerp <expr> )
	<expr>		-	the expression to check

DESCRIPTION

The INTEGERP  predicate  checks if an <expr> is a integer  number.  T is
returned if <expr> is a integer number, NIL is returned otherwise.

EXAMPLES

	(integerp 1)				; returns T - integer
	(integerp #x034)			; returns T - integer readmacro 
	(integerp '1)				; returns T - still an integer
	(setq a 14)				; 
	(integerp a)				; returns T - evaluates to int.
	(integerp 0)				; returns T - integer zero

	(integerp 1.2)				; returns NIL - float
	(integerp 0.0)				; returns NIL - float zero
	(integerp 'a)				; returns NIL - symbol
	(integerp #\a)				; returns NIL - character
	(integerp NIL)				; returns NIL - NIL
	(integerp #(0 1 2))			; returns NIL - array 


intern
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(intern <name-str> )
	<name-str>	-	a string expression

DESCRIPTION

The INTERN  function  takes a string name - <name-str> and creates a new
interned symbol.  What this means is that the symbol  <name-str> will be
placed  into  the  symbol  hash  table  *OBARRAY*.  It's  value  will be
unbound.  It's property list will be NIL (empty).  If the symbol already
exists,  no error or action  is taken and the old  values  and  property
lists  remain  intact.  The INTERN  function  returns  the symbol as its
result.

EXAMPLES

	(defun lookin (sym) 			; create a function to 
	   (aref *obarray* 			;   look inside *OBARRAY*
	         (hash sym (length *obarray*))));   and look for a specific
						;   symbol - returns a list

	(lookin "FINGERS")			; see if "FINGERS" is a symbol
						;   returns (:START1) - it isn't
	(intern "FINGERS")			; intern "FINGERS" as a symbol
						;   returns FINGERS
	(lookin "FINGERS")			; returns (FINGERS :START1) 
	(print fingers)				; error: unbound variable
						;   it exists, but has no value

	(lookin "TOES")				; returns NIL - doesn't exist
	toes					; error: unbound variable 
	(lookin "TOES")				; returns (TOES)
						;   the act of looking for a
						;   value or using a symbol
						;   causes it to be INTERNed

	(lookin "KNEECAPS")			; returns (MAX MAPLIST) - 
						;   KNEECAPS doesn't exist
	(setq kneecaps 'a-bone)			; create symbol with a value
	(lookin "KNEECAPS")			; returns (KNEECAPS MAX MAPLIST)

NOTE:
When you  INTERN a  symbol  like  "fingers",  this  gets  placed  in the
*OBARRAY*  symbol  table  as a lower  case  symbol.  Note  that  this is
different  from doing an INTERN on "FINGERS".  "fingers"  and  "FINGERS"
are two  different  symbols  in  *OBARRAY*.  Remember  also that  normal
symbols  created  by XLISP  are  upper  case  names.  So, an  intern  of
'fingers or  'FINGERS  are normal  symbols,  and will be the  upper-case
symbol FINGERS.

COMMON LISP COMPATABILITY:
Common LISP allows an optional package  specification,  which XLISP does
not support.


:isnew
________________________________________________________________________

type: message selector
location: built-in
source file: xlobj.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(send <object> :isnew <args> )
	<object>	-	an existing object
	<args>		-	the arguments to be passed to the init. code
(send <class> :isnew <ivars> [ <cvars> [ <superclass> ] ] )
	<class>		-	an existing XLISP class
	<ivars>		-	list of instance variables for new class
	<cvars>		-	list of class variable symbols for new class
	<superclass>	-	superclass for new object 
				(the default is 'OBJECT')

DESCRIPTION

The :ISNEW message selector causes an instance to run its initialization
method.  If an :ISNEW  message is sent to a class, the class  definition
and state will be reset as specified in the arguments of the message.

EXAMPLES
	(setq a-class 				; create a new class A-CLASS 
		(send class :new '(state)))	;        with STATE
	(send a-class :answer :isnew '()	; set up initialization
		'((setq state nil) self))	;
	(send a-class :answer :set-it '(value)	; create :SET-IT message
		'((setq state value)))		;
	(setq an-obj (send a-class :new))	; create AN-OBJ out of A-CLASS
	(send an-obj :show)			; returns object - STATE = NIL
	(send an-obj :set-it 5)			; STATE is set to 5
	(send an-obj :show)			; returns object - STATE = 5
	(SEND an-obj :ISNEW)			; re-initialize AN-OBJ
	(send an-obj :show)			; returns object - STATE = NIL

&key
________________________________________________________________________

type: keyword
location: built-in
source file: xleval.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

&key <key-arg> ...
&key ( <key-arg> [ <key-value> [ <exist-symbol> ] ] ) ...
&key ( ( <key-symbol> <key-arg> ) [ <key-value> [ <exist-symbol> ] ] ) ...
	<key-arg>	-	keyword argument
	<key-symbol>	-	keyword argument symbol
	<key-value>	-	keyword argument initialization
	<exist-symbol>	-	keyword argument existence symbol

DESCRIPTION

In XLISP, there are several times that you define a formal argument list
for a body of code (like DEFUN,  DEFMACRO,  :ANSWER and LAMBDA).  All of
the formal  arguments  that are  defined are  required  to appear in the
invocation  of the  defined  function  or  operation.  If there  are any
&OPTIONAL  arguments  defined,  they will be filled in order.  There are
other optional  arguments called KEYWORD arguments.  These arguments are
not position  dependent but can be specified in any order by a preceding
keyword  (a symbol  with a  leading  ':').  If there is no  <key-symbol>
specified in the argument list, the keyword will be constructed from the
<key-arg>  name by adding a leading  ':'.  (For  example a <key-arg>  of
FURTER will generate a keyword symbol of :FURTER).  

Like  the  &OPTIONAL  arguments,  there  can  be  initialization  values
provided  via the  <key-value>  argument.  If  there  is no  <key-value>
argument  and no value is provided by the function  call, the  <key-arg>
value will be NIL.

The  <exist-symbol>,  if  it  is  specified,  will  contain  a T if  the
<key-arg>  value was  supplied by the function  call and a NIL if it was
not  supplied  by the  function  call.  This  <exist-symbol>  allows the
programmer  to  test  for an  argument's  existence.  At the  end of the
function or operation  execution,  these local  symbols and their values
are are removed.

EXAMPLES

	(defun foo 				; define function FOO
	  (a &key b c )				;   with some optional args
	  (print a) (print b) (print c))	;
	(foo)					; error: too few arguments 
	(foo 1)					; prints 1 NIL NIL
	(foo 1 2)				; prints 1 NIL NIL
	(foo 1 :b 2 :c 3)			; prints 1 2 3 
	(foo 1 :c 3 :b 2)			; prints 1 2 3 
	(foo 1 :b 3 :b 2)			; prints 1 3 NIL

	(defun fee				; define function FEE
	  (a &key (b 9 b-passed) )		;   with some optional args
	  (print a) (print b)			;
	  (if b-passed (print "b was passed")	;
	               (print "b not passed")))	;
	(fee)					; error: too few arguments
	(fee 1)					; prints 1 9 "b not passed"
	(fee 1 2)				; prints 1 9 "b not passed"
	(fee 1 :b 2)				; prints 1 2 "b was passed"

	(defun fi				; define function FI
	  (a &key ((:mykey b) 9 b-passed) )	;   with some optional args
	  (print a) (print b)			;
	  (if b-passed (print "b was passed")	;
	               (print "b not passed")))	;
	(fi)					; error: too few arguments
	(fi 1)					; prints 1 9 "b not passed"
	(fi 1 2)				; prints 1 9 "b not passed"
	(fi 1 :b 2)				; prints 1 9 "b not passed"
	(fi 1 :mykey 2)				; prints 1 2 "b was passed"

NOTE:
There is a  &ALLOW-OTHER-KEYS  keyword in XLISP and Common LISP.  In the
case of XLISP, this keyword is extraneous  since the default for keyword
arguments is to allow other keys (without errors).


labels
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(labels  ( [ <function> ... ]  ) <expr> ... )
	<function>	-	a function definition binding which is of the 
				form  ( <symbol> <arg-list> <body> )
	<symbol>	-	the symbol specifying the function name
	<arg-list>	-	the argument list for the function 
	<body>		-	the body of the function
	<expr>		-	an expression

DESCRIPTION

The LABELS special form is basically a local block construct that allows
local  <function>  definitions  followed by a block of code to evaluate.
The first form after the labels is the  'binding'  form.  It  contains a
series of <functions>.  LABELS allows the <functions> to be defined in a
mutually recursive manner.  (The similar FLET form does not allow this.)
The  LABELS  form  will go  through  and  define  the  <symbol>s  of the
<functions>  and then  sequentially  execute the <expr>'s.  The value of
the last  <expr>  evaluated  is  returned.  When the LABELS is  finished
execution, the <symbol>'s that were defined will no longer exist.

EXAMPLES

	(labels ( (fozz (x) (+ x x) ))		; a LABELS with FOZZ local func.
	    (fozz 2))				; returns 4
						; FOZZ no longer exists
	(fozz 2)				; error: unbound function - FOZZ

						; an empty LABELS
	(labels () (print 'a))			; prints A
	
						; LABELS form including
	(labels ( (inc (arg) (est arg))		;   INC definition using EST
		  (est (var) (* .1 var)) )	;   EST definition
	   (inc 99) )				;   returns 9.9
						;
						; FLET form including
	(flet ( (inc (arg) (est arg))		;   INC definition using EST
		(est (var) (* .1 var)) )	;   EST definition
	   (inc 99)				; error: unbound function - EST

NOTE:
FLET  does not allow  recursive  definitions  of  functions.  The  LABEL
special form does allow this.


lambda
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(lambda <arg-list> [ <body> ] )
	<arg-list>	-	A list of the formal arguments to the function
				of the form:	( [ <arg1> ... ]
						  [ &optional <oarg1> ... ]
					  	  [ &rest <rarg> ]
						  [ &key ... ]
					  	  [ &aux <aux1> ... ] )
	<body>		-	A series of LISP forms (expressions) that
				are executed in order.  

DESCRIPTION

LAMBDA returns a function definition - an executable function - that has
no name.

All of the <argN>  formal  arguments  that are  defined are  required to
appear in a call to the  defined  function.  If there are any  &OPTIONAL
arguments  defined,  they will be filled  in order.  If there is a &REST
argument  defined, and all the required  formal  arguments and &OPTIONAL
arguments are filled, any and all further parameters will be passed into
the function  via the <rarg>  argument.  Note that there can be only one
<rarg> argument for &REST.  If there are insufficient parameters for any
of the  &OPTIONAL or &REST  arguments,  they will contain NIL.  The &AUX
variables  are a  mechanism  for you to  define  variables  local to the
function  definition.  At the end of the function execution, these local
symbols and their values are are removed.

EXAMPLES

	(funcall (lambda (a b) (* a b)) 4 8 )	; evaluate a lambda function
						;   returns 32
	(funcall (lambda '(a b) (+ a b)) 1 2)	; evaluate another 
						;   returns 3
	(funcall (lambda (a b) 			; evaluate a more complex one
		    (print "a no-name fnc") 	;   prints "a no-name fnc"
		    (* a b)) 3 8)		;   and returns 24

NOTE:
Using a SETQ on a LAMBDA  expression is not the same as a DEFUN.  A SETQ
on a LAMBDA  will give the  variable  the value of the  LAMBDA  closure.
This does not mean that the variable name can be used as a function.


last
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(last <list-expr> )
	<list-expr>	-	a list or list expression

DESCRIPTION

The LAST function  returns a list containing the last node or element of
a list.  If the last node is a sub-list, this is returned unaffected.

EXAMPLES

	(last NIL)				; returns NIL
	(last 'a)				; error: bad argument type
	(last '(A))				; returns (A)
	(last '(A B C D E))			; returns (E)
	(last '( A (B C) (D E (F))))		; returns ((D E (F)))
	
	(setq children '(junie vicki 		;
			 cindy chris))		;
	(last children)				; returns CHRIS


length
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(length <expr> )
	<expr>		-	a list expression or string expression 

DESCRIPTION

LENGTH returns the length of the <expr>.  If the <expr> is a string, the
number of  characters  is returned.  If the <expr> is a list, the number
of top level  elements  (atoms or sublists) is returned.  If the list is
NIL, a 0 is returned.

EXAMPLES

	(length NIL)				; returns 0
	(length 'a)				; error: bad argument type
	(length '(a))				; returns 1
	(length '(1 2 3 4 5 6))			; returns 6
	(length '(a (b c) (d (e) f) g))		; returns 4

	(length "12345")			; returns 5


let
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(let  ( [ <binding> ... ]  ) <expr> ... )
	<binding>	-	a variable binding which is of the form
				<symbol>     or    ( <symbol> <init-expr> )
	<symbol>	-	a symbol
	<init-expr>	-	an initialization expression for <symbol>
	<expr>		-	an expression

DESCRIPTION

The LET special form is basically a local block  construct that contains
symbols   (with   optional   initializations)   and  a  block   of  code
(expressions)  to  evaluate.  The  first  form  after  the  LET  is  the
'binding' form.  It contains a series of <symbol>'s or <binding>'s.  The
<binding>  is  a  <symbol>  followed  by  an  initialization  expression
<init-expr>.  If  there  is  no   <init-expr>,   the  <symbol>  will  be
initialized  to  NIL.  There  is no  specification  as to the  order  of
execution of the  bindings.  The LET form will go through and create and
initialize the symbols and then sequentially  execute the <expr>'s.  The
value  of the  last  <expr>  evaluated  is  returned.  When  the  LET is
finished  execution,  the  <symbol>'s  that were defined  will no longer
exist or retain their values.

EXAMPLES

	(let (x y z) 				; LET with local vars
	   (print x) (print y) (print z))	;  prints   NIL NIL NIL
	(let ((a 1) (b 2) (c 3))		; LET with local vars & init.
	  (print (+ a b c)))			;  prints and returns 6
	(let ( (a 1) (b 2) (c (+ a b)))		; LET with local vars & init.
	  (print (+ a b c)))			;  error: unbound variable - A
 						;  because (+ A B) init code
						;  depends on vars A and B
						;  which haven't been created
						;  yet - because of ordering


let*
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(let*  ( [ <binding> ... ]  ) <expr> ... )
	<binding>	-	a variable binding which is of the form
				<symbol>     or    ( <symbol> <init-expr> )
	<symbol>	-	a symbol
	<init-expr>	-	an initialization expression for <symbol>
	<expr>		-	an expression

DESCRIPTION

The LET* special form is basically a local block construct that contains
symbols   (with   optional   initializations)   and  a  block   of  code
(expressions)  to  evaluate.  The  first  form  after  the  LET*  is the
'binding' form.  It contains a series of <symbol>'s or <binding>'s.  The
<binding>  is  a  <symbol>  followed  by  an  initialization  expression
<init-expr>.  If  there  is  no   <init-expr>,   the  <symbol>  will  be
initialized  to NIL.  The  execution of the bindings will occur from the
first to the last binding.  The LET* form will go through and create and
initialize the symbols and then sequentially  execute the <expr>'s.  The
value  of the  last  <expr>  evaluated  is  returned.  When the  LET* is
finished  execution,  the  <symbol>'s  that were defined  will no longer
exist or retain their values.

EXAMPLES

	(let* (x y z) 				; LET* with local vars
	   (print x) (print y) (print z))	;  prints   NIL NIL NIL
	(let* ((a 1) (b 2) (c 3))		; LET* with local vars & init.
	  (print (+ a b c)))			;  prints and returns 6
	(let* ( (a 1) (b 2) (c (+ a b)))	; LET* with local vars & init.
	  (print (+ a b c)))			;  prints and returns 6
 						;  because (+ A B) init code
						;  depends on vars A and B
						;  which have been created -
						;  because of ordering of LET*


list
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(list [ <expr1> ... ])
	<exprN>		-	an expression

DESCRIPTION

The LIST function  takes the  expressions  and  constructs a list out of
them.  This constructed list is returned.

EXAMPLES

	(list)					; returns NIL
	(list NIL)				; returns (NIL)
	(list 'a)				; returns (A)
	(list 'a 'b)				; returns (A B)
	(list 'a 'b 'c)				; returns (A B C)
	(list 'a 'b NIL)			; returns (A B NIL)
	(list '(a b) '(c d) '( (e f) ))		; returns ((A B) (C D) ((E F)))
	(list (+ 1 2) (+ 3 4))			; returns (3 7)


listp
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(listp <expr> )
	<expr>		-	the expression to check

DESCRIPTION

The LISTP  predicate  checks if the <expr> is a list.  T is returned  if
<expr>  is a list or an empty  list  (the NIL  value),  NIL is  returned
otherwise.

EXAMPLES

	(listp '(a b))				; returns T - list
	(listp NIL)				; returns T - NIL
	(listp '(a . b))			; returns T - dotted pair list

	(listp (lambda (x) (print x)))		; returns NIL - closure - lambda
	(listp #(1 2 3))			; returns NIL - array
	(listp *standard-output*)		; returns NIL - stream
	(listp 1.2)				; returns NIL - float
	(listp #'quote)				; returns NIL - fsubr
	(listp 1)				; returns NIL - integer
	(listp object)				; returns NIL - object
	(listp "str")				; returns NIL - string
	(listp #'car)				; returns NIL - subr
	(listp 'a)				; returns NIL - symbol

NOTE:
NIL or '()  is  used  in  many  places  as a  list-class  or  atom-class
expression.  Both ATOM and LISTP, when applied to NIL, return T.  If you
wish to check for a non-empty list, use the CONSP predicate.


load
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlsys.c  and  xlread.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(load  <file>  [ :verbose <v-flag> ] [ :print <p-flag> ] ))
	<file>		-	a string expression or symbol 
	<v-flag>	-	an optional key-word expression - default is T
	<p-flag>	-	an optional key-word expression - default is NIL

DESCRIPTION

The LOAD function  opens the <file>, reads and  evaluates  all the forms
within the <file>.  <file> may be a string expression or a symbol.  When
<file>  is a  string,  you may  specify  a  complete  file  location  or
extensions (like  "/usr/local/bin/myfile.lsp" or "A:\LISP\TIM.LSP").  If
<file>  is a string  and  includes  a file  type or an  extension  (like
".lsp"),  then  LOAD  accesses  the  specified  file.  If  there  is  no
extension  on <file>, it will add  ".lsp".  If the  :VERBOSE  keyword is
present and  <v-flag>  is non-NIL, a load  message of the form ; loading
"xxxx.lsp" will be printed to  *STANDARD-OUTPUT*.  If the :PRINT keyword
is  present  and  <p-flag>  is  non-NIL,  the  resulting  value  of each
top-level  form in <file> will be printed to  *STANDARD-OUTPUT*.  If the
file load was successful, then T is returned as the result.  If the file
load was not successful, a NIL is returned.

EXAMPLES

	(load 'gloop)				; prints  ; loading "GLOOP.lsp"
						; returns NIL   there is no file

	(defun foo (x) (print x))		; create a function 
	(savefun foo)				; create a file FOO.lsp
	(load 'foo)				; prints  ; loading "FOO.lsp"
						; returns T
	(load 'foo :verbose NIL)		; no printing	returns T
	(load 'foo :print T)			; prints  FOO	returns T
	(load 'save :verbose T :print T)	; prints  ; loading "FOO.lsp"
						; prints  FOO	returns T
	(load "foo")				; prints  ; loading "foo.lsp"
						; returns NIL	didn't work
						; because the file is "FOO.lsp"
	(load "FOO")				; prints  ; loading "FOO.lsp"
						; returns T	did work
	(load "FOO.lsp")			; prints  ; loading "FOO.lsp"
						; returns T	did work

FILE NAMES:
In the PC and DOS world, all file names and extensions  ("FOO.BAT")  are
automatically made uppercase.  In using XLISP, this means you don't have
to  worry  about  whether  the  name  is  "foo.bat",  "FOO.BAT"  or even
"FoO.bAt" - they will all work.  However, in other file systems (UNIX in
particular),  uppercase and lowercase do make a difference.  So, in UNIX
if you do a (open 'foo-file :direction :output), this will create a file
named FOO-FILE  because XLISP uppercases its symbols.  If you do a (open
"foo-file" :direction :output), this will create a file named "foo-file"
because UNIX doesn't  uppercase  its file names.  Another case is if you
do (savefun  mydefun), this will create the file  "MYDEFUN.lsp".  So, if
you are having  trouble with opening and accessing  files, check to make
sure the file name is in the proper case.

COMMON LISP COMPATABILITY:
Common LISP has a LOAD  function  that is similar to XLISP's  LOAD.  The
only difference is that Common LISP uses an optional  keyword  parameter
:IF-DOES-NOT-EXIST which XLISP does not support.

NOTE:
In XLISP, the keyword  parameters are order sensitive.  If both :VERBOSE
and :PRINT keywords are used, :VERBOSE must come first.

KEYSTROKE EQUIVALENT:
In the  Macintosh  version of XLISP, a COMMAND-l  brings up a dialog box
for loading a file.  COMMAND-n operates  similarly, except that the load
is  done  with  :VERBOSE  and  :PRINT  flags  set.  These  can  also  be
accomplished by a pull-down menu selection.



logand
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(logand <expr1> ... )
	<exprN>		-	an integer expression

DESCRIPTION

The LOGAND  function  returns the logical  (bitwise)  AND of the list of
expressions.  If there is only one  argument, it is returned  unaltered.
If there are two or more  arguments,  the LOGAND  function  performs the
logical and operation successively applying the bitwise operation.

EXAMPLES

	(logand 0 0)				; returns 0
	(logand 0 1)				; returns 0
	(logand 1 0)				; returns 0
	(logand 1 1)				; returns 1
 	(logand 55 #x0F)			; returns 7
	(logand 7 #b0011)			; returns 3
	(logand 1 2 4 8 16)			; returns 0
	(logand 15 7 3)				; returns 3

NOTE:
XLISP does not check when read-macro  expansions (like #x0FF) are out of
bounds.  It gives no error  message and will just truncate the number to
the  low-order  bits  that it can deal  with  (usually  32 bits or 8 hex
digits).


logior
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(logior <expr1> ... )
	<exprN>		-	an integer expression

DESCRIPTION

The LOGIOR function  returns the logical  (bitwise)  INCLUSIVE-OR of the
list of  expressions.  If there is only  one  argument,  it is  returned
unaltered.  If there  are two or more  arguments,  the  LOGIOR  function
performs the inclusive-or successively applying the bitwise operation.

EXAMPLES

	(logior 0 0)				; returns 0
	(logior 0 1)				; returns 1
	(logior 1 0)				; returns 1
	(logior 1 1)				; returns 1
	 
	(logior 1 2 4 8 16 32 64)		; returns 127
	(logior 5 #b010)			; returns 7
	(logior 99 #x1FF)			; returns 511
	(logior 99 #x400)			; returns 1123

NOTE:
XLISP does not check when read-macro  expansions (like #x0FF) are out of
bounds.  It gives no error  message and will just truncate the number to
the  low-order  bits  that it can deal  with  (usually  32 bits or 8 hex
digits).


lognot
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(lognot  <expr> )
	<expr>		-	an integer expression

DESCRIPTION

The LOGNOT  function  returns the  logical  (bitwise)  INVERSION  of the
expression.

EXAMPLES

	(lognot 255)				; returns -256
	(lognot #xffff0000)			; returns 65535
	(lognot #x00000000)			; returns -1
	(lognot 1)				; returns -2

	(logand (lognot 256) 65535)		; returns 65279
	(lognot #xFFFFFFFE)			; returns 1
	(lognot #xFFFFFFFC)			; returns 3

NOTE:
XLISP does not check when read-macro  expansions (like #x0FF) are out of
bounds.  It gives no error  message and will just truncate the number to
the  low-order  bits  that it can deal  with  (usually  32 bits or 8 hex
digits).


logxor
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(logxor  <expr1> ... )
	<exprN>		-	an integer expression

DESCRIPTION

The LOGXOR function  returns the logical  (bitwise)  EXCLUSIVE-OR of the
list of  expressions.  If there is only  one  argument,  it is  returned
unaltered.  If there  are two or more  arguments,  the  LOGXOR  function
performs the exclusive-or successively applying the bitwise operation.

EXAMPLES

	(logxor 0 0)				; returns 0
	(logxor 0 1)				; returns 1
	(logxor 1 0)				; returns 1
	(logxor 1 1)				; returns 0
	(logxor #b0011 #b0101)			; returns 6 
 	(logxor 255 #xF0)			; returns 15
	(logxor 255 #x0F)			; returns 240
	(logxor 255 (logxor 255 99))		; returns 99

NOTE:
XLISP does not check when read-macro  expansions (like #x0FF) are out of
bounds.  It gives no error  message and will just truncate the number to
the  low-order  bits  that it can deal  with  (usually  32 bits or 8 hex
digits).


loop
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(loop  <body> ...  )
	<body>		-	a series of expressions

DESCRIPTION

The LOOP  special  form  specifies  a  'repeat-forever'  construct.  The
expressions  in <body> will be evaluated.  When the last  expression  is
evaluated in <body>, LOOP will then repeat the <body>.  When a RETURN is
evaluated  within a LOOP, the  specified  value will be  returned.  LOOP
itself does not generate a return value.  Other exit mechanisms  include
GO, THROW, RETURN-FROM and errors.

EXAMPLES

	(setq i 65)				; initial value
	(loop					; LOOP
		(princ (int-char i) )		;   print the character
		(if (= i 90) (return "done"))	;   test for limit
		(setq i (1+ i) ) )		;   increment and repeat
						; prints
						;   ABCDEFGHIJKLMNOPQRSTUVWXYZ
						; returns "done"

NOTE:
If you create a LOOP with no exit  mechanism,  you will probably have to
abort your XLISP session.


lower-case-p
________________________________________________________________________

type: predicate function (subr) 
location: built-in
source file: xlstr.c 
Common LISP compatible: yes
versions: all machines

SYNTAX

(lower-case-p <char> )
	<char>		-	a character expression

DESCRIPTION

The LOWER-CASE-P  predicate  checks if the <char>  expression is a lower
case  character.  If <char> is lower case a T is  returned,  otherwise a
NIL is returned.  Lower case characters are 'a' (ASCII decimal value 97)
through 'z' (ASCII decimal value 122).

EXAMPLES

	(lower-case-p #\a)			; returns T
	(lower-case-p #\A)			; returns NIL
	(lower-case-p #\1)			; returns NIL
	(lower-case-p #\[)			; returns NIL


macroexpand
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(macroexpand <form> )
	<form>		-	a macro form

DESCRIPTION

The  MACROEXPAND  function  takes a <form> and  recursively  expands the
macro   definitions  used  in  the  <form>.  The  function  returns  the
expansion.  If the <form> does not contain a macro, the form is returned
unaltered.

EXAMPLES

	(defmacro plus (n1 n2) `(+ ,n1 ,n2))	; define PLUS macro
	(plus 1 2)				; returns 3
	(macroexpand '(plus 3 4))		; returns (+ 3 4)

	(defmacro pl (p1 p2) `(plus ,p1 ,p2))	; define PL macro using PLUS
	(pl 3 4)				; returns 7
	(macroexpand '(pl 3 4))			; returns (+ 3 4)
	(macroexpand-1 '(pl 3 4))		; returns (PLUS 3 4)

COMMON LISP COMPATABILITY:
Common  LISP  returns  2 values  for its  result  of  MACROEXPAND  - the
expanded  form and a T or NIL value that  indicates  if the <form> was a
macro.  XLISP returns only the expanded form.

COMMON LISP COMPATABILITY:
Common  LISP  supports  an  optional  argument  in  MACROEXPAND  for the
environment  of the  expansion.  XLISP does not  support  this  optional
argument.


macroexpand-1
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(macroexpand-1 <form> )
	<form>		-	a macro form

DESCRIPTION

The MACROEXPAND-1 function takes a <form> and expands the first level of
the macro  definition  used in the  <form>.  The  function  returns  the
expansion.  If the <form> does not contain a macro, the form is returned
unaltered.

EXAMPLES

	(defmacro plus (n1 n2) `(+ ,n1 ,n2))	; define PLUS macro
	(plus 1 2)				; returns 3
	(macroexpand '(plus 3 4))		; returns (+ 3 4)
	(macroexpand-1 '(plus 3 4))		; returns (+ 3 4)

	(defmacro pl (p1 p2) `(plus ,p1 ,p2))	; define PL macro using PLUS
	(pl 3 4)				; returns 7
	(macroexpand '(pl 3 4))			; returns (+ 3 4)
	(macroexpand-1 '(pl 3 4))		; returns (PLUS 3 4)

COMMON LISP COMPATABILITY:
Common  LISP  returns 2 values  for its  result of  MACROEXPAND-1  - the
expanded  form and a T or NIL value that  indicates  if the <form> was a
macro.  XLISP returns only the expanded form.

COMMON LISP COMPATABILITY:
Common LISP  supports an  optional  argument  in  MACROEXPAND-1  for the
environment  of the  expansion.  XLISP does not  support  this  optional
argument.


macrolet
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(macrolet  ( [ <macro> ... ]  ) <expr> ... )
	<macro>		-	a macro definition binding which is of the 
				form  ( <symbol> <arg-list> <body> )
	<symbol>	-	the symbol specifying the function name
	<arg-list>	-	the argument list for the function 
	<body>		-	the body of the function
	<expr>		-	an expression

DESCRIPTION

The  MACROLET  special  form is basically a local block  construct  that
allows  local  <macro>  definitions  followed  by a  block  of  code  to
evaluate.  The first form after the macrolet is the 'binding'  form.  It
contains  a series of  <macro>s.  The  MACROLET  form will  sequentially
execute the <expr>'s after defining the <macro>s.  The value of the last
<expr> evaluated is returned.  When the MACROLET is finished  execution,
the <symbol>'s that were defined will no longer exist.

EXAMPLES

						; a MACROLET form including
	(macrolet ((pls (n1 n2) `(+ ,n1 ,n2)))	;  PLS macro
	  (pls 4 5))				;  returns 9
						; the PLS macro no longer exists
	(pls 4 5)				; error: unbound function - PLS

						; an empty MACROLET
	(macrolet () (print 'a))		; prints A


make-array
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(make-array <size> )
	<size>		-	the size (integer) of the array to be created

DESCRIPTION

MAKE-ARRAY creates an array of the specified size and returns the array.
Array  elements  may be any valid  lisp data type -  including  lists or
arrays.  Arrays  made by  MAKE-ARRAY  and  accessed  by AREF are base 0.
This means the first  element is  accessed  by element  number 0 and the
last  element is  accessed  by element  number n-1 (where n is the array
size).  Array elements are initialized to NIL.

EXAMPLES
	(setq my-array (make-array 16))		; make the array
	(aref my-array 0)			; return 0th (first) element
	(aref my-array 15)			; return 15th (last) element
	(aref my-array 16)			; error: non existant element
	(dotimes (i 16) 			; set each element to its index
		 (setf (aref my-array i) i))	;     by the setf function

	(setq new (make-array 4))		; make another array
	(setf (aref new 0) (make-array 4))	; make new[0] an array of 4
	(setf (aref (aref new 0) 1) 'a)		; set new[0,1] = 'a
	(setf (aref new 2) '(a b c))		; set new[2] = '(a b c)
	my-array				; look at array

READ MACRO:
There is a built-in  read-macro  for arrays - # (the hash symbol).  This
allows you to create  arbitrary arrays with initial values without going
through a  MAKE-ARRAY  function.  There is also the VECTOR  function  to
create initialized arrays.  For example:

	(aref #(0 1 2) 1)			; returns 1

COMMON LISP COMPATABILITY:
XLISP  only  supports   one-dimensional  arrays.  Common  LISP  supports
multi-dimension  arrays.  Common  LISP  also  supports  various  keyword
parameters that are not supported in XLISP.


make-string-input-stream
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(make-string-input-stream <string> [ <start-pos> [ <end-pos> ] ] )
	<string>	-	a string expression
	<start-pos>	-	an optional numeric expression, default value
				is 0 (giving the first character of the string)
	<end-pos>	-	an optional numeric expression, default value
				is the length of the string

DESCRIPTION

The MAKE-STRING-INPUT-STREAM function creates an unnamed stream from the
<string>  expression.  The stream  can then be used as any other  stream
object.  The optional  <start-pos>  expression  specifies  the  starting
offset of the <string>  expression.  A <start-pos>  of 0 will start with
the  beginning  of  the  <string>.  The  optional  <end-pos>  expression
specifies the ending offset of the <string>  expression.  A <end-pos> of
4 will  make  the  fourth  character  the  last  in the  stream.  If the
function is  successful,  it returns the unnamed stream  object.  If the
string is empty, an unnamed stream is still returned.  Error  conditions
include <start-pos> and <end-pos> being out of bounds.

EXAMPLES

	(make-string-input-stream "abcdefgh")	; returns #<Unnamed-Stream: #277e2>
	(read (make-string-input-stream 	;
	         "123456"))			; returns 123456
	(read (make-string-input-stream 	;
	         "123456" 1))			; returns 23456
	(read (make-string-input-stream 	;
	         "123456" 1 3))			; returns 23

	(read (make-string-input-stream 	;
	         "123" 0))			; returns 123
	(read (make-string-input-stream 	;
	         "123" 0 3))			; returns 123
	(read (make-string-input-stream 	;
	         "123" 2 1))			; returns NIL
	(read (make-string-input-stream 	;
	         "123" 0 4))			; error: string index out of 
		 				;        bounds - 4


make-string-output-stream
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(make-string-output-stream)


DESCRIPTION

The  MAKE-STRING-OUTPUT-STREAM  function  creates and returns an unnamed
output stream.  The stream can then be used as any other stream  object.


EXAMPLES

	(make-string-output-stream)		; returns #<Unnamed-Stream: #2d9c0>
	(setq out (make-string-output-stream))	; returns #<Unnamed-Stream: #2d95c>
	(format out "fee fi fo fum ")		; \
	(format out "I smell the blood of ")	;  fill up output stream
	(format out "Elmer Fudd")		; /
	(get-output-stream-string out)		; returns 
						;	"fee fi fo fum I smell
						;       the blood of Elmer Fudd"
	(format out "~%now what")		; add more to output stream
	(get-output-stream-string out)		; returns "\nnow what"
	(format out "hello")			; add more to output stream
	(read out)				; returns HELLO


make-symbol
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(make-symbol <symbol-str> )
	<symbol-str>	-	a string expression

DESCRIPTION

The MAKE-SYMBOL  function takes a string name - <symbol-str> and creates
a new symbol.  This symbol is  temporary  and is not  interned  (placed)
into the symbol hash table  *OBARRAY*.  If the symbol already exists, no
error or action is taken and the old values and  property  lists  remain
intact.  The MAKE-SYMBOL function returns the symbol as its result.

EXAMPLES

	(defun lookin (sym) 			; create a function to 
	   (aref *obarray* 			;   look inside *OBARRAY*
	         (hash sym (length *obarray*))));   and look for a specific
						;   symbol - returns a list

	(lookin "FEE")				; returns (CHAR-INT NTH ++) 
						;   FEE symbol doesn't exist
	(MAKE-SYMBOL "FEE")			; returns FEE symbol
	(lookin "FEE")				; returns (CHAR-INT NTH ++) 
						;   FEE still doesn't exist
	(intern "FEE")				; intern FEE symbol
	(lookin "FEE")				; returns (FEE CHAR-INT NTH ++) 
						;   FEE does now exist

NOTE:
When you  MAKE-SYMBOL  a symbol  like  "fingers",  this is a lower  case
symbol.  Note  that  this  is  different  from  doing a  MAKE-SYMBOL  on
"FINGERS".  "fingers" and "FINGERS" are two different symbols.  Remember
also that normal symbols created by XLISP are upper case names.


makunbound
________________________________________________________________________

type: defined function (closure)
location: extension
source file: init.lsp
Common LISP compatible: yes
supported on: all machines

SYNTAX

(makunbound  <symbol> )
	<symbol>	-	an expression evaluating to a symbol

DESCRIPTION

The  MAKUNBOUND  function makes a symbol's value  unbound.  The <symbol>
must be a valid  symbol,  but it does  not  need  to have a  value.  The
MAKUNBOUND function returns the symbol as its result.

EXAMPLES

	(makunbound 'florp)			; returns FLORP
	(setq myvar "hi")			; setup MYVAR "hi"
	myvar					; returns "hi"
	(makunbound 'myvar)			; returns MYVAR
	myvar					; error: unbound variable

NOTE:
MAKUNBOUND is not misspelled - there is no 'e' in it.

NOTE:
The  FMAKUNBOUND  works on  functions  (closures)  in the same way  that
MAKUNBOUND  works on variables.  Be sure to use the correct one for what
you are unbinding.  These  functions do not generate an error if you try
to unbind the wrong  type.  This is because of the  definition  of these
functions  and the fact that the function and  variable  name spaces are
separate.  You can have both a function called FOO and a variable called
FOO.

NOTE:
The function MAKUNBOUND is created in the INIT.LSP file.  If it does not
exist in your XLISP system, you might be having a problem with INIT.LSP.
Before you start XLISP, look in the directory you are currently  in, and
check to see if there is an INIT.LSP.


mapc
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(mapc <function> <list1> [ <list2> ... ] )
	<function>	-	a function definition (like a LAMBDA) 
				or a function name
	<listN>		-	a list or list expression

DESCRIPTION

MAPC applies the  <function> to the succesive  CARs of each of the lists
<listN>.  Each of the lists supplies one of the arguments to <function>.
The MAPC  function  returns a list that is  equivalent to the first list
<list1>.  It's purpose is to perform operations that have  side-effects.
If the lists are of different  lengths, the shortest list will determine
the number of applications of <function>.

EXAMPLES

	(mapc 'princ '(hi there bob))		; prints HITHEREBOB
						;   returns (HI THERE BOB)

	(mapc '+ '(1 2 3) '(1 2 3))		; returns (1 2 3)
						;   there were no side effects

	(mapc (lambda (x y) (print (+ x y)))	; define fun. with side effects
	      '(1 2 3) '(1 2 3))		;   prints 2 4 6 
						;   returns (1 2 3)

NOTE:
The use of the <function>  will work properly when it is a quoted symbol
(which is the name of the function), an unquoted  symbol (whose value is
a function) or a closure object (like a LAMBDA).


mapcan
________________________________________________________________________

type: defined macro (closure)
location: extension
source file: init.lsp
Common LISP compatible: yes
supported on: all machines

SYNTAX

(mapcan <function> <list1> [ <list2> ... ] )
	<function>	-	a function definition (like a LAMBDA) 
				or a function name
	<listN>		-	a list or list expression

DESCRIPTION

MAPCAN applies the <function> to the succesive CARs of each of the lists
<listN>.  Each of the lists supplies one of the arguments to <function>.
MAPCAN is similar to MAPCAR, except that the MAPCAN macro returns a list
that is constructed via the destructive  NCONC function from the results
of the <function>  applications.  If the lists are of different lengths,
the  shortest  list  will  determine  the  number  of  applications   of
<function>.

EXAMPLES

	(mapcar 'list '(1 2 3) '(a b c) )	; returns ((1 A) (2 B) (3 C))
	(mapcan 'list '(1 2 3) '(a b c) )	; returns (1 A 2 B 3 C)
	(mapcan 'list '(a b c) 			; different length lists
		   '(1 2 3 4 5 6))		;   returns (A 1 B 2 C 3)

NOTE:
Remember that MAPCAN uses NCONC and so it deals with its list  arguments
destructively.  It is often  used when you want to  remove  NIL  entries
from the resulting list - because NCONC will take out the NILs.

NOTE:
The use of the <function>  will work properly when it is a quoted symbol
(which is the name of the function), an unquoted  symbol (whose value is
a function) or a closure object (like a LAMBDA).

NOTE:
The macros MAPCAN and MAPCON are created in the INIT.LSP  file.  If they
do not exist in your XLISP  system,  you might be having a problem  with
INIT.LSP.  Before  you  start  XLISP,  look  in the  directory  you  are
currently in, and check to see if there is an INIT.LSP.


mapcar
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(mapcar <function> <list1> [ <list2> ... ] )
	<function>	-	a function definition (like a LAMBDA) 
				or a function name
	<listN>		-	a list or list expression

DESCRIPTION

MAPCAR applies the <function> to the succesive CARs of each of the lists
<listN>.  Each of the lists supplies one of the arguments to <function>.
The MAPCAR function  returns a list that is constructed from the results
of the <function>  applications.  If the lists are of different lengths,
the  shortest  list  will  determine  the  number  of  applications   of
<function>.

EXAMPLES

	(mapcar '+ '(1 2 3) '(1 2 3))		; returns (2 4 6)
	(mapcar 'princ '(1 2 3))		; prints 123
						;   returns (1 2 3)
	(mapcar '+ '(1 2 3) 			; different length lists
		   '(1 2 3 4 5 6))		;   returns (2 4 6)

NOTE:
The use of the <function>  will work properly when it is a quoted symbol
(which is the name of the function), an unquoted  symbol (whose value is
a function) or a closure object (like a LAMBDA).


mapcon
________________________________________________________________________

type: defined macro (closure)
location: extension
source file: init.lsp
Common LISP compatible: yes
supported on: all machines

SYNTAX

(mapcon <function> <list1> [ <list2> ... ] )
	<function>	-	a function definition (like a LAMBDA) 
				or a function name
	<listN>		-	a list or list expression

DESCRIPTION

MAPCON  applies the  <function>  to the  successive  CDRs of each of the
lists  <listN>.  Each of the  lists  supplies  one of the  arguments  to
<function>.  The MAPCON macro is similar to the MAPLIST function, except
that MAPCON returns a list that is constructed via the destructive NCONC
function from the results of the <function>  applications.  If the lists
are of different lengths, the shortest list will determine the number of
applications of <function>.

EXAMPLES

	(maplist 'list '(a b))			; returns (((A B)) ((B)))
	(mapcon  'list '(a b))			; returns ((A B) (B))

NOTE:
Remember that MAPCON uses NCONC and so it  destructively  deals with its
list arguments.

NOTE:
The use of the <function>  will work properly when it is a quoted symbol
(which is the name of the function), an unquoted  symbol (whose value is
a function) or a closure object (like a LAMBDA).

NOTE:
The macros MAPCAN and MAPCON are created in the INIT.LSP  file.  If they
do not exist in your XLISP  system,  you might be having a problem  with
INIT.LSP.  Before  you  start  XLISP,  look  in the  directory  you  are
currently in, and check to see if there is an INIT.LSP.


mapl
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(mapl <function> <list1> [ <list2> ... ] )
	<function>	-	a function definition (like a LAMBDA) 
				or a function name
	<listN>		-	a list or list expression

DESCRIPTION

MAPL applies the <function> to the successive  CDRs of each of the lists
<listN>.  Each of the lists supplies one of the arguments to <function>.
The MAPL  function  returns a list that is  equivalent to the first list
<list1>.  It's purpose is to perform operations that have  side-effects.
If the lists are of different  lengths, the shortest list will determine
the number of applications of <function>.

EXAMPLES

	(mapl 'print '(a b c))			; prints (A B C)
						;        (B C)
						;        (C)
						; returns (A B C)

	(mapl (lambda (x y) (princ x) (princ y)	; apply lambda fun. to list
			    (terpri))		;
	      '(a b c) '(1 2 3))		; prints (A B C)(1 2 3)
						;        (B C)(2 3)
						;        (C)(3)
						; returns (A B C)

NOTE:
The use of the <function>  will work properly when it is a quoted symbol
(which is the name of the function), an unquoted  symbol (whose value is
a function) or a closure object (like a LAMBDA).


maplist
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(maplist <function> <list1> [ <list2> ... ] )
	<function>	-	a function definition (like a LAMBDA) 
				or a function name
	<listN>		-	a list or list expression

DESCRIPTION

MAPLIST  applies the  <function> to the  successive  CDRs of each of the
lists  <listN>.  Each of the  lists  supplies  one of the  arguments  to
<function>.  The  MAPLIST  function  returns a list that is  constructed
from the  results of the  <function>  applications.  If the lists are of
different  lengths,  the  shortest  list will  determine  the  number of
applications of <function>.

EXAMPLES

	(maplist 'print '(a b c))		; prints (A B C)
						;        (B C)
						;        (C)
						; returns ((A B C) (B C) (C))

	(maplist (lambda (x y) 			; append the lists into one	
		     (length (append x y)))	;   list and find it's length
		 '(a b c d) '(1 2 3 4))		; returns (8 6 4 2)

NOTE:
The use of the <function>  will work properly when it is a quoted symbol
(which is the name of the function), an unquoted  symbol (whose value is
a function) or a closure object (like a LAMBDA).


max
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(max <expr1> ... )
	<exprN>		-	integer or floating point number/expression

DESCRIPTION

The MAX function returns the largest numeric expression from the list of
arguments.

EXAMPLES

	(max 1)					; returns 1
	(max 1 -5 9)				; returns 9

	(setq a '( 9 3 5 2))			; set up a list - (9 3 5 2)
	(apply 'max a)				; returns 9
	(apply #'max a)				; returns 9
	(apply 'min a)				; returns 2


member
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(member <expr> <list-expr> [ { :test | :test-not } <test> ] )
	<expr>		-	the expression to find - an atom or list
	<list-expr>	-	the list to search
	<test>		-	optional test function (default is EQL)

DESCRIPTION

MEMBER  searches  through  <list-expr>  for  <expr>.  If  found,  MEMBER
returns the  remainder  of the  <list-expr>  starting  with  <expr>.  If
<expr> is not found, a NIL is  returned.  You may specify  your own test
with the :TEST and :TEST-NOT  keywords followed by the test you which to
perform.

EXAMPLES

	(member 'a '(1 2 3 4))			; returns NIL
	(member '2 '(1 2 3 4))			; returns (2 3 4)

	(setq mylist '(2 4 8 16 32 64 128 256))	; make a numeric list
	(member 6 mylist :test '<)		; returns (8 16 32 64 128 256)
	(member 6 (reverse mylist) :test-not '<); returns (4 2)
	(member '20 '(60 40 20 10) :test '> )	; returns (10)

	(member '(a) '((see) (a) (cat)) 	; returns ((A) (CAT))
		      :test 'equal)		;   note EQUAL as test
	(member "hi" '("a" "hi" "c") 		; returns ("hi" "c")
		:test 'string= )		;   note STRING= as test


NOTE:
The  MEMBER  function  can work  with a list or  string  as the  <expr>.
However, the default EQL test does not work with lists or strings,  only
symbols  and  numbers.  To make  this  work,  you need to use the  :TEST
keyword along with EQUAL for <test>.

COMMON LISP COMPATABILITY:
Common  LISP  supports  the use of the :KEY  keyword  which  specifies a
function  that is applied to each  element of  <list-expr>  before it is
tested.  XLISP does not support this.



:mescape
________________________________________________________________________

type: keyword
location: built-in
source file: xlread.c
Common LISP compatible: no
supported on: all machines

SYNTAX

:mescape


DESCRIPTION

:MESCAPE is an entry that is used in the  *READTABLE*.  *READTABLE* is a
system  variable that contains  XLISP's data structures  relating to the
processing  of  characters  from  the  user (or  files)  and  read-macro
expansions.  The  existance  of the  :MESCAPE  keyword  means  that  the
specified  character is to be used as a multiple escape  character.  The
system  defines  that  the the  vertical  bar  character  | is the  only
:MESCAPE character.

EXAMPLES

	(defun look-at (table)			; define a function to 
	 (dotimes (ch 127)			;   look in a table
	  (prog ( (entry (aref table ch)) )	;   and print out any	  
	    (case entry 			;   entries with a function
	      (:MESCAPE 			;
	          (princ (int-char ch)))	;
	      (T	    NIL))))		;
	 (terpri))				;
	(look-at *readtable*)			;  prints  | 

CAUTION:
If you experiment  with  *READTABLE*, it is useful to save the old value
in a variable, so that you can restore the system state.


min
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(min <expr1> ... )
	<exprN>		-	integer or floating point number/expression

DESCRIPTION

The MIN  function  returns the  minimum  (most  negative or most  nearly
negative) numeric expression from the list of arguments.

EXAMPLES

	(min 1)					; returns 1
	(min 8 7 4 2)				; returns 2
	(min 2 3 -1 -99)			; returns -99
	(setq a '( 9 3 5 2))			; make a numeric list - (9 3 5 2)
	(apply 'min a)				; returns 2
	(apply #'min a)				; returns 2
	(apply 'max a)				; returns 9


minusp
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(minusp <expr> )
	<expr>		-	the numeric expression to check

DESCRIPTION

The MINUSP predicate  checks to see if the number <expr> is negative.  T
is returned if the number is negative  (less than zero), NIL is returned
otherwise.  A bad argument  type error is generated if the <expr> is not
a numeric expression.

EXAMPLES

	(minusp 1)				; returns NIL
	(minusp 0)				; returns NIL
	(minusp -1)				; returns T
	(minusp -.000000005)			; returns T
	(minusp #xFFFFFFFF)			; returns T
	(minusp #x01)				; returns NIL

	(minusp 'a)				; error: bad argument type
	(setq a -3.5)				; set A to -3.5
	(minusp a)				; returns T


nconc
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(nconc [ <list1> ... ] )
	<listN>		-	a list to DESTRUCTIVELY concatenate

DESCRIPTION

NCONC  destructively  concatenates  a sequence of lists and returns  the
result of this concatentation.  The destructive aspect of this operation
means  that the  actual  symbol  values  are used in the  list-modifying
operations  - not  copies.  This  means, for  NCONC,  that the lists are
spliced  together.  <listN> must  evaluate to a valid list.  An atom for
<listN> will result in an error.  NIL is a valid <listN>.

EXAMPLES

	(setq a '(1 2 3))			; set up A with (1 2 3)
	(setq b '(4 5 6))			; set up B with (4 5 6)
	(setq c '(7 8 9))			; set up C with (7 8 9)
	(NCONC a b c)				; returns (1 2 3 4 5 6 7 8 9)
	(setf (nth 8 a) 'end)			; change last element of A
	(print a)				; prints (1 2 3 4 5 6 7 8 END)
	(print b)				; prints (4 5 6 7 8 END)
	(print c)				; prints (7 8 END)


:new
________________________________________________________________________

type: message selector
location: built-in
source file: xlobj.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(send <class> :new <args> )
	<class>		-	an existing XLISP class except for 'CLASS'
	<args>		-	the init. args for the new instance 
(send class :new <ivars> [ <cvars> [ <superclass> ] ] )
	<ivars>		-	list of instance variables for new class
	<cvars>		-	list of class variable symbols for new class
	<superclass>	-	superclass for new object 
				(the default is 'OBJECT')

DESCRIPTION

The :NEW message selector exhibits 2 different  behaviors.  When you are
creating  an  instance  of a  class  you  only  need  the  :NEW  message
(consisting  of the  message  selector  and  any  data).  When  you  are
creating a new class with :NEW, you need to specify  instance  variables
and optionally the class variables and superclass.

EXAMPLES
	(setq new-class 			; create NEW-CLASS with STATE
		(send class :new '(state)))	;
	(setq new-obj (send new-class :new))	; create NEW-OBJ of NEW-CLASS
	(send new-obj :show)			; shows the object
	(setq sub-class 			; create SUB-CLASS of NEW-CLASS
		(send class :new '(sub-state) 	;
				 '() new-class));
	(send sub-class :show)			; show the SUB-CLASS

nil
________________________________________________________________________

type: system constant
location: built-in
source file: xlsym.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

nil

DESCRIPTION

The NIL  constant  represents  the empty  list or the  false  value - as
oppossed  to the true value (the  symbol T).  NIL can be writen as the 3
character symbol NIL or as the empty list ().

EXAMPLES
	(setq myvar NIL)			; set MYVAR to False
	(setq myvar 'NIL)			; NIL and 'NIL evaluate to NIL	
	(setq myvar ())				; () is the empty list = NIL
	(setq myvar '())			; () and '() evaluate to NIL
	(if nil (print "this won't print")	; if/then/else
	        (print "this will print"))

NOTE:
You can not change the value of NIL.


:nmacro
________________________________________________________________________

type: keyword
location: built-in
source file: xlread.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(:nmacro  .  <function> )
	<function>	-	a function

DESCRIPTION

:NMACRO is an entry that is used in the  *READTABLE*.  *READTABLE*  is a
system  variable that contains  XLISP's data structures  relating to the
processing  of  characters  from  the  user (or  files)  and  read-macro
expansions.  The  existance  of  the  :NMACRO  keyword  means  that  the
specified character is the start of a non-terminal  macro.  For :NMACRO,
the form of the  *READTABLE*  entry is a dotted  pair  like  (:NMACRO  .
<function> ).  The <function> can be a built-in read-macro function or a
user defined lambda expression.  The <function> takes two parameters, an
input stream  specification, and an integer that is the character value.
The <function>  should return NIL if the character is 'white-space' or a
value CONSed with NIL to return the value.  The <function> will probably
read additional characters from the input stream.

EXAMPLES

	(defun look-at (table)			; define a function to 
	 (dotimes (ch 127)			;   look in a table
	  (prog ( (entry (aref table ch)) )	;   and print out any	  
	        (if (and (consp entry)		;   :NMACRO entries
	                 (equal (car entry) 	;
			        ':NMACRO))	;
	          (princ (int-char ch)))))	;
	 (terpri))				;
	 					;
	(look-at *readtable*)			;  prints  #

NOTE:
The system defines that the hash (#) character is a  non-terminal.  This
is because  the hash is used for a variety  of 'read  macro  expansions'
including FUNCTION, an ASCII code, and hexadecimal numbers.

CAUTION:
If you experiment  with  *READTABLE*, it is useful to save the old value
in a variable, so that you can restore the system state.


nodebug
________________________________________________________________________

type: defined function (closure) 
location: extension
source file: init.lsp
Common LISP compatible: no
supported on: all machines

SYNTAX

(nodebug)


DESCRIPTION

The NODEBUG function sets  *BREAKENABLE* to NIL.  This has the effect of
turning off the break loop for errors.  NODEBUG always returns NIL.  The
default is DEBUG enabled.

EXAMPLES

	(nodebug)				; returns NIL
	(+ 1 "a")				; error: bad argument type
						; but doesn't enter break-loop
	(debug)					; returns T
	(+ 1 "a")				; error: bad argument type
						; enters break-loop
	(clean-up)				; from within the break-loop

NOTE:
The  functions  DEBUG and NODEBUG are created in the INIT.LSP  file.  If
they do not exist in your  XLISP  system,  you might be having a problem
with  INIT.LSP.  Before you start XLISP, look in the  directory  you are
currently in, and check to see if there is an INIT.LSP.


not
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(not <expr> )
	<expr>		-	the expression to check

DESCRIPTION

The NOT  predicate  checks to see if the <expr> is false.  T is returned
if the expression is NIL, NIL is returned otherwise.

EXAMPLES

	(not '())				; returns T - empty list
	(not ())				; returns T - still empty
	(setq a NIL)				; set up a variable
	(not a)					; returns T - value = empty list

	(not "a")				; returns NIL - not a list
	(not 'a)				; returns NIL - not a list

NOTE:
The NOT predicate is the same function as the NULL predicate.  


nstring-downcase
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(nstring-downcase <string> [ { :start | :end } <offset> ] ... )
	<string>	-	a string expression
	<offset>	-	an optional integer expression (for a keyword)

DESCRIPTION

The NSTRING-DOWNCASE function takes a string argument and makes it lower
case.  This function  modifies the string (or string variable  itself) -
it does not just make a copy.  The lower case string is returned.

The keyword  arguments allow for accessing  substrings  within <string>.
The  keyword  arguments  require a keyword  (:START or :END) first and a
single  integer  expression  second.  The :START  keyword  specifies the
starting offset for the NSTRING-DOWNCASE operation on <string>.  A value
of 0 starts the string at the  beginning  (no offset).  The :END keyword
specifies the end offset for the operation on <string>.

EXAMPLES

	(nstring-downcase "ABcd+-12&[")		; returns "abcd+-&["
	(nstring-downcase "ABCDEFGH" 		;
			 :start 2 :end 4)	; returns "ABcdEFGH"

	(setq mystr "ABcdEFgh")			; set up variable
	(nstring-downcase mystr)		; returns "abcdefgh"
	(print mystr)				; prints  "abcdefgh"
						; note that MYSTR is modified


nstring-upcase
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(nstring-upcase <string> [ { :start | :end } <offset> ] ... )
	<string>	-	a string expression
	<offset>	-	an optional integer expression (for a keyword)

DESCRIPTION

The  NSTRING-UPCASE  function takes a string argument and makes it upper
case.  This function  modifies the string (or string variable  itself) -
it does not just make a copy.  The upper case string is returned.

The keyword  arguments allow for accessing  substrings  within <string>.
The  keyword  arguments  require a keyword  (:START or :END) first and a
single  integer  expression  second.  The :START  keyword  specifies the
starting offset for the  NSTRING-UPCASE  operation on <string>.  A value
of 0 starts the string at the  beginning  (no offset).  The :END keyword
specifies the end offset for the operation on <string>.

EXAMPLES

	(nstring-upcase "ABcd+-12&[")		; returns "ABCD+-&["
	(nstring-upcase "abcdefgh" 		;
			 :start 2 :end 4)	; returns "abCDefgh"

	(setq mystr "ABcdEFgh")			; set up variable
	(nstring-upcase mystr)			; returns "ABCDEFGH"
	(print mystr)				; prints  "ABCDEFGH"
						; note that MYSTR is modified


nth
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(nth <expr> <list-expr> )
	<expr>		-	an integer expression
	<list-expr>	-	a list or list expression

DESCRIPTION

NTH returns the <expr>'th element of <list-expr>.  If the <list-expr> is
shorter than <expr>, a NIL is  returned.  The counting  sequence is base
zero - the first element is the 0th element.

EXAMPLES

	(nth 4 '(0 1 2 3 4 5 6))		; returns 4
	(nth 3 '(a b))				; returns NIL

	(nth 4 'a)				; error: bad argument type 
	(nth 3 "abcdefg")			; error: bad argument type 


nthcdr
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(nthcdr <expr> <list-expr> )
	<expr>		-	an integer expression
	<list-expr>	-	a list or list expression

DESCRIPTION

NTHCDR returns the <expr>'th CDR of  <list-expr>.  If the <list-expr> is
shorter than <expr>, a NIL is  returned.  The counting  sequence is base
zero - the first element is the 0th element.

EXAMPLES

	(nthcdr 4 '(0 1 2 3 4 5 6))		; returns (4 5 6)
	(nthcdr 3 '(a b))			; returns NIL

	(nthcdr 4 'a)				; error: bad argument type


null
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(null <expr> )
	<expr>		-	the expression to check

DESCRIPTION

The NULL  predicate  checks  <expr> for an empty list.  T is returned if
the list is empty, NIL is returned  otherwise.  The <expr> does not have
to be a valid  list, but if it is not a list then NIL is returned as the
result.

EXAMPLES

	(null '())				; returns T - empty list
	(null ())				; returns T - still empty
	(setq a NIL)				; set up a variable
	(null a)				; returns T - value = empty list

	(null "a")				; returns NIL - not a list
	(null 'a)				; returns NIL - not a list

NOTE:
The NULL predicate is the same function as the NOT predicate.


numberp
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(numberp <expr> )
	<expr>		-	the expression to check

DESCRIPTION

The NUMBERP predicate checks if an <expr> is a number.  T is returned if
<expr>  is  an  integer  or  floating  point  number,  NIL  is  returned
otherwise.

EXAMPLES

	(numberp 1)				; returns T - integer
	(numberp 1.2)				; returns T - float
	(numberp '1)				; returns T - still an integer
	(numberp #x034)				; returns T - readmacro produces
						;             an integer

	(numberp 'a)				; returns NIL - symbol
	(numberp #\a)				; returns NIL - character
	(numberp NIL)				; returns NIL - NIL
	(numberp #(0 1 2))			; returns NIL - array 


*obarray*
________________________________________________________________________

type: system variable
location: built-in
source file: xlsym.c
Common LISP compatible: no
supported on: all machines

SYNTAX

*obarray*


DESCRIPTION

*OBARRAY* is the system  variable that contains the system symbol table.
This symbol table is an XLISP array that is constructed out of lists.

EXAMPLES

	(defun lookin (sym) 			; create a function to 
	   (aref *obarray* 			;   look inside *OBARRAY*
	         (hash sym (length *obarray*))));   and look for a specific
		   				;   symbol - returns a list
						;
	(lookin "CAR")				; returns (TEST PEEK CAR)
	(lookin "car")				; returns NIL

NOTE:
When looking into  *OBARRAY* or INTERNing  symbols,  remember that "car"
and "CAR" are two  different  symbols in *OBARRAY*.  Remember  also that
normal  symbols  created by XLISP are upper case names.  So, if you type
in "car" as a normal  symbol, it will be the  symbol  "CAR"  after  this
normal upper-casing operation.


object
________________________________________________________________________

type: object 
location: built-in
source file: xlobj.c
Common LISP compatible: no
supported on: all machines

SYNTAX

object


DESCRIPTION

OBJECT is an object  class.  An object  is a  composite  structure  that
contains   internal  state   information,   methods  (which  respond  to
messages), a pointer to the object's class and a pointer to the object's
super-class.  XLISP  contains  two built in  objects:  OBJECT and CLASS.
OBJECT is the superclass for the CLASS object.

EXAMPLES
	(send object :show)			; look at the object definition

						; example use of objects
	(setq my-class 				; new class MY-CLASS with STATE
		(send class :new '(state)))	;
	(send my-class :answer :isnew '()	; set up initialization
		'((setq state nil) self))	;
	(send my-class :answer :set-it '(value)	; create :SET-IT message
		'((setq state value)))		;
	(setq my-obj (send my-class :new))	; create MY-OBJ out of MY-CLASS
	(send my-obj :set-it 5)			; STATE is set to 5

OBJECT DEFINITION:
The internal definition of the OBJECT object instance is:

	Object is #<Object: #23fd8>, Class is #<Object: #23fe2>
	  MESSAGES = ((:SHOW . #<Subr-: #23db2>) 
	  	      (:CLASS . #<Subr-: #23dee>) 
		      (:ISNEW . #<Subr-: #23e2a>))
	  IVARS = NIL
	  CVARS = NIL
	  CVALS = NIL
	  SUPERCLASS = NIL
	  IVARCNT = 0
	  IVARTOTAL = 0
	#<Object: #23fd8>

The  class of  OBJECT  is  CLASS.  There  is no  superclass  of  OBJECT.
Remember that the location  information (like #23fd8) varies from system
to system, yours will probably look different.

BUILT-IN METHODS:
The built in methods in XLISP include:

		<message>	operation
		-------------------------------------------------------
		:ANSWER		Add a method to an object.
		:CLASS		Return the object's class.
		:ISNEW		Run initialization code on object.
		:NEW		Create a new object (instance or class).
		:SHOW		Show the internal state of the object.

MESSAGE STRUCTURE:
The normal XLISP  convention  for a <message> is to have a valid  symbol
preceeded  by a  colon  like  :ISNEW  or  :MY-MESSAGE.  However,  it  is
possible  to define a  <message>  that is a symbol  without a colon, but
this makes the code less readable.


objectp
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlbfun.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(objectp  <expr> )
	<expr>		-	the expression to check

DESCRIPTION

The OBJECTP  predicate checks if the <expr> is an object.  T is returned
if <expr> is an object, NIL is returned otherwise.

EXAMPLES

	(objectp object)			; returns T
	(objectp class)				; returns T
	(objectp NIL)				; returns NIL
	(objectp '(a b))			; returns NIL


oddp
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(oddp <expr> )
	<expr>		-	the integer numeric expression to check

DESCRIPTION

The ODDP  predicate  checks  to see if the  number  <expr> is odd.  T is
returned  if the  number  is  odd,  NIL  is  returned  otherwise.  A bad
argument  type  error  is  generated  if the  <expr>  is  not a  numeric
expression.  A bad floating  point  operation is generated if the <expr>
is a floating point number.  Zero is an even number.

EXAMPLES

	(oddp 0)				; returns NIL
	(oddp 1)				; returns T
	(oddp 2)				; returns NIL
	(oddp -1)				; returns T
	(oddp -2)				; returns NIL

	(oddp 13.0)				; error: bad flt. pt. op.
	(oddp 'a)				; error: bad argument type
	(setq a 3)				; set value of A to 3
	(oddp a)				; returns T


open
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(open  <file> [ :direction <in-out> ]  )
	<file>		-	a string expression or symbol 
	<in-out>	-	an optional keyword symbol that must either
				:INPUT or :OUTPUT.  The default is :INPUT.

DESCRIPTION

The OPEN function  opens the <file> for input or output.  The <file> may
be a string  expression  or a symbol.  Following the <file>, there is an
optional  keyword,  :DIRECTION.  The argument  following  this is either
:INPUT or :OUTPUT  which  specifies  the  direction  of the file.  If no
:DIRECTION  is  specified,  the  default  is  :INPUT.  When  <file> is a
string, you may specify a complete  file  location or  extensions  (like
"/usr/local/bin/myfile.lsp" or "A:\LISP\TIM.BAT").  If the file open was
successful, then a file pointer of the form #<File:  #99999> is returned
as the result.  If the file open was not  successful, a NIL is returned.
For an input file, the file has to exist, or an error will be  signaled.

EXAMPLES

	(setq f (open 'mine :direction :output)); create file MINE
	(print "hi" f)				; returns "hi"
	(close f)				; file contains <hi>   <NL>
	(setq f (open 'mine :direction :input))	; open MYFILE for input
	(read f)				; returns "hi"	
	(close f)				; close it

FILE NAMES:
In the PC and DOS world, all file names and extensions  ("FOO.BAT")  are
automatically made uppercase.  In using XLISP, this means you don't have
to  worry  about  whether  the  name  is  "foo.bat",  "FOO.BAT"  or even
"FoO.bAt" - they will all work.  However, in other file systems (UNIX in
particular),  uppercase and lowercase do make a difference.  So, in UNIX
if you do a (open 'foo-file :direction :output), this will create a file
named  "FOO-FILE"  because  XLISP  uppercases  its symbols.  If you do a
(open  "foo-file"  :direction  :output),  this will  create a file named
"foo-file"  because UNIX doesn't uppercase its file names.  Another case
is if you do (savefun mydefun), this will create the file "MYDEFUN.lsp".
So, if you are having trouble with opening and accessing files, check to
make sure the file name is in the proper case.

COMMON LISP COMPATABILITY:
Common LISP supports  bidirectional files.  So, porting Common LISP code
may be difficult to port if it uses these other file types.


&optional
________________________________________________________________________

type: keyword
location: built-in
source file: xleval.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

&optional [ <opt-arg> | ( <opt-arg> [ <opt-value> [ <opt-symbol> ] ] ) ] ...
	<opt-arg>	-	optional argument
	<opt-value>	-	optional argument initialization
	<exist-symbol>	-	optional argument existence symbol

DESCRIPTION

In XLISP, there are several times that you define a formal argument list
for a body of code (like DEFUN,  DEFMACRO,  :ANSWER and LAMBDA).  All of
the formal  arguments  that are  defined are  required  to appear in the
invocation  of the  defined  function  or  operation.  If there  are any
&OPTIONAL arguments defined, they will be filled in order.  If there are
insufficient  parameters for the &OPTIONAL  arguments, they will contain
NIL, unless the arguments have an <opt-value>  initial value  specified.
The  <exist-symbol>,  if  it  is  specified,  will  contain  a T if  the
<opt-arg>  was  supplied  by the  function  call and a NIL if it was not
supplied  by  the  function   call.  This   <exist-symbol>   allows  the
programmer  to  test  for an  arguments  existence.  At  the  end of the
function or operation  execution,  these local  symbols and their values
are are removed.

EXAMPLES

	(defun foo 				; define function FOO
	  (a &optional b (c 1) )		;   with some optional args
	  (print a) (print b) (print c))	;
	(foo)					; error: too few arguments 
	(foo 1)					; prints 1 NIL 1
	(foo 1 2)				; prints 1 2 1
	(foo 1 2 3)				; prints 1 2 3 

	(defun fee				; define function FEE
	  (a &optional (b 9 b-passed) )		;   with some optional args
	  (print a) (print b)			;
	  (if b-passed (print "b was passed")	;
	               (print "b not passed")))	;
	(fee 1)					; prints 1 9 "b not passed"
	(fee 1 2)				; prints 1 2 "b was passed"


or
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(or  [ <expr1> ... ] )
	<exprN>		-	an expression

DESCRIPTION

The OR special form evaluates a sequence of expressions  and returns the
effect of a logical  INCLUSIVE-OR  operation on the expressions.  If all
of the expressions  are NIL, NIL is returned as OR's result.  Evaluation
of the expressions  will stop when an expression  evaluates to something
other than NIL, none of the  subsequent  expressions  will be evaluated.
If there are no expressions, OR returns NIL as its result.

EXAMPLES

	(or NIL NIL NIL)			; returns NIL
	(or NIL T NIL)				; returns T
	(or NIL (princ "hi") (princ "ho"))	; prints  hi  and returns "hi"
	(or T T T)				; returns T
	(or)					; returns NIL

	(setq a 5)  (setq b 6)			; set up A and B
	(if (or (< a b) (< b a))		; if 
	   (print "not equal")			;  then
	   (print "equal"))			;  else
						; prints  "not equal"


peek
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlsys.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(peek <address> )
	<address>	-	an integer expression

DESCRIPTION

The PEEK function  returns the internal  memory value at the  <address>.
The returned value is an integer.

EXAMPLES

	(setq var 0)				; set up VAR with 0
	(address-of var)			; returns 123224
	(address-of 'var)			; returns 161922
	(peek (address-of var))			; returns 83951616
	(peek (1+ (address-of var)))		; returns 16777216
	(peek (+ 2 (address-of var)))		; returns 0  <-- value of VAR
	(setq var 14)				; change the value to 14
	(peek (+ 2 (address-of var)))		; returns 14
	(setq var 99)				; change the value to 99
	(peek (+ 2 (address-of var)))		; returns 99

CAUTION:
Be careful  when  modifying  the  internal  state of XLISP.  If you have
modified it, it would be a good idea to exit XLISP and  re-enter  before
doing any work you really want to retain.

ADDITIONAL CAUTION:
It is possible to PEEK and POKE not just XLISP's  memory put other parts
of your  computer's  memory.  Be very careful when doing this.  Also, in
some  computers,  just looking at a memory  location can cause things to
happen - I/O locations fall in this category.


peek-char
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c  
Common LISP compatible: similar
supported on: all machines

SYNTAX

(peek-char  [ <skip-flag>  [ <source> ] ]  )
	<skip-flag>	-	an optional expression - default is NIL
	<source>	-	an optional source - must be a file pointer
				or stream, the default is *standard-input*

DESCRIPTION

The PEEK-CHAR  function looks at a single  character  from the specified
<source>.  The character  looked-at is returned as an integer  value for
the  result.  If the  <skip-flag>  expression  is  NIL,  then  the  next
character will be looked-at,  without  advancing the position within the
file.  If  the   <skip-flag>   expression  is  non-NIL,  then  the  next
non-white-space character will be looked-at.  This skipping does advance
the position within the file.  White-space characters include blank, tab
and new-line  characters.  If <skip-flag>  is not used, no skipping will
occur.  The <source>  may be a file pointer or a stream.  If there is no
<source>,   *STANDARD-INPUT*  is  the  default.  If  an  end-of-file  is
encountered in the <source>, then NIL will be returned as the result.

EXAMPLES

	(setq fp (open "f" :direction :output))	; create file "f"
	(print 12 fp)				;
	(princ "  34" fp)  (terpri fp)		;
	(close fp)				;
						;
	(setq fp (open "f" :direction :input))	; open "f" for reading
	(peek-char NIL fp)			; returns #\1
	(peek-char NIL fp)			; returns #\1 - didn't advance
	(read-char fp)				; returns #\1 - force advance
	(peek-char NIL fp)			; returns #\2
	(read-char fp)				; returns #\2 - force advance
	(peek-char NIL fp)			; returns #\Newline
	(peek-char T fp)			; returns #\3 - skipped blanks
	(read-line fp)				; returns "34"
	(close fp)				;

COMMON LISP COMPATABILITY:
The XLISP and Common LISP PEEK-CHAR  functions are compatable for simple
cases.  They both  allow  for the  optional  <skip-flag>  and  <source>.
However, in Common LISP, there are addition parameters which occur right
after <source> that support various end-of-file operations and recursive
calls.  So, when porting from Common LISP to XLISP,  remember  there are
additional  arguments in Common LISP's  PEEK-CHAR that are not supported
in XLISP.


plusp
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(plusp <expr> )
	<expr>		-	the numeric expression to check

DESCRIPTION

The PLUSP  predicate  checks to see if the number <expr> is positive.  T
is returned if the number is positive  (greater than 0), NIL is returned
otherwise.  A bad argument  type error is generated if the <expr> is not
a numeric expression.

EXAMPLES

	(plusp 0)				; returns NIL
	(plusp 1)				; returns T
	(plusp -1)				; returns NIL
	(plusp #xFFFFFFFF)			; returns NIL
	(plusp #x0FFFFFFF)			; returns T

	(plusp 'a)				; error: bad argument type
	(setq a 4)				; set value of A to 4
	(plusp a)				; returns T


poke
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlsys.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(poke  <address>  <expr> )
	<address>	-	an integer expression
	<expr>		-	an integer expression

DESCRIPTION

The POKE function  writes the <expr> at the internal memory value at the
specified  <address>.  The  returned  value is <expr>.  Be very  careful
with this function.

EXAMPLES

	(setq var 0)				; set up VAR with 0
	(address-of var)			; returns 123224
	(address-of 'var)			; returns 161922
	(peek (address-of var))			; returns 83951616
	(peek (1+ (address-of var)))		; returns 16777216
	(peek (+ 2 (address-of var)))		; returns 0  <-- value of VAR
	(setq var 14)				; change the value to 14
	(peek (+ 2 (address-of var)))		; returns 14
	(poke (+ 2 (address-of var)) 1023)	; POKE the value to 1023
	(print var)				; prints  1023

CAUTION:
Be careful  when  modifying  the  internal  state of XLISP.  If you have
modified it, it would be a good idea to exit XLISP and  re-enter  before
doing any work you really want to retain.

ADDITIONAL CAUTION:
It is possible to PEEK and POKE not just XLISP's  memory but other parts
of your  computer's  memory.  Be very careful when doing this.  Also, in
some  computers,  just looking at a memory  location can cause things to
happen - I/O locations fall in this category.


pp
________________________________________________________________________

type: function (subr)
location: extension 
source file: pp.lsp
Common LISP compatible: no
supported on: all machines

SYNTAX

(pp  <expr> [ <destination>  [ <break-size> ] ] )
	<expr>		-	an expression to be pretty printed
	<destination>	-	an optional destination - must be a file pointer
				or stream, the default is *standard-output*
	<break-size>	-	an integer expression - default is 45

DESCRIPTION

The PP  function  produces a pretty  looking  version of the  <expr> and
prints it to the specified  <destination>.  If <expr> is an atom (like a
string, a  symbol,  a number,  etc.)  PP will  print it like  PRINT.  If
<expr> is a list, it will  perform  indenting.  T is always  returned as
the result of PP.  The  <destination> may be a file pointer or a stream.
If there is no <destination>  (or it is NIL),  *STANDARD-OUTPUT*  is the
default.  The  <break-size>  paramter  is  used  to  determine  when  an
expression   should  be  broken  into   multiple   lines.  The   default
<break-size> is 45.

EXAMPLES

	(pp 'a)					; prints  A	    returns T
	(pp "abcd")				; prints  "abcd"    returns T
	(pp '(a (b c)))				; prints  (A (B C)) returns T

COMMON LISP COMPATABILITY:
In  Common  LISP,  the PP  functionality  is  provided  with the  PPRINT
function.  The PP function was available in previous  XLISP releases and
is still  accessible.  It does allow you to specify  the length  through
<break-size>, which is not available in PPRINT.

NOTE:
PP is an extension to the XLISP system provided in the PP.LSP file.  The
default  system and INIT.LSP  start-up  code do not  automatically  load
PP.LSP.  You need to  specifically  LOAD it  yourself  during your XLISP
session.  Another alternative is to put the code or a (LOAD "pp") in the
INIT.LSP  file.  The PP.LSP should have come with your XLISP system.  If
it doesn't, refer to the EXAMPLE PROGRAMS chapter.


pprint
________________________________________________________________________

type: function (subr)
location: built-in
source file: xlpp.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(pp  <expr> [ <destination> ] )
	<expr>		-	an expression to be pretty printed
	<destination>	-	an optional destination - must be a file pointer
				or stream, the default is *standard-output*

DESCRIPTION

The PPRINT function  produces a pretty looking version of the <expr> and
prints it to the specified  <destination>.  If <expr> is an atom (like a
string, a symbol, a number,  etc.)  PPRINT will print it like PRINT.  If
<expr>  is a list,  it will  perform  indenting,  as  necessary.  NIL is
always  returned  as the result of PPRINT.  The  <destination>  may be a
file pointer or a stream.  If there is no <destination>  (or it is NIL),
*STANDARD-OUTPUT* is the default.

EXAMPLES

	(pprint 'a)		; prints  A	    returns T
	(pprint "abcd")		; prints  "abcd"    returns T

	(pprint '(a-very-long-name (first list) (second list)))
				;
				; prints (A-VERY-LONG-NAME (FIRST LIST)
				; 			   (SECOND LIST))

COMMON LISP COMPATABILITY:
Common LISP specifies that PPRINT with a  <destination>  of NIL, will go
to    *STANDARD-OUTPUT*.   XLISP   does   not   send   the   output   to
*STANDARD-OUTPUT*   with  a  <destination>  of  NIL.  Common  LISP  also
specifies  that a  <destination>  of T will be  sent  to  *TERMINAL-IO*.
XLISP does not allow T as a valid argument for <destination>.


prin1
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c  and  xlprin.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(prin1  <expr>  [ <destination> ] )
	<expr>		-	an expression
	<destination>	-	an optional destination - must be a file pointer
				or stream, the default is *standard-output*

DESCRIPTION

The PRIN1  function  prints the <expr> to the  specified  <destination>.
The  <expr> is printed  without a  new-line.  If <expr> is a string,  it
will be printed  with quotes  around the string.  The <expr> is returned
as the result.  The <destination> may be a file pointer or a stream.  If
there is no <destination>, *STANDARD-OUTPUT* is the default.  The TERPRI
function is used to terminate the print lines produced.

EXAMPLES

	(prin1 'a)				; prints  A	without <NL>
	(prin1 '(a b))				; prints  (A B)	without <NL>
	(prin1 2.5)				; prints  2.5	without <NL>
	(prin1 "hi")				; prints  "hi" 	without <NL>

	(setq f (open "f" :direction :output))	; create file 
	(prin1 "hi" f)				; returns "hi"
	(prin1 1234 f)				; returns 1234
	(prin1 "he" f)				; returns "he"
	(close f) 				; file contains <"hi"1234"he"> 

COMMON LISP COMPATABILITY:
Common LISP specifies that print operations with a <destination> of NIL,
will  go to  *STANDARD-OUTPUT*.  XLISP  does  not  send  the  output  to
*STANDARD-OUTPUT*   with  a  <destination>  of  NIL.  Common  LISP  also
specifies  that a  <destination>  of T will be  sent  to  *TERMINAL-IO*.
XLISP does not allow T as a valid argument for <destination>.


princ
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c  and  xlprin.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(princ  <expr>  [ <destination> ] )
	<expr>		-	an expression
	<destination>	-	an optional destination - must be a file pointer
				or stream, the default is *standard-output*

DESCRIPTION

The PRINC  function  prints the <expr> to the  specified  <destination>.
The  <expr> is printed  without a  new-line.  If <expr> is a string,  it
will not be  printed  with  quotes  around  the  string.  The  <expr> is
returned as the result.  The  <destination>  may be a file  pointer or a
stream.  If there is no <destination>, *STANDARD-OUTPUT* is the default.
The TERPRI function is used to terminate the print lines produced.

EXAMPLES

	(princ 'a)				; prints  A	without <NL>
	(princ '(a b))				; prints  (A B)	without <NL>
	(princ 99)				; prints  99	without <NL>
	(princ "hi")				; prints  hi	without <NL>

	(setq f (open "f" :direction :output))	; create file
	(princ "hi" f)				; returns "hi"
	(princ 727 f)				; returns 727
	(princ "ho" f)				; returns "ho"
	(close f)				; file contains <hi727ho>

COMMON LISP COMPATABILITY:
Common LISP specifies that print operations with a <destination> of NIL,
will  go to  *STANDARD-OUTPUT*.  XLISP  does  not  send  the  output  to
*STANDARD-OUTPUT*   with  a  <destination>  of  NIL.  Common  LISP  also
specifies  that a  <destination>  of T will be  sent  to  *TERMINAL-IO*.
XLISP does not allow T as a valid argument for <destination>.


print
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c  and  xlprin.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(print  <expr>  [ <destination> ] )
	<expr>		-	an expression
	<destination>	-	an optional destination - must be a file pointer
				or stream, the default is *standard-output*

DESCRIPTION

The PRINT  function  prints the <expr> to the  specified  <destination>.
The <expr> is printed followed by a new-line.  If <expr> is a string, it
will be printed  with quotes  around the string.  The <expr> is returned
as the result.  The <destination> may be a file pointer or a stream.  If
there is no <destination>, *STANDARD-OUTPUT* is the default.

EXAMPLES

	(print 'a)				; prints  A	with <NL>
	(print '(a b))				; prints  (A B)	with <NL>
	(print 99)				; prints  99	with <NL>
	(print "hi")				; prints  "hi"	with <NL>

	(setq f (open "f" :direction :output))	; create file
	(print "hi" f)				; returns "hi"
	(print 727 f)				; returns 727
	(print "ho" f)				; returns "ho"
	(close f)				; file contains "hi"<NL>
						;               727<NL>
						;		"ho"<NL>

COMMON LISP COMPATABILITY:
Common LISP specifies that print operations with a <destination> of NIL,
will  go to  *STANDARD-OUTPUT*.  XLISP  does  not  send  the  output  to
*STANDARD-OUTPUT*   with  a  <destination>  of  NIL.  Common  LISP  also
specifies  that a  <destination>  of T will be  sent  to  *TERMINAL-IO*.
XLISP does not allow T as a valid argument for <destination>.


*print-case*
________________________________________________________________________

type: system variable 
location: built-in
source file: xlprin.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

*print-case*


DESCRIPTION

*PRINT-CASE*  is a system  variable  that  allows a user to specify  how
symbols  are  to  be  printed  by  XLISP.  If  *PRINT-CASE*  is  set  to
:DOWNCASE,  all  symbols  will be printed in lower case  characters.  If
*PRINT-CASE*  is set to :UPCASE,  all  symbols  will be printed in upper
case  characters.  If *PRINT-CASE* is set to anything other than :UPCASE
or :DOWNCASE, all symbols will be printed in upper case characters.  The
default value for *PRINT-CASE* is the keyword :UPCASE.

EXAMPLES
	(setq *print-case* :downcase)		; returns :downcase
	(setq a 'b)				; returns b

	(setq *print-case* 'foo)		; returns FOO
	(setq a 'b)				; returns B

	(setq *print-case* :upcase)		; returns :UPCASE
	(setq a 'b)				; returns B

COMMON LISP COMPATABILITY:
Common  LISP  supports  a third  keyword  :CAPITALIZE.  XLISP  does  not
support  this,  but  this  should  not be a  major  problem.  If  set to
:CAPITALIZE, XLISP will print all symbols in upper-case characters.


prog
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(prog  ( [ <binding> ... ]  )  [ <expr> ... ]  )
	<binding>	-	a variable binding which is can take one of 
				<symbol>    or     ( <symbol> <init-expr> )
	<symbol>	-	a symbol
	<init-expr>	-	an initialization expression for <symbol>
	<expr>		-	expressions comprising the body of the loop
				which may contain RETURNs, GOs or tags for GO  

DESCRIPTION

The PROG special  form is basically a 'block'  construct  (like a PASCAL
BEGIN / END) that contains symbols (with optional initializations) and a
block of code  (expressions)  to evaluate.  The PROG form  evaluates its
initializations in no specified order (as opposed to PROG* which does it
sequential order).  The first form after the PROG is the <binding> form.
It contains a series of <symbol>'s or  <binding>'s.  The  <binding> is a
<symbol> followed by an initialization expression <init-expr>.  If there
is no <init-expr>, the <symbol> will be initialized to NIL.  There is no
specification  as to the order of execution  of the bindings or the step
expressions - except that they happen all together.  If a RETURN form is
evaluated,  its value  will be  returned.  Otherwise,  NIL is  returned.
When the PROG is finished  execution,  the <symbol>'s  that were defined
will no longer exist or retain their values.

EXAMPLES

	(prog () (print "hello"))		; prints  "hello"  returns NIL
	(prog (i j)				; PROG with vars I and J
	      (print i) (print j))		; prints  NIL NIL  returns NIL
	(prog ((i 1) (j 2)) 			; PROG with vars I and J
	      (print i) (print j) 		;
	      (return (+ i j)))			; prints  1 2      returns 3


prog*
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(prog*  ( [ <binding> ... ]  )  [ <expr> ... ]  )
	<binding>	-	a variable binding which is can take one of 
				<symbol>     or    ( <symbol> <init-expr> )
	<symbol>	-	a symbol
	<init-expr>	-	an initialization expression for <symbol>
	<expr>		-	expressions comprising the body of the loop
				which may contain RETURNs, GOs or tags for GO  

DESCRIPTION

The PROG* special form is basically a 'block'  construct  (like a PASCAL
BEGIN / END) that contains symbols (with optional initializations) and a
block of code  (expressions)  to evaluate.  The PROG* form evaluates its
initializations in sequential order (as opposed to PROG which does it in
no  specified  order).  The first form after the PROG* is the  'binding'
form.  It contains a series of <symbol>'s or <binding>'s.  The <binding>
is a <symbol> followed by an initialization  expression <init-expr>.  If
there is no  <init-expr>,  the <symbol> will be initialized to NIL.  The
order of  execution of the bindings is  sequential.  If a RETURN form is
evaluated,  its value  will be  returned.  Otherwise,  NIL is  returned.
When the PROG* is finished  execution, the <symbol>'s  that were defined
will no longer exist or retain their values.

EXAMPLES

	(prog* (i j)				; PROG* with vars I and J
	      (print i) (print j))		; prints  NIL NIL  returns NIL
	(prog* ((i 1) (j 2)) 			; PROG* with vars I and J
	      (print i) (print j) 		;
	      (return (+ i j)))			; prints  1 2      returns 3
	(prog* () (print "hello"))		; prints  "hello"  returns NIL

	(prog ((i 1) (j (+ i 1)))		; PROG won't work due to order
	      (print (+ i j)) )			; error: unbound variable - I
	(prog* ((i 1) (j (+ i 1)))		; PROG* will work due to order
	       (print (+ i j)) )		; prints  3        returns NIL


prog1
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(prog1  [ <expr1>  <expr2> ... ]  )
	<exprN>		-	expressions comprising the body of the loop

DESCRIPTION

The PROG1 special form is basically a 'block'  construct  (like a PASCAL
BEGIN / END) that  contains a block of code  (expressions)  to evaluate.
<expr1>'s value will be returned as the result of PROG1.  If there is no
<expr1>, NIL is returned.

EXAMPLES

	(prog1 (print "hi") (print "ho"))	; prints "hi" "ho" returns "hi"
	(prog1)					; returns NIL
	(prog1 'a)				; returns A
	(prog1 "hey" (print "ho"))		; prints "ho"      returns "hey"

NOTE:
PROG1,  PROG2,  PROGN and PROGV do not allow the use of  RETURN or GO or
tags for GO.


prog2
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(prog2  [ <expr1>  <expr2> ... ]  )
	<exprN>		-	expressions comprising the body of the loop

DESCRIPTION

The PROG2 special form is basically a 'block'  construct  (like a PASCAL
BEGIN / END) that  contains a block of code  (expressions)  to evaluate.
<expr2>'s value will be returned as the result of PROG2.  If there is no
<expr2>,  <expr1> is returned.  If there is no <expr1>, NIL is returned.

EXAMPLES

	(prog2 (print "hi") (print "ho"))	; prints "hi" "ho" returns "ho"
	(prog2)					; returns NIL
	(prog2 (print "hi"))			; prints "hi"      returns "hi"
	(prog2 (print "ho") "hey")		; prints "ho"      returns "hey"
	(prog2 'a 'b 'c)			; returns B

NOTE:
PROG1,  PROG2,  PROGN and PROGV do not allow the use of  RETURN or GO or
tags for GO.


progn
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(progn  [ <expr1>  <expr2> ... ]  )
	<exprN>		-	expressions comprising the body of the loop

DESCRIPTION

The PROGN special form is basically a 'block'  construct  (like a PASCAL
BEGIN / END) that  contains a block of code  (expressions)  to evaluate.
The last  <expr>'s  value will be  returned  as the result of PROGN.  If
there are no <expr>s, NIL is returned.

EXAMPLES

	(progn (print "hi") (print "ho"))	; prints "hi" "ho" returns "ho"
	(progn)					; returns NIL
	(progn "hey" (print "ho"))		; prints "ho"      returns "ho"
	(progn 'a)				; returns A
	(progn 'a 'b 'c)			; returns C

NOTE:
PROG1,  PROG2,  PROGN and PROGV do not allow the use of  RETURN or GO or
tags for GO.


progv
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(progv  <symbols> <values> [ <expr1>  <expr2> ... ]  )
	<symbols>	-	a list comprising symbols to be bound
	<values>	-	a list comprising values to be bound to symbols
	<exprN>		-	expressions comprising the body of the loop

DESCRIPTION

The PROGV special form is basically a 'block'  construct  (like a PASCAL
BEGIN / END) that  contains a block of code  (expressions)  to evaluate.
PROGV is  different  from PROG1,  PROG2 and PROGN in that it  contains a
pair of lists - <symbols> and <values>.  Before  evaluating  the <exprN>
expressions,   PROGV  will   dynamically   bind  the   <values>  to  the
corresponding  <symbols>.  If  there  are  too  many  <symbols>  for the
<values>, the <symbols> with no corresponding  <values> will be bound to
NIL.  The  variables  will be unbound after the execution of PROGV.  The
last  <expr>'s  value will be returned as the result of PROGV.  If there
are no <expr>s, NIL is returned.

EXAMPLES

	(progv '(var) '(2) 			; 
		(print var) (print "two"))	; prints 2 "two" returns "two"

	(setq a "beginning")			; initialize A
	(progv '(a) '(during) (print a))	; prints DURING
	(print a)				; prints "beginning"

	(progv '(no-way) '(no-how) )		; returns NIL
	(progv)					; error: too few arguments

NOTE:
PROGV is different  from PROG (which allows  symbols and  initialization
forms) in that PROGV allows its <symbols>  and <values> to be evaluated.
This allows you to pass in forms that generate the  <symbols>  and their
<values>.

NOTE:
PROG1,  PROG2,  PROGN and PROGV do not allow the use of  RETURN or GO or
tags for GO.


psetq
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(psetq [ <symbol> <expr> ] ... )
	<symbol>	-	un-evaluated symbol
	<expr>		-	value for <symbol>

DESCRIPTION

PSETQ sets <expr> as the value of <symbol>.  There can be several  pairs
of  assignment.  PSETQ  performs  these  assignments  in  parallel - the
<symbol>'s  are not assigned new values until all the <expr>'s have been
evaluated.  PSETQ returns the value from the last <expr> as it's result.

EXAMPLES

	(psetq a 1)				; symbol A gets value 1
	(psetq b '(a b c))			; symbol B gets value (A B C)
	(psetq mynum (+ 3 4))			; symbol MYNUM gets value 7

	(setq goo 'ber)				; returns BER
	(setq num 1)				; returns 1
	(psetq goo num num goo)			; returns BER
	(print goo)				; returns 1
	(print num)				; returns BER


putprop
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(putprop <symbol> <value> <property> )
	<symbol>	-	the symbol with a property list
	<value>		- 	the value to be assigned to the property
	<property>	-	the property name being changed/added

DESCRIPTION

PUTPROP  sets  the  value  of the  <property>  in the  <symbol>.  If the
<property> does not exist, the <property> is added to the property list.
The  <symbol>  must be an existing  symbol.  The <value> may be a single
value or a list.

Property  lists are lists  attached to any user defined  variables.  The
lists are in the form of (name1  val1 name2 val2  ....).  Any  number of
properties may be attached to a single variable.

EXAMPLES

	(setq person 'bobby)			; create a var with a value
	(putprop person 'boogie 'last-name)	; add a LAST-NAME property
	(putprop person 'disc-jockey 'job)	; add a JOB property
	(get person 'last-name)			; retrieve LAST-NAME - boogie
	(get person 'job)			; retrieve JOB - disc-jockey
	(get person 'height)			; non-existant - returns NIL
	(putprop person '(10 20 30) 'stats)	; add STATS - a list 
	(get person 'stats)			;

NOTE:
You can set a  property  to the value  NIL.  However,  this NIL value is
indistinguishable  from the NIL returned when a property does not exist.

COMMON LISP COMPATIBILITY:
Common LISP does not have a PUTPROP function.  It uses a SETF to achieve
this  functionality.  Porting  from  Common LISP to XLISP will work fine
since XLISP supports the SETF  modifications  of property lists and GET.
Porting from XLISP to Common LISP will require translating  PUTPROP into
SETF forms.

LISP DIALECTS:
The order of PUTPROP arguments is <symbol>,  <value>,  <property>.  This
is  different  from  many  other  LISPs  which  normally  use  <symbol>,
<property>, <value>.  Be careful when porting existing LISP code.


quote
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(quote <expr> )
	<expr>		-	an expression

DESCRIPTION

QUOTE returns the the <expr> un-evaluated.  

EXAMPLES

	my-var					; error: unbound variable 
	(quote my-var)				; returns MY-VAR
	my-var					; still error: unbound variable
	(set (quote my-var) 111)		; give MY-VAR a value - 
						;   make it exist
	my-var					; returns 111
	(quote my-var)				; returns MY-VAR

						; SAME AS ABOVE BUT USING THE 
						; READ MACRO FOR QUOTE - '
	new-var					; error: unbound variable
	'new-var				; returns NEW-VAR
	new-var					; still error: unbound variable
	(setq new-var 222)			; give NEW-VAR a value -
						;   make it exist
	new-var					; returns 222
	'new-var				; returns NEW-VAR

READ MACRO:  
XLISP  supports  the normal read macro of a single quote as a short-hand
method of writing the QUOTE function.


random
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(random <expr> )
	<expr>		-	integer number/expression

DESCRIPTION

The RANDOM function  generates and returns a random number between 0 and
<expr> - 1.  If <expr> is  negative,  the  number  range is forced to be
positive.

EXAMPLES

	(random 100)				; returns 7
	(random 100)				; returns 49
	(random 100)				; returns 73
	(random -100)				; returns 58
	(random 100.01)				; error: bad flt.pt. operation 

COMMON LISP COMPATABILITY:
Common LISP allows an optional state  parameter,  which is not supported
in XLISP.  Also, Common LISP allows  floating point numbers, which XLISP
does not support.

NOTE:
This  function is an  extension of the XLISP  system.  It is provided in
the  MSSTUFF.C  source code file.  If your XLISP  system is built for an
IBM PC and  compatibles,  this  function  will work.  If your  system is
built on UNIX or some other  operating  system, it will need the code in
the corresponding STUFF.C file.


read
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c  and  xlread.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(read   [ <source>  [ <eof-result> [ <recursive-flag> ] ] ]  )
	<source>	-	an optional source - must be a file pointer
				or stream, the default is *standard-input*
	<eof-result>	-	an optional expression (default is NIL)
	<recursive-flag>-	an optional expression ( NIL or non-NIL )

DESCRIPTION

The READ function reads an expression from the specified  <source>.  The
expression read is a 'normal' XLISP expression - not a line.  This means
that white space is removed - blanks,  empty  lines and  comment  lines.
Read-macro  expansions  will  occur  (like  QUOTE  instead  of  ').  The
expression  needs to be an atom  (numeric,  string or symbol) or a valid
list.  It can span several  lines.  The  expression  read is returned as
the result.  The  <source>  may be a file pointer or a stream.  If there
is no <source>,  *STANDARD-INPUT*  is the default.  If an end-of-file is
encountered  in the  <source>,  then  the  <eof-result>  value  will  be
returned as the result.

If you wish to read just  lines or  characters,  refer to  READ-LINE  or
READ-CHAR.

The  <recursive-flag>  is intended for use with embedded  calls to READ.
This is useful in read-macro and read-table  uses.  If  <recursive-flag>
is non-NIL, the READ does not expect itself to be at a 'top-level',  but
recursively executing within another READ that is in progress.

EXAMPLES

	(setq fp (open "f" :direction :output))	; set up file
	(print "hello" fp)			;
	(print 12.34 fp)			;
	(princ "'(a b" fp)     (terpri fp)	;	fill with stuff
	(princ "; comment" fp) (terpri fp)	;
	(princ " c d)" fp )			;
	(close fp)				;
						;
	(setq fp (open "f" :direction :input))	; now read the file
	(read fp "done")			; returns "hello"
	(read fp "done")			; returns 12.34
	(read fp "done")			; returns (QUOTE (A B C D))
						; note macro expansion of QUOTE
						; note that comment is gone
	(read fp "done")			; returns "done"
	(close fp)

COMMON LISP COMPATABILITY:
The XLISP and Common LISP READ  functions  are similar.  They both allow
for  <source>,  <eof-result>  and  <recursive-flag>.  However, in Common
LISP, there is an addition  end-of-file error parameter.  This parameter
occurs  right after  <source>  and  specifies  whether or not to flag an
error  on   end-of-file.  So,  when  porting,   remember  there  is  one
additional  argument in Common  LISP's  READ.  You need to be  concerned
about this if you use more than just a <source>  argument - going either
from XLISP to Common LISP or vice versa.

COMMON LISP COMPATABILITY:
Common LISP specifies that read  operations with a <source> of NIL, will
come  from   *STANDARD-INPUT*.  XLISP  does  not  read  the  input  from
*STANDARD-INPUT*  with a <source>  of NIL.  Common  LISP also  specifies
that a <source> of T will read from *TERMINAL-IO*.  XLISP does not allow
T as a valid argument for <source>.


read-byte
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c  
Common LISP compatible: similar
supported on: all machines

SYNTAX

(read-byte  [ <source> ]  )
	<source>	-	an optional source - must be a file pointer
				or stream, the default is *standard-input*

DESCRIPTION

The  READ-BYTE  function  reads a single  character  from the  specified
<source>.  The  character  read is returned as an integer  value for the
result.  The <source> may be a file pointer or a stream.  If there is no
<source>,   *STANDARD-INPUT*  is  the  default.  If  an  end-of-file  is
encountered in the <source>, then NIL will be returned as the result.

EXAMPLES

	(setq fp (open "f" :direction :output))	; set up file
	(print 12.34 fp)			;
	(close fp)				;
						;
	(setq fp (open "f" :direction :input))	; now read the file
	(read-byte fp)				; returns 49		"1"
	(read-byte fp)				; returns 50		"2"
	(read-byte fp)				; returns 46		"."
	(read-byte fp)				; returns 51		"3"
	(read-byte fp)				; returns 52		"4"
	(read-byte fp)				; returns 10		"\n"
	(read-byte fp)				; returns NIL		empty
	(close fp)				; 

COMMON LISP COMPATABILITY:
The XLISP and Common LISP READ-BYTE  functions are compatable for simple
cases.  They both allow for the  optional  <source>.  However, in Common
LISP, there are addition  parameters  which occur right after  <source>.
So,  when  porting  from  Common  LISP  to  XLISP,  remember  there  are
additional arguments in Common LISP's READ-BYTE.

COMMON LISP COMPATABILITY:
Common LISP specifies that read  operations with a <source> of NIL, will
come  from   *STANDARD-INPUT*.  XLISP  does  not  read  the  input  from
*STANDARD-INPUT*  with a <source>  of NIL.  Common  LISP also  specifies
that a <source> of T will read from *TERMINAL-IO*.  XLISP does not allow
T as a valid argument for <source>.


read-char
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c  
Common LISP compatible: similar
supported on: all machines

SYNTAX

(read-char  [ <source> ]  )
	<source>	-	an optional source - must be a file pointer
				or stream, the default is *standard-input*

DESCRIPTION

The  READ-CHAR  function  reads a single  character  from the  specified
<source>.  The character  read is returned as a single  character  value
for the  result.  The  <source>  may be a file  pointer or a stream.  If
there  is  no  <source>,   *STANDARD-INPUT*   is  the   default.  If  an
end-of-file is encountered in the <source>, then NIL will be returned as
the result.

EXAMPLES

	(setq fp (open "f" :direction :output))	; set up file
	(print 12.34 fp)			;
	(close fp)				;
						;
	(setq fp (open "f" :direction :input))	; now read the file
	(read-char fp)				; returns #\1
	(read-char fp)				; returns #\2
	(read-char fp)				; returns #\.
	(read-char fp)				; returns #\3
	(read-char fp)				; returns #\4
	(read-char fp)				; returns #\Newline
	(read-char fp)				; returns NIL		empty
	(close fp)				; 

COMMON LISP COMPATABILITY:
The XLISP and Common LISP READ-CHAR  functions are compatable for simple
cases.  They both allow for the  optional  <source>.  However, in Common
LISP, there are addition  parameters  which occur right after  <source>.
So,  when  porting  from  Common  LISP  to  XLISP,  remember  there  are
additional arguments in Common LISP's READ-CHAR.

COMMON LISP COMPATABILITY:
Common LISP specifies that read  operations with a <source> of NIL, will
come  from   *STANDARD-INPUT*.  XLISP  does  not  read  the  input  from
*STANDARD-INPUT*  with a <source>  of NIL.  Common  LISP also  specifies
that a <source> of T will read from *TERMINAL-IO*.  XLISP does not allow
T as a valid argument for <source>.


read-line
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c  
Common LISP compatible: similar
supported on: all machines

SYNTAX

(read-line  [ <source> ]  )
	<source>	-	an optional source - must be a file pointer
				or stream, the default is *standard-input*

DESCRIPTION

The READ-LINE function reads a single line from the specified  <source>.
The  line  read is  returned  as a  string  value  for the  result.  The
<source>  may be a file  pointer or a stream.  If there is no  <source>,
*STANDARD-INPUT*  is the default.  If an end-of-file  is encountered  in
the <source>, then NIL will be returned as the result.

EXAMPLES

	(setq fp (open "f" :direction :output))	; set up file
	(print "fe fi" fp)			;
	(print 12.34 fp)			;
	(close fp)				;
						;
	(setq fp (open "f" :direction :input))	; now read the file
	(read-line fp)				; returns ""fe fi""	
	(read-line fp)				; returns "12.34"
	(read-line fp)				; returns NIL
	(close fp)				; 

COMMON LISP COMPATABILITY:
The XLISP and Common LISP READ-LINE  functions are compatable for simple
cases.  They both allow for the  optional  <source>.  However, in Common
LISP, there are addition  parameters  which occur right after  <source>.
So,  when  porting  from  Common  LISP  to  XLISP,  remember  there  are
additional arguments in Common LISP's READ-LINE.

COMMON LISP COMPATABILITY:
Common LISP specifies that read  operations with a <source> of NIL, will
come  from   *STANDARD-INPUT*.  XLISP  does  not  read  the  input  from
*STANDARD-INPUT*  with a <source>  of NIL.  Common  LISP also  specifies
that a <source> of T will read from *TERMINAL-IO*.  XLISP does not allow
T as a valid argument for <source>.


*readtable*
________________________________________________________________________

type: system variable
location: built-in
source file: xlread.c
Common LISP compatible: related
supported on: all machines

SYNTAX

*readtable*


DESCRIPTION

The  *READTABLE*  is  a  system  variable  that  contains  XLISP's  data
structures  relating to the  processing of characters  from the user (or
files) and read-macro expansions.  The table is 128 entries (0..127) for
each of the 7-bit ASCII  characters  that XLISP can read.  Each entry in
the *READTABLE*  array must be one of NIL,  :CONSTITUENT,  :WHITE-SPACE,
:SESCAPE, :MESCAPE, a :TMACRO dotted pair or a :NMACRO dotted pair.

		Table entry		Meaning
		--------------------------------------------------------
		NIL			Invalid character
		:CONSTITUENT		The character is valid, as is.
		:WHITE-SPACE		The character may be skipped over.
		:SESCAPE		The single escape character ('\');
		:MESCAPE		The multiple escape character ('|');
		(:TMACRO . <f> )	A terminating read-macro
		(:NMACRO . <f> )	A non-terminating read-macro

In the case of :NMACRO and :TMACRO, the form of the *READTABLE* entry is
a list like  (:TMACRO .  <function> ) or (:NMACRO .  <function>  ).  The
<function>  can be a  built-in  read-macro  function  or a user  defined
lambda expression.  The <function> takes two parameters, an input stream
specification,   and  an  integer  that  is  the  character  value.  The
<function>  should  return NIL if the  character is  'white-space'  or a
value CONSed with NIL to return the value.

EXAMPLES

	*readtable*				; returns the current table

	(defun look-at (table)			; define a function to 
	 (dotimes (ch 127)			;   look in a table
	  (prog ( (entry (aref table ch)) )	;   and print out any	  
	    (case entry 			;   entries with a function
	      (NIL	    NIL)		;
	      (:CONSTITUENT NIL)		;
	      (:WHITE-SPACE NIL)		;
	      (:SESCAPE     NIL)		;
	      (:MESCAPE     NIL)		;
	      (T	  (princ (int-char ch)));
	      )))				;
	 (terpri))				;
	 					;
	(look-at *readtable*)			;  prints  "#'(),;`

CAUTION:
If you experiment  with  *READTABLE*, it is useful to save the old value
in a variable, so that you can restore the system state.


rem
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(rem <expr1> ... )
	<exprN>		-	integer number/expression

DESCRIPTION

The REM function takes the first pair of expressions and determines what
is the remainder  from dividing the first by the second  expression.  If
there  are no other  arguments,  this  value is  returned.  If there are
additional  arguments, the remainder of the first pair is applied to the
next  and  then  the next and so on.  In other  words,  (REM A B C D) is
equivalent to (REM (REM (REM A B) C) D).

EXAMPLES

	(rem 1)					; returns 1
	(rem 1 2)				; returns 1
	(rem 13 8)				; returns 5
	(rem 13 8 3)				; returns 2
	(rem 13.5 8)				; error: bad flt.pt. operation

COMMON LISP COMPATABILITY:
Common  LISP only allows two  arguments.  XLISP  supports  an  arbitrary
number of  arguments.  Also,  Common  LISP  allows  for  floating  point
expressions where XLISP does not support this.


remove
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(remove <expr> <list-expr> [ { :test | :test-not } <test> ] )
	<expr>		-	the expression to remove - an atom or list
	<list-expr>	-	the list to remove from 
	<test>		-	optional test function (default is EQL)

DESCRIPTION

REMOVE  searches  through  <list-expr>  for <expr>.  If <expr> is found,
REMOVE  returns  the list with the <expr>  deleted.  All  occurances  of
<expr> are  deleted.  If <expr> is not found,  then the  <list-expr>  is
returned  unaltered.  You may  specify  your own test with the :TEST and
:TEST-NOT keywords followed by the test you which to perform.  Note that
this  operation  is  non-destructive,  it  does  not  modify  or  affect
<list-expr> directly - it creates a modified copy.

EXAMPLES

	(setq mylist '(a b c d it e f))		; set up a list
	(remove 'it mylist)			; returns (A B C D E F)
	(print mylist)				; prints (A B C D IT E F)
						;   note that MYLIST is not
						;   affected 
	(setq mylist '(a b c b d b))		; change list to include
						;   duplicates
	(remove 'b mylist)			; returns (A C D)

	(setq alist '( (a) (b) (it) (c)))	; set up another list
	(remove '(it) alist)			; returns ((A) (B) (IT) (C))
						;   the EQ test doesn't work
						;   for lists
	(remove '(it) alist :test 'equal)	; returns ((A) (B) (C))

	(setq slist '( "a" "b" "it" "c"))	; set up yet another list
	(remove "it" slist)			; returns ("a" "b" "c")
	(remove "it" slist :test-not 'equal)	; returns ("it") - REMOVE
						;   takes away everything but IT

NOTE:
The  REMOVE  function  can work  with a list or  string  as the  <expr>.
However, the default EQL test does not work with lists or strings,  only
symbols  and  numbers.  To make  this  work,  you need to use the  :TEST
keyword along with EQUAL for <test>.

COMMON LISP COMPATABILITY:
XLISP does not support  the  :FROM-END,  :START,  :END,  :COUNT and :KEY
keywords which Common LISP does.


remove-if
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(remove-if <test> <list-expr> )
	<test>		-	the test function to be performed
	<list-expr>	-	the list to remove from 

DESCRIPTION

REMOVE-IF  searches  through  <list-expr>  and removes any elements that
pass the <test>.  Note that this operation is  non-destructive,  it does
not modify or affect <list-expr>  directly - it creates a modified copy.

EXAMPLES

	(setq mylist '(1 2 3 4 5 6 7 8))	; set up a list
	(remove-if 'oddp mylist)		; returns (2 4 6 8)
	(remove-if 'evenp mylist)		; returns (1 3 5 7)
	(print mylist)				; prints (1 2 3 4 5 6 7 8)
						;   note that MYLIST is not
						;   affected 

	(setq mylist '(a nil b nil c))		; set up a list
	(remove-if 'null mylist)		; returns (A B C)

COMMON LISP COMPATABILITY:
XLISP does not support  the  :FROM-END,  :START,  :END,  :COUNT and :KEY
keywords which Common LISP does.


remove-if-not
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(remove-if-not <test> <list-expr> )
	<test>		-	the test function to be performed
	<list-expr>	-	the list to remove from 

DESCRIPTION

REMOVE-IF-NOT searches through <list-expr> and removes any elements that
fail the <test>.  Note that this operation is  non-destructive,  it does
not modify or affect <list-expr>  directly - it creates a modified copy.

EXAMPLES

	(setq mylist '(1 2 3 4 5 6 7 8))	; set up a list
	(remove-if-not 'oddp mylist)		; returns (1 3 5 7)
	(remove-if-not 'evenp mylist)		; returns (2 4 6 8)
	(print mylist)				; prints (1 2 3 4 5 6 7 8)
						;   note that MYLIST is not
						;   affected 

	(setq mylist '(a nil b nil c))		; set up a list
	(remove-if-not 'null mylist)		; returns (NIL NIL)

COMMON LISP COMPATABILITY:
XLISP does not support  the  :FROM-END,  :START,  :END,  :COUNT and :KEY
keywords which Common LISP does.


remprop
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(remprop <symbol> <property> )
	<symbol>	-	the symbol with a property list
	<property>	-	the property name being removed

DESCRIPTION

REMPROP removes the <property> from the <symbol>.  The function  returns
a NIL.  If the <property>  does not exist, there is no error  generated.
The  <symbol>  must be an  existing  symbol.  Property  lists are  lists
attached  to any user  defined  variables.  The lists are in the form of
(name1 val1 name2 val2 ....).  Any number of properties  may be attached
to a single variable.

EXAMPLES

	(setq person 'bobby)			; create a var with a value
	(putprop person 'boogie 'last-name)	; add a LAST-NAME property
	(putprop person 'disc-jockey 'job)	; add a JOB property
	(get person 'last-name)			; retrieve LAST-NAME - boogie
	(get person 'job)			; retrieve JOB - disc-jockey
	(get person 'height)			; non-existant - returns NIL
	(remprop person 'job)			; remove JOB
	(remprop person 'height)		; remove non-existant

COMMON LISP COMPATIBILITY:
Common LISP does not have a REMPROP function.  It uses a SETF to achieve
this  functionality.  Porting  from  Common LISP to XLISP will work fine
since XLISP supports the SETF  modifications  of property lists and GET.
Porting from XLISP to Common LISP will require translating  REMPROP into
SETF forms.


rest
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlinit.lsp
Common LISP compatible: yes
supported on: all machines

SYNTAX

(rest <expr> )
	<expr>		-	a list or list expression

DESCRIPTION

REST  returns the  remainder  of a list or list  expression  after first
element of the list is removed.  If the list is NIL, NIL is returned.

EXAMPLES
	(rest '(a b c))				; returns (B C)
	(rest '((a b) c d))			; returns (C D)
	(rest NIL)				; returns NIL
	(rest 'a)				; error: bad argument type
	(rest '(a))				; returns NIL

	(setq sisters '(virginia vicki cindy))	; set up variable SISTERS
	(first sisters)				; returns VIRGINIA
	(rest sisters)				; returns (VICKI CINDY)

NOTE:
The REST function is set to the same  code as CDR.  


&rest
________________________________________________________________________

type: keyword
location: built-in
source file: xleval.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

&rest [ <rest-arg> ]
	<rest-arg>	-	rest argument symbol

DESCRIPTION

In XLISP, there are several times that you define a formal argument list
for a body of code (like DEFUN,  DEFMACRO,  :ANSWER and LAMBDA).  All of
the formal  arguments  that are  defined are  required  to appear in the
invocation  of the  defined  function  or  operation.  If there  are any
&OPTIONAL  arguments defined, they will be filled in order.  If there is
a &REST  argument  defined, and all the required  formal  arguments  and
&OPTIONAL  arguments are filled, any and all further  parameters will be
passed into the function via the <rarg> argument.  There can be only one
<rest-arg> argument for &REST.  If there are insufficient parameters for
any of the &OPTIONAL or &REST  arguments, they will contain NIL.  At the
end of the  function or  operation  execution,  these local  symbols and
their values are are removed.

EXAMPLES

	(defun foo 				; define function FOO
	  (a b &optional c d &rest e)		;   with some of each argument
	  (print a) (print b) 			;
	  (print c) (print d) 			;   print out each
	  (print e))				;
	(foo)					; error: too few arguments 
	(foo 1)					; error: too few arguments 
	(foo 1 2)				; prints 1 2 NIL NIL NIL
	(foo 1 2 3)				; prints 1 2 3 NIL NIL
	(foo 1 2 3 4)				; prints 1 2 3 4 NIL
	(foo 1 2 3 4 5)				; prints 1 2 3 4 (5)
	(foo 1 2 3 4 5 6 7 8 9)			; prints 1 2 3 4 (5 6 7 8 9)


	(defun my-add 				; define function MY-ADD
	  (num1 &rest num-list &aux sum)	;   with 1 arg, rest, 1 aux var
	  (setq sum num1)			;   clear SUM
	  (dotimes (i (length num-list) )	;   loop through rest list
	     (setq sum (+ sum (car num-list)))  ;      add the number to sum
	     (setq num-list (cdr num-list)))	;      and remove num from list
	  sum)					;   return sum when finished
	(my-add 1 2 3 4)			; returns 10
	(my-add 5 5 5 5 5)			; returns 25


restore
________________________________________________________________________

type: function (subr)  
location: built-in
source file: xldmem.c  xlimage.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(restore <file> )
	<file>		-	a string or symbol for the name of the file 

DESCRIPTION

The RESTORE  function  restores  the  previously  saved XLISP  workspace
(system state) from the specified file.  The <file> may be a string or a
symbol.  If the  <file>  does not  include a '.wks'  suffix,  it will be
extended to be called  <file>.wks.  If successful,  RESTORE will print a
message saying

	[ returning to the top level ]

and will not return any value.  If RESTORE  fails, it will  return  NIL.
There can be several saved workspaces.  These workspaces can be restored
as often as desired.

EXAMPLES
	(defun myfoo (fee fi) 			; create a function
		(+ fee fi))
	(setq myvar 5)				; set MYVAR to value 5
	myvar					; returns 5
	(save 'farp)				; save workspace in FARP.wks

	(setq myvar "garp")			; change MYVAR to "garp"
	myvar					; returns "garp"

	(restore 'farp)				; restore workspace
	myvar					; returns 5

FILE NAMES:
In the PC and DOS world, all file names and extensions  ("FOO.BAT")  are
automatically made uppercase.  In using XLISP, this means you don't have
to  worry  about  whether  the  name  is  "foo.bat",  "FOO.BAT"  or even
"FoO.bAt" - they will all work.  However, in other file systems (UNIX in
particular),  uppercase and lowercase do make a difference.  So, in UNIX
if you do a (open 'foo-file :direction :output), this will create a file
named  "FOO-FILE"  because  XLISP  uppercases  its symbols.  If you do a
(open  "foo-file"  :direction  :output),  this will  create a file named
"foo-file"  because UNIX doesn't uppercase its file names.  Another case
is if you do (save 'world), this will create the file  "WORLD.wks".  So,
if you are having  trouble  with opening and  accessing  files, check to
make sure the file name is in the proper case.


return
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(return  [ <expr> ] )
	<expr>		-	an expression

DESCRIPTION

The RETURN  special  form  allows the  return of an  arbitrary  value at
arbitrary  times within 'block'  constructs  (DO, DO*, DOLIST,  DOTIMES,
LOOP, PROG and PROG*).  The <expr> will be returned by the outer 'block'
construct.  A NIL will be returned  by the outer  'block'  construct  if
there is no <expr>  specified.  If RETURN is used without being within a
valid 'block'  construct, an error is generated:  "error:  no target for
RETURN".

EXAMPLES

	(prog (i) 				; PROG form
	  (print i) (RETURN "foo") (print j))	; prints  NIL     returns "foo"

	(dotimes (i 10) 			;
	  (if (eql i 5) (RETURN 20) 		;
	  		(princ i)))		; prints  01234	  returns 20

	(prog1 (print "hi") (RETURN "foo"))	; prints  "hi"
						; error: no target for RETURN

	(return 9)				; error: no target for RETURN 


return-from
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(return-from  <name> [ <expr> ] )
	<name>		-	an unevaluated symbol for the block name
	<expr>		-	an expression

DESCRIPTION

The RETURN-FROM  special form allows the return of an arbitrary value at
arbitrary  times  within  a  'named-block'   construct  (BLOCK)  of  the
specified  <name>.  The <expr> will be returned by the BLOCK  construct.
A NIL will be  returned  by the  BLOCK  construct  if there is no <expr>
specified.  If  RETURN-FROM  is used without  being within a valid BLOCK
construct, an error is generated:  "error:  no target for RETURN".

EXAMPLES

	(block out 				; outer BLOCK
	   (print "outer")			; 
	   (block in 				; inner BLOCK
		(print "inner")			;
		(return-from out "all done")	;
		(print "won't get here")	;
	   )					;
	)					; prints "outer"
						; prints "inner"
						; returns "all done"

	(return-from nobody 9)			; error: no target for RETURN 


reverse
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(reverse <list-expr> )
	<list-expr>	-	a list or list expression

DESCRIPTION

The REVERSE function reverses the <list-expr>.  The reversed list is the
returned value.  The reversal  process only occurs on the 'top-level' of
the <list-expr>.  If there are nested  sub-lists, these are left intact.

EXAMPLES

	(reverse NIL)				; returns NIL
	(reverse 'a)				; error: bad argument type 
	(reverse '(a))				; returns (A)
	(reverse '(a b c))			; returns (C B A)
	(reverse '((a b) (c d) (e f)))		; returns ((E F) (C D) (A B))
	(reverse (list (+ 1 2) (+ 3 4)))	; returns (7 3)


room
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xldmem.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(room [ <info> ] )
	<info>		-	an optional, unused expression 

DESCRIPTION

The  ROOM   function   prints   the   current   memory   statistics   to
*STANDARD-OUTPUT*.  NIL  is  always  returned.  The  message  shows  the
statistics  for total  NODES,  current  FREE  NODES,  current  number of
allocated memory  SEGMENTS, node size of the ALLOCATEd  memory segments,
TOTAL memory in bytes and total number of garbage  COLLECTIONS that have
occured since this session of XLISP started.

EXAMPLES

	(room)					; prints  Nodes:       4000
						;	  Free nodes:  1723
						;	  Segments:    4
						;         Allocate:    1000
						;	  Total:       52566
						;	  Collections: 8
						; returns NIL

COMMON LISP COMPATABILITY:
In Common LISP, the <info>  argument  controls the amount of information
that is printed.

COMMON LISP COMPATABILITY:
The  form  of  and   information   provided   by  the  ROOM   output  is
implementation dependent.  For portability, you should not count on this
information or form.


rplaca
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(rplaca <list> <expr> )
	<list>		-	the list to DESTRUCTIVELY modify
	<expr>		-	the expression to replace CAR of <list>

DESCRIPTION

RPLACA destructively modifies the CAR of <list> and replaces it with the
<expr>.  The destructive  aspect of this operation means that the actual
symbol  value  is used in the  list-modifying  operations  - not a copy.
<list>  must  evaluate to a valid list.  An atom or NIL for <list>  will
result in an error.

EXAMPLES

	(setq a '(1 2 3))			; make A with value (1 2 3)
	(setq b '(1 2 3))			; make B with value (1 2 3)
	(setq c a)				; make C point to A's value 
	(rplaca a 'new)				; returns (NEW 2 3)
	(print a)				; prints (NEW 2 3)
						; NOTE THAT A IS MODIFIED!
	(print b)				; prints (1 2 3)
						; note that B is not modified
	(print c)				; prints (NEW 2 3)
						; NOTE THAT C IS MODIFIED TOO!

	(setq a '(1 2 3))			; reset A to value (1 2 3)
	(rplaca a '(the sub list))		; returns ((THE SUB LIST) 2 3)
	(rplaca '(1 2 3) 'more)			; returns (MORE 2 3)

	(rplaca 'a 'b)				; error: bad argument type 
 	(rplaca NIL 'b)				; error: bad argument type


rplacd
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(rplacd <list> <expr> )
	<list>		-	the list to DESTRUCTIVELY modify
	<expr>		-	the expression to replace the CDR of <list>

DESCRIPTION

RPLACD destructively modifies the CDR of <list> and replaces it with the
<expr>.  The destructive  aspect of this operation means that the actual
symbol  value  is used in the  list-modifying  operations  - not a copy.
<list>  must  evaluate to a valid list.  An atom or NIL for <list>  will
result in an error.

EXAMPLES

	(setq a '(1 2 3))			; set up A with (1 2 3)
	(rplacd a 'new)				; returns (1 . NEW)
	(print a)				; prints (1 . NEW)
						; NOTE THAT A IS MODIFIED!
						; 
	(rplacd a '(a new list))		; returns (1 A NEW LIST)
	(rplacd '(1 2 3) '(more))		; returns (1 MORE)
	(rplacd 'a 'b)				; error: bad argument type
	(rplacd NIL 'b)				; error: bad argument type


save
________________________________________________________________________

type: function (subr)  
location: built-in
source file: xldmem.c  xlimage.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(save <file> )
	<file>		-	a string or symbol for the name of the file 

DESCRIPTION

The SAVE function saves the current XLISP  workspace  (system  state) to
the  specified  file.  The  <file>  may be a string or a symbol.  If the
<file>  does not  include a '.wks'  suffix,  it will be  extended  to be
called <file>.wks.  The function returns T if the workspace was properly
created  and  saved, NIL is  returned  otherwise.  There can be  several
saved workspaces.  These workspaces can be restored as often as desired.

EXAMPLES
	(defun myfoo (fee fi) 			; create a function
		(+ fee fi))
	(setq myvar 5)				; set MYVAR to value 5
	myvar					; returns 5
	(save 'farp)				; save workspace in FARP.wks

	(setq myvar "garp")			; change MYVAR to "garp"
	myvar					; returns "garp"

	(restore 'farp)				; restore workspace
	myvar					; returns 5

BUG:
The SAVE  function  generates a system error if the <file> being created
already exists.  This <file> will be modified and will not be restorable
after restarting XLISP.

NOTE:
The saved workspace size is implementation  dependent, but can be fairly
large.

FILE NAMES:
In the PC and DOS world, all file names and extensions  ("FOO.BAT")  are
automatically made uppercase.  In using XLISP, this means you don't have
to  worry  about  whether  the  name  is  "foo.bat",  "FOO.BAT"  or even
"FoO.bAt" - they will all work.  However, in other file systems (UNIX in
particular),  uppercase and lowercase do make a difference.  So, in UNIX
if you do a (open 'foo-file :direction :output), this will create a file
named  "FOO-FILE"  because  XLISP  uppercases  its symbols.  If you do a
(open  "foo-file"  :direction  :output),  this will  create a file named
"foo-file"  because UNIX doesn't uppercase its file names.  Another case
is if you do (save 'world), this will create the file  "WORLD.wks".  So,
if you are having  trouble  with opening and  accessing  files, check to
make sure the file name is in the proper case.

COMMON LISP COMPATABILITY:
The SAVE function is similar in use to the SAVE-WORLD function in Common
LISP.  The primarily difference is that SAVE-WORLD allows you to restart
everything  since it  creates  an  executable  file.  The SAVE  function
requires  you to start  XLISP up first and then do a RESTORE.  Depending
on the  operating  system that you are using, it is possible  to write a
SAVE-WORLD equivalent using SAVE, RESTORE and SYSTEM functions.


savefun
________________________________________________________________________

type: defined macro (closure)  
location: extension
source file: init.lsp
Common LISP compatible: no
supported on: all machines

SYNTAX

(savefun <function> )
	<function>	-	the name of the function or macro to be saved

DESCRIPTION

The SAVEFUN macro saves the specified  function or macro to a file.  The
file will be called  <function>.lsp.  The macro  returns  the file  name
that was created.  An error will occur if the  <function>  parameter  is
not a function or macro.

EXAMPLES
	(defun myfoo (fee fi) 			; create a function
		(+ fee fi))
	(savefun myfoo)				; saves MYFOO to "MYFOO.lsp"
	(savefun savefun)			; saves SAVEFUN to "SAVEFUN.lsp"
	(savefun 'a)				; error: bad argument type

NOTE:
The SAVEFUN macro is defined in the INIT.LSP  file.  If SAVEFUN does not
exist in your XLISP system, you might be having a problem with INIT.LSP.
Before you start XLISP, look in the directory you are currently  in, and
check to see if there is an INIT.LSP.  Another  thing to try is to put a
PRINT message in the INIT.LSP  file and make sure that it is printed out
when XLISP starts running.


second
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlinit.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(second <expr> )
	<expr>		-	a list or list expression

DESCRIPTION

SECOND returns the second element of a list or list  expression.  If the
list is NIL, NIL is returned.

EXAMPLES
	(second '(1 2 3))			; returns 2
	(second NIL)				; returns NIL

	(setq carol '(a b c))			; set up variable CAROL
	(first carol)				; returns A
	(second carol)				; returns B
	(rest carol)				; returns (B C)

	(setq children '(amanda ben))		; set up variable CHILDREN
	(second children)			; returns BEN

NOTE:
This  function is set to the same  code as CADR.  


self
________________________________________________________________________

type: symbol
location: built-in
source file: xlobj.c
Common LISP compatible: no
supported on: all machines

SYNTAX

self

DESCRIPTION

SELF evaluates to the current object when used within a message context.

EXAMPLES
	(setq my-class 				; create MY-CLASS with STATE
		(send class :new '(state)))	;
	(send my-class :answer :isnew '()	; set up initialization
		'((setq state nil) SELF))	;     returning SELF 
	(send my-class :answer :set-it '(value)	; create :SET-IT message
		'((setq state value)))		;
	(setq my-obj (send my-class :new))	; create MY-OBJ of MY-CLASS
	(send my-obj :set-it 5)			; STATE is set to 5

CONTEXT: 
SELF does not exist  except  within  the  context  of a method  and it's
execution.

NOTE:
In the previous  example,  there is a SELF in the line that  creates the
:SET-IT  message.  What this does is to return  the  object  as the last
operation when you do an :ISNEW.


send
________________________________________________________________________

type: function (subr)
location: built-in
source file: xlobj.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(send <object> <message> [<args>] )
	<object>	-	an object 
	<message>	-	message selector for object
	<arg>		-	parameter sent to object method

DESCRIPTION

The  SEND  function  is the  mechanism  used to send a  <message>  to an
<object>.  The <message> is the message  selector symbol that is used to
select a particular action (method) from the object.

EXAMPLES
	(setq myclass (send class :new '(var)))	; create MYCLASS with VAR
	(send myclass :answer :isnew '()	; set up initialization
		'((setq var nil) self))
	(send myclass :answer :set-it '(value)	; create :SET-IT message
		'((setq var value)))	
	(setq my-obj (send myclass :new))	; create MY-OBJ of MYCLASS
	(send my-obj :set-it 5)			; VAR is set to 5

BUILT-IN METHODS:
The built in methods in XLISP include:

		<message>	operation
		-------------------------------------------------------
		:ANSWER		Add a method to an object.
		:CLASS		Return the object's class.
		:ISNEW		Run initialization code on object.
		:NEW		Create a new object (instance or class).
		:SHOW		Show the internal state of the object.

MESSAGE STRUCTURE:
The normal XLISP  convention  for a <message> is to have a valid  symbol
preceeded  by a  colon  like  :ISNEW  or  :MY-MESSAGE.  However,  it  is
possible  to define a  <message>  that is a symbol  without a colon, but
this makes the code less readable.


send-super
________________________________________________________________________

type: function (subr)
location: built-in
source file: xlobj.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(send-super <message> [<args>])
	<message>	-	the message selector
	<args>		-	the optional message arguments

DESCRIPTION

The  SEND-SUPER  function  sends the specified  arguments  <args> to the
<message>  specified  method  of the  superclass.  It is  necessary  for
SEND-SUPER  to be executed  from within a method  being  performed on an
object.  It  will   return  the  result  of  sending  the   message.  If
SEND-SUPER is performed  outside of a method an error  "error:  not in a
method" will result.

EXAMPLES
	(setq a-class (send class :new '()))	; create A-CLASS 
	(send a-class :answer :show '()		; set up special SHOW method
		'((print "nobody here") self))	;
	(setq an-obj (send a-class :new))	; create AN-OBJ of A-CLASS
	(send an-obj :show)			; prints "nobody here"
	(send a-class :answer :myshow '()	; set up MYSHOW method which
		'((send-super :show )))		;     calls :SHOW in superclass
	(send an-obj :myshow)			; prints Object is ............


:sescape
________________________________________________________________________

type: keyword
location: built-in
source file: xlread.c
Common LISP compatible: no
supported on: all machines

SYNTAX

:sescape


DESCRIPTION

:SESCAPE is an entry that is used in the  *READTABLE*.  *READTABLE* is a
system  variable that contains  XLISP's data structures  relating to the
processing  of  characters  from  the  user (or  files)  and  read-macro
expansions.  The  existance  of the  :SESCAPE  keyword  means  that  the
specified  character  is to be used as a single  escape  character.  The
system defines that the the vertical bar character \ is the only defined
:SESCAPE character.

EXAMPLES

	(defun look-at (table)			; define a function to 
	 (dotimes (ch 127)			;   look in a table
	  (prog ( (entry (aref table ch)) )	;   and print out any	  
	    (case entry 			;   entries with a function
	      (:SESCAPE 			;
	          (princ (int-char ch)))	;
	      (T	    NIL))))		;
	 (terpri))				;
	(look-at *readtable*)			;  prints  \ 

CAUTION:
If you experiment  with  *READTABLE*, it is useful to save the old value
in a variable, so that you can restore the system state.


set
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(set <symbol> <expr> )
	<symbol>	-	expression that evaluates to a symbol name
				(if expression is quoted, no evaluation occurs)
	<expr>		-	an expression - which will be the new value

DESCRIPTION

SET  evaluates  <symbol> and sets <expr> as it's value.  If the <symbol>
value is quoted (via the QUOTE  special form or  read-macro  expansion),
the  <symbol>  is not  evaluated.  SET returns  the value from <expr> as
it's result.

EXAMPLES

	(set 'a 2)				; sets symbol A to value 2
	(set 'value a)				; sets symbol VALUE to value 2
	(print value)				; show the value - prints 2
	(set 'name 'myvar)			; set symbol NAME to value MYVAR
	(set name 12345)			; set symbol which is the value
						;     of NAME (MYVAR) to 12345
	(print name)				; prints MYVAR	
	(print myvar)				; prints 12345

	(set notsymbol 1)			; error: unbound variable
	(set name notvalue)			; error: unbound variable


setf
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(setf [ <place1> <expr1> ... ] )
	<placeN>	-	a field specifier which may be one of:
				<symbol>		(car <expr> )
				(cdr <expr> )		(nth <n> <expr> )
				(aref <expr> <n> )	(get <symb> <property> )
				(symbol-value <symb> )	(symbol-plist <symb> )
	<exprN>		-	an expression - which will be the new value

DESCRIPTION

SETF  evaluates the field <placeN> and sets <exprN> as it's value.  This
is a  generalized  tool that allows you to set the value of the  various
data types of the system.  SETF  returns the value from  <exprN> as it's
result.  The specific action of SETF depends on the <placeN> field.

EXAMPLES

						; SETF SYMBOL
	(setf a 123)				; set a symbol A to value 123	

						; SETF SYMBOL-VALUE
	(setq x 'y)				; make symbol X with value Y
	(setf (symbol-value x) 'z)		; set symbol that X contains (Y)
						;   to value Z
	
						; SETF LIST ELEMENTS
	(setq mylist '(a b c d))		; MYLIST with value (A B C D)
	(setf (car mylist) 'x)			; change CAR of MYLIST to X
						;   MYLIST now is (X B C D)
	(setf (cdr mylist) '(y z da-end))	; change CDR of MYLIST to 
						;   (Y Z DA-END) so that 
						;   MYLIST now is (X Y Z DA-END)
	(setf (nth 3 mylist) 'here-i-am)	; change 3rd of MYLIST to 
						;   HERE-I-AM so that MYLIST
						;   now is (X Y Z HERE-I-AM)

						; SETF AREF
	(setq myarray (make-array 5))		; make MYARRAY
	(aref myarray 2)			; get value of element 2 = NIL
	(setf (aref myarray 2) 'new-value)	; set value of element 2 to 
						;   value NEW-VALUE
	(print myarray)				; prints 
						;   #(NIL NIL NEW-VALUE NIL NIL)

						; SETF PROPERTIES
	(setq person 'joe-bob)			; make PERSON with value JOE-BOB
	(putprop person 'critic 'profession)	; set PROFESSION property to 
						;   value CRITIC
	(setf (get person 'profession) 		; change PROFESSION to value
	       'texas-critic)			;   TEXAS-CRITIC
	(setf (get person 'home) 'texas)	; add property HOME with 
						;   value TEXAS
	(symbol-plist person)			; returns property list:
						;   (HOME TEXAS 
						;    PROFESSION TEXAS-CRITIC)
	(setf (symbol-plist person) 		; change the property list 
	     '(home on-the-range 		;
	       profession movie-critic))	;
	(get person 'profession)		; now returns MOVIE-CRITIC
	(get person 'home)			; now returns ON-THE-RANGE

OPERATIONS:
	<placeN>		SETF action
	-------------------------------------------------------------------
	<symbol>                Sets the value of  <symbol> to the value
				of  <exprN>.  This  is  equivalent  to a
				(SETQ <symbol> <exprN> ).

	(car <expr> )           Sets the  first  element  of the  <expr>
				list to <exprN>.  <expr> must be a list.
				This is equivalent  to a (RPLACA  <expr>
				<exprN> ) except  that SETF will  return
				<exprN>  as the  value.  (cdr  <expr>  )
				Sets  the  tail of the  <expr>  list  to
				<exprN>.  <expr>  must  be a list.  This
				is  equivalent   to  a  (RPLACD   <expr>
				<exprN> ) except  that SETF will  return
				<exprN> as the value.

	(nth <n> <expr> )       Sets the  <n>th  element  of the  <expr>
				list to <exprN>.  <expr> must be a list.
				This  allows  you  to  set an  arbitrary
				element of a list to an arbitrary value.
				Note that the list is numbered  from the
				0th element (0, 1, 2, 3, ...).

	(aref <expr> <n> )      Sets the  <n>th  element  of the  <expr>
				array  to  <exprN>.  <expr>  must  be an
				array.  This   allows   you  to  set  an
				arbitrary  element  of an  array  to  an
				arbitrary  value.  Note that the list is
				numbered  from the 0th element (0, 1, 2,
				3,  ...).  Note  also  that  this is the
				intended  way to  set  the  value  of an
				array element.

	(get <sym> <prop> )     Sets the  <prop>  of <sym> to the  value
				<exprN>.  If <sym>  does  not  have  the
				<prop>,  one  will be  created.  This is
				equivalent  to  (PUTPROP  <sym>  <exprN>
				<prop> ).

	(symbol-value <symbol>) Sets  the  symbol's   value  to  contain
				<exprN>.  <symbol> is an expression that
				must  evaluate  to a valid  symbol  - it
				doesn't  have to exist  before the SETF,
				it just has to be a valid  symbol.  This
				is equivalent to (SET  <symbol>  <exprN>
				).

	(symbol-plist <symbol>) Sets the  property  list of  <symbol> to
				<exprN>.  This  allows you to change (or
				destroy) the entire  property  list of a
				<symbol> at one time.


set-macro-character
________________________________________________________________________

type: defined function (closure) 
location: extension
source file: init.lsp
Common LISP compatible: related
supported on: all machines

SYNTAX

(set-macro-character <char-num> <function>  [ <termflag> ] )
	<char-num>	-	an integer expression
	<function>	-	a function definition
	<termflag>	-	an expression - NIL or non-NIL

DESCRIPTION

The SET-MACRO-CHARACTER function installs the code that will be executed
when the specified  character  <char-num>  is  encountered  by the XLISP
reader.  The  <function> is placed in the  *READTABLE*  system  variable
which  contains  the  reader  table  array.  The  table  is 128  entries
(0..127)  for each of the 7-bit  ASCII  characters  that XLISP can read.
Each  entry in the  table  must be one of NIL,  :CONSTITUENT,  :SESCAPE,
:MESCAPE,  :WHITE-SPACE, a :TMACRO dotted pair or a :NMACRO dotted pair.
The SET-MACRO-CHARACTER function only allows you to put in a terminating
read-macro  function (:TMACRO) or a non-terminating  read-macro-function
(:NMACRO).  If  the   <termflag>  is  present  and  non-NIL,   then  the
<function> will be put in *READTABLE* as a :TMACRO entry.  If <termflag>
is not present or NIL, then  <function>  will be put in *READTABLE* as a
:NMACRO entry.  The <function> can be a built-in  read-macro function or
a user  defined  defun  symbol or a lambda  expression.  The  <function>
takes two parameters, an input stream specification, and an integer that
is  the  character  value.  The  <function>  should  return  NIL  if the
character  is  'white-space'  or a value  CONSed  with NIL to return the
value.  The function SET-MACRO-CHARACTER always returns T.

EXAMPLES

	(print "hi") % comment			; prints  "hi"  and gives
						; error: unbound variable - %
						; because percent is viewed 
						; as a variable
						;
	(setq semi (get-macro-character #\;))	; get semi-colon code
						;	
	(SET-MACRO-CHARACTER #\% semi T)	; set % to work as a comment
						;
	(print "hi") % comment			; prints  "hi" and no error
						; because % is now a comment
						; character in *READTABLE*

NOTE:
In the normal XLISP system the following characters have code associated
with them in the *READTABLE*:

		" # ' ( ) , ; `

NOTE:
The functions GET-MACRO-CHARACTER and SET-MACRO-CHARACTER are created in
the INIT.LSP file.  If they do not exist in your XLISP system, you might
be having a problem with  INIT.LSP.  Before you start XLISP, look in the
directory  you  are  currently  in,  and  check  to see if  there  is an
INIT.LSP.

COMMON LISP COMPATABILITY:
The SET-MACRO-CHARACTER  function is somewhat related to the Common LISP
SET-DISPATCH-MACRO-CHARACTER function.


setq
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(setq [ <symbol1> <expr1> ] ... )
	<symbolN>	-	un-evaluated symbol
	<exprN>		-	value for <symbolN>

DESCRIPTION

SETQ sets <expr> as the value of  <symbol>.  SETQ returns the value from
<expr> as it's result.

EXAMPLES

	(setq a 1)				; symbol A gets value 1
	(setq b '(a b c))			; symbol B gets value (A B C)
	(setq mynum (+ 3 4))			; symbol MYNUM gets value 7


:show
________________________________________________________________________

type: message selector
location: built-in
source file: xlobj.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(send <object> :show)
	<object>	-	an existing object

DESCRIPTION

The :SHOW  message  selector  attempts to find the 'show'  method in the
specified   <object>'s  class.  Since  the  :SHOW  message  selector  is
built-in  in the root  class  (CLASS),  this is  always a valid  message
selector.  The object must already exist.

EXAMPLES
	(setq my-class 				; create MY-CLASS with STATE
		(send class :new '(state)))	;
	(send my-class :answer :isnew '()	; set up initialization
		'((setq state nil) self))
	(send my-class :answer :set-it '(value)	; create :SET-IT message
		'((setq state value)))	
	(setq my-obj (send my-class :new))	; create MY-OBJ of MY-CLASS
	(send my-obj :show)			; returns object state including
						;   STATE = NIL
	(send my-obj :set-it 5)			; STATE is set to 5
	(send new-obj :show)			; error: unbound variable


sin
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(sin <expr> )
	<expr>		-	floating point number/expression

DESCRIPTION

The SIN  function  returns  the sine of the  <expr>.  The  <expr>  is in
radians.

EXAMPLES

	(sin 0.0)				; returns 0
	(sin .5)				; returns 0.479426
	(sin 1.0)				; returns 0.841471
	(sin (/ 3.14159 2))			; returns 1
	(sin 3.14159)				; returns 2.65359e-06
	(sin 0)					; error: bad integer operation
	(sin 1.)				; error: bad integer operation

COMMON LISP COMPATABILITY:
Common LISP allows for integer numbers, which XLISP does not support for
SIN.


sort
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(sort <list> <test> )
	<list>		-	a list containing elements to be sorted
	<test>		-	the test to use for the sort

DESCRIPTION

The SORT  function  sorts the <list> using the <test> to order the list.
The SORT function is destructive and modifies the <list>.

EXAMPLES

	(setq a '(3 1 4 1 5 9 6 7))		; returns (3 1 4 1 5 9 6 7)
	(sort a '<)				; returns (1 1 3 4 5 6 7 9)
	(print a)				; returns (1 1 3 4 5 6 7 9)
						; notice that A is modified
	(sort a '> )				; returns (9 7 6 5 4 3 1 1)

	(sort '("a" "bar" "foo") 'string> )	; returns ("foo" "bar" "a")

BUG:
XLISP returns the proper  value, but  improperly  modifies the symbol or
actual <list>.

COMMON LISP COMPATABILITY:
Common LISP allows for a :KEY keyword (which allows a specified function
to be run  before  the  ordering  takes  place),  which  XLISP  does not
support.


sqrt
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(sqrt <expr> )
	<expr>		-	floating point number/expression

DESCRIPTION

The SQRT function  calculates the square root of <expr> and returns this
result.

EXAMPLES

	(sqrt 1.0)				; returns 1
	(sqrt 2.0)				; returns 1.41421
	(sqrt 3.0)				; returns 1.73205
	(sqrt 4.0)				; returns 2
	(sqrt 5.0)				; returns 2.23607
	(sqrt -1.0)				; error: sqrt of a neg. number 
	(sqrt 2)				; error: bad integer operation

COMMON LISP COMPATABILITY:
Common LISP allows for integer numbers, which XLISP does not support for
SQRT.


*standard-input*
________________________________________________________________________

type: system variable 
location: built-in
source file: xlinit.c 
Common LISP compatible: yes
supported on: all machines

SYNTAX

*standard-input*


DESCRIPTION

*STANDARD-INPUT*  is a system variable that contains a file pointer that
points to the file where all normal  input from the  programmer  or user
comes  from.  The  default  file  for  *STANDARD-INPUT*  is  the  system
standard input device - normally the system keyboard.

EXAMPLES
	*standard-input*			; returns #<File-Stream: #2442e>

NOTE:
Be careful when modifying the  *STANDARD-INPUT*.  If you do not save the
old file pointer, you will not be able to return to normal operation and
will  need to exit  XLISP.  If the  file or  source  that you  have  set
*STANDARD-INPUT*  to does not  reset  *STANDARD-INPUT*  to its  previous
value, you will never get control back to the keyboard.


*standard-output*
________________________________________________________________________

type: system variable 
location: built-in
source file: xlinit.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

*standard-output*


DESCRIPTION

*STANDARD-OUTPUT* is a system variable that contains a file pointer that
points to the file where all normal  printing  and  messages  from XLISP
will go.  The default file for  *STANDARD-OUTPUT* is the system standard
output device - normally the screen display/crt.

EXAMPLES
	*standard-output*			; returns #<File-Stream: #24406>
	(setq old-so *standard-output*)		; save the file pointer
	(setq fp (open "f" :direction :output))	; open a new output file
	(setq *standard-output* fp)		; change where output goes
						;
	(+ 2 2)					; you won't see any messages
						; just the echo of input line
						;
	(setq *standard-output* old-so)		; restore standard output
	(close fp)				; close file

NOTE:
Be careful when modifying the *STANDARD-OUTPUT*, you will not be able to
see what you are  doing.  If you do not save the old file  pointer,  you
will not be able to return to  normal  operation  and will  need to exit
XLISP.


strcat
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(strcat [ <string1> ... ] )
	<stringN>	-	a string expression

DESCRIPTION

The STRCAT function  returns the  concatenation  of a sequence of string
expressions.  If there are no strings, an empty string is returned.

EXAMPLES

	(strcat)				; returns ""
	(strcat "a")				; returns "a"
	(strcat "a" "b")			; returns "ab"
	(strcat "ab" "cd" "ef")			; returns "abcdef"
	(strcat "f" "ire tr" "uck")		; returns "fire truck"
	(strcat 1 2)				; error: bad argument type


streamp
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(streamp <expr> )
	<expr>		-	the expression to check

DESCRIPTION

The STREAMP predicate checks if an <expr> is a stream.  T is returned if
<expr> is a stream, NIL is returned otherwise.

EXAMPLES

	(streamp *standard-input*)		; returns T - stream
	(streamp *debug-io*)			; returns T - stream
	(streamp (make-string-output-stream))	; returns T - stream
	(setq a *standard-output*)		;
	(streamp a)				; returns T - evaluates to stream

	(streamp "a")				; returns NIL - string
	(streamp #\a)				; returns NIL - character
	(streamp '(a b c))			; returns NIL - list
	(streamp 1)				; returns NIL - integer
	(streamp 1.2)				; returns NIL - float
	(streamp '*debug-io*)			; returns NIL - symbol
	(streamp 'a)				; returns NIL - symbol
	(streamp #(0 1 2))			; returns NIL - array 
	(streamp NIL)				; returns NIL - NIL


string
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(string <expr> )
	<expr>		-	a string, symbol or character expression

DESCRIPTION

The STRING function  forces the <expr> to be a string.  If the <expr> is
a  string,  it is  returned,  as is.  If the  <expr> is a  character,  a
one-character string is returned.  If the <expr> is a symbol, the symbol
is turned into a string.


EXAMPLES

	(string 'foo)				; returns "FOO"
	(string 'x)				; returns "X"
	(string "abcdef")			; returns "abcdef"	
	(string #\a)				; returns "a"
	(string #\A)				; returns "A"
	(string #\Newline)			; returns "\n"


string/=
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(string/= <string1> <string2> [ <key> <offset> ] ... )
	<string1>	-	a string expression
	<string2>	-	a string expression
	<key>		-	a keyword (one of :START1 :START2 :END1 :END2 )
	<offset>	-	an optional integer expression (for a keyword)

DESCRIPTION

The STRING/=  (string-NOT-EQUAL) function takes two string arguments.  A
non-NIL  value is  returned  if  <string1>  is not  equal to  <string2>,
otherwise  NIL is returned.  The non-NIL  value  returned is the integer
index  of  the  first   character  of  <string1>  which  is  CHAR/=  the
corresponding character of <string2>.  This test is case sensitive - the
character #\a is different (and of greater ASCII value) than #\A.

The keyword  arguments allow for accessing  substrings  within <string1>
and <string2>.  The keyword  arguments each require the keyword (:START1
:END1 :START2 :END2) and a single integer  expression as a pair with the
keyword  first and the  integer  second.  The pairs may be in any order.
The start  keywords  specify the  starting  offset of the  substring.  A
value of 0 starts  the  string at the  beginning  (no  offset).  The end
keywords  specify the ending offset of the substring.  A value of 3 ends
the string after the 3rd character (an offset of 3 characters).

EXAMPLES

	(string/= "a" "b")			; returns 0
	(string/= "a" "a")			; returns NIL
	(string/= "a" "A")			; returns 0
	(string/= "A" "a")			; returns 0
	(string/= "abc" "abc ")			; returns 3

	(string/= "J Smith" "K Smith" 		; strip off the first chars 
		   :start1 1 :start2 1)		; returns NIL
	(string/= "abc" "123456789" 		; leave just the first 3 chars 
		   :end2 3 :end1 3)		; returns 0

NOTE:
Be sure that the STRING/=  function is properly  typed in.  The '/' is a
forward  slash.  It is possible to  mistakenly  type a '\'  (backslash).
This is especially  easy because the  character  mechanism is '#\a'.  If
you do use the backslash, no error will be reported because backslash is
the single escape character and the LISP reader will evaluate 'STRING\='
as  'STRING='.  No error will be reported,  but the sense of the test is
reversed.


string<
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(string< <string1> <string2> [ <key> <offset> ] ... )
	<string1>	-	a string expression
	<string2>	-	a string expression
	<key>		-	a keyword (one of :START1 :START2 :END1 :END2 )
	<offset>	-	an optional integer expression (for a keyword)

DESCRIPTION

The STRING<  (string-LESS-THAN)  function takes two string arguments.  A
non-NIL  value is returned if  <string1>  is less than  <string2>  in an
ASCII  ordering,  otherwise NIL is returned.  The non-NIL value returned
is the integer index of the first  character of <string1> which is CHAR<
the corresponding character of <string2>.  This test is case sensitive -
the character #\a is different (and of greater ASCII value) than #\A.

The keyword  arguments allow for accessing  substrings  within <string1>
and <string2>.  The keyword  arguments each require the keyword (:START1
:END1 :START2 :END2) and a single integer  expression as a pair with the
keyword  first and the  integer  second.  The pairs may be in any order.
The start  keywords  specify the  starting  offset of the  substring.  A
value of 0 starts  the  string at the  beginning  (no  offset).  The end
keywords  specify the ending offset of the substring.  A value of 3 ends
the string after the 3rd character (an offset of 3 characters).

EXAMPLES

	(string< "a" "b")			; returns 0
	(string< "a" "a")			; returns NIL
	(string< "a" "A")			; returns NIL
	(string< "A" "a")			; returns 0
	(string< "abc" "abc ")			; returns 3
	(string< "1234567" "1234qrst")		; returns 4

	(string< "J Smith" "K Smith" 		; strip off the first chars 
		  :start1 1 :start2 1)		; returns NIL


string<=
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(string<= <string1> <string2> [ <key> <offset> ] ... )
	<string1>	-	a string expression
	<string2>	-	a string expression
	<key>		-	a keyword (one of :START1 :START2 :END1 :END2 )
	<offset>	-	an optional integer expression (for a keyword)

DESCRIPTION

The  STRING<=  (string-LESS-THAN-OR-EQUAL)  function  takes  two  string
arguments.  A non-NIL  value is returned  if  <string1>  is less than or
equal to <string2> in an ASCII ordering, otherwise NIL is returned.  The
non-NIL  value  returned is the integer index of the first  character of
<string1>  which is CHAR<= the  corresponding  character  of  <string2>.
This test is case  sensitive - the  character  #\a is different  (and of
greater ASCII value) than #\A.

The keyword  arguments allow for accessing  substrings  within <string1>
and <string2>.  The keyword  arguments each require the keyword (:START1
:END1 :START2 :END2) and a single integer  expression as a pair with the
keyword  first and the  integer  second.  The pairs may be in any order.
The start  keywords  specify the  starting  offset of the  substring.  A
value of 0 starts  the  string at the  beginning  (no  offset).  The end
keywords  specify the ending offset of the substring.  A value of 3 ends
the string after the 3rd character (an offset of 3 characters).

EXAMPLES

	(string<= "a" "b")			; returns 0
	(string<= "a" "a")			; returns 1
	(string<= "a" "A")			; returns NIL
	(string<= "A" "a")			; returns 0
	(string<= "abc" "abc ")			; returns 3
	(string<= "1234567" "1234qrst")		; returns 4

	(string<= "J Smith" "K Smith" 		; strip off the first chars 
		  :start1 1 :start2 1)		; returns 7


string=
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(string= <string1> <string2> [ <key> <offset> ] ... )
	<string1>	-	a string expression
	<string2>	-	a string expression
	<key>		-	a keyword (one of :START1 :START2 :END1 :END2 )
	<offset>	-	an optional integer expression (for a keyword)

DESCRIPTION

The STRING=  (string-EQUALITY)  function takes two string arguments.  It
checks  to see if the  string  arguments  have  the  same  values.  T is
returned  if  <string1>  is  equal  to  <string2>.  This  test  is  case
sensitive - the character #\a is different  (and of greater ASCII value)
than #\A.

The keyword  arguments allow for accessing  substrings  within <string1>
and <string2>.  The keyword  arguments each require the keyword (:START1
:END1 :START2 :END2) and a single integer  expression as a pair with the
keyword  first and the  integer  second.  The pairs may be in any order.
The start  keywords  specify the  starting  offset of the  substring.  A
value of 0 starts  the  string at the  beginning  (no  offset).  The end
keywords  specify the ending offset of the substring.  A value of 3 ends
the string after the 3rd character (an offset of 3 characters).

EXAMPLES

	(string= "a" "b")			; returns NIL
	(string= "a" "a")			; returns T
	(string= "a" "A")			; returns NIL
	(string= "A" "a")			; returns NIL
	(string= "abc" "abc ")			; returns NIL

	(string= "J Smith" "K Smith" 		; strip off the first chars 
		   :start1 1 :start2 1)		; returns T
	(string= "abc" "123456789" 		; leave just the first 3 chars 
		   :end2 3 :end1 3)		; returns NIL


string>
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(string> <string1> <string2> [ <key> <offset> ] ... )
	<string1>	-	a string expression
	<string2>	-	a string expression
	<key>		-	a keyword (one of :START1 :START2 :END1 :END2 )
	<offset>	-	an optional integer expression (for a keyword)

DESCRIPTION

The STRING>  (string-GREATER-THAN)  function takes two string arguments.
A non-NIL value is returned if <string1> is greater than <string2> in an
ASCII  ordering,  otherwise NIL is returned.  The non-NIL value returned
is the integer index of the first  character of <string1> which is CHAR>
the corresponding character of <string2>.  This test is case sensitive -
the character #\a is different (and of greater ASCII value) than #\A.

The keyword  arguments allow for accessing  substrings  within <string1>
and <string2>.  The keyword  arguments each require the keyword (:START1
:END1 :START2 :END2) and a single integer  expression as a pair with the
keyword  first and the  integer  second.  The pairs may be in any order.
The start  keywords  specify the  starting  offset of the  substring.  A
value of 0 starts  the  string at the  beginning  (no  offset).  The end
keywords  specify the ending offset of the substring.  A value of 3 ends
the string after the 3rd character (an offset of 3 characters).

EXAMPLES

	(string> "a" "b")			; returns NIL
	(string> "a" "a")			; returns NIL
	(string> "a" "A")			; returns 0
	(string> "A" "a")			; returns NIL
	(string> "abc" "abc ")			; returns NIL
	(string> "1234qrst" "12345678")		; returns 4

	(string> "J Smith" "K Jones" 		; strip off the first chars 
		  :start1 1 :start2 1)		; returns 2


string>=
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(string>= <string1> <string2> [ <key> <offset> ] ... )
	<string1>	-	a string expression
	<string2>	-	a string expression
	<key>		-	a keyword (one of :START1 :START2 :END1 :END2 )
	<offset>	-	an optional integer expression (for a keyword)

DESCRIPTION

The STRING>=  (string-GREATER-THAN-OR-EQUAL)  function  takes two string
arguments.  A non-NIL  value is returned if <string1> is greater than or
equal to <string2> in an ASCII ordering, otherwise NIL is returned.  The
non-NIL  value  returned is the integer index of the first  character of
<string1>  which is CHAR>= the  corresponding  character  of  <string2>.
This test is case  sensitive - the  character  #\a is different  (and of
greater ASCII value) than #\A.

The keyword  arguments allow for accessing  substrings  within <string1>
and <string2>.  The keyword  arguments each require the keyword (:START1
:END1 :START2 :END2) and a single integer  expression as a pair with the
keyword  first and the  integer  second.  The pairs may be in any order.
The start  keywords  specify the  starting  offset of the  substring.  A
value of 0 starts  the  string at the  beginning  (no  offset).  The end
keywords  specify the ending offset of the substring.  A value of 3 ends
the string after the 3rd character (an offset of 3 characters).

EXAMPLES

	(string>= "a" "b")			; returns NIL
	(string>= "a" "a")			; returns 1
	(string>= "a" "A")			; returns 0
	(string>= "A" "a")			; returns NIL
	(string>= "abc" "abc ")			; returns NIL
	(string>= "1234qrst" "12345678")	; returns 4

	(string>= "J Smith" "K Jones" 		; strip off the first chars 
		  :start1 1 :start2 1)		; returns 2


stringp
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(stringp <expr> )
	<expr>		-	the expression to check

DESCRIPTION

The STRINGP predicate checks if an <expr> is a string.  T is returned if
<expr> is a string, NIL is returned otherwise.

EXAMPLES

	(stringp "a")				; returns T - string
	(setq a "hi there"			; 
	(stringp a)				; returns T - evaluates to string

	(stringp #\a)				; returns NIL - character
	(stringp '(a b c))			; returns NIL - list
	(stringp 1)				; returns NIL - integer
	(stringp 1.2)				; returns NIL - float
	(stringp 'a)				; returns NIL - symbol
	(stringp #(0 1 2))			; returns NIL - array 
	(stringp NIL)				; returns NIL - NIL


string-downcase
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(string-downcase <string> [ { :start | :end } <offset> ] ... )
	<string>	-	a string expression
	<offset>	-	an optional integer expression (for a keyword)

DESCRIPTION

The  STRING-DOWNCASE  function takes a string argument and returns a new
string that has been made lower case.

The keyword  arguments allow for accessing  substrings  within <string>.
The  keyword  arguments  require a keyword  (:START or :END) first and a
single  integer  expression  second.  The :START  keyword  specifies the
starting offset for the STRING-DOWNCASE  operation on <string>.  A value
of 0 starts the string at the  beginning  (no offset).  The :END keyword
specifies the end offset for the operation on <string>.

EXAMPLES

	(string-downcase "ABcd+-12&[")		; returns "abcd+-&["
	(string-downcase "ABCDEFGH" 		;
			 :start 2 :end 4)	; returns "ABcdEFGH"

	(setq mystr "ABcdEFgh")			; set up variable
	(string-downcase mystr)			; returns "abcdefgh"
	(print mystr)				; prints  "ABcdEFgh"


string-equal
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(string-equal <string1> <string2> [ <key> <offset> ] ... )
	<string1>	-	a string expression
	<string2>	-	a string expression
	<key>		-	a keyword (one of :START1 :START2 :END1 :END2 )
	<offset>	-	an optional integer expression (for a keyword)

DESCRIPTION

The STRING-EQUAL  function takes two string arguments.  It checks to see
if  the  string  arguments  have  the  same  values.  T is  returned  if
<string1> is equal to <string2>.  This test is not case  sensitive - the
character #\a is considered to be the same as #\A.

The keyword  arguments allow for accessing  substrings  within <string1>
and <string2>.  The keyword  arguments each require the keyword (:START1
:END1 :START2 :END2) and a single integer  expression as a pair with the
keyword  first and the  integer  second.  The pairs may be in any order.
The start  keywords  specify the  starting  offset of the  substring.  A
value of 0 starts  the  string at the  beginning  (no  offset).  The end
keywords  specify the ending offset of the substring.  A value of 3 ends
the string after the 3rd character (an offset of 3 characters).

EXAMPLES

	(string-equal "a" "b")			; returns NIL
	(string-equal "a" "a")			; returns T
	(string-equal "a" "A")			; returns T
	(string-equal "A" "a")			; returns T
	(string-equal "abc" "abc ")		; returns NIL

	(string-equal "J Smith" "K Smith" 	; strip off the first chars 
		   :start1 1 :start2 1)		; returns T
	(string-equal "abc" "123456789" 	; leave just the first 3 chars 
		   :end2 3 :end1 3)		; returns NIL

NOTE:
The STRING-EQUAL function is listed in the documentation that comes with
XLISP as  STRING-EQUALP.  It  functions  properly  in the XLISP  code as
STRING-EQUAL.


string-greaterp
________________________________________________________________________

type: predicate function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(string-greaterp <string1> <string2> [ <key> <offset> ] ... )
	<string1>	-	a string expression
	<string2>	-	a string expression
	<key>		-	a keyword (one of :START1 :START2 :END1 :END2 )
	<offset>	-	an optional integer expression (for a keyword)

DESCRIPTION

The  STRING-GREATERP  function  takes two  string  arguments.  A non-NIL
value is returned if  <string1>  is greater than  <string2>  in an ASCII
ordering,  otherwise NIL is returned.  The non-NIL value returned is the
integer index of the first character of <string1> which is CHAR-GREATERP
the  corresponding  character  of  <string2>.  This  test  is  not  case
sensitive - the character #\a is considered to be the same as #\A.

The keyword  arguments allow for accessing  substrings  within <string1>
and <string2>.  The keyword  arguments each require the keyword (:START1
:END1 :START2 :END2) and a single integer  expression as a pair with the
keyword  first and the  integer  second.  The pairs may be in any order.
The start  keywords  specify the  starting  offset of the  substring.  A
value of 0 starts  the  string at the  beginning  (no  offset).  The end
keywords  specify the ending offset of the substring.  A value of 3 ends
the string after the 3rd character (an offset of 3 characters).

EXAMPLES

	(string-greaterp "a" "b")		; returns NIL
	(string-greaterp "a" "a")		; returns NIL
	(string-greaterp "a" "A")		; returns NIL
	(string-greaterp "A" "a")		; returns NIL
	(string-greaterp "abc" "abc ")		; returns NIL
	(string-greaterp "1234qrst" "12345678")	; returns 4

	(string-greaterp "J Smith" "K Jones" 	; strip off the first chars 
		  :start1 1 :start2 1)		; returns 2


string-left-trim
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(string-left-trim <trim-stuff> <string> )
	<trim-stuff>	-	a string expression
	<string>	-	a string expression

DESCRIPTION

The  STRING-LEFT-TRIM  function  takes the  <trim-stuff>  characters and
removes  them  from  the  left  end of the  <string>.  The  <trim-stuff>
characters  are an  un-ordered  set of characters to be removed - so any
character that occurs in  <trim-stuff>  is removed if it appears in left
portion of <string>.  A new string is created and returned as the result
of this function.

EXAMPLES

	(string-left-trim "." "....foo....")	; returns "foo...."
	(string-left-trim "<>" "<<<<bar>>>>")	; returns "bar>>>>"
	(string-left-trim "(.)" "..(12.34)..")	; returns "12.34).."

COMMON LISP COMPATABILITY:
Common LISP also  supports a list of characters as a valid  <trim-stuff>
argument.  An  example  of  this  is:  (STRING-TRIM  '(#\Tab  #\Newline)
mystring).  XLISP does not support this  non-string  parameter.  Porting
from XLISP will be no problem,  but  modifications  will be necessary if
porting from Common LISP code which uses a list of characters.


string-lessp
________________________________________________________________________

type: predicate function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(string-lessp <string1> <string2> [ <key> <offset> ] ... )
	<string1>	-	a string expression
	<string2>	-	a string expression
	<key>		-	a keyword (one of :START1 :START2 :END1 :END2 )
	<offset>	-	an optional integer expression (for a keyword)

DESCRIPTION

The STRING-LESSP  function takes two string  arguments.  A non-NIL value
is returned if  <string1> is less than  <string2> in an ASCII  ordering,
otherwise  NIL is returned.  The non-NIL  value  returned is the integer
index of the  first  character  of  <string1>  which is  CHAR-LESSP  the
corresponding character of <string2>.  This test is not case sensitive -
the character #\a is considered to be the same as #\A.

The keyword  arguments allow for accessing  substrings  within <string1>
and <string2>.  The keyword  arguments each require the keyword (:START1
:END1 :START2 :END2) and a single integer  expression as a pair with the
keyword  first and the  integer  second.  The pairs may be in any order.
The start  keywords  specify the  starting  offset of the  substring.  A
value of 0 starts  the  string at the  beginning  (no  offset).  The end
keywords  specify the ending offset of the substring.  A value of 3 ends
the string after the 3rd character (an offset of 3 characters).

EXAMPLES

	(string-lessp "a" "b")			; returns 0
	(string-lessp "a" "a")			; returns NIL
	(string-lessp "a" "A")			; returns NIL
	(string-lessp "A" "a")			; returns NIL
	(string-lessp "abc" "abc ")		; returns 3
	(string-lessp "1234567" "1234qrst")	; returns 4

	(string-lessp "J Smith" "K Smith" 	; strip off the first chars 
		  :start1 1 :start2 1)		; returns NIL


string-not-equal
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(string-not-equal <string1> <string2> [ <key> <offset> ] ... )
	<string1>	-	a string expression
	<string2>	-	a string expression
	<key>		-	a keyword (one of :START1 :START2 :END1 :END2 )
	<offset>	-	an optional integer expression (for a keyword)

DESCRIPTION

The  STRING-NOT-EQUAL  function  takes two string  arguments.  A non-NIL
value is returned if <string1> is not equal to <string2>,  otherwise NIL
is  returned.  The non-NIL  value  returned is the integer  index of the
first character of <string1> which is CHAR-NOT-EQUAL  the  corresponding
character of <string2>.  This test is not case sensitive - the character
#\a is considered to be the same as #\A.

The keyword  arguments allow for accessing  substrings  within <string1>
and <string2>.  The keyword  arguments each require the keyword (:START1
:END1 :START2 :END2) and a single integer  expression as a pair with the
keyword  first and the  integer  second.  The pairs may be in any order.
The start  keywords  specify the  starting  offset of the  substring.  A
value of 0 starts  the  string at the  beginning  (no  offset).  The end
keywords  specify the ending offset of the substring.  A value of 3 ends
the string after the 3rd character (an offset of 3 characters).

EXAMPLES

	(string-not-equal "a" "b")		; returns 0
	(string-not-equal "a" "a")		; returns NIL
	(string-not-equal "a" "A")		; returns NIL
	(string-not-equal "A" "a")		; returns NIL
	(string-not-equal "abc" "abc ")		; returns 3

	(string-not-equal "J Smith" "K Smith" 	; strip off the first chars 
		   :start1 1 :start2 1)		; returns NIL
	(string-not-equal "abc" "123456789" 	; leave just the first 3 chars 
		   :end2 3 :end1 3)		; returns 0

NOTE:
The STRING-NOT-EQUAL  function is listed in the documentation that comes
with XLISP as  STRING-NOT-EQUALP.  It  functions  properly  in the XLISP
code as STRING-NOT-EQUAL.


string-not-greaterp
________________________________________________________________________

type: predicate function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(string-not-greaterp <string1> <string2> [ <key> <offset> ] ... )
	<string1>	-	a string expression
	<string2>	-	a string expression
	<key>		-	a keyword (one of :START1 :START2 :END1 :END2 )
	<offset>	-	an optional integer expression (for a keyword)

DESCRIPTION

The STRING-NOT-GREATERP  function takes two string arguments.  A non-NIL
value is returned if <string1> is less than or equal to <string2>  in an
ASCII  ordering,  otherwise NIL is returned.  The non-NIL value returned
is the  integer  index of the  first  character  of  <string1>  which is
CHAR-NOT-GREATERP  the corresponding  character of <string2>.  This test
is not case  sensitive - the  character #\a is considered to be the same
as #\A.

The keyword  arguments allow for accessing  substrings  within <string1>
and <string2>.  The keyword  arguments each require the keyword (:START1
:END1 :START2 :END2) and a single integer  expression as a pair with the
keyword  first and the  integer  second.  The pairs may be in any order.
The start  keywords  specify the  starting  offset of the  substring.  A
value of 0 starts  the  string at the  beginning  (no  offset).  The end
keywords  specify the ending offset of the substring.  A value of 3 ends
the string after the 3rd character (an offset of 3 characters).

EXAMPLES

	(string-not-greaterp "a" "b")		; returns 0
	(string-not-greaterp "b" "a")		; returns NIL
	(string-not-greaterp "a" "a")		; returns 1
	(string-not-greaterp "a" "A")		; returns 1
	(string-not-greaterp "A" "a")		; returns 1
	(string-not-greaterp "abc" "abc ")	; returns 3
	(string-not-greaterp "12345" "1234qr")	; returns 4

	(string-not-greaterp "J Smith" "K Smith"; strip off the first chars 
		  :start1 1 :start2 1)		; returns 7


string-not-lessp
________________________________________________________________________

type: predicate function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(string-not-lessp <string1> <string2> [ <key> <offset> ] ... )
	<string1>	-	a string expression
	<string2>	-	a string expression
	<key>		-	a keyword (one of :START1 :START2 :END1 :END2 )
	<offset>	-	an optional integer expression (for a keyword)

DESCRIPTION

The  STRING-NOT-LESSP  function  takes two string  arguments.  A non-NIL
value is returned if <string1> is greater than or equal to  <string2> in
an  ASCII  ordering,  otherwise  NIL  is  returned.  The  non-NIL  value
returned is the integer index of the first character of <string1>  which
is CHAR-NOT-LESSP  the corresponding  character of <string2>.  This test
is not case  sensitive - the  character #\a is considered to be the same
as #\A.

The keyword  arguments allow for accessing  substrings  within <string1>
and <string2>.  The keyword  arguments each require the keyword (:START1
:END1 :START2 :END2) and a single integer  expression as a pair with the
keyword  first and the  integer  second.  The pairs may be in any order.
The start  keywords  specify the  starting  offset of the  substring.  A
value of 0 starts  the  string at the  beginning  (no  offset).  The end
keywords  specify the ending offset of the substring.  A value of 3 ends
the string after the 3rd character (an offset of 3 characters).

EXAMPLES

	(string-not-lessp "a" "b")		; returns NIL
	(string-not-lessp "a" "a")		; returns 1
	(string-not-lessp "a" "A")		; returns 1
	(string-not-lessp "A" "a")		; returns 1
	(string-not-lessp "abc" "abc ")		; returns NIL
	(string-not-lessp "1234qr" "123456")	; returns 4

	(string-not-lessp "J Smith" "K Jones" 	; strip off the first chars 
		  :start1 1 :start2 1)		; returns 2


string-right-trim
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(string-right-trim <trim-stuff> <string> )
	<trim-stuff>	-	a string expression
	<string>	-	a string expression

DESCRIPTION

The  STRING-RIGHT-TRIM  function takes the  <trim-stuff>  characters and
removes  them  from the  right  end of the  <string>.  The  <trim-stuff>
characters  are an  un-ordered  set of characters to be removed - so any
character that occurs in  <trim-stuff> is removed if it appears in right
portion of <string>.  A new string is created and returned as the result
of this function.

EXAMPLES

	(string-right-trim "." "....foo....")	; returns "....foo"
	(string-right-trim "<>" "<<<<bar>>>>")	; returns "<<<<bar"
	(string-right-trim "(.)" "..(12.34)..")	; returns "..(12.34"

COMMON LISP COMPATABILITY:
Common LISP also  supports a list of characters as a valid  <trim-stuff>
argument.  An  example  of  this  is:  (STRING-TRIM  '(#\Tab  #\Newline)
mystring).  XLISP does not support this  non-string  parameter.  Porting
from XLISP will be no problem,  but  modifications  will be necessary if
porting from Common LISP code which uses a list of characters.


string-trim
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(string-trim <trim-stuff> <string> )
	<trim-stuff>	-	a string expression
	<string>	-	a string expression

DESCRIPTION

The STRING-TRIM  function takes the <trim-stuff>  characters and removes
them from both ends of the <string>.  The <trim-stuff> characters are an
un-ordered  set of  characters  to be  removed - so any  character  that
occurs in  <trim-stuff>  is  removed if it appears  in  <string>.  A new
string is created and returned as the result of this function.

EXAMPLES

	(string-trim "." "....foo....")		; returns "foo"
	(string-trim "<>" "<<<<bar>>>>")	; returns "bar"
	(string-trim "(.)" "..(12.34)..")	; returns "12.34"

COMMON LISP COMPATABILITY:
Common LISP also  supports a list of characters as a valid  <trim-stuff>
argument.  An  example  of  this  is:  (STRING-TRIM  '(#\Tab  #\Newline)
mystring).  XLISP does not support this  non-string  parameter.  Porting
from XLISP will be no problem,  but  modifications  will be necessary if
porting from Common LISP code which uses a list of characters.


string-upcase
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(string-upcase <string> [ { :start | :end } <offset> ] ... )
	<string>	-	a string expression
	<offset>	-	an optional integer expression (for a keyword)

DESCRIPTION

The  STRING-UPCASE  function  takes a string  argument and returns a new
string that has been made upper case.

The keyword  arguments allow for accessing  substrings  within <string>.
The  keyword  arguments  require a keyword  (:START or :END) first and a
single  integer  expression  second.  The :START  keyword  specifies the
starting offset for the STRING-UPCASE operation on <string>.  A value of
0 starts  the string at the  beginning  (no  offset).  The :END  keyword
specifies the end offset for the operation on <string>.

EXAMPLES

	(string-upcase "ABcd+-12&[")		; returns "ABCD+-&["
	(string-upcase "abcdefgh" 		;
			 :start 2 :end 4)	; returns "abCDefgh"

	(setq mystr "ABcdEFgh")			; set up variable
	(string-upcase mystr)			; returns "ABCDEFGH"
	(print mystr)				; prints  "ABcdEFgh"


sublis
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(sublis <a-list> <expr> [ { :test | :test-not } <test> ] )
	<expr>		-	the expression to substitute within - an atom 
				or list
	<a-list>	-	the association list to search
	<test>		-	optional test function (default is EQL)

DESCRIPTION

SUBLIS  searches  through an <expr> and replaces each of the elements in
the <expr> that match the CAR of the  elements of the  association  list
<a-list>  with the CDR of elements of the <a-list>.  The <expr> with the
substitutions  (if any) is returned.  You may specify your own test with
the  :TEST and  :TEST-NOT  keywords  followed  by the test you  which to
perform.  The SUBLIS  function is normally  used with a dotted pair (A .
B) association  list.  It is possible to use a normal list pair (A B) or
a list of the form (A (B C)).

EXAMPLES

	(sublis '( (a . b))   '(a a))		; returns (B B)
	(sublis '( (a b))     '(a a))		; returns ((B) (B))
	(sublis '( (a (b c))) '(a a))		; returns (((B C)) ((B C)))

	(setq newlist '( (a . 1) 		; set up an association list
			 (b . 2) 		;
			 (c . 3) ))		;
	(sublis newlist '(a b c d e f b a c))	; returns (1 2 3 D E F 2 1 3)
	(sublis newlist 'a)			; returns 1

	(setq mylist '((a my-a) (b his-b) 	; set up a non-dotted pair
		       (c her-c) (d end)))	;   assoc list
	(sublis mylist '(a b c d e f g))	; returns ((MY-A) (HIS-B) 
						;          (HER-C) (END) E F G)
	(sublis mylist 'a)			; returns (MY-A)

	(setq numlist '((1 . a) (2 . b)) )	; set up a new assoc list
	(defun mytest (x y) (princ ": ") 	; set up my own test function
			    (princ x) 		;   with 2 parameters
			    (princ " ") 	;   to see what SUBLIS does
			    (princ y) (terpri)	;
			    T)			;   always return TRUE
	(sublis numlist '(3 1) :test mytest)	; prints 	: (3 1) 1
						;   returns A
						;   because the entire list
						;   succeeds with the test
						;   and so (1 . A) produces
						;   the returned value
	(sublis numlist '(1) :test-not mytest)	; prints 	: (1) 1
						;		: (1) 2
						;		: 1 1
						;		: 1 2
						;		: NIL 1
						;		: NIL 2
						;   returns (1)
						;   because SUBLIS tried to
						;   match every list/sublist
						;   against each entry in the
						;   assoc. list and failed
						;   because of the :TEST-NOT
						;   and so returned the 
						;   original list unaltered

NOTE:
The  SUBLIS  function  can work  with a list or  string  as the  <expr>.
However, the default EQL test does not work with lists or strings,  only
symbols  and  numbers.  To make  this  work,  you need to use the  :TEST
keyword along with EQUAL for <test>.

COMMON LISP COMPATABILITY:
Common  LISP  supports  the use of the :KEY  keyword  which  specifies a
function  that is  applied  to each  element  of  <a-list>  before it is
tested.  XLISP does not support this.


subseq
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlstr.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(subseq <string> <start> [ <end> ] )
	<string>	-	a string expression
	<start>		-	an integer expression
	<end>		-	an integer expression

DESCRIPTION

The SUBSEQ function extracts a substring from <string> starting with the
<start> offset and ending with the <end> offset.  The <start> offset has
a origin or 0.  The substring is returned.

EXAMPLES

	(subseq "12345678" 0)			; returns "12345678"
	(subseq "12345678" 2)			; returns "345678"
	(subseq "12345678" 2 4)			; returns "34"
	(subseq "1234" 3)			; returns "4"

	(subseq "1234" 4)			; returns ""
	(subseq "1234" 4 2)			; returns ""
	(subseq "1234" 5)			; error: string index out of 
						; 	 bounds - 5

COMMON LISP COMPATABILITY:
The SUBSEQ in Common LISP is intended  to return a portion of a sequence
-  a   SUBSEQuence.  This   function   operates  on  lists  and  vectors
(one-dimensional  arrays of data) - basically ordered data.  Strings are
just one of the valid types  operated on by SUBSEQ in Common  LISP.  The
XLISP SUBSEQ function only operates on strings.


subst
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xllist.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(subst <new-expr> <old-expr> <expr> [ { :test | :test-not } <test> ] )
	<old-expr>	-	the expression to search for 
	<new-expr>	-	the expression to replace <old-expr> with
	<expr>		-	the expression to substitute within - atom/list
	<test>		-	optional test function (default is EQL)

DESCRIPTION

SUBST  searches  through an <expr> and replaces  each of the  <old-expr>
elements  with the  <new-expr>.  The <expr> with the  substitutions  (if
any) is  returned.  You may  specify  your own test  with the  :TEST and
:TEST-NOT keywords followed by the test you which to perform.

EXAMPLES

	(subst 'new 'old '(old mid dif))	; returns (NEW MID DIF)
	(subst '(a) 'old '(old mid dif))	; returns ((A) MID DIF)
	(subst "a" 'old '(old mid dif))		; returns ("a" MID DIF)

	(defun mytest (x y) (princ x)(princ " "); define a test function
			    (princ y)(terpri)	;   that prints the arguments 
			    T )		 	;   and always returns TRUE
	(subst 'a 'b '(a b c d) :test 'mytest)	; prints (A B C D) B   returns A
	(subst 'a 'b '(a b) :test-not 'mytest)	; prints (A B) B
						;	 A B
						;	 (B) B
						;	 B B
						;	 NIL B     returns (A B)

NOTE:
The  SUBST  function  can  work  with a list or  string  as the  <expr>.
However, the default EQL test does not work with lists or strings,  only
symbols  and  numbers.  To make  this  work,  you need to use the  :TEST
keyword along with EQUAL for <test>.

COMMON LISP COMPATABILITY:
Common  LISP  supports  the use of the :KEY  keyword  which  specifies a
function  that is applied to each element of <expr> before it is tested.
XLISP does not support this.


symbol-name
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(symbol-name <symbol> )
	<symbol>	-	an expression that evaluates to a symbol name 

DESCRIPTION

The SYMBOL-NAME  function takes the <symbol>  expression and returns the
printable string of the <symbol>.  If the <symbol> had not existed, then
it will be created and INTERNed into the system symbol table *OBARRAY* -
but with it's value unbound and an empty property list.

EXAMPLES

	(symbol-name 'foo)			; returns "FOO"
	(symbol-name 'gleep)			; returns "GLEEP"

	(setq my-symbol 'flop)			; define MY-SYMBOL
	(symbol-name my-symbol)			; returns "FLOP"


symbol-plist
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(symbol-plist <symbol> )
	<symbol>	-	the symbol name with a property list

DESCRIPTION

SYMBOL-PLIST  returns the actual  property  list from the <symbol>.  The
<symbol> must be an existing,  bound  variable,  but it does not need to
have anything in it's property list.

Property  lists are lists  attached to any user defined  variables.  The
lists are in the form of (name1  val1 name2 val2  ....).  Any  number of
properties may be attached to a single variable.

EXAMPLES

	(setq person 'bobby)			; create a var with a value
	(putprop person 'boogie 'last-name)	; add a LAST-NAME property
	(putprop person 'disc-jockey 'job)	; add a JOB property
	(putprop person '(10 20 30) 'stats)	; add a STATS list
	(symbol-plist person)			; returns the property list:
						; (STATS (10 20 30)
						;  JOB DISC-JOCKEY
						;  LAST-NAME BOOGIE)


symbol-value
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(symbol-value <symbol> )
	<symbol>	-	an expression that evaluates to a symbol name 

DESCRIPTION

The SYMBOL-VALUE  function takes the <symbol> expression and returns the
current value of the <symbol>.

If the <symbol>  had not existed,  then it will be created and  INTERNed
into the system symbol table *OBARRAY* - but with it's value unbound and
an  empty  property  list.  In this  case of a  previously  non-existant
<symbol>,  since it has no bound  value,  the  SYMBOL-VALUE  will  still
report an error due to an unbound variable.

EXAMPLES

	(setq myvar 55)				; set MYVAR to value 55
	(symbol-value 'myvar)			; returns 55

	(symbol-value 'floop)			; error: unbound variable 

	(setq my-symbol 'a)			; set MY-SYMBOL to A
	(setq a '(contents of symbol a))	; set A to value -
						;   (CONTENTS OF SYMBOL A)
	(symbol-value my-symbol)		; returns (CONTENTS OF SYMBOL A)


symbolp
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xllist.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(symbolp <expr> )
	<expr>		-	the expression to check

DESCRIPTION

The  SYMBOLP  predicate  checks  if an <expr>  is a valid  symbol.  T is
returned  if <expr> is a symbol, NIL is  returned  otherwise.  An <expr>
that evaluates to an integer, function (subr or otherwise), and so on is
not a symbol.  However, the quoted  (un-evaluated) name of these objects
(like 'MYARRAY) is a valid symbol.

EXAMPLES

	(symbolp (make-symbol "a"))		; returns T - symbol
	(symbolp 'a)				; returns T - symbol

	(symbolp #(1 2 3))			; returns NIL - array
	(symbolp (lambda (x) (print x)))	; returns NIL - closure 
	(symbolp *standard-output*)		; returns NIL - stream
	(symbolp 1.2)				; returns NIL - float
	(symbolp 2)				; returns NIL - integer
	(symbolp object)			; returns NIL - object
	(symbolp "hi")				; returns NIL - string

	(symbolp #'car)				; returns NIL - subr 
	(symbolp 'car)				; returns T - it is a symbol now
	(symbolp '2)				; returns NIL - not a symbol


system
________________________________________________________________________

type: function (subr) 
location: system extenstion
source file: msstuff.c and osdefs.h and osptrs.h
Common LISP compatible: no
supported on: MS-DOS compatibles

SYNTAX

(system <command> )
	<command>	-	the OS command string to be executed

DESCRIPTION

The SYSTEM  function  will send the <command>  string to the  underlying
operating  system for execution.  After  execution of the <command>, the
SYSTEM function will return a T result if the <command> was  successful.
If the  <command>  was not  successful,  the numeric  error code will be
returned.  Any output from the  <command>  execution  will not be put in
the transcript file.

EXAMPLES

	(system "dir")				; do a PC directory listing
	(system "mycmd")			; execute a special command

NOTE:
This  function is an  extension of the XLISP  system.  It is provided in
the  MSSTUFF.C  source code file.  If your XLISP  system is built for an
IBM PC and  compatibles or generic  MS-DOS, this function will work.  If
your  system  is built on UNIX or some  other  operating  system,  it is
unlikely  that  these   functions   will  work  unless  you  extend  the
appropriate  STUFF.C file (which may be called something  different like
UNIXSTUFF.C).  The source that could be put in the  appropriate  STUFF.C
file for this extension to work on a UNIX style system is:

	/* xsystem - execute a system command */
	LVAL xsystem()
	{
	    char *cmd="COMMAND";
	    if (moreargs())
		cmd = (char *)getstring(xlgastring());
	    xllastarg();
	    return (system(cmd) == 0 ? true : cvfixnum((FIXTYPE)errno));
	}

The source that gets added to the OSDEFS.H file is:

	extern LVAL xsystem();

The source that gets added to the OSPTRS.H file is:

	{	"SYSTEM",	S,	xsystem	},


t
________________________________________________________________________

type: system constant
location: built-in
source file: xlinit.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

t

DESCRIPTION

The T constant is built into XLISP.  It represents True - as oppossed to
false (NIL).

EXAMPLES
	(setq myvar T)				; set MYVAR to True
	(setq myvar 'T)				; T and 'T both evaluate to T
	(if t (print "this will print")		; if/then/else
	      (print "this won't print"))

NOTE:
Be careful  with the T value.  It is  possible to do a SETQ on T and set
it to other values (like NIL).  Some operations will still return proper
T or NIL values, but the system will be in a bad state.


tagbody
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(tagbody  [ <expr> ... ]  )
	<expr>		-	expressions comprising the body of the block
				which may contain GOs or tags for GO  

DESCRIPTION

The TAGBODY special form is basically a 'block'  construct that contains
a block of code  (expressions)  to evaluate.  After the execution of the
TAGBODY  <expr>'s,  NIL is  returned.  The TAGBODY  special  form allows
'go-to' style branching within the 'block'  construct via the GO special
form.  To  allow  this,  each  <expr>  may  be  a  tag  or a  form.  The
tag-symbol  is the 'label' and must exist  somewhere  within the 'block'
that the GO occurs within.

EXAMPLES

	(tagbody				; build the 'block'
	   start (print "begin")		; tag - start
	 	 (GO end)			; 
		 (print "hello")		; won't ever be reached
	   end   (print "done"))		; tag - END
						; prints  "begin" "done"
						;   returns NIL


tan
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(tan <expr> )
	<expr>		-	floating point number/expression

DESCRIPTION

The TAN  function  calculates  the tangent of the <expr> and returns the
result.  The <expr> is in radians.

EXAMPLES

	(tan 0.0)				; returns 0
	(tan 1.0)				; returns 1.55741
	(tan (/ 3.14159 2))			; returns 753696
	(tan 2.0)				; returns -2.18504
	(tan 3.0)				; returns -0.142547
	(tan 3.14159)				; returns -2.65359e-06
	(tan 4.5)				; returns 4.63733


COMMON LISP COMPATABILITY:
Common LISP allows for integer numbers, which XLISP does not support for
TAN.


terpri
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c  and  xlprin.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(terpri  [ <destination> ] )
	<destination>	-	an optional destination - must be a file pointer
				or stream, the default is *standard-output*

DESCRIPTION

The TERPRI  function  prints a new-line to the specified  <destination>.
This will  terminate  the current print line for  <destination>.  NIL is
always returned as the result.  The  <destination> may be a file pointer
or a  stream.  If there is no  <destination>,  *STANDARD-OUTPUT*  is the
default.

EXAMPLES

	(terpri)				; prints  <NL>

	(setq f (open "pr" :direction :output )); create a file
	(princ "hi" f)				; returns "hi"
	(princ 727 f)				; returns 727
	(princ "ho" f)				; returns "ho"
	(terpri f)				; returns NIL
	(close f)				; file contains hi727ho\n

COMMON LISP COMPATABILITY:
Common LISP specifies that print operations with a <destination> of NIL,
will  go to  *STANDARD-OUTPUT*.  XLISP  does  not  send  the  output  to
*STANDARD-OUTPUT*   with  a  <destination>  of  NIL.  Common  LISP  also
specifies  that a  <destination>  of T will be  sent  to  *TERMINAL-IO*.
XLISP does not allow T as a valid argument for <destination>.


third
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlinit.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(third <expr> )
	<expr>		-	a list or list expression

DESCRIPTION

THIRD  returns the third  element of a list or list  expression.  If the
list is NIL, NIL is returned.

EXAMPLES
	(third '(1 2 3 4))			; returns 3
	(third NIL)				; returns NIL

	(setq kids '(junie vickie cindy chris))	; set up variable KIDS
	(first kids)				; returns JUNIE
	(second kids)				; returns VICKIE
	(third kids)				; returns CINDY
	(fourth kids)				; returns CHRIS
	(rest kids)				; returns (VICKIE CINDY CHRIS)

NOTE:
This  function is set to the same  code as CADDR.  


throw
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c and xljump.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(throw  <tag-symbol>  [ <expr> ]  )
	<tag-symbol>	-	an expression that evaluates to a symbol
	<expr>		-	an optional expression to be returned

DESCRIPTION

The CATCH and THROW  special  forms allow for non-local  exits and traps
without going through the intermediate evaluations and function returns.
The  <expr>  in THROW  specifies  what  value is to be  returned  by the
corresponding  CATCH.  If there is no <expr>, a NIL is  returned  to the
corresponding  CATCH.  If a THROW  is  evaluated  with no  corresponding
CATCH, an error is  generated  - "error:  no target for  THROW".  If, in
the  calling  process,  more  than  one  CATCH  is set up for  the  same
<tag-symbol>, the most recently  evaluated  <tag-symbol> will be the one
that does the actual catching.

EXAMPLES

	(catch 'mytag)				; returns NIL	- no THROW
	(catch 'mytag (+ 1 (+ 2 3)))		; returns 6 	- no THROW
	(catch 'mytag (+ 1 (throw 'mytag)))	; returns NIL	- caught it
	(catch 'mytag (+ 1 (throw 'mytag 55)))	; returns 55	- caught it
	(catch 'mytag (throw 'foo))		; error: no target for THROW

	(defun in (x) 				; define IN
	   (if (numberp x) (+ x x)		;   if number THEN double
        		   (throw 'math 42)))	;             ELSE throw 42
	(defun out (x)				; define OUT
	  (princ "<") (princ  (* (in x) 2))	;   double via multiply
	  (princ ">"))				;
	(defun main (x)				; define MAIN
	  (catch 'math (out x)))		;   with CATCH
	(in 5)					; returns 10
	(out 5)					; prints  <20>   returns ">"
	(main 5)				; prints  <20>   returns ">"
	(main 'a)				; prints  <	 returns 42

NOTE:
Although  CATCH  and  THROW  will  accept a  <tag-symbol>  that is not a
symbol, it will not find this  improper  <tag-symbol>.  An error will be
generated - "error:  no target for THROW".


:tmacro
________________________________________________________________________

type: keyword
location: built-in
source file: xlread.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(:tmacro . <function> )
	<function>	-	a function

DESCRIPTION

:TMACRO is an entry that is used in the  *READTABLE*.  *READTABLE*  is a
system  variable that contains  XLISP's data structures  relating to the
processing  of  characters  from  the  user (or  files)  and  read-macro
expansions.  The  existance  of  the  :TMACRO  keyword  means  that  the
specified  character is a terminal read macro.  For :TMACRO, the form of
the  *READTABLE*  entry is a dotted pair like (:TMACRO .  <function>  ).
The <function> can be a built-in  read-macro  function or a user defined
lambda expression.  The <function> takes two parameters, an input stream
specification,   and  an  integer  that  is  the  character  value.  The
<function>  should  return NIL if the  character is  'white-space'  or a
value CONSed with NIL to return the value.  The <function> will probably
read additional characters from the input stream.

EXAMPLES

	(defun look-at (table)			; define a function to 
	 (dotimes (ch 127)			;   look in a table
	  (prog ( (entry (aref table ch)) )	;   and print out any	  
	        (if (and (consp entry)		;   :TMACRO entries
	                 (equal (car entry) 	;
			        ':TMACRO))	;
	          (princ (int-char ch)))))	;
	 (terpri))				;
	 					;
	(look-at *readtable*)			;  prints "'(),;`

NOTE:
The system defines that the following are :TMACRO characters:

	\ " ` , ( ) ;

CAUTION:
If you experiment  with  *READTABLE*, it is useful to save the old value
in a variable, so that you can restore the system state.


top-level
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlbfun.c  and  xldbug.c
Common LISP compatible: no
supported on: all machines

SYNTAX

(top-level)


DESCRIPTION

The  TOP-LEVEL  function  aborts to the top level of XLISP.  This may be
from within several levels of the break loop.  This is valid for BREAKs,
ERRORs and CERRORs  (continuable  errors).  If  TOP-LEVEL  is  evaluated
while not in a break  loop, a  message  is  printed - "[ back to the top
level ]".  This  message  does not cause  XLISP to go into a break loop.
TOP-LEVEL never actually returns a value.

EXAMPLES

	(top-level)				; [ back to the top level ]

	(break "out")				; break: out		(1st)
	(break "twice")				; break: twice		(2nd)
	(top-level)				; to exit out of break loop 

KEYSTROKE EQUIVALENT:
In the IBM PC and MS-DOS  versions of XLISP, a CTRL-c key  sequence  has
the same  effect as doing a  (TOP-LEVEL).  On a  Macintosh,  this can be
accomplished by a pull-down menu or a COMMAND-t.


trace
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(trace  <function> ... )
	<function>	-	an unquoted function

DESCRIPTION

The TRACE  special form allows the tracing of user or system  functions.
TRACE returns a list  containing  the current set of functions  that are
being traced.  The <function> does not have to be currently  defined, it
can be created as part of the  execution.  The trace output  consists of
entry and exit  information.  At entry and exit of a traced  <function>,
lines will be printed of the form:

	Entering: <function>, Argument list: <arg-list>  
		.
		.
		.
	Exiting: <function>, Value: <ret-value>

EXAMPLES

	(defun foo (x) (print (car x)))		; define FOO
	(trace 'foo)				; returns (FOO)
	(trace 'car)				; returns (CAR FOO)
	(foo '(a))				; Entering: FOO, Argument list: ((A))
						;  Entering: CAR, Argument list: ((A))
						;  Exiting: CAR, Value: A
						; A
						; Exiting: FOO, Value: A
						; returns A

COMMON LISP COMPATABILITY:
The XLISP TRACE  function  does not support any keyword  options,  which
Common LISP allows.


*tracelimit*
________________________________________________________________________

type: system variable
location: built-in
source file: xlinit.c  and  xldbug.c
Common LISP compatible: no
supported on: all machines

SYNTAX

*tracelimit*


DESCRIPTION

*TRACELIMIT*  is a system  variable  that  controls  the number of forms
printed on entry to the break loop.  If *TRACELIMIT* is an integer, then
the  integer is the  maximum  number of forms that will be  printed.  If
*TRACELIMIT*  is NIL or a  non-integer,  then all of the  forms  will be
printed.  Note that  *TRACENABLE*  needs to be set to a non-NIL value to
enable the  printing  of  back-trace  information  on entry to the break
loop.

EXAMPLES

	(defun foo (x) (fee x))			; define FOO
	(defun fee (y) (break))			; define FEE
	(setq *tracenable* T)			; enable the back trace
	(setq *tracelimit* NIL)			; show all the entries
	(foo 5)					; break: **BREAK**
						; prints  Function:.....BREAK..
						;	  Function:.....FEE....
						;	  Arguments:
						;	    5
						;	  Function:.....FOO....
						; 	  Arguments:
						;	    5
	(clean-up)				; from break loop
	(setq *tracelimit* 2)			; show only 2 entries
	(foo 5)					; break: **BREAK**
						; prints  Function:.....BREAK..
						;	  Function:.....FEE....
						;	  Arguments:
						;	    5
	(clean-up)				; from break loop

NOTE:
*TRACENABLE* and *TRACELIMIT* have to do with back trace  information at
entry to a break loop and have nothing to do with TRACE and UNTRACE.


*tracelist*
________________________________________________________________________

type: system variable
location: built-in
source file: xlinit.c  and  xleval.c
Common LISP compatible: no
supported on: all machines

SYNTAX

*tracelist*


DESCRIPTION

*TRACELIST*  is a system  variable  that  contains a list of the current
functions being traced.

EXAMPLES

	(defun foo (x) (print (car x)))		; define FOO
	(trace foo)				; returns (FOO)
	(trace car)				; returns (CAR FOO)
	(print *tracelist*)			; prints  (CAR FOO)
	(untrace foo)				; returns (CAR)
	(untrace car)				; returns NIL
	(print *tracelist*)			; prints  NIL


*tracenable*
________________________________________________________________________

type: system variable
location: built-in
source file: xlinit.c  and  xldbug.c
Common LISP compatible: no
supported on: all machines

SYNTAX

*tracenable*


DESCRIPTION

*TRACENABLE* is a system variable that controls whether or not the break
loop prints any back trace  information  on entry to the break loop.  If
*TRACENABLE* is NIL, then there will be no information  printed on entry
to the break loop.  If *TRACENABLE* is non-NIL, then information will be
printed.  The INIT.LSP  initialization  file sets  *TRACENABLE*  to NIL,
which suppresses the printing.

EXAMPLES

	(defun foo (x) (fee x))			; define FOO
	(defun fee (y) (break))			; define FEE
	(setq *tracenable* T)			; enable the back trace
	(setq *tracelimit* NIL)			; show all the entries
	(foo 5)					; break: **BREAK**
						; prints  Function:.....BREAK..
						;	  Function:.....FEE....
						;	  Arguments:
						;	    5
						;	  Function:.....FOO....
						; 	  Arguments:
						;	    5
	(clean-up)				; from break loop
	(setq *tracelimit* 2)			; show only 2 entries
	(foo 5)					; break: **BREAK**
						; prints  Function:.....BREAK..
						;	  Function:.....FEE....
						;	  Arguments:
						;	    5
	(clean-up)				; from break loop

NOTE:
*TRACENABLE* and *TRACELIMIT* have to do with back trace  information at
entry to a break loop and have nothing to do with TRACE and UNTRACE.


*trace-output*
________________________________________________________________________

type: system variable 
location: built-in
source file: xlinit.c  xlio.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

*trace-output*


DESCRIPTION

*TRACE-OUTPUT*  is a system  variable  that contains a file pointer that
points to the file where all trace output goes to.  The default file for
*TRACE-OUTPUT*  is the  system  standard  error  device -  normally  the
screen.

EXAMPLES
	*trace-output*				; returns #<File-Stream: #243de>

NOTE:
*TRACE-OUTPUT*, *DEBUG-IO* and *ERROR-OUTPUT* are normally all set to the 
same file stream - STDERR.


truncate
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlmath.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(truncate <expr> )
	<expr>		-	integer or floating point number/expression

DESCRIPTION

The TRUNCATE  function  takes the <expr> and  truncates it to an integer
value and returns this result.

EXAMPLES

	(truncate 123.456)			; returns 123
	(truncate -1.49)			; returns -1
	(truncate -1.59)			; returns -1
	(truncate 123)				; returns 123
	(truncate 123.999)			; returns 123

COMMON LISP COMPATABILITY:
Common LISP allows an optional division  parameter, which XLISP does not
support.


type-of
________________________________________________________________________

type: function (subr)
location: built-in
source file: xlsys.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(type-of <expr> )
	<expr>		-	an expression to check

DESCRIPTION

The TYPE-OF function returns the type of the expression.

EXAMPLES

	(type-of NIL)				; returns NIL		
	(type-of '#(1 2 3))			; returns ARRAY	
	(type-of (lambda (x) (print x)))	; returns CLOSURE
	(type-of '(a b))			; returns CONS		
	(type-of #'savefun)			; returns CLOSURE
	(type-of '(a . b))			; returns CONS		
	(type-of *standard-output*)		; returns FILE-STREAM
	(type-of 1.2)				; returns FLONUM	
	(type-of #'do)				; returns FSUBR        
	(type-of 1)				; returns FIXNUM	
	(type-of object)			; returns OBJECT	
	(type-of "str")				; returns STRING	
	(type-of #'car)				; returns SUBR		
	(type-of 'a)				; returns SYMBOL	
	(type-of #\a)				; returns CHARACTER
	(type-of (make-string-input-stream "a")); returns UNNAMED-STREAM

COMMON LISP COMPATABILITY:
The XLISP and Common LISP  TYPE-OF  functions  are  basically  the same.
Differences between the two can occur in what the types are called (like
CHARACTER in XLISP and STANDARD-CHAR in Common LISP).  Also, Common LISP
can give additional  information - for strings, it returns a list of the
form (SIMPLE-STRING 32) where the number 32 is the string size.


*unbound*
________________________________________________________________________

type: system constant
location: built-in
source file: xlinit.c  and  xlsym.c
Common LISP compatible: no
supported on: all machines

SYNTAX

*unbound*


DESCRIPTION

*UNBOUND* is a system  constant  that is used to indicate  when a symbol
has no value.  *UNBOUND* is set to the value *UNBOUND*.  This means that
the system thinks the symbol *UNBOUND* has no value.

EXAMPLES
	*unbound*				; error: unbound variable
	(setq a 5)				; returns 5
	a					; returns 5
	(setq a '*unbound*)			; returns *UNBOUND*
	a					; error: unbound variable

unless
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(unless <test> [ <expr> ... ] )
	<test>		-	an expression - NIL or non-NIL
	<expr>		-	expressions comprising a body of code

DESCRIPTION

The UNLESS macro executes the <expr> forms if <test>  evaluates to a NIL
value.  If <test> is NIL, the value of the last  <expr> is  returned  as
the result.  If <test> is non-NIL,  NIL is returned  with none of <expr>
evaluated.

EXAMPLES

	(unless NIL)				; returns NIL
	(unless T)				; returns NIL
	(unless NIL (print "hi") 'foo)		; prints  "hi"	returns FOO
	(unless (listp "a") 			;
	      (print "not a list"))		; prints  "not a list"
						; returns "not a list"


untrace
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(untrace  <function> ... )
	<function>	-	a function name 

DESCRIPTION

The UNTRACE  special form removes  <function>  from the current  list of
traced  functions.  UNTRACE returns a list containing the current set of
functions that are being traced.  If the <function> does currently exist
or is  currently be traced,  there will be no error  reported.  If there
are no functions being traced, a NIL is returned.

EXAMPLES

	(defun foo (x) (print (car x)))		; define FOO
	(trace 'foo)				; returns (FOO)
	(foo '(a))				; Entering: FOO, Argument list: ((A))
						; A
						; Exiting: FOO, Value: A
						; returns A
	(untrace 'foo)				; returns NIL
	(untrace 'glip)				; returns NIL
	(foo '(a))				; prints  A   and returns  A

COMMON LISP COMPATABILITY:
The XLISP UNTRACE  function  does not support any options,  which Common
LISP allows.


upper-case-p
________________________________________________________________________

type: predicate function (subr) 
location: built-in
source file: xlstr.c 
Common LISP compatible: yes
versions: all machines

SYNTAX

(upper-case-p <char> )
	<char>		-	a character expression

DESCRIPTION

The UPPER-CASE-P  predicate checks if the <char>  expression is an upper
case  character.  If <char> is upper case a T is  returned,  otherwise a
NIL is returned.  Upper case characters are 'A' (ASCII decimal value 65)
through 'Z' (ASCII decimal value 90).

EXAMPLES

	(upper-case-p #\A)			; returns T
	(upper-case-p #\a)			; returns NIL
	(upper-case-p #\1)			; returns NIL
	(upper-case-p #\[)			; returns NIL


unwind-protect
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(unwind-protect <protect-form> <clean-up-form> ... )
	<protect-form>	-	a form that is to be protected
	<clean-up-form>	-	a sequence forms to execute after <protect-form>

DESCRIPTION

The UNWIND-PROTECT  special form allows the protecting (trapping) of all
forms of exit  from the  <protect-form>.  The  exits  that  are  trapped
include  errors,  THROW,  RETURN  and GO.  The  <clean-up-form>  will be
executed  in all cases - when there is an exit from  <protect-form>  and
when the form does not have exit.  UNWIND-PROTECT will return the result
from the <protect-form>, not from the <clean-up-form>s.  Errors or exits
that occur in the  <clean-up-form> are not protected.  It is possible to
trap these with another UNWIND-PROTECT.

EXAMPLES

	(unwind-protect 			;
		(+ 2 2) 			; protected form
		(print "an exit"))		; clean up form
						; prints "an exit"
						; returns 4

	(nodebug)				; to turn off break loop traps
	(unwind-protect 			;
		(+ 1 "2")			; protected form
		(print "something happened"))	; clean up form
						; error: bad argument type - "2"
						; prints "something happened"
	
	(catch 'mytag 				; 
	  (unwind-protect 			; 
	  	(throw 'mytag) 			; protected form
		(print "an exit") ) )		; clean up form
						; prints "an exit"

	(nodebug)				; to turn off break loop traps
	(unwind-protect 			;
		(throw 'notag) 			; protected form
		(print "an exit"))		; clean up form
						; error: no target for THROW
						; prints "an exit"

	(prog () 				; 
		(print "start")			;
		(unwind-protect 		;
			(go end) 		; protected form
			(print "an exit"))	; clean-up form
	  end 	(print "end") )			; prints "start"
						; prints "an exit"
						; prints "end"

	(prog () 				; 
		(print "start")			;
		(unwind-protect 		;
			(return "I'm done")	; protected form
			(print "but first"))	; clean-up form
	 	(print "won't get here") )	; prints "start"
						; prints "but first"
						; returns "I'm done"


vector
________________________________________________________________________

type: function (subr)
location: built-in
source file: xlbfun.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(vector [ <expr> ... ] )
	<expr>		-	an expression

DESCRIPTION

The VECTOR function creates an initialized  vector and returns it as the
result.  VECTOR is  essentially  a fast  method to do a  one-dimensional
MAKE-ARRAY with initial data in the vector.

EXAMPLES

	(vector 'a 'b 'c)			; returns #(A B C)
	(vector '(a b) '(c d))			; returns #((A B) (C D))
	(vector)				; returns #()
	(vector NIL)				; returns #(NIL)
	(vector 'a () 4 "s")			; returns #(A NIL 4 "s")


when
________________________________________________________________________

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(when  <test> [ <expr> ... ] )
	<test>		-	an expression - NIL or non-NIL
	<expr>		-	expressions comprising a body of code

DESCRIPTION

The WHEN  macro  executes  the  <expr>  forms if <test>  evaluates  to a
non-NIL  value.  If <test> is  non-NIL,  the value of the last <expr> is
returned as the result.  If <test> is NIL, NIL is returned  with none of
<expr> evaluated.

EXAMPLES

	(when NIL)				; returns NIL
	(when T)				; returns T
	(when T (print "hi") 'foo)		; prints  "hi"	returns FOO
	(when (listp '(a)) 			;
	      (print "a list"))			; prints  "a list"
						; returns "a list"


:white-space
________________________________________________________________________

type: keyword
location: built-in
source file: xlread.c
Common LISP compatible: no
supported on: all machines

SYNTAX

:white-space


DESCRIPTION

:WHITE-SPACE  is an entry that is used in the  *READTABLE*.  *READTABLE*
is a system variable that contains  XLISP's data structures  relating to
the  processing of  characters  from the user (or files) and  read-macro
expansions.  The existance of the  :WHITE-SPACE  keyword  means that the
specified  character may be skipped over.  The system  defines that tab,
space, return and line-feed are :WHITE-SPACE characters.

EXAMPLES

	(defun look-at (table)			; define a function to 
	 (dotimes (ch 127)			;   look in a table
	  (prog ( (entry (aref table ch)) )	;   and print out any	  
	    (case entry 			;   entries with a function
	      (NIL	    NIL)		;
	      (:CONSTITUENT NIL)		;
	      (:WHITE-SPACE (print ch))		;
	      (T	    NIL))))		;
	 (terpri))				;
	(look-at *readtable*)			;  prints  9 		tab
						;          10 		newline
						;          12 		formfeed
						;          13 		return
						;          32		space

CAUTION:
If you experiment  with  *READTABLE*, it is useful to save the old value
in a variable, so that you can restore the system state.


write-byte
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(write-byte  <expr>  [ <destination> ] )
	<expr>		-	an integer expression
	<destination>	-	an optional destination - must be a file pointer
				or stream, the default is *standard-output*

DESCRIPTION

The  WRITE-BYTE  function  writes  the  <expr>  as a single  byte to the
specified  <destination>.  Only the <expr> byte is  written.  The <expr>
must be an integer  expression.  The <expr> is returned  as the  result.
The  <destination>  may be a file  pointer  or a stream.  If there is no
<destination>, *STANDARD-OUTPUT* is the default.

EXAMPLES

	(write-byte 67)				; prints  C	returns 67
	
	(setq fp (open "t" :direction :output))	; create file 
	(write-byte 65 fp)			; returns 65
	(write-byte 66 fp)			; returns 66
	(write-byte 10 fp)			; returns 10
	(close fp)				; returns NIL
	(read (open "t" :direction :input))	; returns AB

COMMON LISP COMPATABILITY:
Common LISP specifies that print operations with a <destination> of NIL,
will  go to  *STANDARD-OUTPUT*.  XLISP  does  not  send  the  output  to
*STANDARD-OUTPUT*   with  a  <destination>  of  NIL.  Common  LISP  also
specifies  that a  <destination>  of T will be  sent  to  *TERMINAL-IO*.
XLISP does not allow T as a valid argument for <destination>.


write-char
________________________________________________________________________

type: function (subr) 
location: built-in
source file: xlfio.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(write-char  <char-expr>  [ <destination> ] )
	<char-expr>	-	a character expression
	<destination>	-	an optional destination - must be a file pointer
				or stream, the default is *standard-output*

DESCRIPTION

The  WRITE-CHAR   function  writes  the  <char-expr>  to  the  specified
<destination>.  Only the <char-expr> is written.  The  <char-expr>  must
be a character  expression.  The  <char-expr> is returned as the result.
The  <destination>  may be a file  pointer  or a stream.  If there is no
<destination>, *STANDARD-OUTPUT* is the default.

EXAMPLES

	(write-char #\C)			; prints  C	
	
	(setq fp (open "t" :direction :output))	; create file 
	(write-char #\A fp)			; returns #\A
	(write-char #\B fp)			; returns #\B
	(write-char #\Newline fp)		; returns #\Newline
	(close fp)				; returns NIL
	(read (open "t" :direction :input))	; returns AB


COMMON LISP COMPATABILITY:
Common LISP specifies that print operations with a <destination> of NIL,
will  go to  *STANDARD-OUTPUT*.  XLISP  does  not  send  the  output  to
*STANDARD-OUTPUT*   with  a  <destination>  of  NIL.  Common  LISP  also
specifies  that a  <destination>  of T will be  sent  to  *TERMINAL-IO*.
XLISP does not allow T as a valid argument for <destination>.


zerop
________________________________________________________________________

type: predicate function (subr)
location: built-in
source file: xlmath.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(zerop <expr> )
	<expr>		-	the numeric expression to check

DESCRIPTION

The ZEROP  predicate  checks to see if the number  <expr> is zero.  T is
returned  if the  number  is  zero,  NIL is  returned  otherwise.  A bad
argument  type  error  is  generated  if the  <expr>  is  not a  numeric
expression.

EXAMPLES

	(zerop 0)				; returns T
	(zerop 0.0)				; returns T
	(zerop 99999.9)				; returns NIL
	(zerop -0.000000000002)			; returns NIL

	(zerop 'a)				; error: bad argument type
	(setq a 0)				; set value of A to 0
	(zerop a)				; returns T


