ctl_new_pillar_list: Customize the appearance of compound pillars in your tibble...

In r-lib/pillar: Coloured Formatting for Columns

Customize the appearance of compound pillars in your tibble subclass

Description

Gain full control over the appearance of the pillars of your tibble subclass in its body. This method is intended for implementers of subclasses of the "tbl" class. Users will rarely need them, and we also expect the default implementation to be sufficient for the vast majority of cases.

Usage

ctl_new_pillar_list(
  controller,
  x,
  width,
  ...,
  title = NULL,
  first_pillar = NULL
)

Arguments

controller	The object of class "tbl" currently printed.
x	A vector, can also be a data frame, matrix, or array.
width	The available width, can be a vector for multiple tiers. If NULL, only the first pillar is instantiated.
...	These dots are for future extensions and must be empty.
title	The title, derived from the name of the column in the data.
first_pillar	Can be passed to this method if the first pillar for a compound pillar (or the pillar itself for a simple pillar) has been constructed already.

Details

ctl_new_pillar_list() is called to construct a list of pillars. If x is a regular (one-dimensional) vector, the list contains one pillar constructed by ctl_new_pillar(). This method also works for compound columns: columns that are data frames, matrices or arrays, with the following behavior:

• If width is NULL, the method always returns a list of length one containing one pillar object that represents the first sub-column in this compound column.

• Otherwise, the returned list contains one pillar object for all sub-columns that can be fit in the available horizontal space. These pillar objects are obtained by calling ctl_new_pillar_list() with width = NULL on each sub-column until the available width is exhausted.

This method is called to initiate the construction of all pillars in the tibble to be printed. To ensure that all packed columns that fit the available space are printed, ctl_new_pillar_list() may be called twice on the same input: once with width = NULL, and once with width corresponding to the then known available space and with first_pillar set to the pillar object constructed in the first call.

Examples

# Simple column
ctl_new_pillar_list(
  tibble::tibble(),
  palmerpenguins::penguins$weight[1:3],
  width = 10
)

# Packed data frame: unknown width
ctl_new_pillar_list(
  tibble::tibble(),
  palmerpenguins::penguins[1:3, ],
  width = NULL
)

# Packed data frame: known width
ctl_new_pillar_list(
  tibble::tibble(),
  palmerpenguins::penguins,
  width = 60
)

# Deeply packed data frame with known width:
# showing only the first sub-column even if the width is sufficient
ctl_new_pillar_list(
  tibble::tibble(),
  tibble::tibble(x = tibble::tibble(b = 1, c = 2), y = 3),
  width = 60
)

# Packed matrix: unknown width
ctl_new_pillar_list(tibble::tibble(), matrix(1:6, ncol = 2), width = NULL)

# Packed matrix: known width
ctl_new_pillar_list(tibble::tibble(), matrix(1:6, ncol = 2), width = 60)

# Packed array
ctl_new_pillar_list(tibble::tibble(), Titanic, width = 60)

r-lib/pillar documentation built on March 9, 2024, 10:14 a.m.