knit_params: Extract knit parameters from a document

Description

This function reads the YAML front-matter section of a document and returns a list of any parameters declared there. This function exists primarily to support the parameterized reports feature of the rmarkdown package, however is also used by the knitr purl function to include the default parameter values in the R code it emits.

Usage

knit_params(text, evaluate = TRUE)

Arguments

text

Character vector containing the document text.

evaluate

Boolean. If TRUE (the default), expression values embedded within the YAML will be evaluated. If FALSE, parameters defined with an expression will have the parsed but unevaluated expression in their value field.

Value

List of objects of class knit_param that correspond to the parameters declared in the params section of the YAML front matter. These objects have the following fields:

name: The parameter name.
value: The default value for the parameter.
expr: The R expression (if any) that yielded the default value.

In addition, other fields included in the YAML may also be present alongside the name, type, and value fields (e.g. a label field that provides front-ends with a human readable name for the parameter).

Details

Parameters are included in YAML front matter using the params key. This key can have any number of subkeys each of which represents a parameter. For example:

---
title: My Document
output: html_document
params:
  frequency: 10
  show_details: true
---

Parameter values can be provided inline as illustrated above or can be included in a value sub-key. For example:

---
title: My Document
output: html_document
params:
  frequency:
    value: 10
---

This second form is useful when you need to provide additional details about the parameter (e.g. a label field as describe above).

You can also use R code to yield the value of a parameter by prefacing the value with !r, for example:

---
title: My Document
output: html_document
params:
  start: !r Sys.Date()
---