1lisp(3gv)
5lisp(3gv)
6NAME
9 geomview lisp interpreter
10NOTE
12 This document describes the geomview 1.3 lisp interpreter.
13 This version is incompatible with previous versions in
14 several ways. Since the previous one was used mostly just
15 by Geometry Center staff, I am not going to write a docu‐
16 ment detailing the changes. The geomview lisp interpreter
17 is not very well documented in general because I am
18 strongly considering phasing it out and replacing it with
19 a real lisp interpreter in a future version of geomview.
20 If you have any questions about the current version or how
21 to convert programs from an older version please contact
22 me directly [ mbp@geomtech.com ].
23SYNOPSIS
26 #include "lisp.h"
27 void LInit();
29 Lake * LakeDefine(FILE *streamin, FILE *streamout,
30void *river);
31 void LakeFree(Lake *lake);
32 LObject * LNew(LType *type, LCell *cell);
33 LObject * LRefIncr(LObject *obj);
34 void LRefDecr(LObject *obj);
35 void LWrite(FILE *fp, LObject *obj);
36 void LFree(LObject *obj);
37 LObject * LCopy(LObject *obj);
38 LObject * LSexpr(Lake *lake);
39 LObject * LEval(LObject *obj);
40 LObject * LEvalSexpr(Lake *lake);
41 LList * LListNew();
42 LList * LListAppend(LList *list, LObject *obj);
43 void LListFree(LList *list);
44 LList * LListCopy(LList *list);
45 LObject * LListEntry(LList *list, int n);
46 int LListLength(LList *list);
47 int LParseArgs(char *name, Lake *lake, LList *args,
48...);
49 int LDefun(char *name, LObjectFunc func, char
50*help);
51 void LListWrite(FILE *fp, LList *list);
52 LInterest * LInterestList(char *funcname);
53 LObject * LEvalFunc(char *name, ...);
54 int LArgClassValid(LType *type);
55 void LHelpDef(char *key, char *message);
56 LDEFINE(name, ltype, doc)
58 LDECLARE((name, LBEGIN, ...,
60LEND));
61Geometry Center Oct 22 1992 1
68lisp(3) lisp(3)
74DESCRIPTION
77 Geomview contains a minimal lisp interpreter for parsing
78 and evaluating commands. This lisp interpreter is part of
79 the "‐loogutil" library and thus any program which links
80 with this library may use the interpreter. This provides
81 a simple but powerful way to build up a command language.
82 This manual page assumes that you are familiar with the
84 syntax of lisp. The first part describes the basics of
85 using the interpreter. Some gory details that don’t con‐
86 cern most users then follow.
87 The main steps in using the lisp interpreter are
89 1. call Linit() to initialize the interpreter
912. make calls to LDefun(), one for each lisp function you want
92the interpreter to know about 3. define the
93"i/o lake" 4. parse input with calls to LSexpr() and
94evaluate the resulting lisp objects with LEval() (or
95use LEvalSexpr() to combine both steps).
96 For example the following code defines a single function
98 "f" and executes commands from standard input:
99 #include "lisp.h" Lake *lake;
101LObject *obj, *val;
102 LInit(); LDefun("f", f, NULL);
104lake = LakeDefine(stdin, stdout, NULL); while (!fe‐
105of(stdin)) { obj = LSexpr(lake); val =
106LEval(obj); LFree(obj); LFree(val);
107 }
108 The second argument to LDefun() is a function pointer;
110 LDefun() sets up a correspondence between the string "f"
111 and the function f, which is assumed to have been previ‐
112 ously declared. The section FUNCTION DEFINITIONS below
113 gives the expected call syntax and behavior of such func‐
114 tions. (The third argument to LDefun() is a pointer to a
115 string which documents the function and may be NULL if you
116 don’t care about documentation.) LakeDefine() defines an
117 i/o lake; this is a generalization of the notion of an i/o
118 stream. Most programs don’t need to use the generaliza‐
119 tion, though, and can simply pass FILE pointers as LakeDe‐
120 fine()’s first two arguments and NULL as the third one.
121 The section LAKES below gives the details for those who
122 are interested. LSexpr() [which stands for Lisp Symbolic
123 EXPRession] parses a single lisp expression from the lake,
124 returning a lisp object which represents that expression.
125Geometry Center Oct 22 1992 2
129lisp(3) lisp(3)
135 The lisp object is returned as an LObject pointer, which
138 points to an opaque structure containing a representation
139 of the expression. LEval() then evaluates the object; it
140 is during the call to LEval() that the action of the
141 expression takes place. Note that the last two lines of
142 code in this example could have been replaced by the sin‐
143 gle line LEval(LSexpr(lake)) or, more efficiently, by LEv‐
144 alSexpr(lake).
145FUNCTION DEFINITIONS
148 The functions defined by calls to LDefun() are expected to
149 have a certain call syntax; LEval() calls them when it
150 encounters a call to the lisp function named with the cor‐
151 responding string. The macro LDEFINE is provided for
152 declaring them. For example:
153 LDEFINE(f, LSTRING, "(f a b) returns a string repre‐
155senting the0um of the integer a with the floating point number
156b.") { int a; float b;
157 char buf[20], *s;
158 LDECLARE(("f", LBEGIN, LINT,
160&a, LFLOAT, &b,
161LEND)); sprintf(buf,"%f",a+b); s =
162strdup(buf); return LNew(LSTRING, &s); }
163 The important things about this function are:
165 1. It is declared with the LDEFINE macro, the general
167syntax of which is LDEFINE(name, type, helpstr).
168name should be a valid C identifer and will be used
169to construct the actual name of the C function by
170prepending an ’L’ and the name of the help string
171by prepending an ’H’. type should be a lisp object
172type identifier (see below) and determines the type
173of object that the function returns. helpstr is a documentation
174 string.
175 2. The use of the LDECLARE macro. More about this be‐
177low.
178 3. It returns an LObject *. All lisp functions must
180actually return a value. If you don’t care what
181value they return you can return one of the pre‐de‐
182fined values Lnil or Lt (and specify LVOID as the
183type in the LDEFINE header).
184 This particular example is a function which takes two
186 arguments, an int and a float, and returns a string object
187 representing their sum. A lisp call to this function
188 might look like "(f 1 3.4)".
189Geometry Center Oct 22 1992 3
193lisp(3) lisp(3)
199 The LDECLARE macro, defined in lisp.h, sets up the corre‐
202 spondence between variables in the C code and arguments in
203 the lisp call to the function. Note that the arguments to
204 LDECLARE are delimited by *two* pairs of parentheses (this
205 is because C does not allow macros with a variable number
206 of arguments; LDECLARE thus actually takes one argument
207 which is a parenthesized list of an arbitrary number of
208 items). The general usage of LDECLARE is
209 LDECLARE(( name, LBEGIN,
211<argspec>, ..., LEND
212));
213 where name is the name of the function (as specified to
215 LDefun()). <argspec> is an argument specification, which
216 in general consists of a lisp type identifier followed by
217 an address. The identifier indicates the data type of the
218 argument. The builtin type identifiers are LINT (inte‐
219 ger), LFLOAT (float), LSTRING (string), LLOBJECT (lisp
220 object), and LLIST (lisp list). Applications may define
221 additional types whose identifiers may also be used here;
222 see the section CUSTOM LISP TYPES below for details.
223 There may be any number of <argspec>’s; the last must be
224 followed by the special keyword LEND.
225STOP HERE
228 Most users of the lisp interpreter can stop reading this
229 man page here. What follows is only used in advanced sit‐
230 uations.
231EVALUATION OF FUNCTION ARGUMENTS
234 Normally the lisp interpreter evaluates function arguments
235 before passing them to the function; to prevent this eval‐
236 uation from happening you can insert the special token
237 LHOLD in an LDECLARE argument specification before the
238 type keyword. For example
239 LHOLD, LLIST, &list,
241 specifies an unevalutated list argument. This feature is
243 really useful only for LLIST, LLOBJECT, and array types
244 (see below) since the other types evalutate to themselves.
245ARRAYS
248 In general an <argspec> in the LDECLARE call consists of a
249 keyword followed by the address of a scalar data type.
250 Since it is relatively common to use a lisp list to repre‐
251 sent an array of values, however, the special <argspec>
252 keyword LARRAY is provided for dealing with them. It has
253 a different syntax: it should be followed by a lisp type
254Geometry Center Oct 22 1992 4
258lisp(3) lisp(3)
264 identifier which specifies the type of the elements of the
267 array and then by two addresses ‐‐‐ the address of an
268 array and the address of an integer count. Upon entry to
269 LDECLARE the count specifies how many elements may be
270 written into the array. LDECLARE then modifies this num‐
271 ber to indicate the number of entries actually parsed.
272 For example:
273 LDEFINE(myfunc, ...) { float
275f[2]; int fn = 2; LDECLARE(("myfunc",
276LEBGIN LHOLD, LARRAY, f, &fn,
277 LEND)); /* at this point the
278value of fn has been modified to be the number of
279entries actually appearing in the list argument;
280and this number of values have been written into
281the array f. */ ... }
282 defines a function "myfunc" which takes a list of up to 2
284 floats as its only argument. Valid calls to "myfunc"
285 would be "(myfunc ())", "(myfunc (7))", and "(myfunc (7
286 8))".
287 Note the use of LHOLD; this is necessary because otherwise
289 the lisp system would attempt to evaluate the list as a
290 function call before passing it off to myfunc.
291OPTIONAL ARGUMENTS
294 Normally the lisp interpreter will generate (to stderr) a
295 reasonable error message if a function is called with
296 fewer arguments than were specified in LDECLARE. Some
297 functions, however, may have some arguments that are
298 optional. You can define a function which takes optional
299 arguments by putting the keyword LOPTIONAL after the last
300 required argument in the LDECLARE call. Any arguments
301 specified in the list after that are considered optional;
302 the interpreter doesn’t complain if they are not supplied.
303 Note that all optional arguments must come after all
304 required arguments.
305 Normally excess arguments also elicit an error message.
307 The LREST keyword allows control over this situation. If
308 LREST is followed by a pointer to an LList * variable,
309 then trailing arguments are parsed, evaluated (unless
310 LHOLD was used), and the list of them is stored in the
311 given variable. (Note that the value is an LList, not an
312 LObject of type LLIST ‐‐ if there are no excess arguments,
313 the value is NULL, not an empty LLIST.) If LREST is fol‐
314 lowed by a NULL pointer, excess arguments are silently
315Geometry Center Oct 22 1992 5
319lisp(3) lisp(3)
325 ignored. LREST might be useful when a function’s argument
328 types are not known. It’s not necessary to specify LEND
329 after LREST.
330LISP OBJECTS
333 The basic data type of the lisp interpreter is the lisp
334 object; it is represented by an LObject pointer, which
335 points to an opaque data structure. The functions for
336 manipulating lisp objects (i.e. the object’s methods) are:
337 LNew(): creates a new lisp object of the given type
339with the given value. The "type" argument is one
340of the values LSTRING or LLIST, or a type pointer
341defining a custom object type (see CUSTOM OBJECT
342TYPES below). LRefIncr(): increments
343the reference count of a lisp object. The lisp
344interpreter uses the convention that when a proce‐
345dure returns a lisp object, the caller owns the
346object and thus has responsibility for freeing
347it. LRefIncr() can be used to increment the ref‐
348erence count of an existing object about to be re‐
349turned. New objects created by LNew() have their
350reference count initialized to 1 and hence do not
351need to be LRefIncr()’ed. LRefDecr(): decrements the
352reference count of a lisp object. This should
353probably not be called by application programs; it
354is used internally. LWrite(): writes a formatted
355string representation of a lisp object to a
356stream. LFree(): free the space assoicated with a
357lisp object LCopy(): construct a copy of a lisp object
358CUSTOM OBJECT TYPES
361 In addition to the predefined lisp object types you may
362 define your own custom types. This is done by construct‐
363 ing a structure containing various function pointers for
364 manipulating objects of your new type. The address of
365 this structure is then the type identifier for this type
366 and may be used in LDECLARE <argspec>’s and in LNew()
367 calls. (The type names LINT, LSTRING and the other
368 builtin types are actually pointers to predefined struc‐
369 tures.) The structure is of type LType as defined in
370 lisp.h:
371 struct LType {
373 /* name of type */ char *name;
375 /* size of corresponding C type */ int size;
377Geometry Center Oct 22 1992 6
382lisp(3) lisp(3)
388 /* extract cell value from obj */ int (*fro‐
391mobj)(/* LObject *obj, void *x */);
392 /* create a new LObject of this type */ LObject
394*(*toobj)(/* void *x */);
395 /* free a cell of this type */ void (*free)(/*
397void *x */);
398 /* write a cell value to a stream */ void
400(*write)(/* FILE *fp, void *x */);
401 /* test equality of two cells of this type */
403int (*match)(/* void *a, void *b */);
404 /* pull a cell value from a va_list */ void
406(*pull)(/* va_list *a_list, void *x */);
407 /* parse an object of this type */ LObject
409*(*parse)(/* Lake *lake */);
410 /* magic number; always set to LTypeMagic */
412int magic;
413 };
415 The void * pointers in the above point to objects of the
417 type you are defining. For examples of how to define new
418 types see the code in lisp.c that defines the string and
419 list types. See also the file TYPES.DOC in the lisp
420 source code directory for further details.
421LISTS
424 The LList pointer is used to refer to objects of type
425 LLIST, which implement a linked list. The operations on
426 these objects are LListNew(), LListLength(), LListEntry(),
427 LListAppend(), LListCopy(), and LListFree(). These are
428 mostly used internally by the lisp system but are avail‐
429 able for outside use. Maybe I’ll write more documentation
430 for them later if it seems necessary.
431LAKES The Lake structure is a generalization of an input stream.
434 It contains three members: an input FILE pointer
435 ("streamin"), an output FILE pointer ("streamout"), and an
436 arbitrary pointer ("river"). The input FILE pointer is
437 required; the lisp interpreter assumes that every lake has
438 a valid input file pointer. The output FILE pointer is
439 required if you do any operations that result in the
440 intepreter producing any output. The third pointer may
441 point to whatever you want. The lisp interpreter itself
442 does not directly refer to this pointer. It may be used
443 by the parser that you supply when defining a new lisp
444Geometry Center Oct 22 1992 7
448lisp(3) lisp(3)
454 object type.
457 The term "Lake" is supposed to connote something more gen‐
459 eral than a stream; it also seemed particularly appropri‐
460 ate since this interpreter was written in the City of
461 Lakes.
462HIDDEN LAKE ARGUMENTS AND OTHER WET THINGS
465 This section is X rated. Don’t read it unless you are
466 really serious.
467 The lisp interpreter works by first parsing (LSexpr()) an
470 expression then evaluating it (LEval()). The LDECLARE
471 macro is a mechanism which allows both the syntax (for
472 parsing) and the semantics (for evaluation) of an expres‐
473 sion to be specified in the same convenient place ‐‐‐ at
474 the top of the C function which implements the function.
475 The call syntax of all such C functions is
476 LObject *func(Lake *lake, LList *args)
478 When parsing a call to the corresponding lisp function,
480 LSexpr() calls func with that lake pointer, and with args
481 pointing to the head of the list in the parse tree corre‐
482 sponding to this function call. LDECLARE parses the argu‐
483 ments in the call (by reading them from the lake) and
484 appends them to this list. (Note: the head of this list
485 is the function itself, so the first argument becomes
486 entry #2 in the list.)
487 When evaluating the function call, LEval() calls func with
490 lake=NULL and with args pointing to the call’s argument
491 list. (In this case the first entry of the list is the
492 first argument.) LDECLARE then converts the arguments in
493 the list into the appropriate C data types, writing their
494 values into the addresses in the <argspec>s.
495 One side‐effect of using lake=NULL as the signal to evalu‐
499 ate rather than to parse is that the value of the lake
500 pointer is not available at evaluation time. Some func‐
501 tions, however, may want to do something with the lake
502 they were parsed from. For example, the "write" function
503 in geomview writes data to the output stream associated
504 with its input stream. (In geomview these streams are all
505 stored in a general "Pool" structure which is retained as
506 the "river" member of the lake.) The special token LLAKE
507 may be used to cause the lake pointer to be saved in the
508 args list at parse time and written into a variable at
509 evaluation time. It is used exactly like the other
510Geometry Center Oct 22 1992 8
514lisp(3) lisp(3)
520 (scalar) argument keywords:
523 LObject *func(Lake *lake, LList *args) Lake
525*mylake; LDECLARE(("myfunc", LBEGIN
526LARG_LAKE, &mylake, ...
527LARG_END));
528 At evaluation time LDECLARE will set mylake to have the
530 value that lake had at parse time. This looks just like a
531 specification for an argument to the lisp function but it
532 is not ‐‐‐ it is just a way to tell LDECLARE to remember
533 the lake pointer between parse‐ and evaluation‐time.
534BUGS
537 The documentation is incomplete.
538AUTHOR
541 The lisp interpreter was written mostly by Mark Phillips
542 with lots of input and moral support from Stuart Levy and
543 Tamara Munzner.
544Geometry Center Oct 22 1992 9
578