Theformatters package provides two core pieces offunctionality, both related to ASCII rendering:
format_value provides the ability to format single- andmulti-valued elements into ASCII display-ready stringsmatrix_form framework provides generics forimplementing ASCII rendering support for display tablesBoth of these feature sets are used in thertablespackage.
The core motivation forformatters is the rendering ofreporting tables into ASCII. In this context a “value” is the rawcontent that to appear in a single table cell. Most commonly this is anumeric vector of length 1, 2 or – occasionally – 3.
formatters is available on CRAN and you can install thelatest released version with:
install.packages("formatters")or you can install the latest development version directly fromGitHub with:
# install.packages("pak")pak::pak("insightsengineering/formatters")Packaged releases (both those on CRAN and those between official CRANreleases) can be found in thereleaseslist.
To understand how to use this package, please refer to theIntroductiontoformatters article, which provides multiple examplesof code implementation.
formatters ships with a large number of pre-definedformats appropriate for rendering values into ASCII strings. Theseexisting formats are specified by their labels. We can see the list ofthese by calling thelist_valid_format_labels function:
list_valid_format_labels()$`1d` [1]"xx""xx.""xx.x" [4]"xx.xx""xx.xxx""xx.xxxx" [7]"xx%""xx.%""xx.x%"[10]"xx.xx%""xx.xxx%""(N=xx)"[13]">999.9"">999.99""x.xxxx | (<0.0001)"$`2d` [1]"xx / xx""xx. / xx.""xx.x / xx.x" [4]"xx.xx / xx.xx""xx.xxx / xx.xxx""xx (xx%)" [7]"xx (xx.%)""xx (xx.x%)""xx (xx.xx%)"[10]"xx. (xx.%)""xx.x (xx.x%)""xx.xx (xx.xx%)"[13]"(xx, xx)""(xx., xx.)""(xx.x, xx.x)"[16]"(xx.xx, xx.xx)""(xx.xxx, xx.xxx)""(xx.xxxx, xx.xxxx)"[19]"xx - xx""xx.x - xx.x""xx.xx - xx.xx"[22]"xx (xx)""xx. (xx.)""xx.x (xx.x)"[25]"xx.xx (xx.xx)""xx (xx.)""xx (xx.x)"[28]"xx (xx.xx)""xx.x, xx.x""xx.x to xx.x"$`3d`[1]"xx.xx (xx.xx - xx.xx)"attr(,"info")[1]"xx does not modify the element, and xx. rounds a number to 0 digits"Each of these labels describes how the incoming (possiblymulti-element) raw value will be formatted.xx indicatesthat an element of the value will be printed as is, with nomodification.xx. indicates that a numeric value elementwill be rounded to 0 decimal places,xx.x indicatesrounding to 1 decimal place, etc.
Values are formatted via calls toformat_value, likeso:
format_value(5.1235,format ="xx.xx")[1]"5.12"format_value(c(1.2355,2.6789),"(xx.xx, xx.xx)")[1]"(1.24, 2.68)"Advanced Usage Only These features are supported,and in fact are used inrtables and the experimentalrlistings. That said, the API is currently very low-leveland tailored to whatrtables andrlistingsneed. How useful this is to other table frameworks may vary.
The second major piece of functionality informatters isthe ability to render tables into ASCII (and thus directly to theterminal) based on a so-calledMatrixPrintFormrepresentation of the table.
To hook uprtables-style ASCII display for your tables,it suffices to export a method for the exportedmatrix_formgenericformatters provides. This method must return aMatrixPrintForm object representing your table.
We can build a baby example method fordata.frames toillustrate this process:
## pagdfrow supports a large number of pieces of information regarding## siblings and what information should be repeated after a pagination.## we ignore all that here and just give the absolutely crucial info:## nm (name), lab (label), rnum (absolute row position), pth ("path"),## extent (how many lines it takes up), rclass ("class of row")fake_pagdf_row<-function(i, rnms) { nm<- rnms[i]pagdfrow(nm = nm,lab = nm,rnum = i,pth = nm,extent = 1L,rclass ="NA")}matrix_form.data.frame<-function(df) { fmts<-lapply(df,function(x)if(is.null(obj_format(x)))"xx"elseobj_format(x)) bodystrs<-mapply(function(x, fmt) {sapply(x, format_value,format = fmt) },x = df,fmt = fmts) rnms<-row.names(df)if(is.null(rnms)) rnms<-as.character(seq_len(NROW(df))) cnms<-names(df) strings<-rbind(c("", cnms),cbind(rnms, bodystrs)) fnr<-nrow(strings) fnc<-ncol(strings)## center alignment for column labels, left alignment for everything else aligns<-rbind("center",matrix("left",nrow =NROW(df),ncol = fnc))## build up fake pagination df, rowdf<-basic_pagdf(row.names(df))MatrixPrintForm(strings = strings,aligns = aligns,spans =matrix(1,nrow = fnr,ncol = fnc),formats =NULL,row_info = rowdf,has_topleft =FALSE,nlines_header =1,nrow_header =1)}cat(toString(matrix_form.data.frame(mtcars))) mpg cyl disp hp drat wt qsec vs am gear carb—————————————————————————————————————————————————————————————————————————————————————————————Mazda RX42161601103.92.6216.460144Mazda RX4 Wag2161601103.92.87517.020144Datsun71022.84108933.852.3218.611141Hornet4 Drive21.462581103.083.21519.441031Hornet Sportabout18.783601753.153.4417.020032Valiant18.162251052.763.4620.221031Duster36014.383602453.213.5715.840034Merc 240D24.44146.7623.693.19201042Merc23022.84140.8953.923.1522.91042Merc28019.26167.61233.923.4418.31044Merc 280C17.86167.61233.923.4418.91044Merc 450SE16.48275.81803.074.0717.40033Merc 450SL17.38275.81803.073.7317.60033Merc 450SLC15.28275.81803.073.78180033Cadillac Fleetwood10.484722052.935.2517.980034Lincoln Continental10.4846021535.42417.820034Chrysler Imperial14.784402303.235.34517.420034Fiat12832.4478.7664.082.219.471141Honda Civic30.4475.7524.931.61518.521142Toyota Corolla33.9471.1654.221.83519.91141Toyota Corona21.54120.1973.72.46520.011031Dodge Challenger15.583181502.763.5216.870032AMC Javelin15.283041503.153.43517.30032Camaro Z2813.383502453.733.8415.410034Pontiac Firebird19.284001753.083.84517.050032Fiat X1-927.3479664.081.93518.91141Porsche914-2264120.3914.432.1416.70152Lotus Europa30.4495.11133.771.51316.91152Ford Pantera L15.883512644.223.1714.50154Ferrari Dino19.761451753.622.7715.50156Maserati Bora1583013353.543.5714.60158Volvo 142E21.441211094.112.7818.61142