Package 'gbRd'

Utilities for processing Rd objects and files

Description

Provides utilities for processing Rd objects and files. Extract argument descriptions and other parts of the help pages of functions. The main purpose of the functions is to facilitate extraction of descriptions of function arguments for presentation of simplified usage descriptions.

Author(s)

Georgi N. Boshnakov

Maintainer: Georgi N. Boshnakov <[email protected]>

---

Return all or selected sections of a help topic as an Rd object

Description

Return all or selected sections of a help topic as an Rd object. The help topic may be an Rd object, a character string (for the help function), or the value returned by the help function.

Usage

Rd_fun(x, topic, pkgname = "", help_type = "text", verbose = FALSE,
          try.all.packages = FALSE, keep_section = TRUE)

Arguments

x	the help object. Its class may be "Rd", "character", or "help_files_with_topic".
topic	unused, see Details
pkgname	unused, see Details
help_type	type of help, see Details and help.
verbose	logical value, see help.
try.all.packages	logical value, see help.
keep_section	the section(s) to keep. If it is a character vector of length at least one, the sections listed in it (plus ⁠\title⁠ and ⁠\name⁠) are kept in the result, the rest are dropped. Otherwise all sections are returned.

Details

If the class of x is neither "Rd" nor "help_files_with_topic", x is assumed to be appropriate for a call to help. The call is made to obtain an object of class "help_files_with_topic", which is then processed as below. Arguments help_type, verbose and try.all.packages are used only in this case.

If the class of x is "help_files_with_topic" (usually the result of a call to help), then an Rd object is obtained using tools:::fetchRdDB.

The Rd object (x itself or the one obtained as described above) is examined and sections are retained or dropped as specified by argument keep_section. Sections ⁠\title⁠ and ⁠\name⁠ are always kept in the returned value since otherwise the Rd object is considered invalid by (some of?) the system functions.

Value

an Rd object

Note

Note that help works with ‘installed’ help. So, when the Rd object is obtained via a call to help it will not necessarilly be the one that would be obtained from the original Rd file if that contains ⁠\Sexpr⁠ instructions with stage=build or stage=install optional argument. This is not a problem for the intended purpose of this package to allow for extraction of pieces of the help for selective display and related run-time actions. For manipulation of source Rd files one can supply an Rd object obtained by parse_Rd-ying it.

FIXME: I wrote this function in a hurry when it turned out that the help system has changed in R version 2.10, needs clean up.

