From 249a3d4c3ce02e10cb1d7f0ba8801f3b173f9eaa Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Tue, 30 Jul 2024 13:57:02 -0500 Subject: [PATCH] Use markdown in roxygen2 comment --- DESCRIPTION | 3 +- R/appenders.R | 52 +++++++++++++-------------- R/color.R | 4 +-- R/formatters.R | 60 ++++++++++++++++---------------- R/helpers.R | 12 +++---- R/hooks.R | 10 +++--- R/layouts.R | 56 ++++++++++++++--------------- R/levels.R | 25 +++++++------ R/logger.R | 58 +++++++++++++++--------------- R/try.R | 4 +-- R/utils.R | 6 ++-- man/appender_async.Rd | 4 +-- man/appender_console.Rd | 2 +- man/appender_file.Rd | 2 +- man/appender_kinesis.Rd | 2 +- man/appender_pushbullet.Rd | 4 +-- man/appender_slack.Rd | 2 +- man/appender_stdout.Rd | 2 +- man/appender_syslog.Rd | 4 +-- man/appender_tee.Rd | 4 +-- man/appender_telegram.Rd | 2 +- man/catch_base_log.Rd | 2 +- man/colorize_by_log_level.Rd | 2 +- man/formatter_glue.Rd | 4 +-- man/formatter_glue_or_sprintf.Rd | 2 +- man/formatter_glue_safe.Rd | 2 +- man/formatter_json.Rd | 2 +- man/formatter_logging.Rd | 4 +-- man/formatter_pander.Rd | 2 +- man/formatter_paste.Rd | 2 +- man/formatter_sprintf.Rd | 2 +- man/get_logger_meta_variables.Rd | 42 +++++++++++----------- man/grayscale_by_log_level.Rd | 2 +- man/layout_blank.Rd | 4 +-- man/layout_glue.Rd | 6 ++-- man/layout_glue_colors.Rd | 4 +-- man/layout_glue_generator.Rd | 8 ++--- man/layout_json.Rd | 2 +- man/layout_json_parser.Rd | 2 +- man/layout_logging.Rd | 4 +-- man/layout_simple.Rd | 4 +-- man/layout_syslognet.Rd | 2 +- man/log_appender.Rd | 4 +-- man/log_config_setter.Rd | 2 +- man/log_eval.Rd | 4 +-- man/log_formatter.Rd | 4 +-- man/log_layout.Rd | 4 +-- man/log_level.Rd | 6 ++-- man/log_levels.Rd | 18 +++++----- man/log_separator.Rd | 4 +-- man/log_threshold.Rd | 4 +-- man/log_tictoc.Rd | 2 +- man/log_with_separator.Rd | 4 +-- man/logger.Rd | 19 +++++----- man/skip_formatter.Rd | 2 +- man/validate_log_level.Rd | 4 +-- man/with_log_threshold.Rd | 2 +- 57 files changed, 251 insertions(+), 254 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 886713d6..8d17103b 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -11,7 +11,7 @@ Date: 2024-03-03 URL: https://daroczig.github.io/logger/ BugReports: https://github.com/daroczig/logger/issues Encoding: UTF-8 -RoxygenNote: 7.3.1 +RoxygenNote: 7.3.2 License: AGPL-3 Imports: utils @@ -43,3 +43,4 @@ Enhances: log4r VignetteBuilder: knitr Config/testthat/edition: 2 +Roxygen: list(markdown = TRUE) diff --git a/R/appenders.R b/R/appenders.R index a8935de3..da10232f 100644 --- a/R/appenders.R +++ b/R/appenders.R @@ -12,7 +12,7 @@ appender_void <- structure(function(lines) {}, generator = quote(appender_void() #' appender_console(lines) #' #' appender_stderr(lines) -#' @seealso This is a \code{\link{log_appender}}, for alternatives, see eg \code{\link{appender_stdout}}, \code{\link{appender_file}}, \code{\link{appender_tee}}, \code{\link{appender_slack}}, \code{\link{appender_pushbullet}}, \code{\link{appender_telegram}}, \code{\link{appender_syslog}}, \code{\link{appender_kinesis}} and \code{\link{appender_async}} for evaluate any \code{\link{log_appender}} function in a background process. +#' @seealso This is a [log_appender()], for alternatives, see eg [appender_stdout()], [appender_file()], [appender_tee()], [appender_slack()], [appender_pushbullet()], [appender_telegram()], [appender_syslog()], [appender_kinesis()] and [appender_async()] for evaluate any [log_appender()] function in a background process. appender_console <- structure(function(lines) { cat(lines, file = stderr(), sep = '\n') }, generator = quote(appender_console())) @@ -25,7 +25,7 @@ appender_stderr <- appender_console #' Append log record to stdout #' @param lines character vector #' @export -#' @seealso This is a \code{\link{log_appender}}, for alternatives, see eg \code{\link{appender_console}}, \code{\link{appender_file}}, \code{\link{appender_tee}}, \code{\link{appender_slack}}, \code{\link{appender_pushbullet}} +#' @seealso This is a [log_appender()], for alternatives, see eg [appender_console()], [appender_file()], [appender_tee()], [appender_slack()], [appender_pushbullet()] appender_stdout <- structure(function(lines) { cat(lines, sep = '\n') }, generator = quote(appender_stdout())) @@ -33,15 +33,15 @@ appender_stdout <- structure(function(lines) { #' Append log messages to a file #' -#' Log messages are written to a file with basic log rotation: when max number of lines or bytes is defined to be other than \code{Inf}, then the log file is renamed with a \code{.1} suffix and a new log file is created. The renaming happens recursively (eg \code{logfile.1} renamed to \code{logfile.2}) until the specified \code{max_files}, then the oldest file (\code{logfile.{max_files-1}}) is deleted. +#' Log messages are written to a file with basic log rotation: when max number of lines or bytes is defined to be other than `Inf`, then the log file is renamed with a `.1` suffix and a new log file is created. The renaming happens recursively (eg `logfile.1` renamed to `logfile.2`) until the specified `max_files`, then the oldest file (\code{logfile.{max_files-1}}) is deleted. #' @param file path -#' @param append boolean passed to \code{cat} defining if the file should be overwritten with the most recent log message instead of appending +#' @param append boolean passed to `cat` defining if the file should be overwritten with the most recent log message instead of appending #' @param max_lines numeric specifying the maximum number of lines allowed in a file before rotating #' @param max_bytes numeric specifying the maximum number of bytes allowed in a file before rotating #' @param max_files integer specifying the maximum number of files to be used in rotation #' @export -#' @return function taking \code{lines} argument -#' @seealso This is generator function for \code{\link{log_appender}}, for alternatives, see eg \code{\link{appender_console}}, \code{\link{appender_tee}}, \code{\link{appender_slack}}, \code{\link{appender_pushbullet}}, \code{\link{appender_telegram}}, \code{\link{appender_syslog}}, \code{\link{appender_kinesis}} and \code{\link{appender_async}} for evaluate any \code{\link{log_appender}} function in a background process. +#' @return function taking `lines` argument +#' @seealso This is generator function for [log_appender()], for alternatives, see eg [appender_console()], [appender_tee()], [appender_slack()], [appender_pushbullet()], [appender_telegram()], [appender_syslog()], [appender_kinesis()] and [appender_async()] for evaluate any [log_appender()] function in a background process. #' @examples \dontrun{ #' ## ########################################################################## #' ## simple example logging to a file @@ -145,11 +145,11 @@ appender_file <- function(file, append = TRUE, max_lines = Inf, max_bytes = Inf, #' Append log messages to a file and stdout as well #' -#' This appends log messages to both console and a file. The same rotation options are available as in \code{\link{appender_file}}. +#' This appends log messages to both console and a file. The same rotation options are available as in [appender_file()]. #' @inheritParams appender_file #' @export -#' @return function taking \code{lines} argument -#' @seealso This is generator function for \code{\link{log_appender}}, for alternatives, see eg \code{\link{appender_console}}, \code{\link{appender_file}}, \code{\link{appender_slack}}, \code{\link{appender_pushbullet}}, \code{\link{appender_telegram}}, \code{\link{appender_syslog}}, \code{\link{appender_kinesis}} and \code{\link{appender_async}} for evaluate any \code{\link{log_appender}} function in a background process. +#' @return function taking `lines` argument +#' @seealso This is generator function for [log_appender()], for alternatives, see eg [appender_console()], [appender_file()], [appender_slack()], [appender_pushbullet()], [appender_telegram()], [appender_syslog()], [appender_kinesis()] and [appender_async()] for evaluate any [log_appender()] function in a background process. appender_tee <- function(file, append = TRUE, max_lines = Inf, max_bytes = Inf, max_files = 1L) { force(file) force(append) @@ -170,10 +170,10 @@ appender_tee <- function(file, append = TRUE, max_lines = Inf, max_bytes = Inf, #' @param icon_emoji optional override for the bot icon #' @param api_token Slack API token #' @param preformatted use code tags around the message? -#' @return function taking \code{lines} argument +#' @return function taking `lines` argument #' @export #' @note This functionality depends on the \pkg{slackr} package. -#' @seealso This is generator function for \code{\link{log_appender}}, for alternatives, see eg \code{\link{appender_console}}, \code{\link{appender_file}}, \code{\link{appender_tee}}, \code{\link{appender_pushbullet}}, \code{\link{appender_telegram}}, \code{\link{appender_syslog}}, \code{\link{appender_kinesis}} and \code{\link{appender_async}} for evaluate any \code{\link{log_appender}} function in a background process. +#' @seealso This is generator function for [log_appender()], for alternatives, see eg [appender_console()], [appender_file()], [appender_tee()], [appender_pushbullet()], [appender_telegram()], [appender_syslog()], [appender_kinesis()] and [appender_async()] for evaluate any [log_appender()] function in a background process. appender_slack <- function(channel = Sys.getenv('SLACK_CHANNEL'), username = Sys.getenv('SLACK_USERNAME'), icon_emoji = Sys.getenv('SLACK_ICON_EMOJI'), @@ -198,10 +198,10 @@ appender_slack <- function(channel = Sys.getenv('SLACK_CHANNEL'), #' Send log messages to Pushbullet -#' @param ... parameters passed to \code{pbPost}, such as \code{recipients} or \code{apikey}, although it's probably much better to set all these in the \code{~/.rpushbullet.json} as per package docs at \url{http://dirk.eddelbuettel.com/code/rpushbullet.html} +#' @param ... parameters passed to `pbPost`, such as `recipients` or `apikey`, although it's probably much better to set all these in the `~/.rpushbullet.json` as per package docs at #' @export #' @note This functionality depends on the \pkg{RPushbullet} package. -#' @seealso This is generator function for \code{\link{log_appender}}, for alternatives, see eg \code{\link{appender_console}}, \code{\link{appender_file}}, \code{\link{appender_tee}}, \code{\link{appender_slack}}, \code{\link{appender_telegram}}, \code{\link{appender_syslog}}, \code{\link{appender_kinesis}} and \code{\link{appender_async}} for evaluate any \code{\link{log_appender}} function in a background process. +#' @seealso This is generator function for [log_appender()], for alternatives, see eg [appender_console()], [appender_file()], [appender_tee()], [appender_slack()], [appender_telegram()], [appender_syslog()], [appender_kinesis()] and [appender_async()] for evaluate any [log_appender()] function in a background process. #' @export appender_pushbullet <- function(...) { @@ -219,10 +219,10 @@ appender_pushbullet <- function(...) { #' @param chat_id Unique identifier for the target chat or username of the target channel (in the format @channelusername) #' @param bot_token Telegram Authorization token #' @param parse_mode Message parse mode. Allowed values: Markdown or HTML -#' @return function taking \code{lines} argument +#' @return function taking `lines` argument #' @export #' @note This functionality depends on the \pkg{telegram} package. -#' @seealso This is generator function for \code{\link{log_appender}}, for alternatives, see eg \code{\link{appender_console}}, \code{\link{appender_file}}, \code{\link{appender_tee}}, \code{\link{appender_pushbullet}}, \code{\link{appender_syslog}}, \code{\link{appender_kinesis}} and \code{\link{appender_async}} for evaluate any \code{\link{log_appender}} function in a background process. +#' @seealso This is generator function for [log_appender()], for alternatives, see eg [appender_console()], [appender_file()], [appender_tee()], [appender_pushbullet()], [appender_syslog()], [appender_kinesis()] and [appender_async()] for evaluate any [log_appender()] function in a background process. appender_telegram <- function(chat_id = Sys.getenv('TELEGRAM_CHAT_ID'), bot_token = Sys.getenv('TELEGRAM_BOT_TOKEN'), parse_mode = NULL) { @@ -243,11 +243,11 @@ appender_telegram <- function(chat_id = Sys.getenv('TELEGRAM_CHAT_ID'), #' Send log messages to the POSIX system log #' @param identifier A string identifying the process. -#' @param ... Further arguments passed on to \code{\link[rsyslog]{open_syslog}}. -#' @return function taking \code{lines} argument +#' @param ... Further arguments passed on to [rsyslog::open_syslog()]. +#' @return function taking `lines` argument #' @export #' @note This functionality depends on the \pkg{rsyslog} package. -#' @seealso This is generator function for \code{\link{log_appender}}, for alternatives, see eg \code{\link{appender_console}}, \code{\link{appender_file}}, \code{\link{appender_tee}}, \code{\link{appender_pushbullet}}, \code{\link{appender_telegram}}, \code{\link{appender_kinesis}} and \code{\link{appender_async}} for evaluate any \code{\link{log_appender}} function in a background process. +#' @seealso This is generator function for [log_appender()], for alternatives, see eg [appender_console()], [appender_file()], [appender_tee()], [appender_pushbullet()], [appender_telegram()], [appender_kinesis()] and [appender_async()] for evaluate any [log_appender()] function in a background process. #' @examples \dontrun{ #' if (requireNamespace("rsyslog", quietly = TRUE)) { #' log_appender(appender_syslog("test")) @@ -274,7 +274,7 @@ appender_syslog <- function(identifier, ...) { #' @param server machine where syslog daemon runs (string). #' @param port port where syslog daemon listens (integer). #' -#' @return A function taking a \code{lines} argument. +#' @return A function taking a `lines` argument. #' @export #' @note This functionality depends on the \pkg{syslognet} package. #' @examples \dontrun{ @@ -303,10 +303,10 @@ appender_syslognet <- function(identifier, server, port = 601L) { #' Send log messages to a Amazon Kinesis stream #' @param stream name of the Kinesis stream -#' @return function taking \code{lines} and optional \code{partition_key} argument +#' @return function taking `lines` and optional `partition_key` argument #' @export #' @note This functionality depends on the \pkg{botor} package. -#' @seealso This is generator function for \code{\link{log_appender}}, for alternatives, see eg \code{\link{appender_console}}, \code{\link{appender_file}}, \code{\link{appender_tee}}, \code{\link{appender_pushbullet}}, \code{\link{appender_telegram}}, \code{\link{appender_syslog}} and \code{\link{appender_async}} for evaluate any \code{\link{log_appender}} function in a background process. +#' @seealso This is generator function for [log_appender()], for alternatives, see eg [appender_console()], [appender_file()], [appender_tee()], [appender_pushbullet()], [appender_telegram()], [appender_syslog()] and [appender_async()] for evaluate any [log_appender()] function in a background process. appender_kinesis <- function(stream) { fail_on_missing_package('botor') force(stream) @@ -322,14 +322,14 @@ appender_kinesis <- function(stream) { #' Delays executing the actual appender function to the future in a background process to avoid blocking the main R session -#' @param appender a \code{\link{log_appender}} function with a \code{generator} attribute (TODO note not required, all fn will be passed if not) +#' @param appender a [log_appender()] function with a `generator` attribute (TODO note not required, all fn will be passed if not) #' @param batch number of records to process from the queue at once -#' @param namespace \code{logger} namespace to use for logging messages on starting up the background process -#' @param init optional function to run in the background process that is useful to set up the environment required for logging, eg if the \code{appender} function requires some extra packages to be loaded or some environment variables to be set etc -#' @return function taking \code{lines} argument +#' @param namespace `logger` namespace to use for logging messages on starting up the background process +#' @param init optional function to run in the background process that is useful to set up the environment required for logging, eg if the `appender` function requires some extra packages to be loaded or some environment variables to be set etc +#' @return function taking `lines` argument #' @export #' @note This functionality depends on the \pkg{txtq} and \pkg{callr} packages. The R session's temp folder is used for staging files (message queue and other forms of communication between the parent and child processes). -#' @seealso This function is to be used with an actual \code{\link{log_appender}}, for example \code{\link{appender_console}}, \code{\link{appender_file}}, \code{\link{appender_tee}}, \code{\link{appender_pushbullet}}, \code{\link{appender_telegram}}, \code{\link{appender_syslog}} or \code{\link{appender_kinesis}}. +#' @seealso This function is to be used with an actual [log_appender()], for example [appender_console()], [appender_file()], [appender_tee()], [appender_pushbullet()], [appender_telegram()], [appender_syslog()] or [appender_kinesis()]. #' @examples \dontrun{ #' appender_file_slow <- function(file) { #' force(file) diff --git a/R/color.R b/R/color.R index b9bc5f5a..ec805aa0 100644 --- a/R/color.R +++ b/R/color.R @@ -2,7 +2,7 @@ #' #' Adding color to a string to be used in terminal output. Supports ANSI standard colors 8 or 256. #' @param msg string -#' @param level see \code{\link{log_levels}} +#' @param level see [log_levels()] #' @return string with ANSI escape code #' @export #' @examples \dontrun{ @@ -39,7 +39,7 @@ colorize_by_log_level <- function(msg, level) { #' #' Adding color to a string to be used in terminal output. Supports ANSI standard colors 8 or 256. #' @param msg string -#' @param level see \code{\link{log_levels}} +#' @param level see [log_levels()] #' @return string with ANSI escape code #' @export #' @examples \dontrun{ diff --git a/R/formatters.R b/R/formatters.R index 219f3c15..5ba7ade1 100644 --- a/R/formatters.R +++ b/R/formatters.R @@ -1,33 +1,33 @@ -#' Concatenate R objects into a character vector via \code{paste} -#' @param ... passed to \code{paste} +#' Concatenate R objects into a character vector via `paste` +#' @param ... passed to `paste` #' @inheritParams log_level #' @return character vector #' @export -#' @seealso This is a \code{\link{log_formatter}}, for alternatives, see \code{\link{formatter_sprintf}}, \code{\link{formatter_glue}}, \code{\link{formatter_glue_safe}}, \code{\link{formatter_glue_or_sprintf}}, \code{\link{formatter_logging}}, \code{\link{formatter_json}}, \code{\link{formatter_pander}} and \code{\link{skip_formatter}} for marking a string not to apply the formatter on it. +#' @seealso This is a [log_formatter()], for alternatives, see [formatter_sprintf()], [formatter_glue()], [formatter_glue_safe()], [formatter_glue_or_sprintf()], [formatter_logging()], [formatter_json()], [formatter_pander()] and [skip_formatter()] for marking a string not to apply the formatter on it. formatter_paste <- structure(function(..., .logcall = sys.call(), .topcall = sys.call(-1), .topenv = parent.frame()) { eval(paste(...), envir = .topenv) }, generator = quote(formatter_paste())) -#' Apply \code{sprintf} to convert R objects into a character vector -#' @param fmt passed to \code{sprintf} -#' @param ... passed to \code{sprintf} +#' Apply `sprintf` to convert R objects into a character vector +#' @param fmt passed to `sprintf` +#' @param ... passed to `sprintf` #' @inheritParams log_level #' @return character vector #' @export -#' @seealso This is a \code{\link{log_formatter}}, for alternatives, see \code{\link{formatter_paste}}, \code{\link{formatter_glue}}, \code{\link{formatter_glue_safe}}, \code{\link{formatter_glue_or_sprintf}}, \code{\link{formatter_logging}}, \code{\link{formatter_json}}, \code{\link{formatter_pander}} and \code{\link{skip_formatter}} for marking a string not to apply the formatter on it. +#' @seealso This is a [log_formatter()], for alternatives, see [formatter_paste()], [formatter_glue()], [formatter_glue_safe()], [formatter_glue_or_sprintf()], [formatter_logging()], [formatter_json()], [formatter_pander()] and [skip_formatter()] for marking a string not to apply the formatter on it. formatter_sprintf <- structure(function(fmt, ..., .logcall = sys.call(), .topcall = sys.call(-1), .topenv = parent.frame()) { eval(sprintf(fmt, ...), envir = .topenv) }, generator = quote(formatter_sprintf())) -#' Apply \code{glue} to convert R objects into a character vector -#' @param ... passed to \code{glue} for the text interpolation +#' Apply `glue` to convert R objects into a character vector +#' @param ... passed to `glue` for the text interpolation #' @inheritParams log_level #' @return character vector #' @export -#' @note Although this is the default log message formatter function, but when \pkg{glue} is not installed, \code{\link{formatter_sprintf}} will be used as a fallback. -#' @seealso This is a \code{\link{log_formatter}}, for alternatives, see \code{\link{formatter_paste}}, \code{\link{formatter_sprintf}}, \code{\link{formatter_glue_or_sprintf}}, \code{\link{formatter_glue_safe}}, \code{\link{formatter_logging}}, \code{\link{formatter_json}}, \code{\link{formatter_pander}} and \code{\link{skip_formatter}} for marking a string not to apply the formatter on it. +#' @note Although this is the default log message formatter function, but when \pkg{glue} is not installed, [formatter_sprintf()] will be used as a fallback. +#' @seealso This is a [log_formatter()], for alternatives, see [formatter_paste()], [formatter_sprintf()], [formatter_glue_or_sprintf()], [formatter_glue_safe()], [formatter_logging()], [formatter_json()], [formatter_pander()] and [skip_formatter()] for marking a string not to apply the formatter on it. #' @importFrom utils str formatter_glue <- structure(function(..., .logcall = sys.call(), .topcall = sys.call(-1), .topenv = parent.frame()) { fail_on_missing_package('glue') @@ -55,12 +55,12 @@ formatter_glue <- structure(function(..., .logcall = sys.call(), .topcall = sys. }, generator = quote(formatter_glue())) -#' Apply \code{glue_safe} to convert R objects into a character vector -#' @param ... passed to \code{glue_safe} for the text interpolation +#' Apply `glue_safe` to convert R objects into a character vector +#' @param ... passed to `glue_safe` for the text interpolation #' @inheritParams log_level #' @return character vector #' @export -#' @seealso This is a \code{\link{log_formatter}}, for alternatives, see \code{\link{formatter_glue}}, \code{\link{formatter_paste}}, \code{\link{formatter_sprintf}}, \code{\link{formatter_glue}}, \code{\link{formatter_glue_or_sprintf}}, \code{\link{formatter_logging}}, \code{\link{formatter_json}}, \code{\link{formatter_pander}} and \code{\link{skip_formatter}} for marking a string not to apply the formatter on it. +#' @seealso This is a [log_formatter()], for alternatives, see [formatter_glue()], [formatter_paste()], [formatter_sprintf()], [formatter_glue()], [formatter_glue_or_sprintf()], [formatter_logging()], [formatter_json()], [formatter_pander()] and [skip_formatter()] for marking a string not to apply the formatter on it. #' @importFrom utils str formatter_glue_safe <- structure(function(..., .logcall = sys.call(), .topcall = sys.call(-1), .topenv = parent.frame()) { fail_on_missing_package('glue') @@ -79,13 +79,13 @@ formatter_glue_safe <- structure(function(..., .logcall = sys.call(), .topcall = }, generator = quote(formatter_glue_safe())) -#' Apply \code{glue} and \code{sprintf} +#' Apply `glue` and `sprintf` #' -#' The best of both words: using both formatter functions in your log messages, which can be useful eg if you are migrating from \code{sprintf} formatted log messages to \code{glue} or similar. +#' The best of both words: using both formatter functions in your log messages, which can be useful eg if you are migrating from `sprintf` formatted log messages to `glue` or similar. #' -#' Note that this function tries to be smart when passing arguments to \code{glue} and \code{sprintf}, but might fail with some edge cases, and returns an unformatted string. -#' @param msg passed to \code{sprintf} as \code{fmt} or handled as part of \code{...} in \code{glue} -#' @param ... passed to \code{glue} for the text interpolation +#' Note that this function tries to be smart when passing arguments to `glue` and `sprintf`, but might fail with some edge cases, and returns an unformatted string. +#' @param msg passed to `sprintf` as `fmt` or handled as part of `...` in `glue` +#' @param ... passed to `glue` for the text interpolation #' @inheritParams log_level #' @return character vector #' @export @@ -100,7 +100,7 @@ formatter_glue_safe <- structure(function(..., .logcall = sys.call(), .topcall = #' formatter_glue_or_sprintf("Hi %s, did you know that 2*4={2*4}", c('foo', 'bar')) #' formatter_glue_or_sprintf("Hi %s, did you know that 2*4=%s", c('foo', 'bar'), 2*4) #' } -#' @seealso This is a \code{\link{log_formatter}}, for alternatives, see \code{\link{formatter_paste}}, \code{\link{formatter_sprintf}}, \code{\link{formatter_glue}}, \code{\link{formatter_glue_safe}}, \code{\link{formatter_logging}}, \code{\link{formatter_json}}, \code{\link{formatter_pander}} and \code{\link{skip_formatter}} for marking a string not to apply the formatter on it. +#' @seealso This is a [log_formatter()], for alternatives, see [formatter_paste()], [formatter_sprintf()], [formatter_glue()], [formatter_glue_safe()], [formatter_logging()], [formatter_json()], [formatter_pander()] and [skip_formatter()] for marking a string not to apply the formatter on it. formatter_glue_or_sprintf <- structure(function(msg, ..., .logcall = sys.call(), .topcall = sys.call(-1), .topenv = parent.frame()) { params <- list(...) @@ -151,7 +151,7 @@ formatter_glue_or_sprintf <- structure(function(msg, ..., .logcall = sys.call(), #' Transforms all passed R objects into a JSON list -#' @param ... passed to \code{toJSON} wrapped into a \code{list} +#' @param ... passed to `toJSON` wrapped into a `list` #' @inheritParams log_level #' @return character vector #' @export @@ -162,7 +162,7 @@ formatter_glue_or_sprintf <- structure(function(msg, ..., .logcall = sys.call(), #' log_info(everything = 42) #' log_info(mtcars = mtcars, species = iris$Species) #' } -#' @seealso This is a \code{\link{log_formatter}} potentially to be used with \code{\link{layout_json_parser}}, for alternatives, see \code{\link{formatter_paste}}, \code{\link{formatter_sprintf}}, \code{\link{formatter_glue}}, \code{\link{formatter_glue_safe}}, \code{\link{formatter_glue_or_sprintf}}, \code{\link{formatter_logging}}, \code{\link{formatter_pander}} and \code{\link{skip_formatter}} for marking a string not to apply the formatter on it. +#' @seealso This is a [log_formatter()] potentially to be used with [layout_json_parser()], for alternatives, see [formatter_paste()], [formatter_sprintf()], [formatter_glue()], [formatter_glue_safe()], [formatter_glue_or_sprintf()], [formatter_logging()], [formatter_pander()] and [skip_formatter()] for marking a string not to apply the formatter on it. formatter_json <- structure(function(..., .logcall = sys.call(), .topcall = sys.call(-1), .topenv = parent.frame()) { fail_on_missing_package('jsonlite') eval(as.character(jsonlite::toJSON(list(...), auto_unbox = TRUE)), envir = .topenv) @@ -171,10 +171,10 @@ formatter_json <- structure(function(..., .logcall = sys.call(), .topcall = sys. #' Skip the formatter function #' -#' Adds the \code{skip_formatter} attribute to an object so that logger will skip calling the formatter function(s). This is useful if you want to preprocess the log message with a custom function instead of the active formatter function(s). Note that the \code{message} should be a string, and \code{skip_formatter} should be the only input for the logging function to make this work. -#' @param message character vector directly passed to the appender function in \code{\link{logger}} +#' Adds the `skip_formatter` attribute to an object so that logger will skip calling the formatter function(s). This is useful if you want to preprocess the log message with a custom function instead of the active formatter function(s). Note that the `message` should be a string, and `skip_formatter` should be the only input for the logging function to make this work. +#' @param message character vector directly passed to the appender function in [logger()] #' @param ... should be never set -#' @return character vector with \code{skip_formatter} attribute set to \code{TRUE} +#' @return character vector with `skip_formatter` attribute set to `TRUE` #' @export skip_formatter <- function(message, ...) { if (!inherits(message, 'character')) { @@ -189,7 +189,7 @@ skip_formatter <- function(message, ...) { #' Mimic the default formatter used in the \pkg{logging} package #' -#' The \pkg{logging} package uses a formatter that behaves differently when the input is a string or other R object. If the first argument is a string, then \code{\link{sprintf}} is being called -- otherwise it does something like \code{\link{log_eval}} and logs the R expression(s) and the result(s) as well. +#' The \pkg{logging} package uses a formatter that behaves differently when the input is a string or other R object. If the first argument is a string, then [sprintf()] is being called -- otherwise it does something like [log_eval()] and logs the R expression(s) and the result(s) as well. #' @examples \dontrun{ #' log_formatter(formatter_logging) #' log_info('42') @@ -199,11 +199,11 @@ skip_formatter <- function(message, ...) { #' log_info('vector %s', 1:3) #' log_info(12, 1+1, 2 * 2) #' } -#' @param ... string and further params passed to \code{sprintf} or R expressions to be evaluated +#' @param ... string and further params passed to `sprintf` or R expressions to be evaluated #' @inheritParams log_level #' @return character vector #' @export -#' @seealso This is a \code{\link{log_formatter}}, for alternatives, see \code{\link{formatter_paste}}, \code{\link{formatter_glue}}, \code{\link{formatter_glue_safe}}, \code{\link{formatter_glue_or_sprintf}}, \code{\link{formatter_json}}, \code{\link{formatter_pander}} and \code{\link{skip_formatter}} for marking a string not to apply the formatter on it. +#' @seealso This is a [log_formatter()], for alternatives, see [formatter_paste()], [formatter_glue()], [formatter_glue_safe()], [formatter_glue_or_sprintf()], [formatter_json()], [formatter_pander()] and [skip_formatter()] for marking a string not to apply the formatter on it. formatter_logging <- structure(function(..., .logcall = sys.call(), .topcall = sys.call(-1), .topenv = parent.frame()) { params <- list(...) @@ -222,7 +222,7 @@ formatter_logging <- structure(function(..., .logcall = sys.call(), .topcall = s #' Formats R objects with pander #' @param x object to be logged -#' @param ... optional parameters passed to \code{pander} +#' @param ... optional parameters passed to `pander` #' @inheritParams log_level #' @return character vector #' @examples \dontrun{ @@ -236,7 +236,7 @@ formatter_logging <- structure(function(..., .logcall = sys.call(), .topcall = s #' } #' @note This functionality depends on the \pkg{pander} package. #' @export -#' @seealso This is a \code{\link{log_formatter}}, for alternatives, see \code{\link{formatter_paste}}, \code{\link{formatter_sprintf}}, \code{\link{formatter_glue}}, \code{\link{formatter_glue_safe}}, \code{\link{formatter_glue_or_sprintf}}, \code{\link{formatter_logging}} +#' @seealso This is a [log_formatter()], for alternatives, see [formatter_paste()], [formatter_sprintf()], [formatter_glue()], [formatter_glue_safe()], [formatter_glue_or_sprintf()], [formatter_logging()] formatter_pander <- structure(function(x, ..., .logcall = sys.call(), .topcall = sys.call(-1), .topenv = parent.frame()) { fail_on_missing_package('pander') diff --git a/R/helpers.R b/R/helpers.R index 3ce76ea3..d7cde06c 100644 --- a/R/helpers.R +++ b/R/helpers.R @@ -1,7 +1,7 @@ #' Evaluate an expression and log results #' @param expr R expression to be evaluated while logging the expression itself along with the result -#' @param level \code{\link{log_levels}} -#' @param multiline setting to \code{FALSE} will print both the expression (enforced to be on one line by removing line-breaks if any) and its result on a single line separated by \code{=>}, while setting to \code{TRUE} will log the expression and the result in separate sections reserving line-breaks and rendering the printed results +#' @param level [log_levels()] +#' @param multiline setting to `FALSE` will print both the expression (enforced to be on one line by removing line-breaks if any) and its result on a single line separated by `=>`, while setting to `TRUE` will log the expression and the result in separate sections reserving line-breaks and rendering the printed results #' @examples \dontrun{ #' log_eval(pi * 2, level = INFO) #' @@ -90,7 +90,7 @@ log_eval <- function(expr, level = TRACE, multiline = FALSE) { #' log_separator(ERROR, separator = '!', width = 100) #' log_layout(layout_blank) #' log_separator(ERROR, separator = '!', width = 80) -#' @seealso \code{\link{log_with_separator}} +#' @seealso [log_with_separator()] log_separator <- function(level = INFO, namespace = NA_character_, separator = '=', @@ -134,7 +134,7 @@ log_separator <- function(level = INFO, #' logger <- layout_glue_generator(format = '{node}/{pid}/{namespace}/{fn} {time} {level}: {msg}') #' log_layout(logger) #' log_with_separator('Boo!', level = FATAL, width = 120) -#' @seealso \code{\link{log_separator}} +#' @seealso [log_separator()] log_with_separator <- function(..., level = INFO, namespace = NA_character_, separator = '=', width = 80) { base_info_chars <- nchar(catch_base_log(level, namespace, .topcall = sys.call(-1))) @@ -173,8 +173,8 @@ log_with_separator <- function(..., level = INFO, namespace = NA_character_, sep #' Tic-toc logging -#' @param ... passed to \code{log_level} -#' @param level see \code{\link{log_levels}} +#' @param ... passed to `log_level` +#' @param level see [log_levels()] #' @param namespace x #' @export #' @examples \dontrun{ diff --git a/R/hooks.R b/R/hooks.R index eb375397..d41dba9d 100644 --- a/R/hooks.R +++ b/R/hooks.R @@ -10,7 +10,7 @@ warn_if_globalCallingHandlers_is_not_available <- function() { #' Injects a logger call to standard messages #' -#' This function uses \code{trace} to add a \code{log_info} function call when \code{message} is called to log the informative messages with the \code{logger} layout and appender. +#' This function uses `trace` to add a `log_info` function call when `message` is called to log the informative messages with the `logger` layout and appender. #' @export #' @examples \dontrun{ #' log_messages() @@ -40,7 +40,7 @@ log_messages <- function() { #' Injects a logger call to standard warnings #' -#' This function uses \code{trace} to add a \code{log_warn} function call when \code{warning} is called to log the warning messages with the \code{logger} layout and appender. +#' This function uses `trace` to add a `log_warn` function call when `warning` is called to log the warning messages with the `logger` layout and appender. #' @param muffle if TRUE, the warning is not shown after being logged #' @export #' @examples \dontrun{ @@ -74,7 +74,7 @@ log_warnings <- function(muffle = getOption('logger_muffle_warnings', FALSE)) { #' Injects a logger call to standard errors #' -#' This function uses \code{trace} to add a \code{log_error} function call when \code{stop} is called to log the error messages with the \code{logger} layout and appender. +#' This function uses `trace` to add a `log_error` function call when `stop` is called to log the error messages with the `logger` layout and appender. #' @param muffle if TRUE, the error is not thrown after being logged #' @export #' @examples \dontrun{ @@ -108,9 +108,9 @@ log_errors <- function(muffle = getOption('logger_muffle_errors', FALSE)) { #' Auto logging input changes in Shiny app #' -#' This is to be called in the \code{server} section of the Shiny app. +#' This is to be called in the `server` section of the Shiny app. #' @export -#' @param input passed from Shiny's \code{server} +#' @param input passed from Shiny's `server` #' @param level log level #' @param excluded_inputs character vector of input names to exclude from logging #' @param namespace the name of the namespace diff --git a/R/layouts.R b/R/layouts.R index eeae60f5..74149540 100644 --- a/R/layouts.R +++ b/R/layouts.R @@ -1,32 +1,32 @@ #' Collect useful information about the logging environment to be used in log messages #' -#' Available variables to be used in the log formatter functions, eg in \code{\link{layout_glue_generator}}: +#' Available variables to be used in the log formatter functions, eg in [layout_glue_generator()]: #' \itemize{ -#' \item levelr: log level as an R object, eg \code{\link{INFO}} -#' \item level: log level as a string, eg \code{\link{INFO}} -#' \item time: current time as \code{POSIXct} -#' \item node: name by which the machine is known on the network as reported by \code{Sys.info} +#' \item levelr: log level as an R object, eg [INFO()] +#' \item level: log level as a string, eg [INFO()] +#' \item time: current time as `POSIXct` +#' \item node: name by which the machine is known on the network as reported by `Sys.info` #' \item arch: machine type, typically the CPU architecture #' \item os_name: Operating System's name #' \item os_release: Operating System's release #' \item os_version: Operating System's version -#' \item user: name of the real user id as reported by \code{Sys.info} +#' \item user: name of the real user id as reported by `Sys.info` #' \item pid: the process identification number of the R session -#' \item node: name by which the machine is known on the network as reported by \code{Sys.info} +#' \item node: name by which the machine is known on the network as reported by `Sys.info` #' \item r_version: R's major and minor version as a string -#' \item ns: namespace usually defaults to \code{global} or the name of the holding R package of the calling the logging function -#' \item ns_pkg_version: the version of \code{ns} when it's a package -#' \item ans: same as \code{ns} if there's a defined \code{\link{logger}} for the namespace, otherwise a fallback namespace (eg usually \code{global}) -#' \item topenv: the name of the top environment from which the parent call was called (eg R package name or \code{GlobalEnv}) +#' \item ns: namespace usually defaults to `global` or the name of the holding R package of the calling the logging function +#' \item ns_pkg_version: the version of `ns` when it's a package +#' \item ans: same as `ns` if there's a defined [logger()] for the namespace, otherwise a fallback namespace (eg usually `global`) +#' \item topenv: the name of the top environment from which the parent call was called (eg R package name or `GlobalEnv`) #' \item call: parent call (if any) calling the logging function #' \item fn: function's (if any) name calling the logging function #' } -#' @param log_level log level as per \code{\link{log_levels}} +#' @param log_level log level as per [log_levels()] #' @inheritParams log_level #' @return list #' @export #' @importFrom utils packageVersion -#' @seealso \code{\link{layout_glue_generator}} +#' @seealso [layout_glue_generator()] get_logger_meta_variables <- function(log_level = NULL, namespace = NA_character_, .logcall = sys.call(), .topcall = sys.call(-1), .topenv = parent.frame()) { @@ -68,13 +68,13 @@ get_logger_meta_variables <- function(log_level = NULL, namespace = NA_character #' Generate log layout function using common variables available via glue syntax #' -#' \code{format} is passed to \code{glue} with access to the below variables: +#' `format` is passed to `glue` with access to the below variables: #' \itemize{ #' \item msg: the actual log message -#' \item further variables set by \code{\link{get_logger_meta_variables}} +#' \item further variables set by [get_logger_meta_variables()] #' } -#' @param format \code{glue}-flavored layout of the message using the above variables -#' @return function taking \code{level} and \code{msg} arguments - keeping the original call creating the generator in the \code{generator} attribute that is returned when calling \code{\link{log_layout}} for the currently used layout +#' @param format `glue`-flavored layout of the message using the above variables +#' @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 #' @export #' @examples \dontrun{ #' example_layout <- layout_glue_generator( @@ -84,7 +84,7 @@ get_logger_meta_variables <- function(log_level = NULL, namespace = NA_character #' log_layout(example_layout) #' log_info('try {runif(1)}') #' } -#' @seealso See example calls from \code{\link{layout_glue}} and \code{\link{layout_glue_colors}}. +#' @seealso See example calls from [layout_glue()] and [layout_glue_colors()]. layout_glue_generator <- function(format = '{level} [{format(time, "%Y-%m-%d %H:%M:%S")}] {msg}') { force(format) @@ -112,7 +112,7 @@ layout_glue_generator <- function(format = '{level} [{format(time, "%Y-%m-%d %H: #' @param msg string message #' @return character vector #' @export -#' @seealso This is a \code{\link{log_layout}}, for alternatives, see \code{\link{layout_simple}}, \code{\link{layout_glue_colors}}, \code{\link{layout_json}}, or generator functions such as \code{\link{layout_glue_generator}} +#' @seealso This is a [log_layout()], for alternatives, see [layout_simple()], [layout_glue_colors()], [layout_json()], or generator functions such as [layout_glue_generator()] layout_blank <- structure(function(level, msg, namespace = NA_character_, .logcall = sys.call(), .topcall = sys.call(-1), .topenv = parent.frame()) { msg @@ -124,7 +124,7 @@ layout_blank <- structure(function(level, msg, namespace = NA_character_, #' @param msg string message #' @return character vector #' @export -#' @seealso This is a \code{\link{log_layout}}, for alternatives, see \code{\link{layout_blank}}, \code{\link{layout_glue}}, \code{\link{layout_glue_colors}}, \code{\link{layout_json}}, \code{\link{layout_json_parser}}, or generator functions such as \code{\link{layout_glue_generator}} +#' @seealso This is a [log_layout()], for alternatives, see [layout_blank()], [layout_glue()], [layout_glue_colors()], [layout_json()], [layout_json_parser()], or generator functions such as [layout_glue_generator()] layout_simple <- structure(function(level, msg, namespace = NA_character_, .logcall = sys.call(), .topcall = sys.call(-1), .topenv = parent.frame()) { paste0(attr(level, 'level'), ' [', format(Sys.time(), "%Y-%m-%d %H:%M:%S"), '] ', msg) @@ -136,7 +136,7 @@ layout_simple <- structure(function(level, msg, namespace = NA_character_, #' @param msg string message #' @return character vector #' @export -#' @seealso This is a \code{\link{log_layout}}, for alternatives, see \code{\link{layout_blank}}, \code{\link{layout_glue}}, \code{\link{layout_glue_colors}}, \code{\link{layout_json}}, \code{\link{layout_json_parser}}, or generator functions such as \code{\link{layout_glue_generator}} +#' @seealso This is a [log_layout()], for alternatives, see [layout_blank()], [layout_glue()], [layout_glue_colors()], [layout_json()], [layout_json_parser()], or generator functions such as [layout_glue_generator()] #' @examples \dontrun{ #' log_layout(layout_logging) #' log_info(42) @@ -157,17 +157,17 @@ layout_logging <- structure(function(level, msg, namespace = NA_character_, }, generator = quote(layout_logging())) -#' Format a log message with \code{glue} +#' Format a log message with `glue` #' -#' By default, this layout includes the log level of the log record as per \code{\link{log_levels}}, the current timestamp and the actual log message -- that you can override via calling \code{\link{layout_glue_generator}} directly. For colorized output, see \code{\link{layout_glue_colors}}. +#' By default, this layout includes the log level of the log record as per [log_levels()], the current timestamp and the actual log message -- that you can override via calling [layout_glue_generator()] directly. For colorized output, see [layout_glue_colors()]. #' @inheritParams layout_simple #' @return character vector #' @export -#' @seealso This is a \code{\link{log_layout}}, for alternatives, see \code{\link{layout_blank}}, \code{\link{layout_simple}}, \code{\link{layout_glue_colors}}, \code{\link{layout_json}}, \code{\link{layout_json_parser}}, or generator functions such as \code{\link{layout_glue_generator}} +#' @seealso This is a [log_layout()], for alternatives, see [layout_blank()], [layout_simple()], [layout_glue_colors()], [layout_json()], [layout_json_parser()], or generator functions such as [layout_glue_generator()] layout_glue <- layout_glue_generator() -#' Format a log message with \code{glue} and ANSI escape codes to add colors +#' Format a log message with `glue` and ANSI escape codes to add colors #' @inheritParams layout_simple #' @return character vector #' @export @@ -183,7 +183,7 @@ layout_glue <- layout_glue_generator() #' log_error('This is another problem') #' log_fatal('The last problem.') #' } -#' @seealso This is a \code{\link{log_layout}}, for alternatives, see \code{\link{layout_blank}}, \code{\link{layout_simple}}, \code{\link{layout_glue}}, \code{\link{layout_json}}, \code{\link{layout_json_parser}}, or generator functions such as \code{\link{layout_glue_generator}} +#' @seealso This is a [log_layout()], for alternatives, see [layout_blank()], [layout_simple()], [layout_glue()], [layout_json()], [layout_json_parser()], or generator functions such as [layout_glue_generator()] #' @note This functionality depends on the \pkg{crayon} package. layout_glue_colors <- layout_glue_generator( format = paste( @@ -202,7 +202,7 @@ layout_glue_colors <- layout_glue_generator( #' log_info('ok {1:3} + {1:3} = {2*(1:3)}') #' } #' @note This functionality depends on the \pkg{jsonlite} package. -#' @seealso This is a \code{\link{log_layout}}, for alternatives, see \code{\link{layout_blank}}, \code{\link{layout_simple}}, \code{\link{layout_glue}}, \code{\link{layout_glue_colors}}, \code{\link{layout_json_parser}}, or generator functions such as \code{\link{layout_glue_generator}} +#' @seealso This is a [log_layout()], for alternatives, see [layout_blank()], [layout_simple()], [layout_glue()], [layout_glue_colors()], [layout_json_parser()], or generator functions such as [layout_glue_generator()] layout_json <- function(fields = c('time', 'level', 'ns', 'ans', 'topenv', 'fn', 'node', 'arch', 'os_name', 'os_release', 'os_version', 'pid', 'user', 'msg')) { force(fields) @@ -235,7 +235,7 @@ layout_json <- function(fields = c('time', 'level', 'ns', 'ans', 'topenv', 'fn', #' log_info(cars = row.names(mtcars), species = unique(iris$Species)) #' } #' @note This functionality depends on the \pkg{jsonlite} package. -#' @seealso This is a \code{\link{log_layout}} potentially to be used with \code{\link{formatter_json}}, for alternatives, see \code{\link{layout_simple}}, \code{\link{layout_glue}}, \code{\link{layout_glue_colors}}, \code{\link{layout_json}} or generator functions such as \code{\link{layout_glue_generator}} +#' @seealso This is a [log_layout()] potentially to be used with [formatter_json()], for alternatives, see [layout_simple()], [layout_glue()], [layout_glue_colors()], [layout_json()] or generator functions such as [layout_glue_generator()] layout_json_parser <- function(fields = c('time', 'level', 'ns', 'ans', 'topenv', 'fn', 'node', 'arch', 'os_name', 'os_release', 'os_version', 'pid', 'user')) { force(fields) diff --git a/R/levels.R b/R/levels.R index d7a7b02d..3c2a546a 100644 --- a/R/levels.R +++ b/R/levels.R @@ -2,20 +2,19 @@ log_levels_supported <- c('OFF', 'FATAL', 'ERROR', 'WARN', 'SUCCESS', 'INFO', 'D #' Log levels #' -#' The standard Apache logj4 log levels plus a custom level for \code{SUCCESS}. For the full list of these log levels and suggested usage, check the below Details. +#' The standard Apache logj4 log levels plus a custom level for `SUCCESS`. For the full list of these log levels and suggested usage, check the below Details. #' #' List of supported log levels: -#' \enumerate{ -#' \item \code{OFF} No events will be logged -#' \item \code{FATAL} Severe error that will prevent the application from continuing -#' \item \code{ERROR} An error in the application, possibly recoverable -#' \item \code{WARN} An event that might possible lead to an error -#' \item \code{SUCCESS} An explicit success event above the INFO level that you want to log -#' \item \code{INFO} An event for informational purposes -#' \item \code{DEBUG} A general debugging event -#' \item \code{TRACE} A fine-grained debug message, typically capturing the flow through the application. -#' } -#' @references \url{https://logging.apache.org/log4j/2.x/javadoc/log4j-api/org/apache/logging/log4j/Level.html}, \url{https://logging.apache.org/log4j/2.x/manual/customloglevels.html} +#' +#' * `OFF` No events will be logged +#' * `FATAL` Severe error that will prevent the application from continuing +#' * `ERROR` An error in the application, possibly recoverable +#' * `WARN` An event that might possible lead to an error +#' * `SUCCESS` An explicit success event above the INFO level that you want to log +#' * `INFO` An event for informational purposes +#' * `DEBUG` A general debugging event +#' * `TRACE` A fine-grained debug message, typically capturing the flow through the application. +#' @references , #' @aliases log_levels OFF FATAL ERROR WARN SUCCESS INFO DEBUG TRACE #' @rdname log_levels #' @usage @@ -59,7 +58,7 @@ print.loglevel <- function(x, ...) { #' Convert R object into a logger log-level #' @param x string or integer -#' @return pander log-level, e.g. \code{INFO} +#' @return pander log-level, e.g. `INFO` #' @export #' @examples #' as.loglevel(INFO) diff --git a/R/logger.R b/R/logger.R index c5bc2319..d4dfc100 100644 --- a/R/logger.R +++ b/R/logger.R @@ -1,23 +1,21 @@ #' Generate logging utility #' -#' A logger consists of a log level \code{threshold}, a log message \code{formatter} function, a log record \code{layout} formatting function and the \code{appender} function deciding on the destination of the log record. For more details, see the package \code{README.md}. +#' A logger consists of a log level `threshold`, a log message `formatter` function, a log record `layout` formatting function and the `appender` function deciding on the destination of the log record. For more details, see the package `README.md`. #' -#' By default, a general logger definition is created when loading the \code{logger} package, that uses +#' By default, a general logger definition is created when loading the `logger` package, that uses #' -#' \enumerate{ -#' \item \code{\link{INFO}} (or as per the \code{LOGGER_LOG_LEVEL} environment variable override) as the log level threshold -#' \item \code{\link{layout_simple}} as the layout function showing the log level, timestamp and log message -#' \item \code{\link{formatter_glue}} (or \code{\link{formatter_sprintf}} if \pkg{glue} is not installed) as the default formatter function transforming the R objects to be logged to a character vector -#' \item \code{\link{appender_console}} as the default log record destination -#' } -#' @param threshold omit log messages below this \code{\link{log_levels}} -#' @param formatter function pre-processing the message of the log record when it's not wrapped in a \code{\link{skip_formatter}} call +#' * [INFO()] (or as per the `LOGGER_LOG_LEVEL` environment variable override) as the log level threshold +#' * [layout_simple()] as the layout function showing the log level, timestamp and log message +#' * [formatter_glue()] (or [formatter_sprintf()] if \pkg{glue} is not installed) as the default formatter function transforming the R objects to be logged to a character vector +#' * [appender_console()] as the default log record destination +#' @param threshold omit log messages below this [log_levels()] +#' @param formatter function pre-processing the message of the log record when it's not wrapped in a [skip_formatter()] call #' @param layout function rendering the layout of the actual log record #' @param appender function writing the log record -#' @return A function taking the log \code{level} to compare with the set threshold, all the \code{...} arguments passed to the formatter function, besides the standard \code{namespace}, \code{.logcall}, \code{.topcall} and \code{.topenv} arguments (see \code{\link{log_level}} for more details). The function invisibly returns a list including the original \code{level}, \code{namespace}, all \code{...} transformed to a list as \code{params}, the log \code{message} (after calling the \code{formatter} function) and the log \code{record} (after calling the \code{layout} function), and a list of \code{handlers} with the \code{formatter}, \code{layout} and \code{appender} functions. +#' @return A function taking the log `level` to compare with the set threshold, all the `...` arguments passed to the formatter function, besides the standard `namespace`, `.logcall`, `.topcall` and `.topenv` arguments (see [log_level()] for more details). The function invisibly returns a list including the original `level`, `namespace`, all `...` transformed to a list as `params`, the log `message` (after calling the `formatter` function) and the log `record` (after calling the `layout` function), and a list of `handlers` with the `formatter`, `layout` and `appender` functions. #' @export -#' @references For more details, see the Anatomy of a Log Request vignette at \url{https://daroczig.github.io/logger/articles/anatomy.html}. -#' @note It's quite unlikely that you need to call this function directly, but instead set the logger parameters and functions at \code{\link{log_threshold}}, \code{\link{log_formatter}}, \code{\link{log_layout}} and \code{\link{log_appender}} and then call \code{\link{log_levels}} and its derivatives, such as \code{\link{log_info}} directly. +#' @references For more details, see the Anatomy of a Log Request vignette at . +#' @note It's quite unlikely that you need to call this function directly, but instead set the logger parameters and functions at [log_threshold()], [log_formatter()], [log_layout()] and [log_appender()] and then call [log_levels()] and its derivatives, such as [log_info()] directly. #' @examples \dontrun{ #' do.call(logger, logger:::namespaces$global[[1]])(INFO, 42) #' do.call(logger, logger:::namespaces$global[[1]])(INFO, '{pi}') @@ -84,7 +82,7 @@ fallback_namespace <- function(namespace) { #' Base Logging Function #' @param fun_name string a full name of log function -#' @param arg see \code{\link{log_levels}} +#' @param arg see [log_levels()] #' @param namespace logger namespace #' @param index index of the logger within the namespace #' @return currently set or return log function property @@ -139,7 +137,7 @@ delete_logger_index <- function(namespace = 'global', index) { #' Get or set log level threshold -#' @param level see \code{\link{log_levels}} +#' @param level see [log_levels()] #' @param namespace logger namespace #' @param index index of the logger within the namespace #' @return currently set log level threshold @@ -161,38 +159,38 @@ delete_logger_index <- function(namespace = 'global', index) { #' ## set the log level threshold in all namespaces to ERROR #' log_threshold(ERROR, namespace = log_namespaces()) #' } -#' @seealso \code{\link{logger}}, \code{\link{log_layout}}, \code{\link{log_formatter}}, \code{\link{log_appender}} +#' @seealso [logger()], [log_layout()], [log_formatter()], [log_appender()] log_threshold <- function(level = NULL, namespace = 'global', index = 1) { log_config_setter(fun_name = 'log_threshold', arg = level, namespace = namespace, index = index) } #' Get or set log record layout -#' @param layout function defining the structure of a log record, eg \code{\link{layout_simple}}, \code{\link{layout_glue}} or \code{\link{layout_glue_colors}}, \code{\link{layout_json}}, or generator functions such as \code{\link{layout_glue_generator}}, default NULL +#' @param layout function defining the structure of a log record, eg [layout_simple()], [layout_glue()] or [layout_glue_colors()], [layout_json()], or generator functions such as [layout_glue_generator()], default NULL #' @inheritParams log_threshold #' @export #' @examples \dontrun{ #' log_layout(layout_json()) #' log_info(42) #' } -#' @seealso \code{\link{logger}}, \code{\link{log_threshold}}, \code{\link{log_appender}} and \code{\link{log_formatter}} +#' @seealso [logger()], [log_threshold()], [log_appender()] and [log_formatter()] log_layout <- function(layout = NULL, namespace = 'global', index = 1) { log_config_setter(fun_name = 'log_layout', arg = layout, namespace = namespace, index = index) } #' Get or set log message formatter -#' @param formatter function defining how R objects are converted into a single string, eg \code{\link{formatter_paste}}, \code{\link{formatter_sprintf}}, \code{\link{formatter_glue}}, \code{\link{formatter_glue_or_sprintf}}, \code{\link{formatter_logging}}, default NULL +#' @param formatter function defining how R objects are converted into a single string, eg [formatter_paste()], [formatter_sprintf()], [formatter_glue()], [formatter_glue_or_sprintf()], [formatter_logging()], default NULL #' @inheritParams log_threshold #' @export -#' @seealso \code{\link{logger}}, \code{\link{log_threshold}}, \code{\link{log_appender}} and \code{\link{log_layout}} +#' @seealso [logger()], [log_threshold()], [log_appender()] and [log_layout()] log_formatter <- function(formatter = NULL, namespace = 'global', index = 1) { log_config_setter(fun_name = 'log_formatter', arg = formatter, namespace = namespace, index = index) } #' Get or set log record appender function -#' @param appender function delivering a log record to the destination, eg \code{\link{appender_console}}, \code{\link{appender_file}} or \code{\link{appender_tee}}, default NULL +#' @param appender function delivering a log record to the destination, eg [appender_console()], [appender_file()] or [appender_tee()], default NULL #' @inheritParams log_threshold #' @export #' @examples \dontrun{ @@ -210,7 +208,7 @@ log_formatter <- function(formatter = NULL, namespace = 'global', index = 1) { #' log_info(42) #' readLines(t) #' } -#' @seealso \code{\link{logger}}, \code{\link{log_threshold}}, \code{\link{log_layout}} and \code{\link{log_formatter}} +#' @seealso [logger()], [log_threshold()], [log_layout()] and [log_formatter()] log_appender <- function(appender = NULL, namespace = 'global', index = 1) { log_config_setter(fun_name = 'log_appender', arg = appender, namespace = namespace, index = index) } @@ -239,13 +237,13 @@ log_namespaces <- function() { #' Log a message with given log level -#' @param level log level, see \code{\link{log_levels}} for more details +#' @param level log level, see [log_levels()] for more details #' @param ... R objects that can be converted to a character vector via the active message formatter function -#' @param namespace string referring to the \code{logger} environment / config to be used to override the target of the message record to be used instead of the default namespace, which is defined by the R package name from which the logger was called, and falls back to a common, global namespace. +#' @param namespace string referring to the `logger` environment / config to be used to override the target of the message record to be used instead of the default namespace, which is defined by the R package name from which the logger was called, and falls back to a common, global namespace. #' @param .logcall the logging call being evaluated (useful in formatters and layouts when you want to have access to the raw, unevaluated R expression) #' @param .topcall R expression from which the logging function was called (useful in formatters and layouts to extract the calling function's name or arguments) -#' @param .topenv original frame of the \code{.topcall} calling function where the formatter function will be evaluated and that is used to look up the \code{namespace} as well via \code{logger:::top_env_name} -#' @seealso \code{\link{logger}} +#' @param .topenv original frame of the `.topcall` calling function where the formatter function will be evaluated and that is used to look up the `namespace` as well via `logger:::top_env_name` +#' @seealso [logger()] #' @export #' @aliases log_level log_fatal log_error log_warn log_success log_info log_debug log_trace #' @usage @@ -292,7 +290,7 @@ log_namespaces <- function() { #' ## note for the JSON output, glue is not automatically applied #' log_info(glue::glue('ok {1:3} + {1:3} = {2*(1:3)}')) #' } -#' @return Invisible \code{list} of \code{logger} objects. See \code{\link{logger}} for more details on the format/ +#' @return Invisible `list` of `logger` objects. See [logger()] for more details on the format/ log_level <- function(level, ..., namespace = NA_character_, .logcall = sys.call(), .topcall = sys.call(-1), .topenv = parent.frame()) { @@ -337,8 +335,8 @@ log_level <- function(level, ..., namespace = NA_character_, #' Assure valid log level -#' @param level \code{\link{log_levels}} object or string representation -#' @return \code{\link{log_levels}} object +#' @param level [log_levels()] object or string representation +#' @return [log_levels()] object #' @keywords internal validate_log_level <- function(level) { if (inherits(level, 'loglevel')) { @@ -390,7 +388,7 @@ log_trace <- function(..., namespace = NA_character_, #' Evaluate R expression with a temporarily updated log level threshold #' @param expression R command -#' @param threshold \code{\link{log_levels}} +#' @param threshold [log_levels()] #' @inheritParams log_threshold #' @export #' @examples \dontrun{ diff --git a/R/try.R b/R/try.R index 12cb7c69..cb372eea 100644 --- a/R/try.R +++ b/R/try.R @@ -1,8 +1,8 @@ #' Try to evaluate an expressions and evaluate another expression on exception #' @param try R expression -#' @param except fallback R expression to be evaluated if \code{try} fails +#' @param except fallback R expression to be evaluated if `try` fails #' @export -#' @note Suppress log messages in the \code{except} namespace if you don't want to throw a \code{WARN} log message on the exception branch. +#' @note Suppress log messages in the `except` namespace if you don't want to throw a `WARN` log message on the exception branch. #' @examples #' everything %except% 42 #' everything <- '640kb' diff --git a/R/utils.R b/R/utils.R index 0399d7f3..61972994 100644 --- a/R/utils.R +++ b/R/utils.R @@ -42,11 +42,11 @@ top_env_name <- function(.topenv = parent.frame()) { #' Deparse and join all lines into a single line #' -#' Calling \code{deparse} and joining all the returned lines into a +#' Calling `deparse` and joining all the returned lines into a #' single line, separated by whitespace, and then cleaning up all the #' duplicated whitespace (except for excessive whitespace in strings #' between single or double quotes). -#' @param x object to \code{deparse} +#' @param x object to `deparse` #' @return string #' @export deparse_to_one_line <- function(x) { @@ -59,7 +59,7 @@ deparse_to_one_line <- function(x) { #' Catch the log header #' @return string #' @keywords internal -#' @param level see \code{\link{log_levels}} +#' @param level see [log_levels()] #' @param namespace string #' @examples #' \dontrun{ diff --git a/man/appender_async.Rd b/man/appender_async.Rd index 9da31d78..8e4ee115 100644 --- a/man/appender_async.Rd +++ b/man/appender_async.Rd @@ -12,7 +12,7 @@ appender_async( ) } \arguments{ -\item{appender}{a \code{\link{log_appender}} function with a \code{generator} attribute (TODO note not required, all fn will be passed if not)} +\item{appender}{a \code{\link[=log_appender]{log_appender()}} function with a \code{generator} attribute (TODO note not required, all fn will be passed if not)} \item{batch}{number of records to process from the queue at once} @@ -71,5 +71,5 @@ attr(my_appender, 'async_writer_process')$read_error() } } \seealso{ -This function is to be used with an actual \code{\link{log_appender}}, for example \code{\link{appender_console}}, \code{\link{appender_file}}, \code{\link{appender_tee}}, \code{\link{appender_pushbullet}}, \code{\link{appender_telegram}}, \code{\link{appender_syslog}} or \code{\link{appender_kinesis}}. +This function is to be used with an actual \code{\link[=log_appender]{log_appender()}}, for example \code{\link[=appender_console]{appender_console()}}, \code{\link[=appender_file]{appender_file()}}, \code{\link[=appender_tee]{appender_tee()}}, \code{\link[=appender_pushbullet]{appender_pushbullet()}}, \code{\link[=appender_telegram]{appender_telegram()}}, \code{\link[=appender_syslog]{appender_syslog()}} or \code{\link[=appender_kinesis]{appender_kinesis()}}. } diff --git a/man/appender_console.Rd b/man/appender_console.Rd index bd08fc6b..766f2585 100644 --- a/man/appender_console.Rd +++ b/man/appender_console.Rd @@ -16,5 +16,5 @@ appender_stderr(lines) Append log record to stderr } \seealso{ -This is a \code{\link{log_appender}}, for alternatives, see eg \code{\link{appender_stdout}}, \code{\link{appender_file}}, \code{\link{appender_tee}}, \code{\link{appender_slack}}, \code{\link{appender_pushbullet}}, \code{\link{appender_telegram}}, \code{\link{appender_syslog}}, \code{\link{appender_kinesis}} and \code{\link{appender_async}} for evaluate any \code{\link{log_appender}} function in a background process. +This is a \code{\link[=log_appender]{log_appender()}}, for alternatives, see eg \code{\link[=appender_stdout]{appender_stdout()}}, \code{\link[=appender_file]{appender_file()}}, \code{\link[=appender_tee]{appender_tee()}}, \code{\link[=appender_slack]{appender_slack()}}, \code{\link[=appender_pushbullet]{appender_pushbullet()}}, \code{\link[=appender_telegram]{appender_telegram()}}, \code{\link[=appender_syslog]{appender_syslog()}}, \code{\link[=appender_kinesis]{appender_kinesis()}} and \code{\link[=appender_async]{appender_async()}} for evaluate any \code{\link[=log_appender]{log_appender()}} function in a background process. } diff --git a/man/appender_file.Rd b/man/appender_file.Rd index c625426b..6cd04af8 100644 --- a/man/appender_file.Rd +++ b/man/appender_file.Rd @@ -64,5 +64,5 @@ log_threshold(TRACE, namespace = '.logger') } } \seealso{ -This is generator function for \code{\link{log_appender}}, for alternatives, see eg \code{\link{appender_console}}, \code{\link{appender_tee}}, \code{\link{appender_slack}}, \code{\link{appender_pushbullet}}, \code{\link{appender_telegram}}, \code{\link{appender_syslog}}, \code{\link{appender_kinesis}} and \code{\link{appender_async}} for evaluate any \code{\link{log_appender}} function in a background process. +This is generator function for \code{\link[=log_appender]{log_appender()}}, for alternatives, see eg \code{\link[=appender_console]{appender_console()}}, \code{\link[=appender_tee]{appender_tee()}}, \code{\link[=appender_slack]{appender_slack()}}, \code{\link[=appender_pushbullet]{appender_pushbullet()}}, \code{\link[=appender_telegram]{appender_telegram()}}, \code{\link[=appender_syslog]{appender_syslog()}}, \code{\link[=appender_kinesis]{appender_kinesis()}} and \code{\link[=appender_async]{appender_async()}} for evaluate any \code{\link[=log_appender]{log_appender()}} function in a background process. } diff --git a/man/appender_kinesis.Rd b/man/appender_kinesis.Rd index 44e3e71b..e3eff62e 100644 --- a/man/appender_kinesis.Rd +++ b/man/appender_kinesis.Rd @@ -19,5 +19,5 @@ Send log messages to a Amazon Kinesis stream This functionality depends on the \pkg{botor} package. } \seealso{ -This is generator function for \code{\link{log_appender}}, for alternatives, see eg \code{\link{appender_console}}, \code{\link{appender_file}}, \code{\link{appender_tee}}, \code{\link{appender_pushbullet}}, \code{\link{appender_telegram}}, \code{\link{appender_syslog}} and \code{\link{appender_async}} for evaluate any \code{\link{log_appender}} function in a background process. +This is generator function for \code{\link[=log_appender]{log_appender()}}, for alternatives, see eg \code{\link[=appender_console]{appender_console()}}, \code{\link[=appender_file]{appender_file()}}, \code{\link[=appender_tee]{appender_tee()}}, \code{\link[=appender_pushbullet]{appender_pushbullet()}}, \code{\link[=appender_telegram]{appender_telegram()}}, \code{\link[=appender_syslog]{appender_syslog()}} and \code{\link[=appender_async]{appender_async()}} for evaluate any \code{\link[=log_appender]{log_appender()}} function in a background process. } diff --git a/man/appender_pushbullet.Rd b/man/appender_pushbullet.Rd index ebe1a3e6..e7413451 100644 --- a/man/appender_pushbullet.Rd +++ b/man/appender_pushbullet.Rd @@ -7,7 +7,7 @@ appender_pushbullet(...) } \arguments{ -\item{...}{parameters passed to \code{pbPost}, such as \code{recipients} or \code{apikey}, although it's probably much better to set all these in the \code{~/.rpushbullet.json} as per package docs at \url{http://dirk.eddelbuettel.com/code/rpushbullet.html}} +\item{...}{parameters passed to \code{pbPost}, such as \code{recipients} or \code{apikey}, although it's probably much better to set all these in the \verb{~/.rpushbullet.json} as per package docs at \url{http://dirk.eddelbuettel.com/code/rpushbullet.html}} } \description{ Send log messages to Pushbullet @@ -16,5 +16,5 @@ Send log messages to Pushbullet This functionality depends on the \pkg{RPushbullet} package. } \seealso{ -This is generator function for \code{\link{log_appender}}, for alternatives, see eg \code{\link{appender_console}}, \code{\link{appender_file}}, \code{\link{appender_tee}}, \code{\link{appender_slack}}, \code{\link{appender_telegram}}, \code{\link{appender_syslog}}, \code{\link{appender_kinesis}} and \code{\link{appender_async}} for evaluate any \code{\link{log_appender}} function in a background process. +This is generator function for \code{\link[=log_appender]{log_appender()}}, for alternatives, see eg \code{\link[=appender_console]{appender_console()}}, \code{\link[=appender_file]{appender_file()}}, \code{\link[=appender_tee]{appender_tee()}}, \code{\link[=appender_slack]{appender_slack()}}, \code{\link[=appender_telegram]{appender_telegram()}}, \code{\link[=appender_syslog]{appender_syslog()}}, \code{\link[=appender_kinesis]{appender_kinesis()}} and \code{\link[=appender_async]{appender_async()}} for evaluate any \code{\link[=log_appender]{log_appender()}} function in a background process. } diff --git a/man/appender_slack.Rd b/man/appender_slack.Rd index d1553db5..78828c7a 100644 --- a/man/appender_slack.Rd +++ b/man/appender_slack.Rd @@ -33,5 +33,5 @@ Send log messages to a Slack channel This functionality depends on the \pkg{slackr} package. } \seealso{ -This is generator function for \code{\link{log_appender}}, for alternatives, see eg \code{\link{appender_console}}, \code{\link{appender_file}}, \code{\link{appender_tee}}, \code{\link{appender_pushbullet}}, \code{\link{appender_telegram}}, \code{\link{appender_syslog}}, \code{\link{appender_kinesis}} and \code{\link{appender_async}} for evaluate any \code{\link{log_appender}} function in a background process. +This is generator function for \code{\link[=log_appender]{log_appender()}}, for alternatives, see eg \code{\link[=appender_console]{appender_console()}}, \code{\link[=appender_file]{appender_file()}}, \code{\link[=appender_tee]{appender_tee()}}, \code{\link[=appender_pushbullet]{appender_pushbullet()}}, \code{\link[=appender_telegram]{appender_telegram()}}, \code{\link[=appender_syslog]{appender_syslog()}}, \code{\link[=appender_kinesis]{appender_kinesis()}} and \code{\link[=appender_async]{appender_async()}} for evaluate any \code{\link[=log_appender]{log_appender()}} function in a background process. } diff --git a/man/appender_stdout.Rd b/man/appender_stdout.Rd index 792abf08..241a14a5 100644 --- a/man/appender_stdout.Rd +++ b/man/appender_stdout.Rd @@ -13,5 +13,5 @@ appender_stdout(lines) Append log record to stdout } \seealso{ -This is a \code{\link{log_appender}}, for alternatives, see eg \code{\link{appender_console}}, \code{\link{appender_file}}, \code{\link{appender_tee}}, \code{\link{appender_slack}}, \code{\link{appender_pushbullet}} +This is a \code{\link[=log_appender]{log_appender()}}, for alternatives, see eg \code{\link[=appender_console]{appender_console()}}, \code{\link[=appender_file]{appender_file()}}, \code{\link[=appender_tee]{appender_tee()}}, \code{\link[=appender_slack]{appender_slack()}}, \code{\link[=appender_pushbullet]{appender_pushbullet()}} } diff --git a/man/appender_syslog.Rd b/man/appender_syslog.Rd index e7f6c4b3..3c8992cd 100644 --- a/man/appender_syslog.Rd +++ b/man/appender_syslog.Rd @@ -9,7 +9,7 @@ appender_syslog(identifier, ...) \arguments{ \item{identifier}{A string identifying the process.} -\item{...}{Further arguments passed on to \code{\link[rsyslog]{open_syslog}}.} +\item{...}{Further arguments passed on to \code{\link[rsyslog:syslog]{rsyslog::open_syslog()}}.} } \value{ function taking \code{lines} argument @@ -29,5 +29,5 @@ if (requireNamespace("rsyslog", quietly = TRUE)) { } } \seealso{ -This is generator function for \code{\link{log_appender}}, for alternatives, see eg \code{\link{appender_console}}, \code{\link{appender_file}}, \code{\link{appender_tee}}, \code{\link{appender_pushbullet}}, \code{\link{appender_telegram}}, \code{\link{appender_kinesis}} and \code{\link{appender_async}} for evaluate any \code{\link{log_appender}} function in a background process. +This is generator function for \code{\link[=log_appender]{log_appender()}}, for alternatives, see eg \code{\link[=appender_console]{appender_console()}}, \code{\link[=appender_file]{appender_file()}}, \code{\link[=appender_tee]{appender_tee()}}, \code{\link[=appender_pushbullet]{appender_pushbullet()}}, \code{\link[=appender_telegram]{appender_telegram()}}, \code{\link[=appender_kinesis]{appender_kinesis()}} and \code{\link[=appender_async]{appender_async()}} for evaluate any \code{\link[=log_appender]{log_appender()}} function in a background process. } diff --git a/man/appender_tee.Rd b/man/appender_tee.Rd index f78a4034..3ee0d5c4 100644 --- a/man/appender_tee.Rd +++ b/man/appender_tee.Rd @@ -27,8 +27,8 @@ appender_tee( function taking \code{lines} argument } \description{ -This appends log messages to both console and a file. The same rotation options are available as in \code{\link{appender_file}}. +This appends log messages to both console and a file. The same rotation options are available as in \code{\link[=appender_file]{appender_file()}}. } \seealso{ -This is generator function for \code{\link{log_appender}}, for alternatives, see eg \code{\link{appender_console}}, \code{\link{appender_file}}, \code{\link{appender_slack}}, \code{\link{appender_pushbullet}}, \code{\link{appender_telegram}}, \code{\link{appender_syslog}}, \code{\link{appender_kinesis}} and \code{\link{appender_async}} for evaluate any \code{\link{log_appender}} function in a background process. +This is generator function for \code{\link[=log_appender]{log_appender()}}, for alternatives, see eg \code{\link[=appender_console]{appender_console()}}, \code{\link[=appender_file]{appender_file()}}, \code{\link[=appender_slack]{appender_slack()}}, \code{\link[=appender_pushbullet]{appender_pushbullet()}}, \code{\link[=appender_telegram]{appender_telegram()}}, \code{\link[=appender_syslog]{appender_syslog()}}, \code{\link[=appender_kinesis]{appender_kinesis()}} and \code{\link[=appender_async]{appender_async()}} for evaluate any \code{\link[=log_appender]{log_appender()}} function in a background process. } diff --git a/man/appender_telegram.Rd b/man/appender_telegram.Rd index 8a9f8f43..607f64d0 100644 --- a/man/appender_telegram.Rd +++ b/man/appender_telegram.Rd @@ -27,5 +27,5 @@ Send log messages to a Telegram chat This functionality depends on the \pkg{telegram} package. } \seealso{ -This is generator function for \code{\link{log_appender}}, for alternatives, see eg \code{\link{appender_console}}, \code{\link{appender_file}}, \code{\link{appender_tee}}, \code{\link{appender_pushbullet}}, \code{\link{appender_syslog}}, \code{\link{appender_kinesis}} and \code{\link{appender_async}} for evaluate any \code{\link{log_appender}} function in a background process. +This is generator function for \code{\link[=log_appender]{log_appender()}}, for alternatives, see eg \code{\link[=appender_console]{appender_console()}}, \code{\link[=appender_file]{appender_file()}}, \code{\link[=appender_tee]{appender_tee()}}, \code{\link[=appender_pushbullet]{appender_pushbullet()}}, \code{\link[=appender_syslog]{appender_syslog()}}, \code{\link[=appender_kinesis]{appender_kinesis()}} and \code{\link[=appender_async]{appender_async()}} for evaluate any \code{\link[=log_appender]{log_appender()}} function in a background process. } diff --git a/man/catch_base_log.Rd b/man/catch_base_log.Rd index 901bc11b..ba1fbad5 100644 --- a/man/catch_base_log.Rd +++ b/man/catch_base_log.Rd @@ -12,7 +12,7 @@ catch_base_log( ) } \arguments{ -\item{level}{see \code{\link{log_levels}}} +\item{level}{see \code{\link[=log_levels]{log_levels()}}} \item{namespace}{string} } diff --git a/man/colorize_by_log_level.Rd b/man/colorize_by_log_level.Rd index 620530cd..ece6a036 100644 --- a/man/colorize_by_log_level.Rd +++ b/man/colorize_by_log_level.Rd @@ -9,7 +9,7 @@ colorize_by_log_level(msg, level) \arguments{ \item{msg}{string} -\item{level}{see \code{\link{log_levels}}} +\item{level}{see \code{\link[=log_levels]{log_levels()}}} } \value{ string with ANSI escape code diff --git a/man/formatter_glue.Rd b/man/formatter_glue.Rd index cd1493b8..2bdcf8e1 100644 --- a/man/formatter_glue.Rd +++ b/man/formatter_glue.Rd @@ -27,8 +27,8 @@ character vector Apply \code{glue} to convert R objects into a character vector } \note{ -Although this is the default log message formatter function, but when \pkg{glue} is not installed, \code{\link{formatter_sprintf}} will be used as a fallback. +Although this is the default log message formatter function, but when \pkg{glue} is not installed, \code{\link[=formatter_sprintf]{formatter_sprintf()}} will be used as a fallback. } \seealso{ -This is a \code{\link{log_formatter}}, for alternatives, see \code{\link{formatter_paste}}, \code{\link{formatter_sprintf}}, \code{\link{formatter_glue_or_sprintf}}, \code{\link{formatter_glue_safe}}, \code{\link{formatter_logging}}, \code{\link{formatter_json}}, \code{\link{formatter_pander}} and \code{\link{skip_formatter}} for marking a string not to apply the formatter on it. +This is a \code{\link[=log_formatter]{log_formatter()}}, for alternatives, see \code{\link[=formatter_paste]{formatter_paste()}}, \code{\link[=formatter_sprintf]{formatter_sprintf()}}, \code{\link[=formatter_glue_or_sprintf]{formatter_glue_or_sprintf()}}, \code{\link[=formatter_glue_safe]{formatter_glue_safe()}}, \code{\link[=formatter_logging]{formatter_logging()}}, \code{\link[=formatter_json]{formatter_json()}}, \code{\link[=formatter_pander]{formatter_pander()}} and \code{\link[=skip_formatter]{skip_formatter()}} for marking a string not to apply the formatter on it. } diff --git a/man/formatter_glue_or_sprintf.Rd b/man/formatter_glue_or_sprintf.Rd index 04a4ba8e..7e8474a2 100644 --- a/man/formatter_glue_or_sprintf.Rd +++ b/man/formatter_glue_or_sprintf.Rd @@ -46,5 +46,5 @@ formatter_glue_or_sprintf("Hi \%s, did you know that 2*4=\%s", c('foo', 'bar'), } } \seealso{ -This is a \code{\link{log_formatter}}, for alternatives, see \code{\link{formatter_paste}}, \code{\link{formatter_sprintf}}, \code{\link{formatter_glue}}, \code{\link{formatter_glue_safe}}, \code{\link{formatter_logging}}, \code{\link{formatter_json}}, \code{\link{formatter_pander}} and \code{\link{skip_formatter}} for marking a string not to apply the formatter on it. +This is a \code{\link[=log_formatter]{log_formatter()}}, for alternatives, see \code{\link[=formatter_paste]{formatter_paste()}}, \code{\link[=formatter_sprintf]{formatter_sprintf()}}, \code{\link[=formatter_glue]{formatter_glue()}}, \code{\link[=formatter_glue_safe]{formatter_glue_safe()}}, \code{\link[=formatter_logging]{formatter_logging()}}, \code{\link[=formatter_json]{formatter_json()}}, \code{\link[=formatter_pander]{formatter_pander()}} and \code{\link[=skip_formatter]{skip_formatter()}} for marking a string not to apply the formatter on it. } diff --git a/man/formatter_glue_safe.Rd b/man/formatter_glue_safe.Rd index 0f0f9e64..f651dbc0 100644 --- a/man/formatter_glue_safe.Rd +++ b/man/formatter_glue_safe.Rd @@ -27,5 +27,5 @@ character vector Apply \code{glue_safe} to convert R objects into a character vector } \seealso{ -This is a \code{\link{log_formatter}}, for alternatives, see \code{\link{formatter_glue}}, \code{\link{formatter_paste}}, \code{\link{formatter_sprintf}}, \code{\link{formatter_glue}}, \code{\link{formatter_glue_or_sprintf}}, \code{\link{formatter_logging}}, \code{\link{formatter_json}}, \code{\link{formatter_pander}} and \code{\link{skip_formatter}} for marking a string not to apply the formatter on it. +This is a \code{\link[=log_formatter]{log_formatter()}}, for alternatives, see \code{\link[=formatter_glue]{formatter_glue()}}, \code{\link[=formatter_paste]{formatter_paste()}}, \code{\link[=formatter_sprintf]{formatter_sprintf()}}, \code{\link[=formatter_glue]{formatter_glue()}}, \code{\link[=formatter_glue_or_sprintf]{formatter_glue_or_sprintf()}}, \code{\link[=formatter_logging]{formatter_logging()}}, \code{\link[=formatter_json]{formatter_json()}}, \code{\link[=formatter_pander]{formatter_pander()}} and \code{\link[=skip_formatter]{skip_formatter()}} for marking a string not to apply the formatter on it. } diff --git a/man/formatter_json.Rd b/man/formatter_json.Rd index 5372866c..ba6eaff7 100644 --- a/man/formatter_json.Rd +++ b/man/formatter_json.Rd @@ -38,5 +38,5 @@ log_info(mtcars = mtcars, species = iris$Species) } } \seealso{ -This is a \code{\link{log_formatter}} potentially to be used with \code{\link{layout_json_parser}}, for alternatives, see \code{\link{formatter_paste}}, \code{\link{formatter_sprintf}}, \code{\link{formatter_glue}}, \code{\link{formatter_glue_safe}}, \code{\link{formatter_glue_or_sprintf}}, \code{\link{formatter_logging}}, \code{\link{formatter_pander}} and \code{\link{skip_formatter}} for marking a string not to apply the formatter on it. +This is a \code{\link[=log_formatter]{log_formatter()}} potentially to be used with \code{\link[=layout_json_parser]{layout_json_parser()}}, for alternatives, see \code{\link[=formatter_paste]{formatter_paste()}}, \code{\link[=formatter_sprintf]{formatter_sprintf()}}, \code{\link[=formatter_glue]{formatter_glue()}}, \code{\link[=formatter_glue_safe]{formatter_glue_safe()}}, \code{\link[=formatter_glue_or_sprintf]{formatter_glue_or_sprintf()}}, \code{\link[=formatter_logging]{formatter_logging()}}, \code{\link[=formatter_pander]{formatter_pander()}} and \code{\link[=skip_formatter]{skip_formatter()}} for marking a string not to apply the formatter on it. } diff --git a/man/formatter_logging.Rd b/man/formatter_logging.Rd index 79754248..53171dc3 100644 --- a/man/formatter_logging.Rd +++ b/man/formatter_logging.Rd @@ -24,7 +24,7 @@ formatter_logging( character vector } \description{ -The \pkg{logging} package uses a formatter that behaves differently when the input is a string or other R object. If the first argument is a string, then \code{\link{sprintf}} is being called -- otherwise it does something like \code{\link{log_eval}} and logs the R expression(s) and the result(s) as well. +The \pkg{logging} package uses a formatter that behaves differently when the input is a string or other R object. If the first argument is a string, then \code{\link[=sprintf]{sprintf()}} is being called -- otherwise it does something like \code{\link[=log_eval]{log_eval()}} and logs the R expression(s) and the result(s) as well. } \examples{ \dontrun{ @@ -38,5 +38,5 @@ log_info(12, 1+1, 2 * 2) } } \seealso{ -This is a \code{\link{log_formatter}}, for alternatives, see \code{\link{formatter_paste}}, \code{\link{formatter_glue}}, \code{\link{formatter_glue_safe}}, \code{\link{formatter_glue_or_sprintf}}, \code{\link{formatter_json}}, \code{\link{formatter_pander}} and \code{\link{skip_formatter}} for marking a string not to apply the formatter on it. +This is a \code{\link[=log_formatter]{log_formatter()}}, for alternatives, see \code{\link[=formatter_paste]{formatter_paste()}}, \code{\link[=formatter_glue]{formatter_glue()}}, \code{\link[=formatter_glue_safe]{formatter_glue_safe()}}, \code{\link[=formatter_glue_or_sprintf]{formatter_glue_or_sprintf()}}, \code{\link[=formatter_json]{formatter_json()}}, \code{\link[=formatter_pander]{formatter_pander()}} and \code{\link[=skip_formatter]{skip_formatter()}} for marking a string not to apply the formatter on it. } diff --git a/man/formatter_pander.Rd b/man/formatter_pander.Rd index de18bb02..e564b3b7 100644 --- a/man/formatter_pander.Rd +++ b/man/formatter_pander.Rd @@ -44,5 +44,5 @@ log_info(lm(hp ~ wt, mtcars)) } } \seealso{ -This is a \code{\link{log_formatter}}, for alternatives, see \code{\link{formatter_paste}}, \code{\link{formatter_sprintf}}, \code{\link{formatter_glue}}, \code{\link{formatter_glue_safe}}, \code{\link{formatter_glue_or_sprintf}}, \code{\link{formatter_logging}} +This is a \code{\link[=log_formatter]{log_formatter()}}, for alternatives, see \code{\link[=formatter_paste]{formatter_paste()}}, \code{\link[=formatter_sprintf]{formatter_sprintf()}}, \code{\link[=formatter_glue]{formatter_glue()}}, \code{\link[=formatter_glue_safe]{formatter_glue_safe()}}, \code{\link[=formatter_glue_or_sprintf]{formatter_glue_or_sprintf()}}, \code{\link[=formatter_logging]{formatter_logging()}} } diff --git a/man/formatter_paste.Rd b/man/formatter_paste.Rd index 39a2b654..80723138 100644 --- a/man/formatter_paste.Rd +++ b/man/formatter_paste.Rd @@ -27,5 +27,5 @@ character vector Concatenate R objects into a character vector via \code{paste} } \seealso{ -This is a \code{\link{log_formatter}}, for alternatives, see \code{\link{formatter_sprintf}}, \code{\link{formatter_glue}}, \code{\link{formatter_glue_safe}}, \code{\link{formatter_glue_or_sprintf}}, \code{\link{formatter_logging}}, \code{\link{formatter_json}}, \code{\link{formatter_pander}} and \code{\link{skip_formatter}} for marking a string not to apply the formatter on it. +This is a \code{\link[=log_formatter]{log_formatter()}}, for alternatives, see \code{\link[=formatter_sprintf]{formatter_sprintf()}}, \code{\link[=formatter_glue]{formatter_glue()}}, \code{\link[=formatter_glue_safe]{formatter_glue_safe()}}, \code{\link[=formatter_glue_or_sprintf]{formatter_glue_or_sprintf()}}, \code{\link[=formatter_logging]{formatter_logging()}}, \code{\link[=formatter_json]{formatter_json()}}, \code{\link[=formatter_pander]{formatter_pander()}} and \code{\link[=skip_formatter]{skip_formatter()}} for marking a string not to apply the formatter on it. } diff --git a/man/formatter_sprintf.Rd b/man/formatter_sprintf.Rd index 86255db4..fbb7107e 100644 --- a/man/formatter_sprintf.Rd +++ b/man/formatter_sprintf.Rd @@ -30,5 +30,5 @@ character vector Apply \code{sprintf} to convert R objects into a character vector } \seealso{ -This is a \code{\link{log_formatter}}, for alternatives, see \code{\link{formatter_paste}}, \code{\link{formatter_glue}}, \code{\link{formatter_glue_safe}}, \code{\link{formatter_glue_or_sprintf}}, \code{\link{formatter_logging}}, \code{\link{formatter_json}}, \code{\link{formatter_pander}} and \code{\link{skip_formatter}} for marking a string not to apply the formatter on it. +This is a \code{\link[=log_formatter]{log_formatter()}}, for alternatives, see \code{\link[=formatter_paste]{formatter_paste()}}, \code{\link[=formatter_glue]{formatter_glue()}}, \code{\link[=formatter_glue_safe]{formatter_glue_safe()}}, \code{\link[=formatter_glue_or_sprintf]{formatter_glue_or_sprintf()}}, \code{\link[=formatter_logging]{formatter_logging()}}, \code{\link[=formatter_json]{formatter_json()}}, \code{\link[=formatter_pander]{formatter_pander()}} and \code{\link[=skip_formatter]{skip_formatter()}} for marking a string not to apply the formatter on it. } diff --git a/man/get_logger_meta_variables.Rd b/man/get_logger_meta_variables.Rd index f4880ea9..80a6dbe2 100644 --- a/man/get_logger_meta_variables.Rd +++ b/man/get_logger_meta_variables.Rd @@ -13,7 +13,7 @@ get_logger_meta_variables( ) } \arguments{ -\item{log_level}{log level as per \code{\link{log_levels}}} +\item{log_level}{log level as per \code{\link[=log_levels]{log_levels()}}} \item{namespace}{string referring to the \code{logger} environment / config to be used to override the target of the message record to be used instead of the default namespace, which is defined by the R package name from which the logger was called, and falls back to a common, global namespace.} @@ -27,28 +27,28 @@ get_logger_meta_variables( list } \description{ -Available variables to be used in the log formatter functions, eg in \code{\link{layout_glue_generator}}: +Available variables to be used in the log formatter functions, eg in \code{\link[=layout_glue_generator]{layout_glue_generator()}}: \itemize{ - \item levelr: log level as an R object, eg \code{\link{INFO}} - \item level: log level as a string, eg \code{\link{INFO}} - \item time: current time as \code{POSIXct} - \item node: name by which the machine is known on the network as reported by \code{Sys.info} - \item arch: machine type, typically the CPU architecture - \item os_name: Operating System's name - \item os_release: Operating System's release - \item os_version: Operating System's version - \item user: name of the real user id as reported by \code{Sys.info} - \item pid: the process identification number of the R session - \item node: name by which the machine is known on the network as reported by \code{Sys.info} - \item r_version: R's major and minor version as a string - \item ns: namespace usually defaults to \code{global} or the name of the holding R package of the calling the logging function - \item ns_pkg_version: the version of \code{ns} when it's a package - \item ans: same as \code{ns} if there's a defined \code{\link{logger}} for the namespace, otherwise a fallback namespace (eg usually \code{global}) - \item topenv: the name of the top environment from which the parent call was called (eg R package name or \code{GlobalEnv}) - \item call: parent call (if any) calling the logging function - \item fn: function's (if any) name calling the logging function +\item levelr: log level as an R object, eg \code{\link[=INFO]{INFO()}} +\item level: log level as a string, eg \code{\link[=INFO]{INFO()}} +\item time: current time as \code{POSIXct} +\item node: name by which the machine is known on the network as reported by \code{Sys.info} +\item arch: machine type, typically the CPU architecture +\item os_name: Operating System's name +\item os_release: Operating System's release +\item os_version: Operating System's version +\item user: name of the real user id as reported by \code{Sys.info} +\item pid: the process identification number of the R session +\item node: name by which the machine is known on the network as reported by \code{Sys.info} +\item r_version: R's major and minor version as a string +\item ns: namespace usually defaults to \code{global} or the name of the holding R package of the calling the logging function +\item ns_pkg_version: the version of \code{ns} when it's a package +\item ans: same as \code{ns} if there's a defined \code{\link[=logger]{logger()}} for the namespace, otherwise a fallback namespace (eg usually \code{global}) +\item topenv: the name of the top environment from which the parent call was called (eg R package name or \code{GlobalEnv}) +\item call: parent call (if any) calling the logging function +\item fn: function's (if any) name calling the logging function } } \seealso{ -\code{\link{layout_glue_generator}} +\code{\link[=layout_glue_generator]{layout_glue_generator()}} } diff --git a/man/grayscale_by_log_level.Rd b/man/grayscale_by_log_level.Rd index fc73cfcf..e5f942cc 100644 --- a/man/grayscale_by_log_level.Rd +++ b/man/grayscale_by_log_level.Rd @@ -9,7 +9,7 @@ grayscale_by_log_level(msg, level) \arguments{ \item{msg}{string} -\item{level}{see \code{\link{log_levels}}} +\item{level}{see \code{\link[=log_levels]{log_levels()}}} } \value{ string with ANSI escape code diff --git a/man/layout_blank.Rd b/man/layout_blank.Rd index 0ce3e827..da7d0783 100644 --- a/man/layout_blank.Rd +++ b/man/layout_blank.Rd @@ -14,7 +14,7 @@ layout_blank( ) } \arguments{ -\item{level}{log level, see \code{\link{log_levels}} for more details} +\item{level}{log level, see \code{\link[=log_levels]{log_levels()}} for more details} \item{msg}{string message} @@ -33,5 +33,5 @@ character vector Format a log record by including the raw message without anything added or modified } \seealso{ -This is a \code{\link{log_layout}}, for alternatives, see \code{\link{layout_simple}}, \code{\link{layout_glue_colors}}, \code{\link{layout_json}}, or generator functions such as \code{\link{layout_glue_generator}} +This is a \code{\link[=log_layout]{log_layout()}}, for alternatives, see \code{\link[=layout_simple]{layout_simple()}}, \code{\link[=layout_glue_colors]{layout_glue_colors()}}, \code{\link[=layout_json]{layout_json()}}, or generator functions such as \code{\link[=layout_glue_generator]{layout_glue_generator()}} } diff --git a/man/layout_glue.Rd b/man/layout_glue.Rd index 835c34e3..5faead20 100644 --- a/man/layout_glue.Rd +++ b/man/layout_glue.Rd @@ -14,7 +14,7 @@ layout_glue( ) } \arguments{ -\item{level}{log level, see \code{\link{log_levels}} for more details} +\item{level}{log level, see \code{\link[=log_levels]{log_levels()}} for more details} \item{msg}{string message} @@ -30,8 +30,8 @@ layout_glue( character vector } \description{ -By default, this layout includes the log level of the log record as per \code{\link{log_levels}}, the current timestamp and the actual log message -- that you can override via calling \code{\link{layout_glue_generator}} directly. For colorized output, see \code{\link{layout_glue_colors}}. +By default, this layout includes the log level of the log record as per \code{\link[=log_levels]{log_levels()}}, the current timestamp and the actual log message -- that you can override via calling \code{\link[=layout_glue_generator]{layout_glue_generator()}} directly. For colorized output, see \code{\link[=layout_glue_colors]{layout_glue_colors()}}. } \seealso{ -This is a \code{\link{log_layout}}, for alternatives, see \code{\link{layout_blank}}, \code{\link{layout_simple}}, \code{\link{layout_glue_colors}}, \code{\link{layout_json}}, \code{\link{layout_json_parser}}, or generator functions such as \code{\link{layout_glue_generator}} +This is a \code{\link[=log_layout]{log_layout()}}, for alternatives, see \code{\link[=layout_blank]{layout_blank()}}, \code{\link[=layout_simple]{layout_simple()}}, \code{\link[=layout_glue_colors]{layout_glue_colors()}}, \code{\link[=layout_json]{layout_json()}}, \code{\link[=layout_json_parser]{layout_json_parser()}}, or generator functions such as \code{\link[=layout_glue_generator]{layout_glue_generator()}} } diff --git a/man/layout_glue_colors.Rd b/man/layout_glue_colors.Rd index a80d1aa2..ca595d8d 100644 --- a/man/layout_glue_colors.Rd +++ b/man/layout_glue_colors.Rd @@ -14,7 +14,7 @@ layout_glue_colors( ) } \arguments{ -\item{level}{log level, see \code{\link{log_levels}} for more details} +\item{level}{log level, see \code{\link[=log_levels]{log_levels()}} for more details} \item{msg}{string message} @@ -50,5 +50,5 @@ log_fatal('The last problem.') } } \seealso{ -This is a \code{\link{log_layout}}, for alternatives, see \code{\link{layout_blank}}, \code{\link{layout_simple}}, \code{\link{layout_glue}}, \code{\link{layout_json}}, \code{\link{layout_json_parser}}, or generator functions such as \code{\link{layout_glue_generator}} +This is a \code{\link[=log_layout]{log_layout()}}, for alternatives, see \code{\link[=layout_blank]{layout_blank()}}, \code{\link[=layout_simple]{layout_simple()}}, \code{\link[=layout_glue]{layout_glue()}}, \code{\link[=layout_json]{layout_json()}}, \code{\link[=layout_json_parser]{layout_json_parser()}}, or generator functions such as \code{\link[=layout_glue_generator]{layout_glue_generator()}} } diff --git a/man/layout_glue_generator.Rd b/man/layout_glue_generator.Rd index 33ecb17a..74ab7523 100644 --- a/man/layout_glue_generator.Rd +++ b/man/layout_glue_generator.Rd @@ -12,13 +12,13 @@ layout_glue_generator( \item{format}{\code{glue}-flavored layout of the message using the above variables} } \value{ -function taking \code{level} and \code{msg} arguments - keeping the original call creating the generator in the \code{generator} attribute that is returned when calling \code{\link{log_layout}} for the currently used layout +function taking \code{level} and \code{msg} arguments - keeping the original call creating the generator in the \code{generator} attribute that is returned when calling \code{\link[=log_layout]{log_layout()}} for the currently used layout } \description{ \code{format} is passed to \code{glue} with access to the below variables: \itemize{ - \item msg: the actual log message - \item further variables set by \code{\link{get_logger_meta_variables}} +\item msg: the actual log message +\item further variables set by \code{\link[=get_logger_meta_variables]{get_logger_meta_variables()}} } } \examples{ @@ -32,5 +32,5 @@ log_info('try {runif(1)}') } } \seealso{ -See example calls from \code{\link{layout_glue}} and \code{\link{layout_glue_colors}}. +See example calls from \code{\link[=layout_glue]{layout_glue()}} and \code{\link[=layout_glue_colors]{layout_glue_colors()}}. } diff --git a/man/layout_json.Rd b/man/layout_json.Rd index 0ac61c25..84a6e177 100644 --- a/man/layout_json.Rd +++ b/man/layout_json.Rd @@ -29,5 +29,5 @@ log_info('ok {1:3} + {1:3} = {2*(1:3)}') } } \seealso{ -This is a \code{\link{log_layout}}, for alternatives, see \code{\link{layout_blank}}, \code{\link{layout_simple}}, \code{\link{layout_glue}}, \code{\link{layout_glue_colors}}, \code{\link{layout_json_parser}}, or generator functions such as \code{\link{layout_glue_generator}} +This is a \code{\link[=log_layout]{log_layout()}}, for alternatives, see \code{\link[=layout_blank]{layout_blank()}}, \code{\link[=layout_simple]{layout_simple()}}, \code{\link[=layout_glue]{layout_glue()}}, \code{\link[=layout_glue_colors]{layout_glue_colors()}}, \code{\link[=layout_json_parser]{layout_json_parser()}}, or generator functions such as \code{\link[=layout_glue_generator]{layout_glue_generator()}} } diff --git a/man/layout_json_parser.Rd b/man/layout_json_parser.Rd index a2f7fe73..d35a30a4 100644 --- a/man/layout_json_parser.Rd +++ b/man/layout_json_parser.Rd @@ -29,5 +29,5 @@ log_info(cars = row.names(mtcars), species = unique(iris$Species)) } } \seealso{ -This is a \code{\link{log_layout}} potentially to be used with \code{\link{formatter_json}}, for alternatives, see \code{\link{layout_simple}}, \code{\link{layout_glue}}, \code{\link{layout_glue_colors}}, \code{\link{layout_json}} or generator functions such as \code{\link{layout_glue_generator}} +This is a \code{\link[=log_layout]{log_layout()}} potentially to be used with \code{\link[=formatter_json]{formatter_json()}}, for alternatives, see \code{\link[=layout_simple]{layout_simple()}}, \code{\link[=layout_glue]{layout_glue()}}, \code{\link[=layout_glue_colors]{layout_glue_colors()}}, \code{\link[=layout_json]{layout_json()}} or generator functions such as \code{\link[=layout_glue_generator]{layout_glue_generator()}} } diff --git a/man/layout_logging.Rd b/man/layout_logging.Rd index c23664cd..742cdb9d 100644 --- a/man/layout_logging.Rd +++ b/man/layout_logging.Rd @@ -14,7 +14,7 @@ layout_logging( ) } \arguments{ -\item{level}{log level, see \code{\link{log_levels}} for more details} +\item{level}{log level, see \code{\link[=log_levels]{log_levels()}} for more details} \item{msg}{string message} @@ -43,5 +43,5 @@ logger_tester_function(INFO, 42) } } \seealso{ -This is a \code{\link{log_layout}}, for alternatives, see \code{\link{layout_blank}}, \code{\link{layout_glue}}, \code{\link{layout_glue_colors}}, \code{\link{layout_json}}, \code{\link{layout_json_parser}}, or generator functions such as \code{\link{layout_glue_generator}} +This is a \code{\link[=log_layout]{log_layout()}}, for alternatives, see \code{\link[=layout_blank]{layout_blank()}}, \code{\link[=layout_glue]{layout_glue()}}, \code{\link[=layout_glue_colors]{layout_glue_colors()}}, \code{\link[=layout_json]{layout_json()}}, \code{\link[=layout_json_parser]{layout_json_parser()}}, or generator functions such as \code{\link[=layout_glue_generator]{layout_glue_generator()}} } diff --git a/man/layout_simple.Rd b/man/layout_simple.Rd index 2ed33e4a..fbf0cb6c 100644 --- a/man/layout_simple.Rd +++ b/man/layout_simple.Rd @@ -14,7 +14,7 @@ layout_simple( ) } \arguments{ -\item{level}{log level, see \code{\link{log_levels}} for more details} +\item{level}{log level, see \code{\link[=log_levels]{log_levels()}} for more details} \item{msg}{string message} @@ -33,5 +33,5 @@ character vector Format a log record by concatenating the log level, timestamp and message } \seealso{ -This is a \code{\link{log_layout}}, for alternatives, see \code{\link{layout_blank}}, \code{\link{layout_glue}}, \code{\link{layout_glue_colors}}, \code{\link{layout_json}}, \code{\link{layout_json_parser}}, or generator functions such as \code{\link{layout_glue_generator}} +This is a \code{\link[=log_layout]{log_layout()}}, for alternatives, see \code{\link[=layout_blank]{layout_blank()}}, \code{\link[=layout_glue]{layout_glue()}}, \code{\link[=layout_glue_colors]{layout_glue_colors()}}, \code{\link[=layout_json]{layout_json()}}, \code{\link[=layout_json_parser]{layout_json_parser()}}, or generator functions such as \code{\link[=layout_glue_generator]{layout_glue_generator()}} } diff --git a/man/layout_syslognet.Rd b/man/layout_syslognet.Rd index 67017327..c8b6624d 100644 --- a/man/layout_syslognet.Rd +++ b/man/layout_syslognet.Rd @@ -14,7 +14,7 @@ layout_syslognet( ) } \arguments{ -\item{level}{log level, see \code{\link{log_levels}} for more details} +\item{level}{log level, see \code{\link[=log_levels]{log_levels()}} for more details} \item{msg}{string message} diff --git a/man/log_appender.Rd b/man/log_appender.Rd index 39de1560..29f6fb2d 100644 --- a/man/log_appender.Rd +++ b/man/log_appender.Rd @@ -7,7 +7,7 @@ log_appender(appender = NULL, namespace = "global", index = 1) } \arguments{ -\item{appender}{function delivering a log record to the destination, eg \code{\link{appender_console}}, \code{\link{appender_file}} or \code{\link{appender_tee}}, default NULL} +\item{appender}{function delivering a log record to the destination, eg \code{\link[=appender_console]{appender_console()}}, \code{\link[=appender_file]{appender_file()}} or \code{\link[=appender_tee]{appender_tee()}}, default NULL} \item{namespace}{logger namespace} @@ -34,5 +34,5 @@ readLines(t) } } \seealso{ -\code{\link{logger}}, \code{\link{log_threshold}}, \code{\link{log_layout}} and \code{\link{log_formatter}} +\code{\link[=logger]{logger()}}, \code{\link[=log_threshold]{log_threshold()}}, \code{\link[=log_layout]{log_layout()}} and \code{\link[=log_formatter]{log_formatter()}} } diff --git a/man/log_config_setter.Rd b/man/log_config_setter.Rd index 2dfac8c1..9bde4c96 100644 --- a/man/log_config_setter.Rd +++ b/man/log_config_setter.Rd @@ -9,7 +9,7 @@ log_config_setter(fun_name, arg, namespace, index) \arguments{ \item{fun_name}{string a full name of log function} -\item{arg}{see \code{\link{log_levels}}} +\item{arg}{see \code{\link[=log_levels]{log_levels()}}} \item{namespace}{logger namespace} diff --git a/man/log_eval.Rd b/man/log_eval.Rd index 1abead55..44070e81 100644 --- a/man/log_eval.Rd +++ b/man/log_eval.Rd @@ -9,9 +9,9 @@ log_eval(expr, level = TRACE, multiline = FALSE) \arguments{ \item{expr}{R expression to be evaluated while logging the expression itself along with the result} -\item{level}{\code{\link{log_levels}}} +\item{level}{\code{\link[=log_levels]{log_levels()}}} -\item{multiline}{setting to \code{FALSE} will print both the expression (enforced to be on one line by removing line-breaks if any) and its result on a single line separated by \code{=>}, while setting to \code{TRUE} will log the expression and the result in separate sections reserving line-breaks and rendering the printed results} +\item{multiline}{setting to \code{FALSE} will print both the expression (enforced to be on one line by removing line-breaks if any) and its result on a single line separated by \verb{=>}, while setting to \code{TRUE} will log the expression and the result in separate sections reserving line-breaks and rendering the printed results} } \description{ Evaluate an expression and log results diff --git a/man/log_formatter.Rd b/man/log_formatter.Rd index bbde7e8e..813a94f9 100644 --- a/man/log_formatter.Rd +++ b/man/log_formatter.Rd @@ -7,7 +7,7 @@ log_formatter(formatter = NULL, namespace = "global", index = 1) } \arguments{ -\item{formatter}{function defining how R objects are converted into a single string, eg \code{\link{formatter_paste}}, \code{\link{formatter_sprintf}}, \code{\link{formatter_glue}}, \code{\link{formatter_glue_or_sprintf}}, \code{\link{formatter_logging}}, default NULL} +\item{formatter}{function defining how R objects are converted into a single string, eg \code{\link[=formatter_paste]{formatter_paste()}}, \code{\link[=formatter_sprintf]{formatter_sprintf()}}, \code{\link[=formatter_glue]{formatter_glue()}}, \code{\link[=formatter_glue_or_sprintf]{formatter_glue_or_sprintf()}}, \code{\link[=formatter_logging]{formatter_logging()}}, default NULL} \item{namespace}{logger namespace} @@ -17,5 +17,5 @@ log_formatter(formatter = NULL, namespace = "global", index = 1) Get or set log message formatter } \seealso{ -\code{\link{logger}}, \code{\link{log_threshold}}, \code{\link{log_appender}} and \code{\link{log_layout}} +\code{\link[=logger]{logger()}}, \code{\link[=log_threshold]{log_threshold()}}, \code{\link[=log_appender]{log_appender()}} and \code{\link[=log_layout]{log_layout()}} } diff --git a/man/log_layout.Rd b/man/log_layout.Rd index e6a6f3d9..ef60d289 100644 --- a/man/log_layout.Rd +++ b/man/log_layout.Rd @@ -7,7 +7,7 @@ log_layout(layout = NULL, namespace = "global", index = 1) } \arguments{ -\item{layout}{function defining the structure of a log record, eg \code{\link{layout_simple}}, \code{\link{layout_glue}} or \code{\link{layout_glue_colors}}, \code{\link{layout_json}}, or generator functions such as \code{\link{layout_glue_generator}}, default NULL} +\item{layout}{function defining the structure of a log record, eg \code{\link[=layout_simple]{layout_simple()}}, \code{\link[=layout_glue]{layout_glue()}} or \code{\link[=layout_glue_colors]{layout_glue_colors()}}, \code{\link[=layout_json]{layout_json()}}, or generator functions such as \code{\link[=layout_glue_generator]{layout_glue_generator()}}, default NULL} \item{namespace}{logger namespace} @@ -23,5 +23,5 @@ log_info(42) } } \seealso{ -\code{\link{logger}}, \code{\link{log_threshold}}, \code{\link{log_appender}} and \code{\link{log_formatter}} +\code{\link[=logger]{logger()}}, \code{\link[=log_threshold]{log_threshold()}}, \code{\link[=log_appender]{log_appender()}} and \code{\link[=log_formatter]{log_formatter()}} } diff --git a/man/log_level.Rd b/man/log_level.Rd index adcac818..e309caa2 100644 --- a/man/log_level.Rd +++ b/man/log_level.Rd @@ -36,7 +36,7 @@ log_fatal(..., namespace = NA_character_, .logcall = sys.call(), .topcall = sys.call(-1), .topenv = parent.frame()) } \arguments{ -\item{level}{log level, see \code{\link{log_levels}} for more details} +\item{level}{log level, see \code{\link[=log_levels]{log_levels()}} for more details} \item{...}{R objects that can be converted to a character vector via the active message formatter function} @@ -49,7 +49,7 @@ log_fatal(..., namespace = NA_character_, \item{.topenv}{original frame of the \code{.topcall} calling function where the formatter function will be evaluated and that is used to look up the \code{namespace} as well via \code{logger:::top_env_name}} } \value{ -Invisible \code{list} of \code{logger} objects. See \code{\link{logger}} for more details on the format/ +Invisible \code{list} of \code{logger} objects. See \code{\link[=logger]{logger()}} for more details on the format/ } \description{ Log a message with given log level @@ -77,5 +77,5 @@ log_info(glue::glue('ok {1:3} + {1:3} = {2*(1:3)}')) } } \seealso{ -\code{\link{logger}} +\code{\link[=logger]{logger()}} } diff --git a/man/log_levels.Rd b/man/log_levels.Rd index 75fc8b4f..9feec555 100644 --- a/man/log_levels.Rd +++ b/man/log_levels.Rd @@ -37,15 +37,15 @@ The standard Apache logj4 log levels plus a custom level for \code{SUCCESS}. For } \details{ List of supported log levels: -\enumerate{ - \item \code{OFF} No events will be logged - \item \code{FATAL} Severe error that will prevent the application from continuing - \item \code{ERROR} An error in the application, possibly recoverable - \item \code{WARN} An event that might possible lead to an error - \item \code{SUCCESS} An explicit success event above the INFO level that you want to log - \item \code{INFO} An event for informational purposes - \item \code{DEBUG} A general debugging event - \item \code{TRACE} A fine-grained debug message, typically capturing the flow through the application. +\itemize{ +\item \code{OFF} No events will be logged +\item \code{FATAL} Severe error that will prevent the application from continuing +\item \code{ERROR} An error in the application, possibly recoverable +\item \code{WARN} An event that might possible lead to an error +\item \code{SUCCESS} An explicit success event above the INFO level that you want to log +\item \code{INFO} An event for informational purposes +\item \code{DEBUG} A general debugging event +\item \code{TRACE} A fine-grained debug message, typically capturing the flow through the application. } } \references{ diff --git a/man/log_separator.Rd b/man/log_separator.Rd index 37c038b0..10cfaa9b 100644 --- a/man/log_separator.Rd +++ b/man/log_separator.Rd @@ -15,7 +15,7 @@ log_separator( ) } \arguments{ -\item{level}{log level, see \code{\link{log_levels}} for more details} +\item{level}{log level, see \code{\link[=log_levels]{log_levels()}} for more details} \item{namespace}{string referring to the \code{logger} environment / config to be used to override the target of the message record to be used instead of the default namespace, which is defined by the R package name from which the logger was called, and falls back to a common, global namespace.} @@ -43,5 +43,5 @@ log_layout(layout_blank) log_separator(ERROR, separator = '!', width = 80) } \seealso{ -\code{\link{log_with_separator}} +\code{\link[=log_with_separator]{log_with_separator()}} } diff --git a/man/log_threshold.Rd b/man/log_threshold.Rd index 007346f9..2938ab2b 100644 --- a/man/log_threshold.Rd +++ b/man/log_threshold.Rd @@ -7,7 +7,7 @@ log_threshold(level = NULL, namespace = "global", index = 1) } \arguments{ -\item{level}{see \code{\link{log_levels}}} +\item{level}{see \code{\link[=log_levels]{log_levels()}}} \item{namespace}{logger namespace} @@ -39,5 +39,5 @@ log_threshold(ERROR, namespace = log_namespaces()) } } \seealso{ -\code{\link{logger}}, \code{\link{log_layout}}, \code{\link{log_formatter}}, \code{\link{log_appender}} +\code{\link[=logger]{logger()}}, \code{\link[=log_layout]{log_layout()}}, \code{\link[=log_formatter]{log_formatter()}}, \code{\link[=log_appender]{log_appender()}} } diff --git a/man/log_tictoc.Rd b/man/log_tictoc.Rd index dc51632f..7b7c0789 100644 --- a/man/log_tictoc.Rd +++ b/man/log_tictoc.Rd @@ -9,7 +9,7 @@ log_tictoc(..., level = INFO, namespace = NA_character_) \arguments{ \item{...}{passed to \code{log_level}} -\item{level}{see \code{\link{log_levels}}} +\item{level}{see \code{\link[=log_levels]{log_levels()}}} \item{namespace}{x} } diff --git a/man/log_with_separator.Rd b/man/log_with_separator.Rd index e7466dd5..a77f429a 100644 --- a/man/log_with_separator.Rd +++ b/man/log_with_separator.Rd @@ -15,7 +15,7 @@ log_with_separator( \arguments{ \item{...}{R objects that can be converted to a character vector via the active message formatter function} -\item{level}{log level, see \code{\link{log_levels}} for more details} +\item{level}{log level, see \code{\link[=log_levels]{log_levels()}} for more details} \item{namespace}{string referring to the \code{logger} environment / config to be used to override the target of the message record to be used instead of the default namespace, which is defined by the R package name from which the logger was called, and falls back to a common, global namespace.} @@ -45,5 +45,5 @@ log_layout(logger) log_with_separator('Boo!', level = FATAL, width = 120) } \seealso{ -\code{\link{log_separator}} +\code{\link[=log_separator]{log_separator()}} } diff --git a/man/logger.Rd b/man/logger.Rd index 93d8575c..64271ff1 100644 --- a/man/logger.Rd +++ b/man/logger.Rd @@ -7,32 +7,31 @@ logger(threshold, formatter, layout, appender) } \arguments{ -\item{threshold}{omit log messages below this \code{\link{log_levels}}} +\item{threshold}{omit log messages below this \code{\link[=log_levels]{log_levels()}}} -\item{formatter}{function pre-processing the message of the log record when it's not wrapped in a \code{\link{skip_formatter}} call} +\item{formatter}{function pre-processing the message of the log record when it's not wrapped in a \code{\link[=skip_formatter]{skip_formatter()}} call} \item{layout}{function rendering the layout of the actual log record} \item{appender}{function writing the log record} } \value{ -A function taking the log \code{level} to compare with the set threshold, all the \code{...} arguments passed to the formatter function, besides the standard \code{namespace}, \code{.logcall}, \code{.topcall} and \code{.topenv} arguments (see \code{\link{log_level}} for more details). The function invisibly returns a list including the original \code{level}, \code{namespace}, all \code{...} transformed to a list as \code{params}, the log \code{message} (after calling the \code{formatter} function) and the log \code{record} (after calling the \code{layout} function), and a list of \code{handlers} with the \code{formatter}, \code{layout} and \code{appender} functions. +A function taking the log \code{level} to compare with the set threshold, all the \code{...} arguments passed to the formatter function, besides the standard \code{namespace}, \code{.logcall}, \code{.topcall} and \code{.topenv} arguments (see \code{\link[=log_level]{log_level()}} for more details). The function invisibly returns a list including the original \code{level}, \code{namespace}, all \code{...} transformed to a list as \code{params}, the log \code{message} (after calling the \code{formatter} function) and the log \code{record} (after calling the \code{layout} function), and a list of \code{handlers} with the \code{formatter}, \code{layout} and \code{appender} functions. } \description{ A logger consists of a log level \code{threshold}, a log message \code{formatter} function, a log record \code{layout} formatting function and the \code{appender} function deciding on the destination of the log record. For more details, see the package \code{README.md}. } \details{ By default, a general logger definition is created when loading the \code{logger} package, that uses - -\enumerate{ - \item \code{\link{INFO}} (or as per the \code{LOGGER_LOG_LEVEL} environment variable override) as the log level threshold - \item \code{\link{layout_simple}} as the layout function showing the log level, timestamp and log message - \item \code{\link{formatter_glue}} (or \code{\link{formatter_sprintf}} if \pkg{glue} is not installed) as the default formatter function transforming the R objects to be logged to a character vector - \item \code{\link{appender_console}} as the default log record destination +\itemize{ +\item \code{\link[=INFO]{INFO()}} (or as per the \code{LOGGER_LOG_LEVEL} environment variable override) as the log level threshold +\item \code{\link[=layout_simple]{layout_simple()}} as the layout function showing the log level, timestamp and log message +\item \code{\link[=formatter_glue]{formatter_glue()}} (or \code{\link[=formatter_sprintf]{formatter_sprintf()}} if \pkg{glue} is not installed) as the default formatter function transforming the R objects to be logged to a character vector +\item \code{\link[=appender_console]{appender_console()}} as the default log record destination } } \note{ -It's quite unlikely that you need to call this function directly, but instead set the logger parameters and functions at \code{\link{log_threshold}}, \code{\link{log_formatter}}, \code{\link{log_layout}} and \code{\link{log_appender}} and then call \code{\link{log_levels}} and its derivatives, such as \code{\link{log_info}} directly. +It's quite unlikely that you need to call this function directly, but instead set the logger parameters and functions at \code{\link[=log_threshold]{log_threshold()}}, \code{\link[=log_formatter]{log_formatter()}}, \code{\link[=log_layout]{log_layout()}} and \code{\link[=log_appender]{log_appender()}} and then call \code{\link[=log_levels]{log_levels()}} and its derivatives, such as \code{\link[=log_info]{log_info()}} directly. } \examples{ \dontrun{ diff --git a/man/skip_formatter.Rd b/man/skip_formatter.Rd index a4cf605c..0b0cef69 100644 --- a/man/skip_formatter.Rd +++ b/man/skip_formatter.Rd @@ -7,7 +7,7 @@ skip_formatter(message, ...) } \arguments{ -\item{message}{character vector directly passed to the appender function in \code{\link{logger}}} +\item{message}{character vector directly passed to the appender function in \code{\link[=logger]{logger()}}} \item{...}{should be never set} } diff --git a/man/validate_log_level.Rd b/man/validate_log_level.Rd index 2506dc9d..73b3893a 100644 --- a/man/validate_log_level.Rd +++ b/man/validate_log_level.Rd @@ -7,10 +7,10 @@ validate_log_level(level) } \arguments{ -\item{level}{\code{\link{log_levels}} object or string representation} +\item{level}{\code{\link[=log_levels]{log_levels()}} object or string representation} } \value{ -\code{\link{log_levels}} object +\code{\link[=log_levels]{log_levels()}} object } \description{ Assure valid log level diff --git a/man/with_log_threshold.Rd b/man/with_log_threshold.Rd index afe1d52b..ef70902a 100644 --- a/man/with_log_threshold.Rd +++ b/man/with_log_threshold.Rd @@ -14,7 +14,7 @@ with_log_threshold( \arguments{ \item{expression}{R command} -\item{threshold}{\code{\link{log_levels}}} +\item{threshold}{\code{\link[=log_levels]{log_levels()}}} \item{namespace}{logger namespace}