Library

T_BACKENDS

Types that define the supported backends.

struct ColumnTable

This structure helps to access elements that comply with the column access specification of Tables.jl.

Display

Store the information of the display and the current cursor position. Notice that this is not the real cursor position with respect to the display, but with respect to the point in which the table is printed.

Fields

• size: Display size.
• row: Current row.
• col: Current column.
• has_color: Indicates if the display has color support.
• cont_char: The character that indicates the line is cropped.
• cont_space_char: Space character to be printed before cont_char.

HTMLDecoration

Structure that defines parameters to decorate a table cell.

HTMLHighlighter

Defines the default highlighter of a table when using the html backend.

Fields

• f: Function with the signature f(data,i,j) in which should return true if the element (i,j) in data must be highlighter, or false otherwise.
• fd: Function with the signature f(h,data,i,j) in which h is the highlighter. This function must return the HTMLDecoration to be applied to the cell that must be highlighted.
• decoration: The HTMLDecoration to be applied to the highlighted cell if the default fd is used.

Remarks

This structure can be constructed using two helpers:

HTMLHighlighter(f::Function, decoration::HTMLDecoration)

HTMLHighlighter(f::Function, fd::Function)

The first will apply a fixed decoration to the highlighted cell specified in decoration whereas the second let the user select the desired decoration by specifying the function fd.

HTMLTableFormat

Format that will be used to print the HTML table. All parameters are strings compatible with the corresponding HTML property.

Fields

• css: CSS to be injected at the end of the <style> section.
• table_width: Table width.

Remarks

