---
title: "matconv: Converting Function calls"
author: "Siddarta Jairam"
date: "`r strftime(Sys.time(),'%A, %B %d, %Y')`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{function calls}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---


```{r setup, include=FALSE}
library(matconv)
library(knitr)

knitr::opts_chunk$set(fig.pos='center', echo=FALSE, comment='>', results='asis')

showExampleConv <- function(matIn, dict = ""){
	maps <- makeFuncMaps(dict)
	lout <- mat2r(matIn, funcConverters = maps, verbose = 0)

	lout[[2]] <- gsub("\\$", "\\\\$", lout[[2]])
	diff <- length(lout[[2]]) - length(lout[[1]])
	if (diff > 0){
		lout[[1]] <- c(lout[[1]], rep("", diff))
	}
	output <- c("<table><tr>",
    paste0("<th> Dictionary Used </th>",
		"<th>",names(lout)[1],"</th>"),
		paste0("<th>",names(lout)[2],"</th>"),
		"<tr> <td valign = top>",
		paste('|', dict, "\n"),
		"</td> <td valign = top>",
		paste('|', lout[[1]], "\n"),
		"</td>", "<td valign = top>",
		paste('|', lout[[2]], "\n"),
		"</td> </table>")

	cat(paste(output, collapse = "\n"))
}

```
##Dictionary syntax

You cab define a map from using a character vector or a ascii file with the dictionaries. They take on the form "matlab function : Rfunction, arguments". The arguments are given as a comma separated list. For verbatim translation, plain numbers are used and can be used as follows:

```{r first_example}

showExampleConv(
	"thing = linspace(first, second)",
	"linspace:seq, 2, 1")

```

The dictionary is turned into converting functions that are returned as a list of functions using the function "makeFuncMaps". These are named with the Matlab function so the right converter is chosen using name subsetting. You can also do literal strings and strings that have references to the arguments using a percent sign as shown below:

```{r Function_literals}
showExampleConv(
	c("thing = linspace(1, 2, 3)",
	"hjkl = binornd(2.3, 1.5)",
	"asdf = erf(2)"),
	c("linspace:seq, 1, 2, len = %3",
	"binornd:rbinom, 1L, 1, 2",
	"erf: , 2 * pnorm(%1 * sqrt(2)) - 1"))

```

In the second example, R has an extra argument of number of outputs wanted which for the matlab function is always 1. To do this a literal numeral is used by append it with an "L".

In the third example, there isn't a good translation for the "erf" function but it can be done using the mathematical formula. This can be done by just leaving the R function blank and using a literal string.

Matlab has a lot of functions that change dramatically with different inputs. This can be done using flags on the name of the Matlab function. Instead of returning a list of one function in the map it returns multiple functions for conversion. The decision making to use one function over the other is given as another function depending on the inputs in "map\$flags\$DictSwitch". So the calls that are used are used are grabbing the Matlab arguments and throwing them into "dictSwitch" to figure out the index of the function to use. The rest of the flags can be found using that index as well as the function to convert the Matlab line. The switching flags that can be used are as follows:

* number of arguments (--if 2)
* an argument is equal to a particular value (--if 2 == 2L)
* number of outputs requested (--length(out) == 2)
* if none of the other conditions were met (--finally)

```{r Func_switcher}
showExampleConv(
	c("thing = rand(1, 5)",
	 "thing = rand(5, 1)",
	 "thing = rand(5, 5)"),
	c("rand--if 1 == 1L:runif, 2",
    "rand--if 2 == 1L:runif, 1",
    "rand--if finally:matrix, runif(%1 * %2), %1)"))

```

R doesn't have a native way have more than one output from a function like matlab but we can simulate it using a list out and then assign the variables in other calls. For user made functions the solution was to return a list of the variables and this is the unpacking in another environment. This can be done with the flag on the output, "--out args". here args is a space separated list with the args of that R gives in the list output.

```{r mult_out}
showExampleConv(
  c("[myL myU myP] = lu(badMatrix)"),
  c("lu: , expand(lu(Matrix::Matrix(%1))) --out L U P")
  )

```

Function switchers and multiple outputs or any other flag can be used together as everything is indexed at the same level. I can imagine more flags can be added to deal with matrix algebra more directly. This will evolve once the data structures are converted in a later version.

.
