Add nano_init() for setting global options

Author: shikokuchuo

NAMESPACE

@@ -52,6 +52,7 @@ export(listen)
 export(logging)
 export(messenger)
 export(nano)
+export(nano_init)
 export(ncurl)
 export(nng_error)
 export(nng_version)

NEWS.md

@@ -5,10 +5,11 @@
 * New `stream()` interface exposes low-level byte stream functionality in the NNG library, intended for communicating with non-NNG endpoints, including but not limited to websocket servers.
 * `ncurl()` adds an 'async' option to perform HTTP requests asynchronously, returning immediately with a 'recvAio'. Also adds explicit arguments for HTTP method, headers (which takes a named list or character vector) and request data.
 * New `messenger()` function implements a multi-threaded console-based messaging system using NNG's scalability protocols.
-  
+* New `nano_init()` function intended to be called immediately after package load to set how to handle warnings, with a default of immediate printing of warnings (settings automatically reverted upon unload).
+
 #### Updates
 
-* Behavioural change: messages have been upgraded to warnings across the package to allow for enhanced reporting of the originating call e.g. via `warnings()` and flexibility in handling by setting the value of 'warn' using `options()`. `options(warn = 1)` is set upon package load for immediate printing of warnings (and reverted upon unload).
+* Behavioural change: messages have been upgraded to warnings across the package to allow for enhanced reporting of the originating call e.g. via `warnings()` and flexibility in handling via setting `options()`.
 * Unified `send()` and `recv()` functions, and their asynchronous counterparts `send_aio()` and `recv_aio()`, are now S3 generics and can be used across Sockets, Contexts and Streams.
 * Revised 'block' argument for `send()` and `recv()` now allows an integer value for setting a timeout.
 * `send_ctx()` and `recv_ctx()` are deprecated and will be removed in a future package version - the methods for `send()` and `recv()` should be used instead.

R/nanonext-package.R

@@ -11,6 +11,10 @@
 #'
 #' @section Usage notes:
 #'
+#'     Call \code{\link{nano_init}} after package load to set global options.
+#'     The default by calling \code{nano_init()} with no arguments will cause
+#'     generated warnings to print immediately as they occur.
+#'
 #'     \{nanonext\} offers 2 equivalent interfaces: an object-oriented interface,
 #'     and a functional interface.
 #'
@@ -128,16 +132,15 @@ NULL
                               info = TRUE,
                               FALSE)
   .logging. <<- .logging.
-  .warn. <- getOption("warn")
-  .warn. <<- .warn.
-  options(warn = 1L)
   invisible()
 }
 
 .onUnload <- function(libpath) {
-  options(warn = .warn.)
+  if (!is.null(warn <- getOption("nanonext.original.warn"))) {
+    options(warn = warn)
+    options(nanonext.original.warn = NULL)
+  }
   invisible()
 }
 
-.warn. <- NULL
 .logging. <- FALSE

R/utils.R

@@ -33,15 +33,31 @@ nng_version <- function() .Call(rnng_version)
 #'
 #' @section Warnings:
 #'
-#'     A warning is generated every time an 'errorValue' is returned. The package
-#'     changes the behaviour of warnings by setting \code{options(warn = 1)}
-#'     upon package load. This prints the warning to the console as soon as it
-#'     occurs, rather than the default of waiting for the top–level function to
-#'     return.
+#'     A warning is generated every time an 'errorValue' is returned.
 #'
-#'     See \code{\link{warning}} or the entry for 'warn' in \code{\link{options}}
-#'     for further details. The original option value for 'warn' is reverted upon
-#'     package unload.
+#'     \code{\link{nano_init}} may be used to set the value of option 'warn' and
+#'     automatically reverts it upon package unload. The default, applied by
+#'     calling \code{nano_init()} with no arguments, is 'immediate', which prints
+#'     warnings as they occur.
+#'
+#'     Further options for warnings may be set manually via \code{\link{options}}:
+#'
+#'     \itemize{
+#'
+#'     \item{warning.expression} { - an R code expression to be called if a
+#'     warning is
+#'     generated, replacing the standard message. If non-null it is called
+#'     irrespective of the value of option warn.}
+#'
+#'     \item{warning.length} { - sets the truncation limit in bytes for error and warning
+#'     messages. A non-negative integer, with allowed values 100...8170, default
+#'     1000.}
+#'
+#'     \item{nwarnings} { - the limit for the number of warnings kept when warn = 0,
+#'     default 50. This will discard messages if called whilst they are being
+#'     collected. If you increase this limit, be aware that the current
+#'     implementation pre-allocates the equivalent of a named list for them.}
+#'     }
 #'
 #' @examples
 #' nng_error(1L)
@@ -83,15 +99,31 @@ is_nul_byte <- function(x) identical(x, as.raw(0L))
 #'
 #' @section Warnings:
 #'
