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
AttributeAn attribute is a `(name, value)' tuple, which can be associated with a message.
ContextDescribes the context under which messages are converted into their textual representation.
IntAttribute
LStringAttribute
MsgA message is an object that can be converted to human readable text and presented to a program's user.
MsgAttribute
MsgListA 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.