add xml_find_function_calls() helper to source expressions

NEWS.md

@@ -40,7 +40,11 @@
 * `string_boundary_linter()` recognizes regular expression calls like `grepl("^abc$", x)` that can be replaced by using `==` instead (#1613, @MichaelChirico).
 * `unreachable_code_linter()` has an argument `allow_comment_regex` for customizing which "terminal" comments to exclude (#2327, @MichaelChirico). `# nolint end` comments are always excluded, as are {covr} exclusions (e.g. `# nocov end`) by default.
 * `format()` and `print()` methods for `lint` and `lints` classes get a new option `width` to control the printing width of lint messages (#1884, @MichaelChirico). The default is controlled by a new option `lintr.format_width`; if unset, no wrapping occurs (matching earlier behavior).
-* The `source_expression` passed to linters gains a fast way to query function call nodes using `source_expression$xml_find_function_calls()`. Use this to speed up linters using XPaths that start with `//SYMBOL_FUNCTION_CALL`. (@AshesITR, #2357)
+* The full linter suite is roughly 14% faster due to caching of the frequently used `//SMBOL_FUNCTION_CALL` XPath to examine function calls. (@AshesITR, #2357)
+  + The `source_expression` passed to linters gains a fast way to query function call nodes using `source_expression$xml_find_function_calls()`. Use this to speed up linters using XPaths that start with `//SYMBOL_FUNCTION_CALL`.
+  + The vignette on creating linters contains additional information on how to use it.
+  + Instead of `xml_find_all(source_expression$xml_parsed_content, "//SYMBOL_FUNCTION_CALL[text() = 'foo' or text() = 'bar']`, use `source_expression$xml_find_function_calls(c("foo", "bar"))`.
+  + Instead of `make_linter_from_xpath(xpath = "//SYMBOL_FUNCTION_CALL[text() = 'foo' or text() = 'bar']/cond")`, use the new `make_linter_from_function_xpath(function_names = c("foo", "bar"), xpath = "cond")`.
 
 ### New linters
 

R/system_file_linter.R

@@ -25,21 +25,23 @@
 #' @seealso [linters] for a complete list of linters available in lintr.
 #' @export
 system_file_linter <- function() {
-  funs <- c("system.file", "file.path")
   # either system.file(file.path(...)) or file.path(system.file(...))
-  xpath_parts <- glue("
-  parent::expr[following-sibling::expr/expr/SYMBOL_FUNCTION_CALL[text() = '{rev(funs)}']]
+  file_path_xpath <- "
+  parent::expr[following-sibling::expr/expr/SYMBOL_FUNCTION_CALL[text() = 'system.file']]
     /parent::expr
-  ")
+  "
+  system_file_xpath <- "
+  parent::expr[following-sibling::expr/expr/SYMBOL_FUNCTION_CALL[text() = 'file.path']]
+    /parent::expr
+  "
 
   Linter(linter_level = "expression", function(source_expression) {
-    xml_calls <- list(
-      source_expression$xml_find_function_calls(funs[1L]),
-      source_expression$xml_find_function_calls(funs[2L])
-    )
+    file_path_calls <- source_expression$xml_find_function_calls("file.path")
+    system_file_calls <- source_expression$xml_find_function_calls("system.file")
+
     bad_expr <- combine_nodesets(
-      xml_find_all(xml_calls[[1L]], xpath_parts[1L]),
-      xml_find_all(xml_calls[[2L]], xpath_parts[2L])
+      xml_find_all(file_path_calls, file_path_xpath),
+      xml_find_all(system_file_calls, system_file_xpath)
     )
 
     outer_call <- xp_call_name(bad_expr)

vignettes/creating_linters.Rmd

@@ -289,6 +289,11 @@ and so they've been tested and demonstrated their utility already.
    call_xpath <- "parent::expr/some/cond"
    xml_find_all(xml_calls, call_xpath)
    ```
+ * `make_linter_from_xpath()` and `make_linter_from_function_xpath()`: Whenever your
+   linter can be expressed by a static XPath and a static message, use `make_linter_from_xpath()`
+   or, if the XPath starts with `//SYMBOL_FUNCTION_CALL`, use `make_linter_from_function_xpath()`.
+   Instead of `make_linter_from_xpath(xpath = "//SYMBOL_FUNCTION_CALL[text() = 'foo' or text() = 'bar']/cond")`,
+   use `make_linter_from_function_xpath(function_names = c("foo", "bar"), xpath = "cond")`.
 
 ## Contributing to `{lintr}`