-#'     A warning is generated every time an 'errorValue' is returned. The package
-#'     changes the behaviour of warnings by setting \code{options(warn = 1)}
-#'     upon package load. This prints the warning to the console as soon as it
-#'     occurs, rather than the default of waiting for the top–level function to
-#'     return.
+#'     A warning is generated every time an 'errorValue' is returned.
+#'
+#'     \code{\link{nano_init}} may be used to set the value of option 'warn' and
+#'     automatically reverts it upon package unload. The default, applied by
+#'     calling \code{nano_init()} with no arguments, is 'immediate', which prints
+#'     warnings as they occur.
+#'
+#'     Further options for warnings may be set manually via \code{\link{options}}:
+#'
+#'     \itemize{
 #'
-#'     See \code{\link{warning}} or the entry for 'warn' in \code{\link{options}}
-#'     for further details. The original option value for 'warn' is reverted upon
-#'     package unload.
+#'     \item{warning.expression} { - an R code expression to be called if a
+#'     warning is
+#'     generated, replacing the standard message. If non-null it is called
+#'     irrespective of the value of option warn.}
+#'
+#'     \item{warning.length} { - sets the truncation limit in bytes for error and warning
+#'     messages. A non-negative integer, with allowed values 100...8170, default
+#'     1000.}
+#'
+#'     \item{nwarnings} { - the limit for the number of warnings kept when warn = 0,
+#'     default 50. This will discard messages if called whilst they are being
+#'     collected. If you increase this limit, be aware that the current
+#'     implementation pre-allocates the equivalent of a named list for them.}
+#'     }
 #'
 #' @examples
 #' is_error_value(1L)
@@ -100,6 +132,60 @@ is_nul_byte <- function(x) identical(x, as.raw(0L))
 #'
 is_error_value <- function(x) inherits(x, "errorValue")
 
+#' Nanonext Initialise
+#'
+#' Initialise global options - intended to be called immediately after package load.
+#'
+#' @param warn [default 'immediate'] character string defining how to treat
+#'     warnings generated by the package. 'immediate' to print warnings as they
+#'     occur, 'deferred' to print warnings when evaluation returns to the top
+#'     level, 'error' to upgrade all warnings to errors (stops execution), and
+#'     'none' to ignore all warnings.
+#'
+#' @return Integer \code{code} applied to \code{options(warn = code)} (invisibly).
+#'
+#' @section Warnings:
+#'
+#'     A warning is generated every time an 'errorValue' is returned.
+#'
+#'     This funnction sets the option 'warn' to the appropriate value and
+#'     automatically reverts it upon package unload. The default, applied by
+#'     calling \code{nano_init()} with no arguments, is 'immediate', which
+#'     prints warnings as they occur.
+#'
+#'     Further options for warnings may be set manually via \code{\link{options}}:
+#'
+#'     \itemize{
+#'
+#'     \item{warning.expression} { - an R code expression to be called if a
+#'     warning is
+#'     generated, replacing the standard message. If non-null it is called
+#'     irrespective of the value of option warn.}
+#'
+#'     \item{warning.length} { - sets the truncation limit in bytes for error and warning
+#'     messages. A non-negative integer, with allowed values 100...8170, default
+#'     1000.}
+#'
+#'     \item{nwarnings} { - the limit for the number of warnings kept when warn = 0,
+#'     default 50. This will discard messages if called whilst they are being
+#'     collected. If you increase this limit, be aware that the current
+#'     implementation pre-allocates the equivalent of a named list for them.}
+#'     }
+#'
+#' @export
+#'
+nano_init <- function(warn = c("immediate", "deferred", "error", "none")) {
+
+  cand <- c("immediate", "deferred", "error", "none")
+  warn <- switch(pmatch(warn[1L], cand, nomatch = NULL),
+                 1L, 0L, 2L, -1L)
+  is.null(warn) && stop("'warn' should be one of ", paste(cand, collapse = ", "))
+  if (is.null(getOption("nanonext.original.warn"))) options(nanonext.original.warn = getOption("warn"))
+  options(warn = warn)
+  invisible(warn)
+
+}
+
 #' Logging Level
 #'
 #' This function is deprecated.

README.Rmd

@@ -71,6 +71,8 @@ install.packages("nanonext", repos = "https://shikokuchuo.r-universe.dev")
 
 ### Interfaces
 
+Call `nano_init()` after package load to set global options. The default by calling `nano_init()` with no arguments will cause generated warnings to print immediately as they occur.
+
 {nanonext} offers 2 equivalent interfaces: an object-oriented interface, and a functional interface.
 
 #### Object-oriented Interface
@@ -84,6 +86,8 @@ Create nano objects:
 
 ```{r example}
 library(nanonext)
+nano_init()
+
 nano1 <- nano("req", listen = "inproc://nanonext")
 nano2 <- nano("rep", dial = "inproc://nanonext")
 ```
