ast_rule: Build a rule

In astgrepr: Parse and Manipulate R Code

Build a rule

Description

Rules are the core of astgrepr. Those are used to search for nodes and are used in ⁠node_match*()⁠ and ⁠node_find*()⁠ functions. ast_rule() is a very flexible function that allows one to build simple rules but also much more complex and specific ones.

Usage

ast_rule(
  pattern = NULL,
  kind = NULL,
  regex = NULL,
  inside = NULL,
  has = NULL,
  precedes = NULL,
  follows = NULL,
  all = NULL,
  any = NULL,
  not = NULL,
  matches = NULL,
  id = NULL
)

Arguments

pattern	The pattern to look for. This can be a string or an object of class "astgrep_pattern_rule" created by pattern_rule(). This can contain meta-variables to capture certain elements. Those meta-variables can then be recovered with node_get_match() and node_get_multiple_matches(). The meta-variables must start with $ and have only uppercase letters, e.g. ⁠$VAR⁠.
kind	The kind of nodes to look for.
regex	A regex used to look for nodes. This must follow the syntax of the Rust regex crate.
inside	In which node should the node we look for be positioned? This can be another rule made with ast_rule() or an object of class "astgrep_relational_rule" created with relational_rule().
has	Same input type as inside, but this looks for nodes that contain another type of node.
precedes	Same input type as inside, but this looks for nodes that precede another type of node.
follows	Same input type as inside, but this looks for node that follow another type of node.
all	This takes one or a list of rules made with ast_rule(). It only matches nodes that respect all of the rules.
any	This takes one or a list of rules made with ast_rule(). It matches nodes that respect any of the rules.
not	This takes one or a list of rules made with ast_rule(). It excludes those nodes from the selection.
matches	This takes the id of another rule. It is useful to reuse rules.
id	The name of this rule. This can be reused in another rule with matches.

Value

A list (possibly nested) with the class "astgrep_rule".

About meta-variables

Meta-variables allow us to capture some of the content in a pattern. Usually, using $ followed by an id in uppercase letters is enough:

src <- "any(duplicated(x))"

root <- src |>
  tree_new() |>
  tree_root()

root |>
  node_find(ast_rule(pattern = "any(duplicated($A))"))
#> <List of 1 rule>
#> |--rule_1: 1 node

However, in some cases using $ is a problem. For instance, if we want to capture a column name coming after $, then we can't use $ both as code and as identifier.

src <- "df$a"

root <- src |>
  tree_new() |>
  tree_root()

root |>
  node_find(ast_rule(pattern = "df$$A"))
#> <List of 1 rule>
#> |--rule_1: 0 node

In this situation, we can use µ instead:

root |>
  node_find(ast_rule(pattern = "df$µA"))
#> <List of 1 rule>
#> |--rule_1: 1 node

Examples

ast_rule(pattern = "print($A)")

ast_rule(
  pattern = "print($A)",
  inside = ast_rule(
    any = ast_rule(
      kind = c("for_statement", "while_statement")
    )
  )
)

astgrepr documentation built on June 8, 2025, 11:05 a.m.