\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}