PrettyWriter

java.lang.Object
- java.io.Writer
- - gnu.text.PrettyWriter

All Implemented Interfaces:

java.io.Closeable, java.io.Flushable, java.lang.Appendable, java.lang.AutoCloseable
```
public class PrettyWriter
extends java.io.Writer
```
The pretty printer (hereafter PP) is responsible for formatting the results of evaluating expressions so that the human user can easily read them. The PP may also be responsible for choosing where to break lines so that the output looks reasonable. Raw text that has not yet been written out is stored in the "buffer" array, while information about the structure of the text is stored in a queue of "formatting tokens" (see below) called queueInts. A circular queue is used when the PP is not dealing with shared structures, and a linear array is used when it is. This only effects how the formatting tokens are enqueued into the structure, and how the structure is dynamically expanded. Formatting tokens are simply contiguous chunks of the queue. All tokens have a type and a size. For example, there is a formatting token called QITEM_NEWLINE_TYPE whose size is specified by QITEM_NEWLINE_SIZE. The size includes these type and size bits. The tokens use the space allocated to them in different ways. For example, the tab token uses two of its chunks (ints) to specify at which column it was entered, and to which column it should expand to. The tokens are buffered by a display formatter. The display formatter walks the structure to be printed emitting these tokens when it finds it has to, as well as the actual characters to be printed! Remember, the formatting tokens are distinct from the actual characters written, they just control how the characters are displayed. To accommodate this dichotomy, the character buffer holds the actual characters as they appear to the display formatter, the queue holds the formatting tokens plus a mapping that specifies which character in the buffer they end at. Once the display formatter has finished walking the expression to be printed, the formatting queue is walked by the "destructive" methods, i.e., the ones that actually flush the buffer to the output port. As mentioned above, each token encodes the position it references in the character buffer, so we use this information to work our way through the buffer, occasionally modifying the buffer to look pretty (dictated by the formatting tokens). Examples of such modifications include changing a space character to a newline character so that the line will prettily fit on the specified line width, or more drastically, remove a shared object of the expression and replacing it will print-circle notation. Once everything has been flushed, the initial conditions are reset ready for the next printing.

Field Summary

Fields
Modifier and Type	Field and Description
`char[]`	`buffer` Holds all the text that has been output but not yet printed.
`int`	`bufferFillPointer` The index into BUFFER where more text should be put.
`static ThreadLocation`	`indentLoc`
`static int`	`initialBufferSize`
`static ThreadLocation`	`isSharing` Whether to resolve shared structures is dependent on the out:print-circle command line switch being set true.
`static ThreadLocation`	`lineLengthLoc`
`static ThreadLocation`	`miserWidthLoc`
`static int`	`NEWLINE_FILL`
`static int`	`NEWLINE_LINEAR`
`static int`	`NEWLINE_LITERAL`
`static int`	`NEWLINE_MANDATORY`
`static int`	`NEWLINE_MISER`
`static int`	`NEWLINE_SPACE` A non-nested ' ' gets an implicit NEWLINE_SPACE.
`protected java.io.Writer`	`out`
`int`	`pendingBlocksCount` Number of startLogicalBlock - number of endLogicalBlock.

Fields inherited from class java.io.Writer
lock

Constructor Summary

