Faces

PrettyTables.jl accepts a Face of StyledStrings.jl everywhere a decoration can be passed: in the fields of every table style (TextTableStyle, HtmlTableStyle, LatexTableStyle, MarkdownTableStyle, TypstTableStyle, and ExcelTableStyle) and in the general highlighter Highlighter, which works with every back end. StyledStrings.jl is re-exported by PrettyTables.jl, and Face and SimpleColor are exported.

A face describes the attributes of a text:

Face(;
    font          = "Fira Code",
    height        = 120,              # Deci-points (`Int`) or a factor (`Float64`).
    weight        = :bold,            # :thin, :light, :normal, :medium, :bold, :black, ...
    slant         = :italic,          # :normal, :italic, or :oblique.
    foreground    = :red,             # Named color, "#rrggbb", or an `UInt32`.
    background    = "#f0f0f0",
    underline     = true,
    strikethrough = true,
    inverse       = true,
)

Each back end converts the face into its own decoration, ignoring the attributes it cannot represent.

General Highlighter

The general Highlighter is defined by a function f(data, i, j), which returns true if the cell (i, j) must be highlighted, and by a Face:

julia> hl = Highlighter((data, i, j) -> data[i, j] > 5, Face(; weight = :bold, foreground = :red));
julia> pretty_table([1 10; 3 7]; highlighters = [hl])┌────────┬────────┐
│ Col. 1 │ Col. 2 │
├────────┼────────┤
│      1 │     10 │
│      3 │      7 │
└────────┴────────┘
julia> pretty_table([1 10; 3 7]; backend = :html, highlighters = [hl])
julia> pretty_table([1 10; 3 7]; backend = :markdown, highlighters = [hl])| **Col. 1** | **Col. 2** |
|-----------:|-----------:|
|          1 |     **10** |
|          3 |      **7** |

It can also be created from the keywords of Face or from a Crayon:

Highlighter((data, i, j) -> data[i, j] > 5; weight = :bold, foreground = :red)
Highlighter((data, i, j) -> data[i, j] > 5, crayon"bold red")

or from a function fd(h, data, i, j) that returns the face (or the native decoration of the back end) of each highlighted cell:

Highlighter(
    (data, i, j) -> true,
    (h, data, i, j) -> Face(; foreground = data[i, j] > 5 ? :red : :blue),
)

Highlighters of different types can be mixed in the keyword highlighters, and the first match is applied. The decoration of a general highlighter is converted the first time it is used with a back end and cached.

Faces in Table Styles

Every keyword of the constructors of the table styles accepts a Face, which is converted to the decoration of the back end at construction:

julia> style = HtmlTableStyle(; title = Face(; weight = :bold, foreground = :red));
julia> style.title2-element Vector{Pair{String, String}}:
       "color" => "#a51c2c"
 "font-weight" => "bold"

The keywords first_line_column_label and column_label also accept a vector with one decoration per column, mixing faces and native decorations.

Conversion of Faces

The following functions convert a face into the decoration of each back end. They are exported, so that they can be used, for example, in the function fd of a back end highlighter.

The text back end renders the face using its escape sequence, generated by StringManipulation.jl. The named colors are resolved to the values StyledStrings.jl uses to render them in HTML (StringManipulation.face_color_rgb), and the default color of the terminal is ignored.

julia> face = Face(; weight = :bold, slant = :italic, foreground = :red, background = "#00ff00", underline = true, strikethrough = true);
julia> html_decoration(face)5-element Vector{Pair{String, String}}:
            "color" => "#a51c2c"
 "background-color" => "#00ff00"
      "font-weight" => "bold"
       "font-style" => "italic"
  "text-decoration" => "underline line-through"
julia> latex_decoration(face)6-element Vector{String}:
 "textbf"
 "textit"
 "underline"
 "sout"
 "textcolor[HTML]{A51C2C}"
 "colorbox[HTML]{00FF00}"
julia> markdown_decoration(face)MarkdownStyle(true, true, true, false)
julia> typst_decoration(face)4-element Vector{Pair{String, String}}:
 "text-weight" => "bold"
  "text-style" => "italic"
   "text-fill" => "rgb(\"#a51c2c\")"
        "fill" => "rgb(\"#00ff00\")"
julia> excel_decoration(face)7-element Vector{Pair{String, String}}:
              "bold" => "true"
            "italic" => "true"
             "under" => "single"
            "strike" => "true"
             "color" => "FFA51C2C"
 "cell_fill_pattern" => "solid"
 "cell_fill_fgColor" => "FF00FF00"

Styled Strings in Cells

A cell (or a column label, row label, and so on) can be a styled string of StyledStrings.jl (Julia 1.11 or newer). Every back end renders the regions of the string with their faces, converted with the functions above: the text back end writes the escape sequences, the HTML back end wraps each region in a span, the LaTeX back end in the environments, the Markdown back end in the markers, and the Typst back end in a text component. The Excel back end converts the regions to Excel's rich text format (XLSX.RichTextString), where each region becomes a run with the font attributes of its face. Backgrounds are dropped because Excel does not support per-run fills, and a string whose regions carry no font attributes is written as plain text. Notice that XLSX.jl writes a rich text string with a single run as plain text with a cell-level font, and that a table style or highlighter applied to the cell takes precedence over the run attributes it sets.

julia> matrix = [styled"{bold:Bold} and {red:red}" styled"{(fg=blue),italic:Blue italics}"];
julia> pretty_table(matrix; backend = :markdown)|       **Col. 1** |     **Col. 2** |
|-----------------:|---------------:|
| **Bold** and red | *Blue italics* |
julia> pretty_table(matrix; backend = :latex)\begin{tabular}{|r|r|}
  \hline
  \textbf{Col. 1} & \textbf{Col. 2} \\
  \hline
  \textbf{Bold} and \textcolor[HTML]{A51C2C}{red} & \textcolor[HTML]{195EB3}{\textit{Blue italics}} \\
  \hline
\end{tabular}

Compatibility with Crayons.jl

The text back end stores faces, but every place that accepts a Face also accepts a Crayon of Crayons.jl, which is converted to the equivalent face. The keyword constructors of TextHighlighter and Highlighter also accept the keywords of Crayon (bold, faint, italics, negative, foreground, background, underline, and strikethrough), translated to the equivalent attributes.

The conversion is lossy: the attributes blink, conceal, and reset are dropped, and the colors of the 256-color palette are converted to their 24-bit values (except the 16 system colors, which are converted to their names). The color names of Crayons.jl are translated to the ones of StyledStrings.jl (for example, :dark_gray becomes :bright_black and :light_red becomes :bright_red).