Refactor file format guessing

NAMESPACE

@@ -6,6 +6,8 @@ export(cell_limits)
 export(cell_rows)
 export(excel_format)
 export(excel_sheets)
+export(format_from_ext)
+export(format_from_signature)
 export(read_excel)
 export(read_xls)
 export(read_xlsx)

R/excel-format.R

@@ -1,14 +1,26 @@
 #' Determine file format
 #'
-#' Determine if files are xlsx or xls. First the file extension is consulted. If
-#' that is unsuccessful and `guess = TRUE` and the file exists, the format is
-#' guessed from the [file
-#' signature](https://en.wikipedia.org/wiki/List_of_file_signatures) or "magic
-#' number".
+#' @description Determine if files are xls or xlsx (or from the xlsx family).
+#'
+#' @description `excel_format(guess = TRUE)` is used by `read_excel()` to
+#'   determine format. It draws on logic from two lower level functions:
+#'   * `format_from_ext()` attempts to determine format from the file extension.
+#'   * `format_from_signature()` consults the [file
+#'   signature](https://en.wikipedia.org/wiki/List_of_file_signatures) or "magic
+#'   number".
+#'
+#' @description File extensions associated with xlsx vs. xls:
+#'   * xlsx: `.xlsx`, `.xlsm`, `.xltx`, `.xltm`
+#'   * xls: `.xls`
+#'
+#' @description File signatures (in hexadecimal) for xlsx vs xls:
+#'   * xlsx: First 4 bytes are `50 4B 03 04`
+#'   * xls: First 8 bytes are `D0 CF 11 E0 A1 B1 1A E1`
 #'
 #' @inheritParams read_excel
-#' @param guess Logical. Whether to guess format based on the file itself, if
-#'   the extension is neither `"xlsx"` nor `"xls"`.
+#' @param guess Logical. If the file extension is absent or not recognized, this
+#'   controls whether we attempt to guess format based on the file signature or
+#'   "magic number".
 #'
 #' @return Character vector with values `"xlsx"`, `"xls"`, or `NA`.
 #' @export
