orderly (version 1.0.4)

orderly_log_on: Orderly logging and diagnostic messages

Description

Start and stop the orderly log. When active, some actions will print diagnostic information to the message stream. This is set to be on by default.

Usage

orderly_log_on()
orderly_log_off()
orderly_log(topic, value)

Arguments

topic

Up to 9 character text string with the log topic

value

Character string with the log entry

Value

orderly_log_on and orderly_log_off invisibly returns a logical indicating if logging was previously enabled. This allows patterns like:

if (!orderly::orderly_log_off()) {
  on.exit(orderly::orderly_log_on())
}

to disable logging within a function (the on.exit block will be run when the function exits).

Details

The function orderly_log is designed to be used from applications that extend orderly, while the functions orderly_log_on and orderly_log_off can be used by applications or users to enable and disable log messages.

The interface here may expand by adding arguments or change behaviour based on global options. Future versions may support logging to a file, or adding timestamps, or logging in json format, etc.

See Also

orderly_run, which makes use of these log messages

Examples

# NOT RUN {
# We are going to log things below
logging_was_enabled <- orderly::orderly_log_on()

path <- orderly::orderly_example("minimal")

# By default we get both orderly log messages (e.g.,
# "[name] example") and the output of R when it runs the report:
orderly::orderly_run("example", root = path)

# Passing FALSE to the echo argument suppresses R's output but not
# orderly messages:
orderly::orderly_run("example", root = path, echo = FALSE)

# Disabling the log suppresses orderly's messages but still
# displays R's output:
orderly::orderly_log_off()
orderly::orderly_run("example", root = path)

# And using both will prevent all output
orderly::orderly_run("example", root = path, echo = FALSE)

# About orderly log messages:
# Orderly log messages have the form "[title] message"
orderly::orderly_log_on()
orderly::orderly_log("title", "message")

# If logging is disabled they are not printed:
orderly::orderly_log_off()
orderly::orderly_log("title", "message")

# Restore to previous settings:
if (logging_was_enabled) {
  orderly::orderly_log_on()
}
# }

Run the code above in your browser using DataCamp Workspace