Besides the usual HTML tags related to the tables (table, td,th,tr, etc.), there are three important classes that can be used to format tables using the variablecss`.

• header: This is the class of the header (first line).
• subheader: This is the class of the sub-headers (all the rest of the lines in the header section).
• headerLastRow: The last row of the header section has additionally this class.
• rowNumber: All the cells related to the row number have this class. Thus, the row number header can be styled using th.rowNumber and the row numbers cells can be styled using td.rowNumber.

Highlighter

Defines the default highlighter of a table when using the text backend.

Fields

• f: Function with the signature f(data,i,j) in which should return true if the element (i,j) in data must be highlighter, or false otherwise.
• fd: Function with the signature f(h,data,i,j) in which h is the highlighter. This function must return the Crayon to be applied to the cell that must be highlighted.
• crayon: The Crayon to be applied to the highlighted cell if the default fd is used.

Remarks

This structure can be constructed using three helpers:

Highlighter(f::Function; kwargs...)

where it will construct a Crayon using the keywords in kwargs and apply it to the highlighted cell,

Highlighter(f::Function, crayon::Crayon)

where it will apply the crayon to the highlighted cell, and

Highlighter(f::Function, fd::Function)

where it will apply the Crayon returned by the function fd to the highlighted cell.

LatexHighlighter

Defines the default highlighter of a table when using the LaTeX backend.

Fields

• f: Function with the signature f(data,i,j) in which should return true if the element (i,j) in data must be highlighted, or false otherwise.
• fd: A function with the signature f(data,i,j,str)::String in which data is the matrix, (i,j) is the element position in the table, and str is the data converted to string. This function must return a string that will be placed in the cell.

Remarks

This structure can be constructed using two helpers:

LatexHighlighter(f::Function, envs::Union{String,Vector{String}})

LatexHighlighter(f::Function, fd::Function)

The first will apply recursively all the LaTeX environments in envs to the highlighted text whereas the second let the user select the desired decoration by specifying the function fd.

Thus, for example:

LatexHighlighter((data,i,j)->true, ["textbf", "small"])

will wrap all the cells in the table in the following environment:

\textbf{\small{<Cell text>}}

LatexTableFormat

This structure defines the format of the LaTeX table.

Fields

• top_line: Top line of the table.
• header_line: Line that separate the header from the table body.
• mid_line: Line printed in the middle of the table.
• bottom_line: Bottom line of the table.
• left_vline: Left vertical line of the table.
• mid_vline: Vertical line in the middle of the table.
• right_vline: Right vertical line of the table.
• header_envs: LaTeX environments that will be used in each header cell.
• subheader_envs: LaTeX environments that will be used in each sub-header cell.
• hlines: Horizontal lines that must be drawn by default.
• vlines: Vertical lines that must be drawn by default.
• table_type: Select the type of table that should be used for this format.
• wrap_table: Select if the table must be wrapped inside the environment defined by wrap_table_environment.
• wrap_table_environment: Environment in which the table will be wrapped if wrap_table is true.

PrettyTablesConf

Type of the object that holds a pre-defined set of configurations for PrettyTables.jl.

PrintInfo{Td,Th,Trn}

This structure stores the information required so that the backends can print the tables.

struct RowTable

This structure helps to access elements that comply with the row access specification of Tables.jl.

TextFormat

Fields

• up_right_corner: Character in the up right corner.
• up_left_corner: Character in the up left corner.
• bottom_left_corner: Character in the bottom left corner.
• bottom_right_corner: Character in the bottom right corner.
• up_intersection: Character in the intersection of lines in the up part.
• left_intersection: Character in the intersection of lines in the left part.
• right_intersection: Character in the intersection of lines in the right part.
• middle_intersection: Character in the intersection of lines in the middle of the table.
• bottom_intersection: Character in the intersection of the lines in the bottom part.
• column: Character in a vertical line inside the table.
• left_border: Character used as the left border.
• right_border: Character used as the right border.
• row: Character in a horizontal line inside the table.
• hlines: Horizontal lines that must be drawn by default.
• vlines: Vertical lines that must be drawn by default.

Pre-defined formats

The following pre-defined formats are available: unicode (default), mysql, compact, markdown, simple, ascii_rounded, and ascii_dots.

_aprint(buf::IO, [v,] indentation = 0, nspace = 2)

Print the variable v to the buffer buf at the indentation level indentation. Each level has nspaces spaces.

If v is not present, then only the indentation spaces will be printed.

_aprintln(buf::IO, [v,] indentation = 0, nspaces = 2)

Same as _aprint, but a new line will be added at the end.

_compute_table_size_data(header_str::Matrix{String}, data_str::Matrix{Vector{String}}, id_cols::Vector{Int}, Δc::Int, # Configurations columns_width::Vector{Int}, crop_subheader::Bool, maximum_columns_width::Vector{Int}, minimum_columns_width::Vector{Int}, noheader::Bool)

Compute the following table size data:

• The width of each column; and
• The maximum number of lines in the cells of each column.

_conf_to_nt(conf::PrettyTablesConf)

Convert the configuration object conf to a named tuple so that it can be passed to pretty_table.

_crop_str(str, crop_size, lstr = -1)

Return a cropped string of str with size crop_size. Notice that if the last character before the crop does not fit due to its width, then blank spaces are added.

The size of the string can be passed to lstr to save computational burden. If lstr = -1, then the string length will be computed inside the function.

_draw_continuation_row(display::Display, io::IO, tf::TextFormat, text_crayon::Crayon, border_crayon::Crayon, cols_width::Vector{Int}, vlines::Vector{Int}, alignment::Symbol)

Draw the continuation row when the table has filled the vertical space available. This function prints in each column the character ⋮ with the alignment in alignment.

_draw_line!(display::Display, io::IO, left::Char, intersection::Char, right::Char, row::Char, border_crayon::Crayon, cols_width::Vector{Int}, vlines::Vector{Int})

Draw a vertical line in internal line buffer of display and then flush to the io io.

_eol(display::Display)

Return true if the cursor is at the end of line or false otherwise.

_get_composed_ansi_format(ansi::Vector{T}) where T<:AbstractString

Given a vector with a set of ANSI escape sequences, return a composed escape sequence that leads to the same formatting.

_nl!(display::Display, io::IO)

Flush the internal line buffer of display into io.

_p!(display::Display, crayon::Crayon, str::Char, final_line_print::Bool = false, lstr::Int = -1)
_p!(display::Display, crayon::Crayon, str::String, final_line_print::Bool = false, lstr::Int = -1)

Print str into the internal line buffer of display using the Crayon crayon with the display information in display. The parameter final_line_print must be set to true if this is the last string that will be printed in the line. This is necessary for the algorithm to select whether or not to include the continuation character.

The size of the string can be passed to lstr to save computational burden. If lstr = -1, then the string length will be computed inside the function.

The line buffer can be flushed to an io using the function _nl!.

_parse_cell_html(cell::T; kwargs...)

Parse the table cell cell of type T. This function must return a string that will be printed to the IO.

_parse_cell_latex(cell::T; kwargs...)

Parse the table cell cell of type T. This function must return a string that will be printed to the IO.

_parse_cell_text(cell::T; kwargs...)

Parse the table cell cell of type T and return a vector of String with the parsed cell text, one component per line.

_pc!(cond::Bool, display::Display, io::IO, crayon::Crayon, str_true::Union{Char,String}, str_false::Union{Char,String}, final_line_print::Bool = false, lstr_true::Int = -1, lstr_false::Int = -1)

If cond == true then print str_true. Otherwise, print str_false. Those strings will be printed into the internal line buffer of display using the Crayon crayon with the display information in display. The parameter final_line_print must be set to true if this is the last string that will be printed in the line. This is necessary for the algorithm to select whether or not to include the continuation character.

The size of the strings can be passed to lstr_true and lstr_false to save computational burden. If they are -1, then the string lengths will be computed inside the function.

_print_title(buf::IO, title_tokens::Vector{String}, # Configurations has_color::Bool, title_crayon::Crayon)

Print the table title to the buffer buf.

_printable_textwidth(str::AbstractString)

Compute the width of the string str neglecting all ANSI escape sequences that are not printable.

_process_cell_text(data::Any, i::Int, j::Int, data_cell::Bool, data_str::String, data_len::Int, col_width::Int, crayon::Crayon, alignment::Symbol, highlighters::Ref{Any})

Process the cell by applying the right alignment and also verifying the highlighters.

_process_hlines(hlines::Union{Symbol,AbstractVector}, body_hlines::AbstractVector, num_printed_rows::Int, noheader::Bool)

Process the horizontal lines in hlines and body_hlines considering the number of printed rows num_printed_rows and if the header is present (noheader).

It returns a vector of Int stating where the horizontal lines must be drawn.

_process_vlines(vlines::AbstractVector, num_printed_cols::Int)

Process the vertical lines vlines considerering the number of printed columns num_printed_cols.

It returns a vector of Int stating where the vertical lines must be drawn.

_reapply_ansi_format!(lines::Vector{T}) where T<:AbstractString

For each line in lines, reapply the ANSI format left by the previous line.

_render_text(T, v; compact_printing::Bool = true, isstring::Bool = false, limit_printing::Bool = true, linebreaks::Bool = false)

Render the value v to strings using the rendered T to be displayed in the text back-end.

T can be:

• Val(:print): the function print will be used.
• Val(:show): the function show will be used.

This function must return a vector of strings in which each element is a line inside the rendered cell.

If linebreaks is true, then the rendered should split the created string into multiple tokens.

In case show is used, if isstring is false, then it means that the original data is not a string even if v is a string. Hence, the surrounding quotes added by show will be removed. This is required to correctly handle formatters.

If limit_printing is true, then v will be converted to string using the property :limit => true.

_str_aligned(data::String, alignment::Symbol, field_size::Integer, lstr::Integer = -1)

This function returns the string data with alignment alignment in a field with size field_size. alignment can be :l or :L for left alignment, :c or :C for center alignment, or :r or :R for right alignment. It defaults to :r if alignment is any other symbol.

This function also returns the new size of the aligned string.

If the string is larger than field_size, then it will be cropped and ⋯ will be added as the last character.

The size of the string can be passed to lstr to save computational burden. If lstr = -1, then the string length will be computed inside the function.

_str_autowrap(tokens_raw::Vector{String}, width::Int = 0)

Autowrap the tokens in tokens_raw considering a field width of width. It returns a new vector with the new wrapped tokens.

_str_escaped(str::AbstractString)

Return the escaped string representation of str.

_tokenize_title(title::AbstractString, display_width::Int, table_width::Int, # Configurations title_alignment::Symbol, title_autowrap::Bool, title_same_width_as_table::Bool)

Split the table title into tokens considering the line break character.

clear_pt_conf!(conf::PrettyTablesConf)

Clear all configurations in conf.

compact_type_str(T)

Return a string with a compact representation of type T.

ft_latex_sn(m_digits, [columns])

Format the numbers of the elements in the columns columns to a scientific notation using LaTeX. The number is first printed using sprintf1 functions with the g modifier and then converted to the LaTeX format. The number of digits in the mantissa can be selected by the argument m_digits.

If m_digits is a Vector, then columns must be also be a Vector with the same number of elements. If m_digits is a Integer, and columns is not specified (or is empty), then the format will be applied to the entire table. Otherwise, if m_digits is a String and columns is a Vector, then the format will be applied only to the columns in columns.

Remarks

This formatter will be applied only to the cells that are of type Number.

ft_printf(ftv_str, [columns])

Apply the formats ftv_str (see the function sprintf1 of the package Formatting.jl) to the elements in the columns columns.

If ftv_str is a Vector, then columns must be also be a Vector with the same number of elements. If ftv_str is a String, and columns is not specified (or is empty), then the format will be applied to the entire table. Otherwise, if ftv_str is a String and columns is a Vector, then the format will be applied only to the columns in columns.

Remarks

This formatter will be applied only to the cells that are of type Number.

ft_round(digits, [columns])

Round the elements in the columns columns to the number of digits in digits.

If digits is a Vector, then columns must be also be a Vector with the same number of elements. If digits is a Number, and columns is not specified (or is empty), then the rounding will be applied to the entire table. Otherwise, if digits is a Number and columns is a Vector, then the elements in the columns columns will be rounded to the number of digits digits.

hl_cell(i::Number, j::Number, crayon::Crayon)

Highlight the cell (i,j) with the crayon crayon.

hl_cell(cells::AbstractVector{NTuple(2,Int)}, crayon::Crayon)

Highlights all the cells in cells with the crayon crayon.

Remarks

Those functions return a Highlighter to be used with the text backend.

hl_cell(i::Number, j::Number, decoration::HTMLDecoration)

Highlight the cell (i,j) with the decoration decoration (see HTMLDecoration).

hl_cell(cells::AbstractVector{NTuple(2,Int)}, decoration::HTMLDecoration)

Highlights all the cells in cells with the decoration decoration (see HTMLDecoration).

Remarks

Those functions return a HTMLHighlighter to be used with the HTML backend.

hl_col(i::Number, crayon::Crayon)

Highlight the entire column i with the crayon crayon.

hl_col(cols::AbstractVector{Int}, crayon::Crayon)

Highlights all the columns in cols with the crayon crayon.

Remarks

Those functions return a Highlighter to be used with the text backend.

hl_col(i::Number, decoration::HTMLDecoration)

Highlight the entire column i with the decoration decoration.

hl_col(cols::AbstractVector{Int}, decoration::HTMLDecoration)

Highlights all the columns in cols with the decoration decoration.

Remarks

Those functions return a HTMLHighlighter to be used with the HTML backend.

hl_geq(n::Number, decoration::HTMLDecoration)

Highlight all elements that ≥ n using the decoration decoration.

Remarks

Those functions return a HTMLHighlighter to be used with the text backend.

hl_geq(n::Number)

Highlight all elements that ≥ n.

Remarks

Those functions return a Highlighter to be used with the text backend.

hl_gt(n::Number, decoration::HTMLDecoration)

Highlight all elements that > n using the decoration decoration.

Remarks

Those functions return a HTMLHighlighter to be used with the text backend.

hl_gt(n::Number)

Highlight all elements that > n.

Remarks

Those functions return a Highlighter to be used with the text backend.

hl_leq(n::Number, decoration::HTMLDecoration)

Highlight all elements that ≤ n using the decoration decoration.

Remarks

Those functions return a HTMLHighlighter to be used with the text backend.

hl_leq(n::Number)

Highlight all elements that ≤ n.

Remarks

Those functions return a Highlighter to be used with the text backend.

hl_lt(n::Number, decoration::HTMLDecoration)

Highlight all elements that < n using the decoration decoration.

Remarks

Those functions return a HTMLHighlighter to be used with the text backend.

hl_lt(n::Number)

Highlight all elements that < n.

Remarks

Those functions return a Highlighter to be used with the text backend.

hl_row(i::Number, crayon::Crayon)

Highlight the entire row i with the crayon crayon.

hl_row(rows::AbstractVector{Int}, crayon::Crayon)

Highlights all the rows in rows with the crayon crayon.

Remarks

Those functions return a Highlighter to be used with the text backend.

hl_row(i::Number, decoration::HTMLDecoration)

Highlight the entire row i with the decoration decoration.

hl_row(rows::AbstractVector{Int}, decoration::HTMLDecoration)

Highlights all the rows in rows with the decoration decoration.

Remarks

Those functions return a HTMLHighlighter to be used with the HTML backend.

hl_value(v::Any, decoration::HTMLDecoration)

Highlight all the values that matches data[i,j] == v using the decoration decoration.

Remarks

Those functions return a HTMLHighlighter to be used with the text backend.

hl_value(v::Any)

Highlight all the values that matches data[i,j] == v.

Remarks

Those functions return a Highlighter to be used with the text backend.

include_pt_in_file(filename::AbstractString, mark::AbstractString, args...; kwargs...)

Include a table in the file filename using the mark mark.

This function will print a table using the arguments args and keywords kwargs in the function pretty_table (the IO must not be passed to args here). Then, it will search inside the file filename for the following section:

<PrettyTables mark>
...
</PrettyTables>

and will replace everything between the marks with the printed table. If the closing tag is in a separate line, then all characters before it will be kept. This is important to add comment tags.

If the user wants to also remove the opening and ending tags, then pass the keyword remove_tags = true.

The keyword tag_append can be used to pass a string that can be used to add a text after the opening tag. This is important for HTML where the comments have openning and closing tags. Thus, if tag_append = " -->", then the following can be used to add a table into HTML files:

<!-- <PrettyTables mark> -->
...
<!-- </PrettyTables> -->

By default, this function will copy the original file to filename_backup. If this is not desired, then pass the keyword backup_file = false to the function.

pretty_table([io::IO | String,] table;  kwargs...)

Print to io the table table. If io is omitted, then it defaults to stdout. If String is passed in the place of io, then a String with the printed table will be returned by the function.

When printing, it will be verified if table complies with Tables.jl API. If it is compliant, then this interface will be used to print the table. If it is not compliant, then only the following types are supported:

1. AbstractVector: any vector can be printed.
2. AbstractMatrix: any matrix can be printed.
3. Dict: any Dict can be printed. In this case, the special keyword sortkeys can be used to select whether or not the user wants to print the dictionary with the keys sorted. If it is false, then the elements will be printed on the same order returned by the functions keys and values. Notice that this assumes that the keys are sortable, if they are not, then an error will be thrown.

Keywords

• alignment: Select the alignment of the columns (see the section Alignment).

• backend: Select which back-end will be used to print the table (see the section Backend). Notice that the additional configuration in kwargs... depends on the selected backend. (see the section Backend).

• cell_alignment: A tuple of functions with the signature f(data,i,j) that overrides the alignment of the cell (i,j) to the value returned by f. It can also be a single function, when it is assumed that only one alignment function is required, or nothing, when no cell alignment modification will be performed. If the function f does not return a valid alignment symbol as shown in section Alignment, then it will be discarded. For convenience, it can also be a dictionary of type (i,j) => a that overrides the alignment of the cell (i,j) to a. a must be a symbol like specified in the section Alignment.

  Note

  If more than one alignment function is passed to cell_alignment, then the functions will be evaluated in the same order of the tuple. The first one that returns a valid alignment symbol for each cell is applied, and the rest is discarded.

  (Default = nothing)

• cell_first_line_only: If true, then only the first line of each cell will be printed. (Default = false)

• compact_printing: Select if the option :compact will be used when printing the data. (Default = true)

• filters_row: Filters for the rows (see the section Filters).

• filters_col: Filters for the columns (see the section Filters).

• formatters: See the section Formatters.

• header: The header must be a tuple of vectors. Each one must have the number of elements equal to the number of columns in the table. The first vector is considered the header and the others are the subheaders. If it is nothing, then a default value based on the type will be used. If a single vector is passed, then it will be considered the header. (Default = nothing)

• header_alignment: Select the alignment of the header columns (see the section Alignment). If the symbol that specifies the alignment is :s for a specific column, then the same alignment in the keyword alignment for that column will be used. (Default = :s)

• header_cell_alignment: This keyword has the same structure of cell_alignment but in this case it operates in the header. Thus, (i,j) will be a cell in the header matrix that contains the header and sub-headers. This means that the data field in the functions will be the same value passed in the keyword header.

  Note

  If more than one alignment function is passed to header_cell_alignment, then the functions will be evaluated in the same order of the tuple. The first one that returns a valid alignment symbol for each cell is applied, and the rest is discarded.

  (Default = nothing)

• limit_printing: If true, then the cells will be converted using the property :limit => true of IOContext. (Default = true)

• renderer: A symbol that indicates which function should be used to convert an object to a string. It can be :print to use the function print or :show to use the function show. Notice that this selection is applicable only to the table data. Headers, sub-headers, and row name column are always rendered with print. (Default = :print)

• row_names: A vector containing the row names that will be appended to the left of the table. If it is nothing, then the column with the row names will not be shown. Notice that the size of this vector must match the number of rows in the table. (Default = nothing)

• row_name_alignment: Alignment of the column with the rows name (see the section Alignment).

• row_name_column_title: Title of the column with the row names. (Default = "")

• title: The title of the table. If it is empty, then no title will be printed. (Default = "")

• title_alignment: Alignment of the title, which must be a symbol as explained in the section Alignment. This argument is ignored in the LaTeX backend. (Default = :l)

Alignment

The keyword alignment can be a Symbol or a vector of Symbol.

If it is a symbol, we have the following behavior:

• :l or :L: the text of all columns will be left-aligned;
• :c or :C: the text of all columns will be center-aligned;
• :r or :R: the text of all columns will be right-aligned;
• Otherwise it defaults to :r.

If it is a vector, then it must have the same number of symbols as the number of columns in data. The i-th symbol in the vector specify the alignment of the i-th column using the same symbols as described previously.

Filters

It is possible to specify filters to filter the data that will be printed. There are two types of filters: the row filters, which are specified by the keyword filters_row, and the column filters, which are specified by the keyword filters_col.

The filters are a tuple of functions that must have the following signature:

f(data,i)::Bool

in which data is a pointer to the matrix that is being printed and i is the i-th row in the case of the row filters or the i-th column in the case of column filters. If this function returns true for i, then the i-th row (in case of filters_row) or the i-th column (in case of filters_col) will be printed. Otherwise, it will be omitted.

A set of filters can be passed inside of a tuple. Notice that, in this case, all filters for a specific row or column must be return true so that it can be printed, i.e the set of filters has an AND logic.

If the keyword is set to nothing, which is the default, then no filtering will be applied to the data.

Pretty table text back-end

This back-end produces text tables. This back-end can be used by selecting back-end = :text.

Keywords

• border_crayon: Crayon to print the border.

• header_crayon: Crayon to print the header.

• subheader_crayon: Crayon to print sub-headers.

• rownum_header_crayon: Crayon for the header of the column with the row numbers.

• text_crayon: Crayon to print default text.

• alignment_anchor_fallback: This keyword controls the line alignment when using the regex alignment anchors if a match is not found. If it is :l, then the left of the line will be aligned with the anchor. If it is :c, then the line center will be aligned with the anchor. Otherwise, the end of the line will be aligned with the anchor. (Default = :l)

• alignment_anchor_fallback_override: A Dict{Int, Symbol} to override the behavior of fallback_alignment_anchor for a specific column. Example: Dict(3 => :c) changes the fallback alignment anchor behavior for :c only for the column 3.

• alignment_anchor_regex: A dictionary Dict{Int, AbstractVector{Regex}} with a set of regexes that is used to align the values in the columns (keys). The characters at the first regex match (or anchor) of each line in every cell of the column will be aligned. The regex match is searched in the same order as the regexes appear on the vector. The regex matching is applied after the cell conversion to string, which includes the formatters. If no match is found for a specific line, then the alignment of this line depends on the options alignment_anchor_fallback and alignment_anchor_fallback_override. If the key 0 is present, then the related regexes will be used to align all the columns. In this case, all the other keys will be neglected. Example: Dict(2 => [r"\."]) aligns the decimal point of the cells in the second column. (Default = Dict{Int, Vector{Regex}}())

• autowrap: If true, then the text will be wrapped on spaces to fit the column. Notice that this function requires linebreaks = true and the column must have a fixed size (see columns_width).

• body_hlines: A vector of Int indicating row numbers in which an additional horizontal line should be drawn after the row. Notice that numbers lower than 1 and equal or higher than the number of printed rows will be neglected. This vector will be appended to the one in hlines, but the indices here are related to the printed rows of the body. Thus, if 1 is added to body_hlines, then a horizontal line will be drawn after the first data row. (Default = Int[])

• body_hlines_format: A tuple of 4 characters specifying the format of the horizontal lines that will be drawn by body_hlines. The characters must be the left intersection, the middle intersection, the right intersection, and the row. If it is nothing, then it will use the same format specified in tf. (Default = nothing)

• columns_width: A set of integers specifying the width of each column. If the width is equal or lower than 0, then it will be automatically computed to fit the large cell in the column. If it is a single integer, then this number will be used as the size of all columns. (Default = 0)

• crop: Select the printing behavior when the data is bigger than the available display size (see display_size). It can be :both to crop on vertical and horizontal direction, :horizontal to crop only on horizontal direction, :vertical to crop only on vertical direction, or :none to do not crop the data at all. If the io has :limit => true, then crop is set to :both by default. Otherwise, it is set to :none by default.

• crop_num_lines_at_beginning: Number of lines to be left at the beginning of the printing when vertically cropping the output. Notice that the lines required to show the title are automatically computed. (Default = 0)

• crop_subheader: If true, then the sub-header size will not be taken into account when computing the column size. Hence, the print algorithm can crop it to save space. This has no effect if the user selects a fixed column width. (Default = false)

• continuation_row_alignment: A symbol that defines the alignment of the cells in the continuation row. This row is printed if the table is vertically cropped. (Default = :c)

• display_size: A tuple of two integers that defines the display size (num. of rows, num. of columns) that is available to print the table. It is used to crop the data depending on the value of the keyword crop. Notice that if a dimension is not positive, then it will be treated as unlimited. (Default = displaysize(io))

• ellipsis_line_skip: An integer defining how many lines will be skipped from showing the ellipsis that indicates the text was cropped. (Default = 0)

• equal_columns_width: If true, then all the columns will have the same width. (Default = false)

• highlighters: An instance of Highlighter or a tuple with a list of text highlighters (see the section Text highlighters).

• hlines: This variable controls where the horizontal lines will be drawn. It can be nothing, :all, :none or a vector of integers.

  • If it is nothing, which is the default, then the configuration will be obtained from the table format in the variable tf (see TextFormat).
  • If it is :all, then all horizontal lines will be drawn.
  • If it is :none, then no horizontal line will be drawn.
  • If it is a vector of integers, then the horizontal lines will be drawn only after the rows in the vector. Notice that the top line will be drawn if 0 is in hlines, and the header and subheaders are considered as only 1 row. Furthermore, it is important to mention that the row number in this variable is related to the printed rows. Thus, it is affected by filters, and by the option to suppress the header noheader. Finally, for convenience, the top and bottom lines can be drawn by adding the symbols :begin and :end to this vector, respectively, and the line after the header can be drawn by adding the symbol :header.
  Info

  The values of body_hlines will be appended to this vector. Thus, horizontal lines can be drawn even if hlines is :none.

  (Default = nothing)

• linebreaks: If true, then \n will break the line inside the cells. (Default = false)

• maximum_columns_width: A set of integers specifying the maximum width of each column. If the width is equal or lower than 0, then it will be ignored. If it is a single integer, then this number will be used as the maximum width of all columns. Notice that the parameter columns_width has precedence over this one. (Default = 0)

• minimum_columns_width: A set of integers specifying the minimum width of each column. If the width is equal or lower than 0, then it will be ignored. If it is a single integer, then this number will be used as the minimum width of all columns. Notice that the parameter columns_width has precedence over this one. (Default = 0)

• newline_at_end: If false, then the table will not end with a newline character. (Default = true)

• noheader: If true, then the header will not be printed. Notice that all keywords and parameters related to the header and sub-headers will be ignored. (Default = false)

• nosubheader: If true, then the sub-header will not be printed, i.e. the header will contain only one line. Notice that this option has no effect if noheader = true. (Default = false)

• omitted_cell_summary_crayon: Crayon used to print the omitted cell summary.

• overwrite: If true, then the same number of lines in the printed table will be deleted from the output io. This can be used to update the table in the display continuously. (Default = false)

• row_number_alignment: Select the alignment of the row number column (see the section Alignment). (Default = :r)

• row_number_column_title: The title of the column that shows the row numbers. (Default = "Row")

• show_omitted_cell_summary: If true, then a summary will be printed after the table with the number of columns and rows that were omitted. (Default = true)

• show_row_number: If true, then a new column will be printed showing the row number. (Default = false)

• tf: Table format used to print the table (see TextFormat). (Default = tf_unicode)

• title_autowrap: If true, then the title text will be wrapped considering the title size. Otherwise, lines larger than the title size will be cropped. (Default = false)

• title_crayon: Crayon to print the title.

• title_same_width_as_table: If true, then the title width will match that of the table. Otherwise, the title size will be equal to the display width. (Default = false)

• vcrop_mode: This variable defines the vertical crop behavior. If it is :bottom, then the data, if required, will be cropped in the bottom. On the other hand, if it is :middle, then the data will be cropped in the middle if necessary. (Default = :bottom)

• vlines: This variable controls where the vertical lines will be drawn. It can be nothing, :all, :none or a vector of integers.

  • If it is nothing, which is the default, then the configuration will be obtained from the table format in the variable tf (see TextFormat).
  • If it is :all, then all vertical lines will be drawn.
  • If it is :none, then no vertical line will be drawn.
  • If it is a vector of integers, then the vertical lines will be drawn only after the columns in the vector. Notice that the top line will be drawn if 0 is in vlines. Furthermore, it is important to mention that the column number in this variable is related to the printed column. Thus, it is affected by filters, and by the options row_names and show_row_number. Finally, for convenience, the left and right vertical lines can be drawn by adding the symbols :begin and :end to this vector, respectively, and the line after the header can be drawn by adding the symbol :header.

  (Default = nothing)

The keywords header_crayon and subheader_crayon can be a Crayon or a Vector{Crayon}. In the first case, the Crayon will be applied to all the elements. In the second, each element can have its own crayon, but the length of the vector must be equal to the number of columns in the data.

Crayons

A Crayon is an object that handles a style for text printed on terminals. It is defined in the package Crayons.jl. There are many options available to customize the style, such as foreground color, background color, bold text, etc.

A Crayon can be created in two different ways:

julia> Crayon(foreground = :blue, background = :black, bold = :true)

julia> crayon"blue bg:black bold"

For more information, see the package documentation.

Text highlighters

A set of highlighters can be passed as a Tuple to the highlighters keyword. Each highlighter is an instance of the structure Highlighter that contains three fields:

• f: Function with the signature f(data,i,j) in which should return true if the element (i,j) in data must be highlighter, or false otherwise.
• fd: Function with the signature f(h,data,i,j) in which h is the highlighter. This function must return the Crayon to be applied to the cell that must be highlighted.
• crayon: The Crayon to be applied to the highlighted cell if the default fd is used.

The function f has the following signature:

f(data, i, j)

in which data is a reference to the data that is being printed, and i and j are the element coordinates that are being tested. If this function returns true, then the cell (i,j) will be highlighted.

If the function f returns true, then the function fd(h,data,i,j) will be called and must return a Crayon that will be applied to the cell.

A highlighter can be constructed using three helpers:

Highlighter(f::Function; kwargs...)

where it will construct a Crayon using the keywords in kwargs and apply it to the highlighted cell,

Highlighter(f::Function, crayon::Crayon)

where it will apply the crayon to the highlighted cell, and

Highlighter(f::Function, fd::Function)

where it will apply the Crayon returned by the function fd to the highlighted cell.

Pretty table HTML backend

This backend produces HTML tables. This backend can be used by selecting backend = Val(:html).

Keywords

• highlighters: An instance of HTMLHighlighter or a tuple with a list of HTML highlighters (see the section HTML highlighters).
• linebreaks: If true, then \n will be replaced by <br>. (Default = false)
• noheader: If true, then the header will not be printed. Notice that all keywords and parameters related to the header and sub-headers will be ignored. (Default = false)
• nosubheader: If true, then the sub-header will not be printed, i.e. the header will contain only one line. Notice that this option has no effect if noheader = true. (Default = false)
• standalone: If true, then a complete HTML page will be generated. Otherwise, only the content between the tags <table> and </table> will be printed (with the tags included). (Default = true)
• tf: An instance of the structure HTMLTableFormat that defines the general format of the HTML table.

HTML highlighters

A set of highlighters can be passed as a Tuple to the highlighters keyword. Each highlighter is an instance of the structure HTMLHighlighter. It contains the following two public fields:

• f: Function with the signature f(data,i,j) in which should return true if the element (i,j) in data must be highlighted, or false otherwise.
• fd: Function with the signature f(h,data,i,j) in which h is the highlighter. This function must return the HTMLDecoration to be applied to the cell that must be highlighted.

The function f has the following signature:

f(data, i, j)

in which data is a reference to the data that is being printed, and i and j are the element coordinates that are being tested. If this function returns true, then the highlight style will be applied to the (i,j) element. Otherwise, the default style will be used.

If the function f returns true, then the function fd(h,data,i,j) will be called and must return an element of type HTMLDecoration that contains the decoration to be applied to the cell.

A HTML highlighter can be constructed using two helpers:

HTMLHighlighter(f::Function, decoration::HTMLDecoration)

HTMLHighlighter(f::Function, fd::Function)

The first will apply a fixed decoration to the highlighted cell specified in decoration whereas the second let the user select the desired decoration by specifying the function fd.

Pretty table LaTeX backend

This backend produces LaTeX tables. This backend can be used by selecting backend = Val(:latex).

Keywords

• body_hlines: A vector of Int indicating row numbers in which an additional horizontal line should be drawn after the row. Notice that numbers lower than 1 and equal or higher than the number of printed rows will be neglected. This vector will be appended to the one in hlines, but the indices here are related to the printed rows of the body. Thus, if 1 is added to body_hlines, then a horizontal line will be drawn after the first data row. (Default = Int[])

• highlighters: An instance of LatexHighlighter or a tuple with a list of LaTeX highlighters (see the section LaTeX highlighters).

• hlines: This variable controls where the horizontal lines will be drawn. It can be nothing, :all, :none or a vector of integers.

  • If it is nothing, which is the default, then the configuration will be obtained from the table format in the variable tf (see LatexTableFormat).
  • If it is :all, then all horizontal lines will be drawn.
  • If it is :none, then no horizontal line will be drawn.
  • If it is a vector of integers, then the horizontal lines will be drawn only after the rows in the vector. Notice that the top line will be drawn if 0 is in hlines, and the header and subheaders are considered as only 1 row. Furthermore, it is important to mention that the row number in this variable is related to the printed rows. Thus, it is affected by filters, and by the option to suppress the header noheader. Finally, for convenience, the top and bottom lines can be drawn by adding the symbols :begin and :end to this vector, respectively, and the line after the header can be drawn by adding the symbol :header.
  Info

  The values of body_hlines will be appended to this vector. Thus, horizontal lines can be drawn even if hlines is :none.

  (Default = nothing)

• label: The label of the table. If empty, then no label will be added. (Default = "")

• longtable_footer: The string that will be drawn in the footer of the tables before a page break. This only works if table_type is :longtable. If it is nothing, then no footer will be used. (Default = nothing)

• noheader: If true, then the header will not be printed. Notice that all keywords and parameters related to the header and sub-headers will be ignored. (Default = false)

• nosubheader: If true, then the sub-header will not be printed, i.e. the header will contain only one line. Notice that this option has no effect if noheader = true. (Default = false)

• row_number_alignment: Select the alignment of the row number column (see the section Alignment). (Default = :r)

• table_type: Select which LaTeX environment will be used to print the table. Currently supported options are :tabular for tabular or :longtable for longtable. If it is nothing then the default option of the table format will be used. (Default = nothing)

• tf: An instance of the structure LatexTableFormat that defines the general format of the LaTeX table.

• vlines: This variable controls where the vertical lines will be drawn. It can be :all, :none or a vector of integers. In the first case (the default behavior), all vertical lines will be drawn. In the second case, no vertical line will be drawn. In the third case, the vertical lines will be drawn only after the columns in the vector. Notice that the left border will be drawn if 0 is in vlines. Furthermore, it is important to mention that the column number in this variable is related to the printed columns. Thus, it is affected by filters, and by the columns added using the variable show_row_number. Finally, for convenience, the left and right border can be drawn by adding the symbols :begin and :end to this vector, respectively. (Default = :none)

• wrap_table: This variable controls whether to wrap the table in a environment defined by the variable wrap_table_environment. Defaults to true. When false, the printed table begins with egin{tabular}. This option does not work with :longtable. If it is nothing then the default option of the table format will be used. (Default = nothing)

• wrap_table_environment: Environment that will be used to wrap the table if the option wrap_table is true. If it is nothing then the default option of the table format will be used. (Default = nothing)

LaTeX highlighters

A set of highlighters can be passed as a Tuple to the highlighters keyword. Each highlighter is an instance of the structure LatexHighlighter. It contains the following two fields:

• f: Function with the signature f(data,i,j) in which should return true if the element (i,j) in data must be highlighted, or false otherwise.
• fd: A function with the signature f(data,i,j,str)::String in which data is the matrix, (i,j) is the element position in the table, and str is the data converted to string. This function must return a string that will be placed in the cell.

The function f has the following signature:

f(data, i, j)

in which data is a reference to the data that is being printed, i and j are the element coordinates that are being tested. If this function returns true, then the highlight style will be applied to the (i,j) element. Otherwise, the default style will be used.

If the function f returns true, then the function fd(data,i,j,str) will be called and must return the LaTeX string that will be placed in the cell.

There are two helpers that can be used to create LaTeX highlighters:

LatexHighlighter(f::Function, envs::Union{String,Vector{String}})

LatexHighlighter(f::Function, fd::Function)

The first will apply recursively all the LaTeX environments in envs to the highlighted text whereas the second let the user select the desired decoration by specifying the function fd.

Thus, for example:

LatexHighlighter((data,i,j)->true, ["textbf", "small"])

will wrap all the cells in the table in the following environment:

\textbf{\small{<Cell text>}}

Formatters

The keyword formatters can be used to pass functions to format the values in the columns. It must be a tuple of functions in which each function has the following signature:

f(v, i, j)

where v is the value in the cell, i is the row number, and j is the column number. Thus, it must return the formatted value of the cell (i,j) that has the value v. Notice that the returned value will be converted to string after using the function sprint.

This keyword can also be a single function, meaning that only one formatter is available, or nothing, meaning that no formatter will be used.

For example, if we want to multiply all values in odd rows of the column 2 by π, then the formatter should look like:

formatters = (v,i,j) -> (j == 2 && isodd(i)) ? v*π : v

If multiple formatters are available, then they will be applied in the same order as they are located in the tuple. Thus, for the following formatters:

formatters = (f1, f2, f3)

each element v in the table (i-th row and j-th column) will be formatted by:

v = f1(v,i,j)
v = f2(v,i,j)
v = f3(v,i,j)

Thus, the user must be ensure that the type of v between the calls are compatible.

pretty_table_with_conf(conf::PrettyTablesConf, args...; kwargs...)

Call pretty_table using the default configuration in conf. The args... and kwargs... can be the same as those passed to pretty_tables. Notice that all the configurations in kwargs... will overwrite the ones in conf.

The object conf can be created by the function set_pt_conf in which the keyword parameters can be any one supported by the function pretty_table as shown in the following.

set_pt_conf!(conf; kwargs...)

Apply the configurations in kwargs to the object conf.

set_pt_conf(;kwargs...)

Create a new configuration object based on the arguments in kwargs.

@pt(expr...)

Pretty print tables in expr to stdout using the global configurations selected with the macro @ptconf.

Multiple tables can be printed by passing multiple expressions like:

@pt table1 table2 table3

The user can select the table header by passing the expression:

:header = [<Vector with the header>]

Notice that the header is valid only for the next printed table. Hence:

@pt :header = header1 table1 :header = header2 table2 table3

will print table1 using header1, table2 using header2, and table3 using the default header.

Examples

julia> @ptconf tf = simple

julia> @pt :header = ["Time","Velocity"] [1:1:10 ones(10)] :header = ["Time","Position"] [1:1:10 1:1:10]
======= ===========
  Time   Velocity
======= ===========
   1.0        1.0
   2.0        1.0
   3.0        1.0
   4.0        1.0
   5.0        1.0
   6.0        1.0
   7.0        1.0
   8.0        1.0
   9.0        1.0
  10.0        1.0
======= ===========
======= ===========
  Time   Position
======= ===========
     1          1
     2          2
     3          3
     4          4
     5          5
     6          6
     7          7
     8          8
     9          9
    10         10
======= ===========

julia> @pt ones(3,3) + I + [1 2 3; 4 5 6; 7 8 9]
========= ======== =========
  Col. 1   Col. 2   Col. 3
========= ======== =========
     3.0      3.0      4.0
     5.0      7.0      7.0
     8.0      9.0     11.0
========= ======== =========

Remarks

When more than one table is passed to this macro, then multiple calls to pretty_table will occur. Hence, the cropping algorithm will behave exactly the same as printing the tables separately.

@ptconf(expr...)

Add configurations in expr to be used with the macro @pt.

The expression format must be:

keyword1 = value1 keyword2 = value2 ...

in which the keywords can be any other possible keyword that can be used in the function pretty_table.

@ptconfclean()

Clean all global configurations to pretty print tables using the macro @pt.