diff --git a/doc/libdoc/dprint.alan b/doc/libdoc/dprint.alan new file mode 100755 index 00000000..c4a80375 --- /dev/null +++ b/doc/libdoc/dprint.alan @@ -0,0 +1,67 @@ +-*-Text-*- + +DPRINT is Alan's private hack for making defstructs print out nicely in +MacLisp. Unlike defstruct itself, DPRINT can be used in ways that are +incompatible with several other pieces of "semi-standard" MacLisp software, +notably the NIL-in-MacLisp STRING package and the NIL-in-MacLisp CLASS +system. + +DPRINT also defines a simple MacLisp INSPECT function, and a DESCRIBE +function. These can be safely used with anything else you might care to +load. No documentation is provided for either of these functions. To see +how DESCRIBE works, just apply it to a few things. To see how INSPECT +works, apply it to something and then type "?" to the prompt. One +non-obvious feature is that both functions, when applied to no arguments +will use the value of * as their argument. + +Because you might only want the DESCRIBE and INSPECT functions, just +loading DPRINT will not turn on any incompatibilities with any other +(known) MacLisp software package. However if you want to be able to +control the printing of hunks you can take the plunge and turn DPRINT on. +To do this use the DPRINT function which takes one argument. If that +argument is NIL then printing of hunks is reverted to the system default. +If that argument is non-NIL then smart hunk printing is turned on. + +Smart hunk printing does three things for you. + +1. Basic hunks print between square brackets rather than as funny-looking +conses. They also print with the CXR 0 element first. So where you used +to see "(BAR . BAZ . FOO .)" you now see "[FOO BAR BAZ]". This syntax will +NOT read back in again. If you really want to READ hunks, stop reading +now. + +2. "Named" hunks produced by defstruct will not print as above but will +print like "#SPACESHIP-72654", where "SPACESHIP" is the name of the +defstruct and 72654 is a unique octal number (actually the address of the +structure in memory). + +3. Named hunks produced by defstructs that used the :PRINT defstruct +option to specify a printed representation will print as specified. See +the defstruct documentation for more on that. (STRUCT.NEWS +contains the relevant update.) + +Two things to be aware of. + +1. In order to gain control of the printing of hunks, I have to grab +control of a resource that the NIL-in-MacLisp packages also attempt to +control. If I detect that they have already grabbed that resource, then +the DPRINT function will error. You may FORCE control of that resource by +saying (DPRINT 'SCREW). This will no doubt do unpredictable things to the +NIL-in-MacLisp crocks. Use it when you don't care about that. + +2. in order to control printing I have to be prepared to handle at lot of +other nonsense about hunks. Specifically I have been fored to make the +following decisions: + +Hunks will always self-evaluate. They have to do something because loading +a LEDIT on 20X requires that a single hunk be evaluated. (God knows why.) + +EQUAL will always compare two hunks using EQ. + +If some other operation is attempted on hunks that I don't find useful, you +will get the error message: + +;( . ) -- Unknown message to hunk. + +You can send me a complaint explaining just what it is that you think hunks +should do in this situation and we can negotiate it. \ No newline at end of file