Find an associated block

Description

Given a file and line, discover which block the tag is associated with

Usage

associated_block(file, line)

Arguments

Value

(roxygen2::roxy_block() | NULL) A roxy_block if one could be associated, or NULL if not.

Build a collection of conversion edits

Description

Build a collection of conversion edits

Usage

build_convert_edits(format, tags, unmatched = FALSE)

Arguments

Value

(data.frame) A collection of possible tag edits as produced by tag_edit().

See Also

Other convert: convert_match_format(), convert_tag(), make_convert_edits(), tag_edit()

Build format regular expression

Description

Allow glue-style formatting using keyworded regular expressions. The original glue string (anything that isn't expanded by glue) is treated as a string literal, whereas the contents of populated values can be regular expressions, allowing for a more user-friendly way to construct complicated regular expressions.

Usage

build_format_regex(
  format,
  format_re,
  ...,
  type = re_backticked(),
  description = re_any()
)

re_backticked()

re_any()

escape_non_glue_re(x)

Arguments

Details

To bypass glue entirely and use a standard regular expression, use format_re.

The provided regular expression must match all characters from the start of a string to the end. The string also matches using "dot all" syntax, meaning that the . expression will also match newline characters.

Value

(⁠character[1]:⁠) A regular expression string, built from component sub-expressions.

Functions

• re_backticked(): Match within backticks

• re_any(): Match any

• escape_non_glue_re(): Escape all regular expression special characters

  In addition, avoid escaping {}'s that appear to be used as glue keywords. Handles only simple cases, and does not handle recusive curly nesting.

Examples

re <- roxytypes:::build_format_regex(
  "{as}{any}{bs}",
  as = "a+",
  bs = "b+",
  any = ".*?"
)

roxytypes:::regex_capture(re, "aaaa\n\nbb", perl = TRUE)

text <- "@param (`test(\")\")`)"

pattern <- sprintf("`%s`", re_backticked())

m <- regexec(pattern, text, perl = TRUE)
regmatches(text, m)[[1]]
# [1] "`test(\")\")`"

# curlies escaped, as this does not appear to be a glue-style usage
roxytypes:::escape_non_glue_re(".{1,3}")

# curlies not escaped, as this is a glue-style usage
roxytypes:::escape_non_glue_re("this is a {test}")

Clear state object

Description

Clear state object

Usage

clear_state()

roxytypes Config

Description

roxytypes exposes a few configuration options for helping to fine-tune your documentation. These are stored as key-values in a list in either the Config/roxytypes field of your DESCRIPTION file, or in a ./man/roxytypes/meta.R file within your package.

Usage

config(path = getwd(), refresh = FALSE, cache = TRUE)

Details

The available settings are listed below. Some fields are nested, which are shown by concatenating nested keys using $.

• format: An optional glue-style string, which can assume values for name, type and description. See ?roxytypes::tags for details on the source of each of these strings.

• verbose: If TRUE, emit extra diagnostic alerts while processing the package.

Value

(list) A named list of configured behaviors.

Configuration

Description

Various functions for loading, caching and performing configured behaviors using a user-supplied configuration file.

Usage

config_find_from(path = ".")

config_from_desc(path = ".")

config_from_file(path = ".")

Arguments

Details

This constant is used as a variable name in the package environment while documentation is being built to avoid constantly parsing configurations during evaluation of each tag.

Functions

• config_find_from(): Load a configuration from a path

• config_from_desc(): Load a configuration from a DESCRIPTION file

• config_from_file(): Load a configuration from a dotfile

Convert roxygen2 tags to roxytypes tags

Description

Convert a package codebase into applicable roxytypes tags. For roxygen2 tags with drop-in replacements (namely ⁠@param⁠ and ⁠@return⁠ tags), process descriptions and replace tags with roxytypes equivalents.

Usage

convert(
  path = ".",
  format = config(path, refresh = TRUE, cache = FALSE)$format,
  ...,
  unmatched = FALSE,
  verbose = interactive()
)

Arguments

Details

A format string is built using build_format_regex(), which accepts parameters type and description, which describe how to match these components of a parameter definition. They are combined with the literal content of format to produce a regular expression to split existing definitions.

For comprehensive control, pass format_re directly, bypassing expression construction altogether.

Value

(logical[1]) TRUE if successfully completes, FALSE if aborted. Always returns invisibly.

Examples

## Not run: 
convert("(`{type}`) {description}")

## End(Not run)

Tools for modifying configuration files

Description

Tools for modifying configuration files

Usage

make_config_edits(path)

guess_dcf_indent(dcf)

update_config_needs(dcf)

update_config_roxygen_meta(path)

update_config_roxygen_desc(dcf)

update_config_roxygen_expr(expr)

Arguments

Functions

• make_config_edits(): Make edits to various configuration files

• guess_dcf_indent(): Guess the existing dcf indentation

• update_config_needs(): Update the Needs section of a DESCRIPTION file

• update_config_roxygen_meta(): Update the Roxygen man/roxygen/meta.R file

• update_config_roxygen_desc(): Update the Roxygen DESCRIPTION entry

• update_config_roxygen_expr(): Update a Roxygen config expression

Conversion Helpers

Description

Various functions for supporting conversion from standard roxygen tags to ⁠@typed⁠ tags.

Usage

convert_continue_prompt()

preview_convert_edits(edits, n = 1)

preview_convert_edit(edit)

format_diff_chr(d, offset)

diff_lines(d)

Arguments

Value

NULL

Functions

• convert_continue_prompt(): Show a dialog to ask the user how they would like to proceed

• preview_convert_edits(): Preview diffs after applying conversion rules

• preview_convert_edit(): Preview diffs after applying conversion rules

• format_diff_chr(): Format a diff object for cli display

• diff_lines(): Build a data.frame of old and new line numbers for a diff

Match a conversion format and structure results

Description

Match a conversion format and structure results

Usage

convert_match_format(x, format)

Arguments

Value

(⁠: list⁠) A named list of type, description and matched fields. type and description represent the result of captured groups. If no capture groups were used, the raw string is used as a description. matched is a logical[1] indicating whether the provided format matched against the provided input.

See Also

Other convert: build_convert_edits(), convert_tag(), make_convert_edits(), tag_edit()

Convert a roxygen2 tag to roxytypes equivalent

Description

Convert a roxygen2 tag to roxytypes equivalent

Usage

convert_tag(tag, format, ...)

## Default S3 method:
convert_tag(tag, format, ...)

## S3 method for class 'return'
convert_tag(tag, format, ...)

## S3 method for class 'param'
convert_tag(tag, format, ...)

Arguments

Value

(“NULL or [tag_edit()]) If the tag can be converted, a tag_edit() is returned, otherwise 'NULL'.

Methods (by class)

• convert_tag(default): Default handler for tags that can not be converted.

• convert_tag(return): Convert ⁠@return⁠ tags, parsing type and description from existing description.

• convert_tag(param): Convert ⁠@param⁠ tags, parsing type and description from existing description.

See Also

Other convert: build_convert_edits(), convert_match_format(), make_convert_edits(), tag_edit()

Default formatter for ⁠@typed⁠

Description

Adds special cases for when the type uses other roxygen2 syntax

Usage

default_format(x, name, type, description, ...)

Arguments

Value

A formatted character value.

Find package root directory

Description

Traces parent directories until we find a pacakge root

Usage

find_package_root(path = ".")

Arguments

Value

(character[1]) The file path to the package root directory.

If-not-null-else

Description

If-not-null-else

Usage

lhs %||% rhs

Make tag edits

Description

Make tag edits

Usage

make_convert_edits(edits)

Arguments

Value

(integer[1]) The number of edits that were made.

See Also

Other convert: build_convert_edits(), convert_match_format(), convert_tag(), tag_edit()

A helper to reliably read DCF files

Description

A helper to reliably read DCF files

Usage

read_dcf_asis(path)

Arguments

Value

(data.frame) The result of read.dcf().

A half-baked extract method

Description

A half-baked extract method

Usage

re_extract(pattern, replace, x)

extract_backticked(x)

extract_quoted(x)

is_backticked(x)

is_bracketed(x)

Arguments

Value

(character[1]) The substituted string if a replacement is made, or NULL otherwise.

Functions

• extract_backticked(): Extract contents of a backtick-enclosed string

• extract_quoted(): Extract contents of a quoted (single or double) string

• is_backticked(): Extract contents of a backtick-enclosed string

• is_bracketed(): Test whether contents are enclosed in brackets

Note

This implementation is considered half-baked because there's no check for whether a replacement is made that results in the same string. This case will be interpreted the same as if there was no match.

Capture regex groups

Description

Captures regex groups and returns a named matrix of groups with one column per capture group and one row per element in x.

Usage

regex_capture(pattern, x, ...)

Arguments

roxygen2 ⁠@typed⁠ tag parsing

Description

Parse a ⁠@typed⁠ tag and return parsed components as value

Usage

## S3 method for class 'roxy_tag_typed'
roxy_tag_parse(x)

Arguments

Value

(⁠roxygen2 tag⁠) A parsed roxygen2 ⁠@typed⁠ rd_tag.

roxygen2 ⁠@typedreturn⁠ tag parsing

Description

Parse a ⁠@typedreturn⁠ tag and return parsed components as value

Usage

## S3 method for class 'roxy_tag_typedreturn'
roxy_tag_parse(x)

Arguments

Value

(⁠roxygen2 tag⁠) A parsed roxygen2 ⁠@typedreturn⁠ rd_tag.

roxygen2 ⁠@typed⁠ tag rd section population

Description

Push typed fields into ⁠@param⁠ section

Usage

## S3 method for class 'roxy_tag_typed'
roxy_tag_rd(x, base_path, env)

Arguments

Value

(roxygen2::rd_section) A roxygen2 "param" rd_section with formatted type information.

roxygen2 ⁠@typedreturn⁠ tag rd section population

Description

Push typed fields into ⁠@param⁠ section

Usage

## S3 method for class 'roxy_tag_typedreturn'
roxy_tag_rd(x, base_path, env)

Arguments

Value

(roxygen2::rd_section) A roxygen2 ⁠@value⁠ rd_tag with formatted type information.

Fetch roxygen2 blocks

Description

Avoid recomputing roxygen2s parsing by saving the blocks after the first tag is hit.

Usage

roxygen_blocks(path = getwd(), refresh = FALSE, cache = TRUE)

Split and trim a string

Description

Split and trim a string

Usage

split_and_trim(x)

Arguments

Value

(x: character) A character vector of trimed lines.

Built a conversion edit

Description

Built a conversion edit

Usage

tag_edit(tag, new, matched)

Arguments

Value

(data.frame) A single-observation dataset representing information for a tag edit. The data.frame row includes variables:

• file: (character[1]) The source file for the tag.

• line: (integer[1]) The first line of the tag.

• n: (integer[1]) The number of lines the tag spans.

• matched: (logical[1]) Whether the tag matched a specified format.

• new: (list[1](character)) The new contents to replace the tag.

See Also

Other convert: build_convert_edits(), convert_match_format(), convert_tag(), make_convert_edits()

roxytypes tags

Description

The ⁠@typed⁠ tag introduces a syntax for defining parameter types as a roxygen2 tag.

Usage

#' @typed <var>: <type>
#'   <description>

Details

Be aware that there are a few syntactic requirements:

• : delimiter between the variable name and type.

• ⁠\n⁠ after the type to separate it from the description.

Default type Parsing Syntax

The type portion of the ⁠@typed⁠ tag syntax will handle a bit of syntax as special cases.

• ⁠[type]⁠: Types wrapped in brackets, for example ⁠[roxygen2::roxy_tags()]⁠ will be left as-is, without wrapping the string in backticks to display as inline code and preserve the native roxygen2 reference link.

  #' @typed arg: [package::function()]
  #'   long form description.
  

• `type`: Types wrapped in backticks will be kept as-is. Additional backticks will not be inserted.

  #' @typed arg: `class`
  #'   long form description.
  

• "type" or 'type': Types wrapped in quotes (either single or double), will be provided as literal values, removing the surrounding quotation marks.

  #' @typed arg: "`class_a` or `class_b`"
  #'   depending on the class of the object provided, either an `"A"`
  #'   or a `"B"`.
  

Custom type Parsing Function

The above defaults are meant to cover most use cases and should be sufficient for all but the most elaborate development practices. If you need to go beyond these default behaviors, you can also provide a parsing function, accepting the parsed roxygen tag as well as the raw contents.

The function accepts the roxygen2::roxy_tag() produced when parsing the tag, whose ⁠$val⁠ contains fields name, type and description. For convenience, the ⁠$val⁠ contents is unpacked as arguments, though the structure of this tag is liable to change.

To implement a typescript-style class union syntax,

#' @typed arg: class_a | class_b | class_c
#'   depending on the class of the object provided, either an `"A"`
#'   or a `"B"`.

to produce the parameter definition

(`class_a`, `class_c` or `class_b`) depending on the class of the object
provided, either an `"A"`, `"B"` or a `"C"`.

we might define the following in DESCRIPTION (or in man/roxytypes/meta.R).

Config/roxytypes: list(
  format = function(tag, ..., name, type, description) {
    types <- paste0("`", trimws(strsplit(type, "|", fixed = TRUE)[[1]]), "`")
    types <- glue::glue_collapse(types, sep = ", ", last = " or ")
    paste0("(", types, ") ", description)
  }
)

Parse a raw ⁠@typed⁠ tag

Description

Parse a raw ⁠@typed⁠ tag

Usage

try_parse_typed(raw)

Arguments

Parse a raw ⁠@typedreturn⁠ tag

Description

Parse a raw ⁠@typedreturn⁠ tag

Usage

try_parse_typedreturn(raw)

Arguments

roxygen2 ⁠@typedreturn⁠ tag

Description

The ⁠@typedreturn⁠ tag introduces a syntax for defining return types as a roxygen2 tag.

Usage

#' @typedreturn <type>
#'   <description>

Details

There is one important syntactic features:

• ⁠\n⁠ after the type to separate it from the description.

vapply helpers

Description

vapply helpers

Usage

vlapply(..., FUN.VALUE = logical(1L))

vcapply(..., FUN.VALUE = character(1L))

Arguments

Functions

• vlapply(): Logical vapply

• vcapply(): Character vapply

A helper to apply field names to all roxy_tag val fields

Description

A helper to apply field names to all roxy_tag val fields

Usage

with_roxy_field_subclass(x)

Arguments

Value

(⁠: list⁠) A nearly identical list, where elements have additional subclasses based on their field names.