---
title: "Customize Your Diagrams"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Customize Your Diagrams}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

In this vignette we showcase the arguments of `flow_view()` and `flow_run()`
that affect the way the diagrams are displayed.

## `prefix`

`prefix` is used to display special comments on top of code blocks, it must start 
with `"#"`.

```{r, eval = FALSE}
library(flow)

factorial <- function(x) {
  ## is the input valid ?
  if(!is.integer(x) && length(x) == 1) {
    ## fail explicitly
    stop("`x` must be integer!")
  }
  ## initialize result
  res <- 1
  for(i in 2:x) {
    ## update result
    res <- res * i
    ## is the result to big ?
    if(res > 1000) {
      ## fail explicitly
      stop("too big!!!") 
    }
  }
  res
}

flow_view(factorial, prefix = "##")
```

<img src="customize_1.png" alt="" width="300"/>

* `prefix` can be of length > 1 in which case all given prefixes are considered
* The unprefixed comments are ignored.
* Prefixed comments right before control flow calls (here `if`) will serve
as headers for control flow header blocks.
* Prefixed comments before other code will serve as headers for the subsequent
code chunks.
* Adding special comments in the middle of a code block code will split the block in two
* We need to use `{}` after `if (n == 0L)` if we want to use a prefixed comment

This argument is ignored when using the *plantuml* engine.

## `code`

`code` is used to choose whether to display the code in code blocks or only the 
header, if `NA` the code will be displayed only if no header is defined by 
special comments.

```{r, eval = FALSE}
flow_view(factorial, code = FALSE)
```

<img src="customize_2.png" alt="" width="300"/>

```{r, eval = FALSE}
flow_view(factorial, prefix = "##", code = FALSE)
```

<img src="customize_3.png" alt="" width="300"/>

```{r, eval = FALSE}
flow_view(factorial, prefix = "##", code = NA) # pay attention to the last block
```

<img src="customize_4.png" alt="" width="300"/>

This argument is ignored when using the *plantuml* engine.

## `narrow`

`narrow` is used to narrow makes sure the diagram stays centered on one column,
it will be longer but won't shift, which might be easier to display
on web pages for instance.

```{r, eval = FALSE}
kg_to_lb <- function(mass) {
  if(mass < 0) {
    stop("mass should not be negative!")
  } else {
      mass <- 2.20462262185 * mass
  }
  mass
}

flow_view(kg_to_lb)
```

<img src="customize_5.png" alt="" width="300"/>

```{r, eval = FALSE}
flow_view(kg_to_lb, narrow = TRUE)
```

<img src="customize_6.png" alt="" width="300"/>

This argument is ignored when using the *plantuml* engine.

## `truncate`

`truncate` is used to provide the maximum number of characters to be printed per 
line, it works for code and headers.

```{r, eval = FALSE}
fun <- function() {
  ## short header
  x <- "__________________________long string__________________________"
  ## __________________________long header__________________________
  x
}
flow_view(fun, prefix = "##")
```

<img src="customize_7.png" alt="" width="300"/>

```{r, eval = FALSE}
flow_view(fun, truncate = 15, prefix = "##")
```

<img src="customize_8.png" alt="" width="300"/>

## `swap`

By default calls like `x <- if(cond) a else b` are automatically transformed into
`if(cond) x <- a else x <- b` so we can display the logic in a proper diagram.

If this is not acceptable this can be turned off by setting `swap` to `FALSE`.

```{r, eval = FALSE}
fun <- function(cond) {
  x <- if(cond) this else that
  x
}

flow_view(fun)
```

<img src="customize_9.png" alt="" width="300"/>

```{r, eval = FALSE}
flow_view(fun, swap = FALSE)
```

<img src="customize_10.png" alt="" width="300"/>