Package 'entratar'

Description

These functions perform checks that assert the underlying class of objects passed to them.

• check_inherits(): checks that object x is of class class using base::inherits()

• check_inherits2(): checks that object x is of class class using base::.class2()

• check_inherits_any(): checks that object x is at least one of the provided classes via rlang::inherits_any()

• check_inherits_all(): checks that object x is all of the provided classes via rlang::inherits_all()

If validation fails for any of these functions, an error is thrown via check_abort() displaying a friendly error message.

Usage

check_inherits(
  x,
  class,
  arg = rlang::caller_arg(x),
  call = rlang::caller_env()
)

check_inherits2(
  x,
  class,
  arg = rlang::caller_arg(x),
  call = rlang::caller_env()
)

check_inherits_any(
  x,
  classes,
  arg = rlang::caller_arg(x),
  call = rlang::caller_env()
)

check_inherits_all(
  x,
  classes,
  arg = rlang::caller_arg(x),
  call = rlang::caller_env()
)

Arguments

Value

If checks pass, invisibly returns the provided x object. If checks fail, a condition error is thrown.

Description

Checks the provided x is not "empty" via rlang::is_empty().

Usage

check_not_empty(x, arg = rlang::caller_arg(x), call = rlang::caller_env())

Arguments

Value

If checks pass, invisibly returns the provided x object. If checks fail, a condition error is thrown.

Description

Checks the provided x is a scalar string via rlang::check_string().

Usage

check_string(
  x,
  allow_empty = FALSE,
  allow_na = FALSE,
  allow_null = FALSE,
  arg = rlang::caller_arg(x),
  call = rlang::caller_env()
)

Arguments

Value

If x is not a scalar string, an error is thrown. Otherwise, x is invisibly returned.

Description

These functions are specialized versions of the entratar condition functions that are intended for use in the package's internal checking functions. They create conditions with specific classes that can be used to identify and handle errors, warnings, and messages.

Usage

entrata_abort_check(
  msg,
  ...,
  parent = NULL,
  call = rlang::caller_env(),
  .envir = parent.frame()
)

entrata_warn_check(
  msg,
  ...,
  call = rlang::caller_env(),
  .envir = parent.frame()
)

entrata_inform_check(
  msg,
  ...,
  call = rlang::caller_env(),
  .envir = parent.frame()
)

check_abort(
  msg,
  ...,
  parent = NULL,
  call = rlang::caller_env(),
  .envir = parent.frame()
)

check_warn(msg, ..., call = rlang::caller_env(), .envir = parent.frame())

check_inform(msg, ..., call = rlang::caller_env(), .envir = parent.frame())

Arguments

Details

The condition class hierarchy is structured like so:

<entrata_condition>
  ├── <entrata_error>
  │   ├── <entrata_{custom}_error>
  ├── <entrata_warning>
  │   ├── <entrata_{custom}_warning>
  ├── <entrata_message>
  └────── <entrata_{custom}_message>

where ⁠<entrata_condition>⁠ is the base class for all entratar conditions and sits on top of the existing rlang and base R condition classes.

For example, an entrata error thrown without any additional custom class added to it using entrata_abort() will have the following classes:

[1] "entrata_error" "entrata_condition" "rlang_error" "error" "condition"

This allows for filtering and handling of Entrata-specific conditions while still being compatible with the broader R condition system.

Value

These functions do not return values, but are used for their side effects, namely creating and signaling conditions. The entrata_abort() function will stop execution, while entrata_warn() & entrata_inform() will allow execution to proceed.

Functions

• entrata_abort_check(): creates an entrata_error condition for checks.

• entrata_warn_check(): creates an entrata_warning condition for checks.

• entrata_inform_check(): creates an entrata_message condition for checks.

Aliases

• check_abort(): alias for entrata_abort_check()

• check_warn(): alias for entrata_warn_check()

• check_inform(): alias for entrata_inform_check()

See Also

Utility Functions: entrata_active_config

Conditions: entratar-conditions

Examples

## Not run: 
entrata_abort("This is a entratar error.")

# catch a condition and check its classes
err <- rlang::catch_cnd(entrata_abort("Error Message"))
class(err)

# catch a warning and check its classes
wrn <- rlang::catch_cnd(entrata_warn("Warning Message"))
class(wrn)

# catch a message and check its classes
msg <- rlang::catch_cnd(entrata_inform("Message"))
class(msg)

## End(Not run)

Description

Functions for quickly accessing or setting the active configuration file and environment for config::get().

Get:

• get_active_config_env(): Returns the active configuration run-time environment (ENTRATA_CONFIG_ACTIVE, R_CONFIG_ACTIVE).

• get_active_config_file(): Returns the active configuration file (ENTRATA_CONFIG_FILE, R_CONFIG_FILE).

Set:

• set_active_config_env(env): Sets the active configuration environment

• set_active_config_file(file): Sets the active configuration file

Usage

get_active_config_env(
  default = c("default", "development", "production", "testing")
)

set_active_config_env(env)

get_active_config_file(default = pkg_sys_config("config.yml"))

set_active_config_file(file)

Arguments

Value

• get_active_config_env(): The active configuration environment as a string.

• get_active_config_file(): The active configuration file as a string.

• set_active_config_env(env): Returns the previous active configuration environment.

• set_active_config_file(file): Returns the previous active configuration file.

See Also

config::get()

Utility Functions: entrata_abort_check()

Description

Functions for creating and handling custom Entrata-specific conditions, including errors, warnings, and messages.

• entrata_abort(): creates a condition representing an error and when thrown, aborts execution.

• entrata_warn(): creates a condition representing a warning condition

• entrata_inform(): creates a condition representing a message condition

These functions wrap cli::cli_abort(), cli::cli_warn(), and cli::cli_inform() respectively, adding entratar-specific context and class names (⁠entrata_*⁠) to the condition objects for downstream handling and identification.

Usage

entrata_abort(
  msg = NULL,
  cls = NULL,
  ...,
  parent = NULL,
  call = rlang::caller_env(),
  .envir = parent.frame()
)

entrata_warn(msg = NULL, cls = NULL, ..., .envir = parent.frame())

entrata_inform(msg = NULL, cls = NULL, ..., .envir = parent.frame())

Arguments

Details

The condition class hierarchy is structured like so:

<entrata_condition>
  ├── <entrata_error>
  │   ├── <entrata_{custom}_error>
  ├── <entrata_warning>
  │   ├── <entrata_{custom}_warning>
  ├── <entrata_message>
  └────── <entrata_{custom}_message>

where ⁠<entrata_condition>⁠ is the base class for all entratar conditions and sits on top of the existing rlang and base R condition classes.

For example, an entrata error thrown without any additional custom class added to it using entrata_abort() will have the following classes:

[1] "entrata_error" "entrata_condition" "rlang_error" "error" "condition"

This allows for filtering and handling of Entrata-specific conditions while still being compatible with the broader R condition system.

Value

These functions do not return values, but are used for their side effects, namely creating and signaling conditions. The entrata_abort() function will stop execution, while entrata_warn() & entrata_inform() will allow execution to proceed.

See Also

Conditions: entrata_abort_check()

Examples

## Not run: 
entrata_abort("This is a entratar error.")

# catch a condition and check its classes
err <- rlang::catch_cnd(entrata_abort("Error Message"))
class(err)

# catch a warning and check its classes
wrn <- rlang::catch_cnd(entrata_warn("Warning Message"))
class(wrn)

# catch a message and check its classes
msg <- rlang::catch_cnd(entrata_inform("Message"))
class(msg)

## End(Not run)