Find matches in text

match_text() searches text that has already been read into R. It is the text-level counterpart of match_files(): it does not read from disk and does not record file encoding information.

Usage

match_text(text, path, pattern, replacement = NULL, ..., context = 5L)

Arguments

text

Text content as a single string.

path

Source identifier associated with text. This is stored in the resulting seekr_match object and used later for inspection and diagnostics. It may be a real file path, but it does not need to point to an existing file unless the result is later passed to replace_files().

pattern

Pattern to search for, matched using stringr (ICU regular expressions). Either:

• A string, automatically wrapped as stringr::regex() with ignore_case = FALSE, multiline = TRUE, comments = FALSE, and dotall = FALSE.

• A stringr_pattern object such as stringr::regex(), stringr::fixed(), or stringr::coll(), used as-is for more control.

replacement

Replacement to associate with each match. Replacements are computed immediately during the search and stored in the result. Either:

• NULL (default): no replacement. replace_files() cannot be called without setting replacements first.

• A plain string, used literally as replacement text.

• A string with backreferences of the form \1, \2, etc., replaced with the corresponding capture group from pattern.

• A function, called once per file with a character vector of all matches found in that file, and expected to return a character vector of the same length (e.g. toupper).

• A function wrapped with with_capture_groups_matrix(), called once per file with a character matrix where the first column is the full match and the remaining columns are the capture groups.

...

These dots are for future extensions and must be empty.

context

Number of surrounding lines to capture around each match. Either:

• A single non-negative integer (default: 5L): captures the same number of lines before and after each match.

• A pair of non-negative integers c(before, after): captures before lines before and after lines after each match.

Value

A seekr_match vector.

Details

The resulting seekr_match vector can be inspected, summarized, filtered, updated, and passed to replace_text(). It is not intended to be passed to replace_files(), because seekr did not read the source file and does not control how the text was decoded.

Use match_files() or seek()/seekr() for the usual file workflow.

Examples

text <- "Commodo labore culpa ullamco TODO irure laboris FIXME Lorem sunt sint"
x <- match_text(text = text, path = "lorem.txt", pattern = "TODO")
y <- match_text(text = text, path = "lorem.txt", pattern = "FIXME")
z <- c(x, y)
z
#> <seekr::match[2]> 1 source
#> lorem.txt [2]
#> [1] -> 1 | Commodo labore culpa ullamco TODO irure laboris FIXME Lorem sunt sint
#> [2] -> 1 | Commodo labore culpa ullamco TODO irure laboris FIXME Lorem sunt sint
#>