Minimalist Lisp Reader for C code
---------------------------------

This code used to support more of the Common Lisp reader.  Cliff,
however, argued both eloquently and convincingly that it should support
no more than necessary.  Therefore, it is somewhat minimalist -- it
supports only what it has to in order to parse the configuration file.

What's Supported?  What's Not Supported?
----------------------------------------

There are four types of lisp object:
	Symbol
	String
	Number
	Cons Cell

An atom is a number if it starts with a digit (0-9) or a sign (+,-).
It's a string if it starts with a double-quote (").  Otherwise it's a
symbol.

Numbers are *VERY* restrictive.

Numbers come in one type -- integer -- and no other numbers are
supported.  No floats.  No complex.  No rational.  No bignums -- if it
doesn't fit into 32 bits, then tough.  And it makes no attempt to detect
overflow.

The read-base is always 10 -- there is no way of changing it.

If DO_SHARP is defined when the code is compiled, then #b, #o, and #x
are recognized for base 2, 8, and 16, respectively.  These are supported
solely because they're used by the config file.

Numbers must consist solely of an optional sign {+,-} and one or more
digits {0,1,2,3,4,5,6,7,8,9,a,b,c,d,e,f,A,B,C,D,E,F}.

The sign, if present, must be first.

Strings begin at a double-quote (") and continue until the next
double-quote.

Character Types
---------------

Characters come in the same types as mentioned in the CLtL book.
The following is a brief description of each of the types:

Whitespace:
-----------
THe characters listed on page 336 of CLtL (table 22-1: Standard
Character Syntax Types) as whitespace, are treated as whitespace.

Illegal:
--------
All non-whitespace control characters are illegal.  All non-ASCII
characters are illegal.

Constituent:
------------
Those listed on page 336 as constituent characters are treated as
constituent characters.

Multiple Escape:
----------------
Vertical-bar  (|) is treated as a multiple escape character.  It may be
ripped out of a future version.

Single Escape:
--------------
Back-slash(\) is treated as a single escape character.  It may be ripped
out of a future version.

Macros:
-------
Single-quote ('), double-quote ("), open parenthesis {(}, close
parenthesis {)}, and semicolon (;) are supported.

Back-quote (`), comma (,), and sharp-sign (#) are not supported.

Note: this means that read-time conditionals (#+ and #-), balanced
comments (#| .... |#), and alternate number bases (#b, #o, #x, #Nr), and
the like are *NOT* supported.

[Note: #b, #o, and #x are supported if DO_SHARP is defined.  The others
aren't.]

Why doesn't it support more?
----------------------------

Part of the argument in favor of making this code somewhat minimalist,
is to help alleviate creeping featurism.

The hope, in part, is that by making it minimalist, it'll be easier to
resist cries requesting that various features be added.

By making it small, it should be easier to maintain and easier to
remember just what syntax it does accept -- and hence what can be placed
in the configuration file.

Packages
--------
There is *NO* understanding of packages.  Thus the following:

	*World-Configuration*
	CMI:*World-Configuration*
	CMI::*World-Configuration*

are three *DIFFERENT* symbols -- two of which happen to contains colons.
A colon is *NOT* treated specially in any fashion.

Garbage
-------
There is, of course, no garbage collector.  The reader does not create
garbage.  But, if you fail to store the pointer returned by Fread, then
*YOU* will create garbage.  If you have no further use for a lisp
object, you should call Ffree on that object.

NIL, 's_exp, and end of file
----------------------------
Both () and nil are recognized as denoting the special object NIL.
The C symbol is Qnil.  It prints as nil.

's_exp is recognized as a short-hand for (quote s_exp).  The C symbol is
Qquote.  It prints as quote.

Each call to yyparse returns one s-exp or an error.  Once end of file is
reached, the symbol Qeof is returned.  This symbol prints as <<eof>>.

Support functions
-----------------
Cons is, of necessity, supported;  as is a two list version of nconc
(which I have decided to call nconc2, for lack of a better name).

For debugging, a subset of print is supported.  It's not a completely
compatible subset.  It's provided *ONLY* for debugging.

When you are done with a lisp structure, you must free it as there is no
garbage collector.

Before calling yyparse, you must initialize the parser.

These support function all have names starting with a capital f.
Thus, the names are Fcons, Fnconc2, Fprint, Ffree, and Finitialize.

A function called xmalloc is used for allocating storage.  It calls
malloc and aborts if malloc fails to allocate the storage.

EVAL
----
There is *NO* eval here.  None.  Nada.  Zero.  Zip.  NONE.  How you
write things, matters.  Just because they'd be evaluated the same by a
full fledged lisp system, doesn't mean that they're the same here.
I say again: there is *NO* eval here.

Comments, Flames, Questions
---------------------------
If you have any comments, flames, or questions let me know.

David