@@ -24,22 +36,34 @@
 #' )
 #' excel_format(files)
 excel_format <- function(path, guess = TRUE) {
-  ext <- tolower(tools::file_ext(path))
-
-  formats <- c(xls = "xls", xlsx = "xlsx", xlsm = "xlsx")
-  format <- unname(formats[ext])
-
-  if (!guess || !anyNA(format)) {
+  format <- format_from_ext(path)
+  if (!isTRUE(guess)) {
     return(format)
   }
-
   guess_me <- is.na(format) & file.exists(path)
-  format[guess_me] <- guess_format(path[guess_me])
+  format[guess_me] <- format_from_signature(path[guess_me])
   format
 }
 
-guess_format <- function(x) {
-  signature <- lapply(x, first_8_bytes)
+#' @rdname excel_format
+#' @export
+format_from_ext <- function(path) {
+  ext <- tolower(tools::file_ext(path))
+
+  formats <- c(
+    xls = "xls",
+    xlsx = "xlsx",
+    xlsm = "xlsx",
+    xltx = "xlsx",
+    xltm = "xlsx"
+  )
+  unname(formats[ext])
+}
+
+#' @rdname excel_format
+#' @export
+format_from_signature <- function(path) {
+  signature <- lapply(path, first_8_bytes)
   vapply(signature, sig_to_fmt, "xlsx?")
 }
 
@@ -62,3 +86,11 @@ sig_to_fmt <- function(x) {
     NA_character_
   }
 }
+
+check_format <- function(path) {
+  format <- excel_format(path)
+  if (is.na(format)) {
+    stop("Can't establish that the input is either xls or xlsx.", call. = FALSE)
+  }
+  format
+}

R/excel-sheets.R

@@ -10,6 +10,7 @@
 #' path <- readxl_example("datasets.xls")
 #' lapply(excel_sheets(path), read_excel, path = path)
 excel_sheets <- function(path) {
+  path <- check_file(path)
   format <- check_format(path)
 
   switch(format,

R/read_excel.R

@@ -4,7 +4,7 @@ NULL
 
 #' Read xls and xlsx files
 #'
-#' @param path Path to the xls/xlsx file
+#' @param path Path to the xls/xlsx file.
 #' @param sheet Sheet to read. Either a string (the name of a sheet), or an
 #'   integer (the position of the sheet). Ignored if the sheet is specified via
 #'   `range`. If neither argument specifies the sheet, defaults to the first
@@ -85,6 +85,7 @@ read_excel <- function(path, sheet = NULL, range = NULL,
                        col_names = TRUE, col_types = NULL,
                        na = "", trim_ws = TRUE, skip = 0, n_max = Inf,
                        guess_max = min(1000, n_max)) {
+  path <- check_file(path)
   format <- check_format(path)
   read_excel_(
     path = path, sheet = sheet, range = range,
@@ -95,15 +96,17 @@ read_excel <- function(path, sheet = NULL, range = NULL,
   )
 }
 
-#' `read_excel()` tries to determine format from the file extension and the file
-#' itself, in that order. Use `read_xls()` and `read_xlsx()` directly to
-#' eliminate the guessing.
+#' `read_excel()` calls [excel_format()] to determine if `path` is xls or xlsx,
+#' based on the file extension and the file itself, in that order. Use
+#' `read_xls()` and `read_xlsx()` directly if you know better and want to
+#' prevent such guessing.
 #' @rdname read_excel
 #' @export
 read_xls <- function(path, sheet = NULL, range = NULL,
                      col_names = TRUE, col_types = NULL,
                      na = "", trim_ws = TRUE, skip = 0, n_max = Inf,
                      guess_max = min(1000, n_max)) {
+  path <- check_file(path)
   read_excel_(
     path = path, sheet = sheet, range = range,
     col_names = col_names, col_types = col_types,
@@ -118,6 +121,7 @@ read_xlsx <- function(path, sheet = NULL, range = NULL,
                       col_names = TRUE, col_types = NULL,
                       na = "", trim_ws = TRUE, skip = 0, n_max = Inf,
                       guess_max = min(1000, n_max)) {
+  path <- check_file(path)
   read_excel_(
     path = path, sheet = sheet, range = range,
     col_names = col_names, col_types = col_types,
@@ -130,7 +134,6 @@ read_excel_ <- function(path, sheet = NULL, range = NULL,
                         col_names = TRUE, col_types = NULL,
                         na = "", trim_ws = TRUE, skip = 0, n_max = Inf,
                         guess_max = min(1000, n_max), format) {
-  path <- check_file(path)
   if (format == "xls") {
     sheets_fun <- xls_sheets
     read_fun <- read_xls_
@@ -162,28 +165,6 @@ read_excel_ <- function(path, sheet = NULL, range = NULL,
 
 # Helper functions -------------------------------------------------------------
 
-check_format <- function(path) {
-  path <- check_file(path)
-  format <- excel_format(path)
-  if (is.na(format)) {
-    ext <- tolower(tools::file_ext(path))
-    if (nzchar(ext)) {
-      stop(
-        "Extension is neither 'xlsx' nor 'xls': ",
-        sQuote(ext),
-        call. = FALSE
-      )
-    } else {
-      stop(
-        "File has no extension and doesn't seem to be xlsx or xls: ",
-        sQuote(path),
-        call. = FALSE
-      )
-    }
-  }
-  format
-}
-
 ## return a zero-indexed sheet number
 standardise_sheet <- function(sheet, range, sheet_names) {
   range_sheet <- cellranger::as.cell_limits(range)[["sheet"]]

_pkgdown.yml

@@ -46,6 +46,7 @@ reference:
       Functions to learn properties of xls and xlsx files.
     contents:
       - excel_sheets
+      - excel_format
   - title: "Describe a target rectangle"
     desc: >
       Flexible specification of cell rectangles.