forked from vim-scripts/Vim-R-plugin
-
Notifications
You must be signed in to change notification settings - Fork 34
/
r-plugin.txt
2320 lines (1956 loc) · 93.3 KB
/
r-plugin.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-plugin.txt* *vim-r-plugin*
Vim-R-plugin~
Plugin to work with R~
Authors: Jakson A. Aquino <jalvesaq@gmail.com>
Jose Claudio Faria <joseclaudio.faria@gmail.com>
Version: 0.9.8
For Vim version 7.3
1. Overview |r-plugin-overview|
2. Main features |r-plugin-features|
3. Installation |r-plugin-installation|
4. Use |r-plugin-use|
5. Known bugs and workarounds |r-plugin-known-bugs|
6. Options |r-plugin-options|
7. Custom key bindings |r-plugin-key-bindings|
8. Files |r-plugin-files|
9. FAQ and tips |r-plugin-tips|
10. News |r-plugin-news|
==============================================================================
*r-plugin-overview*
1. Overview~
This plugin improves Vim's support for editing R code and makes it possible to
integrate Vim with R.
It uses some ideas and code from Johannes Ranke's (vim-r-plugin), Eric Van
Dewoestine's (screen.vim plugin), Vincent Nijs (R.vim for Mac OS X) and some
ideas from the Tinn-R (Windows only) project.
The latest stable version of this plugin is available at:
http://www.vim.org/scripts/script.php?script_id=2628
Feedback is welcomed. Please submit bug reports and feature requests to the
developers, we are very interested in what you like and what you would like to
see in future releases. Do not like a feature? Tell us and we may add an
option to disable it. Cryptic error message are bugs... Please report them.
The plugin should emit useful warnings if you do things it was not programmed
to deal with.
==============================================================================
*r-plugin-features*
2. Main features~
* Syntax highlighting for R code, including:
- Special characters in strings.
- Functions of all installed packages (must be updated manually).
- Special highlighting for R output (.Rout files).
- Spell check only strings and comments.
- Fold code when foldmethod=syntax.
* Syntax highlighting for RHelp syntax.
* Smart indentation for R, RHelp and Rnoweb syntax.
* 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 and pdflatex commands.
* Omni completion (auto-completion) for R objects (.GlobalEnv and installed
packages). The list of installed packages must be updated manually.
* Auto-completion of function arguments.
* Ability to see R's documentation in a Vim's 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 formating 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.
* Most of the plugin's behavior is customizable.
==============================================================================
*r-plugin-installation*
3. Installation~
The installation instructions are split in four sections: (1) general
instructions for all operating systems; (2) instructions that are specific for
either Unix/Linux/OSX or Windows; (3) troubleshooting; and (4) optional steps.
3.1. General instructions I~
Note: Most of the plugin commands require that you type the <LocalLeader>
which is '\' by default.
You need to activate plugins and indentation according to 'filetype'. You
should have at least the following options in your |vimrc|:
>
set nocompatible
syntax enable
filetype plugin on
filetype indent on
<
Make a backup of your ~/.vim directory because existing files will be
replaced. Please, look at |r-plugin-files| to see the list of files.
3.2. Operating system specific instructions~
3.2.1. Unix (Linux, OS X, etc.)~
Uncompress the archive:
>
unzip vim-r-plugin-*.zip -d ~/.vim
<
Start Vim and build the tags file for this document (and others that eventually
are in the same directory):
>
:helptags ~/.vim/doc
<
Note: If you are using Mac OS X and prefer that Vim uses AppleScript to send
commands to R, then the installation is finished and you should now read
sections 3.3 and 3.4.
In addition to having R installed in your system, this plugin has the
following dependencies:
Depends:~
Vim >= 7.3 with Python support.
Tmux >= 1.5: http://tmux.sourceforge.net
Screen plugin: http://www.vim.org/scripts/script.php?script_id=2711
vimcom >= 0.9-3: An R package.
Suggests:~
ncurses-term: http://invisible-island.net/ncurses
colorout: An R package.
setwidth: An R package.
Note: Tmux and ncurses-term are already packaged for most GNU/Linux
distributions and other Unix variants. The library ncurses-term is
necessary only for 256 color support in the terminal emulator.
Unfortunately their installation instructions vary widely and are beyond
the scope of this documentation.
The vimcom package creates a server on R to allow the communication with
Vim. The package is not used to send commands from Vim to R, but it is
necessary to open R documentation in Vim's buffer, run the Object Browser,
run either Sweave() or knit() on the document being edited. It also has
some functions called by Vim such as vim.plot(), vim.print(), and
vim.bol(). This last one is required to build the data base used in
omnicompletion.
The colorout package colorizes the R output and the setwidth package
adjusts the value of options("width") whenever the terminal is resized.
They can be installed from within R. The colorout package is available at
http://www.lepem.ufc.br/jaa/colorout.html while setwidth and vimcom can be
installed as usual:
>
install.packages(c("vimcom", "setwidth"))
<
You certainly will want to put something like the following at the end of
your ~/.Rprofile:
>
if(interactive()){
library(colorout)
library(setwidth)
library(vimcom)
}
<
The plugin will run R inside a Tmux session. If you are using Vim (not GVim),
you may be interested in reading |r-plugin-tmux| section to learn a few useful
shortcuts. The tmux.conf file created by the plugin sets Tmux to work with Vi
key bindings, <C-a> as the escape character and also enables the mouse for
Tmux.
Note: The plugin can use different mechanisms to send commands to R. The
mechanism that will be used depends on both what applications and plugins you
have installed and what options you have in your |vimrc|. The two lists below
show how the plugin will work on Linux in different conditions:
Vim Condition~
------------------------------ -------------------------------------
Screen plugin (Tmux) default on Linux
Screen plugin (GNU Screen) vimrplugin_tmux = 0 or Tmux not found
Tmux (external terminal) vimrplugin_screenplugin = 0
GNU Screen (external terminal) vimrplugin_screenplugin = 0 and no Tmux
GVim Condition~
------------------------------ -------------------------------------
Tmux (external terminal) default on Linux
GNU Screen (external terminal) vimrplugin_tmux = 0 or Tmux not found
Note: On Mac OS X the plugin will use AppleScript in both Vim and GVim unless
vimrplugin_applescript = 0.
3.2.2. Windows~
In addition to having R installed in your system, this plugin requires users
to install external dependencies:
* Vim's version must be >= 7.3
* Python: http://www.python.org/download/
Note: The official Vim is 32 bit and, thus, Python must be 32 bit too.
However, Vim and R run as independent processes, that is, you may have
32 bit Vim sending commands to 64 bit R.
Note: Be careful to download the correct Python version because Vim
needs a specific version of Python DLL. For example, the official
Vim 7.3 for Windows needs either Python 2.7 or 3.1. If Python was
not installed or was not found, the Vim-R-plugin will output
information about what Python version Vim was compiled against. Do
the following if you want to discover this information manually:
1. Type :version in Vim (normal mode).
2. Look for a string like -DDYNAMIC_PYTHON_DLL="python27.dll".
3. Install the Python version which corresponds to the version
which Vim was linked against. In the example of step 2
(python27.dll) the required Python version is 2.7.x.
* pywin32: http://sourceforge.net/projects/pywin32/
Note: The default download may not match the Python version Vim was
linked against. You have to "View all files" on the download page to
find the file that matches exactly the version of Python that you
installed.
* vimcom >= 0.9-3: An R package. You can install it with the R command
install.packages("vimcom"). The vimcom package creates a server on R to
allow the communication with Vim. You certainly will want to put the
following lines at the end of your Rprofile (usually at
~/Documents/.Rprofile):
>
if(interactive()){
library(vimcom)
}
<
Create your |vimfiles| directory if you do not have it yet. Its path will be
similar to one of the following:
>
C:\Documents and Settings\yourlogin\vimfiles
C:\Users\yourlogin\vimfiles
<
Uncompress the archive. Right click on the plugin's zip file and choose
"Extract all". Then choose ~/vimfiles as the destination directory.
Start Vim and build the tags file for this document (and others that eventually
are in the same directory):
>
:helptags ~\vimfiles\doc
<
Start editing an R file with GVim and try to send some lines to R Console. You
may have to adjust the value of |vimrplugin_sleeptime|.
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 or .Rnw file. The menu items and tool bar buttons will not be visible and
the key bindings will not be active while editing either unnamed files or
files with name extensions other than .R or .Rnw. If the plugin is active,
pressing <LocalLeader>rf should start R.
Look at the ~/.vim (Linux, Unix, OS X) or ~/vimfiles (Windows) directory. Is
there a subdirectory named "r-plugin"? If not, then you unpacked the plugin in
the wrong place.
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.
Are you using Debian, Ubuntu or other Debian based Linux distribution? If yes,
you may prefer to install the Debian package available at:
http://www.lepem.ufc.br/jaa/vim-r-plugin.html
3.4. General instructions II (optional steps)~
3.4.1 Update list of objects~
Start R and update the list of objects for omni completion and syntax
highlight (see |:RUpdateObjList| for details).
3.4.2 Customize the plugin~
Please, read the section |r-plugin-options|. Emacs/ESS users should read the
section Indenting setup (|r-plugin-indenting|) of this document.
3.4.3 Hide unused buttons~
Edit GVim's toolbar and remove the buttons that you never use. The plugin adds
some buttons to the toolbar, but you may not see them because GVim has too
many buttons by default. Please see the page below to know how to hide buttons
on the toolbar:
http://vim.wikia.com/wiki/Hide_toolbar_or_menus_to_see_more_text
3.4.4 Install additional plugins~
You may be interested in installing additional general plugins to get
functionality not provided by this file type plugin. ShowMarks and snipMate
are particularly interesting. Please read |r-plugin-tips| for details.
==============================================================================
*r-plugin-use*
4. Use~
4.1. Key bindings~
Note: The <LocalLeader> is '\' by default.
Note: It is recommended the use of different keys for <Leader> and
<LocalLeader> to avoid clashes between filetype plugins and general plugins
key binds. See |filetype-plugins| and |maplocalleader|.
To use the plugin, open a .R or .Rnw or .Rd 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 and, in
some cases, toolbar buttons. In the list below, the backslash represents the
<LocalLeader>. Not all menu items and key bindings are
enabled in all filetypes supported by the plugin (r, rnoweb, rhelp):
Start/Close
. Start R (default) \rf
. Start R --vanilla \rv
. Start R (custom) \rc
--------------------------------------------------------
. Close R (no save) \rq
-----------------------------------------------------------
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
--------------------------------------------------------
. 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
--------------------------------------------------------
. 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>
-----------------------------------------------------------
Command
. List space \rl
. Clear console \rr
. Clear all \rm
--------------------------------------------------------
. Print (cur) \rp
. Names (cur) \rn
. Structure (cur) \rt
--------------------------------------------------------
. 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 and PDF (cur file, verbose) (Windows) \sv
. Sweave, BibTeX and PDF (cur file) (Linux/Unix) \sb
--------------------------------------------------------
. Knit (cur file) \kn
. Spin (cur file) \ks
. Knit and PDF (cur file) \kp
. Knit and Beamer PDF (cur file) (Only Rmd) \kl
. Knit and PDF (cur file, verbose) (Windows) \kv
. Knit, BibTeX and PDF (cur file) (Linux/Unix) \kb
--------------------------------------------------------
. Open PDF (cur file) \op
--------------------------------------------------------
. Build tags file (cur dir) :RBuildTags
-----------------------------------------------------------
Edit
. Insert "<-" _
. Complete object name ^X^O
. Complete function arguments ^X^A
--------------------------------------------------------
. Indent (line) ==
. Indent (selected lines) =
. Indent (whole buffer) gg=G
--------------------------------------------------------
. Comment/Uncomment (line, sel) \xx
. Add/Align right comment (line, sel) \;
--------------------------------------------------------
. Go (next R chunk) gn
. Go (previous R chunk) gN
-----------------------------------------------------------
Syntax
. Build omnils (loaded packages) :RUpdateObjList
-----------------------------------------------------------
Object Browser
. Show/Update \ro
. Expand (all lists) \r=
. Collapse (all lists) \r-
. Toggle (cur) Enter
-----------------------------------------------------------
Help (plugin)
Help (R) :Rhelp
-----------------------------------------------------------
Please see |r-plugin-key-bindings| to learn how to customize the key bindings
without editing the plugin directly.
After the command <LocalLeader>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. Please see
|vimrplugin_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
|vimrplugin_underscore| 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 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 documentations and print different objects in each
case:
>
y <- rnorm(100)
x <- rnorm(100)
m <- lm(y ~ x)
summary(x)
summary(m)
<
When completing object names (CTRL-X CTRL-O) and function arguments (CTRL-X
CTRL-A) you have to press CTRL-N to go foward in the list and CTRL-P to go
backward (see |popupmenu-completion|). Note: if using Vim in a terminal
emulator, Tmux will capture the CTRL-A command. You have to do CTRL-A twice to
pass a single CTRL-A to Vim. For rnoweb, rmd and rrst file types, CTRL-X
CTRL-A can also be used to complete knitr chunk options if the cursor is
inside the chunk header.
If R is not running or if it is running but is busy the completion will be
based on information saved with the command |:RUpdateObjList|. Otherwise, the
pop up menu for completion of function arguments will include an additional
line with the name of the library where the function is (if the function name
can be found in more than one library) and the function method (if what is
being shown are the arguments of a method and not of the function itself).
To get help on an R topic, 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 one built by |:RUpdateObjList|.
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).
4.2. Edition of 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
4.3. Omni completion and the highlighting of functions~
*:RUpdateObjList*
The plugin adds some features to the default syntax highlight of R code. One
such feature is the highlight of R functions. However, only functions that
R loads by default are highlighted. To add functions of other libraries, you
should do the following:
1. Start R from within Vim.
2. Use R's library() to load the libraries whose functions you want
highlighted.
3. Run the following command in Vim's Normal mode:
:RUpdateObjList
The command :RUpdateObjList in addition to creating a list of function names
to be highlighted also creates a file containing a list of objects for omni
completion (|compl-omni|) including all objects currently in R's workspace,
except the .GlobalEnv objects. These two lists are stored permanently in the
~/.vim/r-plugin directory.
The command :RUpdateObjList waits 60 seconds to R finish building the list.
If this time is not enough to your system, please, set a different value of
|vimrplugin_buildwait|.
You should run :RUpdateObjList whenever you upgrade R since some functions
are removed and new ones are added at each new R version.
Note: If you have too many loaded packages Vim may be unable to load the list
of functions for syntax highlight.
4.4. Omni completion~
Vim can automatically complete the names of R objects when CTRL-X CTRL-O is
pressed in insert mode (see |omni-completion| for details and 'completeopt' to
know how to customize the |omni-completion|). Omni completion shows in a pop
up menu the name of the object, its class and its environment (most
frequently, its package name). If the object is a function, its arguments are
shown in a separate window.
If a data.frame is found, while building the list of objects, the columns in
the data.frame are added to the list. When you try to use omni completion to
complete the name of a data.frame, the columns are not shown. But when the
data.frame name is already complete, and you have inserted the '$' symbol,
omni completion will show the column names.
Vim uses two files: one for the objects of .GlobalEnv and the other for all
other objects. The .GlobalEnv list is stored in the /tmp/r-plugin-yourlogin
directory and, thus, is deleted after each reboot. The other file is stored in
~/.vim/r-plugin and remains available until you manually rebuild it with the
command: |:RUpdateObjList|.
4.5. The Object Browser~
You have to do <LocalLeader>ro to either start or updated the Object Browser.
The updating is automatic only if the Object Browser is running in a separate
Tmux panel. The Object Browser has two views: .GlobalEnv and Libraries. If you
either press <Enter> or double click (GVim or Vim with 'mouse' set to "a") 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 an object has the attribute "label", it will also
be displayed. Please, see the R help for package vimcom for some options to
control the Object Browser behavior. 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> over a
library to see its objects. In the Object Browser, the libraries have the
color defined by the PreProc highlighting group, and 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 R function (if
any) used to classify the objects:
PreProc libraries
Number is.numeric()
String is.character()
Special is.factor()
Boolean is.logical()
Type is.list()
Function is.function()
Statement isS4()
When running in a terminal emulator under Tmux, the Object Browser will be
updated automatically. One limitation is that objects made available by the
command data() may not have their classes recognized in the GlobalEnv view.
When running under Tmux, the Normal mode command d deletes the object on the
cursor line or the element of a list or data.frame. If the Object Browser is
showing the libraries, the library currently under the cursor line is
detached. The Object Browser may stop to be updated automatically for a few
seconds if you press d many times quickly. Please, use a value greater than
250 to set the time in milliseconds that the Object Browser should wait for R
message that the object was already deleted (see |vimrplugin_ob_sleep|).
4.6. Commenting and uncommenting lines~
You can toggle the state of a line as either commented or uncommented by
typing <LocalLeader>xx.
You can also add comments to the right of a line with the <LocalLeader>;
shortcut. By default, the comment starts at the 40th column, which can be
changed by setting the value of r_indent_comment_column, as below:
>
let r_indent_comment_column = 20
<
If the line is longer than 38 characters, the comment will start two columns
after the last character in the line. If you are running <LocalLeader>; over a
selection of lines, the comments will be aligned according to the longest
line.
While typing comments the leader comment string is automatically added to new
lines when you reach 'textwidth' but not when you press <Enter>. Please, read
the Vim help about 'formatoptions' and |fo-table|. For example, you can add the
following line to your |vimrc| if you want the comment string being added
after <Enter>:
>
autocmd FileType r setlocal formatoptions-=t formatoptions+=croql
<
4.7. 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
function rtags() to build the tags file for the R scripts in the current
directory. Please read |r-plugin-tagsfile| to learn how to create a tags file
referencing source code located in other directories, including the entire R
source code.
4.8. Tmux usage~
*r-plugin-tmux*
When running Vim in a terminal emulator (Linux/Unix only), the Vim-R-plugin
will use the screen.vim plugin to restart Vim and start R in a Tmux session.
The Tmux configuration file provided by the Vim-R-plugin configures Tmux to
use vi key bindings. It also configures Tmux to react to mouse clicks. You
should be able to switch the active pane by clicking on an inactive pane, to
resize the panes by clicking on the border line and dragging it, and to scroll
the R Console with the mouse wheel. When you use the mouse wheel, Tmux enters
in its copy/scroll back mode (see below).
The configuration script also sets <C-a> as the Tmux scape character (the
default is <C-b>), that is, you have to type <C-a> before typing a Tmux
command. Below are the most useful key bindings to use Tmux with the tmux.conf
created by the Vim-R-plugin (see |vimrplugin_notmuxconf| if you prefer to use
your own ~/.tmux.conf)
<C-a>arrow keys : Move the cursor to the Tmux panel above, below, at the
right or at the left of the current one.
<C-a><C-Up> : Move the panel division upward one line, that is, resize
the panels. Repeat <C-Up> to move more. <C-Down> will
move the division downward one line. If you are using
the vertical split, you should use <C-Left> and
<C-Right> to resize the panels.
<C-a>[ : Enter the copy/scroll back mode. You can use <PgUp>,
<PgDown> and vi key bindings to move the cursor around
the panel. Press q to quit copy mode.
<C-a>] : Paste the content of Tmux paste buffer.
While in the copy and scroll back mode, the following key bindings are very
useful:
q : Quit the copy and scroll mode.
<Space> : Start text selection.
v<Space> : Start rectangular text selection.
<Enter> : Copy the selection to Tmux paste buffer.
Please, read the manual page of Tmux if you want to change the Tmux
configuration and learn more commands. To read the Tmux manual, type in the
terminal emulator:
>
man tmux
>
Note: <C-a> was configured as the Tmux scape character, and it will not be
passed to applications running under Tmux. To send <C-a> to either R or Vim
you have to type <C-a>a.
With Tmux, you can the detach the Vim-R session and reattach it latter. This
is useful if you plan to begin the use the Vim-R-plugin in a machine and
latter move to another computer. However, normally you will get |E325|, caused
by the presence of a 'swapfile' (please, read the screen.vim plugin
documentation, especially the section |screen-gotchas| for details). This
problem will not happen if you start Vim from within a Tmux session, as in the
example below.
A sample detachable session could be:
- Create your ~/.tmux.conf if it does not exist yet. You may put the lines
below in your ~/.tmux.conf as a starting point to your own configuration
file:
>
set-option -g prefix C-a
unbind-key C-b
bind-key C-a send-prefix
set-window-option -g mode-keys vi
set -g terminal-overrides 'xterm*:smcup@:rmcup@'
set -g mode-mouse on
set -g mouse-select-pane on
set -g mouse-resize-pane on
<
- Start Tmux:
tmux
- Start Vim:
vim theScript.R
- Use Vim to start an R session:
<LocalLeader>rf
- Send code from Vim to R, and, then, detach Vim and R with <C-a>d
The command will be <C-b>d if you have not set <C-a> as the scape
character in your ~/.tmux.conf.
- Some time latter (even if accessing the machine remotely) reattach the
Tmux session:
tmux attach
See |vimrplugin_only_in_tmux| if you always prefer starting Tmux before
starting Vim, but sometimes forget to start Tmux.
4.9. GNU Screen usage~
*r-plugin-screen*
When running Vim in a terminal emulator (Linux/Unix only), the Vim-R-plugin
will use the screen.vim plugin to restart Vim and start R in a Tmux session.
However, the plugin will use GNU Screen if Tmux is not installed or if you
have set the value of vimrplugin_tmux = 0 in your |vimrc|.
You may want to create your own ~/.screenrc to customize GNU Screen behavior
(see |vimrplugin_noscreenrc|). Below are the most useful key bindings to use
the Vim-R-plugin with the screenrc that the plugin creates:
<C-Tab> : Move the cursor to the next panel.
<C-a>a : Decrease the height of the current panel.
<C-a>z : Increase the height of the current panel.
<C-a>[ : Enter the copy/scroll back mode. You can use <PgUp>,
<PgDown> and vi key bindings to move the cursor around
the panel. Press q to quit copy mode.
<C-a>] : Paste the content of GNU Screen paste buffer.
While in the copy and scroll back mode, the following key bindings are very
useful:
q : Quit the copy and scroll mode.
<Space> : Start text selection.
<Enter> : Copy the selection to GNU Screen paste buffer.
==============================================================================
*r-plugin-known-bugs*
5. Known bugs and workarounds~
The bugs that are known to exist but that will not be fixed are listed in this
section. Some of them can not be fixed because they depend on either R or Vim
missing features; others would be very time consuming to fix without breaking
anything.
5.1. The Object Browser segfaults (Linux/Unix only)~
If the Vim instance running the Object Browser crashes you may want to close
all Vim instances and kill any Vim wandering around with the command (typed in
a terminal emulator):
>
killall -9 vim
<
5.2. R's source() issues~
The R's source() function prints an extra new line between commands if the
option echo = TRUE, and error messages and warning are printed only after the
entire code is sourced, which makes it more difficult to find errors in the
code sent to R.
5.3. The clipboard's content is lost (Windows only)~
On Windows, the plugin copies the command that will be sent to R into the
clipboard. Thus, if you have anything in the clipboard it will be lost while
using the plugin.
5.4. The buffer name must be in the window title (Windows only)~
On Windows the plugin tries to activate the "R Console" window, paste the
command that is being sent to R, and, then, activate the GVim window. To
activate the GVim window the plugin requires that the name of the file being
edited be in the GVim window title. This is the default if you have not set
the option 'titlestring'.
5.5. The menu may not reflect some of your custom key bindings~
If you have created a custom key binding for the Vim-R-plugin, 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.6. Syntactically correct code may be wrongly indented~
If the Vim-R-plugin indents your code wrongly you may get the correct
indentation by adding braces and line breaks to it. Example:
>
# This code will be wrongly indented
levels(x) <- ## nl == nL or 1
if (nl == nL) as.character(labels)
else paste(labels, seq_along(levels), sep = "")
class(x) <- c(if(ordered) "ordered", "factor")
# But this one will be correctly indented
levels(x) <- ## nl == nL or 1
if (nl == nL)
as.character(labels)
else
paste(labels, seq_along(levels), sep = "")
class(x) <- c(if(ordered) "ordered", "factor")
<
5.7. Commands are sent twice on Mac OS X~
If you use the screen plugin with GNU Screen, individual lines may be sent
duplicated to R on Mac OS X.
5.8. [Errno 98] Address already in use~
When deleting objects using the "d" command in the Object Browser, the message
"[Errno 98] Address already in use" may appear. In this case, the Object
Browser will not work properly until you stop using it and wait for the time
set in 'updatetime' (four seconds, by default). Then, the Object Browser
should be normal again. The "d" command is available only when running R on
Tmux.
5.9. "VimCom port not found" on OpenBSD~
When the loopback interface has both IPv4 and IPv6 addresses vimcom loads ok
but apparently does not listen on the IPv4 address (127.0.0.1), only on the
IPv6 one (fe80::1).
==============================================================================
*r-plugin-options*
6. Options~
|vimrplugin_term| External terminal to be used
|vimrplugin_term_cmd| Complete command to open an external terminal
|vimrplugin_underscore| Convert '_' into ' <- '
|vimrplugin_rnowebchunk| Convert '<' into '<<>>=\n@' in Rnoweb files
|vimrplugin_objbr_place| Placement of Object Browser
|vimrplugin_objbr_w| Initial width of Object Browser window
|vimrplugin_external_ob| Run Object Browser on external terminal
|vimrplugin_objbr_sleep| Time the Object Browser waits for R after "d"
|vimrplugin_vimpager| Use Vim to see R documentation
|vimrplugin_editor_w| Minimum width of R script buffer
|vimrplugin_help_w| Desired width of R documentation buffer
|vimrplugin_nosingler| A single R process for all Vim instances
|vimrplugin_by_vim_instance| Each Vim instance runs its own R
|vimrplugin_i386| Use 32 bit version of R
|vimrplugin_r_path| Directory where R is
|vimrplugin_r_args| Arguments to pass to R
|vimrplugin_buildwait| Time to wait for :RUpdateObjList to finish
|vimrplugin_routmorecolors| More syntax highlighting in R output
|vimrplugin_routnotab| Show output of R CMD BATCH in new window
|vimrplugin_indent_commented| Indent lines commented with the \xx command
|vimrplugin_sleeptime| Delay while sending commands in MS Windows
|vimrplugin_noscreenrc| Do not write custom screenrc
|vimrplugin_screenplugin| Use the screen.vim plugin
|vimrplugin_screenvsplit| Split the window vertically (screen plugin)
|vimrplugin_tmux| Choose between Tmux and GNU Screen
|vimrplugin_applescript| Use osascript in Mac OS X.
|vimrplugin_allnames| Show names which begin with a dot
|vimrplugin_listmethods| Do .vim.list.args() instead of args()
|vimrplugin_specialplot| Do .vim.plot() instead of plot()
|vimrplugin_maxdeparse| Argument to R args() function
|vimrplugin_latexcmd| Command to run on .tex files
|vimrplugin_sweaveargs| Arguments do Sweave()
|vimrplugin_never_unmake_menu| Do not unmake the menu when switching buffers
|vimrplugin_map_r| Use 'r' to send lines and selected text
|vimrplugin_ca_ck| Add ^A^K to the beginning of commands.
|vimrplugin_openpdf| Open PDF after processing rnoweb file.
|vimrplugin_openpdf_quietly| Open PDF quietly.
|vimrplugin_insert_mode_cmds| Allow R commands in insert mode.
6.1. Terminal emulator (Linux/Unix only)~
*vimrplugin_term*
The plugin uses the first terminal emulator that it finds in the following
list:
1. gnome-terminal,
2. konsole,
3. xfce4-terminal,
4. iterm
5. Eterm,
6. rxvt,
7. aterm,
8. roxterm,
9. terminator,
10. xterm.
If Vim does not select your favorite terminal emulator, you may define it in
your |vimrc| by setting the variable vimrplugin_term, as shown below:
>
let vimrplugin_term = "xterm"
let vimrplugin_term = "/Applications/Utilities/Terminal.app/Contents/MacOS/Terminal"
<
*vimrplugin_term_cmd*
If your terminal emulator is not listed above, or if you are not satisfied
with the way your terminal emulator is called by the plugin, you may define in
your |vimrc| the variable vimrplugin_term_cmd, as in the examples below:
>
let vimrplugin_term_cmd = "gnome-terminal --title R -e"
let vimrplugin_term_cmd = "terminator --title R -x"
let vimrplugin_term_cmd = "/Applications/Utilities/iTerm.app/Contents/MacOS/iTerm -t R"
<
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.
6.2. Underscore and Rnoweb completion of code block~
*vimrplugin_underscore*
*vimrplugin_rnowebchunk*
While editing R code, '_' is replaced with ' <- '. To disable this feature,
put in your |vimrc|:
>
let vimrplugin_underscore = 0
<
In Rnoweb files, a '<' is replaced with '<<>>=\n@'. To disable this feature,
put in your |vimrc|:
>
let vimrplugin_rnowebchunk = 0
<
6.3. Object Browser options~
*vimrplugin_objbr_place*
*vimrplugin_objbr_w*
*vimrplugin_external_ob*
By default, the object browser will be created with 40 columns. 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 |vimrplugin_objbr_w| in your
|vimrc|, as below:
>
let vimrplugin_objbr_w = 30
<
The Object Browser will always be created by splitting the Vim script window
if you are running GVim. However, if running Vim in a terminal emulator, the
Object Browser will be created in a independent Vim instance in a Tmux panel
beside the R Console. Valid values for the Object Browser placement are
"script" or "console" and "right" or "left" separated by a comma. Examples:
>
let vimrplugin_objbr_place = "script,right"
let vimrplugin_objbr_place = "console,left"
<
If vimrplugin_external_ob = 1 and R is running in an external terminal
emulator and the communication with R is being established through Tmux, the
Object Browser will be placed besides the R Console in the external terminal
emulator. In this case, the command <LocalLeader>rh will not work on the
Object Browser.
When deleting an object from the Object Browser (possible if running Vim under
Tmux), the following option controls the time in milliseconds that the Object
Browser will wait for R to send the message updating the list of objects:
>
let vimrplugin_ob_sleep = 250m
<
You should increase this value if the "[Errno 98]" message appears frequently.