tbl_format_setup: Set up formatting

In hadley/pillar: Coloured Formatting for Columns

Set up formatting

Description

tbl_format_setup() is called by format.tbl(). This method collects information that is common to the header, body, and footer parts of a tibble. Examples:

• the dimensions sometimes are reported both in the header and (implicitly) in the footer of a tibble;

• the columns shown in the body decide which columns are shown in the footer.

This information is computed in tbl_format_setup(). The result is passed on to the tbl_format_header(), tbl_format_body(), and tbl_format_footer() methods. If you need to customize parts of the printed output independently, override these methods instead.

By checking the setup argument, you can return an object that is suitable for a call to tbl_format_header() if setup is NULL. In this case, the method is called a second time with the return value of the first call as setup.

Usage

tbl_format_setup(
  x,
  width = NULL,
  ...,
  setup = list(tbl_sum = tbl_sum(x)),
  n = NULL,
  max_extra_cols = NULL,
  max_footer_lines = NULL,
  focus = NULL
)

## S3 method for class 'tbl'
tbl_format_setup(
  x,
  width,
  ...,
  setup,
  n,
  max_extra_cols,
  max_footer_lines,
  focus
)

Arguments

x	An object.
width	Actual width for printing, a numeric greater than zero. This argument is mandatory for all implementations of this method.
...	Extra arguments to print.tbl() or format.tbl().
setup	This generic is first called with setup = NULL . If the method evaluates this argument, the return value will only be used in a call to tbl_format_header(), and after that, a second call to this generic will be made with the return value of the first call as setup which then will be used in calls to tbl_format_body() and tbl_format_footer(). This allows displaying the header before starting the computation required for the body and footer.
n	Actual number of rows to print. No options should be considered by implementations of this method.
max_extra_cols	Number of columns to print abbreviated information for, if the width is too small for the entire tibble. No options should be considered by implementations of this method.
max_footer_lines	Maximum number of lines for the footer. No options should be considered by implementations of this method.
focus	Names of columns to show preferentially if space is tight.

Details

Extend this method to prepare information that is used in several parts of the printed output of a tibble-like object, or to collect additional arguments passed via ... to print.tbl() or format.tbl().

We expect that tbl_format_setup() is extended only rarely, and overridden only in exceptional circumstances, if at all. If you override this method, you must also implement tbl_format_header(), tbl_format_body(), and tbl_format_footer() for your class.

Implementing a method allows to override printing and formatting of the entire object without overriding the print() and format() methods directly. This allows to keep the logic of the width and n arguments.

The default method for the "tbl" class collects information for standard printing for tibbles. See new_tbl_format_setup() for details on the returned object.

Value

An object that can be passed as setup argument to tbl_format_header(), tbl_format_body(), and tbl_format_footer().

Examples

tbl_format_setup(palmerpenguins::penguins)

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