WHAT'S Lily?
------------

This directory contains the Lily (LIsp LibrarY) C++ class library which gives 
C++ programmers the capability to write LISP-style code.

I think Lily will be useful in academia for instructors who
want to teach artificial intelligence techniques with C++.  The
garbage collection mechanism employed by Lily is slow which will make it
unattractive for commercial use.

DISCLAIMER
----------

This is the first release of Lily.  My hope is that lots of people will
be interested in Lily.  If that turns out to be the case then I will gladly 
enhance Lily and its documentation.  But for now, I just want to get Lily 
out there and get some feedback.

DOCUMENTATION
-------------

Documentation is minimal.  The "Lily User's Guide" (in file lily.txt) provides
a good overview of the architecture of Lily -- the document is unfinished.  
All of the example programs are from Winston's book "LISP Second Edition" so
you will be much better off if you have a copy.  Steele's "Common LISP" 
describes the behavior of the LISP functions.  

FEEDBACK
--------

If you have any comments or suggestions regarding Lily please send them to:

sheldon@kong.gsfc.nasa.gov

COMPILERS SUPPORTED
-------------------

Lily works well with GNU g++ version 2.4.5 (and probably earlier releases).

Lily works with Turbo C++ for Windows but not with Turbo C++ (though the
current version hasn't been tested with Turbo C++ for Windows).

Lily does *not* work with AT&T's cfront because cfront does not handle 
temporary objects very well.

If you try Lily on another compiler please inform me as to whether it
works or not (see FEEDBACK) so I can include that information in future
releases.

INSTALLATION
------------

Anonymously get lily-0.1.tar.gz from sunsite.unc.edu (152.2.22.81) in
directory /pub/Linux/...?

Uncompress and untar Lily:

	% gunzip -c lily-0.1.tar.gz | tar xvf -

To make the Lily library and all the examples just type 'make'.

CONTENTS
--------

	Lily Class Library

		multarg.h|c 
		read.h|c 
		integer.h|c 
		real.h|c
		function.h|c
		symbol.h|c 
		cons.h|c 
		object.h|c 
		friend.h|c
		dbg.h
		lily.h		-- #include this file to use Lily

	Lily Examples

		fchain.h|c mnfchain.c fchain.dat	chapter 18 Winston
		interp.h|c mninterp.c				chapter 23 Winston
		match.h|c mnmatch.c	match.dat		chapter 17 Winston
		testlily.c				validates Lily functions and garbage collection

	GNU libg++ files used for hash tables

		Pix.h
		fcthash.h|c
		fctmap.h|c
		fctmapds.h
		fctmapvh.h|c

	Miscellaneous

		Makefile
		lily.txt	-- Lily documentation
		COPYING.LIB	-- GNU LIBRARY GENERAL PUBLIC LICENSE
		count.		-- This file is created when you run any Lily program.
					-- The last line of 'count.' should look something like:
					-- 	  count-- = 0, Cons is 131840
					-- which indicates the Lily garbage collector worked 
					-- properly.

EXAMPLES
--------

The best way to learn about Lily is to examine the example programs.
The example programs are Lily translations of Lisp programs found
in the book "LISP", second edition by Winston and Horn.
Most or all of chapters 17, 18, and 23 are implemented in the examples.
Chapter 17: Symbolic Pattern Matching
Chapter 18: Expert Problem Solving Using Rules and Streams
Chapter 23: LISP in LISP


FUTURE ENHANCEMENTS
-------------------

The following features have already been tried with Lily:

	logical operators (or, and, etc)
	inlining
	using yacc/lex (or Bison/Flex) for parsing LISP expressions
	LISP -> Lily translator
	Customized free store management (Object ctors and dtors)

I didn't include these features because I didn't want to clutter things.
(OK, over time, I've lost some or all of these features.)
If there is sufficient interest in Lily I would be happy to provide them.

The LISP->Lily translator is probably the most interesting.  It's actually
quite easy to do.  First you write the translator in LISP.  If you have
a LISP system you can run the translator on itself to produce the Lily 
version.  If you don't, then you rewrite the translator in Lily,
apply it to the LISP version, and compare the output to your Lily version.
Of course, the translator will only handle things that are supported in Lily.
But you could write the translator such that it would flag unrecognized 
constructs which could later be translated by hand.

It's fun to try and extend Lily to provide more and more LISP functionality.
In the future we could add all the various data structures to LISP (hash
tables, arrays, etc) and also try to support all of the control structures.
But I don't think that should be done.  My belief is that Lily provides
heterogeous list processing capabilities like those found in LISP, but in
terms of all the other features that LISP provides, well if you want all
of them then you should use LISP.  But that's just my opinion.

COPYING
-------

Lily uses the GNU Library General Public License (see the file COPYING.LIB).

MISCELLANEOUS
-------------

All text files in this directory (including this README) use 4-space tabs.

Have fun!

Roger Sheldon
November 1993
