README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
if (basename(getwd()) == "docs") {
  knitr::opts_knit$set(root.dir = file.path(getwd(), ".."))
}
fs:::pkgdown_tmp(c("/tmp/filedd463d6d7e0f", "/tmp/filedd464dbb3467"))
```

# fs <a href="https://fs.r-lib.org/"><img src="man/figures/logo.png" align="right" height="138" alt="fs website" /></a>

<!-- badges: start -->
[![lifecycle](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://lifecycle.r-lib.org/articles/stages.html#maturing)
[![R-CMD-check](https://github.com/r-lib/fs/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-lib/fs/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/r-lib/fs/graph/badge.svg)](https://app.codecov.io/gh/r-lib/fs)
<!-- badges: end -->

**fs** provides a cross-platform, uniform interface to file system operations.
It shares the same back-end component as [nodejs](https://nodejs.org), the
[libuv](https://docs.libuv.org/en/v1.x/fs.html) C library, which brings the
benefit of extensive real-world use and rigorous cross-platform testing. The
name, and some of the interface, is partially inspired by Rust's [fs
module](https://doc.rust-lang.org/std/fs/index.html).

## Installation

You can install the released version of **fs** from [CRAN](https://CRAN.R-project.org) with:

``` r
install.packages("fs")
```

And the development version from [GitHub](https://github.com/) with:
```r
pak::pak("r-lib/fs")
```

## Comparison vs base equivalents

**fs** functions smooth over some of the idiosyncrasies of file handling with
base R functions:

* Vectorization. All **fs** functions are vectorized, accepting multiple paths
  as input. Base functions are inconsistently vectorized.

* Predictable return values that always convey a path. All **fs** functions
  return a character vector of paths, a named integer or a logical vector, where
  the names give the paths. Base return values are more varied: they are often
  logical or contain error codes which require downstream processing.

* Explicit failure. If **fs** operations fail, they throw an error. Base
  functions tend to generate a warning and a system dependent error code. This
  makes it easy to miss a failure.

* UTF-8 all the things. **fs** functions always convert input paths to UTF-8 and
  return results as UTF-8. This gives you path encoding consistency across OSes.
  Base functions rely on the native system encoding.

* Naming convention. **fs** functions use a consistent naming convention.
  Because base R's functions were gradually added over time there are a number
  of different conventions used (e.g. `path.expand()` vs `normalizePath()`;
  `Sys.chmod()` vs `file.access()`).

### Tidy paths

**fs** functions always return 'tidy' paths. Tidy paths

  - Always use `/` to delimit directories
  - never have multiple `/` or trailing `/`

Tidy paths are also coloured (if your terminal supports it) based on the
file permissions and file type. This colouring can be customized or extended by
setting the `LS_COLORS` environment variable, in the same output format as [GNU
dircolors](https://www.bigsoft.co.uk/blog/index.php/2008/04/11/configuring-ls_colors).

## Usage

**fs** functions are divided into four main categories:

  * `path_` for manipulating and constructing paths
  * `file_` for files
  * `dir_` for directories
  * `link_` for links

Directories and links are special types of files, so `file_` functions
will generally also work when applied to a directory or link.

```{r}
library(fs)

# Construct a path to a file with `path()`
path("foo", "bar", letters[1:3], ext = "txt")

# list files in the current directory
dir_ls()

# create a new directory
tmp <- dir_create(file_temp())
tmp

# create new files in that directory
file_create(path(tmp, "my-file.txt"))
dir_ls(tmp)

# remove files from the directory
file_delete(path(tmp, "my-file.txt"))
dir_ls(tmp)

# remove the directory
dir_delete(tmp)
```

**fs** is designed to work well with the pipe, though because it is a
minimal-dependency infrastructure package it doesn't provide the pipe itself.
You will need to attach [magrittr](https://magrittr.tidyverse.org) or similar.

```{r}
library(magrittr)

paths <- file_temp() |>
  dir_create() |>
  path(letters[1:5]) |>
  file_create()
paths

paths |> file_delete()
```

**fs** functions also work well in conjunction with other
[tidyverse](https://www.tidyverse.org/) packages, like
[dplyr](https://dplyr.tidyverse.org) and [purrr](https://purrr.tidyverse.org).

Some examples...

```{r}
suppressMessages(
  library(tidyverse))
```

Filter files by type, permission and size

```{r}
dir_info("src", recurse = FALSE) |>
  filter(type == "file", permissions == "u+r", size > "10KB") |>
  arrange(desc(size)) |>
  select(path, permissions, size, modification_time)
```

Tabulate and display folder size.

```{r}
dir_info("src", recurse = TRUE) |>
  group_by(directory = path_dir(path)) |>
  tally(wt = size, sort = TRUE)
```

Read a collection of files into one data frame.

`dir_ls()` returns a named vector, so it can be used directly with
`purrr::map_df(.id)`.

```{r}
# Create separate files for each species
iris |>
  (\(x) split(x, x$Species))() |>
  map(select, -Species) |>
  iwalk(\(.x, .y) write_tsv(.x, paste0(.y, ".tsv")))

# Show the files
iris_files <- dir_ls(glob = "*.tsv")
iris_files

# Read the data into a single table, including the filenames
iris_files |>
  map_df(read_tsv, .id = "file", col_types = cols(), n_max = 2)

file_delete(iris_files)
```

## Feedback wanted!

We hope **fs** is a useful tool for both analysis scripts and packages.
Please open [GitHub issues](https://github.com/r-lib/fs) for any feature requests or bugs.

In particular, we have found non-ASCII filenames in non-English locales on
Windows to be especially tricky to reproduce and handle correctly. Feedback
from users who use commonly have this situation is greatly appreciated.

## Code of Conduct

Please note that the fs project is released with a
[Contributor Code of Conduct](https://fs.r-lib.org/dev/CODE_OF_CONDUCT.html).
By contributing to this project, you agree to abide by its terms.