Overview

Code snippets are text macros that are used for quickly inserting common snippets of code. For example, the fun snippet inserts an R function definition:

Snippet Completion

If you select the snippet from the completion list, it will be inserted along with several text placeholders which you can fill in by typing and then pressing Tab to advance to the next placeholder:

Snippet Insertion

Other useful snippets include:

  • lib, req, and source for the library(), require(), and source() functions,

  • df and mat for defining data frames and matrices,

  • if, el, and ei for conditional expressions,

  • apply, lapply, sapply, etc. for the apply family of functions,

  • sc, sm, and sg for defining S4 classes/methods.

Snippets are a great way to automate the insertion of commonly used code, and are available for R, C/C++, JavaScript, and several other languages.

Inserting Snippets

As illustrated above, code snippets show up alongside other code completion results and can be inserted by picking them from the completion list. By default, the completion list will show up automatically when you pause typing for 250 milliseconds and can also be manually activated via the Tab key. In addition, if you have typed the character sequence for a snippet and want to insert it immediately (without going through the completion list), you can press Shift+Tab.

Note that for Markdown snippets within R Markdown documents, you always need to use the Shift+Tab sequence as there is no standard tab completion available within the Markdown editing mode.

Customizing Snippets

You can edit the built-in snippet definitions and even add snippets of your own via the Edit Snippets button in Global Options -> Code:

Snippet Editing

Custom snippets are defined using the snippet keyword. The contents of the snippet should be indented below using the Tab key (rather than with spaces). Variables can be defined using the form {1:varname}. For example, here’s the definition of the setMethod() snippet:

snippet sm
    setMethod("${1:gen}", ${2:"class"}, function(${3:obj}, ...) {
        ${0}
    })

Because $ is used as a special character to denote where the cursor should jump after completing each section of a snippet, in order to insert a literal $ it must be escaped as \$.

Executing R Code

You can also run R code in your snippet. You can use `r expr` anywhere in your snippet; your R code will be executed when the snippet is expanded, and the result inserted into the document. For example, the following snippet can be used to insert a timestamp based on the output of the R date() function:

snippet ts
  `r paste("#", date(), "------------------------------

You can also, as of RStudio v0.99.706, pass the text following the cursor into a snippet, using $$. For example, the following snippet could be used to evaluate an expression following an ! (note that this is not part of the default set of RStudio snippets):

snippet !
  `r eval(parse(text = "$$"))`

If you type !rnorm(5)<Shift-Tab>, you should see the output of running rnorm(5) inserted into the editor. Be careful not to run code that could hang or freeze your R session!

Saving and Sharing Snippets

Once you’ve customized snippets for a given language, they are written into the ~/.R/snippets directory. For example, the customized versions of R and C/C++ snippets are written to:

~/.R/snippets/r.snippets
~/.R/snippets/c_cpp.snippets

You can edit these files directly to customize snippet definitions or you can use the Edit Snippets dialog as described above. If you need to move custom snippet definitions to another system, then simply place them in ~/.R/snippets and they’ll be used in preference to the built-in snippet definitions.