\begindata{text,539456488}
\textdsversion{12}
\template{help}
\define{global
}
\chapter{ELI

The Embedded Lisp Interpreter

}
\section{What ELI is

}\leftindent{
The Embedded Lisp Interpreter is a library of functions implementing a Lisp 
interpreter.  This library can be compiled into your application, giving your 
program the ability to interpret Lisp expressions.  This is a simple way to 
provide a powerful programmability feature for your code.  Currently, ELI is 
featured as the system underlying \italic{\helptopic{FLAMES}}, the Filtering 
Language for the Andrew MEssage System.


The Lisp procedures built in to ELI are documented in the file 


\leftindent{/usr/andrew/doc/eli/procs.doc}


The additional procedures made available by FLAMES are documented in 


\leftindent{/usr/andrew/doc/ams/Flames.pgr}

}
\section{How ELI Works

}
\leftindent{When the Embedded Lisp Interpreter is linked into your code, 
approximately 200 functions become available; for most applications, you'll 
probably need only about 10 or 20 of these.  These functions are fully 
documented (and indexed) in 


\leftindent{/usr/andrew/doc/eli/libcalls.pgr

/usr/andrew/doc/eli/libcalls.idx}


These functions take care of things like evaluating s-expressions, allocating 
Lisp objects, recovering from Lisp errors, etc.

}
\section{Using ELI

}
\leftindent{To build a program using the ELI library, you must link in the 
libraries 


\leftindent{/usr/andrew/lib/libeli.a

/usr/andrew/lib/librxp.a

/usr/andrew/lib/libplumber.a

/usr/andrew/lib/libutil.a

/usr/andrew/lib/librauth.a

/usr/andrew/lib/afs/syslib.a}


Also, any source files that use ELI functions or data types must include the 
header file 


\leftindent{/usr/andrew/include/eli.h}


You must declare one global variable whose name must be EliProcessInfo, and 
whose type is EliProcessInfo_t.  Furthermore, for each namespace that you wish 
to maintain (it is possible to have more than one), you must declare a "state 
variable" of type EliState_t.  A pointer to this variable is passed to most 
ELI functions.  Before any ELI operations can take place, you must have an 
initialized state variable; state variables are initialized with the function 
EliInit.  Among other things, EliInit places the definitions for the standard 
Lisp primitives in a namespace.  (Primitives are Lisp functions like SETQ 
which cannot easily be defined in Lisp itself.)


Once you have an initialized state variable, it is possible to parse 
s-expressions ("sexps") that are in files, in strings or on the standard 
input, and then to evaluate them and manipulate the results.  ELI defines 
about 60 Lisp primitives such as SETQ and CONS; these are documented in 


\leftindent{/usr/andrew/doc/eli/procs.doc}


You can write new primitives and compile them into your code; primitives 
defined by a client can be incorporated into a namespace along with the 
predefined primitives by using the function EliPrimDef.  A complete discussion 
of how to write code that is to be compiled with ELI appears in 


\leftindent{/usr/andrew/doc/eli/programs.pgr}

}
\section{ELI Concepts

}
\leftindent{Most ELI concepts are the usual Lisp concepts, with a few notable 
exceptions.  One exception is the idea that one can have separate namespaces. 
 When one SETQ's a symbol, or DEFUN's a function (for instance), these symbols 
are stored in a "symbol table" which is contained within a namespace; hence, 
different namespaces need not contain the same SETQs or DEFUNs.


Another important, non-standard concept is that of the "trace stack".  The 
trace stack makes it possible to avoid unpredictable garbage collection 
kicking in and locking up the system.  Every Lisp objects in ELI (cons cells, 
symbols, etc.) has a reference count which is always equal to the number of 
other Lisp objects pointing to it.  However, simply assigning variables to 
point to objects does not alter their reference count; that is to say, if 
\italic{foo} is a cons cell and \italic{bar} is any s-expression, then the 
call


\indent{\typewriter{EliCons_BindCar(st, foo, bar);}}


will cause \italic{bar} to become the car of the cons cell \italic{foo} and 
will increment the reference count of \italic{bar} (\italic{st} here 
represents the state variable).  However, simply saying


\indent{\typewriter{var = bar;}}


does not alter bar's reference count (obviously).  To prevent bar's reference 
count from dropping below zero by some subsequent operation (thus 
de-allocating bar before we want it to go away), we have the trace stack. 
 Whenever a Lisp object is allocated, a pointer to it is pushed onto the trace 
stack, causing its reference count to immediately become 1.  Later, when you 
are sure that you no longer need those objects which have recently been 
allocated, you can use EliTraceStk_Purge to pop all the elements off of the 
trace stack, thus decrementing the reference counts of the objects that the 
stack points to.  Then, and only then, might some reference counts go to zero 
and the associated objects be de-allocated.  It is possible, but unwise, to 
bypass the trace-stack scheme (by allocating objects (say, cons cells) with 
eliCons_GetNew instead of EliCons_GetNew).  See the file 


\leftindent{/usr/andrew/doc/eli/programs.pgr}


for more on writing ELI applications.

}
\section{Preferences

}
\leftindent{ELI uses the *.elipath preference in a user's preferences file; by 
default, the elipath is "/usr/andrew/lib/eli".  This preference is used by the 
LOAD primitive and dictates the sequence of directories to be searched when 
looking for ELI libraries (Lisp source libraries).  There is also the 
capability to define a "client" library path; for example, FLAMES (the 
Filtering Language for the Andrew MEssage System) makes additional use of 
preferences by looking for the *.flamespath preference, which is a sequence of 
directories to use for the LOAD primitive \italic{before} using the 
directories in the *.elipath preference.}\leftindent{

}
\section{Program Author}


\leftindent{Bob Glickstein}


\section{Related Tools

}
Some of the information on ELI is in /usr/andrew/doc/eli.  Use your favorite 
editor to see these files.


\leftindent{types.pgr    (internal data structures)

libcalls.pgr    (reference manual of internal function calls)

libcalls.idx    (an index to the former)

procs.doc	(reference to Lisp primitives and library functions)

programs.pgr    (programming examples)}


There are also several help files related to ELI and Flames.  Select 
(highlight) one of the italicized names and choose "Show Help on Selected 
Word" from the pop-up menu to see the help file for:


\leftindent{\italic{\helptopic{bglisp}

\helptopic{flames}


}}

\begindata{bp,537558784}
\enddata{bp,537558784}
\view{bpv,537558784,1755,0,0}
Copyright 1992 Carnegie Mellon University and IBM.  All rights reserved.

\smaller{\smaller{$Disclaimer: 

Permission to use, copy, modify, and distribute this software and its 

documentation for any purpose is hereby granted without fee, 

provided that the above copyright notice appear in all copies and that 

both that copyright notice, this permission notice, and the following 

disclaimer appear in supporting documentation, and that the names of 

IBM, Carnegie Mellon University, and other copyright holders, not be 

used in advertising or publicity pertaining to distribution of the software 

without specific, written prior permission.



IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS 

DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 

ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO EVENT 

SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER 

BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY 

DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, 

WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS 

ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 

OF THIS SOFTWARE.

 $

}}\enddata{text,539456488}
