package matrix
Build not yet checkedInstall
dune-project
Dependency
Authors
Maintainers
Sources
sha256=a92cbbcbe016fb19fb0a749222da0e459a9567aef3f4c7340d9bd6b71c53ed6f
sha512=6a7ab054605538bb31a2b73a1a6d093981a2704c9f0af5852221c05735290d74aca7c7282298c4d0f91e86a800e2ccd94b4918af883cd963449c758eb6b272b3
doc/matrix.ansi/Ansi/Style/index.html
Module Ansi.StyleSource
Styles.
Styles, the colors, attributes and hyperlink of shown text.
A style gives text an optional foreground and background color (Color), a set of attributes (Attr), and an optional hyperlink, a URL that OSC 8 attaches to the text. A style is immutable.
Styles compose by merging an overlay over a base (merge), so that a style drawn over a theme refines it. The merge has the overlay's colors and link where the overlay has them and the base's otherwise, and the attributes of both. An absent color or link therefore inherits, and a merge never turns an attribute off. A program that needs one off, or no link, applies a modifier, such as with_bold false or unlink, to the merged style.
Written to a terminal, an absent color is the terminal's default color. emit writes the SGR codes that turn one style into another, and writes no hyperlink, which Ansi.render and Sgr_state handle.
This makes a title bold over a theme and prints it. The merge keeps the theme's colors, since the overlay has none:
let theme = Ansi.Style.make ~fg:Ansi.Color.white ~bg:Ansi.Color.blue () in
let title = Ansi.Style.(theme ++ make ~bold:true ()) in
print_string (Ansi.Style.styled ~reset:true title "Report")Styles
The type for styles. A program reads the fields by pattern matching and builds a style with this module's functions.
Constructors
val make :
?fg:Color.t ->
?bg:Color.t ->
?bold:bool ->
?dim:bool ->
?italic:bool ->
?underline:bool ->
?blink:bool ->
?inverse:bool ->
?hidden:bool ->
?strikethrough:bool ->
?overline:bool ->
?double_underline:bool ->
?framed:bool ->
?encircled:bool ->
?link:string ->
unit ->
tmake ?fg ?bg ... ?link () is the style with the colors fg and bg, the attributes whose arguments are true, and the hyperlink link. An omitted color or link is absent, and an omitted attribute is off.
Modifiers
A modifier is the style it is given with one property changed.
Colors
Attributes
with_bold b s to with_encircled b s are s with one attribute on if b is true and off otherwise.
with_attrs a s is s with the attributes a in place of its own.
overlay_attrs s a is s with the attributes a added to its own.
with_double_underline b s is s with double underline b.
with_hidden b s is s with hidden b.
Hyperlinks
Merging
resolve ss is default with each style of ss merged over it in turn, from first to last.
Predicates and comparisons
equal a b is true iff a and b have equal colors (Color.equal), attributes and links.
Writing
The transition from a style prev to a style s is the SGR codes that make a terminal showing prev show s. Its codes are those that clear attributes, then those that set the foreground and the background where they change, then those that set attributes. An attribute of s that shares its clearing code with a cleared one is set again. The transition ignores links.
A transition is written for a terminal of a color depth (Color.depth), `Truecolor unless depth says otherwise. Its colors are reduced by Color.to_depth and written by Color.emit_sgr_codes at that depth, as Sgr_state writes them.
sgr_sequence ~depth ~prev s is the SGR sequence of to_sgr_codes ~depth ~prev s, and "" if that is [].
Reading SGR
apply_sgr p s is s after SELECT GRAPHIC RENDITION with the parameters p (ECMA-48 §8.3.117). The parameters apply from left to right, so 7;0 leaves inverse off. An absent parameter is 0, and an empty list is a single 0.
- 0 resets the rendition to no colors and no attributes. The hyperlink stays, since OSC 8 sets it and SGR does not.
- An attribute code means what
emitwrites for it, so 1 is bold, 22 neither bold nor dim, 24 neither underline, and so on. 6, rapid blink, is blink.4:0is 24,4:2is 21 (double underline), and the other underline styles, such as4:3(curly), are 4. - 30..37, 90..97, 40..47 and 100..107 select a palette color, and 39 and 49 select
Color.default_fgandColor.default_bg. 38 and 48 select a color written as T.416 sub-parameters (38:5:n,38:2:r:g:bor38:2:cs:r:g:b) or as xterm's separate parameters (38;5;nor38;2;r;g;b). An incomplete color in the second form ends the list. 58, the underline color, is read the same way and changes nothing. - A parameter with sub-parameters changes nothing unless its code is 4, 38, 48 or 58, the codes whose sub-parameters SGR defines (ECMA-48 §5.4.2). So
1:2leaves bold as it was, and:changes nothing. - Other codes change nothing.
Formatting
pp ppf s formats s for inspection, such as "Style\{fg=#ff0000, attrs=[Bold]\}".