From bc0a28246d9005036cc9ae545aa6910aa5f96a4f Mon Sep 17 00:00:00 2001 From: olivroy <52606734+olivroy@users.noreply.github.com> Date: Fri, 28 Jun 2024 11:51:31 -0400 Subject: [PATCH] Deprecate old functions `write_*()` and `remove_*()` (#1064) * Deprecate `remove_comment()` `write_comment()`, `write_formula()`, `write_data()`, `write_datatable()`, `convertToExcelDate()` * Update tests/testthat/test-wb_functions.R * Move functions to deprecate file. * Apply suggestions from code review --- NEWS.md | 3 + R/class-comment.R | 28 +-- R/class-workbook.R | 10 +- R/dates.R | 12 -- R/deprecate.R | 226 ++++++++++++++++++++++++ R/write.R | 41 +---- R/write_xlsx.R | 4 +- man/comment_internal.Rd | 156 ++++++++--------- man/convertToExcelDate.Rd | 28 +-- man/convert_date.Rd | 3 +- man/write_data.Rd | 2 +- man/write_datatable.Rd | 240 +++++++++++++------------- man/write_formula.Rd | 6 +- tests/testthat/test-class-comment.R | 10 +- tests/testthat/test-save.R | 2 +- tests/testthat/test-wb_functions.R | 2 +- tests/testthat/test-write.R | 10 +- tests/testthat/test-writing_posixct.R | 2 +- 18 files changed, 477 insertions(+), 308 deletions(-) create mode 100644 R/deprecate.R diff --git a/NEWS.md b/NEWS.md index 1108fc89f..5144b61d9 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,8 @@ # openxlsx2 (development version) +* Legacy `write_data()`, `write_datatable()`, `write_formula()`, `write_comment()` are now deprecated in favour of `wb_add_data()`, `wb_add_data_table()`, `wb_add_formula()`, and `wb_add_comment()`. + +* `convertToExcelDate()` is defunct and will be removed in a future version of the package. Use `convert_to_excel_date()`. *************************************************************************** diff --git a/R/class-comment.R b/R/class-comment.R index c79fb8614..fda4955d4 100644 --- a/R/class-comment.R +++ b/R/class-comment.R @@ -187,24 +187,7 @@ create_comment <- function(text, wb_comment(text = text, author = author, style = style, visible = visible, width = width[1], height = height[1]) } -#' Internal comment functions -#' -#' Users are advised to use [wb_add_comment()] and [wb_remove_comment()]. -#' This function is used internally by openxlsx2. It will stop exporting it at -#' some point in the future. Use the replacement function at your earliest convenience. -#' @name comment_internal -NULL - -#' @rdname comment_internal -#' @inheritParams wb_add_comment -#' @param comment An object created by [create_comment()] -#' @param row,col Row and column of the cell -#' @param color optional background color -#' @param file optional background image (file extension must be png or jpeg) -#' @keywords internal -#' @export -#' @inherit wb_add_comment examples -write_comment <- function( +do_write_comment <- function( wb, sheet, col = NULL, @@ -418,19 +401,14 @@ write_comment <- function( invisible(wb) } -#' @rdname comment_internal -#' @param gridExpand If `TRUE`, all data in rectangle min(rows):max(rows) X min(cols):max(cols) -#' will be removed. -#' @keywords internal -#' @export -remove_comment <- function( +do_remove_comment <- function( wb, sheet, col = NULL, row = NULL, gridExpand = TRUE, dims = NULL - ) { +) { # TODO add as method; wbWorkbook$remove_comment() assert_workbook(wb) diff --git a/R/class-workbook.R b/R/class-workbook.R index 504a826fc..77cfd4883 100644 --- a/R/class-workbook.R +++ b/R/class-workbook.R @@ -1358,7 +1358,7 @@ wbWorkbook <- R6::R6Class( ) } - write_data( + do_write_data( wb = self, sheet = sheet, x = x, @@ -1436,7 +1436,7 @@ wbWorkbook <- R6::R6Class( ) } - write_datatable( + do_write_datatable( wb = self, x = x, sheet = sheet, @@ -2400,7 +2400,7 @@ wbWorkbook <- R6::R6Class( ) { standardize_case_names(...) - write_formula( + do_write_formula( wb = self, sheet = sheet, x = x, @@ -5040,7 +5040,7 @@ wbWorkbook <- R6::R6Class( if (!is.null(color) && !is_wbColour(color)) stop("color needs to be a wb_color()") - write_comment( + do_write_comment( wb = self, sheet = sheet, comment = comment, @@ -5106,7 +5106,7 @@ wbWorkbook <- R6::R6Class( gridExpand <- TRUE } - remove_comment( + do_remove_comment( wb = self, sheet = sheet, col = col, diff --git a/R/dates.R b/R/dates.R index 9e1d7aee3..00f9f8743 100644 --- a/R/dates.R +++ b/R/dates.R @@ -178,18 +178,6 @@ convert_to_excel_date <- function(df, date1904 = FALSE) { df } -#' Convert to Excel data -#' -#' Use [convert_to_excel_date()] in new code -#' @usage NULL -#' @inheritParams convert_to_excel_date -#' @keywords internal -#' @export -convertToExcelDate <- function(df, date1904 = FALSE) { - .Deprecated(old = "convertToExcelDate", new = "convert_to_excel_date", package = "openxlsx2") - convert_to_excel_date(df = df, date1904 = date1904) -} - # `convert_to_excel_date()` helpers ----------------------------------- #' conversion helper function #' @param x a date, posixct or hms object diff --git a/R/deprecate.R b/R/deprecate.R new file mode 100644 index 000000000..a2bd288d1 --- /dev/null +++ b/R/deprecate.R @@ -0,0 +1,226 @@ +#' Internal comment functions +#' +#' Users are advised to use [wb_add_comment()] and [wb_remove_comment()]. +#' `write_comment()` and `remove_comment()` are now deprecated. openxlsx2 will stop +#' exporting it at some point in the future. Use the replacement functions. +#' @name comment_internal +NULL + +#' @rdname comment_internal +#' @inheritParams wb_add_comment +#' @param comment An object created by [create_comment()] +#' @param row,col Row and column of the cell +#' @param color optional background color +#' @param file optional background image (file extension must be png or jpeg) +#' @keywords internal +#' @export +#' @inherit wb_add_comment examples +write_comment <- function( + wb, + sheet, + col = NULL, + row = NULL, + comment, + dims = rowcol_to_dim(row, col), + color = NULL, + file = NULL +) { + .Deprecated("wb_add_comment()", package = "openxlsx2", old = "write_comment()") + do_write_comment( + wb, + sheet, + col, + row, + comment, + dims, + color, + file + ) +} + +#' @rdname comment_internal +#' @param gridExpand If `TRUE`, all data in rectangle min(rows):max(rows) X min(cols):max(cols) +#' will be removed. +#' @keywords internal +#' @export +remove_comment <- function( + wb, + sheet, + col = NULL, + row = NULL, + gridExpand = TRUE, + dims = NULL +) { + .Deprecated("wb_remove_comment()", package = "openxlsx2", old = "remove_comment()") + do_remove_comment( + wb, + sheet, + col, + row, + gridExpand, + dims + ) +} + +#' Convert to Excel data +#' +#' Use [convert_to_excel_date()]. +#' @usage NULL +#' @inheritParams convert_to_excel_date +#' @keywords internal +#' @export +convertToExcelDate <- function(df, date1904 = FALSE) { + stop("convertToExcelDate() is defunct and will be removed in new version. Use convert_to_excel_date().", call. = FALSE) +} + +#' Write an object to a worksheet +#' +#' Use [wb_add_data()] or [write_xlsx()] in new code. +#' +#' @inheritParams wb_add_data +#' @return invisible(0) +#' @export +#' @keywords internal +write_data <- function( + wb, + sheet, + x, + dims = wb_dims(start_row, start_col), + start_col = 1, + start_row = 1, + array = FALSE, + col_names = TRUE, + row_names = FALSE, + with_filter = FALSE, + sep = ", ", + name = NULL, + apply_cell_style = TRUE, + remove_cell_style = FALSE, + na.strings = na_strings(), + inline_strings = TRUE, + enforce = FALSE, + ... +) { + .Deprecated("wb_add_data()", package = "openxlsx2", old = "write_data()") + do_write_data( + wb = wb, + sheet = sheet, + x = x, + dims = dims, + start_col = start_col, + start_row = start_col, + array = array, + col_names = col_names, + row_names = row_names, + with_filter = with_filter, + sep = sep, + name = name, + apply_cell_style = apply_cell_style, + remove_cell_style = remove_cell_style, + na.strings = na.strings, + inline_strings = inline_strings, + enforce = enforce, + ... + ) +} + +#' Write to a worksheet as an Excel table +#' +#' Write to a worksheet and format as an Excel table. Use [wb_add_data_table()] in new code. +#' This function is deprecated and may not be exported in the future. +#' @inheritParams wb_add_data_table +#' @inherit wb_add_data_table details +#' @export +#' @keywords internal +write_datatable <- function( + wb, + sheet, + x, + dims = wb_dims(start_row, start_col), + start_col = 1, + start_row = 1, + col_names = TRUE, + row_names = FALSE, + table_style = "TableStyleLight9", + table_name = NULL, + with_filter = TRUE, + sep = ", ", + first_column = FALSE, + last_column = FALSE, + banded_rows = TRUE, + banded_cols = FALSE, + apply_cell_style = TRUE, + remove_cell_style = FALSE, + na.strings = na_strings(), + inline_strings = TRUE, + total_row = FALSE, + ... +) { + .Deprecated("wb_add_data_table()", package = "openxlsx2", old = "write_datatable()") + do_write_datatable( + wb = wb, + sheet = sheet, + x = x, + dims = dims, + start_col = start_col, + start_row = start_row, + col_names = col_names, + row_names = row_names, + table_style = table_style, + table_name = table_name, + with_filter = with_filter, + sep = sep, + first_column = first_column, + last_column = last_column, + banded_rows = banded_rows, + banded_cols = banded_cols, + apply_cell_style = apply_cell_style, + remove_cell_style = remove_cell_style, + na.strings = na.strings, + inline_strings = inline_strings, + total_row = total_row, + ... + + ) +} + +#' Write a character vector as an Excel Formula +#' +#' Write a a character vector containing Excel formula to a worksheet. +#' Use [wb_add_formula()] or `add_formula()` in new code. This function is +#' deprecated and may be defunct. +#' +#' @inheritParams wb_add_formula +#' @export +#' @keywords internal +write_formula <- function( + wb, + sheet, + x, + dims = wb_dims(start_row, start_col), + start_col = 1, + start_row = 1, + array = FALSE, + cm = FALSE, + apply_cell_style = TRUE, + remove_cell_style = FALSE, + enforce = FALSE, + ... +) { + .Deprecated("wb_add_formula()", package = "openxlsx2", old = "write_formula()") + + do_write_formula( + wb = wb, + sheet = sheet, + x = x, + dims = dims, + start_col = start_col, + start_row = start_row, + array = array, + cm = cm, + apply_cell_style = apply_cell_style, + remove_cell_style = remove_cell_style, + enforce = enforce, + ... + ) +} diff --git a/R/write.R b/R/write.R index bb59cd17b..490dbf878 100644 --- a/R/write.R +++ b/R/write.R @@ -1087,16 +1087,9 @@ write_data_table <- function( return(wb) } -# `write_data()` --------------------------------------------------------------- -#' Write an object to a worksheet -#' -#' Use [wb_add_data()] or [write_xlsx()] in new code. -#' -#' @inheritParams wb_add_data -#' @return invisible(0) -#' @export -#' @keywords internal -write_data <- function( +# `do_write_data()` --------------------------------------------------------------- + +do_write_data <- function( wb, sheet, x, @@ -1147,17 +1140,8 @@ write_data <- function( ) } -# write_formula() ------------------------------------------- -#' Write a character vector as an Excel Formula -#' -#' Write a a character vector containing Excel formula to a worksheet. -#' Use [wb_add_formula()] or `add_formula()` in new code. This function is meant -#' for internal use. -#' -#' @inheritParams wb_add_formula -#' @export -#' @keywords internal -write_formula <- function( +# do_write_formula() ------------------------------------------- +do_write_formula <- function( wb, sheet, x, @@ -1171,7 +1155,6 @@ write_formula <- function( enforce = FALSE, ... ) { - standardize_case_names(...) assert_class(x, "character") @@ -1258,7 +1241,7 @@ write_formula <- function( } } - write_data( + do_write_data( wb = wb, sheet = sheet, x = dfx, @@ -1275,16 +1258,8 @@ write_formula <- function( } -# `write_datatable()` ---------------------- -#' Write to a worksheet as an Excel table -#' -#' Write to a worksheet and format as an Excel table. Use [wb_add_data_table()] in new code. -#' This function may not be exported -#' @inheritParams wb_add_data_table -#' @inherit wb_add_data_table details -#' @export -#' @keywords internal -write_datatable <- function( +# `do_write_datatable()` ---------------------- +do_write_datatable <- function( wb, sheet, x, diff --git a/R/write_xlsx.R b/R/write_xlsx.R index f71c025c0..825da3a61 100644 --- a/R/write_xlsx.R +++ b/R/write_xlsx.R @@ -353,7 +353,7 @@ write_xlsx <- function(x, file, as_table = FALSE, ...) { if (as_table[i]) { # add data table?? - write_datatable( + do_write_datatable( wb = wb, sheet = i, x = x[[i]], @@ -369,7 +369,7 @@ write_xlsx <- function(x, file, as_table = FALSE, ...) { ) } else { # TODO add_data()? - write_data( + do_write_data( wb = wb, sheet = i, x = x[[i]], diff --git a/man/comment_internal.Rd b/man/comment_internal.Rd index 6a767d4e4..316e4a5c8 100644 --- a/man/comment_internal.Rd +++ b/man/comment_internal.Rd @@ -1,78 +1,78 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/class-comment.R -\name{comment_internal} -\alias{comment_internal} -\alias{write_comment} -\alias{remove_comment} -\title{Internal comment functions} -\usage{ -write_comment( - wb, - sheet, - col = NULL, - row = NULL, - comment, - dims = rowcol_to_dim(row, col), - color = NULL, - file = NULL -) - -remove_comment( - wb, - sheet, - col = NULL, - row = NULL, - gridExpand = TRUE, - dims = NULL -) -} -\arguments{ -\item{wb}{A workbook object} - -\item{sheet}{A worksheet of the workbook} - -\item{row, col}{Row and column of the cell} - -\item{comment}{An object created by \code{\link[=create_comment]{create_comment()}}} - -\item{dims}{Optional row and column as spreadsheet dimension, e.g. "A1"} - -\item{color}{optional background color} - -\item{file}{optional background image (file extension must be png or jpeg)} - -\item{gridExpand}{If \code{TRUE}, all data in rectangle min(rows):max(rows) X min(cols):max(cols) -will be removed.} -} -\description{ -Users are advised to use \code{\link[=wb_add_comment]{wb_add_comment()}} and \code{\link[=wb_remove_comment]{wb_remove_comment()}}. -This function is used internally by openxlsx2. It will stop exporting it at -some point in the future. Use the replacement function at your earliest convenience. -} -\examples{ -wb <- wb_workbook() -wb$add_worksheet("Sheet 1") -# add a comment without author -c1 <- wb_comment(text = "this is a comment", author = "") -wb$add_comment(dims = "B10", comment = c1) -#' # Remove comment -wb$remove_comment(sheet = "Sheet 1", dims = "B10") -# Write another comment with author information -c2 <- wb_comment(text = "this is another comment", author = "Marco Polo", visible = TRUE) -wb$add_comment(sheet = 1, dims = "C10", comment = c2) -# Works with formatted text also. -formatted_text <- fmt_txt("bar", underline = TRUE) -wb$add_comment(dims = "B5", comment = formatted_text) -# With background color -wb$add_comment(dims = "B7", comment = formatted_text, color = wb_color("green")) -# With background image. File extension must be png or jpeg, not jpg? -tmp <- tempfile(fileext = ".png") -png(file = tmp, bg = "transparent") -plot(1:10) -rect(1, 5, 3, 7, col = "white") -dev.off() - -c1 <- wb_comment(text = "this is a comment", author = "", visible = TRUE) -wb$add_comment(dims = "B12", comment = c1, file = tmp) -} -\keyword{internal} +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/deprecate.R +\name{comment_internal} +\alias{comment_internal} +\alias{write_comment} +\alias{remove_comment} +\title{Internal comment functions} +\usage{ +write_comment( + wb, + sheet, + col = NULL, + row = NULL, + comment, + dims = rowcol_to_dim(row, col), + color = NULL, + file = NULL +) + +remove_comment( + wb, + sheet, + col = NULL, + row = NULL, + gridExpand = TRUE, + dims = NULL +) +} +\arguments{ +\item{wb}{A workbook object} + +\item{sheet}{A worksheet of the workbook} + +\item{row, col}{Row and column of the cell} + +\item{comment}{An object created by \code{\link[=create_comment]{create_comment()}}} + +\item{dims}{Optional row and column as spreadsheet dimension, e.g. "A1"} + +\item{color}{optional background color} + +\item{file}{optional background image (file extension must be png or jpeg)} + +\item{gridExpand}{If \code{TRUE}, all data in rectangle min(rows):max(rows) X min(cols):max(cols) +will be removed.} +} +\description{ +Users are advised to use \code{\link[=wb_add_comment]{wb_add_comment()}} and \code{\link[=wb_remove_comment]{wb_remove_comment()}}. +\code{write_comment()} and \code{remove_comment()} are now deprecated. openxlsx2 will stop +exporting it at some point in the future. Use the replacement functions. +} +\examples{ +wb <- wb_workbook() +wb$add_worksheet("Sheet 1") +# add a comment without author +c1 <- wb_comment(text = "this is a comment", author = "") +wb$add_comment(dims = "B10", comment = c1) +#' # Remove comment +wb$remove_comment(sheet = "Sheet 1", dims = "B10") +# Write another comment with author information +c2 <- wb_comment(text = "this is another comment", author = "Marco Polo", visible = TRUE) +wb$add_comment(sheet = 1, dims = "C10", comment = c2) +# Works with formatted text also. +formatted_text <- fmt_txt("bar", underline = TRUE) +wb$add_comment(dims = "B5", comment = formatted_text) +# With background color +wb$add_comment(dims = "B7", comment = formatted_text, color = wb_color("green")) +# With background image. File extension must be png or jpeg, not jpg? +tmp <- tempfile(fileext = ".png") +png(file = tmp, bg = "transparent") +plot(1:10) +rect(1, 5, 3, 7, col = "white") +dev.off() + +c1 <- wb_comment(text = "this is a comment", author = "", visible = TRUE) +wb$add_comment(dims = "B12", comment = c1, file = tmp) +} +\keyword{internal} diff --git a/man/convertToExcelDate.Rd b/man/convertToExcelDate.Rd index 395121548..f5a9cc6fc 100644 --- a/man/convertToExcelDate.Rd +++ b/man/convertToExcelDate.Rd @@ -1,14 +1,14 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/dates.R -\name{convertToExcelDate} -\alias{convertToExcelDate} -\title{Convert to Excel data} -\arguments{ -\item{df}{dataframe} - -\item{date1904}{take different origin} -} -\description{ -Use \code{\link[=convert_to_excel_date]{convert_to_excel_date()}} in new code -} -\keyword{internal} +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/deprecate.R +\name{convertToExcelDate} +\alias{convertToExcelDate} +\title{Convert to Excel data} +\arguments{ +\item{df}{dataframe} + +\item{date1904}{take different origin} +} +\description{ +Use \code{\link[=convert_to_excel_date]{convert_to_excel_date()}}. +} +\keyword{internal} diff --git a/man/convert_date.Rd b/man/convert_date.Rd index 6e5159ff7..8380bc462 100644 --- a/man/convert_date.Rd +++ b/man/convert_date.Rd @@ -20,8 +20,7 @@ convert_hms(x) \item{...}{ Arguments passed on to \code{\link[base:as.Date]{base::as.Date.character}} \describe{ - \item{\code{format}}{a \code{\link[base]{character}} string. If not specified when - converting from a character representation, it will try + \item{\code{format}}{\code{\link[base]{character}} string. If not specified, it will try \code{tryFormats} one by one on the first non-\code{NA} element, and give an error if none works. Otherwise, the processing is via \code{\link[base]{strptime}()} whose help page describes available diff --git a/man/write_data.Rd b/man/write_data.Rd index 37fe84828..7f9471b2a 100644 --- a/man/write_data.Rd +++ b/man/write_data.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/write.R +% Please edit documentation in R/deprecate.R \name{write_data} \alias{write_data} \title{Write an object to a worksheet} diff --git a/man/write_datatable.Rd b/man/write_datatable.Rd index 510bd5af9..270b0b0dc 100644 --- a/man/write_datatable.Rd +++ b/man/write_datatable.Rd @@ -1,120 +1,120 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/write.R -\name{write_datatable} -\alias{write_datatable} -\title{Write to a worksheet as an Excel table} -\usage{ -write_datatable( - wb, - sheet, - x, - dims = wb_dims(start_row, start_col), - start_col = 1, - start_row = 1, - col_names = TRUE, - row_names = FALSE, - table_style = "TableStyleLight9", - table_name = NULL, - with_filter = TRUE, - sep = ", ", - first_column = FALSE, - last_column = FALSE, - banded_rows = TRUE, - banded_cols = FALSE, - apply_cell_style = TRUE, - remove_cell_style = FALSE, - na.strings = na_strings(), - inline_strings = TRUE, - total_row = FALSE, - ... -) -} -\arguments{ -\item{wb}{A Workbook object containing a worksheet.} - -\item{sheet}{The worksheet to write to. Can be the worksheet index or name.} - -\item{x}{A data frame} - -\item{dims}{Spreadsheet cell range that will determine \code{start_col} and \code{start_row}: "A1", "A1:B2", "A:B"} - -\item{start_col}{A vector specifying the starting column to write \code{x} to.} - -\item{start_row}{A vector specifying the starting row to write \code{x} to.} - -\item{col_names}{If \code{TRUE}, column names of \code{x} are written.} - -\item{row_names}{If \code{TRUE}, the row names of \code{x} are written.} - -\item{table_style}{Any table style name or "none" (see \code{vignette("openxlsx2_style_manual")})} - -\item{table_name}{Name of table in workbook. The table name must be unique.} - -\item{with_filter}{If \code{TRUE}, columns with have filters in the first row.} - -\item{sep}{Only applies to list columns. The separator used to collapse list -columns to a character vector e.g. -\code{sapply(x$list_column, paste, collapse = sep)}. -\cr\cr -\cr\strong{The below options correspond to Excel table options:} -\cr -\if{html}{\figure{tableoptions.png}{options: width="40\%" alt="Figure: table_options.png"}} -\if{latex}{\figure{tableoptions.pdf}{options: width=7cm}}} - -\item{first_column}{logical. If \code{TRUE}, the first column is bold.} - -\item{last_column}{logical. If \code{TRUE}, the last column is bold.} - -\item{banded_rows}{logical. If \code{TRUE}, rows are color banded.} - -\item{banded_cols}{logical. If \code{TRUE}, the columns are color banded.} - -\item{apply_cell_style}{Should we write cell styles to the workbook} - -\item{remove_cell_style}{keep the cell style?} - -\item{na.strings}{Value used for replacing \code{NA} values from \code{x}. Default -looks if \code{options(openxlsx2.na.strings)} is set. Otherwise \code{\link[=na_strings]{na_strings()}} -uses the special \verb{#N/A} value within the workbook.} - -\item{inline_strings}{write characters as inline strings} - -\item{total_row}{logical. With the default \code{FALSE} no total row is added.} - -\item{...}{additional arguments} -} -\description{ -Write to a worksheet and format as an Excel table. Use \code{\link[=wb_add_data_table]{wb_add_data_table()}} in new code. -This function may not be exported -} -\details{ -Formulae written using \code{\link[=wb_add_formula]{wb_add_formula()}} to a Workbook object will -not get picked up by \code{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 \code{"_openxlsx_NA"} is reserved for \code{openxlsx2}. -If the data frame contains this string, the output will be broken. - -Supported classes are data frames, matrices and vectors of various types and -everything that can be converted into a data frame with \code{as.data.frame()}. -Everything else that the user wants to write should either be converted into -a vector or data frame or written in vector or data frame segments. This -includes base classes such as \code{table}, which were coerced internally in the -predecessor of this package. - -Even vectors and data frames can consist of different classes. Many base -classes are covered, though not all and far from all third-party classes. -When data of an unknown class is written, it is handled with \code{as.character()}. -It is not possible to write character nodes beginning with \verb{} or \verb{}. Both -are reserved for internal functions. If you need these. You have to wrap -the input string in \code{fmt_txt()}. - -The columns of \code{x} with class Date/POSIXt, currency, accounting, hyperlink, -percentage are automatically styled as dates, currency, accounting, -hyperlinks, percentages respectively. - -Functions \code{\link[=wb_add_data]{wb_add_data()}} and \code{\link[=wb_add_data_table]{wb_add_data_table()}} behave quite similar. The -distinction is that the latter creates a table in the worksheet that can be -used for different kind of formulas and can be sorted independently, though -is less flexible than basic cell regions. -} -\keyword{internal} +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/deprecate.R +\name{write_datatable} +\alias{write_datatable} +\title{Write to a worksheet as an Excel table} +\usage{ +write_datatable( + wb, + sheet, + x, + dims = wb_dims(start_row, start_col), + start_col = 1, + start_row = 1, + col_names = TRUE, + row_names = FALSE, + table_style = "TableStyleLight9", + table_name = NULL, + with_filter = TRUE, + sep = ", ", + first_column = FALSE, + last_column = FALSE, + banded_rows = TRUE, + banded_cols = FALSE, + apply_cell_style = TRUE, + remove_cell_style = FALSE, + na.strings = na_strings(), + inline_strings = TRUE, + total_row = FALSE, + ... +) +} +\arguments{ +\item{wb}{A Workbook object containing a worksheet.} + +\item{sheet}{The worksheet to write to. Can be the worksheet index or name.} + +\item{x}{A data frame} + +\item{dims}{Spreadsheet cell range that will determine \code{start_col} and \code{start_row}: "A1", "A1:B2", "A:B"} + +\item{start_col}{A vector specifying the starting column to write \code{x} to.} + +\item{start_row}{A vector specifying the starting row to write \code{x} to.} + +\item{col_names}{If \code{TRUE}, column names of \code{x} are written.} + +\item{row_names}{If \code{TRUE}, the row names of \code{x} are written.} + +\item{table_style}{Any table style name or "none" (see \code{vignette("openxlsx2_style_manual")})} + +\item{table_name}{Name of table in workbook. The table name must be unique.} + +\item{with_filter}{If \code{TRUE}, columns with have filters in the first row.} + +\item{sep}{Only applies to list columns. The separator used to collapse list +columns to a character vector e.g. +\code{sapply(x$list_column, paste, collapse = sep)}. +\cr\cr +\cr\strong{The below options correspond to Excel table options:} +\cr +\if{html}{\figure{tableoptions.png}{options: width="40\%" alt="Figure: table_options.png"}} +\if{latex}{\figure{tableoptions.pdf}{options: width=7cm}}} + +\item{first_column}{logical. If \code{TRUE}, the first column is bold.} + +\item{last_column}{logical. If \code{TRUE}, the last column is bold.} + +\item{banded_rows}{logical. If \code{TRUE}, rows are color banded.} + +\item{banded_cols}{logical. If \code{TRUE}, the columns are color banded.} + +\item{apply_cell_style}{Should we write cell styles to the workbook} + +\item{remove_cell_style}{keep the cell style?} + +\item{na.strings}{Value used for replacing \code{NA} values from \code{x}. Default +looks if \code{options(openxlsx2.na.strings)} is set. Otherwise \code{\link[=na_strings]{na_strings()}} +uses the special \verb{#N/A} value within the workbook.} + +\item{inline_strings}{write characters as inline strings} + +\item{total_row}{logical. With the default \code{FALSE} no total row is added.} + +\item{...}{additional arguments} +} +\description{ +Write to a worksheet and format as an Excel table. Use \code{\link[=wb_add_data_table]{wb_add_data_table()}} in new code. +This function is deprecated and may not be exported in the future. +} +\details{ +Formulae written using \code{\link[=wb_add_formula]{wb_add_formula()}} to a Workbook object will +not get picked up by \code{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 \code{"_openxlsx_NA"} is reserved for \code{openxlsx2}. +If the data frame contains this string, the output will be broken. + +Supported classes are data frames, matrices and vectors of various types and +everything that can be converted into a data frame with \code{as.data.frame()}. +Everything else that the user wants to write should either be converted into +a vector or data frame or written in vector or data frame segments. This +includes base classes such as \code{table}, which were coerced internally in the +predecessor of this package. + +Even vectors and data frames can consist of different classes. Many base +classes are covered, though not all and far from all third-party classes. +When data of an unknown class is written, it is handled with \code{as.character()}. +It is not possible to write character nodes beginning with \verb{} or \verb{}. Both +are reserved for internal functions. If you need these. You have to wrap +the input string in \code{fmt_txt()}. + +The columns of \code{x} with class Date/POSIXt, currency, accounting, hyperlink, +percentage are automatically styled as dates, currency, accounting, +hyperlinks, percentages respectively. + +Functions \code{\link[=wb_add_data]{wb_add_data()}} and \code{\link[=wb_add_data_table]{wb_add_data_table()}} behave quite similar. The +distinction is that the latter creates a table in the worksheet that can be +used for different kind of formulas and can be sorted independently, though +is less flexible than basic cell regions. +} +\keyword{internal} diff --git a/man/write_formula.Rd b/man/write_formula.Rd index 043eafa2e..4b8beb33b 100644 --- a/man/write_formula.Rd +++ b/man/write_formula.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/write.R +% Please edit documentation in R/deprecate.R \name{write_formula} \alias{write_formula} \title{Write a character vector as an Excel Formula} @@ -47,7 +47,7 @@ Add this, if you see "@" inserted into your formulas.} } \description{ Write a a character vector containing Excel formula to a worksheet. -Use \code{\link[=wb_add_formula]{wb_add_formula()}} or \code{add_formula()} in new code. This function is meant -for internal use. +Use \code{\link[=wb_add_formula]{wb_add_formula()}} or \code{add_formula()} in new code. This function is +deprecated and may be defunct. } \keyword{internal} diff --git a/tests/testthat/test-class-comment.R b/tests/testthat/test-class-comment.R index d6ce97990..6c2db840d 100644 --- a/tests/testthat/test-class-comment.R +++ b/tests/testthat/test-class-comment.R @@ -44,23 +44,23 @@ test_that("comments", { # write comment without author c1 <- create_comment(text = "this is a comment", author = "") - write_comment(wb, 1, col = "B", row = 10, comment = c1) + wb <- wb_add_comment(wb, 1, dims = "B10", comment = c1) # Write another comment with author information c2 <- create_comment(text = "this is another comment", author = "Marco Polo") - write_comment(wb, 1, col = "C", row = 10, comment = c2) + wb <- wb_add_comment(wb, 1, dims = "C10", comment = c2) # write a styled comment with system author s1 <- create_font(b = "true", color = wb_colour(hex = "FFFF0000"), sz = "12") s2 <- create_font(color = wb_colour(hex = "FF000000"), sz = "9") c3 <- create_comment(text = c("This Part Bold red\n\n", "This part black"), style = c(s1, s2)) - expect_silent(write_comment(wb, 1, col = 6, row = 3, comment = c3)) + expect_silent(wb$add_comment(1, dims = "F1", comment = c3)) expect_length(wb$comments, 1) expect_length(wb$comments[[1]], 3) - expect_silent(remove_comment(wb, 1, col = "B", row = 10)) + expect_silent(wb$remove_comment(1, dims = "B10")) expect_length(wb$comments, 1) expect_length(wb$comments[[1]], 2) @@ -98,7 +98,7 @@ test_that("load comments", { ## add a new comment to a workbook that has comments c1 <- create_comment(text = "this is a comment", author = "") - expect_silent(write_comment(wb, 5, col = "B", row = 10, comment = c1)) + expect_silent(wb$add_comment(5, dims = "B10", comment = c1)) wb$save(temp) diff --git a/tests/testthat/test-save.R b/tests/testthat/test-save.R index 3ab427dd6..04202b522 100644 --- a/tests/testthat/test-save.R +++ b/tests/testthat/test-save.R @@ -45,7 +45,7 @@ test_that("creating hyperlinks", { expect_equal(linkString, linkString2) # write file without errors - write_formula(wb, sheet, x = linkString, startCol = 1, startRow = 1) + wb$add_formula(sheet, x = linkString, startCol = 1, startRow = 1) expect_silent(wb_save(wb, tempFile, overwrite = TRUE)) # TODO: add a check that the written xlsx file contains linkString diff --git a/tests/testthat/test-wb_functions.R b/tests/testthat/test-wb_functions.R index 9612961fc..d48ea3995 100644 --- a/tests/testthat/test-wb_functions.R +++ b/tests/testthat/test-wb_functions.R @@ -34,7 +34,7 @@ test_that("wb_to_df", { expect_equal(convert_to_excel_date(df = exp["Var5"], date1904 = FALSE), got["Var5"]) - expect_warning(convertToExcelDate(df = exp["Var5"], date1904 = FALSE), "deprecated") + expect_error(convertToExcelDate(df = exp["Var5"], date1904 = FALSE), "defunct") # return the underlying Excel formula instead of their values got <- wb_to_df(wb1, showFormula = TRUE) diff --git a/tests/testthat/test-write.R b/tests/testthat/test-write.R index 031899182..8028a29a1 100644 --- a/tests/testthat/test-write.R +++ b/tests/testthat/test-write.R @@ -17,8 +17,8 @@ test_that("write_formula", { # write data add array formula later wb <- wb_workbook() wb <- wb_add_worksheet(wb, "df") - wb$add_data("df", df, startCol = "C") - write_formula(wb, "df", start_col = "E", start_row = 2, + wb$add_data(x = df, startCol = "C") + wb$add_formula(start_col = "E", start_row = 2, x = "SUM(C2:C11*D2:D11)", array = TRUE) @@ -31,9 +31,9 @@ test_that("write_formula", { # write formula first add data later wb <- wb_workbook() wb <- wb_add_worksheet(wb, "df") - write_formula(wb, "df", start_col = "E", start_row = 2, - x = "SUM(C2:C11*D2:D11)", - array = TRUE) + wb$add_formula(start_col = "E", start_row = 2, + x = "SUM(C2:C11*D2:D11)", + array = TRUE) wb$add_data("df", df, start_col = "C") cc <- wb$worksheets[[1]]$sheet_data$cc diff --git a/tests/testthat/test-writing_posixct.R b/tests/testthat/test-writing_posixct.R index 3800b5176..01983d119 100644 --- a/tests/testthat/test-writing_posixct.R +++ b/tests/testthat/test-writing_posixct.R @@ -1,4 +1,4 @@ -test_that("Writing Posixct with write_data & write_datatable", { +test_that("Writing Posixct with wb_add_data() & wb_add_data_table()", { op <- options("openxlsx2.datetimeFormat" = "dd/mm/yy hh:mm") on.exit(options(op), add = TRUE)