Tools for Package Development

Tools for Package Development [R logo]

Help pages for package `tools' version 2.4.1

tools-package | Tools for Package Development
Adobe_glyphs | Conversion Tables between Character Sets
buildVignettes | List and Build Package Vignettes
charset_to_Unicode | Conversion Tables between Character Sets
checkDocFiles | QC Checks for R Code and/or Documentation
checkDocStyle | QC Checks for R Code and/or Documentation
checkFF | Check Foreign Function Calls
checkMD5sums | Check and Create MD5 Checksum Files
checkReplaceFuns | QC Checks for R Code and/or Documentation
checkS3methods | QC Checks for R Code and/or Documentation
checkTnF | Check R Packages or Code for T/F
checkVignettes | Check Package Vignettes
codoc | Check Code/Documentation Consistency
codocClasses | Check Code/Documentation Consistency
codocData | Check Code/Documentation Consistency
delimMatch | Delimited Pattern Matching
encoded_text_to_latex | Translate non-ASCII Text to LaTeX Escapes
file_path_as_absolute | File Utilities
file_path_sans_ext | File Utilities
file_test | File Utilities
getDepList | Functions to Retrieve Dependency Information
installFoundDepends | A function to install unresolved dependencies
list_files_with_exts | File Utilities
list_files_with_type | File Utilities
makeLazyLoading | Lazy Loading of Packages
md5sum | Compute MD5 Checksums
package.dependencies | Check Package Dependencies
pkgDepends | Functions to Retrieve Dependency Information
pkgVignettes | List and Build Package Vignettes
print.checkDocFiles | QC Checks for R Code and/or Documentation
print.checkDocStyle | QC Checks for R Code and/or Documentation
print.checkFF | Check Foreign Function Calls
print.checkReplaceFuns | QC Checks for R Code and/or Documentation
print.checkS3methods | QC Checks for R Code and/or Documentation
print.checkTnF | Check R Packages or Code for T/F
print.checkVignettes | Check Package Vignettes
print.codoc | Check Code/Documentation Consistency
print.codocClasses | Check Code/Documentation Consistency
print.codocData | Check Code/Documentation Consistency
print.undoc | Find Undocumented Objects
QC | QC Checks for R Code and/or Documentation
Rdindex | Generate Index from Rd Files
Rd_db | Rd Utilities
Rd_parse | Rd Utilities
read.00Index | Read 00Index-style Files
texi2dvi | Compile LaTeX Files
tools | Tools for Package Development
tools-deprecated | Deprecated Objects in Package tools
undoc | Find Undocumented Objects
vignetteDepends | Retrieve Dependency Information for a Vignette
write_PACKAGES | Generate PACKAGES files
xgettext | Extract Translatable Messages from R Files in a Package
xgettext2pot | Extract Translatable Messages from R Files in a Package
xngettext | Extract Translatable Messages from R Files in a Package


List and Build Package Vignettes

Description

Run Sweave and texi2dvi on all vignettes of a package.

Usage

buildVignettes(package, dir, lib.loc = NULL, quiet = TRUE)
pkgVignettes(package, dir, lib.loc = NULL)

Arguments

package | a character string naming an installed package. If given, Sweave files are searched in subdirectory doc.
dir | a character string specifying the path to a package's root source directory. This subdirectory inst/doc is searched for Sweave files.
lib.loc | a character vector of directory names of R libraries, or NULL. The default value of NULL corresponds to all libraries currently known. The specified library trees are used to to search for package.
quiet | logical. Run Sweave and texi2dvi in quiet mode.

Value

buildVignettes is called for its side effect of creating the PDF versions of all vignettes.
pkgVignettes returns an object of class "pkgVignettes".

[Package tools version 2.4.1 Index]


Conversion Tables between Character Sets

Description

charset_to_Unicode is a matrix of Unicode points with columns for the common 8-bit encodings.

Adobe_glyphs is a dataframe which gives Adobe glyph names for Unicode points. It has two character columns, "adobe" and "unicode" (a 4-digit hex representation).

Usage

charset_to_Unicode

Adobe_glyphs

Details

charset_to_Unicode is an integer matrix of class c("noquote", "hexmode") so prints in hexadecimal. The mappings are those used by libiconv: there are differences in the way quotes and minus/hyphen are mapped between sources (and the postscript encoding files use a different mapping).

Adobe_glyphs include all the Adobe glyph names which correspond to single Unicode characters. It is sorted by Unicode point and within a point alphabetically on the glyph(there can be more than one name for a Unicode point). The data are in the file ‘R_HOME/share/encodings/Adobe_glyphlist’.

Source

http://partners.adobe.com/public/developer/en/opentype/glyphlist.txt

Examples

## find Adobe names for ISOLatin2 chars.
latin2 <- charset_to_Unicode[, "ISOLatin2"]
aUnicode <- as.numeric(paste("0x", Adobe_glyphs$unicode, sep=""))
keep <- aUnicode %in% latin2
aUnicode <- aUnicode[keep]
aAdobe <- Adobe_glyphs[keep, 1]
## first match
aLatin2 <- aAdobe[match(latin2, aUnicode)]
## all matches
bLatin2 <- lapply(1:256, function(x) aAdobe[aUnicode == latin2[x]])
format(bLatin2, justify="none")


Check Foreign Function Calls

Description

Performs checks on calls to compiled code from R code. Currently only whether the interface functions such as .C and .Fortran are called with a "NativeSymbolInfo" first argument or with argument PACKAGE specified, which is highly recommended to avoid name clashes in foreign function calls.

Usage

checkFF(package, dir, file, lib.loc = NULL,
        verbose = getOption("verbose"))

Arguments

package | a character string naming an installed package. If given, the installed R code of the package is checked.
dir | a character string specifying the path to a package's root source directory. This should contain the subdirectory R (for R code). Only used if package is not given.
file | the name of a file containing R code to be checked. Used if neither package nor dir are given.
lib.loc | a character vector of directory names of R libraries, or NULL. The default value of NULL corresponds to all libraries currently known. The specified library trees are used to to search for package.
verbose | a logical. If TRUE, additional diagnostics are printed (and the result is returned invisibly).

Details

Note that we can only check if the name argument is a symbol or a character string, not what class of object the symbol resolves to at run-time.

If the package has a namespace and if that contains a useDynLib directive, calls in top-level functions in the package are not reported as their symbols will be preferentially looked up in the DLL named in the first useDynLib directive.

Value

An object of class "checkFF", which currently is a list of the (parsed) foreign function calls with a character first argument and no PACKAGE argument.
There is a print method to display the information contained in such objects.

Warning

This function is still experimental. Both name and interface might change in future versions.

See Also

.C, .Fortran; Foreign.

Examples

checkFF(package = "stats", verbose = TRUE)


Check and Create MD5 Checksum Files

Description

checkMD5sums checks the files against a file MD5.

Usage

checkMD5sums(pkg, dir)

Arguments

pkg | the name of an installed package
dir | the path to the top-level directory of an installed package.

Details

The file ‘MD5’ which is created is in a format which can be checked by md5sum -c MD5 if a suitable command-line version of md5sum is available. (One is supplied in the bundle at http://www.murdoch-sutherland.com/Rtools/tools.zip.)

If dir is missing, an installed package of name pkg is searched for.

The private function tools:::.installMD5sums is used to create MD5 files in the Windows build.

Value

checkMD5sums returns a logical, NA if there is no MD5 file to be checked.

See Also

md5sum


Check R Packages or Code for T/F

Description

Checks the specified R package or code file for occurrences of T or F, and gathers the expression containing these. This is useful as in R T and F are just variables which are set to the logicals TRUE and FALSE by default, but are not reserved words and hence can be overwritten by the user. Hence, one should always use TRUE and FALSE for the logicals.

Usage

checkTnF(package, dir, file, lib.loc = NULL)

Arguments

package | a character string naming an installed package. If given, the installed R code and the examples in the documentation files of the package are checked. R code installed as an image file cannot be checked.
dir | a character string specifying the path to a package's root source directory. This must contain the subdirectory ‘R’ (for R code), and should also contain ‘man’ (for documentation). Only used if package is not given. If used, the R code files and the examples in the documentation files are checked.
file | the name of a file containing R code to be checked. Used if neither package nor dir are given.
lib.loc | a character vector of directory names of R libraries, or NULL. The default value of NULL corresponds to all libraries currently known. The specified library trees are used to to search for package.

Value

An object of class "checkTnF" which is a list containing, for each file where occurences of T or F were found, a list with the expressions containing these occurrences. The names of the list are the corresponding file names.
There is a print method for nicely displaying the information contained in such objects.

Warning

This function is still experimental. Both name and interface might change in future versions.


Check Package Vignettes

Description

Check all Sweave files of a package by running Sweave and/or Stangle on them. All R source code files found after the tangling step are sourceed to check whether all code can be executed without errors.

Usage

checkVignettes(package, dir, lib.loc = NULL, tangle = TRUE,
               weave = TRUE, workdir = c("tmp", "src", "cur"),
               keepfiles = FALSE)

Arguments

package | a character string naming an installed package. If given, Sweave files are searched in subdirectory doc.
dir | a character string specifying the path to a package's root source directory. This subdirectory inst/doc is searched for Sweave files.
lib.loc | a character vector of directory names of R libraries, or NULL. The default value of NULL corresponds to all libraries currently known. The specified library trees are used to to search for package.
tangle | Perform a tangle and source the extraced code?
weave | Perform a weave?
workdir | Directory used as working directory while checking the vignettes. If "tmp" then a temporary directory is created, this is the default. If "src" then the directory containing the vignettes itself is used, if "cur" then the current working directory of R is used.
keepfiles | Delete file in temporary directory? This option is ignored when workdir!="tmp".

Value

An object of class "checkVignettes" which is a list with the error messages found during the tangle and weave steps. There is a print method for nicely displaying the information contained in such objects.


Check Code/Documentation Consistency

Description

Find inconsistencies between actual and documented “structure” of R objects in a package. codoc compares names and optionally also corresponding positions and default values of the arguments of functions. codocClasses and codocData compare slot names of S4 classes and variable names of data sets, respectively.

Usage

codoc(package, dir, lib.loc = NULL,
      use.values = NULL, verbose = getOption("verbose"))
codocClasses(package, lib.loc = NULL)
codocData(package, lib.loc = NULL)

Arguments

package | a character string naming an installed package.
dir | a character string specifying the path to a package's root source directory. This must contain the subdirectories ‘man’ with R documentation sources (in Rd format) and ‘R’ with R code. Only used if package is not given.
lib.loc | a character vector of directory names of R libraries, or NULL. The default value of NULL corresponds to all libraries currently known. The specified library trees are used to to search for package.
use.values | if FALSE, do not use function default values when comparing code and docs. Otherwise, compare all default values if TRUE, and only the ones documented in the usage otherwise (default).
verbose | a logical. If TRUE, additional diagnostics are printed.

Details

The purpose of codoc is to check whether the documented usage of function objects agrees with their formal arguments as defined in the R code. This is not always straightforward, in particular as the usage information for methods to generic functions often employs the name of the generic rather than the method.

The following algorithm is used. If an installed package is used, it is loaded (unless it is the base package), after possibly detaching an already loaded version of the package. Otherwise, if the sources are used, the R code files of the package are collected and sourced in a new environment. Then, the usage sections of the Rd files are extracted and parsed “as much as possible” to give the formals documented. For interpreted functions in the code environment, the formals are compared between code and documentation according to the values of the argument use.values. Synopsis sections are used if present; their occurrence is reported if verbose is true.

If a package has a namespace both exported and unexported objects are checked, as well as registered S3 methods. (In the unlikely event of differences the order is exported objects in the package, registered S3 methods and finally objects in the namespace and only the first found is checked.)

Currently, the R documentation format has no high-level markup for the basic “structure” of classes and data sets (similar to the usage sections for function synopses). Variable names for data frames in documentation objects obtained by suitably editing “shells” created by prompt are recognized by codocData and used provided that the documentation object is for a single data frame (i.e., only has one alias). codocClasses analogously handles slot names for classes in documentation objects obtained by editing shells created by promptClass.

Help files named pkg_name-defunct.Rd for the appropriate pkg_name are checked more loosely, as they may have undocumented arguments.

Value

codoc returns an object of class "codoc". Currently, this is a list which, for each Rd object in the package where an inconsistency was found, contains an element with a list of the mismatches (which in turn are lists with elements code and docs, giving the corresponding arguments obtained from the function's code and documented usage).
codocClasses and codocData return objects of class "codocClasses" and "codocData", respectively, with a structure similar to class "codoc".
There are print methods for nicely displaying the information contained in such objects.

Warning

Both codocClasses and codocData are still experimental. Names, interfaces and values might change in future versions.

Note

The default for use.values has been changed from FALSE to NULL, for R versions 1.9.0 and later.

See Also

undoc, QC


Delimited Pattern Matching

Description

Match delimited substrings in a character vector, with proper nesting.

Usage

delimMatch(x, delim = c("{", "}"), syntax = "Rd")

Arguments

x | a character vector.
delim | a character vector of length 2 giving the start and end delimiters. Future versions might allow for arbitrary regular expressions.
syntax | currently, always the string "Rd" indicating Rd syntax (i.e., % starts a comment extending till the end of the line, and \ escapes). Future versions might know about other syntaxes, perhaps via “syntax tables” allowing to flexibly specify comment, escape, and quote characters.

Value

An integer vector of the same length as x giving the starting position (in characters) of the first match, or -1 if there is none, with attribute "match.length" giving the length (in characters) of the matched text (or -1 for no match).

See Also

regexpr for “simple” pattern matching.

Examples

x <- c("\value{foo}", "function(bar)")
delimMatch(x)
delimMatch(x, c("(", ")"))


Translate non-ASCII Text to LaTeX Escapes

Description

Translate non-ASCII characters in text to LaTeX escape sequences.

Usage

encoded_text_to_latex(x, encoding = c("latin1", "latin2", "latin9",
                                       "UTF-8", "utf8"))

Arguments

x | a character vector.
encoding | the encoding to be assumed. "latin9" is officially ISO-8859-15 or Latin-9, but known as latin9 to LaTeX's inputenc package.

Details

Non-ASCII characters in x are replaced by an appropriate LaTeX escape sequence, or ? if there is no appropriate sequence.

Even if there is an appropriate sequence, it may not be supported by the font in use. Hyphen is mapped to \-.

Value

A character vector of the same length as x.

See Also

iconv

Examples

x <- "fa\xE7ile"
encoded_text_to_latex(x, "latin1")
## Not run:
## create a tex file to show the upper half of 8-bit charsets
x <- rawToChar(as.raw(160:255), multiple=TRUE)
(x <- matrix(x, ncol=16, byrow=TRUE))
xx <- x
xx[] <- encoded_text_to_latex(x, "latin1") # or latin2 or latin9
xx <- apply(xx, 1, paste, collapse="&")
con <- file("test-encoding.tex", "w")
header <- c(
"\documentclass{article}",
"\usepackage[T1]{fontenc}",
"\usepackage{Rd}",
"\begin{document}",
"\HeaderA{test}{}{test}",
"\begin{Details}\relax",
"\Tabular{cccccccccccccccc}{")
trailer <- c("}", "\end{Details}", "\end{document}")
writeLines(header, con)
writeLines(paste(xx, "\\", sep=""), con)
writeLines(trailer, con)
close(con)
## and some UTF_8 chars
x <- intToUtf8(as.integer(
    c(160:383,0x0192,0x02C6,0x02C7,0x02CA,0x02D8,
      0x02D9, 0x02DD, 0x200C, 0x2018, 0x2019, 0x201C,
      0x201D, 0x2020, 0x2022, 0x2026, 0x20AC)),
               multiple=TRUE)
x <- matrix(x, ncol=16, byrow=TRUE)
xx <- x
xx[] <- encoded_text_to_latex(x, "UTF-8")
xx <- apply(xx, 1, paste, collapse="&")
con <- file("test-utf8.tex", "w")
writeLines(header, con)
writeLines(paste(xx, "\\", sep=""), con)
writeLines(trailer, con)
close(con)
## End(Not run)


File Utilities

Description

Utilities for testing and listing files, and manipulating file paths.

Usage

file_path_as_absolute(x)
file_path_sans_ext(x)
file_test(op, x, y)
list_files_with_exts(dir, exts, all.files = FALSE, full.names = TRUE)
list_files_with_type(dir, type, all.files = FALSE, full.names = TRUE,
                     OS_subdirs = .OStype())

Arguments

x,y | character vectors giving file paths.
op | a character string specifying the test to be performed. Unary tests (only x is used) are "-f" (existence and not being a directory) and "-d" (existence and directory); binary tests are "-nt" (newer than, using the modification dates) and "-ot".
dir | a character string with the path name to a directory.
exts | a character vector of possible file extensions.
all.files | a logical. If FALSE (default), only visible files are considered; if TRUE, all files are used.
full.names | a logical indicating whether the full paths of the files found are returned (default), or just the file names.
type | a character string giving the “type” of the files to be listed, as characterized by their extensions. Currently, possible values are "code" (R code), "data" (data sets), "demo" (demos), "docs" (R documentation), and "vignette" (vignettes).
OS_subdirs | a character vector with the names of OS-specific subdirectories to possibly include in the listing of R code and documentation files. By default, the value of the environment variable R_OSTYPE, or if this is empty, the value of .Platform$OS.type, is used.

Details

file_path_as_absolute turns a possibly relative file path absolute, performing tilde expansion if necessary. Currently, only a single existing path can be given.

file_path_sans_ext returns the file paths without extensions. (Only purely alphanumeric extensions are recognized.)

file_test performs shell-style file tests. Note that file.exists only tests for existence (test -e on some systems) but not for not being a directory.

list_files_with_exts returns the paths or names of the files in directory dir with extension matching one of the elements of exts. Note that by default, full paths are returned, and that only visible files are used.

list_files_with_type returns the paths of the files in dir of the given “type”, as determined by the extensions recognized by R. When listing R code and documentation files, files in OS-specific subdirectories are included if present according to the value of OS_subdirs. Note that by default, full paths are returned, and that only visible files are used.

See Also

file.path, file.info, list.files

Examples

dir <- file.path(R.home(), "library", "stats")
file_test("-d", dir)
file_test("-nt", file.path(dir, "R"), file.path(dir, "demo"))
list_files_with_exts(file.path(dir, "demo"), "R")
list_files_with_type(file.path(dir, "demo"), "demo") # the same
file_path_sans_ext(list.files(file.path(R.home(), "modules")))


Functions to Retrieve Dependency Information

Description

Given a dependency matrix, will create a DependsList object for that package which will include the dependencies for that matrix, which ones are installed, which unresolved dependencies were found online, which unresolved dependencies were not found online, and any R dependencies.

Usage

getDepList(depMtrx, instPkgs, recursive = TRUE, local = TRUE,
           reduce = TRUE, lib.loc = NULL)

pkgDepends(pkg, recursive = TRUE, local = TRUE, reduce = TRUE,
           lib.loc = NULL)

Arguments

depMtrx | A dependency matrix as from package.dependencies
pkg | The name of the package
instPkgs | A matrix specifying all packages installed on the local system, as from installed.packages
recursive | Whether or not to include indirect dependencies
local | Whether or not to search only locally
reduce | Whether or not to collapse all sets of dependencies to a minimal value
lib.loc | What libraries to use when looking for installed packages. NULL indicates all library directories in the user's .libPaths().

Details

The function pkgDepends is a convenience function which wraps getDepList and takes as input a package name. It will then query installed.packages and also generate a dependency matrix, calling getDepList with this information and returning the result.

These functions will retrieve information about the dependencies of the matrix, resulting in a DependsList object. This is a list with four elements:

Depends
A vector of the dependencies for this package.
Installed
A vector of the dependencies which have been satisfied by the currently installed packages.
Found
A list representing the dependencies which are not in Installed but were found online. This list has element names which are the URLs for the repositories in which packages were found and the elements themselves are vectors of package names which were found in the respective repositories. If local=TRUE, the Found element will always be empty.
R
Any R version dependencies.

If recursive is TRUE, any package that is specified as a dependency will in turn have its dependencies included (and so on), these are known as indirect dependencies. If recursive is FALSE, only the dependencies directly stated by the package will be used.

If local is TRUE, the system will only look at the user's local install and not online to find unresolved dependencies.

If reduce is TRUE, the system will collapse the fields in the DependsList object such that a minimal set of dependencies are specified (for instance if there was ('foo', 'foo (>= 1.0.0)', 'foo (>= 1.3.0)'), it would only return 'foo (>= 1.3.0)').

Value

An object of class DependsList

Author(s)

Jeff Gentry

See Also

installFoundDepends

Examples

pkgDepends("tools", local = FALSE)


A function to install unresolved dependencies

Description

This function will take the Found element of a pkgDependsList object and attempt to install all of the listed packages from the specified repositories.

Usage

installFoundDepends(depPkgList, ...)

Arguments

depPkgList | A Found element from a pkgDependsList object
... | Arguments to pass on to install.packages

Details

This function takes as input the Found list from a pkgDependsList object. This list will have element names being URLs corresponding to repositories and the elements will be vectors of package names. For each element, install.packages is called for that URL to install all packages listed in the vector.

Author(s)

Jeff Gentry

See Also

pkgDepends, install.packages

Examples

## Set up a temporary directory to install packages to
tmp <- tempfile()
dir.create(tmp)

pDL <- pkgDepends("tools",local=FALSE)
installFoundDepends(pDL$Found, destdir=tmp)


Lazy Loading of Packages

Description

Tools for Lazy Loading of Packages from a Database.

Usage

makeLazyLoading(package, lib.loc = NULL, compress = TRUE,
                keep.source = getOption("keep.source.pkgs"))

Arguments

package | package name string
lib.loc | library trees, as in library
keep.source | logical; should sources be kept when saving from source
compress | logical; whether to compress entries on the database.

Details

A tool to set up packages for lazy loading from a database. For packages other than base you can use makeLazyLoading(package) to convert them to use lazy loading.

Author(s)

Luke Tierney and Brian Ripley

Examples

  # set up package "splines" for lazy loading -- already done
  ## Not run:
    tools:::makeLazyLoading("splines")

## End(Not run)


Compute MD5 Checksums

Description

Compute the 32-byte MD5 checksums of one or more files.

Usage

md5sum(files)

Arguments

files character. The paths of file(s) to be check-summed.

Value

A character vector of the same length as files, with names equal to files. The elements will be NA for non-existent or unreadable files, otherwise a 32-character string of hexadecimal digits.
On Windows all files are read in binary mode (as the md5sum utilities there do): on other OSes the files are read in the default way.

See Also

checkMD5sums

Examples

md5sum(dir(R.home(), pattern="^COPY", full.names=TRUE))


Check Package Dependencies

Description

Parses and checks the dependencies of a package against the currently installed version of R [and other packages].

Usage

package.dependencies(x, check = FALSE,
                     depLevel = c("Depends", "Imports", "Suggests"))

Arguments

x | A matrix of package descriptions as returned by available.packages.
check | If TRUE, return logical vector of check results. If FALSE, return parsed list of dependencies.
depLevel | Whether to look for Depends or Suggests level dependencies.

Details

Currently we only check if the package conforms with the currently running version of R. In the future we might add checks for inter-package dependencies.

See Also

update.packages


QC Checks for R Code and/or Documentation

Description

Functions for performing various quality checks.

Usage

checkDocFiles(package, dir, lib.loc = NULL)
checkDocStyle(package, dir, lib.loc = NULL)
checkReplaceFuns(package, dir, lib.loc = NULL)
checkS3methods(package, dir, lib.loc = NULL)

Arguments

package | a character string naming an installed package.
dir | a character string specifying the path to a package's root source directory. This should contain the subdirectories R (for R code) and ‘man’ with R documentation sources (in Rd format). Only used if package is not given.
lib.loc | a character vector of directory names of R libraries, or NULL. The default value of NULL corresponds to all libraries currently known. The specified library trees are used to to search for package.

Details

checkDocFiles checks, for all Rd files in a package, whether all arguments shown in the usage sections of the Rd file are documented in its arguments section. It also reports duplicated entries in the arguments section, and “over-documented” arguments which are given in the arguments section but not in the usage. Note that the match is for the usage section and not a possibly existing synopsis section, as the usage is what gets displayed.

checkDocStyle investigates how (S3) methods are shown in the usages of the Rd files in a package. It reports the methods shown by their full name rather than using the Rd \method markup for indicating S3 methods. Earlier versions of R also reported about methods shown along with their generic, which typically caused problems for the documentation of the primary argument in the generic and its methods. With \method now being expanded in a way that class information is preserved, “joint” documentation is no longer necessarily a problem. (The corresponding information is still contained in the object returned by checkDocStyle.)

checkReplaceFuns checks whether replacement functions or S3/S4 replacement methods in the package R code have their final argument named value.

checkS3methods checks whether all S3 methods defined in the package R code have all arguments of the corresponding generic, with positional arguments of the generics in the same positions for the method. As an exception, the first argument of a formula method may be called formula even if this is not the name used by the generic. The rules when ... is involved are subtle: see the source code. Functions recognized as S3 generics are those with a call to UseMethod in their body, internal S3 generics (see InternalMethods), and S3 group generics (see Math). Possible dispatch under a different name is not taken into account. The generics are sought first in the given package, then in the base package and (currently) the packages graphics, stats, and utils added in R 1.9.0 by splitting the former base, and, if an installed package is tested, also in the loaded namespaces/packages listed in the package's ‘DESCRIPTION’ Depends field.

If using an installed package, the checks needing access to all R objects of the package will load the package (unless it is the base package), after possibly detaching an already loaded version of the package.

Value

The functions return objects of class the same as the respective function names containing the information about problems detected. There is a print method for nicely displaying the information contained in such objects.

Warning

These functions are still experimental. Names, interfaces and values might change in future versions.


Generate Index from Rd Files

Description

Print a 2-column index table with “names” and titles from given R documentation files to a given output file or connection. The titles are nicely formatted between two column positions (typically 25 and 72, respectively).

Usage

Rdindex(RdFiles, outFile = "", type = NULL,
        width = 0.9 * getOption("width"), indent = NULL)

Arguments

RdFiles | a character vector specifying the Rd files to be used for creating the index, either by giving the paths to the files, or the path to a single directory with the sources of a package.
outFile | a connection, or a character string naming the output file to print to. "" (the default) indicates output is to the console.
type | a character string giving the documentation type of the Rd files to be included in the index, or NULL (the default). The type of an Rd file is typically specified via the \docType tag; if type is "data", Rd files whose only keyword is datasets are included as well.
width | a positive integer giving the target column for wrapping lines in the output.
indent | a positive integer specifying the indentation of the second column. Must not be greater than width/2, and defaults to width/3.

Details

If a name is not a valid alias, the first alias (or the empty string if there is none) is used instead.


Rd Utilities

Description

Utilities for computing on the information in Rd objects.

Usage

Rd_db(package, dir, lib.loc = NULL)
Rd_parse(file, text = NULL)

Arguments

package | a character string naming an installed package.
dir | a character string specifying the path to a package's root source directory. This should contain the subdirectory ‘man’ with R documentation sources (in Rd format). Only used if package is not given.
lib.loc | a character vector of directory names of R libraries, or NULL. The default value of NULL corresponds to all libraries currently known. The specified library trees are used to to search for package.
file | a connection, or a character string giving the name of a file or a URL to read documentation in Rd format from.
text | character vector with documentation in Rd format. Elements are treated as if they were lines of a file.

Details

Rd_db builds a simple “data base” of all Rd sources in a package, as a list of character vectors with the lines of the Rd files in the package. This is particularly useful for working on installed packages, where the individual Rd files in the sources are no longer available.

Rd_parse is a simple top-level Rd parser/analyzer. It returns a list with components

meta
a list containing the Rd metadata (aliases, concepts, keywords, and documentation type);
data
a data frame with the names (tags) and corresponding text (vals) of the top-level sections in the R documentation object;
rest
top-level text not accounted for (currently, silently discarded by Rdconv, and hence usually the indication of a problem).

Note that at least for the time being, only the top-level structure is analyzed.

Warning

These functions are still experimental. Names, interfaces and values might change in future versions.

Examples

## Build the Rd db for the (installed) base package.
db <- Rd_db("base")
## Run Rd_parse on all entries in the Rd db.
db <- lapply(db, function(txt) Rd_parse(text = txt))
## Extract the metadata.
meta <- lapply(db, "[[", "meta")

## Keyword metadata per Rd file.
keywords <- lapply(meta, "[[", "keywords")
## Tabulate the keyword entries.
kw_table <- sort(table(unlist(keywords)))
## The 5 most frequent ones:
rev(kw_table)[1 : 5]
## The "most informative" ones:
kw_table[kw_table == 1]

## Concept metadata per Rd file.
concepts <- lapply(meta, "[[", "concepts")
## How many files already have \concept metadata?
sum(sapply(concepts, length) > 0)
## How many concept entries altogether?
length(unlist(concepts))


Read 00Index-style Files

Description

Read item/description information from 00Index-style files. Such files are description lists rendered in tabular form, and currently used for the ‘INDEX’ and ‘demo/00Index’ files of add-on packages.

Usage

read.00Index(file)

Arguments

file the name of a file to read data values from. If the specified file is "", then input is taken from the keyboard (in this case input can be terminated by a blank line). Alternatively, file can be a connection, which will be opened if necessary, and if so closed at the end of the function call.

Value

a character matrix with 2 columns named "Item" and "Description" which hold the items and descriptions.

See Also

formatDL for the inverse operation of creating a 00Index-style file from items and their descriptions.


Compile LaTeX Files

Description

Run latex and bibtex until all cross-references are resolved and create either a dvi or PDF file.

Usage

texi2dvi(file, pdf = FALSE, clean = FALSE, quiet = TRUE,
         texi2dvi = getOption("texi2dvi"))

Arguments

file | character. Name of TeX source file.
pdf | logical. If TRUE, a PDF file is produced insted of the default dvi file (texi2dvi command line option --pdf).
clean | logical. If TRUE, all auxiliary files are removed (texi2dvi command line option --clean). Does not work on some platforms.
quiet | logical. No output unless an error occurs.
texi2dvi | character (or NULL). Script or program used to compile a TeX file to dvi or PDF, respectively. If set to NULL, the ‘texi2dvi’ script in R's ‘bin’ directory is used (if it exists), otherwise it is assumed that texi2dvi is in the search path.

Details

Some TeX installations do not have ‘texi2dvi.exe’. If ‘texify.exe’ is present, then it can be used instead: set options(texi2dvi="texify.exe") or to the full path of the program.

Author(s)

Achim Zeileis


Defunct Objects in Package tools

Description

The functions or variables listed here are defunct, and may get removed as soon as of the next release.

Usage

See Also

tools-deprecated,
Deprecated,
Defunct


Deprecated Objects in Package tools

Description

The functions or variables listed here are provided for compatibility with older versions of R only, and may be defunct as soon as of the next release.

Usage

See Also

Deprecated,
Defunct


Tools for Package Development

Description

Tools for package development, administration and documentation

Details

This package contains tools for manipulating R packages and their documentation.

For a complete list of functions, use library(help="tools").

Author(s)

Kurt Hornik and Friedrich Leisch

Maintainer: R Core Team R-core@r-project.org


Find Undocumented Objects

Description

Finds the objects in a package which are undocumented, in the sense that they are visible to the user (or data objects or S4 classes provided by the package), but no documentation entry exists.

Usage

undoc(package, dir, lib.loc = NULL)

Arguments

package | a character string naming an installed package.
dir | a character string specifying the path to a package's root source directory. This must contain the subdirectory ‘man’ with R documentation sources (in Rd format), and at least one of the ‘R’ or ‘data’ subdirectories with R code or data objects, respectively.
lib.loc | a character vector of directory names of R libraries, or NULL. The default value of NULL corresponds to all libraries currently known. The specified library trees are used to to search for package.

Details

This function is useful for package maintainers mostly. In principle, all user level R objects should be documented; note however that the precise rules for documenting methods of generic functions are still under discussion.

Value

An object of class "undoc" which is a list of character vectors containing the names of the undocumented objects split according to documentation type. This representation is still experimental, and might change in future versions.
There is a print method for nicely displaying the information contained in such objects.

See Also

codoc, QC

Examples

undoc("tools")                  # Undocumented objects in 'tools'


Retrieve Dependency Information for a Vignette

Description

Given a vignette name, will create a DependsList object that reports information about the packages the vignette depends on.

Usage

vignetteDepends(vignette, recursive = TRUE, reduce = TRUE,
                local = TRUE, lib.loc = NULL)

Arguments

vignette | The path to the vignette source
recursive | Whether or not to include indirect dependencies
reduce | Whether or not to collapse all sets of dependencies to a minimal value
local | Whether or not to search only locally
lib.loc | What libraries to search in locally

Details

If recursive is TRUE, any package that is specified as a dependency will in turn have its dependencies included (and so on), these are known as indirect dependencies. If recursive is FALSE, only the dependencies directly named by the vignette will be used.

If local is TRUE, the system will only look at the user's local machine and not online to find dependencies.

If reduce is TRUE, the system will collapse the fields in the DependsList to the minimal set of dependencies (for instance if the dependencies were ('foo', 'foo (>= 1.0.0)', 'foo (>= 1.3.0)'), the return value would be 'foo (>= 1.3.0)').

Value

An object of class DependsList

Author(s)

Jeff Gentry

See Also

pkgDepends

Examples

gridEx <- system.file("doc", "grid.Snw", package = "grid")
vignetteDepends(gridEx)


Generate PACKAGES files

Description

Generate ‘PACKAGES’ and ‘PACKAGES.gz’ files for a repository of source or Mac/Windows binary packages.

Usage

write_PACKAGES(dir, fields = NULL,
               type = c("source", "mac.binary", "win.binary"),
               verbose = FALSE)

Arguments

dir | Character vector describing the location of the repository (directory including source or binary packages) to generate the ‘PACKAGES’ and ‘PACKAGES.gz’ files from and write them to.
fields | a character vector giving the fields to be used in the ‘PACKAGES’ and ‘PACKAGES.gz’ files in addition to the default ones, or NULL (default). The default corresponds to the fields needed by available.packages: “Package”, “Bundle”, “Priority”, “Version”, “Depends”, “Suggests”, “Imports” and “Contains”.
type | Type of packages: currently source ‘.tar.gz’ archives, and Mac or Windows binary (‘.tgz’ or ‘.zip’, respectively) packages are supported. Defaults to "win.binary" on Windows and to "source" otherwise.
verbose | logical. Should packages be listed as they are processed?

Details

type = "win.binary" uses unz connections to read all ‘DESCRIPTION’ files contained in the (zipped) binary packages for Windows in the given directory dir, and builds ‘PACKAGES’ and ‘PACKAGES.gz’ files from these information.

Value

Invisibly returns the number of packages described in the resulting ‘PACKAGES’ and ‘PACKAGES.gz’ files. If 0, no packages were found and no files were written.

Note

Processing ‘.tar.gz’ archives to extract the ‘DESCRIPTION’ files is quite slow.

This function can be useful on other OSes to prepare a repository to be accessed by Windows machines, so type = "win.binary" should work on all OSes.

Author(s)

Uwe Ligges and R-core.

See Also

See read.dcf and write.dcf for reading ‘DESCRIPTION’ files and writing the ‘PACKAGES’ and ‘PACKAGES.gz’ files.

Examples

## Not run:
write_PACKAGES("c:/myFolder/myRepository")  # on Windows
write_PACKAGES("/pub/RWin/bin/windows/contrib/2.1",
               type="win.binary")  # on Linux
## End(Not run)


Extract Translatable Messages from R Files in a Package

Description

For each file in the ‘R’ directory (including system-specific subdirectories) of a package, extract the unique arguments passed to stop, warning, message, gettext and gettextf, or to ngettext.

Usage

xgettext(dir, verbose = FALSE, asCall = TRUE)

xngettext(dir, verbose = FALSE)

xgettext2pot(dir, potFile)

Arguments

dir | the directory of a source package.
verbose | logical: should each file be listed as it is processed?
asCall | logical: if TRUE each argument is returned whole, otherwise the strings within each argument are extracted.
potFile | name of po template file to be produced. Defaults to "R-pkg.pot" where pkg is the basename of dir.

Details

Leading and trailing white space (space, tab and linefeed) is removed for calls to gettext, gettextf, stop, warning, and message, as it is by the internal code that passes strings for translation.

We look to see if these functions were called with domain = NA and if so omit the call if asCall = TRUE: note that the call might contain a call to gettext which would be visible if asCall = FALSE.

xgettext2pot calls xgettext and then xngettext, and writes a PO template file for use with the GNU Gettext tools. This ensures that the strings for simple translation are unique in the file (as GNU Gettext requires), but does not do so for ngettext calls (and the rules are not stated in the Gettext manual).

If applied to the base package, this also looks in the .R files in ‘R_HOME/share/R’.

Value

For xgettext, a list of objects of class "xgettext" (which has a print method), one per source file that potentially contains translatable strings
For nxgettext, a list of objects of class "xngettext", which are themselves lists of length-2 character strings.

Examples

## Not run:
## in a source-directory build of R:
xgettext(file.path(R.home(), "src", "library", "splines"))
## End(Not run)