---
title: "Generate File Specifications"
output:
  rmarkdown::html_vignette:
    css: "custom.css"
    toc: true
    toc_float: false
    toc_depth: 4
    number_sections: false
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{Generate File Specifications}
---

```{r, include=FALSE}
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.

```{r}
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

```{r}
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:

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

```{r}
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

```{r}
pkg %>% collate(file_root_core())
```

To include all files under the package root, use

```{r}
pkg %>% collate(file_root_all())
```

We can feed one or more file specifications to `collate()`.
The union of the matched files will be returned:

```{r}
pkg %>% collate(file_r(), file_man())
```

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

```{r}
pkg %>% collate(file_src())
```

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

```{r}
pkg %>% collate(file_r(), file_man(), file_src())
```

## Default file specification

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

```{r}
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.

```{r}
pkg %>% collate(file_auto("inst/"))
```