sextile.viewdata.wrapping

Breaking text into lines narrow enough for a viewdata frame.

Forty columns is narrow, and a word that fits no line is split rather than dropped or allowed to overrun. Widths are counted in cells, not characters, because transliteration can lengthen a string on its way to the wire – the G0 set draws … as three full stops – so a line measured in characters can overrun the row it was wrapped for.

Lines are balanced by default rather than filled greedily: balancing chooses the breaks that minimise the squared slack, spreading the unavoidable gap across several lines rather than stranding it on one. Breaking says how the slack is laid out – PARAGRAPH leaves the last line free, since a paragraph’s final line is expected to be short; DISPLAY counts it, so a short centred title reads as two even lines rather than a full one and an orphan.

class sextile.viewdata.wrapping.Breaking(*values)

Bases: Enum

How wrapping lays the unavoidable slack across the lines it breaks into.

GREEDY

As much on each line as fits, taken in turn.

PARAGRAPH

Balanced with the last line free, for body text: a paragraph’s final line is expected to be short, so the lines before it are not crammed to fatten it. The default.

DISPLAY

Balanced with the last line counted, for a centred or display string, so a short two-line title reads as two even lines rather than a full first line and an orphan.

sextile.viewdata.wrapping.wrap_text(text, width, *, breaking=Breaking.PARAGRAPH)

Break text into lines of at most width cells.

Parameters:

• text (str) – The text to wrap.

• width (int) – The cells a line may take.

• breaking (Breaking) – How to lay the slack across the lines – PARAGRAPH (the default) for body text, DISPLAY for a centred string, GREEDY to fill each line in turn. See Breaking.

Return type:

list[str]

Returns:

The lines. Whitespace collapses to single spaces, no line carries leading or trailing space, and a word wider than width is split across as many lines as it needs.

Raises:

ValueError – If width is less than one.

sextile.viewdata.wrapping.wrap_within(text, *, cells, rows, breaking=Breaking.PARAGRAPH)

Wrap text to a region with a height as well as a width, cutting to fit.

Parameters:

• text (str) – The text to wrap.

• cells (int) – The cells a line may take.

• rows (int) – The most lines the region holds.

• breaking (Breaking) – How to lay the slack, as wrap_text takes it; DISPLAY for a centred region such as a masthead’s description.

Return type:

list[str]

Returns:

The wrapped lines, at most rows of them; the words that do not fit are the last ones, so size a region for the longest thing it can be handed. Empty for a region with no room, rather than raising, since a squeezed layout is a bug to fix and not a reason to fail on a live call.

Wrapped as usual and cut: balanced wrapping never needs a line a greedy fill would have saved, which holds for DISPLAY as well as PARAGRAPH.