README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
library(dplyr)
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# breakerofchains <img src="inst/media/breakerofchains.png" align="right" width="300px"/>

<!-- badges: start -->
[![R-CMD-check](https://github.com/MilesMcBain/breakerofchains/workflows/R-CMD-check/badge.svg)](https://github.com/MilesMcBain/breakerofchains/actions)
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://www.tidyverse.org/lifecycle/#stable)
<!-- badges: end -->

Break your chain at the cursor line. Run the first bit. See the output. Be free.

## Installation

```{r eval = FALSE}
# install.packages("remotes")
remotes::install_github("MilesMcBain/breakerofchains")
```

## Usage

Say you had: 

```{r, eval = FALSE}
library(tidyverse)

star_plot <-
  starwars %>%
  group_by(species, sex) %>%
  select(height, mass) %>%
  summarise(
    height = mean(height, na.rm = TRUE),
    mass = mean(mass, na.rm = TRUE)
  ) %>%
  ggplot(aes(x = height, y = mass)) +
  geom_point()
```

1. Pop your cursor on line you want to run up to. e.g. `select(height, mass)`.

2. Invoke the RStudio Addin `Break chain and run to cursor`

3. Code is run from start of chain up to your cursor line, and result is printed in the console:

```{r}
starwars %>%
  group_by(species, sex) %>%
  select(height, mass)
```

```{r, echo = FALSE, include = FALSE}
.chain <-
  starwars %>%
  group_by(species, sex) %>%
  select(height, mass)
```
with a stored result available in `.chain`:

```{r}
glimpse(.chain)
```

For pipe chains Base pipe `|>` is supported, but chains can also be broken at lines ending in any
`%%` infix, and any math/logic infix. So you can break `ggplot2` layers
chained with `+` this way too.

## Stored result `.chain`

By default the result of the last broken chain is saved in your environment
as the variable `.chain` so you can immediately start passing it to further
diagnostics. I've found this is nicer than `.Last.value` which
is easy to accidentally overwrite, and has a hard to remember the capitalisation scheme.

Disable this behaviour with `options(breakerofchains_store_result = FALSE)`

## Keybindings

* RStudio: [addins can be bound to keys using the keybinding menu](https://www.infoworld.com/article/3327573/do-more-with-r-rstudio-addins-and-keyboard-shortcuts.html).
* VSCode: create a binding for your `keybindings.json` like:

```{json}
[
    {
        "description": "run breakerofchains",
        "key": "ctrl+shift+b",
        "command": "r.runCommand",
        "when": "editorTextFocus",
        "args": "breakerofchains::break_chain()"
    },
]
```

## Pitfalls

Since R's parser is used to help figure out where the chain starts, the
process will fail if any of the code above the cursor is invalid - even code
not in the chain. 

For Rmd documents only code in the current chunk is parsed.

## Extending it yourself

`break_chain()` returns the result of the chain evaluation invisibly, so you can
build your own shortcuts that do something with the result other than print it
to the console. E.g. `View(break_chain())` See `break_chain` and `NEWS.md` for more info.