-
Notifications
You must be signed in to change notification settings - Fork 13
/
R.nvim.txt
1810 lines (1518 loc) · 78.4 KB
/
R.nvim.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
*R.nvim.txt* *R.nvim*
R.nvim
Plugin to work with R
Authors: R.nvim team (see: https://github.com/R-nvim)
Version: 0.9.0
For Neovim >= 0.9.5
1. Overview |R.nvim-overview|
2. Main features |R.nvim-features|
3. Installation |R.nvim-installation|
4. Use |R.nvim-use|
5. Known bugs and workarounds |R.nvim-known-bugs|
6. Options |R.nvim-options|
7. Custom key bindings |R.nvim-key-bindings|
8. History |R.nvim-history|
==============================================================================
1. Overview *R.nvim-overview*
This plugin improves the support for editing R code with Neovim.
Feedback is welcomed. Please submit bug reports to the developers. Do not like
a feature? Tell us and we may add an option to disable it.
The plugin should emit useful warnings if you do things it was not programmed
to deal with. Cryptic error message are bugs... Please report them at:
https://github.com/jalvesaq/Nvim-R/discussions
Git pull requests are welcome.
==============================================================================
2. Main features *R.nvim-features*
* 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 LaTeX commands.
* Auto completion (with `cmp-r`):
- R objects (.GlobalEnv and loaded packages).
- function arguments.
- knitr chunk options.
- Quarto cell options.
* Ability to see R's documentation in an editor buffer:
- 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):
- Tree view of objects.
- 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.
* Special highlighting for R output (.Rout files).
* Most of the plugin's behavior is customizable.
==============================================================================
3. Installation *R.nvim-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:
Neovim >= 0.9.5
https://github.com/neovim/neovim/releases
See also: https://github.com/neovim/neovim/wiki/Installing-Neovim
nvim-treesitter + parsers for `r`, `markdown` and `rnoweb`:
https://github.com/nvim-treesitter/nvim-treesitter
cmp-r (for auto-completion):
https://github.com/R-nvim/cmp-r
R >= 4.0.0:
http://www.r-project.org/
Notes about the R package `nvimcom`:
- The R package `nvimcom` is included in R.nvim 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 R.nvim
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 |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.
On OS X: Skim.
On Windows: SumatraPDF.
Suggestions for Unix (Linux, OS X, etc.):
Tmux >= 3.0: http://tmux.sourceforge.net
Tmux is required only if you want to run R in an external
terminal emulator (see |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 |external_term|). You should put in your Rprofile:
`library(colorout)`
Suggestions for bibliographic completion from Zotero in RMarkdown (`.Rmd`) and
Quarto (`.qmd`) documents:
- https://github.com/jalvesaq/zotcite
- https://github.com/jalvesaq/cmp-zotcite
------------------------------------------------------------------------------
3.2. Installation of the plugin
It is recommended that you use a plugin manager to install R.nvim. See the
Wiki:
https://github.com/R-nvim/R.nvim/wiki
------------------------------------------------------------------------------
3.3. Troubleshooting (if the plugin doesn't work)
Note: The <LocalLeader> is '\' by default.
The plugin is a |file-type| plugin. It will be active only if you are editing
a .R, .Rnw, .Rd, .Rmd 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: However, see:
https://github.com/jalvesaq/Nvim-R/wiki/Enable-Nvim-R-for-any-file-type
If the plugin is active, pressing <LocalLeader>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)
<
If R does not start with the <LocalLeader>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 Neovim and starting them again.
If you still see the message "The package nvimcom wasn't loaded yet" after
starting R, then R.nvim could not induce R to load nvimcom. R.nvim 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 R.nvim, as in the example below:
>r
if(Sys.getenv("RNVIM_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 <LocalLeader>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 |R.nvim-options| to see if there is an option that could make you
happier.
You can also install additional plugins to get other useful functionalities to
edit R code. Please, access R.nvim's wiki:
https://github.com/R-nvim/R.nvim/wiki
==============================================================================
4. Use *R.nvim-use*
By default, R.nvim will run R in a built-in terminal emulator, but you can
change this behavior (see |external_term|).
------------------------------------------------------------------------------
4.1. Key bindings
Note: The <LocalLeader> is '\' by default.
To use the plugin, open a .R, .Rnw, .Rd, .Rmd or .qmd file with Neovim
and type <LocalLeader>rf. Then, you will be able to use the plugin key
bindings to send commands to R.
The default key binding to quit R is <LocalLeader>rq, but if you quit Neovim
with R still running in a Neovim's built-in terminal emulator, R.nvim will
send to R the command `quit(save = "no")` (see the |auto_quit| option).
This plugin has many key bindings. Not all key bindings are enabled in all
file types supported by the plugin (r, rnoweb, rhelp, rmd, and quarto).
To see the list of mappings, do in Normal mode:
>vim
:RMapsDesc
<
Please see |R.nvim-key-bindings| to learn how to customize the key bindings.
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) and if the number of lines is higher than
|max_paste_lines|, 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 <LocalLeader>d. See the option `source_args` If you
want to see what lines are being sourced when sending a selection of lines.
The <LocalLeader>m{motion} command sends the lines from the motion command
that follows <LocalLeader>m, e.g. <LocalLeader>m} (from the current line to
the end of paragraph) or <LocalLeader>m3j (the next 3 lines including the
current one).
If the cursor is between manually inserted marks (a-z), the plugin will send
the lines between them to R if you press <LocalLeader>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<letter> 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 2 and press `ma`; go to line 6 and press `mb`; go
to line 4 and press `<LocalLeader>bb` to send lines 2 to 5 to R. Normally, Vim
marks are not visible, but there are plugins that highlight them.
Sending a selection of lines is actually a special case of sending a marked
block with the marks being `'<` and `'>`. That is the reason why the command
to send selection also works in Normal mode: it will send the lines that
were selected for the last time.
You can also use the command `:RSend` to type and, then, send a line of code
to R.
The command <LocalLeader>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, Neovim will
save the current buffer if it has any pending changes before performing the
tasks. After <LocalLeader>ao, Neovim 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 |routnotab| if you prefer that the file is open in a new split
window. Note: The command <LocalLeader>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 <M--> will write " <- " (see |assignment_keymap|
if you want to change this feature).
When you press <LocalLeader>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 <LocalLeader>rp, that is, while printing an
object. For example, if you run the code below and, then, press
<LocalLeader>rh and <LocalLeader>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)
<
To get help on an R topic, you can also type in Neovim (Normal mode):
>vim
:RHelp topic
<
You may close the R documentation buffer by simply pressing `q`. R
documentation is open in a 'modifiable' buffer to allow you to edit the
code in the "Examples" section. Press `<LocalLeader>`ge to go to the
"Examples" section and use R.nvim key bindings to send code to R Console.
The command <LocalLeader>td will run `dput()` with the object under cursor as
argument and insert the output in a new tab. The command <LocalLeader>rv will
also run `dput()` with the object under cursor as argument and show the output
in a new tab, while <LocalLeader>vs will show it in a horizontal split, and
<LocalLeader>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
<LocalLeader>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 R.nvim to call an external application to
display the data.frame or matrix (see |R.nvim-df-view|). All files involved in
these operations are created in R.nvim'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` <cmd> 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 of R from its console to Neovim. For example, to insert
the output of `dput(levels(var))`, where `var` is a factor vector, we could do
in Neovim:
>vim
:RInsert dput(levels(var))
<
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 command to send a line to R Console will make cursor
to jump to the next chunk. While editing Rnoweb files, the following commands
are available in Normal mode:
[count]<LocalLeader>gn : go to the next chunk of R code
[count]<LocalLeader>gN : go to the previous chunk of R code
You can also press <LocalLeader>gt to go the corresponding line in the
generated .tex file (if SyncTeX is enabled).
The commands <LocalLeader>cc and cd send the current chunk of R code
to R Console. The command <LocalLeader>ch sends the R code from the first
chunk up to the current line.
The commands <LocalLeader>kn builds the .tex file from Rnoweb using the knitr
package and <LocalLeader>kp compiles the PDF; for Sweave, the commands are,
respectively <LocalLeader>sw and <LocalLeader>sp. You can jump from the Rnoweb
file to the PDF (SyncTeX forward search) with the command <LocalLeader>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: <C-LeftMouse>
Skim: <S-Cmd-Click>
Sumatra: <Double-click>
In any case, the PDF viewer must be started by the R.nvim plugin. See
|R.nvim-SyncTeX| for details.
------------------------------------------------------------------------------
4.3. Auto-completion
If `cmp-r` (a source for `nvim-cmp`) is installed, Neovim can
automatically complete the names of R objects as you type them.
R.nvim does not complete the names of all functions of all installed packages
(see |start_libs|); only of loaded libraries.
For both `library()` and `require()`, when completing the first argument, the
popup list shows the names of installed packages.
------------------------------------------------------------------------------
4.4. The Object Browser
You have to use <LocalLeader>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 <Enter> 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("haven")
d <- read_spss("/path/to/spss/dataset.sav")
<
In the Object Browser window, while in Normal mode, you can either press
<Enter> or double click over a data.frame or list to show/hide its elements.
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 <Enter> 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 <Enter> 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 cmp-r is installed, the
list of .GlobalEnv objects will be automatically updated by R after each
successful command evaluation. This may slowdown R if its workspace has
too many objects, data.frames with too many columns or lists with too many
elements.
- 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 auto
completion. Also, they are not included in the Object Browser.
------------------------------------------------------------------------------
4.5. Build a tags file to jump to function definitions *RBuildTags*
Neovim 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. Syntax highlight of .Rout files
You can set both foreground and background colors of R output in your
`init.lua`. The example below is for an interface of Neovim with
'termguicolors' (see |true-color|):
>lua
if vim.o.termguicolors then
vim.g.rout_color_input = "guifg=#9e9e9e"
vim.g.rout_color_normal = "guifg=#ff5f00"
vim.g.rout_color_number = "guifg=#ffaf00"
vim.g.rout_color_integer = "guifg=#feaf00"
vim.g.rout_color_float = "guifg=#fdaf00"
vim.g.rout_color_complex = "guifg=#fcaf00"
vim.g.rout_color_negnum = "guifg=#d7afff"
vim.g.rout_color_negfloat = "guifg=#d6afff"
vim.g.rout_color_date = "guifg=#00d7af"
vim.g.rout_color_true = "guifg=#5dd685"
vim.g.rout_color_false = "guifg=#ff5d5e"
vim.g.rout_color_inf = "guifg=#10aed7"
vim.g.rout_color_constant = "guifg=#5fafcf"
vim.g.rout_color_string = "guifg=#5fd7af"
vim.g.rout_color_error = "guifg=#ffffff guibg=#c40000"
vim.g.rout_color_warn = "guifg=#d00000"
vim.g.rout_color_index = "guifg=#d0d080"
end
<
If you prefer that R output is highlighted using your current `colorscheme`,
put in your `init.lua`:
>lua
vim.g.rout_follow_colorscheme = true
<
==============================================================================
5. Known bugs and workarounds *R.nvim-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 Neovim;
others would be very time consuming to fix without breaking anything.
------------------------------------------------------------------------------
5.1. R must be started by Neovim
The communication between Neovim and R will work only if R was started by the
running Neovim instance through the <LocalLeader>rf command. If you use R.nvim
to start R in an external terminal and, then close Neovim and open it again,
there will be no communication between R and the new Neovim instance.
Please see the explanation on the communication between Neovim and R at the
end of
https://github.com/R-nvim/R.nvim/blob/master/README.md
------------------------------------------------------------------------------
5.2. Cannot raise window (web browser or PDF viewer)
When you generate an HTML or PDF document from a Quarto, Rmd, or Rnoweb
document, R.nvim can raise (focus) the web browser or PDF viewer if you are
using Xorg or Sway (both on Linux). The necessary code was not written yet for
other systems (macOS, Windows, and most Wayland compositors on Linux). Please,
see the function `utils.get_focused_win_info()` if you want to fix the issue
on your system.
------------------------------------------------------------------------------
5.3. 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.4. Wrong message that "R is busy" (Windows only)
On Windows, when code is sent from Neovim 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 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 Neovim
that "R is busy" and Neovim will display this message. Everything should work
as expected again after any valid code is executed in the R Console.
------------------------------------------------------------------------------
5.5. Error if there is no package installed (on Windows only)
On Windows, Neovim may fail to recognize that a directory is not writable, and
this is required by R.nvim to detect if it is necessary to create the
directory defined by `$R_LIBS_USER` environment variable. Consequently, R.nvim
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 R.nvim.
------------------------------------------------------------------------------
5.6. ~/.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("This message will break compilation by gcc!")
<
------------------------------------------------------------------------------
5.7 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, all R.nvim
variables will be used at their default values. 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 *R.nvim-options*
The complete list of options and their defined values can be seen with the
command:
>vim
:RConfigShow
<
|auto_start| Start R automatically
|objbr_auto_start| Start the Object Browser automatically
|built-in-terminal| Options to control Neovim's built-in terminal
|external_term| Command to run R in an external terminal emulator
|silent_term| Do not show terminal errors
|set_home_env| Set the value of $HOME for R (Windows only)
|save_win_pos| Save position of Rgui window (Windows only)
|arrange_windows| Restore position of R window (Windows only)
|assignment_keymap| Choose what to convert into ' <- '
|pipe_keymap| Choose what to convert into ' |> ' (or ' %>% ')
|pipe_version| Either "native"/"|>" or "magrittr"/"%>%"
|rnowebchunk| Convert '<' into '<<>>=\n@' in Rnoweb files
|rmdchunk| Convert grave accent chunk into delimiters
|rproj_prioritise| Use .Rproj file to override options
|objbr_place| Placement of Object Browser
|objbr_w| Initial width of Object Browser window
|objbr_h| Initial height of Object Browser window
|objbr_opendf| Display data.frames open in the Object Browser
|objbr_openlist| Display lists open in the Object Browser
|objbr_allnames| Display hidden objects in the Object Browser
|nvimpager| Use Neovim to see R documentation
|open_example| Use Neovim to display R examples
|R_path| Directory where R is
|R_app|, |R_cmd| Names of R applications
|R_args| Arguments to pass to R
|start_libs| Objects for auto completion and syntax highlight
|Rout_more_colors| More syntax highlighting in R output
|routnotab| Show output of R CMD BATCH in new window
|config_tmux| Don't use a specially built Tmux config file
|rconsole_height| Number of lines of R Console
|rconsole_width| Number of columns of R Console
|min_editor_width| Minimum number of columns of editor after R start
|applescript| Use osascript in Mac OS X to run R.app
|RStudio_cmd| Run RStudio instead of R.
|listmethods| Do `nvim.list.args()` instead of `args()`
|specialplot| Do `nvim.plot()` instead of `plot()`
|paragraph_begin| Send paragraph from its beginning
|parenblock| Send lines until closing parenthesis
|bracketed_paste| Bracket R code in special escape sequences
|clear_console| Send <C-L> to clear R's console
|source_args| Arguments to R `source()` function
|max_paste_lines| Maximum number of lines to be pasted into R Console
|latexcmd| Command to run on .tex files
|texerr| Show a summary of LaTeX errors after compilation
|sweaveargs| Arguments do `Sweave()`
|rmd_environment| Environment in which to save evaluated rmd code
|rmarkdown_args| Further options to be passed to `rmarkdown::render()`
|quarto_render_args| Options to be passed to `quarto::quarto_render()`
|quarto_preview_args| Options to be passed to `quarto::quarto_preview()`
|clear_line| Clear R Console line before sending a command
|editing_mode| The mode defined in your `~/.inputrc`
|pdfviewer| PDF application used to open PDF documents
|open_pdf| Open PDF after processing Rmd, Quarto or Rnoweb file
|open_html| Open HTML after processing Rmd or Quarto
|insert_mode_cmds| Allow R commands in insert mode
|rmhidden| Remove hidden objects from R workspace
|wait| Time to wait for nvimcom loading
|wait_reply| Time to wait for R reply
|setwd| Directory where to start R
|hook| Lua functions to call after certain events
|user_maps_only| Only user specified key bindings
|disable_cmds| List of commands to be disabled
|tmpdir| Where temporary files are created
|compldir| Where lists for auto completion are stored
|remote_compldir| Mount point of remote cache directory
|R.nvim-df-view| Options for visualizing a data.frame or matrix
|R.nvim-SyncTeX| Options for SyncTeX
------------------------------------------------------------------------------
6.1. Automatic start: R and Object Browser *auto_start*
*objbr_auto_start*
By default, you have to start R manually with the command <LocalLeader>rf.
If you want that R starts automatically when you load an R script while
starting Neovim, put in your config:
>lua
auto_start = "on startup"
<
If you want that R starts automatically when you start editing an R script
even if Neovim is already started, put in your config:
>lua
auto_start = "always"
<
The default value of `auto_start` is "no".
See also: |hook|.
If you want to always start the Object Browser immediately after starting R,
put in your config:
>lua
objbr_auto_start = true
<
See also: |hook|.
------------------------------------------------------------------------------
6.2. R in Neovim built-in terminal *R-built-in-terminal*
*esc_term*
By default, R runs in a Neovim buffer created with the command |:term|,
and the <Esc> 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 <Esc> key in R, for example if you want to use `vi`, `vim` or
`nvim` within R Console, put in your config:
>lua
esc_term = false
<
Then, you will have to press the default <C-\><C-n> to go from Terminal to
Normal mode.
R.nvim sets the option "editor" to a function that makes the object to be
edited in a new tab when `esc_term` = `true` (the default value).
*close_term*
Neovim does not close its built-in terminal emulator when the application
running in it quits, but R.nvim does close it for you. If you rather prefer
that the terminal remains open after R quitting, put in your config:
>lua
close_term = false
<
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, R.nvim will move the cursor to the last line of R Console before
sending a command to it, forcing the auto scrolling of the terminal. You can
disable this feature with the option:
>lua
auto_scroll = false
<
*hl_term*
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 `hl_term` (`false` or `true`) determines whether Neovim should syntax
highlight the R output, and its default value will be set to `false` if the
package colorout is loaded. If you prefer do not rely on the auto detection
of colorout, you should set the value of `hl_term` in your config. Example:
>lua
hl_term = false
< *OutDec*
Right after starting R, R.nvim 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 config:
>lua
OutDec = ","
< *setwidth*
On Unix systems, BEFORE sending a command to R Console, if the terminal width
has changed, Neovim will send to nvimcom the command `options(width=X)`,
where X is the new terminal width. You can set the value of `setwidth` to 0 to
avoid the width being set. Example:
>lua
setwidth = false
<
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 config, R.nvim will calculate the
number of columns available for R as the window width - 6. If you want a
different adjustment, you should set `setwidth` as a negative value between
-1 and -16. Example:
>lua
setwidth = -7
<
You can also set the value of `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.
*buffer_opts*
R.nvim 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
`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:
>lua
buffer_opts = "winfixwidth winfixheight nobuflisted"
<
If you do not want to run R in Neovim's built-in terminal emulator, you
have to install Tmux >= 3.0, and then put in your config:
>lua
external_term = true
<
Then, R will start in an external terminal emulator (useful if you use two
monitors and want Neovim and R separate from each other), and Tmux will be
used to send commands from Neovim to R.
------------------------------------------------------------------------------
6.3. Terminal emulator (Linux/Unix only) *external_term*
*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 Neovim's built-in terminal emulator, unless you set the value of
`external_term`, which can be a boolean value, the name of the terminal
emulator or the complete command to run the terminal emulator. On Windows,
only boolean values are valid; if `true` R.nvim will 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. kitty
3. gnome-terminal
4. konsole
5. xfce4-terminal
6. alacritty
7. xterm
If the value of `external_term` is `true`, 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 config. Below are some examples of
how to set the value of `external_term`:
>lua
external_term = true -- Run R in an external terminal (or Rgui.exe)
external_term = "konsole" -- Run R in konsole
<
If you are not satisfied with the way your terminal emulator is called by the
plugin, you may define in your config the variable `external_term` as the
complete command to run the terminal. Examples:
>lua
external_term = "xterm -title R -e"
external_term = "tilix -a session-add-right -e"
external_term = "xfce4-terminal --icon=/path/to/icons/R.png --title=R -x"
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 config:
>lua
silent_term = true
<
*auto_quit*
When Neovim is closed, the R connection with Neovim is closed and cannot be
reestablished. Thus, unless you usually keep working on the R Console after
quitting Neovim, you will prefer that R quits automatically when you leave
Neovim. In this case, you have to put in your config:
>lua
auto_quit = true
<
The default value of `auto_quit` is `true` if R is running in a Neovim's
built-in terminal emulator and `false` otherwise.
------------------------------------------------------------------------------
6.4. Windows specific options *save_win_pos*
*arrange_windows*
*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 |init.lua|. Example:
>lua
vim.env.PATH = "C:\\rtools40\\mingw64\\bin;C:\\rtools40\\usr\\bin;" .. $PATH
<
By default, R.nvim will save the positions of R Console and Neovim windows
when you quit R with the <LocalLeader>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 config:
>lua
save_win_pos = false
arrange_windows = false
<
If you want Rgui window always in a specific arrangement, regardless of
its state when you have quit R for the last time, you should arrange it
in the way you want, quit R, change in your config only the value of
`save_win_pos` and, finally, quit Neovim.
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 config:
>lua
set_home_env = false
<
------------------------------------------------------------------------------
6.5. Assignment pipe operators *assignment_keymap*
*pipe_keymap*
*pipe_version*
While editing R code, <M--> is replaced with `<-`. To disable this feature,
put in your config:
>lua
assignment_keymap = ""
<
If you want to bind other keys to be replaced by `<-`, set the value of
|assignment_keymap| in your config, as in the example below which emulates,
Emacs+ESS behavior:
>lua
assignment_keymap = "_"
<
Note: You can't map <C-=> because in Neovim only alphabetic letters can be
mapped in combination with the CTRL key.
There is a keybinding for inserting the pipe operator (`|>`) which defaults to
`<LocalLeader>,` and is configurable with the option `pipe_keymap`. To disable
this feature, put in your config:
>lua
pipe_keymap = ""
<
R.nvim is aware of `.Rproj` files (the project-level configuration files used
by RStudio). This may, for example, change whether `pipe_keymap` inserts `|>`
or `%>%` for a particular project. See the option |rproj_prioritise| for a
full list of the behaviours which may be affected by `.Rproj` files, or to
change whether they should affect things at all.
------------------------------------------------------------------------------
6.6. Rnoweb completion of code block *rnowebchunk*
*rmdchunk*
In Rnoweb files, a `<` is replaced with `<<>>=\n@`. To disable this feature,
put in your config:
>lua
rnowebchunk = false
<
Similarly, in Rmd and Quarto files, the grave accent (backtick) is replaced
with chunk delimiters unless you put in your config:
>lua
rmdchunk = 0
<
You can also define a different shortcut for `rmdchunk`. For example, to use
two backticks instead of one to trigger the completion of the chunk delimiter,
put in your config:
>lua
rmdchunk = "``"
<
If `rmdchunk = 2` (the default), in addition of 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.
------------------------------------------------------------------------------
6.7. Object Browser options *objbr_w*
*objbr_h*
*objbr_place*