package notty

empty is a zero-sized image.

string attr s is an image containing text s, styled with attr.

• raises Invalid_argument

  if string is not a valid UTF-8 sequence, or contains control characters.

uchars attr us is an image containing text us, styled with attr.

• raises Invalid_argument

  if us contains control characters.

char attr c w h is a w * h grid of c.

• raises Invalid_argument

  if c is a control character.

uchar attr u w h is a w * h grid of u.

• raises Invalid_argument

  if u is a control character.

void w h is a w * h rectangle of transparent cells.

void is magical: it has geometry, but no displayable content. This is different, for example, from the space character U+0020, which renders as a cell filled with the background color. This means that void interacts specially with overlays.

A negative size is treated as 0. void 0 0 is empty. Void with only one dimension 0 acts as a spacing element in the other dimension.

i1 <|> i2 is an image with i1 to the left of i2.

Its width = width i1 + width i2 and height = max (height i1) (height i2). Images are top-aligned. The missing region is implicitly filled with void.

[x] <|> [y] = [xy]
        [y]   [.y]

(Where . denotes void.)

<|> and void form a monoid. <|> is left-associative.

i1 <-> i2 is an image with i1 above i2.

Its width = max (width i1) (width i2) and height = height i1 + height i2. Images are left-aligned. The missing region is implicitly filled with void.

[xx] <-> [y] = [xx]
               [y.]

<-> and void form a monoid. <-> is left-associative.

i1 </> i2 is an image with i1 overlaid over i2.

Its width = max (width i1) (width i2) and height = max (height i1) (height i2). Images are top-left-aligned. In the region of their overlap, only the void cells of i1 show fragments of i2.

[x.x] </> [yyyy] = [xyxy]

</> and void form a monoid. </> is left-associative.

hcrop left right i is i with left leftmost, and right rightmost columns missing. If left + right >= width i the result is empty.

If either left or right is negative, instead of being cropped, the image is padded on that side.

For example:

• hcrop 0 1 [abc] = [ab]
• hcrop 1 1 [abc] = [b]
• hcrop (-1) 1 [abc] = void 1 1 <|> hcrop 0 1 [abc] = [.ab]
• hcrop 2 2 [abc] = empty

vcrop top bottom i is the vertical analogue to hcrop.

crop ~l:left ~r:right ~t:top ~b:bottom i is vcrop left right (hcrop top bottom) i.

Missing arguments default to 0.

hcrop with margins negated.

vcrop with margins negated.

crop with margins negated.

hcat xs horizontally concatenates xs. See beside.

vcat xs vertically concatenates xs. See above.

zcat xs overlays xs. See over.

tile m n i is a grid of m horizontal and n vertical repetitions of i.

hsnap ~align w i is an image of width strictly w obtained by either horizontally padding or cropping i and positioning it according to ~align.

~align defaults to `Middle.

vsnap ~align h i is an image of height strictly h obtained by either vertically padding or cropping i and positioning it according to ~align.

~align defaults to `Middle.

strf ?attr ?w:width format ... pretty-prints like Format.asprintf format ..., but returns an image.

attr is the (outermost) attribute. Defaults to A.empty.

width is used to set the margin on the formatter. This is only a hint, and does not guarantee the width of the result. Consult Format.set_margin for details. Defaults to an unspecified, large number.

kstrf ?attr ?w k format ... is continuation-based strf ?attr ?w format ....

attr a f is a pretty-printer like f, except its output is styled with a. This applies only outside of any styling f itself might embed.