--- title: "Recommended Workflow and Examples" author: "Vilmantas Gegzna" date: "`r Sys.Date()`" output: rmarkdown::html_vignette: toc: yes vignette: > %\VignetteIndexEntry{1 Workflow and Examples} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- 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: ```{r Install package from CRAN, eval=FALSE} install.packages("spAddins") ``` Development version can be installed from GitHub: ```{r Install package from GitHub, eval=FALSE} 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](https://rstudio.github.io/rstudioaddins/#keyboard-shorcuts) - [Customizing Keyboard Shortcuts](https://support.rstudio.com/hc/en-us/articles/206382178-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: ```{r, include = FALSE} library(magrittr) ``` ```{r, eval = FALSE} library(magrittr) ``` To learn more about the `%$%` operator type: ```{r, eval = FALSE} ?magrittr::`%$%` ``` It can replace this commands, where `$` is used, e.g.: ```{r, eval = FALSE} 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()`: ```{r, eval = FALSE} CO2 table(Type, Treatment) ``` Apply the shortcut combination `Ctrl + Alt + Shift + S`. As a result the operator is inserted: ```{r} CO2 %$% table(Type, Treatment) ``` 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](http://rmarkdown.rstudio.com/) 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. | 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 | Table: A few examples of addins that insert operators The following functions may be useful for either editing **R Markdown** files or, if commented (`#`), for structuring R code files. | 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 | `~~~~~~~~~~` | Table: Addins that insert lines 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 | 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 | Table: Addins that convert between types of slashes ## "Enclose" family These functions are useful for editing **R Markdown** files. | 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\` | `r 2 + 3` | | 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}$ | Table: Several examples of addins that format text in *R Markdown* # Feedback Your feedback is wellcome at https://github.com/GegznaV/spAddins/issues * * *