Generate File Specifications
In pkglite: Compact Package Representations

knitr::opts_chunk$set(
  comment = "#>",
  collapse = TRUE
)

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 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 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())

To include all files under the package root, use

pkg %>% collate(file_root_all())

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())

If file specification did not match any files, an empty file collection is returned:

pkg %>% collate(file_src())

Naturally, this would not add additional files to the collection:

pkg %>% collate(file_r(), file_man(), file_src())

Default file specification

file_default() offers a default combination of the file specification templates.

pkg %>% collate(file_default())

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.