Merge branch 'main' into properties

R/class-comment.R

@@ -84,22 +84,19 @@ wbComment <- R6::R6Class(
 # TODO write_comment() should leverage wbWorkbook$addComment() more
 # TODO remove_comment() should leverage wbWorkbook$remove_comment() more
 
-#' Create, write and remove comments
+#' Create a comment
 #'
-#' The comment functions (create, write and remove) allow the
-#' modification of comments. In newer spreadsheet software they are called
-#' notes, while they are called comments in openxml. Modification of what
-#' newer spreadsheet software now calls comment is possible via
-#' [wb_add_thread()].
+#' Creates a `wbComment` object. Use with [wb_add_comment()] to add to a worksheet location.
 #'
 #' @param text Comment text. Character vector.
 #' @param author Author of comment. A string.
 #' @param style A Style object or list of style objects the same length as comment vector.
 #' @param visible `TRUE` or `FALSE`. Is comment visible?
 #' @param width Textbox integer width in number of cells
 #' @param height Textbox integer height in number of cells
+#' @returns a `wbComment` object
+#' @seealso [wb_add_comment()]
 #' @export
-#' @rdname comment
 #' @examples
 #' wb <- wb_workbook()
 #' wb$add_worksheet("Sheet 1")
@@ -118,9 +115,6 @@ wbComment <- R6::R6Class(
 #' c3 <- create_comment(text = c("This Part Bold red\n\n", "This part black"), style = c(s1, s2))
 #'
 #' wb$add_comment(sheet = 1, dims = wb_dims(3, 6), comment = c3)
-#'
-#' # remove the first comment c1
-#' wb$remove_comment(1, dims = "B10")
 create_comment <- function(text,
   author = Sys.info()[["user"]],
   style = NULL,

R/class-workbook.R

@@ -2,7 +2,7 @@
 
 # R6 class ----------------------------------------------------------------
 # Lines 7 and 8 are needed until r-lib/roxygen2#1504 is fixed
-#' R6 class for a Workbook
+#' R6 class for a workbook
 #'
 #' @description
 #' A workbook
@@ -73,7 +73,7 @@ wbWorkbook <- R6::R6Class(
     #' @field media media
     media = NULL,
 
-    #' @field metadata metadata
+    #' @field metadata contains cell/value metadata imported on load from xl/metadata.xml
     metadata = NULL,
 
     #' @field persons persons
@@ -4821,13 +4821,12 @@ wbWorkbook <- R6::R6Class(
     add_form_control = function(
       sheet   = current_sheet(),
       dims    = "A1",
-      type    = NULL,
+      type    = c("Checkbox", "Radio", "Drop"),
       text    = NULL,
       link    = NULL,
       range   = NULL,
       checked = FALSE
     ) {
-
       sheet <- private$get_sheet_index(sheet)
 
       if (!is.null(dims)) {
@@ -4849,13 +4848,10 @@ wbWorkbook <- R6::R6Class(
         }
       }
 
-      if (is.null(text)) {
-        text <- ""
-      }
+      text <- text %||% ""
+
+      type <- match.arg(type)
 
-      if (is.null(type)) {
-        type <- "Checkbox"
-      }
 
       clientData <- genClientDataFC(left, top, right, bottom, link, range, type, checked)
 
@@ -5654,12 +5650,12 @@ wbWorkbook <- R6::R6Class(
       local_sheet        = FALSE,
       overwrite          = FALSE,
       comment            = NULL,
+      hidden             = NULL,
       custom_menu        = NULL,
       description        = NULL,
       is_function        = NULL,
       function_group_id  = NULL,
       help               = NULL,
-      hidden             = NULL,
       local_name         = NULL,
       publish_to_server  = NULL,
       status_bar         = NULL,
@@ -7185,7 +7181,8 @@ wbWorkbook <- R6::R6Class(
       }
 
       if (tolower(sheet) %in% self$sheet_names) {
-        warning("Fixing: a sheet with name '", sheet, '"already exists. Creating a unique sheetname"')
+        warning('Attempted to add a worksheet that is invalid or already exists.\n',
+                'Fixing: a sheet with name "', sheet, '" already exists. Creating a unique sheetname"', call. = FALSE)
         ## We simply append (1), while spreadsheet software would increase
         ## the integer as: Sheet, Sheet (1), Sheet (2) etc.
         sheet <- paste(sheet, "(1)")

R/get-named-regions.R

@@ -54,12 +54,33 @@ wb_get_named_regions_tab <- function(wb) {
   )
 }
 
-#' Get create or remove named regions
+#' Get named regions in a workbook or an xlsx file
 #'
-#' Return a vector of named regions in a xlsx file or `wbWorkbook` object
-#' @param x An xlsx file or `wbWorkbook` object
-#' @param tables add tables too if `TRUE`
+#' @returns A vector of named regions in `x`.
+#' @param x An xlsx file or a`wbWorkbook` object
+#' @param tables Should data tables be included in the result?
+#' @seealso [wb_add_named_region()], [wb_get_tables()]
 #' @export
+#' @examples
+#' wb <- wb_workbook()
+#' wb$add_worksheet("Sheet 1")
+#'
+#' ## specify region
+#' wb$add_data(x = iris, start_col = 1, start_row = 1)
+#' wb$add_named_region(
+#'   name = "iris",
+#'   dims = wb_dims(x = iris)
+#' )$add_data(sheet = 1, x = iris, name = "iris2", start_col = 10)
+#'
+#' out_file <- temp_xlsx()
+#' wb_save(wb, out_file, overwrite = TRUE)
+#'
+#' ## see named regions
+#' wb_get_named_regions(wb) ## From Workbook object
+#' wb_get_named_regions(out_file) ## From xlsx file
+#'
+#' df <- read_xlsx(out_file, named_region = "iris2")
+#' head(df)
 wb_get_named_regions <- function(x, tables = FALSE) {
   if (inherits(x, "wbWorkbook")) {
     wb <- x

R/helper-functions.R

@@ -391,12 +391,15 @@ hashPassword <- function(password) {
   format(as.hexmode(hash), upper.case = TRUE)
 }
 
-#' create sparklines used in `add_sparline()`
-#' @details the colors are all predefined to be rgb. Maybe theme colors can be
+#' Create sparklines object
+#'
+#' Create a sparkline to be added a workbook with [wb_add_sparklines()]
+#'
+#' Colors are all predefined to be rgb. Maybe theme colors can be
 #' used too.
 #' @param sheet sheet
-#' @param dims dims
-#' @param sqref sqref
+#' @param dims Cell range of cells used to create the sparklines
+#' @param sqref Cell range of the destination of the sparklines.
 #' @param type type
 #' @param negative negative
 #' @param displayEmptyCellsAs displayEmptyCellsAs
@@ -413,6 +416,7 @@ hashPassword <- function(password) {
 #' @param colorLast colorLast
 #' @param colorHigh colorHigh
 #' @param colorLow colorLow
+#' @return A string containing XML code
 #' @examples
 #' # create sparklineGroup
 #' sparklines <- c(
@@ -452,6 +456,7 @@ create_sparklines <- function(
     colorHigh = wb_color(hex = "FFD00000"),
     colorLow = wb_color(hex = "FFD00000")
 ) {
+  # TODO change arguments to snake case?
 
   assert_class(dims, "character")
   assert_class(sqref, "character")
@@ -1336,3 +1341,18 @@ solve_merge <- function(have, want) {
 
   vapply(pieces, dataframe_to_dims, NA_character_)
 }
+
+#' get the basename
+#' on windows [basename()] only handles strings up to 255 characters, but we
+#' can have longer strings when loading file systems
+#' @param path a character string
+#' @keywords internal
+#' @noRd
+basename2 <- function(path) {
+  is_to_long <- vapply(path, to_long, NA)
+  if (any(is_to_long)) {
+    return(gsub(".*[\\/]", "", path))
+  } else {
+    return(basename(path))
+  }
+}

R/read.R

@@ -1,9 +1,9 @@
 # `wb_to_df()` ----------------------------------------
-#' Create Dataframe from Workbook
+#' Create a data frame from a Workbook
 #'
 #' Simple function to create a `data.frame` from a workbook. Simple as in simply
-#' written down. [read_xlsx()] and [wb_read()] are just internal wrappers for
-#' [wb_to_df()] intended for people coming from other packages.
+#' written down. `read_xlsx()` and `wb_read()` are just internal wrappers of
+#' `wb_to_df()` intended for people coming from other packages.
 #'
 #' @details
 #' Depending if the R package `hms` is loaded, `wb_to_df()` returns
@@ -13,11 +13,17 @@
 #' * 0: character
 #' * 1: numeric
 #' * 2: date
-#' * 3: posixt
+#' * 3: posixt (datetime)
 #' * 4: logical
+#'
+#' `read_xlsx()` will not pick up formulas added to a Workbook object
+#' via [wb_add_formula()]. This is because only the formula is written and left
+#' to be evaluated when the file is opened in a spreadsheet software.
+#' Opening, saving and closing the file in a spreadsheet software will resolve this.
+#'
 #' @seealso [wb_get_named_regions()]
 #'
-#' @param file An xlsx file, Workbook object or URL to xlsx file.
+#' @param file An xlsx file, [wbWorkbook] object or URL to xlsx file.
 #' @param sheet Either sheet name or index. When missing the first sheet in the workbook is selected.
 #' @param col_names If `TRUE`, the first row of data will be used as column names.
 #' @param row_names If `TRUE`, the first col of data will be used as row names.
@@ -31,12 +37,12 @@
 #' @param skip_hidden_rows If `TRUE`, hidden rows are skipped.
 #' @param start_row first row to begin looking for data.
 #' @param start_col first column to begin looking for data.
-#' @param rows A numeric vector specifying which rows in the Excel file to read.
+#' @param rows A numeric vector specifying which rows in the xlsx file to read.
 #'   If `NULL`, all rows are read.
-#' @param cols A numeric vector specifying which columns in the Excel file to read.
+#' @param cols A numeric vector specifying which columns in the xlsx file to read.
 #'   If `NULL`, all columns are read.
 #' @param named_region Character string with a `named_region` (defined name or table).
-#'   If no sheet is selected, the first appearance will be selected.
+#'   If no sheet is selected, the first appearance will be selected. See [wb_get_named_regions()]
 #' @param types A named numeric indicating, the type of the data.
 #'   Names must match the returned data. See **Details** for more.
 #' @param na.strings A character vector of strings which are to be interpreted as `NA`.
@@ -97,7 +103,7 @@
 #' wb_to_df(wb1, na.strings = "a")
 #'
 #' ###########################################################################
-#' # named_region // namedRegion
+#' # Named regions
 #' file_named_region <- system.file("extdata", "namedRegions3.xlsx", package = "openxlsx2")
 #' wb2 <- wb_load(file_named_region)
 #'
@@ -599,11 +605,6 @@ wb_to_df <- function(
 # `read_xlsx()` -----------------------------------------------------------------
 # Ignored by roxygen2 when combining documentation
 # #' Read from an Excel file or Workbook object
-#'
-#' @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 be evaluated when the file is opened in Excel.
-#' Opening, saving and closing the file with Excel will resolve this.
 #' @rdname wb_to_df
 #' @export
 read_xlsx <- function(
@@ -702,13 +703,17 @@ wb_read <- function(
 
 }
 
+#' Add the `wb_data` attribute to a data frame in a worksheet
+#'
 #' provide wb_data object as mschart input
+#'
 #' @param wb a workbook
 #' @param sheet a sheet in the workbook either name or index
 #' @param dims the dimensions
-#' @param ... additional arguments for wb_to_df. Be aware that not every
+#' @param ... additional arguments for `wb_to_df()`. Be aware that not every
 #' argument is valid.
-#' @seealso [wb_to_df()] [wb_add_mschart()]
+#' @returns A data frame of class `wb_data`.
+#' @seealso [wb_to_df()] [wb_add_mschart()], [wb_add_pivot_table()]
 #' @examples
 #'  wb <- wb_workbook() %>%
 #'    wb_add_worksheet() %>%

R/utils.R

@@ -185,8 +185,10 @@ random_string <- function(n = 1, length = 16, pattern = "[A-Za-z0-9]", keep_seed
 #'   * A list of rows and columns for `to_rowcol`
 #' @examples
 #' dims_to_rowcol("A1:J10")
-#' rowcol_to_dims(1:10, 1:10)
+#' wb_dims(1:10, 1:10)
+#'
 #' @name dims_helper
+#' @seealso [wb_dims()]
 NULL
 #' @rdname dims_helper
 #' @export

R/wb_functions.R

@@ -262,12 +262,15 @@ style_is_hms <- function(cellXfs, numfmt_date) {
 }
 
 
-#' @rdname cleanup
+#' Delete data
+#'
+#' This function is deprecated. Use [wb_clean_sheet()].
 #' @param wb workbook
 #' @param sheet sheet to clean
 #' @param cols numeric column vector
 #' @param rows numeric row vector
 #' @export
+#' @keywords internal
 delete_data <- function(wb, sheet, cols, rows) {
 
   .Deprecated(old = "delete_data", new = "wb_clean_sheet", package = "openxlsx2")

R/wb_load.R

@@ -1,26 +1,28 @@
-#' @name wb_load
-#' @title Load an existing .xlsx file
+#' Load an existing .xlsx file
+#'
+#' `wb_load()` returns a [wbWorkbook] object conserving styles and
+#' formatting of the original input file.
+#'
+#' A warning is displayed if an xml namespace for main is found in the xlsx file.
+#' Certain xlsx files created by third-party applications contain a namespace
+#' (usually `x`). This namespace is not required for the file to work in spreadsheet
+#' software and is not expected by `openxlsx2`. Therefore it is removed when the
+#' file is loaded into a workbook. Removal is generally expected to be safe,
+#' but the feature is still experimental.
+#'
 #' @param file A path to an existing .xlsx or .xlsm file
 #' @param sheet optional sheet parameter. if this is applied, only the selected
-#' sheet will be loaded.
+#'   sheet will be loaded.
 #' @param data_only mode to import if only a data frame should be returned. This
-#' strips the wbWorkbook to a bare minimum.
+#'   strips the `wbWorkbook` to a bare minimum.
 #' @param calc_chain optionally you can keep the calculation chain intact. This
-#' is used by spreadsheet software to identify the order in which formulas are
-#' evaluated. Removing the calculation chain is considered harmless. The calc
-#' chain will be created upon the next time the worksheet is loaded in
-#' spreadsheet software. Keeping it, might only speed loading time in said
-#' software.
+#'   is used by spreadsheet software to identify the order in which formulas are
+#'   evaluated. Removing the calculation chain is considered harmless. The calc
+#'   chain will be created upon the next time the worksheet is loaded in
+#'   spreadsheet software. Keeping it, might only speed loading time in said
+#'   software.
 #' @param ... additional arguments
-#' @description  wb_load returns a workbook object conserving styles and
-#' formatting of the original .xlsx file.
-#' @details A warning is displayed if an xml namespace for main is found in the
-#' xlsx file. Certain xlsx files created by third-party applications contain a
-#' namespace (usually `x`). This namespace is not required for the file to work
-#' in spreadsheet software and is not expected by `openxlsx2`. Therefore it is
-#' removed when the file is loaded into a workbook. Removal is generally
-#' expected to be safe, but the feature is still experimental.
-#' @return Workbook object.
+#' @return A Workbook object.
 #' @export
 #' @seealso [wb_remove_worksheet()]
 #' @examples
@@ -848,7 +850,7 @@ wb_load <- function(
         # we do not ship this binary blob, therefore spreadsheet software may
         # stumble over this non existent reference. In the future we might want
         # to check if the references are valid pre file saving.
-        sel_row <- !grepl("printerSettings", basename(xml_relship$Target))
+        sel_row <- !grepl("printerSettings", basename2(xml_relship$Target))
         sel_col <- c("Id", "Type", "Target", "TargetMode")
         # return as xml
         xml <- df_to_xml("Relationship", xml_relship[sel_row, sel_col])
@@ -875,7 +877,7 @@ wb_load <- function(
 
       if (ncol(wb_rels)) {
         # since target can be any hyperlink, we have to expect various things here like uint64
-        wb_rels$tid <- suppressWarnings(as.integer(gsub("\\D+", "", basename(wb_rels$Target))))
+        wb_rels$tid <- suppressWarnings(as.integer(gsub("\\D+", "", basename2(wb_rels$Target))))
         wb_rels$typ <- basename(wb_rels$Type)
 
         cmmts <- wb_rels$tid[wb_rels$typ == "comments"]