deavmi/dlog
deavmi
/
dlog
mirror of https://github.com/deavmi/dlog.git
1
0
Fork 0
Code Issues Releases Activity

Removed code

This commit is contained in:
Tristan B. Velloza Kildaire 2022-11-22 17:35:29 +02:00
parent 9c55fee725
commit 81246b9240
11 changed files with 137 additions and 335 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
README.md
View File

@ -1,130 +0,0 @@
![](branding/logo.png)
dlog
====
**Simple and modular logging library**
`[2021-Dec-23 11:17:35.3527637] (source/dlog/testing/thing.d:12): This is a log message`
---
## Usage
We recommend you use [dub](http://code.dlang.org) to add dlog to your project as follows:
```
dub add dlog
```
* [View on DUB](https://code.dlang.org/packages/dlog)
* [View API](https://dlog.dpldocs.info/)
### Components
dlog is formed out of two main components:
1. `Logger`
* The logger contains the needed barebones for facilitating the actual logging of text
2. `MessageTransform`
* A MessageTransform is attached to a logger and performs manipulation on the text input into the logger for logging
* They may be chained as to perform multiple transformations in a stream-like fashion
### Quick start
If you want to immediately begin logging text usin the defaults and don't care about implementing your own transformations then you can
simply use the defaulkt logger as follows:
```d
import dlog;
Logger logger = new DefaultLogger();
logger.log("This is a log message");
logger.log(1);
logger.log(1==1);
logger.log([1,2,3]);
```
This will output the following:
```
[2021-Dec-23 11:17:35.3527637] (source/dlog/testing/thing.d:12): This is a log message
[2021-Dec-23 11:17:35.3527717] (source/dlog/testing/thing.d:13): 1
[2021-Dec-23 11:17:35.3527789] (source/dlog/testing/thing.d:14): true
[2021-Dec-23 11:17:35.3527871] (source/dlog/testing/thing.d:15): [1, 2, 3]
```
As you can see file and line numbering of where the `log()` function is called appears in the log message which can be quite helpful
for debugging.
### Custom loggers
#### Implementing your own transform
Perhaps the default transformation, `DefaultTransform`, may not be what you want. Maybe you want the module name included in the logged
messages or perhaps don't want the date-and-timestamp included at all. All of this can be up to you if you choose to implement your own
message transform.
You will need to start off with a class that inherits from the `MessageTransform` class and then which overrides the `transform` method as shown below:
```d
import dlog;
public class CustomTranform : MessageTransform
{
public override string transform(string text, string[] context)
{
string transformed;
/* Insert code to transform `text` and return the `transformed` text */
return transformed;
}
}
```
Additional information, besides the text being logged itself (this is the `string text` argument), comes in the form of a string array as `string[] context`
the contents of which are described below:
1. `context[0]`
* This contains `__FILE_FULL_PATH__` which is the full path (absolute) to the source file where `log()` was called
2. `context[1]`
* This contains `__FILE__` which is the path (starting at `source/` to the source file where `log()` was called
3. `context[2]`
* This contains a stringified version of `__LINE__` which is the line number of the call to `log()`
4. `context[3]`
* This contains `__MODULE__` which is the name of the module the call to `log()` appeared in
5. `context[4]`
* This contains `__FUNCTION__` which is the name of the function `log()` was called in
6. `context[5]`
* This contains `__PRETTY_FUNCTION__` which is the same as above but with type information
7. `context[5..X]`
* This contains optional extras that were set when the `log()` function was called with the `contextExtras` set
* Example: `log("Hello world", contextExtras=[this])`
#### Creating a Logger
We now need to create a logger that makes use of our message transform, we can do so by creating an instance
of the `Logger` class and passing in our `MessageTransform` as so:
```d
Logger customLogger = new DefaultLogger(new CustomTranform());
```
The above is all one needs to be able to pull off a custom transformation.
#### Custom Logger
Custom loggers can also be created by sub-classing the `Logger` class and overriding the `logImpl(string)` method.
The reason someone may want to do this is up to them. One easy to think of reason is to perhaps applying filtering
of messages to be logged and skip them (as this method is where the I/O of printing out the logs normally happens).
Another reason may be to log to a different data resource, the `DefaultLogger` writes to the file descriptor `0` (stdout),
but you may want to log over a socket connection to a remote machine for example, or perhaps do several pieces of
I/O for your logging. One can do that with a custom logger, you shoudl see `source/dlog/defaults.d` for the implementation
of a custom logger, such as `DefaultLogger`.
## License
LGPLv2

BIN
branding/logo.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 12 KiB

BIN
branding/logo.xcf
View File

Binary file not shown.

10
docs/custom_loggers.md Normal file
View File

@ -0,0 +1,10 @@
Custom loggers
==============
Custom loggers can also be created by sub-classing the `Logger` class and overriding the `logImpl(string)` method.
The reason someone may want to do this is up to them. One easy to think of reason is to perhaps applying filtering
of messages to be logged and skip them (as this method is where the I/O of printing out the logs normally happens).
Another reason may be to log to a different data resource, the `DefaultLogger` writes to the file descriptor `0` (stdout),
but you may want to log over a socket connection to a remote machine for example, or perhaps do several pieces of
I/O for your logging. One can do that with a custom logger, you shoudl see `source/dlog/defaults.d` for the implementation
of a custom logger, such as `DefaultLogger`.

56
docs/custom_transforms.md Normal file
View File

@ -0,0 +1,56 @@
Custom transforms
=================
## Implementing your own transform
Perhaps the default transformation, `DefaultTransform`, may not be what you want. Maybe you want the module name included in the logged
messages or perhaps don't want the date-and-timestamp included at all. All of this can be up to you if you choose to implement your own
message transform.
You will need to start off with a class that inherits from the `MessageTransform` class and then which overrides the `transform` method as shown below:
```d
import dlog;
public class CustomTranform : MessageTransform
{
public override string transform(string text, string[] context)
{
string transformed;
/* Insert code to transform `text` and return the `transformed` text */
return transformed;
}
}
```
Additional information, besides the text being logged itself (this is the `string text` argument), comes in the form of a string array as `string[] context`
the contents of which are described below:
1. `context[0]`
* This contains `__FILE_FULL_PATH__` which is the full path (absolute) to the source file where `log()` was called
2. `context[1]`
* This contains `__FILE__` which is the path (starting at `source/` to the source file where `log()` was called
3. `context[2]`
* This contains a stringified version of `__LINE__` which is the line number of the call to `log()`
4. `context[3]`
* This contains `__MODULE__` which is the name of the module the call to `log()` appeared in
5. `context[4]`
* This contains `__FUNCTION__` which is the name of the function `log()` was called in
6. `context[5]`
* This contains `__PRETTY_FUNCTION__` which is the same as above but with type information
7. `context[5..X]`
* This contains optional extras that were set when the `log()` function was called with the `contextExtras` set
* Example: `log("Hello world", contextExtras=[this])`
## Creating a Logger
We now need to create a logger that makes use of our message transform, we can do so by creating an instance
of the `Logger` class and passing in our `MessageTransform` as so:
```d
Logger customLogger = new DefaultLogger(new CustomTranform());
```
The above is all one needs to be able to pull off a custom transformation.

32
docs/index.md Normal file
View File

@ -0,0 +1,32 @@
dlog
====
**Simple and modular logging library**
## Usage
We recommend you use [dub](http://code.dlang.org) to add dlog to your project as follows:
```
dub add dlog
```
* [View on DUB](https://code.dlang.org/packages/dlog)
* [View API](https://dlog.dpldocs.info/)
## Components
dlog is formed out of two main components:
1. `Logger`
* The logger contains the needed barebones for facilitating the actual logging of text
2. `MessageTransform`
* A MessageTransform is attached to a logger and performs manipulation on the text input into the logger for logging
* They may be chained as to perform multiple transformations in a stream-like fashion
---
## License
LGPLv2

39
docs/quick_start.md Normal file
View File

@ -0,0 +1,39 @@
Quick start
===========
### Adding the dependency
We recommend you use [dub](http://code.dlang.org) to add dlog to your project as follows:
```
dub add dlog
```
### Start logging
If you want to immediately begin logging text usin the defaults and don't care about implementing your own transformations then you can
simply use the default logger as follows:
```d
import dlog;
Logger logger = new DefaultLogger();
logger.log("This is a log message");
logger.log(1);
logger.log(1==1);
logger.log([1,2,3]);
```
This will output the following:
```
[2021-Dec-23 11:17:35.3527637] (source/dlog/testing/thing.d:12): This is a log message
[2021-Dec-23 11:17:35.3527717] (source/dlog/testing/thing.d:13): 1
[2021-Dec-23 11:17:35.3527789] (source/dlog/testing/thing.d:14): true
[2021-Dec-23 11:17:35.3527871] (source/dlog/testing/thing.d:15): [1, 2, 3]
```
As you can see file and line numbering of where the `log()` function is called appears in the log message which can be quite helpful
for debugging.

10
dub.json
View File

@ -1,10 +0,0 @@
{
"authors": [
"Tristan B. Kildaire"
],
"copyright": "Copyright © 2021, Tristan B. Kildaire",
"description": "Simple and modular logging library",
"license": "LGPLv2",
"name": "dlog",
"targetType": "library",
}

161
source/dlog/core.d
View File

@ -1,161 +0,0 @@
/**
* Core module containing types pertaining to the base Logger
* class and base MessageTransform class (along with a default
* transform, DefaultTransform)
*/
module dlog.core;
import std.conv : to;
import dlog.defaults;
/**
* DefaultTransform
*
* Provides a transformation of the kind
*
* [date+time] (srcFile:lineNumber): message `\n`
*/
public final class DefaultTransform : MessageTransform
{
/**
* Our transformation
*/
public override string transform(string text, string[] context)
{
string message;
/* Date and time */
import std.datetime.systime : Clock, SysTime;
SysTime currTime = Clock.currTime();
import std.conv : to;
string timestamp = to!(string)(currTime);
message = "["~timestamp~"]";
/* Module information */
message = message ~ "\t(";
message = message ~ context[1]~":"~context[2];
message = message ~ "): "~text;
/* Add trailing newline */
message = message ~ '\n';
return message;
}
}
/**
* Logger
*
* Represents a logger instance
*/
public class Logger
{
/* Starting transformation */
private MessageTransform messageTransform;
/**
* Constructs a new Logger with the default
* MessageTransform, see TODO (ref module)
*/
this()
{
this(new DefaultTransform());
}
/**
* Constructs a new Logger with the given
* MessageTransform
*/
this(MessageTransform messageTransform)
{
this.messageTransform = messageTransform;
}
/**
* Log a message
*/
public final void log(TextType)(TextType message, string c1 = __FILE_FULL_PATH__,
string c2 = __FILE__, ulong c3 = __LINE__,
string c4 = __MODULE__, string c5 = __FUNCTION__,
string c6 = __PRETTY_FUNCTION__, string[] contextExtras = null)
{
/* Construct context array */
string[] context = [c1, c2, to!(string)(c3), c4, c5, c6]~contextExtras;
/* Apply the transformation on the message */
string transformedMesage = messageTransform.execute(to!(string)(message), context);
/* Call the underlying logger implementation */
logImpl(transformedMesage);
}
/**
* Logging implementation, this is where the fina
* transformed text will be transferred to and finally
* logged
*/
protected abstract void logImpl(string message);
}
/**
* MessageTransform
*
* A message transform takes in text, applies
* a transformation to it and outputs said text
*
* Transforms may be chained
*/
public abstract class MessageTransform
{
/* Next transformation (if any) */
private MessageTransform chainedTransform;
/**
* The actual textual transformation.
*
* This is to be implemented by sub-classes
*/
public abstract string transform(string text, string[] context);
/**
* Chain a transform
*/
public final void chain(MessageTransform transform)
{
chainedTransform = transform;
}
/**
* Perform the transformation
*/
public final string execute(string text, string[] context)
{
/* Perform the transformation */
string transformedText = transform(text, context);
/* If there is a chained transformation */
if(chainedTransform)
{
transformedText = chainedTransform.execute(transformedText, context);
}
return transformedText;
}
}
/**
* Tests the DefaultLogger
*/
unittest
{
Logger logger = new DefaultLogger();
logger.log("This is a log message");
logger.log(1);
logger.log(1.1);
logger.log(true);
logger.log([1,2,3]);
logger.log('f');
logger.log(logger);
}

25
source/dlog/defaults.d
View File

@ -1,25 +0,0 @@
/**
* Includes defaults such as the DefaultLogger
*/
module dlog.defaults;
import dlog.core : Logger;
/**
* DefaultLogger
*
* The default logger logs to standard output (fd 0)
*/
public final class DefaultLogger : Logger
{
this()
{
/* Use the DefaultTransform */
}
protected override void logImpl(string message)
{
import std.stdio : write;
write(message);
}
}

9
source/dlog/package.d
View File

@ -1,9 +0,0 @@
/**
* Package definition module
*
* Import this to use dlog
*/
module dlog;
public import dlog.core;
public import dlog.defaults;