README.Rmd

---
output: github_document
---

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

# inlineOutputAddin

<!-- badges: start -->
<!-- Add badges here later (CRAN, R-CMD-check, etc.) -->
<!-- badges: end -->

`inlineOutputAddin` provides an RStudio addin that evaluates selected R code and inserts or updates a marked, commented output block directly in an `.R` script.

This makes plain R scripts behave a bit like lightweight notebooks, while remaining standard `.R` files.

## Installation

You can install the development version from GitHub:

```{r eval=FALSE}
# install.packages("pak")
pak::pak("danielrak/inlineOutputAddin")
```

Or using `remotes`:

```{r eval=FALSE}
remotes::install_github("danielrak/inlineOutputAddin")
```

## What It Does

Given code like:

```r
head(mtcars)
```

Running the addin inserts (or updates) a marked output block:

```r
head(mtcars)
# >>> output
#                    mpg cyl disp  hp drat    wt  qsec vs am gear carb
# Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
# ...
# <<< output
```

If the code changes and the addin is run again, the existing output block is automatically replaced.

## How to Use

1. Open an `.R` script in RStudio.
2. Select code (or place the cursor on a single line).
3. Run the addin:

   - Via **Addins → Update Inline Output**
   - Or assign a keyboard shortcut in:
     `Tools → Modify Keyboard Shortcuts`

The function evaluates the code in the global environment and:

- Inserts a new output block if none exists
- Replaces the existing `# >>> output` / `# <<< output` block if present

Because evaluation happens in the global environment, objects you create
persist between runs. A plain assignment prints nothing in the console, so
(just like running it there) the addin adds no output block and simply runs
the code. The object is then available for the next run:

```r
df <- data.frame(x = 1:3, y = c("a", "b", "c"))   # runs; no output block added

nrow(df)   # df is still available on the next run
# >>> output
# [1] 3
# <<< output
```

The addin works with most common analysis code, including:

- Multi-line expressions (the whole top-level call is evaluated)
- Both the native pipe `|>` and the magrittr pipe `%>%` (when you have
  attached magrittr, e.g. via `library(magrittr)` or `library(dplyr)`)
- `print()` output, `cat()` output, messages and warnings
- Errors, which are reported inside the block rather than interrupting you

## Output Markers

The addin uses the following markers:

```
# >>> output
# <<< output
```

Everything between them is treated as generated output and may be replaced on the next run.

## Notes

- The addin requires **RStudio**.
- It captures printed console output.
- Long outputs are truncated for readability (`max_lines`).
- ggplot/grid plots are drawn in the Plots pane and recorded as a
  `<plot rendered>` placeholder in the block.
- It does not modify code outside the marked output block.

## Example (Non-interactive)

Because this functionality depends on RStudio, examples are guarded:

```{r}
if (rstudioapi::isAvailable()) {
  # dscript()
}
```

## Motivation

Plain `.R` scripts are often preferred in institutional or production settings.  
This addin provides a lightweight way to keep code and results together without switching to R Markdown or Quarto.

## License

MIT © Daniel Rakotomalala