Vim as a Simple (R) IDE without Plugins II

1 Introduction

This post is a sequel to Vim as a Simple IDE without Plugins. There we showed how to send text from an open file in Vim to a console running another buffer in the same Vim session. This lets us step through scripts in R, Python, Julia, etc interactively without having to start a full IDE like Rstudio, or even necessarily be in a graphical environment - we just need a terminal session.

In this post, we make a simple popup menu to work with R packages. If our current working directory is within an R package, the menu will allow us to build & install the package, generate its documentation, run a CRAN check, etc. That will take place in a terminal buffer running in the same Vim session. This post is specific to R, but the pattern might extend to other languages.

The complete code is given in a vimrc file; this also includes the material from the prequel. As before, you can copy or import the contents into your own vimrc file to make use of them.

The final result is demonstrated in Figure 1, where the following sequence is shown.

1. Initially start Vim in a folder which is not an R package and see an alert when we try to bring up the menu.
2. Exit Vim and change to another folder that is part of a package.
3. Start Vim, try to build the package documentation, but get informed that no R terminal is running.
4. Start an R terminal in Vim and exchange windows so that terminal is on the right side of the screen.
5. Build package documentation and PDF manual using the menu.
6. Run a line from the script window to view a manual page from the package.
7. Switch focus to the terminal, close the manual page, and exit the session.

Figure 1: Demonstration.

2 Are we in an R Package?

Suppose our current working directory is /path/to/folder. To determine whether we are in an R package, we check for the existence of a DESCRIPTION file in the current directory; if found, that will be considered the root of the project. Otherwise, we repeat the check in the parent directory /path/to. We proceed this way until we reach / where there are no more parents to check. This follows the idea from the find_package_root function in the desc R package.

The following Vimscript function carries this out.

function! RProjectRoot(path) abort
    let path = a:path
    let done = v:false

    while done == v:false
        let ff = expand(path) . "/" . 'DESCRIPTION'

        if filereadable(ff)
            return path
        endif

        let newpath = fnamemodify(path, ':h')
        let done = (newpath == path)
        let path = newpath
    endwhile

    throw "Not within an R project: " . a:path
endfunction

The fnamemodify function is used to obtain the parent directory of the current path. If the argument path is the root, the result newpath will also be the root, and we have nothing else to check. An exception is thrown if we cannot find any DESCRIPTION file when we reach the root directory.

3 Menu Operations and R Functions

If we determine that we are in an R package, our menu will carry out selected actions via corresponding calls to the R devtools package. This mapping is shown in Table 1.

Table 1: Menu operations and corresponding devtools functions.

Action	Function
Load	load_all
Install	install_local
Document	document
Test	test
Clean	clean_dll
Manual	build_manual
Vignettes	build_vignettes
Build Source	build with binary = FALSE
Build Binary	build with binary = TRUE
Check	check

4 Menu in Vim

For the Vim menu, we will use the popup_menu function. It takes an array of menu options and a dictionary of additional named arguments. We will set two named arguments: the title of the menu and a handler. The handler is another function that is called when an item is selected in the menu; its job is to take the selection and carry out the desired action. Both of these functions are defined within an RProjectMenu function, is invoked to bring up the menu.

The following snippet is an abridged version of RProjectMenu, which can be seen in vimrc. The MenuHandler function is somewhat long, so the contents are summarized as comments.

function! RProjectMenu() abort
    function! MenuHandler(id, idx)
        " 1. Get the selected menu item
        " 2. Call RProjectRoot to see if we are in an R project; if so,
        "    get the path to the root. If not, print a message to the
        "    user and return.
        " 3. Form a string with the corresponding devtools command.
        " 4. See if there is a terminal running R. If not, alert the
        "    user and return.
        " 5. If we made it this far, send command to the terminal
        "    running R.
    endfunction

    try
        let projroot = RProjectRoot(getcwd())
    catch /.*/
        echom v:exception
        return
    endtry

    let items = [ 'Load', 'Install', 'Document', 'Test', 'Clean', 'Manual',
    \ 'Vignettes', 'Build Source', 'Build Binary', 'Check' ]

    let args = #{
    \ title: 'R Project: ' . pathshorten(expand(projroot)),
    \ callback: 'MenuHandler'
    \ }

    call popup_menu(items, args)
endfunction

Note

In our implementation, we look for a terminal by name using the function call bufnr('R'). The 'R' name will be set if we start the terminal using the method developed in the prequel post, or if we start it manually via :term('R') or :vert term('R'). These actions start a dedicated terminal for R which will exit when the R session ends.

It is also possible to repurpose a running terminal by changing its buffer name. To do this, take the following steps.

1. Change focus to the terminal window.
2. Enter terminal-normal mode using keystrokes <c-\><c-n> (Ctrl-\ then Ctrl-n).
3. Enter the command :file R'.
4. Type i to return to terminal-insert mode

5 Keybinding

We can set a keybinding to easily call the menu. In the prequel post, we set the <leader> key to space bar. Here we set <leader>r (i.e., <space> then r) as the binding to invoke the menu.

nnoremap <silent> <leader>r :call RProjectMenu()<cr>

We should now be able to use the menu as in Figure 1.