frames0python.module
fault.format

Inline box rendering for replayable views of text content.

frames provides functions for formatting framed text from Content. Content represents a sequence rows consisting of a single column; the placement of str instances within the tuples contained by the sequence controls the alignment of the displayed text. A leading None within the instance causes a horizontal separator to be drawn according to the selected box theme.

Engineering

Somewhat of a warning. Raw (integer) indexes are commonly used within this module; the "themes" are regular strings, f_solid, and the indexes refer to the boundary character at that index within the theme. The included themes have identical character counts, but customized themes may have extensions in order to support transitions by stitch.

typing
import

itertools
import

functools
import

halves
data

halves = "\u258C\u2590"

charif
function

charif(characters)

Whether the character is a Unicode Box Drawing character.

Content
data

Content = typing.Sequence[
	typing.Union[
		# Left and Right text; use empty strings to disable a side.
		typing.Tuple[str, str],
		# Aligned center; only one field is allowed for centering.
		typing.Tuple[str, None],
		# Division (horizontal bar)
		typing.Tuple[None],
		# Division, custom horizontal.
		typing.Tuple[None, str],
	]
]

dlength
function

dlength(field)

dformat
function

dformat(context, field)

strings
function

strings(sequence)

Emit the formatted lines of a prepared sequence as str instances. Newline characters are not added to line.

keys
data

keys = [
	'top-left-corner',
	'top-horizontal-left',
	'top-intersection',
	'top-horizontal-right',
	'top-right-corner',
	'heading-vertical-open',
	'space',
	'heading-vertical-center',
	'space',
	'heading-vertical-close',
	'left-intersection',
	'body-horizontal-left',
	'full-intersection',
	'body-horizontal-right',
	'right-intersection',
	'body-vertical-open',
	'space',
	'body-vertical-center',
	'space',
	'body-vertical-close',
	'bottom-left-corner',
	'bottom-horizontal-left',
	'bottom-intersection',
	'bottom-horizontal-right',
	'bottom-right-corner',
	# Any extensions will be local to the frame theme.
]

corners
data

corners = [
	'top-left-corner',
	'top-right-corner',
	'bottom-left-corner',
	'bottom-right-corner',
]

f_ascii
data

f_ascii = (
	'+' '-' '+' '-' '+'
	'|' ' ' '|' ' ' '|'
	'+' '-' '+' '-' '+'
	'|' ' ' '|' ' ' '|'
	'+' '-' '+' '-' '+'
)

f_bold
data

f_bold = (
	'┏' '━' '┳' '━' '┓'
	'┃' ' ' '┃' ' ' '┃'
	'┣' '━' '╋' '━' '┫'
	'┃' ' ' '┃' ' ' '┃'
	'┗' '━' '┻' '━' '┛'
)

f_solid
data

f_solid = (
	'┌' '─' '┬' '─' '┐'
	'│' ' ' '│' ' ' '│'
	'├' '─' '┼' '─' '┤'
	'│' ' ' '│' ' ' '│'
	'└' '─' '┴' '─' '┘'
)

f_double
data

f_double = (
	'╔' '═' '╦' '═' '╗'
	'║' ' ' '║' ' ' '║'
	'╠' '═' '╬' '═' '╣'
	'║' ' ' '║' ' ' '║'
	'╚' '═' '╩' '═' '╝'
)

rounds
data

rounds=('╭' '╮' '╰' '╯')

_corner_adjustments
function

_corner_adjustments(space, selections)

round
function

round(theme, *corners)

Create a new theme based on theme applying rounded corners where specified in corners.

rdiagonal = round(f_solid, 'top-left', 'bottom-right')

width
function

width(sequence)

Calculate the sum of the lengths of each item in the sequence; excepting values starting with None representing a division.

prepare
function

prepare(theme, width, sequence)

Build sequences of strings providing the necessary formatting for the display of the framed data.

prepareParameters

theme

The frame characters to use by default. Usually one of f_ascii, f_solid, f_bold, f_double.

width

The span of the data to align on. Usually, the maximum length of a row calculated by max(width(sequence)).

sequence

An iterable producing tuples of strings that will populate the displayed rows.

minimum

Undocumented.

margins

Undocumented.

border

Undocumented.

len

Undocumented.

align
function

align(left, right, offsets)

Vertically pad the two prepared images with empty records according to the describes offsets.

alignParameters

left

The frame that will be placed on the left side.

right

The frame that will be placed on the right side.

offsets

The pair of vertical offsets for the left and right designating where their top will be placed. Defaults to zeros.

len

Undocumented.

sum

Undocumented.

map

Undocumented.

range

Undocumented.

combinations
data

combinations = {
	(5, 1): 12,
	(1, 5): 12,
	(4, 10): 12,
	(4, 20): 12,
	(14, 0): 12,
	(14, 10): 12,
	(14, 20): 12,
	(24, 10): 12,
	(24, 0): 12,

	(4, 5): 14,
	(14, 5): 14,
	(24, 5): 14,

	(5, 20): 10,
	(5, 10): 10,
	(5, 0): 10,
	(5, 15): 15,

	(4, 0): 2,
	(0, 4): 2,
	(5, 24): 19,
	(24, 20): 22,
}

combine
function

combine(theme, mapping, borders)

Calculate the combined border for the given characters according to the theme, combination mapping using the adjacent borders.

stitch
function

stitch(aligned)

Connects prepared frames along the vertical borders.

Join two prepared frames so that intersections are properly combined. Both the left and right sides are modified in place respecting the boundaries.

If the two prepared frames are not of equal length (rows), align must be called on the two frames before being given to stitch.

stitchParameters

aligned

An iterator of aligned pairs providing the left and right side to connect together into a combined image.

Multiple pairs are accepted to stitch the vertical edges as well as the horizontal.

combinations

Undocumented.