README.Rmd

---
title: "infuser"
output: md_document
---

[![Travis Build Status](https://travis-ci.org/Bart6114/infuser.svg)](https://travis-ci.org/Bart6114/infuser)
[![Coverage Status](https://coveralls.io/repos/Bart6114/infuser/badge.svg)](https://coveralls.io/r/Bart6114/infuser)
[![CRAN_Status_Badge](http://www.r-pkg.org/badges/version/infuser)](http://cran.r-project.org/web/packages/infuser)
[![Downloads](http://cranlogs.r-pkg.org/badges/infuser)](http://cran.rstudio.com/package=infuser)

```infuser``` is a simple and very basic templating engine for R. It replaces parameters within templates with specified values. Templates can be either contained in a string or in a file.

## Installation

```{r, eval=FALSE}
install.packages("infuser")
```

If you want to use the most up-to-date version, install using ```devtools::install_github```.

```{r, eval=FALSE}
devtools::install_github("Bart6114/infuser")
```

## Hello World

A simple Hello World example that makes use of the `magrittr` piping workflow.

```{r}
library(magrittr)
library(infuser)

"Hello {{var1}}!" %>%
  infuse(var1="world")
```

## Usage

### Working with character strings as templates

Let's have a look at an example string.

```{r}
my_sql<-"SELECT * FROM Customers
WHERE Year = {{year}}
AND Month = {{month|3}};"
```

Here the variable parameters are enclosed by ```{{``` and ```}}``` characters. See ```?infuse``` to use your own specification.

From now on, we suppose the character string ```my_sql```  is our template. To show the parameters requested by the template you can run the following.

```{r, results='hide'}
library(infuser)
variables_requested(my_sql, verbose = TRUE)
```

To fill in the template simply provide the requested parameters.

```{r}
  infuse(my_sql, year=2016, month=8)
```

You can also provide a named list with the requested parameters.

```{r}
my_list<- 
  list(year=2016,
       month=8)

infuse(my_sql, my_list)
```

If a default value is available in the template, it will be used if the parameter is not specified.

```{r}
infuse(my_sql, year=2016)
```

### Working with text files as templates

Just like we're using a string here, a text file can be used. An example text file can be found in the package as follows:

```{r}
example_file<-
  system.file("extdata", "sql1.sql", package="infuser")

example_file
```

Again, we can check which parameters are requested by the template.

```{r, results='hide'}
variables_requested(example_file, verbose = TRUE)
```

And provide their values.

```{r}
infuse(example_file, year = 2016, month = 12)
```

### Infusing vectors

It is quite easy to infuse a vector.

```{r}
years <- c(2013,2014,2015)
sql_string <- "SELECT * FROM T1 WHERE Year IN ({{years}})"

infuse(sql_string, years=years)
```

You can also specify the collapse character.

```{r}
infuse(sql_string, years=years, collapse_char = ";")
```



### Processing / transforming your inputs

A ```transform_function``` can be specified in the ```infuse``` command. This allows for pre-processing of the parameter values before inserting them in the template.

What we don't want to happen is the following:

```{r}
sql<-"INSERT INTO Students (Name) VALUES ({{name}})"
name <- "Robert'); DROP TABLE Students;--"

infuse(sql, name = name)
```

Yikes! A way to solve this is to specify your own custom transform function.

```{r}
my_transform_function<-function(v){
  # replace single quotes with double quotes
  v<-gsub("'", "''", v)
  # encloses the string in single quotes
  v<-paste0("'",v,"'")
  
  return(v)
}

infuse(sql, name = name, transform_function = my_transform_function)
```

Of course you can also use functions from other packages. Specifically for SQL I advise you to take a look at the ```dbplyr::build_sql``` function.


```{r}
infuse(sql, name = name, transform_function = dbplyr::build_sql)
```

## Issues / questions

Simply create a new issue at this GitHub repository.


## Changes

### v.0.2.8

- added `strict` parameter to `infuser`, if set to `TRUE` will stop processing in case of incomplete set of supplied template parameters

### v.0.2.7

- change `dpyr::build_sql` to `dbplyr::build_sql`

### v.0.2.6
- set `readLines`'s `warn` parameter to `FALSE`

### v.0.2.5
- fixed bug/typo related to #10

### v.0.2.4
- fixed testing to adhere to new `testthat` standards

### v.0.2.2
- dropped `key_value_list` parameter (will be interpreted automatically)
- fixed passing of the `variable_identifier`
- ability to make `variable_identifier` persistent

### v.0.2.1
- fixed: incorrect replacement of parameters with same prefix

### v.0.2.0
- consolidating adjustments and releasing version on CRAN

### v.0.1.4
- updated print function for output of infuse (uses ```cat``` for now on)

### v0.1.3
- added optional ```collapse_char``` argument to ```infuse``` command

### v0.1.2
- added optional ```key_value_list``` argument to ```infuse``` command

### v0.1.1
- added optional ```transform_function``` argument to ```infuse``` command