Author: Vilmantas Gegzna
Date: 2017-12-14

# Recommended Workflow and Examples

#### Vilmantas Gegzna

#### 2017-12-14

This vignette introduces to package `spAddins`: describes a recommended workflow, explains how the functions of the package should be used and gives several examples.

# About The Package

`spAddins` is an R package that provides a set of RStudio addins which are designed to be used in combination with user-defined RStudio keyboard shortcuts. These addins do the following:

1. format text in R Markdown documents:
   - enclose either selected text or selected rows with special symbols and text gets inerpreted in a special way when rendered with R Markdown (e.g., converts “bold” into “**bold**” that is interpreted as “bold”).
2. insert text (e.g., operators `%>%`, `<<-`, `%$%`) at the cursor position;
3. replace symbols in selected pieces of text (e.g., convert backslashes to forward slashes which results in strings like `"c:\data\"` converted into `"c:/data/"`).

# The Workflow

The recommended workflow consists of four main steps. Step 1 and Step 2 should usually be done only once. Step 3 and Step 4 can be repeated as many times as needed.

## Step 1: Install the package

Released version of package `spAddins` can be installed from CRAN:

    install.packages("spAddins")

Development version can be installed from GitHub:

    if (!require(devtools)) install.packages("devtools")
    library(devtools)
    install_github("GegznaV/spAddins")

## Step 2: Define keyboard shortcuts

The most of the functions in the package are also RStudio addins. This fact allows setting user-defined RStudio keyboard shortcuts that call the functions in a more convenient way. Thus the second step is to define keyboard shortcuts for package’s `spAddins` functions of interest.

To learn how to add user defined RStudio keyboard shortcuts, visit these links:

- Keyboard Shorcuts
- Customizing Keyboard Shortcuts.

## Step 3: Place a cursor / Select some text

Package `spAddins` contains 3 types of addins:

- those which insert text;
- those which replace text;
- those which enclose text (insert symbols on both sides of selected text).

For addins which insert text, in either R editor or in R console place your cursor at the position at which the text should be inserted.

For addins which either replace or enclose text, in R editor or in R console select a piece of text in which certain symbols should be replaced or enclosed.

## Step 4: Use the keyboard shortcuts

To call a desired addin function, apply an appropriate keyboard shortcut which in Step 2 was associated with that function.

# A Few Examples

## Insert `%$%` operator

This example demonstrates how to use addins which insert text.

Let package `spAddins` be already installed. First, let’s set keyboard shortcut `Ctrl + Alt + Shift + S` to call function `rs_insert_exposition_pipe()` which inserts exposition pipe-operator `%$%` at the cursor position. This operator is defined in package `magrittr` thus the package must be loaded too:

    library(magrittr)

To learn more about the `%$%` operator type:

    ?magrittr::`%$%`

It can replace this commands, where `$` is used, e.g.:

    table(CO2$Type, CO2$Treatment)

Next, place your cursor at the position, where the operator should be inserted. For example, between the name of data set `CO2` and the name of a function `table()`:

    CO2  table(Type, Treatment)

Apply the shortcut combination `Ctrl + Alt + Shift + S`. As a result the operator is inserted:

    CO2  %$%  table(Type, Treatment)

    ##              Treatment
    ## Type          nonchilled chilled
    ##   Quebec              21      21
    ##   Mississippi         21      21

## Replace `\` with `/`

This example describes how to use addins which replace text.