Constructors
Constructor and Description
`PrettyWriter(java.io.Writer out)` Construct a PrettyWriter with `prettyPrintingMode = 1`
`PrettyWriter(java.io.Writer out, boolean prettyPrintingMode)` Construct a PrettyWriter.
`PrettyWriter(java.io.Writer out, int lineLength)` Construct a PrettyWriter which breaks on a given line length.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addIndentation(int amount, boolean current)`
`void`	`clearBuffer()`
`void`	`clearIDHash()`
`void`	`clearWordEnd()`
`void`	`close()`
`void`	`closeThis()` Flush and close this local Writer, but not underlying Writers.
`void`	`endLogicalBlock()`
`void`	`endLogicalBlock(java.lang.String suffix)`
`int`	`enqueue(int kind, int size)` Enqueue a formatting token into `queueInts`.
`int`	`enqueueIndent(char kind, int amount)`
`void`	`enqueueNewline(int kind)` Enqueue a newline formatting token.
`void`	`flush()`
`void`	`forcePrettyOutput()`
`int`	`getColumnNumber()` Not meaningful if `prettyPrintingMode > 0`.
`protected int`	`getMiserWidth()`
`int`	`getPrettyPrintingMode()` Return pretty-printing mode.
`int`	`IDHashGetFromIndex(int index)`
`int`	`IDHashLookup(java.lang.Object obj)`
`int`	`IDHashPutAtIndex(java.lang.Object obj, int value, int index)`
`void`	`initialiseIDHash()`
`boolean`	`isPrettyPrinting()` Is pretty printing enabled?
`void`	`lineAbbreviationHappened()`
`void`	`resolveBackReferences()` Walk through the queue, emitting print circle notation as described in SRFI-38.
`void`	`setColumnNumber(int column)`
`void`	`setIndentation(int column)`
`void`	`setPrettyPrinting(boolean mode)` Turn pretty printing on or off.
`void`	`setPrettyPrintingMode(int mode)` Control pretty-printing mode.
`void`	`setSharing(boolean sharing)`
`void`	`startLogicalBlock(java.lang.String prefix, boolean perLine, java.lang.String suffix)`
`void`	`write(char[] str)`
`void`	`write(char[] str, int start, int count)`
`void`	`write(int ch)` Write a character to the buffer.
`void`	`write(java.lang.String str)`
`void`	`write(java.lang.String str, int start, int count)` Write a (sub)string to the output buffer.
`void`	`writeBackReference(int posn)` Enqueue a back-reference token to the formatting queue.
`void`	`writeBreak(int kind)`
`void`	`writeEndOfExpression()`
`void`	`writePairEnd(java.lang.Integer posn)` Enqueue a pair-end token to the formatting queue.
`int`	`writePositionMarker(boolean grouping)` A position marker is queued for every Scheme object that could refer to itself (or other parts of the structure).
`void`	`writeWordEnd()` Note the end of a "word".
`void`	`writeWordStart()` Maybe write a word-separating space.

Methods inherited from class java.io.Writer
append, append, append

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - out
```
protected java.io.Writer out
```
  - lineLengthLoc
```
public static ThreadLocation lineLengthLoc
```
  - miserWidthLoc
```
public static ThreadLocation miserWidthLoc
```
  - indentLoc
```
public static ThreadLocation indentLoc
```
  - isSharing
```
public static ThreadLocation isSharing
```
    Whether to resolve shared structures is dependent on the out:print-circle command line switch being set true. The PrettyWriter uses a different data structure to resolve back-references when we're emitting print-circle notation.
  - initialBufferSize
```
public static int initialBufferSize
```
  - buffer
```
public char[] buffer
```
    Holds all the text that has been output but not yet printed.
  - bufferFillPointer
```
public int bufferFillPointer
```
    The index into BUFFER where more text should be put.
  - pendingBlocksCount
```
public int pendingBlocksCount
```
    Number of startLogicalBlock - number of endLogicalBlock.
  - NEWLINE_LINEAR
```
public static final int NEWLINE_LINEAR
```
    See Also:
    Constant Field Values
  - NEWLINE_LITERAL
```
public static final int NEWLINE_LITERAL
```
    See Also:
    Constant Field Values
  - NEWLINE_FILL
```
public static final int NEWLINE_FILL
```
    See Also:
    Constant Field Values
  - NEWLINE_SPACE
```
public static final int NEWLINE_SPACE
```
    A non-nested ' ' gets an implicit NEWLINE_SPACE. This is treated similarly to NEWLINE_FILL, but not quite.
    
    See Also:
    Constant Field Values
  - NEWLINE_MISER
```
public static final int NEWLINE_MISER
```
    See Also:
    Constant Field Values
  - NEWLINE_MANDATORY
```
public static final int NEWLINE_MANDATORY
```
    See Also:
    Constant Field Values
- Constructor Detail
  - PrettyWriter
```
public PrettyWriter(java.io.Writer out)
```
    Construct a PrettyWriter with prettyPrintingMode = 1
    
    Parameters:
    out - The output to write to
    See Also:
    prettyPrintingMode
  - PrettyWriter
```
public PrettyWriter(java.io.Writer out,
            int lineLength)
```
    Construct a PrettyWriter which breaks on a given line length. If lineLength is strictly greater than one, prettyPrintingMode is set to 1, otherwise it's set to 0.
    
    Parameters:
    out - The output to write to
    lineLength - The column width lines should break on
    See Also:
    #lineLength
  - PrettyWriter
```
public PrettyWriter(java.io.Writer out,
            boolean prettyPrintingMode)
