---
title: "What is in the package?"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{What is in the package?}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Example files

This package provides example files containing artificial path data. The files 
are located in the `extdata` folder of the package. The function 
`extdata_file()` returns the full path to a file in this folder when being 
given the filename:

```{r}
(example_file <- fakin.path.app:::extdata_file("example_file_info_1.csv"))
```

## Read Functions

The package contains functions named `read_*`. These functions are 
described in the following.

### read_csv()

This function reads a csv file either with `read.table()` (version = 1) or 
with `data.table::fread()` (version = 2). It reports about what it does and 
about the time it takes.

```{r}
data_1 <- kwb.fakin::read_csv(example_file, version = 1) 

data_2 <- kwb.fakin::read_csv(example_file, version = 2)

head(data_1, 3)

head(data_2, 3)

identical(data_1, data_2)
```

### read_file_info()

This function reads a text file that contains any kind of file path information.
The function is aimed to read files containing file paths only, one path per
line, as well as files that contain additional information such as file size,
creation time or last modification time. File sizes are assumed to be given in
bytes and are converted to Mebibytes (MiB = 2^20 bytes) in order to avoid very
large numbers that require a non-standard data type.

```{r}
file_info <- fakin.path.app::read_file_paths(example_file)

head(file_info)
```

When reading files that only contain file paths (without any additional columns)
the function adds columns `type` and `size`. The `type` is guessed from the
filename extension whereas the `size` is set to 0 for directories and to `2^20`
for files. You can specify the `fileEncoding` assumed for the file. When being
set to `NULL` the function uses `utils::localeToCharset()` to guess an encoding.
The encoding is passed to the function `file()` that is used to open an explicit
connection. This connection is then given to `readLines()`. The lines read are
assumed to be full file paths. Backslashes are converted to slashes. By default,
all paths are sorted.

```{r}
# Helper function
read_example <- function(x) {
  fakin.path.app::read_file_paths(kwb.fakin::extdata_file(x))
} 

file_paths <- read_example("example_file_paths.csv")
folder_paths <- read_example("example_folder_paths.csv")

head(file_paths)
head(folder_paths)
```

### read_path_information()

This function reads file information files specified by a name pattern matching
the files to be read. It calls `read_file_info()` in a loop over the files and
returns a list with the list elements named according to the file names. The
content of a file matching `path-info_<yyyy-mm-dd_HHMM>_<name>.csv` appears in
the list as element `<name>`.

```{r error = TRUE}
file_infos <- kwb.fakin::read_path_information(
  file_info_dir = kwb.fakin::extdata_file(""), 
  pattern = "^example_file_info.*\\.csv$", 
  sep = ";"
)
```

## File Listing Functions

The functions treated so far have in common that they read file information from
files. The following functions can be used to create these files. They use `dir`
or more advanced functions from the fs package.

### list_files

```{r}
kwb.fakin::list_files
```

### get_recursive_file_info

This is just a wrapper around `fs::dir_info()` with `recurse = TRUE`. The 
function is run inside a call to `kwb.utils::catAndRun()`.

```{r}
root <- system.file(package = "kwb.fakin")
file_info <- fakin.path.app::get_recursive_file_info(root)
head(file_info[, 1:3])
```