help.search {base}

R Documentation

Search the Help System

Description

Allows for searching the help system for documentation matching a given character string in the (file) name, alias, title, or keyword entries (or any combination thereof), using either fuzzy matching or regular expression matching. Names and titles of the matched help entries are nicely displayed.

Usage

help.search(pattern, fields = c("alias", "title"),
            apropos, keyword, whatis, ignore.case = TRUE,
            package = NULL, lib.loc = NULL,
            help.db = getOption("help.db"),
            verbose = getOption("verbose"),
            rebuild = FALSE, agrep = NULL)

Arguments

pattern	a character string to be matched in the specified fields. If this is given, the arguments apropos, keyword, and whatis are ignored.
fields	a character vector specifying the fields of the help data bases to be searched. The entries must be abbreviations of "name", "alias", "title", and "keyword", corresponding to the help page's (file) name, the topics it provides documentation for, its title, and the keywords it can be classified to.
apropos	a character string to be matched in the help page topics and title.
keyword	a character string to be matched in the help page keywords.
whatis	a character string to be matched in the help page topics.
ignore.case	a logical. If TRUE, case is ignored during matching; if FALSE, pattern matching is case sensitive.
package	a character vector with the names of packages to search through, or NULL in which case all available packages in the specified library trees lib.loc are searched.
lib.loc	a character vector describing the location of R library trees to search through, or NULL. The default value of NULL corresponds to all libraries currently known.
help.db	a character string giving the file path to a previously built and saved help data base, or NULL.
verbose	logical; if TRUE, the search process is traced.
rebuild	a logical indicating whether the help data base should be rebuilt.
agrep	if NULL (the default) and the character string to be matched consists of alphanumeric characters, whitespace or a dash only, approximate (fuzzy) matching via agrep is used; otherwise, it is taken to contain a regular expression to be matched via grep. If FALSE, approximate matching is not used. Otherwise, one can give a numeric or a list specifying the maximal distance for the approximate match, see argument max.distance in the documentation for agrep.

Details

Upon installation of a package, a contents data base which contains the information on name, aliases, title and keywords is computed from the Rd files in the package and serialized as ‘Rd.rds’ in the ‘Meta’ subdirectory of the top-level package installation directory (or, prior to R 1.7, as ‘CONTENTS’ in Debian Control Format with aliases and keywords collapsed to character strings in the top-level package installation directory). This is the data base searched by help.search().

The arguments apropos and whatis play a role similar to the Unix commands with the same names.

If possible, the help data base is saved to the file ‘help.db’ in the ‘.R’ subdirectory of the user's home directory or the current working directory.

Note that currently, the aliases in the matching help files are not displayed.

Value

The results are returned in an object of class "hsearch", which has a print method for nicely displaying the results of the query. This mechanism is experimental, and may change in future versions of R.

See Also

help; help.start for starting the hypertext (currently HTML) version of R's online documentation, which offers a similar search mechanism.

apropos uses regexps and has nice examples.

Examples

help.search("linear models")    # In case you forgot how to fit linear
                                # models
help.search("non-existent topic")
## Not run: 
help.search("print")            # All help pages with topics or title
                                # matching `print'
help.search(apropos = "print")  # The same

help.search(keyword = "hplot")  # All help pages documenting high-level
                                # plots.

## Help pages with documented topics starting with 'try'.
help.search("\\btry", fields = "alias")
## Do not use '^' or '$' when matching aliases or keywords
## (unless all packages were installed using R 1.7 or newer).

## End(Not run)

---