From ccdc6e00a762d33ce1b4d910a185b19d1fc00631 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Mon, 11 Mar 2024 17:45:41 -0400 Subject: [PATCH 1/8] Clean up function documentation --- NAMESPACE | 1 - NEWS.md | 1 + R/listing_export.R | 4 +- R/paginate_listing.R | 16 ---- R/rlistings.R | 119 +++++++++++-------------- R/rlistings_methods.R | 71 ++++++++------- man/defunct.Rd | 38 -------- man/listing_methods.Rd | 22 ++--- man/listings.Rd | 77 ++++++++-------- man/make_row_df-listing_df-method.Rd | 14 +-- man/matrix_form-listing_df-method.Rd | 14 +-- man/reexports.Rd | 2 + man/vec_nlines.Rd | 12 ++- tests/testthat/test-export.R | 2 - tests/testthat/test-listings.R | 2 - tests/testthat/test-paginate_listing.R | 5 -- tests/testthat/test-print.R | 1 + 17 files changed, 164 insertions(+), 237 deletions(-) delete mode 100644 man/defunct.Rd diff --git a/NAMESPACE b/NAMESPACE index 6961d5e3..b06aa2f1 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -10,7 +10,6 @@ export(export_as_txt) export(get_keycols) export(is_keycol) export(listing_dispcols) -export(pag_listing_indices) export(paginate_listing) exportMethods("[") exportMethods("main_footer<-") diff --git a/NEWS.md b/NEWS.md index 9f748db1..b6e085ae 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,6 +2,7 @@ * Added relevant tests for pagination when key columns need to be repeated in each page and when they are all empty. * Added relevant tests for new line characters' handling in footnotes and titles. * Added cheatsheet. + * Remove defunct function `pag_listing_indices`. ## rlistings 0.2.7 * Applied `styler` and resolved package lint. Changed default indentation from 4 spaces to 2. diff --git a/R/listing_export.R b/R/listing_export.R index 5af4c9d3..5f8ac89f 100644 --- a/R/listing_export.R +++ b/R/listing_export.R @@ -1,14 +1,16 @@ #' @importFrom formatters export_as_txt #' -#' @export #' @examples #' dat <- ex_adae +#' #' lsting <- as_listing(dat[1:25, ], key_cols = c("USUBJID", "AESOC")) %>% #' add_listing_col("AETOXGR") %>% #' add_listing_col("BMRKR1", format = "xx.x") %>% #' add_listing_col("AESER / AREL", fun = function(df) paste(df$AESER, df$AREL, sep = " / ")) #' main_title(lsting) <- "this is some title" #' main_footer(lsting) <- "this is some footer" +#' #' cat(export_as_txt(lsting, file = NULL, paginate = TRUE)) #' +#' @export formatters::export_as_txt diff --git a/R/paginate_listing.R b/R/paginate_listing.R index a0c5423e..f7ca6406 100644 --- a/R/paginate_listing.R +++ b/R/paginate_listing.R @@ -106,19 +106,3 @@ paginate_listing <- function(lsting, ret <- unlist(full_pag, recursive = FALSE) ret } - -#' @title Defunct functions -#' -#' @description -#' These functions are defunct and their symbols will be removed entirely -#' in a future release. -#' @rdname defunct -#' @inheritParams paginate_listing -#' @export -pag_listing_indices <- function(lsting, - lpp = 15, - colwidths = NULL, - max_width = NULL, - verbose = FALSE) { - .Defunct("paginate_indices", package = "formatters") -} diff --git a/R/rlistings.R b/R/rlistings.R index 543501b4..ad16fbe9 100644 --- a/R/rlistings.R +++ b/R/rlistings.R @@ -1,47 +1,45 @@ setOldClass(c("listing_df", "tbl_df", "tbl", "data.frame")) setOldClass(c("MatrixPrintForm", "list")) -#' @rdname listings -#' @title Create a Listing from a `data.frame` or `tibble` +#' Create a listing from a `data.frame` or `tibble` #' #' @description `r lifecycle::badge("experimental")` #' -#' Creates listings by using `cols` and `key_cols` to produce a compact and -#' elegant representation of the `data.frame` or `tibble` in input. +#' Create listings displaying `key_cols` and `disp_cols` to produce a compact and +#' elegant representation of the input `data.frame` or `tibble`. #' -#' @param df data.frame or listing_df. The (non-listing) data.frame to be converted to a listing or -#' the listing_df to be modified. -#' @param key_cols character. Names of columns which should be treated as *key columns* +#' @param df (`data.frame` or `listing_df`)\cr the `data.frame` to be converted to a listing or +#' `listing_df` to be modified. +#' @param key_cols (`character`)\cr vector of names of columns which should be treated as *key columns* #' when rendering the listing. Key columns allow you to group repeat occurrences. -#' @param disp_cols character or NULL. Names of non-key columns which should be displayed when -#' the listing is rendered. Defaults to all columns of `df` not named in `key_cols` or +#' @param disp_cols (`character` or `NULL`)\cr vector of names of non-key columns which should be +#' displayed when the listing is rendered. Defaults to all columns of `df` not named in `key_cols` or #' `non_disp_cols`. -#' @param non_disp_cols character or NULL. Names of non-key columns to be excluded as display -#' columns. All other non-key columns are then treated as display columns. Invalid if -#' `disp_cols` is non-NULL. -#' @param unique_rows logical(1). Should only unique rows be included in the listing. Defaults to `FALSE`. -#' @param default_formatting list. A named list of default column format configurations to apply when rendering the -#' listing. Each name-value pair consists of a name corresponding to a data class (or "numeric" for all unspecified -#' numeric classes) and a value of type `fmt_config` with the format configuration that should be implemented for -#' columns of that class. If named element "all" is included in the list, this configuration will be used for all -#' data classes not specified. Objects of type `fmt_config` can take 3 arguments: `format`, `na_str`, and `align`. -#' @param col_formatting list. A named list of custom column formatting configurations to apply to specific columns -#' when rendering the listing. Each name-value pair consists of a name corresponding to a column name and a value of -#' type `fmt_config` with the formatting configuration that should be implemented for that column. Objects of type -#' `fmt_config` can take 3 arguments: `format`, `na_str`, and `align`. Defaults to `NULL`. -#' @param main_title character(1) or NULL. The main title for the listing, or -#' `NULL` (the default). Must be length 1 non-NULL. -#' @param subtitles character or NULL. A vector of subtitle(s) for the -#' listing, or `NULL` (the default). -#' @param main_footer character or NULL. A vector of main footer lines -#' for the listing, or `NULL` (the default). -#' @param prov_footer character or NULL. A vector of provenance strings -#' for the listing, or `NULL` (the default). Each string element is placed on a new line. -#' @param vec any. A column vector from a `listing_df` to be annotated as a key column. +#' @param non_disp_cols (`character` or `NULL`)\cr vector of names of non-key columns to be excluded as display +#' columns. All other non-key columns are treated as display columns. Ignored if `disp_cols` is non-`NULL`. +#' @param unique_rows (`logical(1)`)\cr whether only unique rows should be included in the listing. Defaults to `FALSE`. +#' @param default_formatting (`list`)\cr a named list of default column format configurations to apply when rendering +#' the listing. Each name-value pair consists of a name corresponding to a data class (or "numeric" for all +#' unspecified numeric classes) and a value of type `fmt_config` with the format configuration that should be +#' implemented for columns of that class. If named element "all" is included in the list, this configuration will be +#' used for all data classes not specified. Objects of type `fmt_config` can take 3 arguments: `format`, `na_str`, +#' and `align`. +#' @param col_formatting (`list`)\cr a named list of custom column formatting configurations to apply to specific +#' columns when rendering the listing. Each name-value pair consists of a name corresponding to a column name and a +#' value of type `fmt_config` with the formatting configuration that should be implemented for that column. Objects +#' of type `fmt_config` can take 3 arguments: `format`, `na_str`, and `align`. Defaults to `NULL`. +#' @param main_title (`character(1)` or `NULL`)\cr the main title for the listing, or +#' `NULL` (the default). +#' @param subtitles (`character` or `NULL`)\cr a vector of subtitles for the listing, or `NULL` (the default). +#' @param main_footer (`character` or `NULL`)\cr a vector of main footer lines for the listing, or `NULL` (the default). +#' @param prov_footer (`character` or `NULL`)\cr a vector of provenance footer lines for the listing, or `NULL` +#' (the default). Each string element is placed on a new line. +#' @param vec (`character(1)`)\cr name of a column vector from a `listing_df` object to be annotated as a key column. #' -#' @return A `listing_df` object, sorted by the key columns. +#' @return a `listing_df` object, sorted by its key columns. #' -#' @details At its core, a `listing_df` object is a `tbl_df` object with a customized +#' @details +#' At its core, a `listing_df` object is a `tbl_df` object with a customized #' print method and support for the formatting and pagination machinery provided by #' the `formatters` package. #' @@ -51,9 +49,9 @@ setOldClass(c("MatrixPrintForm", "list")) #' #' All key columns are also display columns. #' -#' `listing_df` objects are always sorted by their set of key_columns at creation time. +#' `listing_df` objects are always sorted by their set of key columns at creation time. #' Any `listing_df` object which is not sorted by its full set of key columns (e.g., -#' one whose rows have been reordered explicitly creation) is invalid and the behavior +#' one whose rows have been reordered explicitly during creation) is invalid and the behavior #' when rendering or paginating that object is undefined. #' #' Each value of a key column is printed only once per page and per unique combination of @@ -70,7 +68,6 @@ setOldClass(c("MatrixPrintForm", "list")) #' within the object available for computations but *are not rendered during #' printing or export of the listing*. #' -#' #' @examples #' dat <- ex_adae #' @@ -128,6 +125,7 @@ setOldClass(c("MatrixPrintForm", "list")) #' cat(toString(mat)) #' #' @export +#' @rdname listings as_listing <- function(df, key_cols = names(df)[1], disp_cols = NULL, @@ -230,7 +228,6 @@ as_listing <- function(df, df } - #' @export #' @rdname listings as_keycol <- function(vec) { @@ -243,15 +240,12 @@ as_keycol <- function(vec) { vec } - #' @export #' @rdname listings is_keycol <- function(vec) { inherits(vec, "listing_keycol") } - - #' @export #' @rdname listings get_keycols <- function(df) { @@ -259,19 +253,19 @@ get_keycols <- function(df) { } #' @inherit formatters::matrix_form -#' @seealso [formatters::matrix_form()] -#' @param indent_rownames logical(1). Silently ignored, as listings do not have row names +#' @param indent_rownames (`logical(1)`)\cr silently ignored, as listings do not have row names #' nor indenting structure. +#' @param expand_newlines (`logical(1)`)\cr this should always be `TRUE` for listings. We keep it +#' for debugging reasons. +#' +#' @return a [`MatrixPrintForm`] object. +#' +#' @seealso [formatters::matrix_form()] #' #' @examples #' lsting <- as_listing(mtcars) #' mf <- matrix_form(lsting) #' -#' @return a `MatrixPrintForm` object -#' -#' @note Parameter `expand_newlines` should always be `TRUE` for listings. We keep it for -#' debugging reasons. -#' #' @export setMethod( "matrix_form", "listing_df", @@ -286,7 +280,6 @@ setMethod( attributes(listing) <- atts keycols <- get_keycols(listing) - bodymat <- matrix("", nrow = nrow(listing), ncol = ncol(listing) @@ -294,7 +287,6 @@ setMethod( colnames(bodymat) <- names(listing) - curkey <- "" for (i in seq_along(keycols)) { kcol <- keycols[i] @@ -314,7 +306,6 @@ setMethod( } } - fullmat <- rbind( var_labels(listing, fill = TRUE), bodymat @@ -356,21 +347,23 @@ setMethod( } ) - #' @export #' @rdname listings listing_dispcols <- function(df) attr(df, "listing_dispcols") %||% character() +#' @param new (`character`)\cr vector of names of columns to be added to +#' the set of display columns. +#' #' @export -#' @param new character. Names of columns to be added to -#' the set of display columns. #' @rdname listings add_listing_dispcol <- function(df, new) { listing_dispcols(df) <- c(listing_dispcols(df), new) df } + +#' @param value (`character(1)`)\cr new value. +#' #' @export -#' @param value character. New value. #' @rdname listings `listing_dispcols<-` <- function(df, value) { if (!is.character(value)) { @@ -390,22 +383,18 @@ add_listing_dispcol <- function(df, new) { df } - - -#' @rdname listings -#' -#' @param name character(1). Name of the existing or new column to be -#' displayed when the listing is rendered. -#' @param fun function or NULL. A function which accepts \code{df} and -#' returns the vector for a new column, which is added to \code{df} as -#' \code{name}, or NULL if marking an existing column as -#' a listing column. #' @inheritParams formatters::fmt_config +#' @param name (`character(1)`)\cr name of the existing or new column to be +#' displayed when the listing is rendered. +#' @param fun (`function` or `NULL`)\cr a function which accepts `df` and +#' returns the vector for a new column, which is added to `df` as +#' `name`, or `NULL` if marking an existing column as a listing column. #' -#' @return `df`, with `name` created (if necessary) and marked for +#' @return `df` with `name` created (if necessary) and marked for #' display during rendering. #' #' @export +#' @rdname listings add_listing_col <- function(df, name, fun = NULL, diff --git a/R/rlistings_methods.R b/R/rlistings_methods.R index 1c73458b..b80431af 100644 --- a/R/rlistings_methods.R +++ b/R/rlistings_methods.R @@ -11,14 +11,15 @@ #' Methods for `listing_df` objects #' -#' See core documentation in \code{formatters} for descriptions -#' of these functions. +#' See core documentation in [`formatters`] for descriptions of these functions. #' -#' @export #' @inheritParams formatters::toString -#' @param x listing_df. The listing. -#' @param ... dots. See `toString` method in \code{formatters} for all parameters. +#' @param x (`listing_df`)\cr the listing. +#' @param ... additional parameters passed to [formatters::toString()]. +#' #' @method print listing_df +#' +#' @export #' @name listing_methods print.listing_df <- function(x, widths = NULL, tf_wrap = FALSE, max_width = NULL, ...) { cat(toString(matrix_form(x), widths = widths, tf_wrap = tf_wrap, max_width = max_width, ...)) @@ -44,11 +45,11 @@ basic_run_lens <- function(x) { diff(c(0L, i)) } - -#' @rdname vec_nlines -#' @param df listing_df. The listing. +#' @param df (`listing_df`)\cr the listing. #' @param colnm Column name #' @param colvec Column values based on colnm +#' +#' @rdname vec_nlines format_colvector <- function(df, colnm, colvec = df[[colnm]]) { if (missing(colvec) && !(colnm %in% names(df))) { stop("column ", colnm, " not found") @@ -67,17 +68,16 @@ format_colvector <- function(df, colnm, colvec = df[[colnm]]) { #' For `vec_nlines`, calculate the number of lines each element of a column vector will #' take to render. For `format_colvector`, #' -#' @param vec any vector. A column vector to be rendered into ASCII. -#' @param max_width numeric (or NULL). The width the column will be -#' rendered in. -#' @return a numeric vector of the number of lines elementwise that -#' will be needed to render the elements of \code{vec} to width -#' \code{max_width}. +#' @param vec (`any`)\cr a column vector to be rendered into ASCII. +#' @param max_width (`numeric(1)` or `NULL`)\cr the width to render the column with. +#' @return (`numeric`)\cr a vector of the number of lines element-wise that will be +#' needed to render the elements of `vec` to width `max_width`. +#' #' @keywords internal setGeneric("vec_nlines", function(vec, max_width = NULL) standardGeneric("vec_nlines")) #' @rdname vec_nlines -#' @param vec A vector. +#' @param vec (`any`)\cr a vector. #' @keywords internal setMethod("vec_nlines", "ANY", function(vec, max_width = NULL) { if (is.null(max_width)) { @@ -100,19 +100,22 @@ setMethod("vec_nlines", "ANY", function(vec, max_width = NULL) { ## ret[is.na(ret)] <- format_value(NA_character ## }) -#' Make pagination dataframe for a listing -#' @export +#' Make pagination data frame for a listing +#' #' @inheritParams formatters::make_row_df -#' @param tt listing_df. The listing to be rendered -#' @param visible_only logical(1). Ignored, as listings -#' do not have non-visible structural elements. +#' @param tt (`listing_df`)\cr the listing to be rendered. +#' @param visible_only (`logical(1)`)\cr ignored, as listings do not have +#' non-visible structural elements. +#' +#' @return a `data.frame` with pagination information. +#' +#' @seealso [formatters::make_row_df()] #' #' @examples #' lsting <- as_listing(mtcars) #' mf <- matrix_form(lsting) #' -#' @return a data.frame with pagination information. -#' @seealso \code{\link[formatters]{make_row_df}} +#' @export setMethod( "make_row_df", "listing_df", function(tt, colwidths = NULL, visible_only = TRUE, @@ -216,14 +219,14 @@ setMethod( ## ret ## }) -#' @export -#' @param x listing_df. The listing. #' @inheritParams base::Extract -#' @param i ANY. Passed to base `[` methods. -#' @param j ANY. Passed to base `[` methods. +#' @param x (`listing_df`)\cr the listing. +#' @param i (`any`)\cr object passed to base `[` methods. +#' @param j (`any`)\cr object passed to base `[` methods. +#' +#' @export #' @aliases [,listing_df-method #' @rdname listing_methods -#' @keywords internal setMethod( "[", "listing_df", function(x, i, j, drop = FALSE) { @@ -238,17 +241,19 @@ setMethod( ) #' @rdname listing_methods -#' @param obj The object. -#' @export -#' @return for getter methods, the value of the aspect of -#' \code{obj}; for setter methods, \code{obj} with -#' the relevant element of the listing updated. +#' @param obj (`listing_df`)\cr the listing. +#' +#' @return +#' * Getter methods return the value of the aspect of `obj`. +#' * Setter methods return `obj` with the relevant element of the listing updated. #' #' @examples #' lsting <- as_listing(mtcars) #' main_title(lsting) <- "Hi there" #' #' main_title(lsting) +#' +#' @export setMethod( "main_title", "listing_df", function(obj) attr(obj, "main_title") %||% character() @@ -260,12 +265,14 @@ setMethod( "subtitles", "listing_df", function(obj) attr(obj, "subtitles") %||% character() ) + #' @rdname listing_methods #' @export setMethod( "main_footer", "listing_df", function(obj) attr(obj, "main_footer") %||% character() ) + #' @rdname listing_methods #' @export setMethod( diff --git a/man/defunct.Rd b/man/defunct.Rd deleted file mode 100644 index 14514726..00000000 --- a/man/defunct.Rd +++ /dev/null @@ -1,38 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/paginate_listing.R -\name{pag_listing_indices} -\alias{pag_listing_indices} -\title{Defunct functions} -\usage{ -pag_listing_indices( - lsting, - lpp = 15, - colwidths = NULL, - max_width = NULL, - verbose = FALSE -) -} -\arguments{ -\item{lsting}{listing_df. The listing to paginate.} - -\item{lpp}{numeric(1) or NULL. Number of row lines (not counting titles and -footers) to have per page. Standard is \code{70} while \code{NULL} disables vertical -pagination.} - -\item{colwidths}{numeric vector. Column widths (in characters) for -use with vertical pagination.} - -\item{max_width}{integer(1), character(1) or \code{NULL}. Width that title -and footer (including footnotes) materials should be -word-wrapped to. If \code{NULL}, it is set to the current print width -of the session (\code{getOption("width")}). If set to \code{"auto"}, -the width of the table (plus any table inset) is used. Ignored -completely if \code{tf_wrap} is \code{FALSE}.} - -\item{verbose}{logical(1). Should additional informative messages about the search for -pagination breaks be shown. Defaults to \code{FALSE}.} -} -\description{ -These functions are defunct and their symbols will be removed entirely -in a future release. -} diff --git a/man/listing_methods.Rd b/man/listing_methods.Rd index 65b8a96c..2dced068 100644 --- a/man/listing_methods.Rd +++ b/man/listing_methods.Rd @@ -41,7 +41,7 @@ \S4method{num_rep_cols}{listing_df}(obj) } \arguments{ -\item{x}{listing_df. The listing.} +\item{x}{(\code{listing_df})\cr the listing.} \item{widths}{numeric (or \code{NULL}). (proposed) widths for the columns of \code{x}. The expected length of this numeric vector can be @@ -58,11 +58,11 @@ of the session (\code{getOption("width")}). If set to \code{"auto"}, the width of the table (plus any table inset) is used. Ignored completely if \code{tf_wrap} is \code{FALSE}.} -\item{...}{dots. See \code{toString} method in \code{formatters} for all parameters.} +\item{...}{additional parameters passed to \code{\link[formatters:tostring]{formatters::toString()}}.} -\item{i}{ANY. Passed to base \code{[} methods.} +\item{i}{(\code{any})\cr object passed to base \code{[} methods.} -\item{j}{ANY. Passed to base \code{[} methods.} +\item{j}{(\code{any})\cr object passed to base \code{[} methods.} \item{drop}{For matrices and arrays. If \code{TRUE} the result is coerced to the lowest possible dimension (see the examples). This @@ -70,24 +70,24 @@ completely if \code{tf_wrap} is \code{FALSE}.} \code{\link[base]{drop}} for further details. } -\item{obj}{The object.} +\item{obj}{(\code{listing_df})\cr the listing.} \item{value}{typically an array-like \R object of a similar class as \code{x}.} } \value{ -for getter methods, the value of the aspect of -\code{obj}; for setter methods, \code{obj} with -the relevant element of the listing updated. +\itemize{ +\item Getter methods return the value of the aspect of \code{obj}. +\item Setter methods return \code{obj} with the relevant element of the listing updated. +} } \description{ -See core documentation in \code{formatters} for descriptions -of these functions. +See core documentation in \code{\link{formatters}} for descriptions of these functions. } \examples{ lsting <- as_listing(mtcars) main_title(lsting) <- "Hi there" main_title(lsting) + } -\keyword{internal} diff --git a/man/listings.Rd b/man/listings.Rd index 63f8841a..b5f64e7a 100644 --- a/man/listings.Rd +++ b/man/listings.Rd @@ -9,7 +9,7 @@ \alias{add_listing_dispcol} \alias{listing_dispcols<-} \alias{add_listing_col} -\title{Create a Listing from a \code{data.frame} or \code{tibble}} +\title{Create a listing from a \code{data.frame} or \code{tibble}} \usage{ as_listing( df, @@ -47,59 +47,56 @@ add_listing_col( ) } \arguments{ -\item{df}{data.frame or listing_df. The (non-listing) data.frame to be converted to a listing or -the listing_df to be modified.} +\item{df}{(\code{data.frame} or \code{listing_df})\cr the \code{data.frame} to be converted to a listing or +\code{listing_df} to be modified.} -\item{key_cols}{character. Names of columns which should be treated as \emph{key columns} +\item{key_cols}{(\code{character})\cr vector of names of columns which should be treated as \emph{key columns} when rendering the listing. Key columns allow you to group repeat occurrences.} -\item{disp_cols}{character or NULL. Names of non-key columns which should be displayed when -the listing is rendered. Defaults to all columns of \code{df} not named in \code{key_cols} or +\item{disp_cols}{(\code{character} or \code{NULL})\cr vector of names of non-key columns which should be +displayed when the listing is rendered. Defaults to all columns of \code{df} not named in \code{key_cols} or \code{non_disp_cols}.} -\item{non_disp_cols}{character or NULL. Names of non-key columns to be excluded as display -columns. All other non-key columns are then treated as display columns. Invalid if -\code{disp_cols} is non-NULL.} +\item{non_disp_cols}{(\code{character} or \code{NULL})\cr vector of names of non-key columns to be excluded as display +columns. All other non-key columns are treated as display columns. Ignored if \code{disp_cols} is non-\code{NULL}.} -\item{unique_rows}{logical(1). Should only unique rows be included in the listing. Defaults to \code{FALSE}.} +\item{unique_rows}{(\code{logical(1)})\cr whether only unique rows should be included in the listing. Defaults to \code{FALSE}.} -\item{default_formatting}{list. A named list of default column format configurations to apply when rendering the -listing. Each name-value pair consists of a name corresponding to a data class (or "numeric" for all unspecified -numeric classes) and a value of type \code{fmt_config} with the format configuration that should be implemented for -columns of that class. If named element "all" is included in the list, this configuration will be used for all -data classes not specified. Objects of type \code{fmt_config} can take 3 arguments: \code{format}, \code{na_str}, and \code{align}.} +\item{default_formatting}{(\code{list})\cr a named list of default column format configurations to apply when rendering +the listing. Each name-value pair consists of a name corresponding to a data class (or "numeric" for all +unspecified numeric classes) and a value of type \code{fmt_config} with the format configuration that should be +implemented for columns of that class. If named element "all" is included in the list, this configuration will be +used for all data classes not specified. Objects of type \code{fmt_config} can take 3 arguments: \code{format}, \code{na_str}, +and \code{align}.} -\item{col_formatting}{list. A named list of custom column formatting configurations to apply to specific columns -when rendering the listing. Each name-value pair consists of a name corresponding to a column name and a value of -type \code{fmt_config} with the formatting configuration that should be implemented for that column. Objects of type -\code{fmt_config} can take 3 arguments: \code{format}, \code{na_str}, and \code{align}. Defaults to \code{NULL}.} +\item{col_formatting}{(\code{list})\cr a named list of custom column formatting configurations to apply to specific +columns when rendering the listing. Each name-value pair consists of a name corresponding to a column name and a +value of type \code{fmt_config} with the formatting configuration that should be implemented for that column. Objects +of type \code{fmt_config} can take 3 arguments: \code{format}, \code{na_str}, and \code{align}. Defaults to \code{NULL}.} -\item{main_title}{character(1) or NULL. The main title for the listing, or -\code{NULL} (the default). Must be length 1 non-NULL.} +\item{main_title}{(\code{character(1)} or \code{NULL})\cr the main title for the listing, or +\code{NULL} (the default).} -\item{subtitles}{character or NULL. A vector of subtitle(s) for the -listing, or \code{NULL} (the default).} +\item{subtitles}{(\code{character} or \code{NULL})\cr a vector of subtitles for the listing, or \code{NULL} (the default).} -\item{main_footer}{character or NULL. A vector of main footer lines -for the listing, or \code{NULL} (the default).} +\item{main_footer}{(\code{character} or \code{NULL})\cr a vector of main footer lines for the listing, or \code{NULL} (the default).} -\item{prov_footer}{character or NULL. A vector of provenance strings -for the listing, or \code{NULL} (the default). Each string element is placed on a new line.} +\item{prov_footer}{(\code{character} or \code{NULL})\cr a vector of provenance footer lines for the listing, or \code{NULL} +(the default). Each string element is placed on a new line.} -\item{vec}{any. A column vector from a \code{listing_df} to be annotated as a key column.} +\item{vec}{(\code{character(1)})\cr name of a column vector from a \code{listing_df} object to be annotated as a key column.} -\item{new}{character. Names of columns to be added to +\item{new}{(\code{character})\cr vector of names of columns to be added to the set of display columns.} -\item{value}{character. New value.} +\item{value}{(\code{character(1)})\cr new value.} -\item{name}{character(1). Name of the existing or new column to be +\item{name}{(\code{character(1)})\cr name of the existing or new column to be displayed when the listing is rendered.} -\item{fun}{function or NULL. A function which accepts \code{df} and +\item{fun}{(\code{function} or \code{NULL})\cr a function which accepts \code{df} and returns the vector for a new column, which is added to \code{df} as -\code{name}, or NULL if marking an existing column as -a listing column.} +\code{name}, or \code{NULL} if marking an existing column as a listing column.} \item{format}{character(1) or function. A format label (string) or \code{formatter} function.} @@ -108,16 +105,16 @@ a listing column.} \item{align}{character(1). Alignment values should be rendered with.} } \value{ -A \code{listing_df} object, sorted by the key columns. +a \code{listing_df} object, sorted by its key columns. -\code{df}, with \code{name} created (if necessary) and marked for +\code{df} with \code{name} created (if necessary) and marked for display during rendering. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} -Creates listings by using \code{cols} and \code{key_cols} to produce a compact and -elegant representation of the \code{data.frame} or \code{tibble} in input. +Create listings displaying \code{key_cols} and \code{disp_cols} to produce a compact and +elegant representation of the input \code{data.frame} or \code{tibble}. } \details{ At its core, a \code{listing_df} object is a \code{tbl_df} object with a customized @@ -130,9 +127,9 @@ Key columns act as indexes, which means a number of things in practice. All key columns are also display columns. -\code{listing_df} objects are always sorted by their set of key_columns at creation time. +\code{listing_df} objects are always sorted by their set of key columns at creation time. Any \code{listing_df} object which is not sorted by its full set of key columns (e.g., -one whose rows have been reordered explicitly creation) is invalid and the behavior +one whose rows have been reordered explicitly during creation) is invalid and the behavior when rendering or paginating that object is undefined. Each value of a key column is printed only once per page and per unique combination of diff --git a/man/make_row_df-listing_df-method.Rd b/man/make_row_df-listing_df-method.Rd index cdc2183f..d2f0b0ae 100644 --- a/man/make_row_df-listing_df-method.Rd +++ b/man/make_row_df-listing_df-method.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/rlistings_methods.R \name{make_row_df,listing_df-method} \alias{make_row_df,listing_df-method} -\title{Make pagination dataframe for a listing} +\title{Make pagination data frame for a listing} \usage{ \S4method{make_row_df}{listing_df}( tt, @@ -19,12 +19,12 @@ ) } \arguments{ -\item{tt}{listing_df. The listing to be rendered} +\item{tt}{(\code{listing_df})\cr the listing to be rendered.} \item{colwidths}{numeric. Internal detail do not set manually.} -\item{visible_only}{logical(1). Ignored, as listings -do not have non-visible structural elements.} +\item{visible_only}{(\code{logical(1)})\cr ignored, as listings do not have +non-visible structural elements.} \item{rownum}{numeric(1). Internal detail do not set manually.} @@ -44,10 +44,10 @@ do not have non-visible structural elements.} \item{nsibs}{integer(1). Internal detail do not set manually.} } \value{ -a data.frame with pagination information. +a \code{data.frame} with pagination information. } \description{ -Make pagination dataframe for a listing +Make pagination data frame for a listing } \examples{ lsting <- as_listing(mtcars) @@ -55,5 +55,5 @@ mf <- matrix_form(lsting) } \seealso{ -\code{\link[formatters]{make_row_df}} +\code{\link[formatters:make_row_df]{formatters::make_row_df()}} } diff --git a/man/matrix_form-listing_df-method.Rd b/man/matrix_form-listing_df-method.Rd index a84f4ad4..0d2208e5 100644 --- a/man/matrix_form-listing_df-method.Rd +++ b/man/matrix_form-listing_df-method.Rd @@ -9,16 +9,14 @@ \arguments{ \item{obj}{ANY. Object to be transformed into a ready-to-render form (a \code{MatrixPrintForm} object)} -\item{indent_rownames}{logical(1). Silently ignored, as listings do not have row names +\item{indent_rownames}{(\code{logical(1)})\cr silently ignored, as listings do not have row names nor indenting structure.} -\item{expand_newlines}{logical(1). Should the matrix form generated -expand rows whose values contain newlines into multiple -'physical' rows (as they will appear when rendered into -ASCII). Defaults to \code{TRUE}} +\item{expand_newlines}{(\code{logical(1)})\cr this should always be \code{TRUE} for listings. We keep it +for debugging reasons.} } \value{ -a \code{MatrixPrintForm} object +a \code{\link{MatrixPrintForm}} object. } \description{ Although \code{rtables} are represented as a tree data structure when outputting the table to ASCII or HTML it is @@ -29,10 +27,6 @@ The strings in the return object are defined as follows: row labels are those de cell values are determined using \code{get_formatted_cells}. (Column labels are calculated using a non-exported internal function. } -\note{ -Parameter \code{expand_newlines} should always be \code{TRUE} for listings. We keep it for -debugging reasons. -} \examples{ lsting <- as_listing(mtcars) mf <- matrix_form(lsting) diff --git a/man/reexports.Rd b/man/reexports.Rd index 529792d7..1006b197 100644 --- a/man/reexports.Rd +++ b/man/reexports.Rd @@ -7,12 +7,14 @@ \title{Objects exported from other packages} \examples{ dat <- ex_adae + lsting <- as_listing(dat[1:25, ], key_cols = c("USUBJID", "AESOC")) \%>\% add_listing_col("AETOXGR") \%>\% add_listing_col("BMRKR1", format = "xx.x") \%>\% add_listing_col("AESER / AREL", fun = function(df) paste(df$AESER, df$AREL, sep = " / ")) main_title(lsting) <- "this is some title" main_footer(lsting) <- "this is some footer" + cat(export_as_txt(lsting, file = NULL, paginate = TRUE)) } diff --git a/man/vec_nlines.Rd b/man/vec_nlines.Rd index 810bbcc1..1e36d59f 100644 --- a/man/vec_nlines.Rd +++ b/man/vec_nlines.Rd @@ -13,21 +13,19 @@ vec_nlines(vec, max_width = NULL) \S4method{vec_nlines}{ANY}(vec, max_width = NULL) } \arguments{ -\item{df}{listing_df. The listing.} +\item{df}{(\code{listing_df})\cr the listing.} \item{colnm}{Column name} \item{colvec}{Column values based on colnm} -\item{vec}{A vector.} +\item{vec}{(\code{any})\cr a vector.} -\item{max_width}{numeric (or NULL). The width the column will be -rendered in.} +\item{max_width}{(\code{numeric(1)} or \code{NULL})\cr the width to render the column with.} } \value{ -a numeric vector of the number of lines elementwise that -will be needed to render the elements of \code{vec} to width -\code{max_width}. +(\code{numeric})\cr a vector of the number of lines element-wise that will be +needed to render the elements of \code{vec} to width \code{max_width}. } \description{ For \code{vec_nlines}, calculate the number of lines each element of a column vector will diff --git a/tests/testthat/test-export.R b/tests/testthat/test-export.R index 50c43570..25bf04e8 100644 --- a/tests/testthat/test-export.R +++ b/tests/testthat/test-export.R @@ -24,7 +24,6 @@ testthat::test_that("key columns repeat with export_as_txt", { testthat::expect_snapshot(cat(listing_exp)) }) - testthat::test_that("key columns repeat with pagination with export_as_txt", { # pre-processing and ordering tbl <- as_listing( @@ -38,7 +37,6 @@ testthat::test_that("key columns repeat with pagination with export_as_txt", { page_break = "\n" )) - testthat::expect_snapshot(cat(listing)) }) diff --git a/tests/testthat/test-listings.R b/tests/testthat/test-listings.R index 9059ae38..47cde948 100644 --- a/tests/testthat/test-listings.R +++ b/tests/testthat/test-listings.R @@ -17,7 +17,6 @@ testthat::test_that("Column labels are the same", { ) }) - testthat::test_that("listings work well with different formats and attributes", { # (1) Error with NA values in numeric column when apply format anl_tmp <- anl @@ -132,7 +131,6 @@ testthat::test_that("regression test for keycols being lost due to `head()`", { ) }) - testthat::test_that("column inclusion and ordering stuff", { ## key columns must be left-most k columns (#36) lsting <- as_listing( diff --git a/tests/testthat/test-paginate_listing.R b/tests/testthat/test-paginate_listing.R index 2a891364..771ed901 100644 --- a/tests/testthat/test-paginate_listing.R +++ b/tests/testthat/test-paginate_listing.R @@ -165,7 +165,6 @@ testthat::test_that("pagination: lpp and cpp correctly computed for margins", { testthat::expect_identical(res, pag) }) - testthat::test_that("pagination works with col wrapping", { lsting <- h_lsting_adae(disp_cols = c("USUBJID", "AESOC", "RACE")) @@ -216,10 +215,6 @@ testthat::test_that("pagination repeats keycols in other pages", { ) }) -testthat::test_that("defunct is defunct", { - testthat::expect_error(pag_listing_indices(), "defunct") -}) - testthat::test_that("paginate_to_mpfs works with wrapping on keycols", { iris2 <- iris[1:10, 3:5] iris2$Species <- "SOMETHING VERY LONG THAT BREAKS PAGINATION" diff --git a/tests/testthat/test-print.R b/tests/testthat/test-print.R index f907daa0..1bc4e2bb 100644 --- a/tests/testthat/test-print.R +++ b/tests/testthat/test-print.R @@ -18,6 +18,7 @@ testthat::test_that("Listing print correctly with different widths", { testthat::expect_snapshot(cat(toString(matrix_form(lsting), widths = c(7, 8, 9), hsep = "-"))) }) + testthat::test_that("as_listing produces correct output when default_formatting is specified", { anl$BMRKR1[3:6] <- NA lsting <- as_listing( From 08a4683e04a8c52bbfcedee8eed93b17cc654643 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Mon, 11 Mar 2024 17:46:40 -0400 Subject: [PATCH 2/8] Inherit documentation changes from formatters --- man/listing_methods.Rd | 24 ++++++------- man/listings.Rd | 6 ++-- man/make_row_df-listing_df-method.Rd | 19 +++++------ man/matrix_form-listing_df-method.Rd | 11 ++---- man/paginate.Rd | 51 ++++++++++++---------------- 5 files changed, 47 insertions(+), 64 deletions(-) diff --git a/man/listing_methods.Rd b/man/listing_methods.Rd index 2dced068..4ec7ddad 100644 --- a/man/listing_methods.Rd +++ b/man/listing_methods.Rd @@ -43,20 +43,16 @@ \arguments{ \item{x}{(\code{listing_df})\cr the listing.} -\item{widths}{numeric (or \code{NULL}). (proposed) widths for the columns -of \code{x}. The expected length of this numeric vector can be -retrieved with \code{ncol() + 1} as the column of row names must -also be considered.} - -\item{tf_wrap}{logical(1). Should the texts for title, subtitle, -and footnotes be wrapped?} - -\item{max_width}{integer(1), character(1) or \code{NULL}. Width that title -and footer (including footnotes) materials should be -word-wrapped to. If \code{NULL}, it is set to the current print width -of the session (\code{getOption("width")}). If set to \code{"auto"}, -the width of the table (plus any table inset) is used. Ignored -completely if \code{tf_wrap} is \code{FALSE}.} +\item{widths}{(\code{numeric} or \code{NULL})\cr Proposed widths for the columns of \code{x}. The expected +length of this numeric vector can be retrieved with \code{ncol(x) + 1} as the column of row names +must also be considered.} + +\item{tf_wrap}{(\code{logical(1)})\cr whether the text for title, subtitles, and footnotes should be wrapped.} + +\item{max_width}{(\code{integer(1)}, \code{character(1)} or \code{NULL})\cr width that title and footer (including +footnotes) materials should be word-wrapped to. If \code{NULL}, it is set to the current print width of the +session (\code{getOption("width")}). If set to \code{"auto"}, the width of the table (plus any table inset) is +used. Parameter is ignored if \code{tf_wrap = FALSE}.} \item{...}{additional parameters passed to \code{\link[formatters:tostring]{formatters::toString()}}.} diff --git a/man/listings.Rd b/man/listings.Rd index b5f64e7a..fd0c5fa0 100644 --- a/man/listings.Rd +++ b/man/listings.Rd @@ -98,11 +98,11 @@ displayed when the listing is rendered.} returns the vector for a new column, which is added to \code{df} as \code{name}, or \code{NULL} if marking an existing column as a listing column.} -\item{format}{character(1) or function. A format label (string) or \code{formatter} function.} +\item{format}{(\code{character(1)} or \code{function})\cr a format label (string) or formatter function.} -\item{na_str}{character(1). String that should be displayed in place of missing values.} +\item{na_str}{(\code{character(1)})\cr string that should be displayed in place of missing values.} -\item{align}{character(1). Alignment values should be rendered with.} +\item{align}{(\code{character(1)})\cr alignment values should be rendered with.} } \value{ a \code{listing_df} object, sorted by its key columns. diff --git a/man/make_row_df-listing_df-method.Rd b/man/make_row_df-listing_df-method.Rd index d2f0b0ae..821d695a 100644 --- a/man/make_row_df-listing_df-method.Rd +++ b/man/make_row_df-listing_df-method.Rd @@ -21,27 +21,26 @@ \arguments{ \item{tt}{(\code{listing_df})\cr the listing to be rendered.} -\item{colwidths}{numeric. Internal detail do not set manually.} +\item{colwidths}{(\code{numeric})\cr internal detail, do not set manually.} \item{visible_only}{(\code{logical(1)})\cr ignored, as listings do not have non-visible structural elements.} -\item{rownum}{numeric(1). Internal detail do not set manually.} +\item{rownum}{(\code{numeric(1)})\cr internal detail, do not set manually.} -\item{indent}{integer(1). Internal detail do not set manually.} +\item{indent}{(\code{integer(1)})\cr internal detail, do not set manually.} -\item{path}{character. Path to the (sub)table represented by -\code{tt}. Defaults to \code{character()}} +\item{path}{(\code{character})\cr path to the (sub)table represented by \code{tt}. Defaults to \code{character()}.} -\item{incontent}{logical(1). Internal detail do not set manually.} +\item{incontent}{(\code{logical(1)})\cr internal detail, do not set manually.} -\item{repr_ext}{integer(1). Internal detail do not set manually.} +\item{repr_ext}{(\code{integer(1)})\cr internal detail, do not set manually.} -\item{repr_inds}{integer. Internal detail do not set manually.} +\item{repr_inds}{(\code{integer})\cr internal detail, do not set manually.} -\item{sibpos}{integer(1). Internal detail do not set manually.} +\item{sibpos}{(\code{integer(1)})\cr internal detail, do not set manually.} -\item{nsibs}{integer(1). Internal detail do not set manually.} +\item{nsibs}{(\code{integer(1)})\cr internal detail, do not set manually.} } \value{ a \code{data.frame} with pagination information. diff --git a/man/matrix_form-listing_df-method.Rd b/man/matrix_form-listing_df-method.Rd index 0d2208e5..922316b4 100644 --- a/man/matrix_form-listing_df-method.Rd +++ b/man/matrix_form-listing_df-method.Rd @@ -7,7 +7,7 @@ \S4method{matrix_form}{listing_df}(obj, indent_rownames = FALSE, expand_newlines = TRUE) } \arguments{ -\item{obj}{ANY. Object to be transformed into a ready-to-render form (a \code{MatrixPrintForm} object)} +\item{obj}{(\code{any})\cr object to be transformed into a ready-to-render form (a \code{\link[formatters]{MatrixPrintForm}} object).} \item{indent_rownames}{(\code{logical(1)})\cr silently ignored, as listings do not have row names nor indenting structure.} @@ -19,13 +19,8 @@ for debugging reasons.} a \code{\link{MatrixPrintForm}} object. } \description{ -Although \code{rtables} are represented as a tree data structure when outputting the table to ASCII or HTML it is -useful to map the \code{rtable} to an in between state with the formatted cells in a matrix form. -} -\details{ -The strings in the return object are defined as follows: row labels are those determined by \code{summarize_rows} and -cell values are determined using \code{get_formatted_cells}. -(Column labels are calculated using a non-exported internal function. +Although \code{rtable}s are represented as a tree data structure when outputting the table to ASCII or HTML, +it is useful to map the \code{rtable} to an in-between state with the formatted cells in a matrix form. } \examples{ lsting <- as_listing(mtcars) diff --git a/man/paginate.Rd b/man/paginate.Rd index af291130..333b3189 100644 --- a/man/paginate.Rd +++ b/man/paginate.Rd @@ -25,30 +25,27 @@ paginate_listing( \arguments{ \item{lsting}{listing_df. The listing to paginate.} -\item{page_type}{character(1). Name of a page type. See -\code{page_types}. Ignored when \code{pg_width} and \code{pg_height} -are set directly.} +\item{page_type}{(\code{character(1)})\cr name of a page type. See \code{\link[formatters]{page_types}}. Ignored +when \code{pg_width} and \code{pg_height} are set directly.} -\item{font_family}{character(1). Name of a font family. An error -will be thrown if the family named is not monospaced. Defaults -to Courier.} +\item{font_family}{(\code{character(1)})\cr name of a font family. An error will be thrown +if the family named is not monospaced. Defaults to \code{"Courier"}.} -\item{font_size}{numeric(1). Font size, defaults to 12.} +\item{font_size}{(\code{numeric(1)})\cr font size. Defaults to \code{12}.} -\item{lineheight}{numeric(1). Line height, defaults to 1.} +\item{lineheight}{(\code{numeric(1)})\cr line height. Defaults to \code{1}.} -\item{landscape}{logical(1). Should the dimensions of \code{page_type} -be inverted for landscape? Defaults to \code{FALSE}, ignored when -\code{pg_width} and \code{pg_height} are set directly.} +\item{landscape}{(\code{logical(1)})\cr whether the dimensions of \code{page_type} should be +inverted for landscape orientation. Defaults to \code{FALSE}, ignored when \code{pg_width} and +\code{pg_height} are set directly.} -\item{pg_width}{numeric(1). Page width in inches.} +\item{pg_width}{(\code{numeric(1)})\cr page width in inches.} -\item{pg_height}{numeric(1). Page height in inches.} +\item{pg_height}{(\code{numeric(1)})\cr page height in inches.} -\item{margins}{numeric(4). Named numeric vector containing \code{'bottom'}, -\code{'left'}, \code{'top'}, and \code{'right'} margins in inches. Defaults -to \code{.5} inches for both vertical margins and \code{.75} for both -horizontal margins.} +\item{margins}{(\code{numeric(4)})\cr named numeric vector containing \code{"bottom"}, \code{"left"}, +\code{"top"}, and \code{"right"} margins in inches. Defaults to \code{.5} inches for both vertical +margins and \code{.75} for both horizontal margins.} \item{lpp}{numeric(1) or NULL. Number of row lines (not counting titles and footers) to have per page. Standard is \code{70} while \code{NULL} disables vertical @@ -58,21 +55,17 @@ pagination.} horizontal pagination. \code{NULL} (the default) indicates no horizontal pagination should be done.} -\item{colwidths}{numeric vector. Column widths (in characters) for -use with vertical pagination.} +\item{colwidths}{(\code{numeric})\cr vector of column widths (in characters) for use in vertical pagination.} -\item{tf_wrap}{logical(1). Should the texts for title, subtitle, -and footnotes be wrapped?} +\item{tf_wrap}{(\code{logical(1)})\cr whether the text for title, subtitles, and footnotes should be wrapped.} -\item{max_width}{integer(1), character(1) or \code{NULL}. Width that title -and footer (including footnotes) materials should be -word-wrapped to. If \code{NULL}, it is set to the current print width -of the session (\code{getOption("width")}). If set to \code{"auto"}, -the width of the table (plus any table inset) is used. Ignored -completely if \code{tf_wrap} is \code{FALSE}.} +\item{max_width}{(\code{integer(1)}, \code{character(1)} or \code{NULL})\cr width that title and footer (including +footnotes) materials should be word-wrapped to. If \code{NULL}, it is set to the current print width of the +session (\code{getOption("width")}). If set to \code{"auto"}, the width of the table (plus any table inset) is +used. Parameter is ignored if \code{tf_wrap = FALSE}.} -\item{verbose}{logical(1). Should additional informative messages about the search for -pagination breaks be shown. Defaults to \code{FALSE}.} +\item{verbose}{(\code{logical(1)})\cr whether additional informative messages about the search for +pagination breaks should be shown. Defaults to \code{FALSE}.} } \value{ A list of listings' objects that are meant to be on separated pages. From 35d8620db019c196b3bbe377db162338b684c265 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Wed, 20 Mar 2024 19:24:07 -0400 Subject: [PATCH 3/8] Clean up --- R/rlistings_methods.R | 8 ++++---- man/listing_methods.Rd | 4 ++-- man/matrix_form-listing_df-method.Rd | 2 +- man/vec_nlines.Rd | 2 +- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/R/rlistings_methods.R b/R/rlistings_methods.R index b80431af..3bfd79c8 100644 --- a/R/rlistings_methods.R +++ b/R/rlistings_methods.R @@ -68,7 +68,7 @@ format_colvector <- function(df, colnm, colvec = df[[colnm]]) { #' For `vec_nlines`, calculate the number of lines each element of a column vector will #' take to render. For `format_colvector`, #' -#' @param vec (`any`)\cr a column vector to be rendered into ASCII. +#' @param vec (`ANY`)\cr a column vector to be rendered into ASCII. #' @param max_width (`numeric(1)` or `NULL`)\cr the width to render the column with. #' @return (`numeric`)\cr a vector of the number of lines element-wise that will be #' needed to render the elements of `vec` to width `max_width`. @@ -77,7 +77,7 @@ format_colvector <- function(df, colnm, colvec = df[[colnm]]) { setGeneric("vec_nlines", function(vec, max_width = NULL) standardGeneric("vec_nlines")) #' @rdname vec_nlines -#' @param vec (`any`)\cr a vector. +#' @param vec (`ANY`)\cr a vector. #' @keywords internal setMethod("vec_nlines", "ANY", function(vec, max_width = NULL) { if (is.null(max_width)) { @@ -221,8 +221,8 @@ setMethod( #' @inheritParams base::Extract #' @param x (`listing_df`)\cr the listing. -#' @param i (`any`)\cr object passed to base `[` methods. -#' @param j (`any`)\cr object passed to base `[` methods. +#' @param i (`ANY`)\cr object passed to base `[` methods. +#' @param j (`ANY`)\cr object passed to base `[` methods. #' #' @export #' @aliases [,listing_df-method diff --git a/man/listing_methods.Rd b/man/listing_methods.Rd index 4ec7ddad..de714a95 100644 --- a/man/listing_methods.Rd +++ b/man/listing_methods.Rd @@ -56,9 +56,9 @@ used. Parameter is ignored if \code{tf_wrap = FALSE}.} \item{...}{additional parameters passed to \code{\link[formatters:tostring]{formatters::toString()}}.} -\item{i}{(\code{any})\cr object passed to base \code{[} methods.} +\item{i}{(\code{ANY})\cr object passed to base \code{[} methods.} -\item{j}{(\code{any})\cr object passed to base \code{[} methods.} +\item{j}{(\code{ANY})\cr object passed to base \code{[} methods.} \item{drop}{For matrices and arrays. If \code{TRUE} the result is coerced to the lowest possible dimension (see the examples). This diff --git a/man/matrix_form-listing_df-method.Rd b/man/matrix_form-listing_df-method.Rd index 922316b4..eae4c7d2 100644 --- a/man/matrix_form-listing_df-method.Rd +++ b/man/matrix_form-listing_df-method.Rd @@ -7,7 +7,7 @@ \S4method{matrix_form}{listing_df}(obj, indent_rownames = FALSE, expand_newlines = TRUE) } \arguments{ -\item{obj}{(\code{any})\cr object to be transformed into a ready-to-render form (a \code{\link[formatters]{MatrixPrintForm}} object).} +\item{obj}{(\code{ANY})\cr object to be transformed into a ready-to-render form (a \code{\link[formatters]{MatrixPrintForm}} object).} \item{indent_rownames}{(\code{logical(1)})\cr silently ignored, as listings do not have row names nor indenting structure.} diff --git a/man/vec_nlines.Rd b/man/vec_nlines.Rd index 1e36d59f..85b2a651 100644 --- a/man/vec_nlines.Rd +++ b/man/vec_nlines.Rd @@ -19,7 +19,7 @@ vec_nlines(vec, max_width = NULL) \item{colvec}{Column values based on colnm} -\item{vec}{(\code{any})\cr a vector.} +\item{vec}{(\code{ANY})\cr a vector.} \item{max_width}{(\code{numeric(1)} or \code{NULL})\cr the width to render the column with.} } From f2541f10507af9867deecf23921ef5a651f7f750 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Wed, 20 Mar 2024 19:32:23 -0400 Subject: [PATCH 4/8] Update WORDLIST --- inst/WORDLIST | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/inst/WORDLIST b/inst/WORDLIST index b1ce3613..81396b84 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -2,6 +2,7 @@ ADAE Biomarker Cheatsheet Forkers +Getter Hoffmann README Repo @@ -14,8 +15,8 @@ customizations de df droppage +formatter funder -getter pagesize pre repo From 34196a4e23905d681d8ff9af17216ea64d5f65b0 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Fri, 22 Mar 2024 14:25:02 -0400 Subject: [PATCH 5/8] Additional clean up --- R/paginate_listing.R | 28 +++++++++------------------- R/rlistings_methods.R | 16 +++++++++------- inst/WORDLIST | 1 - man/listing_methods.Rd | 6 +++--- man/paginate.Rd | 25 ++++++++----------------- man/vec_nlines.Rd | 6 +++--- 6 files changed, 32 insertions(+), 50 deletions(-) diff --git a/R/paginate_listing.R b/R/paginate_listing.R index f7ca6406..7a4b4f8e 100644 --- a/R/paginate_listing.R +++ b/R/paginate_listing.R @@ -3,31 +3,24 @@ #' @description `r lifecycle::badge("experimental")` #' #' Pagination of a listing. This can be vertical for long listings with many -#' rows or horizontal if there are many columns. +#' rows and/or horizontal if there are many columns. #' -#' @param lsting listing_df. The listing to paginate. -#' @param lpp numeric(1) or NULL. Number of row lines (not counting titles and -#' footers) to have per page. Standard is `70` while `NULL` disables vertical -#' pagination. -#' @param cpp numeric(1) or NULL. Width (in characters) of the pages for -#' horizontal pagination. `NULL` (the default) indicates no horizontal -#' pagination should be done. #' @inheritParams formatters::pag_indices_inner #' @inheritParams formatters::vert_pag_indices #' @inheritParams formatters::page_lcpp #' @inheritParams formatters::toString +#' @param lsting (`listing_df`)\cr the listing to paginate. +#' @param lpp (`numeric(1)` or `NULL`)\cr number of rows/lines (excluding titles and footers) +#' to include per page. Standard is `70` while `NULL` disables vertical pagination. +#' @param cpp (`numeric(1)` or `NULL`)\cr width (in characters) of the pages for horizontal +#' pagination. `NULL` (the default) indicates no horizontal pagination should be done. #' -#' @returns A list of listings' objects that are meant to be on separated pages. -#' For `pag_tt_indices` a list of paginated-groups of row-indices of `lsting`. -#' -#' @rdname paginate +#' @return A list of `listing_df` objects where each list element corresponds to a separate page. #' #' @examples #' dat <- ex_adae #' lsting <- as_listing(dat[1:25, ], disp_cols = c("USUBJID", "AESOC", "RACE", "AETOXGR", "BMRKR1")) -#' #' mat <- matrix_form(lsting) -#' #' cat(toString(mat)) #' #' paginate_listing(lsting, lpp = 10) @@ -35,12 +28,9 @@ #' paginate_listing(lsting, cpp = 100, lpp = 40) #' #' paginate_listing(lsting, cpp = 80, lpp = 40, verbose = TRUE) -#' @export #' -#' @return for `paginate_listing` a list containing separate -#' `listing_df` objects for each page, for `pag_listing_indices`, -#' a list of indices in the direction being paginated corresponding -#' to the individual pages in that dimension. +#' @export +#' @rdname paginate paginate_listing <- function(lsting, page_type = "letter", font_family = "Courier", diff --git a/R/rlistings_methods.R b/R/rlistings_methods.R index 3bfd79c8..ebd8f37e 100644 --- a/R/rlistings_methods.R +++ b/R/rlistings_methods.R @@ -46,10 +46,11 @@ basic_run_lens <- function(x) { } #' @param df (`listing_df`)\cr the listing. -#' @param colnm Column name -#' @param colvec Column values based on colnm +#' @param colnm (`character(1)`)\cr column name. +#' @param colvec (`vector`)\cr column values based on `colnm`. #' #' @rdname vec_nlines +#' @keywords internal format_colvector <- function(df, colnm, colvec = df[[colnm]]) { if (missing(colvec) && !(colnm %in% names(df))) { stop("column ", colnm, " not found") @@ -68,7 +69,7 @@ format_colvector <- function(df, colnm, colvec = df[[colnm]]) { #' For `vec_nlines`, calculate the number of lines each element of a column vector will #' take to render. For `format_colvector`, #' -#' @param vec (`ANY`)\cr a column vector to be rendered into ASCII. +#' @param vec (`vector`)\cr a column vector to be rendered into ASCII. #' @param max_width (`numeric(1)` or `NULL`)\cr the width to render the column with. #' @return (`numeric`)\cr a vector of the number of lines element-wise that will be #' needed to render the elements of `vec` to width `max_width`. @@ -76,8 +77,9 @@ format_colvector <- function(df, colnm, colvec = df[[colnm]]) { #' @keywords internal setGeneric("vec_nlines", function(vec, max_width = NULL) standardGeneric("vec_nlines")) +#' @param vec (`vector`)\cr a vector. +#' #' @rdname vec_nlines -#' @param vec (`ANY`)\cr a vector. #' @keywords internal setMethod("vec_nlines", "ANY", function(vec, max_width = NULL) { if (is.null(max_width)) { @@ -221,8 +223,8 @@ setMethod( #' @inheritParams base::Extract #' @param x (`listing_df`)\cr the listing. -#' @param i (`ANY`)\cr object passed to base `[` methods. -#' @param j (`ANY`)\cr object passed to base `[` methods. +#' @param i (`any`)\cr object passed to base `[` methods. +#' @param j (`any`)\cr object passed to base `[` methods. #' #' @export #' @aliases [,listing_df-method @@ -244,7 +246,7 @@ setMethod( #' @param obj (`listing_df`)\cr the listing. #' #' @return -#' * Getter methods return the value of the aspect of `obj`. +#' * Accessor methods return the value of the aspect of `obj`. #' * Setter methods return `obj` with the relevant element of the listing updated. #' #' @examples diff --git a/inst/WORDLIST b/inst/WORDLIST index 81396b84..ece60666 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -2,7 +2,6 @@ ADAE Biomarker Cheatsheet Forkers -Getter Hoffmann README Repo diff --git a/man/listing_methods.Rd b/man/listing_methods.Rd index de714a95..9ee2f3ea 100644 --- a/man/listing_methods.Rd +++ b/man/listing_methods.Rd @@ -56,9 +56,9 @@ used. Parameter is ignored if \code{tf_wrap = FALSE}.} \item{...}{additional parameters passed to \code{\link[formatters:tostring]{formatters::toString()}}.} -\item{i}{(\code{ANY})\cr object passed to base \code{[} methods.} +\item{i}{(\code{any})\cr object passed to base \code{[} methods.} -\item{j}{(\code{ANY})\cr object passed to base \code{[} methods.} +\item{j}{(\code{any})\cr object passed to base \code{[} methods.} \item{drop}{For matrices and arrays. If \code{TRUE} the result is coerced to the lowest possible dimension (see the examples). This @@ -73,7 +73,7 @@ used. Parameter is ignored if \code{tf_wrap = FALSE}.} } \value{ \itemize{ -\item Getter methods return the value of the aspect of \code{obj}. +\item Accessor methods return the value of the aspect of \code{obj}. \item Setter methods return \code{obj} with the relevant element of the listing updated. } } diff --git a/man/paginate.Rd b/man/paginate.Rd index 333b3189..1cccf557 100644 --- a/man/paginate.Rd +++ b/man/paginate.Rd @@ -23,7 +23,7 @@ paginate_listing( ) } \arguments{ -\item{lsting}{listing_df. The listing to paginate.} +\item{lsting}{(\code{listing_df})\cr the listing to paginate.} \item{page_type}{(\code{character(1)})\cr name of a page type. See \code{\link[formatters]{page_types}}. Ignored when \code{pg_width} and \code{pg_height} are set directly.} @@ -47,13 +47,11 @@ inverted for landscape orientation. Defaults to \code{FALSE}, ignored when \code \code{"top"}, and \code{"right"} margins in inches. Defaults to \code{.5} inches for both vertical margins and \code{.75} for both horizontal margins.} -\item{lpp}{numeric(1) or NULL. Number of row lines (not counting titles and -footers) to have per page. Standard is \code{70} while \code{NULL} disables vertical -pagination.} +\item{lpp}{(\code{numeric(1)} or \code{NULL})\cr number of rows/lines (excluding titles and footers) +to include per page. Standard is \code{70} while \code{NULL} disables vertical pagination.} -\item{cpp}{numeric(1) or NULL. Width (in characters) of the pages for -horizontal pagination. \code{NULL} (the default) indicates no horizontal -pagination should be done.} +\item{cpp}{(\code{numeric(1)} or \code{NULL})\cr width (in characters) of the pages for horizontal +pagination. \code{NULL} (the default) indicates no horizontal pagination should be done.} \item{colwidths}{(\code{numeric})\cr vector of column widths (in characters) for use in vertical pagination.} @@ -68,26 +66,18 @@ used. Parameter is ignored if \code{tf_wrap = FALSE}.} pagination breaks should be shown. Defaults to \code{FALSE}.} } \value{ -A list of listings' objects that are meant to be on separated pages. -For \code{pag_tt_indices} a list of paginated-groups of row-indices of \code{lsting}. - -for \code{paginate_listing} a list containing separate -\code{listing_df} objects for each page, for \code{pag_listing_indices}, -a list of indices in the direction being paginated corresponding -to the individual pages in that dimension. +A list of \code{listing_df} objects where each list element corresponds to a separate page. } \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} Pagination of a listing. This can be vertical for long listings with many -rows or horizontal if there are many columns. +rows and/or horizontal if there are many columns. } \examples{ dat <- ex_adae lsting <- as_listing(dat[1:25, ], disp_cols = c("USUBJID", "AESOC", "RACE", "AETOXGR", "BMRKR1")) - mat <- matrix_form(lsting) - cat(toString(mat)) paginate_listing(lsting, lpp = 10) @@ -95,4 +85,5 @@ paginate_listing(lsting, lpp = 10) paginate_listing(lsting, cpp = 100, lpp = 40) paginate_listing(lsting, cpp = 80, lpp = 40, verbose = TRUE) + } diff --git a/man/vec_nlines.Rd b/man/vec_nlines.Rd index 85b2a651..482d27a2 100644 --- a/man/vec_nlines.Rd +++ b/man/vec_nlines.Rd @@ -15,11 +15,11 @@ vec_nlines(vec, max_width = NULL) \arguments{ \item{df}{(\code{listing_df})\cr the listing.} -\item{colnm}{Column name} +\item{colnm}{(\code{character(1)})\cr column name.} -\item{colvec}{Column values based on colnm} +\item{colvec}{(\code{vector})\cr column values based on \code{colnm}.} -\item{vec}{(\code{ANY})\cr a vector.} +\item{vec}{(\code{vector})\cr a vector.} \item{max_width}{(\code{numeric(1)} or \code{NULL})\cr the width to render the column with.} } From 13a11eafb7580311dd8dd95063291ab6887363e1 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Tue, 26 Mar 2024 17:31:25 -0400 Subject: [PATCH 6/8] Inherit changes from formatters --- R/rlistings.R | 14 +++++++------- R/rlistings_methods.R | 4 ++-- man/listing_methods.Rd | 4 ++-- man/listings.Rd | 16 ++++++++-------- man/make_row_df-listing_df-method.Rd | 4 ++-- man/matrix_form-listing_df-method.Rd | 4 ++-- man/paginate.Rd | 12 ++++++------ man/vec_nlines.Rd | 2 +- 8 files changed, 30 insertions(+), 30 deletions(-) diff --git a/R/rlistings.R b/R/rlistings.R index ad16fbe9..681c2a60 100644 --- a/R/rlistings.R +++ b/R/rlistings.R @@ -17,7 +17,7 @@ setOldClass(c("MatrixPrintForm", "list")) #' `non_disp_cols`. #' @param non_disp_cols (`character` or `NULL`)\cr vector of names of non-key columns to be excluded as display #' columns. All other non-key columns are treated as display columns. Ignored if `disp_cols` is non-`NULL`. -#' @param unique_rows (`logical(1)`)\cr whether only unique rows should be included in the listing. Defaults to `FALSE`. +#' @param unique_rows (`flag`)\cr whether only unique rows should be included in the listing. Defaults to `FALSE`. #' @param default_formatting (`list`)\cr a named list of default column format configurations to apply when rendering #' the listing. Each name-value pair consists of a name corresponding to a data class (or "numeric" for all #' unspecified numeric classes) and a value of type `fmt_config` with the format configuration that should be @@ -28,13 +28,13 @@ setOldClass(c("MatrixPrintForm", "list")) #' columns when rendering the listing. Each name-value pair consists of a name corresponding to a column name and a #' value of type `fmt_config` with the formatting configuration that should be implemented for that column. Objects #' of type `fmt_config` can take 3 arguments: `format`, `na_str`, and `align`. Defaults to `NULL`. -#' @param main_title (`character(1)` or `NULL`)\cr the main title for the listing, or +#' @param main_title (`string` or `NULL`)\cr the main title for the listing, or #' `NULL` (the default). #' @param subtitles (`character` or `NULL`)\cr a vector of subtitles for the listing, or `NULL` (the default). #' @param main_footer (`character` or `NULL`)\cr a vector of main footer lines for the listing, or `NULL` (the default). #' @param prov_footer (`character` or `NULL`)\cr a vector of provenance footer lines for the listing, or `NULL` #' (the default). Each string element is placed on a new line. -#' @param vec (`character(1)`)\cr name of a column vector from a `listing_df` object to be annotated as a key column. +#' @param vec (`string`)\cr name of a column vector from a `listing_df` object to be annotated as a key column. #' #' @return a `listing_df` object, sorted by its key columns. #' @@ -253,9 +253,9 @@ get_keycols <- function(df) { } #' @inherit formatters::matrix_form -#' @param indent_rownames (`logical(1)`)\cr silently ignored, as listings do not have row names +#' @param indent_rownames (`flag`)\cr silently ignored, as listings do not have row names #' nor indenting structure. -#' @param expand_newlines (`logical(1)`)\cr this should always be `TRUE` for listings. We keep it +#' @param expand_newlines (`flag`)\cr this should always be `TRUE` for listings. We keep it #' for debugging reasons. #' #' @return a [`MatrixPrintForm`] object. @@ -361,7 +361,7 @@ add_listing_dispcol <- function(df, new) { df } -#' @param value (`character(1)`)\cr new value. +#' @param value (`string`)\cr new value. #' #' @export #' @rdname listings @@ -384,7 +384,7 @@ add_listing_dispcol <- function(df, new) { } #' @inheritParams formatters::fmt_config -#' @param name (`character(1)`)\cr name of the existing or new column to be +#' @param name (`string`)\cr name of the existing or new column to be #' displayed when the listing is rendered. #' @param fun (`function` or `NULL`)\cr a function which accepts `df` and #' returns the vector for a new column, which is added to `df` as diff --git a/R/rlistings_methods.R b/R/rlistings_methods.R index ebd8f37e..52816faf 100644 --- a/R/rlistings_methods.R +++ b/R/rlistings_methods.R @@ -46,7 +46,7 @@ basic_run_lens <- function(x) { } #' @param df (`listing_df`)\cr the listing. -#' @param colnm (`character(1)`)\cr column name. +#' @param colnm (`string`)\cr column name. #' @param colvec (`vector`)\cr column values based on `colnm`. #' #' @rdname vec_nlines @@ -106,7 +106,7 @@ setMethod("vec_nlines", "ANY", function(vec, max_width = NULL) { #' #' @inheritParams formatters::make_row_df #' @param tt (`listing_df`)\cr the listing to be rendered. -#' @param visible_only (`logical(1)`)\cr ignored, as listings do not have +#' @param visible_only (`flag`)\cr ignored, as listings do not have #' non-visible structural elements. #' #' @return a `data.frame` with pagination information. diff --git a/man/listing_methods.Rd b/man/listing_methods.Rd index 9ee2f3ea..1bf99d8f 100644 --- a/man/listing_methods.Rd +++ b/man/listing_methods.Rd @@ -47,9 +47,9 @@ length of this numeric vector can be retrieved with \code{ncol(x) + 1} as the column of row names must also be considered.} -\item{tf_wrap}{(\code{logical(1)})\cr whether the text for title, subtitles, and footnotes should be wrapped.} +\item{tf_wrap}{(\code{flag})\cr whether the text for title, subtitles, and footnotes should be wrapped.} -\item{max_width}{(\code{integer(1)}, \code{character(1)} or \code{NULL})\cr width that title and footer (including +\item{max_width}{(\code{integer(1)}, \code{string} or \code{NULL})\cr width that title and footer (including footnotes) materials should be word-wrapped to. If \code{NULL}, it is set to the current print width of the session (\code{getOption("width")}). If set to \code{"auto"}, the width of the table (plus any table inset) is used. Parameter is ignored if \code{tf_wrap = FALSE}.} diff --git a/man/listings.Rd b/man/listings.Rd index fd0c5fa0..f09ab9b8 100644 --- a/man/listings.Rd +++ b/man/listings.Rd @@ -60,7 +60,7 @@ displayed when the listing is rendered. Defaults to all columns of \code{df} not \item{non_disp_cols}{(\code{character} or \code{NULL})\cr vector of names of non-key columns to be excluded as display columns. All other non-key columns are treated as display columns. Ignored if \code{disp_cols} is non-\code{NULL}.} -\item{unique_rows}{(\code{logical(1)})\cr whether only unique rows should be included in the listing. Defaults to \code{FALSE}.} +\item{unique_rows}{(\code{flag})\cr whether only unique rows should be included in the listing. Defaults to \code{FALSE}.} \item{default_formatting}{(\code{list})\cr a named list of default column format configurations to apply when rendering the listing. Each name-value pair consists of a name corresponding to a data class (or "numeric" for all @@ -74,7 +74,7 @@ columns when rendering the listing. Each name-value pair consists of a name corr value of type \code{fmt_config} with the formatting configuration that should be implemented for that column. Objects of type \code{fmt_config} can take 3 arguments: \code{format}, \code{na_str}, and \code{align}. Defaults to \code{NULL}.} -\item{main_title}{(\code{character(1)} or \code{NULL})\cr the main title for the listing, or +\item{main_title}{(\code{string} or \code{NULL})\cr the main title for the listing, or \code{NULL} (the default).} \item{subtitles}{(\code{character} or \code{NULL})\cr a vector of subtitles for the listing, or \code{NULL} (the default).} @@ -84,25 +84,25 @@ of type \code{fmt_config} can take 3 arguments: \code{format}, \code{na_str}, an \item{prov_footer}{(\code{character} or \code{NULL})\cr a vector of provenance footer lines for the listing, or \code{NULL} (the default). Each string element is placed on a new line.} -\item{vec}{(\code{character(1)})\cr name of a column vector from a \code{listing_df} object to be annotated as a key column.} +\item{vec}{(\code{string})\cr name of a column vector from a \code{listing_df} object to be annotated as a key column.} \item{new}{(\code{character})\cr vector of names of columns to be added to the set of display columns.} -\item{value}{(\code{character(1)})\cr new value.} +\item{value}{(\code{string})\cr new value.} -\item{name}{(\code{character(1)})\cr name of the existing or new column to be +\item{name}{(\code{string})\cr name of the existing or new column to be displayed when the listing is rendered.} \item{fun}{(\code{function} or \code{NULL})\cr a function which accepts \code{df} and returns the vector for a new column, which is added to \code{df} as \code{name}, or \code{NULL} if marking an existing column as a listing column.} -\item{format}{(\code{character(1)} or \code{function})\cr a format label (string) or formatter function.} +\item{format}{(\code{string} or \code{function})\cr a format label (string) or formatter function.} -\item{na_str}{(\code{character(1)})\cr string that should be displayed in place of missing values.} +\item{na_str}{(\code{string})\cr string that should be displayed in place of missing values.} -\item{align}{(\code{character(1)})\cr alignment values should be rendered with.} +\item{align}{(\code{string})\cr alignment values should be rendered with.} } \value{ a \code{listing_df} object, sorted by its key columns. diff --git a/man/make_row_df-listing_df-method.Rd b/man/make_row_df-listing_df-method.Rd index 821d695a..5de8782b 100644 --- a/man/make_row_df-listing_df-method.Rd +++ b/man/make_row_df-listing_df-method.Rd @@ -23,7 +23,7 @@ \item{colwidths}{(\code{numeric})\cr internal detail, do not set manually.} -\item{visible_only}{(\code{logical(1)})\cr ignored, as listings do not have +\item{visible_only}{(\code{flag})\cr ignored, as listings do not have non-visible structural elements.} \item{rownum}{(\code{numeric(1)})\cr internal detail, do not set manually.} @@ -32,7 +32,7 @@ non-visible structural elements.} \item{path}{(\code{character})\cr path to the (sub)table represented by \code{tt}. Defaults to \code{character()}.} -\item{incontent}{(\code{logical(1)})\cr internal detail, do not set manually.} +\item{incontent}{(\code{flag})\cr internal detail, do not set manually.} \item{repr_ext}{(\code{integer(1)})\cr internal detail, do not set manually.} diff --git a/man/matrix_form-listing_df-method.Rd b/man/matrix_form-listing_df-method.Rd index eae4c7d2..010bb658 100644 --- a/man/matrix_form-listing_df-method.Rd +++ b/man/matrix_form-listing_df-method.Rd @@ -9,10 +9,10 @@ \arguments{ \item{obj}{(\code{ANY})\cr object to be transformed into a ready-to-render form (a \code{\link[formatters]{MatrixPrintForm}} object).} -\item{indent_rownames}{(\code{logical(1)})\cr silently ignored, as listings do not have row names +\item{indent_rownames}{(\code{flag})\cr silently ignored, as listings do not have row names nor indenting structure.} -\item{expand_newlines}{(\code{logical(1)})\cr this should always be \code{TRUE} for listings. We keep it +\item{expand_newlines}{(\code{flag})\cr this should always be \code{TRUE} for listings. We keep it for debugging reasons.} } \value{ diff --git a/man/paginate.Rd b/man/paginate.Rd index 1cccf557..94d61497 100644 --- a/man/paginate.Rd +++ b/man/paginate.Rd @@ -25,17 +25,17 @@ paginate_listing( \arguments{ \item{lsting}{(\code{listing_df})\cr the listing to paginate.} -\item{page_type}{(\code{character(1)})\cr name of a page type. See \code{\link[formatters]{page_types}}. Ignored +\item{page_type}{(\code{string})\cr name of a page type. See \code{\link[formatters]{page_types}}. Ignored when \code{pg_width} and \code{pg_height} are set directly.} -\item{font_family}{(\code{character(1)})\cr name of a font family. An error will be thrown +\item{font_family}{(\code{string})\cr name of a font family. An error will be thrown if the family named is not monospaced. Defaults to \code{"Courier"}.} \item{font_size}{(\code{numeric(1)})\cr font size. Defaults to \code{12}.} \item{lineheight}{(\code{numeric(1)})\cr line height. Defaults to \code{1}.} -\item{landscape}{(\code{logical(1)})\cr whether the dimensions of \code{page_type} should be +\item{landscape}{(\code{flag})\cr whether the dimensions of \code{page_type} should be inverted for landscape orientation. Defaults to \code{FALSE}, ignored when \code{pg_width} and \code{pg_height} are set directly.} @@ -55,14 +55,14 @@ pagination. \code{NULL} (the default) indicates no horizontal pagination should \item{colwidths}{(\code{numeric})\cr vector of column widths (in characters) for use in vertical pagination.} -\item{tf_wrap}{(\code{logical(1)})\cr whether the text for title, subtitles, and footnotes should be wrapped.} +\item{tf_wrap}{(\code{flag})\cr whether the text for title, subtitles, and footnotes should be wrapped.} -\item{max_width}{(\code{integer(1)}, \code{character(1)} or \code{NULL})\cr width that title and footer (including +\item{max_width}{(\code{integer(1)}, \code{string} or \code{NULL})\cr width that title and footer (including footnotes) materials should be word-wrapped to. If \code{NULL}, it is set to the current print width of the session (\code{getOption("width")}). If set to \code{"auto"}, the width of the table (plus any table inset) is used. Parameter is ignored if \code{tf_wrap = FALSE}.} -\item{verbose}{(\code{logical(1)})\cr whether additional informative messages about the search for +\item{verbose}{(\code{flag})\cr whether additional informative messages about the search for pagination breaks should be shown. Defaults to \code{FALSE}.} } \value{ diff --git a/man/vec_nlines.Rd b/man/vec_nlines.Rd index 482d27a2..c34c3d7d 100644 --- a/man/vec_nlines.Rd +++ b/man/vec_nlines.Rd @@ -15,7 +15,7 @@ vec_nlines(vec, max_width = NULL) \arguments{ \item{df}{(\code{listing_df})\cr the listing.} -\item{colnm}{(\code{character(1)})\cr column name.} +\item{colnm}{(\code{string})\cr column name.} \item{colvec}{(\code{vector})\cr column values based on \code{colnm}.} From 811ef764468db10c5a6b0bb0a9a7a94cf987c4d9 Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Wed, 3 Apr 2024 10:38:12 -0400 Subject: [PATCH 7/8] Version of formatters --- DESCRIPTION | 2 +- man/listings.Rd | 9 ++++----- man/paginate.Rd | 6 +++--- 3 files changed, 8 insertions(+), 9 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 4e05d704..71e45c23 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -21,7 +21,7 @@ URL: https://insightsengineering.github.io/rlistings/, https://github.com/insightsengineering/rlistings/ BugReports: https://github.com/insightsengineering/rlistings/issues Depends: - formatters (>= 0.5.5.9005), + formatters (>= 0.5.5.9018), methods, tibble (>= 2.0.0) Imports: diff --git a/man/listings.Rd b/man/listings.Rd index c6581857..80b653be 100644 --- a/man/listings.Rd +++ b/man/listings.Rd @@ -75,8 +75,7 @@ columns when rendering the listing. Each name-value pair consists of a name corr value of type \code{fmt_config} with the formatting configuration that should be implemented for that column. Objects of type \code{fmt_config} can take 3 arguments: \code{format}, \code{na_str}, and \code{align}. Defaults to \code{NULL}.} -\item{main_title}{(\code{string} or \code{NULL})\cr the main title for the listing, or -\code{NULL} (the default).} +\item{main_title}{(\code{string} or \code{NULL})\cr the main title for the listing, or \code{NULL} (the default).} \item{subtitles}{(\code{character} or \code{NULL})\cr a vector of subtitles for the listing, or \code{NULL} (the default).} @@ -85,8 +84,8 @@ of type \code{fmt_config} can take 3 arguments: \code{format}, \code{na_str}, an \item{prov_footer}{(\code{character} or \code{NULL})\cr a vector of provenance footer lines for the listing, or \code{NULL} (the default). Each string element is placed on a new line.} -\item{split_into_pages_by_var}{character or NULL. The name of a column for which the -listing should be split into pages, one for each level of the column. Check +\item{split_into_pages_by_var}{(\code{character} or \code{NULL})\cr the name of a variable for on the listing should be split +into pages, with each page corresponding to one unique value/level of the variable. See \code{\link[=split_into_pages_by_var]{split_into_pages_by_var()}} for more details.} \item{vec}{(\code{string})\cr name of a column vector from a \code{listing_df} object to be annotated as a key column.} @@ -110,7 +109,7 @@ returns the vector for a new column, which is added to \code{df} as \item{align}{(\code{string})\cr alignment values should be rendered with.} } \value{ -a \code{listing_df} object, sorted by its key columns. +A \code{listing_df} object, sorted by its key columns. \code{df} with \code{name} created (if necessary) and marked for display during rendering. diff --git a/man/paginate.Rd b/man/paginate.Rd index 15af935d..5b8e2162 100644 --- a/man/paginate.Rd +++ b/man/paginate.Rd @@ -59,8 +59,8 @@ pagination. \code{NULL} (the default) indicates no horizontal pagination should \item{tf_wrap}{(\code{flag})\cr whether the text for title, subtitles, and footnotes should be wrapped.} -\item{rep_cols}{numeric(1). Number of \emph{columns} (not including -row labels) to be repeated on every page. Defaults to 0} +\item{rep_cols}{(\code{numeric(1)})\cr number of \emph{columns} (not including row labels) to be repeated on every page. +Defaults to 0.} \item{max_width}{(\code{integer(1)}, \code{string} or \code{NULL})\cr width that title and footer (including footnotes) materials should be word-wrapped to. If \code{NULL}, it is set to the current print width of the @@ -70,7 +70,7 @@ used. Parameter is ignored if \code{tf_wrap = FALSE}.} \item{verbose}{(\code{flag})\cr whether additional informative messages about the search for pagination breaks should be shown. Defaults to \code{FALSE}.} -\item{print_pages}{(\code{logical(1)})\cr whether to also print the paginated listing to console +\item{print_pages}{(\code{flag})\cr whether the paginated listing should be printed to the console (\code{cat(toString(x))}).} } \value{ From 9371dd12d3e12dac356de75de09688998c8666fd Mon Sep 17 00:00:00 2001 From: Emily de la Rua Date: Wed, 3 Apr 2024 10:58:01 -0400 Subject: [PATCH 8/8] Styler --- R/rlistings.R | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/R/rlistings.R b/R/rlistings.R index 65a2b246..a95ba723 100644 --- a/R/rlistings.R +++ b/R/rlistings.R @@ -33,8 +33,8 @@ setOldClass(c("MatrixPrintForm", "list")) #' @param main_footer (`character` or `NULL`)\cr a vector of main footer lines for the listing, or `NULL` (the default). #' @param prov_footer (`character` or `NULL`)\cr a vector of provenance footer lines for the listing, or `NULL` #' (the default). Each string element is placed on a new line. -#' @param split_into_pages_by_var (`character` or `NULL`)\cr the name of a variable for on the listing should be split -#' into pages, with each page corresponding to one unique value/level of the variable. See +#' @param split_into_pages_by_var (`character` or `NULL`)\cr the name of a variable for on the listing should be split +#' into pages, with each page corresponding to one unique value/level of the variable. See #' [split_into_pages_by_var()] for more details. #' @param vec (`string`)\cr name of a column vector from a `listing_df` object to be annotated as a key column. #'