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

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

# General informations

The logging of informations is important to have useful logs to explicit
processings.
Info logs are used to show general informations.
Warning logs are used to show potential errors, that are not blocking for
the processing.
Error logs are used to explicit better errors, before stopping the
program.
Debug logs are usually activated with the command line flag `-d`. They
are used to show usefull debug informations and should be very widely
used.
Verbose are like info logs, but devivers optionnal informations. It is
usually activated with the `-v` or `-V` command line flag.
INTERNAL logs are for the logger itself, when it detects internal
problems, like a closed output log file, or so.

# What is a logger?

This is a class that helps you logging outputs. The advantages of using
a logger is that people write logs in a uniform way.
The logger can be named and will provide more informations like:

 - the part of the program this log string comes from
 - the time it happenned
 - the severity of the information

It can also help you create log files, 


# How to create a logger?
```{r}
logger <- W4MRUtils::get_logger("LoggerTest1")
```


# How to create a log file?

```{r}
## provide a path at logger creation
logfile <- tempfile()
logger <- W4MRUtils::get_logger(
  "LoggerTest2",
  out_path = logfile
)
```

or

```{r}
## add it after the logger's creation
logfile <- tempfile()
logger <- W4MRUtils::get_logger("LoggerTest3")
logger$set_out_paths(logfile)
```

# How to send messages?
```{r}
## messages are printed to the terminal and sent to the log file.
logger$info("Info message")
logger$warning("Warning message")
logger$error("Error message")
logger$debug("Debug message")
## debug messages are deactivated by default
logger$verbose("Verbose message")
## verbose messages are deactivated by default
print(readLines(logfile))
file.remove(logfile)
```



# formating

By default, logs are formated using the following pattern:
"[{{ level }}-{{ name }}-{{ time }}] - {{ message }}"
You can change the format string when you create the logger with get_logger:

```{r}
W4MRUtils::get_logger(
  "Processing",
  format = "[{{ time }}-{{ name }}] - {{ message }}"
)
```

# coloring
By default, a coloring is used to easily differentiate kinds of log.
The coloring is the following:

  - info: green
  - warning: orange
  - error: red
  - debug: purplue
  - verbose: blue
  - INTERNAL: white

This coloring can be changed by providing a named list to the get_logger
function:

```{r}
W4MRUtils::get_logger(
  "Processing",
  coloring = list(
    debug = "red",
    warning = "green",
    error = "purple",
    verbose = "blue",
    info = "orange",
    INTERNAL = "white"
  ),
  show_debug = TRUE
)$info("Infos are orange")$debug("Debug is red")
```