pillar v1.1.0

0

Monthly downloads

0th

Percentile

Coloured Formatting for Columns

Provides a 'pillar' generic designed for formatting columns of data using the full range of colours provided by modern terminals.

Readme

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(1, -3, -5, NA, -8, -10))
pillar(x)
#>           <dbl>
#> 1234567890     
#>     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
    • 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

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

  • 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
colonnade Format multiple vectors in a tabular display
dim_desc Format dimensions
expect_known_display Test helpers
extra_cols Retrieve information about columns that didn't fit the available width
get_extent Calculate display width
new_ornament Helper to define the contents of a pillar
pillar Format a vector suitable for tabular display
pillar_shaft Column data
style_num Styling helpers
type_sum Provide a succinct summary of an object
new_pillar_shaft Constructor for column data
pillar-package pillar: Coloured Formatting for Columns
No Results!

Last month downloads

Details

License GPL-3
Encoding UTF-8
LazyData true
URL https://github.com/r-lib/pillar
BugReports https://github.com/r-lib/pillar/issues
RoxygenNote 6.0.1
Collate 'capital.R' 'compat-purrr.R' 'dim.R' 'extent.R' 'multi.R' 'ornament.R' 'pillar-package.R' 'pillar.R' 'rowid-capital.R' 'rowid-data.R' 'rowid-title.R' 'rowid-type.R' 'scientific.R' 'shaft.R' 'shaft-simple.R' 'sigfig.R' 'spark-bar.R' 'spark-line.R' 'strrep.R' 'styles.R' 'testthat.R' 'tick.R' 'title.R' 'type-sum.R' 'type.R' 'utils.R' 'width.R' 'zzz.R'
NeedsCompilation no
Packaged 2018-01-14 21:11:40 UTC; muelleki
Repository CRAN
Date/Publication 2018-01-14 22:42:38 UTC

Include our badge in your README

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