R: Convert f_usage objects to text appropriate for usage...

deparse_usage {Rdpack} | R Documentation

## Convert f_usage objects to text appropriate for usage sections in Rd files

### Description

Converts f_usage objects to text appropriate for usage sections in Rd files. Handles S3 methods.

### Usage

    deparse_usage(x)
    deparse_usage1(x, width = 72)
    ## S3 method for class 'f_usage'
    as.character(x, ... )

### Arguments

`x` | an object from class `"f_usage"`. For `deparse_usage`, `x` can also be a list of `"f_usage"` objects.
`width` | maximal width of text on a line.
`...` | ignored.

### Details

Both, `deparse_usage1` and the `as.character` method for class `"f_usage"`, convert an `"f_usage"` object to a character string suitable for Rd documentation. The `as.character` method is the user level function (it just calls `deparse_usage1`), `deparse_usage1` is internal function for programming. In the example below the first command creates an `"f_usage"` object, then the second converts it to character string.

    (a <- pairlist2f_usage1(formals(cor), "cor"))
    ##: name      = cor
    ##: S3class   =
    ##: S4sig     =
    ##: infix     = FALSE
    ##: fu        = TRUE
    ##: argnames  = x y use method
    ##: defaults  : y = NULL
    ##:             use = "everything"
    ##:             method = c("pearson", "kendall", "spearman")

    cat(as.character(a))
    ##: cor(x, y = NULL, use = "everything",
    ##:     method = c("pearson", "kendall", "spearman"))

Each usage entriy is formatted and, if necessary, split over several lines. The width (number of characters) on a line can be changed with argument `width`.

`deparse_usage` can be used when `x` is a list of `"f_usage"` objects. It calls `deparse_usage1` with each of them and returns a character vector with one element for each component of `x`. When `x` is an object from class `"f_usage"`, `deparse_usage` is equivalent to `deparse_usage1`.

### Value

For `deparse_usage1` and `as.character.f_usage`, a named character vector of length one (the name is the function name).

For `deparse_usage`, a named character vector with one entry for the usage text for each function.

### Author(s)

Georgi N. Boshnakov

### See Also

`pairlist2f_usage1`

### Examples

    cur_wd <- getwd()
    setwd(tempdir())

    ## prepare a list of "f_usage" objects
    fnseq <- reprompt(seq)            # get and save the help page of "seq"
    rdoseq <- tools::parse_Rd(fnseq)  # parse the Rd file
    ut <- get_usage_text(rdoseq)      # get the contents of the usage section
    cat(ut, "\n")                     #     of seq() (a character string)
    utp <- parse_usage_text(ut)       # parse to a list of "f_usage" objects

    ## deparse the "f_usage" list - each statement gets a separate string
    cat(deparse_usage(utp), sep = "\n")

    ## explore some of the usage entries individually;
    ## the generic seq() has a boring signature
    utp[[1]]
    as.character(utp[[1]])
    deparse_usage1(utp[[1]])  # same

    ## the default S3 method is more interesting
    utp[[2]]
    cat(deparse_usage1(utp[[2]]))
    cat(as.character(utp[[2]]))   # same

    unlink(fnseq)
    setwd(cur_wd)

[Package Rdpack version 0.10-1 Index]