README.md

# IRCNOW lib

* 1. [Logger](#Logger)
  * 1.1. [Formating the logger](#Formatingthelogger)
  * 1.2. [SUGAR vs JSON](#SUGARvsJSON)
  * 1.3. [Loggin Verbosity](#LogginVerbosity)


##  1. <a name='Logger'></a>Logger

Example usage:
```perl
use strict;
use warnings;

use lib qw(./lib);
use IRCNOW::Logger;

my $logger = new IRCNOW::Logger(IRCNOW::Logger->INFO, IRCNOW::Logger->SUGAR);
#my $logger = new IRCNOW::Logger(IRCNOW::Logger->DEBUG, IRCNOW::Logger->SUGAR);
#my $logger = new Logger(IRCNOW::Logger->DEBUG, Logger->SUGAR, ":loglevel :timestamp :msg");
#my $logger = new Logger(IRCNOW::Logger->DEBUG, Logger->SUGAR, ":loglevel :invalid :timestamp :msg");
#my $logger = new Logger(IRCNOW::Logger->DEBUG, Logger->SUGAR, ":timestamp [:loglevel%2] :package%8 :file%10 :msg");

$logger->debug("debug");
$logger->info("info");
$logger->warn("warn");
$logger->error("error");


# output:
# 2023-07-02 19:22:03 [DEBUG] main     test.pl:12 debug
# 2023-07-02 19:22:03 [INFO ] main     test.pl:13 info
# 2023-07-02 19:22:03 [WARN ] main     test.pl:14 warn
# 2023-07-02 19:22:03 [ERROR] main     test.pl:15 error
```

Arguments are: `verbosity, printType, format`.

###  1.1. <a name='Formatingthelogger'></a>Formating the logger

Logger has these fields:
* timestamp
* loglevel
* package
* file
* fileline (file with line number)
* line
* msg

Prepend the field with a `:` and postfix the field with a `%` followed by a number. Add spaces in between.
ex:

`:timestamp [:loglevel%5] :package%8 :fileline%10 :msg`

Note: If your field value is longer than the specified length, it will print out the full value.
EX: 
Format: `:timestamp [:loglevel%2] :package%8 :fileline%10 :msg` 
result:
```
2023-07-02 19:21:54 [DEBUG] main     test.pl    debug
2023-07-02 19:21:54 [INFO] main     test.pl    info
2023-07-02 19:21:54 [WARN] main     test.pl    warn
2023-07-02 19:21:54 [ERROR] main     test.pl    error
```

###  1.2. <a name='SUGARvsJSON'></a>SUGAR vs JSON

There are two options to print logs:
* sugar
* JSON

JSON logging is meant for being picked up by services such as grafana or the elk stack.
Sugar logging is meant for human readable output to stdout. 

Example of JSON:
```
{ "level": "DEBUG", "msg": "debug", "package": "main", "file": "test.pl:12" }
{ "level": "INFO", "msg": "info", "package": "main", "file": "test.pl:13" }
{ "level": "WARN", "msg": "warn", "package": "main", "file": "test.pl:14" }
{ "level": "ERROR", "msg": "error", "package": "main", "file": "test.pl:15" }
```

Example of Sugar:
```
2023-07-02 19:22:03 [DEBUG] main     test.pl:12 debug
2023-07-02 19:22:03 [INFO ] main     test.pl:13 info
2023-07-02 19:22:03 [WARN ] main     test.pl:14 warn
2023-07-02 19:22:03 [ERROR] main     test.pl:15 error
```

###  1.3. <a name='LogginVerbosity'></a>Logging Verbosity

There are verbosity levels:
* NONE
* ERRORS
* ERROR (backwards compatible)
* WARNINGS
* WARN (backwards compatible)
* INFO
* DEBUG
* ALL

Each level is in order such that if the `INFO` level was chosen, you would see logs for `ERROR`, `WARN`, and `INFO`