This function replicates pattern objects, replacing placeholder keywords in each iteration with values from the provided data. This allows efficiently creating R Markdown documents with many repeating pieces which may shift alongside the underlying data.

heddle(data, pattern, ..., strip.whitespace = FALSE)



Input dataframe to pull replacement values from. Accepts either vector or dataframe inputs.


The base pattern, as either an atomic vector (which will be recycled for every value in your data) or a vector of the same length as your data (which will be applied element-wise to your data, so that data[[1]] will replace pattern[[1]]).


Values indicating what placeholders in the pattern should be replaced -- see "Specifying replacement values" below for more.


A boolean (TRUE/FALSE) value indicating if whitespace should be removed from the replacement variable. Toggle this on if you're using the variable in chunk labels or similar places.


Returns a character vector of the pattern with placeholders replaced by variables.

Specifying replacement values

heddle can accept multiple different values for ..., depending on how you call it.

If data is a vector (which is the case when either calling heddle on a vector directly, or using it in a mutate) call, ... should be unnamed strings matching the values to be replaced. If any argument passed to ... isn't found in the pattern, a warning will be raised -- use NA to replicate patterns without replacing any values.

If data is a dataframe (which is the case both when calling heddle on a dataframe directly or using it in combination with nest and map), ... should be a set of name = variable pairs, with the name matching the keyword to be replaced by that variable. Names should be quoted, variable names don't need to be. As with vectors, if any argument passed to ... isn't found in the pattern, a warning will be raised.

See also

Other manipulation functions: create_yaml_header(), make_template(), provide_parameters(), use_parameters()


# When passed a vector, heddle replaces all placeholders passed to ... # with each value spList <- unique(iris$Species) heddle(spList, "SPECIES CODE GWAR ", "GWAR")
#> [1] "SPECIES CODE setosa " "SPECIES CODE versicolor " #> [3] "SPECIES CODE virginica "
heddle(spList, "SPECIES CODE GWAR ", "GWAR", "CODE")
#> [1] "SPECIES setosa setosa " "SPECIES versicolor versicolor " #> [3] "SPECIES virginica virginica "
heddle("test string", "pattern tk", "tk", strip.whitespace = TRUE)
#> teststring #> "pattern teststring"
# When passed a dataframe, heddle uses "Name" = Variable syntax to determine # which values should replace which placeholders spList <- data.frame(Species = c(unique(iris$Species), "test string")) heddle(spList, "SPECIES CODE GWAR ", "GWAR" = Species)
#> [1] "SPECIES CODE 1 " "SPECIES CODE 2 " #> [3] "SPECIES CODE 3 " "SPECIES CODE test string "
heddle(spList, "SPECIES CODE GWAR ", "GWAR" = Species, "CODE" = Species)
#> [1] "SPECIES 1 1 " "SPECIES 2 2 " #> [3] "SPECIES 3 3 " "SPECIES test string test string "