Get roxygen2 blocks

Parses the roxygen2 package documentation of a specific R package or from a single .R source code file.

Usage

roxy_blocks(pkg = NULL, ..., text = NULL, quiet = TRUE)

Arguments

pkg, text: Either a package name (pkg) or a character vector of R source code lines (text) to extract the object's roxygen2 tag value from.
...: Further arguments passed on to utils::download.packages(), excluding "pkgs", "destdir", "available", "type" and "quiet". Only relevant if pkg is provided.
quiet: Whether or not to suppress printing status output from internal processing.

Value

A list of roxy_block objects.

Examples

# Either provide an R source file as a character vector `text`...
text <- readr::read_lines(paste0("https://raw.githubusercontent.com/r-lib/rlang/",
                                 "db52a58d505b65f58ba922d4752b5b0061f2a98c/R/fn.R"))

pal::roxy_blocks(text = text) |> head(n = 3L)
#> [[1]]
#> <roxy_block> [<text>:39]
#>   $tag
#>     [line:  1] @title 'Create a function' {parsed}
#>     [line:  3] @description '...' {parsed}
#>     [line: 10] @param 'args A named list or pairlist of default argume...' {parsed}
#>     [line: 14] @param 'body A language object representing the code in...' {parsed}
#>     [line: 17] @param 'env The parent environment of the function, def...' {parsed}
#>     [line: 19] @export '' {parsed}
#>     [line: 20] @examples '...' {parsed}
#>     [line: 39] @usage '<generated>' {parsed}
#>     [line: 39] @.formals '<generated>' {parsed}
#>     [line: 39] @backref '<generated>' {parsed}
#>   $call   new_function <- function(args, body, env = caller_env()) { ...
#>   $object <function> 
#>     $topic new_function
#>     $alias new_function
#> 
#> [[2]]
#> <roxy_block> [<text>:50]
#>   $tag
#>     [line: 46] @title 'Name of a primitive function' {parsed}
#>     [line: 47] @param 'prim A primitive function such as [base::c()].' {parsed}
#>     [line: 48] @keywords 'internal' {parsed}
#>     [line: 49] @export '' {parsed}
#>     [line: 50] @usage '<generated>' {parsed}
#>     [line: 50] @.formals '<generated>' {parsed}
#>     [line: 50] @backref '<generated>' {parsed}
#>   $call   prim_name <- function(prim) { ...
#>   $object <function> 
#>     $topic prim_name
#>     $alias prim_name
#> 
#> [[3]]
#> <roxy_block> [<text>:91]
#>   $tag
#>     [line: 62] @title 'Extract arguments from a function' {parsed}
#>     [line: 64] @description '`fn_fmls()` returns a named list of formal argu...' {parsed}
#>     [line: 70] @details 'Unlike `formals()`, these helpers throw an erro...' {parsed}
#>     [line: 73] @param 'fn A function. It is lookep up in the calling f...' {parsed}
#>     [line: 75] @seealso '[call_args()] and [call_args_names()]' {parsed}
#>     [line: 76] @export '' {parsed}
#>     [line: 77] @examples '...' {parsed}
#>     [line: 91] @usage '<generated>' {parsed}
#>     [line: 91] @.formals '<generated>' {parsed}
#>     [line: 91] @backref '<generated>' {parsed}
#>   $call   fn_fmls <- function(fn = caller_fn()) { ...
#>   $object <function> 
#>     $topic fn_fmls
#>     $alias fn_fmls
#> 

# ...or provide a package name as `pkg`
try(
  pal::roxy_blocks(pkg = "tinkr",
                   repos = "https://cloud.r-project.org") |>
    head(n = 3L)
)
#> [[1]]
#> <roxy_block> [add_md.R:9]
#>   $tag
#>     [line:  1] @title 'Add markdown content to an XML object' {parsed}
#>     [line:  3] @param 'body an XML object generated via {tinkr}' {parsed}
#>     [line:  4] @param 'md a string of new markdown to insert' {parsed}
#>     [line:  5] @param 'where the position in the markdown document to ...' {parsed}
#>     [line:  6] @keywords 'internal
#> ' {parsed}
#>     [line:  8] @return 'a copy of the XML object with the markdown inse...' {parsed}
#>     [line:  9] @usage '<generated>' {parsed}
#>     [line:  9] @.formals '<generated>' {parsed}
#>     [line:  9] @backref '<generated>' {parsed}
#>   $call   add_md <- function(body, md, where = 0L) { ...
#>   $object <function> 
#>     $topic add_md
#>     $alias add_md
#> 
#> [[2]]
#> <roxy_block> [add_md.R:59]
#>   $tag
#>     [line: 35] @title 'Convert markdown to XML' {parsed}
#>     [line: 37] @param 'md a character vector of markdown text' {parsed}
#>     [line: 38] @return 'an XML nodeset of the markdown text' {parsed}
#>     [line: 39] @keywords 'internal' {parsed}
#>     [line: 40] @examples '...' {parsed}
#>     [line: 59] @usage '<generated>' {parsed}
#>     [line: 59] @.formals '<generated>' {parsed}
#>     [line: 59] @backref '<generated>' {parsed}
#>   $call   md_to_xml <- function(md) { ...
#>   $object <function> 
#>     $topic md_to_xml
#>     $alias md_to_xml
#> 
#> [[3]]
#> <roxy_block> [asis-nodes.R:24]
#>   $tag
#>     [line:  1] @title 'Protect math elements from commonmark's charact...' {parsed}
#>     [line:  3] @param 'body an XML object' {parsed}
#>     [line:  4] @param 'ns an XML namespace object (defaults: [md_ns()]).' {parsed}
#>     [line:  5] @return 'a copy of the modified XML object' {parsed}
#>     [line:  6] @details 'Commonmark does not know what LaTeX is and will...' {parsed}
#>     [line: 12] @note 'this function is also a method in the [tinkr::y...' {parsed}
#>     [line: 14] @export '' {parsed}
#>     [line: 15] @examples '...' {parsed}
#>     [line: 24] @usage '<generated>' {parsed}
#>     [line: 24] @.formals '<generated>' {parsed}
#>     [line: 24] @backref '<generated>' {parsed}
#>   $call   protect_math <- function(body, ns = md_ns()) { ...
#>   $object <function> 
#>     $topic protect_math
#>     $alias protect_math
#>

Usage

Arguments

Value

See also

Examples