rprojroot

https://rprojroot.r-lib.org/
Admin
rprojroot is an R package that helps access files relative to a project root, eliminating working...
Tokens:13,851
Snippets:162
Trust Score:8.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example: Finding package root file

Source: https://rprojroot.r-lib.org/reference/find_root_file.html

Demonstrates how to find a package root file by specifying additional path components. This example is conditional and may not run directly.

```r
if (FALSE) { # \dontrun{
find_package_root_file("tests", "testthat.R")
has_file("DESCRIPTION", "^Package: ")
has_file("DESCRIPTION", "^Package: ")$make_fix_file(".")
} # }
```

--------------------------------

### Install rprojroot Package

Source: https://rprojroot.r-lib.org/index.html

Provides the command to install the rprojroot package from CRAN. This is necessary before using the package's functionalities.

```r
install.package("rprojroot")
```

--------------------------------

### Verify file existence using rprojroot

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Demonstrates how to use `find_root_file` to get a stable path and then checks if the file exists at that location. This confirms rprojroot's ability to locate files consistently.

```R
# Specify a path/to/file relative to the root
rel_path_from_root <- find_root_file("R", "rrmake.R", criterion = has_file("DESCRIPTION"))

# Find a file relative to the root
file.exists(rel_path_from_root)
```

--------------------------------

### Find Project Root with Absolute Path Input

Source: https://rprojroot.r-lib.org/index.html

Illustrates how 'find_file()' handles an absolute path as the first argument, ensuring correct project root identification even when starting from a subdirectory.

```r
setwd(file.path(pkg, "R"))
path <- is_r_package$find_file()
is_r_package$find_file(path, "tests", "testthat")
#> [1] "/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpVBhMLR/file337b29a46586/tests/testthat"
```

--------------------------------

### Get file size relative to project root

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Demonstrates how to get the size of a file located at the project root, even when the working directory is outside the project. Uses `withr::with_dir` to temporarily change the directory.

```R
withr::with_dir(
  "../..",
  file.size(F("NAMESPACE"))
)
```

--------------------------------

### List files in testthat hierarchy

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Lists all files within a 'hierarchy' subdirectory of the testthat root. This example uses two project root lookups to ensure it works in various contexts, including vignette rendering.

```R
dir(is_testthat$find_file("hierarchy", path = is_r_package$find_file()))
```

--------------------------------

### Example of using thisfile() within a conditional block

Source: https://rprojroot.r-lib.org/reference/thisfile.html

This example demonstrates how to use the thisfile() function within an R script. The condition `FALSE` prevents the code from running during standard package checks, but it shows the intended usage.

```R
if (FALSE) { # \dontrun{
thisfile()
} # }
```

--------------------------------

### Get Current Working Directory Base Name

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

This snippet shows how to get the base name of the current working directory. Useful for understanding the current context within a project.

```r
basename(getwd())
```

--------------------------------

### Find Project Root with File Pattern and Content

Source: https://rprojroot.r-lib.org/reference/find_root.html

Searches for a project root directory containing a 'DESCRIPTION' file with a package name starting with 'Package: '. This is useful for identifying the top-level directory of an R package.

```R
find_root(has_file_pattern(
  pattern = glob2rx("DESCRIPTION"),
  contents = "^Package: "
))
```

--------------------------------

### Finding Files Relative to the Project Root

Source: https://rprojroot.r-lib.org/reference/index.html

Functions to locate specific files within a project's directory structure, starting from the identified root.

```APIDOC
## find_root_file()

### Description
Finds a file path relative to the root of a directory hierarchy.

### Usage
```r
find_root_file(filename, path = ".", criterion = NULL, all = FALSE)
```

## find_rstudio_root_file()

### Description
Finds a file path relative to the root of an RStudio project.

### Usage
```r
find_rstudio_root_file(filename, path = ".", all = FALSE)
```

## find_package_root_file()

### Description
Finds a file path relative to the root of an R package.

### Usage
```r
find_package_root_file(filename, path = ".", all = FALSE)
```

## find_remake_root_file()

### Description
Finds a file path relative to the root of a remake project.

### Usage
```r
find_remake_root_file(filename, path = ".", all = FALSE)
```

## find_testthat_root_file()

### Description
Finds a file path relative to the root of a testthat project.

### Usage
```r
find_testthat_root_file(filename, path = ".", all = FALSE)
```
```

--------------------------------

### Call thisfile() to get the current script path

Source: https://rprojroot.r-lib.org/reference/thisfile.html

Use thisfile() to determine the path of the currently running script. Returns NULL if the path cannot be determined. This function is now available in the whereami package.

```R
thisfile()
```

--------------------------------

### Call thisfile_source() to get the current script path when sourced

Source: https://rprojroot.r-lib.org/reference/thisfile.html

Use thisfile_source() to determine the path of the currently running script when it has been sourced. Returns NULL if the path cannot be determined. This function is now available in the whereami package.

```R
thisfile_source()
```

--------------------------------

### find_root

Source: https://rprojroot.r-lib.org/reference/find_root.html

Searches for a directory that satisfies a given root criterion, starting from a specified path and moving up the hierarchy.

