Loyc.IMessageSink Interface Reference

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

---

Source file:

• /Core/Loyc.Essentials/Utilities/IMessageSink.cs

Inheritance diagram for Loyc.IMessageSink:

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.

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

Each message has a "type" Symbol which indicates the type of message being printed. 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 represents 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.

See also

MessageSink, ConsoleMessageSink, TraceMessageSink, NullMessageSink, MessageFilter, MessageHolder, MessageSplitter

Public Member Functions
void	Write (Severity type, object context, string format)
	Writes a message to the target that this object represents. More...
void	Write (Severity type, object context, string format, object arg0, object arg1=null)
void	Write (Severity type, object context, string format, params object[] args)
bool	IsEnabled (Severity type)
	Returns true if messages of the specified type will actually be printed, or false if Write(type, ...) is a no-op. More...

Member Function Documentation

bool Loyc.IMessageSink.IsEnabled

(

Severity

type

)

Returns true if messages of the specified type will actually be printed, or false if Write(type, ...) is a no-op.

Implemented in Loyc.MessageSinkFromDelegate, Loyc.MessageSplitter, Loyc.SeverityMessageFilter, Loyc.MessageFilter, Loyc.MessageHolder, Loyc.TraceMessageSink, Loyc.NullMessageSink, and Loyc.ConsoleMessageSink.

void Loyc.IMessageSink.Write	(	Severity	type,
		object	context,
		string	format
	)

Writes a message to the target that this object represents.

Parameters

type	Severity or importance of the message; widely-used types include Error, Warning, Note, Debug, and Verbose. The special type Detail is intended to provide more information about a previous message.
context	An object that the message is related to, or that represents the location that the message applies to. The message sink may try to convert this object to a string and include it in its output. See also MessageSink.LocationString().
format	A message to display. If there are additional arguments, placeholders such as {0} and {1} refer to these arguments.

Implemented in Loyc.MessageSinkFromDelegate, Loyc.MessageSplitter, Loyc.SeverityMessageFilter, Loyc.MessageFilter, Loyc.MessageHolder, Loyc.TraceMessageSink, Loyc.NullMessageSink, and Loyc.ConsoleMessageSink.

Referenced by Loyc.LLPG.Macros.LLLPG_parser().