1
2
3
4lisp(3gv)
5lisp(3gv)
6
7
8NAME
9       geomview lisp interpreter
10
11NOTE
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 ].
23
24
25SYNOPSIS
26       #include "lisp.h"
27
28       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
57       LDEFINE(name, ltype, doc)
58
59       LDECLARE((name,  LBEGIN,                   ...,
60LEND));
61
62
63
64
65
66
67Geometry Center            Oct 22 1992                          1
68
69
70
71
72
73lisp(3)                                                   lisp(3)
74
75
76DESCRIPTION
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
83       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
88       The main steps in using the lisp interpreter are
89
90         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
97       For  example  the following code defines a single function
98       "f" and executes commands from standard input:
99
100            #include  "lisp.h"              Lake  *lake;
101LObject *obj, *val;
102
103           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
109       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.
125
126
127
128Geometry Center            Oct 22 1992                          2
129
130
131
132
133
134lisp(3)                                                   lisp(3)
135
136
137       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).
145
146
147FUNCTION 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
154           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
159              LDECLARE(("f", LBEGIN,                        LINT,
160&a,                            LFLOAT,    &b,
161LEND));                sprintf(buf,"%f",a+b);                s  =
162strdup(buf);              return LNew(LSTRING, &s);            }
163
164       The important things about this function are:
165
166           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
176           2. The use of the LDECLARE macro.  More about this be‐
177low.
178
179            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
185       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)".
189
190
191
192Geometry Center            Oct 22 1992                          3
193
194
195
196
197
198lisp(3)                                                   lisp(3)
199
200
201       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
210               LDECLARE((    name,    LBEGIN,
211<argspec>,                       ...,                        LEND
212));
213
214       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.
225
226
227STOP 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.
231
232
233EVALUATION 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
240           LHOLD, LLIST, &list,
241
242       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.
245
246
247ARRAYS
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
254
255
256
257Geometry Center            Oct 22 1992                          4
258
259
260
261
262
263lisp(3)                                                   lisp(3)
264
265
266       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
274            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
283       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
288       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.
291
292
293OPTIONAL 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
306       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
315
316
317
318Geometry Center            Oct 22 1992                          5
319
320
321
322
323
324lisp(3)                                                   lisp(3)
325
326
327       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.
330
331
332LISP 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
338           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
358
359
360CUSTOM 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
372       struct LType {
373
374         /* name of type */          char *name;
375
376         /* size of corresponding C type */          int size;
377
378
379
380
381Geometry Center            Oct 22 1992                          6
382
383
384
385
386
387lisp(3)                                                   lisp(3)
388
389
390          /*  extract  cell value from obj */          int (*fro‐
391mobj)(/* LObject *obj, void *x */);
392
393         /* create a new LObject of this type */          LObject
394*(*toobj)(/* void *x */);
395
396          /* free a cell of this type */          void (*free)(/*
397void *x */);
398
399         /* write a cell value  to  a  stream  */            void
400(*write)(/* FILE *fp, void *x */);
401
402          /*  test equality of two cells of this type */
403int (*match)(/* void *a, void *b */);
404
405         /* pull a cell value from a  va_list  */            void
406(*pull)(/* va_list *a_list, void *x */);
407
408          /*  parse  an  object  of this type */          LObject
409*(*parse)(/* Lake *lake */);
410
411         /* magic number; always set to  LTypeMagic  */
412int magic;
413
414       };
415
416       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.
421
422
423LISTS
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.
431
432
433LAKES  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
444
445
446
447Geometry Center            Oct 22 1992                          7
448
449
450
451
452
453lisp(3)                                                   lisp(3)
454
455
456       object type.
457
458       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.
462
463
464HIDDEN LAKE ARGUMENTS AND OTHER WET THINGS
465       This  section  is  X  rated.  Don’t read it unless you are
466       really serious.
467
468
469       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
477           LObject *func(Lake *lake, LList *args)
478
479       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
488
489       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
496
497
498       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
510
511
512
513Geometry Center            Oct 22 1992                          8
514
515
516
517
518
519lisp(3)                                                   lisp(3)
520
521
522       (scalar) argument keywords:
523
524           LObject *func(Lake *lake, LList *args)            Lake
525*mylake;            LDECLARE(("myfunc",  LBEGIN
526LARG_LAKE,  &mylake,                        ...
527LARG_END));
528
529       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.
534
535
536BUGS
537       The documentation is incomplete.
538
539
540AUTHOR
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.
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577Geometry Center            Oct 22 1992                          9
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
Impressum