-
Notifications
You must be signed in to change notification settings - Fork 127
/
Copy pathNvim-R.txt
2923 lines (2497 loc) · 114 KB
/
Nvim-R.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
*Nvim-R.txt* *Nvim-R*
Nvim-R~
Plugin to work with R~
Authors: Jakson A. Aquino <[email protected]>
Jose Claudio Faria <[email protected]>
Version: 0.9.19
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|
==============================================================================
*Nvim-R-overview*
1. Overview~
This plugin improves the support for editing R code with both Vim and Neovim,
integrating them with R. Stable versions of this plugin are available
available at:
https://github.com/jalvesaq/Nvim-R/releases
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/issues
Patches and git pull requests are welcome. If you want a feature that only few
people might be interested in, you can write a script to be sourced by Nvim-R
(see |R_source|).
==============================================================================
*Nvim-R-features*
2. Main features~
* Syntax highlighting for R code, including:
- Special characters in strings.
- Functions of loaded packages.
- Special highlighting for R output (.Rout files).
- Spell check only strings and comments.
* 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.
* 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.
==============================================================================
*Nvim-R-installation*
3. 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.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
or 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.
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 automatic code completion (Neovim only):~
- https://github.com/hrsh7th/nvim-cmp
- https://github.com/jalvesaq/cmp-nvim-r
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:
>
: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 <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, .Rrst or .qmd file. The 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 <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`:
>
options(nvimcom.verbose = 4)
<
To see messages received by Neovim, uncomment the first line of the function
`ROnJobStdout()` at `R/nvimrcom.vim` and delete the string "DEBUG:". It will
become:
>
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 <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 Vim/Neovim 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:
>
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 <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 |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. Below are some suggestions.
VOoM - Outliner~
To use VOoM as outliner for Rmd documents, you should configure it to use the
"pandoc" engine for outlining the structure of Rmd documents, and "latex" for
Rnoweb ones. Example for |vimrc|:
>
let voom_ft_modes = {'markdown': 'pandoc', 'rmd': 'pandoc',
\ 'quarto': 'pandoc', 'rnoweb': 'latex'}
<
And for |init.lua|:
>
vim.g.voom_ft_modes = {
markdown = 'pandoc',
rmd = 'pandoc',
quarto = 'pandoc',
rnoweb = 'latex'
}
<
You can install VOoM from: https://github.com/vim-voom/VOoM
Zotero - zotcite~
If you use either RMarkdown or Quarto to write academic papers and Zotero for
reference management, you may want to try zotcite:
https://github.com/jalvesaq/zotcite
Other plugins~
Please, access Nvim-R's wiki:
https://github.com/jalvesaq/Nvim-R/wiki
==============================================================================
*Nvim-R-use*
4. 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 <LocalLeader> is '\' by default.
To use the plugin, open a .R, .Rnw, .Rd, .Rmd, .Rrst, or .qmd file with Vim
and type <LocalLeader>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 <LocalLeader>. 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<Left>
. Right part of line (cur) \r<Right>
. 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
--------------------------------------------------------
. Indent (line) ==
. Indent (selected lines) =
. Indent (whole buffer) gg=G
--------------------------------------------------------
. 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 <LocalLeader>d. If you want to see
what lines are being sourced when sending a selection of lines, you can use
either <LocalLeader>se or <LocalLeader>sa instead of <LocalLeader>ss. 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
line).
If the cursor is between any two marks, 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|). Normally, Vim marks are no 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:
>
nmap <LocalLeader>: :RSend
<
Observe that there is an empty space after `:RSend`, so you do not have to
type it.
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, Vim will
save the current buffer if it has any pending changes before performing the
tasks. After <LocalLeader>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 <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 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 <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:
>
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`:
>
summary(object = x)
summary(object = m)
<
To get help on an R topic, you can also type in Vim (Normal mode):
>
:Rhelp topic
<
The command may be abbreviated to `:Rh` and you can either press <Tab> 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 <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 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` <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 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:
>
: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]<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, ce, cd and ca 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 the Rnoweb one 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 (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>
Evince: <C-LeftMouse>
Okular: <S-LeftMouse>
Skim: <S-Cmd-Click>
Sumatra: <Double-click>
In any case, the pdf viewer must be started by the Nvim-R plugin. See
|Nvim-R-SyncTeX| for details.
------------------------------------------------------------------------------
4.3. Omni completion and syntax highlighting~
The plugin adds some features to the default syntax highlight of R code. One
such feature is the highlight of R functions.
Note: If you have too many loaded packages Vim may be unable to load the
list of functions for syntax highlight.
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 <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:
>
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
<Enter> 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 <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):
>
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.
------------------------------------------------------------------------------
*RBuildTags*
4.6. Build a tags file to jump to function definitions~
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.
------------------------------------------------------------------------------
*debug-R-functions*
4.7. Debugging R functions (Unix only)~
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 <LocalLeader>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:
>
add.one <- function(x){
y <- x + 1
print(y)
return(invisible(NULL))
}
<
You could debug the `add.one()` function from another script such as:
>
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:
>
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:
>
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:
>
hi QuickFixLine ctermfg=231 ctermbg=23 guifg=white guibg=#005f5f
<
------------------------------------------------------------------------------
4.8. 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|):
>
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 are running Vim with support for 256 colors, you could use lines like
these:
>
if &t_Co == 256
let rout_color_input = 'ctermfg=247'
let rout_color_normal = 'ctermfg=39'
" etc.
endif
<
You can also set both true colors and 256 colors at the same time:
>
let rout_color_input = 'ctermfg=247 guifg=#9e9e9e'
let rout_color_normal = 'ctermfg=39 guifg=#ff5f00'
" etc.
<
To know what number corresponds to your preferred color (among the 256
possibilities), hover you mouse pointer over the table of colors built by:
>
library("colorout")
show256Colors()
<
If you prefer that R output is highlighted using your current `colorscheme`,
put in your `vimrc`:
>
let rout_follow_colorscheme = 1
<
==============================================================================
*Nvim-R-known-bugs*
5. Known bugs and workarounds~
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'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.2. 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.3. 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.4. 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.5. 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.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:
>
print("Hello bug!")
<
------------------------------------------------------------------------------
5.7. R must be started by Vim~
The communication between Vim and R will work only if R was started by
Vim through the <LocalLeader>rf command because the plugin was designed to
connect each Vim instance with its own R instance.
If you start R before Vim, it will not inherit from Vim the environment
variables `R_DEFAULT_PACKAGES`, `NVIMR_TMPDIR`, `NVIMR_COMPLDIR`, `NVIMR_ID`, and
`NVIMR_SECRET`. The first one induces R to load nvimcom; the second variable is
the path used by the R package nvimcom to save temporary files used by Nvim-R
to: perform omni completion, show R documentation in a Vim buffer, and update
the Object Browser. The two last ones are used by Nvim-R and by nvimcom to
know that the connections are valid. Unless you are running R in a Neovim's
built-in terminal (which is the default on Unix), if you use Vim to start R,
but then close Vim, some variables will become outdated. Additionally, Nvim-R
sets the value of its internal variable SendCmdToR from SendCmdToR_fake to the
appropriate value when R is successfully started. It is possible to set the
values of all those variables and start the TCP server manually, but it
is not practical to do so.
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
==============================================================================
*Nvim-R-options*
6. Options~
|R_auto_start| Start R automatically
|R_objbr_auto_start| Start the Object Browser automatically
|R-built-in-terminal| Options to control Vim/Neovim'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