nojhan/clutchlog
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

better readme

Browse source
This commit is contained in:
Johann Dreo 2020-09-04 10:51:58 +02:00
commit 75f18ea8a8
1 changed files with 14 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

30
README.md
View file

@ -1,27 +1,24 @@
Clutchlog is a logging system whith targets versatile debugging. **Clutchlog is a logging system whith targets versatile debugging.**
It allows to (de)clutch messages either for a given: log level, source code location or call stack depth. **It allows to (de)clutch messages either for a given: log level, source code location or call stack depth.**
Features Features
======== ========
Clutchlog allows to select which log messages will be displayed, based on their locations: Clutchlog allows to select which log messages will be displayed, based on their locations:
- classical log levels: each message has a given detail level and it is displayed if you ask for a at least the same one - *classical log levels*: each message has a given detail level and it is displayed if you ask for a at least the same
(current ones: quiet, error, warning, info, debug, xdebug). one.
- call stack depth: you can ask to display messages within functions which are called up to a given stack depth. - *call stack depth*: you can ask to display messages within functions which are called up to a given stack depth.
- source code location: you can ask to display messages called from given files, functions and line number, all based on - *source code location*: you can ask to display messages called from given files, functions and line number, all based on
regular expressions. regular expressions.
Appart from those, Clutchlog have classical logging system features: output selection and formatting,
default to unbuffered mode, etc.
Of course, Clutchlog is disabled by default if `NDEBUG` is not defined. Of course, Clutchlog is disabled by default if `NDEBUG` is not defined.
Example Example
======= =======
Adding a message is a simple as calling a macro (which is declutched in Debug build type): Adding a message is a simple as calling a macro (which is declutched in Debug build type, when `NDEBUG` is not defined):
```cpp ```cpp
CLUTCHLOG(info, "matrix size: " << m << "x" << n); CLUTCHLOG(info, "matrix size: " << m << "x" << n);
``` ```
@ -81,7 +78,7 @@ CLUTCHLOG(debug, "hello " << value << " world");
There is also a macro to dump the content of an iterable within a separate file: `CLUTCHDUMP`. There is also a macro to dump the content of an iterable within a separate file: `CLUTCHDUMP`.
This function takes care of incrementing a numeric suffix in the file name, This function takes care of incrementing a numeric suffix in the file name,
if an existing file exists. if an existing file with this name exists.
```cpp ```cpp
std::vector<int> v(10); std::vector<int> v(10);
std::generate(v.begin(), v.end(), std::rand); std::generate(v.begin(), v.end(), std::rand);
@ -99,7 +96,7 @@ Note that if you pass a file name without the `{n}` tag, the file will be overwr
Location filtering Location filtering
------------------ ------------------
To configure the global behaviour of the logger, you must first get a reference on its instance: To configure the global behaviour of the logger, you must first get a reference on its (singleton) instance:
```cpp ```cpp
auto& log = clutchlog::logger(); auto& log = clutchlog::logger();
``` ```
@ -114,13 +111,13 @@ Current levels are defined in an enumeration as `clutchlog::level`:
enum level {quiet=0, error=1, warning=2, progress=3, info=4, debug=5, xdebug=6}; enum level {quiet=0, error=1, warning=2, progress=3, info=4, debug=5, xdebug=6};
``` ```
File, function and line are indicated using regular expression: File, function and line filters are indicated using (ECMAScript) regular expressions:
```cpp ```cpp
log.file(".*"); // File location, defaults to any. log.file(".*"); // File location, defaults to any.
log.func(".*"); // Function location, defaults to any. log.func(".*"); // Function location, defaults to any.
log.line(".*"); // Line location, defaults to any. log.line(".*"); // Line location, defaults to any.
``` ```
A shortcut function can be used to indicates file, function and line regular expression at once: A shortcut function can be used to filter all at once:
```cpp ```cpp
log.location(file, func, line); // Defaults to any, second and last parameters being optional. log.location(file, func, line); // Defaults to any, second and last parameters being optional.
``` ```
@ -142,7 +139,7 @@ Available tags are:
- `{msg}`: the logged message, - `{msg}`: the logged message,
- `{name}`: the name of the current binary, - `{name}`: the name of the current binary,
- `{level}`: the current log level (i.e. `Quiet`, `Error`, `Warning`, `Info`, `Debug` or `XDebug`), - `{level}`: the current log level (i.e. `Quiet`, `Error`, `Warning`, `Progress`, `Info`, `Debug` or `XDebug`),
- `{level_letter}`: the first letter of the current log level, - `{level_letter}`: the first letter of the current log level,
- `{file}`: the current file (absolute path), - `{file}`: the current file (absolute path),
- `{func}`: the current function, - `{func}`: the current function,
@ -155,8 +152,9 @@ it can be overriden at compile time by defining the `CLUTCHLOG_DEFAULT_FORMAT` m
The default format of the comment added with the dump macro is The default format of the comment added with the dump macro is
`"# [{name}] {level} in {func} (at depth {depth}) @ {file}:{line}"`. `"# [{name}] {level} in {func} (at depth {depth}) @ {file}:{line}"`.
It can be modified at compile time with `CLUTCHDUMP_DEFAULT_FORMAT`. It can be edited with the `format_comment` method.
If it is set to an empty string, then no comment line is added. If it is set to an empty string, then no comment line is added.
The default can be modified at compile time with `CLUTCHDUMP_DEFAULT_FORMAT`.
By default, the separator between items in the container is a new line. By default, the separator between items in the container is a new line.
To change this behaviour, you can change `CLUTCHDUMP_DEFAULT_SEP` or To change this behaviour, you can change `CLUTCHDUMP_DEFAULT_SEP` or
call the low-level `dump` method. call the low-level `dump` method.