README.Rmd

---
output: github_document
editor_options: 
  chunk_output_type: console
---

<!-- 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%"
)
```

# tor

<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/tor)](https://CRAN.R-project.org/package=tor)
[![Codecov test coverage](https://codecov.io/gh/maurolepore/tor/branch/main/graph/badge.svg)](https://app.codecov.io/gh/maurolepore/tor?branch=main)
[![R-CMD-check](https://github.com/maurolepore/tor/workflows/R-CMD-check/badge.svg)](https://github.com/maurolepore/tor/actions)
[![R-CMD-check](https://github.com/maurolepore/tor/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/maurolepore/tor/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

__tor__ (_to-R_) helps you to import multiple files at once. For example:

* Run `list_rds()` to import all .csv files from your working directory into a list.
* Run `load_csv()` to import all .csv files from your working directory into your global environment.

## Installation

Install __tor__ from CRAN with:

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

Or install the development version from GitHub with:

``` r
# install.packages("devtools")
devtools::install_github("maurolepore/tor")
```

## Example

```{r}
library(tor)

withr::local_options(readr.show_col_types = FALSE)
```

### `list_*()`: Import multiple files from a directory into a list

All functions default to importing files from the working directory.

```{r}
dir()

list_csv()
```

Often you will specify a `path` to read from.

```{r}
# Helpes create paths to examples
tor_example()

(path_rds <- tor_example("rds"))
dir(path_rds)

list_rds(path_rds)
```

You may read all files with a particular extension.

```{r}
path_mixed <- tor_example("mixed")
dir(path_mixed)

list_rdata(path_mixed)
```

Or you may read specific files matching a pattern.

```{r}
list_rdata(path_mixed, regexp = "[.]RData", ignore.case = FALSE)
```

`list_any()` is the most flexible function. You supply the function to read with.

```{r}
(path_csv <- tor_example("csv"))
dir(path_csv)

list_any(path_csv, read.csv)
```

It understands lambda functions and formulas (powered by [__rlang__](https://rlang.r-lib.org/)).

```{r}
# Use the pipe (%>%)
library(magrittr)

(path_rdata <- tor_example("rdata"))
dir(path_rdata)

path_rdata %>%
  list_any(function(x) get(load(x)))

# Same
path_rdata %>%
  list_any(~ get(load(.x)))
```

Pass additional arguments via `...` or inside the lambda function.

```{r}
path_csv %>%
  list_any(readr::read_csv, skip = 1)

path_csv %>%
  list_any(~ read.csv(., stringsAsFactors = FALSE))
```

It also provides the arguments `regexp`, `ignore.case`, and `invert` to pick specific files in a directory (powered by [__fs__](https://fs.r-lib.org/)).

```{r}
path_mixed <- tor_example("mixed")
dir(path_mixed)

path_mixed %>%
  list_any(~ get(load(.)), "[.]Rdata$", ignore.case = TRUE)

path_mixed %>%
  list_any(~ get(load(.)), regexp = "[.]csv$", invert = TRUE)
```

### `load_*()`: Load multiple files from a directory into an environment

All functions default to importing files from the working directory and into the global environment.

```{r}
# The working directory contains .csv files
dir()

load_csv()

# Each file is now available as a dataframe in the global environment
csv1
csv2

rm(list = ls())
```

You may import files from a specific `path`.

```{r}
(path_mixed <- tor_example("mixed"))
dir(path_mixed)

load_rdata(path_mixed)

ls()
rda
```

You may import files into a specific `envir`onment.

```{r}
e <- new.env()
ls(e)

load_rdata(path_mixed, envir = e)

ls(e)
```

For more flexibility use `load_any()` with a function able to read one file of the format you want to import.

```{r}
dir()

load_any(".", .f = readr::read_csv, regexp = "[.]csv$")

# The data is now available in the global environment
csv1
csv2
```

# Related projects

Two great packages to read and write data are [__rio__](https://CRAN.R-project.org/package=rio) and [__io__](https://CRAN.R-project.org/package=io).

## Information

* [Getting help](https://maurolepore.github.io/tor/SUPPORT.html).
* [Contributing](https://maurolepore.github.io/tor/CONTRIBUTING.html).
* [Contributor Code of Conduct](https://maurolepore.github.io/tor/CODE_OF_CONDUCT.html).