```
    Construct a PrettyWriter.
    
    Parameters:
    out - The output port to write to
    prettyPrintingMode - If true then prettyPrintingMode = 1 otherwise prettyPrintingMode = 0
- Method Detail
  - initialiseIDHash
```
public void initialiseIDHash()
```
  - clearIDHash
```
public void clearIDHash()
```
  - IDHashLookup
```
public int IDHashLookup(java.lang.Object obj)
```
  - IDHashGetFromIndex
```
public int IDHashGetFromIndex(int index)
```
  - IDHashPutAtIndex
```
public int IDHashPutAtIndex(java.lang.Object obj,
                   int value,
                   int index)
```
  - setPrettyPrintingMode
```
public void setPrettyPrintingMode(int mode)
```
    Control pretty-printing mode.
    
    Parameters:
    mode - the value 0 disables pretty-printing; the value 1 enables ecplicit pretty-printing; the value 2 enables pretty-printing with auto-fill, which means that spaces are treated like enqueing NEWLINE_SPACE (essentiall a 'fill').
  - setSharing
```
public void setSharing(boolean sharing)
```
  - getPrettyPrintingMode
```
public int getPrettyPrintingMode()
```
    Return pretty-printing mode.
    
    Returns:
    0, 1, 2, as described for setPrettyPrintingMode(int).
  - isPrettyPrinting
```
public boolean isPrettyPrinting()
```
    Is pretty printing enabled?
  - setPrettyPrinting
```
public void setPrettyPrinting(boolean mode)
```
    Turn pretty printing on or off. Equivalent to setPrettyPrintingMode(mode?1:0).
  - writeWordEnd
```
public void writeWordEnd()
```
    Note the end of a "word". See writeWordStart().
  - writeWordStart
```
public void writeWordStart()
```
    Maybe write a word-separating space. Specifically, write a space if the previous output was writeWordEnd(). Otherwise, do nothing.
  - clearWordEnd
```
public void clearWordEnd()
```
  - write
```
public void write(int ch)
```
    Write a character to the buffer. If we're pretty printing and the character is a space character, two cases arise. If the character is a newline, then enqueue a NEWLINE_LITERAL, which has to used. If the character is a space, then we may at our discretion place a newline there if the printing requires that we do so. Note that this doesn't mean we *will* print a newline, just that we can. For other characters, we just populate the buffer.
    
    Overrides:
    
    write in class java.io.Writer
    
    Parameters:
    ch - The character to write.
  - write
```
public void write(java.lang.String str)
```
    Overrides:
    
    write in class java.io.Writer
  - write
```
public void write(java.lang.String str,
         int start,
         int count)
```
    Write a (sub)string to the output buffer. Newlines and spaces are handled, and appropriate formatting token emitted in such cases.
    
    Overrides:
    
    write in class java.io.Writer
    
    Parameters:
    str - The string to use
    start - Where to start in the string
    count - The number of character to write from the string
  - write
```
public void write(char[] str)
```
    Overrides:
    
    write in class java.io.Writer
  - write
```
public void write(char[] str,
         int start,
         int count)
```
    Specified by:
    
    write in class java.io.Writer
  - writePositionMarker
```
public int writePositionMarker(boolean grouping)
```
    A position marker is queued for every Scheme object that *could* refer to itself (or other parts of the structure). Currently, this applies only to vectors and lists. For each such object, the printer records it. All position markers are assumed inactive (i.e. not back-referenced) until proven otherwise. Some position markers are required to group new sublists, the grouping variable notes this.
    
    Returns:
    Integer The index in queueInts where this marker resides it's used for back-reference lookup.
    See Also:
    writeBackReference(int)
  - writeBackReference
```
public void writeBackReference(int posn)
```
    Enqueue a back-reference token to the formatting queue. When the display formatter has detected that an object is referring to an "enclosing" object, a back-reference is queued. This makes the printer emit suitable notation to demonstrate the shared structure. The position marker this back-reference references is made active. If the structure to be printed was really sharing before, it is after this method.
    
    Parameters:
    posn - The index in the queueInts array of the referenced position marker.
  - writePairEnd
```
public void writePairEnd(java.lang.Integer posn)
```
    Enqueue a pair-end token to the formatting queue. When a position marker is grouping it creates a new sublist, which of course needs a closing parenthesis that's not originally present in the structure to be printed. This token informs the back reference resolver to emit an extra closing parenthesis so that the reader will be happy.
    
    Parameters:
    posn - The index in the queueInts array of the referenced position marker.
  - writeEndOfExpression
```
public void writeEndOfExpression()
```
  - setIndentation
```
public void setIndentation(int column)
```
  - enqueue
```
public int enqueue(int kind,
          int size)
