rscontract

Intro

Makes it easier for other R packages or R projects to integrate with the RStudio Connections Contract. It provides several options to describe the structure of your connection. One of the options provided by rscontract is to use a YAML file that can contain the structure of the connection, and easily convert that into a proper RStudio Connections contract with a couple of lines of code:


Functions

It provides two levels of integration abstraction with the Connections pane:

  1. rscontract_spec() (higher) - Enables the user to pass a hierarchical list to describe the structure of the connection (catalog/schema/table). The defaults are setup so you can open a very simple connection without changing any arguments. The idea is to allow you to easily iterate through small argument changes as you are learning how the Connection pane works.
  2. rscontract_ide() (lower) - The arguments of this function matches one-to-one with the expected entries needed to open a Connection pane.

The as_rscontract() function converts a variable into the same format that rscontract_ide() returns. This makes it possible for objects such as lists returned by yaml::read_yaml() to work.

There are three functions that actually interact with the RStudio IDE:

  1. rscontract_open() - Opens the Connection pane. It requires a properly formatted Connections pane provided by the rscontract_spec(), rscontract_ide(), or as_rscontract() functions.
  2. rscontract_update() - Refreshes the already opened Connections pane
  3. rscontract_close() - Closes the Connections pane.

Installation

You can install the development version from GitHub with:

Examples

Basic example

The stock output of rscontract_spec() is loaded into a variable spec. This way it is possible to display its contents before using it to open a new connection.

library(rscontract)

The connection can now be opened with spec.

Notice above the values of the type and host entries inside spec. Those are the two pieces of information needed by RStudio to identify the connection that needs to be updated, or closed.


rscontract comes with a basic example accessible via the sample_catalog() function. By default, rscontract_spec() uses sample_catalog() in the object_types entry to automatically give you working sample Connections pane.

rscontract_update("spec_host", "spec_type")

After closing the connection, the content from the connect_script variable can be seen.

rscontract_close("spec_host", "spec_type")


Modified spec

To start creating your own connection setup, simply modify the arguments in rscontract_spec() that you wish to test. Here is an example of a few modifications that are possible to make:


Action buttons

The Connections pane also give you the ability to add custom buttons at the top of the pane. These can be setup to run a specific R instruction once clicked. To add them simply modify the action entry in the spec. In the example below, “hello” is sent to the R Console when ‘Button 1’ is clicked.

spec$actions <- list(
  "Button 1" = list(
    icon = system.file("images", "rstudio-icon.png", package = "rscontract"),
    callback = function() print("hello")
  )
)

rscontract_open(spec)


To add flexibility, wrap the list preparation inside a function:

spec_function <- function(x, message) {
  x$actions <- list(
  "Button 1" = list(
    icon = system.file("images", "rstudio-icon.png", package = "rscontract"),
    callback = function() print(message)
  ))
  x
}

rscontract_open(spec_function(spec, "test"))
rscontract_close("my_host", "my_type")

From a file

A YAML file can be used to create the connection. The structure and name of each field has to match to what is expected by rscontract. The example below shows a basic example of the names and the expected type of input. By default, the content in the following fields will be evaluated is if it was R code:

  • disconnect_code
  • preview_code

Here is an sample file included as part of the rscontract package:

The key of using a YAML file, is to coerce it into a contract format using as_rscontract(). Then use rscontract_open() to start the connection.