lava.text
Class ParallelColumnsWriter

java.lang.Object
  |
  +--lava.text.ParallelColumnsWriter

public class ParallelColumnsWriter

extends java.lang.Object

Formats data into parallel columns.

Details: A ParallelColumnsWriter merges several streams of text into a single output stream, formatted as parallel columns. Each column flows independently of the others, except where relationships between column elements are specifically indicated.

The constructor for this class requires a Writer, which is the output stream for the merged inputs, and an array of ints, which indicate the width of each column. The length of the int array determines the total number of columns. Column data is submitted to a ParallelColumnsWriter using its write method, which accepts an array of Strings containing a line of text for each column. (Entries in the array that are set to null indicate that no data is being provided for the corresponding column.) Each column accumulates its text and formats it independently, but whenever the String array supplied to the write method contains more than one non-null entry, the lines of text given in that call are guaranteed to appear side-by-side.

The following example demonstrates the use of ParallelColumnsWriter.

Consider the following program:

1: import java.io.OutputStreamWriter; 2: import java.io.IOException; 3: import lava.text.ParallelColumnsWriter; 4: 5: class test 6: { 7: public static void main (String[] args) throws IOException 8: { 9: ParallelColumnsWriter cols = 10: new ParallelColumnsWriter 11: ( 12: new OutputStreamWriter (System . out), 13: new int[] {57, 10} 14: ); 15: for (int i = 1; i < 15; ++ i) 16: { 17: if (i == 10) 18: { 19: cols . writeln (new String[] {"Look at me!", "line 10"}); 20: continue; 21: } 22: cols . writeln (new String[] {null, "line " + i}); 23: if (i == 5) 24: cols . writeln 25: ( 26: new String[] 27: { 28: "The first five lines have already been sent to the right column.", 29: null 30: } 31: ); 32: } 33: cols . close (); 34: } 35: }

This program produces the following output:

The first five lines have already been sent to the right  | line 1
column.                                                   | line 2
                                                          | line 3
                                                          | line 4
                                                          | line 5
                                                          | line 6
                                                          | line 7
                                                          | line 8
                                                          | line 9
Look at me!                                               | line 10
                                                          | line 11
                                                          | line 12
                                                          | line 13
                                                          | line 14

Here's what happened (follow along in the code):

1. First, a ParallelColumnsWriter is initialized to format two parallel columns, with margins of 57 and 10 characters (source 9-14).
2. Inside the loop, text is sent only to the right column for the first 5 lines (source 22). At this point, the column writer hasn't produced any output yet, since data for the left column has not been received. (The lines for the right column are stored in a buffer.)
3. As soon as the first line of text for the left column is submitted (source 24-31), however, the column writer now has enough data to format the first two lines. (Note that the line in the left column automatically wrapped onto the next column.)
4. Next, lines 6-9 are sent, again only to the right side, and output is once again delayed.
5. In the next iteration, however, i=10, and so output is sent to both sides simultaneously (source 17-21). When this happens, the output is guaranteed to be aligned. The column writer automatically pads the left column with enough blank lines to synchronize the columns, and then outputs the two lines side by side.
6. For the remainder of the loop, lines 11 through 14 are sent to the right column only. Again, the column writer must delay its output by storing the right column text in a buffer.
7. When the writer is closed, however, the buffer is flushed, producing the rest of the output.

Constructor Summary

ParallelColumnsWriter(java.io.Writer writer, int[] col_widths)
Initialize a new ParallelColumnsWriter that writes to the specified Writer.

Method Summary

void	align(boolean[] which) Causes the indicated columns to be synchronized.
void	close() Flushes buffered column data and closes the output stream.
void	writeln(java.lang.String[] text) Enqueues lines of text into their respective columns.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ParallelColumnsWriter

public ParallelColumnsWriter(java.io.Writer writer,
                             int[] col_widths)

Initialize a new ParallelColumnsWriter that writes to the specified Writer. The number of columns is col_widths.length. The width of each column is given by an integer in col_widths.

Parameters:

writer - the output stream

col_widths - the number and widths of the columns

Method Detail

writeln

public void writeln(java.lang.String[] text)
             throws java.io.IOException

Enqueues lines of text into their respective columns. The lines of text are given in text, a String array. Note that the array's length must be equal to the number of columns specified when this instance was constructed. Elements in the array corresponding to columns for which no output is provided should be set to null. For all non-null entries however, the column writer will place those lines at the same depth in the output. (In other words, column lines submitted together will always appear together.) Except for this guarantee, column output is compacted as much as possible. (Note: Calls to this method will not always produce output. Output occurs only if all columns become non-empty as a result of the call.)

Parameters:

text - an array of text lines

Throws:

java.io.IOException - if an I/O error occurs

align

public void align(boolean[] which)
           throws java.io.IOException

Causes the indicated columns to be synchronized. In other words, all indicated columns except for the longest one will be padded with blank lines until they are the same length as the longest one. Columns are "indicated" by setting the entry in which, the indicator array, to true. (Note that calls to this method may result in output from the column writer, since an empty column that was "holding up" other columns may be padded as a result of this call.)

Parameters:

which - the column indicators

Throws:

java.io.IOException - if an I/O error occurs

close

public void close()
           throws java.io.IOException

Flushes buffered column data and closes the output stream.

Throws:

java.io.IOException - if an I/O error occurs