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
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.
Syntax
gmsgs.exe <description_file_1> .. <description_file_N>
Arguments
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.
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)
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, %").
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:
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:
This is a generic class PROJECT_MESSAGE [ G -> MESSAGE ]. It allows to manipulate messages including their creation, displaying, etc.
make (msg_file_name: STRING) -- Initialized message system and attaches it to the specified -- message file
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
This class represents the message generated by the message system.
make (message_id: INTEGER; parameters: ARRAY [ANY]) -- Creates a new message instance by the specified message -- identifier using the given message parameters
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
This class inherits from the class PROJECT_MESSAGE and can be used in most applications to handle messages.
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
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 | - | - | - |
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.
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 |
See "Utility Arg_Msg" for details.