Package {sessioncheck}

Title: Checks Session Status
Version: 0.1.1
Description: Provides tools for checking whether an R session is in a clean state, including the global environment, attached packages, loaded namespaces, attached environments, session run time, R options, locale settings, and system environment variables. Intended as a safer replacement for the common 'rm(list = ls())' idiom: rather than silently wiping the global environment, sessioncheck() surfaces problems so the user can make an informed decision.
License: MIT + file LICENSE
Encoding: UTF-8
Language: en-US
URL: https://github.com/djnavarro/sessioncheck, https://sessioncheck.djnavarro.net/
BugReports: https://github.com/djnavarro/sessioncheck/issues
Suggests: knitr, rmarkdown, spelling, testthat (≥ 3.0.0)
Config/testthat/edition: 3
Config/Needs/website: djnavarro/waeponwifestre
Config/roxygen2/version: 8.0.0
NeedsCompilation: no
Packaged: 2026-07-28 23:37:23 UTC; danielle
Author: Danielle Navarro ORCID iD [aut, cre, cph], Meghan Harris ORCID iD [ctb]
Maintainer: Danielle Navarro <djnavarro@protonmail.com>
Repository: CRAN
Date/Publication: 2026-07-28 23:50:02 UTC

Check environments attached to the search path

Description

Individual session check function that inspects the names of attached non-package environments. Session checkers can produce errors, warnings, or messages if requested.

Usage

check_attached_environments(
  action = "warn",
  allow_attached_environments = NULL
)

Arguments

action

Behavior to take if the status is not clean. Possible values are "error", "warn", "message", and "none". The default is action = "warn".

allow_attached_environments

Character vector containing names of environments that are "allowed", and will not trigger an action if attached to the search path.

Details

This checker inspects all environments on the search path. This includes attached packages, anything added using attach(), and the global environment. When allow_attached_environments = NULL, package environments do not trigger an action, nor do "tools:rstudio", "tools:positron", "tools:callr", or "Autoloads". The global environment and the package environment for the base package never trigger actions.

Value

Invisibly returns an object of class sessioncheck_status.

See Also

check_attached_packages(), check_loaded_namespaces(), check_globalenv_objects(), check_sessiontime(), check_required_options(), check_required_locale(), check_required_sysenv()

Examples

check_attached_environments(action = "message")

Check attached packages

Description

Individual session check function that inspects the attached packages. Session checkers can produce errors, warnings, or messages if requested.

Usage

check_attached_packages(action = "warn", allow_attached_packages = NULL)

Arguments

action

Behavior to take if the status is not clean. Possible values are "error", "warn", "message", and "none". The default is action = "warn".

allow_attached_packages

Character vector containing names of packages that are "allowed", and will not trigger an action if attached to the search path.

Details

This checker inspects the list of packages that have been attached to the search path (e.g., via library()). Regardless of the value of allow_attached_packages, R packages that have "base" priority (e.g., base, utils, and grDevices) do not trigger an action. When allow_attached_packages = NULL these are the only packages that will not trigger actions.

Value

Invisibly returns an object of class sessioncheck_status.

See Also

check_loaded_namespaces(), check_globalenv_objects(), check_attached_environments(), check_sessiontime(), check_required_options(), check_required_locale(), check_required_sysenv()

Examples

check_attached_packages(action = "message")

Check global environment objects

Description

Individual session check functions that inspect the contents of the global environment and the names of attached non-package environments. Session checkers can produce errors, warnings, or messages if requested.

Usage

check_globalenv_objects(action = "warn", allow_globalenv_objects = NULL)

Arguments

action

Behavior to take if the status is not clean. Possible values are "error", "warn", "message", and "none". The default is action = "warn".

allow_globalenv_objects

Character vector containing names of objects that are "allowed", and will not trigger an action.

Details

This checker inspects the state of the global environment and takes action based on the objects found there. When allow_globalenv_objects = NULL, variables in the global environment will not trigger an action if the name starts with a dot. For example, .Random.seed and .Last.value do not trigger actions by default.

Value

Invisibly returns an object of class sessioncheck_status.

See Also

check_attached_packages(), check_loaded_namespaces(), check_attached_environments(), check_sessiontime(), check_required_options(), check_required_locale(), check_required_sysenv()

Examples

check_globalenv_objects(action = "message")

Check loaded namespaces

Description

Individual session check function that inspects the loaded namespaces. Session checkers can produce errors, warnings, or messages if requested.

Usage

check_loaded_namespaces(action = "warn", allow_loaded_namespaces = NULL)

Arguments

action

Behavior to take if the status is not clean. Possible values are "error", "warn", "message", and "none". The default is action = "warn".

allow_loaded_namespaces

Character vector containing names of packages that are "allowed", and will not trigger an action if loaded via namespace.

Details

This checker inspects the list of loaded namespaces (packages that have been loaded but not attached). Regardless of the value of allow_loaded_namespaces, R packages that have "base" priority (e.g., base, utils, and grDevices) do not trigger an action, nor does the sessioncheck package itself, since the package namespace must be loaded in order to call the function.

