facilitate user extension of break_chain

may fix #15

.Rbuildignore

@@ -4,3 +4,5 @@
 ^\.github$
 ^\.vscode$
 ^\.devcontainer
+^.*\.Rproj$
+^\.Rproj\.user$

.devcontainer/devcontainer.json

@@ -5,7 +5,7 @@
 	"build": {
 		"dockerfile": "Dockerfile",
 		// Update VARIANT to pick a specific R version: latest, ... ,4.0.1 , 4.0.0
-		"args": { "VARIANT": "devel" }
+		"args": { "VARIANT": "4.1.0" }
 	},
 
 	// Set *default* container specific settings.json values on container create.

.gitignore

@@ -0,0 +1,5 @@
+.Rproj.user
+.Rhistory
+.RData
+.Ruserdata
+*.Rproj

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: breakerofchains
 Title: Break Chained Expressions and Run Them with Printed Output
-Version: 0.2.2
+Version: 0.3.0
 Authors@R: 
     person(given = "Miles",
            family = "McBain",
@@ -15,7 +15,7 @@ Description: Run an infix operator expression chain up to the line your
 License: MIT + file LICENSE
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.1.1
+RoxygenNote: 7.1.2
 Suggests: 
     testthat (>= 3.0.0)
 Config/testthat/edition: 3

NEWS.md

@@ -0,0 +1,23 @@
+# 0.3.0
+
+`break_chain()` is now extendable by developers. It returns the result of chain
+evaluation invisibly, so that you can handle the result as you choose with a new
+shortcut, e.g. `View(break_chain())`. Also in aid of this, printing and
+assigning the result of evaluation can be disabled via arguments, e.g. : 
+
+`View(break_chain(print_result = FALSE, assign_result = FALSE))`
+
+For RStudio users, probably the best way to quickly build a custom chain result
+handler is via the excellent `{shrtcts}` package. You could put something like
+this in your `~/shrtcts.R`:
+
+```{r}
+#' View broken chain
+#'
+#' @interactive
+function() {
+  View(breakerofchains::break_chain(print_result = FALSE, assign_result = FALSE))
+}
+```
+
+Thanks to @chorgan182 for giving me the idea for this in [#15](https://github.com/MilesMcBain/breakerofchains/issues/15)

R/chain_break.R

@@ -19,8 +19,19 @@
 #'
 #' It is unlikely you want to run this function directly. You probably want to
 #' bind it to a keyboard shortcut. See README for more information.
+#' 
+#' Developers: You can create addins / shortcuts that treat the result of chain evaluation differently
+#' by wrapping this function. e.g. `view(break_chain())` The parameters of this
+#' function are inteded to be useful for this e.g.
+#' `view(break_chain(print_result = FALSE))`
+#' @param print_result Enable/disable printing of chain evaluation result in console.
+#'   Useful when wrapping this function to display results in a custom way.
+#' @param assign_result assign the result of chain evaluation to `.chain` in Global environment?
 #' @export
-break_chain <- function() {
+#' @return the result of chain execution invisibly
+break_chain <- function(
+    print_result = TRUE, 
+    assign_result = getOption("breakerofchains_store_result", TRUE)) {
     doc_context <- rstudioapi::getActiveDocumentContext()
 
     doc_lines <- doc_context$contents
@@ -36,10 +47,10 @@ break_chain <- function() {
 
     calling_env <- parent.frame()
     .chain <- eval(parse(text = broken_chain), envir = calling_env)
-    print(.chain)
+    if (print_result) print(.chain)
 
-    if (getOption("breakerofchains_store_result", TRUE)) assign(".chain", .chain, .GlobalEnv)
-    invisible()
+    if (assign_result) assign(".chain", .chain, .GlobalEnv)
+    invisible(.chain)
 }
 
 

README.Rmd

@@ -110,3 +110,9 @@ 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.

README.md

@@ -39,22 +39,20 @@ star_plot <-
   geom_point()
 ```
 
-1.  Pop your cursor on line you want to run up to. e.g. `select(height,
-    mass)`.
+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:
 
-<!-- end list -->
-
 ``` r
 starwars %>%
   group_by(species, sex) %>%
   select(height, mass)
 #> Adding missing grouping variables: `species`, `sex`
-#> # A tibble: 87 x 4
+#> # A tibble: 87 × 4
 #> # Groups:   species, sex [41]
 #>    species sex    height  mass
 #>    <chr>   <chr>   <int> <dbl>
@@ -96,16 +94,14 @@ 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)`
+Disable this behaviour with
+`options(breakerofchains_store_result = FALSE)`
 
 ## Keybindings
 
-  - RStudio: [addins can be bound to keys using the keybinding
+-   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:
-
-<!-- end list -->
+-   VSCode: create a binding for your `keybindings.json` like:
 
 ``` json
 [
@@ -126,3 +122,10 @@ 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.