Merge pull request #1078 from aronatkins/knit_params.yaml

Split yaml_params.yaml out of knit_params

Author: yihui

DESCRIPTION

@@ -1,13 +1,14 @@
 Package: knitr
 Type: Package
 Title: A General-Purpose Package for Dynamic Report Generation in R
-Version: 1.10.17
+Version: 1.10.18
 Date: 2015-05-06
 Authors@R: c(
     person("Adam", "Vogt", role = "ctb"),
     person("Alastair", "Andrew", role = "ctb"),
     person("Alex", "Zvoleff", role = "ctb"),
     person("Andre", "Simon", role = "ctb", comment = "the CSS files under inst/themes/ were derived from the Highlight package http://www.andre-simon.de"),
+    person("Aron", "Atkins", role = "ctb"),
     person("Ashley", "Manton", role = "ctb"),
     person("Ben", "Baumer", role = "ctb"),
     person("Brian", "Diggs", role = "ctb"),

NAMESPACE

@@ -59,6 +59,7 @@ export(knit_global)
 export(knit_hooks)
 export(knit_meta)
 export(knit_params)
+export(knit_params_yaml)
 export(knit_patterns)
 export(knit_print)
 export(knit_rd)

R/params.R

@@ -7,15 +7,17 @@
 #' the default parameter values in the R code it emits.
 #'
 #' @param text Character vector containing the document text
-#'
+#' @param evaluate If TRUE, expression values embedded within the YAML will be
+#' evaluated. This is the default. When FALSE, parameters defined by an
+#' expression will have the parsed expression in its \code{value} field.
+#' 
 #' @return List of objects of class \code{knit_param} that correspond to the
 #'   parameters declared in the \code{params} section of the YAML front matter.
 #'   These objects have the following fields:
 #'
 #'   \describe{
 #'     \item{\code{name}}{The parameter name.}
 #'     \item{\code{value}}{The default value for the parameter.}
-#'     \item{\code{class}}{The R class names of the parameter's default value.}
 #'     \item{\code{expr}}{The R expression (if any) that yielded the default value.}
 #'   }
 #'
@@ -68,7 +70,7 @@
 #' }
 #'
 #' @export
-knit_params = function(text) {
+knit_params = function(text, evaluate = TRUE) {
 
   # make sure each element is on one line
   text = split_lines(text)
@@ -78,12 +80,33 @@ knit_params = function(text) {
   if (is.null(yaml)) return(list())
 
   yaml = enc2utf8(yaml)
+  knit_params_yaml(yaml, evaluate = evaluate)
+}
+
+#' Extract knit parameters from YAML text
+#'
+#' This function reads the YAML front-matter that has already been extracted
+#' from a document and returns a list of any parameters declared there.
+#'
+#' @param yaml Character vector containing the YAML text
+#' @param evaluate If TRUE, expression values embedded within the YAML will be
+#' evaluated. This is the default. When FALSE, parameters defined by an
+#' expression will have the parsed expression in its \code{value} field.
+#'
+#' @return List of objects of class \code{knit_param} that correspond to the
+#' parameters declared in the \code{params} section of the YAML. See
+#' \code{\link{knit_params}} for a full description of these objects.
+#'
+#' @seealso \code{\link{knit_params}}
+#' 
+#' @export
+knit_params_yaml = function(yaml, evaluate = TRUE) {
   # parse the yaml using our handlers
-  parsed_yaml = yaml::yaml.load(yaml, handlers = knit_params_handlers())
+  parsed_yaml = yaml::yaml.load(yaml, handlers = knit_params_handlers(evaluate = evaluate))
 
   # if we found paramters then resolve and return them
   if (is.list(parsed_yaml) && !is.null(parsed_yaml$params)) {
-    resolve_params(mark_utf8(parsed_yaml$params))
+    resolve_params(mark_utf8(parsed_yaml$params), evaluate = evaluate)
   } else {
     list()
   }
@@ -149,14 +172,20 @@ yaml_front_matter = function(lines) {
 
 
 # define custom handlers for knitr_params
-knit_params_handlers = function() {
+knit_params_handlers = function(evaluate = TRUE) {
 
   # generic handler for r expressions where we want to preserve both the original
   # code and the fact that it was an expression.
   expr_handler = function(value) {
-    evaluated_value = eval(parse_only(value))
-    attr(evaluated_value, "expr") = value
-    evaluated_value
+    expression = parse_only(value)
+    transformed_value = if (evaluate) {
+      eval(expression)
+    } else {
+      # When we are not evaluating, provide the parsed expression as the transformed value
+      expression
+    }
+    attr(transformed_value, "expr") = value
+    transformed_value
   }
 
   list(
@@ -189,7 +218,7 @@ knit_params_handlers = function() {
 
 # resolve the raw params list into the full params data structure (with name,
 # type, value, and other optional fields included)
-resolve_params = function(params) {
+resolve_params = function(params, evaluate = TRUE) {
 
   # get the expr attribute (if any)
   expr_attr = function(value) {
@@ -241,16 +270,6 @@ resolve_params = function(params) {
     # normalize parameter value (i.e. strip attributes, list -> vector)
     param$value = param_value(param$value)
 
-    # record parameter class (must be explicit for null values)
-    if (!is.null(param$value)) {
-      param$class = class(param$value)
-    } else {
-      if (is.null(param$class))
-        stop("no class field specified for YAML parameter '", name, "'",
-             " (fields with a value of null must specify an explicit class)",
-             call. = FALSE)
-    }
-
     # add knit_param class
     param = structure(param, class = "knit_param")
 

man/knit_params.Rd

@@ -3,10 +3,14 @@
 \alias{knit_params}
 \title{Extract knit parameters from a document}
 \usage{
-knit_params(text)
+knit_params(text, evaluate = TRUE)
 }
 \arguments{
 \item{text}{Character vector containing the document text}
+
+\item{evaluate}{If TRUE, expression values embedded within the YAML will be
+evaluated. This is the default. When FALSE, parameters defined by an
+expression will have the parsed expression in its \code{value} field.}
 }
 \value{
 List of objects of class \code{knit_param} that correspond to the
@@ -16,7 +20,6 @@ List of objects of class \code{knit_param} that correspond to the
   \describe{
     \item{\code{name}}{The parameter name.}
     \item{\code{value}}{The default value for the parameter.}
-    \item{\code{class}}{The R class names of the parameter's default value.}
     \item{\code{expr}}{The R expression (if any) that yielded the default value.}
   }
 

man/knit_params_yaml.Rd

@@ -0,0 +1,26 @@
+% Please edit documentation in R/params.R
+\name{knit_params_yaml}
+\alias{knit_params_yaml}
+\title{Extract knit parameters from YAML text}
+\usage{
+knit_params_yaml(yaml, evaluate = TRUE)
+}
+\arguments{
+\item{yaml}{Character vector containing the YAML text}
+
+\item{evaluate}{If TRUE, expression values embedded within the YAML will be
+evaluated. This is the default. When FALSE, parameters defined by an
+expression will have the parsed expression in its \code{value} field.}
+}
+\value{
+List of objects of class \code{knit_param} that correspond to the
+parameters declared in the \code{params} section of the YAML. See
+\code{\link{knit_params}} for a full description of these objects.
+}
+\description{
+This function reads the YAML front-matter that has already been extracted
+from a document and returns a list of any parameters declared there.
+}
+\seealso{
+\code{\link{knit_params}}
+}

tests/testit/test-params.R

@@ -1,9 +1,14 @@
 library(testit)
 
 # helper function to convert raw src to params list
-read_params <- function(src) {
+read_params <- function(src, evaluate = TRUE) {
   lines <- strsplit(src, "\n")[[1]]
-  knit_params(lines)
+  knit_params(lines, evaluate = evaluate)
+}
+
+# helper function to convert raw src yaml to params list
+read_params_yaml <- function(src, evaluate = TRUE) {
+  knit_params_yaml(src, evaluate = evaluate)
 }
 
 
@@ -35,10 +40,10 @@ params:
 '
 )
 assert(params[[1]]$name == 'start')
-assert('Date' %in% params[[1]]$class)
+assert('Date' %in% class(params[[1]]$value))
 assert(params[[1]]$value == as.Date("2015-01-01"))
 assert(params[[2]]$name == 'end')
-assert('POSIXct' %in% params[[2]]$class)
+assert('POSIXct' %in% class(params[[2]]$value))
 assert(params[[2]]$value == as.POSIXct("2015-01-01 12:30:00", tz = "GMT"))
 
 
@@ -119,13 +124,40 @@ params:
 '
 )
 assert(!is.null(params[[1]]$expr))
-assert('Date' %in% params[[1]]$class)
+assert('Date' %in% class(params[[1]]$value))
 assert(params[[2]]$expr)
-assert('POSIXct' %in% params[[2]]$class)
+assert('POSIXct' %in% class(params[[2]]$value))
 assert(is.null(params[[3]]$expr))
 
+## test handling of unevaluated expressions --------------------------------------------
 
+params <- read_params('
+---
+params:
+  today: !r Sys.Date()
+---
+', evaluate = FALSE)
+assert(identical(params$today$expr, "Sys.Date()"))
+assert(identical(class(params$today$value), "expression"))
 
+## test handling of yaml parameters --------------------------------------------
 
+params <- read_params_yaml('
+params:
+  x: 1
+  today: !r Sys.Date()
+')
+assert(params$x$value == 1)
+assert(identical(class(params$x$value), "integer"))
+assert(identical(params$today$expr, "Sys.Date()"))
+assert('Date' %in% class(params$today$value))
 
+## test handling of unevaluated yaml parameters --------------------------------------------
+
+params <- read_params_yaml('
+params:
+  today: !r Sys.Date()
+', evaluate = FALSE)
+assert(identical(params$today$expr, "Sys.Date()"))
+assert(identical(class(params$today$value), "expression"))