```APIDOC
## find_root

### Description
Searches for a directory that satisfies a given root criterion, starting from a specified path and moving up the hierarchy. If no root is found, an error is thrown.

### Usage
```R
find_root(criterion, path = ".")
```

### Arguments
#### criterion
- **criterion** (root_criterion) - A criterion, one of the predefined criteria or created by `root_criterion()`. Will be coerced using `as_root_criterion()`.

#### path
- **path** (character(1)) - The start directory.

### Value
The normalized path of the root as specified by the search criterion. Throws an error if no root is found.

### Details
Starting from the working directory, the `find_root()` function searches for the root. If a root is found, the `...` arguments are used to construct a path; thus, if no extra arguments are given, the root is returned. If no root is found, an error is thrown.

### Examples
```R
if (FALSE) { # \dontrun{
find_root(has_file_pattern(
  pattern = glob2rx("DESCRIPTION"),
  contents = "^Package: "
))
}
```
```

--------------------------------

### Call thisfile_rscript() to get the current script path when run with Rscript

Source: https://rprojroot.r-lib.org/reference/thisfile.html

Use thisfile_rscript() to determine the path of the currently running script when executed with Rscript. Returns NULL if the path cannot be determined. This function is now available in the whereami package.

```R
thisfile_rscript()
```

--------------------------------

### Call thisfile_r() to get the current script path when run with R --file

Source: https://rprojroot.r-lib.org/reference/thisfile.html

Use thisfile_r() to determine the path of the currently running script when executed with R --file. Returns NULL if the path cannot be determined. This function is now available in the whereami package.

```R
thisfile_r()
```

--------------------------------

### Call thisfile_knit() to get the current script path when processed by knitr

Source: https://rprojroot.r-lib.org/reference/thisfile.html

Use thisfile_knit() to determine the path of the currently running script when it has been processed by knitr. Returns NULL if the path cannot be determined. This function is now available in the whereami package.

```R
thisfile_knit()
```

--------------------------------

### Create a Demonstration Package

Source: https://rprojroot.r-lib.org/index.html

Creates a temporary R package directory for demonstration purposes using the 'usethis' package. This sets up a project structure that rprojroot can recognize.

```r
dir <- tempfile()
pkg <- usethis::create_package(dir)
#> ✔ Creating
#>   /var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpVBhMLR/file337b29a46586/.
#> ✔ Setting active project to
#>   "/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpVBhMLR/file337b29a46586".
#> ✔ Creating R/.
#> ✔ Writing DESCRIPTION.
#> Package: file337b29a46586
#> Title: What the Package Does (One Line, Title Case)
#> Version: 0.0.0.9000
#> Date: 2025-06-27
#> Authors@R (parsed):
#>     * Kirill Müller <kirill@cynkra.com> [aut, cre] (<https://orcid.org/0000-0002-1416-3412>)
#> Description: What the package does (one paragraph).
#> License: MIT
#> URL: https://github.com/krlmlr/rprojroot,
#>     https://krlmlr.github.io/rprojroot
#> BugReports: https://github.com/krlmlr/rprojroot/issues
#> Encoding: UTF-8
#> Roxygen: list(markdown = TRUE)
#> RoxygenNote: 7.3.2.9000
#> ✔ Writing NAMESPACE.
#> ✔ Setting active project to "<no active project>".

```

--------------------------------

### Load rprojroot Package

Source: https://rprojroot.r-lib.org/index.html

Loads the rprojroot package into the current R session. This is the first step before using any of its functions.

```r
library(rprojroot)
```

--------------------------------

### Access Project File from Any Directory

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Demonstrates using the 'root_file' accessor to find a project file ('DESCRIPTION') even when the current working directory is outside the project. This ensures reliable file access.

```r
withr::with_dir(
  "../..",
  readLines(root_file("DESCRIPTION"), 3)
)
```

--------------------------------

### Define and use a shorter alias for find_package_root_file

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Create a shorter alias for `find_package_root_file` to reduce typing effort when frequently accessing project files.

```R
# Use a shorter alias
file.exists(P("vignettes", "rprojroot.Rmd"))
```

--------------------------------

### Retrieve Project Root

Source: https://rprojroot.r-lib.org/index.html

Shows how to retrieve the project root directory when the current working directory is confirmed to be within the project.

```r
setwd(file.path(pkg, "R"))
is_r_package$find_file()
```

--------------------------------

### Find Project Root and List Directory Contents

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Finds the project root using a criterion that checks for a file named 'DESCRIPTION' and then lists all files and directories within that root. Requires the rprojroot library to be loaded.

```r
library(rprojroot)

# List all files and directories below the root
dir(find_root(has_file("DESCRIPTION")))
```

--------------------------------

### Test Function Output

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

This snippet demonstrates how to write a test case using the testthat package to verify the output of a function.

```R
testthat::test_that(
  "my_fun() returns expected output",
  testthat::expect_equal(
    my_fun_run,
    expected_output
  )
)
```

--------------------------------

### Load test data using custom path helper

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Demonstrates how to use the custom `get_my_path` function to locate and load saved R data files for testing, ensuring the correct paths are used regardless of the current working directory.

```R
## Find the correct path with your custom rprojroot helper function
path_to_my_args_file <- get_my_path("my_args.Rdata")

## Load the input arguments
load(file = path_to_my_args_file)

## Run the function with those arguments
my_fun_run <- do.call(my_fun, my_args)

## Load the historical expectation with the helper
load(file = get_my_path("expected_output.Rdata"))
```

