Enhanced C#
Language of your choice: library documentation
Loyc.IMessageSink< in in TSeverity, in in TContext > Interface Template Reference

A general-purpose interface for a class that accepts formatted messages with context information. More...


Source file:
Inheritance diagram for Loyc.IMessageSink< in in TSeverity, in in TContext >:
LeMP.IMacroContext Loyc.ConsoleMessageSink Loyc.MessageFilter Loyc.MessageHolder Loyc.MessageSinkFromDelegate Loyc.MessageSplitter Loyc.NullMessageSink Loyc.SeverityMessageFilter Loyc.TraceMessageSink

Remarks

A general-purpose interface for a class that accepts formatted messages with context information.

IMessageSink is used for dependency injection of a target for formatted messages; it could be used for log messages, compiler error messages, or to report the progress of a process, for instance.

It is typical to use IMessageSink without type parameters.

Since .NET does not allow static members in an interface, the static members can be found in MessageSink.

Each message has a Severity. For message sinks that are used as loggers, this should be one of the following logging levels, listed in order of importance: Fatal, Error, Warning, Note, Debug, Verbose.

For message sinks that are used for compiler messages, the standard levels are: Fatal, Error, Warning, Note, Detail. "Detail" provides more information about a previously-printed message, while "Note" is intended for independent messages that are less severe than warnings (e.g. lints). Some compilers may distiguish "soft" errors (which do not prevent the program from starting) from "critical" errors (which do). In that case, Error may represent such a "soft" error and Critical may represent a "hard" error. Fatal, in contrast, represents an error that causes the compiler to halt immediately.

The message sink itself should perform localization, which can be done with Localize.Localized.

Only a single Write() method is truly needed (Write(Severity, object, string, object[])), but for efficiency reasons the interface contains two other writers. It is expected to be fairly common that a message sink will drop some or all messages without printing them, e.g. if a message sink is used for logging, verbose messages might be "off" by default. It would be wasteful to actually localize and format a message if the message will not actually be printed, and it would also be wasteful to create an array of objects to hold the arguments if they are just going to be discarded. With that in mind, since most formatting requests only need a couple of arguments, there is an overload of Write() that accepts up to two arguments without the need to package them into an array, and there is an overload that takes no formatting arguments (this indicates that parameter substitution is not required and should not be attempted.)

In addition, the caller can call IsEnabled(Severity) to avoid doing any work required to prepare a message for printing when a certain category of output is disabled.

Template Parameters
TSeverityThe type of the first parameter to Write, which is used to indicate the "kind" of message being logged. Typically this parameter is Severity, which includes values like Note, Warning and Error.
TContextThe type of the second parameer to Write, which indicates where the error occurs. If the message relates to a text file or source code, the location is typically indicated with an object of type Loyc.Syntax.SourceRange or Loyc.Syntax.LNode.
See also
MessageSink, ConsoleMessageSink, TraceMessageSink, NullMessageSink, MessageFilter, MessageHolder, MessageSplitter, IHasLocation