Generator of message output subsystem (gmsgs) v1.3

Contents

1. Introduction
2. Command line syntax
3. Message description file format
3.1. Structure
3.2. Message types
3.3. Message description
4. Output files
4.1. Message file
4.2. Eiffel source text
5. Message system classes
5.1. Class PROJECT_MESSAGE
5.1.1. Creation routine
5.1.2. Features
5.2. Class MESSAGE
5.2.1. Creation routine
5.2.2. Features
5.3. Class STANDARD_MESSAGES
5.3.1. Features
5.4. Classes FATAL_ERROR, ERROR, WARNING and INFORMATION
5.5. Building user application
5.6. Errors of the generator
6. Examples

1. Introduction

The utility allows to automatically generate source texts of classes which can be used to handle messages produced by the user program. The generator translates description file of output messages into the corresponding Eiffel sources along with prepared message file of the program.

The GUI version of the program is also provided: dm_gmsgs.

2. Command line syntax

Syntax

gmsgs.exe <description_file_1> .. <description_file_N>

Arguments

3. Message description file format

3.1. Structure

Message description file is a text file which consists of 2 parts. The first part is optional. It describes so called user message types. The second part of the file describes messages. The message description file should not be empty.

3.2. Message types

The message system supports different message types. They include predefined message types and user-defined message types. Predefined message types are always available for the message description. User-defined message types become available after their specification.

Message types affect the behaviour of message system. The table below shows the difference among message types:

Message type Has preamble Error count incremented Can be disabled Is added to list Raises exception Message name
information - - + - - -
warning + - + + - Warning
error + + + + - Error
fatal_error + - - - + Fatal error
<user_type> + - + + - <name>

Information messages look as a plain text. All other messages will be prepended by the special text which designates the message name and the message code in the following format:

<message_name> ' ' <message_code> " : " <message_text>

Message names for the predefined message types are shown in the table. Message codes are taken from the message description.

User can define his own message type in the first part of the message description file. The syntax is:

'<' <user_type> '>' '(' <message_name> ')'

Here <user_type> designates the name of the user-defined type, <message_name> is the message name which will be used while displaying the message. <user_type> cannot be equal to one of the predefined type names and it should satisfy to the rules of Eiffel identifiers.

Example.

The following lines would add three new message types (warning_level_1, warning_level_2 and bug):

    <warning_level_1> (Warning)
    <warning_level_2> (Warning)
    <bug>             (Bug in the program)

3.3. Message description

Syntax:

'{'<message_code>'}'
'<'<message_name>'>'
'@' <message_type> ':'
'"'<message_text>'"'

where

<message_code> an arbitrary string which designates the message code; all message codes should be different
<message_name> an Eiffel identifier of the message; two or more message descriptions cannot have the same name
<message_type> a type of the message (see "Message types" for details)
<message_text> the text of the message which cannot be extended to several lines

