config {pkgdepends}R Documentation

Package configuration (internals)

Description

Internal machinery for pkgdepends configuration. See current_config() for how this machinery can be used to define the configuration of a package.

This is a standalone file that can be copied into another package without changes.

Usage

config

Format

config is a list of functions with a closure. You can use it two ways.

For one set of configuration values in a package, include this in .onLoad():

conf <- config$new("prefix")
conf$add("myenrry", "string", "default-value")
...
conf$lock()

For _multiple _ sets of configuration values (e.g. one per object), include a function like this in the package:

current_config <- function() {
  conf <- config$new("prefix")
  conf$add("myentry", "string", "default-value")
  ...
  conf$lock()
  conf
}

and then call current_config() every time you need to create a new set of configuration values.

Terminology

Config entry (or entry)

A single configurable entity. A config entry has a name. This name is always standardized by replacing dashes with underscores.

A config entry has a type: a string, a flag, or some user defined type. It can also have a default value. Examples:

Configuration (or config)

A set of configuration entries. config$new() returns a configuration. A configuration can be extended by adding new entries to it, until it is locked.

R option (or option)

An option set with base::options() and queried with base::getOption().

Configuration prefix

A prefix that is typically package specific, and it is used for all config entries of a package, to avoid environment variable and option name clashes between packages.

Config entry type

It defines the allowed values of configuration entries, and also how a string from an environment variable is translated to the value of the entry. See the list of builtin types below. You can also define new types.

Built-in types

string

String scalar, NA is not allowed.

count

Non-negative integer, NA is not allowed.

flag

Logical scalar, NA is not allowed. For environment variables the TRUE values are: yes, true, 1 and on, and the FALSE values are: no, false, 0, off. (All are case insensitive.)

string_or_null

String or NULL. NA is not allowed. In environment variables the string NULL means an R NULL value.

character

Character vector without NA values. In environment variables the entries are separated by a semicolon.

custom

Custom type. An env_decode function must be specified for each config entry of this type, otherwise an error is throw if the corresponding environment variable is set.

config$onload_hook(): pretty-printing configuration

Call config$onload_hook() from the package's .onLoad() function if you want to define S3 methods to print the package configuration nicer.

Usage

config$onload_hook()

config$new(): Create a new configuration

Typically new() is called outside of the functions of the package, so the config object is created at install time.

Usage

conf <- config$new(prefix = utils::packageName(parent.frame()))

Arguments

Value

new() returns a config object, which is a list containing the configuration data and functions (methods) to query and change it.

conf <- config$new()

Configuration methods

conf$add(): add a new configuration entry

Usage
conf$add(
  name,
  type = conf$types,
  default = NULL,
  check = type[1],
  env_decode = type[1]
)
Arguments
Value

The configuration, invisibly.

conf$get(): query the value of a configuration entry

Usage
conf$get(name)
Arguments
Value

Value of the entry.

conf$set(): set the value of a configuration entry

If you ⁠$set()⁠ a config entry, then the value used in ⁠$set()⁠ will be returned by ⁠$get()⁠, without consulting R options or environment variables.

Usage
conf$set(name, value)
Arguments
Value

The configuration, invisibly.

⁠$conf$unset()⁠: unset a configuration entry

Note that this function does not unset R options and environment variables. It merely removes a value that was assigned by ⁠$set()⁠ or ⁠$update()⁠.

Usage
conf$unset(name)
Arguments
Value

The configuration, invisibly.

cond$update(): update the values of configuration entries

You can use this method to set()and/or$unset()⁠multiple config entries.⁠NULL⁠values in⁠new' will unset the corresponding entry.

Usage
conf$update(new)
Arguments
Value

The configuration, invisibly.

conf$list(): query the names of all config entries

Note that their order is non-deterministic currently.

Usage
conf$list()
Value

Character vector.

conf$exists(): check if a config entry exists

Usage
conf$exists(name)
Arguments
Value

Logical scalar, TRUE if the entry exists in the configuration, FALSE otherwise. Note that TRUE does not mean that the value of the entry was set.

conf$lock(): lock the configuration

If a configuration is locked, then no more entries can be added to it.

Usage
conf$lock()
Value

The configuration, invisibly.

conf$fix(): fix the value of a single configuration entry

The currently ⁠$set()⁠ value is fixed and cannot be changed any more. You can fix an entry without setting its value, in which case R options and environment variables can still be used to update it.

Usage
conf$unset(name)
Arguments
Value

The configuration, invisibly.

conf$add_type(): add a new config entry type to a configuration

After this the new type can be used in conf$add() calls.

Usage
conf$add_type(type_name, check, env_decode)
Arguments
Value

The configuration, invisibly.


[Package pkgdepends version 0.9.0 Index]