R: Parse formal arguments of functions

parse_pairlist {Rdpack} | R Documentation

## Parse formal arguments of functions

### Description

Parse formal arguments of functions and convert them to f_usage objects.

### Usage

    parse_pairlist(x)

    pairlist2f_usage1(x, name, S3class = "", S4sig = "", infix = FALSE,
                      fu = TRUE)

### Arguments

`x` | a pairlist representing the arguments of a function.
`name` | function name.
`S3class` | S3 class, see ‘Details’
`S4sig` | S4 signature, see Details.
`infix` | if `TRUE` the function usage is in infix form, see Details.
`fu` | if TRUE the object is a function, otherwise it is something else (e.g. a variable or a constant like `pi` and `Inf`).

### Details

These functions are mostly internal.

`parse_pairlist` parses the pairlist object, `x`, into a list with two components. The first component contains the names of the arguments. The second component is a named list containing the default values, converted to strings. Only arguments with default values have entries in the second component (so, it may be of length zero). If `x` is empty or `NULL`, both components have length zero. An example:

    parse_pairlist(formals(system.file))
    ##: $argnames
    ##: [1] "..."      "package"  "lib.loc"  "mustWork"

    ##: $defaults
    ##:    package    lib.loc   mustWork
    ##: "\"base\""     "NULL"    "FALSE"

`pairlist2f_usage1()` creates an object of S3 class `"f_usage"`. The object contains the result of parsing `x` with `parse_pairlist(x)` and a number of additional components which are copies of the remaining arguments to the function (without any processing). The components are listed in section Values. `S3class` is set to an S3 class for for S3 methods, `S4sig` is the signature of an S4 method (as used in Rd macro `\S4method`). `infix` is `TRUE` for the rare occations when the function is primarily used in infix form.

Class `"f_usage"` has a method for `as.character()` which generates a text suitable for inclusion in Rd documentation.

    pairlist2f_usage1(formals(summary.lm), "summary", S3class = "lm")
    ##: name      = summary
    ##: S3class   = lm
    ##: S4sig     =
    ##: infix     = FALSE
    ##: fu        = TRUE
    ##: argnames  = object correlation symbolic.cor ...
    ##: defaults  : correlation = FALSE
    ##:             symbolic.cor = FALSE

### Value

For `parse_pairlist`, a list with the following components:

`argnames` | the names of all arguments, a character vector
`defaults` | a named character vector containing the default values, converted to character strings. Only arguments with defaults have entries in this vector.

For `pairlist2f_usage1`, an object with S3 class `"f_usage"`. This is a list as for `parse_pairlist` and the following additional components:

`name` | function name, a character string.
`S3class` | S3 class, a character string; `""` if not an S3 method.
`S4sig` | S4 signature; `""` if not an S4 method.
`infix` | a logical value, `TRUE` for infix operators.
`fu` | indicates the type of the object, usually `TRUE`, see Details.

### Author(s)

Georgi N. Boshnakov

### See Also

`promptUsage` accepts `f_usage` objects, `get_usage`

### Examples

    parse_pairlist(formals(lm))
    parse_pairlist(formals(system.file))
    s_lm <- pairlist2f_usage1(formals(summary.lm), "summary", S3class = "lm")
    s_lm
    as.character(s_lm)

[Package Rdpack version 0.10-1 Index]