paginate_indices: Paginate a table-like object for rendering

In formatters: ASCII Formatting for Values and Tables

Paginate a table-like object for rendering

Description

These functions perform or diagnose bi-directional pagination on an object.

Usage

paginate_indices(
  obj,
  page_type = "letter",
  font_family = "Courier",
  font_size = 8,
  lineheight = 1,
  landscape = FALSE,
  pg_width = NULL,
  pg_height = NULL,
  margins = c(top = 0.5, bottom = 0.5, left = 0.75, right = 0.75),
  lpp = NA_integer_,
  cpp = NA_integer_,
  min_siblings = 2,
  nosplitin = list(rows = character(), cols = character()),
  colwidths = NULL,
  tf_wrap = FALSE,
  max_width = NULL,
  indent_size = 2,
  pg_size_spec = NULL,
  rep_cols = num_rep_cols(obj),
  col_gap = 3,
  fontspec = font_spec(font_family, font_size, lineheight),
  verbose = FALSE
)

paginate_to_mpfs(
  obj,
  page_type = "letter",
  font_family = "Courier",
  font_size = 8,
  lineheight = 1,
  landscape = FALSE,
  pg_width = NULL,
  pg_height = NULL,
  margins = c(top = 0.5, bottom = 0.5, left = 0.75, right = 0.75),
  lpp = NA_integer_,
  cpp = NA_integer_,
  min_siblings = 2,
  nosplitin = character(),
  colwidths = NULL,
  tf_wrap = FALSE,
  max_width = NULL,
  indent_size = 2,
  pg_size_spec = NULL,
  page_num = default_page_number(),
  rep_cols = NULL,
  col_gap = 3,
  fontspec = font_spec(font_family, font_size, lineheight),
  verbose = FALSE
)

diagnose_pagination(
  obj,
  page_type = "letter",
  font_family = "Courier",
  font_size = 8,
  lineheight = 1,
  landscape = FALSE,
  pg_width = NULL,
  pg_height = NULL,
  margins = c(top = 0.5, bottom = 0.5, left = 0.75, right = 0.75),
  lpp = NA_integer_,
  cpp = NA_integer_,
  min_siblings = 2,
  nosplitin = character(),
  colwidths = propose_column_widths(matrix_form(obj, TRUE), fontspec = fontspec),
  tf_wrap = FALSE,
  max_width = NULL,
  indent_size = 2,
  pg_size_spec = NULL,
  rep_cols = num_rep_cols(obj),
  col_gap = 3,
  verbose = FALSE,
  fontspec = font_spec(font_family, font_size, lineheight),
  ...
)

Arguments

obj	(ANY) object to be paginated. Must have a matrix_form() method.
page_type	(string) name of a page type. See page_types. Ignored when pg_width and pg_height are set directly.
font_family	(string) name of a font family. An error will be thrown if the family named is not monospaced. Defaults to "Courier".
font_size	(numeric(1)) font size. Defaults to 12.
lineheight	(numeric(1)) line height. Defaults to 1.
landscape	(flag) whether the dimensions of page_type should be inverted for landscape orientation. Defaults to FALSE, ignored when pg_width and pg_height are set directly.
pg_width	(numeric(1)) page width in inches.
pg_height	(numeric(1)) page height in inches.
margins	(numeric(4)) named numeric vector containing "bottom", "left", "top", and "right" margins in inches. Defaults to .5 inches for both vertical margins and .75 for both horizontal margins.
lpp	(numeric(1) or NULL) lines per page. If NA (the default), this is calculated automatically based on the specified page size). NULL indicates no vertical pagination should occur.
cpp	(numeric(1) or NULL) width (in characters) per page. If NA (the default), this is calculated automatically based on the specified page size). NULL indicates no horizontal pagination should occur.
min_siblings	(numeric) minimum sibling rows which must appear on either side of pagination row for a mid-subtable split to be valid. Defaults to 2 for tables. It is automatically turned off (set to 0) for listings.
nosplitin	(character) list of names of subtables where page breaks are not allowed, regardless of other considerations. Defaults to none.
colwidths	(numeric) vector of column widths (in characters) for use in vertical pagination.
tf_wrap	(flag) whether the text for title, subtitles, and footnotes should be wrapped.
max_width	(integer(1), string or NULL) width that title and footer (including footnotes) materials should be word-wrapped to. If NULL, it is set to the current print width of the session (getOption("width")). If set to "auto", the width of the table (plus any table inset) is used. Parameter is ignored if tf_wrap = FALSE.
indent_size	(numeric(1)) indent size, in characters. Ignored when x is already a MatrixPrintForm object in favor of information there.
pg_size_spec	(page_size_spec) . a pre-calculated page size specification. Typically this is not set by end users.
rep_cols	(numeric(1)) number of columns (not including row labels) to be repeated on every page. Defaults to 0.
col_gap	(numeric(1)) The number of spaces to be placed between columns in the rendered table (and assumed for horizontal pagination).
fontspec	(font_spec) a font_spec object specifying the font information to use for calculating string widths and heights, as returned by font_spec().
verbose	(flag) whether additional informative messages about the search for pagination breaks should be shown. Defaults to FALSE.
page_num	(string) placeholder string for page numbers. See default_page_number for more information. Defaults to NULL.
...	additional parameters passed to individual methods.

