Say something when a formula string is written as text (#147)

A cell column has no column-wide "these are all formulas", so

  df[i, j] <- "=SUM(A1:A2)"

writes those characters.  That is the documented rule and it stays, but it is a
quiet way to lose every formula on a sheet: run unpatched against this writexl,
BioMonTools produces a workbook whose NOTES sheet has 0 formula cells and 20
inert HYPERLINK strings, and nothing -- not R, not R CMD check, not CRAN's
reverse-dependency run -- says a word.  The file opens, so the check passes.

The assignment now warns and names the spelling that works.  Nothing about what
gets written changes.

Scoped to assignment, where the ambiguity is.  Measured:

  d[i, j] <- "=SUM(A1)"              warns
  d[i, j] <- "plain text"            silent
  d[i, j] <- 99                      silent
  d[i, j] <- NA                      silent
  d[i, j] <- xl_formula("=SUM(A1)")  silent
  xl_cell_general(value = "=SUM(A1)") silent

The last is deliberate: constructing a text cell that looks like a formula is
documented behaviour, and it is not the assignment path's business to
second-guess a constructor.

Unpatched BioMonTools now raises 50-odd warnings where it raised none.  It is
still worth patching -- the warning tells you the formulas are gone, it does not
put them back.

Author: billdenney

R/xl_cell_general.R

@@ -464,6 +464,7 @@ length.xl_cell_general <- function(x) length(unclass(x))
 #' @export
 `[<-.xl_cell_general` <- function(x, i, value) {
   recs <- .cell_records(x)
+  .warn_formula_as_text(value)
   repl <- if (inherits(value, "xl_cell_general")) .cell_records(value)
           else .cell_records(xl_cell_general(value = value))
   # `i` may point past the end -- `d[3, 2] <-` on a one-row frame does exactly
@@ -474,6 +475,26 @@ length.xl_cell_general <- function(x) length(unclass(x))
   .new_cell_vector(.fill_empty_cells(recs))
 }
 
+# A string beginning with "=" assigned into a cell column is written as those
+# characters, not as a formula: a cell column has no column-wide "these are all
+# formulas".  That is the documented rule, but it is a quiet way to lose every
+# formula on a sheet -- a reverse dependency shipped a workbook with twenty
+# inert HYPERLINK strings and nothing said a word -- so say something.
+#
+# Only on assignment, where the ambiguity is.  xl_cell_general(value = "=x")
+# writing text is deliberate and stays silent.
+.warn_formula_as_text <- function(value) {
+  if (inherits(value, "xl_cell_general") || !is.character(value)) return(invisible(NULL))
+  v <- value[!is.na(value)]
+  if (!length(v) || !any(startsWith(v, "="))) return(invisible(NULL))
+  warning("assigning a string beginning with \"=\" into a cell column writes ",
+          "those characters, not a formula. Use xl_formula() for a formula, ",
+          "either per cell or over the finished column:
+",
+          "  df[[j]] <- xl_formula(df[[j]])", call. = FALSE)
+  invisible(NULL)
+}
+
 # Extending a data frame pads its other columns, and `[<-.data.frame` does that
 # through `length<-`.  Without this method the cell column stays short and the
 # frame is refused with "replacement has N rows, data has N+1".

tests/testthat/test-cell-vector.R

@@ -52,7 +52,9 @@ test_that("the pattern that broke a reverse dependency works", {
   expect_s3_class(NOTES[[2]], "xl_cell_general")
 
   NOTES[1, 1] <- "Title"
-  NOTES[3, 2] <- "=LEFT(A1,1)"
+  # writing a formula string as a value is what this pattern does; the warning
+  # is the subject of its own test below
+  expect_warning(NOTES[3, 2] <- "=LEFT(A1,1)", "not a formula")
   expect_s3_class(NOTES[[2]], "xl_cell_general")
   # the carrier and the records stay in step: a stale record list is how this
   # corrupts silently rather than loudly
@@ -123,7 +125,7 @@ test_that("assigning a bare string writes a string, not a formula", {
   # column-level kind here, and `d[i, j] <- "=A1"` writes the six characters.
   d <- data.frame(a = 1:2)
   d[, 2] <- xl_formula(c("=A1", "=A2"))
-  d[2, 2] <- "=SUM(A1:A2)"
+  expect_warning(d[2, 2] <- "=SUM(A1:A2)", "not a formula")
   expect_equal(.cell_records(d[[2]])[[2L]]$value, "=SUM(A1:A2)")
   expect_true(is.na(.cell_records(d[[2]])[[2L]]$formula))
   # the formula spelling is explicit, and still available
@@ -164,3 +166,23 @@ test_that("`length<-` grows and shrinks a cell vector", {
   expect_length(x, 2L)
   expect_equal(x[[2L]]$value, 2)
 })
+
+test_that("writing a formula string as a value says so", {
+  # a cell column has no column-wide "these are all formulas", so this writes
+  # the characters.  That is the rule, but it is a quiet way to lose every
+  # formula on a sheet, so it warns -- and points at the spelling that works.
+  d <- data.frame(a = 1:2)
+  d[, 2] <- xl_cell_general(value = c(1, 2))
+  expect_warning(d[2, 2] <- "=SUM(A1)", "Use xl_formula")
+  expect_warning(d[2, 2] <- "=SUM(A1)", "df[[j]] <- xl_formula", fixed = TRUE)
+
+  # and stays quiet everywhere the intent is already clear
+  expect_silent(d[2, 2] <- "plain text")
+  expect_silent(d[2, 2] <- 99)
+  expect_silent(d[2, 2] <- NA)
+  expect_silent(d[2, 2] <- xl_formula("=SUM(A1)"))
+  expect_silent(d[2, 2] <- xl_cell_general(formula = "=SUM(A1)"))
+  # constructing a text cell that looks like a formula is deliberate and
+  # documented, so it is not the assignment's business to second-guess it
+  expect_silent(xl_cell_general(value = "=SUM(A1)"))
+})