SUMMARY: MODULE | CLASS | TYPE | PROC | VAR | CONST | DETAIL: TYPE | PROC | VAR | CONST |
This module combines several concepts: messages, message attributes, message contexts, and message lists. This four aspects make this module a little bit involved, but at the core it is actually very simple.
The topics attributes and contexts are primarily of interest for modules that generate messages. They determine the content of the message, and how it can be translated into readable text. A user will mostly be in the position of message consumer, and will be handed filled in message objects. For a user, the typical operation will be to convert a message into descriptive text (see methods Msg.GetText and Msg.GetLText).
Message lists are a convenience feature for modules like parsers, which normally do not abort after a single error message. Usually, they try to continue their work after an error, looking for more problems and possibly emitting more error messages.
CharClass
Class List | |
Attribute | An attribute is a `(name, value)' tuple, which can be associated with a message. |
Context | Describes the context under which messages are converted into their textual representation. |
IntAttribute | |
LStringAttribute | |
Msg | A message is an object that can be converted to human readable text and presented to a program's user. |
MsgAttribute | |
MsgList | A message list is an often used contruct to collect several error messages that all refer to the same resource. |
StringAttribute |
Class Summary: Attribute [Detail] | |
+--Msg.Attribute An attribute is a `(name, value)' tuple, which can be associated with a message. When a message is tranlated into its readable version through the Msg.GetText function, the value part is first converted to some textual representation, and then inserted into the message's text. Within a message, an attribute is uniquely identified by its name. | |
Field Summary | |
name-: StringPtr The attribute name. | |
nextAttrib-: Attribute Points to the next attribute in the message's attribute list. | |
Constructor Summary | |
InitAttribute(Attribute, String) Initializes attribute object and sets its name. | |
Method Summary | |
ReplacementText(VAR LString) Converts attribute value into some textual representation. |
Class Summary: Context [Detail] | |
+--Msg.Context Describes the context under which messages are converted into their textual representation. Together, a message's context and its code identify the message type. As a debugging aid, an identification string can be associated with a context object (see procedure InitContext). | |
Field Summary | |
id-: StringPtr The textual id associated with the context instance. | |
Constructor Summary | |
InitContext(Context, String) The string argument id should describe the message context to the programmer. | |
Method Summary | |
GetTemplate(Msg, VAR LString) Returns a template string for the message msg. |
Class Summary: IntAttribute [Detail] | |
+---Msg.Attribute | +--Msg.IntAttribute | |
Field Summary | |
int-: LONGINT | |
Inherited Fields | |
From Msg.Attribute: | |
Constructor Summary | |
NewIntAttrib(String, LONGINT): IntAttribute | |
Method Summary | |
ReplacementText(VAR LString) Converts attribute value into some textual representation. | |
Inherited Methods | |
From Msg.Attribute: |
Class Summary: LStringAttribute [Detail] | |
+---Msg.Attribute | +--Msg.LStringAttribute | |
Field Summary | |
string-: LStringPtr | |
Inherited Fields | |
From Msg.Attribute: | |
Constructor Summary | |
NewLStringAttrib(String, LStringPtr): LStringAttribute | |
Method Summary | |
ReplacementText(VAR LString) Converts attribute value into some textual representation. | |
Inherited Methods | |
From Msg.Attribute: |
Class Summary: Msg [Detail] | |
+--Msg.Msg A message is an object that can be converted to human readable text and presented to a program's user. Within the OOC library, messages are used to store errors in the I/O modules, and the XML library uses them to create an error list when parsing an XML document. A message's type is uniquely identified by its context and its code. Using these two attributes, a message can be converted to text. The text may contain placeholders, which are filled by the textual representation of attribute values associated with the message. | |
Field Summary | |
attribList-: Attribute The list of attributes associated with the message. | |
code-: Code The message code. | |
context-: Context The context in which the message was created. | |
nextMsg-: Msg | |
prevMsg-: Msg Used by MsgList. | |
Constructor Summary | |
New(Context, Code): Msg Creates a new message object for the given context, using the specified message code. | |
Method Summary | |
GetAttribute(String): Attribute Returns the attribute name of the message object. | |
GetLText(VAR LString) Converts a message into a string. | |
GetText(VAR String) Like Msg.GetLText, but the message text is truncated to ISO-Latin1 characters. | |
SetAttribute(Attribute) Appends an attribute to the message's attribute list. | |
SetIntAttrib(String, LONGINT) | |
SetLStringAttrib(String, LStringPtr) | |
SetMsgAttrib(String, Msg) | |
SetStringAttrib(String, StringPtr) |
Class Summary: MsgAttribute [Detail] | |
+---Msg.Attribute | +--Msg.MsgAttribute | |
Field Summary | |
msg-: Msg | |
Inherited Fields | |
From Msg.Attribute: | |
Constructor Summary | |
NewMsgAttrib(String, Msg): MsgAttribute | |
Method Summary | |
ReplacementText(VAR LString) Converts attribute value into some textual representation. | |
Inherited Methods | |
From Msg.Attribute: |
Class Summary: MsgList [Detail] | |
+--Msg.MsgList A message list is an often used contruct to collect several error messages that all refer to the same resource. For example within a parser, multiple messages are collected before aborting processing and presenting all messages to the user. | |
Field Summary | |
msgCount-: LONGINT The number of messages in the list. | |
msgList-: Msg | |
Constructor Summary | |
InitMsgList(MsgList) | |
NewMsgList(): MsgList | |
Method Summary | |
Append(Msg) Appends the message msg to the list l. | |
AppendList(MsgList) Appends the messages of list source to l. |
Class Summary: StringAttribute [Detail] | |
+---Msg.Attribute | +--Msg.StringAttribute | |
Field Summary | |
string-: StringPtr | |
Inherited Fields | |
From Msg.Attribute: | |
Constructor Summary | |
NewStringAttrib(String, StringPtr): StringAttribute | |
Method Summary | |
ReplacementText(VAR LString) Converts attribute value into some textual representation. | |
Inherited Methods | |
From Msg.Attribute: |
Type Summary | |
Char = CHAR | |
Code = LONGINT Identifier for a message's content. | |
LChar = LONGCHAR | |
LString = ARRAY OF LChar | |
LStringPtr = POINTER TO LString | |
String = ARRAY OF Char | |
StringPtr = POINTER TO String |
Procedure Summary | |
GetLStringPtr(LString): LStringPtr Creates a copy of str on the heap and returns a pointer to it. | |
GetStringPtr(String): StringPtr Creates a copy of str on the heap and returns a pointer to it. |
Constant Summary | |
sizeAttrName Maximum length of the attribute name for InitAttribute, NewIntAttrib, NewStringAttrib, NewLStringAttrib, or NewMsgAttrib. | |
sizeAttrReplacement Maximum length of an attribute's replacement text. |
Class Detail: Attribute |
Field Detail |
FIELD name-: StringPtr
The attribute name. Note that it is restricted to sizeAttrName characters.
FIELD nextAttrib-: Attribute
Points to the next attribute in the message's attribute list.
Constructor Detail |
PROCEDURE InitAttribute(attr: Attribute; name: String)
Initializes attribute object and sets its name.
Method Detail |
PROCEDURE (attr: Attribute) ReplacementText(VAR text: LString)
Converts attribute value into some textual representation. The length of the resulting string must not exceed sizeAttrReplacement characters: Msg.GetLText calls this procedure with a text buffer of `sizeAttrReplacement+1' bytes.
Class Detail: Context |
Field Detail |
FIELD id-: StringPtr
The textual id associated with the context instance. See procedure InitContext.
Constructor Detail |
PROCEDURE InitContext(context: Context; id: String)
The string argument id should describe the message context to the programmer. It should not appear in output generated for a program's user, or at least it should not be necessary for a user to interpret ths string to understand the message. It is a good idea to use the module name of the context variable for the identifier. If this is not sufficient to identify the variable, add the variable name to the string.
Method Detail |
PROCEDURE (context: Context) GetTemplate(msg: Msg; VAR templ: LString)
Returns a template string for the message msg. The string may contain attribute references. Instead of the reference `${foo}', the procedure Msg.GetText will insert the textual representation of the attribute with the name `foo'. The special reference `${MSG_CONTEXT}' is replaced by the value of context.id, and `${MSG_CODE}' with msg.code.
The default implementation returns this string:
MSG_CONTEXT: ${MSG_CONTEXT} MSG_CODE: ${MSG_CODE} attribute_name: ${attribute_name}The last line is repeated for every attribute name. The lines are separated by CharClass.eol.
Pre-condition: msg is not NIL.
Class Detail: IntAttribute |
Field Detail |
FIELD int-: LONGINT
Constructor Detail |
PROCEDURE NewIntAttrib(name: String; value: LONGINT): IntAttribute
Method Detail |
PROCEDURE (attr: IntAttribute) ReplacementText(VAR text: LString)
Converts attribute value into some textual representation. The length of the resulting string must not exceed sizeAttrReplacement characters: Msg.GetLText calls this procedure with a text buffer of `sizeAttrReplacement+1' bytes.
[Description inherited from ReplacementText]
Redefines: ReplacementText
Class Detail: LStringAttribute |
Field Detail |
FIELD string-: LStringPtr
Constructor Detail |
PROCEDURE NewLStringAttrib(name: String; value: LStringPtr): LStringAttribute
Method Detail |
PROCEDURE (attr: LStringAttribute) ReplacementText(VAR text: LString)
Converts attribute value into some textual representation. The length of the resulting string must not exceed sizeAttrReplacement characters: Msg.GetLText calls this procedure with a text buffer of `sizeAttrReplacement+1' bytes.
[Description inherited from ReplacementText]
Redefines: ReplacementText
Class Detail: Msg |
Field Detail |
FIELD attribList-: Attribute
The list of attributes associated with the message. They are sorted by name.
FIELD code-: Code
The message code.
FIELD context-: Context
The context in which the message was created. Within a given context, the message code code uniquely identifies the message type.
FIELD nextMsg-: Msg
FIELD prevMsg-: Msg
Used by MsgList. Initialized to NIL.
Constructor Detail |
PROCEDURE New(context: Context; code: Code): Msg
Creates a new message object for the given context, using the specified message code. The message's attribute list is empty.
Method Detail |
PROCEDURE (msg: Msg) GetAttribute(name: String): Attribute
Returns the attribute name of the message object. If no such attribute exists, the value NIL is returned.
PROCEDURE (msg: Msg) GetLText(VAR text: LString)
Converts a message into a string. The basic format of the string is determined by calling msg.context.GetTemplate. Then the attributes are inserted into the template string: the placeholder string `${foo}' is replaced with the textual representation of attribute.
Pre-condition: `LEN(text) < 2^15'
Note: Behaviour is undefined if replacement text of attribute contains an attribute reference.
PROCEDURE (msg: Msg) GetText(VAR text: String)
Like Msg.GetLText, but the message text is truncated to ISO-Latin1 characters. All characters that are not part of ISO-Latin1 are mapped to question marks `?'.
PROCEDURE (msg: Msg) SetAttribute(attr: Attribute)
Appends an attribute to the message's attribute list. If an attribute of the same name exists already, it is replaced by the new one.
Pre-condition: `Length(attr.name^)<=sizeAttrName' and attr has not been attached to any other message.
PROCEDURE (msg: Msg) SetIntAttrib(name: String; value: LONGINT)
PROCEDURE (msg: Msg) SetLStringAttrib(name: String; value: LStringPtr)
PROCEDURE (msg: Msg) SetMsgAttrib(name: String; value: Msg)
PROCEDURE (msg: Msg) SetStringAttrib(name: String; value: StringPtr)
Class Detail: MsgAttribute |
Field Detail |
FIELD msg-: Msg
Constructor Detail |
PROCEDURE NewMsgAttrib(name: String; value: Msg): MsgAttribute
Method Detail |
PROCEDURE (attr: MsgAttribute) ReplacementText(VAR text: LString)
Converts attribute value into some textual representation. The length of the resulting string must not exceed sizeAttrReplacement characters: Msg.GetLText calls this procedure with a text buffer of `sizeAttrReplacement+1' bytes.
[Description inherited from ReplacementText]
Redefines: ReplacementText
Class Detail: MsgList |
Field Detail |
FIELD msgCount-: LONGINT
The number of messages in the list. An empty list has a msgCount of zero.
FIELD msgList-: Msg
Constructor Detail |
PROCEDURE InitMsgList(l: MsgList)
PROCEDURE NewMsgList(): MsgList
Method Detail |
PROCEDURE (l: MsgList) Append(msg: Msg)
Appends the message msg to the list l.
Pre-condition: msg is not part of another message list.
PROCEDURE (l: MsgList) AppendList(source: MsgList)
Appends the messages of list source to l. Afterwards, source is an empty list, and the elements of source can be found at the end of the list l.
Class Detail: StringAttribute |
Field Detail |
FIELD string-: StringPtr
Constructor Detail |
PROCEDURE NewStringAttrib(name: String; value: StringPtr): StringAttribute
Method Detail |
PROCEDURE (attr: StringAttribute) ReplacementText(VAR text: LString)
Converts attribute value into some textual representation. The length of the resulting string must not exceed sizeAttrReplacement characters: Msg.GetLText calls this procedure with a text buffer of `sizeAttrReplacement+1' bytes.
[Description inherited from ReplacementText]
Redefines: ReplacementText
Type Detail |
TYPE Char = CHAR
TYPE Code = LONGINT
Identifier for a message's content. Together with the message context, this value uniquely identifies the type of the message.
TYPE LChar = LONGCHAR
TYPE LString = ARRAY OF LChar
TYPE LStringPtr = POINTER TO LString
TYPE String = ARRAY OF Char
TYPE StringPtr = POINTER TO String
Procedure Detail |
PROCEDURE GetLStringPtr(str: LString): LStringPtr
Creates a copy of str on the heap and returns a pointer to it.
PROCEDURE GetStringPtr(str: String): StringPtr
Creates a copy of str on the heap and returns a pointer to it.
Constant Detail |
CONST sizeAttrName
Maximum length of the attribute name for InitAttribute, NewIntAttrib, NewStringAttrib, NewLStringAttrib, or NewMsgAttrib.
CONST sizeAttrReplacement
Maximum length of an attribute's replacement text.