Details

paginate_indices renders obj into a MatrixPrintForm (MPF), then uses that representation to calculate the rows and columns of obj corresponding to each page of the pagination of obj, but simply returns these indices rather than paginating obj itself (see Details for an important caveat).

paginate_to_mpfs renders obj into its MPF intermediate representation, then paginates that MPF into component MPFs each corresponding to an individual page and returns those in a list.

diagnose_pagination attempts pagination via paginate_to_mpfs, then returns diagnostic information which explains why page breaks were positioned where they were, or alternatively why no valid pagination could be found.

All three of these functions generally support all classes which have a corresponding matrix_form() method which returns a valid MatrixPrintForm object (including MatrixPrintForm objects themselves).

paginate_indices is directly called by paginate_to_mpfs (and thus diagnose_pagination). For most classes, and most tables represented by supported classes, calling paginate_to_mpfs is equivalent to a manual ⁠paginate_indices -> subset obj into pages -> matrix_form⁠ workflow.

The exception to this equivalence is objects which support "forced pagination", or pagination logic which is built into the object itself rather than being a function of space on a page. Forced pagination generally involves the creation of, e.g., page-specific titles which apply to these forced paginations. paginate_to_mpfs and diagnose_pagination support forced pagination by automatically calling the do_forced_paginate() generic on the object and then paginating each object returned by that generic separately. The assumption here, then, is that page-specific titles and such are handled by the class' do_forced_paginate() method.

paginate_indices, on the other hand, does not support forced pagination, because it returns only a set of indices for row and column subsetting for each page, and thus cannot retain any changes, e.g., to titles, done within do_forced_paginate(). paginate_indices does call do_forced_paginate(), but instead of continuing it throws an error in the case that the result is larger than a single "page".

diagnose_pagination attempts pagination and then, regardless of success or failure, returns diagnostic information about pagination attempts (if any) after each row and column.

The diagnostics data reflects the final time the pagination algorithm evaluated a page break at the specified location, regardless of how many times the position was assessed in total.

To get information about intermediate attempts, perform pagination with verbose = TRUE and inspect the messages in order.

Value

• paginate_indices returns a list with two elements of the same length: pag_row_indices and pag_col_indices.

• paginate_to_mpfs returns a list of MatrixPrintForm objects representing each individual page after pagination (including forced pagination if necessary).

• diagnose_pagination returns a list containing:

  lpp_diagnostics

  Diagnostic information regarding lines per page.

  row_diagnostics

  Basic information about rows, whether pagination was attempted after each row, and the final result of such an attempt, if made.

  cpp_diagnostics

  Diagnostic information regarding columns per page.

  col_diagnostics

  Very basic information about leaf columns, whether pagination was attempted after each leaf column, ad the final result of such attempts, if made.

Note

For diagnose_pagination, the column labels are not displayed in the col_diagnostics element due to certain internal implementation details; rather the diagnostics are reported in terms of absolute (leaf) column position. This is a known limitation, and may eventually be changed, but the information remains useful as it is currently reported.

diagnose_pagination is intended for interactive debugging use and should not be programmed against, as the exact content and form of the verbose messages it captures and returns is subject to change.

Because diagnose_pagination relies on capture.output(type = "message"), it cannot be used within the testthat (and likely other) testing frameworks, and likely cannot be used within knitr/rmarkdown contexts either, as this clashes with those systems' capture of messages.

Examples

mpf <- basic_matrix_form(mtcars)

paginate_indices(mpf, pg_width = 5, pg_height = 3)

paginate_to_mpfs(mpf, pg_width = 5, pg_height = 3)

diagnose_pagination(mpf, pg_width = 5, pg_height = 3)
clws <- propose_column_widths(mpf)
clws[1] <- floor(clws[1] / 3)
dgnost <- diagnose_pagination(mpf, pg_width = 5, pg_height = 3, colwidths = clws)
try(diagnose_pagination(mpf, pg_width = 1)) # fails

formatters documentation built on Sept. 13, 2024, 1:10 a.m.