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

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

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 = default_hsep(),
  indent_size = 2,
  tf_wrap = paginate,
  max_width = NULL,
  colwidths = NULL,
  min_siblings = 2,
  nosplitin = character(),
  rep_cols = num_rep_cols(x),
  verbose = FALSE,
  page_break = "\\s\\n"
)

Arguments

x: ANY. The table-like object to export. Must have an applicable matrix_form method.
file: character(1) or NULL. If non-NULL, the path to write a text file to containing the x rendered as ASCII text,
page_type: character(1). Name of a page type. See page_types. Ignored when pg_width and pg_height are set directly.
landscape: logical(1). Should the dimensions of page_type be inverted for landscape? 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: character(1). 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: logical(1). 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.
...: Passed to individual methods.
hsep: character(1). Characters to repeat to create header/body separator line.
indent_size: numeric(1). Indent size in characters. Ignored when x is already a MatrixPrintForm object in favor of information there.
tf_wrap: logical(1). Should the texts for title, subtitle, and footnotes be wrapped?
max_width: integer(1), character(1) 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. Ignored completely if tf_wrap is FALSE.
colwidths: numeric vector. Column widths (in characters) for use with 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.
nosplitin: character. List of names of sub-tables 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: logical(1). Should additional informative messages about the search for pagination breaks be shown. Defaults to FALSE.
page_break: character(1). Page break symbol (defaults to outputting "\n\s").

Value

if file is NULL, the total paginated and then concatenated string value, otherwise the file that was written.

Details

if x has an num_rep_cols method, the value returned by it will be used for rep_cols by default, if not, 0 will be used.

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

Examples

