Library

struct HTMLDecoration

Structure that defines parameters to decorate a table cell.

struct 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.

struct 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.

struct Highlighter

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

Fileds

• 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.
• crayon: Crayon with the style of a highlighted element.

function Highlighter(f; kwargs...)

Construct a Highlighter with activation function f and pass all the keyword arguments kwargs to Crayon.

struct 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.
• row: Character in a horizontal line.
• top_line: If true, then the top table line will be drawn.
• header_line: If true, then the line between the header and the data will be drawn.
• bottom_line: If true, then the bottom table line will be drawn.

Pre-defined formats

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

function 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.

function 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.

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

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

function 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).

function 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.

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

Highlight the entire column i with the crayon crayon.

function 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.

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

Highlight the entire column i with the decoration decoration.

function 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.

function 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.

function 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.

function 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.

function 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.

function hl_lt(n::Number)

Highlight all elements that < n.

Remarks

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

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

Highlight the entire row i with the crayon crayon.

function 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.

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

Highlight the entire row i with the decoration decoration.

function 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.

function 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.

function 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.

function pretty_table([io::IO,] data::AbstractVecOrMat{T1}, header::AbstractVecOrMat{T2};  kwargs...) where {T1,T2}

Print to io the vector or matrix data with header header. If io is omitted, then it defaults to stdout. If header is empty, then it will be automatically filled with "Col. i" for the i-th column.

The header can be a Vector or a Matrix. If it is a Matrix, then each row will be a header line. The first line is called header and the others are called sub-headers .

function pretty_table([io::IO,] data::AbstractVecOrMat{T}; ...) where T

Print to io the vector or matrix data. If io is omitted, then it defaults to stdout. The header will be automatically filled with "Col. i" for the i-th column.

function pretty_table([io::IO,] dict::Dict{K,V}; sortkeys = true, ...) where {K,V}

Print to io the dictionary dict in a matrix form (one column for the keys and other for the values). If io is omitted, then it defaults to stdout.

In this case, the 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.

function pretty_table([io::IO,] table; ...)

Print to io the table table. In this case, table must comply with the API of Tables.jl. If io is omitted, then it defaults to stdout.

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).
• filters_row: Filters for the rows (see the section Filters).
• filters_col: Filters for the columns (see the section Filters).

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.
• subheaders_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.
• 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).
• cell_alignment: A dictionary of type (i,j) => a that overrides that alignment of the cell (i,j) to a regardless of the columns alignment selected. a must be a symbol like specified in the section Alignment.
• 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 screen size (see screen_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.
• formatter: See the section Formatter.
• highlighters: An instance of Highlighter or a tuple with a list of text highlighters (see the section Text highlighters).
• 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 rows will be neglected.
• hlines_format: A tuple of 4 characters specifying the format of the horizontal lines. 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)
• linebreaks: If true, then \n will break the line inside the cells. (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)
• same_column_size: If true, then all the columns will have the same size. (Default = false)
• screen_size: A tuple of two integers that defines the screen 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. If it is nothing, then the size will be obtained automatically. Notice that if a dimension is not positive, then it will be treated as unlimited. (Default = nothing)
• 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 = unicode)

The keywords header_crayon and subheaders_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 highlighter keyword. Each highlighter is an instance of the structure Highlighter that contains 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.
• crayon: Crayon with the style of a highlighted element.

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.

Notice that if multiple highlighters are valid for the element (i,j), then the applied style will be equal to the first match considering the order in the Tuple highlighters.

If only a single highlighter is wanted, then it can be passed directly to the keyword highlighter without being inside a Tuple.

Pretty table HTML backend

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

Keywords

• cell_alignment: A dictionary of type (i,j) => a that overrides that alignment of the cell (i,j) to a regardless of the columns alignment selected. a must be a symbol like specified in the section Alignment.
• formatter: See the section Formatter.
• 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)
• show_row_number: If true, then a new column will be printed showing the row number. (Default = false)
• 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 highlighter keyword. Each highlighter is an instance of a structure that is a subtype of AbstractHTMLHighlighter. It also must also contain at least the following two fields to comply with the API:

• 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.

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.

Notice that if multiple highlighters are valid for the element (i,j), then the applied style will be equal to the first match considering the order in the Tuple highlighters.

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.

If only a single highlighter is wanted, then it can be passed directly to the keyword highlighter without being inside a Tuple.

Formatter

The keyword formatter can be used to pass functions to format the values in the columns. It must be a Dict{Number,Function}(). The key indicates the column number in which its elements will be converted by the function in the value of the dictionary. The function must have the following signature:

f(value, i)

in which value is the data and i is the row number. It must return the formatted value.

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

Dict(2 => (v,i)->isodd(i) ? v*π : v)

If the key 0 is present, then the corresponding function will be applied to all columns that does not have a specific key.

macro 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.

macro 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.

macro @ptconfclean()

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

abstract type AbstractHTMLHighlighter

All HTLM highlighters must be a subtype of AbstractHTMLHighlighter. They API dictates that they must implement two functions:

• 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.

struct PrintInfo{Td,Th}

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

mutable struct Screen

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

Fields

• size: Screen size.
• row: Current row.
• col: Current column.
• has_color: Indicates if the screen has color support.

function _draw_continuation_row(screen, io, tf, text_crayon, border_crayon, num_printed_cols, cols_width, show_row_number, row_number_width)

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

function _draw_line!(screen, io, left, intersection, right, row, border_crayon, num_cols, cols_width, show_row_number, row_number_width)

Draw a vertical line in io using the information in screen.

function _eol(screen)

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

function _nl!(screen, io)

Add a new line into io using the screen information in screen.

function _p!(screen, io, crayon, str, final_line_print = false)

Print str into io using the Crayon crayon with the screen information in screen. 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.

function _str_aligned(data::AbstractString, alignment::Symbol, field_size::Integer)

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.

function _str_escaped(str::AbstractString)

Return the escaped string representation of str.

function _str_line_breaks(str::AbstractString, autowrap::Bool = false, width::Int = 0)

Split the string str into substring, each one meaning one new line. If autowrap is true, then the text will be wrapped so that it fits the column with the width width.