brew.Rdbrew provides a templating system for text reporting. The syntax is similar to PHP,
Java Server Pages, Ruby's erb module, and Python's psp module.
brew(file=stdin(),output=stdout(),text=NULL,envir=parent.frame(),
run=TRUE,parseCode=TRUE,tplParser=NULL,chdir=FALSE, extendedErrorReport=FALSE)A connection, or a character string naming the file to read from. stdin() is the default.
A connection, or a character string naming the file to print to. stdout() is the default.
A character string treated as if it contained lines of a file
to read from. Only one of file or text is used as input.
Default is NULL.
the environment in which the input is to
be evaluated. Default is the caller's environment, useful for
nested brew calls.
Logical to determine if brew should evaluate the input (run=TRUE) or
just parse it (run=FALSE). Useful for debugging.
Logical. only relevant when run=FALSE. When TRUE the brewed code is parsed and then silently returned. When FALSE, the brewed code is returned as a list. See the Value section for details.
a function to parse the text between '<%%' and '%%>' and return the result as a character vector. The template text is passed to the function as a variable length character vector in the first argument position.
logical; if TRUE and file is a pathname, the R working
directory is temporarily changed to the directory containing
file for evaluating. brew will also honor the global option brew.chdir.
changes error handling behaviour to print a stack trace when an error occurs, the global option brew.extended.error can also be used to achive the same effect. Existing brew behaviour is preserved if this switch is not set to TRUE.
brew syntax is quite simple and there are very few delimiters to learn:
1. All text that falls outside of the delimiters is printed as-is.
2. R expressions between the '<%' and '%>' delimiters are executed in-place.
3. The value of the R expression between the '<%=' and '%>' delimiters is printed.
4. All text between the '<%#' and '%>' delimiters is thrown away. Use it as a comment.
5. If you place a '-' just before the '%>' delimiter, and it's placed at the end of a line, then the newline is omitted from the output.
The following template contains syntax to exercise all brew functionality:
---------------
You won't see this R output, but it will run. <% foo <- 'bar' %>
Now foo is <%=foo%> and today is <%=format(Sys.time(),'%B %d, %Y')%>.
<%# Comment -- ignored -- useful in testing.
Also notice the dash-percent-gt.
It chops off the trailing newline.
You can add it to any percent-gt. -%>
How about generating a template from a template?
<%% foo <- 'fee fi fo fum' %%>
foo is still <%=foo%>.
---------------
The output is:
--------------
You won't see this R output, but it will run.
Now foo is bar and today is April 20, 2007.
How about generating a template from a template?
<% foo <- 'fee fi fo fum' %>
foo is still bar.
--------------
Also, for power users, there's one more thing:
6. Text between the '<%%' and '%%>' delimiters is treated as a brew template and is printed as-is, but the delimiters are changed to '<%' and '%>'. This happens when tplParser=NULL. But if tplParser is a valid function, then the text is passed to tplParser which should return a character vector to replace the text.
NOTE: brew calls can be nested and rely on placing a function named '.brew.cat' in the environment in which it is passed. Each time brew is called, a check for the existence of this function is made. If it exists, then it is replaced with a new copy that is lexically scoped to the current brew frame. Once the brew call is done, the function is replaced with the previous function. The function is finally removed from the environment once all brew calls return.
When run=TRUE, the value of the last expression after brewing the input or an object of class 'try-error' containing the error message if brewing failed.
When run=FALSE and parseCode=TRUE, a function whose environment contains the text vector and the code vector of the parsed expressions after brewing the input. It takes brew's output and envir arguments.
When run=FALSE and parseCode=FALSE, a list containing the text vector and the unparsed code vector.
Sweave for the original report generator.
## A port of the Sweave test file.
brew(system.file("brew-test-1.brew",package="brew"),"brew-test-1.tex",envir=new.env())
##clean up generated files
unlink("brew-test-1-1.eps")
unlink("brew-test-1-2.eps")
unlink("brew-test-1.tex")
## Everything you wanted to know about your R session.
brew(system.file("brew-test-2.brew",package="brew"),"brew-test-2.html",envir=new.env())
#> Error in if (length(obj) == 0 || is.null(obj) || obj == "") obj <- " " :
#> missing value where TRUE/FALSE needed
browseURL(paste('file://',file.path(getwd(),'brew-test-2.html'),sep=''))
## clean up generated files
unlink("brew-test-2.html")
## Don't sully up environment, so use envir=new.env(). Nested brew calls will still work.
brew(system.file("example1.brew",package="brew"),envir=new.env())
#> Title: brew test
#> current time: 2025-10-14 14:54:53
#> value of foo: bar
#> i is 1
#> from example2.brew, foo is: bar1
#> i is 2
#> from example2.brew, foo is: bar12
#> i is 3
#> from example2.brew, foo is: bar123
#> i is 4
#> from example2.brew, foo is: bar1234
#> i is 5
#> from example2.brew, foo is: bar12345
#> i is 6
#> from example2.brew, foo is: bar123456
#> i is 7
#> from example2.brew, foo is: bar1234567
#> i is 8
#> from example2.brew, foo is: bar12345678
#> i is 9
#> from example2.brew, foo is: bar123456789
#> i is 10
#> from example2.brew, foo is: bar12345678910
## Various ways to print R output
library(datasets)
brew(system.file("catprint.brew",package="brew"),envir=new.env())
#> DATA FRAME OUTPUT (LISTS TOO)
#>
#> Let's run this: <% data(iris) %>
#>
#> Let's look at some R output:
#>
#> If we say this: <% head(iris) %>
#> the output is this:
#>
#> nothing right?
#>
#> if we say this: <%= head(iris) %>
#> it's an error because cat() cannot handle lists.
#>
#> But if we say this: <% print(head(iris)) %>
#> the output is this:
#> Sepal.Length Sepal.Width Petal.Length Petal.Width Species
#> 1 5.1 3.5 1.4 0.2 setosa
#> 2 4.9 3.0 1.4 0.2 setosa
#> 3 4.7 3.2 1.3 0.2 setosa
#> 4 4.6 3.1 1.5 0.2 setosa
#> 5 5.0 3.6 1.4 0.2 setosa
#> 6 5.4 3.9 1.7 0.4 setosa
#>
#>
#> VECTOR OUTPUT
#>
#> We'll work with v: <% v <- head(iris)$Sepal.Length %>
#>
#>
#> If we say this: <%= v %>
#> the output is this:
#> 5.1 4.9 4.7 4.6 5 5.4
#> because 'cat()' coerces v to a character vector
#>
#> How about <%= v > 5 %>
#> TRUE FALSE FALSE FALSE FALSE TRUE
#> So cat() can deal with any vector
#>
#> And if we say this: <% print(v) %>
#> the output is:
#> [1] 5.1 4.9 4.7 4.6 5.0 5.4
#>
rm(iris)
#> Warning: object 'iris' not found
## The example from the Details section
brew(system.file("featurefull.brew",package="brew"),envir=new.env())
#> You won't see this R output, but it will run.
#> Now foo is bar and today is October 14, 2025.
#> How about generating a template from a template?
#> <%
#> foo <- 'fee fi fo fum'
#> brew <- 'haha'
#> %>
#> foo is still bar.
#> Contents of current directory:
#> [1] "index.html"
#>
## Using the tplParser argument
tParse <- function(text) paste('Got this: <',text,'>\n',sep='',collapse='')
brew(system.file("featurefull.brew",package="brew"),envir=new.env(),tplParser=tParse)
#> You won't see this R output, but it will run.
#> Now foo is bar and today is October 14, 2025.
#> How about generating a template from a template?
#> Got this: <
#> >
#> Got this: < foo <- 'fee fi fo fum'
#> >
#> Got this: < brew <- 'haha'
#> >
#> Got this: <>
#>
#> foo is still bar.
#> Contents of current directory:
#> [1] "index.html"
#>
rm(tParse)