Conciser having a string `"c:\data\"` in which backslashes (`\`) must be replaced with forward slashes (`/`). Addin function `rs_replace_slash_b2fw()` (b – backslash, fw – forward slash) is designed exactly for this task. Let’s define a new shortcut combination, say `Ctrl + Alt + Shift + /`, which calls the addin function. Now to know the place where the replacement should be applied an appropriate piece of text in either R editor or R console must be selected. Thus let’s select whole string `"c:\data\"` and push `Ctrl + Alt + Shift + /`. The result: as expected, the string is converted into `"c:/data/"`.

## Enclose with `**`…`**`

This example describes how to use addins which enclose text.

Conciser having an R Markdown file and a string `"This word should be in bold."` in it. In this string word `word` must be in bold. Addin function `rmd_bold()` encloses selected text in double asterisk `**` signs, and this is interpreted as bold in R markdown. Let’s define shortcut combination, say `Ctrl + Shift + B`, which calls the addin function. Now select the word `word` which is either in R editor or R console and push `Ctrl + Shift + B` to call the addin function. The result: `"This **word** should be in bold."`

# Available add-in functions

## “Insert” family

These functions insert various R operators.

A few examples of addins that insert operators
Function | Inserts | Package associated with operator
--- | --- | ---
rs_insert_arrow_rl2() | <<- | R base
rs_insert_arrow_lr() | -> | R base
rs_insert_arrow_lr2() | ->> | R base
rs_insert_infix_in() | %in% | R base
rs_insert_matrix_multiplication() | %*% | R base
rs_insert_pipe | %>% | magrittr
rs_insert_tee_pipe() | %T>% | magrittr
rs_insert_update_pipe() | %<>% | magrittr
rs_insert_exposition_pipe() | %$% | magrittr

The following functions may be useful for either editing R Markdown files or, if commented (`#`), for structuring R code files.

Addins that insert lines
Function | Description | Example (first 10 symbols)
--- | --- | ---
rs_insert_line_ss() | Insert single straight (SS) line | `----------`
rs_insert_line_ds() | Insert double straight (DS) line | `==========`
rs_insert_line_sw() | Insert single wavy (SW) line | `~~~~~~~~~~`

The length of line is from the beggining of selection to the 79-th column of the row (i.e., the position of 79-th symbol in the row).

## “Replace” family

Addins that convert between types of slashes
Action | Function | Text to edit | Result
--- | --- | --- | ---
Replace \ with \\ | rs_replace_slash_bs2d() | “c:\data\” | “c:\\data\\”
Replace \ with / | rs_replace_slash_b2fw() | “c:\data\” | “c:/data/”
Replace / with \ | rs_replace_slash_fw2b() | new line/n | new line\n
Replace \\ with \ | rs_replace_slash_bd2s() | new line\\n | new line\n

## “Enclose” family

These functions are useful for editing R Markdown files.

Several examples of addins that format text in R Markdown
Action | Function | Text to edit | Result | Interpreted as
--- | --- | --- | --- | ---
Enclose with double asterisk (`**`) | rmd_bold() | bold | **bold** | bold
Enclose with single underscore (`**_` and `_**`) | rmd_italics() | italics | _italics_ | italics
Enclose with single underscore (`_`) | rmd_bold_italics() | bold italics | **_bold italics_** | bold italics
Enclose with double underscore (`__`) | rmd_bold2() | bold | __bold__ | bold
Enclose with single asterisk (`*`) | rmd_italics2() | italics | *italics* | italics
Enclose with caret (`^`) | rmd_superscript() | a superscript | a ^superscript^ | a superscript
Enclose with single tilde (`~`) | rmd_subscript() | a subscript | a ~subscript~ | a subscript
Enclose with double tilde (`~~`) | rmd_strikethrough() | strikethrough | ~~strikethrough~~ | strikethrough
Enclose with single backick (`) | rmd_code_inline() | code | `code` | `code`
Enclose as inline R code to evaluate | rmd_r_code_inline() | 2 + 3 | ` r 2 + 3` | 5
Enclose with single dollar sign (`$`) | enclose_with_dollar() | equation^{inline} | `$equation^{inline}$` | \(equation^{inline}\)
Enclose with double dollar sign (`$$`) | enclose_with_dollar2() | equation_{block} | `$$equation_{block}$$` | \(equation_{block}\)

# Feedback

Your feedback is wellcome at https://github.com/GegznaV/spAddins/issues