doc / version bump

Author: s-fleck

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: lgr
 Title: A Fully Featured Logging Framework
-Version: 0.2.0.9001
+Version: 0.9.0.9000
 Authors@R: 
     person(given = "Stefan",
            family = "Fleck",
@@ -41,7 +41,8 @@ Suggests:
     tibble,
     tools,
     utils,
-    whoami
+    whoami,
+    yaml
 VignetteBuilder: 
     knitr
 Encoding: UTF-8

NAMESPACE

@@ -1,6 +1,7 @@
 # Generated by roxygen2: do not edit by hand
 
 S3method(as.data.frame,LogEvent)
+S3method(as_logger_config,Logger)
 S3method(as_logger_config,character)
 S3method(as_logger_config,list)
 S3method(format,LogEvent)

R/Logger.R

@@ -133,6 +133,14 @@
 #'     filters.
 #'   }
 #'
+#'   \item{`config(cfg  = NULL, file = NULL, text = NULL`}{Load a Logger
+#'     configuration. `cfg` can be either a special list object, the path to
+#'     a YAML config file, or a character scalar containing YAML. The arguments
+#'     `file` and `text` can used alternatively and enforce that the supplied
+#'     argument is of the specified type.
+#'     See [logger_config] for details.
+#'   }
+#'
 #'   \item{`add_appender(appender, name = NULL)`, `remove_appender(pos)`}{
 #'     Add or remove an [Appender]. Supplying a `name` is optional but
 #'     recommended. After adding an Appender with
@@ -247,46 +255,6 @@ Logger <- R6::R6Class(
       invisible(self)
     },
 
-    config = function(
-      cfg  = NULL,
-      file = NULL,
-      text = NULL
-    ){
-      assert(
-        is.null(cfg) + is.null(file) + is.null(text) >= 2,
-        "You can only specify one of `cfg`, `file` and `text`."
-      )
-
-      if (!is.null(cfg)){
-        cfg <- as_logger_config(cfg)
-
-      } else if (!is.null(file)){
-        assert(
-          is_scalar_character(file) && !grepl("\n", file) && file.exists(file),
-          "`file` is not a valid path to a readable file"
-        )
-        cfg <- as_logger_config(file)
-
-      } else if (!is.null(text)){
-        assert(
-          is_scalar_character(text) && grepl("\n", text),
-          "`text` must be a character scalar containing valid YAML"
-        )
-        cfg <- as_logger_config(text)
-
-      } else {
-        cfg <- as_logger_config()
-      }
-
-      self$set_threshold(cfg$threshold)
-      self$set_appenders(cfg$appenders)
-      self$set_propagate(cfg$propagate)
-      self$set_filters(cfg$filters)
-      self$set_exception_handler(cfg$exception_handler)
-
-      self
-    },
-
 
     log = function(
       level,
@@ -453,6 +421,48 @@ Logger <- R6::R6Class(
       )
     },
 
+
+    config = function(
+      cfg  = NULL,
+      file = NULL,
+      text = NULL
+    ){
+      assert(
+        is.null(cfg) + is.null(file) + is.null(text) >= 2,
+        "You can only specify one of `cfg`, `file` and `text`."
+      )
+
+      if (!is.null(cfg)){
+        cfg <- as_logger_config(cfg)
+
+      } else if (!is.null(file)){
+        assert(
+          is_scalar_character(file) && !grepl("\n", file) && file.exists(file),
+          "`file` is not a valid path to a readable file"
+        )
+        cfg <- as_logger_config(file)
+
+      } else if (!is.null(text)){
+        assert(
+          is_scalar_character(text) && grepl("\n", text),
+          "`text` must be a character scalar containing valid YAML"
+        )
+        cfg <- as_logger_config(text)
+
+      } else {
+        cfg <- as_logger_config()
+      }
+
+      self$set_threshold(cfg$threshold)
+      self$set_appenders(cfg$appenders)
+      self$set_propagate(cfg$propagate)
+      self$set_filters(cfg$filters)
+      self$set_exception_handler(cfg$exception_handler)
+
+      self
+    },
+
+
     add_appender = function(
       appender,
       name = NULL

R/logger_config.R

@@ -1,17 +1,41 @@
 #' Logger Configuration Objects
 #'
-#' `logger_config()` and `basic_config()` can be used to directly create
-#' objects that can be passed to the `$config()` method of Loggers.
+#' `logger_config()` is an S3 constructor for `logger_config` objects
+#' that can be passed to the `$config` method of a [Logger]. You
+#' can just pass a normal `list` instead, but using this constructor is
+#' a more formal way that includes additional argument checking.
 #'
-#' @param appenders,threshold,filters,exception_handler,propagate see [Logger]
 #'
-#' @return a `list` with subclass `"logger_config"`
+#' @param appenders see [Logger]
+#' @param threshold see [Logger]
+#' @param filters see [Logger]
+#' @param exception_handler see [Logger]
+#' @param propagate see [Logger]
+#'
+#' @return a `list` with the subclass `"logger_config"`
 #' @export
 #'
 #' @examples
+#' lg <- get_logger("test")
+#'
+#' # explicetely defining logger configurations with logger_config
+#'
 #' # call without arguments to generate the default configuration
-#' cfg <- logger_config()
+#' cfg <- logger_config()  # same as the unconfigured state of a Logger
+#' lg$config(cfg)
+#'
 #'
+#' # Creating a logger config form YAML
+#' cfg <- "
+#' Logger:
+#'   name: test/blubb
+#'   threshold: info
+#'   propagate: false
+#'   appenders:
+#'     AppenderFile:
+#'       file: /tmp/blah.txt
+#' "
+#' lg$config(cfg)  # calls as_logger_config() internally
 logger_config <- function(
   appenders = list(),
   threshold = NULL,
@@ -46,39 +70,25 @@ logger_config <- function(
 #'
 #' @param x any \R object. Especially:
 #'   * A `character` scalar. This can either be the path to a
-#'     [YAML][https://yaml.org/] file, or directly valid YAML
+#'     YAML file or a character scalar containing valid YAML
 #'   * a list containing the elements `appenders`, `threshold`, `exception_handler`,
 #'     `propagate` and `filters`. See the section *Fields* in [Logger] for
 #'     details.
 #'   * a Logger object, to clone its configuration.
 #'
 #' @rdname logger_config
+#' @seealso \url{https://www.yaml.org/}
 #' @return a logger_config object
 #' @export
 #'
-#' @examples
-#' cfg <- "
-#' Logger:
-#'   name: test/blubb
-#'   threshold: info
-#'   propagate: false
-#'   appenders:
-#'     AppenderFile:
-#'       file: /tmp/blah.txt
-#' "
-#' lg$config(as_logger_config(cfg))
-#' # but you can just do the following directly
-#' lg <- get_logger("test")
-#' lg$config(cfg)
-#'
 as_logger_config <- function(x){
   UseMethod("as_logger_config")
 }
 
 
 
 
-#' @rdname as_logger_config
+#' @rdname logger_config
 #' @export
 as_logger_config.list <- function(x){
   assert(is.list(x))
@@ -99,7 +109,7 @@ as_logger_config.list <- function(x){
 
 
 
-#' @rdname as_logger_config
+#' @rdname logger_config
 #' @export
 as_logger_config.character <- function(
   x
@@ -125,8 +135,8 @@ as_logger_config.character <- function(
 
 
 
-#' @param x
-#' @rdname as_logger_config
+#' @export
+#' @rdname logger_config
 as_logger_config.Logger <- function(x){
   logger_config(
     appenders = x$appenders,
@@ -232,27 +242,3 @@ standardize_filters_list <- function(x){
 
   x
 }
-
-
-
-#' Title
-#' @rdname logger_config
-#' @param file `character` scalar.
-#' @param fmt
-#' @param fmt_timestamp
-#' @param threshold
-#' @param appenders
-#'
-#' @return
-#' @export
-#'
-#' @examples
-basic_config = function(
-  file,
-  fmt,
-  fmt_timestamp,
-  threshold,
-  appenders
-){
-
-}

R/simple_logging.R

@@ -3,7 +3,6 @@
 #' These functions provide a simple interface to the root logger. If you do not
 #' need any of the more advanced features of lgr, start here.
 #'
-#'
 #' @name simple_logging
 #'
 #' @examples
@@ -19,7 +18,7 @@ NULL
 
 #' Basic Setup for the Logging Systen
 #'
-#' Quick and easy way to configure the root logger for logging to a root file
+#' Quick and easy way to configure the root logger for logging to a file
 #'
 #' @param file `character` scalar: If not `NULL` a [AppenderFile] will be created
 #'   that logs to this file. If the filename ends in `.jsonl` an [AppenderJson]
@@ -29,16 +28,20 @@ NULL
 #'   (see [format.LogEvent])
 #' @inheritParams print.LogEvent
 #' @inheritParams Logger
-#' @param appenders
+#' @param appenders a single [Appender] or a list thereof. Musst be `NULL` if
+#'   if `file` is already specified.
+#' @param threshold `character` or `integer` scalar.
+#'   The minimum [log level][log_levels] that should be processed by the root
+#'   logger.
 #'
 #' @return `NULL` (invisibly)
 #' @export
 #'
 #' @examples
-#'
-#' basic_config(tempfile())
-#' print(lgr)
-#'
+#' \dontrun{
+#' make the root logger log to a file
+#' basic_config(file = tempfile())
+#' }
 basic_config <- function(
   file = NULL,
   fmt = NULL,
@@ -50,7 +53,7 @@ basic_config <- function(
 
 
   if (!is.null(file)){
-    assert(is.null(appenders), "`appenders` must be null if `file` is specified")
+    assert(is.null(appenders), "`appenders` must be NULL if `file` is specified")
 
     pos <- regexpr("\\.([[:alnum:]]+)$", file)
     ext <- ifelse(pos > -1L, substring(file, pos + 1L), "")
@@ -76,9 +79,6 @@ basic_config <- function(
   l$set_appenders(appenders)
   l$set_threshold(threshold)
 
-  # reset to defaults
-  l$set_exception_handler(default_exception_handler)
-
   invisible(NULL)
 }
 

R/utils-logging.R

@@ -14,7 +14,10 @@
 #'
 #' # temporarily disable logging
 #' lg$fatal("foo")
-#' without_logging(lg$fatal("bar"))
+#' without_logging({
+#'   lg$info("everything in this codeblock will be suppressed")
+#'   lg$fatal("bar")
+#' })
 #'
 #' # globally disable logging
 #' suspend_logging()
@@ -45,8 +48,6 @@ unsuspend_logging <- function(){
 #' @rdname suspend_logging
 #' @param code Any \R code
 #' @export
-#' @examples
-#'
 without_logging <- function(code){
   old <- getOption("lgr.logging_suspended")
   on.exit(options(lgr.logging_suspended = old))
@@ -58,13 +59,8 @@ without_logging <- function(code){
 
 
 
-#'
-#'
 #' @rdname suspend_logging
-#' @param code Any \R code
 #' @export
-#' @examples
-#'
 with_logging <- function(code){
   old <- getOption("lgr.logging_suspended")
   on.exit(options(lgr.logging_suspended = old))

README.Rmd

@@ -150,7 +150,6 @@ lgr is currently very actively developed, and feature requests are encouraged.
 
 
 
-
 ## Dependencies
 
 [R6](https://github.com/r-lib/R6): The R6 class system prevents the framework
@@ -194,6 +193,8 @@ dependencies, and are well maintained :
     manually if you want to use it for logging.
   - [desc](https://CRAN.R-project.org/package=desc) for the package development
     convenince function `use_logger()`
+  - [yaml](https://CRAN.R-project.org/package=yaml) for configuring loggers 
+    via YAML files
 
   Other optional dependencies (future, future.apply) do not provide any extra
   functionallity but had to be included for some of the automated unit tests