A function to initialize the log file.

log_open(file_name = "", logdir = TRUE, show_notes = TRUE, autolog = NULL)

Arguments

file_name

The name of the log file. If no path is specified, the working directory will be used.

logdir

Send the log to a log directory named "log". If the log directory does not exist, the function will create it. Valid values are TRUE and FALSE. The default is TRUE.

show_notes

If true, will write notes to the log. Valid values are TRUE and FALSE. Default is TRUE.

autolog

Whether to turn on autolog functionality. Autolog automatically logs functions from the dplyr, tidyr, and sassy family of packages. To enable autolog, either set this parameter to TRUE or set the "logr.autolog" option to TRUE. A FALSE value on this parameter will override the global option. The global option will override a NULL on this parameter. Default is that autolog is disabled.

Value

The path of the log.

Details

The log_open function initializes and opens the log file. This function must be called first, before any logging can occur. The function determines the log path, attaches event handlers, clears existing log files, and initiates a new log.

The file_name parameter may be a full path, a relative path, or a file name. An relative path or file name will be assumed to be relative to the current working directory. If the file_name does not have a '.log' extension, the log_open function will add it.

If requested in the logdir parameter, the log_open function will write to a 'log' subdirectory of the path specified in the file_name. If the 'log' subdirectory does not exist, the function will create it.

The log file will be initialized with a header that shows the log file name, the current working directory, the current user, and a timestamp of when the log_open function was called.

All errors, the last warning, and any log_print output will be written to the log. The log file will exist in the location specified in the file_name parameter, and will normally have a '.log' extension.

If errors or warnings are generated, a second file will be written that contains only error and warning messages. This second file will have a '.msg' extension and will exist in the specified log directory. If the log is clean, the msg file will not be created. The purpose of the msg file is to give the user a visual indicator from the file system that an error or warning occurred. This indicator msg file is useful when running programs in batch.

To use logr, call log_open, and then make calls to log_print as needed to print variables or data frames to the log. The log_print function can be used in place of a standard print function. Anything printed with log_print will be printed to the log, and to the console if working interactively.

This package provides the functionality of sink, but in much more user-friendly way. Recommended usage is to call log_open at the top of the script, call log_print as needed to log interim state, and call log_close at the bottom of the script.

Logging may be controlled globally using the "logr.on" option. This option accepts a TRUE or FALSE value. If the option is set to FALSE, logr will print to the console, but not to the log. Example: options("logr.on" = TRUE)

Notes may be controlled globally using the "logr.notes" option. This option also accepts a TRUE or FALSE value, and determines whether or not to print notes in the log. The global option will override the show_notes parameter on the log_open function. Example: options("logr.notes" = FALSE)

Version v1.2.0 of the logr package introduced autolog. The autolog feature provides automatic logging for dplyr, tidyr, and the sassy family of packages. To use autolog, set the autolog parameter to TRUE, or set the global option logr.autolog to TRUE. To maintain backward compatibility with prior versions, autolog is disabled by default.

See also

log_print for printing to the log (and console), and log_close to close the log.

Examples

# Create temp file location
tmp <- file.path(tempdir(), "test.log")

# Open log
lf <- log_open(tmp)

# Send message to log
log_print("High Mileage Cars Subset")

# Perform operations
hmc <- subset(mtcars, mtcars$mpg > 20)

# Print data to log
log_print(hmc)

# Close log
log_close()

# View results
writeLines(readLines(lf))