--------------------------------

### Finding and Fixing Files with Root Criteria

Source: https://rprojroot.r-lib.org/reference/rprojroot-package.html

Demonstrates how to use a predefined root criterion to find a specific file and create a function to fix file paths relative to the project root. This is useful for ensuring consistent file access across different environments.

```r
if (FALSE) { # \dontrun{
is_r_package$find_file("NAMESPACE")
root_fun <- is_r_package$make_fix_file()
root_fun("NAMESPACE")
} # }
```

--------------------------------

### Usage of find_root_file and variants

Source: https://rprojroot.r-lib.org/reference/find_root_file.html

These functions are wrappers around `find_root()` that append arbitrary path components to the root using `base::file.path()`.

```r
find_root_file(..., criterion, path = ".")

find_rstudio_root_file(..., path = ".")

find_package_root_file(..., path = ".")

find_remake_root_file(..., path = ".")

find_testthat_root_file(..., path = ".")
```

--------------------------------

### Define and Use an R Package Root Criterion

Source: https://rprojroot.r-lib.org/index.html

Demonstrates how to use the 'is_r_package' criterion to find the root of an R package. It shows how 'find_file()' works relative to the working directory and how it handles subdirectories.

```r
setwd(pkg)
is_r_package
#> Root criterion: contains a file "DESCRIPTION" with contents matching "^Package: "
is_r_package$find_file()
#> [1] "/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpVBhMLR/file337b29a46586"
is_r_package$find_file("tests", "testthat")
#> [1] "/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpVBhMLR/file337b29a46586/tests/testthat"
```

```r
setwd(file.path(pkg, "R"))
is_r_package$find_file()
#> [1] "/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpVBhMLR/file337b29a46586"
is_r_package$find_file("tests", "testthat")
#> [1] "/private/var/folders/dj/yhk9rkx97wn_ykqtnmk18xvc0000gn/T/RtmpVBhMLR/file337b29a46586/tests/testthat"
```

--------------------------------

### Accessing root criterion methods

Source: https://rprojroot.r-lib.org/reference/root_criterion.html

Demonstrates how to access the `find_file` and `make_fix_file` methods of a root criterion object. These are typically used within `<dontrun>` blocks.

```R
is_r_package$find_file
is_r_package$make_fix_file(".")
```

--------------------------------

### Define relative path from project root

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Defines a path to a file relative to the project's root directory. This path is stable regardless of the current working directory.

```R
rel_path_from_root <- "R/rrmake.R"
rel_path_from_root <- file.path("R", "rrmake.R") ## identical
```

--------------------------------

### Define custom path helper for test data

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Creates a utility function `get_my_path` to find files within a specific 'testing_data' subdirectory relative to the testthat project root. This simplifies accessing saved data files for testing.

```R
## saved to tests/testthat/helper.R
get_my_path <- function(file_name) {
  rprojroot::find_testthat_root_file(
    "testing_data", filename
  )
}
```

--------------------------------

### Create a criterion to check for a file with specific content

Source: https://rprojroot.r-lib.org/reference/root_criterion.html

The `is_r_package` criterion demonstrates checking for a file ('DESCRIPTION') with specific content using a regular expression.

```R
is_r_package
```

--------------------------------

### Deprecated Functions: as.root_criterion and is.root_criterion

Source: https://rprojroot.r-lib.org/reference/deprecated.html

The functions `as.root_criterion` and `is.root_criterion` are deprecated. Please use `as_root_criterion()` and `is_root_criterion()` respectively.

```APIDOC
## Usage
__```
as.root_criterion(...)

is.root_criterion(...)
```__
```

--------------------------------

### Find File with Absolute or Relative Path

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Safely finds a file relative to the project root, handling cases where the provided path might be absolute or relative. This allows for more robust path manipulation.

```r
path <- root$find_file()
readLines(root$find_file(path, "DESCRIPTION"), 3)
```

--------------------------------

### Define custom root criterion: has_file with content match

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Define a root criterion based on the presence and content of a file. This allows for more specific project identification.

```R
is_projecttemplate_project <- has_file("config/global.dcf", "^version: ")
is_projecttemplate_project
```

--------------------------------

### Deprecated as.root_criterion and is.root_criterion

Source: https://rprojroot.r-lib.org/reference/deprecated.html

These functions are deprecated. Use `as_root_criterion()` and `is_root_criterion()` instead.

```R
as.root_criterion(...)
```

```R
is.root_criterion(...)
```

--------------------------------

### Create Fixed File Accessor using thisfile()

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Constructs a file accessor function based on the directory of the currently executing script or vignette. This is a fallback method when other root identification methods are not suitable.

```r
root_file <- root$make_fix_file(dirname(thisfile()))
```

--------------------------------

### Combine root criteria using the OR operator

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Combine multiple root criteria using the '|' operator to define a project root that satisfies any of the specified conditions.

```R
is_r_package | is_rstudio_project
```

--------------------------------

### Create a Fixed File Accessor Function

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Constructs a function that can find a specific file relative to the project root. This function is useful for consistently accessing project files.

```r
root_file <- root$make_fix_file()
```

--------------------------------