A message text may have parameters. They are designated as %<parameter_number>, where <parameter_number> is an integer constant. On output the parameters are replaced by the corresponding values specified during the message creation. Character '%' should be written as "%%". All standard Eiffel special character encodings can be used in the message text, except %/NNN/ (e.g., %N, %T, %").

4. Output files

4.1. Message file

As a result of message description file translation, two output files are generated: a message file and an Eiffel source. The message file gets the name of the message description file with the extention changed into ".msg". The message file is a text file, every line of which has the following format:

'{'<message_code>'}' '"'<message_text>'"'

where fields <message_code> and <message_text> are taken from the message description.

The message file can be edited using the following rules:

  1. One line corresponds to one message.
  2. The order of the messages in the file should not be changed.
  3. Messages should not be removed from or added to the file.
  4. <message_code> should not be changed.

4.2. Eiffel source text

The utility produces the Eiffel source text for the class MESSAGE_CODE in the file "msg_code.e". The class has two sets of constants which may be used to handle messages:

message types
these are "information", "warning", "error", or "fatal_error" for predefined types, or user-defined names for user-defined types
message identifiers
these are taken from the message description file; message identifier is used to reference an appropriate message

5. Message system classes

5.1. Class PROJECT_MESSAGE

This is a generic class PROJECT_MESSAGE [ G -> MESSAGE ]. It allows to manipulate messages including their creation, displaying, etc.

5.1.1. Creation routine

	make (msg_file_name: STRING)
		-- Initialized message system and attaches it to the specified
		-- message file

5.1.2. Features

	file_is_actual: BOOLEAN
		-- True if the message file is actual; False otherwise

	message (message_id: INTEGER; message_parameters: ARRAY [ANY])
		-- Creates a new message with the specified message identifier and
		-- the given parameters Then calls feature "add"

	add (m: G)
		-- Adds the specified message to the message pool
		-- Calls feature "display_message" if echo is enabled
		-- Calls feature "do_action" from the class MESSAGE

	messages: ARRAY [G]
		-- Message pool

	messages_count: INTEGER
		-- Total number of messages in the message pool

	errors_count: INTEGER
		-- Total number of the error messages

	set_echo (on: BOOLEAN)
		-- Enables (on=True) or disables (on=False) echo

	enable (message_id: INTEGER)
		-- Enables the messages with the given identifier

	disable (message_id: INTEGER)
		-- Disables the messages with the given identifier

	disable_type (message_type: CHARACTER)
		-- Disables all messages of the specified type

	enable_type (message_type: CHARACTER)
		-- Enables all messages of the specified type

	has_messages_for_print: BOOLEAN
		-- True if the message pool has enabled messages

	display (header, footer: STRING)
		-- Displays all enabled messages (using the feature
		-- "display_message")
		-- The listing begins with the text "header" and ends with the text
		-- "footer"

	display_message (m: G)
		-- Displays the specified message

5.2. Class MESSAGE

This class represents the message generated by the message system.

5.2.1. Creation routine

	make (message_id: INTEGER; parameters: ARRAY [ANY])
		-- Creates a new message instance by the specified message
		-- identifier using the given message parameters

5.2.2. Features

	text: ARRAY [ANY]
		-- Message parameters that replace parameters in the message text

	name: INTEGER
		-- Message identifier

	type: CHARACTER
		-- Message type

	message_name: STRING
		-- Name of the message type

	message_code: STRING
		-- Message code

	is_error: BOOLEAN
		-- True if this is an error message

	do_action
		-- The feature which is called when the message is added to the
		-- message pool; by default it has an empty body

	to_add: BOOLEAN
		-- True means that this message will be added into the message
		-- pool
		-- False means that this message will be just displayed but not
		-- added to the message pool

	out: STRING
		-- Formatted message text with a proper preamble and substituted
		-- parameters

5.3. Class STANDARD_MESSAGES

This class inherits from the class PROJECT_MESSAGE and can be used in most applications to handle messages.

5.3.1. Features

	set_output_mode (file_name: STRING; mode: CHARACTER)
		-- Sets the mode to output messages accordingly to the parameter
		-- "mode":
		--     's' - output goes to the console
		--     'f' - output goes to the file named "file_name"
		--     'b' - output goes to both the console and the file
		--     'n' - no output

	fatal_error (message_id: INTEGER; parameters: ARRAY [ANY])
		-- Creates a fatal error message (represented by the class
		-- FATAL_ERROR) with the specified identifier and parameters
		-- Calls the feature "do_action" for the created object

	error (message_id: INTEGER; parameters: ARRAY [ANY])
		-- Creates an error message (represented by the class ERROR) with the
		-- specified identifier and parameters
		-- Calls the feature "add"

	warning (message_id: INTEGER; parameters: ARRAY [ANY])
		-- Creates a warning message (represented by the class WARNING) with
		-- the specified identifier and parameters
		-- Calls the feature "add"

	information (message_id: INTEGER; parameters: ARRAY [ANY])
		-- Creates an information message (represented by the class WARNING)
		-- with the specified identifier and parameters
		-- Calls the feature "display_message"

	width: INTEGER
		-- Maximal width for wrapping the long messages into several lines
		-- on output

	set_width (w: INTEGER)
		-- Sets the "width" to the given value

	display_message (m: G)
		-- Displays the message accordingly to the displaying mode

5.4. Classes FATAL_ERROR, ERROR, WARNING and INFORMATION

All the classes FATAL_ERROR, ERROR, WARNING and INFORMATION inherit from the class MESSAGE. Their differences are shown in the table below (see "Class MESSAGE" for details):

MESSAGE FATAL_ERROR ERROR WARNING INFORMATION
to_add False - - False
is_error - True - -
do_action exception - - -

5.5. Building user application

In order to use the generated message handling system, it's necessary to put the generated file "msg_code.e" into the directory which contains a cluster from your project.

5.6. Errors of the generator

The generator may produce the following errors:

MT1 Can not open the file 'filename'
MT2 Symbol 'symbol' is expected at position 'line:pos' in messages description file
MT3 Message code is expected at position 'line:pos'
MT4 Message identifier is expected at position 'line:pos'
MT5 Message type is expected at position 'line:pos'
MT6 The message identifier is declared twice
MT7 The message code is declared twice
MT8 The message type is declared twice
MT9 User message type name is expected at position 'line:pos'
MT10 User message type declaration expected at position 'line:pos'
MT11 Unknown message type
MT12 Message identifier is not valid Eiffel identifier
MT13 User message type is declared as not valid Eiffel identifier
MT14 User message type is one of the predefined message types

6. Examples

See "Utility Arg_Msg" for details.


Copyright © Object Tools -- info@object-tools.com
Last updated: 2005/02/02 11:51:35