From f9163e4fdb047b44b4ef49367c729c2f773aebf6 Mon Sep 17 00:00:00 2001 From: olivroy <52606734+olivroy@users.noreply.github.com> Date: Thu, 13 Jul 2023 16:20:44 -0400 Subject: [PATCH] R/write.R cleanup (#683) * Remove `@name` Remove `@title`, `@description Remove `####` Remove \itemize to use md. Move `@export` tag. Document * Place the exported functions on top of the file and document. (i.e. no .Rd change ) * Revert commit --- R/write.R | 95 +++++++++++++++++++++--------------------- man/write_data.Rd | 9 ++-- man/write_datatable.Rd | 3 -- man/write_formula.Rd | 18 ++++---- 4 files changed, 60 insertions(+), 65 deletions(-) diff --git a/R/write.R b/R/write.R index 35492dec5..78496516b 100644 --- a/R/write.R +++ b/R/write.R @@ -654,12 +654,12 @@ write_data2 <- function( return(wb) } - - -#' internal driver function to write_data and write_data_table -#' @name write_datatable -#' @title Write to a worksheet as an Excel table -#' @description Write to a worksheet and format as an Excel table +# `write_data_table()` --------------------------------------------------------- +# `write_data_table()` an internal driver function to `write_data` and `write_data_table` ---- +#' Write to a worksheet as an Excel table +#' +#' Write to a worksheet and format as an Excel table +#' #' @param wb A Workbook object containing a worksheet. #' @param sheet The worksheet to write to. Can be the worksheet index or name. #' @param x A data frame. @@ -685,6 +685,7 @@ write_data2 <- function( #' `na_strings()` uses the special `#N/A` value within the workbook. #' @param inline_strings optional write strings as inline strings #' @noRd +#' @keywords internal write_data_table <- function( wb, sheet, @@ -941,10 +942,15 @@ write_data_table <- function( return(wb) } - -#' @name write_data -#' @title Write an object to a worksheet -#' @description Write an object to worksheet with optional styling. +# `write_data()` --------------------------------------------------------------- +#' Write an object to a worksheet +#' +#' Write an object to worksheet with optional styling. +#' +#' Formulae written using write_formula to a Workbook object will not get picked up by read_xlsx(). +#' This is because only the formula is written and left to Excel to evaluate the formula when the file is opened in Excel. +#' The string `"_openxlsx_NA"` is reserved for `openxlsx2`. If the data frame contains this string, the output will be broken. +#' #' @param wb A Workbook object containing a worksheet. #' @param sheet The worksheet to write to. Can be the worksheet index or name. #' @param x Object to be written. For classes supported look at the examples. @@ -964,14 +970,8 @@ write_data_table <- function( #' @param inline_strings write characters as inline strings #' @param ... additional arguments #' @seealso [write_datatable()] -#' @export write_data -#' @details Formulae written using write_formula to a Workbook object will not get picked up by read_xlsx(). -#' This is because only the formula is written and left to Excel to evaluate the formula when the file is opened in Excel. -#' The string `"_openxlsx_NA"` is reserved for `openxlsx2`. If the data frame contains this string, the output will be broken. -#' @rdname write_data #' @return invisible(0) #' @examples -#' #' ## See formatting vignette for further examples. #' #' ## Options for default styling (These are the defaults) @@ -979,7 +979,7 @@ write_data_table <- function( #' options("openxlsx2.datetimeFormat" = "yyyy-mm-dd hh:mm:ss") #' options("openxlsx2.numFmt" = NULL) #' -#' ##################################################################################### +#' ############################################################################# #' ## Create Workbook object and add worksheets #' wb <- wb_workbook() #' @@ -990,7 +990,7 @@ write_data_table <- function( #' x <- mtcars[1:6, ] #' wb$add_data("Cars", x, startCol = 2, startRow = 3, rowNames = TRUE) #' -#' ##################################################################################### +#' ############################################################################# #' ## Hyperlinks #' ## - vectors/columns with class 'hyperlink' are written as hyperlinks' #' @@ -999,7 +999,7 @@ write_data_table <- function( #' class(v) <- "hyperlink" #' wb$add_data("Cars", x = v, dims = c("B32")) #' -#' ##################################################################################### +#' ############################################################################# #' ## Formulas #' ## - vectors/columns with class 'formula' are written as formulas' #' @@ -1013,7 +1013,7 @@ write_data_table <- function( #' #' wb$add_data(sheet = "Formula", x = df) #' -#' ########################################################################### +#' ############################################################################# #' # update cell range and add mtcars #' xlsxFile <- system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2") #' wb2 <- wb_load(xlsxFile) @@ -1022,6 +1022,7 @@ write_data_table <- function( #' wb_to_df(wb2) #' write_data(wb2, 1, mtcars, startCol = 4, startRow = 4) #' wb_to_df(wb2) +#' @export write_data <- function( wb, sheet, @@ -1071,20 +1072,20 @@ write_data <- function( ) } - -#' @name write_formula -#' @title Write a character vector as an Excel Formula -#' @description Write a a character vector containing Excel formula to a worksheet. -#' @details Currently only the English version of functions are supported. Please don't use the local translation. +# write_formula() ------------------------------------------- +#' Write a character vector as an Excel Formula +#' +#' Write a a character vector containing Excel formula to a worksheet. +#' +#' @details +#' Currently only the English version of functions are supported. Please don't use the local translation. #' The examples below show a small list of possible formulas: -#' \itemize{ -#' \item{SUM(B2:B4)} -#' \item{AVERAGE(B2:B4)} -#' \item{MIN(B2:B4)} -#' \item{MAX(B2:B4)} -#' \item{...} +#' * SUM(B2:B4) +#' * AVERAGE(B2:B4) +#' * MIN(B2:B4) +#' * MAX(B2:B4) +#' * ... #' -#' } #' @param wb A Workbook object containing a worksheet. #' @param sheet The worksheet to write to. Can be the worksheet index or name. #' @param x A character vector. @@ -1097,17 +1098,14 @@ write_data <- function( #' @param remove_cell_style if writing into existing cells, should the cell style be removed? #' @param ... additional arguments #' @seealso [write_data()] -#' @export write_formula -#' @rdname write_formula #' @examples -#' #' ## There are 3 ways to write a formula #' #' wb <- wb_workbook() #' wb$add_worksheet("Sheet 1") #' wb$add_data("Sheet 1", x = iris) #' -#' ## SEE int2col() to convert int to Excel column label +#' ## SEE `int2col()` to convert int to Excel column label #' #' ## 1. - As a character vector using write_formula #' @@ -1133,7 +1131,6 @@ write_data <- function( #' wb$add_data(sheet = 2, x = df) #' #' -#' #' ## 3. - As a vector with class "formula" using write_data #' #' v2 <- c("SUM(A2:A4)", "AVERAGE(B2:B4)", "MEDIAN(C2:C4)") @@ -1141,6 +1138,7 @@ write_data <- function( #' #' wb$add_data(sheet = 2, x = v2, startCol = 10, startRow = 2) #' +#' #' ## 4. - Writing internal hyperlinks #' #' wb <- wb_workbook() @@ -1148,6 +1146,7 @@ write_data <- function( #' wb$add_worksheet("Sheet2") #' write_formula(wb, "Sheet1", x = '=HYPERLINK("#Sheet2!B3", "Text to Display - Link to Sheet2")') #' +#' #' ## 5. - Writing array formulas #' #' set.seed(123) @@ -1161,7 +1160,7 @@ write_data <- function( #' write_formula(wb, "df", startCol = "E", startRow = "2", #' x = "SUM(C2:C11*D2:D11)", #' array = TRUE) -#' +#' @export write_formula <- function( wb, sheet, @@ -1262,10 +1261,11 @@ write_formula <- function( } - -#' @name write_datatable -#' @title Write to a worksheet as an Excel table -#' @description Write to a worksheet and format as an Excel table +# `write_datatable()` ---------------------- +#' Write to a worksheet as an Excel table +#' +#' Write to a worksheet and format as an Excel table +#' #' @param wb A Workbook object containing a worksheet. #' @param sheet The worksheet to write to. Can be the worksheet index or name. #' @param x A data frame. @@ -1299,11 +1299,11 @@ write_formula <- function( #' hyperlinks, percentages respectively. #' The string `"_openxlsx_NA"` is reserved for `openxlsx2`. If the data frame #' contains this string, the output will be broken. -#' @seealso [wb_add_worksheet()] -#' @seealso [write_data()] -#' @seealso [wb_remove_tables()] -#' @seealso [wb_get_tables()] -#' @export +#' @seealso +#' [wb_add_worksheet()] +#' [write_data()] +#' [wb_remove_tables()] +#' [wb_get_tables()] #' @examples #' ## see package vignettes for further examples. #' @@ -1386,6 +1386,7 @@ write_formula <- function( #' tableStyle = style, startRow = 7, startCol = i * 3 - 2 #' ) #' } +#' @export write_datatable <- function( wb, sheet, diff --git a/man/write_data.Rd b/man/write_data.Rd index 24f9ca7ce..803d02c00 100644 --- a/man/write_data.Rd +++ b/man/write_data.Rd @@ -102,7 +102,6 @@ This is because only the formula is written and left to Excel to evaluate the fo The string \code{"_openxlsx_NA"} is reserved for \code{openxlsx2}. If the data frame contains this string, the output will be broken. } \examples{ - ## See formatting vignette for further examples. ## Options for default styling (These are the defaults) @@ -110,7 +109,7 @@ options("openxlsx2.dateFormat" = "mm/dd/yyyy") options("openxlsx2.datetimeFormat" = "yyyy-mm-dd hh:mm:ss") options("openxlsx2.numFmt" = NULL) -##################################################################################### +############################################################################# ## Create Workbook object and add worksheets wb <- wb_workbook() @@ -121,7 +120,7 @@ wb$add_worksheet("Formula") x <- mtcars[1:6, ] wb$add_data("Cars", x, startCol = 2, startRow = 3, rowNames = TRUE) -##################################################################################### +############################################################################# ## Hyperlinks ## - vectors/columns with class 'hyperlink' are written as hyperlinks' @@ -130,7 +129,7 @@ names(v) <- paste0("Hyperlink", 1:4) # Optional: names will be used as display t class(v) <- "hyperlink" wb$add_data("Cars", x = v, dims = c("B32")) -##################################################################################### +############################################################################# ## Formulas ## - vectors/columns with class 'formula' are written as formulas' @@ -144,7 +143,7 @@ class(df$z) <- c(class(df$z), "formula") wb$add_data(sheet = "Formula", x = df) -########################################################################### +############################################################################# # update cell range and add mtcars xlsxFile <- system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2") wb2 <- wb_load(xlsxFile) diff --git a/man/write_datatable.Rd b/man/write_datatable.Rd index 89d164be8..024ef7211 100644 --- a/man/write_datatable.Rd +++ b/man/write_datatable.Rd @@ -172,10 +172,7 @@ for (i in 1:11) { } \seealso{ \code{\link[=wb_add_worksheet]{wb_add_worksheet()}} - \code{\link[=write_data]{write_data()}} - \code{\link[=wb_remove_tables]{wb_remove_tables()}} - \code{\link[=wb_get_tables]{wb_get_tables()}} } diff --git a/man/write_formula.Rd b/man/write_formula.Rd index 23c78236c..6167e10eb 100644 --- a/man/write_formula.Rd +++ b/man/write_formula.Rd @@ -48,23 +48,21 @@ Write a a character vector containing Excel formula to a worksheet. Currently only the English version of functions are supported. Please don't use the local translation. The examples below show a small list of possible formulas: \itemize{ -\item{SUM(B2:B4)} -\item{AVERAGE(B2:B4)} -\item{MIN(B2:B4)} -\item{MAX(B2:B4)} -\item{...} - +\item SUM(B2:B4) +\item AVERAGE(B2:B4) +\item MIN(B2:B4) +\item MAX(B2:B4) +\item ... } } \examples{ - ## There are 3 ways to write a formula wb <- wb_workbook() wb$add_worksheet("Sheet 1") wb$add_data("Sheet 1", x = iris) -## SEE int2col() to convert int to Excel column label +## SEE `int2col()` to convert int to Excel column label ## 1. - As a character vector using write_formula @@ -90,7 +88,6 @@ wb$add_worksheet("Sheet 2") wb$add_data(sheet = 2, x = df) - ## 3. - As a vector with class "formula" using write_data v2 <- c("SUM(A2:A4)", "AVERAGE(B2:B4)", "MEDIAN(C2:C4)") @@ -98,6 +95,7 @@ class(v2) <- c(class(v2), "formula") wb$add_data(sheet = 2, x = v2, startCol = 10, startRow = 2) + ## 4. - Writing internal hyperlinks wb <- wb_workbook() @@ -105,6 +103,7 @@ wb$add_worksheet("Sheet1") wb$add_worksheet("Sheet2") write_formula(wb, "Sheet1", x = '=HYPERLINK("#Sheet2!B3", "Text to Display - Link to Sheet2")') + ## 5. - Writing array formulas set.seed(123) @@ -118,7 +117,6 @@ wb$add_data("df", df, startCol = "C") write_formula(wb, "df", startCol = "E", startRow = "2", x = "SUM(C2:C11*D2:D11)", array = TRUE) - } \seealso{ \code{\link[=write_data]{write_data()}}