Report

Print a character string or a data object into a same output file. Convenient for log file generation.

Usage

report(
  data,
  output = "log.txt",
  path,
  append = FALSE,
  rownames_kept = FALSE,
  vector_cat = FALSE,
  noquote = TRUE,
  sep = 2,
  safer_check = TRUE,
  lib_path = NULL,
  error_text = ""
)

Arguments

data

Object to print in the output file. If NULL, nothing is done, with no warning.

output

Single character string. Name of the output file.

path

Single character string indicating the path where to write the output file.

append

Single logical value. If the output file already exists and append is FALSE, an error message is returned (no overwrite of existing file). Otherwise, the printing is appended (and the output file is created if it does not exist yet).

rownames_kept

Single logical value. Defines whether row names have to be removed or not in 2D objects. Warning: in 1D tables, names over the values are taken as row names, and are thus removed if rownames_kept is FALSE.

vector_cat

Single logical value. If TRUE, print a vector of length > 1 using cat() instead of capture.output(). Otherwise (default FALSE) print a vector of length > 1 using capture.output(). Names of values are not printed when TRUE.

noquote

Single logical value. If TRUE no quote are added to the returned character strings.

sep

Single non null and positive integer representing the number of empty lines added in the output file after the printed data.

safer_check

Single logical value. Perform some "safer" checks? If TRUE, checkings are performed before main code running (see the safer-r project): 1) correct lib_path argument value 2) required functions and related packages effectively present in local R libraries and 3) R classical operators (like "<-") not overwritten by another package because of the R scope. Must be set to FALSE if this function is used inside another "safer" function to avoid pointless multiple checkings.

lib_path

Vector of characters specifying the absolute pathways of the directories containing the required packages for the function, if not in the default directories. Useful when R packages are not installed in the default directories because of lack of admin rights. More precisely, lib_path is passed through the new argument of .libPaths() so that the new library paths are unique(c(new, .Library.site, .Library)). Warning: .libPaths() is restored to the initial paths, after function execution. Ignored if NULL (default) or if the safer_check argument is FALSE: only the pathways specified by the current .libPaths() are used for package calling.

error_text

Single character string used to add information in error messages returned by the function, notably if the function is inside other functions, which is practical for debugging. Example: error_text = " INSIDE <PACKAGE_1>::<FUNCTION_1> INSIDE <PACKAGE_2>::<FUNCTION_2>.". If NULL, converted into "".

Value

Nothing (implementation of an existing file) or a text file.

See also

capture.output.

Author

Gael Millot

Yushi Han

Haiding Wang

Examples

# Warning: these examples may not work well when using the "Run examples" link 
# because of a particular environment. Please, copy-paste in a local environment.
# See also https://safer-r.github.io/saferDev/articles/report.html
if (FALSE) {
# Example that creates a file/folder in the working directory
saferDev::report(data = "THE FOLLOWING VECTOR IS:\n", output = "results.txt", path = ".", 
append = TRUE, sep = 1)
saferDev::report(data = 1:3, output = "results.txt", path = ".", append = TRUE, 
rownames_kept = FALSE, vector_cat = FALSE, noquote = FALSE, sep = 2)
saferDev::report(data = "THE FOLLOWING MATRIX IS:\n", output = "results.txt", path = ".", 
append = TRUE, sep = 1)
saferDev::report(data = matrix(1:5), output = "results.txt", path = ".", append = TRUE, 
rownames_kept = FALSE, vector_cat = FALSE, noquote = FALSE, sep = 5)
saferDev::report(data = "THE FOLLOWING DATA FRAME IS:\n", output = "results.txt", path = ".", 
append = TRUE, sep = 1)
saferDev::report(data = data.frame(A = 1:8, B = letters[1:8]), output = "results.txt", path = ".", 
append = TRUE, rownames_kept = FALSE, vector_cat = FALSE, noquote = FALSE, sep = 1)
}