Module text 

Terminal text: making repository metadata safe to print, and measuring it in columns rather than in bytes.

Everything the banner shows comes out of the repository — a branch name, a recipe’s doc comment, a directory name — and none of it is trusted. A branch really can be called $(rm -rf /), and a doc comment really can carry an escape sequence that repaints the terminal, moves the cursor, or sets the window title. sanitise is what stands between that and a person’s shell.

Width is the other half. A box drawn by counting bytes falls apart on the first non-ASCII character, and a box drawn by counting chars falls apart on the first combining mark or CJK name. width counts columns.

Functions

char_width

The width of one character in terminal columns: zero for a combining mark, two for the wide and fullwidth blocks, one otherwise.

pad

Pad a string on the right to columns display columns, cutting it if it is longer.

pad_with

pad, with the truncation mark given explicitly.

sanitise

Make one value safe to print in a terminal.

truncate

Cut a string to at most columns display columns, ending with … when anything was removed. Never splits a character, and never returns something wider than it was asked for — including the ellipsis.

truncate_with

truncate, with the mark that says something was removed given explicitly. A terminal that cannot render … gets ..., and the width arithmetic follows the mark it was actually given rather than assuming one column.

width

The width of a string in terminal columns.