Generate File Specifications

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.

library("pkglite")

File specification

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

File collection

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:

pkg <- system.file("examples/pkg1/", package = "pkglite")

pkg %>% collate(fs)
#> -- File collection -------------------------------------------------------
#> -- Package: pkg1 ---------------------------------------------------------
#>           path_rel format
#> 1         R/data.R   text
#> 2        R/hello.R   text
#> 3 R/pkg1-package.R   text

File specification templates

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.

File specification usage patterns

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

Default file specification

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

Automatic file specification

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.

pkg %>% collate(file_auto("inst/"))
#> -- File collection -------------------------------------------------------
#> -- Package: pkg1 ---------------------------------------------------------
#>                   path_rel format
#> 1 inst/extdata/dataset.tsv   text