# Msg

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.

### Import List

        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: name, nextAttrib
Constructor Summary
NewIntAttrib(String, LONGINT): IntAttribute
Method Summary
ReplacementText(VAR LString) Converts attribute value into some textual representation.
Inherited Methods
From Msg.Attribute: ReplacementText

Class Summary: LStringAttribute [Detail]

      +---Msg.Attribute
           |
           +--Msg.LStringAttribute

Field Summary
string-: LStringPtr
Inherited Fields
From Msg.Attribute: name, nextAttrib
Constructor Summary
NewLStringAttrib(String, LStringPtr): LStringAttribute
Method Summary
ReplacementText(VAR LString) Converts attribute value into some textual representation.
Inherited Methods
From Msg.Attribute: ReplacementText

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: name, nextAttrib
Constructor Summary
NewMsgAttrib(String, Msg): MsgAttribute
Method Summary
ReplacementText(VAR LString) Converts attribute value into some textual representation.
Inherited Methods
From Msg.Attribute: ReplacementText

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: name, nextAttrib
Constructor Summary
NewStringAttrib(String, StringPtr): StringAttribute
Method Summary
ReplacementText(VAR LString) Converts attribute value into some textual representation.
Inherited Methods
From Msg.Attribute: ReplacementText

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

### name

    FIELD name-: StringPtr

> The attribute name. Note that it is restricted to sizeAttrName characters.

### nextAttrib

    FIELD nextAttrib-: Attribute

> Points to the next attribute in the message's attribute list.

Constructor Detail

### InitAttribute

    PROCEDURE InitAttribute(attr: Attribute;
                            name: String)

> Initializes attribute object and sets its name.

Method Detail

### ReplacementText

    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

### id

    FIELD id-: StringPtr

> The textual id associated with the context instance. See procedure InitContext.

Constructor Detail

### InitContext

    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

### GetTemplate

    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

### int

    FIELD int-: LONGINT

Constructor Detail

### NewIntAttrib

    PROCEDURE NewIntAttrib(name: String;
                           value: LONGINT): IntAttribute

Method Detail

### ReplacementText

    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

### string

    FIELD string-: LStringPtr

Constructor Detail

### NewLStringAttrib

    PROCEDURE NewLStringAttrib(name: String;
                               value: LStringPtr): LStringAttribute

Method Detail

### ReplacementText

    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

### attribList

    FIELD attribList-: Attribute

> The list of attributes associated with the message. They are sorted by name.

### code

    FIELD code-: Code

> The message code.

### context

    FIELD context-: Context

> The context in which the message was created. Within a given context, the message code code uniquely identifies the message type.

### nextMsg

    FIELD nextMsg-: Msg

### prevMsg

    FIELD prevMsg-: Msg

> Used by MsgList. Initialized to NIL.

Constructor Detail

### New

    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

### GetAttribute

    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.

### GetLText

    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.

### GetText

    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 ``?`'.

### SetAttribute

    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.

### SetIntAttrib

    PROCEDURE (msg: Msg) SetIntAttrib(name: String;
                           value: LONGINT)

### SetLStringAttrib

    PROCEDURE (msg: Msg) SetLStringAttrib(name: String;
                               value: LStringPtr)

### SetMsgAttrib

    PROCEDURE (msg: Msg) SetMsgAttrib(name: String;
                           value: Msg)

### SetStringAttrib

    PROCEDURE (msg: Msg) SetStringAttrib(name: String;
                              value: StringPtr)

Class Detail: MsgAttribute

Field Detail

### msg

    FIELD msg-: Msg

Constructor Detail

### NewMsgAttrib

    PROCEDURE NewMsgAttrib(name: String;
                           value: Msg): MsgAttribute

Method Detail

### ReplacementText

    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

### msgCount

    FIELD msgCount-: LONGINT

> The number of messages in the list. An empty list has a msgCount of zero.

### msgList

    FIELD msgList-: Msg

Constructor Detail

### InitMsgList

    PROCEDURE InitMsgList(l: MsgList)

### NewMsgList

    PROCEDURE NewMsgList(): MsgList

Method Detail

### Append

    PROCEDURE (l: MsgList) Append(msg: Msg)

> Appends the message msg to the list l.

> Pre-condition: msg is not part of another message list.

### AppendList

    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

### string

    FIELD string-: StringPtr

Constructor Detail

### NewStringAttrib

    PROCEDURE NewStringAttrib(name: String;
                              value: StringPtr): StringAttribute

Method Detail

### ReplacementText

    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

### Char

    TYPE Char = CHAR

### Code

    TYPE Code = LONGINT

> Identifier for a message's content. Together with the message context, this value uniquely identifies the type of the message.

### LChar

    TYPE LChar = LONGCHAR

### LString

    TYPE LString = ARRAY OF LChar

### LStringPtr

    TYPE LStringPtr = POINTER TO LString

### String

    TYPE String = ARRAY OF Char

### StringPtr

    TYPE StringPtr = POINTER TO String

Procedure Detail

### GetLStringPtr

    PROCEDURE GetLStringPtr(str: LString): LStringPtr

> Creates a copy of str on the heap and returns a pointer to it.

### GetStringPtr

    PROCEDURE GetStringPtr(str: String): StringPtr

> Creates a copy of str on the heap and returns a pointer to it.

Constant Detail

### sizeAttrName

    CONST sizeAttrName

> Maximum length of the attribute name for InitAttribute, NewIntAttrib, NewStringAttrib, NewLStringAttrib, or NewMsgAttrib.

### sizeAttrReplacement

    CONST sizeAttrReplacement

> Maximum length of an attribute's replacement text.