Provides a 'pillar' generic designed for formatting columns of data using the full range of colours provided by modern terminals.
pillar provides tools for styling columns of data, artfully using colour and unicode characters to guide the eye.
pillar is not designed for end-users but will eventually be incorporated in packages like tibble.
library(pillar)x <- 123456789 * (10 ^ c(-3, -5, NA, -8, -10))pillar(x)#> <dbl>#> 123457.#> 1235.#> NA#> 1.23#> 0.0123
If you render this in a console that supports colour, you'll see something that looks like this:
The primary user of this package is tibble, which in the current development version already lets pillar do all the formatting work. Packages that implement a data type to be used in a tibble column can add color with only a few changes:
pillar_shaft()method for your data type.
Suggestsand implement dynamic method registration
Imports, and import the methods you override with a regular
tidyverse/hms#43 shows the changes that were necessary to add colored output for the hms package:
pillar.Rfor the actual implementation (old name
DESCRIPTIONfor the dependency
zzz.Rfor the dynamic method registration
Some more detail is given below.
This method accepts a vector of arbitrary length and is expected to return an S3 object with the following properties:
"min_width", if missing,
format(x, width, ...)that can be called with any value between
characterand has attributes
"align"(with supported values
new_pillar_shaft() returns such an object, and also correctly formats
NA values. In many cases, the implementation of
pillar_shaft.your_class_name() will format the data as a character vector (using color for emphasis) and simply call
pillar_shaft.numeric() for a code that allows changing the display depending on the available width.
style_neg()to format negative values
style_num()to format numbers
If you avoid the strong dependency on pillar, you need a helper,
register_s3_method(), which you can borrow e.g. from hms. In
.onLoad(), call this helper as follows:
register_s3_method("pillar", "pillar_shaft", "your_class_name")
"your_class_name" with the name of the S3 class of your data type.
The earliest use of unicode characters to generate sparklines appears to be from 2009.
Exercising these ideas to their fullest requires a font with good support for block drawing characters. PragamataPro is one such font.
Unknown data types are formatted using
Multi-tier colonnades can always fill the last tier, even if the width isn't a proper multiple of
options(width = 80, tibble.width = 200) will print a wide tibble in three tiers, each 80 characters wide, with a total width of 240 characters.)
Fixed mixed formatting (showing some pillars with maximum, and some with minimum width). If a pillar's minimum width is smaller than
getOption("width"), it is shown nevertheless, abbreviated with dots if necessary.
Printing large multi-tier colonnades is much faster, the code that distributes pillars over tiers uses a much simpler and much faster algorithm (tidyverse/tibble#422).
Printing is now faster overall, because less work is done for formatting in "subtle" style (gray of a fixed level), and because
fansi::strip_sgr() is used instead of
Slightly faster printing of colonnades by reusing an intermediate result.
pillar() no longer adds backticks if
title is non-syntactic.
colonnade() supports data frames and matrices. When printing, each sub-column is shown individually, using a title that resembles the syntax used to access it. Also supports recursively nested data frames (with data frame or matrix columns).
Added fuzz tests for character colonnades of varying widths.
fansi::substr_ctl() in favor of
colonnade()now handles pillars named
new_pillar_type()to support consistent output in
format_type_sum()generic that allows overriding the formatting of the type summary in the capital (#73).
digits.secsoption is respected when computing the width for date-time values (#102).
TRUEto turn it on again (default:
numeric. Trailing zeros are not shown anymore if all displayed numbers are whole numbers (#62).
Durationfrom lubridate) are now formatted using
pillar_shaft()method is not implemented for that class (#88).
1e-310) are now printed corectly (tidyverse/tibble#377).
getOption("pillar.sigfig") >= 6(tidyverse/tibble#380).
style_subtle_num(), formatting depends on the
NAvalues are now shown in plain red, without changing the background color (#70).
pillar.sigfigto control the number of significant digits, for highlighting and truncation (#72),
pillar.subtleto specify if insignificant digits should be printed in gray (#72),
pillar.negto specify if negative digits should be printed in red,
pillar.boldto specify if column headers should be printed in bold (default:
pillar.min_title_charsto specify the minimum number of characters to display for each column name (default: 15 characters, #75).
digits.secsoption is set (#74).
pillar(x, title = NULL, width = NULL, ...) colonnade(x, has_row_id = TRUE, width = NULL, ...) squeeze(x, width = NULL, ...)
new_pillar_shaft_simple(formatted, ..., width = NULL, align = "left", min_width = NULL, na_indent = 0L) new_pillar_shaft(x, ..., width, min_width = width, subclass) new_ornament(x, width = NULL, align = NULL) get_extent(x) get_max_extent(x)
dim_desc(x) style_na(x) style_neg(x) style_num(x, negative, significant = rep_along(x, TRUE)) style_subtle(x)
expect_known_display(object, file, ..., width = 80L, crayon = TRUE)
pillar_shaft(x, ...) # AsIs, Date, POSIXt, character, default, list, logical, numeric type_sum(x) # AsIs, Date, POSIXct, data.frame, default, difftime, factor, ordered is_vector_s3(x) # Date, POSIXct, data.frame, default, difftime, factor, ordered obj_sum(x) # AsIs, POSIXlt, default, list extra_cols(x, ...) # squeezed_colonnade