Value

Invisibly returns an object of class sessioncheck_status.

See Also

check_attached_packages(), check_globalenv_objects(), check_attached_environments(), check_sessiontime(), check_required_options(), check_required_locale(), check_required_sysenv()

Examples

check_loaded_namespaces(action = "message")

Check required values for locale settings

Description

Individual session check function that inspects the locale settings. Session checkers can produce errors, warnings, or messages if requested.

Usage

check_required_locale(action = "warn", required_locale = NULL)

Arguments

action

Behavior to take if the status is not clean. Possible values are "error", "warn", "message", and "none". The default is action = "warn".

required_locale

A named list of required locale settings. If any of these are missing or have different values to the required values, an action is triggered.

Value

Invisibly returns an object of class sessioncheck_status.

See Also

check_attached_packages(), check_loaded_namespaces(), check_globalenv_objects(), check_attached_environments(), check_sessiontime(), check_required_options(), check_required_sysenv()

Examples

check_required_locale(action = "message", required_locale = list(LC_TIME = "en_US.UTF-8"))

Check required values for options

Description

Individual session check function that inspects the options. Session checkers can produce errors, warnings, or messages if requested.

Usage

check_required_options(action = "warn", required_options = NULL)

Arguments

action

Behavior to take if the status is not clean. Possible values are "error", "warn", "message", and "none". The default is action = "warn".

required_options

A named list of required options. If any of these options are missing or have different values to the required values, an action is triggered.

Value

Invisibly returns an object of class sessioncheck_status.

See Also

check_attached_packages(), check_loaded_namespaces(), check_globalenv_objects(), check_attached_environments(), check_sessiontime(), check_required_locale(), check_required_sysenv()

Examples

check_required_options(action = "message", required_options = list(scipen = 0L, max.print = 50L))

Check required values for system environment variables

Description

Individual session check function that inspects system environment variables. Session checkers can produce errors, warnings, or messages if requested.

Usage

check_required_sysenv(action = "warn", required_sysenv = NULL)

Arguments

action

Behavior to take if the status is not clean. Possible values are "error", "warn", "message", and "none". The default is action = "warn".

required_sysenv

A named list of required system environment variables. If any of these variables are missing or have different values to the required values, an action is triggered.

Value

Invisibly returns an object of class sessioncheck_status.

See Also

check_attached_packages(), check_loaded_namespaces(), check_globalenv_objects(), check_attached_environments(), check_sessiontime(), check_required_options(), check_required_locale()

Examples

check_required_sysenv(action = "message", required_sysenv = list(R_TEST = "value"))

Check session run time

Description

Individual session check function that inspects the session run time information. Session checkers can produce errors, warnings, or messages if requested.

Usage

check_sessiontime(action = "warn", max_sessiontime = NULL)

Arguments

action

Behavior to take if the status is not clean. Possible values are "error", "warn", "message", and "none". The default is action = "warn".

max_sessiontime

Maximum session time permitted in seconds before the checker takes action

Value

Invisibly returns an object of class sessioncheck_status.

See Also

check_attached_packages(), check_loaded_namespaces(), check_globalenv_objects(), check_attached_environments(), check_required_options(), check_required_locale(), check_required_sysenv()

Examples

check_sessiontime(action = "message")

Coerce session check object to a data frame

Description

Coerce session check object to a data frame

Usage

## S3 method for class 'sessioncheck_status'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'sessioncheck_sessioncheck'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

x

An object of class sessioncheck_status or sessioncheck_sessioncheck

row.names

Ignored

optional

Ignored

...

Ignored

Value

A data frame

Format and print sessioncheck objects

Description

Format and print sessioncheck objects

Usage

## S3 method for class 'sessioncheck_status'
format(x, ...)

## S3 method for class 'sessioncheck_sessioncheck'
format(x, ...)

## S3 method for class 'sessioncheck_status'
print(x, ...)

## S3 method for class 'sessioncheck_sessioncheck'
print(x, ...)

Arguments

x

An object of class sessioncheck_status or sessioncheck_sessioncheck

...

Ignored

Value

Character vector

Checks the overall status of the R session

Description

Individual session check functions that each inspect one way in which an R session could be considered not to be "clean". Session checkers can produce errors, warnings, or messages if requested.

Usage

sessioncheck(action = NULL, checks = NULL, ...)

Arguments

action

Behavior to take if the status is not clean. Possible values are "error", "warn", "message", and "none". If the user does not specify an action the default to set action = "warn".

checks

Character vector listing the checks to run. If the user does not specify the checks, the default is to run checks = c("globalenv_objects", "attached_packages", "attached_environments").

...

Arguments passed to individual checks.

Details

sessioncheck() allows the user to apply multiple session checks in a single function. The following arguments are recognized via ...:

Other arguments are ignored.

Value

Invisibly returns an object of class sessioncheck_sessioncheck.

Examples

sessioncheck(action = "message")