### Create a fixed root function

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Define a function that computes file paths relative to the project root at creation time using `$make_fix_file()`. This is useful for consistently referencing files within a project.

```R
# Define a function that computes file paths below the current root
F <- is_r_package$make_fix_file()
F
```

```R
# Show contents of the NAMESPACE file in our project
readLines(F("NAMESPACE"))
```

--------------------------------

### Predefined Root Criteria

Source: https://rprojroot.r-lib.org/reference/rprojroot-package.html

The package provides several predefined criteria to identify the root of a project. These criteria can be used to locate files relative to the project root.

```APIDOC
## Predefined Root Criteria

### Description
These are predefined criteria objects that can be used to identify the root of a project. They are accessible as elements of the `criteria` object.

### Usage
Access a criterion using `criteria$criterion_name`.

### Examples
```R
# Accessing the 'is_r_package' criterion
is_r_package <- criteria$is_r_package

# Using the criterion to find a file
is_r_package$find_file("NAMESPACE")

# Creating a function to fix a file path relative to the project root
root_fun <- is_r_package$make_fix_file()
root_fun("NAMESPACE")
```

### Available Criteria:
- **`is_rstudio_project`**: Root criterion: contains a file matching '[.]Rproj$' with contents matching '^Version: ' in the first line.
- **`is_vscode_project`**: Root criterion: contains a file '.vscode/settings.json'.
- **`is_r_package`**: Root criterion: contains a file 'DESCRIPTION' with contents matching '^Package: '.
- **`is_remake_project`**: Root criterion: contains a file 'remake.yml'.
- **`is_pkgdown_project`**: Root criterion: one of contains a file '_pkgdown.yml', '_pkgdown.yaml', 'pkgdown/_pkgdown.yml', 'pkgdown/_pkgdown.yaml', 'inst/_pkgdown.yml', or 'inst/_pkgdown.yaml'.
- **`is_renv_project`**: Root criterion: contains a file 'renv.lock' with contents matching '"Packages":\s*\{'.
- **`is_projectile_project`**: Root criterion: contains a file '.projectile'.
- **`is_quarto_project`**: Root criterion: contains a file '_quarto.yml'.
- **`is_git_root`**: Root criterion: one of contains a directory '.git' or a file '.git' with contents matching '^gitdir: '.
- **`is_svn_root`**: Root criterion: contains a directory '.svn'.
- **`is_vcs_root`**: Root criterion: one of contains a directory '.git', a file '.git' with contents matching '^gitdir: ', or a directory '.svn'.
- **`is_testthat`**: Root criterion: directory name is "testthat" (also look in subdirectories: `tests/testthat`, `testthat`).
- **`from_wd`**: Root criterion: from current working directory.
```

--------------------------------

### Define a custom root criterion

Source: https://rprojroot.r-lib.org/reference/root_criterion.html

Create a custom root criterion by providing a test function and a description. The test function takes a path and returns TRUE if it's a project root.

```R
root_criterion(function(path) file.exists(file.path(path, "somefile")), "has somefile")
```

--------------------------------

### Find file relative to project root using a criterion

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Finds a file relative to the project root by specifying the path components and a criterion to identify the root. This is the recommended method for stable paths.

```R
# Specify a path/to/file relative to the root
rel_path_from_root <- find_root_file("R", "rrmake.R", criterion = has_file("DESCRIPTION"))
```

--------------------------------

### Use find_package_root_file shortcut

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Utilize the `find_package_root_file` shortcut to easily locate files within an R package project structure. This function is a shortcut for `find_root_file(..., criterion = is_r_package)`.

```R
# Print first lines of the source for this document
head(readLines(find_package_root_file("vignettes", "rprojroot.Rmd")))
```

--------------------------------

### Predefined Root Criteria in rprojroot

Source: https://rprojroot.r-lib.org/reference/rprojroot-package.html

This snippet displays the available predefined root criteria objects. These objects can be used to identify the root directory of different types of projects.

```r
criteria
#> $is_rstudio_project
#> Root criterion: contains a file matching '[.]Rproj$' with contents matching '^Version: ' in the first line
#> 
#> $is_vscode_project
#> Root criterion: contains a file '.vscode/settings.json'
#> 
#> $is_r_package
#> Root criterion: contains a file 'DESCRIPTION' with contents matching '^Package: '
#> 
#> $is_remake_project
#> Root criterion: contains a file 'remake.yml'
#> 
#> $is_pkgdown_project
#> Root criterion: one of
#> - contains a file '_pkgdown.yml'
#> - contains a file '_pkgdown.yaml'
#> - contains a file 'pkgdown/_pkgdown.yml'
#> - contains a file 'pkgdown/_pkgdown.yaml'
#> - contains a file 'inst/_pkgdown.yml'
#> - contains a file 'inst/_pkgdown.yaml'
#> 
#> $is_renv_project
#> Root criterion: contains a file 'renv.lock' with contents matching '"Packages":\s*\{" 
#> 
#> $is_projectile_project
#> Root criterion: contains a file '.projectile'
#> 
#> $is_quarto_project
#> Root criterion: contains a file '_quarto.yml'
#> 
#> $is_git_root
#> Root criterion: one of
#> - contains a directory '.git'
#> - contains a file '.git' with contents matching '^gitdir: '
#> 
#> $is_svn_root
#> Root criterion: contains a directory '.svn'
#> 
#> $is_vcs_root
#> Root criterion: one of
#> - contains a directory '.git'
#> - contains a file '.git' with contents matching '^gitdir: '
#> - contains a directory '.svn'
#> 
#> $is_testthat
#> Root criterion: directory name is "testthat" (also look in subdirectories: `tests/testthat`, `testthat`)
#> 
#> $from_wd
#> Root criterion: from current working directory
#> 
#> attr(,"class")
#> [1] "root_criteria"
```

