org.clapper.util.io

Class WordWrapWriter

java.lang.Object

java.io.Writer

java.io.PrintWriter

org.clapper.util.io.WordWrapWriter

All Implemented Interfaces:

java.io.Closeable, java.io.Flushable, java.lang.Appendable, java.lang.AutoCloseable

public class WordWrapWriter
extends java.io.PrintWriter

The WordWrapWriter class is a filter class. A WordWrapWriter object wraps a Writer or OutputStream object, filtering output to the wrapped object so that output lines are broken on word boundaries and fit nicely within the proscribed output width. Messages may be written with prefixes or without them, depending upon various settings in the WordWrapWriter object; the columnar width of the output object can be controlled, as well.

For example, the long message

Unable to open file /usr/local/etc/wombat: No such file or directory

might appear like this without a prefix:

 Unable to open file /usr/local/etc/wombat: No such file or
 directory
 

and like this if the prefix is "myprog:"

 myprog: Unable to open file /usr/local/etc/wombat: No such
         file or directory
 

Alternatively, if the output width is shortened, the same message can be made to wrap something like this:

 myprog: Unable to open file
         /usr/local/etc/wombat:
         No such file or
         directory
 

Note how the WordWrapWriter output's logic will "tab" past the prefix on wrapped lines.

WordWrapWriter objects also support the notion of an indentation level, which is independent of the prefix. A non-zero indentation level causes each line, including the first line, to be indented that many characters. Thus, calling setIndentation() with a value of 4 will cause each output line to be preceded by 4 blanks. (It's also possible to change the indentation character from a blank to any other character. See setIndentationChar() for details.)

The logic is predicated on the notion of a "message"; that is, a WordWrapWriter object has to know where a message begins and ends, so it can tell when to write the prefix, reset its internal column count, etc. The class's notion of a message is straightforward: A message consists of all characters written to the object via one of the write() methods, up to and including either an embedded newline or a call to the flush() method. The println() methods implicitly call flush(), as does any write() method that encounters an embedded newline. Thus, it's rarely necessary to call flush() manually.

Notes

1. The class does not do any special processing of tab characters. Embedded tab characters can have surprising (and unwanted) effects on the rendered output.
2. Wrapping another WordWrapWriter object is an invitation to trouble.
3. Technically, this class probably ought to extend the java.io.FilterWriter class, since performs filtering of output written to another underlying Writer or OutputStream. However, I wanted WordWrapWriter to be polymorphically compatible with java.io.PrintWriter, so it could be passed to methods expecting a PrintWriter object; there are more methods that expect a PrintWriter than there are methods that expect a FilterWriter.

See Also:

Writer, PrintWriter

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_LINE_LENGTH The default line length.

Fields inherited from class java.io.PrintWriter

out

Fields inherited from class java.io.Writer

lock

Constructor Summary

Constructors

Constructor and Description
WordWrapWriter(java.io.OutputStream output) Build an WordWrapWriter object that will write its output to the specified OutputStream object, using the default line length of 80.
WordWrapWriter(java.io.OutputStream output, int lineLength) Build an WordWrapWriter object that will write its output to the specified OutputStream object, using the specified line length.
WordWrapWriter(java.io.OutputStream output, int lineLength, int indentSpaces) Build an WordWrapWriter object that will write its output to the specified OutputStream object, using the specified line length.
WordWrapWriter(java.io.PrintWriter output) Build an WordWrapWriter object that will write its output to the specified PrintWriter object, using the default line length of 80.
WordWrapWriter(java.io.PrintWriter output, int lineLength) Build an WordWrapWriter object that will write its output to the specified PrintWriter object, using the specified line length.
WordWrapWriter(java.io.PrintWriter output, int lineLength, int indentSpaces) Build an WordWrapWriter object that will write its output to the specified PrintWriter object, using the specified line length.
WordWrapWriter(java.io.Writer output) Build an WordWrapWriter object that will write its output to the specified Writer object, using the default line length of 80.
WordWrapWriter(java.io.Writer output, int lineLength) Build an WordWrapWriter object that will write its output to the specified Writer object, using the specified line length.
WordWrapWriter(java.io.Writer output, int lineLength, int indentSpaces) Build an WordWrapWriter object that will write its output to the specified Writer object, using the specified line length.

Method Summary

Modifier and Type	Method and Description
boolean	checkError() Flush the stream and check its error state.
void	close() Close the stream, flushing it first.
void	flush() Flush the stream.
int	getIndentation() Retrieve the current indentation setting for wrapped lines.
char	getIndentationChar() Get the current indentation character.
int	getLineLength() Retrieve the current line length.
java.lang.String	getPrefix() Get the current prefix.
void	print(boolean b) Print a boolean.
void	print(char c) Print a character.
void	print(char[] s) Print an array of characters.
void	print(double d) Print a double.
void	print(float f) Print a float.
void	print(int i) Print an integer.
void	print(long l) Print a long.
void	print(java.lang.Object x) Print an Object.
void	print(short s) Print a short.
void	print(java.lang.String s) Print a String.
void	println() End the current line.
void	println(boolean b) Print a boolean and finish the line.
void	println(char c) Print a character and finish the line.
void	println(char[] s) Print an array of characters.
void	println(double d) Print a double and finish the line.
void	println(float f) Print a float and finish the line.
void	println(int i) Print an integer.
void	println(long l) Print a long and finish the line.
void	println(java.lang.Object x) Print an Object and finish the line.
void	println(short s) Print a short and finish the line.
void	println(java.lang.String s) Print a String and finish the line.
void	setIndentation(int newIndentation) Set the indentation value for wrapped lines.
void	setIndentationChar(char c) Change the indentation character.
void	setLineLength(int newLineLength) Set the line length.
java.lang.String	setPrefix(java.lang.String newPrefix) Set the current prefix.
void	write(char[] cbuf) Write an array of characters.
void	write(char[] cbuf, int off, int len) Write a portion of an array of characters to the underlying output object.
void	write(int c) Write a single character.
void	write(java.lang.String s) Write a string.
void	write(java.lang.String s, int off, int len) Write a portion of a String of characters to the underlying output object.

Methods inherited from class java.io.PrintWriter

append, append, append, clearError, format, format, printf, printf, setError

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_LINE_LENGTH

public static final int DEFAULT_LINE_LENGTH

The default line length.

See Also:

Constant Field Values

Constructor Detail

WordWrapWriter

public WordWrapWriter(java.io.Writer output)

Build an WordWrapWriter object that will write its output to the specified Writer object, using the default line length of 80.

Parameters:

output - Where the output goes.

See Also:

DEFAULT_LINE_LENGTH, WordWrapWriter(Writer,int), WordWrapWriter(Writer,int,int), WordWrapWriter(PrintWriter), WordWrapWriter(OutputStream), Writer

WordWrapWriter

public WordWrapWriter(java.io.PrintWriter output)

Build an WordWrapWriter object that will write its output to the specified PrintWriter object, using the default line length of 80.

Parameters:

output - Where the output goes.

See Also:

DEFAULT_LINE_LENGTH, WordWrapWriter(Writer), WordWrapWriter(PrintWriter,int), WordWrapWriter(PrintWriter,int,int), WordWrapWriter(OutputStream), Writer

WordWrapWriter

public WordWrapWriter(java.io.OutputStream output)

Build an WordWrapWriter object that will write its output to the specified OutputStream object, using the default line length of 80.

Parameters:

output - Where the output goes.

See Also:

DEFAULT_LINE_LENGTH, WordWrapWriter(OutputStream,int), WordWrapWriter(OutputStream,int,int), WordWrapWriter(Writer), WordWrapWriter(PrintWriter), OutputStream

WordWrapWriter

public WordWrapWriter(java.io.Writer output,
                      int lineLength)

Build an WordWrapWriter object that will write its output to the specified Writer object, using the specified line length.

Parameters:

output - Where the output goes.

lineLength - The desired line length.

See Also:

DEFAULT_LINE_LENGTH, WordWrapWriter(Writer), WordWrapWriter(Writer,int,int), WordWrapWriter(PrintWriter,int), WordWrapWriter(OutputStream,int), Writer

WordWrapWriter

public WordWrapWriter(java.io.PrintWriter output,
                      int lineLength)

Build an WordWrapWriter object that will write its output to the specified PrintWriter object, using the specified line length.

Parameters:

output - Where the output goes.

lineLength - The desired line length.

See Also:

DEFAULT_LINE_LENGTH, WordWrapWriter(PrintWriter), WordWrapWriter(PrintWriter,int,int), WordWrapWriter(Writer,int), WordWrapWriter(OutputStream,int), Writer

WordWrapWriter

public WordWrapWriter(java.io.OutputStream output,
                      int lineLength)

Build an WordWrapWriter object that will write its output to the specified OutputStream object, using the specified line length.

Parameters:

output - Where the output goes.

lineLength - The desired line length.

See Also:

DEFAULT_LINE_LENGTH, WordWrapWriter(OutputStream), WordWrapWriter(OutputStream,int,int), WordWrapWriter(Writer,int), WordWrapWriter(PrintWriter,int), Writer

WordWrapWriter

public WordWrapWriter(java.io.Writer output,
                      int lineLength,
                      int indentSpaces)

Build an WordWrapWriter object that will write its output to the specified Writer object, using the specified line length. In addition, wrapped lines will be indented by the indicated number of spaces.

Parameters:

output - Where the output goes.

lineLength - The desired line length.

indentSpaces - How many blanks to indent lines that are wrapped.

See Also:

DEFAULT_LINE_LENGTH, WordWrapWriter(Writer), WordWrapWriter(Writer,int), WordWrapWriter(PrintWriter,int,int), WordWrapWriter(OutputStream,int,int), setIndentationChar(char), Writer

WordWrapWriter

public WordWrapWriter(java.io.PrintWriter output,
                      int lineLength,
                      int indentSpaces)

Build an WordWrapWriter object that will write its output to the specified PrintWriter object, using the specified line length. In addition, wrapped lines will be indented by the indicated number of spaces.

Parameters:

output - Where the output goes.

lineLength - The desired line length.

indentSpaces - How many blanks to indent lines that are wrapped.

See Also:

DEFAULT_LINE_LENGTH, WordWrapWriter(PrintWriter), WordWrapWriter(PrintWriter,int), WordWrapWriter(Writer,int,int), WordWrapWriter(OutputStream,int,int), setIndentationChar(char), Writer

WordWrapWriter

public WordWrapWriter(java.io.OutputStream output,
                      int lineLength,
                      int indentSpaces)

Build an WordWrapWriter object that will write its output to the specified OutputStream object, using the specified line length. In addition, wrapped lines will be indented by the indicated number of spaces.

Parameters:

output - Where the output goes.

lineLength - The desired line length.

indentSpaces - How many blanks to indent lines that are wrapped.

See Also:

DEFAULT_LINE_LENGTH, WordWrapWriter(OutputStream), WordWrapWriter(OutputStream,int), WordWrapWriter(Writer,int,int), WordWrapWriter(PrintWriter,int,int), setIndentationChar(char), Writer

Method Detail

checkError

public boolean checkError()

Flush the stream and check its error state.

Overrides:

checkError in class java.io.PrintWriter

close

public void close()

Close the stream, flushing it first. Closing a previously-closed stream has no effect.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Overrides:

close in class java.io.PrintWriter

flush

public void flush()

Flush the stream. If the stream has saved any characters from the various write() methods in a buffer, write them immediately to their intended destination. Then, if that destination is another character or byte stream, flush it. Thus one flush() invocation will flush all the buffers in a chain of Writers and OutputStreams.

Specified by:

flush in interface java.io.Flushable

Overrides:

flush in class java.io.PrintWriter

getIndentation

public int getIndentation()

Retrieve the current indentation setting for wrapped lines.

Returns:

The indentation setting, a count that indicates how many leading spaces will be emitted on wrapped lines.

getIndentationChar

public char getIndentationChar()

Get the current indentation character. By default, the indentation character is a blank.

Returns:

The current indentation character.

See Also:

setIndentationChar(char)

getPrefix

public java.lang.String getPrefix()

Get the current prefix. The prefix is the string that's displayed before the first line of output; subsequent wrapped lines are tabbed past the prefix.

Returns:

the current prefix, or null if there isn't one.

See Also:

setPrefix(java.lang.String)

getLineLength

public int getLineLength()

Retrieve the current line length.

Returns:

The line length.

setIndentation

public void setIndentation(int newIndentation)

Set the indentation value for wrapped lines.

Parameters:

newIndentation - The indentation setting, a count that indicates how many leading spaces will be emitted on wrapped lines. A value of 0 disables the feature.

Throws:

java.lang.IndexOutOfBoundsException - the value is negative

setIndentationChar

public void setIndentationChar(char c)

Change the indentation character. By default, the indentation character is a blank.

Parameters:

c - The new indentation character.

See Also:

getIndentationChar()

setLineLength

public void setLineLength(int newLineLength)
                   throws java.lang.IndexOutOfBoundsException

Set the line length.

Parameters:

newLineLength - The new line length to use. A value of 0 disables wrapping.

Throws:

java.lang.IndexOutOfBoundsException - the value is negative

setPrefix

public java.lang.String setPrefix(java.lang.String newPrefix)

Set the current prefix. The prefix is a string that's displayed before the first line of output; subsequent wrapped lines are tabbed past the prefix. For instance, suppose the prefix is set to "foo: ". A message emitted while "foo: " is the prefix might look like this:

 foo: Unable to access the frammistat: No
      such file or device.
 

Parameters:

newPrefix - The new prefix to be set

Returns:

the old prefix, or null if there isn't one.

See Also:

getPrefix()

print

public void print(boolean b)

Print a boolean.

Overrides:

print in class java.io.PrintWriter

Parameters:

b - The boolean to print

print

public void print(char c)

Print a character.

Overrides:

print in class java.io.PrintWriter

Parameters:

c - The character to print

print

public void print(char[] s)

Print an array of characters.

Overrides:

print in class java.io.PrintWriter

Parameters:

s - The array of characters to print

print

public void print(double d)

Print a double.

Overrides:

print in class java.io.PrintWriter

Parameters:

d - The double floating point number to print

print

public void print(float f)

Print a float.

Overrides:

print in class java.io.PrintWriter

Parameters:

f - The floating point number to print

print

public void print(int i)

Print an integer.

Overrides:

print in class java.io.PrintWriter

Parameters:

i - The integer to print

print

public void print(long l)

Print a long.

Overrides:

print in class java.io.PrintWriter

Parameters:

l - The long to print

print

public void print(short s)

Print a short.

Parameters:

s - The short to print

print

public void print(java.lang.String s)

Print a String.

Overrides:

print in class java.io.PrintWriter

Parameters:

s - The String to print.

print

public void print(java.lang.Object x)

Print an Object.

Overrides:

print in class java.io.PrintWriter

Parameters:

x - The object to print.

println

public void println()

End the current line.

Overrides:

println in class java.io.PrintWriter

println

public void println(boolean b)

Print a boolean and finish the line.

Overrides:

println in class java.io.PrintWriter

Parameters:

b - The boolean to print

println

public void println(char c)

Print a character and finish the line.

Overrides:

println in class java.io.PrintWriter

Parameters:

c - The character to print

println

public void println(char[] s)

Print an array of characters.

Overrides:

println in class java.io.PrintWriter

Parameters:

s - The array of characters to print

println

public void println(double d)

Print a double and finish the line.

Overrides:

println in class java.io.PrintWriter

Parameters:

d - The double floating point number to print

println

public void println(float f)

Print a float and finish the line.

Overrides:

println in class java.io.PrintWriter

Parameters:

f - The floating point number to print

println

public void println(int i)

Print an integer.

Overrides:

println in class java.io.PrintWriter

Parameters:

i - The integer to print

println

public void println(long l)

Print a long and finish the line.

Overrides:

println in class java.io.PrintWriter

Parameters:

l - The long to print

println

public void println(short s)

Print a short and finish the line.

Parameters:

s - The short to print

println

public void println(java.lang.String s)

Print a String and finish the line.

Overrides:

println in class java.io.PrintWriter

Parameters:

s - The String to print.

println

public void println(java.lang.Object x)

Print an Object and finish the line.

Overrides:

println in class java.io.PrintWriter

Parameters:

x - The object to print.

write

public void write(int c)

Write a single character. This method is called by all other write(), print() and println() methods. Thus, subclasses that wish to preprocess (or intercept) the output only have to override this method.

Overrides:

write in class java.io.PrintWriter

Parameters:

c - Character to write

write

public void write(char[] cbuf,
                  int off,
                  int len)

Write a portion of an array of characters to the underlying output object. Assumes the characters represent the start of a new line. Each line is indented according to this object's defined indentation level.

Overrides:

write in class java.io.PrintWriter

Parameters:

cbuf - Array of characters

off - Offset from which to start writing characters

len - Number of characters to write

write

public void write(java.lang.String s,
                  int off,
                  int len)

Write a portion of a String of characters to the underlying output object. Assumes the characters represent the start of a new line. Each line is indented according to this object's defined indentation level.

Overrides:

write in class java.io.PrintWriter

Parameters:

s - String from which to write

off - Offset from which to start writing characters

len - Number of characters to write

write

public void write(java.lang.String s)

Write a string.

Overrides:

write in class java.io.PrintWriter

Parameters:

s - String to write

write

public void write(char[] cbuf)

Write an array of characters.

Overrides:

write in class java.io.PrintWriter

Parameters:

cbuf - Array of characters to write