| Title: | Tools for Package Development |
|---|---|
| Description: | Tools for package development, administration and documentation. |
| Authors: | R Core Team |
| Maintainer: | R Core Team <[email protected]> |
| License: | Part of R 4.4.1 |
| Version: | 4.4.1 |
| Built: | 2024-06-15 17:27:02 UTC |
| Source: | base |
Tools for package development, administration and documentation.
This package contains tools for manipulating R packages and their documentation.
For a complete list of functions, use library(help = "tools").
Kurt Hornik and Friedrich Leisch
Maintainer: R Core Team [email protected]
.print.via.format is a “prototype” print()
method, useful, at least as a start, by a simple
print.<myS3class> <- .print.via.format
.print.via.format(x, ...).print.via.format(x, ...)
x |
object to be printed. |
... |
optional further arguments, passed to |
x, invisibly (by invisible()), as
print methods should.
The print generic; its default method
print.default (used for many basic implicit classes such
as "numeric", "character" and arrays of
them, lists etc).
## The function is simply defined as function (x, ...) { writeLines(format(x, ...)) invisible(x) } ## is used for simple print methods in R, and as prototype for new methods.## The function is simply defined as function (x, ...) { writeLines(format(x, ...)) invisible(x) } ## is used for simple print methods in R, and as prototype for new methods.
The data() command with no arguments lists all the
datasets available via data in attached packages, and to do so a
per-package list is installed. Creating that list at install time can
be slow for packages with huge datasets, and can be expedited by a
supplying ‘data/datalist’ file.
add_datalist(pkgpath, force = FALSE, small.size = 1024^2)add_datalist(pkgpath, force = FALSE, small.size = 1024^2)
pkgpath |
The path to a (source) package. |
force |
logical: can an existing ‘data/datalist’ file be over-written? |
small.size |
number: a ‘data/datalist’ file is created only if
the total size of the data files is larger than |
R CMD build will call this function to add a data list to
packages with 1MB or more of file in the ‘data’ directory.
It can also be also helpful to give a ‘data/datalist’ file in packages whose datasets have many dependencies, including loading the packages itself (and maybe others).
data.
The ‘Writing R Extensions’ manual.
When testing code, it is not sufficient to check that results are correct, but also that errors or warnings are signalled in appropriate situations. The functions described here provide a convenient facility for doing so. The three functions check that evaluating the supplied expression produces an error, a warning or one of a specified list of conditions, respectively. If the assertion fails, an error is signalled.
assertError(expr, classes = "error", verbose = FALSE) assertWarning(expr, classes = "warning", verbose = FALSE) assertCondition(expr, ..., .exprString = , verbose = FALSE)assertError(expr, classes = "error", verbose = FALSE) assertWarning(expr, classes = "warning", verbose = FALSE) assertCondition(expr, ..., .exprString = , verbose = FALSE)
expr |
an unevaluated R expression which will be evaluated via
|
classes, ...
|
|
.exprString |
The string to be printed corresponding to
|
verbose |
If |
assertCondition() uses the general condition mechanism to
check all the conditions generated in evaluating expr. The
occurrence of any of the supplied condition classes among these satisfies the
assertion regardless of what other conditions may be signalled.
assertError() is a convenience function for asserting errors;
it calls assertCondition().
assertWarning() asserts that a warning will be signalled, but
not an error, whereas assertCondition(expr, "warning")
will be satisfied even if an error follows the warning. See the examples.
If the assertion is satisfied, a list of all the condition objects
signalled is returned, invisibly. See conditionMessage for the
interpretation of these objects. Note that all conditions
signalled during the evaluation are returned, whether or not they
were among the requirements.
John Chambers and Martin Maechler
stop, warning;
signalCondition, tryCatch.
assertError(sqrt("abc")) assertWarning(matrix(1:8, 4,3)) assertCondition( ""-1 ) # ok, any condition would satisfy this try( assertCondition(sqrt(2), "warning") ) ## .. Failed to get warning in evaluating sqrt(2) assertCondition(sqrt("abc"), "error") # ok try( assertCondition(sqrt("abc"), "warning") )# -> error: had no warning assertCondition(sqrt("abc"), "error") ## identical to assertError() call above assertCondition(matrix(1:5, 2,3), "warning") try( assertCondition(matrix(1:8, 4,3), "error") ) ## .. Failed to get expected error .... ## either warning or worse: assertCondition(matrix(1:8, 4,3), "error","warning") # OK assertCondition(matrix(1:8, 4, 3), "warning") # OK ## when both are signalled: ff <- function() { warning("my warning"); stop("my error") } assertCondition(ff(), "warning") ## but assertWarning does not allow an error to follow try(assertWarning(ff())) assertCondition(ff(), "error") # ok assertCondition(ff(), "error", "warning") # ok (quietly, catching warning) ## assert that assertC..() does not assert [and use *one* argument only] assertCondition( assertCondition(sqrt( 2 ), "warning") ) assertCondition( assertCondition(sqrt("abc"), "warning"), "error") assertCondition( assertCondition(matrix(1:8, 4,3), "error"), "error")assertError(sqrt("abc")) assertWarning(matrix(1:8, 4,3)) assertCondition( ""-1 ) # ok, any condition would satisfy this try( assertCondition(sqrt(2), "warning") ) ## .. Failed to get warning in evaluating sqrt(2) assertCondition(sqrt("abc"), "error") # ok try( assertCondition(sqrt("abc"), "warning") )# -> error: had no warning assertCondition(sqrt("abc"), "error") ## identical to assertError() call above assertCondition(matrix(1:5, 2,3), "warning") try( assertCondition(matrix(1:8, 4,3), "error") ) ## .. Failed to get expected error .... ## either warning or worse: assertCondition(matrix(1:8, 4,3), "error","warning") # OK assertCondition(matrix(1:8, 4, 3), "warning") # OK ## when both are signalled: ff <- function() { warning("my warning"); stop("my error") } assertCondition(ff(), "warning") ## but assertWarning does not allow an error to follow try(assertWarning(ff())) assertCondition(ff(), "error") # ok assertCondition(ff(), "error", "warning") # ok (quietly, catching warning) ## assert that assertC..() does not assert [and use *one* argument only] assertCondition( assertCondition(sqrt( 2 ), "warning") ) assertCondition( assertCondition(sqrt("abc"), "warning"), "error") assertCondition( assertCondition(matrix(1:8, 4,3), "error"), "error")
This function defines and registers styles for rendering
bibentry objects into ‘Rd’ format, for later
conversion to text, HTML, etc.
bibstyle(style, envir, ..., .init = FALSE, .default = TRUE) getBibstyle(all = FALSE)bibstyle(style, envir, ..., .init = FALSE, .default = TRUE) getBibstyle(all = FALSE)
style |
A character string naming the style. |
envir |
(optional) An environment holding the functions to implement the style. |
... |
Named arguments to add to the environment. |
.init |
Whether to initialize the environment from the default style |
.default |
Whether to set the specified style as the default style. |
all |
Whether to return the names of all registered styles. |
Rendering of bibentry objects may be done using routines
modelled after those used by BibTeX. This function allows environments
to be created and manipulated to contain those routines.
There are two ways to create a new style environment. The easiest
is to set .init = TRUE, in which case the environment will be
initialized with a copy of the default "JSS" environment. (This style
is modelled after the ‘jss.bst’ style used by the Journal
of Statistical Software.) Alternatively, the envir argument
can be used to specify a completely new style environment.
To find the name of the default style, use getBibstyle(). To
retrieve an existing style without setting it as the default, use
bibstyle(style, .default = FALSE). To modify an existing style,
specify style and some named entries via ....
(Modifying the default "JSS" style is discouraged.) Setting
style to NULL or leaving it missing will retrieve the
default style, but modifications will not be allowed.
At a minimum, the environment should contain routines to render each
of the 12 types of bibliographic entry supported by
bibentry as well as several other routines
described below.
The former must be named formatArticle,
formatBook, formatInbook, formatIncollection,
formatInProceedings, formatManual,
formatMastersthesis, formatMisc, formatPhdthesis,
formatProceedings, formatTechreport and
formatUnpublished. Each of these takes one argument, a single
unclass'ed entry from the bibentry vector
passed to the renderer, and should produce a single element character
vector (possibly containing newlines).
The other routines are as follows. sortKeys, a function to
produce a sort key to sort the entries, is passed the original
bibentry vector and should produce a sortable vector of
the same length to define the sort order. Finally,
the optional function cite should have the same argument list
as utils::cite, and should produce a citation to be used
in text.
The format method for "bibentry" objects adds a
field named ".index" to each entry after sorting and before
formatting. This is a 1-based index within the complete object that
can be used in styles that require numbering. Although the
"JSS" style doesn't use numbers, it includes a
fmtPrefix() stub function that may be used to display them.
See the example below.
bibstyle returns the environment which has been selected or created.
getBibstyle returns the name of the default style, or all
style names.
Duncan Murdoch
refs <- c(bibentry(bibtype = "manual", title = "R: A Language and Environment for Statistical Computing", author = person("R Core Team"), organization = "R Foundation for Statistical Computing", address = "Vienna, Austria", year = 2013, url = "https://www.R-project.org"), bibentry(bibtype = "article", author = c(person(c("George", "E.", "P."), "Box"), person(c("David", "R."), "Cox")), year = 1964, title = "An Analysis of Transformations", journal = "Journal of the Royal Statistical Society, Series B", volume = 26, number = 2, pages = "211--243", doi = "10.1111/j.2517-6161.1964.tb00553.x")) bibstyle("unsorted", sortKeys = function(refs) seq_along(refs), fmtPrefix = function(paper) paste0("[", paper$.index, "]"), .init = TRUE) print(refs, .bibstyle = "unsorted")refs <- c(bibentry(bibtype = "manual", title = "R: A Language and Environment for Statistical Computing", author = person("R Core Team"), organization = "R Foundation for Statistical Computing", address = "Vienna, Austria", year = 2013, url = "https://www.R-project.org"), bibentry(bibtype = "article", author = c(person(c("George", "E.", "P."), "Box"), person(c("David", "R."), "Cox")), year = 1964, title = "An Analysis of Transformations", journal = "Journal of the Royal Statistical Society, Series B", volume = 26, number = 2, pages = "211--243", doi = "10.1111/j.2517-6161.1964.tb00553.x")) bibstyle("unsorted", sortKeys = function(refs) seq_along(refs), fmtPrefix = function(paper) paste0("[", paper$.index, "]"), .init = TRUE) print(refs, .bibstyle = "unsorted")
Run Sweave (or other custom weave function),
texi2pdf, and/or Stangle
(or other custom tangle function) on one vignette.
This is the workhorse of R CMD Sweave.
buildVignette(file, dir = ".", weave = TRUE, latex = TRUE, tangle = TRUE, quiet = TRUE, clean = TRUE, keep = character(), engine = NULL, buildPkg = NULL, encoding, ...)buildVignette(file, dir = ".", weave = TRUE, latex = TRUE, tangle = TRUE, quiet = TRUE, clean = TRUE, keep = character(), engine = NULL, buildPkg = NULL, encoding, ...)
file |
character; the vignette source file. |
dir |
character; the working directory in which the intermediate and output files will be produced. |
weave |
logical; should weave be run? |
latex |
logical; should texi2pdf be run if weaving produces a ‘.tex’ file? |
tangle |
logical; should tangle be run? |
quiet |
logical; run in quiet mode? |
clean |
logical; whether to remove some newly created, often intermediate, files. See details below. |
keep |
a list of file names to keep in any case when cleaning. Note that “target” files are kept anyway. |
engine |
|
buildPkg |
|
encoding |
the encoding to assume for the file. If not
specified, it will be read if possible from the file's contents.
Note that if the vignette is part of a package,
|
... |
Additional arguments passed to weave and tangle. |
This function determines the vignette engine for the vignette (default
utils::Sweave), then weaves and/or tangles the vignette using
that engine. Finally, if clean is TRUE, newly created
intermediate files (non “targets”, where these depend on the engine,
etc, and not any in keep) will be deleted. If clean is
NA, and weave is true, newly created intermediate output
files (e.g., ‘.tex’) will not be deleted even if a ‘.pdf’
file has been produced from them.
If buildPkg is specified, those packages will be loaded before
the vignette is processed and will be used as the default packages in
the search for a vignette engine, but an explicitly specified package
in the vignette source (e.g., using
‘\VignetteEngine{utils::Sweave}’ to specify the Sweave
engine in the utils package) will override it. In contrast, if
the engine argument is given, it will override the vignette
source.
A character vector naming the files that have been produced.
Henrik Bengtsson and Duncan Murdoch
buildVignettes for building all vignettes in a package.
Run Sweave (or other custom weave function)
and texi2pdf on all vignettes
of a package, or list the vignettes.
buildVignettes(package, dir, lib.loc = NULL, quiet = TRUE, clean = TRUE, tangle = FALSE, skip = NULL, ser_elibs = NULL) pkgVignettes(package, dir, subdirs = NULL, lib.loc = NULL, output = FALSE, source = FALSE, check = FALSE)buildVignettes(package, dir, lib.loc = NULL, quiet = TRUE, clean = TRUE, tangle = FALSE, skip = NULL, ser_elibs = NULL) pkgVignettes(package, dir, subdirs = NULL, lib.loc = NULL, output = FALSE, source = FALSE, check = FALSE)
package |
a character string naming an installed package. If given, vignette source files are by default looked for in subdirectory ‘doc’. |
dir |
a character string specifying the path to a package's root source directory. If given, vignette source files are by default looked for in subdirectory ‘vignettes’. |
lib.loc |
a character vector of directory names of R libraries,
or |
quiet |
logical.
Weave and run |
clean |
Remove all files generated by the build, even if there were copies there before. |
tangle |
logical. Do tangling as well as weaving. |
skip |
a character vector of names of vignettes (without file
extension, matching the |
ser_elibs |
For use from |
subdirs |
a character vector of subdirectories of |
output |
logical indicating if the output filenames for each
vignette should be returned (in component |
source |
logical indicating if the tangled output
filenames for each vignette should be returned (in component |
check |
logical. If |
buildVignettes is used by R CMD build and
R CMD check to (re-)build vignette outputs from their sources.
As from R 3.4.1, both of these functions ignore files that are listed in
the ‘.Rbuildignore’ file in dir.
buildVignettes is called for its side effect of creating the
outputs of all vignettes, and if tangle = TRUE,
extracting the R code.
pkgVignettes returns an object of class "pkgVignettes"
if a vignette directory is found, otherwise NULL.
gVigns <- pkgVignettes("grid") str(gVigns)gVigns <- pkgVignettes("grid") str(gVigns)
charset_to_Unicode is a matrix of Unicode code points with
columns for the common 8-bit encodings.
Adobe_glyphs is a data frame which gives Adobe glyph names for
Unicode code points. It has two character columns, "adobe" and
"unicode" (a 4-digit hex representation).
charset_to_Unicode Adobe_glyphscharset_to_Unicode Adobe_glyphs
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 includes all the Adobe glyph names which correspond
to single Unicode characters. It is sorted by Unicode code point and
within a point alphabetically on the glyph (there can be more than one
name for a Unicode code point). The data are in the file
‘R_HOME/share/encodings/Adobe_glyphlist’.
## find Adobe names for ISOLatin2 chars. latin2 <- charset_to_Unicode[, "ISOLatin2"] aUnicode <- as.hexmode(paste0("0x", Adobe_glyphs$unicode)) 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")## find Adobe names for ISOLatin2 chars. latin2 <- charset_to_Unicode[, "ISOLatin2"] aUnicode <- as.hexmode(paste0("0x", Adobe_glyphs$unicode)) 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 source packages in a given directory, optionally with their reverse dependencies.
check_packages_in_dir(dir, pfiles = Sys.glob("*.tar.gz"), check_args = character(), check_args_db = list(), reverse = NULL, check_env = character(), xvfb = FALSE, Ncpus = getOption("Ncpus", 1L), clean = TRUE, install_args = list(), parallel_args = list(), ...) summarize_check_packages_in_dir_results(dir, all = TRUE, full = FALSE, ...) summarize_check_packages_in_dir_timings(dir, all = FALSE, full = FALSE) summarize_check_packages_in_dir_depends(dir, all = FALSE, which = c("Depends", "Imports", "LinkingTo")) check_packages_in_dir_changes(dir, old, outputs = FALSE, sources = FALSE, ...) check_packages_in_dir_details(dir, logs = NULL, drop_ok = TRUE, ...)check_packages_in_dir(dir, pfiles = Sys.glob("*.tar.gz"), check_args = character(), check_args_db = list(), reverse = NULL, check_env = character(), xvfb = FALSE, Ncpus = getOption("Ncpus", 1L), clean = TRUE, install_args = list(), parallel_args = list(), ...) summarize_check_packages_in_dir_results(dir, all = TRUE, full = FALSE, ...) summarize_check_packages_in_dir_timings(dir, all = FALSE, full = FALSE) summarize_check_packages_in_dir_depends(dir, all = FALSE, which = c("Depends", "Imports", "LinkingTo")) check_packages_in_dir_changes(dir, old, outputs = FALSE, sources = FALSE, ...) check_packages_in_dir_details(dir, logs = NULL, drop_ok = TRUE, ...)
dir |
a character string giving the path to the directory with the source ‘.tar.gz’ files to be checked. |
pfiles |
(optional) character vector of tarball files to be
checked. Useful for choosing a subset of the ‘*.tar.gz’ files in
|
check_args |
a character vector with arguments to be passed to
|
check_args_db |
a named list of character vectors with arguments
to be passed to |
reverse |
a list with names partially matching |
check_env |
a character vector of name=value strings to set environment variables for checking, or a list of length two of such character vectors to be used for checking packages and reverse dependencies, respectively. |
xvfb |
a logical indicating whether to perform checking inside a
virtual framebuffer X server (Unix only), or a character vector of
|
Ncpus |
the number of parallel processes to use for parallel installation and checking. |
clean |
a logical indicating whether to remove the downloaded reverse dependency sources. |
install_args |
list of arguments to be passed to underlying
|
parallel_args |
list of arguments to be passed to underlying calls
of |
... |
passed to |
all |
a logical indicating whether to also summarize the reverse dependencies checked. |
full |
a logical indicating whether to also give details for checks with non-ok results, or summarize check example timings (if available). |
which |
see |
old |
a character string giving the path to the directory of a
previous |
outputs |
a logical indicating whether to analyze changes in the outputs of the checks performed, or only (default) the status of the checks. |
sources |
a logical indicating whether to also investigate the
changes in the source files checked (default: |
logs |
a character vector with the paths of ‘00check.log’ to
analyze. Only used if |
drop_ok |
a logical indicating whether to drop checks with ‘ok’ status, or a character vector with the ‘ok’ status tags to drop. The default corresponds to tags ‘OK’, ‘NONE’ and ‘SKIPPED’. |
check_packages_in_dir allows to conveniently check source
package ‘.tar.gz’ files in the given directory dir, along
with their reverse dependencies as controlled by reverse.
The "which" component of reverse can also be a list, in
which case reverse dependencies are obtained for each element of the
list and the corresponding element of the "recursive" component
of reverse (which is recycled as needed).
If needed, the source ‘.tar.gz’ files of the reverse dependencies
to be checked as well are downloaded into dir (and removed at
the end if clean is true). Next, all packages (additionally)
needed for checking are installed to the ‘Library’ subdirectory
of dir. Then, all ‘.tar.gz’ files are checked using the
given arguments and environment variables, with outputs and messages
to files in the ‘Outputs’ subdirectory of dir. The
‘*.Rcheck’ directories with the check results of the reverse
dependencies are renamed by prefixing their base names with
‘rdepends_’.
Results and timings can conveniently be summarized using
summarize_check_packages_in_dir_results and
summarize_check_packages_in_dir_timings, respectively.
Installation and checking is performed in parallel if Ncpus is
greater than one: this will use mclapply on
Unix and parLapply on Windows.
check_packages_in_dir returns an object inheriting from class
"check_packages_in_dir" which has print and
summary methods.
check_packages_in_dir_changes allows to analyze the effect of
changing (some of) the sources. With dir and old the
paths to the directories with the new and old sources, respectively,
and the corresponding check results, possible changes in the check
results can conveniently be analyzed as controlled via options
outputs and sources. The changes object returned can be
subscripted according to change in severity from the old to the new
results by using one of "==", "!=", "<",
"<=", ">" or ">=" as row index.
check_packages_in_dir_details analyzes check log files to
obtain check details as a data frame which can be used for further
processing, providing check name, status and output for every check
performed and not dropped according to status tag (via variables
Check, Status and Output, respectively).
Environment variable _R_CHECK_ELAPSED_TIMEOUT_ can be used to
set a limit on the elapsed time of each check run. See the
‘R Internals’ manual for how the value is interpreted and for
other environment variables which can be used for finer-grained
control on timeouts within a check run.
This functionality is still experimental: interfaces may change in future versions.
## Not run: ## Check packages in dir without reverse dependencies: check_packages_in_dir(dir) ## Check packages in dir and their reverse dependencies using the ## defaults (all repositories in getOption("repos"), all "strong" ## reverse dependencies, no recursive reverse dependencies): check_packages_in_dir(dir, reverse = list()) ## Check packages in dir with their reverse dependencies from CRAN, ## using all strong reverse dependencies and reverse suggests: check_packages_in_dir(dir, reverse = list(repos = getOption("repos")["CRAN"], which = "most")) ## Check packages in dir with their reverse dependencies from CRAN, ## using '--as-cran' for the former but not the latter: check_packages_in_dir(dir, check_args = c("--as-cran", ""), reverse = list(repos = getOption("repos")["CRAN"])) ## End(Not run)## Not run: ## Check packages in dir without reverse dependencies: check_packages_in_dir(dir) ## Check packages in dir and their reverse dependencies using the ## defaults (all repositories in getOption("repos"), all "strong" ## reverse dependencies, no recursive reverse dependencies): check_packages_in_dir(dir, reverse = list()) ## Check packages in dir with their reverse dependencies from CRAN, ## using all strong reverse dependencies and reverse suggests: check_packages_in_dir(dir, reverse = list(repos = getOption("repos")["CRAN"], which = "most")) ## Check packages in dir with their reverse dependencies from CRAN, ## using '--as-cran' for the former but not the latter: check_packages_in_dir(dir, check_args = c("--as-cran", ""), reverse = list(repos = getOption("repos")["CRAN"])) ## End(Not run)
Performs checks on calls to compiled code from R code. Currently only
checks 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.
checkFF(package, dir, file, lib.loc = NULL, registration = FALSE, check_DUP = FALSE, verbose = getOption("verbose"))checkFF(package, dir, file, lib.loc = NULL, registration = FALSE, check_DUP = FALSE, verbose = getOption("verbose"))
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 |
file |
the name of a file containing R code to be checked. Used
if neither |
lib.loc |
a character vector of directory names of R libraries,
or |
registration |
a logical. If |
check_DUP |
a logical. If |
verbose |
a logical. If |
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 which 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.
This checks that calls with PACKAGE specified are to the
same package, and reports separately those which are in base packages
and those which are in other packages (and if those packages are
specified in the ‘DESCRIPTION’ file).
An object of class "checkFF".
There are format and print methods to display the
information contained in such objects.
# order is pretty much random checkFF(package = "stats", verbose = TRUE)# order is pretty much random checkFF(package = "stats", verbose = TRUE)
checkMD5sums checks the files against a file ‘MD5’.
checkMD5sums(package, dir)checkMD5sums(package, dir)
package |
the name of an installed package |
dir |
the path to the top-level directory of an installed package. |
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. (For Windows, one is supplied in
the bundle at https://cran.r-project.org/bin/windows/Rtools/.)
If dir is missing, an installed package of name package
is searched for.
The private function tools:::.installMD5sums is used to create
MD5 files in the Windows build.
checkMD5sums returns a logical, NA if there is no
‘MD5’ file to be checked.
These functions compare formats embedded in English messages
with translated strings to check for consistency. checkPoFile
checks one file, while checkPoFiles checks all files for specified
or all languages.
checkPoFile(f, strictPlural = FALSE) checkPoFiles(language, dir = ".")checkPoFile(f, strictPlural = FALSE) checkPoFiles(language, dir = ".")
f |
a character string giving a single filepath. |
strictPlural |
whether to compare formats of singular and plural forms in a strict way. |
language |
a character string giving a language code, or a
‘regexp’ (regular expression), to match languages in |
dir |
a path to a directory in which to check files. |
Part of R's internationalization depends on translations of messages
in ‘.po’ files. In these files an ‘English’ message taken
from the R sources is followed by a translation into another
language. Many of these messages are format strings for C or R
sprintf and related functions. In these cases, the
translation must give a compatible format or an error will be
generated when the message is displayed.
The rules for compatibility differ between C and R in several ways. C
supports several conversions not supported by R, namely c,
u, p, n. It is allowed in C's sprintf()
function to have more arguments than are needed by the format string,
but in R the counts must match exactly. R requires types of
arguments to match, whereas C will do the display whether it makes
sense or not.
These functions compromise on the testing as follows. The additional formats allowed in C are accepted, and all differences in argument type or count are reported. As a consequence some reported differences are not errors.
If the strictPlural argument is TRUE, then argument
lists must agree exactly between singular and plural forms of messages; if
FALSE, then translations only need to match one or the other
of the two forms. When checkPoFiles calls checkPoFile,
the strictPlural argument is set to TRUE for files with
names starting ‘R-’, and to FALSE otherwise.
Items marked as ‘fuzzy’ in the ‘.po’ file are not processed (as they are ignored by the message compiler).
If a difference is found, the translated string is checked for variant
percent signs (e.g., the wide percent sign "\uFF05"). Such signs
will not be recognized as format specifiers, and are likely to be
errors.
Both functions return an object of S3 class "check_po_files". A
print method is defined for this class to display a report on
the differences.
Duncan Murdoch
See the GNU gettext manual for the ‘.po’ file format:
https://www.gnu.org/software/gettext/manual/gettext.html.
update_pkg_po() which calls checkPoFile();
xgettext, sprintf.
## Not run: checkPoFiles("de", "/path/to/R/src/directory") ## End(Not run)## Not run: checkPoFiles("de", "/path/to/R/src/directory") ## End(Not run)
Check an help file or the output of the parse_Rd function.
checkRd(Rd, defines = .Platform$OS.type, stages = "render", unknownOK = TRUE, listOK = TRUE, ..., def_enc = FALSE)checkRd(Rd, defines = .Platform$OS.type, stages = "render", unknownOK = TRUE, listOK = TRUE, ..., def_enc = FALSE)
Rd |
a filename or |
defines |
string(s) to use in |
stages |
at which stage ( |
unknownOK |
unrecognized macros are treated as errors if
|
listOK |
unnecessary non-empty braces (e.g., around text, not as
an argument) are treated as errors if |
... |
additional parameters to pass to |
def_enc |
logical: has the package declared an encoding, so tests for non-ASCII text are suppressed? |
checkRd performs consistency checks on an Rd file, confirming that
required sections are present, etc.
It accepts a filename for an Rd file, and will use
parse_Rd to parse it before applying the checks. If so,
warnings from parse_Rd are collected, together with those from
the internal function prepare_Rd, which does the
#ifdef and \Sexpr processing, drops sections that
would not be rendered or are duplicated (and should not be) and
removes empty sections.
An Rd object is passed through prepare_Rd, but it may already
have been (and installed Rd objects have).
Warnings are given a ‘level’: those from prepare_Rd have
level 0. These include
\Sexpr expects R code; found ... |
Unprocessed ‘stage’ macro from stage-stage \Sexpr
|
| All text must be in a section |
| Only one tag name section is allowed: the first will be used |
| docType type is unrecognized |
| Section name is unrecognized and will be dropped |
| Dropping empty section name |
checkRd itself can show
| 7 | Tag tag name not recognized |
| 7 | Unrecognized format: ... |
| 7 | \tabular format must be simple text |
| 7 | Unrecognized \tabular format: ... |
| 7 | Only n columns allowed in this table |
| 7 | Tag tag name is invalid in a block name block |
| 7 | \method not valid outside a code block |
| 7 | Tag \method is only valid in \usage
|
| 7 | Tag \dontrun is only valid in \examples
|
| 7 | Invalid email address: ... |
| 7 | Invalid URL: ... |
| 5 | \name should not contain !, | or @ |
| 5 | \item in block name must have non-empty label |
| 3 | Empty section tag name |
| -1 | \name should only contain printable ASCII characters |
| -1 | Non-ASCII contents without declared encoding |
| -1 | Non-ASCII contents in second part of \enc
|
| -1 | Escaped LaTeX specials: ... |
| -1|-3 | Lost braces ... |
| -3 | Tag \ldots is invalid in a code block |
| -5 | \title should not end in a period |
and variations with \method replaced by \S3method or
\S4method, \dontrun replaced by \donttest, \dontdiff or
\dontshow, and \title replaced by \section or
\subsection name.
“Lost braces” are uprated to warning level -1 when they match
common markup mistakes, e.g., ‘code{text}’ rendered as
‘codetext’ due to the missing backslash escape for the macro name.
Note that both prepare_Rd and checkRd have tests for an
empty section: that in checkRd is stricter (essentially that
nothing is output).
This may fail through an R error, but otherwise warnings are
collected as returned as an object of class "checkRd", a
character vector of messages. This class has a print method
which only prints unique messages, and has argument minlevel
that can be used to select only more serious messages. (This is set
to -1 in R CMD check.)
Possible fatal errors are those
from !unknownOK or !listOK,
from invalid \if or \ifelse conditions,
from running the parser (e.g., a
non-existent file, unclosed quoted string, non-ASCII input without a
specified encoding, an invalid value for an \Sexpr option),
or from prepare_Rd (multiple
\Rdversion declarations, invalid \encoding or
\docType or \name sections, and missing or duplicate
\name or \title sections),
including errors from parsing/running code from \Sexpr macros
(if covered by stages).
Duncan Murdoch, Brian Ripley
## parsed Rd from the installed version of _this_ help file rd <- Rd_db("tools")[["checkRd.Rd"]] rd stopifnot(length(checkRd(rd)) == 0) # there should be no issues ## make up \tabular issues bad <- r"(\name{bad}\title{bad}\description{\tabular{p}{1 \tab 2}})" (res <- checkRd(parse_Rd(textConnection(bad)))) stopifnot(length(res) > 0)## parsed Rd from the installed version of _this_ help file rd <- Rd_db("tools")[["checkRd.Rd"]] rd stopifnot(length(checkRd(rd)) == 0) # there should be no issues ## make up \tabular issues bad <- r"(\name{bad}\title{bad}\description{\tabular{p}{1 \tab 2}})" (res <- checkRd(parse_Rd(textConnection(bad)))) stopifnot(length(res) > 0)
This reports for each of the files produced by save the size,
if it was saved in ASCII or XDR binary format, and if it was
compressed (and if so in what format).
Usually such files have extension ‘.rda’ or ‘.RData’, hence the name of the function.
checkRdaFiles(paths) resaveRdaFiles(paths, compress = c("auto", "gzip", "bzip2", "xz"), compression_level, version = NULL)checkRdaFiles(paths) resaveRdaFiles(paths, compress = c("auto", "gzip", "bzip2", "xz"), compression_level, version = NULL)
paths |
A character vector of paths to |
compress, compression_level
|
Type and level of compression: see
|
version |
The format to be used when re-saving: see
|
compress = "auto" asks R to choose the compression and ignores
compression_level. It will try "gzip", "bzip2"
and if the "gzip" compressed size is over 10Kb, "xz" and
choose the smallest compressed file (but with a 10% bias towards
"gzip"). This can be slow.
For back-compatibility, version = NULL is interpreted to mean
version 2: however version-3 files will only be saved as version 3.
For checkRdaFiles, a data frame with rows names paths
and columns
size |
numeric: file size in bytes, |
ASCII |
logical: true for save(ASCII = TRUE), |
compress |
character: type of compression. One of |
version |
integer: positive with the version(s) of the
|
## Not run: ## from a package top-level source directory paths <- sort(Sys.glob(c("data/*.rda", "data/*.RData"))) (res <- checkRdaFiles(paths)) ## pick out some that may need attention bad <- is.na(res$ASCII) | res$ASCII | (res$size > 1e4 & res$compress == "none") res[bad, ] ## End(Not run)## Not run: ## from a package top-level source directory paths <- sort(Sys.glob(c("data/*.rda", "data/*.RData"))) (res <- checkRdaFiles(paths)) ## pick out some that may need attention bad <- is.na(res$ASCII) | res$ASCII | (res$size > 1e4 & res$compress == "none") res[bad, ] ## End(Not run)
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.
checkTnF(package, dir, file, lib.loc = NULL)checkTnF(package, dir, file, lib.loc = NULL)
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 |
file |
the name of a file containing R code to be checked. Used
if neither |
lib.loc |
a character vector of directory names of R libraries,
or |
An object of class "checkTnF" which is a list containing, for
each file where occurrences 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.
Check all vignettes of a package by running
Sweave (or other custom weave function) and/or
Stangle (or other custom tangle function) on them.
All R source code files found after the tangling step are
sourceed to check whether all code can be
executed without errors.
checkVignettes(package, dir, lib.loc = NULL, tangle = TRUE, weave = TRUE, latex = FALSE, workdir = c("tmp", "src", "cur"), keepfiles = FALSE)checkVignettes(package, dir, lib.loc = NULL, tangle = TRUE, weave = TRUE, latex = FALSE, workdir = c("tmp", "src", "cur"), keepfiles = FALSE)
package |
a character string naming an installed package. If given, vignette source files are looked for in subdirectory ‘doc’. |
dir |
a character string specifying the path to a package's root source directory. If given, vignette source files are looked for in subdirectory ‘vignettes’. |
lib.loc |
a character vector of directory names of R libraries,
or |
tangle |
Perform a tangle and |
weave |
Perform a weave? |
latex |
logical: if |
workdir |
Directory used as working directory while checking the
vignettes. If |
keepfiles |
Delete files in the temporary directory? This option is
ignored when |
This function first uses pkgVignettes to find the
package vignettes, and in particular their vignette engines (see
vignetteEngine).
If tangle is true, it then runs Stangle (or
other custom tangle function provided by the engine) to produce (one
or more) R code files from each vignette, then sources
each code file in turn.
If weave is true, the vignettes are run through
Sweave (or other custom weave function provided by the
engine). If latex is also true and there is no ‘Makefile’
in the vignettes directory, texi2pdf is run on the
intermediate ‘.tex’ files from weaving for those vignettes which
did not give errors in the previous steps.
An object of class "checkVignettes", which is a list with the
error messages found during the tangle, source, weave and latex steps.
There is a print method for displaying the information
contained in such objects.
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.
codoc(package, dir, lib.loc = NULL, use.values = NULL, verbose = getOption("verbose")) codocClasses(package, lib.loc = NULL) codocData(package, lib.loc = NULL)codoc(package, dir, lib.loc = NULL, use.values = NULL, verbose = getOption("verbose")) codocClasses(package, lib.loc = NULL) codocData(package, lib.loc = NULL)
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 |
lib.loc |
a character vector of directory names of R libraries,
or |
use.values |
if |
verbose |
a logical. If |
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.
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 ‘templates’
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 ‘pkgname-defunct.Rd’ for the appropriate pkgname are checked more loosely, as they may have undocumented arguments.
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.
The default for use.values has been changed from
FALSE to NULL, for R versions 1.9.0 and later.
Re-save PDF files (especially vignettes) more compactly.
Support function for R CMD build --compact-vignettes.
compactPDF(paths, qpdf = Sys.which(Sys.getenv("R_QPDF", "qpdf")), gs_cmd = Sys.getenv("R_GSCMD", ""), gs_quality = Sys.getenv("GS_QUALITY", "none"), gs_extras = character(), verbose = FALSE) ## S3 method for class 'compactPDF' format(x, ratio = 0.9, diff = 1e4, ...)compactPDF(paths, qpdf = Sys.which(Sys.getenv("R_QPDF", "qpdf")), gs_cmd = Sys.getenv("R_GSCMD", ""), gs_quality = Sys.getenv("GS_QUALITY", "none"), gs_extras = character(), verbose = FALSE) ## S3 method for class 'compactPDF' format(x, ratio = 0.9, diff = 1e4, ...)
paths |
A character vector of paths to PDF files, or a length-one character vector naming a directory, when all ‘.pdf’ files in that directory will be used. |
qpdf |
Character string giving the path to the |
gs_cmd |
Character string giving the path to the GhostScript
executable, if that is to be used. On Windows this is the path to
‘gswin32c.exe’ or ‘gswin64c.exe’. If |
gs_quality |
A character string indicating the quality required:
the options are |
gs_extras |
An optional character vector of further options to be passed to GhostScript. |
verbose |
|
x |
An object of class |
ratio, diff
|
Limits for reporting: files are only reported whose
sizes are reduced both by a factor of |
... |
Further arguments to be passed to or from other methods. |
This by default makes use of qpdf, available from
https://qpdf.sourceforge.io/ (including as a Windows binary) and
included with the CRAN macOS distribution of R. If gs_cmd
is non-empty and gs_quality != "none", GhostScript will used
first, then qpdf if it is available. If
gs_quality != "none" and gs_cmd is "", an attempt
will be made to find a GhostScript executable.
qpdf and/or gs_cmd are run on all PDF files found,
and those which are reduced in size by at least 10% and 10Kb are
replaced.
The strategy of our use of qpdf is to (losslessly) compress
both PDF streams and objects. GhostScript compresses streams and more
(including downsampling and compressing embedded images) and
consequently is much slower and may lose quality (but can also produce
much smaller PDF files). However, quality "ebook" is perfectly
adequate for screen viewing and printing on laser printers.
Where PDF files are changed they will become PDF version 1.5 files: these have been supported by Acrobat Reader since version 6 in 2003, so this is very unlikely to cause difficulties.
Stream compression is what most often has large gains. Most PDF
documents are generated with object compression, but this does not
seem to be the default for MiKTeX's pdflatex. For some PDF
files (and especially package vignettes), using GhostScript can
dramatically reduce the space taken by embedded images (often
screenshots).
Where both GhostScript and qpdf are selected (when
gs_quality != "none" and both executables are found), they are
run in that order and the size reductions apply to the total
compression achieved.
An object of class c("compactPDF", "data.frame").
This has two columns, the old and new sizes in bytes for the files
that were changed.
There are format and print methods: the latter passes
... to the format method, so will accept ratio and
diff arguments.
The external tools used may change in future releases.
Frequently, updates to GhostScript have produced better compression (up to several times better), so if possible use the latest version available.
For other tools to compact PDF files, see the ‘Writing R Extensions’ manual.
Tools for obtaining information about current packages in the CRAN package repository, and their check status.
CRAN_package_db() CRAN_check_results(flavors = NULL) CRAN_check_details(flavors = NULL) CRAN_check_issues() summarize_CRAN_check_status(packages, results = NULL, details = NULL, issues = NULL)CRAN_package_db() CRAN_check_results(flavors = NULL) CRAN_check_details(flavors = NULL) CRAN_check_issues() summarize_CRAN_check_status(packages, results = NULL, details = NULL, issues = NULL)
packages |
a character vector of package names. |
flavors |
a character vector of CRAN check flavor names, or
|
results |
the return value of |
details |
the return value of |
issues |
the return value of |
CRAN_package_db() returns a data frame with character columns
containing most ‘DESCRIPTION’ metadata for the current packages
in the CRAN package repository, including in particular the
Description and Maintainer information not provided by
utils::available.packages().
CRAN_check_results() returns a data frame with the basic
CRAN package check results including timings, with columns
Package, Flavor and Status giving the package
name, check flavor, and overall check status, respectively.
CRAN_check_details() returns a data frame inheriting from class
"check_details" (which has useful print and
format methods) with details on the check results, providing
check name, status and output for every non-OK check (via
columns Check, Status and Output, respectively).
Packages with all-OK checks are indicated via a * Check
wildcard name and OK Status.
CRAN_check_issues() returns a character frame with additional
check issues (including the memory-access check results made available
from https://www.stats.ox.ac.uk/pub/bdr/memtests/) as a
character frame with variables Package, Version,
kind (an identifier for the issue) and href (a URL with
information on the issue).
See ‘Details’. Note that the results are collated on
CRAN: currently this is done in a locale which sorts
aAbB ....
The main functions access a CRAN mirror specified by the
environment variable R_CRAN_WEB, defaulting to one specified in
the "repos" option. Otherwise the entry in the
‘repositories’ file (see setRepositories) is used:
if that specifies ‘@CRAN@’ (the default) or does not contain an
entry for CRAN then https://CRAN.R-project.org is used.
The mirror to be used is reported by
utils::findCRANmirror("web").
Note that these functions access parts of CRAN under ‘web/contrib’ and ‘web/packages’ so if you have specified a mirror of just ‘src/contrib’ for installing packages you will need to set R_CRAN_WEB to point to a full mirror.
Internal functions CRAN_aliases_db, CRAN_archive_db,
CRAN_current_db and CRAN_rdxrefs_db (used by R
CMD check) use R_CRAN_SRC rather than R_CRAN_WEB.
## This can be rather slow with a non-local CRAN mirror ## and might fail (slowly) without Internet access in that case. set.seed(11) # but the packages chosen will change as soon as CRAN does. pdb <- CRAN_package_db() dim(pdb) ## DESCRIPTION fields included: colnames(pdb) ## Summarize publication dates: summary(as.Date(pdb$Published)) ## Summarize numbers of packages according to maintainer: summary(lengths(split(pdb$Package, pdb$Maintainer))) ## Packages with 'LASSO' in their Description: pdb$Package[grepl("LASSO", pdb$Description)] results <- CRAN_check_results() ## Available variables: names(results) ## Tabulate overall check status according to flavor: with(results, table(Flavor, Status)) details <- CRAN_check_details() ## Available variables: names(details) ## Tabulate checks according to their status: tab <- with(details, table(Check, Status)) ## Inspect some installation problems: bad <- subset(details, ((Check == "whether package can be installed") & (Status != "OK"))) ## Show a random sample of up to 6 head(bad[sample(seq_len(NROW(bad)), NROW(bad)), ]) issues <- CRAN_check_issues() head(issues) ## Show counts of issues according to kind: table(issues[, "kind"]) ## Summarize CRAN check status for 10 randomly-selected packages ## (reusing the information already read in): pos <- sample(seq_len(NROW(pdb)), 10L) summarize_CRAN_check_status(pdb[pos, "Package"], results, details, issues)## This can be rather slow with a non-local CRAN mirror ## and might fail (slowly) without Internet access in that case. set.seed(11) # but the packages chosen will change as soon as CRAN does. pdb <- CRAN_package_db() dim(pdb) ## DESCRIPTION fields included: colnames(pdb) ## Summarize publication dates: summary(as.Date(pdb$Published)) ## Summarize numbers of packages according to maintainer: summary(lengths(split(pdb$Package, pdb$Maintainer))) ## Packages with 'LASSO' in their Description: pdb$Package[grepl("LASSO", pdb$Description)] results <- CRAN_check_results() ## Available variables: names(results) ## Tabulate overall check status according to flavor: with(results, table(Flavor, Status)) details <- CRAN_check_details() ## Available variables: names(details) ## Tabulate checks according to their status: tab <- with(details, table(Check, Status)) ## Inspect some installation problems: bad <- subset(details, ((Check == "whether package can be installed") & (Status != "OK"))) ## Show a random sample of up to 6 head(bad[sample(seq_len(NROW(bad)), NROW(bad)), ]) issues <- CRAN_check_issues() head(issues) ## Show counts of issues according to kind: table(issues[, "kind"]) ## Summarize CRAN check status for 10 randomly-selected packages ## (reusing the information already read in): pos <- sample(seq_len(NROW(pdb)), 10L) summarize_CRAN_check_status(pdb[pos, "Package"], results, details, issues)
Match delimited substrings in a character vector, with proper nesting.
delimMatch(x, delim = c("{", "}"), syntax = "Rd")delimMatch(x, delim = c("{", "}"), syntax = "Rd")
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 |
An integer vector of the same length as x giving the starting
position (in characters) of the first match, or if there is
none, with attribute "match.length" giving the length (in
characters) of the matched text (or for no match).
regexpr for ‘simple’ pattern matching.
x <- c("\\value{foo}", "function(bar)") delimMatch(x) delimMatch(x, c("(", ")"))x <- c("\\value{foo}", "function(bar)") delimMatch(x) delimMatch(x, c("(", ")"))
Find ‘reverse’ dependencies of packages, that is those packages which depend on this one, and (optionally) so on recursively.
dependsOnPkgs(pkgs, dependencies = "strong", recursive = TRUE, lib.loc = NULL, installed = utils::installed.packages(lib.loc, fields = "Enhances"))dependsOnPkgs(pkgs, dependencies = "strong", recursive = TRUE, lib.loc = NULL, installed = utils::installed.packages(lib.loc, fields = "Enhances"))
pkgs |
a character vector of package names. |
dependencies |
a character vector listing the types of
dependencies, a subset of
|
recursive |
logical: should reverse dependencies of reverse dependencies (and so on) be included? |
lib.loc |
a character vector of R library trees, or |
installed |
a result of calling |
A character vector of package names, which does not include any from
pkgs.
package_dependencies() to get the regular
(“forward”) dependencies of a package.
## there are few dependencies in a vanilla R installation: ## lattice may not be installed dependsOnPkgs("lattice")## there are few dependencies in a vanilla R installation: ## lattice may not be installed dependsOnPkgs("lattice")
Translate non-ASCII characters in text to LaTeX escape sequences.
encoded_text_to_latex(x, encoding = c("latin1", "latin2", "latin9", "UTF-8", "utf8"))encoded_text_to_latex(x, encoding = c("latin1", "latin2", "latin9", "UTF-8", "utf8"))
x |
a character vector. |
encoding |
the encoding to be assumed. |
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 ‘\-’.
A character vector of the same length as x.
x <- "fran\xE7ais" 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(paste0(xx, "\\\\"), 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)x <- "fran\xE7ais" 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(paste0(xx, "\\\\"), 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)
Utilities for listing files, and manipulating file paths.
file_ext(x) file_path_as_absolute(x) file_path_sans_ext(x, compression = FALSE) 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())file_ext(x) file_path_as_absolute(x) file_path_sans_ext(x, compression = FALSE) 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())
x |
character vector giving file paths. |
compression |
logical: should compression extension ‘.gz’, ‘.bz2’ or ‘.xz’ be removed first? |
dir |
a character string with the path name to a directory. |
exts |
a character vector of possible file extensions (excluding the leading dot). |
all.files |
a logical. If |
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 |
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
|
file_ext returns the file (name) extensions (excluding the
leading dot).
(Only purely alphanumeric extensions are recognized.)
file_path_as_absolute turns a possibly relative file path
absolute, performing tilde expansion if necessary. This is a wrapper
for normalizePath. Currently, x must be a single
existing path.
file_path_sans_ext returns the file paths without extensions
(and the leading dot).
(Only purely alphanumeric extensions are recognized.)
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.
file.path,
file.info,
list.files
dir <- file.path(R.home(), "library", "stats") 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"))))dir <- file.path(R.home(), "library", "stats") 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"))))
Find a GhostScript executable in a cross-platform way.
find_gs_cmd(gs_cmd = "")find_gs_cmd(gs_cmd = "")
gs_cmd |
The name, full or partial path of a GhostScript executable. |
The details differ by platform.
On a Unix-alike, the GhostScript executable is usually called
gs. The name (and possibly path) of the command is taken
first from argument gs_cmd then from the environment variable
R_GSCMD and default gs. This is then looked for on the
system path and the value returned if a match is found.
On Windows, the name of the command is taken from argument
gs_cmd then from the environment variables R_GSCMD and
GSC. If neither of those produces a suitable command name,
gswin64c and gswin32c are tried in turn. In all
cases the command is looked for on the system PATH.
Note that on Windows (and some other OSes) there are separate GhostScript executables to display Postscript/PDF files and to manipulate them: this function looks for the latter.
A character string giving the full path to a GhostScript executable if one was found, otherwise an empty string.
## Not run: ## Suppose a Solaris system has GhostScript 9.00 on the path and ## 9.07 in /opt/csw/bin. Then one might set Sys.setenv(R_GSCMD = "/opt/csw/bin/gs") ## End(Not run)## Not run: ## Suppose a Solaris system has GhostScript 9.00 on the path and ## 9.07 in /opt/csw/bin. Then one might set Sys.setenv(R_GSCMD = "/opt/csw/bin/gs") ## End(Not run)
This function gets information on installed vignettes.
getVignetteInfo(package = NULL, lib.loc = NULL, all = TRUE)getVignetteInfo(package = NULL, lib.loc = NULL, all = TRUE)
package |
Which package to look in, or |
lib.loc |
Which library to look in. |
all |
Whether to search all installed packages, or just attached packages. |
A matrix with columns
Package |
the name of the package |
Dir |
the directory where the package is installed |
Topic |
the name of the vignette |
File |
the base filename of the source of the vignette |
Title |
the title of the vignette |
R |
the tangled R source from the vignette |
PDF |
the PDF or HTML file for display |
The last column of the result is named PDF for historical reasons,
but it may contain a filename of a PDF or HTML document.
pkgVignettes is a similar function that can work on
an uninstalled package.
getVignetteInfo("grid")getVignetteInfo("grid")
This function generates the standard HTML header used on R help pages.
HTMLheader(title = "R", logo = TRUE, up = NULL, top = file.path(Rhome, "doc/html/index.html"), Rhome = "", css = file.path(Rhome, "doc/html/R.css"), headerTitle = paste("R:", title), outputEncoding = "UTF-8")HTMLheader(title = "R", logo = TRUE, up = NULL, top = file.path(Rhome, "doc/html/index.html"), Rhome = "", css = file.path(Rhome, "doc/html/R.css"), headerTitle = paste("R:", title), outputEncoding = "UTF-8")
title |
The title to display and use in the HTML headers. Should have had any HTML escaping already done. |
logo |
Whether to display the R logo after the title. |
up |
Which page (if any) to link to on the “up” button. |
top |
Which page (if any) to link to on the “top” button. |
Rhome |
A relative path to the R home directory. See the ‘Details’. |
css |
The relative URL for the Cascading Style Sheet. |
headerTitle |
The title used in the headers. |
outputEncoding |
The declared encoding for the whole page. |
The up and top links should be relative to the current page.
The Rhome path default works with dynamic help; for static help, a
relative path (e.g., ‘../..’) to it should be used.
A character vector containing the lines of an HTML header which can be used to start a page in the R help system.
cat(HTMLheader("This is a sample header"), sep="\n")cat(HTMLheader("This is a sample header"), sep="\n")
Compute relative file paths for URLs to other package's installed HTML documentation.
findHTMLlinks(pkgDir = "", lib.loc = NULL, level = 0:2)findHTMLlinks(pkgDir = "", lib.loc = NULL, level = 0:2)
pkgDir |
the top-level directory of an installed package. The default indicates no package. |
lib.loc |
character vector describing the location of R library
trees to scan: the default indicates |
level |
Which level(s) to include. |
findHTMLlinks tries to resolve links from one help page to
another. It uses in decreasing priority
The package in pkgDir: this is used when converting
HTML help for that package (level 0).
The base and recommended packages (level 1).
Other packages found in the library trees specified by
lib.loc in the order of the trees and alphabetically within a
library tree (level 2).
A named character vector of file paths, relative to the ‘html’ directory of an installed package. So these are of the form ‘"../../somepkg/html/sometopic.html"’.
Duncan Murdoch, Brian Ripley
Loads macros from an ‘.Rd’ file, or from several ‘.Rd’ files contained in a package.
loadRdMacros(file, macros = TRUE) loadPkgRdMacros(pkgdir, macros = NULL)loadRdMacros(file, macros = TRUE) loadPkgRdMacros(pkgdir, macros = NULL)
file |
A file in Rd format containing macro definitions. |
macros |
optionally, a previous set of macro definitions, in the format
expected by the |
pkgdir |
The base directory of a source package or an installed package. |
The Rd files parsed by these functions should contain only macro definitions; a warning will be issued if anything else other than comments or white space is found.
The macros argument may be a filename of a base set of macros,
or the result of a previous call to loadRdMacros or
loadPkgRdMacros in the same session. These results should be
assumed to be valid only within the current session.
The loadPkgRdMacros function first looks for an "RdMacros"
entry in the package ‘DESCRIPTION’ file. If present, it should
contain a comma-separated list of other package names; their macros
will be loaded before those of the current package. It will then look
in the current package for ‘.Rd’ files in the ‘man/macros’
or ‘help/macros’ subdirectories, and load those.
These functions each return an environment containing objects with the
names of the newly defined macros from the last file processed. The
parent environment will be macros from the previous file, and so on.
The first file processed will have emptyenv() as its
parent.
Duncan Murdoch
See the ‘Writing R Extensions’ manual for the syntax of Rd files, or https://developer.r-project.org/parseRd.pdf for a technical discussion.
f <- tempfile() writeLines(r"( \newcommand{\Rlogo}{ \if{html}{\figure{Rlogo.svg}{options: width=100 alt="R logo"}} \if{latex}{\figure{Rlogo.pdf}{options: width=0.5in}} } )", f) m <- loadRdMacros(f) ls(m) ls(parent.env(m)) ls(parent.env(parent.env(m))) parse_Rd(textConnection(r"(\Rlogo)"), fragment = TRUE, macros = m)f <- tempfile() writeLines(r"( \newcommand{\Rlogo}{ \if{html}{\figure{Rlogo.svg}{options: width=100 alt="R logo"}} \if{latex}{\figure{Rlogo.pdf}{options: width=0.5in}} } )", f) m <- loadRdMacros(f) ls(m) ls(parent.env(m)) ls(parent.env(parent.env(m))) parse_Rd(textConnection(r"(\Rlogo)"), fragment = TRUE, macros = m)
A utility for R Core members to prepare a package of updated translations.
make_translations_pkg(srcdir, outDir = ".", append = "-1")make_translations_pkg(srcdir, outDir = ".", append = "-1")
srcdir |
The R source directory. |
outDir |
The directory into which to place the prepared package. |
append |
The suffix for the package version number, e.g. ‘3.0.0-1’ will be the default in R 3.0.0. |
This extracts the translations in a current R source distribution and
packages them as a source package called translations which can
be distributed on CRAN and installed by
update.packages. This allows e.g. the translations
shipped in R 3.x.y to be updated to those currently in
‘R-patched’, even by a user without administrative privileges.
The package has a ‘Depends’ field which restricts it to versions
‘3.x.*’ for a single x.
Determine the location of the user and site specific ‘Makevars’ files for customizing package compilation.
makevars_user() makevars_site()makevars_user() makevars_site()
Package maintainers can use these functions to employ user and site
specific compilation settings also for compilations not using R's
mechanisms (in particular, custom compilations in subdirectories of
‘src’), e.g., by adding configure code calling R with
cat(tools::makevars_user()) or
cat(tools::makevars_site()), and if non-empty passing this with
-f to custom Make invocations.
A character string with the path to the user or site specific ‘Makevars’ file, or an empty character vector if there is no such file.
Section ‘Customizing package compilation’ in the ‘R Installation and Administration’ manual.
makevars_user() makevars_site()makevars_user() makevars_site()
The Rd parser records locations in ‘.Rd’ files from
which components of the file are read. Output generators
Rd2HTML and Rd2latex can output
information about these locations as “concordances” between
source and output lines.
matchConcordance converts from output locations
to source locations. The "Rconcordance" method of
as.character produces
strings to embed in output files, and the default method of
as.Rconcordance
converts these back to objects that can be interpreted
by matchConcordance.
matchConcordance(linenum, concordance) ## S3 method for class 'Rconcordance' as.character(x, targetfile = "", ...) as.Rconcordance(x, ...) followConcordance(concordance, prevConcordance)matchConcordance(linenum, concordance) ## S3 method for class 'Rconcordance' as.character(x, targetfile = "", ...) as.Rconcordance(x, ...) followConcordance(concordance, prevConcordance)
linenum |
One or more line numbers being queried. |
concordance |
The concordance data for the file containing the lines: an object
of class |
prevConcordance |
A concordance object retrieved from the current file. |
targetfile |
The output filename. |
x |
The object to convert: for |
... |
Further arguments passed to other methods. |
The correspondence between target lines and source lines in Rd file conversion is not one to one. Often a single source line can lead to the generation of multiple output lines, and sometimes more than one source line triggers output on the same output line.
matchConcordance converts from target lines to
source lines. This can be used to help in understanding how
particular output lines
depend on the source, e.g. when an error is found in the
output file. When more than one line contributes
to the output, the last one will be returned.
The "Rconcordance" method of as.character converts a
concordance object
to strings suitable for embedding (e.g. in comments) in an
output file.
The default method of as.Rconcordance searches for strings matching the
pattern of as.character.Rconcordance output, then converts
those lines back to a single concordance.
followConcordance is used when a file is transformed
more than once. The first transformation records a
concordance in the file which is read as prevConcordance.
followConcordance chains this with the current
concordance, relating the final result to the original
source.
There are 3 kinds of objects used to hold concordances.
Objects of class "activeConcordance" are internal to tools; they
are used by Rd2HTML and Rd2latex while building the output
file and saving links to the source file.
Objects of class "Rconcordance" are visible to users.
They are list objects with the following three fields:
offsetThe number of lines of output before the first one corresponding to this concordance.
srcLineFor each line of output after the offset,
the corresponding input file line number. There may be more lines
of output than the length of srcLine, in which case nothing
can be inferred about the source of those lines.
srcFileA vector of filenames of length 1 or the
same length as srcLine giving the source file(s) for
each output line.
Concordance strings are produced by the "Rconcordance" method of
as.character;
they are simply character vectors encoding the concordance data.
The default method of the as.concordance generic function
converts them to "Rconcordance" objects.
matchConcordance returns a character array with one row
per input linenum entry and
two columns, "srcFile" and "srcLine".
For the "Rconcordance" method of as.character, a character
vector used (e.g. in Sweave) to embed
the concordance in a file.
For as.concordance, an "Rconcordance" object, or NULL
if no concordance strings are found.
Duncan Murdoch
Compute the 32-byte MD5 hashes of one or more files.
md5sum(files)md5sum(files)
files |
character. The paths of file(s) whose contents are to be hashed. |
A MD5 ‘hash’ or ‘checksum’ or ‘message digest’ is a 128-bit summary of the file contents represented by 32 hexadecimal digits. Files with different MD5 sums are different: only very exceptionally (and usually with the intent to deceive) are those with the same sums different.
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
mode (almost always text mode where there is more than one).
MD5 sums are used as a check that R packages have been unpacked correctly and not subsequently accidentally modified.
A character vector of the same length as files, with names
equal to files (possibly expanded). The elements will be
NA for non-existent or unreadable files, otherwise a
32-character string of hexadecimal digits.
The underlying C code was written by Ulrich Drepper and extracted from
a 2001 release of glibc.
as.vector(md5sum(dir(R.home(), pattern = "^COPY", full.names = TRUE)))as.vector(md5sum(dir(R.home(), pattern = "^COPY", full.names = TRUE)))
Find (recursively) dependencies or reverse dependencies of packages.
package_dependencies(packages = NULL, db = NULL, which = "strong", recursive = FALSE, reverse = FALSE, verbose = getOption("verbose"))package_dependencies(packages = NULL, db = NULL, which = "strong", recursive = FALSE, reverse = FALSE, verbose = getOption("verbose"))
packages |
a character vector of package names. |
db |
character matrix as from |
which |
a character vector listing the types of
dependencies, a subset of
|
recursive |
a logical indicating whether (reverse) dependencies
of (reverse) dependencies (and so on) should be included, or a
character vector like |
reverse |
logical: if |
verbose |
logical indicating if output should monitor the package search cycles. |
Named list with one element for each package in argument packages,
each consists of a character vector naming the (recursive) (reverse) dependencies
of that package.
For given packages which are not found in the db, NULL entries are returned,
as opposed to character(0) entries which indicate no dependencies.
myPkgs <- c("MASS", "Matrix", "KernSmooth", "class", "cluster", "codetools") pdb <- available.packages(repos = findCRANmirror("web")) system.time( dep1 <- package_dependencies(myPkgs, db = pdb) # all arguments at default ) # very fast utils::str(dep1, vec.len=10) system.time( ## reverse dependencies, recursively --- takes much longer: deps <- package_dependencies(myPkgs, db = pdb, which = "most", recursive = TRUE, reverse = TRUE) ) # seen ~ 10 seconds lengths(deps) # 2020-05-03: all are 16053, but codetools with 16057 ## install.packages(dependencies = TRUE) installs 'most' dependencies ## and the strong recursive dependencies of these: these dependencies ## can be obtained using 'which = "most"' and 'recursive = "strong"'. ## To illustrate on the first packages with non-missing Suggests: packages <- pdb[head(which(!is.na(pdb[, "Suggests"]))), "Package"] package_dependencies(packages, db = pdb, which = "most", recursive = "strong")myPkgs <- c("MASS", "Matrix", "KernSmooth", "class", "cluster", "codetools") pdb <- available.packages(repos = findCRANmirror("web")) system.time( dep1 <- package_dependencies(myPkgs, db = pdb) # all arguments at default ) # very fast utils::str(dep1, vec.len=10) system.time( ## reverse dependencies, recursively --- takes much longer: deps <- package_dependencies(myPkgs, db = pdb, which = "most", recursive = TRUE, reverse = TRUE) ) # seen ~ 10 seconds lengths(deps) # 2020-05-03: all are 16053, but codetools with 16057 ## install.packages(dependencies = TRUE) installs 'most' dependencies ## and the strong recursive dependencies of these: these dependencies ## can be obtained using 'which = "most"' and 'recursive = "strong"'. ## To illustrate on the first packages with non-missing Suggests: packages <- pdb[head(which(!is.na(pdb[, "Suggests"]))), "Package"] package_dependencies(packages, db = pdb, which = "most", recursive = "strong")
Write a skeleton for adding native routine registration to a package.
package_native_routine_registration_skeleton(dir, con = stdout(), align = TRUE, character_only = TRUE, include_declarations = TRUE)package_native_routine_registration_skeleton(dir, con = stdout(), align = TRUE, character_only = TRUE, include_declarations = TRUE)
dir |
Top-level directory of a package. |
con |
Connection on which to write the skeleton: can be specified as a file path. |
align |
Logical: should the registration tables be lined up in three columns each? |
character_only |
Logical: should only |
include_declarations |
Logical: should the output include declarations (also known as ‘prototypes’) for the registered routines? |
Registration is described in section ‘Registering native routines’ of ‘Writing R Extensions’. This function produces a skeleton of the C code which needs to be added to enable registration, conventionally as file ‘src/init.c’ or appended to the sole C file of the package.
This function examines the code in the ‘R’ directory of the
package for calls to .C, .Fortran, .Call and
.External and creates registration information for those it can
make sense of. If the number of arguments used cannot be determined
it will be recorded as -1: such values should be corrected.
Optionally the skeleton will include declarations for the registered
routines: they should be checked against the C/Fortran source code,
not least as the number of arguments is taken from the R code. For
.Call and .External calls they will often suffice, but
for .C and .Fortran calls the ‘void *’ arguments
would ideally be replaced by the actual types. Otherwise declarations
need to be included (they may exist earlier in that file if appending
to a file, or in a header file which can be included in
‘init.c’).
The default value of character_only is appropriate when working
on a package without any existing registration:
character_only = FALSE
can be used to suggest updates for a package which has been
extended since registration. For the default value, if .NAME
values are found which are not character strings (e.g. names
or expressions) this is noted via a comment in the output.
Packages which used the earlier form of creating R objects for native
symbols via additional arguments in a useDynLib
directive will probably most easily be updated to use registration
with character_only = FALSE.
If an entry point is used with different numbers of arguments in the
package's R code, an entry in the table (and optionally, a
declaration) is made for each number, and a comment placed in the
output. This needs to be resolved: only .External calls can
have a variable number of arguments, which should be declared as
-1.
A surprising number of CRAN packages had calls in R code to native routines not included in the package, which will lead to a ‘loading failed’ error during package installation when the registration C code is added.
Calls which do not name a routine such as .Call(...) will be
silently ignored.
None: the output is written to the connection con.
There are several tools available to extract function declarations from C or C++ code.
For C code one can use cproto
(https://invisible-island.net/cproto/cproto.html; Windows
executables are available), for
example
cproto -I/path/to/R/include -e *.c
ctags (commonly distributed with the OS)
covers C and C++., using something like
ctags -x *.c
to list all function usages. (The ‘Exuberant’ version allows a lot more control.)
gfortran 9.2 and later can extract C prototypes for Fortran
subroutines with a special flag:
gfortran -c -fc-prototypes-external file.f
although ironically not for functions declared bind(C).
This only examines the ‘R’ directory: it will not find
e.g. .Call calls used directly in examples, tests etc.
Static code analysis is used to find the .C etc calls: it
will find those in parts of the R code ‘commented out’
by inclusion in if(FALSE) { ... }.
On the other hand, it will fail to find the entry points in
constructs like
.Call(if(int) "rle_i" else "rle_d", i, force)
and does not know the value of variables in calls like
.Call (cfunction, ...)
.Call(..., PACKAGE="sparseLTSEigen")
(but if character_only is false, will extract the first as
"cfunction"). Calls which have not been fully resolved will be
noted via comments in the output file.
Call to entry points in other packages will be ignored if they have an
explicit (character string) PACKAGE argument.
## Not run: ## with a completed splines/DESCRIPTION file, tools::package_native_routine_registration_skeleton('splines',,,FALSE) ## produces #include <R.h> #include <Rinternals.h> #include <stdlib.h> // for NULL #include <R_ext/Rdynload.h> /* FIXME: Check these declarations against the C/Fortran source code. */ /* .Call calls */ extern SEXP spline_basis(SEXP, SEXP, SEXP, SEXP); extern SEXP spline_value(SEXP, SEXP, SEXP, SEXP, SEXP); static const R_CallMethodDef CallEntries[] = { {"spline_basis", (DL_FUNC) &spline_basis, 4}, {"spline_value", (DL_FUNC) &spline_value, 5}, {NULL, NULL, 0} }; void R_init_splines(DllInfo *dll) { R_registerRoutines(dll, NULL, CallEntries, NULL, NULL); R_useDynamicSymbols(dll, FALSE); } ## End(Not run)## Not run: ## with a completed splines/DESCRIPTION file, tools::package_native_routine_registration_skeleton('splines',,,FALSE) ## produces #include <R.h> #include <Rinternals.h> #include <stdlib.h> // for NULL #include <R_ext/Rdynload.h> /* FIXME: Check these declarations against the C/Fortran source code. */ /* .Call calls */ extern SEXP spline_basis(SEXP, SEXP, SEXP, SEXP); extern SEXP spline_value(SEXP, SEXP, SEXP, SEXP, SEXP); static const R_CallMethodDef CallEntries[] = { {"spline_basis", (DL_FUNC) &spline_basis, 4}, {"spline_value", (DL_FUNC) &spline_value, 5}, {NULL, NULL, 0} }; void R_init_splines(DllInfo *dll) { R_registerRoutines(dll, NULL, CallEntries, NULL, NULL); R_useDynamicSymbols(dll, FALSE); } ## End(Not run)
This function reads an R documentation (Rd) file and parses it, for processing by other functions.
parse_Rd(file, srcfile = NULL, encoding = "unknown", verbose = FALSE, fragment = FALSE, warningCalls = TRUE, macros = file.path(R.home("share"), "Rd", "macros", "system.Rd"), permissive = FALSE) ## S3 method for class 'Rd' print(x, deparse = FALSE, ...) ## S3 method for class 'Rd' as.character(x, deparse = FALSE, ...)parse_Rd(file, srcfile = NULL, encoding = "unknown", verbose = FALSE, fragment = FALSE, warningCalls = TRUE, macros = file.path(R.home("share"), "Rd", "macros", "system.Rd"), permissive = FALSE) ## S3 method for class 'Rd' print(x, deparse = FALSE, ...) ## S3 method for class 'Rd' as.character(x, deparse = FALSE, ...)
file |
A filename or text-mode connection. At present filenames work best. |
srcfile |
|
encoding |
Encoding to be assumed for input strings. |
verbose |
Logical indicating whether detailed parsing information should be printed. |
fragment |
Logical indicating whether file represents a complete Rd file, or a fragment. |
warningCalls |
Logical: should parser warnings include the call? |
macros |
Filename or environment from which to load additional macros, or a logical value. See the Details below. |
permissive |
Logical indicating that unrecognized macros should be treated as text with no warning. |
x |
An object of class Rd. |
deparse |
If |
... |
Further arguments to be passed to or from other methods. |
This function parses ‘Rd’ files according to the specification given in https://developer.r-project.org/parseRd.pdf.
It generates a warning for each parse error and attempts to continue parsing. In order to continue, it is generally necessary to drop some parts of the file, so such warnings should not be ignored.
Files without a marked encoding are by default assumed to be in the
native encoding. An alternate default can be set using the
encoding argument. All text in files is translated to the
UTF-8 encoding in the parsed object.
As from R version 3.2.0, User-defined macros may be given in a
separate file using ‘\newcommand’ or ‘\renewcommand’.
An environment may also be given: it would be produced by
loadRdMacros, loadPkgRdMacros, or
by a previous call to parse_Rd. If a logical value
is given, only the default built-in macros will be used;
FALSE indicates that no "macros" attribute
will be returned with the result.
The permissive argument allows text to be parsed that is
not completely in Rd format. Typically it would be LaTeX code,
used in an Rd fragment, e.g. in a bibentry.
With permissive = TRUE, this will be passed through as plain
text. Since parse_Rd doesn't know how many arguments
belong in LaTeX macros, it will guess based on the presence
of braces after the macro; this is not infallible.
parse_Rd returns an object of class "Rd". The
internal format of this object is subject to change. The
as.character() and print() methods defined for the
class return character vectors and print them, respectively.
Unless macros = FALSE, the object will have an attribute
named "macros", which is an environment containing the
macros defined in file, in a format that can be used for
further parse_Rd calls in the same session. It is not
guaranteed to work if saved to a file and reloaded in a different
session.
Duncan Murdoch
https://developer.r-project.org/parseRd.pdf
Rd2HTML for the converters that use the output of
parse_Rd().
The parseLatex function parses LaTeX source, producing a
structured object; deparseLatex reverses the process. The
latexToUtf8 function takes a LaTeX object, and processes a number
of different macros to convert them into the corresponding UTF-8
characters.
parseLatex(text, filename = deparse1(substitute(text)), verbose = FALSE, verbatim = c("verbatim", "verbatim*", "Sinput", "Soutput"), verb = "\\Sexpr") deparseLatex(x, dropBraces = FALSE) latexToUtf8(x)parseLatex(text, filename = deparse1(substitute(text)), verbose = FALSE, verbatim = c("verbatim", "verbatim*", "Sinput", "Soutput"), verb = "\\Sexpr") deparseLatex(x, dropBraces = FALSE) latexToUtf8(x)
text |
A character vector containing LaTeX source code. |
filename |
A filename to use in syntax error messages. |
verbose |
If |
verbatim |
A character vector containing the names of LaTeX environments holding verbatim text. |
verb |
A character vector containing LaTeX macros that should be assumed to hold verbatim text. |
x |
A |
dropBraces |
Drop unnecessary braces when displaying a |
The parser does not recognize all legal LaTeX code, only relatively simple examples. It does not associate arguments with macros, that needs to be done after parsing, with knowledge of the definitions of each macro. The main intention for this function is to process simple LaTeX code used in bibliographic references, not fully general LaTeX documents.
Verbose text is allowed in three forms: the \verb macro (with
single character delimiters), environments whose names are listed
in the verbatim argument, and other macros (with
brace delimiters) whose names are listed in the verb
argument.
The parseLatex() function returns a recursive object of class
"LaTeX". Each of the entries in this object will have a
"latex_tag" attribute identifying its syntactic role.
The deparseLatex() function returns a single element character
vector, possibly containing embedded newlines.
The latexToUtf8() function returns a modified version of the
"LaTeX" object that was passed to it.
Duncan Murdoch
latex <- parseLatex("fran\\c{c}ais") deparseLatex(latexToUtf8(latex))latex <- parseLatex("fran\\c{c}ais") deparseLatex(latexToUtf8(latex))
Generate a single-page HTML reference manual from the Rd sources contained in an installed or source R package.
pkg2HTML(package, dir = NULL, lib.loc = NULL, outputEncoding = "UTF-8", stylesheet = file.path(R.home("doc"), "html", "R-nav.css"), hooks = list(pkg_href = function(pkg) sprintf("%s.html", pkg)), texmath = getOption("help.htmlmath"), prism = TRUE, out = NULL, toc_entry = c("title", "name"), ..., Rhtml = FALSE, mathjax_config = file.path(R.home("doc"), "html", "mathjax-config.js"), include_description = TRUE)pkg2HTML(package, dir = NULL, lib.loc = NULL, outputEncoding = "UTF-8", stylesheet = file.path(R.home("doc"), "html", "R-nav.css"), hooks = list(pkg_href = function(pkg) sprintf("%s.html", pkg)), texmath = getOption("help.htmlmath"), prism = TRUE, out = NULL, toc_entry = c("title", "name"), ..., Rhtml = FALSE, mathjax_config = file.path(R.home("doc"), "html", "mathjax-config.js"), include_description = TRUE)
package |
a character string, typically giving the name of an installed package. Can also be a file path or URL pointing to a source tarball (this feature is experimental). |
dir |
character string giving the path to a directory containing an installed or source package. |
lib.loc |
a character vector describing the location of R
library trees to search through, or |
outputEncoding |
character string; see |
stylesheet |
character string giving URL containing CSS style information. |
hooks |
A list of functions controlling details of
output. Currently the only component used is |
texmath |
character string controlling math rendering library to
be used, either |
prism |
logical flag controlling code highlighting, as described in
|
out |
a filename or connection object to which to write the
output. By default ( |
toc_entry |
Determines whether the entry for a help page in the table of contents is the name of the help page or its title. |
... |
additional arguments, passed on to
|
Rhtml |
logical: whether the output is intended to be a Rhtml
file that can be processed using knitr. If |
mathjax_config |
character string giving path of file containing
configuration instructions for mathjax. Relevant only if
|
include_description |
logical flag indicating whether the output
should begin with the contents of the |
The pkg2HTML function is intended to produce a single-page HTML
reference manual for a given package, with links to other
packages. The URLs of links to external packages are controlled by the
provided hooks.
The handling of \Sexpr-s are necessarily incomplete, but can be
controlled to some extent by specifying the stages
argument. Best results are likely for installed packages.
The name of the output file (invisibly).
Deepayan Sarkar
pkg2HTML("tools", out = tempfile(fileext = ".html")) |> browseURL()pkg2HTML("tools", out = tempfile(fileext = ".html")) |> browseURL()
pskill sends a signal to a process, usually to terminate it.
pskill(pid, signal = SIGTERM) SIGHUP SIGINT SIGQUIT SIGKILL SIGTERM SIGSTOP SIGTSTP SIGCHLD SIGUSR1 SIGUSR2pskill(pid, signal = SIGTERM) SIGHUP SIGINT SIGQUIT SIGKILL SIGTERM SIGSTOP SIGTSTP SIGCHLD SIGUSR1 SIGUSR2
pid |
positive integers: one or more process IDs as returned by
|
signal |
integer, most often one of the symbolic constants. |
Signals are a C99 concept, but only a small number are required to be
supported (of those listed, only SIGINT and SIGTERM).
They are much more widely used on POSIX operating systems (which
should define all of those listed here), which also support a
kill system call to send a signal to a process, most often to
terminate it. Function pskill provides a wrapper: it silently
ignores invalid values of its arguments, including zero or negative
pids.
In normal use on a Unix-alike, Ctrl-C sends SIGINT,
Ctrl-\ sends SIGQUIT and Ctrl-Z sends
SIGTSTP: that and SIGSTOP suspend a process which can be
resumed by SIGCONT.
The signals are small integers, but the actual numeric values are not
standardized (and most do differ between OSes). The SIG*
objects contain the appropriate integer values for the current platform
(or NA_INTEGER_ if the signal is not defined).
Only SIGINT and SIGTERM will be defined on Windows, and
pskill will always use the Windows system call
TerminateProcess.
A logical vector of the same length as pid,
TRUE (for success) or FALSE, invisibly.
Package parallel has several means to launch child processes which record the process IDs.
## Not run: pskill(c(237, 245), SIGKILL) ## End(Not run)## Not run: pskill(c(237, 245), SIGKILL) ## End(Not run)
Get or set the ‘niceness’ of the current process, or one or more other processes.
psnice(pid = Sys.getpid(), value = NA_integer_)psnice(pid = Sys.getpid(), value = NA_integer_)
pid |
positive integers: the process IDs of one of more processes: defaults to the R session process. |
value |
The niceness to be set, or |
POSIX operating systems have a concept of process priorities, usually
from 0 to 39 (or 40) with 20 being a normal priority and (somewhat
confusingly) larger numeric values denoting lower priority. To add to
the confusion, there is a ‘niceness’ value, the amount by which
the priority numerically exceeds 20 (which can be negative).
Processes with high niceness will receive less CPU time than those
with normal priority. On some OSes, processes with niceness
+19 are only run when the system would otherwise be idle.
On many OSes utilities such as top report the priority and
not the niceness. Niceness is used by the utility
‘/usr/bin/renice’: ‘/usr/bin/nice’ (and
/usr/bin/renice -n) specifies an increment in niceness.
Only privileged users (usually super-users) can lower the niceness.
Windows has a slightly different concept of ‘priority
classes’. We have mapped the idle priority to niceness 19,
‘below normal’ to 15, normal to 0, ‘above
normal’ to -5 and ‘realtime’ to -10. Unlike
Unix-alikes, a non-privileged user can increase the priority class on
Windows (but using ‘realtime’ is inadvisable).
An integer vector of previous niceness values,
NA if unknown for any reason.
Various functions in package parallel create child processes whose priority may need to be changed.
Functions for performing various quality control (QC) checks on R code and documentation, notably on R packages.
checkDocFiles (package, dir, lib.loc = NULL, chkInternal = NULL) checkDocStyle (package, dir, lib.loc = NULL) checkReplaceFuns(package, dir, lib.loc = NULL) checkS3methods (package, dir, lib.loc = NULL) checkRdContents (package, dir, lib.loc = NULL, chkInternal = NULL) langElts nonS3methods(package)checkDocFiles (package, dir, lib.loc = NULL, chkInternal = NULL) checkDocStyle (package, dir, lib.loc = NULL) checkReplaceFuns(package, dir, lib.loc = NULL) checkS3methods (package, dir, lib.loc = NULL) checkRdContents (package, dir, lib.loc = NULL, chkInternal = NULL) langElts nonS3methods(package)
package |
a character string naming an installed package. |
dir |
a character string specifying the path to a package's root
source (or installed in some cases) directory. This should contain the subdirectories ‘R’
(for R code) and ‘man’ with R documentation sources (in Rd
format). Only used if |
lib.loc |
a character vector of directory names of R libraries,
or |
chkInternal |
logical indicating if Rd files marked with keyword
|
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.
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 (if given an installed package) in
the package imports, and finally the namespace environment for the
base package.
checkRdContents() checks Rd content, e.g., whether arguments of
functions in the usage section have non empty descriptions.
nonS3methods(package) returns a character vector with
the names of the functions in package which ‘look’ like
S3 methods, but are not. Using package = NULL returns all
known examples.
langElts is a character vector of names of “language
elements” of R. These are implemented as “very primitive”
functions (no argument list; print()ing as
.Primitive("name")).
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.
The functions return objects of class the same as the respective
function names containing the information about problems detected.
There are print methods for nicely displaying the information
contained in such objects.
R CMD InterfaceInvoke R CMD tools from within R.
Rcmd(args, ...)Rcmd(args, ...)
args |
a character vector of arguments to |
... |
arguments to be passed to |
Provides a portable convenience interface to the R CMD
mechanism by invoking the corresponding system commands (using the
version of R currently used) via system2.
See section “Value” in system2.
These functions take the output of parse_Rd(), an
Rd object, and produce a help page from it. As they are mainly
intended for internal use, their interfaces are subject to change.
Rd2HTML(Rd, out = "", package = "", defines = .Platform$OS.type, Links = NULL, Links2 = NULL, stages = "render", outputEncoding = "UTF-8", dynamic = FALSE, no_links = FALSE, fragment = FALSE, stylesheet = if (dynamic) "/doc/html/R.css" else "R.css", texmath = getOption("help.htmlmath"), concordance = FALSE, standalone = TRUE, hooks = list(), toc = isTRUE(getOption("help.htmltoc")), Rhtml = FALSE, ...) Rd2txt(Rd, out = "", package = "", defines = .Platform$OS.type, stages = "render", outputEncoding = "", fragment = FALSE, options, ...) Rd2latex(Rd, out = "", defines = .Platform$OS.type, stages = "render", outputEncoding = "UTF-8", fragment = FALSE, ..., writeEncoding = TRUE, concordance = FALSE) Rd2ex(Rd, out = "", defines = .Platform$OS.type, stages = "render", outputEncoding = "UTF-8", commentDontrun = TRUE, commentDonttest = FALSE, ...)Rd2HTML(Rd, out = "", package = "", defines = .Platform$OS.type, Links = NULL, Links2 = NULL, stages = "render", outputEncoding = "UTF-8", dynamic = FALSE, no_links = FALSE, fragment = FALSE, stylesheet = if (dynamic) "/doc/html/R.css" else "R.css", texmath = getOption("help.htmlmath"), concordance = FALSE, standalone = TRUE, hooks = list(), toc = isTRUE(getOption("help.htmltoc")), Rhtml = FALSE, ...) Rd2txt(Rd, out = "", package = "", defines = .Platform$OS.type, stages = "render", outputEncoding = "", fragment = FALSE, options, ...) Rd2latex(Rd, out = "", defines = .Platform$OS.type, stages = "render", outputEncoding = "UTF-8", fragment = FALSE, ..., writeEncoding = TRUE, concordance = FALSE) Rd2ex(Rd, out = "", defines = .Platform$OS.type, stages = "render", outputEncoding = "UTF-8", commentDontrun = TRUE, commentDonttest = FALSE, ...)
Rd |
a filename or |
out |
a filename or connection object to which to write the
output. The default |
package |
the package to list in the output. |
defines |
string(s) to use in |
stages |
at which stage ( |
outputEncoding |
see the ‘Encodings’ section below. |
dynamic |
logical: set links for render-time resolution by dynamic help system. |
no_links |
logical: suppress hyperlinks to other help topics.
Used by |
fragment |
logical: should fragments of Rd files be accepted? See the notes below. |
stylesheet |
character: a URL for a stylesheet to be used in the header of the HTML output page. |
texmath |
character: controls how mathematics in |
concordance |
Whether concordance data should be embedded in the output file and attached to the return value. |
standalone |
logical: whether the output is intended to be a
standalone HTML file. If |
hooks |
A list of functions controlling details of
output. Currently the only component used is |
toc |
logical: whether the HTML output should include a table
of contents. Ignored unless |
Rhtml |
logical: whether the output is intended to be a Rhtml
file that can be processed using knitr. If |
Links, Links2
|
|
options |
An optional named list of options to pass to
|
... |
additional parameters to pass to |
writeEncoding |
should |
commentDontrun |
should |
commentDonttest |
should |
These functions convert help documents: Rd2HTML produces HTML,
Rd2txt produces plain text, Rd2latex produces LaTeX.
Rd2ex extracts the examples in the format used by
example and R utilities.
Each of the functions accepts a filename for an Rd file, and
will use parse_Rd to parse it before applying the
conversions or checks.
The difference between arguments Link and Link2 is that
links are looked in them in turn, so lazy-evaluation can be used to
only do a second-level search for links if required.
Before R 3.6.0, the default for Rd2latex was outputEncoding = "ASCII",
including using the second option of \enc markup, because LaTeX
versions did not provide enough coverage of UTF-8 glyphs for a long time.
Rd2txt will format text paragraphs to a width determined by
width, with appropriate margins. The default is to be close to
the rendering in versions of R < 2.10.0.
Rd2txt will use directional quotes (see sQuote)
if option "useFancyQuotes" is true (usually the default,
see sQuote) and
the current encoding is UTF-8.
Various aspects of formatting by Rd2txt are controlled by the
options argument, documented with the Rd2txt_options
function. Changes made using options are temporary, those
made with Rd2txt_options are persistent.
When fragment = TRUE, the Rd file will be rendered
with no processing of \Sexpr elements or conditional defines
using #ifdef or #ifndef. Normally a fragment represents
text within a section, but if the first element of the fragment
is a section macro, the whole fragment will be rendered as
a series of sections, without the usual sorting.
These functions are executed mainly for the side effect of writing the
converted help page. Their value is the name of the output file
(invisibly). For Rd2latex, the output name is given an
attribute "latexEncoding" giving the encoding of the file in a
form suitable for use with the LaTeX ‘inputenc’ package. For
Rd2HTML with standalone = FALSE, an attribute
"info" gives supplementary information such as the contents of
the name and title fields. This is currently
experimental, and the details are subject to change.
For Rd2HTML and Rd2latex with concordance = TRUE, a
"concordance" attribute is added, containing an
Rconcordance object.
Rd files are normally intended to be rendered on a wide variety of systems, so care must be taken in the encoding of non-ASCII characters. In general, any such encoding should be declared using the ‘encoding’ section for there to be any hope of correct rendering.
For output, the outputEncoding argument will be used:
outputEncoding = "" will choose the native encoding for the
current system.
If the text cannot be converted to the outputEncoding, byte
substitution will be used (see iconv): Rd2latex
and Rd2ex give a warning.
The \Sexpr macro includes
R code that will be executed at one of three times: build time
(when a package's source code is built into a tarball),
install time (when the package is installed or
built into a binary package), and render time (when the man
page is converted to a readable format).
For example, this man page was:
built on 2024-06-16 at 05:27:52,
installed on 2024-06-16 at 05:27:52, and
rendered on 2024-09-28 at 14:34:40.
Duncan Murdoch, Brian Ripley
https://developer.r-project.org/parseRd.pdf
parse_Rd, checkRd,
findHTMLlinks, Rd2txt_options,
matchConcordance.
## Simulate rendering of this (installed) page in HTML and text format Rd <- Rd_db("tools")[["Rd2HTML.Rd"]] outfile <- tempfile(fileext = ".html") Rd2HTML(Rd, outfile, package = "tools") |> browseURL() outfile <- tempfile(fileext = ".txt") Rd2txt(Rd, outfile, package = "tools") |> file.show()## Simulate rendering of this (installed) page in HTML and text format Rd <- Rd_db("tools")[["Rd2HTML.Rd"]] outfile <- tempfile(fileext = ".html") Rd2HTML(Rd, outfile, package = "tools") |> browseURL() outfile <- tempfile(fileext = ".txt") Rd2txt(Rd, outfile, package = "tools") |> file.show()
This function sets various options for displaying text help.
Rd2txt_options(...)Rd2txt_options(...)
... |
A list containing named options, or options passed as individual named arguments. See below for currently defined ones. |
This function persistently sets various formatting options for the
Rd2txt function which is used in displaying text format
help. Currently defined options are:
(default 80): The width of the output page.
(default 10): The minimum indent to use in a list.
(default 4): The extra indent to use in each level of nested lists.
(default 5): The indent level for a section.
(default 2): The extra indentation for each nested section level.
(default "* ", with the asterisk replaced by a
Unicode bullet in UTF-8 and most Windows locales):
The symbol to use as a bullet in itemized lists.
: A function to format item numbers in enumerated lists.
(default FALSE): Whether to show URLs when
expanding \href tags.
(default TRUE): Whether to render
\code and similar with single quotes.
(default TRUE): Whether to render
section titles with underlines (via backspacing).
If called with no arguments, returns all option settings in a list. Otherwise, it changes the named settings and invisibly returns their previous values.
Duncan Murdoch
saveOpts <- Rd2txt_options() saveOpts Rd2txt_options(minIndent = 4) Rd2txt_options()[["minIndent"]] Rd2txt_options(saveOpts) stopifnot(identical(Rd2txt_options(), saveOpts))saveOpts <- Rd2txt_options() saveOpts Rd2txt_options(minIndent = 4) Rd2txt_options()[["minIndent"]] Rd2txt_options(saveOpts) stopifnot(identical(Rd2txt_options(), saveOpts))
Given two R output files, compute differences ignoring headers, footers and some other differences.
Rdiff(from, to, useDiff = FALSE, forEx = FALSE, nullPointers = TRUE, Log = FALSE)Rdiff(from, to, useDiff = FALSE, forEx = FALSE, nullPointers = TRUE, Log = FALSE)
from, to
|
filepaths to be compared |
useDiff |
should |
forEx |
logical: extra pruning for ‘-Ex.Rout’ files to exclude headers and footers of examples, code and results for "--timings", etc. |
nullPointers |
logical: should the displayed addresses of
pointers be set to |
Log |
logical: should the returned value include a log of differences found? |
The R startup banner and any timing information from R CMD
BATCH are removed from both files, together with lines about
loading packages. UTF-8 fancy quotes (see sQuote) and
on Windows, Windows' so-called ‘smart quotes’, are mapped to
a simple quote. Addresses of environments, compiled bytecode and
other exotic types expressed as hex addresses
(e.g., ‘<environment: 0x12345678>’) are mapped to
0x00000000. The files are then compared line-by-line. If
there are the same number of lines and useDiff is false, a
simple diff -b -like display of differences is printed
(which ignores trailing spaces and differences in numbers of
consecutive spaces), otherwise diff -bw is called on the
edited files. (This tries to ignore all differences in whitespace:
note that flag -w is not required by POSIX but is supported
by GNU, Solaris and FreeBSD versions – macOS uses an old GNU version.)
There is limited support for comparing PDF files produced by
pdf(compress = FALSE), mainly for use in make check
– this requires a diff command and useDiff = TRUE.
Mainly for use in examples and tests, text from marker ‘> ## IGNORE_RDIFF_BEGIN’ up to (but not including) ‘> ## IGNORE_RDIFF_END’ is ignored.
If Log is true, a list with components status (see
below) and out, a character vector of descriptions of
differences, possibly of zero length.
Otherwise, a status indicator (invisibly), 0L if and only if no
differences were found.
The shell script run as R CMD Rdiff, which uses
useDiff = TRUE.
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).
Rdindex(RdFiles, outFile = "", type = NULL, width = 0.9 * getOption("width"), indent = NULL)Rdindex(RdFiles, outFile = "", type = NULL, width = 0.9 * getOption("width"), indent = NULL)
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. |
type |
a character string giving the documentation type of the Rd
files to be included in the index, or |
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 |
If a name is not a valid alias, the first alias (or the empty string if there is none) is used instead.
This function blanks out all non-text in an Rd file, for spell checking or other uses.
RdTextFilter(ifile, encoding = "unknown", keepSpacing = TRUE, drop = character(), keep = character(), macros = file.path(R.home("share"), "Rd", "macros", "system.Rd"))RdTextFilter(ifile, encoding = "unknown", keepSpacing = TRUE, drop = character(), keep = character(), macros = file.path(R.home("share"), "Rd", "macros", "system.Rd"))
ifile |
An input file specified as a filename or connection, or an |
encoding |
An encoding name to pass to |
keepSpacing |
Whether to try to leave the text in the same lines and columns as in the original file. |
drop |
Additional sections of the Rd to drop. |
keep |
Sections of the Rd file to keep. |
macros |
Macro definitions to assume when parsing. See |
This function parses the Rd file, then walks through it, element by
element. Items with tag "TEXT" are kept in the same position as
they appeared in the original file, while other parts of the file are
replaced with blanks, so a spell checker such as aspell
can check only the text and report the position in the original file.
(If keepSpacing is FALSE, blank filling will not occur,
and text will not be output in its original location.)
By default, the tags \S3method, \S4method,
\command, \docType, \email, \encoding,
\file, \keyword, \link, \linkS4class,
\method, \pkg, and \var are skipped. Additional
tags can be skipped by listing them in the drop argument;
listing tags in the keep argument will stop them from being
skipped. It is also possible to keep any of the
c("RCODE", "COMMENT", "VERB") tags, which correspond to R-like
code, comments, and verbatim text respectively, or to drop
"TEXT".
A character vector which if written to a file, one element per line, would duplicate the text elements of the original Rd file.
The filter attempts to merge text elements into single words when markup in the Rd file is used to highlight just the start of a word.
Duncan Murdoch
aspell, for which this is an acceptable filter.
Utilities for computing on the information in Rd objects.
Rd_db(package, dir, lib.loc = NULL, stages = "build")Rd_db(package, dir, lib.loc = NULL, stages = "build")
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
|
lib.loc |
a character vector of directory names of R libraries,
or |
stages |
if |
Rd_db builds a simple database of all Rd objects in a package,
as a list of the results of running parse_Rd on the Rd
source files in the package and processing platform conditionals
and some \Sexpr macros.
## Build the Rd db for the (installed) base package. db <- Rd_db("base") ## Keyword metadata per Rd object. keywords <- lapply(db, tools:::.Rd_get_metadata, "keyword") ## 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(db, tools:::.Rd_get_metadata, "concept") ## How many files already have \concept metadata? sum(sapply(concepts, length) > 0) ## How many concept entries altogether? length(unlist(concepts))## Build the Rd db for the (installed) base package. db <- Rd_db("base") ## Keyword metadata per Rd object. keywords <- lapply(db, tools:::.Rd_get_metadata, "keyword") ## 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(db, tools:::.Rd_get_metadata, "concept") ## How many files already have \concept metadata? sum(sapply(concepts, length) > 0) ## How many concept entries altogether? length(unlist(concepts))
Read item/description information from ‘00Index’-like files. Such files are description lists rendered in tabular form, and currently used for the ‘INDEX’ and ‘demo/00Index’ files of add-on packages.
read.00Index(file)read.00Index(file)
file |
the name of a file to read data values from. If the
specified file is |
A character matrix with 2 columns named "Item" and
"Description" which hold the items and descriptions.
formatDL for the inverse operation of creating a
00Index-style file from items and their descriptions.
This function prints elements of a character vector which contain non-ASCII bytes, printing such bytes as a escape like ‘<fc>’.
showNonASCII(x) showNonASCIIfile(file)showNonASCII(x) showNonASCIIfile(file)
x |
a character vector. |
file |
path to a file. |
This was originally written to help detect non-portable text in files in packages.
It prints all elements of x which contain non-ASCII characters,
preceded by the element number and with non-ASCII bytes highlighted
via iconv(sub = "byte").
However, this rendering depends on iconv(to = "ASCII")
failing to convert, and macOS 14 no longer does so reliably so for
example permille (‘\u2030’) is rendered as o/oo.
The elements of x containing non-ASCII characters will be returned
invisibly.
out <- c( "fran\xE7ais: test of showNonASCII():", "\\details{", " This is a good line", " This has an \xfcmlaut in it.", " OK again.", "}") f <- tempfile() cat(out, file = f, sep = "\n") showNonASCIIfile(f) unlink(f)out <- c( "fran\xE7ais: test of showNonASCII():", "\\details{", " This is a good line", " This has an \xfcmlaut in it.", " OK again.", "}") f <- tempfile() cat(out, file = f, sep = "\n") showNonASCIIfile(f) unlink(f)
This function starts the internal help server, so that HTML help pages are rendered when requested.
startDynamicHelp(start = TRUE)startDynamicHelp(start = TRUE)
start |
logical: whether to start or shut down the dynamic help
system. If |
This function starts the internal HTTP server, which runs on the
loopback interface (‘127.0.0.1’). If options("help.ports")
is set to a vector of non-zero integer values, startDynamicHelp will try
those ports in order; otherwise, it tries up to 10 random ports to
find one not in use. It can be disabled by setting the environment
variable R_DISABLE_HTTPD to a non-empty value or options("help.ports")
to 0.
startDynamicHelp is called by functions that need to use the
server, so would rarely be called directly by a user.
Note that options(help_type = "html") must be set to actually
make use of HTML help, although it might be the default for an R
installation.
If the server cannot be started or is disabled,
help.start will be unavailable and requests for HTML
help will give text help (with a warning).
The browser in use does need to be able to connect to the loopback interface: occasionally it is set to use a proxy for HTTP on all interfaces, which will not work – the solution is to add an exception for ‘127.0.0.1’.
The chosen port number is returned invisibly (which will be 0
if the server has been stopped).
help.start and help(help_type = "html")
will attempt to start the HTTP server if required
Rd2HTML is used to render the package help pages.
This function blanks out code chunks and Noweb markup in an Sweave input file, for spell checking or other uses.
SweaveTeXFilter(ifile, encoding = "unknown")SweaveTeXFilter(ifile, encoding = "unknown")
ifile |
Input file or connection. |
encoding |
Text encoding to pass to |
This function blanks out all Noweb markup and code chunks from an Sweave input file, leaving behind the LaTeX source, so that a LaTeX-aware spelling checker can check it and report errors in their original locations.
A character vector which if written to a file, one element per line, would duplicate the text elements of the original Sweave input file.
Duncan Murdoch
aspell, for which this is used with filter = "Sweave".
These functions allow an installed package to be tested, or all base and recommended packages.
testInstalledPackage(pkg, lib.loc = NULL, outDir = ".", types = c("examples", "tests", "vignettes"), srcdir = NULL, Ropts = "", ...) testInstalledPackages(outDir = ".", errorsAreFatal = TRUE, scope = c("both", "base", "recommended"), types = c("examples", "tests", "vignettes"), srcdir = NULL, Ropts = "", ...) testInstalledBasic(scope = c("basic", "devel", "both", "internet", "all"), outDir = file.path(R.home(), "tests"), testSrcdir = getTestSrcdir(outDir)) standard_package_names()testInstalledPackage(pkg, lib.loc = NULL, outDir = ".", types = c("examples", "tests", "vignettes"), srcdir = NULL, Ropts = "", ...) testInstalledPackages(outDir = ".", errorsAreFatal = TRUE, scope = c("both", "base", "recommended"), types = c("examples", "tests", "vignettes"), srcdir = NULL, Ropts = "", ...) testInstalledBasic(scope = c("basic", "devel", "both", "internet", "all"), outDir = file.path(R.home(), "tests"), testSrcdir = getTestSrcdir(outDir)) standard_package_names()
pkg |
name of an installed package. |
lib.loc |
library path(s) in which to look for the package. See
|
outDir |
the directory into which to write the output files: this
should already exist. The default, |
types |
type(s) of tests to be done. |
srcdir |
Optional directory to look for |
Ropts |
Additional options such as -d valgrind to be
passed to |
errorsAreFatal |
logical: should testing terminate at the first error? |
scope |
a string indicating which set(s) should be tested.
|
... |
additional arguments use when preparing the files to be
run, e.g. |
testSrcdir |
optional directory where the test R scripts are found. |
The testInstalledPackage{s}() tests depend on having the package
example files installed (which is the default).
If package-specific tests are found in a
‘tests’ directory they can be tested: these are not
installed by default, but will be if
R CMD INSTALL --install-tests was used. Finally, the R
code in any vignettes can be extracted and tested.
The package-specific tests are run in a ‘pkg-tests’ subdirectory of
‘outDir’, and leave their output there.
testInstalledBasic runs the basic tests, if installed or inside
testSrcdir. This
should be run with LC_COLLATE=C set: the function tries to set
this but it may not work on all OSes. For non-English locales it may
be desirable to set environment variables LANGUAGE to ‘en’
and LC_TIME to ‘C’ to reduce the number of differences from
reference results.
Except on Windows, if the environment variable TEST_MC_CORES is
set to an integer greater than one, testInstalledPackages will
run the package tests in parallel using its value as the maximum
number of parallel processes.
The package-specific tests for the base and recommended packages are
not normally installed, but make install-tests is provided
to do so (as well as the basic tests).
Invisibly 0L for success, 1L for failure.
standard_package_names() returns a list with
components named
base |
a |
recommended |
a |
str(stPkgs <- standard_package_names()) ## consistency of packageDescription and standard_package_names : (pNms <- unlist(stPkgs, FALSE)) (prio <- sapply(as.vector(pNms), packageDescription, fields = "Priority")) stopifnot(identical(unname(prio), sub("[0-9]+$", '', names(pNms))))str(stPkgs <- standard_package_names()) ## consistency of packageDescription and standard_package_names : (pNms <- unlist(stPkgs, FALSE)) (prio <- sapply(as.vector(pNms), packageDescription, fields = "Priority")) stopifnot(identical(unname(prio), sub("[0-9]+$", '', names(pNms))))
Run latex/pdflatex, makeindex and bibtex
until all cross-references are resolved to create a DVI or a PDF file.
texi2dvi(file, pdf = FALSE, clean = FALSE, quiet = TRUE, texi2dvi = getOption("texi2dvi"), texinputs = NULL, index = TRUE) texi2pdf(file, clean = FALSE, quiet = TRUE, texi2dvi = getOption("texi2dvi"), texinputs = NULL, index = TRUE)texi2dvi(file, pdf = FALSE, clean = FALSE, quiet = TRUE, texi2dvi = getOption("texi2dvi"), texinputs = NULL, index = TRUE) texi2pdf(file, clean = FALSE, quiet = TRUE, texi2dvi = getOption("texi2dvi"), texinputs = NULL, index = TRUE)
file |
character string. Name of the LaTeX source file. |
pdf |
logical. If |
clean |
logical. If |
quiet |
logical. No output unless an error occurs. |
texi2dvi |
character string (or |
texinputs |
|
index |
logical: should indices be prepared? |
texi2pdf is a wrapper for the common case of
texi2dvi(pdf = TRUE).
Despite the name, this is used in R to compile LaTeX files,
specifically those generated from vignettes and by the
Rd2pdf script (used for package reference manuals). It
ensures that the ‘R_HOME/share/texmf’ directory is
in the TEXINPUTS path, so R style files such as ‘Sweave.sty’
and ‘Rd.sty’ will be found. The TeX search path used is first the
existing TEXINPUTS setting (or the current directory if unset),
then elements of argument texinputs, then
‘R_HOME/share/texmf’ and finally the default path.
Analogous changes are made to BIBINPUTS and BSTINPUTS
settings.
The default option for texi2dvi is set from environment variable
R_TEXI2DVICMD, and the default for that is set from environment
variable TEXI2DVI or if that is unset, from a value chosen when
R is configured.
A shell script texi2dvi is part of GNU's texinfo.
Several issues have been seen with released versions, so if yours does
not work correctly try R_TEXI2DVICMD=emulation.
Occasionally indices contain special characters which cause indexing
to fail (particularly when using the ‘hyperref’ LaTeX package)
even on valid input. The argument index = FALSE is provided to
allow package manuals to be made when this happens: it uses emulation.
Invisible NULL. Used for the side effect of creating a DVI or
PDF file in the current working directory (and maybe other files,
especially if clean = FALSE).
There are various versions of the texi2dvi script on
Unix-alikes and quite a number of bugs have been seen, some of which
this R wrapper works around.
One that was present with texi2dvi version 4.8 (as
supplied by macOS) is that it will not work correctly for paths which
contain spaces, nor if the absolute path to a file would contain
spaces.
The three possible approaches all have their quirks. For example the
Unix-alike texi2dvi script removes ancillary files that already
exist but the other two approaches do not (and may get confused by
such files).
Where supported (texi2dvi 5.0 and later;
texify.exe from MiKTeX), option --max-iterations=20
is used to avoid infinite retries.
The emulation mode supports quiet = TRUE from R 3.2.3 only.
Currently clean = TRUE only cleans up in this mode if the
conversion was successful—this gives users a chance to examine log
files in the event of error.
All the approaches should respect the values of environment variables LATEX, PDFLATEX, MAKEINDEX and BIBTEX for the full paths to the corresponding commands.
Originally Achim Zeileis but largely rewritten by R-core.
This generic function generates a complete HTML page from an object.
toHTML(x, ...) ## S3 method for class 'packageIQR' toHTML(x, ...) ## S3 method for class 'news_db' toHTML(x, ...)toHTML(x, ...) ## S3 method for class 'packageIQR' toHTML(x, ...) ## S3 method for class 'news_db' toHTML(x, ...)
x |
An object to display. |
... |
Optional parameters for methods; the |
A character vector to display the object x. The "packageIQR" method
is designed to display lists in the R help system.
cat(toHTML(demo(package = "base")), sep = "\n")cat(toHTML(demo(package = "base")), sep = "\n")
(Currently none)
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.
Methods for this function render their associated classes as a fragment of Rd code, which can then be rendered into text, HTML, or LaTeX.
toRd(obj, ...) ## S3 method for class 'bibentry' toRd(obj, style = NULL, ...)toRd(obj, ...) ## S3 method for class 'bibentry' toRd(obj, style = NULL, ...)
obj |
The object to be rendered. |
style |
The style to be used in converting a |
... |
Additional arguments used by methods. |
See bibstyle for a discussion of styles. The default style = NULL value
gives the default style.
Returns a character vector containing a fragment of Rd code that could
be parsed and rendered. The default method converts obj to mode character,
then escapes any Rd markup within it. The bibentry method converts an
object of that class to markup appropriate for use in a bibliography.
Convert a character vector to title case, especially package titles.
toTitleCase(text)toTitleCase(text)
text |
a character vector. |
This is intended for English text only.
No definition of‘title case’ is universally accepted: all agree that ‘principal’ words are capitalized and common words like ‘for’ are not, but not which words fall into each category.
Generally words in all capitals are left alone: this implementation knows about conventional mixed-case words such as ‘LaTeX’ and ‘OpenBUGS’ and a few technical terms which are not usually capitalized such as ‘jar’ and ‘xls’. However, unknown technical terms will be capitalized unless they are single words enclosed in single quotes: names of packages and libraries should be quoted in titles.
A character vector of the same length as text, without names.
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.
undoc(package, dir, lib.loc = NULL)undoc(package, dir, lib.loc = NULL)
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 |
This function is useful for package maintainers mostly. In principle, all user-level R objects should be documented.
The base package is special as it contains the primitives and
these do not have definitions available at code level. We provide
equivalent closures in environments .ArgsEnv and
.GenericArgsEnv in the base package that are used
for various purposes: undoc("base") checks that all the
primitives that are not language constructs are prototyped in those
environments and no others are.
An object of class "undoc" which is a list of character vectors
containing the names of the undocumented objects split according to
documentation type.
There is a print method for nicely displaying the information
contained in such objects.
undoc("tools") # Undocumented objects in 'tools'undoc("tools") # Undocumented objects in 'tools'
Update an existing repository by reading the PACKAGES
file, retaining entries which are still valid, removing entries which
are no longer valid, and only processing built package tarballs which do not
match existing entries.
update_PACKAGES can be much faster than
write_PACKAGES for small-moderate changes to large
repository indexes, particularly in non-strict mode (see Details).
update_PACKAGES(dir = ".", fields = NULL, type = c("source", "mac.binary", "win.binary"), verbose.level = as.integer(dryrun), latestOnly = TRUE, addFiles = FALSE, rds_compress = "xz", strict = TRUE, dryrun = FALSE)update_PACKAGES(dir = ".", fields = NULL, type = c("source", "mac.binary", "win.binary"), verbose.level = as.integer(dryrun), latestOnly = TRUE, addFiles = FALSE, rds_compress = "xz", strict = TRUE, dryrun = FALSE)
dir |
see |
fields |
see |
type |
see |
verbose.level |
one of {0, 1, 2}, the level of informative messages
displayed throughout the process. Defaults to 0 if
|
latestOnly |
see |
addFiles |
see |
rds_compress |
see |
strict |
logical. Should “strict mode” be used when checking
existing |
dryrun |
logical. Should the updates to existing |
Throughout this section, package tarball is defined to mean any
archive file in dir whose name can be interpreted as
‘package_version.ext’ – with ext the appropriate
extension for built packages of type type – (or that is pointed
to by the File field of an existing PACKAGES entry).
Novel package tarballs are those which do not match an existing
PACKAGES file entry.
update_PACKAGES calls directly down to
write_PACKAGES with a warning (and thus all package tarballs
will be processed), if any of the following conditions hold:
type is "win.binary" and strict is
TRUE (no MD5 checksums are included in win.binary PACKAGES files)
No PACKAGES file exists under dir
A PACKAGES file exists under dir but is empty
fields is not NULL and one or more specified fields
are not present in the existing PACKAGES file
update_PACKAGES avoids (re)processing package tarballs in cases where
a PACKAGES file entry already exists and appears to remain valid. The
logic for detecting still-valid entries is as follows:
Any package tarball which was last modified more recently than the
existing PACKAGES file is considered novel; existing
PACKAGES entries appearing to correspond to such tarballs are
always considered stale and replaced by newly generated ones.
Similarly, all PACKAGES entries that do not correspond to any
package tarball found in dir are considered invalid and are
excluded from the resulting updated PACKAGES files.
When strict is TRUE, PACKAGES entries that match a package
tarball (by package name and version) are confirmed via MD5 checksum;
only those that pass are retained as valid. All novel package tarballs
are fully processed by the standard machinery underlying
write_PACKAGES and the resulting entries are
added. Finally, if latestOnly is TRUE, package-version
pruning is performed across the entries.
When strict is FALSE, package tarballs are assumed to encode
correct metadata in their filenames. PACKAGES entries which
appear to match a package tarball are retained as valid (No MD5 checksum
testing occurs). If latestOnly is TRUE, package-version
pruning is performed across the full set of retained entries and novel package
tarballs before the processing of the novel tarballs, at
significant computational and time savings in some
situations. After the optional pruning, any relevant novel package
tarballs are processed via the standard machinery and added to the
set of retained entries.
In both cases, after the above process concludes, entries are sorted
alphabetically by the string concatenation of Package and
Version. This should match the entry order write_PACKAGES
outputs.
The fields within the entries are ordered as follows: canonical fields -
i.e., those appearing as columns when available.packages is
called on a CRAN mirror - appear first in their canonical order,
followed by any non-canonical fields.
After entry and field reordering, the final database of PACKAGES
entries is written to all three PACKAGES files, overwriting the
existing versions.
When verbose.level is 0, no extra messages are displayed
to the user. When it is 1, detailed information about what is
happening is conveyed via messages, but underlying machinery from
write_PACKAGES is invoked with verbose = FALSE.
Behavior when verbose.level is 2 is identical to
verbose.level 1 with the exception that underlying
machinery from write_PACKAGES is invoked with
verbose = TRUE, which will individually list every processed
tarball.
While both strict and non-strict modes can offer speedups when updating small percentages of large repositories, non-strict mode is much faster and is recommended in situations where the assumption it makes about tarballs' filenames encoding accurate information is safe.
Users should expect significantly smaller speedups over
write_PACKAGES in the type == "win.binary" case on at
least some operating systems. This is due to write_PACKAGES being
significantly faster in this context, rather than update_PACKAGES
being slower.
Gabriel Becker (adapted from previous, related work by him in the switchr package which is copyright Genentech, Inc.)
## Not run: write_PACKAGES("c:/myFolder/myRepository") # on Windows update_PACKAGES("c:/myFolder/myRepository") # on Windows write_PACKAGES("/pub/RWin/bin/windows/contrib/2.9", type = "win.binary") # on Linux update_PACKAGES("/pub/RWin/bin/windows/contrib/2.9", type = "win.binary") # on Linux ## End(Not run)## Not run: write_PACKAGES("c:/myFolder/myRepository") # on Windows update_PACKAGES("c:/myFolder/myRepository") # on Windows write_PACKAGES("/pub/RWin/bin/windows/contrib/2.9", type = "win.binary") # on Linux update_PACKAGES("/pub/RWin/bin/windows/contrib/2.9", type = "win.binary") # on Linux ## End(Not run)
Prepare the ‘po’ directory of a package and optionally compile and install the translations.
update_pkg_po(pkgdir, pkg = NULL, version = NULL, pot_make = TRUE, mo_make = TRUE, verbose = getOption("verbose"), mergeOpts = "", copyright, bugs)update_pkg_po(pkgdir, pkg = NULL, version = NULL, pot_make = TRUE, mo_make = TRUE, verbose = getOption("verbose"), mergeOpts = "", copyright, bugs)
pkgdir |
The path to the package directory. |
pkg |
The package name: if |
version |
The package version: if |
pot_make, mo_make
|
|
verbose |
|
mergeOpts |
a string, by default empty, of space-separated options to
|
copyright, bugs
|
optional character strings for the ‘Copyright’ and ‘Report-Msgid-Bugs-To’ details in the template files. |
This performs a series of steps to prepare or update messages in the package.
If the package sources do not already have a ‘po’ directory, one is created.
xgettext2pot is called to create/update a file
‘po/R-pkgname.pot’ containing the translatable messages
in the package.
All existing files in directory po with names
‘R-lang.po’ are updated from ‘R-pkgname.pot’,
checkPoFile is called on the updated file, and if
there are no problems the file is compiled and installed under
‘inst/po’.
In a UTF-8 locale, a ‘translation’ ‘[email protected]’ is created with UTF-8 directional quotes, compiled and installed under ‘inst/po’.
The remaining steps are done only if file
‘po/pkgname.pot’ already exists. The
‘src/*.{c,cc,cpp,m,mm}’ files in the package are examined to
create a file ‘po/pkgname.pot’ containing the translatable
messages in the C/C++ files. If there is a src/windows
directory, files within it are also examined.
All existing files in directory po with names
‘lang.po’ are updated from ‘pkgname.pot’,
checkPoFile is called on the updated file, and if
there are no problems the file is compiled and
installed under ‘inst/po’.
In a UTF-8 locale, a ‘translation’ ‘[email protected]’ is created with UTF-8 directional quotes, compiled and installed under ‘inst/po’.
Note that C/C++ messages are not automatically prepared for translation as they need to be explicitly marked for translation in the source files. Once that has been done, create an empty file ‘po/pkgname.pot’ in the package sources and run this function again.
pkg = "base" is special (and for use by R developers only):
the C files are not in the package directory but in the main sources.
This function requires the following tools from the GNU
gettext-tools: xgettext, msgmerge,
msgfmt, msginit and msgconv. These are
part of most Linux distributions and easily compiled from the sources
on Unix-alikes (including macOS). Pre-compiled versions for
Windows are available in
https://www.stats.ox.ac.uk/pub/Rtools/goodies/gettext-tools.zip.
It will probably not work correctly for en@quot translations
except in a UTF-8 locale, so these are skipped elsewhere.
Directories for storing R-related user-specific data, configuration and cache files.
R_user_dir(package, which = c("data", "config", "cache"))R_user_dir(package, which = c("data", "config", "cache"))
package |
a character string giving the name of an R package |
which |
a character string indicating the kind of file(s) of interest. Can be abbreviated. |
For desktop environments using X Windows, the freedesktop.org project (formerly X Desktop Group, XDG) developed the XDG Base Directory Specification (https://specifications.freedesktop.org/basedir-spec) for standardizing the location where certain files should be placed. CRAN package rappdirs provides these general locations with appropriate values for all platforms for which R is available.
R_user_dir specializes the general mechanism to R package
specific locations for user files, by providing package specific
subdirectories inside a ‘R’ subdirectory inside the “base”
directories appropriate for user-specific data, configuration and
cache files (see the examples), with the intent that packages will not
interfere if they work within their respective subdirectories.
The locations of these base directories can be customized via the specific environment variables R_USER_DATA_DIR, R_USER_CONFIG_DIR and R_USER_CACHE_DIR. If these are not set, the general XDG-style environment variables XDG_DATA_HOME, XDG_CONFIG_HOME and XDG_CACHE_HOME are used if set, and otherwise, defaults appropriate for the R platform in use are employed.
R_user_dir("FOO", "cache") ## Create one, platform agnostically, must work if <normal> : (Rdb <- R_user_dir("base")) if(newD <- !dir.exists(Rdb)) # should work user specifically: newD <- dir.create(Rdb, recursive=TRUE) dir(Rdb) # typically empty if(newD) unlink(Rdb) # cleaning up list.files(R_user_dir("grid"), full.names = TRUE)R_user_dir("FOO", "cache") ## Create one, platform agnostically, must work if <normal> : (Rdb <- R_user_dir("base")) if(newD <- !dir.exists(Rdb)) # should work user specifically: newD <- dir.create(Rdb, recursive=TRUE) dir(Rdb) # typically empty if(newD) unlink(Rdb) # cleaning up list.files(R_user_dir("grid"), full.names = TRUE)
Vignettes are normally processed by Sweave, but package
writers may choose to use a different engine (e.g., one provided by the
knitr, noweb or R.rsp packages). This function
is used by those packages to register their engines, and internally by
R to retrieve them.
vignetteEngine(name, weave, tangle, pattern = NULL, package = NULL, aspell = list())vignetteEngine(name, weave, tangle, pattern = NULL, package = NULL, aspell = list())
name |
the name of the engine. |
weave |
a function to convert vignette source files to PDF/HTML or intermediate LaTeX output. |
tangle |
a function to convert vignette source files to R code. |
pattern |
a regular expression pattern for the filenames handled
by this engine, or |
package |
the package registering the engine. By default, this
is the package calling |
aspell |
a list with element names |
If weave is missing, vignetteEngine will return the currently
registered engine matching name and package.
If weave is NULL, the specified engine will be deleted.
Other settings define a new engine. The weave and tangle
functions must be defined with argument lists compatible with
function(file, ...). Currently the ... arguments may
include logical argument quiet and character argument
encoding; others may be added in future. These are described in
the documentation for Sweave and Stangle.
The weave and tangle functions should return the
filename of the output file that has been produced. Currently the
weave function, when operating on a file named
‘<name><pattern>’ must produce a file named
‘<name>[.](tex|pdf|html)’.
The ‘.tex’ files will be processed by pdflatex to
produce ‘.pdf’ output for display to the user; the others will be
displayed as produced. The tangle function must produce a file
named ‘<name>[.][rRsS]’ containing the executable R code from
the vignette. The tangle function may support a
split = TRUE argument, and then it should produce files named
‘<name>.*[.][rRsS]’.
The pattern argument gives a regular expression to match the
extensions of files which are to be processed as vignette input files.
If set to NULL, the default pattern "[.][RrSs](nw|tex)$"
is used.
If the engine is being deleted, NULL. Otherwise a list
containing components
name |
The name of the engine |
package |
The name of its package |
pattern |
The pattern for vignette input files |
weave |
The weave function |
tangle |
The tangle function |
Duncan Murdoch and Henrik Bengtsson.
Sweave and the ‘Writing R Extensions’ manual.
str(vignetteEngine("Sweave"))str(vignetteEngine("Sweave"))
Extract metadata from a vignette source file.
vignetteInfo(file)vignetteInfo(file)
file |
file name of the vignette. |
A list with the following
character components:
file |
the |
title |
the vignette title from ‘\VignetteIndexEntry’, possibly an empty string. |
depends |
a vector of package dependencies from ‘\VignetteDepends’, possibly of length 0. |
keywords |
a vector of keywords from ‘\VignetteKeyword’, possibly of length 0. |
engine |
the |
package_dependencies for recursive dependencies.
gridEx <- system.file("doc", "grid.Rnw", package = "grid") vi <- vignetteInfo(gridEx) str(vi)gridEx <- system.file("doc", "grid.Rnw", package = "grid") vi <- vignetteInfo(gridEx) str(vi)
Generate ‘PACKAGES’, ‘PACKAGES.gz’ and ‘PACKAGES.rds’ files for a repository of source or Mac/Windows binary packages.
write_PACKAGES(dir = ".", fields = NULL, type = c("source", "mac.binary", "win.binary"), verbose = FALSE, unpacked = FALSE, subdirs = FALSE, latestOnly = TRUE, addFiles = FALSE, rds_compress = "xz", validate = FALSE)write_PACKAGES(dir = ".", fields = NULL, type = c("source", "mac.binary", "win.binary"), verbose = FALSE, unpacked = FALSE, subdirs = FALSE, latestOnly = TRUE, addFiles = FALSE, rds_compress = "xz", validate = FALSE)
dir |
Character vector describing the location of the repository (directory including source or binary packages) to generate the ‘PACKAGES’, ‘PACKAGES.gz’ and ‘PACKAGES.rds’ files from and write them to. |
fields |
a character vector giving the fields to be used in the
‘PACKAGES’, ‘PACKAGES.gz’ and ‘PACKAGES.rds’ files in
addition to the default ones, or The default corresponds to
the fields needed by |
type |
Type of packages: currently source ‘.tar.{gz,bz2,xz}’ archives,
and macOS or Windows binary (‘.tgz’ or ‘.zip’,
respectively) packages are supported. Defaults to
|
verbose |
logical. Should packages be listed as they are processed? |
unpacked |
a logical indicating whether the package contents are available in unpacked form or not (default). |
subdirs |
either logical (to indicate if subdirectories should be included, recursively) or a character vector of names of subdirectories to include (which are not recursed). |
latestOnly |
logical: if multiple versions of a package are available should only the latest version be included? |
addFiles |
logical: should the filenames be included as field ‘File’ in the ‘PACKAGES’ file. |
rds_compress |
The type of compression to be used for
‘PACKAGES.rds’: see |
validate |
a logical indicating whether ‘DESCRIPTION’ files should be validated, and the corresponding packages skipped in case this finds problems. |
write_PACKAGES scans the named directory for R packages,
extracts information from each package's ‘DESCRIPTION’ file, and
writes this information into the ‘PACKAGES’, ‘PACKAGES.gz’
and ‘PACKAGES.rds’ files, where the first two represent the
information in DCF format, and the third serializes it via
saveRDS.
Including non-latest versions of packages is only useful if they have
less constraining version requirements, so for example
latestOnly = FALSE could be used for a source repository when
‘foo_1.0’ depends on ‘R >= 2.15.0’ but ‘foo_0.9’ is
available which depends on ‘R >= 2.11.0’.
Support for repositories with subdirectories and hence for
subdirs != FALSE depends on recording a "Path" field in
the ‘PACKAGES’ files.
Support for more general file names (e.g., other types of compression)
via a "File" field in the ‘PACKAGES’ files can be
used by download.packages. If the file names are not of
the standard form, use addFiles = TRUE.
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 files
‘PACKAGES’, ‘PACKAGES.gz’ and ‘PACKAGES.rds’ files from
this information.
For a remote repository there is a tradeoff between download speed and
time spent by available.packages processing the
downloaded file(s). For large repositories it is likely to be
beneficial to use rds_compress = "xz".
Invisibly returns the number of packages described in the resulting
‘PACKAGES’, ‘PACKAGES.gz’ and ‘PACKAGES.rds’ files. If
0, no packages were found and no files were written.
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.
Uwe Ligges and R-core.
See read.dcf and write.dcf for reading
‘DESCRIPTION’ files and writing the ‘PACKAGES’ and
‘PACKAGES.gz’ files. See update_PACKAGES for
efficiently updating existing ‘PACKAGES’ and ‘PACKAGES.gz’
files.
## Not run: write_PACKAGES("c:/myFolder/myRepository") # on Windows write_PACKAGES("/pub/RWin/bin/windows/contrib/2.9", type = "win.binary") # on Linux ## End(Not run)## Not run: write_PACKAGES("c:/myFolder/myRepository") # on Windows write_PACKAGES("/pub/RWin/bin/windows/contrib/2.9", type = "win.binary") # on Linux ## End(Not run)
For each file in the ‘R’ directory (including system-specific subdirectories) of a source package, extract the unique arguments passed to these “message generating” calls;
xgettext():to stop, warning, message,
packageStartupMessage, gettext and
gettextf,
xngettext():to ngettext.
xgettext2pot() calls both xgettext() and then xngettext().
xgettext(dir, verbose = FALSE, asCall = TRUE) xngettext(dir, verbose = FALSE) xgettext2pot(dir, potFile, name = "R", version, bugs)xgettext(dir, verbose = FALSE, asCall = TRUE) xngettext(dir, verbose = FALSE) xgettext2pot(dir, potFile, name = "R", version, bugs)
dir |
the directory of a source package, i.e., with a ‘./R’ sub directory. |
verbose |
logical: should each file be listed as it is processed? |
asCall |
logical: if |
potFile |
name of |
name, version, bugs
|
as recorded in the template file:
|
Leading and trailing white space (space, tab and linefeed
(aka newline, i.e., ‘\n’)) is removed
for all the calls extracted by xgettext(), see
‘Description’ above,
as it is by the internal code that passes strings for translation.
We look to see if the matched functions were called with
domain = NA. If so, when asCall is true, the whole call
is omitted. Note that a call might contain a nested call
to gettext (or warning, etc.) whose strings would be visible
if asCall is false.
xgettext2pot calls xgettext and then xngettext,
and writes a PO template file (to potFile) 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, but msgfmt complains if there is duplication between
the sets.).
If applied to the base package, this also looks in the ‘.R’ files in ‘R_HOME/share/R’.
For xgettext, a list of objects of class "xgettext"
(which has a print method), one per source file that
contains potentially translatable strings.
For xngettext, a list of objects of class "xngettext",
which are themselves lists of length-2 character vectors.
update_pkg_po() which calls xgettext2pot().
## Not run: ## in a source-directory build (not typical!) of R; ## otherwise, download and unpack the R sources, and replace ## R.home() by "<my_path_to_source_R>" : xgettext(file.path(R.home(), "src", "library", "splines")) ## End(Not run) ## Create source package-like <tmp>/R/foo.R and get text from it: tmpPkg <- tempdir() tmpRDir <- file.path(tmpPkg, "R") dir.create(tmpRDir, showWarnings = FALSE) fnChar <- paste(sep = "\n", "foo <- function(x) {", " if (x < -1) stop('too small')", " # messages unduplicated (not so for ngettext)", " if (x < -.5) stop('too small')", " if (x < 0) {", " warning(", " 'sqrt(x) is', sqrt(as.complex(x)),", " ', which may be too small'", " )", " }", " # calls with domain=NA are skipped", " if (x == 0) cat(gettext('x is 0!\n', domain=NA))", " # gettext strings may be ignored due to 'outer' domain=NA", " if (x > 10) warning('x is ', gettextf('%.2f', x), domain=NA)", " # using a custom condition class", " if (x == 42)", " stop(errorCondition(gettext('needs Deep Thought'), class='myError'))", " x", "}") writeLines(fnChar, con = file.path(tmpRDir, "foo.R")) ## [[1]] : suppressing (tmpfile) name to make example Rdiff-able xgettext(tmpPkg, asCall=TRUE )[[1]] # default; shows calls xgettext(tmpPkg, asCall=FALSE)[[1]] # doesn't ; but then ' %.2f ' unlink(tmpRDir, recursive=TRUE)## Not run: ## in a source-directory build (not typical!) of R; ## otherwise, download and unpack the R sources, and replace ## R.home() by "<my_path_to_source_R>" : xgettext(file.path(R.home(), "src", "library", "splines")) ## End(Not run) ## Create source package-like <tmp>/R/foo.R and get text from it: tmpPkg <- tempdir() tmpRDir <- file.path(tmpPkg, "R") dir.create(tmpRDir, showWarnings = FALSE) fnChar <- paste(sep = "\n", "foo <- function(x) {", " if (x < -1) stop('too small')", " # messages unduplicated (not so for ngettext)", " if (x < -.5) stop('too small')", " if (x < 0) {", " warning(", " 'sqrt(x) is', sqrt(as.complex(x)),", " ', which may be too small'", " )", " }", " # calls with domain=NA are skipped", " if (x == 0) cat(gettext('x is 0!\n', domain=NA))", " # gettext strings may be ignored due to 'outer' domain=NA", " if (x > 10) warning('x is ', gettextf('%.2f', x), domain=NA)", " # using a custom condition class", " if (x == 42)", " stop(errorCondition(gettext('needs Deep Thought'), class='myError'))", " x", "}") writeLines(fnChar, con = file.path(tmpRDir, "foo.R")) ## [[1]] : suppressing (tmpfile) name to make example Rdiff-able xgettext(tmpPkg, asCall=TRUE )[[1]] # default; shows calls xgettext(tmpPkg, asCall=FALSE)[[1]] # doesn't ; but then ' %.2f ' unlink(tmpRDir, recursive=TRUE)