spacemacs/layers/+lang/ess/README.org

#+TITLE: ESS (R) layer

[[file:img/r.jpg]]

* Table of Contents                                         :TOC_4_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
- [[#options][Options]]
- [[#key-bindings][Key Bindings]]
  - [[#inferior-repl-process][Inferior REPL process]]
  - [[#help][Help]]
  - [[#more-interaction-with-the-repl][More interaction with the REPL]]
  - [[#r-devtools][R devtools]]
  - [[#debugging][Debugging]]
  - [[#editing-markdown][Editing Markdown]]

* Description
This layer adds support for statistical programming languages to Spacemacs.

** Features:
- Syntax highlighting
- Auto-completion
- Syntax-checking via [[https://github.com/jimhester/lintr][lintr]]
- Additional data viewer for R via [[https://github.com/myuhe/ess-R-data-view.el][ess-R-data-view]]
- Support for Org-Babel
- Better 'equals' behavior via [[https://github.com/genovese/ess-smart-equals][ess-smart-equals]]
- Showing of inline help for =R= constructs
- Repl support via =R terminal=
- Support for =S=, =SAS= and =R=
- Much more via the [[https://ess.r-project.org/Manual/ess.html#Current-Features][ESS Project]]

* Install
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =ess= to the existing =dotspacemacs-configuration-layers= list in this
file.

Also install [[https://github.com/jimhester/lintr][lintr]] library via the R terminal to enable syntax checking.
To do so start the R terminal and type below code.

#+BEGIN_SRC R
  install.packages("lintr")
#+END_SRC

* Options
To turn off the automatic replacement of underscores by =<-=, set in your
=~/.spacemacs=:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '((ess :variables
                                                         ess-disable-underscore-assign t)))
#+END_SRC

Alternatively you may enable =ess-smart-equals=, which also disables replacement
of underscores by =<-=, and additionally replace the equals sign with =<-= when
appropriate:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '((ess :variables
                                                         ess-enable-smart-equals t)))
#+END_SRC

* Key Bindings
** Inferior REPL process
Send code to inferior process with these commands:

| Key Binding | Description                                          |
|-------------+------------------------------------------------------|
| ~SPC m '​~   | start REPL                                           |
| ~SPC m ,​~   | send region, current function, or paragraph and step |
| ~SPC m s i~ | start REPL                                           |
| ~SPC m s s~ | switch between file and REPL                         |
| ~SPC m s S~ | switch the process associate with file               |
|-------------+------------------------------------------------------|
| ~SPC m s b~ | send buffer and keep code buffer focused             |
| ~SPC m s B~ | send buffer and switch to REPL in insert mode        |
| ~SPC m s d~ | send region or line and step                         |
| ~SPC m s D~ | send function or paragraph and step                  |
| ~SPC m s f~ | send function and keep code buffer focused           |
| ~SPC m s F~ | send function and focus REPL                         |
| ~SPC m s l~ | send line and keep code buffer focused               |
| ~SPC m s L~ | send line and focus REPL                             |
| ~SPC m s r~ | send region and keep code buffer focused             |
| ~SPC m s R~ | send region and focus REPL                           |

** Help
Get help and helpers for inspecting objects at point are available in R buffers only.

| Key Binding | Description                                                    |
|-------------+----------------------------------------------------------------|
| ~SPC m h a~ | help apropos                                                   |
| ~SPC m h d~ | display help on object                                         |
| ~SPC m h e~ | describe object                                                |
| ~SPC m h h~ | display help on object                                         |
| ~SPC m h i~ | display index for package                                      |
| ~SPC m h m~ | manual lookup                                                  |
| ~SPC m h o~ | display demos                                                  |
| ~SPC m h p~ | view data under point using [ess-R-data-view][ess-R-data-view] |
| ~SPC m h r~ | lookup reference                                               |
| ~SPC m h t~ | view table using [ess-R-data-view][ess-R-data-view]            |
| ~SPC m h v~ | display vignettes                                              |
| ~SPC m h w~ | help web search                                                |
| ~C-j~       | next item in REPL history                                      |
| ~C-k~       | previous item in REPL history                                  |

** More interaction with the REPL
Helpers that provide further interaction with the REPL.

| Key Binding   | Description                                           |
|---------------+-------------------------------------------------------|
| ~SPC m r /~   | set working directory                                 |
| ~SPC m r TAB~ | install package                                       |
| ~SPC m r d~   | edit object source or dump() object into a new buffer |
| ~SPC m r e~   | execute a command in the ESS process                  |
| ~SPC m r i~   | install package                                       |
| ~SPC m r l~   | load installed package                                |
| ~SPC m r r~   | reload ESS process                                    |
| ~SPC m r s~   | set source style                                      |
| ~SPC m r t~   | build tags for directory                              |
| ~SPC m r w~   | set "width" option                                    |

** R devtools
Interaction with the =R= =devtools= package.

| Key Binding   | Description                              |
|---------------+------------------------------------------|
| ~SPC m w TAB~ | interface for =devtools::install()=      |
| ~SPC m w a~   | ask for a devtools command and runs it   |
| ~SPC m w c~   | interface for =devtools::check()=        |
| ~SPC m w d~   | interface for =devtools::document()=     |
| ~SPC m w i~   | interface for =devtools::install()=      |
| ~SPC m w l~   | interface for =devtools::load_all()=     |
| ~SPC m w r~   | interface for =devtools::revdep_check()= |
| ~SPC m w s~   | set a package for ESS r-package commands |
| ~SPC m w t~   | interface for =devtools::tests()=        |
| ~SPC m w u~   | interface for =devtools::unload()=       |

** Debugging
Tools for debugging

| Key Binding  | Description                                                       |
|--------------+-------------------------------------------------------------------|
| ~SPC m d ?~  | 'ess-tracebug-show-help                                           |
| ~SPC m d `~  | show traceback and last error message                             |
| ~SPC m d \~~ | display call current call stack                                   |
| ~SPC m d b~  | set breakpoint                                                    |
| ~SPC m d B~  | set conditional breakpoint                                        |
| ~SPC m d d~  | set debugging flag for function                                   |
| ~SPC m d e~  | toggle the `on-error` action                                      |
| ~SPC m d i~  | jump to point where the last debugger or traceback event occurred |
| ~SPC m d k~  | kill breakpoint                                                   |
| ~SPC m d K~  | kill all breakpoints in buffer                                    |
| ~SPC m d l~  | Set breakpoint logger                                             |
| ~SPC m d n~  | go to next breakpoint                                             |
| ~SPC m d N~  | go to previous breakpoint                                         |
| ~SPC m d p~  | go to previous breakpoint                                         |
| ~SPC m d o~  | toggle breakpoint state                                           |
| ~SPC m d s~  | set environment for evaluation                                    |
| ~SPC m d t~  | toggle tracebug                                                   |
| ~SPC m d u~  | unflag function for debug                                         |
| ~SPC m d w~  | trigger ESS watch mode                                            |

** Editing Markdown
Edit Markdown files

| Key Binding | Description                                               |
|-------------+-----------------------------------------------------------|
| ~SPC m c C~ | send knitr/sweave chunk and switch to REPL in insert mode |
| ~SPC m c c~ | send knitr/sweave chunk and keep buffer focused           |
| ~SPC m c d~ | send knitr/sweave chunk and step to next chunk            |
| ~SPC m c m~ | mark knitr/sweave chunk around point                      |
| ~SPC m c n~ | next knitr/sweave chunk                                   |
| ~SPC m c N~ | previous knitr/sweave chunk                               |