*Nvim-R.txt* *Nvim-R* Nvim-R Plugin to work with R Authors: Jakson A. Aquino Jose Claudio Faria Version: 0.9.20 For Neovim >= 0.6.0 and Vim >= 8.2.84 1. Overview |Nvim-R-overview| 2. Main features |Nvim-R-features| 3. Installation |Nvim-R-installation| 4. Use |Nvim-R-use| 5. Known bugs and workarounds |Nvim-R-known-bugs| 6. Options |Nvim-R-options| 7. Custom key bindings |Nvim-R-key-bindings| 8. News |Nvim-R-news| ============================================================================== 1. Overview *Nvim-R-overview* This plugin improves the support for editing R code in Vim. It is available at: https://github.com/jalvesaq/Nvim-R The plugin should emit useful warnings if you do things it was not programmed to deal with. Please report critical bugs to: https://github.com/jalvesaq/Nvim-R/issues Pull requests fixing bugs are welcome. ============================================================================== 2. Main features *Nvim-R-features* * Additional syntax highlighting for R code, including: - Functions of loaded packages. - Special highlighting for R output (.Rout files). * Integrated communication with R: - Start/Close R. - Send lines, selection, paragraphs, functions, blocks, entire file. - Send commands with the object under cursor as argument: help, args, plot, print, str, summary, example, names. - Send to R the Sweave, knit and pdflatex commands. * Omni completion of: - R objects (.GlobalEnv and loaded packages). - function arguments (if R is running). - knitr chunk options. - Quarto cell options. * Limited support for debugging R functions. * Ability to see R's documentation in an editor buffer: - Automatic calculation of the best layout of the R documentation buffer (split the window either horizontally or vertically according to the available room). - Automatic formatting of the text to fit the panel width. - Send code and commands to R (useful to run examples). - Jump to another R documentation. - Syntax highlighting of R documentation. * Object Browser (.GlobalEnv and loaded packages): - Send commands with the object under cursor as argument. - Call R's `help()` with the object under cursor as argument. - Syntax highlighting of the Object Browser. * SyncTeX support for Rnoweb. * Most of the plugin's behavior is customizable. ============================================================================== 3. Installation *Nvim-R-installation* The installation process is described in four sections: 3.1. Installation of dependencies 3.2. Installation of the plugin 3.3. Troubleshooting 3.4. Optional steps ------------------------------------------------------------------------------ 3.1. Installation of dependencies Before installing the plugin, you should install its dependencies: Main dependencies: Vim >= 8.2.84: http://www.vim.org/download.php Vim must be compiled with |+channel|, |+job| and |+conceal| features. In Normal mode, do `:version` to check if your Vim has these features. or Neovim >= 0.6.0 https://github.com/neovim/neovim/releases See also: https://github.com/neovim/neovim/wiki/Installing-Neovim Also cmp-nvim-r if you want auto omni completion from Nvim-R: https://github.com/jalvesaq/cmp-nvim-r R >= 4.0.0: http://www.r-project.org/ Notes about the R package `nvimcom`: - The R package `nvimcom` is included in Nvim-R and is automatically installed and updated whenever necessary. The package requires compilation by a C compiler (e.g. `gcc` or `clang`). - You do not need to load nvimcom in your .Rprofile because the Nvim-R plugin sets the environment variable `R_DEFAULT_PACKAGES`, including `nvimcom` in the list of packages to be loaded on R startup. However, if you set the option `defaultPackages` in a .Rprofile, you should include "nvimcom" among the packages to be loaded (see |nvimcom-not-loaded|). - On Windows, you have to install Rtools to be able to build the package: https://cran.r-project.org/bin/windows/Rtools/ Additional dependencies for editing Rnoweb documents: latexmk: Automate the compilation of LaTeX documents. See examples in |R_latexcmd|. PDF viewer with SyncTeX support and capable of automatically reloading documents. This is required only if you edit Rnoweb files. On Linux and other Unix systems: Zathura (recommended), Evince or Okular. On OS X: Skim. On Windows: SumatraPDF. Suggestions for Unix (Linux, OS X, Cygwin, etc.): Tmux >= 3.0: http://tmux.sourceforge.net Tmux is required only if you want to run R in an external terminal emulator (see |R_external_term|). colorout: https://github.com/jalvesaq/colorout/releases Colorizes the R output in terminal emulators. (Mostly useful if running R in an external terminal emulator. See |R_external_term|). You should put in your Rprofile: `library(colorout)` If running Gnome Shell on Wayland, you may also want to install the extension "Activate Window By Title" which will be used to raise Zathura window displaying the PDF file generated from Rnoweb, Rmd or Quarto documents. Suggestions for bibliographic completion from Zotero: For RMarkdown (`.Rmd`) and Quarto (`.qmd`) documents: - https://github.com/jalvesaq/zotcite - https://github.com/jalvesaq/cmp-zotcite ------------------------------------------------------------------------------ 3.2. Installation of the plugin If you have a previous Vimball installation, you should uninstall it first: >vim :packadd vimball :RmVimball Nvim-R < Either use a plugin manager to install Nvim-R or follow the instructions on Vim |packages| to install the Nvim-R package (either the zip or the tar.gz file) released at: https://github.com/jalvesaq/Nvim-R/releases ------------------------------------------------------------------------------ 3.3. Troubleshooting (if the plugin doesn't work) Note: The is '\' by default. The plugin is a |file-type| plugin. It will be active only if you are editing a .R, .Rnw, .Rd, .Rmd, .Rrst or .qmd file. The key bindings will not be active while editing either unnamed files or files with name extensions other than the mentioned above: Hhowever, see: https://github.com/jalvesaq/Nvim-R/wiki/Enable-Nvim-R-for-any-file-type If the plugin is active, pressing rf should start R. Did you see warning messages but they disappeared before you have had time to read them? Type the command |:messages| in Normal mode to see them again. Run the command `:RDebugInfo` which will show information useful to fix some common issues. To see messages received by `nvimcom`, put in your `~/.Rprofile`: >r options(nvimcom.verbose = 5) < To see messages received by Vim, uncomment the first line of the function `ROnJobStdout()` at `R/nvimrcom.vim` and delete the string "DEBUG:". It will become: >vim call writefile(a:data, "/dev/shm/nvimrserver_stdout", "a") < Then, in another terminal or in another Tmux pane, you would have to use tail to follow the output: > tail -f /dev/shm/nvimrserver_stdout < If R does not start with the rf command and you get an error message instead, you may want to set the path to the R executable (see |R_path|). *nvimcom-not-loaded* If you see the following message in the R console: > During startup - Warning messages: 1: In library(package, lib.loc = lib.loc, character.only = TRUE, logical.return = TRUE, : there is no package called ‘nvimcom’ 2: package ‘nvimcom’ in options("defaultPackages") was not found < Try quitting both R and Vim and starting them again. If you still see the message "The package nvimcom wasn't loaded yet" after starting R, then Nvim-R could not induce R to load nvimcom. Nvim-R sets the environment variable `R_DEFAULT_PACKAGES` before starting R. If the variable already exists, the string ",nvimcom" is appended to it. However, if you set the option `defaultPackages` in your .Rprofile or in a .Rprofile in the current directory, the environment variable will be overridden. Thus, if you have to set the option `defaultPackages`, you should include "nvimcom" among the packages to be loaded. You might want to include "nvimcom" only if R was started by Nvim-R, as in the example below: >r if(Sys.getenv("NVIMR_TMPDIR") == ""){ options(defaultPackages = c("utils", "grDevices", "graphics", "stats", "methods")) } else { options(defaultPackages = c("utils", "grDevices", "graphics", "stats", "methods", "nvimcom")) } < Finally, run the command `:RDebugInfo` after rf and check the path where nvimcom was installed. On Windows, nvimcom compilation will fail if your `.Rprofile` outputs anything during R Startup. It will also fail with a message about `--slave` not being a `gcc` option if either `make.exe` or `gcc.exe` from RTools are not the first ones found in your systems' `PATH` (see |R_path| and |Rtools-path|). ------------------------------------------------------------------------------ 3.4. Optional steps The plugin should work without the need of any configuration right after installed, but if you do not like how the plugin works, you could look at the section |Nvim-R-options| to see if there is an option that could make you happier. You can also install additional plugins to get more useful functionality to edit R code. Please, access Nvim-R's wiki: https://github.com/jalvesaq/Nvim-R/wiki ============================================================================== 4. Use *Nvim-R-use* By default, Nvim-R will run R in a built-in terminal emulator, but you can change this behavior (see |R_external_term|). ------------------------------------------------------------------------------ 4.1. Key bindings Note: The is '\' by default. To use the plugin, open a .R, .Rnw, .Rd, .Rmd, .Rrst, or .qmd file with Vim and type rf. Then, you will be able to use the plugin key bindings to send commands to R. This plugin has many key bindings, which correspond with menu entries. In the list below, the backslash represents the . Not all menu items and key bindings are enabled in all file types supported by the plugin (r, rnoweb, rhelp, rrst, rmd, and quarto). Menu entry Default shortcut Start/Close . Start R (default) \rf . Start R (custom) \rc -------------------------------------------------------- . Close R (no save) \rq . Stop (interrupt) R :RStop ----------------------------------------------------------- Send . File \aa . File (echo) \ae . File (open .Rout) \ao -------------------------------------------------------- . Block (cur) \bb . Block (cur, echo) \be . Block (cur, down) \bd . Block (cur, echo and down) \ba -------------------------------------------------------- . Chunk (cur) \cc . Chunk (cur, echo) \ce . Chunk (cur, down) \cd . Chunk (cur, echo and down) \ca . Chunk (from first to here) \ch -------------------------------------------------------- . Function (cur) \ff . Function (cur, echo) \fe . Function (cur and down) \fd . Function (cur, echo and down) \fa -------------------------------------------------------- . Selection \ss . Selection (echo) \se . Selection (and down) \sd . Selection (echo and down) \sa . Selection (evaluate and insert output in new tab) \so -------------------------------------------------------- . Send motion region \m{motion} -------------------------------------------------------- . Paragraph \pp . Paragraph (echo) \pe . Paragraph (and down) \pd . Paragraph (echo and down) \pa -------------------------------------------------------- . Line \l . Line (and down) \d . Line (and new one) \q . Left part of line (cur) \r . Right part of line (cur) \r . Line (evaluate and insert the output as comment) \o . All lines above the current one \su ----------------------------------------------------------- Command . List space \rl . Clear console \rr . Remove objects and clear console \rm -------------------------------------------------------- . Print (cur) \rp . Names (cur) \rn . Structure (cur) \rt . View data.frame (cur) in new tab \rv . View data.frame (cur) in horizontal split \vs . View data.frame (cur) in vertical split \vv . View head(data.frame) (cur) in horizontal split \vh . Run dput(cur) and show output in new tab \td -------------------------------------------------------- . Arguments (cur) \ra . Example (cur) \re . Help (cur) \rh -------------------------------------------------------- . Summary (cur) \rs . Plot (cur) \rg . Plot and summary (cur) \rb -------------------------------------------------------- . Set working directory (cur file path) \rd -------------------------------------------------------- . Sweave (cur file) \sw . Sweave and PDF (cur file) \sp . Sweave, BibTeX and PDF (cur file) (Linux/Unix) \sb -------------------------------------------------------- . Knit (cur file) \kn . Knit, BibTeX and PDF (cur file) (Linux/Unix) \kb . Knit and PDF (cur file) \kp . Knit and Beamer PDF (cur file) \kl . Knit and HTML (cur file, verbose) \kh . Knit and ODT (cur file) \ko . Knit and Word Document (cur file) \kw . Markdown render (cur file) \kr . Markdown render [all in YAML] (cur file) \ka . Spin (cur file) (only .R) \ks -------------------------------------------------------- . Quarto render (cur file) \qr . Quarto preview (cur file) \qp . Quarto stop preview (all files) \qs -------------------------------------------------------- . Open attachment of reference (Rmd, Rnoweb) \oa . Open PDF (cur file) \op . Search forward (SyncTeX) \gp . Go to LaTeX (SyncTeX) \gt -------------------------------------------------------- . Debug (function) \bg . Undebug (function) \ud -------------------------------------------------------- . Build tags file (cur dir) :RBuildTags ----------------------------------------------------------- Edit . Insert "<-" _ . Complete object name CTRL-X CTRL-O -------------------------------------------------------- . Go (next R chunk) \gn . Go (previous R chunk) \gN ----------------------------------------------------------- Object Browser . Open/Close \ro . Expand (all lists) \r= . Collapse (all lists) \r- . Toggle (cur) Enter ----------------------------------------------------------- Help (plugin) Help (R) :Rhelp ----------------------------------------------------------- Please see |Nvim-R-key-bindings| to learn how to customize the key bindings without editing the plugin directly. The plugin commands that send code to R Console are the most commonly used. If the code to be sent to R has a single line it is sent directly to R Console. If it has more than one line (a selection of lines, a block of lines between two marks, a paragraph etc) the lines are written to a file and the plugin sends to R the command to source the file. To send to R Console the line currently under the cursor you should type d. If you want to see what lines are being sourced when sending a selection of lines, you can use either se or sa instead of ss. The m{motion} command sends the lines from the motion command that follows m, e.g. m} (from the current line to the end of paragraph) or m3j (the next 3 lines including the current line). If the cursor is between manually inserted marks, the plugin will send the lines between them to R if you press bb. If the cursor is above the first mark, the plugin will send from the beginning of the file to the mark. If the cursor is below the last mark, the plugin will send from the mark to the end of the file. The mark above the cursor is included and the mark below is excluded from the block to be sent to R. To create a mark, press m in Normal mode (see |mark|). For example, consider the following code (with line numbers): > 1 2 x <- 3 3 y <- 2 4 5 z <- x + y 6 In Normal mode, go to line 1 and press `ma`; go to line 6 and press `mb`; go to line 4 and press `bb` to send lines 1 to 5 to R. Normally, Vim marks are not visible, but there are plugins that highlight them. You can also use the command `:RSend` to type and, then, send a line of code to R. If you use this command frequently, you may consider creating a map for it in your |vimrc|. For example: >vim nmap : :RSend < Observe that there is an empty space after `:RSend`, so you do not have to type it. The command o runs in the background the R command `print(line)`, where `line` is the line under the cursor, and adds the output as commented lines to the source code. If the cursor is over the header of an R chunk with the `child` option (from Rnoweb, RMarkdown, Quarto or RreStructuredText document), and you use one of the commands that send a single line of code to R, then the plugin will send to R the command to knit the child document. After the commands that send, sweave or knit the current buffer, Vim will save the current buffer if it has any pending changes before performing the tasks. After ao, Vim will run "R CMD BATCH --no-restore --no-save" on the current file and show the resulting .Rout file in a new tab. Please see |R_routnotab| if you prefer that the file is open in a new split window. Note: The command ao, silently writes the current buffer to its file if it was modified and deletes the .Rout file if it exists. R syntax uses " <- " to assign values to variables which is inconvenient to type. In insert mode, typing a single underscore, "_", will write " <- ", unless you are typing inside a string. The replacement will always happen if syntax highlighting is off (see |:syn-on| and |:syn-off|). If necessary, it is possible to insert an actual underscore into your file by typing a second underscore. This behavior is similar to the EMACS ESS mode some users may be familiar with and is enabled by default. You have to change the value of |R_assign| to disable underscore replacement. When you press rh, the plugin shows the help for the function under the cursor. The plugin also checks the class of the first object passed as argument to the function to try to figure out whether the function is a generic one and whether it is more appropriate to show a specific method. The same procedure is followed with rp, that is, while printing an object. For example, if you run the code below and, then, press rh and rp over the two occurrences of `summary`, the plugin will show different help documents and print different function methods in each case: >r y <- rnorm(100) x <- rnorm(100) m <- lm(y ~ x) summary(x) summary(m) < Nvim-R will not check the class of the first object if the `=` operator is present. For example, in the two cases below you would get the generic help for `summary`: >r summary(object = x) summary(object = m) < To get help on an R topic, you can also type in Vim (Normal mode): >vim :Rhelp topic < The command may be abbreviated to `:Rh` and you can either press to trigger the autocompletion of R objects names or hit CTRL-D to list the possible completions (see |cmdline-completion| for details on the various ways of getting command-line completion). The list of objects used for completion is the same available for omni completion (see |R_start_libs|). You may close the R documentation buffer by simply pressing `q`. The command td will run `dput()` with the object under cursor as argument and insert the output in a new tab. The command rv will also run `dput()` with the object under cursor as argument and show the output in a new tab, while vs will show it in a horizontal split, and vv will show it in a vertical split. However, if the object under the cursor is a data.frame or a matrix, instead of displaying the output of `dput()`, the commands will save the data.frame or matrix in a text file with values separated by tab characters and display this file. The command vh will show the `head()` of the data.frame or matrix in a horizontal split that opens above the current window. This behavior can be customized, and you can configure Nvim-R to call an external application to display the data.frame or matrix (see |Nvim-R-df-view|). All files involved in these operations are created in Nvim-R's temporary directory and deleted when R quits. You can source all .R files in a directory with the Normal mode command `:RSourceDir`, which accepts an optional argument (the directory to be sourced). In Normal mode `:RStop` sends to R SIGINT which is the same signal sent when you press CTRL-C into R's Console. If R does not quit normally, you can kill it with the `:RKill` command. ------------------------------------------------------------------------------ *:Rinsert* *:Rformat* The command `:Rinsert` inserts one or more lines with the output of the R command sent to R. By using this command we can avoid the need of copying and pasting the output R from its console to Vim. For example, to insert the output of `dput(levels(var))`, where `var` is a factor vector, we could do in Vim: >vim :Rinsert dput(levels(var)) < The output inserted by `:Rinsert` is limited to 5012 characters. The command `:Rformat` calls the function `style_text()` (if the package `styler` is installed) or the function `tidy_source()` (if the package `formatR` is installed) to format either the entire buffer or the selected lines. The command only works if R is running. If `style_text()` is used the value of 'shiftwidth' is passed as `indent_by`, and if `tidy_source()` is used, the value of the `width.cutoff` argument is set to the buffer's 'textwidth' if it is not outside the range 20-180. Se R help on `tidy_source` for details on how to control the function behavior. ------------------------------------------------------------------------------ 4.2. Editing Rnoweb files In Rnoweb files (.Rnw), when the cursor is over the `@` character, which finishes an R chunk, the sending of all commands to R is suspended and the shortcut to send the current line makes the cursor to jump to the next chunk. While editing Rnoweb files, the following commands are available in Normal mode: [count]gn : go to the next chunk of R code [count]gN : go to the previous chunk of R code You can also press gt to go the corresponding line in the generated .tex file (if SyncTeX is enabled). The commands cc, ce, cd and ca send the current chunk of R code to R Console. The command ch sends the R code from the first chunk up to the current line. The commands kn builds the .tex file from the Rnoweb one using the knitr package and kp compiles the pdf; for Sweave, the commands are, respectively sw and sp. You can jump from the Rnoweb file to the PDF (forward search) with the command gp. The command to jump from a specific location in the PDF to the corresponding line in the Rnoweb (backward search) is specific to each pdf viewer: Zathura: Evince: Okular: Skim: Sumatra: In any case, the pdf viewer must be started by the Nvim-R plugin. See |Nvim-R-SyncTeX| for details. ------------------------------------------------------------------------------ 4.3. Omni completion If `cmp-nvim-r` (a source for `nvim-cmp`) is installed, Neovim can automatically complete the names of R objects as you type them (but conventional Vim omni completion does not work if `cmp-nvim-r` is installed). Nvim-R does not complete the names of all functions of all installed packages (see |R_start_libs|). For both `library()` and `require()`, when completing the first argument, the popup list shows the names of installed packages. Vim uses one file to store the names of .GlobalEnv objects and a list of files for all other objects. The .GlobalEnv list is stored in the `$NVIMR_TMPDIR` directory and is deleted when you quit Vim. The other files are stored in the `$NVIMR_COMPLDIR` directory, are automatically updated and remain available unless you manually delete them. ------------------------------------------------------------------------------ 4.4. The Object Browser You have to use ro to either open or close the Object Browser on the same tab page. If it is already open on another tab page, it will be closed there and opened again in the current one. The Object Browser has two views: .GlobalEnv and Libraries. If you press on the first line of the Object Browser it will toggle the view between the objects in .GlobalEnv and the currently loaded libraries. In the .GlobalEnv view, if a data.frame column has the attribute "label", it will also be displayed. For instance, the code below would make the Object Browser display the variable labels of an imported SPSS dataset: >r library(foreign) d <- read.spss("/path/to/spss/dataset.sav", to.data.frame = TRUE) vlabs <- attr(d, "variable.labels") for(n in names(vlabs)) attr(d[[n]], "label") <- vlabs[[n]] < In the Object Browser window, while in Normal mode, you can either press or double click (GVim only) over a data.frame or list to show/hide its elements (not if viewing the content of loaded libraries). If you are running R in an environment where the string UTF-8 is part of either LC_MESSAGES or LC_ALL variables, Unicode line drawing characters will be used to draw lines in the Object Browser. This is the case of most Linux distributions. In the Libraries view, you can either double click or press on a library name to see its objects. In the Object Browser, the libraries have the color defined by the PreProc highlighting group. The other objects have their colors defined by the return value of some R functions. Each line in the table below shows a highlighting group and the corresponding type of R object: PreProc libraries Include environment Number numeric String character Special factor Boolean logical Type data.frame StorageClass list Structure s4 Function function Statement control flow (for, while, break, etc) Comment promise (lazy load object) One limitation of the Object Browser is that objects made available by the command `data()` are only links to the actual objects (promises of lazily loading the object when needed) and their real classes are not recognized in the GlobalEnv view. The same problem happens when the `knitr` option `cache.lazy=TRUE`. However, if you press over the name of the object in the Object Browser, it will be actually loaded by the command (ran in the background): >r obj <- obj < Notes: - If either the Object Browser is open or omni completion is enabled, the list of .GlobalEnv objects will be automatically updated by R after each successful evaluation of command. This may slowdown R if its workspace has too many objects, data.frames with too many columns or lists with too many elements (see |R_set_omnifunc|). - Names of objects are stupidly truncated if they occupy more than 62 bytes. This means that Unicode sequences might be split and become invalid. - Active bindings are not included in the list of objects for omni completion. Also, they are not included in the Object Browser. ------------------------------------------------------------------------------ 4.5. Build a tags file to jump to function definitions *RBuildTags* Vim can jump to functions defined in other files if you press CTRL-] over the name of a function, but it needs a tags file to be able to find the function definition (see |tags-and-searches|). The command `:RBuildTags` calls the R functions `rtags()` and `etags2ctags` to build the tags file for the R scripts in the current directory. ------------------------------------------------------------------------------ 4.6. Debugging R functions (Unix only) *debug-R-functions* The Nvim-R-Plugin has limited debugging facilities available on Unix systems (not available on Windows). To debug a function with Nvim-R you have to do the following: 1. Source the R script where the function is with the `source()` function of the `base` package. 2. In the R Console, run either `debug(funcname)` or `debugonce(funcname)` where `funcname` is the name of the function (not quoted). Nvim-R will send this command to R Console if you press db in Normal mode with the cursor over the function name. 3. Call the function. See `:Rh browser` for available commands in debugging mode. For example, if you have a file named `my_function.R` with the following contents: >r add.one <- function(x){ y <- x + 1 print(y) return(invisible(NULL)) } < You could debug the `add.one()` function from another script such as: >r source("path/to/my_function.R") debug(add.one) add.one(7) < If you do not want to start debugging the function from its first line, instead of calling `debug(funcname)` before calling the function, you should add the line `browser()` to the function at the line where the debugging session should start. Example: >r add.one <- function(x){ y <- x + 1 browser() print(y) return(invisible(NULL)) } < If you want a conditional breakpoint, you should call the `browser()` command only if a condition is satisfied. Example: >r add.one <- function(x){ y <- x + 1 if(x > 9) browser() print(y) return(invisible(NULL)) } < One limitation is that Nvim-R also does not help you setting breakpoints. You have to set them manually as explained above. Another limitation of Nvim-R is that it might be unable to jump to the line in the source code that is being evaluated if either you have sent the function directly to the R Console or the function has been sent by the `knitr` package, without calling the function `source()`. In either case, Nvim-R will try to find the pattern `funcname <- function(` in the buffer being edited. If the pattern is found, the cursor will jump to its position. The highlighting group used to highlight the line being debugged is the QuickFixLine (see |hl-QuickFixLine|). Its foreground and background colors are defined by your colorscheme, but you can change them in your |vimrc| (see |cterm-colors| and |gui-colors|). Example: >vim hi QuickFixLine ctermfg=231 ctermbg=23 guifg=white guibg=#005f5f < ------------------------------------------------------------------------------ 4.7. Syntax highlight of .Rout files You can set both foreground and background colors of R output in your `vimrc`. The example below is for either a GUI version of Vim or a terminal interface of Neovim with 'termguicolors' (see |true-color|): >r if has('gui_running') || &termguicolors let rout_color_input = 'guifg=#9e9e9e' let rout_color_normal = 'guifg=#ff5f00' let rout_color_number = 'guifg=#ffaf00' let rout_color_integer = 'guifg=#feaf00' let rout_color_float = 'guifg=#fdaf00' let rout_color_complex = 'guifg=#fcaf00' let rout_color_negnum = 'guifg=#d7afff' let rout_color_negfloat = 'guifg=#d6afff' let rout_color_date = 'guifg=#00d7af' let rout_color_true = 'guifg=#5dd685' let rout_color_false = 'guifg=#ff5d5e' let rout_color_inf = 'guifg=#10aed7' let rout_color_constant = 'guifg=#5fafcf' let rout_color_string = 'guifg=#5fd7af' let rout_color_error = 'guifg=#ffffff guibg=#c40000' let rout_color_warn = 'guifg=#d00000' let rout_color_index = 'guifg=#d0d080' endif < If you prefer that R output is highlighted using your current `colorscheme`, put in your `vimrc`: >vim let rout_follow_colorscheme = 1 < ============================================================================== 5. Known bugs and workarounds *Nvim-R-known-bugs* Known bugs that will not be fixed are listed in this section. Some of them can not be fixed because they depend on missing features in either R or Vim; others would be very time consuming to fix without breaking anything. ------------------------------------------------------------------------------ 5.1. R must be started by Vim The communication between Vim and R will work only if R was started by the running Vim instance through the rf command. If you use Nvim-R to start R in an external terminal and, then close Vim and open it again, there will be no communication between R and the new Vim instance. Please see the explanation on the communication between Vim and R at the end of https://github.com/jalvesaq/Nvim-R/blob/master/README.md ------------------------------------------------------------------------------ 5.2. R's source() issues The R's `source()` function of the base package prints an extra new line between commands if the option `echo = TRUE`, and error and warning messages are printed only after the entire code is sourced. This makes it more difficult to find errors in the code sent to R. Details: https://stat.ethz.ch/pipermail/r-devel/2012-December/065352.html ------------------------------------------------------------------------------ 5.3. The menu may not reflect some of your custom key bindings If you have created a custom key binding for Nvim-R, the menu in GVim will not always reflect the correct key binding if it is not the same for Normal, Visual and Insert modes. ------------------------------------------------------------------------------ 5.4. Functions are not always correctly sent to R The plugin is only capable of recognizing functions defined using the `<-` operator. Also, only the current function scope is sent to R. See: https://github.com/jalvesaq/Nvim-R/issues/34 ------------------------------------------------------------------------------ 5.5. Wrong message that "R is busy" (Windows only) On Windows, when code is sent from Vim to R Console, the nvimcom library sets the value of the internal variable `r_is_busy` to 1. The value is set back to 0 when any code is successfully evaluated. If you send invalid code to R, there will be no successful evaluation of code and, thus, the value of `r_is_busy` will remain set to 1. Then, if you try to update the object browser, see the R documentation for any function, or do other tasks that require the hidden evaluation of code by R, the nvimcom library will refuse to do the tasks to avoid any risk of corrupting R's memory. It will tell Vim that "R is busy" and Vim will display this message. Everything should work as expected again after any valid code is executed in the R Console. ------------------------------------------------------------------------------ 5.6. Error if there is no package installed (Neovim on Windows only) On Windows, Neovim fails to recognize that a directory is not writable, and this is required by Nvim-R to detect if it is necessary to create the directory defined by `$R_LIBS_USER` environment variable. Consequently, Nvim-R does no try to create the directory and nvimcom installation fails. This problem will happen if you have just installed or upgraded R. The workaround is to manually open R and install any package with the `install.packages()` command before using Nvim-R. ------------------------------------------------------------------------------ 5.7. ~/.Rprofile should not output anything (Windows only) The compilation of `nvimcom` during R startup will fail on Windows if your `~/.Rprofile` outputs anything. Example of how to replicate the bug: >r print("Hello bug!") < ------------------------------------------------------------------------------ 5.8 You can't put `syntax enable` in your `init.vim` (OS X only) It seems that if you put the command `syntax enable` in your `init.vim` on OS X, file type plugins are immediately sourced. Consequently, some Nvim-R variables (`R_disable_cmds`, and `R_user_maps_only`) will be used at their default values even if their values have been set in the `init.vim`. The workaround is do not include the superfluous command `syntax enable` in the `init.vim`. For details, please, access: https://github.com/jalvesaq/Nvim-R/issues/668 ============================================================================== 6. Options *Nvim-R-options* |R_auto_start| Start R automatically |R_objbr_auto_start| Start the Object Browser automatically |R-built-in-terminal| Options to control Vim's built-in terminal |R_external_term| Command to run R in an external terminal emulator |R_silent_term| Do not show terminal errors |R_set_home_env| Set the value of $HOME for R (Windows only) |R_save_win_pos| Save positions of R and GVim windows (Windows only) |R_arrange_windows| Restore positions of R and GVim windows (Windows only) |R_assign| Convert '_' into ' <- ' |R_assign_map| Choose what to convert into ' <- ' |R_rnowebchunk| Convert '<' into '<<>>=\n@' in Rnoweb files |R_rmdchunk| Convert grave accent chunk into delimiters |R_objbr_place| Placement of Object Browser |R_objbr_w| Initial width of Object Browser window |R_objbr_h| Initial height of Object Browser window |R_objbr_opendf| Display data.frames open in the Object Browser |R_objbr_openlist| Display lists open in the Object Browser |R_objbr_allnames| Display hidden objects in the Object Browser |R_nvimpager| Use Vim to see R documentation |R_open_example| Use Vim to display R examples |R_editor_w| Minimum width of R script buffer |R_help_w| Desired width of R documentation buffer |R_path| Directory where R is |R_app|, |R_cmd| Names of R applications |R_args| Arguments to pass to R |R_start_libs| Objects for omni completion and syntax highlight |Rout_more_colors| More syntax highlighting in R output |R_hi_fun| Highlight R functions |R_hi_fun_paren| Highlight R functions only if followed by a `(` |R_routnotab| Show output of R CMD BATCH in new window |R_notmuxconf| Don't use a specially built Tmux config file |R_rconsole_height| Number of lines of R Console |R_rconsole_width| Number of columns of R Console |R_min_editor_width| Minimum number of columns of editor after R start |R_applescript| Use osascript in Mac OS X to run R.app |RStudio_cmd| Run RStudio instead of R. |R_listmethods| Do `nvim.list.args()` instead of `args()` |R_specialplot| Do `nvim.plot()` instead of `plot()` |R_paragraph_begin| Send paragraph from its beginning |R_parenblock| Send lines until closing parenthesis |R_bracketed_paste| Bracket R code in special escape sequences |R_clear_console| Send to clear R's console |R_source_args| Arguments to R `source()` function |R_commented_lines| Include commented lines in code sent to `source()` |R_latexcmd| Command to run on .tex files |R_texerr| Show a summary of LaTeX errors after compilation |R_sweaveargs| Arguments do `Sweave()` |R_rmd_environment| Environment in which to save evaluated rmd code |R_rmarkdown_args| Further options to be passed to `rmarkdown::render()` |R_quarto_render_args| Options to be passed to `quarto::quarto_render()` |R_quarto_preview_args| Options to be passed to `quarto::quarto_preview()` |R_never_unmake_menu| Do not unmake the menu when switching buffers |R_clear_line| Clear R Console line before sending a command |R_editing_mode| The mode defined in your `~/.inputrc` |R_pdfviewer| PDF application used to open PDF documents |R_openpdf| Open PDF after processing rnoweb file |R_openhtml| Open HTML after processing either Rrst or Rmd |R_strict_rst| Code style for generated rst files |R_insert_mode_cmds| Allow R commands in insert mode |R_rmhidden| Remove hidden objects from R workspace |R_source| Source additional Vim scripts |R_non_r_compl| Bibliography completion |R_wait| Time to wait for nvimcom loading |R_wait_reply| Time to wait for R reply |R_nvim_wd| Start R in Vim's working directory |R_after_start| Commands to be executed after R startup |R_after_ob_open| Commands executed after the Object Browser opening |R_debug| Support for debugging functions |R_user_maps_only| Only user specified key bindings |R_disable_cmds| List of commands to be disabled |R_tmpdir| Where temporary files are created |R_compldir| Where lists for omni completion are stored |R_set_omnifunc| Should Nvim-R set the 'omnifunc'? |R_fun_data_1| What the data.frame to complete function arguments is |R_fun_data_2| Where the data.frame to complete function arguments is |R_quarto_intel| Where the Quarto completion data is |R_bib_compl| List of file types for bib completion |R_remote_compldir| Mount point of remote cache directory |Nvim-R-df-view| Options for visualizing a data.frame or matrix |Nvim-R-SyncTeX| Options for SyncTeX ------------------------------------------------------------------------------ 6.1. Automatic start: R and Object Browser *R_auto_start* *R_objbr_auto_start* By default, you have to start R manually with the command rf. If you want that R starts automatically when you load an R script while starting Vim, put in your |vimrc|: >vim let R_auto_start = 1 < If you want that R starts automatically when you start editing an R script even if Vim is already started, put in your |vimrc|: >vim let R_auto_start = 2 < See also: |R_after_start|. If you want to always start the Object Browser immediately after starting R, put in your |vimrc|: >vim let R_objbr_auto_start = 1 < See also: |R_after_ob_open|. ------------------------------------------------------------------------------ 6.2. R in Vim built-in terminal *R-built-in-terminal* *R_esc_term* By default, R runs in a Vim buffer created with the command |:term|, and the key is mapped to stop the Terminal mode and go to Normal mode. In Terminal mode, What you type is passed directly to R while in Normal mode Vim's navigation commands work as usual (see |motion.txt|). If you need the key in R, for example if you want to use `vi`, `vim` or `nvim` within R Console, put in your |vimrc|: >vim let R_esc_term = 0 < Then, you will have to press the default to go from Terminal to Normal mode. Nvim-R sets the option "editor" to a function that makes the object to be edited in a new tab when `R_esc_term` = 1 (the default value). *R_close_term* Neovim does not close its built-in terminal emulator when the application running in it quits, but Nvim-R does close it for you. If you rather prefer that the terminal remains open after R quits, put in your |vimrc|: >vim let R_close_term = 0 < Neovim stops automatically scrolling the R Console if you move the cursor to any line that is not the last one. This emulates the behavior of other terminal emulator, but considering that (1) R only outputs something after we send a command to it, and (2) when we send a command to R, we want to see its output, Nvim-R will move the cursor to the last line of R Console before sending a command to it, forcing the auto scrolling of the terminal. *R_hl_term* If you are using Neovim, Nvim-R will move the cursor to the end of R Console's buffer before sending a command to force the scrolling R output, but you can put the line below in your |init.vim| to disable the auto scrolling of the terminal: >vim let R_auto_scroll = 0 < You may either use the package colorout (Unix only) to colorize R output or let Neovim highlight the terminal contents as it was a .Rout file type. Two advantages of colorout are the possibility of highlighting numbers close to zero in a different color and the distinction between stdout and stderr. The value of `R_hl_term` (0 or 1) determines whether Neovim should syntax highlight the R output, and its default value will be set to 0 if the package colorout is loaded. If you prefer do not rely on the auto detection of colorout, you should set the value of `R_hl_term` in your |vimrc|. Example: >vim let R_hl_term = 0 < *R_OutDec* Right after starting R, Nvim-R will try to detect if either the value of R's `OutDec` option is `","` or the current R script sets the `OutDec` option. If you are using Neovim to syntax highlight R's output and it is not correctly detecting R's `OutDec` option, then, to get numbers correctly recognized, you should put in your |vimrc|: >vim let R_OutDec = ',' < *R_setwidth* On Unix systems, BEFORE sending a command to R Console, if the terminal width has changed, Vim will send to nvimcom the command `options(width=X)`, where X is the new terminal width. You can set the value of `R_setwidth` to 0 to avoid the width being set. Example: >vim let R_setwidth = 0 < On Windows, the command is sent to R Console because it would crash R if sent through nvimcom. If you have the option 'number' set in your |vimrc|, Nvim-R will calculate the number of columns available for R as the window width - 6. If you want a different adjustment, you should set `R_setwidth` as a negative value between -1 and -16. Example: >vim let R_setwidth = -7 < You can also set the value of `R_setwidth` to `2`. In this case, nvimcom will check the value of the environment variable `COLUMNS` AFTER each command is executed and if the environment variable exists, R's width option will be set accordingly. This is the most precise way of setting the option "width", but it has the disadvantage of setting it only after the command is executed. That is, the width will be outdated for the first command executed after a change in the number of columns of the R Console window. *R_buffer_opts* Nvim-R sets the options 'winfixwidth' and 'winfixheight' in the window where R runs. This prevents the window of being automatically resized in some circumstances. It also sets the option 'nobuflisted'. You can set the value of `R_buffer_opts` to define what options should be set in the R Console buffer. It is a list of Vim options separated by spaces. Example with its default value: >vim let R_buffer_opts = "winfixwidth winfixheight nobuflisted" < If you do not want to run R in Vim's built in terminal emulator, you have to install Tmux >= 2.0, and then put in your |vimrc|: >vim let R_external_term = 1 < Then, R will start in an external terminal emulator (useful if you use two monitors and want Vim and R separate from each other), and Tmux will be used to send commands from Vim to R. ------------------------------------------------------------------------------ 6.3. Terminal emulator (Linux/Unix only) *R_external_term* *R_silent_term* Note: The options of this section are ignored on Mac OS X, where the command `open` is called to run the default application used to run shell scripts. R will run in Vim's built-in terminal emulator, unless you set the value of `R_external_term`, which can be a numeric value (either `0` or `1`), the name of the terminal emulator or the complete command to run the terminal emulator. On Windows, the only valid value is `1`, which will make Nvim-R to run `Rgui.exe`, and not really a terminal emulator. On Linux, the complete command for running the terminal is predefined for the following options: 1. foot 2. gnome-terminal, 3. konsole, 4. xfce4-terminal, 5. Eterm, 6. (u)rxvt, 7. aterm, 8. roxterm, 9. lxterminal 10. xterm. If the value of `R_external_term` is 1, the plugin runs the first terminal emulator that it finds from the above list. If your favorite terminal emulator is not selected, you may define it in your |vimrc|. Below are some examples of how to set the value of `R_external_term`: >vim let R_external_term = 1 " Run R in an external terminal (or Rgui.exe) let R_external_term = 'foot' " Run R in in foot < If you are not satisfied with the way your terminal emulator is called by the plugin, you may define in your |vimrc| the variable `R_external_term` as the complete command to run the terminal. Examples: >vim let R_external_term = 'xterm -title R -e' let R_external_term = 'tilix -a session-add-right -e' let R_external_term = 'xfce4-terminal --icon=/path/to/icons/R.png --title=R -x' let R_external_term = 'foot -a R -T R --login-shell --log-level error' < Please, look at the manual of your terminal emulator to know how to call it. The last argument must be the one which precedes the command to be executed. The terminal error messages, if any, are shown as warning messages, unless you put in your |vimrc|: >vim let R_silent_term = 1 < ------------------------------------------------------------------------------ 6.4. Windows specific options *R_save_win_pos* *R_arrange_windows* *R_set_home_env* *Rtools-path* If R cannot find either `make` or `gcc` while trying to compile nvimcom, you should add their directories to the beginning of the `PATH` environment variable in your |vimrc|: >vim let $PATH = "C:\\rtools40\\mingw64\\bin;C:\\rtools40\\usr\\bin;" . $PATH < By default, Nvim-R will save the positions of R Console and Vim windows when you quit R with the rq command, and it will restore the positions of the windows when you start R. If you do not like this behavior, you can put in your |vimrc|: >vim let R_save_win_pos = 0 let R_arrange_windows = 0 < If you want R and GVim windows always in a specific arrangement, regardless of their state when you have quit R for the last time, you should arrange them in the way you want, quit R, change in your |vimrc| only the value of `R_save_win_pos` and, finally, quit Vim. The plugin sets `$HOME` as the Windows register value for "Personal" "Shell Folders" which is the same value set by R. However, if you have set `$HOME` yourself with the intention of changing the default value of `$HOME` assumed by R, you will want to put in your |vimrc|: >vim let R_set_home_env = 0 < ------------------------------------------------------------------------------ 6.5. Assignment operator and Rnoweb completion of code block *R_rnowebchunk* *R_rmdchunk* *R_assign_map* *R_assign* In Rnoweb files, a `<` is replaced with `<<>>=\n@`. To disable this feature, put in your |vimrc|: >vim let R_rnowebchunk = 0 < Similarly, in Rmd files the grave accent (backtick) is replaced with chunk delimiters unless you put in your |vimrc|: >vim let R_rmdchunk = 0 < You can also define a different shortcut for `R_rmdchunk`. For example, to use two backticks instead of one to trigger the completion of the chunk delimiter, put in your |vimrc|: >vim let R_rmdchunk = '``' < If `R_rmdchunk = 2` (the default), in addition to creating an empty chunk block, a single backtick will be converted in inline R delimiters if the cursor is not at the beginning of the line. While editing R code, `_` is replaced with `<-`. If you want to bind other keys to be replaced by `<-`, set the value of |R_assign_map| in your |vimrc|, as in the example below which emulates RStudio behavior (may only work on GVim or Neovim): >vim let R_assign_map = '' < Note: You can't map , as StatET does because in Vim only alphabetic letters can be mapped in combination with the CTRL key. See also: https://github.com/jalvesaq/Nvim-R/issues/634 To completely disable this feature, put in your |vimrc|: >vim let R_assign = 0 < If you need to type many object names with underscores and still want to use `_` as the trigger for the assign symbol, you may want to set the value of `R_assign` as 2. Then, you will have to type two `_` to get them converted into `<-`. Alternatively, if the value of `R_assign` is 3, the plugin will run the following command in each buffer containing R code (R, Rnoweb, Rhelp, Rrst, and Rmd): >vim iabb _ <- < That is, the underscore will be replaced with the assign operator only if it is preceded by a space and followed by a non-word character. ------------------------------------------------------------------------------ 6.6. Object Browser options *R_objbr_w* *R_objbr_h* *R_objbr_place* *R_objbr_opendf* *R_objbr_openlist* *R_objbr_allnames* By default, the Object Browser will be created at the right of the script window, and with 40 columns. Valid values for the Object Browser placement are the combination of either "script" or "console" and "right", "left", "above", "below", separated by a comma. You can also simply choose "RIGHT", "LEFT", "TOP" or "BOTTOM" to start the Object Browser as far as possible to the indicated direction. Examples: >vim let R_objbr_place = 'script,right' let R_objbr_place = 'console,left' let R_objbr_place = 'LEFT' let R_objbr_place = 'RIGHT' < The minimum width of the Object Browser window is 9 columns. You can change the object browser's default width by setting the value of |R_objbr_w| in your |vimrc|, as below: >vim let R_objbr_w = 30 < If the Object Browser is being created bellow or at the top of the existing window, it will be 10 lines high, unless you set its height in your |vimrc|: >vim let R_objbr_h = 20 < Below is an example of setup of some other options in the |vimrc| that control the behavior of the Object Browser: >vim let R_objbr_opendf = 1 " Show data.frames elements let R_objbr_openlist = 0 " Show lists elements let R_objbr_allnames = 0 " Show hidden objects < Objects whose names start with a "." are hidden by default. If you want them displayed in the Object Browser, set the value of `R_objbr_allnames` to `1`. When a `data.frame` appears in the Object Browser for the first time, its elements are immediately displayed, but the elements of a `list` are displayed only if it is explicitly opened. The options `R_objbr_opendf` and `R_objbr_openlist` control the initial status (either opened or closed) of, respectively, `data.frames` and `lists`. The options are ignored for `data.frames` and `lists` of libraries which are always started closed. ------------------------------------------------------------------------------ 6.7. Vim as pager for R *R_open_example* *R_nvimpager* *R_editor_w* *R_help_w* ------------------------------------------------------------------------------ 6.7.1. Quick setup If you do not want to see R examples in a Vim buffer, put in your |vimrc|: >vim let R_open_example = 0 < If you do not want to see R documentation in a Vim buffer, put in your |vimrc|: >vim let R_nvimpager = 'no' < This option can only be set to "no" in the |vimrc|. It will be automatically changed to a suitable value if it is set to "no" after Vim startup. If you want to see R documentation in Vim, but are not satisfied with the way it works, please, read the subsection 6.7.2 below. ------------------------------------------------------------------------------ 6.7.2. Details and other options: The plugin key bindings will remain active in the documentation buffer, and, thus, you will be able to send commands to R as you do while editing an R script. You can, for example, use rh to jump to another R help document. The valid values of `R_nvimpager` are: "vertical" : Split the window vertically if the editor width is large enough; otherwise, split the window horizontally and attempt to set the window height to at least 20 lines. This is the default. "tab" : Show the help document in a new tab. If there is already a tab with an R help document tab, use it. This is the default if `R_external_term` = 1. "horizontal": Split the window horizontally. "tabnew" : Show the help document in a new tab. "no" : Do not show R documentation in Vim. The window will be considered large enough if it has more columns than `R_editor_w` + `R_help_w`. These variables control the minimum width of the editor window and the help window, and their default values are, respectively, 66 and 46. Thus, if you want to have more control over Vim's behavior while opening R's documentations, you will want to set different values to some variables in your |vimrc|, as in the example: >vim let R_editor_w = 80 let R_editor_h = 60 < Unless the value of `R_nvimpager` is "tabnew", the buffer name will always be "R_doc" to force the reuse of the window when users jump from one help page to another. ------------------------------------------------------------------------------ 6.8. R path and application names *R_path* *R_app* *R_cmd* Vim will run the first R executable in the path. You can set an alternative path to R in your |vimrc| as in the examples: >vim let R_path = '/path/to/my/preferred/R/version/bin' let R_path = "C:\\Program Files\\R\\R-4.0.1\\bin\\x64" < On Windows, Vim will try to find the R install path in the Windows Registry. You can set the path to a different R version for specific R scripts in your |vimrc|. Example: >vim autocmd BufReadPre ~/old* let R_path='~/app/R-4.0.0/bin' < The `R_path` variable can also be prefixed to the `PATH` environment variable. So, it can include more than one directory separated by a `;` on Windows or a `:` on other systems. This is specially important to include the path to RTools `bin` directories on Windows. Example: >vim let R_path = 'C:\rtools40\mingw64\bin;C:\rtools40\usr\bin;C:\Program Files\R\R-4.0.1\bin\x64' < By default `R_cmd` is `"R"` (but it might be the same as `R_app`) and will be used to run some scripts in the background, such as: > R CMD build nvimcom R CMD install nvimcom R CMD BATCH current_script.R < If it is necessary to call a different application to run the above commands in your system, you should set the value of `R_cmd` in your |vimrc|. By default the value of `R_app` is `"R"` on Unix systems (such as Linux and Mac OS X). On Windows, it is `Rterm.exe` if R is going to run in a Vim buffer and `"Rgui.exe"` otherwise. Nvim-R cannot send messages to `Rterm.exe` in an external `cmd` window. If your R binary has a different name (for example, if it is called by a custom script), you should set the value of `R_app` in your |vimrc| (and, perhaps, `R_cmd` too). Example: >vim let R_app = 'radian' let R_cmd = 'R' < ------------------------------------------------------------------------------ 6.9. Arguments to R *R_args* Set this option in your |vimrc| if you want to pass command line arguments to R at the startup. The value of this variable must be a |List|. Example: >vim let R_args = ['--no-save', '--quiet'] < On Linux, there is no default value for |R_args|. On Windows, the default value is `['--sdi']`, but you may change it to `['--mdi']` if you do not like the SDI style of the graphical user interface. ------------------------------------------------------------------------------ 6.10. Omnicompletion and syntax highlighting *R_start_libs* The list of functions to be highlighted and the list of objects for omni completion are built dynamically as the libraries are loaded by R. If R is running, only the names of objects in .GlobalEnv and in loaded libraries are completed. If R is not running, only objects of libraries listed in `R_start_libs` and as the first argument of either `library()` and `require()` commands in the current buffer will have their names completed. However, you can set the value of `R_start_libs` if you want that the functions and objects of specific packages are respectively highlighted and available for omni completion even if R is not running yet. By default, only the functions of vanilla R are always highlighted. Below is the default value of `R_start_libs`: >vim let R_start_libs = 'base,stats,graphics,grDevices,utils,methods' < *Rout_more_colors* By default, the R commands in .Rout files are highlighted with the color of comments, and only the output of commands has some of its elements highlighted (numbers, strings, index of vectors, warnings and errors). If you prefer that R commands in the R output are highlighted as they are in R scripts, put the following in your |vimrc|: >vim let Rout_more_colors = 1 < When syntax highlighting .Rout files, Nvim-R considers "> " as the prompt string and "+ " as the continuation string. If you have defined different prompt and continuation strings in your `~/.Rprofile`, Nvim-R will try to get them from R, but if they include special characters, you may have to define them in your |vimrc| too to avoid errors and get them properly highlighted. For example, if you have in your `~/.Rprofile` >r options(prompt = '\u1b[34m»\u1b[0m ') < you should put in your |vimrc|: >vim let Rout_prompt_str = '»' < *R_hi_fun_paren* By default, Nvim-R highlights the names of R functions even if they are not followed by a parenthesis. If you prefer to highlight R functions only if the `(` is typed, put in your |vimrc|: >vim let R_hi_fun_paren = 1 < Notes: - The syntax highlighting is slower when `R_hi_fun_paren` is 1, and, depending on your system configuration, the slowness might be noticeable. - If you have too many loaded packages Vim may be unable to load the list of functions for syntax highlight. - Nvim-R does not control the syntax highlighting of functions when `nvim-treesitter` is enabled to highlight code on Neovim. By default, functions from `.GlobalEnv` and other environments in the `search()` path whose names do not start with `"package:"` are immediately highlighted after being created in the R workspace if `R_set_omnifunc` is not empty, the Object Browser is open, or `cmp-nvim-r` is installed. Functions from environments in the search path are highlighted as functions from packages, but in Neovim (not in Vim) you can set a different highlight command for them in your |vimrc|, as in the example below: >vim hi rGlobEnvFun ctermfg=117 guifg=#87d7ff cterm=italic gui=italic < If you prefer to completely disable the syntax highlighting of R functions by Nvim-R put in your |vimrc|: >vim let R_hi_fun = 0 < ------------------------------------------------------------------------------ 6.11. How to automatically open the .Rout file *R_routnotab* After the command ao, Vim will save the current buffer if it has any pending changes, run `R CMD BATCH --no-restore --no-save` on the current file and show the resulting .Rout file in a new tab. If you prefer that the file is open in a new split window, put in your |vimrc|: >vim let R_routnotab = 1 < ------------------------------------------------------------------------------ 6.12. Tmux configuration (Linux/Unix only) *R_notmuxconf* If Vim is running R in an external terminal emulator, R will run in a Tmux session with a specially built Tmux configuration file. If you want to use your own ~/.tmux.conf, put in your |vimrc|: >vim let R_notmuxconf = 1 < If you opted for using your own configuration file, the plugin will write a minimum configuration which will set the value of four environment variables required for the communication with R and then source your own configuration file (~/.tmux.conf). ------------------------------------------------------------------------------ 6.13. Control of R window *R_rconsole_height* *R_rconsole_width* *R_min_editor_width* When starting R, Vim's window is split vertically if its width is larger than: > R_min_editor_width + R_rconsole_width + 1 + (&number * &numberwidth) < That is, if it is large enough to guarantee that both the script and the R windows will have at least the desired number of columns even if 'number' is set. The default value of both `R_min_editor_width` and `R_rconsole_width` is 80. If you prefer the window is always split vertically, set these two options with lower values in your |vimrc|. Example: >vim let R_rconsole_width = 57 let R_min_editor_width = 18 < You can also set a `R_rconsole_width` relative to current Vim window width. For example, if you want to split the available horizontal space evenly between Vim and R, put in your |vimrc|: >vim let R_rconsole_width = winwidth(0) / 2 autocmd VimResized * let R_rconsole_width = winwidth(0) / 2 < If you always prefer a horizontal split, set the value of `R_rconsole_width` to 0: >vim let R_rconsole_width = 0 < For a horizontal split, you can set the number of lines of the R window: >vim let R_rconsole_height = 15 < You should set 'nosplitright' if you wanted the R Console on the left side, and 'nosplitbelow' if you wanted it above the R script. Note: If running R in a Neovim buffer, the number of lines and columns will automatically change if you switch between horizontal and vertical splits (see |CTRL-W_K| and |CTRL-W_H|). You may request Neovim to try to keep the minimum width and height of a specific window by setting the options 'winwidth' and 'winheight'. So, if the window is split horizontally and you want a small R Console window, you should set a large value for 'winheight' in the script window. ------------------------------------------------------------------------------ 6.14. Integration with R.app (OS X only) and RStudio *R_applescript* *RStudio_cmd* If you are on Mac OS X and want to use the R.app graphical application, put in your |vimrc|: >vim let R_external_term = 1 let R_applescript = 1 < If you want to run RStudio instead of R set in your |vimrc| the value of `RStudio_cmd` to the complete path of the RStudio_cmd binary. Example: >vim let R_external_term = 1 let RStudio_cmd = 'C:\Program Files\RStudio\bin\rstudio' < Note: You must manually run a successful comand in RStudio Console before sending code from Vim to RStudio. The command might be something as simple as the number `1`. ------------------------------------------------------------------------------ 6.15. Special R functions *R_listmethods* *R_specialplot* The R function `args()` lists the arguments of a function, but not the arguments of its methods. If you want that the plugin calls the function `nvim.list.args()` after ra, you have to add to your |vimrc|: >vim let R_listmethods = 1 < By default, R makes a scatter plot of numeric vectors. The function `nvim.plot()` do both a histogram and a box plot. The function can be called by the plugin after rg if you put the following line in your |vimrc|: >vim let R_specialplot = 1 < ------------------------------------------------------------------------------ 6.16. Control how paragraphs and lines are sent *R_paragraph_begin* *R_parenblock* *R_bracketed_paste* *R_clear_console* By default, when you press pp Nvim-R sends all contiguous lines to R, that is all lines above and below the current one that are not separated by an empty line. If you prefer that only lines from the cursor position to the end of the paragraph are sent, put in your |vimrc|: >vim let R_paragraph_begin = 0 < If a line has an opening parenthesis, all lines up to the closing parenthesis are sent to R when you send a line of code to R. If you prefer to send the lines one by one, put in your |vimrc|: >vim let R_parenblock = 0 < Bracketed paste mode will bracket R code in special escape sequences when it is being sent to R so that R can tell the differences between stuff that you type directly to the console and stuff that you send. It is particularly useful when you are using a version of R which is compiled against readline 7.0+ or when rice console is used. To enable it, put in your |vimrc|: >vim let R_bracketed_paste = 1 < Some versions of R's console interpret as a command to clear the console while others have no command to clear the console. You should set the value of `R_clear_console` as `0` if you see `^L` printed in the R's console after rm: >vim let R_clear_console = 0 < ------------------------------------------------------------------------------ 6.17. Arguments to R source() function *R_source_args* *R_commented_lines* When you send multiple lines of code to R (a selection of lines, a paragraph, code between two marks or an R chunk of code), Nvim-R saves the lines in a temporary file and, then, sends to R a command which calls `base::source()` to run the commands from the temporary file. By default, R's `source()` is called with the arguments `print.eval=TRUE` and `spaced=FALSE`. The argument `local=parent.frame()` is passed to `source()` too because it is run inside another function. But you can either add or change the arguments passed to it. Examples: > let R_source_args = 'echo = TRUE' let R_source_args = 'print.eval = FALSE, echo = TRUE, spaced = TRUE' < The option `R_commented_lines` was dropped because it unduly removed lines from multi-line raw strings if they included a hashtag. See: https://github.com/jalvesaq/Nvim-R/issues/743 ------------------------------------------------------------------------------ 6.18. LaTeX options *R_sweaveargs* *R_latexcmd* *R_texerr* *R_cite_pattern* To produce a pdf document from the .tex file generated by either `Sweave()` or `knit()` command, Nvim-R calls: > latexmk -pdf -pdflatex="xelatex %O -file-line-error -interaction=nonstopmode -synctex=1 %S" < If `xelatex` is not installed, it will be replaced with `pdflatex` in the above command. If `latexmk` is not installed, Nvim-R will call either `xelatex` or `pdflatex` directly. You can set the value `R_latexcmd` to change this behavior. `R_latexcmd` is a list: its first element is the command to be executed and the remaining elements are arguments to be passed to the command. Examples: >vim let R_latexcmd = ['pdflatex'] let R_latexcmd = ['xelatex'] let R_latexcmd = ['latexmk', '-pdf', '-pdflatex="xelatex %O -synctex=1 %S"'] < The elements of `R_latexcmd` may contain double quotes (as in the last example above), but not single quotes, because Nvim-R will use single quotes to separate them in an R's `c()` command. If you want to pass arguments to the `Sweave()` function, set the value of the `R_sweaveargs` variable. If the value of `R_texerr` is `1`, nvmimcom will output to R Console LaTeX errors and warnings produced by the compilation of the .tex document into .pdf. So, you do not have to scroll the R Console seeking for these messages. However, if Nvim-R cannot not find the LaTeX log file because it is not saved in the same directory as the Rnoweb, you should set the value of `R_latex_build_dir`. Example: >vim let R_latex_build_dir = 'build' < See also |R_bib_compl|. ------------------------------------------------------------------------------ 6.19. rmarkdown::render() options *R_rmd_environment* *R_rmarkdown_args* When rendering an Rmd file, the code can be evaluated (and saved) in a specified environment. The default value is `.GlobalEnv` which makes the objects stored in the Rmd file available on the R console. If you do not want the objects stored in the Rmd file to be available in the global environment, you can set >vim let R_rmd_environment = 'new.env()' < Other options to be passed to `rmarkdown::render()` might be defined with `R_rmarkdown_args`, as in the example: >vim let R_rmarkdown_args = 'output_dir = "output", clean = FALSE' < ------------------------------------------------------------------------------ 6.20. Quarto's render and preview options *R_quarto_render_args* *R_quarto_preview_args* If you want to send the commands `quarto::quarto_render()` and `quarto::quarto_preview()` to R with additional arguments, you should define the values of `R_quarto_render_args` and `R_quarto_preview_args` in your |vimrc|, as in the examples: >vim let R_quarto_render_args = ', pandoc_args = c("-F", "apafix.py")' let R_quarto_preview_args = ', browse = FALSE' < ------------------------------------------------------------------------------ 6.21. Never unmake the R menu *R_never_unmake_menu* Use this option if you want that the "R" menu item in GVim is not deleted when you change from one buffer to another, for example, when going from a .R file to a .txt one: >vim let R_never_unmake_menu = 1 < When this option is enabled all menu items are created regardless of the file type. ------------------------------------------------------------------------------ 6.22. Clear R Console line before sending commands *R_clear_line* *R_editing_mode* When one types in the R Console the cursor goes to the beginning of the line and when one types the characters to the right of the cursor are deleted. This is useful to avoid characters left on the R Console being mixed with commands sent by Vim. Nvim-R will add to every command if you put in your |vimrc|: >vim let R_clear_line = 1 < Nvim-R reads your `~/.inputrc` and, if it finds the string "set editing-mode vi" it will send to R 0Da instead of . If Nvim-R fails to detect that R is running in vi editing mode, you have to put this line in your |vimrc|: >vim let R_editing_mode = "vi" < This might produce a beep when sending commands, and you may want to disable the audible bell only for R by putting in your `~/.inputrc`: > $if R set bell-style none $else set bell-style audible $endif < Note: You can't control the bell on Windows; it is hardcoded to run in Rterm and to not run in Rgui. ------------------------------------------------------------------------------ 6.23. Open PDF after processing quarto, rnoweb, rmd or rrst files *R_pdfviewer* *R_openpdf* *R_openhtml* The plugin can automatically open the pdf file generated by pdflatex, after either `Sweave()` or `knit()`. This behavior is controlled by the variable |R_openpdf| whose value may be 0 (do not open the pdf), 1 (open only the first time that pdflatex is called) or a number higher than 1 (always open the pdf). For example, if you want that the pdf application is started automatically but do not want the terminal (or GVim) losing focus every time that you generate the pdf, you should put in put in your |vimrc|: >vim let R_openpdf = 1 < If you use Linux or other Unix and eventually use the system console (without the X server) you may want to put in your |vimrc|: >vim if $DISPLAY == "" && $WAYLAND_DISPLAY == "" let R_openpdf = 0 endif < The default value of `R_openpdf` is 1 on Mac OS X and 2 on Windows. On Linux, it is 2 on the X Server and on Sway Window Manager and 1 on other Wayland compositors. On Windows, Nvim-R will call Sumatra to open the PDF, and, on Mac OS X, it will call Skim. On Linux, you can change the value of `R_pdfviewer` in your |vimrc| to define what PDF viewer will be called. Valid values are "zathura" (default, and the one best integrated with Nvim-R), "evince" and "okular". On Linux, if running on the X server (not on Wayland), the application `wmctrl` is required to raise both the PDF viewer and Vim windows. If using Gnome Shell on Wayland, the extension "Activate Window By Title" is required (https://extensions.gnome.org/extension/5021/activate-window-by-title/). If editing an Rmd file, you can produce the html result with kr or kh (it may also work with other file types). The html file will be automatically opened if you put the following in your |vimrc|: >vim let R_openhtml = 1 < The meanings of different values of `R_openhtml` are: 0: Never open the html. 1: Always open the html. The browser application called by Nvim-R is whatever is returned by the R command `getOption("browser")`, unless it is NULL. In this case, Nvim-R will call `open` on both Windows and Mac OS X, and `xdg-open` on Linux. Most browser will open a new tab each time they are called instead of refreshing a document that is already open. So, if you rather prefer that Nvim-R never tries to open the web browser, put in your |vimrc|: >vim let R_openhtml = 0 < For Quarto documents, the available key bindings are qr (render document), qp (preview document), and qs (stop previewing). The command kr achieves basically the same result of kr. The difference is that the generated document is open after kr, and qr allows Quarto specific options (see |R_quarto_render_args|). ------------------------------------------------------------------------------ 6.24. Support to RreStructuredText file *R_rrstcompiler* *R_strict_rst* *R_rst2pdfpath* *R_rst2pdfargs* By default, Nvim-R sends the command `render_rst(strict=TRUE)` to R before using R's `knit()` function to convert an Rrst file into an rst one. If you prefer the non strict rst code, put the following in your |vimrc|: >vim let R_strict_rst = 0 < You can also set the value of `R_rst2pdfpath` (the path to rst2pdf application), `R_rrstcompiler` (the compiler argument to be passed to R function knit2pdf), and `R_rst2pdfargs` (further arguments to be passed to R function knit2pdf). ------------------------------------------------------------------------------ 6.25. Allow R commands in insert mode *R_insert_mode_cmds* Nvim-R commands are enabled for Normal mode, but most of them can also be enabled in Insert mode. However, depending on your , this can make it very difficult to write R packages or Sweave files. For example, if is set to the `\` character, typing `\dQuote` in a .Rd file tries to send the command! If you want to enable commands in Insert mode, add the following to your |vimrc|: >vim let R_insert_mode_cmds = 1 < ------------------------------------------------------------------------------ 6.26. Show/remove hidden objects *R_rmhidden* Hidden objects are removed from R workspace when you do rm. If you prefer to remove only visible objects, put in your |vimrc|: >vim let g:R_rmhidden = 0 < After removing the objects, Nvim-R will also send CTRL-L to the R Console to clear the screen. If you have set vi mode in your `~/.inputrc` you might also want to set CTRL-L to clear the screen, as explained at https://unix.stackexchange.com/questions/104094/is-there-any-way-to-enable-ctrll-to-clear-screen-when-set-o-vi-is-set ------------------------------------------------------------------------------ 6.27. Source additional Vim scripts *R_source* This variable should contain a comma separated list of Vim scripts to be sourced by Nvim-R. These scripts may provide additional functionality and/or change the behavior of Nvim-R. If you have such scripts, put in your |vimrc|: >vim let R_source = '~/path/to/MyScript.vim,/path/to/AnotherScript.vim' < Currently, there is only one script known to extend Nvim-R features: Support for the devtools R package: https://github.com/mllg/vim-devtools-plugin ------------------------------------------------------------------------------ 6.28. Completion of non R code *R_non_r_compl* Rnoweb: The omni completion of bibliographic data from bib files requires Python 3 and the PyBTeX library for Python 3. For Rnoweb documents, omni completion of citation keys gathers data from `.bib` files in the same directory of the current Rnoweb document, and the completion works only if a pattern similar to "\cite{" precedes the cursor (see |R_cite_pattern|). Some of the most commonly used LaTeX commands are also completed. The completion of the argument for both `\ref{}` and `\pageref{}` includes both the label of R chunks where the option `fig.cap` was found prefixed with `fig:` and the string attributed to the argument `label` in the R code, but only if they begin with the substring "tab:". If the reference includes the field "file", you can open this file by typing od in Normal mode with the cursor over the citation key. Rmarkdown and Quarto: For either RMarkdown or Quarto documents it is recommended to install zotcite and cmp-zotcite for completing citation keys directly from Zotero database: https://github.com/jalvesaq/zotcite https://github.com/jalvesaq/cmp-zotcite If zotcite is not installed, Nvim-R will do omni completion of bibliographic citation keys from `.bib` files, requiring Python 3 and the PyBTeX library for Python 3 to work. Then, Nvim-R will look for bibliographic data in any `.bib` file listed in the `bibliography` field of the YAML header. If the `bibliography` field is not defined, it will use all `.bib` files that are in the same directory of the RMarkdown document as bibliography sources. The list of `.bib` files is updated whenever the buffer is saved. If the reference includes the field "file", you can open this file by typing od in Normal mode with the cursor over the citation key. If you include Python chunks in your Rmd document, you should put the lines below in your |vimrc| to get them highlighted: >vim let g:markdown_fenced_languages = ['r', 'python'] let g:rmd_fenced_languages = ['r', 'python'] < Lines of Python code are sent to R Console as arguments to `reticulate::py_run_string()`. How to disable: To disable the completion of non R code in Rmd and Rnoweb files, and use the omni completion provided by another plugin, put in your |vimrc|: >vim let R_non_r_compl = 0 < Then, Nvim-R may use another function to complete non R code, such as the ones from vim-pandoc or LaTeX-Box If you want a different function for completion of non R code, you should not set the value 'omnifunc' in your |vimrc| because you would lose the completion of R objects. It is better to use an |autocmd| to set the value of the buffer variable `b:rplugin_non_r_omnifunc`. Example: >vim autocmd FileType rmd let b:rplugin_non_r_omnifunc = "pandoc#completion#Complete" < Note: On Windows, Nvim-R's bibliographic completion works only with ascii letters. See also |R_bib_compl|. ------------------------------------------------------------------------------ 6.29. Time to wait for nvimcom loading *R_wait* Nvim-R asynchronously waits 60 seconds for the nvimcom package to be loaded during R startup. If 60 seconds are not enough to your R startup, then set a higher value for the variable in your |vimrc|. Example: >vim let R_wait = 100 < ------------------------------------------------------------------------------ 6.30. Time to wait for R reply *R_wait_reply* By default Nvim-R waits 2 seconds for R to reply after a request for omni completion is issued. You can set the amount of time Nvim-R waits (in seconds) in your |vimrc|. Example: >vim let R_wait_reply = 5 < ------------------------------------------------------------------------------ 6.31. Start R in working directory of Vim *R_nvim_wd* When you are editing an R file (.R, .Rnw, .Rd, .Rmd, .Rrst, or .qmd) and start R, the R package nvimcom runs the command `setwd()` with the directory of the file being edited as argument, that is, the R working directory becomes the same directory of the R file. If you want R's working directory to be the same as Vim's working directory, put in your |vimrc|: >vim let R_nvim_wd = 1 < This option is useful only for those who did not enable 'autochdir'. If you prefer that Nvim-R does not set the working directory in any way, put in |vimrc|: >vim let R_nvim_wd = -1 < ------------------------------------------------------------------------------ 6.32. Commands to be executed after either R startup or Object Browser opening *R_after_start* *R_after_ob_open* If you want the execution of Vim, R, or external commands right after R startup, set the value of `R_after_start` in your |vimrc|. The `R_after_start` variable must be a list of strings. Strings representing Vim commands must start with `:`, R commands must be prefixed with `R:`, and external commands must be prefixed with `!`. You can put commands in your `~/.Rprofile` that will be run only if R was started by Nvim-R as in the example below: >r if (Sys.getenv("NVIMR_TMPDIR") == "") cat("~/Rprofile: R was called by Nvim-R\n", file = stderr()) < However, if for any reason you `~/.Rprofile` is not being sourced, you can include in `R_after_start` R commands that should be executed during R startup (more precisely, during `nvimcom` loading). Example: >vim let R_after_start = ['R: cat("R_after_start: R was called by Nvim-R\n", file = stderr())'] < Note: The loading of `nvimcom` will fail if the command to be executed is invalid. In the example above, we have had to use `\n` to indicate a new line. For an example of Vim command, if you want that the R script window is hidden right after R startup, put in your |vimrc|: >vim let R_after_start = [':hide'] < Nvim-R stores the environment variable $WINDOWID of the terminal where R is running as $RCONSOLE. Thus, if you are running R in a external terminal emulator on the X server (not on Wayland) on Linux, `~/bin` is in your path, and you want to resize and change the positions of the terminals containing Vim and R, you may create a script `~/bin/after_R_start` similar to the following: > #!/bin/sh wmctrl -i -r $RCONSOLE -e 0,0,200,1200,800 wmctrl -i -r $WINDOWID -e 0,300,40,1200,800 wmctrl -i -r $WINDOWID -b remove,maximized_vert,maximized_horz < Then, make the script executable, and put in your |vimrc|: >vim let R_external_term = 1 let R_after_start = ['!after_R_start'] < Similarly, on Mac OS X, the script below (developed by songcai) will bring the focus to Vim terminal window: > #!/usr/bin/env osascript --Raise the Terminal window containing name ".R". tell application "Terminal" set index of window 1 where name contains ".R" to 1 delay 0.05 activate window 1 end tell --Click the title bar of the raised window to bring focus to it. tell application "System Events" tell process "Terminal" click menu item (name of window 1) of menu of menu bar item "Window" of menu bar 1 end tell end tell < If you want that Nvim-R executes Vim commands right after the Object Browser is open, set the value of `R_after_ob_open` as a list of commands. Example: >vim let R_after_ob_open = [':tabnew %'] < ------------------------------------------------------------------------------ 6.33. Support for debugging functions *R_debug* Put the line below in your |vimrc| if do not want that the cursor jumps to the line being debugged (when `browser()` is run). Highlighting of the line being debugged will also be disabled. >vim let R_debug = 0 < Nvim-R puts the cursor in the R Console when the debugging starts. If you do not want this, put in your |vimrc|: >vim let R_dbg_jump = 0 < The highlighted debugged line incrementally moves down the buffer with code execution and, with long scripts, it may stay at the bottom of the window as you debug. You can hold the highlighted line in the middle of the window with >vim let R_debug_center = 1 < ------------------------------------------------------------------------------ 6.34. Disable Nvim-R commands *R_user_maps_only* *R_disable_cmds* *R_filetypes* The Nvim-R sets many default key bindings. The user can set custom key bindings (|Nvim-R-key-bindings|). If you wish Nvim-R to only use those key-bindings specified by the user, put in your |vimrc|: >vim let R_user_maps_only = 1 < If you want to disable only some of Nvim-R commands, create a Vim list with their key bindings names in your |vimrc|. The complete list of key bindings names is shown at the Custom key bindings section (Nvim-R-key-bindings). Below is an example on how to disable the commands that sends `setwd()` and `dput()` to R Console: >vim let R_disable_cmds = ['RSetwd', 'RDputObj'] < If you want to disable Nvim-R for a specific file type, create the variable `R_filetypes` with a list of file types that should be supported. Example: >vim let R_filetypes = ['r', 'rmd', 'rrst', 'rnoweb', 'quarto', 'rhelp'] < If the variable `R_filetypes` does not exist, all file types from the above list will be supported. ------------------------------------------------------------------------------ 6.35. Temporary files directories *R_tmpdir* *R_compldir* You can change the directories where temporary files are created and stored by setting in your |vimrc| the values of `R_tmpdir` and `R_compldir`, as in the example below: >vim let R_tmpdir = '/dev/shm/R_tmp_dir' let R_compldir = '~/.cache/Nvim-R' < The default paths of these directories depend on the operating system. If you want to know what they are, while editing an R file, do in Normal mode: >vim :echo g:rplugin.tmpdir :echo g:rplugin.compldir < ------------------------------------------------------------------------------ 6.36. Omni completion *R_set_omnifunc* *R_fun_data_1* *R_fun_data_2* *R_quarto_intel* *R_bib_compl* There are two ways of getting automatic completion of R objects names while you type: using Nvim-R's built-in completion system (as a source for `nvim-cmp`) and using a language server. See: https://github.com/jalvesaq/cmp-nvim-r https://github.com/REditorSupport/languageserver The advantage of Nvim-R's built-in system is the ability to complete objects of the R's workspace (`.GlobalEnv`), including column names of data.frames. Note: If you are using the `languageserver` package, you should disable its omni completion feature in your `~/.Rprofile` to get completions from `cmp-nvim-r`: >r options(languageserver.server_capabilities = list(completionProvider = FALSE, completionItemResolve = FALSE)) < If you prefer to get completions from the language server, `cmp-nvim-r` should not be installed, and you should set `R_set_omnifunc` as an empty list in your |vimrc|: >vim let R_set_omnifunc = [] < If `cmp-nvim-r` is not installed, you still can define in your |vimrc| the list of file types supported by Nvim-R that should have the traditional Vim's omni completion enabled. Example: >vim let R_set_omnifunc = ["r", "rmd", "quarto", "rnoweb", "rhelp", "rrst"] < While completing function arguments, Nvim-R may include column names from the data.frame passed as the first argument, and you may set in your |vimrc| the list of functions that might benefit from this kind of completion. The example below sets `R_fun_data_1` to its default value: >vim let R_fun_data_1 = ['select', 'rename', 'mutate', 'filter'] Nvim-R can also include column names from a data.frame passed as the first argument of the parent function. For example, if you were typing >r with(my_data_frame, lm( < and, then, trigger omni completion, the column names of `my_data_frame` would be included in the completion menu. By default, only the function `aes` (if passed as argument for `ggplot`) and the functions `lm`, `glm` or `lmer` (if passed as argument for `with`) will have column names of the first argument of the parent function included in the completion menu. You have to set the value of `R_fun_data_2` in your |vimrc| to include more functions. `R_fun_data_2` is a dictionary with parent functions as keys. The value of each key is a list of functions that are expected to be nested in the parent function. If the name of the nested function is `*`, it will match any name. Example: >vim let R_fun_data_2 = {'ggplot': ['aes'], 'with': ['*']} < Note: The algorithm for finding the first argument of the parent function is very simple and would wrongly recognize `data` as the name of the `data.frame` in the following code: >r ggplot(data = my_data_frame, mapping = aes( < Nvim-R receives the list of objects for omni completion from the nvimrserver job running in the background. If the list is too big to be transmitted through nvimrserver's `stdout`, the completion might be aborted. If editing Quarto documents, Nvim-R will try to find the file `yaml-intelligence-resources.json` which is part of `quarto` application and has all necessary information for completion of valid YAML options in an Quarto document. If Nvim-R fails to find the file, you can set the value of `R_quarto_intel` in your |vimrc|. Example: >vim let R_quarto_intel = '~/Downloads/quarto-1.1.251/share/editor/tools/yaml/yaml-intelligence-resources.json' < Omni completion in Rnoweb files will include results from bib files entries (requiring Python 3 and python3-pybtex): required for omni completion of citation keys (following |R_cite_pattern|) in Rnoweb documents. Completion of bib file entries might also be enabled to `rmd` and `quarto` file types if you include them in the list `R_bib_compl`. Example: >vim let R_bib_compl = ['rnoweb', 'rmd', 'quarto'] < However, there are many alternative plugins for completing bib keys that work better than Nvim-R. Examples: - `zotcite` with `cmp-zotice` (for Markdown, Rmd and Quarto): https://github.com/jalvesaq/zotcite https://github.com/jalvesaq/cmp-zotcite - `VimTeX` (for Rnoweb): https://github.com/lervag/vimtex/ - Either `cmp-pandoc-references` or `cmp-pandoc.nvim` source for `nvim-cmp`: https://github.com/jc-doyle/cmp-pandoc-references https://github.com/aspeddro/cmp-pandoc.nvim ------------------------------------------------------------------------------ 6.37. Options for accessing Remote R from local Vim *R_remote_compldir* See https://github.com/jalvesaq/Nvim-R/wiki/Remote-access ------------------------------------------------------------------------------ 6.38. View a data.frame or matrix *Nvim-R-df-view* *R_csv_app* *R_csv_delim* You can see data.frames and matrices in external applications with rv. By default, Nvim-R will generate a `tsv` file from the `data.frame` or `matrix` and display it in a new tab. But you can change this by setting the value of `R_csv_app` which must be a string. If `R_csv_app` begins with "terminal:", Nvim-R will open a new tab with the application running in a terminal emulator. For example, if you want to use Visidata to see tabular data, put in your |vimrc|: >vim let R_csv_app = 'terminal:vd' < If you are running Vim within Tmux, you may prefer: >vim let R_csv_app = 'tmux new-window vd' < If `R_csv_app` begins with ":", Nvim-R will append the name of the tsv file and |:execute| the command. Example: >vim let R_csv_app = ':vsplit' < You may also include "%s" in `R_csv_app` to indicate the position of the tsv file name in the command to be executed. Example using the `toggleterm.nvim` plugin which requires the whole command within quotes: >vim let R_csv_app = ':TermExec cmd="vd %s"' < You may also try to see the table in a graphical viewer such as LibreOffice Calc: >vim let R_csv_app = 'localc' let R_csv_app = 'c:/Program Files (x86)/LibreOffice 4/program/scalc.exe' < On Windows, `R_csv_app` works only in GVim, not in Neovim. If the default field delimiter causes problems in your case, you can change it in your |vimrc|. Valid values are `"\t"`, `";"` and `","`. Example: >vim let R_csv_delim = ',' < There is also the option of configuring Nvim-R to run an R command to display the data. Examples: >vim let R_df_viewer = "relimp::showData(%s, font = 'Courier 14')" < The value of `R_df_viewer` is a string and the substring `%s` is replaced by the name of the object under the cursor. ------------------------------------------------------------------------------ 6.39. SyncTeX support *Nvim-R-SyncTeX* SyncTeX is a communication system used by some PDF viewers and by some text editors which allow users to jump from a specific line in the text editor to the corresponding line in the PDF viewer and vice-versa. Nvim-R has support for SyncTeX in five applications: Linux: Zathura, Evince and Okular OS X: Skim Windows: SumatraPDF To completely disable SyncTeX support, put in your |vimrc|: >vim let R_synctex = 0 < You do not have to do anything special in your Rnoweb document, if you are using the knitr package, and are editing single file Rnoweb documents. Otherwise, keep reading... If you use `Sweave()` rather than `knit()`, you must put in your Rnoweb document: > \SweaveOpts{concordance=TRUE} < If you work with a master document and child subdocuments, each child subdocument (TeX and Rnoweb alike) should include the following line: > % !Rnw root = master.Rnw < where `master.Rnw` must be replaced with the name of the actual master document. Note: The knitr package (as of version 1.7) had at least two limitations: - It had no SyncTeX support for child documents. The correspondence data point to lines right below child chunks in the master document and not to somewhere in the child documents themselves. See: https://github.com/yihui/knitr/issues/225 - It only started registering the concordance after the first chunk. So, it is recommended that you put the first chunk of R code just after the `\begin{document}` command. *R_term_title* If running Gnome Shell on Wayland, you have to install the extension "Activate Window by Title" and set the title of your terminal emulator in your |vimrc| in order to have the terminal window raised on SyncTeX backward events. Example: >vim let R_term_title = 'Terminal' < ============================================================================== 7. Custom key bindings *Nvim-R-key-bindings* When creating custom key bindings for Nvim-R, it is necessary to create three maps for most functions because the way the function is called is different in each Vim mode. Thus, key bindings must be made for Normal mode, Insert mode, and Visual mode. To customize a key binding you could put something like this in your |vimrc|: >vim function! s:customNvimRMappings() nmap sr RStart imap sr RStart vmap sr RStart endfunction augroup myNvimR au! autocmd filetype r call s:customNvimRMappings() augroup end < The above example shows how to add a key binding to start R for sr for just r buffers. The default rf still exists. After changing the maps in your |vimrc|, you have to restart Vim. If you want to remove the default mappings, you can set |R_user_maps_only| . Only the custom key bindings for Normal mode are shown in Vim's menu, but you can type |:map| to see the complete list of current mappings, and below is the list of the names for custom key bindings (the prefix RE means "echo"; RD, "cursor down"; RED, both "echo" and "down"): Star/Close R: RStart RCustomStart RClose RSaveClose Clear R console: RClearAll RClearConsole Edit R code: RIndent RNextRChunk RPreviousRChunk Send line or part of it to R: RSendLine RDSendLine RSendLAndOpenNewOne RNLeftPart RNRightPart RILeftPart RIRightPart RDSendLineAndInsertOutput Send code to R console: RSendAboveLines RSendSelection RESendSelection RDSendSelection REDSendSelection RSendMotion RSendSelAndInsertOutput RSendMBlock RESendMBlock RDSendMBlock REDSendMBlock RSendParagraph RESendParagraph RDSendParagraph REDSendParagraph RSendFunction RESendFunction RDSendFunction REDSendFunction RSendFile Send command to R: RHelp RPlot RSPlot RShowArgs RShowEx RShowRout RObjectNames RObjectPr RObjectStr RViewDF (view data.frame or other object) RViewDFs (view object in split window) RViewDFv (view object in vertically split window) RViewDFa (view object in split window above the current one) RDputObj RSetwd RSummary RListSpace Support to Sweave and knitr: RSendChunk RDSendChunk RESendChunk REDSendChunk RSendChunkFH (from the first chunk to here) RBibTeX (Sweave) RBibTeXK (Knitr) RSweave RKnit RMakeHTML RMakePDF (Sweave) RMakePDFK (Knitr) RMakePDFKb (.Rmd, beamer) RMakeODT (.Rmd, Open document) RMakeWord (.Rmd, Word document) RMakeRmd (rmarkdown default) RMakeAll (rmarkdown all in YAML) ROpenPDF RSyncFor (SyncTeX search forward) RGoToTeX (Got to LaTeX output) RSpinFile RNextRChunk RPreviousRChunk Support for Quarto: RQuartoRender RQuartoPreview RQuartoStop Open attachment of bib item: ROpenRefFile Debugging functions: RDebug RUndebug Object browser: RUpdateObjBrowser ROpenLists RCloseLists See also: |R_user_maps_only| and |R_disable_cmds|. The completion of function arguments only happens in Insert mode. The plugin also contains a function called RAction which allows you to build ad-hoc commands to R. This function takes the name of an R function such as "levels" or "table" and the word under the cursor, and passes them to R as a command. For example, if your cursor is sitting on top of the object called gender and you call the RAction function, with an argument such as levels, Vim will pass the command `levels(gender)` to R, which will show you the levels of the object gender. To make it even easier to use this and other functions, you could write custom key bindings in your |vimrc|, as in the examples below: >vim nmap rk :call RAction("levels") nmap t :call RAction("tail") nmap H :call RAction("head") < If you want an action over an selection, then the second argument must be the string `"v"`: >vim vmap h :call RAction("head", "v") < In this case, the beginning and the end of the selection must be in the same line. If either a second or a third optional argument starts with a comma, it will be inserted as argument(s) to the RAction function. Examples: >vim nmap h :call RAction('head', ', n = 10') nmap t :call RAction('tail', ', n = 10, addrownums = FALSE') < If the command that you want to send does not require an R object as argument, you can create a shortcut to it by following the example: >vim map s :call g:SendCmdToR("search()") < See also: |R_source|. ============================================================================== 8. News *Nvim-R-news* 0.9.20 (2024-03-03) * Minor bug fixes. 0.9.19 (2023-11-22) * Make TCP connection on Windows work again, and fix minor bugs. 0.9.18 (2023-11-12) * TCP communication on Windows is broken. * Integration with cmp-nvim-r, a source for nvim-cmp. * Delete options R_auto_omni and R_hi_fun_globenv. * New options: R_filetypes, R_fun_data_1 and R_fun_data_2, R_quarto_intel, R_bib_compl, R_enable_comment. * Require either Neovim 0.6.0 or Vim 8.2.84. 0.9.17 (2022-09-29) * Require either Neovim 0.5.0 or Vim 8.2.84. * New options: R_set_omnifunc, R_auto_omni, R_rmarkdown_args, R_objbr_auto_start, R_quarto_render_args, and R_quarto_preview_args, R_debug_center, R_term_title. * Delete options: R_omni_tmp_file and R_omni_size 0.9.16 (2021-04-29) * Minor bug fixes. * New options: R_omni_size and R_omni_tmp_file. * Option R_path might be a list of directories. 0.9.15 (2021-04-14) * Delete options R_ls_env_tol, R_objbr_labelerr, R_show_arg_help. * New options: R_clear_console, R_debug, R_auto_start, R_dbg_jump. * Replace options R_in_buffer, R_term and R_term_cmd with a single option: R_external_term. * Make R_rmdchunk more flexible. * Change default key binding for calling debug() from \db to \bg to avoid conflict with \d (send line). * Require either Neovim >= 0.4.3 or Vim >= 8.1.1705. 0.9.14 (2020-06-01) * New command \su (send all lines above the current one). * New command \m (send lines from motion command). * New option: R_disable_cmds. * New option: R_after_ob_open. * R_after_start is a list now. * Recommend Visidata and delete option R_csv_warn. * Delete command triggered by tp. * Delete options R_args_in_stline, R_sttline_fmt, R_show_args, R_complete and Rtools_path. * Limited support for debugging R functions. 0.9.13 (2019-05-05) * Support for Python code in knitr chunks: integration with the R package reticulate and with the jedi-vim plugin. * New options: R_editing_mode, R_buffer_opts. * Minor bug fixes. 0.9.12 (2018-08-19) * Minor bug fixes. * Bibliographic completion for Rmd. * New command: :RDebugInfo * New options: R_hi_fun_globenv, R_auto_scroll, R_ls_env_tol, R_non_r_compl, R_cite_pattern. * Accept prefix "terminal:" in `R_csv_app`. * Remove option R_tmux_split. * Changes: - If the Object Browser is already open, \ro will close it. - The values "bottom" and "top" are no longer valid for R_objbr_place (use "below" and "above" instead). 0.9.11 (2018-01-29) * The option R_latexcmd now is a list and the option R_latexmk no longer exists. By default, latexmk and xelatex will be called to compile pdf documents. * Arguments completion is now done by CTRL-X CTRL-O. * New options: R_OutDec, R_csv_delim, R_rmdchunk, R_parenblock, R_bracketed_paste, R_complete. * New command: `:RSend`. * Require Neovim >= 0.2.0 (Linux, OS X) or >= 0.2.1 (Windows). 0.9.10 (2017-09-08) * Change command \dt to \td and \pt to \tp. * New default value for R_show_args = 1. * New options: R_hi_fun_paren, R_show_arg_help,R_sttline_fmt and R_set_sttline_cmd. * Minor bug fixes. 0.9.9 (2017-04-22) * Delete option R_vsplit. * New options: R_min_editor_width and R_wait_reply, Rtools_path, R_remote_tmpdir, R_nvimcom_home, R_paragraph_begin. * Rename option R_ca_ck as R_clear_line * Change in \pp behavior. * Minor bug fixes. 0.9.8 (2016-12-10) * Minor bug fixes. * New commands: \dt and \pt * Require Neovim >= 0.1.7. 0.9.7 (2016-09-26) * Require Vim >= 8.0.0 or Neovim >= 0.1.5. * Replaced R_nvimcom_wait (time in miliseconds) with R_wait (time in seconds). * Minor bug fixes. 0.9.6 (2016-08-10) * New option: R_open_example. * Change default value of R_source_args to "print.eval=TRUE". * Change in \aa and \ae: do not save the buffer before sending the whole file to R. * Minor bug fixes. 0.9.5 (2016-05-18) * Ask whether R_LIBS_USER directory should be created. 0.9.4 (2016-05-16) * Delete option R_tmux_ob. The Object Browser will always start in a Vim split window, not in a Tmux split pane. * New option: R_cmd * Minor bug fixes. * Require Neovim >= 0.1.4 or Vim >= 7.4.1829. 0.9.3 (2016-03-26) * Build nvimcom even when Nvim-R directory in non-writable. 0.9.2 (2016-03-19) * Support Vim. * New option: R_app. 0.9.1 (2016-02-28) * New option: R_close_term. * Delete option: R_restart. 0.9.0 (2015-11-03) * Initial release of Nvim-R for Neovim 0.1.0. vim:tw=78:ts=8:ft=help:norl