RevBank::Wrap

Word wrap output to the terminal width

---

Synopsis

binmode STDOUT, ":via(RevBank::Wrap)";

say "  give account amount reason  \tTransfer money to account";

Description

A PerlIO layer that word wraps lines that are wider than the terminal. Lines that fit are passed through unchanged. Without a terminal, nothing is wrapped, but the markers described below are still taken out.

The layer encodes text as UTF-8, so print characters, not encoded bytes.

Continuation lines are indented as far as the line's leading whitespace. A tab sets the indentation to the column it is in, and is not printed. If less than two fifths of the width, or fewer than $RevBank::Wrap::min_width columns, is left after the tab, the line is broken there instead, and the rest is indented two more than the leading whitespace.

Text in wide characters, like Japanese, is also broken between characters, where the Unicode line breaking rules allow it.

A no-break space ("\N{NBSP}") joins words so that the line is not broken there, and is printed as a normal space.

A word that is wider than the terminal is not broken, but left for the terminal to wrap, so that it can still be copied and pasted as a whole.

Text without a newline, like a prompt or cursor movement, is passed through unchanged when it is flushed. So is a line with control characters other than SGR escape sequences, because its width cannot be known.

Functions

wrap_line($line, $column, $columns)

Returns $line, which starts at $column, wrapped to $columns. With $columns 0, only the tabs are removed.

wrap_text($text)

Wraps each line of $text to the width of STDOUT, for text that is printed without going through the layer, like the prompt that readline prints.

width($text)

The number of columns that $text takes, not counting SGR escape sequences and readline's \x01 and \x02 markers.

clip($text, $columns)

The longest start of $text that fits in $columns.

Author

Juerd Waalboer #####@juerd.nl