README.Rmd

---
output: github_document
---

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

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# fluffy <a href="https://lj-jenkins.github.io/fluffy/"><img src="man/figures/logo.png" align="right" height="138" alt="fluffy website" /></a>

<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/fluffy)](https://CRAN.R-project.org/package=fluffy)
[![status](https://tinyverse.netlify.app/badge/fluffy)](https://CRAN.R-project.org/package=fluffy)
[![R-CMD-check](https://github.com/LJ-Jenkins/fluffy/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/LJ-Jenkins/fluffy/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

Validate R objects against user-defined schemas, with informative errors and data transformation.

## Installation

Install the latest release of fluffy from CRAN:

```{r, eval = FALSE}
install.packages("fluffy")
```

You can install the development version of fluffy from GitHub:

```{r, eval = FALSE}
# install.packages("pak")
pak::pak("LJ-Jenkins/fluffy")
```

## Basic Usage

```{r basic usage, error=TRUE}
library(fluffy)

df <- data.frame(x = 1:3, y = c(" a", "b  ", " c"))

v <- Validator(
  data = df,
  schema = list(
    type = "data.frame",
    min_nrow = 1,
    x = list(
      type = "numeric",
      max_val = 5
    ),
    y = list(
      type = "character",
      apply = function(x) trimws(x),
      nzchar = TRUE
    )
  )
)

#- Specified data is transformed
v@data

#- Overall validity
v@valid

#- Structured errors property
v@errors

#- Informative errors that reflect the perceived data structure
Validator(
  data = list(1, a = "a", b = 10, x = -1),
  schema = list(
    type = "data.frame",
    list(type = "character"),
    a = list(min_nchar = 2),
    b = list(min_length = 2, max_val = 5),
    x = list(positive = TRUE)
  ),
  error = TRUE
)

#- Transformed data can be accessed during the validation
Validator(
  data = list(a = 1, b = 1),
  schema = list(
    a = list(apply = "function(x) x + 1"),
    b = list(apply = function(x, .data, ...) if (.data[["a"]] > 1) x + 1)
  )
)@data

#- Extensible
s <- Schema(list(double_if_five_else_error = TRUE))
s@valid
s@errors

s <- add_rule(
  s,
  name = "double_if_five_else_error",
  validator_fn = function(field, schema_field, ...) {
    if (schema_field) {
      if (length(field) != 1L) {
        list(error = "Field must be length 1.")
      } else if (field != 5) {
        list(error = "Does not equal 5.")
      } else {
        list(data = field * 2)
      }
    }
  },
  schema_fn = function(schema_field, ...) {
    if (!isTRUE(schema_field) && !isFALSE(schema_field)) {
      "Must be a boolean."
    }
  },
  rule_type = "transform"
)
s@valid

v <- Validator(data = 5, schema = s)
v@valid
v@data
Validator(data = 1, schema = s, error = TRUE)

#- Works on numerous non-empty R object types, with data elements able to be
# validated if they can be accessed with `[[`.
Validator(
  call("mean", 1:10),
  list(
    type = "call",
    list(type = "name"),
    list(predicate = "function(x) identical(x, 1:10)")
  )
)@valid
Validator(expression(x + 1), list(type = "expression"))@valid
Validator(table(x = 1), list(type = "table"))@valid
Validator(new.env(), list(type = "environment"))@valid
e <- new.env()
e$a <- 1L
e$b <- "Hi"
Validator(
  e,
  list(
    type = "environment",
    a = list(type = "integer"),
    b = list(type = "character")
  )
)@valid
```

## Overview

fluffy provides three [S7](https://CRAN.R-project.org/package=S7) classes: `Registry`, `Schema`, and `Validator`.

`Registry` defines rules and stores all built-in fluffy rule names and definitions.
```{r Registry}
r <- Registry()

S7::prop_names(r)
```

`Schema` takes a user-defined nested list schema, validates the schema, and reorders the schema according to the order defined in the `Registry`. By default `Schema` creates a `Registry` if one is not passed to the function.
```{r Schema}
s <- Schema(list(type = "integer", default = 1L))

s@schema

S7::prop_names(s)
```

`Validator` takes data and a user-defined `Schema`, and applies each `Schema` field against the data. It does this in four passes:

1. control rules: rules that can alter control flow and stop other rules operating, e.g., `required`.
2. transform rules: rules that can modify the data, e.g., `apply` and `coerce`.
3. validate rules: rules that check the data against the schema, e.g., `type` and `min_val`.
4. finalize rules: rules that only operate if all other rules in the schema node passed validation without error, e.g., `apply_last` and `coerce_last`.

A list given as a schema will be passed to `Schema()` on ingest.
```{r Validator}
v <- Validator(
  data = list(a = 1, b = "Hello"),
  schema = list(
    a = list(
      type = "numeric",
      min_val = 0,
      max_val = 5
    ),
    b = list(
      type = "character",
      apply = "\\(x) paste(x, 'World!')"
    ),
    c = list(
      required = FALSE,
      type = "data.frame"
    ),
    d = list(
      default = 10L
    )
  )
)

v@data

S7::prop_names(v)
```

Using list schemas but virtually any R type for validation, fluffy can be used on a range of data types once loaded into R.
```{r data types example, error=TRUE}
yaml_schema <- yaml::yaml.load(
  "
  type: 'list'
  a:
    type: 'character'
  b:
    type: 'list'
    a:
      type: 'numeric'
    b:
      type: 'character'
      min_nchar: 3
  "
)

yaml_data <- yaml::yaml.load(
  "
  a: 1
  b:
    a: 1
    b: 'Hi'
  "
)

Validator(yaml_data, yaml_schema, error = TRUE)

json_schema <- jsonlite::fromJSON(
  '{
    "type": "list",
    "a": {
      "type": "numeric",
      "min_length": 2
    },
    "b": {
      "type": "list",
      "a": {
        "type": "numeric",
        "max_val": 5
      },
      "b": {
        "type": "character"
      }
    }
  }'
)

json_data <- jsonlite::fromJSON(
  '{
    "a": 1,
    "b": {
      "a": 10,
      "b": "Hi"
    }
  }'
)

Validator(json_data, json_schema, error = TRUE)

# rectangular data, from `readr` readme
# works for any data.frame data, e.g., sav, dta, xls, xlsx, csv, tsv, etc.
rect_schema <- list(
  type = "data.frame",
  chicken = list(
    type = "character",
    nzchar = TRUE
  ),
  sex = list(
    coerce = "factor",
    levels = c("rooster", "hen")
  ),
  eggs_laid = list(
    type = "integer",
    positive = TRUE
  ),
  motto = list(
    type = "character",
    nzchar = TRUE
  )
)

rect_data <- readr::read_csv(
  readr::readr_example("chickens.csv"),
  show_col_types = FALSE
)

Validator(rect_data, rect_schema, error = TRUE)
```

## Vignettes

For detailed information on using fluffy, see the vignettes:

* [Builtin rules](https://lj-jenkins.github.io/fluffy/articles/validation-rules.html)

* [Creating Schemas and Validating Data](https://lj-jenkins.github.io/fluffy/articles/validating-data.html)

* [Adding custom rules](https://lj-jenkins.github.io/fluffy/articles/custom-rules.html)

## Notes

fluffy was inspired by and modelled on Python's [Cerberus](https://github.com/pyeve/cerberus) (hence the name!). 

Error printing in fluffy was modelled on [lobstr](https://lobstr.r-lib.org/)'s tree function.

fluffy was originally called 'RV' but was renamed to distinguish itself from the [rv package manager](https://github.com/A2-ai/rv).

## Getting help

If you encounter a clear bug, please file an issue with a minimal reproducible example on [GitHub](https://github.com/LJ-Jenkins/fluffy/issues).

## Code of Conduct

Please note that this project is released with a [Contributor Code of Conduct](https://lj-jenkins.github.io/fluffy/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.