batgrl.text_tools

Tools for text.

Module Attributes

Cell	A structured array type that represents a single cell in a terminal.

Functions

_parse_batgrl_md(text)	Parse batgrl markdown and return the minimum canvas size to fit text and a list of lines of styled characters.
_smooth_bar(blocks, max_length, proportion, ...)	Create a smooth bar with given blocks.
_text_to_cells(text)	Convert some text to a list of lists of Cells and the minimum canvas size to fit them.
_write_lines_to_canvas(lines, canvas, ...)	Write a list of lists of Cells to a canvas array.
add_text(canvas, text, *[, fg_color, ...])	Add multiple lines of text to a view of a canvas.
binary_to_box(array_2x2)	Convert a (h, w, 2, 2)-shaped boolean array into a (h, w) array of box unicode characters.
binary_to_braille(array_4x2)	Convert a (h, w, 4, 2)-shaped boolean array into a (h, w) array of braille unicode characters.
cell_sans(*names)	Return all fields of Cell not in names.
char_width(char)	Return the column width of a character.
coerce_cell(char, default)	Try to coerce a string or Cell scalar into a half-width Cell scalar.
is_word_char(char)	Whether char is a word character.
new_cell([char, bold, italic, underline, ...])	Create a Cell scalar.
smooth_horizontal_bar(max_width, proportion)	Create a horizontal bar that's some proportion of max_width at an offset.
smooth_vertical_bar(max_height, proportion)	Create a vertical bar that's some proportion of max_height at an offset.
str_width(chars)	Return the total column width of a string.

batgrl.text_tools.Cell = dtype([('char', '<U1'), ('bold', '?'), ('italic', '?'), ('underline', '?'), ('strikethrough', '?'), ('overline', '?'), ('reverse', '?'), ('fg_color', 'u1', (3,)), ('bg_color', 'u1', (3,))])

A structured array type that represents a single cell in a terminal.

batgrl.text_tools.add_text(canvas: ndarray[Any, dtype[dtype(['char', '<U1', 'bold', '?', 'italic', '?', 'underline', '?', 'strikethrough', '?', 'overline', '?', 'reverse', '?', 'fg_color', 'u1', 3, 'bg_color', 'u1', 3])]], text: str, *, fg_color: Color | None = None, bg_color: Color | None = None, markdown: bool = False, truncate_text: bool = False)

Add multiple lines of text to a view of a canvas.

If markdown is true, text can be styled using batgrl markdown. The syntax is: - italic: *this is italic text* - bold: **this is bold text** - strikethrough: ~~this is strikethrough text~~ - underlined: __this is underlined text__ - overlined: ^^this is overlined text^^

Text is added starting at first index in canvas. Every new line is added on a new row.

Parameters:

canvasNDArray[Cell]

A 1- or 2-dimensional view of a Text canvas.

textstr

Text to add to canvas.

fg_colorColor | None, default: None

Foreground color of text. If not given, current canvas foreground color is used.

bg_colorColor | None, default: None

Background color of text. If not given, current canvas background color is used.

markdownbool, default: False

Whether to parse text for batgrl markdown.

truncate_textbool, default: False

For text that doesn’t fit on canvas, truncate text if true else raise an IndexError.

batgrl.text_tools.binary_to_box(array_2x2: ndarray[Any, dtype[bool | uint64]]) → ndarray[Any, dtype[dtype('<U1')]]

Convert a (h, w, 2, 2)-shaped boolean array into a (h, w) array of box unicode characters.

Parameters:

array_2x2NDArray[np.bool_]

A (h, w, 2, 2)-shaped boolean numpy array.

Returns:

NDArray[np.dtype(“<U1”)]

A numpy array of box unicode characters.

batgrl.text_tools.binary_to_braille(array_4x2: ndarray[Any, dtype[bool]]) → ndarray[Any, dtype[dtype('<U1')]]

Convert a (h, w, 4, 2)-shaped boolean array into a (h, w) array of braille unicode characters.

Parameters:

array_4x2NDArray[np.bool_]

A (h, w, 4, 2)-shaped boolean numpy array.

Returns:

NDArray[np.dtype(“<U1”)]

A numpy array of braille unicode characters.

batgrl.text_tools.cell_sans(*names: str) → list[str]

Return all fields of Cell not in names.

Parameters:

*namesstr

