Updated documentation for disabling html escaping. (issue #16)(Thanks…

… to @ctbrown)
edwindj · Jun 18, 2014 · 5cbd573 · 5cbd573
1 parent 39ef6fa
commit 5cbd573
Show file tree

Hide file tree

Showing 14 changed files with 82 additions and 60 deletions.
diff --git a/NAMESPACE b/NAMESPACE
@@ -1,3 +1,5 @@
+# Generated by roxygen2 (4.0.1): do not edit by hand
+
 export(iteratelist)
 export(rowSplit)
 export(whisker.escape)

diff --git a/NEWS b/NEWS
@@ -1,5 +1,6 @@
 0.4 
 - Fixed issue #12: inconsistent treatment of new lines (Thanks to @danhalligan)
+- Updated documentation for disabling html escaping. (issue #16)(Thanks to @ctbrown)
 
 0.3-3 
 - Added an option "strict" to render. Setting it to FALSE allows for "." in names

diff --git a/R/whisker.R b/R/whisker.R
@@ -9,6 +9,10 @@
 #' @rdname whisker.render
 #' @example examples/whisker_render.R
 #' @export
+#' @note 
+#' By default whisker applies html escaping on the generated text. 
+#' To prevent this use \{\{\{variable\}\}\} (triple) in stead of 
+#' \{\{variable\}\}.
 whisker.render <- function( template
                           , data = parent.frame()
                           , partials = list()

diff --git a/examples/rowSplit.R b/examples/rowSplit.R
@@ -6,4 +6,4 @@ template <-
 count: {{count}}, spray: {{spray}}\n
 {{/dat}}"
 
-whisker.render(template)
+whisker.render(template)
diff --git a/examples/whisker_render.R b/examples/whisker_render.R
@@ -2,3 +2,13 @@ template <- "Hello {{place}}!"
 place <- "World"
 
 whisker.render(template)
+
+# to prevent html escaping use triple {{{}}}
+template <- 
+  "I'm escaped: {{name}}
+And I'm not: {{{name}}}"
+
+data <- list( name = '<My Name="Nescio&">')
+whisker.render(template, data)
+# I'm escaped: &lt;My Name=&quot;Nescio&amp;&quot;&gt;
+# And I'm not: <My Name="Nescio&">
diff --git a/man/delimit.Rd b/man/delimit.Rd
@@ -1,13 +1,14 @@
+% Generated by roxygen2 (4.0.1): do not edit by hand
 \name{delimit}
 \alias{delimit}
 \title{enclose a key with delimiters}
 \usage{
 delimit(x, delim = tag2delim())
 }
 \arguments{
-  \item{x}{character with delimiter seperated with a space}
+\item{x}{character with delimiter seperated with a space}
 
-  \item{delim}{character vector with escaped delimiters}
+\item{delim}{character vector with escaped delimiters}
 }
 \description{
 enclose a key with delimiters

diff --git a/man/isFalsey.Rd b/man/isFalsey.Rd
@@ -1,11 +1,12 @@
+% Generated by roxygen2 (4.0.1): do not edit by hand
 \name{isFalsey}
 \alias{isFalsey}
 \title{Is a value falsey according to Mustache specifications?}
 \usage{
 isFalsey(x)
 }
 \arguments{
-  \item{x}{value}
+\item{x}{value}
 }
 \value{
 TRUE if falsey, otherwise FALSE

diff --git a/man/iteratelist.Rd b/man/iteratelist.Rd
@@ -1,28 +1,25 @@
+% Generated by roxygen2 (4.0.1): do not edit by hand
 \name{iteratelist}
 \alias{iteratelist}
 \title{Create an iteration list from a R object}
 \usage{
 iteratelist(x, name = "name", value = "value")
 }
 \arguments{
-  \item{x}{\code{list} or other object that will be coerced
-  to \code{list}}
+\item{x}{\code{list} or other object that will be coerced to \code{list}}
 
-  \item{name}{\code{character} name for resulting name
-  member.}
+\item{name}{\code{character} name for resulting name member.}
 
-  \item{value}{\code{character} name for resulting value
-  member.}
+\item{value}{\code{character} name for resulting value member.}
 }
 \value{
 unnamed \code{list} with name value lists
 }
 \description{
-In some case it is useful to iterate over a named
-\code{list} or \code{vector} \code{iteratelist} will create
-a new unnamed \code{list} with name value members: each
-item will be a list where 'name' is the corresponding name
-and 'value' is the original value in list \code{x}.
+In some case it is useful to iterate over a named \code{list} or \code{vector}
+\code{iteratelist} will create a new unnamed \code{list} with name value members:
+each item will be a list where 'name' is the corresponding name and 'value' is the original
+value in list \code{x}.
 }
 \examples{
 # create an iteration list from a named vector

diff --git a/man/rowSplit.Rd b/man/rowSplit.Rd
@@ -1,20 +1,19 @@
+% Generated by roxygen2 (4.0.1): do not edit by hand
 \name{rowSplit}
 \alias{rowSplit}
 \title{Split a data.frame or matrix into rows}
 \usage{
 rowSplit(x, ...)
 }
 \arguments{
-  \item{x}{\code{data.frame} or \code{matrix}}
+\item{x}{\code{data.frame} or \code{matrix}}
 
-  \item{...}{other options will be passed onto
-  \code{\link{split}}}
+\item{...}{other options will be passed onto \code{\link{split}}}
 }
 \description{
-Utility function for splitting a data.frame into rows. In a
-whisker template it can be useful to iterate over the rows
-of a data.frame or matrix. For example rendering a table in
-HTML.
+Utility function for splitting a data.frame into rows.
+In a whisker template it can be useful to iterate over the rows of a data.frame or matrix.
+For example rendering a table in HTML.
 }
 \examples{
 dat <- head(InsectSprays)

diff --git a/man/rxsplit.Rd b/man/rxsplit.Rd
@@ -1,17 +1,18 @@
+% Generated by roxygen2 (4.0.1): do not edit by hand
 \name{rxsplit}
 \alias{rxsplit}
 \title{Split a character in three parts}
 \usage{
 rxsplit(x, pattern)
 }
 \arguments{
-  \item{x}{character text to be split}
+\item{x}{character text to be split}
 
-  \item{pattern}{pattern used for splitting}
+\item{pattern}{pattern used for splitting}
 }
 \description{
-It differs from strsplit in that it only splits on the
-first occurrence and returns all parts of the string given
+It differs from strsplit in that it only splits on the first occurrence
+and returns all parts of the string given
 }
 \keyword{internal}
 
diff --git a/man/tag2delim.Rd b/man/tag2delim.Rd
@@ -1,15 +1,14 @@
+% Generated by roxygen2 (4.0.1): do not edit by hand
 \name{tag2delim}
 \alias{tag2delim}
 \title{change a delimiter tag into two escaped characters}
 \usage{
 tag2delim(tag = "{{ }}", escape = TRUE)
 }
 \arguments{
-  \item{tag}{character with delimiter tag seperated with a
-  space}
+\item{tag}{character with delimiter tag seperated with a space}
 
-  \item{tag}{character with delimiter tag seperated with a
-  space}
+\item{tag}{character with delimiter tag seperated with a space}
 }
 \description{
 change a delimiter tag into two escaped characters

diff --git a/man/whisker-package.Rd b/man/whisker-package.Rd
@@ -1,30 +1,24 @@
+% Generated by roxygen2 (4.0.1): do not edit by hand
 \docType{package}
 \name{whisker-package}
 \alias{whisker-package}
 \title{{{Mustache for R}}}
 \description{
-Whisker is a templating engine for R conforming to the
-Mustache specification. Mustache is a logicless templating
-language, meaning that no programming source code can be
-used in your templates. This may seem very limited, but
-Mustache is nonetheless powerful and has the advantage of
-being able to be used unaltered in many programming
-languages. For example it make it very easy to write a web
-application in R using Mustache templates and where the
-browser can template using javascript's "Mustache.js"
+Whisker is a templating engine for R conforming to the Mustache specification.
+Mustache is a logicless templating language, meaning that no programming source
+code can be used in your templates. This may seem very limited, but Mustache is nonetheless
+powerful and has the advantage of being able to be used unaltered in many programming
+languages. For example it make it very easy to write a web application in R using Mustache templates
+and where the browser can template using javascript's "Mustache.js"
 }
 \details{
-Mustache (and therefore \code{whisker}) takes a simple but
-different approach to templating compared to most
-templating engines. Most templating libraries for example
-\code{Sweave} and \code{brew} allow the user to mix
-programming code and text throughout the template. This is
-powerful, but ties a template directly to a programming
-language. Furthermore that approach makes it difficult to
-seperate programming code from templating code.
-
-Whisker on the other hand, takes a Mustache template and
-uses the variables of the current environment (or the
+Mustache (and therefore \code{whisker}) takes a simple but different approach to templating compared to
+most templating engines. Most templating libraries for example \code{Sweave} and \code{brew} allow the user
+to mix programming code and text throughout the template. This is powerful, but ties a template directly
+to a programming language. Furthermore that approach makes it difficult to seperate programming code
+from templating code.
+
+Whisker on the other hand, takes a Mustache template and uses the variables of the current environment (or the
 supplied \code{list}) to fill in the variables.
 }
 \examples{

diff --git a/man/whisker.escape.Rd b/man/whisker.escape.Rd
@@ -1,11 +1,12 @@
+% Generated by roxygen2 (4.0.1): do not edit by hand
 \name{whisker.escape}
 \alias{whisker.escape}
 \title{escape basic HTML characters}
 \usage{
 whisker.escape(x)
 }
 \arguments{
-  \item{x}{\code{character} that will be escaped}
+\item{x}{\code{character} that will be escaped}
 }
 \value{
 HTML escaped character

diff --git a/man/whisker.render.Rd b/man/whisker.render.Rd
@@ -1,3 +1,4 @@
+% Generated by roxygen2 (4.0.1): do not edit by hand
 \name{whisker.render}
 \alias{whisker.render}
 \title{Logicless templating}
@@ -6,30 +7,41 @@ whisker.render(template, data = parent.frame(), partials = list(),
   debug = FALSE, strict = TRUE)
 }
 \arguments{
-  \item{template}{\code{character} with template text}
+\item{template}{\code{character} with template text}
 
-  \item{data}{named \code{list} or \code{environment} with
-  variables that will be used during rendering}
+\item{data}{named \code{list} or \code{environment} with variables that will be used during rendering}
 
-  \item{partials}{named \code{list} with partial templates,
-  will be used during template construction}
+\item{partials}{named \code{list} with partial templates, will be used during template construction}
 
-  \item{debug}{Used for debugging purposes, likely to
-  disappear}
+\item{debug}{Used for debugging purposes, likely to disappear}
 
-  \item{strict}{\code{logical} if \code{TRUE} the
-  seperation symbol is a "." otherwise a "$"}
+\item{strict}{\code{logical} if \code{TRUE} the seperation symbol is a "." otherwise a "$"}
 }
 \value{
 \code{character} with rendered template
 }
 \description{
 Logicless templating
 }
+\note{
+By default whisker applies html escaping on the generated text.
+To prevent this use \{\{\{variable\}\}\} (triple) in stead of
+\{\{variable\}\}.
+}
 \examples{
 template <- "Hello {{place}}!"
 place <- "World"
 
 whisker.render(template)
+
+# to prevent html escaping use triple {{{}}}
+template <- 
+  "I'm escaped: {{name}}
+And I'm not: {{{name}}}"
+
+data <- list( name = '<My Name="Nescio&">')
+whisker.render(template, data)
+# I'm escaped: &lt;My Name=&quot;Nescio&amp;&quot;&gt;
+# And I'm not: <My Name="Nescio&">
 }