Get the File Path to a Matching File

Get the file path to a matching file while ensuring that only one file in a directory has a name matching pattern, for example before attempting to read a file.

Usage

get_file_path(dir = ".", pattern, ignore_case = TRUE, quietly = FALSE)

Arguments

dir

character string containing a valid path, see 'Details' and the section 'Notes on Paths' below.

pattern

character string containing a regular expression used to select names of files that are present in dir.

ignore_case

TRUE or FALSE: use case-insensitive pattern matching?

quietly

TRUE or FALSE: suppress the message with the found file name?

Value

A character string with the absolute normalized path to the file with a name matching pattern if there is exactly one such file in directory dir. Use basename() on the result to obtain the filename itself.

An error is thrown if no match, or multiple matches, are found. If ignore_case is FALSE, the error message indicates if any case-insensitive match is present.

Details

The path in dir is interpreted as a relative path to the directory where to look for a file, starting from the working directory, see the section 'Notes on Paths' below.

In contrast to the default of list.files(), get_file_path() includes 'hidden' files, i.e., files with names that start with a dot, but excludes directories.

Notes on Paths

The file separator is a backslash (\) on Windows but a forward slash (/) on other operating systems: use file.path() or fs::path() to construct paths in a platform-independent way and .Platform$file.sep to get the file separator used on the current platform.

Furthermore, the backslash is also used as an escape character in R, such that backslashes need to be escaped in R code by doubling them. Use cat(x) to omit the escape characters to see how x would be printed.

The working directory can be indicated by a single dot (".") and the parent directory can be indicated by two dots ("..").

relative paths start from the working directory. In contrast, absolute paths start from the root directory and thus give the complete path, such that the path still points to the same directory if the working directory changes.

Paths can be normalised, e.g., through normalizePath() or fs::path_norm() (which is also called by fs::path_abs()). On case-insensitive file systems, this also adjusts the case to match names of directories that are already present.

See also

checkinput::is_path() to check if a path is valid, with extensive references about file paths and directories; create_file_path() to create a file path and creating the indicated directory if it does not yet exist; fs::file_exists() and list.files() (which includes directories in its output) to check for existence of files without checking they are a unique match to a pattern; file.info() and file.access() to extract information about files or directories

Other functions to handle paths and directories: create_dir(), create_file_path(), create_tempdir()

Other functions to check equality: are_equal(), check_case(), not_in(), replace_nonalnum(), replace_vals(), signif_custom()

Examples

# Create files in a temporary directory
my_tempdir <- create_tempdir(prefix = "examplegetfilepath")
my_tempfiles <- fs::path_abs(
  fs::path(my_tempdir,
           c("some_filename.txt", "another_filename.txt"))
)

# Create the files
file.create(my_tempfiles)
#> [1] TRUE TRUE

get_file_path(dir = my_tempdir, pattern = "some_file")
#> Using file '/tmp/RtmpmaAUni/examplegetfilepath1aa919616985/some_filename.txt'
#> /tmp/RtmpmaAUni/examplegetfilepath1aa919616985/some_filename.txt

# The same file is found if case-insensitive matching is used:
get_file_path(dir = my_tempdir, pattern = "SOME_FILE",
              ignore_case = TRUE)
#> Using file '/tmp/RtmpmaAUni/examplegetfilepath1aa919616985/some_filename.txt'
#> /tmp/RtmpmaAUni/examplegetfilepath1aa919616985/some_filename.txt

# Error reporting the presence of a case-insensitive match.
try(get_file_path(dir = my_tempdir, pattern = "SOME_FILE",
                  ignore_case = FALSE))
#> Error in get_file_path(dir = my_tempdir, pattern = "SOME_FILE", ignore_case = FALSE) : 
#>   No case-sensitive matches to pattern 'SOME_FILE' are present in directory
#> '/tmp/RtmpmaAUni/examplegetfilepath1aa919616985'.
#> However, one or more case-insensitive matches to 'pattern' are present:
#> 'some_filename.txt'.

# 'pattern' is interpreted as a regular expression
get_file_path(dir = my_tempdir, pattern = "^.+er_file")
#> Using file '/tmp/RtmpmaAUni/examplegetfilepath1aa919616985/another_filename.txt'
#> /tmp/RtmpmaAUni/examplegetfilepath1aa919616985/another_filename.txt

# Error reporting no match found.
try(get_file_path(dir = my_tempdir,
                 pattern = "missing_filename_abcde",
                 ignore_case = TRUE))
#> Error in get_file_path(dir = my_tempdir, pattern = "missing_filename_abcde",  : 
#>   No matches to pattern 'missing_filename_abcde' are present in directory
#> '/tmp/RtmpmaAUni/examplegetfilepath1aa919616985'.
try(get_file_path(dir = my_tempdir,
                 pattern = "missing_filename_abcde",
                 ignore_case = FALSE))
#> Error in get_file_path(dir = my_tempdir, pattern = "missing_filename_abcde",  : 
#>   No case-sensitive matches to pattern 'missing_filename_abcde' are present in directory
#> '/tmp/RtmpmaAUni/examplegetfilepath1aa919616985'.
#> No case-insensitive match is present either.

# Error if multiple matches are present.
try(get_file_path(dir = my_tempdir, pattern = "_filename"))
#> Error in get_file_path(dir = my_tempdir, pattern = "_filename") : 
#>   Multiple matches to pattern '_filename' are present in directory
#> '/tmp/RtmpmaAUni/examplegetfilepath1aa919616985':
#> 'another_filename.txt'
#> 'some_filename.txt'!

# Clean up
unlink(x = my_tempfiles)
rm(my_tempfiles)