pillar

Travis-CI Build Status Coverage status CRAN status

pillar provides tools for styling columns of data, artfully using colour and unicode characters to guide the eye.

Installation

# install.packages("devtools")
devtools::install_github("r-lib/pillar")

Usage

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:

Extending

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:

  1. Implement the pillar_shaft() method for your data type.
  2. Add pillar to Suggests and implement dynamic method registration

tidyverse/hms#43 shows the changes that were necessary to add colored output for the hms package:

Some more detail is given below.

Implementing pillar_shaft.your_class_name()

This method accepts a vector of arbitrary length and is expected to return an S3 object with the following properties:

The function 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 new_pillar_shaft(). See pillar_shaft.numeric() for a code that allows changing the display depending on the available width.

Useful helpers

Dynamic method registration

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")

Replace "your_class_name" with the name of the S3 class of your data type.

Inspirations

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.