---
title: "Console Printing"
output: 
  BiocStyle::html_document:
    self_contained: yes
    toc: true
    toc_float: true
    toc_depth: 2
    code_folding: show
date: "`r doc_date()`"
package: "`r pkg_ver('GiottoUtils')`"
vignette: >
  %\VignetteIndexEntry{Console Printing}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}  
---

## Relevant Options
```
options("giotto.verbose")
options("giotto.logdir")
options("giotto.last_logpath")
```


## Overview

Diagnostic prints in R are vital for communicating to both users and developers what the function is doing and how it may be going wrong. *GiottoUtils* exports a collection of utility functions that facilitate pretty printing and readability.

There are several types of console printouts in R. Giotto uses the following types of functions for specific purposes:\
- `message()` - Descriptive messages of what a function is doing (most common)\
- `cat()` and `print()` - Diagnostic outputs, usually comments and previews of the data\
- `warning()` - When a function behavior is potentially problematic, given the context and/or inputs\
- `stop()` - Error messages

## Text Formatting

`GiottoUtils::wrap_txt()` can be used to format text to wrap to to console size
or 100 char by default - whichever is less. New lines are treated like "\\n" and
it also applies an indent to all lines after the first.\
This function is wrapped by the convenient print functions detailed below.\
```{r}
library(GiottoUtils)
cat(wrap_txt("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."))
```

<details> <summary>See base behavior</summary>
Base functions for console prints lack text wrapping. Linebreaks also require usage of "\\n" to be formatted as expected.

```{r}
# Code formatting causes "    " to be added the next line
cat("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
    Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.")

# Using \n instead
cat("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\nUt enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.")
```
</details>


## Messages
Giotto primarily uses messages to write helpful console prints.
Whenever a function has a message print, we also encourage adding a `verbose`
param so that it can be turned off. The standard implementation looks like this.
```{r}
test_fun1 <- function(verbose = TRUE) {
    if (verbose) message("hello world")
}

test_fun1()
```

*GiottoUtils* v0.1.1 introduces `vmsg()` which simplifies this to a single
function without a preceding `if` statement. It also applies text wrapping.
Note that the `verbose` default should be `NULL` with this implementation since
`vmsg()` checks for a default using the `"giotto.verbose"` option that can be
set globally.
``` {r}
test_fun2 <- function(verbose = NULL) {
    vmsg(.v = verbose, "hello world")
}

test_fun2()
```

### Debug messages

`vmsg()` also provides other modes of prints. For debugging purposes, it can
be helpful to include more abstract or wordy printouts such as messages for
every successful step. These can be included by flagging as `"debug"`
```{r}
test_debug <- function(verbose = NULL) {
    vmsg(.v = verbose, .is_debug = TRUE, "this is a debug statement")
    vmsg(.v = verbose, "this is a normal message")
}

test_debug(verbose = TRUE)
test_debug(verbose = "debug")
```

### Logging messages

For cases where a record of the messages would be helpful, but it would be
preferred that nothing is actually printed to the console, `vmsg()` also supports
writing to a logfile. This can be done by passing either `"log"` or `"log_debug"`
for the desired level of verbosity to the `verbose` param or `"giotto.verbose"`
option.\
The logfile defaults to being created in `tempdir()`, but this can be set to a
directory of choice using the `"giotto.logdir"` option. The specific path to
the logfile is stored within the `"giotto.last_logpath"`.
```{r}
vmsg(.v = "log", "Write this to a logfile in tempdir")
```

To read the log items, use `giottoReadLog()`.
```{r}
giottoReadLog()
```

You can start a new logfile using `giottoNewLog()`


## Errors
With the modularization of *Giotto* in v4.0.0, it can be hard to find which
module a specific error came from. `.gstop()` is an error handling internal
function within each of the modules that seeks to solve this.
This function will pre-pend which module the error happened in. It also
provides the `.n` param that allows developers to specify how many stackframes
back the error should be reported from.
```{r, error = TRUE}
foo <- function(x, y) {
    GiottoUtils:::.gstop("This is an error.")
}

bar <- function() {
    foo(1, 2)
}

bar()

foo <- function(x, y) {
    GiottoUtils:::.gstop("This is an error.", .n = 2) # report from one stackframe back
}

bar()
```

```{r}
sessionInfo()
```