Movatterモバイル変換

Format a quarto object

Description

Creates a formatted representation of a quarto object in aform suitable for printing. When callingknitr::knit_print()on a quarto object, the relevantformat() method is calledfirst, and the formatted version is printed to the document.Note that the baseprint() method for quarto objects doesnot callformat().

Usage

## S3 method for class 'quarto_section'format(x, ...)## S3 method for class 'quarto_tabset'format(x, ...)## S3 method for class 'quarto_div'format(x, ...)## S3 method for class 'quarto_span'format(x, ...)## S3 method for class 'quarto_markdown'format(x, ...)## S3 method for class 'quarto_group'format(x, ...)

Arguments

Details

The intent behind theformat() methods for quarto objectsis to create a ready-to-print representation of that is almostidentical to what will be printed into the quarto documentwhenknitr::knit_print() is called. Because of this, theformatted version of a quarto object is a string or a list ofstrings, but it may also include plot objects that have notyet been rendered. The resulting representation isn't alwaysvery pretty, though it is generally fairly readable.

Value

A formatted quarto object. Forquarto_section,quarto_span,andquarto_markdown objects, the formatted output is always astring (character vector of length 1). Forquarto_tabset andquarto_group objects, the output is always a list whose elementsare either strings or plot objects. Forquarto_div objects,the output is currently a string, but this may change to listoutput in future if divs are permitted to contain plots.

Examples

# formatted sections, spans and divs ----------------------------------sec <- quarto_section("Header", level = 2L)spn <- quarto_span("Content", class = "underline")div <- quarto_div("Content", class = "content-margin")format(sec)format(spn)format(div)# formatted tabsets ---------------------------------------------------tbs <- quarto_tabset(  content = list(tab1 = 1:10, tab2 = "hello"),  title = "Header",  level = 2L)format(tbs)# formatted groups and markdown ---------------------------------------mkd <- quarto_markdown(list("- this is a", "- markdown list"), sep = "\n")gps <- quarto_group(list(div, mkd))format(mkd)format(gps)

Dynamically generate quarto syntax

Description

Define quarto objects for insertion into a document.Intended to be used inside a quarto document, within a knitrcode chunk with theresults: asis option set.

Usage

quarto_section(title, level)quarto_tabset(content, level, title = NULL, names = NULL)quarto_div(content, class = NULL, sep = "")quarto_span(content, class = NULL, sep = "")quarto_group(content, sep = "")quarto_markdown(content, sep = "")

Arguments

Details

The purpose of these functions is to allow the user to dynamicallygenerate quarto syntax from R. When used within a quarto document theyallow the user to generate callouts, margin text, tabsets, sectionheaders, and other kinds of quarto output. At the current state ofdevelopment the functionality is somewhat limited, discussed below.

The⁠quarto_*()⁠ functions supplied by the quartose package have a commondesign: argument values supplied by the user are stored internally as alist, with only a minimum of processing done at the time that the functionis called. The object is assigned to two S3 classes, the "quarto_object"shared by all objects, and a specific class associated with the callingfunction. These objects can be inspected and manipulated programmaticallylike any other R objects prior to printing.

When creating a quarto object, note that most⁠quarto_*()⁠ functions takeacontent argument, which differs slightly depending on the context:

• Forquarto_section() there is no 'content“ argument: section headershave titles, but they do not contain content.

• Forquarto_span() the 'content“ argumentmust be a character vector,not a list.

• Forquarto_div() the⁠content`` argument is permitted to be a character vector or a list, but it will always be stored internally as a list. If the input is a list, it can contain other quarto objects. The intended use for this is a div that contains several spans, but it is not limited to this use case. At present, ⁠quarto_div()' cannot handleplot objects, but functionality may be extended to permit this in future.

• Forquarto_tabset() thecontent argumentmust be a list. The listelements can be any printable R object: each element of the list willappear in its own tab. At present the support for graphics objects islimited: ggplot2 objects are captured and will only be rendered whenknitr::knit_print() is called. No attempt is made (as yet!) to supportother kinds of graphic objects, and if these are passed via thecontentargument the function will likely fail.

• Forquarto_markdown() thecontent argument may be a character vectoror a list of character vectors. The function will throw an error if otherkinds of objects are passed viacontent.

