qlcheckr is an R package designed to analyse parsed user code by searching for specific patterns within its Abstract Syntax Tree (AST). The package is ideal for interactive code evaluation in Quarto Live environments, enabling precise checks for function usage, arguments, and expressions.

The qlcheckr package is designed with minimal dependencies to ensure a lightweight footprint, making it an ideal choice for integration with Quarto Live environments. By avoiding external package dependencies, qlcheckr significantly reduces file size and load times. The package design prioritises simplicity and speed, providing helpful tools without unnecessary bloat.

• Function Usage Detection: Verify if a specific function is used in the code.
• Argument Matching: Identify the presence of specific arguments in function calls.
• Expression Searching: Detect custom expressions within the code.
• Flexible Pattern Matching: Combine searches for functions, arguments, and expressions.

To install the development version of qlcheckr from GitHub, use the remotes package:

# Install remotes if not already installed
install.packages("remotes")

# Install qlcheckr
remotes::install_github("learnr-academy/qlcheckr")

The search_ast function allows you to search for specific patterns in parsed R code.

library(qlcheckr)

code <- quote(mean(x))
search_ast(code, .fn = "mean")
#> [1] FALSE

code <- quote(mean(x, na.rm = TRUE))
search_ast(code, na.rm = TRUE)
#> [1] TRUE
search_ast(code, na.rm = FALSE)
#> [1] FALSE

code <- quote(mean(x + y))
search_ast(code, .expr = x + y)
#> [1] TRUE

The exists_in() function checks whether elements in a list satisfy specific conditions. It is particularly useful when working with multiple outputs to pinpoint a result or identify errors.

The .evaluate_result object available in the check chunk of quarto-live exercises contains information about results, errors, warnings, messages and more. A manually constructed .evaluate_result is shown here for testing purposes:

.evaluate_result <- evaluate::evaluate(
'print(rnorm(10))
sample$x
log(-1)
message("Hello world")',
output_handler = ql_output_handler)

Suppose you are processing a list of numeric outputs and want to find if any value is greater than a threshold:

ql_results()
#> [[1]]
#>  [1] -0.6264538  0.1836433 -0.8356286  1.5952808  0.3295078 -0.8204684
#>  [7]  0.4874291  0.7383247  0.5757814 -0.3053884
#> 
#> [[2]]
#> [1] NaN
#> 
#> [[3]]
#> NULL

exists_in(ql_results(), ~ any(. > 0.5))
#> [1] TRUE

This helps quickly confirm if any result (among many outputs) passes your test.

Consider checking code that might generate errors, which can be obtained in Quarto Live check environments with the ql_errors() helper. exists_in() can again be used to search for specific errors.

ql_errors()
#> [1] "object of type 'closure' is not subsettable"

exists_in(ql_errors(), grepl, pattern = "not subsettable")
#> [1] TRUE
exists_in(ql_errors(), grepl, pattern = "non-numeric argument")
#> [1] FALSE

This is valuable for identifying and debugging specific errors among many possible results.

It is also possible to search warnings and messages with similar helpers:

ql_warnings()
#> [1] "NaNs produced"
ql_messages()
#> [1] "Hello world\n"

We welcome contributions to qlcheckr! If you encounter any issues or have suggestions for improvement, please open an issue or submit a pull request on GitHub.

qlcheckr is licensed under the MIT License. See the LICENSE file for details.