heddlr (version 0.6.0)

heddle: Transform pattern objects into template pieces

Description

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.

Usage

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

Arguments

data

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

pattern

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.

strip.whitespace

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.

Value

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()

Examples

# NOT RUN {
# When passed a vector, heddle replaces all placeholders passed to ...
# with each value
spList <- unique(iris$Species)
heddle(spList, "SPECIES CODE GWAR ", "GWAR")
heddle(spList, "SPECIES CODE GWAR ", "GWAR", "CODE")
heddle("test string", "pattern tk", "tk", strip.whitespace = TRUE)

# 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)
heddle(spList, "SPECIES CODE GWAR ", "GWAR" = Species, "CODE" = Species)
# }