#' Registers a logger instance in a given logging namespace.

#'

#' @description `r lifecycle::badge("experimental")`

#'

#' @note It's a thin wrapper around the `logger` package.

#'

#' @details Creates a new logging namespace specified by the `namespace` argument.

#' When the `layout` and `level` arguments are set to `NULL` (default), the function

#' gets the values for them from system variables or R options.

#' When deciding what to use (either argument, an R option or system variable), the function

#' picks the first non `NULL` value, checking in order:

#' 1. Function argument.

#' 2. System variable.

#' 3. R option.

#'

#' `layout` and `level` can be set as system environment variables, respectively:

#' * `teal.log_layout` as `TEAL.LOG_LAYOUT`,

#' * `teal.log_level` as `TEAL.LOG_LEVEL`.

#'

#' If neither the argument nor the environment variable is set the function uses the following R options:

#' * `options(teal.log_layout)`, which is passed to [logger::layout_glue_generator()],

#' * `options(teal.log_level)`, which is passed to [logger::log_threshold()]

#'

#'

#' The logs are output to `stdout` by default. Check `logger` for more information

#' about layouts and how to use `logger`.

#'

#' @seealso The package vignettes for more help: `browseVignettes("teal.logger")`.

#'

#' @param namespace (`character(1)` or `NA_character_`)\cr

#'  the name of the logging namespace

#' @param layout (`character(1)`)\cr

#'  the log layout. Alongside the standard logging variables provided by the `logging` package

#'  (e.g. `pid`) the `token` variable can be used which will write the last 8 characters of the

#'  shiny session token to the log.

#' @param level (`character(1)` or `call`) the log level. Can be passed as

#'   character or one of the `logger`'s objects.

#'   See [logger::log_threshold()] for more information.

#'

#' @return `invisible(NULL)`

#' @export

#'

#' @examples

#' options(teal.log_layout = "{msg}")

#' options(teal.log_level = "ERROR")

#' register_logger(namespace = "new_namespace")

#' \donttest{

#' logger::log_info("Hello from new_namespace", namespace = "new_namespace")

#' }

#'

register_logger <- function(namespace = NA_character_,

                            layout = NULL,

                            level = NULL) {

  }

  }

      ))

    }

  )

    )

  }

    },

      ))

    }

  )

}

#' Generate log layout function using common variables available via glue syntax including shiny session token

#'

#' @inheritParams register_logger

#' @return function taking `level` and `msg` arguments - keeping the original call creating the generator

#'   in the generator attribute that is returned when calling log_layout for the currently used layout

#' @details this function behaves in the same way as [logger::layout_glue_generator()]

#'   but allows the shiny session token (last 8 chars) to be included in the logging layout

#' @keywords internal

layout_teal_glue_generator <- function(layout) {

      }

      ), {

        }

      })

    },

  )

}

#' Logs the basic information about the session.

#'

#' @return `invisible(NULL)`

#' @export

#'

log_system_info <- function() {

    )

  }

  # Paste package names and versions

}

#' Get value from environmental variable or R option or default in that order if the previous one is missing.

#' @param env_var_name (`character(1)`) name of the system variable

#' @param option_name (`character(1)`) name of the option

#' @param default optional, default value if both `Sys.getenv(env_var_name)` and `getOption(option_name)` are empty

#' @return an object of any class

#' @keywords internal

get_val <- function(env_var_name, option_name, default = NULL) {

}

#' Register handlers for logging messages, warnings and errors

#'

#' @param namespace (`character(1)`) the logger namespace

#' @param package (`character(1)`) the package name

#'

#' @return `NULL` invisibly. Called for its side effects.

#'

#' @details

#' This function registers global handlers for messages, warnings and errors.

#' The handlers will investigate the call stack and if it contains a function

#' from the package, the message, warning or error will be logged into the respective

#' namespace.

#'

#' The handlers are registered only once per package and type. Consecutive calls will no effect.

#' Registering handlers for package `base` is not supported.

#'

#' Use `TEAL.LOG_MUFFLE` environmental variable or `teal.log_muffle` R option to optionally

#' control recover strategies. If `TRUE` (a default value) then the handler will jump to muffle

#' restart for a given type of condition and doesn't continue (with output to the console).

#' Applicable for message and warning types only. The errors won't be suppressed.

#'

#' @note Registering handlers is forbidden within `tryCatch()` or `withCallingHandlers()`.

#' Because of this, handlers are registered only if it is possible.

#'

#' @seealso [globalCallingHandlers()]

#'

#' @export

#'

#' @examples

#' \dontrun{

#' register_handlers("teal.logger")

#' # see the outcome

#' globalCallingHandlers()

#' }

register_handlers <- function(namespace, package = namespace) {

  }

}

register_handler_type <- function(

    namespace,

    package = namespace,

    type = c("error", "warning", "message")) {

  }

  }

  }

  # avoid re-registering handlers

  }

  # create a handler object

  # loop through the call stack starting from the bottom (the last call)

  # if a function is from pre-registered package then log using pre-specified namespace

  )

  # nocov start

  handler_fun <- function(m) {

    i <- sys.nframe() - 1L # loop starting from the bottom of the stack and go up

    while (i > 0L) { # exclude 0L as this value will detect the current `handler_fun()` function

      env_sys_fun_i <- environment(sys.function(i))

      pkg_sys_fun_i <- if (!is.null(env_sys_fun_i)) { # primitive functions don't have environment

        methods::getPackageName(env_sys_fun_i)

      } else {

        ""

      }

      if (pkg_sys_fun_i %in% ls(envir = registered_handlers_namespaces)) {

        msg <- parse_logger_message(m)

        log_namespace <- registered_handlers_namespaces[[pkg_sys_fun_i]]

        logger_fun(msg, namespace = log_namespace)

        # muffle restart

        if (isTRUE(as.logical(get_val("TEAL.LOG_MUFFLE", "teal.log_muffle", TRUE)))) {

          if (type == "message") {

            invokeRestart("muffleMessage")

          }

          if (type == "warning") {

            invokeRestart("muffleWarning")

          }

        }

        break

      }

      i <- i - 1L

    }

    m

  }

  # nocov end

  # add attributes to enable checking if the handler is already registered

  )

  # construct & eval the call - globalCallingHandlers() requires named arguments

  )

}

parse_logger_message <- function(m) {

  }

}

register_handlers_possible <- function() {

    }

  }

  return(TRUE) # nocov: impossible to cover because testthat introduces it's own handlers and we want to return FALSE

}

#' Suppress logger logs

#'

#' This function suppresses `logger` when running tests via `testthat`.

#' To suppress logs for a single test, add this function

#' call within the `testthat::test_that` expression. To suppress logs for an entire

#' test file, call this function at the start of the file.

#'

#' @return `NULL` invisible

#' @export

#' @examples

#' testthat::test_that("An example test", {

#'   suppress_logs()

#'   testthat::expect_true(TRUE)

#' })

#'

suppress_logs <- function() {

}