flogging 0.6.0

This is a fast, flexible logging crate, loosely based on the Java logging package: java.util.logging.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

<!-- markdownlint-disable-file MD036 MD037 -->

# FLogging crate

**<< Under Active Development >>**

`Flogging` provides an easy framework for logging.

Log entries can be sent to the console (stdout or stderr), file, memory log, or a custom handler. They
can be formatted in various layouts: ISO8601, Simple, Unix TimeStamp, or a custom
layout.

Macros and public methods are provided, with the macros being the simplest _method_ of operation.

There are several levels for logging at:

- SEVERE,
- WARNING,
- INFO,
- CONFIG,
- FINE,
- FINER, and
- FINEST

There are even two special settings:

- ALL, and
- OFF

## ** WARNING **

**_Version 0.6.0_** **BREAKS**:

- The output from `Iso8601Formatter`. It has been changed [^bars].
  The format string for `fmt_string` has been changed from:

  `"{dt:35} |{mod_path}->{fn_name}| [{level:7}] {message}"`

  to:

  `"{dt:35} {mod_path}->{fn_name} [{level:7}] {message}"`

- In similar fashion, both `SimpleFormatter` and `UnixTimestampFormatter` have been changed [^bars].
- Added new method to `HandlerTrait` - `set_test_mode()`. This will require updating any custom formatters you have created.

[^bars]: This may affect any tests or logs that expect the precise old format.\
Sorry about this. The "|" bars were a holdover from early testing, and were not
removed before publishing.

**Note:**\
Version (0.6.0) is backwards compatible with version (0.5.0). Therefore it has the same warning. It is recommended that any use of version (0.4.X) be bumped to atleast (0.5.0), fixing the minor issue, as this will continue into all subsequent version updates.

**_Version 0.5.0_** **BREAKS** the custom formatter API.

If you have _not_ yet started developing your own versions of the formatter, then this will _NOT_ affect you. The Public API is currently backwards compatible to version (0.4.1).

For the rest of you, please check out `FormatType::Custom` and view the **Change Log**.

## New Instruction Guide

That's right. I realized that having _just_ the API documentation was not going to be enough for you nerds out there, who just **love** to customize. So, I have written a guide. So far it covers the development of a _custom handler_ and a _custom formatter_. There should be enough of an example of each to get you started.

At some point in the future, I might add more help/instructions. But at the moment I can't think of anything else to add. If you think of something that will help you and others, create an [issue on Github].

## Acknowledgement

This project is being developed as a learning experience. I am fully aware that there are many other logging crates out there, but where is the fun in that? As a hobbyist it still seems like a good idea.

A lot of the functionality has been inspired by, and even copied from (at the API level), the JDK's `java.util.logging` package. Whether or not it will ever become a _full_ port, only time and my level of interest, will tell. Remember, "learning experience"?

## What's in a name?

`Flogging`, as-in, "Flogging a dead horse", or "Just another f\*ing logger". As I wrote above, there are _many_ other logging crates around. This is just my learning spin on a very well covered tool.

## What's in a number?

As per the requirements of the crate site (<https://crates.io/>), I am using
Semantic Versioning in accordance with the specifications documented
on this site: <https://semver.org/>.

Therefore, once I am certain that the API is stable, I'll release v1.0.0.

## Coverage Report

I have included the latest test coverage report, generated by `llvm-cov` and `llvm-cov-pretty`.\
It is located here: [coverage report].

## History

See [RELEASELOG.md] and [CHANGELOG.md]

## Final word

Having said all that, with jokes aside, this is a fully working project. One that I
hope others will benefit from. If not just using it, then perhaps learning from
the source code displaying the various solutions to the problems involved in providing the
functionality.

Anyway, have fun.\
[Bradley Willcott][bw]\
<mailto:bw.opensource@yahoo.com>

[bw]: https://github.com/bewillcott
[coverage report]: https://bewillcott.github.io/flogging/coverage
[CHANGELOG.md]: https://bewillcott.github.io/flogging/extras/CHANGELOG.html
[RELEASELOG.md]: https://bewillcott.github.io/flogging/extras/RELEASELOG.html
[issue on Github]: https://github.com/bewillcott/flogging/issues