index.md

In hadley/pillar: Coloured Formatting for Columns

pillar

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

Installation

# pillar is installed if you install the tidyverse package:
install.packages("tidyverse")

# Alternatively, install just pillar:
install.packages("pillar")

Usage

pillar is a developer-facing package that is not designed for end-users. It powers the print() and format() methods for tibbles. It also and defines generics and helpers that are useful for package authors who create custom vector classes (see https://github.com/krlmlr/awesome-vctrs#readme for examples) or custom table classes (like dbplyr or sf).

library(pillar)

x <- 123456789 * (10^c(-3, -5, NA, -8, -10))
pillar(x)
#> [1m<pillar>[22m
#>       [3m[38;5;246m<dbl>[39m[23m
#> [4m1[24m[4m2[24m[4m3[24m457.    
#>   [4m1[24m235.    
#>     [31mNA[39m     
#>      1.23  
#>      0.012[4m3[24m

tbl_format_setup(tibble::tibble(x))
#> [1m<pillar_tbl_format_setup>[22m
#> [1m<tbl_format_header(setup)>[22m
#> [38;5;246m# A tibble: 5 × 1[39m
#> [1m<tbl_format_body(setup)>[22m
#>             [1mx[22m
#>         [3m[38;5;246m<dbl>[39m[23m
#> [38;5;250m1[39m [4m1[24m[4m2[24m[4m3[24m457.    
#> [38;5;250m2[39m   [4m1[24m235.    
#> [38;5;250m3[39m     [31mNA[39m     
#> [38;5;250m4[39m      1.23  
#> [38;5;250m5[39m      0.012[4m3[24m
#> [1m<tbl_format_footer(setup)>[22m

Custom vector classes

The primary user of this package is tibble, which lets pillar do all the formatting work. Packages that implement a data type to be used in a tibble column can customize the display by implementing a pillar_shaft() method.

library(pillar)

percent <- vctrs::new_vctr(9:11 * 0.01, class = "percent")

pillar_shaft.percent <- function(x, ...) {
  fmt <- format(vctrs::vec_data(x) * 100)
  new_pillar_shaft_simple(paste0(fmt, " ", style_subtle("%")), align = "right")
}

pillar(percent)
#> [1m<pillar>[22m
#> [3m[38;5;246m<percent>[39m[23m
#>       9 [38;5;246m%[39m
#>      10 [38;5;246m%[39m
#>      11 [38;5;246m%[39m

See vignette("pillar", package = "vctrs") for details.

Custom table classes

pillar provides various extension points for customizing how a tibble-like class is printed.

tbl <- vctrs::new_data_frame(list(a = 1:3), class = c("my_tbl", "tbl"))

tbl_sum.my_tbl <- function(x, ...) {
  c("Hello" = "world!")
}

tbl
#> [38;5;246m# Hello: world![39m
#>       [1ma[22m
#>   [3m[38;5;246m<int>[39m[23m
#> [38;5;250m1[39m     1
#> [38;5;250m2[39m     2
#> [38;5;250m3[39m     3

See vignette("extending", package = "pillar") for a walkthrough of the options.

hadley/pillar documentation built on Dec. 19, 2024, 6:22 a.m.