spin {knitr}R Documentation

Spin goat's hair into wool

Description

This function takes a specially formatted R script and converts it to a literate programming document. By default normal text (documentation) should be written after the roxygen comment (#') and code chunk options are written after #+ or #- or # ----.

Usage

spin(hair, knit = TRUE, report = TRUE, text = NULL, envir = parent.frame(), 
    format = c("Rmd", "Rnw", "Rhtml", "Rtex", "Rrst"), doc = "^#+'[ ]?", 
    inline = "^[{][{](.+)[}][}][ ]*$", comment = c("^[# ]*/[*]", "^.*[*]/ *$"), 
    precious = !knit && is.null(text))

Arguments

hair

the path to the R script

knit

logical: whether to compile the document after conversion

report

logical: whether to generate report for ‘Rmd’, ‘Rnw’ and ‘Rtex’ output (ignored if knit = FALSE)

text

a character vector as an alternative way to hair to provide the R source; if text is not NULL, hair will be ignored

envir

the environment for knit() to evaluate the code

format

character: the output format (it takes five possible values); the default is R Markdown

doc

a regular expression to identify the documentation lines; by default it follows the roxygen convention, but it can be customized, e.g. if you want to use ## to denote documentation, you can use '^##\\s*'

inline

a regular expression to identify inline R expressions; by default, code of the form ((code)) on its own line is treated as an inline expression

comment

a pair of regular expressions for the start and end delimiters of comments; the lines between a start and an end delimiter will be ignored; by default, the delimiters are /* in the beginning and */ in the end of a line (following the convention of C comments)

precious

logical: whether intermediate files (e.g., .Rmd files when format is "Rmd") should be preserved; default FALSE if knit == TRUE and input is a file

Details

Obviously the goat's hair is the original R script, and the wool is the literate programming document (ready to be knitted).

Value

If text is NULL, the path of the final output document, otherwise the content of the output.

Note

If the output format is Rnw and no document class is specified in roxygen comments, this function will automatically add the article class to the LaTeX document so that it is complete and can be compiled. You can always specify the document class and other LaTeX settings in roxygen comments manually.

When the output format is Rmd, it is compiled to HTML via knit2html(), which uses R Markdown v1 instead of v2. If you want to use the latter, you should call rmarkdown::render() instead.

Author(s)

Yihui Xie, with the original idea from Richard FitzJohn (who named it as sowsear() which meant to make a silk purse out of a sow's ear)

References

http://yihui.name/knitr/demo/stitch/

See Also

stitch (feed a template with an R script)

Examples

#' write normal text like this and chunk options like below

#+ label, opt=value

# /*
#' these lines are treated as comments in spin()
1 + 1
# */

(s = system.file("examples", "knitr-spin.R", package = "knitr"))
spin(s)  # default markdown
o = spin(s, knit = FALSE)  # convert only; do not make a purse yet
knit2html(o)  # compile to HTML

# other formats
spin(s, FALSE, format = "Rnw")  # you need to write documentclass after #'
spin(s, FALSE, format = "Rhtml")
spin(s, FALSE, format = "Rtex")
spin(s, FALSE, format = "Rrst")

[Package knitr version 1.15.20 Index]