A general-purpose interface for a class that accepts formatted messages with context information. More...
Source file:
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
-
TContext The 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 | ) |
Returns true if messages of the specified type will actually be printed, or false if Write(type, ...) has no effect.
Implemented in Loyc.TraceMessageSink, Loyc.MessageSinkWithContext< TContext >, Loyc.MessageSinkFromDelegate, Loyc.MessageMulticaster< TContext >, Loyc.NullMessageSink, Loyc.MessageFilter, Loyc.ConsoleMessageSink, Loyc.SeverityMessageFilter< TContext >, and Loyc.MessageHolder.
Referenced by Loyc.SeverityMessageFilter< TContext >.IsEnabled(), Loyc.MessageFilter.IsEnabled(), and Loyc.MessageSinkWithContext< TContext >.IsEnabled().
◆ 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
-
level 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.ContextToString(). format A 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().