--------------------------------

### find_root_file

Source: https://rprojroot.r-lib.org/reference/find_root_file.html

A wrapper around find_root() that appends arbitrary path components to the root using base::file.path().

```APIDOC
## find_root_file

### Description
Finds a file relative to the project root, appending additional path components.

### Arguments
- `...` (character): Further path components passed to `file.path()`. All arguments must be the same length or length one.
- `criterion` (`root_criterion`): A criterion for finding the root, which will be coerced using `as_root_criterion()`.
- `path` (character(1)): The starting directory for the search.

### Value
The normalized path of the root with additional path components appended. Throws an error if no root is found.

### Details
If the first path component in `...` is an absolute path, `criterion` and `path` are ignored, and `...` is forwarded to `file.path()`.

### See also
`find_root()`, `utils::glob2rx()`, `base::file.path()`

### Examples
```R
if (FALSE) { # \dontrun{
find_package_root_file("tests", "testthat.R")
}
```
```

--------------------------------

### Define relative path from tests/testthat

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Defines a relative path to a file from the 'tests/testthat' directory. This path is specific to the current working directory and differs from paths defined in other directories.

```R
rel_path_from_testthat <- "../../R/rrmake.R"
```

--------------------------------

### Create Fixed File Accessor with Absolute Path

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Constructs a file accessor function using a known absolute path within the project. This is useful when the project root cannot be determined automatically but an absolute path is known.

```r
root_file <- root$make_fix_file("C:\\Users\\User Name\\...")
```

--------------------------------

### Finding the Root of a Directory Hierarchy

Source: https://rprojroot.r-lib.org/reference/index.html

These functions help in identifying the root directory of a project based on various heuristics.

```APIDOC
## find_root()

### Description
Finds the root of a directory hierarchy.

### Usage
```r
find_root(path = ".", criterion = NULL)
```

## get_root_desc()

### Description
Retrieves a description of the root directory.

### Usage
```r
get_root_desc(path = ".", criterion = NULL)
```
```

--------------------------------

### Find File Relative to Project Root

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Locates a file relative to the project root, even when the current working directory is a subdirectory. Assumes the current working directory is below the project root.

```r
readLines(root$find_file("DESCRIPTION"), 3)
```

--------------------------------

### Coerce string to a root criterion

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Shows how a character string can be automatically coerced into a `has_file` root criterion, simplifying the process of defining criteria.

```R
as_root_criterion("DESCRIPTION")
```

--------------------------------

### Define Project Root for R Package

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Assigns a function to 'root' that identifies the project root based on R package conventions. This function can then be used to find files within the project.

```r
root <- rprojroot::is_r_package
```

--------------------------------

### Prespecified Criteria for Root Identification

Source: https://rprojroot.r-lib.org/reference/index.html

A collection of predefined criteria that can be used to identify project roots.

```APIDOC
## criteria

### Description
Represents prespecified criteria for identifying project roots.

## is_rstudio_project

### Description
Criterion to check if the current directory is an RStudio project.

## is_vscode_project

### Description
Criterion to check if the current directory is a VS Code project.

## is_r_package

### Description
Criterion to check if the current directory is an R package.

## is_remake_project

### Description
Criterion to check if the current directory is a remake project.

## is_drake_project

### Description
Criterion to check if the current directory is a drake project.

## is_targets_project

### Description
Criterion to check if the current directory is a targets project.

## is_pkgdown_project

### Description
Criterion to check if the current directory is a pkgdown project.

## is_renv_project

### Description
Criterion to check if the current directory is an renv project.

## is_projectile_project

### Description
Criterion to check if the current directory is a projectile project.

## is_quarto_project

### Description
Criterion to check if the current directory is a Quarto project.

## is_git_root

### Description
Criterion to check if the current directory is the root of a Git repository.

## is_svn_root

### Description
Criterion to check if the current directory is the root of an SVN repository.

## is_vcs_root

### Description
Criterion to check if the current directory is the root of any version control system.

## is_testthat

### Description
Criterion to check if the current directory is a testthat project.

## from_wd

### Description
Criterion based on the current working directory.

```

--------------------------------

### Use a custom criterion to find the root directory

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Access the `find_file` method associated with a custom criterion to locate the root directory based on that criterion. This can result in an error if the criterion is not met.

```R
# Use the has_license criterion to find the root
R <- has_license$find_file
R
```

```R
# Our package does not have a LICENSE file, trying to find the root results in an error
R()
```

--------------------------------

### Create a criterion to check for a specific file

Source: https://rprojroot.r-lib.org/reference/root_criterion.html

Use `has_file` to create a root criterion that checks for the existence of a specific file. This is a common way to identify R package roots.

```R
has_file("DESCRIPTION")
```

--------------------------------

### thisfile()

