documentation

This commit is contained in:
Ellpeck 2020-07-23 02:46:34 +02:00
parent 4617ef5a00
commit 2ab19a2e5d
6 changed files with 158 additions and 5 deletions

View file

@ -1,8 +1,15 @@
using System; using System;
namespace ExtremelySimpleLogger { namespace ExtremelySimpleLogger {
/// <summary>
/// A <see cref="Sink"/> that writes log output to <see cref="Console.Out"/>.
/// </summary>
public class ConsoleSink : Sink { public class ConsoleSink : Sink {
/// <summary>
/// Logs the given message, which has already been formatted using <see cref="Sink.Formatter"/>.
/// </summary>
/// <param name="s">The message to log</param>
public override void Log(string s) { public override void Log(string s) {
Console.WriteLine(s); Console.WriteLine(s);
} }

View file

@ -1,15 +1,27 @@
using System;
using System.IO; using System.IO;
namespace ExtremelySimpleLogger { namespace ExtremelySimpleLogger {
/// <summary>
/// A <see cref="Sink"/> that writes log output to a file.
/// </summary>
public class FileSink : Sink { public class FileSink : Sink {
private readonly StreamWriter writer; private readonly StreamWriter writer;
/// <summary>
/// Creates a new file sink with the given settings.
/// </summary>
/// <param name="file">The full, or relative, path of the file to write to</param>
/// <param name="append">Whether new output should be appended to the old log file</param>
public FileSink(string file, bool append) : public FileSink(string file, bool append) :
this(new FileInfo(file), append) { this(new FileInfo(file), append) {
} }
/// <summary>
/// Creates a new file sink with the given settings.
/// </summary>
/// <param name="file">The full, or relative, path of the file to write to</param>
/// <param name="append">Whether new output should be appended to the old log file</param>
public FileSink(FileInfo file, bool append) { public FileSink(FileInfo file, bool append) {
var dir = file.Directory; var dir = file.Directory;
if (dir != null && !dir.Exists) if (dir != null && !dir.Exists)
@ -22,6 +34,10 @@ namespace ExtremelySimpleLogger {
this.writer.AutoFlush = true; this.writer.AutoFlush = true;
} }
/// <summary>
/// Logs the given message, which has already been formatted using <see cref="Sink.Formatter"/>.
/// </summary>
/// <param name="s">The message to log</param>
public override void Log(string s) { public override void Log(string s) {
this.writer.WriteLine(s); this.writer.WriteLine(s);
} }

View file

@ -1,11 +1,33 @@
namespace ExtremelySimpleLogger { namespace ExtremelySimpleLogger {
/// <summary>
/// A log level represents the importance of a message.
/// The higher the log level (the farther down in the list), the more important it is.
/// </summary>
public enum LogLevel { public enum LogLevel {
/// <summary>
/// The log level for very high-detail messages that are used for intensive debugging
/// </summary>
Trace, Trace,
/// <summary>
/// The log level for high-detail messages that are used for debugging
/// </summary>
Debug, Debug,
/// <summary>
/// The log level for informational messages
/// </summary>
Info, Info,
/// <summary>
/// The log level for warnings.
/// </summary>
Warn, Warn,
/// <summary>
/// The log level for errors.
/// </summary>
Error, Error,
/// <summary>
/// The log level for fatal exceptions, like when the program encounters a crash.
/// </summary>
Fatal Fatal
} }

View file

@ -2,17 +2,47 @@ using System;
using System.Collections.Generic; using System.Collections.Generic;
namespace ExtremelySimpleLogger { namespace ExtremelySimpleLogger {
/// <summary>
/// The implementation of a logger, which is a wrapper class around multiple logging <see cref="Sinks"/>.
///
/// To start logging with a logger, its <see cref="Sinks"/> need to be initialized.
/// There are two default implementations: <see cref="FileSink"/> and <see cref="ConsoleSink"/>.
/// </summary>
public class Logger { public class Logger {
/// <summary>
/// All of the <see cref="Sink"/> instances that this logger logs to.
/// By default, <see cref="FileSink"/> and <see cref="ConsoleSink"/> are available.
/// </summary>
public List<Sink> Sinks { get; set; } = new List<Sink>(); public List<Sink> Sinks { get; set; } = new List<Sink>();
/// <summary>
/// The minimum <see cref="LogLevel"/> that a message needs to have for this logger to log it.
/// </summary>
public LogLevel MinimumLevel { get; set; } = LogLevel.Trace; public LogLevel MinimumLevel { get; set; } = LogLevel.Trace;
/// <summary>
/// If this property is set to <code>false</code>, this logger will not log any messages.
/// </summary>
public bool IsEnabled { get; set; } = true; public bool IsEnabled { get; set; } = true;
/// <summary>
/// The name of this logger. This name is used in <see cref="Sink.FormatDefault"/> by default.
/// </summary>
public string Name { get; set; } public string Name { get; set; }
/// <summary>
/// Initializes a new logger with the given name.
/// Note that, for this logger to do anything, its <see cref="Sinks"/> need to be initialized.
/// </summary>
/// <param name="name">The logger's name</param>
public Logger(string name = "") { public Logger(string name = "") {
this.Name = name; this.Name = name;
} }
/// <summary>
/// Logs a message, passing it on to this logger's <see cref="Sinks"/>.
/// </summary>
/// <param name="level">The importance level of this message</param>
/// <param name="message">The message</param>
/// <param name="e">An optional exception whose stack trace will be appended to the message</param>
public void Log(LogLevel level, object message, Exception e = null) { public void Log(LogLevel level, object message, Exception e = null) {
if (!this.IsEnabled || level < this.MinimumLevel) if (!this.IsEnabled || level < this.MinimumLevel)
return; return;
@ -22,11 +52,43 @@ namespace ExtremelySimpleLogger {
} }
} }
/// <summary>
/// Logs a message with the <see cref="LogLevel.Trace"/> log level.
/// </summary>
/// <param name="message">The message</param>
public void Trace(object message) => this.Log(LogLevel.Trace, message); public void Trace(object message) => this.Log(LogLevel.Trace, message);
/// <summary>
/// Logs a message with the <see cref="LogLevel.Debug"/> log level.
/// </summary>
/// <param name="message">The message</param>
public void Debug(object message) => this.Log(LogLevel.Debug, message); public void Debug(object message) => this.Log(LogLevel.Debug, message);
/// <summary>
/// Logs a message with the <see cref="LogLevel.Info"/> log level.
/// </summary>
/// <param name="message">The message</param>
public void Info(object message) => this.Log(LogLevel.Info, message); public void Info(object message) => this.Log(LogLevel.Info, message);
/// <summary>
/// Logs a message with the <see cref="LogLevel.Warn"/> log level.
/// </summary>
/// <param name="message">The message</param>
/// <param name="e">An optional exception whose stack trace will be appended to the message</param>
public void Warn(object message, Exception e = null) => this.Log(LogLevel.Warn, message, e); public void Warn(object message, Exception e = null) => this.Log(LogLevel.Warn, message, e);
/// <summary>
/// Logs a message with the <see cref="LogLevel.Error"/> log level.
/// </summary>
/// <param name="message">The message</param>
/// <param name="e">An optional exception whose stack trace will be appended to the message</param>
public void Error(object message, Exception e = null) => this.Log(LogLevel.Error, message, e); public void Error(object message, Exception e = null) => this.Log(LogLevel.Error, message, e);
/// <summary>
/// Logs a message with the <see cref="LogLevel.Fatal"/> log level.
/// </summary>
/// <param name="message">The message</param>
/// <param name="e">An optional exception whose stack trace will be appended to the message</param>
public void Fatal(object message, Exception e = null) => this.Log(LogLevel.Fatal, message, e); public void Fatal(object message, Exception e = null) => this.Log(LogLevel.Fatal, message, e);
} }

View file

@ -2,21 +2,59 @@ using System;
using System.Text; using System.Text;
namespace ExtremelySimpleLogger { namespace ExtremelySimpleLogger {
/// <summary>
/// A sink is a way for log messages passed to a <see cref="Logger"/> to be processed in a certain way.
/// By default, <see cref="FileSink"/> and <see cref="ConsoleSink"/> are available.
/// </summary>
public abstract class Sink { public abstract class Sink {
/// <summary>
/// The minimum level that a log message needs to have for it to be processed by this sink.
/// </summary>
public LogLevel MinimumLevel { get; set; } = LogLevel.Info; public LogLevel MinimumLevel { get; set; } = LogLevel.Info;
/// <summary>
/// The <see cref="LogFormatter"/> with which this message should be formatted.
/// By default, <see cref="FormatDefault"/> is used.
/// </summary>
public LogFormatter Formatter { get; set; } public LogFormatter Formatter { get; set; }
/// <summary>
/// Initializes a new sink with the default settings.
/// </summary>
public Sink() { public Sink() {
this.Formatter = this.FormatDefault; this.Formatter = this.FormatDefault;
} }
public void Log(Logger logger, LogLevel level, object message, Exception e = null) { /// <summary>
/// Logs a message in the way specified by the sink's implementation.
/// </summary>
/// <param name="logger">The logger that the message was passed to</param>
/// <param name="level">The importance level of this message</param>
/// <param name="message">The message</param>
/// <param name="e">An optional exception whose stack trace will be appended to the message</param>
public virtual void Log(Logger logger, LogLevel level, object message, Exception e = null) {
this.Log(this.Formatter.Invoke(logger, level, message, e)); this.Log(this.Formatter.Invoke(logger, level, message, e));
} }
/// <summary>
/// Logs the given message, which has already been formatted using <see cref="Formatter"/>.
/// </summary>
/// <param name="s">The message to log</param>
public abstract void Log(string s); public abstract void Log(string s);
/// <summary>
/// The default formatter for logging messages.
/// By default, messages are laid out as follows:
/// <code>
/// [Date and time] [Logger name, if set] [Log level] Message
/// Exception, if set
/// </code>
/// </summary>
/// <param name="logger">The logger that the message was passed to</param>
/// <param name="level">The importance level of this message</param>
/// <param name="message">The message</param>
/// <param name="e">An optional exception whose stack trace will be appended to the message</param>
/// <returns>A formatted string to log</returns>
public virtual string FormatDefault(Logger logger, LogLevel level, object message, Exception e = null) { public virtual string FormatDefault(Logger logger, LogLevel level, object message, Exception e = null) {
var builder = new StringBuilder(); var builder = new StringBuilder();
// date // date
@ -34,6 +72,13 @@ namespace ExtremelySimpleLogger {
return builder.ToString(); return builder.ToString();
} }
/// <summary>
/// A delegate method used by <see cref="Sink.Formatter"/>.
/// </summary>
/// <param name="logger">The logger that the message was passed to</param>
/// <param name="level">The importance level of this message</param>
/// <param name="message">The message</param>
/// <param name="e">An optional exception whose stack trace will be appended to the message</param>
public delegate string LogFormatter(Logger logger, LogLevel level, object message, Exception e = null); public delegate string LogFormatter(Logger logger, LogLevel level, object message, Exception e = null);
} }

View file

@ -5,7 +5,7 @@ using ExtremelySimpleLogger;
namespace Sample { namespace Sample {
internal static class Program { internal static class Program {
private static void Main(string[] args) { private static void Main() {
var logger = new Logger { var logger = new Logger {
Name = "Test Logger", Name = "Test Logger",
Sinks = { Sinks = {
@ -23,7 +23,8 @@ namespace Sample {
logger.Error("An exception was thrown!", e); logger.Error("An exception was thrown!", e);
} }
logger.Log(LogLevel.Trace, "The program finished."); logger.Log(LogLevel.Trace, "This is a message that only the file sink will receive, since its minimum level is lower.");
logger.Log(LogLevel.Info, "The program finished.");
} }
} }