/[cvsroot]/skandha4/info/slisp-1
ViewVC logotype

Contents of /skandha4/info/slisp-1

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1.1.1 - (show annotations) (download) (vendor branch)
Tue May 25 09:39:21 1999 UTC (21 years, 5 months ago) by jsp
Branch: biostr, MAIN
CVS Tags: skandha4, skandha4_1_6, dsg_1_0, HEAD
Branch point for: skandha4_pub, autoconf
Changes since 1.1: +0 -0 lines
ANSI C version of Skandha4


1 This is Info file slisp, produced by Makeinfo version 1.68 from the
2 input file slisp.texi.
3
4 This file documents slisp, (skandha-lisp), an extendable xlisp.
5
6 Copyright @copyright 1994 University of Washington Digital Anatomist
7 Program by Jeff Prothero (jsp@biostr.washington.edu) and Jim Brinkley
8 See slisp/SLISPCOPYING for details
9
10 
11 File: slisp, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
12
13 Slisp Programmer's Online Documentation
14
15 Slisp (skandha lisp) is based on Xlisp, by David Betz. It consists
16 of basic xlisp, together with an organization that makes it relatively
17 easy to add new C functions to xlisp, which then become part of the
18 primitive lisp functions. This manual documents slisp, as well as
19 xlisp itself. Applications, such as skandha4, which are built on slisp,
20 are documented in their own separate nodes in the info tree, thereby
21 allowing different applications to be included at different sites. An
22 overview of the chapters is provided in the Introduction.
23
24 The particular slisp application(s) available at your site depends
25 on the modules that are included, but all applications will include
26 the primitive functions documented here. Additional primitive functions
27 provided in an application will be documented at the info node
28 describing that application.
29
30 Normally, to run an slisp application just type the name of the
31 application at the shell prompt. If it is present the basic slisp
32 application is called sl.
33
34 Modified for generic slisp, by Jim Brinkley, from skandha4
35 documentation by Jeff Prothero
36
37 * Menu:
38
39 * Introduction::
40 * Slisp Tutorial::
41 * Xlisp Tutorial::
42 * Xlisp Objects Tutorial::
43 * Xlisp Language Reference::
44 * Xlisp Internals::
45
46 
47 File: slisp, Node: Introduction, Next: Slisp Tutorial, Prev: Top, Up: Top
48
49 Introduction
50 ************
51
52 This manual documents slisp for programmers intending to write
53 application lisp code and/or add new C-coded primitives to xlisp. This
54 manual is *not* intended for nonprogrammers who only want to use the
55 system.
56
57 Slisp (skandha-lisp) is an extensible version of David Betz's
58 `76704.47@CompuServe.COM' 'xlisp', a small lisp interpreter written in
59 portable C.
60
61 The particular xlisp version used derives from Niels P Mayer's
62 `mayer@hplnpm.hpl.hp.com' 'winterp' package for x-windows, and
63 incorporates much work by Tom Almy `toma@sail.labs.tek.com', among
64 others. It has been modified by adding hooks which make it easy to
65 add new functions to the interpreter without actually modifying the
66 interpreter source files, turning xlisp into a generic application
67 engine which can - and is - being used for a variety of applications.
68 Within our own group slisp is the basis for skandha4, a 3-D graphics
69 package; siserver, a lisp interface to a structural information
70 database, and others. We hope that by providing the basic slisp
71 environment many other similar applications will be developed.
72
73 Slisp uses the hybrid implementation strategy of emacs, winterp,
74 xlispstat, the Nasa Panel Library, autocad and other recent packages,
75 using a small portable lisp interpreter as a flexible high-level
76 application programming language, together with application-specific
77 C-coded primitives to provide speed and special facilities where needed.
78
79 Quick Overview of the chapters in this manual.
80
81 Slisp Tutorial
82 An introduction to Slisp, which becomes progressively more
83 detailed. How to program in LISP using an existing slisp
84 application, how to download a personal copy of slisp in order to
85 add new c functions, the file organization of slisp, how to
86 configure slisp for a new machine, how to create a new slisp
87 application, how to create a new slisp c module that is to be part
88 of an slisp application, and how to add new primitives.
89
90 Xlisp Tutorial
91 A simple introduction to LISP programming in xlisp. This is a
92 fairly generic introduction to lisp programming suitable for
93 programmers who haven't used the language before.
94
95 Programmers new to lisp will want to read this chapter thoroughly
96 and work the examples; Programmers who know lisp will probably
97 want to skim it quickly to get a feel for what xlisp does and does
98 not support.
99
100 Xlisp Objects Tutorial
101 A simple introduction to the object-oriented facilities of xlisp.
102 These predate the common-lisp object oriented facilities, and
103 unfortunately are quite different from the commonlisp approach.
104 On the bright side, xlisp's facilities are *much* simpler, while
105 still giving us what we really need.
106
107 Programmers new to xlisp will want to read this chapter thoroughly.
108
109 Xlisp Reference
110 Exhaustive function by function and variable by variable
111 documentation of the standard xlisp facilities, . It does *not*
112 document facilities added to xlisp by application programs such as
113 skandha4, since the same xlisp kernel is used by a number of
114 different packages, and it is important to maintain a clear
115 distinction between the invariant xlisp kernel and the
116 application-specific stuff. The slisp file hierarchy is designed
117 to allow application-specific documentation to be added as a
118 separate top level in the emacs info directory, one for each
119 separate application. However, every application will have access
120 to the basic functions documented in this chapter.
121
122 No sane person is likely to actually read this chapter end to end.
123
124 Xlisp Internals
125 The internal workings of the xlisp core interpreter. You certainly
126 don't need to read this if you are just writing lisp code, and you
127 shouldn't need to understand most of it even if you are adding new
128 C primitives.
129
130 
131 File: slisp, Node: Slisp Tutorial, Next: Xlisp Tutorial, Prev: Introduction, Up: Top
132
133 Slisp Tutorial
134 **************
135
136 This chapter describes how to get started programming in Slisp,
137 sharing slisp source code, the basic organization of slisp, methods for
138 creating new applications, and basic methods for adding new primitive
139 functions to xlisp.
140
141 Section overview. The items are presented in order of increasing
142 detail, beginning with programming in LISP only, and ending with adding
143 new primitive c-coded functions to slisp.
144
145 Lisp Programming in Slisp
146 Basic procedures for LISP programming, for programmers who will be
147 writing LISP code using an existing compiled slisp application
148 such as sl.
149
150 Sharing Slisp code
151 Describes our current methods for sharing slisp code at our site.
152 How we've set up our source code archive, methods for copying a
153 version of slisp into your personal directory, and methods for
154 handling multiple machine architectures accessing a common nfs
155 mounted source directory. We also discuss tradeoffs between this
156 and other sharing schemes such as CVS, that we have not yet
157 implemented.
158
159 Slisp Organization
160 The overall file structure of slisp.
161
162 Configuring a Machine
163 How to configure slisp to run on a given machine.
164
165 Creating a New Application
166 How to compile a set of existing modules into a new application.
167
168 Creating a New Module
169 How to create a new module that can be included in an
170 application, where a module contains the c code to create
171 additional lisp primitive functions.
172
173 Creating New Primitives
174 How to create additional lisp primitives within a module.
175
176 Embedding Slisp in C
177 How to include Slisp in a larger C program
178
179 Client-Server Operations
180 Using slisp over a network
181
182 History:
183 Created 10/8/93 by jfb (Jim Brinkley)
184
185 Modified 10/3/94 by jfb. Added client-server operations
186
187 Modified 3/17/95, jfb. Added ScopyFiles and SinstallFiles
188
189 * Menu:
190
191 * Lisp Programming in Slisp::
192 * Sharing Slisp Code::
193 * Slisp Organization::
194 * Configuring a Machine::
195 * Creating a New Application::
196 * Creating a New Module::
197 * Creating New Primitives::
198 * Embedding Slisp in C::
199 * Client-Server Operations::
200
201 
202 File: slisp, Node: Lisp Programming in Slisp, Next: Sharing Slisp Code, Prev: Slisp Tutorial, Up: Slisp Tutorial
203
204 Lisp Programming in Slisp
205 =========================
206
207 Most programmers will simply want to program in lisp, rather than
208 create new primitive C functions. The simplest way to do this is to
209 simply type the name of an slisp application installed at your site, in
210 a shell. For example type sl, for the basic slisp application that
211 contains the xlisp primitives. Of course, like any other Unix
212 application, sl must be available from your PATH variable.
213
214 Slisp (and Xlisp) uses an environment variable called XLPATH, which
215 is a search path for loading lisp files. At our site this path is
216 defined for all users (in applications installed in /usr/local/bin) to
217 be /usr/local/xlisp, so any files in this directory can be loaded just
218 by typing (LOAD-LIBRARY file) in the application.
219
220 If you change XLPATH then the search path can be customized. For
221 example, if init.lsp is present in the initial XLPATH then this file
222 will always be loaded at startup, which you may not want. Instead if
223 you set XLPATH to be mypath:$XLPATH, slisp will first search for files
224 in mypath before it searches the original XLPATH. This means you can
225 have your own init.lsp file which will be loaded instead of the system
226 init.lsp file, or you can preferentially load custom copies of lsp
227 files that are part of a larger system.
228
229 In order to setup your own XLPATH look at the executable file for
230 the application you are using. For the basic slisp application sl, this
231 file is called sl, and is probably installed in /usr/local/bin. If not
232 ask the person who installed slisp at your site.
233
234 The file app (the executable file whose name is the name of the
235 application) is actually a shell script which first sets XLPATH, then
236 executes the binary file, which is app.bin, or in the case of sl,
237 sl.bin. To create your own XLPATH copy app to your own directory, then
238 change XLPATH to be whatever you want it to be.
239
240 You can also change the name of this file if you want its name to
241 reflect a specific application that adds lisp files. For example, one
242 application we have is called siserver, which includes c modules to
243 access a database system. To make a special bibliographic retrieval
244 application that uses the database it might be reasonable to rename
245 siserver to bib, set XLPATH within the shell script bib to include any
246 lisp directories containing files you want dynamically loaded, and
247 include on the line that calls siserver.bin any lisp files you want to
248 always load at runtime.
249
250 Once the basic structure of an slisp application is set up the rest
251 is simply lisp programming. For a basic tutorial about the xlisp
252 primitive functions and object oriented extensions that are available
253 in every slisp application see Xlisp Tutorial and Xlisp Objects
254 Tutorial. For a complete reference of xlisp functions see Xlisp
255 Reference. For descriptions of additional primitive functions that are
256 added for specific applications see the info node associated with that
257 application.
258
259 
260 File: slisp, Node: Sharing Slisp Code, Next: Slisp Organization, Prev: Lisp Programming in Slisp, Up: Slisp Tutorial
261
262 Sharing Slisp Code
263 ==================
264
265 This section describes how we have set up slisp for sharing in the
266 Digital Anatomist Program. This is somewhat specific for our program,
267 but it may give ideas for other sites. At the end of this node we
268 describe tradeoffs and other ideas we haven't had time to pursue yet.
269
270 In the Digital Anatomist Program all relevant machines have
271 /usr/local/src mounted from a single machine (betz). The archive copy
272 of slisp is kept in this directory as /usr/local/src/slisp. This
273 directory should be visible from the machine on which you are planning
274 to use slisp. Even if it isn't a copy of slisp can be made for your own
275 machine if necessary.
276
277 The basic approach we currently use is to keep usr/local/src/slisp
278 as the archive directory for sharing changes to slisp, but each
279 programmer downloads a copy of the relevant modules from the archive,
280 and compiles an application from within his own directory.
281
282 Once the local version has been verified the programmer uploads his
283 changes into the archive and notifies the other programmers by email in
284 person that he has done this. The other programmers can then download
285 the changed files to their own personal copies of slisp. Only members
286 of the slisp unix group may write to the archive but anyone can read
287 from it.
288
289 In the following menu items, Downloading and Uploading refer to
290 entire slisp applications such as skandha4, sl or siserver. If you just
291 want to upload or download individual files or directories, or if you
292 want to install a list of lisp files in a common location, see the menu
293 item for Copying Individual Files.
294
295 * Menu:
296
297 * Downloading::
298 * Uploading::
299 * Copying Individual Files::
300 * Sharing Issues::
301
302 
303 File: slisp, Node: Downloading, Next: Uploading, Prev: Sharing Slisp Code, Up: Sharing Slisp Code
304
305 Downloading
306 ===========
307
308 In the following let Archive=/usr/local/src, or a similar path that
309 refers to the location of the slisp sharable archive. Let
310 Local=$HOME/src, or a similar path that refers to your personal copy of
311 slisp in your home directory.
312
313 To aid in downloading a local version of slisp, a script called
314 Scopy is located in Archive/slisp/bin. To run this script cd to the
315 archive subdirectory in which the application you are interested in
316 resides (e.g. Archive/slisp/sl), then run Scopy Local. The result
317 will be that a directory hierarchy called Local/slisp will be created,
318 and only those slisp modules required for the application will be
319 copied. The basic application sl will always be copied, but the sl
320 directory is very small.
321
322 This assumes Scopy is in your search path. It is useful in general
323 to include Local/slisp/bin in your search path, (which will include
324 Scopy once the initial download has been made) since the other
325 configuration scripts reside there as well.
326
327 If Local/slisp already exists then files of the same name will be
328 replaced from the archive copies. Thus, Scopy can be used to update
329 your personal copy of Slisp after someone else has made changes. Of
330 course it would be prudent to see what the changes are before you
331 delete your own copies. This can be done on many machines by running
332 diff -r Archive/slisp Local/Slisp, which will recursively list all the
333 differences between the two directories.
334
335 
336 File: slisp, Node: Uploading, Next: Copying Individual Files, Prev: Downloading, Up: Sharing Slisp Code
337
338 Uploading
339 =========
340
341 In the following let Archive=/usr/local/src, or a similar path that
342 refers to the location of the slisp sharable archive. Let
343 Local=$HOME/src, or a similar path that refers to your personal copy of
344 slisp in your home directory.
345
346 To merge your changes back into Archive/slisp Scopy can be used in
347 the reverse direction. That is, cd to your local copy of the
348 application directory you are working with (e.g. Local/slisp/sl), and
349 run Scopy Archive, which will replace the archive copies with your
350 files of the same name, leaving other archive files unchanged. This
351 assumes you have write priviledges in Archive.
352
353 Before you do this please add a description of your changes to the
354 front of Local/slisp/Changelog.txt, which will then replace the version
355 in Archive. It is also important to not upload your changes before you
356 have donwloaded someone else's changes or you will overwrite them.
357 Since we are not yet using a revision control system we need to
358 communicate often with each other.
359
360 
361 File: slisp, Node: Copying Individual Files, Next: Sharing Issues, Prev: Uploading, Up: Sharing Slisp Code
362
363 Copying Individual Files
364 ========================
365
366 The sections on uploading and downloading assume you want to move
367 entire Slisp applications. If you are just interested in uploading or
368 downloading individual files or directories you can use two additional
369 scripts, both of which are in slisp/bin. These scripts are ScopyFiles
370 and Sinstallfiles
371
372 Scopyfiles is used to copy a list of files from a source slisp
373 hierarchy to the same relative positions in a destination hierarchy.
374 Thus, if you make changes in only a few files in your local copy of
375 Slisp you can run this file to upload just those files to the archive.
376 The script appends the list of changed files to a file called
377 ChangedFiles in the destination. This list can be cut and pasted into a
378 filelist as input to this script, so that others can download just the
379 changed files to their own local copies.
380
381 The syntax for this script is:
382
383 ScopyFiles sourcepath destpath filelist
384
385 sourcepath is the path to the root of the source slisp hierarchy,
386 eg., /usr/people/brinkley/src/slisp.
387
388 destpath is the path to the root of the destination slisp hierarchy,
389 e.g., /usr/local/src/slisp
390
391 filelist is a list of pathnames relative to the source and
392 destination hierarchies. Each file in filelist can be either a file or
393 a directory.
394
395 The second script is Sinstallfiles. This script has the same syntax
396 as ScopyFiles, except all entries in filelist must be files, not
397 direcctories. All files in filelist are copied to the same level in the
398 destination directory. This is useful for installing lisp files that
399 are all meant to be at the same level in a lisp search directory for
400 slisp applications.
401
402 For example destpath in our case will usually be /usr/local/xlisp,
403 since this is the path for loading lisp files in our local environment.
404
405 
406 File: slisp, Node: Sharing Issues, Prev: Copying Individual Files, Up: Sharing Slisp Code
407
408 Sharing Issues
409 ==============
410
411 This method of code sharing is based on the ideas used in CVS,
412 concurrent versions systems. I (jfb) tried to get CVS working for slisp
413 but found that, although it worked, it was very unforgiving when I made
414 a mistake or when I deleted or renamed a directory. Perhaps someone
415 else can get this working, since our current approach does not allow
416 for revision control, which will have to be done for now just by
417 freezing versions of the entire slisp archive in seperate compressed
418 tar files.
419
420 Another approach that I looked at was allowing the slisp archive to
421 be shared while code was being compiled. That is, a programmer would
422 only have local copies of those modules he was modifying, and would
423 link to source code in the nfs mounted archive.
424
425 The advantages of this are 1) only a single copy of shared code
426 would exist, and 2) some space would be saved.
427
428 The disadvantages are 1) this mechanism is not yet implemented and
429 we've spent too much time on this already 2) Any change added by a
430 programmer to the shared archive will be immediately seen by all others
431 who use the archive, which may mean that a person's application will
432 break 3) If a programmer desires to download a version of slisp that is
433 not on the net then the shared archive will also have to be
434 downloaded.
435
436 The main reason we didn't look at this alternative is that it would
437 take time to implement, and we first need to see how useful slisp will
438 be before we make it work better. This whole area is of course related
439 to CASE, and we probably should be implementing this all in some
440 commercial CASE tool.
441
442 
443 File: slisp, Node: Slisp Organization, Next: Configuring a Machine, Prev: Sharing Slisp Code, Up: Slisp Tutorial
444
445 Slisp Organization
446 ==================
447
448 This node describes the basic organization of the slisp file
449 hierarchy. This same organization will be found in the slisp archive
450 and in all downloaded copies.
451
452 Slisp is organized as a file directory called slisp consisting
453 mostly of a set of modules, each contained within a subdirectory. One
454 of the modules is xcore, the basic xlisp interpreter written by Dave
455 Betz. Each of the other modules (each starting with x, i.e. xetc) is a
456 set of c and or lsp functions for implementing a new module.
457
458 An slisp application is defined by a subdirectory within slisp (say
459 sl, for the basic sl application), whose name is the name of the
460 application, and which contains configuration information,
461 documentation, and generated files specific to the application. This
462 organization allows more than one application to be built within the
463 same directory hierarchy by simply creating a new application directory.
464
465 The files within each application directory are described in *Note
466 Creating a New Application::.
467
468 The files within each module are described in *Note Creating a New
469 Module::.
470
471 The following additional files and directories are present in all
472 slisp distributions:
473
474 * bin
475
476 Sconfigure - configure a new machine.
477
478 Smake - configure a new application.
479
480 Scopy - Download or upload an slisp application to a local
481 directory for compiling.
482
483 make_tags - make tags for emacs
484
485 * c - functions and main programs independent of any module
486
487 seval.c - routines for embedding slisp in C as a local client
488
489 netseval.c - analogous routines for running slisp over a network
490
491 sl_client. - main program for creating example network and local
492 clients
493
494 client_check.c - check routines for local and network clients
495
496 * Changelog.txt - Changes in overall slisp. This should be added to
497 by programmers to document the changes to slisp that they upload
498 to the shared archive.
499
500 * doc - miscelaneous documentation not in info format
501
502 * include - global h files needed by more than one module
503
504 * info
505
506 Global documentation in texi format that is formatted by the
507 program makeinfo from the Free Software Foundation. All info
508 nodes below the slisp node, including the node you are reading
509 now, are created from source files in this directory.
510
511 * lsp
512
513 Global lsp files of use to more than one application. In
514 particular slispinit.lsp contains useful functions, test*.lsp are
515 used by make check to test individual modules, and classes.lsp
516 contains macros for easier manipulation of the xlisp object system.
517
518 * Makefile.x - a section of make targets that is included by the
519 Makefiles in each module.
520
521 * README - general organization of slisp
522
523 * sl
524
525 The basic slisp application sl. This directory can be used as a
526 template for creating other applications. Each application is
527 defined by a subdirectory of slisp whose name is the name of the
528 application.
529
530 * systems
531
532 Files defining the characteristics of machines on which slisp is
533 designed to run. One of these files is read by Sconfigure to
534 configure a machine for slisp. In theory the systems information
535 should be independent of the applications information. This is not
536 yet actually the case. An example is that our NeXT file contains
537 in the variable OTHERLIBES the sybase library, which is needed by
538 the module xsybase.
539
540 * util - General purpose utility routines
541
542 In addition to the directories within the slisp hierarchy, the
543 configuration scripts Sconfigure and Smake will create files within
544 $HOME/bin and $HOME/lib. The idea is that no derived files (such as o
545 files or libraries) should be created in the source slisp directory, so
546 that multiple machines can access a single nfs mounted source
547 directory, yet create machine and application-specific binary files.
548 The files created are:
549
550 * $HOME/bin
551
552 appname - a shell script that sets XLPATH, then calls appname.bin,
553 where appname is the name of an application (e.g. sl).
554
555 appname.bin - the executable for appname
556
557 * $HOME/lib
558
559 Makefile.def - Machine specific definitions created by Sconfigure
560
561 Makefile.lastapp - The last application compiled. Needed by make
562 check in order to know which application to run when checking test
563 code for a module.
564
565 slisp-host - a link to slisp/systems/host, created by Sconfigure
566
567 libslisp.a - library of all o files for all modules except xcore.
568 This library is shared by all applications.
569
570 libapp.a (e.g. libsl.a for the basic slisp application) - xcore
571 routines that were compiled for a specific application. The basic
572 approach to adding new c primitives into xlisp is to re-compile
573 xcore and include the new c code, so xcore will be different for
574 each application.
575
576 
577 File: slisp, Node: Configuring a Machine, Next: Creating a New Application, Prev: Slisp Organization, Up: Slisp Tutorial
578
579 Configuring a Machine
580 =====================
581
582 Once a copy of slisp has been downloaded to your local directory, it
583 must be configured to run on your local machine. To do this run
584 slisp/bin/Sconfigure machine, where machine is the name of a machine
585 defined by a file in slisp/systems. In this case and in all subsequent
586 discussion slisp refers to the downloaded slisp directory that is in
587 your local HOME directory.
588
589 Sconfigure will read the information in the machine file and create
590 the appropriate HOME/lib files as outlined in the previous node. If a
591 file for your machine does not exist create one by copying an existing
592 one, renaming it to an appropriate name for your machine, and setting
593 the variables appropriately. All variables must be set. Of course we
594 can't guarantee that slisp will run on any machine, but we hope that it
595 will be as portable as Xlisp is.
596
597 
598 File: slisp, Node: Creating a New Application, Next: Creating a New Module, Prev: Configuring a Machine, Up: Slisp Tutorial
599
600 Creating a New Application
601 ==========================
602
603 A new application is created by creating a new copy of an existing
604 application directory and naming it app (where app is the application
605 name). The basic slisp application sl is useful as a template for
606 creating new applications.
607
608 Within slisp/app, edit the modules file to determine which x modules
609 are included, edit install_aux for installing any special files in the
610 install locations, and edit the documentation in the info directory.
611
612 The documentation file is built from app/info/Makefile. The
613 documentation consists of several files that are included in the top
614 level, which is generally called app.texi (eg sl.texi for the basic
615 slisp application). This file then includes intro.texi, which
616 introduces the application, a tutorial (if present) and ref.texi which
617 is built automatically from the included files. The reference file is
618 begun by ref.header, which always must exist with the name ref.header,
619 but which can be customized for the application.
620
621 The script slisp/bin/Smake is then run to configure a Makefile and
622 auxiliary files for the application, which are saved within the
623 application directory. This script must be run from within slisp/app,
624 where app is the name of the application.
625
626 Once the app is configured it is built by the following:
627
628 1. cd to slisp/app
629
630 2. make clobber, to remove any previous versions
631
632 3. make all, to make the application and the documentation
633
634 4. make check, runs various test routines and writes the log in
635 app/check.log.
636
637 5. make install, (as root) installs the application, documentation
638 and loaded lsp files in directories specified in the system file.
639
640 
641 File: slisp, Node: Creating a New Module, Next: Creating New Primitives, Prev: Creating a New Application, Up: Slisp Tutorial
642
643 Creating a New Module
644 =====================
645
646 A new module is created by copying an existing module and editing
647 the files appropriately. A good module to use for this purpose is xetc,
648 looking at xcore/doc/mymodule.h for ideas on how to create new xlisp
649 primitives. Also XlispInternals has at the end a discussion of how to
650 add new primitives.
651
652 In the following, let xmodule be the name of the module which is
653 also the name of the subdirectory under slisp. I.e. for xetc, xmodule =
654 xetc.
655
656 The following subdirectories and files must be present in every
657 module. All files are given relative to slisp/xmodule.
658
659 * c - C source code plus header files.
660
661 * c/Makefile
662
663 Overall makefile for the module. Must contain the targets clean
664 and xlisplibmore. xlisplibmore is a placeholder for additional
665 commands that should be performed when xlisplib is reached, which
666 is defined in Makefile.x at the top level. An example is the
667 command in xgt to make the distribution makefile. XLISPLIBOBJS is
668 a list of o files that are to be included in the module.
669
670 * c/xmodule.h
671
672 The master include file for the module, a subset of mymodule.h,
673 may be empty but must exist. The name must be xmodule.h (ie
674 xetc.h).
675
676 * check - Location of regression tests to make sure a module is
677 installed correctly.
678
679 * check/Makefile
680
681 Must exist and contain the targets test and clean.
682
683 * info - location of info documentation files used to build the
684 reference manual for an application.
685
686 * info/xmodule.texi
687
688 Documentation in texi format. May be empty but must exist.
689
690 * info/xmodule.menu
691
692 Info menu item for reference manual. May be empty but must exist.
693
694 * lsp
695
696 Lisp files for the module. May be empty but must exist.
697
698 Other subdirectories may be present but do not need to be.
699
700 
701 File: slisp, Node: Creating New Primitives, Next: Embedding Slisp in C, Prev: Creating a New Module, Up: Slisp Tutorial
702
703 Creating New Primitives
704 =======================
705
706 Not done. For now look at Xlisp Internals:"How do I add a new
707 primitive fn to xlisp?" , xcore/doc/mymodule.h, and of course source
708 code in the various modules.
709
710 One important point when adding new primitives. It is essential that
711 LVALS be protected with xlsave or xlprotect. If not the garbage
712 collector may try to collect them at inopportune times, with the result
713 that you will get very obscure bugs, often causing your program to
714 hang. Similarly it is essential to pop all saved variables off the
715 evaluation stack when exiting your function (except when you call
716 xlfail for an error, since the stack is cleared for you). Otherwise the
717 garbage collector will later try to access a NULL pointer, often
718 causing a segmentation fault. Based on our experience, if you get
719 strange, almost untraceable bugs, they are almost certainly due to
720 improperly protecting or releasing LVALS. Worse yet these bugs can
721 happen in your own application even if your module is ok but someone
722 elses module doesn't properly protect LVALS.
723
724 The section on Xlisp Internals mentioned above discusses this in
725 more detail.
726
727 
728 File: slisp, Node: Embedding Slisp in C, Next: Client-Server Operations, Prev: Creating New Primitives, Up: Slisp Tutorial
729
730 Embedding Slisp in C
731 ====================
732
733 The files /include/seval.h and /c/seval.c allow slisp to be
734 included as part of other C programs, so that it can be controlled in a
735 different manner than the read-eval-print cycle that is used in xmain,
736 the main program in xlisp. The primary motivation for this is to allow
737 slisp to be controlled from a graphical user interface. For example, an
738 slisp application could become a module within AVS, (Advanced
739 Visualization System), or an object within a NeXTStep application.
740
741 The main routines are sl_Init, to initialize slisp, and sl_Eval_Str,
742 which accepts a string describing an s-expression, calls slisp to
743 evaluate it, and writes the results to an output string pointer (memory
744 for the output string is allocated by seval.c). Slisp errors are
745 written to the output string. There are also routines to get the C
746 integer, float or string value of the current LISP expression. Since
747 all of Slisp is supported, all primitive functions are available, as
748 are any LISP functions via the LOAD lisp command.
749
750 Note that seval.c always disables debugging and tracing even if the
751 lisp programmer sets *BREAKENABLE* or *TRACENABLE* to T. This is
752 because the debug loop in xlisp requires more input, which is
753 incompatible with the notion of sending all input in a string, and then
754 receiving all output in another string.
755
756 The externally callable functions are defined in seval.h, which
757 should be included in the external program, along with a compiler
758 directive -I$(SLISPROOT)/include to find the include file, where
759 SLISPROOT is the location of the top level slisp directory. The main
760 program should be linked with up to four libraries: LOCALLIBES
761 XCORELIBES XLISPLIBES NETLIBES OTHERLIBES, in that order. All the
762 libraries are automatically created in the LIBPATH directory, which is
763 specified in the appropriate slisp/systems file.
764
765 LOCALLIBES is libseval.a, and is the library for the routines in
766 seval.c.
767
768 XCORELIBES are the routines from xcore that implement the basic
769 xlisp functions designed by Dave Betz. This library is different for
770 each application. For sl the library is called libsl.a.
771
772 XLISPLIBES is the common library containing all new c-coded
773 primitive functions added to slisp by any compiled application. This
774 file is called libslisp.a.
775
776 NETLIBES contains analogous routines to seval.c, defined in
777 c/netseval.c, that allow an slisp application to act as a network
778 client for another slisp server (see the section on client-server
779 operations). This library is only required if the application being
780 embedded has been compiled with the xnet module.
781
782 OTHERLIBES are any other libraries potentially needed by an
783 application on a given machine, as defined in the appropriate
784 slisp/systems file.
785
786 slisp/c contains the source code for seval.c, as well as an example
787 embedded application. The Makefile for each application has a target
788 called "local_client". When this target is made the c/Makefile is used
789 to compile an example local client whose name is appc, where app is the
790 name of the executable shell for the application. For example, for sl
791 the local client is slc.
792
793 For the local client c/Makefile defines LOCAL_CLIENT, and compiles
794 c/sl_client.c. This program can be used as a template for including the
795 seval.c functions.
796
797 In addition when "make check" is run for an application, the
798 c/Makefile "check" target is run, which creates an executable
799 "local_check" from client_check.c. client_check.c provides examples
800 for using the routines in seval.c.
801
802 A somewhat simpler example is shown below, which is essentially the
803 same as sl_client.c, but without all the makefile flags.
804
805 # Example Makefile that searches libraries in HOME/lib
806 # which is where the slisp libraries are created by default.
807 # Search application library sl before slisp
808 LIBS= -L$HOME/lib -lseval -lsl -lslisp -lnetseval
809 CFLAGS= -I$HOME/src/slisp/include #location of seval.h
810
811 slc:slc.o
812 cc slc.o $(LIBS) -o slc
813
814 /******************************************************************/
815 /* slc.c */
816
817
818 #include "seval.h"
819 #include <stdio.h>
820
821 #define BUF_SIZ 4000
822
823 /* Example main program that uses the functions in seval.h */
824 /* to implement a read-eval-print loop to the terminal. sl_Init */
825 /* and sl_Eval_Str are the two routines from seval.h. */
826 /* Note that we don't include */
827 /* a newline in our prompt, since the slisp return */
828 /* values always end with a newline anyhow, following */
829 /* the convention used in other xlisp routines. */
830
831 main()
832 {
833 char inbuf[ BUF_SIZ ];
834 sl_Init();
835 for (;;) {
836 int got_err;
837 char* result, *out;
838 /* Read string to evaluate from user: */
839 printf("> ");
840 fgets( inbuf, BUF_SIZ, stdin );
841 /* Evaluate the string: */
842 out = sl_Eval_Str(&got_err, &result, inbuf );
843 /* If out != result then the evaluated */
844 /* function printed some output before */
845 /* returning, as for example from a PRINT */
846 /* or FORMAT function call */
847 if (out != result) printf("%s", out);
848 /* If an error was returned by slisp */
849 /* got_err will be true. The error messages */
850 /* are not prepended by "error: " because */
851 /* some programs may not want this. But to */
852 /* be consistent with slisp conventions the */
853 /* error message should be prepended with */
854 /* error: */
855 /* If an error was not received then result */
856 /* has the string equivalent of the value */
857 /* returned by the function */
858 if (got_err)
859 printf("error: %s", result);
860 else
861 printf("%s", result);
862 }
863 }
864
865 
866 File: slisp, Node: Client-Server Operations, Prev: Embedding Slisp in C, Up: Slisp Tutorial
867
868 Client-Server Operations
869 ========================
870
871 A tcp-based network protocol has been designed which allows a
872 client to evaluate s-expressions via an slisp server running on a
873 remote machine. Any compiled slisp application may be run as a server,
874 and an application compiled with the xnet module may be run as a
875 client. A network client that is embedded in a C program may also be
876 created.
877
878 * Menu:
879
880 * Server Mode::
881 * LISP Network Client::
882 * Embedded Network Client::
883
884 
885 File: slisp, Node: Server Mode, Next: LISP Network Client, Up: Client-Server Operations
886
887 Server Mode
888 -----------
889
890 Any slisp application may be run in server mode by starting it with
891 the -s flag. The -s flag causes the application to supress the initial
892 prompt, and to enclose output in control character delimiters that
893 allow the client to disambiguate error and other output from the value
894 returned by the function.
895
896 The program can be made into a network accessible server by
897 including it as one of the programs known to the internet superserver
898 inetd. The operations for accomplishing this must be done by root on
899 the server machine. The following operations use as an example the
900 creation of a server for the basic slisp application sl, on port 5201:
901
902 1. Read about inetd and services by doing man inetd and man
903 services.
904
905 2. Choose a port number, an application name (usually the name of
906 the executable), and a user under whom the application should run. Port
907 numbers above 5000 are usually safe. The user should not be root since
908 slisp contains the "system" command which under root could do almost
909 anything. An ordinary user is usually best, or one that is created for
910 the server.
911
912 3. Make an entry in /etc/services for the port number, application
913 name and protocol (tcp). For example, to run the basic slisp
914 applications sl as a server on port 5201:
915
916 sl 5201/tcp
917
918 4. Make an entry in /etc/inetd.conf to tell inetd which program to
919 run when a connection is made on the given port with the service name
920 defined in /etc/services:
921
922 sl stream tcp nowait slisp /usr/localbin/sl sl -s
923
924 The fields are separated by spaces or tabs. For this example the
925 fields are:a) sl - the name of the service defined in /etc/services b)
926 stream, tcp and nowait - should always be set to these for this
927 protocol c) slisp - the name of the user under which the server should
928 run. Here we've created a pseudo user called slisp, d)
929 /usr/localbin/sl, the pathname to the executable - note this can be the
930 executable shell script. Environment variables set by the shell script
931 are remembered by the server, e) sl - The first argument, always the
932 name of the executable, f) -s - any remaining arguments.
933
934 The appropriate man pages have more information.
935
936 
937 File: slisp, Node: LISP Network Client, Next: Embedded Network Client, Prev: Server Mode, Up: Client-Server Operations
938
939 LISP Network Client
940 -------------------
941
942 If an slisp application is compiled with the xnet module it can be a
943 client to an slisp server. Lisp primitives defined in xnet.c setup a
944 connection to the remote server, and allow control over the delimiters
945 and the timeout. Once the connection has been established an
946 s-expression may be evaluated on the remote server by the function
947 NET-EVAL, which is nearly the same as the ordinary LISP EVAL function.
948 The results of the NET-EVAL function are available within the local
949 slisp process as long as the results don't include pointers to objects
950 in the remote memory space.
951
952 The xnet functions are described in the reference part of the info
953 documention for any application compiled with xnet.
954
955 
956 File: slisp, Node: Embedded Network Client, Prev: LISP Network Client, Up: Client-Server Operations
957
958 Embedded Network Client
959 -----------------------
960
961 xnet utilizes c functions defined in slisp/c/netseval.c, which are
962 compiled by every application into the library libnetseval.a. If this
963 library is linked with any C program the C program can call the
964 functions in netseval.c to evaluate s-expressions on a remote server.
965 The functions in netseval.c are semantically equivalent to those in
966 seval.c (described in the section on embedding lisp in C), with the
967 addition of functions for establishing a connection.
968
969 c/sl_client.c, when compiled with the NET_CLIENT flag, creates a
970 network client called netsl. netsl is created whenever the net_client
971 target is made in an application Makefile. c/client_check.c, when
972 compiled with the NET_CLIENT flag by the check target in each
973 application Makefile, also shows an example of an embedded network
974 client.
975
976 Since for a network client all of slisp is located on the server,
977 the only library that needs to be linked into a C program is
978 libnetseval.c, which is shown in the c/Makefile for the target
979 net_client.
980
981 A somewhat simpler example is shown below, which is essentially the
982 same as sl_client.c, but without all the makefile flags. This is also
983 very similar to slc, the main program described under embedding lisp in
984 C.
985
986 # Example Makefile that searches libraries in HOME/lib
987 # which is where the slisp libraries are created by default.
988 # Search application library sl before slisp
989 LIBS= -L$HOME/lib -lnetseval
990 CFLAGS= -I$HOME/src/slisp/include #location of netseval.h
991
992 netsl:netsl.o
993 cc netsl.o $(LIBS) -o netsl
994
995 /******************************************************************/
996 /* netsl.c */
997
998
999 #include "netseval.h"
1000 #include <stdio.h>
1001
1002 #define BUF_SIZ 4000
1003
1004 /* Example main program that uses the functions in netseval.h */
1005 /* to implement a read-eval-print loop to the terminal. */
1006 /* Functions starting with sn_ are the routines from netseval.c */
1007 /* Note that we don't include */
1008 /* a newline in our prompt, since the slisp return */
1009 /* values always end with a newline anyhow, following */
1010 /* the convention used in other xlisp routines. */
1011
1012 main()
1013 {
1014 char inbuf[ BUF_SIZ ];
1015 int s;
1016 sl_Init();
1017 if (!(argc == 3)) {
1018 printf("Usage: %s <hostname> <port number>\n", argv[0]);
1019 exit(1);
1020 }
1021 s = sn_Connect(argv[1], atoi(argv[2]), &got_err, &result, &err);
1022 if (got_err) {
1023 if (result)
1024 printf("%s", result);
1025 printf("error: %s", err);
1026 printf("Can't connect to %s on port %s\n", argv[1], argv[2]);
1027 exit(1);
1028 }
1029 printf("%s", result);
1030 sn_Set_Socket(s);
1031 for (;;) {
1032 int got_err;
1033 char* result, *out;
1034 /* Read string to evaluate from user: */
1035 printf("> ");
1036 fgets( inbuf, BUF_SIZ, stdin );
1037 out = sn_Eval_Str(&got_err, &result, inbuf );
1038 if (out != result) printf("%s", out);
1039 if (got_err) {
1040 if (!strcmp(result, "Server timeout\n") ||
1041 !strcmp(result, "Connection not open\n")) {
1042 printf("%s", result);
1043 exit(0);
1044 }
1045 else
1046 printf("error: %s", result);
1047 }
1048 else
1049 printf("%s", result);
1050
1051 }
1052 }
1053
1054 
1055 File: slisp, Node: Xlisp Tutorial, Next: Xlisp Objects Tutorial, Prev: Slisp Tutorial, Up: Top
1056
1057 Xlisp Tutorial
1058 **************
1059
1060 Copyright
1061 =========
1062
1063 This chapter is adapted from an 'xlisp.doc' file with the following
1064 copyright:
1065
1066 XLISP: An Object-oriented Lisp
1067
1068 Version 2.1 (WINTERP)
1069
1070 April 23, 1989
1071
1072 by
1073
1074 David Michael Betz
1075
1076 P.O. Box 144
1077
1078 Peterborough, NH 03458
1079
1080 (603) 924-4145 (home)
1081
1082 Copyright (c) 1989, by David Michael Betz
1083
1084 Note: This document has been updated to include new lisp primitives
1085
1086 added by the WINTERP distribution of XLISP 2.1.
1087
1088 WINTERP 1.0 Copyright 1989 Hewlett-Packard Company (by Niels Mayer).
1089
1090 $Header: /usr/local/cvsroot/src/slisp/info/xlisptut.texi,v 1.1.1.1 1998/06/20 03:54:55 ben Exp $
1091
1092 * Menu:
1093
1094 * Xlisp Tutorial Introduction::
1095 * Note From Author::
1096 * Xlisp Command Loop::
1097 * Break Command Loop::
1098 * Data Types::
1099 * The Evaluator::
1100 * Lexical Conventions::
1101 * Readtables::
1102 * Lambda Lists::
1103 * Objects::
1104 * Class Object::
1105 * Class Class::
1106 * Symbols::
1107 * Evaluation Functions::
1108 * Symbol Functions::
1109 * Property List Functions::
1110 * Array Functions::
1111 * List Functions::
1112 * Destructive List Functions::
1113 * Predicate Functions::
1114 * Control Constructs::
1115 * Looping Constructs::
1116 * Progs And Blocks::
1117 * Debugging And Error Handling::
1118 * Arithmetic Functions::
1119 * Bitwise Functions::
1120 * String Functions::
1121 * Character Functions::
1122 * I/O Functions::
1123 * Format Function::
1124 * File I/O Functions::
1125 * String Stream Functions::
1126 * Structures::
1127 * System Functions::
1128 * File I/O Examples::
1129 * Unix I/O Functions::
1130
1131 
1132 File: slisp, Node: Xlisp Tutorial Introduction, Next: Note From Author, Prev: Xlisp Tutorial, Up: Xlisp Tutorial
1133
1134 Introduction
1135 ============
1136
1137 XLISP is an experimental programming language combining some of the
1138 features of Common Lisp with an object-oriented extension capability.
1139 It was implemented to allow experimentation with object-oriented
1140 programming on small computers.
1141
1142 There are currently implementations of XLISP running on the IBM- PC
1143 and clones under MS-DOS, on the Macintosh, the Atari-ST and the Amiga.
1144 It is completely written in the programming language 'C' and is easily
1145 extended with user written built-in functions and classes. It is
1146 available in source form to non-commercial users.
1147
1148 Many Common Lisp functions are built into XLISP. In addition, XLISP
1149 defines the objects 'Object' and 'Class' as primitives. 'Object' is the
1150 only class that has no superclass and hence is the root of the class
1151 heirarchy tree. 'Class' is the class of which all classes are instances
1152 (it is the only object that is an instance of itself).
1153
1154 This document is a brief description of XLISP. It assumes some
1155 knowledge of LISP and some understanding of the concepts of
1156 object-oriented programming.
1157
1158 I recommend the book "LISP" by Winston and Horn and published by
1159 Addison Wesley for learning Lisp. The first edition of this book is
1160 based on MacLisp and the second edition is based on Common Lisp. XLISP
1161 will continue to migrate towards compatibility with Common Lisp.
1162
1163 You will probably also need a copy of "Common Lisp: The Language" by
1164 Guy L. Steele, Jr., published by Digital Press to use as a reference for
1165 some of the Common Lisp functions that are described only briefly in
1166 this document.
1167
1168 
1169 File: slisp, Node: Note From Author, Next: Xlisp Command Loop, Prev: Xlisp Tutorial Introduction, Up: Xlisp Tutorial
1170
1171 A Note From The Author
1172 ======================
1173
1174 If you have any problems with XLISP, feel free to contact me for
1175 help or advice. Please remember that since XLISP is available in
1176 source form in a high level language, many users have been making
1177 versions available on a variety of machines. If you call to report a
1178 problem with a specific version, I may not be able to help you if that
1179 version runs on a machine to which I don't have access. Please have
1180 the version number of the version that you are running readily
1181 accessible before calling me.
1182
1183 If you find a bug in XLISP, first try to fix the bug yourself using
1184 the source code provided. If you are successful in fixing the bug,
1185 send the bug report along with the fix to me. If you don't have access
1186 to a C compiler or are unable to fix a bug, please send the bug report
1187 to me and I'll try to fix it.
1188
1189 Any suggestions for improvements will be welcomed. Feel free to
1190 extend the language in whatever way suits your needs. However, PLEASE
1191 DO NOT RELEASE ENHANCED VERSIONS WITHOUT CHECKING WITH ME FIRST!! I
1192 would like to be the clearing house for new features added to XLISP.
1193 If you want to add features for your own personal use, go ahead. But,
1194 if you want to distribute your enhanced version, contact me first.
1195 Please remember that the goal of XLISP is to provide a language to
1196 learn and experiment with LISP and object-oriented programming on small
1197 computers. I don't want it to get so big that it requires megabytes of
1198 memory to run.
1199
1200 
1201 File: slisp, Node: Xlisp Command Loop, Next: Break Command Loop, Prev: Note From Author, Up: Xlisp Tutorial
1202
1203 Xlisp Command Loop
1204 ==================
1205
1206 When XLISP is started, it first tries to load the workspace
1207 "xlisp.wks" from the current directory. If that file doesn't exist,
1208 XLISP builds an initial workspace, empty except for the built-in
1209 functions and symbols.
1210
1211 Then XLISP attempts to load "init.lsp" from the current directory.
1212 It then loads any files named as parameters on the command line (after
1213 appending ".lsp" to their names).
1214
1215 XLISP then issues the following prompt:
1216
1217 >
1218
1219 This indicates that XLISP is waiting for an expression to be typed.
1220
1221 When a complete expression has been entered, XLISP attempts to
1222 evaluate that expression. If the expression evaluates successfully,
1223 XLISP prints the result and then returns to the initial prompt waiting
1224 for another expression to be typed.
1225

brinkley@uw.edu
ViewVC Help
Powered by ViewVC 1.1.26