• Forquarto_group() thecontent argumentmust be a list, and allelements of the list must be quarto objects. The intended use of thisfunction is simply to collect several quarto objects into a single groupthat will be printed all at the same time rather than sequentially.

Creating a quarto object only defines the data structure, it does notperform any formatting. Similarly, if the object is printed usingprint(), no formatting will be applied. A brief summary of thedata structure will be printed to the console, no more. However, whenknitr::knit_print() is called, the quarto object is first passed tothe relevantformat() method, which is responsible for constructingthe appropriate quarto syntax. Callingformat() will return acharacter vector or a list. If it returns a list all elements willeither be character strings with the appropriate quarto syntax, or aplot object that has not yet been rendered. After formatting is appliedtheknitr::knit_print() method will pass the strings (or plots) tothe document. For more detail on the formatting and printing methodsseeknit_print.quarto_object() andformat.quarto_object().

Value

These functions always return an object with parent S3 class"quarto_object", in addition to a specific S3 class correspondingto the function. For example,quarto_section() objects also possess the"quarto_section" class.

Examples

# quarto_section ------------------------------------------------------sec <- quarto_section("A level-two header", level = 2L)# quarto objects have two classes, a general purpose class shared by # all quarto objects, and a class specific to the functionclass(sec)  # base::print() displays an abstract summary of the object print(sec)# knitr::knit_print() produces the rendered quarto syntaxknitr::knit_print(sec)# quarto_span ---------------------------------------------------------spn1 <- quarto_span("This is plain text")spn2 <- quarto_span("This is underlined text", class = "underline")print(spn1)print(spn2)knitr::knit_print(spn1)knitr::knit_print(spn2)# quarto_div ----------------------------------------------------------# quarto_div objects are flexible: they can take a character vector as# the content argument, but can also take lists of other objects; note# that internally the content is always represented as a listdiv1 <- quarto_div("This is a callout note", class = "callout-note")div2 <- quarto_div(  content = list(    quarto_span(content = "You can wrap multiple spans in a div so that"),    quarto_span(content = "some text is highlighted", class = "mark"),    quarto_span(content = "and some is underlined", class = "underline")  ),  class = c("column-margin", "callout-tip"),  sep = " ")print(div1)print(div2)knitr::knit_print(div1)knitr::knit_print(div2)# quarto_tabset -------------------------------------------------------tbs <- quarto_tabset(list(tab1 = 1:10, tab2 = "hello"), level = 3L)print(tbs)knitr::knit_print(tbs)# quarto_markdown -----------------------------------------------------mkd <- quarto_markdown(list("- a markdown", "- list"), sep = "\n")print(mkd)knitr::knit_print(mkd)# quarto_group --------------------------------------------------------grp <- quarto_group(list(  quarto_div("This is a callout note", class = "callout-note"),  quarto_div("This is a callout tip", class = "callout-tip")))print(grp)knitr::knit_print(grp)

Print a quarto object

Description

Prints a quarto object. When callingknitr::knit_print()on a quarto object, the relevantformat() method is calledfirst, and the formatted version is printed to the document.When callingprint(), a summary of the object structure isprinted.

Usage

## S3 method for class 'quarto_object'knit_print(x, ...)## S3 method for class 'quarto_object'print(x, ...)

Arguments

Details

There are two print methods supplied for quarto objects, one forbase::print() and another forknitr::knit_print(). The regularprint method behaves similarly to any other print method: it printsa summary of the object to the R console, and invisibly returns theobject itself.

Whenknitr::knit_print() is called on a quarto object, the behavioris quite different. The object is first passed toformat(), whichconstructs the required quarto syntax, then the object is printedto the document (or console, if called interactively) using theappropriate syntax. In this case, the function invisibly returnsNULL.

Value

knitr::knit_print() invisibly returnsNULL;print()invisibly returns the quarto object itself.

Examples

# a quarto_section objectsec <- quarto_section("A level-two header", level = 2L) # base::print() displays a summary of the object print(sec)# knitr::knit_print() displays the rendered quarto syntaxknitr::knit_print(sec) # a quarto_span objectspn <- quarto_span("This is underlined", class = "underline")print(spn)knitr::knit_print(spn)