touch up R6 class

DESCRIPTION

@@ -10,10 +10,9 @@ Authors@R:
              comment = c(ORCID = "0000-0002-0750-061X")),
       person(given = "Posit Software, PBC",
              role = "cph"))
-Description: R binding for 'libfswatch', a filesystem monitoring library. All
-    functions are asynchronous and do not block the session. Set watches on
-    files or directories recursively. Log activity, or trigger an R function to
-    run when an event occurs. 
+Description: R binding for 'libfswatch', a file system monitoring library. Watch
+    files or directories recursively in the background. Log activity, or trigger
+    an R function to run every time an event occurs. 
 License: MIT + file LICENSE
 BugReports: https://github.com/shikokuchuo/watcher/issues
 URL: https://shikokuchuo.net/watcher/, https://github.com/shikokuchuo/watcher/

R/watch.R

@@ -1,10 +1,10 @@
 #' Watch a Filesystem Location
 #'
-#' Create a watch on a filesystem location. Start and stop monitoring
-#' asynchronously.
+#' Create a 'Watcher' on a filesystem location to monitor for changes in the
+#' background.
 #'
-#' A limited subset of events are watched, namely: Created, Updated, Removed and
-#' Renamed. Default latency is 1s.
+#' A limited subset of filesystem events are watched, namely: Created, Updated,
+#' Removed and Renamed. Default latency is 1s.
 #'
 #' @param path character path to a file or directory to watch. Defaults to the
 #'   current working directory.
@@ -14,7 +14,8 @@
 #'   time an event is triggered - requires the \pkg{later} package. The default,
 #'   `NULL`, causes event paths and types to be written to `stdout` instead.
 #'
-#' @return A 'Watcher' R6 class object.
+#' @return A 'Watcher' R6 class object. Start and stop background monitoring
+#'   using the `$start()` and `$stop()` methods.
 #'
 #' @examples
 #' w <- watcher(tempdir())
@@ -35,12 +36,15 @@ Watcher <- R6Class(
     active = FALSE,
     callback = NULL,
     path = NULL,
-    recursive = TRUE,
+    recursive = NULL,
     initialize = function(path = getwd(), recursive = TRUE, callback = NULL) {
-      self$path <- path.expand(path)
-      self$recursive <- as.logical(recursive)
-      self$callback <- callback
-      private$watch <- .Call(watcher_create, self$path, self$recursive, self$callback)
+      if (is.null(self$path)) {
+        self$path <- path.expand(path)
+        self$recursive <- as.logical(recursive)
+        self$callback <- callback
+        private$watch <- .Call(watcher_create, self$path, self$recursive, self$callback)
+      }
+      invisible(self)
     },
     start = function() {
       res <- .Call(watcher_start_monitor, private$watch)
@@ -51,13 +55,11 @@ Watcher <- R6Class(
       res <- invisible(.Call(watcher_stop_monitor, private$watch))
       if (res) self$active <- FALSE
       invisible(res)
-    },
-    print = function(...) {
-      cat(sprintf("<Watcher>\n  start()\n  stop()\n  path: %s\n  recursive: %s\n  active: %s\n",
-                  self$path, self$recursive, self$active))
     }
   ),
   private = list(
     watch = NULL
-  )
+  ),
+  cloneable = FALSE,
+  lock_class = TRUE
 )

README.Rmd

@@ -22,12 +22,12 @@ knitr::opts_chunk$set(
 
 Watch the File System for Changes
 
-R binding for 'libfswatch', a filesystem monitoring library.
+R binding for 'libfswatch', a file system monitoring library.
 
-All watching is asynchronous and does not block the session.
+All watching is done in the background, operating asynchronously without blocking the session.
 
-- Set watches on files or directories recursively.
-- Log activity, or trigger an R function to run when an event occurs.
+- Watch files or directories recursively.
+- Log activity, or trigger an R function to run every time an event occurs.
 
 ## Installation
 
@@ -39,7 +39,7 @@ pak::pak("shikokuchuo/watcher")
 
 ## Example
 
-Create a 'watch' using `watcher::watcher()`.
+Create a 'Watcher' using `watcher::watcher()`.
 
 By default this will watch the current working directory recursively and write events to `stdout`.
 
@@ -54,15 +54,15 @@ w <- watcher(dir, recursive = TRUE, callback = function() print("event triggered
 w
 w$start()
 
-Sys.sleep(1L)
+Sys.sleep(1)
 file.create(file.path(dir, "oldfile"))
-later::run_now(2L)
+later::run_now(2)
 
 file.rename(file.path(dir, "oldfile"), file.path(dir, "newfile"))
-later::run_now(2L)
+later::run_now(2)
 
 file.remove(file.path(dir, "newfile"))
-later::run_now(2L)
+later::run_now(2)
 
 w$stop()
 unlink(dir, force = TRUE)

README.md

@@ -12,12 +12,14 @@ coverage](https://codecov.io/gh/shikokuchuo/watcher/graph/badge.svg)](https://ap
 
 Watch the File System for Changes
 
-R binding for ‘libfswatch’, a filesystem monitoring library.
+R binding for ‘libfswatch’, a file system monitoring library.
 
-All watching is asynchronous and does not block the session.
+All watching is done in the background, operating asynchronously without
+blocking the session.
 
-- Set watches on files or directories recursively.
-- Log activity, or trigger an R function to run when an event occurs.
+- Watch files or directories recursively.
+- Log activity, or trigger an R function to run every time an event
+  occurs.
 
 ## Installation
 
@@ -29,7 +31,7 @@ pak::pak("shikokuchuo/watcher")
 
 ## Example
 
-Create a ‘watch’ using `watcher::watcher()`.
+Create a ‘Watcher’ using `watcher::watcher()`.
 
 By default this will watch the current working directory recursively and
 write events to `stdout`.
@@ -47,27 +49,32 @@ dir.create(dir)
 w <- watcher(dir, recursive = TRUE, callback = function() print("event triggered"))
 w
 #> <Watcher>
-#>   start()
-#>   stop()
-#>   path: /tmp/RtmpTjz7M7/watcher-example
-#>   recursive: TRUE
-#>   active: FALSE
+#>   Public:
+#>     active: FALSE
+#>     callback: function () 
+#>     initialize: function (path = getwd(), recursive = TRUE, callback = NULL) 
+#>     path: /tmp/Rtmp8wU9e9/watcher-example
+#>     recursive: TRUE
+#>     start: function () 
+#>     stop: function () 
+#>   Private:
+#>     watch: externalptr
 w$start()
 
-Sys.sleep(1L)
+Sys.sleep(1)
 file.create(file.path(dir, "oldfile"))
 #> [1] TRUE
-later::run_now(2L)
+later::run_now(2)
 #> [1] "event triggered"
 
 file.rename(file.path(dir, "oldfile"), file.path(dir, "newfile"))
 #> [1] TRUE
-later::run_now(2L)
+later::run_now(2)
 #> [1] "event triggered"
 
 file.remove(file.path(dir, "newfile"))
 #> [1] TRUE
-later::run_now(2L)
+later::run_now(2)
 #> [1] "event triggered"
 
 w$stop()