File specifications define the file packing scope in the source R package. We will discuss how to write file specifications and use them to create a file collection.
In pkglite
, a file specification
defines the parameters to locate the files matching specific criteria
under an R package. One can use file_spec()
to create a
file specification.
For example, to match the .R
files under the
R/
folder, use
fs <- file_spec(
"R/",
pattern = "\\.R$", format = "text",
recursive = FALSE, ignore_case = TRUE, all_files = FALSE
)
fs
#> -- File specification ----------------------------------------------------------
#> - Relative path: "R/"
#> - Pattern: "\\.R$"
#> - Format: "text"
#> - Recursive: FALSE
#> - Ignore case: TRUE
#> - All files: FALSE
A file collection is generated by evaluating file
specification(s) under a package directory. It contains the metadata of
the list of matching files. Use collate()
to create a file
collection:
We have included a few file specifications to cover the common file
structures in an R package. See ?file_spec_templates
for
details. We will use some of them to demonstrate how to combine them to
cover an entire package.
To generate a file collection that includes a core set of files under the package root, use
pkg %>% collate(file_root_core())
#> -- File collection -------------------------------------------------------------
#> -- Package: pkg1 ---------------------------------------------------------------
#> path_rel format
#> 1 DESCRIPTION text
#> 2 NAMESPACE text
#> 3 NEWS.md text
#> 4 README.md text
To include all files under the package root, use
pkg %>% collate(file_root_all())
#> -- File collection -------------------------------------------------------------
#> -- Package: pkg1 ---------------------------------------------------------------
#> path_rel format
#> 1 DESCRIPTION text
#> 2 NAMESPACE text
#> 3 NEWS.md text
#> 4 README.md text
We can feed one or more file specifications to
collate()
. The union of the matched files will be
returned:
pkg %>% collate(file_r(), file_man())
#> -- File collection -------------------------------------------------------------
#> -- Package: pkg1 ---------------------------------------------------------------
#> path_rel format
#> 1 R/data.R text
#> 2 R/hello.R text
#> 3 R/pkg1-package.R text
#> 4 R/sysdata.rda binary
#> 5 man/dataset.Rd text
#> 6 man/hello_world.Rd text
#> 7 man/pkg1-package.Rd text
#> 8 man/figures/logo.png binary
If file specification did not match any files, an empty file collection is returned:
pkg %>% collate(file_src())
#> -- File collection -------------------------------------------------------------
#> -- Package: pkg1 ---------------------------------------------------------------
#> [1] path_rel format
#> <0 rows> (or 0-length row.names)
Naturally, this would not add additional files to the collection:
pkg %>% collate(file_r(), file_man(), file_src())
#> -- File collection -------------------------------------------------------------
#> -- Package: pkg1 ---------------------------------------------------------------
#> path_rel format
#> 1 R/data.R text
#> 2 R/hello.R text
#> 3 R/pkg1-package.R text
#> 4 R/sysdata.rda binary
#> 5 man/dataset.Rd text
#> 6 man/hello_world.Rd text
#> 7 man/pkg1-package.Rd text
#> 8 man/figures/logo.png binary
file_default()
offers a default combination of the file
specification templates.
pkg %>% collate(file_default())
#> -- File collection -------------------------------------------------------------
#> -- Package: pkg1 ---------------------------------------------------------------
#> path_rel format
#> 1 DESCRIPTION text
#> 2 NAMESPACE text
#> 3 NEWS.md text
#> 4 README.md text
#> 5 R/data.R text
#> 6 R/hello.R text
#> 7 R/pkg1-package.R text
#> 8 R/sysdata.rda binary
#> 9 man/dataset.Rd text
#> 10 man/hello_world.Rd text
#> 11 man/pkg1-package.Rd text
#> 12 man/figures/logo.png binary
#> 13 vignettes/example.bib text
#> 14 vignettes/pkg1.Rmd text
#> 15 data/dataset.rda binary
file_auto()
provides a specification that lists all
files (with an extension) under a folder recursively. It also guesses
the file format type based on the file extension. This is useful for
directories like inst/
that do not share a standard
structure or filename pattern across packages.