Source: https://rprojroot.r-lib.org/reference/thisfile.html

Attempts to determine the path of the currently running script using various heuristics. It works when the script is sourced, processed by knitr, or run with Rscript or the --file parameter.

```APIDOC
## Function: thisfile()

### Description
Determines the path of the currently running script by applying heuristics.

### Usage
```R
thisfile()
```

### Value
The path of the currently running script, or NULL if it cannot be determined.

### Details
This function works if the script was `source`d, processed with `knitr`, or run with `Rscript` or using the `--file` parameter to the `R` executable. For code run with `Rscript`, the exact value of the parameter passed to `Rscript` is returned.

### Example
```R
if (FALSE) { # \dontrun{
thisfile()
}
```
```

--------------------------------

### has_file

Source: https://rprojroot.r-lib.org/reference/root_criterion.html

Creates a root criterion that checks for the existence of a specific file.

```APIDOC
## has_file(filepath, contents = NULL, n = -1L, fixed = FALSE)

### Description
Constructs a criterion that checks for the existence of a specific file, optionally with specific contents. The file can be in a subdirectory of the root.

### Arguments
* `filepath` (`character(1)`): File path (can contain directories).
* `contents` (`character(1)`, optional): If `NULL` (the default), file contents are not checked. Otherwise, `contents` is a regular expression (if `fixed` is `FALSE`) or a search string (if `fixed` is `TRUE`), and file contents are checked matching lines.
* `n` (`integerish(1)`): Maximum number of lines to read to check file contents. Defaults to -1 (all lines).
* `fixed` (`logical(1)`): If `FALSE` (default), `contents` is treated as a regular expression. If `TRUE`, `contents` is treated as a fixed string.

### Value
A `root_criterion` object.
```

--------------------------------

### get_root_desc

Source: https://rprojroot.r-lib.org/reference/find_root.html

Returns the description of the criterion used for identifying a root path.

```APIDOC
## get_root_desc

### Description
Returns the description of the criterion for a root path. This is especially useful for composite root criteria created with `|.root_criterion()`.

### Usage
```R
get_root_desc(criterion, path)
```

### Arguments
#### criterion
- **criterion** (root_criterion) - A criterion, one of the predefined criteria or created by `root_criterion()`. Will be coerced using `as_root_criterion()`.

#### path
- **path** (character(1)) - The start directory.

### Value
The description of the root criterion.
```

--------------------------------

### Combining Root Criteria with |

Source: https://rprojroot.r-lib.org/reference/root_criterion.html

Combines two root criteria into a single criterion that matches if either of the original criteria match.

```APIDOC
## x | y

### Description
Combines two root criteria using the `|` operator. The resulting criterion is a composite criterion that requires either of the original criteria (`x` or `y`) to match.

### Arguments
* `x` (`object`): The left-hand side root criterion.
* `y` (`object`): The right-hand side root criterion.

### Value
A composite `root_criterion` object.
```

--------------------------------

### Identify testthat project root criterion

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Shows the 'testthat' root criterion, which identifies directories named 'testthat' or 'tests/testthat'. This is useful for locating files within test suites.

```R
is_testthat
```

--------------------------------

### find_package_root_file

Source: https://rprojroot.r-lib.org/reference/find_root_file.html

Finds a file relative to the package root.

```APIDOC
## find_package_root_file

### Description
Finds a file relative to the package root, appending additional path components.

### Arguments
- `...` (character): Further path components passed to `file.path()`.
- `path` (character(1)): The starting directory for the search.

### Value
The normalized path of the package root with additional path components appended.
```

--------------------------------

### as_root_criterion

Source: https://rprojroot.r-lib.org/reference/root_criterion.html

Converts an object to a root criterion.

```APIDOC
## as_root_criterion(x)

### Description
Converts an object to a `root_criterion`. Accepts objects of class `root_criterion` directly, and character values which are converted using `has_file`.

### Arguments
* `x` (`object`): The object to convert. Can be a `root_criterion` or a `character`.

### Value
A `root_criterion` object.
```

--------------------------------

### Checking if a Directory is a Project Root

Source: https://rprojroot.r-lib.org/reference/index.html

Functions to determine if a given directory meets the criteria of a project root.

```APIDOC
## root_criterion()

### Description
Creates a root criterion object.

### Usage
```r
root_criterion(path = ".", criterion = NULL)
```

## is_root_criterion()

### Description
Checks if a directory is a project root based on a criterion.

### Usage
```r
is_root_criterion(path = ".", criterion = NULL)
```

## as_root_criterion()

### Description
Converts a path to a root criterion.

### Usage
```r
as_root_criterion(path = ".")
```

## `|`(_<root_criterion>_)

### Description
Combines root criteria using logical OR.

### Usage
```r
`<root_criterion>` | `<root_criterion>`
```

## has_file()

### Description
Creates a criterion that checks for the presence of a specific file.

### Usage
```r
has_file(filename)
```

## has_dir()

### Description
Creates a criterion that checks for the presence of a specific directory.

### Usage
```r
has_dir(dirname)
```

## has_file_pattern()

### Description
Creates a criterion that checks for files matching a pattern.

### Usage
```r
has_file_pattern(pattern)
```

## has_basename()

### Description
Creates a criterion that checks for a specific basename.

### Usage
```r
has_basename(basename)
```
```

