Skip to contents

Get or set the local selenider session

Source: R/aaa_env.R
get_session.Rd

Change the locally defined selenider_session() object, allowing it to be used in functions like s() without explicitly providing it.

get_session() retrieves the current local session. If none have been created, a session is created automatically.

local_session() sets the local session. The function uses withr::defer() to make sure the session is closed and the local session is set to its previous value when it is no longer needed.

with_session() runs some code with a temporary local session. The session is closed and the local session is set to its previous value when the code finishes executing.

Usage

get_session(create = TRUE, .env = rlang::caller_env())

local_session(session, .local_envir = rlang::caller_env(), close = TRUE)

with_session(session, code, close = TRUE)

Arguments

create

If a session is not found, should we create a new one? If this is FALSE and a session is not found, NULL is returned.

.env

If get_session() creates a session, the environment where this session is being used.

session

The selenider_session() object to use.

.local_envir

The environment where the session is being used. When the function associated with this environment finishes execution, the session will be reset.

close

Should we close session when the local session is reset? Set this to FALSE if you want to use the session even if it is no longer the local session. If you want to close the session manually, use close_session().

code

The code to run with the local session set.

Value

get_session() returns the local selenider_session() object (or a newly created session).

local_session() returns the previous local session object (or NULL). This is the same as running get_session() before this function.

with_session() returns the result of code.

Details

Use withr::deferred_run() to reset any local sessions set using local_session().

See also

selenider_session(), which calls local_session() unless otherwise specified.

Examples

# Don't set the local session, since we want to do it manually.
session <- selenider_session(local = FALSE)

get_session(create = FALSE) # NULL

local_session(session, close = FALSE)

get_session(create = FALSE)

withr::deferred_run()

get_session(create = FALSE) # NULL

# By default, the local session is only set inside the function that it is
# called.
# If we want to set the local session outside the scope of a function, we
# need to use the `.local_envir` argument.
set_my_session <- function(env = rlang::caller_env()) {
  # caller_env() is the environment where the function is called.
  local_session(session, .local_envir = env, close = FALSE)
}

set_my_session()

with_session(
  session,
  {
    get_session(create = FALSE)
  },
  close = FALSE
)

get_session(create = FALSE)