source.all: Source all programs in a directory

Description

A function to source all programs in a specified directory. The function will run each R program file in the directory, and then return a data frame of results of the run.

Usage

source.all(path = ".", pattern = NULL, exclude = NULL, isolate = TRUE)

Value

A data frame of the results of the source operation. The data frame will show each file sourced, the time started, the time ended, the status, and any error messages. The status value is either 0 (no errors) or 1 (errors).

Arguments

path: The directory to source programs from. Default is the current working directory.
pattern: A full or partial name of the programs to source. If partial, use the question mark (?) or asterisk (*) characters to indicate the missing piece(s). Default is NULL, which will return all programs. You may pass multiple patterns as a vector. In that case, the function will perform an "or" operation on each pattern. Note that it is not necessary to include the ".R" file extension in your patterns. It is assumed that all source files have a ".R" extension.
exclude: A vector of patterns to exclude from the included programs. The exclusion patterns can be the names of specific programs or a wild card exclusion. The asterisk (*) and question mark (?) characters may be used to indicate partial matches. Similar to the "pattern" parameter, the ".R" file extension can be ignored.
isolate: Whether to isolate each source call to its own environment. Valid values are TRUE, FALSE, or an environment to run in. If the isolate parameter is FALSE, the programs will run in the global environment. Default is TRUE.

Result Dataset

The source.all function returns a dataset showing the results of the source operation. There will be one row for each program executed. The return dataset has the following columns:

Filename: The name of the program.
StartTime: The date and time execution started.
EndTime: The date and time execution ended.
Status: A numeric value indicating whether or not the program returned errors or warnings. A zero (0) value indicates that no errors occurred. A one (1) value indicates that an error occurred. Warnings can also be generated along with an error, but the status will still be one (1). A two (2) value indicates that warnings occurred but no errors. Note that capture of warnings is less reliable than the capture of errors. It is possible that a program may generate a warning and still return a zero (0) status. If you want to ensure that warnings are detected, convert them to errors with options(warn = 2).
Message: If errors or warnings are returned from the program, they will be shown in this column. Multiple messages will be separated with a semi-colon (;) and a carriage return.

In addition to the information shown above, the results dataset will have attributes assigned with the parameter values passed to the function. Those attributes can be observed with the Base R attributes() function.

Source Isolation

Multiple programs running in the same environment have a risk of conflicting variables or data. Variables created by the first program can possibly interfere with the running of the next program. Or they could conflict with variables in the global environment. To avoid such conflicts, each program is run in its own environment by default. isolate = TRUE starts each program with a clean workspace, and is the best choice for running programs in batch.

There may be situations, however, where you do not want to isolate the source calls. For example, if you are loading functions from a utility library, you may actually wanted them loaded into the global environment so they can by accessed by you or your programs. In this case, set the "isolate" parameter to FALSE.

Lastly, there may be situations where you want to intentionally share an environment, or extract values create by the running programs. In this case, you can instantiate a new environment yourself, and pass that to the "isolate" parameter instead of TRUE or FALSE. Note that this environment will be shared by all programs, but will not have access to the global environment.

Details

The source.all function attempts to run all programs in a directory. This function is useful for batch runs. It has parameters to control which programs are run or not run. By default, the function will run all programs in the working directory. You can use the "pattern" and "exclude" parameters to specify individual program names, or wild card matches. Inclusion and exclusion patterns are case-insensitive.

Note that the function will run all programs, regardless of any errors. Errors will be indicated in the "Status" and "Message" columns of the result dataset.

Examples

Run this code

# Create temp directory
tmp <- tempdir()

# Write program 1
p1 <- file(file.path(tmp, "prog1.R"))
writeLines("print('Hello from program 1')", p1)
close(p1)

# Write program 2
p2 <- file(file.path(tmp, "prog2.R"))
writeLines("stop('Error from program 2')", p2)
close(p2)

# Write program 3
p3 <- file(file.path(tmp, "prog3.R"))
writeLines("print('Hello from program 3')", p3)
close(p3)

# Example #1: Run all programs
res1 <- source.all(tmp)
# [1] "Hello from program 1"
# [1] "Hello from program 3"

# View results
res1
#   Filename           StartTime             EndTime Status              Message
# 1  prog1.R 2024-03-05 10:12:04 2024-03-05 10:12:04      0              Success
# 2  prog2.R 2024-03-05 10:12:04 2024-03-05 10:12:04      1 Error from program 2
# 3  prog3.R 2024-03-05 10:12:04 2024-03-05 10:12:04      0              Success

#' # Example #2: Exclusion criteria
res2 <- source.all(tmp, exclude = "prog2")
# [1] "Hello from program 1"
# [1] "Hello from program 3"

# View results
res2
# Filename           StartTime             EndTime Status Message
# 1  prog1.R 2024-03-05 10:13:24 2024-03-05 10:13:24      0 Success
# 2  prog3.R 2024-03-05 10:13:24 2024-03-05 10:13:24      0 Success

# Example #3: Inclusion criteria
res3 <- source.all(tmp, pattern = "*2")

# View results
res3
#   Filename           StartTime             EndTime Status              Message
# 1  prog2.R 2024-03-05 10:16:41 2024-03-05 10:16:41      1 Error from program 2

# View attributes
attributes(res3)
# $names
# [1] "Filename"  "StartTime" "EndTime"   "Status"    "Message"
#
# $class
# [1] "data.frame"
#
# $row.names
# [1] 1
#
# $path
# [1] "C:\Users\dbosa\AppData\Local\Temp\RtmpGAXYJl"
#
# $pattern
# [1] "*2.R"
#
# $errors
# [1] 1

Run the code above in your browser using DataLab