StructuredStreamsDoc.tioga
Mike Spreitzer July 30, 1986 9:36:03 pm PDT
StructuredStreams
CEDAR 6.0 — FOR INTERNAL XEROX USE ONLY
StructuredStreams
Mike Spreitzer
© Copyright 1985 Xerox Corporation. All rights reserved.
Abstract: StructuredStreams provides streams that format with whitespace according to a nested object structure. The basic formatting mechanism, UnparserBuffer, is also exported.
Keywords: Stream, Format, Whitespace, Pretty Print, Structure, Object, Nest
XEROX  Xerox Corporation
   Palo Alto Research Center
   3333 Coyote Hill Road
   Palo Alto, California 94304

For Internal Xerox Use Only
1. UnparserBuffer
This is a package originally made by Greg Nelson, to make it easy to pretty print parse trees. The documentation is in the interface. Here is a duplication of the introductory paragraph:
Formatted output routines. Send a stream of characters through a buffer, delineate the stream into subsequences called objects. The objects can be nested. (Objects are called "groups" in CGN9.) For each object, specify within it a set of breakpoints. The routines will format the text as follows. (1) An object will be printed all on one line if possible. (2) If an object cannot fit on one line, new lines will be started at one or more of the object's breakpoints, so that no text overflows the right margin. (3) With each breakpoint there is associated an integer call the breakpoint's offset. If a new line is started at a breakpoint, then the new line will be indented by the sum of the breakpoint's offset plus the indentation of the first character of the smallest object that contains the breakpoint. (4) Each breakpoint is labelled with the rules used for determining if it breaks. There are four sets of rules available: (width) break if and only if necessary to avoid overflowing the right margin; (united) like width, but also break if the smallest containing object contains (recursively) a breakpoint that breaks; (left-looking) like width, but also break if an object between the breakpoint in question and the preceeding breakpoint directly in the smallest enclosing object, if any, else the beginning of the smallest enclosing object, breaks; and (always) always break. (5) Each breakpoint has a sep, which is a string. If that breakpoint does not break, that string is inserted into the text after the breakpoint. If the breakpoint does break, the string is not inserted into the text.
2. StructuredStreams
StructuredStreams provides an IO.STREAM style interface to UnparserBuffer. Again, documented in the interface. Here's the introductory paragraph:
Greg Nelson has implemented a package called UnparserBuffer for his use in formatting Juno programs. StructuredStreams is a streams interface to it. A StructuredStream is an output stream, layered on another stream which recieves the formatted characters. A StructuredStream takes in a stream of characters, delimited into nested objects, each of which has a beginning, an end, and some breakpoints. The StructuredStream delivers to its understream the characters, interspersed with various white space characters (carriage returns and spaces) according to the formatting rules (described in UnparserBuffer.Mesa). The rules are such that characters sent to a StructuredStream outside of any object delimiters will not get any white space inserted among them. Also, StructuredStreams has been defined so that an ordinary stream used in place of a StructuredStream gives no ill effects.