usage: Show the usage of a function

Description

Print the reformatted usage of a function. The arguments of the function are searched by argsAnywhere(), so the function can be either exported or non-exported from a package. S3 methods will be marked.

Usage

usage(
  FUN,
  width = getOption("width"),
  tidy = TRUE,
  output = TRUE,
  indent.by.FUN = FALSE,
  fail = c("warn", "stop", "none")
)

Value

Reformatted usage code of a function, in character strings (invisible).

Arguments

FUN: The function name.
width: The width of the output.
tidy: Whether to reformat the usage code.
output: Whether to print the output to the console (via cat()).
indent.by.FUN: Whether to indent subsequent lines by the width of the function name (see “Details”).
fail: A character string that represents the action taken when the width constraint is unfulfillable. "warn" and "stop" will signal warnings and errors, while "none" will do nothing.

Details

Line breaks in the output occur between arguments. In particular, default values of arguments will not be split across lines.

When indent.by.FUN is FALSE, indentation is set by the option getOption("formatR.indent", 4L), the default value of the indent argument of tidy_source().

Examples

Run this code

library(formatR)
usage(var)

usage(plot)

usage(plot.default)  # default method
usage("plot.lm")  # on the 'lm' class

usage(usage)

usage(barplot.default, width = 60)  # output lines have 60 characters or less

# indent by width of 'barplot('
usage(barplot.default, width = 60, indent.by.FUN = TRUE)

if (FALSE) {
# a warning is raised because the width constraint is unfulfillable
usage(barplot.default, width = 30)
}