Work with valid configurations

Description

S7schema() provides a generic way of working with yaml configuration files.

The object is created by supplying both an initial YAML configuration (file) and the JSON schema definition (schema) of the configuration file.

The initial configuration is validated before the new object is returned. If not valid the first error is thrown, together with a path to the entry in the YAML file, and a description of the error.

The S7schema class inherits from list, ensuring that the content of the YAML file can be accessed as if read directly with yaml::read_yaml(), and supports the below workflow:

1. Read and validate config file: x <- S7schema(...)

2. Edit content as if it was a list: x$new_entry <- "new_value"

3. Validate new content against the original schema: validate(x)

4. Use values in downstream functions: x$new_entry

Usage

S7schema(file, schema)

Arguments

Details

See internal validator() documentation for more info on how the validation is done.

Value

New S7schema object.

Properties

schema

character(1) path to JSON schema being used to validate against.

validator

Internal validator() used to validate the content (read-only).

file

character(1) path to the source YAML file.

Examples

# Work with yaml configuration file:
S7schema(
  file = system.file("examples/config.yml", package = "S7schema"),
  schema = system.file("examples/schema.json", package = "S7schema")
)

Document configuration schema

Description

Creates markdown documentation of a configuration suitable for use in e.g. vignettes to provide easy readable documentation for users.

Usage

document_schema(x, header_start_level = 1L)

Arguments

Value

character(1)/knitr::asis_output() markdown with the documentation.

Examples

# Simple example schema
system.file("examples/schema.json", package = "S7schema") |>
  document_schema(2) |>
  cat()

# Changing header start level to 1
system.file("examples/schema.json", package = "S7schema") |>
  document_schema(1) |>
  cat()

# Example with definitions
system.file("examples/definitions.json", package = "S7schema") |>
  document_schema(2) |>
  cat()

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

S7

validate

Convert an R object to YAML

Description

This function is used internally when validating list or S7schema objects, and when using write_config() to save a configuration.

Underneath it is calling yaml::as.yaml() to do the conversion, but all logical values are converted to true/false instead of yes/no respectively for a more robust integration with other YAML parsers.

It is rarely relevant to call this function directly except for debugging purposes, or when implementing a new method for your own object class.

Usage

to_yaml(x)

Arguments

Details

to_yaml() dispatches based on the class of x. Register a new S7 method if you want to overwrite how your own class is converted to YAML. See S7::method() for more information.

The default method just uses yaml::verbatim_logical() to overwrite the default behavior of handling logical values:

function(x) {
  yaml::as.yaml(
    x = x,
    handlers = list(
      logical = yaml::verbatim_logical
    )
  )
}

Copy this and add your own additional handlers when implementing a new method.

Value

character(1) YAML string.

Examples

# Convert simple list to YAML
to_yaml(list(hello = "world", is_today = TRUE)) |>
  cat()

# Convert S7schema object
x <- S7schema(
  file = system.file("examples/config.yml", package = "S7schema"),
  schema = system.file("examples/schema.json", package = "S7schema")
)

print(x)

to_yaml(x) |>
  cat()

One-shot validation of configurations

Description

Check if a configuration is in accordance with a JSON schema definition.

It is possible to either validate an existing list object in memory or an existing yaml configuration file.

Usage

validate_list(x, schema)

validate_yaml(file, schema)

Arguments

Details

See internal validator() documentation for more info on how the validation is done.

Value

• validate_list(): invisible(x)

• validate_yaml(): invisible(file)

See Also

S7schema()

Examples

# Validate list object in memory
validate_list(
  x = list(my_config_var = 1),
  schema = system.file("examples/schema.json", package = "S7schema")
) |>
  print()

# Validate yaml file on disk
validate_yaml(
  file = system.file("examples/config.yml", package = "S7schema"),
  schema = system.file("examples/schema.json", package = "S7schema")
) |>
  print()

Internal validator based on a JSON schema

Description

Based on a JSON schema, ajv is used to create a validator object in Javascript that can be used to check an input yaml. This is done in a V8::v8() context, and stored inside the context property of the the object.

See json-schema.org on how to specify a JSON schema.

Usage

validator(schema)

Arguments

Value

New validator object

Properties

context

V8::v8() context with a validator object based on the schema

Write YAML configuration file

Description

Thin wrapper around to_yaml() calling validate() before converting to YAML and creating the file, ensuring that the saved configuration is valid.

Usage

write_config(x, file = x@file)

Arguments

Value

Invisible x (the input S7schema object). Called for side effect of writing the file.

Examples

# Read configuration file:
x <- S7schema(
  file = system.file("examples/config.yml", package = "S7schema"),
  schema = system.file("examples/schema.json", package = "S7schema")
)

print(x)

# Edit content
x$my_config_var <- 2

# Save new file
write_config(
  x = x,
  file = tempfile(fileext = ".yml")
)