--------------------------------

### Check for Specific File Presence

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

A generic root criterion that checks for the existence of a specific file within the project directory.

```r
rprojroot::has_file(".git/index")
```

--------------------------------

### thisfile_r()

Source: https://rprojroot.r-lib.org/reference/thisfile.html

A specific variant of thisfile() that is intended for use when R is run with the --file parameter.

```APIDOC
## Function: thisfile_r()

### Description
Determines the path of the currently running script when R is executed with the `--file` parameter.

### Usage
```R
thisfile_r()
```

### Value
The path of the currently running script, or NULL if it cannot be determined.

### Details
This function is part of the heuristics to find the script's path and works when R is run using the `--file` parameter.

### Example
```R
if (FALSE) { # \dontrun{
thisfile_r()
}
```
```

--------------------------------

### find_remake_root_file

Source: https://rprojroot.r-lib.org/reference/find_root_file.html

Finds a file relative to the remake root.

```APIDOC
## find_remake_root_file

### Description
Finds a file relative to the remake root, appending additional path components.

### Arguments
- `...` (character): Further path components passed to `file.path()`.
- `path` (character(1)): The starting directory for the search.

### Value
The normalized path of the remake root with additional path components appended.
```

--------------------------------

### thisfile_source()

Source: https://rprojroot.r-lib.org/reference/thisfile.html

A specific variant of thisfile() that is intended for use when a script is sourced.

```APIDOC
## Function: thisfile_source()

### Description
Determines the path of the currently running script, specifically when sourced.

### Usage
```R
thisfile_source()
```

### Value
The path of the currently running script, or NULL if it cannot be determined.

### Details
This function is part of the heuristics to find the script's path and works when the script is `source`d.

### Example
```R
if (FALSE) { # \dontrun{
thisfile_source()
}
```
```

--------------------------------

### has_file_pattern

Source: https://rprojroot.r-lib.org/reference/root_criterion.html

Creates a root criterion that checks for a file matching a pattern.

```APIDOC
## has_file_pattern(pattern, contents = NULL, n = -1L, fixed = FALSE)

### Description
Constructs a criterion that checks for the existence of a file that matches a given pattern, optionally with specific contents.

### Arguments
* `pattern` (`character(1)`): Regular expression to match the file name against.
* `contents` (`character(1)`, optional): If `NULL` (the default), file contents are not checked. Otherwise, `contents` is a regular expression (if `fixed` is `FALSE`) or a search string (if `fixed` is `TRUE`), and file contents are checked matching lines.
* `n` (`integerish(1)`): Maximum number of lines to read to check file contents. Defaults to -1 (all lines).
* `fixed` (`logical(1)`): If `FALSE` (default), `contents` is treated as a regular expression. If `TRUE`, `contents` is treated as a fixed string.

### Value
A `root_criterion` object.
```

--------------------------------

### has_basename

Source: https://rprojroot.r-lib.org/reference/root_criterion.html

Creates a root criterion that checks the basename of the root directory.

```APIDOC
## has_basename(basename, subdir = NULL)

### Description
Constructs a criterion that checks if the `base::basename()` of the root directory has a specific name. Supports case-insensitive file systems.

### Arguments
* `basename` (`character(1)`): The required name of the root directory.
* `subdir` (`character`, optional): If given, the criterion will also be tested in the subdirectories defined by this argument, in the order given. The first existing directory will be used as a starting point.

### Value
A `root_criterion` object.
```

--------------------------------

### find_testthat_root_file

Source: https://rprojroot.r-lib.org/reference/find_root_file.html

Finds a file relative to the testthat root.

```APIDOC
## find_testthat_root_file

### Description
Finds a file relative to the testthat root, appending additional path components.

### Arguments
- `...` (character): Further path components passed to `file.path()`.
- `path` (character(1)): The starting directory for the search.

### Value
The normalized path of the testthat root with additional path components appended.
```

--------------------------------

### Define custom root criterion: has_file

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Create a custom root criterion by checking for the existence of a specific file. This is useful for projects with unique file structures.

```R
has_license <- has_file("LICENSE")
has_license
```

--------------------------------

### Define relative path from vignettes

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Defines a relative path to a file from the 'vignettes' directory. This path is specific to the current working directory.

```R
rel_path_from_vignettes <- "../R/rrmake.R"
rel_path_from_vignettes <- file.path("..", "R", "rrmake.R") ## identical
```

--------------------------------

### Check if Project is an R Package

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

Use this criterion to identify if the current project is an R package by checking for a 'DESCRIPTION' file with specific content.

```r
rprojroot::is_r_package
```

--------------------------------

### root_criterion

Source: https://rprojroot.r-lib.org/reference/root_criterion.html

Constructs a root criterion object used to determine if a directory is a project root.

```APIDOC
## root_criterion(testfun, desc, subdir = NULL)

### Description
Constructs a root criterion object that decides if a given directory is a project root.

### Arguments
* `testfun` (`function`|`list(function)`): A function with one parameter that returns `TRUE` if the directory specified by this parameter is the project root, and `FALSE` otherwise. Can also be a list of such functions.
* `desc` (`character`): A textual description of the test criterion, of the same length as `testfun`.
* `subdir` (`character`, optional): If given, the criterion will also be tested in the subdirectories defined by this argument, in the order given. The first existing directory will be used as a starting point.

### Value
An S3 object of class `root_criterion` with members `testfun`, `desc`, and `subdir`, and methods `find_file` and `make_fix_file`.
```

