Switch to warning on unknown class in sha, document option (#227)

* Revert back to warning on unknown class in sha1

Adding link to https://github.com/inbo/n2kanalysis/blob/main/R/sha1.R showing
how to add custom S3 dispatcher
Also update tests as needed

* Tweak warning check on sha1() with missing class

* elaborate the sha1 warning (#228)

* Micro edits following #228

---------

Co-authored-by: Thierry Onkelinx <[email protected]>

ChangeLog

@@ -1,3 +1,14 @@
+2025-01-07  Thierry Onkelinx <[email protected]>
+
+	* R/sha1.R (sha1.default): Tweak message
+	* man/sha1.R: Extend fallback discussion
+
+2025-01-06  Dirk Eddelbuettel  <[email protected]>
+
+	* R/sha1.R (sha1.default): Revert to warning
+	* man/sha1.R: Document fallback, provide reference to package
+	implementing local S3 dispatch override methods
+
 2025-01-03  Dirk Eddelbuettel  <[email protected]>
 
 	* DESCRIPTION (Version, Date): Roll micro version and date

R/sha1.R

@@ -1,7 +1,7 @@
 
 ##  sha1 -- SHA1 hash generation for R
 ##
-##  Copyright (C) 2015 - 2019  Thierry Onkelinx and Dirk Eddelbuettel
+##  Copyright (C) 2015 - 2025  Thierry Onkelinx and Dirk Eddelbuettel
 ##  Copyright (C) 2016 - 2019  Viliam Simko
 ##
 ##  This file is part of digest.
@@ -29,8 +29,9 @@ sha1.default <- function(x, digits = 14L, zapsmall = 7L, ..., algo = "sha1") {
     if (is.list(x)) {
         return(sha1.list(x, digits = digits, zapsmall = zapsmall, ..., algo = algo))
     }
-    message("sha1() has no method for the '", paste(class(x), collapse = "', '"),
-            "' class, so using fallback.")
+    warning("sha1() has no method for the '", paste(class(x), collapse = "', '"),
+            "' class, so using fallback.\nPlease read the note in ?digest::sha1",
+            "on why this might be a problem.")
     sha1_attr_digest(x = x, digits = digits, zapsmall = zapsmall, ..., algo = algo)
 }
 

inst/tinytest/test_sha1.R

@@ -511,9 +511,7 @@ expect_true(is.character(sha1(1L)))
 # Class: raw
 expect_true(is.character(sha1(as.raw(1))))
 
-# Check that the expected warning is given for sha1.default usage and that a result is produced
-expect_message(
-    sha1(logLik(lmx <- lm(x ~ 1, data = data.frame(x = 1:5)))),
-    pattern = "sha1\\(\\) has no method for the 'logLik' class, so using fallback\\."
-)
-expect_true(is.character(sha1(logLik(lmx <- lm(x ~ 1, data = data.frame(x = 1:5))))))
+# Check that a warning is given for sha1.default usage and that a result is produced
+expect_warning(val <- sha1(logLik(lmx <- lm(x ~ 1, data = data.frame(x = 1:5)))),
+               "sha1\\(\\) has no method for the 'logLik' class, so using fallback.")
+expect_true(is.character(val))

man/sha1.Rd

@@ -114,4 +114,13 @@ some classes. This was fixed in version 0.6.23. Use
 \code{options(sha1PackageVersion = "0.6.22")} to get the old behaviour.
 
 Version 0.6.24 and later ignore attributes named \code{srcref}.
+
+Version 0.6.38 and later use \code{digest()} as a fallback for undefined
+methods. Note that this breaks the guarantee for identical hashes between 32-bit
+and 64-bit system. We recommend to write a custom method for such class. The
+basic idea is the convert the class in a list of classes that \code{sha1} can
+handle. The project \url{https://github.com/inbo/n2kanalysis/} demonstrates
+how to create custom \code{sha1} dispatchers for other S3 classes, see
+file \url{https://github.com/inbo/n2kanalysis/blob/main/R/sha1.R}.
+
 }