```
    Enqueue a formatting token into queueInts. The kind and size parameters are packed into a 32-bit integer and then stored in the QITEM_TYPE_AND_SIZE offset of this token's computed base address. If the queueInts array is not big enough to hold the new token, two cases arise. If we're not handling a shared structure, the queue is expanded, and the old formatting tokens are moved to the high end of the queue, leaving new space at the front. If we are handling shared structure, the queue size is double, and we continue to enqueue items from the old queueSize.
    
    Parameters:
    kind - The type of formatting token
    size - The size of this formatting token
    
    Returns:
    The address of the token in queueInts
  - enqueueNewline
```
public void enqueueNewline(int kind)
```
    Enqueue a newline formatting token. A pass is made through the formatting tokens up to this one, where section sizes are computed. If we're not sharing, then a tentative output is done when the current buffer cannot fit on one line.
    
    Parameters:
    kind - The type of newline to enqueue
  - writeBreak
```
public final void writeBreak(int kind)
```
  - enqueueIndent
```
public int enqueueIndent(char kind,
                int amount)
```
  - addIndentation
```
public void addIndentation(int amount,
                  boolean current)
```
  - startLogicalBlock
```
public void startLogicalBlock(java.lang.String prefix,
                     boolean perLine,
                     java.lang.String suffix)
```
  - endLogicalBlock
```
public void endLogicalBlock()
```
  - endLogicalBlock
```
public void endLogicalBlock(java.lang.String suffix)
```
  - getMiserWidth
```
protected int getMiserWidth()
```
  - lineAbbreviationHappened
```
public void lineAbbreviationHappened()
```
  - resolveBackReferences
```
public void resolveBackReferences()
```
    Walk through the queue, emitting print circle notation as described in SRFI-38. For each position marker encountered, if the position marker has been referenced, emit the #N= notation. For each back-reference, find the corresponding position marker and emit the #N# notation. A Gap Buffer is employed to facilitate amortised linear buffer insertion when emitting the new print-circle notation. The method populates the rest of the buffer contents by using the QITEM_POSN information in SRFI-38 unrelated formatting tokens. When the print-circle notation has been emitted, future QITEM_POSN's need to be updated, this is achieved by maintaining a delta variable that records how many extra characters have been emitted to the output buffer.
  - forcePrettyOutput
```
public void forcePrettyOutput()
                       throws java.io.IOException
```
    Throws:
    
    java.io.IOException
  - flush
```
public void flush()
```
    Specified by:
    
    flush in interface java.io.Flushable
    
    Specified by:
    
    flush in class java.io.Writer
  - close
```
public void close()
           throws java.io.IOException
```
    Specified by:
    
    close in interface java.io.Closeable
    
    Specified by:
    
    close in interface java.lang.AutoCloseable
    
    Specified by:
    
    close in class java.io.Writer
    
    Throws:
    
    java.io.IOException
  - closeThis
```
public void closeThis()
               throws java.io.IOException
```
    Flush and close this local Writer, but not underlying Writers.
    
    Throws:
    
    java.io.IOException
  - getColumnNumber
```
public int getColumnNumber()
```
    Not meaningful if prettyPrintingMode > 0.
  - setColumnNumber
```
public void setColumnNumber(int column)
```
  - clearBuffer
```
public void clearBuffer()
```

Class PrettyWriter

Field Summary

Fields inherited from class java.io.Writer

Constructor Summary

Method Summary

Methods inherited from class java.io.Writer

Methods inherited from class java.lang.Object

Field Detail

out

lineLengthLoc

miserWidthLoc

indentLoc

isSharing

initialBufferSize

buffer

bufferFillPointer

pendingBlocksCount

NEWLINE_LINEAR

NEWLINE_LITERAL

NEWLINE_FILL

NEWLINE_SPACE

NEWLINE_MISER

NEWLINE_MANDATORY

Constructor Detail

PrettyWriter

PrettyWriter

PrettyWriter

Method Detail

initialiseIDHash

clearIDHash

IDHashLookup

IDHashGetFromIndex

IDHashPutAtIndex

setPrettyPrintingMode

setSharing

getPrettyPrintingMode

isPrettyPrinting

setPrettyPrinting

writeWordEnd

writeWordStart

clearWordEnd

write

write

write

write

write

writePositionMarker

writeBackReference

writePairEnd

writeEndOfExpression

setIndentation

enqueue

enqueueNewline

writeBreak

enqueueIndent

addIndentation

startLogicalBlock

endLogicalBlock

endLogicalBlock

getMiserWidth

lineAbbreviationHappened

resolveBackReferences

forcePrettyOutput

flush

close

closeThis

getColumnNumber

setColumnNumber

clearBuffer