Enhanced C#
Language of your choice: library documentation
Public Member Functions | List of all members
Loyc.IMessageSink< 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 TContext >:
LeMP.IMacroContext Loyc.ConsoleMessageSink Loyc.MessageFilter Loyc.MessageHolder Loyc.MessageMulticaster< TContext > Loyc.MessageSinkFromDelegate Loyc.MessageSinkWithContext< TContext > Loyc.NullMessageSink Loyc.SeverityMessageFilter< TContext > Loyc.TraceMessageSink

Remarks

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

Alias for IMessageSink<object>.

Helpful article: http://core.loyc.net/essentials/messagesink.html

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. Frequently-used message sinks include ConsoleMessageSink.Value, TraceMessageSink.Value, and MessageHolder.

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.

If the message sink may produce messages that users will see, the message sink itself should perform localization using Localize.Localized(string, object[]).

Only a single Write() method is truly needed (Write(Severity, TContext, 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
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.ISourceRange or Loyc.Syntax.ILNode.
See also
MessageSink, ConsoleMessageSink, TraceMessageSink, NullMessageSink, MessageFilter, MessageHolder, MessageMulticaster, IHasLocation
See also
IMessageSink<TContext>

Public Member Functions

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

Member Function Documentation

◆ IsEnabled()

bool Loyc.IMessageSink< in in TContext >.IsEnabled ( Severity  level)

◆ Write()

void Loyc.IMessageSink< in in TContext >.Write ( Severity  level,
TContext  context,
[Localizable] string  format 
)

Writes a message to the target that this object represents.

Parameters
levelSeverity 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.
contextAn 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.ContextToString().
formatA message to display. If there are additional arguments, placeholders such as {0} and {1} refer to these arguments.

Implemented in Loyc.MessageSinkWithContext< TContext >, Loyc.MessageMulticaster< TContext >, and Loyc.SeverityMessageFilter< TContext >.

Referenced by Loyc.Syntax.BaseParser< Token >.Error(), Loyc.Syntax.Lexing.BaseLexer< CharSrc >.Error(), Loyc.Syntax.Lexing.IndentTokenGenerator< Token >.IndentChangedUnexpectedly(), Loyc.Ecs.Parser.EcsPreprocessor.NextToken(), Loyc.SeverityMessageFilter< TContext >.Write(), and Loyc.MessageSinkWithContext< TContext >.Write().