orderly_plugin_context: Fetch plugin context

Description

Fetch the running context, for use within a plugin. The intention here is that within free functions that your plugin makes available, you will call this function to get information about the state of a packet. You will then typically call orderly_plugin_add_metadata() afterwards.

Usage

orderly_plugin_context(name, envir)

Value

A list with elements:

is_active: a logical, indicating if we're running under orderly_run(); you may need to change behaviour depending on this value.
path: the path of the running packet. This is almost always the working directory, unless the packet contains calls to setwd() or similar. You may create files here.
config: the configuration for this plugin, after processing with the plugin's read function (see orderly_plugin_register)
envir: the environment that the packet is running in. Often this will be the global environment, but do not assume this! You may read and write from this environment.
src: the path to the packet source directory. This is different to the current directory when the packet is running, but the same when the user is interactively working with a report. You may read from this directory but must not write to it
parameters: the parameters as passed through to the run the report.

Arguments

name: Name of the plugin
envir: The environment of the calling function. You can typically pass parent.frame() (or rlang::caller_env()) here if the function calling orderly_plugin_context() is the function that would be called by a user. This argument only has an effect in interactive use (where envir is almost certainly the global environment).

Details

When a plugin function is called, orderly will be running in one of two modes; (1) from within orderly_run(), in which case we're part way through creating a packet in a brand new directory, and possibly using a special environment for evaluation, or (2) interactively, with a user developing their report. The plugin needs to be able to support both modes, and this function will return information about the state to help you cope with either case.

Examples

Run this code

# The example code from vignette("plugins") is available in the package
fs::dir_tree(system.file("examples/example.db", package = "orderly"))

# See orderly_plugin_context in context here:
orderly_example_show("R/plugin.R", example = "example.db")