export_as_txt(basic_matrix_form(mtcars), pg_height = 5, pg_width = 4)
#> [1] "                      mpg    cyl\n————————————————————————————————\nMazda RX4             21     6  \nMazda RX4 Wag         21     6  \nDatsun 710            22.8   4  \nHornet 4 Drive        21.4   6  \nHornet Sportabout     18.7   8  \nValiant               18.1   6  \nDuster 360            14.3   8  \nMerc 240D             24.4   4  \nMerc 230              22.8   4  \nMerc 280              19.2   6  \nMerc 280C             17.8   6  \nMerc 450SE            16.4   8  \nMerc 450SL            17.3   8  \nMerc 450SLC           15.2   8  \nCadillac Fleetwood    10.4   8  \nLincoln Continental   10.4   8  \nChrysler Imperial     14.7   8  \nFiat 128              32.4   4  \nHonda Civic           30.4   4  \nToyota Corolla        33.9   4  \nToyota Corona         21.5   4  \nDodge Challenger      15.5   8  \nAMC Javelin           15.2   8  \nCamaro Z28            13.3   8  \nPontiac Firebird      19.2   8  \nFiat X1-9             27.3   4  \nPorsche 914-2         26     4  \nLotus Europa          30.4   4  \nFord Pantera L        15.8   8  \nFerrari Dino          19.7   6  \nMaserati Bora         15     8  \nVolvo 142E            21.4   4  \n\\s\\n                      disp    hp \n—————————————————————————————————\nMazda RX4             160     110\nMazda RX4 Wag         160     110\nDatsun 710            108     93 \nHornet 4 Drive        258     110\nHornet Sportabout     360     175\nValiant               225     105\nDuster 360            360     245\nMerc 240D             146.7   62 \nMerc 230              140.8   95 \nMerc 280              167.6   123\nMerc 280C             167.6   123\nMerc 450SE            275.8   180\nMerc 450SL            275.8   180\nMerc 450SLC           275.8   180\nCadillac Fleetwood    472     205\nLincoln Continental   460     215\nChrysler Imperial     440     230\nFiat 128              78.7    66 \nHonda Civic           75.7    52 \nToyota Corolla        71.1    65 \nToyota Corona         120.1   97 \nDodge Challenger      318     150\nAMC Javelin           304     150\nCamaro Z28            350     245\nPontiac Firebird      400     175\nFiat X1-9             79      66 \nPorsche 914-2         120.3   91 \nLotus Europa          95.1    113\nFord Pantera L        351     264\nFerrari Dino          145     175\nMaserati Bora         301     335\nVolvo 142E            121     109\n\\s\\n                      drat    wt  \n——————————————————————————————————\nMazda RX4             3.9    2.62 \nMazda RX4 Wag         3.9    2.875\nDatsun 710            3.85   2.32 \nHornet 4 Drive        3.08   3.215\nHornet Sportabout     3.15   3.44 \nValiant               2.76   3.46 \nDuster 360            3.21   3.57 \nMerc 240D             3.69   3.19 \nMerc 230              3.92   3.15 \nMerc 280              3.92   3.44 \nMerc 280C             3.92   3.44 \nMerc 450SE            3.07   4.07 \nMerc 450SL            3.07   3.73 \nMerc 450SLC           3.07   3.78 \nCadillac Fleetwood    2.93   5.25 \nLincoln Continental   3      5.424\nChrysler Imperial     3.23   5.345\nFiat 128              4.08   2.2  \nHonda Civic           4.93   1.615\nToyota Corolla        4.22   1.835\nToyota Corona         3.7    2.465\nDodge Challenger      2.76   3.52 \nAMC Javelin           3.15   3.435\nCamaro Z28            3.73   3.84 \nPontiac Firebird      3.08   3.845\nFiat X1-9             4.08   1.935\nPorsche 914-2         4.43   2.14 \nLotus Europa          3.77   1.513\nFord Pantera L        4.22   3.17 \nFerrari Dino          3.62   2.77 \nMaserati Bora         3.54   3.57 \nVolvo 142E            4.11   2.78 \n\\s\\n                      qsec    vs   am\n—————————————————————————————————————\nMazda RX4             16.46   0    1 \nMazda RX4 Wag         17.02   0    1 \nDatsun 710            18.61   1    1 \nHornet 4 Drive        19.44   1    0 \nHornet Sportabout     17.02   0    0 \nValiant               20.22   1    0 \nDuster 360            15.84   0    0 \nMerc 240D             20      1    0 \nMerc 230              22.9    1    0 \nMerc 280              18.3    1    0 \nMerc 280C             18.9    1    0 \nMerc 450SE            17.4    0    0 \nMerc 450SL            17.6    0    0 \nMerc 450SLC           18      0    0 \nCadillac Fleetwood    17.98   0    0 \nLincoln Continental   17.82   0    0 \nChrysler Imperial     17.42   0    0 \nFiat 128              19.47   1    1 \nHonda Civic           18.52   1    1 \nToyota Corolla        19.9    1    1 \nToyota Corona         20.01   1    0 \nDodge Challenger      16.87   0    0 \nAMC Javelin           17.3    0    0 \nCamaro Z28            15.41   0    0 \nPontiac Firebird      17.05   0    0 \nFiat X1-9             18.9    1    1 \nPorsche 914-2         16.7    0    1 \nLotus Europa          16.9    1    1 \nFord Pantera L        14.5    0    1 \nFerrari Dino          15.5    0    1 \nMaserati Bora         14.6    0    1 \nVolvo 142E            18.6    1    1 \n\\s\\n                      gear   carb\n—————————————————————————————————\nMazda RX4             4      4   \nMazda RX4 Wag         4      4   \nDatsun 710            4      1   \nHornet 4 Drive        3      1   \nHornet Sportabout     3      2   \nValiant               3      1   \nDuster 360            3      4   \nMerc 240D             4      2   \nMerc 230              4      2   \nMerc 280              4      4   \nMerc 280C             4      4   \nMerc 450SE            3      3   \nMerc 450SL            3      3   \nMerc 450SLC           3      3   \nCadillac Fleetwood    3      4   \nLincoln Continental   3      4   \nChrysler Imperial     3      4   \nFiat 128              4      1   \nHonda Civic           4      2   \nToyota Corolla        4      1   \nToyota Corona         3      1   \nDodge Challenger      3      2   \nAMC Javelin           3      2   \nCamaro Z28            3      4   \nPontiac Firebird      3      2   \nFiat X1-9             4      1   \nPorsche 914-2         5      2   \nLotus Europa          5      2   \nFord Pantera L        5      4   \nFerrari Dino          5      6   \nMaserati Bora         5      8   \nVolvo 142E            4      2   \n"