---
title: "matconv: The use of syntax converters"
author: "Siddarta Jairam"
date: "`r strftime(Sys.time(),'%A, %B %d, %Y')`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{basic syntax }
  %\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){
	lout <- mat2r(matIn, verbose = 0)
	diff <- length(lout[[2]]) - length(lout[[1]])
	if (diff > 0){
		lout[[1]] <- c(lout[[1]], rep("", diff))
	}
	output <- c("<table><tr>",
    paste0("<th>",names(lout)[1],"</th>"),
		paste0("<th>",names(lout)[2],"</th>"),
		"<tr> <td valign = top>",
		paste('|', lout[[1]], "\n"),
		"</td>", "<td valign = top>",
		paste('|', lout[[2]], "\n"),
		"</td> </table>")
	
	cat(paste(output, collapse = "\n"))
}

```
## Basic calls

The first thing that the translator does is go through the program and convert the basic syntax from Matlab to R. This includes the following:

1. Changing symbols around ('~' to '!', 'end' to '}')
2. Get rid of the semicolons at the end of the line
3. Change the assignment symbol from '=' to '<-'

This is done with simple 'gsub' calls and examples are shown below.

```{r basSyntax}
example <- c( "thing = 5 * 3;", "thing2 = (thing ~= 14);")
showExampleConv(example)

```


## Flow Control

Next it goes through all the different flow control blocks and converts them to the R equivalent. The converted blocks are as follows.

1. if
2. if else
3. for
4. while

Switch statements will be included in a future version as R does not really have a true switch / case type block. The 'switch' function is helpful in a lot of situations but the usage is different from how other languages do switch blocks. Below are some examples of how its used for the other blocks.

```{r flow}
example <- c("if argLen == 1", "  doThing = 9999;","else", "  doThing = 1;","end")
showExampleConv(example)

```

## User functions

In matlab there is a distinction between script files and function files. If a function file is supplied (first word is "function") than the function definitions will be changed with some of syntax.

The returned objects are gathered and put in a 'return' statement at the end of the function. If there is more than one return statement a list of those objects are returned. Default inputs or an unknown length of inputs into a Matlab function is handled using a protected word 'varargin'. The closest R equivalent is '...' which will be turned into a list as the variable 'varargin' in the R version. There is a whole family of input and output handlers in Matlab but this is the most useful in my eyes so I gave it higher priority. Examples of this type of conversion is shown below.

```{r userFunctions}
example <- c("function [ dat ] = xlsReadPretty(varargin))", "  didThing = 1*3;", "  dat = didThing / 3;", "end")
showExampleConv(example)

```

In another version, there could be options to make this conversion more integrated with the rest of the code or specifying another return class other than 'list'. This is a precursour to the function converters by adding these user functions into the dictionary of Matlab base functions to R base functions.