Documentation Suggestion about tinsel

[nteetor]

re: interactive sourcing
In tinsel 0.0.2, currently living on the dev branch, I added an RStudio addin to allow interactive decoratee sourcing. This works similarly to running a highlighted piece of code with Cmd+Return (mac) or Ctrl+Enter (windows/linux). I hope to have 0.0.2 released mid December. In the mean time feel free to use the development version of tinsel. I would appreciate any feedback regarding the new addin.

re: package authorship
This is my big challenge going forward. In the long run, I want decorating functions to be seamless, not a cumbersome extra step in package development. I would love, for example, to have many of the devtools functions related to R package development understand decorated functions. However, re-writing these functions is not productive at the moment, not unless tinsel becomes widely adopted. Here is a temporary fix for including decorated functions in a package.

Create a file, in this case hello.R, as you would,

#' Make Function Output more Exciting
#'
#' Concatenates \code{'!!!'} onto the end of a function's return value.
#'
#' @param f A function to decorate.
#'
#' @keywords internal
#' @export
excite <- function(f) {
  function() {
    paste0(f(), '!!!')
  }
}

#' Hello, world!
#'
#' This is an example function named 'hello' which returns 'Hello, world!'.
#'
#' \subsection{decorated by:} {
#'
#' This function is decorated by \link{excite}.
#'
#' }
#' @export
#. excite
hello <- function() {
 "Hello, world!"
}

(the decorator comment will not interfere with the roxygen comments)

Now create a file to overwrite the default definition of hello. Let's call the second file overwrite.R,

# load decorated functions and overwrite existing undecorated definitions

tinsel::source_decoratees('R/hello.R')

Finally, make sure your DESCRIPTION file has a collate section and lists overwrite.R as the last file (or at least after the file(s) with the decorated functions),

Package: example
Type: Package
....
Collate:
    'hello.R'
    'overwrite.R'

When you build and reload the package, hello is decorated and produces the expected output,

> tinsel::is.decorated(hello)
[1] TRUE
> hello()
[1] "Hello, world!!!!"

Add additional decorated functions to overwrite.R. I hope this helps while a better solution is developed.

Decorated functions can be tested, but only if the decorators are in the same file or defined ahead of time. Adding an additional parameter to source_decoratees allowing the programmer to list file(s) which contain decorator definitions could prove beneficial, #6.

[nteetor]

I would recommend using the addin(s). As you say source_decoratees() is far from interactive, but the addin(s) make tinsel and decorated functions feel much more interactive. The addin to be released in 0.0.2 will expand upon this.

As I said there's plenty to do to make decorators a part of package development, but I hope you will continue to try out tinsel. I certainly appreciate the feedback. This is how tinsel will get better.

Cheers, Nate.

[nteetor]

@drknexus , are you using the RStudio addin currently provided by tinsel?

[russellpierce]

@nteetor I haven't yet, I was looking it over and deciding if and where it belonged in my toolbox. Certainly nice for things like memoising functions as a matter of course. The only other syntax-lite approach is something like...

(function(x) {x}) %>% memoise::memoise()

... but I like the decoration approach also.