todo: In recent versions of R, help may return more than one file (see paths in this function's source), this needs to be handled.

Author(s)

Georgi N. Boshnakov

Examples

# 1st arg is name of a function
Rd_fun("data.frame",keep_section="\\arguments")
Rd_fun("seq",keep_section="\\arguments")

# 1st arg is the value of a call to help()
h1 <- help("seq")
class(h1)
Rd_fun(h1,keep_section="\\title") # note: in Rd file the number of
Rd_fun(h1,keep_section="\\arguments") # backslashes is twice that in
                                        # the rendered doc.

---

Extract selected help sections as text.

Description

Extract selected help sections as text.

Usage

Rd_help2txt(x, topic, pkgname = "", help_type = "text",
               verbose = FALSE, try.all.packages = FALSE,
               keep_section = TRUE, omit_sec_header = FALSE)

Arguments

x	the help object. Its class may be "Rd", string or "help_files_with_topic".
topic	passed on to Rd_fun
pkgname	passed on to Rd_fun
help_type	passed on to Rd_fun
verbose	passed on to Rd_fun
try.all.packages	passed on to Rd_fun
keep_section	the section to keep. If it is a character vector of length at least one, the sections listed in it (plus ⁠\title⁠ and ⁠\name⁠) are kept in the result, the rest are dropped. Otherwise all sections are returned.
omit_sec_header	whether to omit or not the section header

Details

Basically, this function calls Rd_fun to get an Rd object containing the required help sections, then converts them to text with tools::Rd2txt. At this point however unwanted sections may be present since tools::Rd2txt requires ⁠\title⁠ and ⁠\name⁠. If ⁠\title⁠ is not an element of keep_section, it should be dropped. Other header information is dropped if omit_sec_header = TRUE. The way this is done is crude and based on inspection. It would be better done using the Rd object but then I might need to, effectively reprogram Rd2txt.

FIXME: The above was done for version R-2.10 (I think), see if a more modular version is available in current versions of R. Also, it is tested only with help_type="text".

FIXME: Arguments whose description is marked "passed on to Rd_fun" could be replaced by a "..." argument.

Value

A character vector containing the text of the selected help sections.

Note

In R-2.12.0 the function tools::Rd2txt acquired a fragment argument. So, tools::Rd2txt now works with fragments and can be used directly in many cases.

Author(s)

Georgi N. Boshnakov

Examples

# 1st arg is the name of a function
Rd_help2txt("data.frame",keep_section="\\arguments")

Rd_help2txt("seq",keep_section="\\examples")
Rd_help2txt("seq",keep_section="\\examples",omit_sec_header=TRUE)

---

Wrap an object so that it can be used as a section element of an Rd object.

Description

Wrap an object so that it can be used as a section element of an Rd object.

Usage

Rdo_set_sectag(s,sectag,eltag)
Rd_title(s)
Rd_name(s)
Rd_args(s)

Arguments

s	the object to be wrapped, often a string, see Details
sectag	the section tag, a string
eltag	the element tag, a string

Details

Rdo_set_sectag sets atrribute "Rd_tag" of the object s to eltag, then wraps s in list() with "Rd_tag" attribute sectag.

The remaining functions provide one-argument access for some frequently used special cases. eltag is "TEXT" for Rd_title and "VERB" for Rd_name and Rd_args. The values of sectag are ⁠\title⁠, ⁠\name⁠ and ⁠\arguments⁠, respectively.

Value

A tagged list as described in Details.

Author(s)

Georgi N. Boshnakov

Examples

Rd_title("My seq")
Rd_name("myseq")

"a" %in% letters

# to do: more examples

---

Extract the descriptions of one or more arguments of a function

Description

Extract help descriptions of one or more arguments of a function and return them as a string.

Usage

Rdo_args2txt(rdo, arg, title = "Hhh", name = "Aa", type = "text")

Arguments

rdo	the documentation for the topic, typically an Rd object but may be anything that Rd_fun accepts: Rd object, name of a function, or the value returned by help.
arg	name(s) of argument(s) to describe, a character vector, see also Details section
title	Title, a string
name	name, a string
type	type of the help, defaults to "text"

Details

The title and name fields are there, since descriptions of arguments usually do not use the same header as the description of the corresponding function.

The current defaults show that this is still not finished.

Value

A string (character vector of length one).

Author(s)

Georgi N. Boshnakov

See Also

Rdo_args2txt_list

Examples

# ?seq
cat(Rdo_args2txt("seq", c("by", "...")))
cat(Rdo_args2txt("seq", c("from", "by")))

---

Extract the descriptions of the arguments of a function

Description

Collect the descriptions of the arguments of a function in a named list with one element per argument.

Usage

Rdo_args2txt_list(x, arg, ...)

Arguments

x	help object, may be any of the types that Rd_fun accepts: Rd object, name of a function, or the the value returned by help.
arg	A character vector naming the arguments to describe. If arg is missing, descriptions of all arguments are extracted.
...	additional arguments to pass to Rdo_args2txt

Details

If several arguments are described in a single documentation entry, then the whole text of the entry is given for each of the arguments.

Value

A named list with one entry (a string) for each of the requested arguments.

Author(s)

Georgi N. Boshnakov

See Also

Rdo_args2txt

Examples

# each arg always gets an individual entry in the list;
# compare:
Rdo_args2txt_list("seq", c("from", "to", "by"))
# to:
cat(Rdo_args2txt("seq", c("from", "to", "by")))

---

Create basic Rd objects

Description

Create basic Rd objects with fields title, name and arguments.

Usage

Rdo_create(arguments, title = "Dummy title", name = "dummy name")

Rdo_empty(rdtag)

Arguments

arguments	The argument field of an Rd object
title	the title, a string
name	the name, atring
rdtag	a value for "Rd_tag", a string.

Details

Rdo_create is an auxiliary function used to prepare arguments for a call to Rd_help2txt since the latter works on Rd objects or text but not on Rd sections.

Rdo_empty creates an empty object of class "Rd" if rdtag is missing. If rdtag is supplied the object is a list with attribute "Rd_tag" set to rdtag.

Value

an Rd object or a list with attribute "Rd_tag".

Author(s)

Georgi N. Boshnakov

Examples

require(tools)   # for Rd2txt
a1 <- Rdo_get_args("seq")
a1
Rdo_create(a1)
Rd2txt(Rdo_create(a1))

a2 <- Rdo_get_args("seq", c("from", "to", "by"))
a2
Rdo_create(a2)
Rd2txt(Rdo_create(a2))

Rdo_empty()
class(Rdo_empty())
str(Rdo_empty())

---

Extract argument description from a help topic

Description

Extract argument description from a help topic.

Usage

Rdo_get_args(rd, args, ...)
Rdo_get_arg(rd, arg)

Arguments

rd	the documentation for the topic, typically an Rd object but may be anything that Rd_fun accepts.
arg	an argument name, a string
args	names of arguments to describe, a character vector, see also Details section
...	not used

Details

If arguments is missing, descriptions of all arguments are returned.

Effort is made to handle the case when two or more arguments are described in a single entry. In that case it is not possible to disentangle the description automatically. So, the description is returned as is. Also, only one copy of the description is returned, see the examples with the from and to arguments of function seq.

The ... argument is handled, as well, give it as the string ⁠...⁠ in args.

Rdo_get_arg simply calls Rdo_get_args and returns the first element of its value. This means that arg is expected to be of length one, but this is not enforced. Note also that Rdo_get_arg is not completely equivalent to calling Rdo_get_args with length(args)=1.

Value

For Rdo_get_args, an Rd fragment representing the (part of) help section ⁠\arguments⁠ containing descriptions of the requested arguments.

For Rdo_get_arg an Rd fragment representing the help for a single argument.

Author(s)

Georgi N. Boshnakov

Examples

h1 <- help("seq")
Rdo_get_args(h1)
Rdo_get_args(h1,"by")
Rdo_get_args(h1,"length.out")
Rdo_get_args(h1,"...")
Rdo_get_args(h1,"from")
Rdo_get_args(h1,c("from","by"))
Rdo_get_args(h1,c("from", "to"))

Rdo_get_args("seq")
Rdo_get_args("seq","by")
Rdo_get_args("seq","length.out")
Rdo_get_args("seq","...")
Rdo_get_args("seq","from")
Rdo_get_args("seq",c("from","by"))
Rdo_get_args("seq",c("from", "to"))

---

Extract a section element from an Rd object or Rd fragment

Description

Extract a section element from an Rd object or Rd fragment.

Usage

Rdo_section(rdo, sec)

Arguments

rdo	an Rd object or fragment
sec	the required section, a string

Details

If the class or the "Rd_tag" attribute of rdo is "Rd" the required section is extracted. Otherwise, if this attribute is equal to sec, then rdo is returned.

In all other cases it is assumed that rdo is the contents of the required section, its "Rd_tag" attribute is set to sec and returned without further modification.

Value

An Rd fragment for use as a section element of an Rd object

Note

This function is intended for use by other functions which work with Rd objects.

Author(s)

Georgi N. Boshnakov

---