elixir (version 0.1.2)

expr_replace: Replace patterns within expressions

Description

Match and replace elements of patterns in an expression or a list of expressions.

Usage

expr_replace(expr, ..., patterns, replacements,
    n = Inf, env = parent.frame())

Value

The input expression(s) with any replacements made.

Arguments

expr

Input. An expression, expr_list, or list() of expressions. Also works with formulas or lists of formulas.

...

Alternating series of patterns and replacements. Each pattern should be a single expression (though alternatives can be specified with ?). Each replacement should be either a single expression or a function (see Function replacements).

patterns

Patterns to look for. An expression, expr_list, or list() of expressions.

replacements

Replacements, one for each pattern. Each can be an expression or a function (see Function replacements).

n

Maximum number of times for each expression to make each replacement; default is Inf.

env

Environment for injections in expr, pattern (see expression).

Function replacements

Normally, each replacement is an expression template with capture names (like .A or ..B) standing in for the matched parts, e.g. { .A + ..B }. But if a replacement is a function, it is called for each match and the return value is used as the replacement, e.g. function(m) substitute(A - B, m).

The function takes a single argument: a named list containing the match details. This list has elements match (the matched expression), loc (its location), and all captures named without leading dots. For example, with the pattern { ..A ^ .N } matching x^2, the function receives:

list(match = quote(x^2), loc = ..., A = quote(x), N = 2)

To build a new expression from captures, you can pass the list as the second argument to base::substitute(). A full example:

expr_replace({ x^2 + y^2 + z^3 }, { ..A ^ .N },
    function(m) {
        if (m$N == 2) substitute(square(A), m) else substitute(A ^ N, m)
    })
# => square(x) + square(y) + z^3

Details

Patterns follow the syntax for expr_match().

See Also

expr_match() to find patterns in expressions, and its cousins expr_count(), expr_detect(), expr_extract(), and expr_locate().

Examples

# Example with alternating patterns and replacements
expr_replace({ 1 + 2 }, {1}, {one}, {2}, {two})

# Example with patterns and replacements in a list
expr_replace({ 1 + 2 }, patterns = expr_list({1}, {2}),
    replacements = expr_list({one}, {two}))

# Replace with captures
expr_replace({ 1 + 2 }, ~{ .A + .B }, { .A - .B })

# Function replacement with conditional logic
expr_replace({ x^2 + y^2 + z^3 }, { ..A ^ .N },
    function(m) {
        if (m$N == 2) substitute(square(A), m) else substitute(A ^ N, m)
    })