# ZyX-I/vim-r-plugin2 forked from jimmyharris/vim-r-plugin2

### Subversion checkout URL

You can clone with HTTPS or Subversion.

Fetching contributors…

Cannot retrieve contributors at this time

798 lines (659 sloc) 31.35 kb
 *r-plugin.txt* *vim-r-plugin* vim-r-plugin2~ Plugin to work with R~ Authors: Jakson A. Aquino José Cláudio Faria Version: 100521 For Vim version 7.2 and above 1. Overview |r-plugin-overview| 2. Main features |r-plugin-features| 3. Installation |r-plugin-installation| 4. Use |r-plugin-use| 5. How the plugin works |r-plugin-functioning| 6. Known bugs and workarounds |r-plugin-known-bugs| 7. Options |r-plugin-options| 8. Custom key bindings |r-plugin-custom-key-bindings| 9. Files |r-plugin-files| 10. FAQ and tips |r-plugin-faq| 11. News |r-plugin-news| ------------------------------------------------------------------------------ 1. Overview~ *r-plugin-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 plugin) and some ideas from the Tinn-R (Windows only) project. The latest version of this plugin is available at: http://www.vim.org/scripts/script.php?script_id=2628 Constructive 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. ------------------------------------------------------------------------------ 2. Main features~ *r-plugin-features* 2.1. Linux/Unix only:~ * Integrated communication with R; * Omni completion (auto-completion) for R objects. 2.2. All platforms:~ * Syntax highlighting for R syntax; * Smart indentation for R syntax. ------------------------------------------------------------------------------ 3. Installation~ *r-plugin-installation* 3.1. Dependencies~ This plugin requires users to install two external dependencies. Before using this plugin, you must install: * screen - http://www.gnu.org/software/screen/ * R-Project - http://www.r-project.org/ This software is already packaged for most GNU/Linux distributions and other Unix variants. In fact, screen is installed by default on many Linux distributions. Unfortunately, installation instructions for these dependencies vary widely and are beyond the scope of this documentation. Please review the installation instructions for your operating system for these external dependencies. 3.2. General instructions~ You need to activate plugins and indentation according to 'filetype' in your |vimrc|: > filetype plugin indent on < Create your ~/.vim directory if you do not have it yet: > mkdir -p ~/.vim < 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. Uncompress the archive: > tar -xvzf vim-r-plugin2-*.tar.gz -C ~/.vim < Start Vim and build the tags file for this document (and others that eventually are in at the same directory): > :helptags ~/.vim/doc < Update the list of objects for omni completion and syntax highlight (see |:RUpdateObjList| for details). 3.3. Optional step~ Edit Vim'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 ------------------------------------------------------------------------------ 4. Use~ *r-plugin-use* 4.1 Key bindings~ 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' variable (see ||) Start/Close . Start R (default) \rf . Start R --vanilla \rv . Start R (custom) \rc -------------------------------------------- . Close R (no save) \rq . Close R (save workspace) \rw ----------------------------------------------- Send . File \aa . File (echo) \ae -------------------------------------------- . Block (cur) \bb . Block (cur, echo) \be . Block (cur, down) \bd . Block (cur, echo and down) \ba -------------------------------------------- . Function (cur) \ff . Function (cur echo) \fe . Function (cur and down) \fd . Function (cur, echo and down) \fa -------------------------------------------- . Paragraph \pp . Paragraph (echo) \pe . Paragraph (and down) \pd . Paragraph (echo and down) \pa -------------------------------------------- . Selection \ss . Selection (echo) \se . Selection (and down) \sd . Selection (echo and down) \sa -------------------------------------------- . Line \l . Line (and down) \d . Line (and new one) \q ----------------------------------------------- Control . List space \rl . Clear console \rr . Clear all \rm -------------------------------------------- . Object (print) \rp . Object (names) \rn . Object (str) \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 -------------------------------------------- . Rebuild (list of objects) \ro . 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. 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. The key bindings \sw and \sp are useful only if the file type is rnoweb (.Rnw). When the cursor is over the @ character that 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. Please see |r-plugin-custom-key-bindings| to learn how to customize the key bindings without editing the plugin directly, and |g:vimrplugin_underscore| to to disable underscore replacement. 4.2 Syntax highlight and omni completion~ *: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 tags file for omni completion including all objects currently in R's workspace, with the exception of the .GlobalEnv objects. These two lists are stored permanently in the ~/.vim/tools directory. If you prefer to not have the functions highlighted, delete the file ~/.vim/tools/rfunctions. ------------------------------------------------------------------------------ 5. How the plugin works~ *r-plugin-functioning* Vim and R run as independent processes. The main disadvantage is that we have limited communication between the two applications: Vim can send strings to R through screen and R can write files to be read by Vim. That's all. The main advantage is that Vim's or the plugin's bugs will not affect R. 5.1. Communication through screen~ The r-plugin uses screen to communicate with R. First, the plugin initiates a new screen session and uses this to start a new R process. The plugin's menu options, toolbar buttons and key bindings can then be used to communicate with the newly started R process. The plugin sends commands to R through screen. By default, all Vim buffers share the same R process, but it is also possible to configure Vim so that each buffer runs its own instance of R in a separate terminal emulator. In this case, the screen sessions have unique names. The names are made using the user name and the seconds of localtime(). Hence, a name clash is possible if a single user starts more than one Vim buffer at the same second. To change the default behavior and force all Vim buffers to use different R processes see |g:vimrplugin_single_r|. 5.2. 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. You can build/rebuild the tags file at any time. Remember, you must rebuild the tags file manually to add the names of other objects created after building the tags file. If a data.frame is found, while building the tags file, the columns in the data.frame are added to the list of objects. 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. The tags file used for omni completion is built by the R function contained in the script ~/.vim/tools/rtags.R. This function is sourced by R, which causes R to create the tags file used by Vim. Vim uses two tags files: one for the objects of .GlobalEnv and the other for all other objects. The .GlobalEnv tags file is stored in the /tmp directory and, thus, is deleted after each reboot. The other tags file is stored in ~/.vim/tools and remains available until you manually rebuild it with the command: |:RUpdateObjList|. ------------------------------------------------------------------------------ 6. Known bugs and workarounds~ *r-plugin-known-bugs* 6.1. R session is detached when GVim is closed~ If you launch GVim through a custom keyboard shortcut, the problem may be solved if you add -f as parameter to GVim. The R session will also be detached when GVim is closed if you launch GVim by the command line in a terminal emulator, and, then, close the terminal-emulator. In any case, to reattach to the R session, open a new terminal window and type: > screen -r < 6.2. Indentation~ Correctly written code might be wrongly indented. Examples: this code is indented as:~ if(T) if(T) for(i in 1:2) for(i in 1:2) { { cat(i, "\n") cat(i, "\n") } } if(T){ if(T){ if(T) if(T) { { cat("something\n") cat("something\n") }} }} 6.3 R's source() issues~ The R's source() function prints an extra new line between commands if the option echo = TRUE, and error messages are printed only after the function has finished, which make it more difficult to find errors in the code sent to R. 6.4 GVim's toolbar buttons, menu and title bar blink during omni completion~ The plugin unmakes the R menu and the related toolbar buttons when Vim leaves the R buffer. During omni completion, Vim leaves the R buffer and goes to the scratch window and, consequently, the plugin unmakes the toolbar buttons and R related menu items. ------------------------------------------------------------------------------ 7. Options~ *r-plugin-options* *g:vimrplugin_term* 7.1. Terminal emulator~ The plugin uses the first terminal emulator that it finds in the following list: 1. gnome-terminal, 2. konsole, 3. xfce4-terminal, 4. Eterm, 5. rxvt, 6. aterm, 7. xterm. If Vim does not select your favorite terminal emulator, you may define it in your |vimrc| by setting the variable g:vimrplugin_term, as shown below: > let g:vimrplugin_term = "xterm" < *g: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 g:vimrplugin_term_cmd, as in the example below: > let g:vimrplugin_term_cmd = "gnome-terminal -t R -e" < 7.2. Underscore~ *g:vimrplugin_underscore* To disable the underscore replacement with " <- " put the following in your |vimrc|: > let g:vimrplugin_underscore = 1 < 7.3. Pager~ *r-pager* You may also want to use less in a separate terminal emulator as the default pager for R's help. You can use the script ~/.vim/tools/rpager.sh (which will call less) by putting in your ~/.Rprofile: > options(pager="~/.vim/tools/rpager.sh") This script can be easily modified to use your favorite terminal emulator. The script contains options for several popular emulators such as gnome-terminal and konsole but defaults to xterm. 7.4. Html help~ *g:vimrplugin_hstart* The plugin can call R's function help.start() the first time that you press CTRL-H. If you want this behavior, you should put in your |vimrc|: > let g:vimrplugin_hstart = 1 < *g:vimrplugin_browser_time* After calling help.start(), the plugin will wait 4 seconds before sending to R the help command. If your browser needs either more or less time to start, you may want to add the following global variable (with the appropriate value) to your |vimrc|: > let g:vimrplugin_browser_time = 4 < 7.5. Number of R processes~ *g:vimrplugin_nosingler* *g:vimrplugin_by_vim_instance* If you prefer that each Vim buffer uses its own R process, put the following option in your |vimrc|: > let g:vimrplugin_nosingler = 1 < If you prefer that each Vim instance calls its own R process and all of the instance's buffers send code to this R process while other Vim instances send code to other R processes then put the following in your |vimrc|: > let g:vimrplugin_by_vim_instance = 1 > This is the default behavior when using Vim with the screen.vim plugin, and, thus, there is no need to use this option if already running Vim with the option |g:vimrplugin_screenplugin|(see below). The |g:vimrplugin_by_vim_instance| option requires that vim is acting as a command server because the variable |v:servername| is used to make the name of the screen session which will run R. By default, GVim runs as server, but Vim does not. Hence, if you are using Vim you have either to start Vim with the argument --servername or use the screen.vim plugin which tries to restart Vim with the --servername argument. If you want to use more than nine GVim instances you will have to use the --servername argument because screen will not differentiate between the names "GVIM1" and "GVIM10". 7.6. Screen configuration~ *g:vimrplugin_noscreenrc* Vim runs screen with a special configuration file. If you want to use your own ~/.screenrc, put in your |vimrc|: > let g:vimrplugin_noscreenrc = 1 < 7.7. Integration with screen.vim~ *g:vimrplugin_screenplugin* By default, the r-plugin does not use the screen.vim plugin, written by Eric Van Dewoestine. If you prefer to use both plugins at the same time, download and install the screen.vim (version 0.8 or above) from: http://www.vim.org/scripts/script.php?script_id=2711 Using both plugins at the same time is especially useful for users who may prefer to use Vim and R from the command-line, rather than using the graphical interface provided by GVim. To integrate the r-plugin with screen.vim you will need to add the following to your |vimrc|: > let g:vimrplugin_screenplugin = 1 < Note: Read the screen.vim description at plugin/screen.vim, especially the section "Gotchas" (the E325 is caused by the presence of 'swapfile'). This problem will not happen if you start Vim from within a screen session, as in the example below. However, when starting Vim from within screen you will not be able to start a new R session after closing the first one with the \rq command. Moreover, you will have to manually switch from one screen region to another and kill them. A sample detachable session could be: - Start vim through screen: screen vim theScript.R - Use Vim to start an R session: \rf - Send code from Vim to R, and, then, detach Vim and R with d - Some time latter reattach the screen session: screen -r - Type S to split the region, to go the other region and n until you get one region with Vim and the other with R. - When you have finished to use Vim and R close them and type exit to quit the screen session. Here are several useful screen shortcuts: go from Vim to R and vice-versa :resize N set the height of the current window to N lines n switch to the next screen session p switch to the previous screen session S split the current region in two new ones X kill the current region By default, screen waits briefly after it receives external commands and other default options may not be what you want. Please read screen documentation to know how to configure it. Below is a sample ~/.screenrc you may consider as a starting point to create your own: > msgwait 0 termcapinfo xterm* 'ti@:te@' vbell off term screen-256color < 7.8. Map 'r'~ *g:vimrplugin_map_r* Some users may already be familiar with the key bindings from earlier releases of the r-plugin. If the variable g:vimrplugin_map_r exists, the plugin will map the letter 'r' to send lines to R when there are visually selected lines, for compatibility with the original plugin. To activate this option, insert the following into |vimrc|: > let g:vimrplugin_map_r = 1 < You may want to add the following three lines to your |vimrc| which were in the original plugin and will increase compatibility with code edited with Emacs: > set expandtab set shiftwidth=4 set tabstop=8 < 7.9. maxdeparse~ *g:vimrplugin_maxdeparse* You can set the argument maxdeparse to be passed to R's source() function. Example: > let g:vimrplugin_maxdeparse = 300 < 7.10. LaTeX command~ *g:vimrplugin_latexcmd* By default, Vim calls pdflatex to produce a pdf document from the .tex file produced by the R Sweave command. You can use the option g:vimrplugin_latexcmd to change this behavior. Example: > let g:vimrplugin_latexcmd = "latex" < ------------------------------------------------------------------------------ 8. Custom key bindings~ *r-plugin-custom-key-bindings* When creating custom key bindings for the r-plugin, it is necessary to create three maps for most functions because the way the function is called is different in each Vim mode. Thus, key bindings must be made for normal mode, insert mode, and visual mode. To customize a key binding you should put in your |vimrc| something like: > map RStart imap RStart vmap RStart < The above example shows how you can increase compatibility with old versions of the r-plugin, by changing the key binding used to start R from rf to the old default value, F2. Custom key bindings are not shown in Vim's menu, but you can type |:map| to see the list of current mappings, and below is the list of the names for custom key bindings: > RBuildTags RESendSelection RSendLine RClearAll RHelp RSendMBlock RClearConsole RListSpace RSendSelection RClose RMakePDF RSetwd RCustomStart RObjectNames RShowArgs RDSendFunction RObjectPr RShowEx RDSendLine RObjectStr RSPlot RDSendSelection RPlot RStart REDSendMBlock RSaveClose RStop REDSendSelection RSendFile RSummary RESendFile RSendFunction RSweave RESendMBlock RSendLAndOpenNewOne RvanillaStart < The plugin also contains a function called RAction which allows you to build ad-hoc commands to R. This function takes the name of an R function such as "levels" or "table" and the word under the cursor, and passes them to R as a command. For example, if your cursor is sitting on top of the object called gender and you call the RAction function, with an argument such as levels, Vim will pass the command levels(gender) to R, which will show you the levels of the object gender. To make it even easier to use this function, you could write a custom key binding that would allow you to rapidly get the levels of the object under your cursor. Add the following to your |vimrc| to have an easy way to pass R the levels command. > map rk :call RAction("levels") < then (assuming that the leader key is "\") if you type \rk R will receive the command > levels(myObject) < You should replace rk with the key binding that you want to use and "levels" with the R function that you want to call. ------------------------------------------------------------------------------ 9. Files~ *r-plugin-files* The following files are part of the plugin and should be in your ~/.vim directory after the installation: .vim |-- after | |-- filetype.vim | -- syntax | -- r.vim | |-- autoload | -- rcomplete.vim | |-- bitmaps | |-- r-close.xpm | |-- r-control-clear.png | |-- r-control-clearall.png | |-- r-control-listspace.png | |-- r-send-block.png | |-- r-send-file.png | |-- r-send-function.png | |-- r-send-line.png | |-- r-send-selection.png | -- r-start.xpm | |-- doc | -- r-plugin.txt | |-- ftplugin | |-- r.vim | |-- rhelp.vim -> r.vim | -- rnoweb.vim -> r.vim | |-- indent | -- r.vim | -- tools |-- rargs.R |-- rpager.sh `-- rtags.R ------------------------------------------------------------------------------ 10. FAQ and tips~ *r-plugin-faq* 10.1. How can I make the plugin active for all file types?~ If you want to make most of the plugin functions available for any file type, create a symbolic link to ftplugin/r.vim in the plugin directory. For example, if you installed the plugin in your home directory do the following commands in a terminal emulator: > cd ~/.vim/plugin ln -s ../ftplugin/r.vim < 10.2. How do marked blocks work?~ Vim allows several marks (bookmarks). The most commonly used marks are |a..z|. If the cursor is between any two marks, the plugin will send all of the lines between them to R. To make it easier to remember where blocks begin and end, we recommended that you use the showmarks plugin available at: http://www.vim.org/scripts/script.php?script_id=152 This plugin makes it possible to visually manage your marks. You may want to add the following two lines to your |vimrc| to customize showmarks behavior: > let marksCloseWhenSelected = 0 let showmarks_include = "abcdefghijklmnopqrstuvwxyz" < 10.3. Is it possible to stop R from within Vim?~ Sorry, it is not possible. You have to press ^C into R's terminal emulator. 10.4. Easier key bindings for most used commands~ The most used commands from vim-r-plugin probably are "Send line" and "Send selection". You may find it a good idea to map them to the space bar in your |vimrc| (suggestion made by Iago Mosqueira): > vmap RDSendSelection nmap RDSendLine < 10.5 Use "," as local map leader~ People writing Rnoweb documents may find it better to use a comma as local leader instead of the default backslash: > let maplocalleader = "," < 10.6 Run your Makefile from within R~ Do you have many Rnoweb files included in a master tex or Rnoweb file and uses a Makefile to build the pdf? You may consider it useful to put the following line in your |vimrc|: > nmap sm :update:call SendCmdToScreen('system("make")') < 10.7 Group windows with compiz~ It may be easier to work with the plugin if the various related windows (editor, terminal, and graphics window) are grouped because they will be raised together when one of them receives the focus. You may need CompizConfig Settings Manager installed to enable this feature (look at the "Window Management" section for "Group and Tab Windows"). ------------------------------------------------------------------------------ 11. News~ *r-plugin-news* 100521 (2010-05-12) * Replaced "-t" with "--title" to make xfce4-terminal work again. 100512 (2010-05-12) * Thanks to Tortonesi Mauro who wrote a patch to make the plugin work with pathogen.vim. * Added simple syntax hightlight for .Rout files. * Increased the time limit of RUpdateObjList to two minutes. * Improvement in the syntax highlight based on code written by Zhuojun Chen. * Thanks to Scott Kostyshak who helped to improve the documentation. * Iago Mosqueira suggested that the plugin should be able to run one R process for each Vim instance, and his suggestion was implemented with the option g:vimrplugin_by_vim_instance. 091223 (2009-12-23) * Syntax highlight for R functions. * Added "info" field to omni completion (thanks to Ben Kujala for writing the original code). 091016 (2009-10-16) * The plugin now can run together with screen.vim, thanks to Eric Van Dewoestine, the author of screen.vim, who added script integration to screen.vim. * Andy Choens has made many improvements on the documentation. * Added the possibility of custom key binding creation to call any R function with the word under cursor as argument. * The key bindings related with Sweave are activated even if the file type is not rnoweb. * Replaced with in the key bindings. * Added "Send Paragraph" commands. 091004 (2009-10-04) * José Cláudio Faria has began to work in the project as co-author. * Some ideas from Tinn-R project were ported to the plugin. * The main menu has new items and the toolbar new icons. * Documentation improvements. 090828 (2009-08-28) * Faster startup. * Better support for Rnoweb files: the cursor goes to '^<<' if the sent line is '^@$'. 090811 (2009-08-12) * Now use screen instead of funnel.pl. The bugs and limitations related with funnel.pl are solved. * Deleted key binding for R-devel. * Automatically detect available terminal emulators and choose one of them. * By default, no longer calls help.start() the first time that CTRL-H is pressed. 090810 (2009-08-10) * Added R icons for some terminal emulators. * Removed the script open-gvim-here. You may use Vim's option autochdir. * Added option g:vimrplugin_term. * Improved indentation script. * Changed key binding from Shift-Enter, which doesn't work in any terminal, to Alt-Enter, which at least works in xterm. 090610 (2009-06-11) * The options expandtab, shiftwidth and tabstop are no longer set by the plugin. * Better word detection before calling R's help(). * Fixed bug in underscore replacement. * Fixed small bug in code indentation. * Added scipt rpager.sh. * Added two new plugin options: no underscore replacement and fixed name for the pipe file instead of random one. 090523 (2009-05-23) * Key bindings now are customizable. * Default key binding for calling R's args() changed to Shift-F1. * New R script rargs.R gives better results for generic functions than R's args() called directly. 090519 (2009-05-20) * Don't send large blocks of code to R to avoid xterm freezing. * Automatically call help.start() after CTRL-H is pressed for the first time, and wait 4 seconds for the browser start before calling R's help(). These features are customizable. * Fixed tags file script. 090516 (2009-05-16) * Added documentation. * Added ability to send function to R, revert the automatic conversion of "_" into "<-" and call R's help(). * Added archive with some files to ease desktop integration, if desired. 090507 (2009-05-08) * Initial upload vim:tw=78:ts=8:ft=help:norl:
Something went wrong with that request. Please try again.