export_as_txt {formatters}

Export a table-like object to plain (ASCII) text with page breaks

Description

This function converts x to a MatrixPrintForm object via matrix_form(), paginates it via paginate_to_mpfs(), converts each page to ASCII text via toString(), and outputs the strings, separated by page_break, to file.

Usage

export_as_txt(
  x,
  file = NULL,
  page_type = NULL,
  landscape = FALSE,
  pg_width = page_dim(page_type)[if (landscape) 2 else 1],
  pg_height = page_dim(page_type)[if (landscape) 1 else 2],
  font_family = "Courier",
  font_size = 8,
  lineheight = 1L,
  margins = c(top = 0.5, bottom = 0.5, left = 0.75, right = 0.75),
  paginate = TRUE,
  cpp = NA_integer_,
  lpp = NA_integer_,
  ...,
  hsep = NULL,
  indent_size = 2,
  tf_wrap = paginate,
  max_width = NULL,
  colwidths = NULL,
  min_siblings = 2,
  nosplitin = character(),
  rep_cols = NULL,
  verbose = FALSE,
  page_break = "\\s\\n",
  page_num = default_page_number(),
  fontspec = font_spec(font_family, font_size, lineheight),
  col_gap = 3
)

Arguments

x

(ANY)
a table-like object to export. Must have an applicable matrix_form method.

file

(string or NULL)
if non-NULL, the path to write a text file to containing x rendered as ASCII text.

page_type

(string)
name of a page type. See page_types. Ignored when pg_width and pg_height are set directly.

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.

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.

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.

paginate

(flag)
whether pagination should be performed. Defaults to TRUE if page size is specified (including the default).

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.

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.

...

additional parameters passed to paginate_to_mpfs().

hsep

(string)
character to repeat to create header/body separator line. If NULL, the object value will be used. If " ", an empty separator will be printed. See default_hsep() for more information.

indent_size

(numeric(1))
indent size, in characters. Ignored when x is already a MatrixPrintForm object in favor of information there.

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.

colwidths

(numeric)
vector of column widths (in characters) for use in vertical pagination.

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.

rep_cols

(numeric(1))
number of columns (not including row labels) to be repeated on every page. Defaults to 0.

verbose

(flag)
whether additional informative messages about the search for pagination breaks should be shown. Defaults to FALSE.

page_break

(string)
page break symbol (defaults to "\\n\\s").

page_num

(string)
placeholder string for page numbers. See default_page_number for more information. Defaults to NULL.

fontspec

(font_spec)
a font_spec object specifying the font information to use for calculating string widths and heights, as returned by font_spec().

col_gap

(numeric(1))
The number of spaces to be placed between columns in the rendered table (and assumed for horizontal pagination).

Details

If x has a num_rep_cols method, the value returned by it will be used for rep_cols by default. Otherwise, 0 will be used.

If x has an applicable do_forced_paginate method, it will be invoked during the pagination process.

Value

If file is NULL, the full paginated and concatenated string value is returned, otherwise the output is written to file and no value (invisible NULL) is returned.

Examples

export_as_txt(basic_matrix_form(mtcars), pg_height = 5, pg_width = 4)