all_args_here — all_args_here • saferDev

Verify that all the functions used inside a function are written with all their arguments. For instance: base::paste0(letters[1:2], collapse = NULL, recycle0 = FALSE) and not paste0(letters[1:2]).

Usage

all_args_here(
  x,
  export = FALSE,
  path_out = ".",
  df_name = "res.tsv",
  overwrite = FALSE,
  safer_check = TRUE,
  lib_path = NULL,
  error_text = ""
)

Arguments

x: Function name, written without quotes and brackets.
export: Single logical value. Export the data frame into a .tsv file? If TRUE, the data frame is not returned by the function but only exported.
path_out: Single character string indicating the absolute pathway of the folder where to export the data frame. path_out = "." means the R working directory set by the user. Ignored if export is FALSE
df_name: Single character string indicating the name of the exported data frame file. Ignored if export is FALSE.
overwrite: Single logical value. Overwrite potential df_name file already existing in path_out? Ignored if export is FALSE.
safer_check: Single logical value. Perform some "safer" checks? If TRUE, checkings are performed before main code running (see https://github.com/safer-r): 1) correct lib_path argument value 2) required functions and related packages effectively present in local R lybraries and 3) R classical operators (like "<-") not overwritten by another package because of the R scope. Must be set to FALSE if this fonction 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 package 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

A data frame indicating the missing arguments or a message saying that everything seems fine. If export argument is TRUE, then the data frame is exported as res.tsv instead of being returned. Data frame: $LINE_NB: the line number in the function code (starting at the "<- function" line, i.e., without counting the #' header lines) $FUN_NAME: the function name. $FUN_ARGS: the written arguments of $FUN_NAME. "NOT_CONSIDERED" means that the function is between quotes or after $ $FUN_POS: the position of the first character of the function name in the $LINE_NB line of the code. $DEF_ARGS: the defaults arguments of $FUN_NAME. "NO_ARGS" means that the function has no arguments. "INTERNAL_FUNCTION" means that the function has been created inside the checked function. "SKIPPED" means that the function is not analyzed for the reason indicated in the "details" section below. $MISSING_ARG_NAMES: the missing argument names in $FUN_ARGS. $MISSING_ARGS: the missing arguments with their values in $FUN_ARGS. $STATUS: either "GOOD", meaning that all the arguments are already written, or a new proposal of arguments writing, or indicates if some arguments are not fully written (abbreviation is discouraged), or nothing.

An additionnal message "EVERYTHING SEEMS CLEAN" if the $STATUS column is only made of "" and "GOOD".

Details

More precisely, all_args_here() verifies that all the strings before an opening bracket "(" are written with all their arguments. Thus, it cannot check function names written without brackets, like in the FUN argument of some functions, e.g., sapply(1:3, FUN = as.character).

The perl regex used to detect a function name is: "([a-zA-Z]|\.[a-zA-Z._])[a-zA-Z0-9._]*\s*\(".

Currently, all_args_here() cannot detect functions written between quotes, like "+"() or "rownames<-"(x, "a").

Function names preceeded by $ are not considered.

The following R functions are skipped: "function", "if", "for", "while", "repeat" and "else".

Warning: the following R functions are also skipped (as indicated by "SKIPPED" in the $DEF_ARGS column of the returned data frame) for the indicated reason: "as.environment" (https://bugs.r-project.org/show_bug.cgi?id=18849).

Warning: some functions, like rownames(), have different arguments depending on whether something is assigned to it (e.g., rownames(x) <- "a") or not. The all_args_here() function always propose the arguments defined in the help page without assignement, meaning that is cannot detect the assignation. A way to by-pass this is to use the "exact" writing of the function. For instance, base::"rownames<-"(x, "a") instead of using base::rownames(x) <- "a", and use getAnywhere("rownames<-") to see the arguments of the function.

Most of the time, all_args_here() does not check inside comments, but some unexpected writing could dupe all_args_here(). Please, report here https://github.com/safer-r/saferDev/issues if it is the case.

The returned line numbers are indicative, depending on which source is checked. For instance, saferDev::report (compiled) has not the same line numbers as its source file (https://github.com/safer-r/saferDev/blob/main/R/report.R). Notably, compiled functions do not have comments anymore, compared to the same source function sourced into the working environment. In addition, the counting starts at the "<- function" line, i.e., without counting the #' header lines potentially present in source files.

The function works by notably replacing first in the code: 1) the three consecutive characters "'" or '"' by three spaces, 2) "\"'" and '\'"' by four spaces and 3) escape quotes like \" or \' by two spaces.

Warnings: 1) The function could not properly work if any comma is present in default argument values. Please, report here https://github.com/safer-r/saferDev/issues if it is the case.

2) Proposals in the STATUS column are only suggestions, as it is difficult to anticipate all the exceptions with arguments writing.

Author

Gael Millot

Examples

if (FALSE)  # Example that return an error
all_args_here(mean) # example that return an error
source("https://raw.githubusercontent.com/safer-r/saferDev/main/dev/other/test2.R") ; all_args_here(test2) # the checked function must be executable
#> Error: 
#> 
#> ================
#> 
#> ERROR IN saferDev:::.all_args_here_fill() INSIDE saferDev::all_args_here().
#> 
#> THE TESTED FUNCTION test2 SEEMS TO HAVE A WRITING ERROR IN LINE 13 AND FUNCTION length.
#> PLEASE, RUN THE TESTED FUNCTION FIRST.
#> 
#> ================
#> 

FUN2 <- function(x, y){middle_bracket2 <- base::do.call(what = base::c, args = code_for_col, quote = FALSE, envir = base::parent.frame())}
all_args_here(FUN2, safer_check = FALSE)
#> 
#> INSIDE FUN2(), ARGUMENTS ARE MISSING.
#> 
#>   LINE_NB     FUN_NAME
#> 1       1      do.call
#> 2       1 parent.frame
#>                                                                                    FUN_ARGS
#> 1 do.call(what = base::c, args = code_for_col, quote = FALSE, envir = base::parent.frame())
#> 2                                                                            parent.frame()
#>   FUN_POS                                          DEF_ARGS MISSING_ARG_NAMES
#> 1      41 what, args, quote = FALSE, envir = parent.frame()                  
#> 2     115                                             n = 1                 n
#>   MISSING_ARGS              STATUS
#> 1                             GOOD
#> 2        n = 1 parent.frame(n = 1)
source("https://raw.githubusercontent.com/safer-r/.github/refs/heads/main/profile/backbone.R")
all_args_here(BACKBONE, export = TRUE, safer_check = FALSE)
#> 
#> AFTER RUNNING all_args_here() OF THE saferDev PACKAGE:
#> RESULT EXPORTED IN:
#> ./res.tsv
#> BUT INSIDE BACKBONE(), EVERYTHING SEEMS CLEAN.
#>