diff --git a/README.md b/README.md deleted file mode 100644 index 05399f1..0000000 --- a/README.md +++ /dev/null @@ -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 diff --git a/branding/logo.png b/branding/logo.png deleted file mode 100644 index 7f29ba5..0000000 Binary files a/branding/logo.png and /dev/null differ diff --git a/branding/logo.xcf b/branding/logo.xcf deleted file mode 100644 index 8370fee..0000000 Binary files a/branding/logo.xcf and /dev/null differ diff --git a/docs/custom_loggers.md b/docs/custom_loggers.md new file mode 100644 index 0000000..e354e5d --- /dev/null +++ b/docs/custom_loggers.md @@ -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`. diff --git a/docs/custom_transforms.md b/docs/custom_transforms.md new file mode 100644 index 0000000..3c66906 --- /dev/null +++ b/docs/custom_transforms.md @@ -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. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..8c53810 --- /dev/null +++ b/docs/index.md @@ -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 + diff --git a/docs/quick_start.md b/docs/quick_start.md new file mode 100644 index 0000000..b24bb2b --- /dev/null +++ b/docs/quick_start.md @@ -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. diff --git a/dub.json b/dub.json deleted file mode 100644 index dbe13d3..0000000 --- a/dub.json +++ /dev/null @@ -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", -} diff --git a/source/dlog/core.d b/source/dlog/core.d deleted file mode 100644 index 04865d9..0000000 --- a/source/dlog/core.d +++ /dev/null @@ -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); -} diff --git a/source/dlog/defaults.d b/source/dlog/defaults.d deleted file mode 100644 index c096113..0000000 --- a/source/dlog/defaults.d +++ /dev/null @@ -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); - } -} diff --git a/source/dlog/package.d b/source/dlog/package.d deleted file mode 100644 index f91db70..0000000 --- a/source/dlog/package.d +++ /dev/null @@ -1,9 +0,0 @@ -/** -* Package definition module -* -* Import this to use dlog -*/ -module dlog; - -public import dlog.core; -public import dlog.defaults;