--------------------------------

### Project Type Criteria

Source: https://rprojroot.r-lib.org/reference/criteria.html

These functions serve as boolean criteria to identify specific project types or structures.

```APIDOC
## is_rstudio_project

### Description
Checks if the current directory is an RStudio project.

### Details
Looks for a file with the extension `.Rproj`.

## is_vscode_project

### Description
Checks if the current directory is a VS Code project.

### Details
Looks for a `.vscode/settings.json` file.

## is_r_package

### Description
Checks if the current directory is an R package.

### Details
Looks for a `DESCRIPTION` file.

## is_remake_project

### Description
Checks if the current directory is a remake project.

### Details
Looks for a `remake.yml` file.

## is_drake_project

### Description
Checks if the current directory is a drake project.

### Details
Looks for a `.drake` directory.

## is_targets_project

### Description
Checks if the current directory is a targets project.

### Details
Looks for a `_targets.R` file.

## is_pkgdown_project

### Description
Checks if the current directory is a pkgdown project.

### Details
Looks for a `_pkgdown.yml`, `_pkgdown.yaml`, `pkgdown/_pkgdown.yml`, and/or `inst/_pkgdown.yml` file.

## is_renv_project

### Description
Checks if the current directory is an renv project.

### Details
Looks for an `renv.lock` file.

## is_projectile_project

### Description
Checks if the current directory is a projectile project.

### Details
Looks for a `.projectile` file.

## is_quarto_project

### Description
Checks if the current directory is a Quarto project.

### Details
Looks for a `_quarto.yml` file.

## is_git_root

### Description
Checks if the current directory is the root of a Git repository.

### Details
Looks for a `.git` directory.

## is_svn_root

### Description
Checks if the current directory is the root of an SVN repository.

### Details
Looks for a `.svn` directory.

## is_vcs_root

### Description
Checks if the current directory is the root of a version control system.

### Details
Currently only supports Git and SVN.

## is_testthat

### Description
Checks if the current directory is set up for testthat.

### Details
Looks for the `testthat` directory. Works when developing, testing, and checking a package.

## from_wd

### Description
Uses the current working directory as the root.

### Details
This criterion uses the current working directory.

```

--------------------------------

### find_rstudio_root_file

Source: https://rprojroot.r-lib.org/reference/find_root_file.html

Finds a file relative to the RStudio project root.

```APIDOC
## find_rstudio_root_file

### Description
Finds a file relative to the RStudio project root, appending additional path components.

### Arguments
- `...` (character): Further path components passed to `file.path()`.
- `path` (character(1)): The starting directory for the search.

### Value
The normalized path of the RStudio project root with additional path components appended.
```

--------------------------------

### has_dir

Source: https://rprojroot.r-lib.org/reference/root_criterion.html

Creates a root criterion that checks for the existence of a specific directory.

```APIDOC
## has_dir(filepath)

### Description
Constructs a criterion that checks for the existence of a specific directory.

### Arguments
* `filepath` (`character(1)`): The path to the directory to check for.

### Value
A `root_criterion` object.
```

--------------------------------

### thisfile_rscript()

Source: https://rprojroot.r-lib.org/reference/thisfile.html

A specific variant of thisfile() that is intended for use when a script is run with Rscript.

```APIDOC
## Function: thisfile_rscript()

### Description
Determines the path of the currently running script when executed with `Rscript`.

### Usage
```R
thisfile_rscript()
```

### Value
The path of the currently running script, or NULL if it cannot be determined.

### Details
This function is part of the heuristics to find the script's path and works when the script is run with `Rscript`. The exact value of the parameter passed to `Rscript` is returned.

### Example
```R
if (FALSE) { # \dontrun{
thisfile_rscript()
}
```
```

--------------------------------

### Check if Project is an RStudio Project

Source: https://rprojroot.r-lib.org/articles/rprojroot.html

This criterion helps identify an RStudio project by looking for a '.Rproj' file with specific content in the first line.

```r
rprojroot::is_rstudio_project
```

--------------------------------

### thisfile_knit()

Source: https://rprojroot.r-lib.org/reference/thisfile.html

A specific variant of thisfile() that is intended for use when a script is processed with knitr.

```APIDOC
## Function: thisfile_knit()

### Description
Determines the path of the currently running script when processed with `knitr`.

### Usage
```R
thisfile_knit()
```

### Value
The path of the currently running script, or NULL if it cannot be determined.

### Details
This function is part of the heuristics to find the script's path and works when the script is processed with `knitr`.

### Example
```R
if (FALSE) { # \dontrun{
thisfile_knit()
}
```
```

--------------------------------

### is_root_criterion

Source: https://rprojroot.r-lib.org/reference/root_criterion.html

Checks if an object is a root criterion.

```APIDOC
## is_root_criterion(x)

### Description
Checks if the given object `x` is of class `root_criterion`.

### Arguments
* `x` (`object`): The object to check.

### Value
`TRUE` if `x` is a `root_criterion`, `FALSE` otherwise.
```
Tokens:
Raw