pillar v1.4.6

0

Monthly downloads

0th

Percentile

Coloured Formatting for Columns

Provides 'pillar' and 'colonnade' generics designed for formatting columns of data using the full range of colours provided by modern terminals.

Readme

pillar

Lifecycle:
maturing R 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

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

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

# Or the the development version from GitHub:
# install.packages("devtools")
devtools::install_github("r-lib/pillar")

Usage

pillar is a developer-facing package that 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 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 using vctrs::s3_register().
    • If you don’t mind the dependency, you can also add it to Imports, and import the methods you override with a regular NAMESPACE import.

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

  • pillar.R for the actual implementation (old name colformat.R)
  • DESCRIPTION for the dependency
  • zzz.R for the dynamic method registration

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:

  • It has an attribute "width"
  • It can have an attribute "min_width", if missing, "width" is used
  • It must implement a method format(x, width, ...) that can be called with any value between min_width and width
    • This method must return an object that inherits from character and has attributes "align" (with supported values "left", "right", and "center") and "width"

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

  • style_neg() to format negative values
  • style_num() to format numbers
  • style_subtle() to de-emphasize

Inspirations

  • TextPlots for use of Braille characters

  • spark for use of block characters.

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.

Functions in pillar

Name Description
new_ornament Helper to define the contents of a pillar
colonnade Format multiple vectors in a tabular display
extra_cols Retrieve information about columns that didn't fit the available width
align Alignment helper
format_type_sum Format a type summary
deprecated Deprecated functions
expect_known_display Test helpers
new_pillar_shaft Constructor for column data
pillar-package pillar: Coloured Formatting for Columns
pillar Format a vector suitable for tabular display
type_sum Provide a succinct summary of an object
new_pillar_type Prepare a column type for formatting
new_pillar_title Prepare a column title for formatting
pillar_shaft Column data
style_num Styling helpers
dim_desc Format dimensions
get_extent Calculate display width
No Results!

Last month downloads

Details

License GPL-3
URL https://github.com/r-lib/pillar
BugReports https://github.com/r-lib/pillar/issues
Encoding UTF-8
LazyData true
RoxygenNote 7.1.1.9000
NeedsCompilation no
Packaged 2020-07-10 13:36:04 UTC; kirill
Repository CRAN
Date/Publication 2020-07-10 17:10:13 UTC

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/pillar)](http://www.rdocumentation.org/packages/pillar)