Tidy the API: shared coercion, accurate docs, most-probable-first arguments

Follow-up to the xl_sheet_view() regrouping, from an API review before the next
phase widens things further.

The three cell shorthands each repeated the same factor-to-character coercion
and a stopifnot() whose failure printed an expression rather than a name. They
now share .as_character_arg(), which reports the argument and the class it got.

write_xlsx()'s format_headers documentation still described the header as
"centered and bold". That stopped being true when the header format became
configurable through xl_properties(header_format =), so it now says what the
argument actually does and points at the setting. xl_workbook() inherits both
that and col_names rather than carrying its own paraphrase.

xl_hyperlink(name =), xl_hyperlink_cell(value =) and xl_cell_general(value =)
all mean the display text shown instead of a URL; the docs now say so, since
the differing names are only an accident of xl_hyperlink() mirroring Excel's
HYPERLINK() argument.

Two signatures now lead with their most probable argument: xl_font() with bold
and italic rather than name and size, and xl_comment() with author before
format. Every call site names its arguments past the first, so nothing
positional depended on the old order.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: billdenney

R/excel_types.R

@@ -1,3 +1,14 @@
+# Coerce a character-ish argument, accepting a factor, and fail with a message
+# that names the argument rather than stopifnot()'s expression dump.  Shared by
+# the three cell shorthands below, which all take a character vector first.
+.as_character_arg <- function(x, arg) {
+  if (is.factor(x)) x <- as.character(x)
+  if (!is.character(x))
+    stop(sprintf("`%s` must be a character vector (got %s)", arg,
+                 paste(class(x), collapse = "/")), call. = FALSE)
+  x
+}
+
 #' Excel Types
 #'
 #' Create special column types to write to a spreadsheet.
@@ -50,9 +61,7 @@
 #' # cleanup
 #' unlink(c('universities.xlsx', 'universities2.xlsx'))
 xl_formula <- function(x, format = NULL){
-  if(is.factor(x))
-    x <- as.character(x)
-  stopifnot(is.character(x))
+  x <- .as_character_arg(x, "x")
   if(!all(grepl("^=",x) | is.na(x)))
     stop("Formulas must start with '='")
   xl_cell_general(formula = x, format = format)
@@ -62,12 +71,13 @@ xl_formula <- function(x, format = NULL){
 #' @export
 #' @param url character vector of URLs.  Use `NA` to produce a blank cell.
 #' @param name character vector of friendly display names shown in the cell
+#'   instead of the URL.  This is the same idea as `value` in
+#'   [xl_hyperlink_cell()] and in [xl_cell_general()]; the names differ only
+#'   because `xl_hyperlink()` mirrors Excel's own `HYPERLINK()` argument
 #'   instead of the raw URL.  When `NULL`, the URL is shown.  Ignored for
 #'   `NA` URLs.
 xl_hyperlink <- function(url, name = NULL, format = NULL){
-  if(is.factor(url))
-    url <- as.character(url)
-  stopifnot(is.character(url))
+  url <- .as_character_arg(url, "url")
   fmlas <- if(!is.null(name)){
     paste0("=HYPERLINK(", dubquote(url), ",", dubquote(name), ")")
   } else {
@@ -80,13 +90,12 @@ xl_hyperlink <- function(url, name = NULL, format = NULL){
 #' @rdname xl_formula
 #' @export
 #' @param value character vector (or `NULL`) of display text shown in the
+#'   cell instead of the URL --- the same idea as `name` in [xl_hyperlink()]
 #'   cell.  For `xl_hyperlink_cell()`, when `NULL` the raw URL is shown.
 #'   Recycled to the length of `url`.  Automatically set to `NA` for cells
 #'   whose URL is `NA`.
 xl_hyperlink_cell <- function(url, value = NULL, format = NULL){
-  if(is.factor(url))
-    url <- as.character(url)
-  stopifnot(is.character(url))
+  url <- .as_character_arg(url, "url")
   if(is.null(value)){
     xl_cell_general(hyperlink = url, format = format)
   } else {

R/write_xlsx.R

@@ -22,8 +22,10 @@
 #' @param x a data frame, an [xl_sheet], an [xl_workbook], or a (named) list of
 #'   data frames / `xl_sheet`s that become the sheets in the xlsx
 #' @param path a file name to write to
-#' @param col_names write column names at the top of the file?
-#' @param format_headers make the \code{col_names} in the xlsx centered and bold
+#' @param col_names write column names as the header row at the top of the sheet?
+#' @param format_headers apply the workbook's header format to that header row?
+#'   The default header format is bold and centered; change it with
+#'   \code{\link{xl_properties}(header_format = )}.
 #' @param use_zip64 use \href{https://en.wikipedia.org/wiki/Zip_(file_format)#ZIP64}{zip64}
 #' to enable support for 4GB+ xlsx files. Not all platforms can read this.
 #' @examples # Roundtrip example with single excel sheet named 'mysheet'

R/xl_comment.R

@@ -60,7 +60,7 @@ is_xl_comment <- function(x) inherits(x, "xl_comment")
 #' xl_comment("Estimate", author = "Finance",
 #'            format = xl_font(name = "Arial", size = 10) +
 #'                     xl_fill(background = "lightyellow"))
-xl_comment <- function(text, format = NULL, author = NA, visible = NA,
+xl_comment <- function(text, author = NA, format = NULL, visible = NA,
                        width = NA, height = NA, x_scale = NA, y_scale = NA,
                        start_row = NA, start_col = NA, x_offset = NA,
                        y_offset = NA) {

R/xl_format.R

@@ -204,7 +204,7 @@ NULL
 
 #' @rdname xl_format_groups
 #' @export
-xl_font <- function(name = NA, size = NA, color = NA, bold = NA, italic = NA,
+xl_font <- function(bold = NA, italic = NA, color = NA, size = NA, name = NA,
                     underline = NA, strikeout = NA, script = NA, family = NA,
                     charset = NA, outline = NA, shadow = NA, condense = NA,
                     extend = NA, scheme = NA, theme = NA, color_indexed = NA,

R/xl_sheet.R

@@ -147,6 +147,11 @@ xl_row_spec <- function(rows, height = NA, hidden = NA, level = NA,
 #' @param page An [xl_page_setup()] describing how the sheet prints
 #'   (orientation, paper size, margins, scaling, header and footer). Affects
 #'   printing only, never the cell data.
+#' @param merge One [xl_merge()], or a list of them, merging rectangles of cells
+#'   into single cells.  Merges are applied after the sheet's rows are written,
+#'   so a merge over cells the data frame filled keeps only the merged text ---
+#'   as merging in Excel does.  Any merge turns off the memory-efficient
+#'   row-streaming mode, since it writes back over rows already emitted.
 #' @return An `xl_sheet` object.
 #' @family writexl
 #' @seealso [xl_col_spec], [xl_row_spec], [write_xlsx]

R/xl_workbook.R

@@ -135,8 +135,7 @@ print.xl_properties <- function(x, ...) {
 #'
 #' @param sheets A data frame, an [xl_sheet], or a (named) list of them.
 #' @param properties An [xl_properties] object.
-#' @param col_names Write column names as the header row?
-#' @param format_headers Apply the header format to the header row?
+#' @inheritParams write_xlsx
 #' @return An `xl_workbook` object.
 #' @family writexl
 #' @seealso [xl_properties], [xl_sheet], [write_xlsx]