@@ -110,6 +114,8 @@ Create sockets:
 
 ```{r example2}
 library(nanonext)
+nano_init()
+
 socket1 <- socket("push", listen = "tcp://127.0.0.1:5555")
 socket2 <- socket("pull", dial = "tcp://127.0.0.1:5555")
 ```

README.md

@@ -72,6 +72,10 @@ install.packages("nanonext", repos = "https://shikokuchuo.r-universe.dev")
 
 ### Interfaces
 
+Call `nano_init()` after package load to set global options. The default
+by calling `nano_init()` with no arguments will cause generated warnings
+to print immediately as they occur.
+
 {nanonext} offers 2 equivalent interfaces: an object-oriented interface,
 and a functional interface.
 
@@ -90,6 +94,8 @@ Create nano objects:
 
 ``` r
 library(nanonext)
+nano_init()
+
 nano1 <- nano("req", listen = "inproc://nanonext")
 nano2 <- nano("rep", dial = "inproc://nanonext")
 ```
@@ -129,6 +135,8 @@ Create sockets:
 
 ``` r
 library(nanonext)
+nano_init()
+
 socket1 <- socket("push", listen = "tcp://127.0.0.1:5555")
 socket2 <- socket("pull", dial = "tcp://127.0.0.1:5555")
 ```
@@ -370,7 +378,7 @@ aio
 #> < recvAio >
 #>  - $data for message data
 aio$data |> str()
-#>  num [1:100000000] -0.257 -0.142 -0.473 0.718 -1.426 ...
+#>  num [1:100000000] 0.946 -0.658 -1.397 0.983 0.339 ...
 ```
 
 As `call_aio()` is blocking and will wait for completion, an alternative
@@ -505,11 +513,11 @@ ncurl("http://httpbin.org/headers")
 #>   [1] 7b 0a 20 20 22 68 65 61 64 65 72 73 22 3a 20 7b 0a 20 20 20 20 22 48 6f 73
 #>  [26] 74 22 3a 20 22 68 74 74 70 62 69 6e 2e 6f 72 67 22 2c 20 0a 20 20 20 20 22
 #>  [51] 58 2d 41 6d 7a 6e 2d 54 72 61 63 65 2d 49 64 22 3a 20 22 52 6f 6f 74 3d 31
-#>  [76] 2d 36 32 34 65 30 30 36 64 2d 37 38 30 37 36 62 37 63 31 35 65 64 66 37 65
-#> [101] 37 31 64 36 62 32 34 63 35 22 0a 20 20 7d 0a 7d 0a
+#>  [76] 2d 36 32 34 65 61 39 38 66 2d 35 31 39 65 31 39 66 61 31 38 61 37 38 31 31
+#> [101] 31 31 66 62 34 36 62 35 36 22 0a 20 20 7d 0a 7d 0a
 #> 
 #> $data
-#> [1] "{\n  \"headers\": {\n    \"Host\": \"httpbin.org\", \n    \"X-Amzn-Trace-Id\": \"Root=1-624e006d-78076b7c15edf7e71d6b24c5\"\n  }\n}\n"
+#> [1] "{\n  \"headers\": {\n    \"Host\": \"httpbin.org\", \n    \"X-Amzn-Trace-Id\": \"Root=1-624ea98f-519e19fa18a781111fb46b56\"\n  }\n}\n"
 ```
 
 For advanced use, supports additional HTTP methods such as POST or PUT.
@@ -524,7 +532,7 @@ res
 #>  - $raw for raw message
 
 call_aio(res)$data
-#> [1] "{\n  \"args\": {}, \n  \"data\": \"{\\\"key\\\": \\\"value\\\"}\", \n  \"files\": {}, \n  \"form\": {}, \n  \"headers\": {\n    \"Authorization\": \"Bearer APIKEY\", \n    \"Content-Length\": \"16\", \n    \"Content-Type\": \"application/json\", \n    \"Host\": \"httpbin.org\", \n    \"X-Amzn-Trace-Id\": \"Root=1-624e006d-06173bcd5b43d5622303afe5\"\n  }, \n  \"json\": {\n    \"key\": \"value\"\n  }, \n  \"origin\": \"78.145.225.121\", \n  \"url\": \"http://httpbin.org/post\"\n}\n"
+#> [1] "{\n  \"args\": {}, \n  \"data\": \"{\\\"key\\\": \\\"value\\\"}\", \n  \"files\": {}, \n  \"form\": {}, \n  \"headers\": {\n    \"Authorization\": \"Bearer APIKEY\", \n    \"Content-Length\": \"16\", \n    \"Content-Type\": \"application/json\", \n    \"Host\": \"httpbin.org\", \n    \"X-Amzn-Trace-Id\": \"Root=1-624ea98f-641a91ed52b661a054b5065c\"\n  }, \n  \"json\": {\n    \"key\": \"value\"\n  }, \n  \"origin\": \"79.173.189.204\", \n  \"url\": \"http://httpbin.org/post\"\n}\n"
 ```
 
 In this respect, it may be used as a performant and lightweight method