batgrl.text_tools#

Tools for text.

Module Attributes

EGC_BASE

A bit flag to mark egcs in canvas arrays.

EGC_POOL

Storage for extended grapheme clusters.

EGCS

Extended grapheme clusters currently stored in EGC_POOL and their index.

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_cells_to_canvas(cells, 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.

canvas_as_text(canvas[, line_widths])

Return a Cell array as a single multi-line string.

egc_chr(ord)

Return the extended grapheme cluster represented by ord.

egc_ord(text)

Return either a unicode codepoint or an index into the egc pool for the first extended grapheme cluster in text.

is_word_char(char)

Whether char is a word character.

new_cell([ord, style, fg_color, bg_color])

Create a 0-dimensional cell_dtype array.

put_egc(canvas, text)

Set each ord in canvas to represent the first extended grapheme cluster in text.

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.

Classes

Style(*values)

The graphic rendition parameters of a terminal cell.

batgrl.text_tools.EGCS: dict[str, int] = {}#

Extended grapheme clusters currently stored in EGC_POOL and their index.

batgrl.text_tools.EGC_BASE: Final = 1572864#

A bit flag to mark egcs in canvas arrays. Must be greater than sys.maxunicode.

batgrl.text_tools.EGC_POOL: list[str] = []#

Storage for extended grapheme clusters.

If ord_ is an ord in a canvas array and ord_ & EGC_BASE is non-zero, then ord_ - EGC_BASE is an index into EGC_POOL. In this way, we can use the uint32 “ord” field in canvas arrays to store both codepoints and egcs.

class batgrl.text_tools.Style(*values)#

Bases: IntFlag

The graphic rendition parameters of a terminal cell.

Attributes:
denominator

the denominator of a rational number in lowest terms

imag

the imaginary part of a complex number

numerator

the numerator of a rational number in lowest terms

real

the real part of a complex number

Methods

as_integer_ratio(/)

Return a pair of integers, whose ratio is equal to the original int.

bit_count(/)

Number of ones in the binary representation of the absolute value of self.

bit_length(/)

Number of bits necessary to represent self in binary.

conjugate

Returns self, the complex conjugate of any int.

from_bytes(/, bytes[, byteorder, signed])

Return the integer represented by the given array of bytes.

is_integer(/)

Returns True.

to_bytes(/[, length, byteorder, signed])

Return an array of bytes representing an integer.

batgrl.text_tools.add_text(canvas: ndarray[tuple[int], dtype(['ord', '<u8', 'style', 'u1', 'fg_color', 'u1', 3, 'bg_color', 'u1', 3])] | ndarray[tuple[int, int], dtype(['ord', '<u8', 'style', 'u1', '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) None#

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:
canvasCell1D | Cell2D

A 1- or 2-dimensional view of a Cell array.

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.canvas_as_text(canvas: ndarray[tuple[int], dtype(['ord', '<u8', 'style', 'u1', 'fg_color', 'u1', 3, 'bg_color', 'u1', 3])] | ndarray[tuple[int, int], dtype(['ord', '<u8', 'style', 'u1', 'fg_color', 'u1', 3, 'bg_color', 'u1', 3])], line_widths: list[int] | None = None) str#

Return a Cell array as a single multi-line string.

Parameters:
canvasCell1D | Cell2D

The Cell array to convert.

line_widthslist[int] | None

Optionally truncate line n to have column width line_widths[n]. If line_widths[n] is greater than the column width of line n it is ignored.

Returns:
str

The canvas as a multi-line string.

batgrl.text_tools.egc_chr(ord: int) str#

Return the extended grapheme cluster represented by ord.

Parameters:
ordint

The ord of the extended grapheme cluster.

Returns:
str

The extended grapheme cluster represented by ord.

See also

egc_ord
batgrl.text_tools.egc_ord(text: str) int#

Return either a unicode codepoint or an index into the egc pool for the first extended grapheme cluster in text.

Parameters:
textstr

An extended grapheme cluster.

Returns:
int

A unicode codepoint or an index into EGC_POOL.

See also

egc_chr
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(ord: int = 32, style: ~batgrl.text_tools.Style = <Style.DEFAULT: 0>, fg_color: ~batgrl.colors.color_types.Color = (255, 255, 255), bg_color: ~batgrl.colors.color_types.Color = (0, 0, 0)) ndarray[tuple[()], dtype(['ord', '<u8', 'style', 'u1', 'fg_color', 'u1', 3, 'bg_color', 'u1', 3])]#

Create a 0-dimensional cell_dtype array.

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

Parameters:
ordint, default: 0x20

The cell’s character’s ord.

styleStyle, Style.DEFAULT

The style (bold, italic, etc.) of the cell.

fg_colorColor, default: WHITE

Foreground color of cell.

bg_colorColor, default: BLACK

Background color of cell.

Returns:
Cell0D

A 0-dimensional cell_dtype array.

batgrl.text_tools.put_egc(canvas: ndarray[tuple[int, ...], dtype(['ord', '<u8', 'style', 'u1', 'fg_color', 'u1', 3, 'bg_color', 'u1', 3])], text: str) None#

Set each ord in canvas to represent the first extended grapheme cluster in text.

Parameters:
canvasCell2D

A Cell array or view.

textstr

An extended grapheme cluster.

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.