LaTeXTabulars

LaTeXTabulars.LaTeXTabulars — Module

LaTeXTabulars.jl

Write tabular data from Julia in LaTeX format.

This is a very thin wrapper, basically for avoiding some loops and repeatedly used strings. It assumes that you know how the LaTeX tabular environment works, and you have formatted the cells to strings if you want anything fancy like rounding or alignment on the decimal dot.

The package is documented with a manual and docstrings.

Writing tables

The main entry point of the package is latex_tabular, which takes a destination (a filename, or String), a table specification (eg Tabular and an iterable, which is rendered elementwise using the following rules:

special objects like Rule emit the corresponding $\LaTeX$ code,
vectors and iterables emit a row of cells (not checked for length),
matrices are treated as rows of vectors,
Tuples are “splat” into place, which is useful for writing functions that format tables.

Note

Some examples in this manual, eg the one below, use the booktabs LaTeX package. If you are including them in a $\LaTeX$ document, make sure you add \usepackage{booktabs}.

latex_tabular(String, Tabular("lr"),
              [Rule(:top),
              ["critter", "count"],
              Rule(:mid),
               ["cats", 5],
               ["dogs", 7],
               Rule(:bottom)])

\begin{tabular}{lr}
\toprule
critter & count \\
\midrule
cats & $5$ \\
dogs & $7$ \\
\bottomrule
\end{tabular}

which renders as

Example block output

The simplest table specification is Tabular.

LaTeXTabulars.Tabular — Type

Tabular(cols)

For the LaTeX environment \begin{tabular}{cols} ... \end{tabular}.

cols should follow the column specification syntax of tabular.

Example

julia> using LaTeXTabulars

julia> Tabular("l" * "r"^5)
Tabular("lrrrrr")

Long tables are also supported.

LaTeXTabulars.LongTable — Type

LongTable(cols, header)

The longtable $\LaTeX$ environment. cols is a column specification, header is an iterable of cells (cf latex_cell that is repeated at the top of each page. formatter is applied to all cells.

Other table types would be simple to add, see adding extensions.

LaTeXTabulars.latex_tabular — Function

latex_tabular(io, t, lines; formatter)

Print lines to io as a LaTeX using the given environment.

Each line in lines can be

a rule-like object, eg Rule or CMidRule,
an iterable (eg AbstractVector) of cells,
a Tuple, which is treated as multiple lines (“splat” in place), which is useful for functions that generate lines with associated rules, or multiple CMidRules,
a matrix, each row of which is treated as a line.

Constructs which contain cells are printed by latex_cell, using the formatter, which leaves strings and LaTeX cells as is.

It is recommended that formatting parts of the table is done directly on the arguments, using a suitable formatter. See the manual for examples.

See latex_cell for the kinds of cell supported (particularly MultiColumn, but for full formatting control, use an String or LaTeXString for cells.

latex_tabular(, t, lines; formatter)

LaTeX output as a string. See other method for the other arguments.

latex_tabular(filename, t, lines; formatter)

Write a tabular-like LaTeX environment to filename, which is overwritten if it already exists.

Cells

Tables contain formatting (eg rules) and cells.

Cells can be

strings (which are escaped when written into LaTeX, so eg % is replaced by \%),
LaTeX wrappers like LaTeXEscapes.LaTeX and LaTeXStrings.LaTeXString,
and arbitrary Julia objects, which are converted with string, then escaped.

These rules apply to all cells, including MultiColumn and other special wrappers.

Inserting LaTeX code

LaTeX code can be inserted into tables using the LaTeXEscapes.jl and LaTeXStrings.jl packages, which use the lx"..."[m] and L"..." read string macros, respectively. The difference between the two packages is that lx"..." does not create values which are subtypes of string, and does not wrap in math mode inless you add the m flag. Naturally, the explicit wrapper types (eg LaTeXEscapes.LaTeX) can be used, too.

using LaTeXEscapes, LaTeXStrings
latex_tabular(String, Tabular("ll"),
               [[lx"\alpha"m, L"\beta"],
                [LaTeX(raw"$\gamma$"), "100%"]])

\begin{tabular}{ll}
$\alpha$ & $\beta$ \\
$\gamma$ & 100\% \\
\end{tabular}

which renders as

Special constructs

LaTeXTabulars.Rule — Type

Rule()
Rule(kind)

Horizontal rule. The kind of the rule is specified by a symbol, which will generally be printed as \KINDrule for rules in booktabs, eg Rule(:top) prints \toprule. To obtain a \hline, use Rule{:h}.

LaTeXTabulars.CMidRule — Type

CMidRule([wd], [trim], left, right)

Will be printed as \cmidrule[wd](trim)[left-right]. When wd or trim is nothing, it is omitted. Use with the booktabs LaTeX package.

LaTeXTabulars.LineSpace — Type

LineSpace([wd])

Prints \addlinespace[wd]. When wd is nothing, it is omitted. Use with the booktabs LaTeX package.

LaTeXTabulars.MultiColumn — Type

MultiColumn(n, pos, cell)

For \multicolumn{n}{pos}{cell}. Use the symbols :l, :c, :r for pos.

LaTeXTabulars.MultiRow — Type

MultiRow(n::Int, vpos::Symbol, cell::Any, width::String)
MultiRow(n, vpos, cell; width="*")

For \multirow[vpos]{n}{width}{cell}. Use the symbols :t, :c, :b for vpos.

Formatting

For the purposes of this package, formatting is the conversion of Julia values to strings or LaTeX code.

A formatter is a callable that converts its arguments to the above, or leaves it alone. This allows the user to chain formatters.

The user can either format the arguments to latex_tabular directly, which allows more flexibility, or provide a formatter via the formatter keyword, which defaults to DEFAULT_FORMATTER, which is initialized with SimpleCellFormatter.

latex_tabular(String, Tabular("ll"),
               [[Inf, -Inf],
                [NaN, -0.0],
                [missing, nothing]])

\begin{tabular}{ll}
$\infty$ & $-\infty$ \\
NaN & $-0.0$ \\
--- & --- \\
\end{tabular}

which renders as

LaTeXTabulars.DEFAULT_FORMATTER — Constant

The default formatter for latex_table. Its initial value is SimpleCellFormatter.

LaTeXTabulars.SimpleCellFormatter — Type

SimpleCellFormatter(; inf, minus_inf, NaN, nothing, missing)

A simple formatter that replaces some commonly used values used in displaying data.

Each field below should contain a string or a LaTeX code (otherwise, it is emitted as an escaped string).

Adding extensions

You can extend the functionality of this package in various ways:

add formatters (see eg SimpleCellFormatter),
add rule-like objects, for which you have to define a LaTeXTabulars.latex_line method,
add a new table type, for which it is recommended that you define LaTeXTabulars.latex_env_begin and LaTeXTabulars.latex_env_end. See the LongTable methods for an example.

Note

It is very unlikely that you have to add methods for LaTeXTabulars.latex_cell or LaTeXTabulars.latex_tabular.

LaTeXTabulars.latex_cell — Function

latex_cell(io, x, formatter)

Write a the contents of cell to io as LaTeX.

formatter is callable that is used to format cells that are not already ::AbstractString or ::LaTeX. If either of these are returned by the formatter, they are written into the LaTeX output, otherwise they are formatted as strings (and escaped asnecessary when written into LaTeX).

Note

If you want to make simple formatting changes, it is best to write your own formatter.

LaTeXTabulars.latex_line — Function

latex_line(io, _, _)

Emit an object that takes up a whole line in a table. Mostly used for rules.

LaTeXTabulars.latex_env_begin — Function

latex_env_begin(io, t, formatter)

Write the beginning of the environment t, using formatter.

LaTeXTabulars.latex_env_end — Function

latex_env_end(io, t, formatter)

Write the end of the environment t, using formatter.

Note

Rule types in booktabs are supported. Vertical rules of any kind are not explicitly supported and it would be difficult to convince me to add them. The documentation of booktabs should explain why. That said, if you insist, you can use a cell like \vline text.