Excluded fields of Cell.

Returns:

list[str]

All fields of Cell not in names.

batgrl.text_tools.char_width(char: str) → int

Return the column width of a character.

Parameters:

charstr

A unicode character.

Returns:

int

The character column width.

batgrl.text_tools.coerce_cell(char: ndarray[Any, dtype[dtype(['char', '<U1', 'bold', '?', 'italic', '?', 'underline', '?', 'strikethrough', '?', 'overline', '?', 'reverse', '?', 'fg_color', 'u1', 3, 'bg_color', 'u1', 3])]] | str, default: ndarray[Any, dtype[dtype(['char', '<U1', 'bold', '?', 'italic', '?', 'underline', '?', 'strikethrough', '?', 'overline', '?', 'reverse', '?', 'fg_color', 'u1', 3, 'bg_color', 'u1', 3])]]) → ndarray[Any, dtype[dtype(['char', '<U1', 'bold', '?', 'italic', '?', 'underline', '?', 'strikethrough', '?', 'overline', '?', 'reverse', '?', 'fg_color', 'u1', 3, 'bg_color', 'u1', 3])]]

Try to coerce a string or Cell scalar into a half-width Cell scalar.

Parameters:

charNDArray[Cell] | str

The character to coerce.

defaultNDArray[Cell] | None, default: None

The fallback character (or None) if character can’t be coerced.

Returns:

NDArray[Cell] | None

The coerced Cell or None if character can’t be coerced.

batgrl.text_tools.is_word_char(char: str) → bool

Whether char is a word character.

A character is a word character if it is alphanumeric or an underscore.

Parameters:

charstr

The char to test.

Returns:

bool

Whether the char is a word character.

batgrl.text_tools.new_cell(char: str = ' ', bold: bool = False, italic: bool = False, underline: bool = False, strikethrough: bool = False, overline: bool = False, reverse: bool = False, fg_color: Color = (255, 255, 255), bg_color: Color = (0, 0, 0)) → ndarray[Any, dtype[dtype(['char', '<U1', 'bold', '?', 'italic', '?', 'underline', '?', 'strikethrough', '?', 'overline', '?', 'reverse', '?', 'fg_color', 'u1', 3, 'bg_color', 'u1', 3])]]

Create a Cell scalar.

A Cell is a structured array type that represents a single cell in a terminal.

Parameters:

charstr, default: “ “

The cell’s character.

boldbool, default: False

Whether cell is bold.

italicbool, default: False

Whether cell is italic.

underlinebool, default: False

Whether cell is underlined.

strikethroughbool, default: False

Whether cell is strikethrough.

overlinebool, default: False

Whether cell is overlined.

fg_colorColor, default: WHITE

Foreground color of cell.

bg_colorColor, default: BLACK

Background color of cell.

Returns:

NDArray[Cell]

A Cell scalar.

batgrl.text_tools.smooth_horizontal_bar(max_width: int, proportion: float, offset: float = 0.0) → tuple[str, ...]

Create a horizontal bar that’s some proportion of max_width at an offset.

Offset bars will return a minimum of 2 characters and the first character of the bar should have it’s colors reversed.

Parameters:

max_widthint

The width of the bar if the proportion was 1.0.

proportionfloat

The width of the bar as a proportion of the max_width.

offsetfloat, default: 0.0

Offset the bar horizontally by some non-negative amont.

Returns:

tuple[str, …]

The bar as a tuple of characters.

batgrl.text_tools.smooth_vertical_bar(max_height: int, proportion: float, offset: float = 0.0, reversed: bool = False) → tuple[str, ...]

Create a vertical bar that’s some proportion of max_height at an offset.

Offset bars will return a minimum of 2 characters and the first character of the bar should have it’s colors reversed (or, if bar is reversed, all colors should be reversed except first character).

Parameters:

max_heightint

The height of the bar if proportion was 1.0.

proportionfloat

The height of the bar as a proportion of the max_height.

offsetfloat, default: 0.0

Offset the bar vertically by some non-negative amount.

reversedbool, default: False

Reversed vertical bar is drawn top-to-bottom and offset downwards.

Returns:

tuple[str, …]

The bar as a tuple of characaters.

batgrl.text_tools.str_width(chars: str) → int

Return the total column width of a string.

Parameters:

charsstr

A string.

Returns:

int

The total column width of the string.