Version: 0.1.2
Encoding: UTF-8
Title: Writing 'YAML' Headers for 'R-Markdown' Documents
Depends: R(≥ 4.2)
Imports: methods, rmarkdown, tools, yaml
Suggests: knitr, testthat
Description: Setting layout through 'YAML' headers in 'R-Markdown' documents, enabling their automatic generation. Functions and methods may summarize 'R' objects in automatic reports, for instance check-lists and further reports applied to the packages 'taxlist' and 'vegtable'.
SystemRequirements: pandoc (>= 1.14) - http://pandoc.org
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
URL: https://github.com/kamapu/yamlme, https://kamapu.github.io/rpkg/yamlme/, https://kamapu.github.io/yamlme/
BugReports: https://github.com/kamapu/yamlme/issues
VignetteBuilder: knitr
RoxygenNote: 7.2.1
Collate: 'imports.R' 'classes.R' 'as.R' 'print.R' 'read_rmd.R' 'render_rmd.R' 'update.R' 'write_rmd.R'
NeedsCompilation: no
Packaged: 2022-11-09 17:26:19 UTC; miguel
Author: Miguel Alvarez ORCID iD [aut, cre], Bisrat Haile Gebrekidan [ctb]
Maintainer: Miguel Alvarez <kamapu78@gmail.com>
Repository: CRAN
Date/Publication: 2022-11-09 17:50:02 UTC

Coercing lists and rmd_doc objects

Description

Coercion of lists into rmd_doc objects and vice versa.

Objects of class rmd_doc can be created from lists or converted back to lists. This is convenient for defining functions that manipulate the content of such objects.

Usage

list2rmd_doc(object)

rmd_doc2list(object)

Arguments

object

Either a list or a rmd_doc object.

Examples

## Create a document from a list
my_document <- list(
    title = "Sample Document",
    author = "Miguel Alavarez",
    output = "html_document",
    body = txt_body(
        "# Intro",
        "",
        "This is just an example."
    ))
my_document <- as(my_document, "rmd_doc")

## Convert back to a list
my_document <- as(my_document, "list")

Print Method for rmd_doc

Description

Quick display for rmd_doc objects. This method also defines the way how objects are displayed in the console.

Usage

## S3 method for class 'rmd_doc'
print(x, maxlines = 10, ...)

Arguments

x

An object of class rmd_doc.

maxlines

An integer value indicating the number of lines used for the display. Longer documents will be truncated.

...

Further arguments passed among methods (not yet in use).

Value

A display of the resulting R-Markdown document in the console.

Examples

## Document without header
my_document <- read_rmd(
  file = file.path(path.package("yamlme"), "taxlistjourney.Rmd"),
  skip_head = TRUE
)
my_document

## Add header using update
my_document <- update(my_document,
  title = "A journey in rOpenSci",
  author = "Miguel Alvarez",
  output = "html_document"
)
my_document

## Header only
my_document$body <- NULL
my_document

Print content of rmd_doc into a text string

Description

Content of rmd_doc objects will be converted into a string that will be passed either to print() or to write_rmd().

Usage

print2text(x)

Arguments

x

Input rmd_doc object.

Read R-markdown Documents

Description

Import Rmd files into objects of class rmd_doc.

The function txt_body() add a line break at the end of each element of a character vector considering them as single lines.

Note that comments will be deleted in the input file.

Usage

read_rmd(file, ..., skip_head = FALSE)

txt_body(...)

Arguments

file

Character value indicating the path and the name to the Rmd file.

...

Arguments passed by read_rmd() to readLines(). In txt_body() they are character values passed to c().

skip_head

Logical value indicating whether the yaml head should be skip or not (this argument is not used at the moment).

Value

The function read_rmd() returns a rmd_doc object. The function txt_body(), a character vector suitable for the parameter body in the function write_rmd().

Examples

## Not run: 
## Read pre-installed example
ex_document <- read_rmd(file.path(
  path.package("yamlme"),
  "taxlistjourney.Rmd"
))

## End(Not run)

Render documents from object

Description

This function is a wrapper of rmarkdown::render() and will also work with file names but also enables the possibility of rendering from objects created by write_rmd().

Usage

render_rmd(input, ...)

## S3 method for class 'character'
render_rmd(input, ...)

## S3 method for class 'rmd_doc'
render_rmd(input, output_file, delete_rmd = TRUE, ...)

Arguments

input

Either a character value indicating the path and the name of the r-markdown file, or an object of class rmd_doc, written by write_rmd().

...

Further parameters passed to rmarkdown::render().

output_file

A character value indicating the name of the output file. This argument is passed to rmarkdown::render(). Note that the argument only contains the name of the file without extension and can only be written at the working directory.

delete_rmd

A logical value idicating whether the temporary Rmd file should be deleted or not. If not, the file gets the same name as the rendered file.

Examples

## Not run: 
## copy example to your working directory
filename <- "taxlistjourney.Rmd"
file.copy(from = file.path(path.package("yamlme"), filename), to = filename)

## Render the file with rmarkdown::render()
render_rmd(filename, output_file = "example")
browseURL("example.html")

## Render the file with yamlme
text_document <- read_rmd(filename)

text_document <- update(text_document,
  title = "my title", author = "my name",
  output = "html_document"
)

render_rmd(text_document, output_file = "example2")
browseURL("example2.html")

## End(Not run)

R-markdown document

Description

An S3 class for rmarkdown documents iheriting properties from lists. Header settings are a list at object$header, while content in markdown is a character vector at object$body.

Update an rmd_doc

Description

Alternative to modify settings and content in rmd_doc objects. Note that to skip some elements of the YAML header, you can set the argument NULL to the respective parameter.

Usage

## S3 method for class 'rmd_doc'
update(object, ...)

Arguments

object

An object of class rmd_doc.

...

Named arguments to be inserted in the YAML header (passed to write_rmd()).

Examples

## Create a document from a list
my_document <- list(
    title = "Sample Document",
    author = "Miguel Alavarez",
    output = "html_document",
    body = txt_body(
        "# Intro",
        "",
        "This is just an example."
    ))
my_document <- as(my_document, "rmd_doc")
my_document

## Change output format
my_document <- update(my_document, output = "pdf_document")
my_document

Writing R-Markdown Documents

Description

This function generates R-Markdown documents by including the settings as arguments of the function. Comments and pieces of header can be also added through the argument append.

Usage

write_rmd(object, ...)

## S3 method for class 'rmd_doc'
write_rmd(object, filename, ...)

Arguments

object

rmd_doc object used to write an Rmarkdown file. If header is missing, write_rmd() will fail with an error message.

...

Further arguments passed among methods (not yet used).

filename

A character value with the name of the file to be written. If not included, the extension *.Rmd will be appended to this name. If missing, no file will be written by this function.

Value

A character vector of class rmd_doc and, if argument set for parameter filename, an Rmd file.

Examples

## Not run: 
my_document <- list(
  title = "Sample Document",
  author = "Miguel Alavarez",
  output = "html_document",
  body = txt_body(
    "# Intro",
    "",
    "This is just an example."
  )
)
my_document <- as(my_document, "rmd_doc")
write_rmd(my_document, filename = file.path(tempdir(), "example"))

## End(Not run)