Faces

PrettyTables.jl describes the decorations using the Face objects of StyledStrings.jl. A face can be passed:

• to the fields of the backend-agnostic TableStyle (see Table Format and Style);
• to the general Highlighter (see Highlighters);
• to the fields of every native table style (TextTableStyle, HtmlTableStyle, LatexTableStyle, MarkdownTableStyle, TypstTableStyle, ExcelTableStyle, and DocxTableStyle) and to the constructors of every native highlighter.

StyledStrings.jl is re-exported by PrettyTables.jl, and Face and SimpleColor are exported. Hence, no additional package must be loaded to style the tables.

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. For example, the Markdown back end only renders the bold and italic text.

Faces in Table Styles

The recommended way to decorate the table sections is the backend-agnostic TableStyle, whose fields are faces. Each field that is set overrides the corresponding field of the default style of the selected back end:

julia> style = TableStyle(;
           title = Face(; weight = :bold, foreground = :magenta),
           first_line_column_label = Face(; weight = :bold, foreground = :blue),
       );
julia> pretty_table([1 2; 3 4]; style, title = "Title")       Title
┌────────┬────────┐
│ Col. 1 │ Col. 2 │
├────────┼────────┤
│      1 │      2 │
│      3 │      4 │
└────────┴────────┘
julia> pretty_table([1 2; 3 4]; backend = :latex, style, title = "Title")\begin{tabular}{|r|r|}
  \multicolumn{2}{@{}c@{}}{\textcolor[HTML]{803D9B}{\textbf{Title}}} \\
  \hline
  \textcolor[HTML]{195EB3}{\textbf{Col. 1}} & \textcolor[HTML]{195EB3}{\textbf{Col. 2}} \\
  \hline
  1 & 2 \\
  3 & 4 \\
  \hline
\end{tabular}

The same style in the HTML back end:

pretty_table(HTML, [1 2; 3 4]; style, title = "Title")

Every keyword of the constructors of the native table styles also accepts a Face, which is converted to the decoration of the back end at construction. This is useful to set the fields that only exist in a specific back end, such as the table_border of TextTableStyle:

julia> style = TextTableStyle(; table_border = Face(; foreground = :yellow));
julia> pretty_table([1 2; 3 4]; style)┌────────┬────────┐
│ Col. 1 │ Col. 2 │
├────────┼────────┤
│      1 │      2 │
│      3 │      4 │
└────────┴────────┘
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.

Faces in Highlighters

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. It works with every back end:

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 = :latex, highlighters = [hl])\begin{tabular}{|r|r|}
  \hline
  \textbf{Col. 1} & \textbf{Col. 2} \\
  \hline
  1 & \textcolor[HTML]{A51C2C}{\textbf{10}} \\
  3 & \textcolor[HTML]{A51C2C}{\textbf{7}} \\
  \hline
\end{tabular}

For more information, see the section Highlighters.

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 native 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"
julia> docx_decoration(face)6-element Vector{Pair{String, String}}:
       "bold" => "true"
     "italic" => "true"
  "underline" => "single"
     "strike" => "true"
      "color" => "A51C2C"
 "background" => "00FF00"

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.

julia> matrix = [styled"{bold:Bold} and {red:red}" styled"{(fg=blue),italic:Blue italics}"];
julia> pretty_table(matrix)┌──────────────┬──────────────┐
│       Col. 1 │       Col. 2 │
├──────────────┼──────────────┤
│ Bold and red │ 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}

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.

The Word back end converts each region to a text run with the attributes of its face. Backgrounds are dropped because Word shades the entire cell, and, as in the Excel back end, the attributes of the table style or highlighter applied to the cell take precedence over the ones of the regions.

Compatibility with Crayons.jl

Before the support for faces, the decorations of the text back end were described using the Crayon objects of Crayons.jl. For backward compatibility, every place that accepts a Face also accepts a Crayon, which is converted to the equivalent face: the table styles of every back end, TableStyle, and the highlighters. The keyword constructors of the highlighters also accept the keywords of Crayon (bold, faint, italics, negative, foreground, background, underline, and strikethrough), translated to the equivalent attributes. However, new code should use faces.

The conversion is lossy: the attributes blink, conceal, and reset have no counterpart in a face and they are dropped with a warning, shown once per session; the attributes explicitly turned off (for example, bold = false) and the default color of the terminal are omitted because every styled segment of a table starts after a reset; bold has priority over faint when both are set; 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), which requires a terminal with 24-bit color support. 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).

The following table shows the equivalent faces of some common crayons: