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

Contents of /skandha4/info/slisp-3

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1.1.1 - (show annotations) (download) (vendor branch)
Tue May 25 09:39:20 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: Bitwise Functions, Next: String Functions, Prev: Arithmetic Functions, Up: Xlisp Tutorial
12
13 Bitwise Logical Functions
14 =========================
15
16 (logand <expr>...) THE BITWISE AND OF A LIST OF NUMBERS
17 <expr> the numbers
18 returns the result of the and operation
19
20 (logior <expr>...) THE BITWISE INCLUSIVE OR OF A LIST OF NUMBERS
21 <expr> the numbers
22 returns the result of the inclusive or operation
23
24 (logxor <expr>...) THE BITWISE EXCLUSIVE OR OF A LIST OF NUMBERS
25 <expr> the numbers
26 returns the result of the exclusive or operation
27
28 (lognot <expr>) THE BITWISE NOT OF A NUMBER
29 <expr> the number
30 returns the bitwise inversion of number
31
32 
33 File: slisp, Node: String Functions, Next: Character Functions, Prev: Bitwise Functions, Up: Xlisp Tutorial
34
35 String Functions
36 ================
37
38 (string <expr>) MAKE A STRING FROM A CHARACTER, SYMBOL OR STRING.
39 <expr> the expression.
40 returns a string. Calling string on a string argument is a no-op.
41
42 (string-trim <bag> <str>) TRIM BOTH ENDS OF A STRING
43 <bag> a string containing characters to trim
44 <str> the string to trim
45 returns a trimmed copy of the string
46
47 (string-left-trim <bag> <str>) TRIM THE LEFT END OF A STRING
48 <bag> a string containing characters to trim
49 <str> the string to trim
50 returns a trimed copy of the string
51
52 (string-right-trim <bag> <str>) TRIM THE RIGHT END OF A STRING
53 <bag> a string containing characters to trim
54 <str> the string to trim
55 returns a trimed copy of the string
56
57 (string-upcase <str> &key :start :end) CONVERT TO UPPERCASE
58 <str> the string
59 :start the starting offset
60 :end the ending offset + 1
61 returns a converted copy of the string
62
63 (string-downcase <str> &key :start :end) CONVERT TO LOWERCASE
64 <str> the string
65 :start the starting offset
66 :end the ending offset + 1
67 returns a converted copy of the string
68
69 (nstring-upcase <str> &key :start :end) CONVERT TO UPPERCASE
70 <str> the string
71 :start the starting offset
72 :end the ending offset + 1
73 returns the converted string (not a copy)
74
75 (nstring-downcase <str> &key :start :end) CONVERT TO LOWERCASE
76 <str> the string
77 :start the starting offset
78 :end the ending offset + 1
79 returns the converted string (not a copy)
80
81 (strcat <expr>...) CONCATENATE STRINGS
82 <expr> the strings to concatenate
83 returns the result of concatenating the strings
84
85 (subseq <string> <start> [<end>]) EXTRACT A SUBSTRING
86 <string> the string
87 <start> the starting position (zero origin)
88 <end> the ending position + 1 (defaults to end)
89 returns substring between <start> and <end>
90
91 (string< <str1> <str2> &key :start1 :end1 :start2 :end2)
92 (string<= <str1> <str2> &key :start1 :end1 :start2 :end2)
93 (string= <str1> <str2> &key :start1 :end1 :start2 :end2)
94 (string/= <str1> <str2> &key :start1 :end1 :start2 :end2)
95 (string>= <str1> <str2> &key :start1 :end1 :start2 :end2)
96 (string> <str1> <str2> &key :start1 :end1 :start2 :end2)
97 <str1> the first string to compare
98 <str2> the second string to compare
99 :start1 first substring starting offset
100 :end1 first substring ending offset + 1
101 :start2 second substring starting offset
102 :end2 second substring ending offset + 1
103 returns t if predicate is true, nil otherwise
104 Note: case is significant with these comparison functions.
105
106 (string-lessp <str1> <str2> &key :start1 :end1 :start2 :end2)
107 (string-not-greaterp <str1> <str2> &key :start1 :end1 :start2 :end2)
108 (string-equalp <str1> <str2> &key :start1 :end1 :start2 :end2)
109 (string-not-equalp <str1> <str2> &key :start1 :end1 :start2 :end2)
110 (string-not-lessp <str1> <str2> &key :start1 :end1 :start2 :end2)
111 (string-greaterp <str1> <str2> &key :start1 :end1 :start2 :end2)
112 <str1> the first string to compare
113 <str2> the second string to compare
114 :start1 first substring starting offset
115 :end1 first substring ending offset + 1
116 :start2 second substring starting offset
117 :end2 second substring ending offset + 1
118 returns t if predicate is true, nil otherwise
119 Note: case is not significant with these comparison functions.
120
121 
122 File: slisp, Node: Character Functions, Next: I/O Functions, Prev: String Functions, Up: Xlisp Tutorial
123
124 Character Functions
125 ===================
126
127 (char <string> <index>) EXTRACT A CHARACTER FROM A STRING
128 <string> the string
129 <index> the string index (zero relative)
130 returns the ascii code of the character
131
132 (upper-case-p <chr>) IS THIS AN UPPER CASE CHARACTER?
133 <chr> the character
134 returns true if the character is upper case, nil otherwise
135
136 (lower-case-p <chr>) IS THIS A LOWER CASE CHARACTER?
137 <chr> the character
138 returns true if the character is lower case, nil otherwise
139
140 (both-case-p <chr>) IS THIS AN ALPHABETIC (EITHER CASE) CHARACTER?
141 <chr> the character
142 returns true if the character is alphabetic, nil otherwise
143
144 (digit-char-p <chr>) IS THIS A DIGIT CHARACTER?
145 <chr> the character
146 returns the digit weight if character is a digit, nil otherwise
147
148 (char-code <chr>) GET THE ASCII CODE OF A CHARACTER
149 <chr> the character
150 returns the ASCII character code (integer)
151
152 (code-char <code>) GET THE CHARACTER WITH A SPECFIED ASCII CODE
153 <code> the ASCII code (integer)
154 returns the character with that code or nil
155
156 (char-upcase <chr>) CONVERT A CHARACTER TO UPPER CASE
157 <chr> the character
158 returns the upper case character
159
160 (char-downcase <chr>) CONVERT A CHARACTER TO LOWER CASE
161 <chr> the character
162 returns the lower case character
163
164 (digit-char <n>) CONVERT A DIGIT WEIGHT TO A DIGIT
165 <n> the digit weight (integer)
166 returns the digit character or nil
167
168 (char-int <chr>) CONVERT A CHARACTER TO AN INTEGER
169 <chr> the character
170 returns the ASCII character code
171
172 (int-char <int>) CONVERT AN INTEGER TO A CHARACTER
173 <int> the ASCII character code
174 returns the character with that code
175
176 (char< <chr1> <chr2>...)
177 (char<= <chr1> <chr2>...)
178 (char= <chr1> <chr2>...)
179 (char/= <chr1> <chr2>...)
180 (char>= <chr1> <chr2>...)
181 (char> <chr1> <chr2>...)
182 <chr1> the first character to compare
183 <chr2> the second character(s) to compare
184 returns t if predicate is true, nil otherwise
185 Note: case is significant with these comparison functions.
186
187 (char-lessp <chr1> <chr2>...)
188 (char-not-greaterp <chr1> <chr2>...)
189 (char-equalp <chr1> <chr2>...)
190 (char-not-equalp <chr1> <chr2>...)
191 (char-not-lessp <chr1> <chr2>...)
192 (char-greaterp <chr1> <chr2>...)
193 <chr1> the first string to compare
194 <chr2> the second string(s) to compare
195 returns t if predicate is true, nil otherwise
196 Note: case is not significant with these comparison functions.
197
198 
199 File: slisp, Node: I/O Functions, Next: Format Function, Prev: Character Functions, Up: Xlisp Tutorial
200
201 Input/Output Functions
202 ======================
203
204 (read [<stream> [<eof> [<rflag>]]]) READ AN EXPRESSION
205 <stream> the input stream (default is standard input)
206 <eof> the value to return on end of file (default is nil)
207 <rflag> recursive read flag (default is nil)
208 returns the expression read
209
210 (print <expr> [<stream>]) PRINT AN EXPRESSION ON A NEW LINE
211 <expr> the expression to be printed
212 <stream> the output stream (default is standard output)
213 returns the expression
214
215 (prin1 <expr> [<stream>]) PRINT AN EXPRESSION
216 <expr> the expression to be printed
217 <stream> the output stream (default is standard output)
218 returns the expression
219
220 (princ <expr> [<stream>]) PRINT AN EXPRESSION WITHOUT QUOTING
221 <expr> the expressions to be printed
222 <stream> the output stream (default is standard output)
223 returns the expression
224
225 (pprint <expr> [<stream>]) PRETTY PRINT AN EXPRESSION
226 <expr> the expressions to be printed
227 <stream> the output stream (default is standard output)
228 returns the expression
229
230 (terpri [<stream>]) TERMINATE THE CURRENT PRINT LINE
231 <stream> the output stream (default is standard output)
232 returns nil
233
234 (flatsize <expr>) LENGTH OF PRINTED REPRESENTATION USING PRIN1
235 <expr> the expression
236 returns the length
237
238 (flatc <expr>) LENGTH OF PRINTED REPRESENTATION USING PRINC
239 <expr> the expression
240 returns the length
241
242 
243 File: slisp, Node: Format Function, Next: File I/O Functions, Prev: I/O Functions, Up: Xlisp Tutorial
244
245 Format Function
246 ===============
247
248 (format <stream> <fmt> <arg>...) DO FORMATTED OUTPUT
249 <stream> the output stream
250 <fmt> the format string
251 <arg> the format arguments
252 returns output string if <stream> is nil, nil otherwise
253
254 The format string can contain characters that should be copied
255 directly to the output and formatting directives. The formatting
256 directives are:
257
258 ~A print next argument using princ
259 ~S print next argument using prin1
260 ~% start a new line
261 ~~ print a tilde character
262
263 
264 File: slisp, Node: File I/O Functions, Next: String Stream Functions, Prev: Format Function, Up: Xlisp Tutorial
265
266 File I/O Functions
267 ==================
268
269 (open <fname> &key :direction) OPEN A FILE STREAM
270 <fname> the file name string or symbol
271 :direction :input or :output (default is :input)
272 returns a stream
273
274 (close <stream>) CLOSE A FILE STREAM
275 <stream> the stream
276 returns nil
277
278 (read-char [<stream>]) READ A CHARACTER FROM A STREAM
279 <stream> the input stream (default is standard input)
280 returns the character
281
282 (peek-char [<flag> [<stream>]]) PEEK AT THE NEXT CHARACTER
283 <flag> flag for skipping white space (default is nil)
284 <stream> the input stream (default is standard input)
285 returns the character (integer)
286
287 (write-char <ch> [<stream>]) WRITE A CHARACTER TO A STREAM
288 <ch> the character to write
289 <stream> the output stream (default is standard output)
290 returns the character
291
292 (read-line [<stream>]) READ A LINE FROM A STREAM
293 <stream> the input stream (default is standard input)
294 returns the string
295
296 (read-byte [<stream>]) READ A BYTE FROM A STREAM
297 <stream> the input stream (default is standard input)
298 returns the byte (integer)
299
300 (write-byte <byte> [<stream>]) WRITE A BYTE TO A STREAM
301 <byte> the byte to write (integer)
302 <stream> the output stream (default is standard output)
303 returns the byte (integer)
304
305 
306 File: slisp, Node: String Stream Functions, Next: Structures, Prev: File I/O Functions, Up: Xlisp Tutorial
307
308 String Stream Functions
309 =======================
310
311 These functions operate on unnamed streams. An unnamed output stream
312 collects characters sent to it when it is used as the destination of any
313 output function. The functions 'get-output- stream-string' and string
314 or a list of characters.
315
316 An unnamed input stream is setup with the 'make-string-input- stream'
317 function and returns each character of the string when it is used as the
318 source of any input function.
319
320 (make-string-input-stream <str> [<start> [<end>]])
321 <str> the string
322 <start> the starting offset
323 <end> the ending offset + 1
324 returns an unnamed stream that reads from the string
325
326 (make-string-output-stream)
327 returns an unnamed output stream
328
329 (get-output-stream-string <stream>)
330 <stream> the output stream
331 returns the output so far as a string
332 Note: the output stream is emptied by this function
333
334 (get-output-stream-list <stream>)
335 <stream> the output stream
336 returns the output so far as a list
337 Note: the output stream is emptied by this function
338
339 
340 File: slisp, Node: Structures, Next: System Functions, Prev: String Stream Functions, Up: Xlisp Tutorial
341
342 Structures
343 ==========
344
345 XLISP provides a subset of the Common Lisp structure definition
346 facility. No options or slot options are allowed, but slots can have
347 default initialization expressions.
348
349 (defstruct name <slot-desc>...)
350 or
351 (defstruct (name <option>...) <slot-desc>...)
352 <name> the structure name symbol
353 <option> option description
354 <slot-desc> slot descriptions
355 returns the structure name
356
357 The recognized options are:
358
359 (:conc-name name)
360 (:include name [<slot-desc>...])
361
362 Note that if :CONC-NAME appears, it should be before :INCLUDE.
363
364 Each slot description takes the form:
365
366 <name>
367 or
368 (<name> <defexpr>)
369
370 If the default initialization expression is not specified, the slot
371 will be initialized to NIL if no keyword argument is passed to the
372 creation function.
373
374 DEFSTRUCT causes access functions to be created for each of the slots
375 and also arranges that SETF will work with those access functions. The
376 access function names are constructed by taking the structure name,
377 appending a '-' and then appending the slot name. This can be
378 overridden by using the :CONC-NAME option.
379
380 DEFSTRUCT also makes a creation function called MAKE- <structname>, a
381 copy function called COPY-<structname> and a predicate function called
382 <structname>-P. The creation function takes keyword arguments for each
383 of the slots.
384
385 For instance:
386
387 (defstruct foo bar (gag 2))
388
389 creates the following functions:
390
391 (foo-bar <expr>)
392 (setf (foo-bar <expr>) <value>)
393 (foo-gag <expr>)
394 (setf (foo-gag <expr>) <value>)
395 (make-foo &key :bar :gag)
396 (copy-foo <expr>)
397 (foo-p <expr>)
398
399 
400 File: slisp, Node: System Functions, Next: File I/O Examples, Prev: Structures, Up: Xlisp Tutorial
401
402 System Functions
403 ================
404
405 (load <fname> &key :verbose :print) LOAD A SOURCE FILE
406 <fname> the filename string or symbol
407 :verbose the verbose flag (default is t)
408 :print the print flag (default is nil)
409 returns the filename
410
411 (save <fname>) SAVE WORKSPACE TO A FILE
412 <fname> the filename string or symbol
413 returns t if workspace was written, nil otherwise
414
415 (restore <fname>) RESTORE WORKSPACE FROM A FILE
416 <fname> the filename string or symbol
417 returns nil on failure, otherwise never returns
418
419 (dribble [<fname>]) CREATE A FILE WITH A TRANSCRIPT OF A SESSION
420 <fname> file name string or symbol
421 (if missing, close current transcript)
422 returns t if the transcript is opened, nil if it is closed
423
424 (gc) FORCE GARBAGE COLLECTION
425 returns nil
426
427 (expand <num>) EXPAND MEMORY BY ADDING SEGMENTS
428 <num> the number of segments to add
429 returns the number of segments added
430
431 (alloc <num>) CHANGE NUMBER OF NODES TO ALLOCATE IN EACH SEGMENT
432 <num> the number of nodes to allocate
433 returns the old number of nodes to allocate
434
435 (room) SHOW MEMORY ALLOCATION STATISTICS
436 returns nil
437
438 (type-of <expr>) RETURNS THE TYPE OF THE EXPRESSION
439 <expr> the expression to return the type of
440 returns nil if the value is nil otherwise one of the symbols:
441 SYMBOL for symbols
442 OBJECT for objects
443 CONS for conses
444 SUBR for built-in functions
445 FSUBR for special forms
446 CLOSURE for defined functions
447 STRING for strings
448 FIXNUM for integers
449 FLONUM for floating point numbers
450 CHARACTER for characters
451 FILE-STREAM for file pointers
452 UNNAMED-STREAM for unnamed streams
453 ARRAY for arrays
454
455 (peek <addrs>) PEEK AT A LOCATION IN MEMORY
456 <addrs> the address to peek at (integer)
457 returns the value at the specified address (integer)
458
459 (poke <addrs> <value>) POKE A VALUE INTO MEMORY
460 <addrs> the address to poke (integer)
461 <value> the value to poke into the address (integer)
462 returns the value
463
464 (address-of <expr>) GET THE ADDRESS OF AN XLISP NODE
465 <expr> the node
466 returns the address of the node (integer)
467
468 (exit) EXIT XLISP
469 returns never returns
470
471 
472 File: slisp, Node: File I/O Examples, Next: Unix I/O Functions, Prev: System Functions, Up: Xlisp Tutorial
473
474 File I/O Examples
475 =================
476
477 Input from a File
478
479 To open a file for input, use the OPEN function with the keyword
480 argument :DIRECTION set to :INPUT. To open a file for output, use the
481 OPEN function with the keyword argument :DIRECTION set to :OUTPUT. The
482 OPEN function takes a single required argument which is the name of the
483 file to be opened. This name can be in the form of a string or a
484 symbol. The OPEN function returns an object of type FILE-STREAM if it
485 succeeds in opening the specified file. It returns the value NIL if it
486 fails. In order to manipulate the file, it is necessary to save the
487 value returned by the OPEN function. This is usually done by assigning
488 it to a variable with the SETQ special form or by binding it using LET
489 or LET*. Here is an example:
490
491 (setq fp (open "init.lsp" :direction :input))
492
493 Evaluating this expression will result in the file "init.lsp" being
494 opened. The file object that will be returned by the OPEN function will
495 be assigned to the variable "fp".
496
497 It is now possible to use the file for input. To read an expression
498 from the file, just supply the value of the "fp" variable as the
499 optional "stream" argument to READ.
500
501 (read fp)
502
503 Evaluating this expression will result in reading the first
504 expression from the file "init.lsp". The expression will be returned
505 as the result of the READ function. More expressions can be read from
506 the file using further calls to the READ function. When there are no
507 more expressions to read, the READ function will return NIL (or
508 whatever value was supplied as the second argument to READ).
509
510 Once you are done reading from the file, you should close it. To
511 close the file, use the following expression:
512
513 (close fp)
514
515 Evaluating this expression will cause the file to be closed.
516
517 Output to a File
518
519 Writing to a file is pretty much the same as reading from one. You
520 need to open the file first. This time you should use the OPEN
521 function to indicate that you will do output to the file. For example:
522
523 (setq fp (open "test.dat" :direction :output))
524
525 Evaluating this expression will open the file "test.dat" for output.
526 If the file already exists, its current contents will be discarded.
527 If it doesn't already exist, it will be created. In any case, a
528 FILE-STREAM object will be returned by the OPEN function. This file
529 object will be assigned to the "fp" variable.
530
531 It is now possible to write to this file by supplying the value of
532 the "fp" variable as the optional "stream" parameter in the PRINT
533 function.
534
535 (print "Hello there" fp)
536
537 Evaluating this expression will result in the string "Hello there"
538 being written to the file "test.dat". More data can be written to the
539 file using the same technique.
540
541 Once you are done writing to the file, you should close it. Closing
542 an output file is just like closing an input file.
543
544 (close fp)
545
546 Evaluating this expression will close the output file and make it
547 permanent.
548
549 A Slightly More Complicated File Example
550
551 This example shows how to open a file, read each Lisp expression from
552 the file and print it. It demonstrates the use of files and the use of
553 the optional "stream" argument to the READ function.
554
555 (do* ((fp (open "test.dat" :direction :input))
556 (ex (read fp) (read fp)))
557 ((null ex) nil)
558 (print ex))
559
560 
561 File: slisp, Node: Unix I/O Functions, Prev: File I/O Examples, Up: Xlisp Tutorial
562
563 Unix I/O Functions
564 ==================
565
566 The following functions were added to XLISP by Niels Mayer for use
567 with WINTERP. These functions are UN*X-specific:
568
569 POPEN - start a process and open a pipe as a read/write stream
570 (popen <shell-command> :direction <direction>)
571 <shell-cmd> is a string which is sent to shell
572 /bin/sh and is executed as command.
573 <direction> a keyword symbol, :input means a stream
574 is created that reads from stdout of
575 <shell-cmd>; :output means a stream
576 is created that writes to stdin of
577 <shell-cmd>. (:input is the default.)
578 returns a stream, or NIL if the pipe or /bin/sh
579 process couldn't be created.
580
581 PCLOSE -- close a pipe stream as opened by POPEN.
582 (pclose <stream>)
583 <stream> a stream object created by POPEN
584 returns T if the command executed successfully, else
585 returns the integer exit status of
586 <shell-cmd>.
587
588 SYSTEM - run a process, sending output (if any) to stdout/stderr
589 (system <shell-cmd>)
590 <shell-cmd> is a string which is sent to shell
591 /bin/sh and is executed as command.
592 returns T if the command executed successfully,
593 else returns the integer exit status of
594 <shell-cmd>.
595
596 FSCANF-FIXNUM - read a fixnum value from a stream using fscanf(3x).
597 (fscanf-fixnum <stream> <format>)
598 <stream> a stream object created via OPEN or POPEN.
599 Will give an error for "unnamed streams".
600 <format> a format string containing a single
601 conversion directive that will result in
602 an integer valued conversion %d, %u, %o,
603 %x, %ld, %lu, %lo and %lx style conversions
604 are acceptable for this routine. See the
605 manual page for fscanf(3x) for details.
606 returns an integer if fscanf(3x) reports that
607 the conversion specified by <format>
608 succeeded. Returns NIL if the conversion
609 wasn't successful, or if EOF was reached.
610
611 WARNING: specifying a <format> that will result in the conversion of
612 a result larger than sizeof(long) will result in corrupted memory and
613 core dumps.
614
615 FSCANF-STRING - read a string value from a stream using fscanf(3x).
616 (fscanf-string <stream> <format>)
617 <stream> a stream object created via OPEN or POPEN.
618 Will give an error for "unnamed streams".
619 <format> a format string containing a single
620 conversion directive that will result in
621 a string valued conversion. %s, %c, and
622 %[...] style conversions are acceptable for
623 this routine. See the manual page for
624 fscanf(3x) for details.
625 returns a string if fscanf(3x) reports that
626 the conversion specified by <format>
627 succeeded. Returns NIL if the conversion
628 wasn't successful, or if EOF was reached.
629
630 WARNING: specifying a <scanf-format> that will result in the
631 conversion of a result larger than 1024 characters will result in
632 corrupted memory and core dumps.
633
634 FSCANF-FLONUM - read a float from a stream using fscanf(3x).
635 (fscanf-flonum <stream> <format>)
636 <stream> a stream object created via OPEN or POPEN.
637 Will give an error for "unnamed streams".
638 <format> a format string containing a single
639 conversion directive that will result in
640 a FLONUM valued conversion. %e %f or %g
641 are valid conversion specifiers for this
642 routine. See the manual page for fscanf(3x)
643 for details.
644 returns a float if fscanf(3x) reports that
645 the conversion specified by <format>
646 succeeded. Returns NIL if the conversion
647 wasn't successful, or if EOF was reached.
648
649 WARNING: specifying a <scanf-format> that will result in the
650 conversion of a result larger than sizeof(float) will result in
651 corrupted memory and core dumps.
652
653 
654 File: slisp, Node: Xlisp Objects Tutorial, Next: Xlisp Language Reference, Prev: Xlisp Tutorial, Up: Top
655
656 Xlisp Objects Primer
657 ********************
658
659 Copyright
660 =========
661
662 This chapter is adapted from an 'XlispOop.doc' file with the
663 following copyright:
664
665 XLISP 2.0 OBJECTS PRIMER
666
667 by
668
669 Tim I Mikkelsen
670
671 February 3, 1990
672
673 Copyright (c) 1990 by Tim I. Mikkelsen. All Rights Reserved.
674 No part of this document may be copied, reproduced or translated
675 for commercial use without prior written consent of the author.
676 Permission is granted for non-commercial use as long as this
677 notice is left intact.
678
679 One of the features in the design of XLISP is object-oriented
680 programming. This primer is intended to serve as a very brief
681 introduction to the object facilities of the XLISP 2.0 dialect of
682 LISP. Note that the object features of XLISP are not based on
683 other existing object definitions in other LISP dialects. If you
684 find problems in the primer, I'd appreciate hearing.
685
686 Tim Mikkelsen
687
688 (tim@hpfcbig.SDE.HP.COM)
689
690 4316 Picadilly Drive
691
692 Fort Collins, Colorado 80526
693
694 * Menu:
695
696 * Programming Styles::
697 * Object Oriented Programming::
698 * Xlisp Object Terminology::
699 * Sending Messages::
700 * Classes::
701 * A Better Class Example::
702 * Instances::
703 * Methods::
704 * Messages To Superclass::
705 * Object And Class::
706 * A More Realistic Example::
707
708 
709 File: slisp, Node: Programming Styles, Next: Object Oriented Programming, Prev: Xlisp Objects Tutorial, Up: Xlisp Objects Tutorial
710
711 Programming Styles
712 ==================
713
714 There are many programming paradigms (models). Some of the paradigms
715 are procedural, functional, rule-based, declarative and object-oriented.
716 A language can have aspects of one or many of these programming models.
717
718 Procedure-Oriented
719 ------------------
720
721 The programming paradigm most people are familiar with is the
722 procedural style. The primitives in procedural programming are:
723 subroutines and data structures. Through these primitives, programmers
724 have some limited abilities to share programs and program fragments. C
725 and Pascal are examples of procedural languages. Some procedural
726 languages (such as Modula and ADA) have extensions that provide for
727 better sharing of code.
728
729 Object-Oriented Programming
730 ---------------------------
731
732 Object-oriented programming is based on the primitives of objects,
733 classes and messages. Objects are defined in terms of classes. Actions
734 occur by sending a message to an object. An object's definition can be
735 inherited from more general classes. Objective-C and C++ both are
736 object-oriented dialects of the C language. Many dialects of LISP have
737 some object oriented extension (Flavors, Common LOOPS, CLOS and others).
738 There currently is standards work proceeding to add object-oriented
739 programming to Common LISP.
740
741 
742 File: slisp, Node: Object Oriented Programming, Next: Xlisp Object Terminology, Prev: Programming Styles, Up: Xlisp Objects Tutorial
743
744 Object Oriented Programming
745 ===========================
746
747 So, the object-oriented programming model is based around the
748 concepts of objects, classes and messages. An object is essentially a
749 black box that contains internal state information. You send an object
750 a message which causes the object to perform some operation. Objects
751 are defined and described through classes.
752
753 One aspect of an object is that you do not have to know what is
754 inside - or how it works - to be able to use it. From a programming
755 point of view, this is very handy. You can develop a series of objects
756 for someone to use. If you need to change what goes on inside, the
757 users of the objects should be unaware.
758
759 Another aspect of objects is that of inheritance. You can build up
760 new classes from existing classes by inheriting the existing class's
761 functionality and then extending the new definition. For example, you
762 can define a tool class (with various attributes) and then go about
763 creating object instances tool-1, tool-2, and so on. You can also
764 create new sub-classes of the tool class like power-tool. This is also
765 very handy because you don't have to re-implement something if you can
766 build it up from existing code.
767
768 
769 File: slisp, Node: Xlisp Object Terminology, Next: Sending Messages, Prev: Object Oriented Programming, Up: Xlisp Objects Tutorial
770
771 Xlisp Object Terminology
772 ========================
773
774 There are, as previously mentioned, many different languages with
775 object-oriented extensions and facilities. The terminology, operations
776 and styles of these are very different. Some of the main definitions
777 for XLISP's object-oriented extensions are:
778
779 Object data type
780 The OBJECT DATA TYPE is a built-in data type of XLISP. Members of
781 the object data type are object instances and classes.
782
783 Object instances
784 An OBJECT INSTANCE is a composite structure that contains internal
785 state information, methods (the code which respond to messages), a
786 pointer to the object instance's defining class and a pointer to
787 the object's super-class. XLISP contains no built-in object
788 instances.
789
790 Class objects
791 A CLASS OBJECT is, essentially, the template for defining the
792 derived object instances. A class object, although used
793 differently from a simple object instance, is structurally a
794 member of the object data type. It is also contains the linking
795 mechanism that allows you to build class hierarchies (sub-classes
796 and super-classes). XLISP contains two built-in class objects:
797 OBJECT and CLASS.
798
799 Message selector
800 The MESSAGE SELECTOR is the symbol that is used to select a
801 particular action (Method) from the object.
802
803 Message
804 The MESSAGE is the combination of the message selector and the
805 data (if any) to be sent to the object.
806
807 Method
808 The METHOD is the actual code that gets executed when the object
809 receives the Message.
810
811 
812 File: slisp, Node: Sending Messages, Next: Classes, Prev: Xlisp Object Terminology, Up: Xlisp Objects Tutorial
813
814 Sending Messages
815 ================
816
817 The mechanism for sending messages to XLISP objects is via the SEND
818 function. It takes an object, a message selector and various optional
819 arguments (depending on the message selector).
820
821 The way that a user creates a new object is to send a :NEW message
822 to a previously defined class. The result of this SEND will return an
823 object, so this is normally preceded by a SETQ. The values shown in the
824 examples that follow may not match what you see if you try this on your
825 version of XLISP - this is not an error. The screens that are used in
826 the various examples are similar to what you should see on your computer
827 screen. The ">" is the normal XLISP prompt (the characters that follow
828 the prompt is what you should type in to try these examples).
829
830 ________________________________________________________________
831 |
832 | > (setq my-object (send object :new))
833 | #<Object: #2e100>
834 |________________________________________________________________
835
836 The object created here is of limited value. Most often, you create
837 a class object and then you create instances of that class. So in the
838 following example, a class called MY-CLASS is created that inherits its
839 definition from the a built-in CLASS definition. Then two instances are
840 created of the new class.
841
842 ________________________________________________________________
843 |
844 | > (setq my-class (send class :new '()))
845 | #<Object: #27756>
846 |
847 | > (setq my-instance (send my-class :new))
848 | #<Object: #27652>
849 |
850 | > (setq another-instance (send my-class :new))
851 |#<Object: #275da>
852 |________________________________________________________________
853
854 
855 File: slisp, Node: Classes, Next: A Better Class Example, Prev: Sending Messages, Up: Xlisp Objects Tutorial
856
857 Classes
858 =======
859
860 Previously, a :NEW message was used to create an object. The message
861 used to see what is in an object is the :SHOW message.
862
863 ________________________________________________________________
864 |
865 | > (send my-class :show)
866 | Object is #<Object: #27756>, Class is #<Object: #23fe2>
867 | MESSAGES = NIL
868 | IVARS = NIL
869 | CVARS = NIL
870 | CVALS = NIL
871 | SUPERCLASS = #<Object: #23fd8>
872 | IVARCNT = 0
873 | IVARTOTAL = 0
874 | #<Object: #27756>
875 |________________________________________________________________
876
877 From the display of the MY-CLASS object you can see there are a
878 variety of components. The components of a class are:
879
880 Class Pointer
881 This pointer shows to what class the object (instance or class)
882 belongs. For a class, this always points to the built-in object
883 CLASS. This is also true of the CLASS object, its class pointer
884 points to itself.
885
886 Superclass Pointer
887 This pointer shows what the next class up the class hierarchy is.
888 If the user does not specify what class is the superclass, it will
889 point to the built-in class OBJECT.
890
891 Messages
892 This component shows what messages are allowed for the class, and
893 the description of the method that will be used. If the method is
894 system-defined, it will show up in the form of '#<Subr-: #18b98>'.
895 Remember that the class hierarchy (through the Superclass Pointer)
896 is searched if the requested message is not found in the class.
897
898 Instance Variables
899 This component lists what instance variables will be created when
900 an object instance is created. If no instances of the class
901 exist, there are no Instance Variables. If there are 5 instances
902 of a class, there are 5 complete and different groups of the
903 Instance Variables.
904
905 Class Variables and Values
906 The CLASS VARIABLES (CVAR) component lists what class variables
907 exist within the class. The Class Values (CVAL) component shows
908 what the current values of the variables are. Class Variables are
909 used to hold state information about a class. There will be one
910 of each of the Class Variables, independent of the number of
911 instances of the class created.
912
913 
914 File: slisp, Node: A Better Class Example, Next: Instances, Prev: Classes, Up: Xlisp Objects Tutorial
915
916 A Better Class Example
917 ======================
918
919 The example previously shown does work, but the class and instances
920 created don't really do anything of interest. The following example
921 sets up a tool class and creates some tool instances.
922
923 ________________________________________________________________
924 |
925 | > (setq my-tools (send class :new '(power moveable operation)))
926 | #<Object: #277a6>
927 |
928 | > (send my-tools :answer :isnew '(pow mov op)
929 | '((setq power pow)
930 | (setq moveable mov)
931 | (setq operation op)))
932 | #<Object: #277a6>
933 |
934 | > (setq drill (send my-tools :new 'AC t 'holes))
935 | #<Object: #2ddbc>
936 |
937 | > (setq hand-saw (send my-tools :new 'none t 'cuts))
938 | #<Object: #2dc40>
939 |
940 | > (setq table-saw (send my-tools :new 'AC nil 'cuts))
941 | #<Object: #2db00>
942 |________________________________________________________________
943
944 So, a class of objects called MY-TOOLS was created. Note that the
945 class object MY-TOOLS was created by sending the :NEW message to the
946 built-in CLASS object. Within the MY-TOOL class, there are three
947 instances called DRILL, HAND-SAW and TABLE-SAW. These were created by
948 sending the :NEW message to the MY-TOOLS class object. Notice that the
949 parameters followed the message selector.
950
951 
952 File: slisp, Node: Instances, Next: Methods, Prev: A Better Class Example, Up: Xlisp Objects Tutorial
953
954 Instances
955 =========
956
957 The following is a display of the contents of some of the previously
958 created instances:
959
960 ________________________________________________________________
961 |
962 | > (send drill :show)
963 | Object is #<Object: #2ddbc>, Class is #<Object: #277a6>
964 | POWER = AC
965 | MOVEABLE = T
966 | OPERATION = HOLES
967 | #<Object: #2ddbc>
968 |
969 | > (send hand-saw :show)
970 | Object is #<Object: #2dc40>, Class is #<Object: #277a6>
971 | POWER = NONE
972 | MOVEABLE = T
973 | OPERATION = CUTS
974 | #<Object: #2dc40>
975 |________________________________________________________________
976
977 From the display of these instances you can see there are some
978 components and values. The components of an instance are:
979
980 Class Pointer
981 This pointer shows to which class the current object instance
982 belongs. It is through this link that the system finds the
983 methods to execute for the received messages.
984
985 Instance Variables and Values
986 The Instance Variables (IVAR) component lists what variables exist
987 within the instance. The Instance Values component holds what the
988 current values of the variables are. Instance Variables are used
989 to hold state information for each instance. There will be a
990 group of Instance Variables for each instance.
991
992 
993 File: slisp, Node: Methods, Next: Messages To Superclass, Prev: Instances, Up: Xlisp Objects Tutorial
994
995 Methods
996 =======
997
998 There have been a few of the messages and methods in XLISP shown to
999 this point (:NEW and :SHOW). The following are the methods built into
1000 XLISP:
1001
1002 `:ANSWER'
1003 The :ANSWER method allows you to define or change methods within a
1004 class.
1005
1006 `:CLASS'
1007 The :CLASS method returns the class of an object.
1008
1009 `:ISNEW'
1010 The :ISNEW method causes an instance to run its initialization
1011 code. When the :ISNEW method is run on a class, it resets the
1012 class state. This allows you to re-define instance variables,
1013 class variables, etc.
1014
1015 `:NEW'
1016 The :NEW method allows you to create an instance when the :NEW
1017 message is sent to a user-defined class. The :NEW method allows
1018 you to create a new class (when the :NEW message is sent to the
1019 built-in CLASS).
1020
1021 `:SHOW'
1022 The :SHOW method displays the instance or class.
1023
1024 
1025 File: slisp, Node: Messages To Superclass, Next: Object And Class, Prev: Methods, Up: Xlisp Objects Tutorial
1026
1027 Sending Messages To A Superclass
1028 ================================
1029
1030 In addition to the SEND function, there is another function called
1031 SEND-SUPER. The SEND-SUPER function causes the specified message to be
1032 performed by the superclass method. This is a mechanism to allow
1033 chaining of methods in a class hierarchy. This chaining behavior can be
1034 achieved by creating a method for a class with the :ANSWER message.
1035 Within the body of the method, you include a SEND-SUPER form. This
1036 function is allowed only inside the execution of a method of an object.
1037
1038 
1039 File: slisp, Node: Object And Class, Next: A More Realistic Example, Prev: Messages To Superclass, Up: Xlisp Objects Tutorial
1040
1041 Object And Class
1042 ================
1043
1044 The definition of the built-in class OBJECT is:
1045
1046 ________________________________________________________________
1047 |
1048 | > (send object :show)
1049 | Object is #<Object: #23fd8>, Class is #<Object: #23fe2>
1050 | MESSAGES = ((:SHOW . #<Subr-: #23db2>)
1051 | (:CLASS . #<Subr-: #23dee>)
1052 | (:ISNEW . #<Subr-: #23e2a>))
1053 | IVARS = NIL
1054 | CVARS = NIL
1055 | CVALS = NIL
1056 | SUPERCLASS = NIL
1057 | IVARCNT = 0
1058 | IVARTOTAL = 0
1059 | #<Object: #23fd8>
1060 |________________________________________________________________
1061
1062 Note that OBJECT is a class - as opposed to an "instance-style"
1063 object. OBJECT has no superclass, it is the top or root of the class
1064 hierarchy. OBJECT's class is CLASS.
1065
1066 ________________________________________________________________
1067 |
1068 | > (send class :show)
1069 | Object is #<Object: #23fe2>, Class is #<Object: #23fe2>
1070 | MESSAGES = ((:ANSWER . #<Subr-: #23e48>)
1071 | (:ISNEW . #<Subr-: #23e84>)
1072 | (:NEW . #<Subr-: #23ea2>))
1073 | IVARS = (MESSAGES IVARS CVARS CVALS SUPERCLASS
1074 | IVARCNT IVARTOTAL)
1075 | CVARS = NIL
1076 | CVALS = NIL
1077 | SUPERCLASS = #<Object: #23fd8>
1078 | IVARCNT = 7
1079 | IVARTOTAL = 7
1080 | #<Object: #23fe2>
1081 |________________________________________________________________
1082
1083 CLASS has a superclass of OBJECT. It's class is itself - CLASS.
1084

brinkley@uw.edu
ViewVC Help
Powered by ViewVC 1.1.26