# Section 8.10.3.11:
REPORTER

###### class REPORTER

#### Formal Types

The reporter is an 'opaque' type - indicated as a token.

types
SAME = REPORTER ;
REPORTER = token

This class is provided to report errors, warnings, etc to a program execution environment through the standard error channel. Where the execution environment supports a 'throwback' message system then errors and warnings are also sent to a throw-back channel for use by other applications which may be 'listening out' for such messages.

A fatal error may optionally be reported by raising an exception if required. This is always done as a string exception, created for the purpose by this object.

The features of this class are divided into sections for the purpose of simplification. First the creation routines, then the throwback features and, finally the error and warning message specifications are given in the last two sections.

### Creation

The three creation variants are provided for use where more or less control is desired over the default behaviour of the reporter. In all cases, however, the first argument is expected to be an array of messages in the form specified by the Sather string formatting class FMT - into which one or more values can be inserted as needed at run-time.

#### create

This first variant enables a using class to determine the cultural context in which errors/warnings shall be presented - as well as requesting throw-back facilities.

create | (
| format_strings : ARRAY{STR},
| library : LIBCHARS,
| do_throwback : BOOL
| ) : SAME

##### Formal Signature

create(msgs : seq of STR, lib : LIBCHARS, throw : BOOL) res : SAME

##### Pre-condition

pre len msgs > 0
and len msgs(1) > 0

##### Post-condition

Note that the can_throw predicate may be either true or false since it can only be set to true if the environment supports throw-back.

post error_free(res)
and warnings(res) = 0
and warning_not_error(res)
and not raise_error(res)
and max_index(res) = len msgs - 1

This routine creates a new reporter object to use the list of messages provided as the first argument - messages to be produced in the given culture and, if the third argument is true a request for throw-back facilities has been made.

#### create

Apart from not requesting throw-back, this creation variant is identical to the one above.

create | (
| format_strings : ARRAY{STR},
| library : LIBCHARS
| ) : SAME

##### Formal Signature

create2(msgs : seq of STR, lib : LIBCHARS) res : SAME

##### Pre-condition

pre len msgs > 0
and len msgs(1) > 0

##### Post-condition

Note for this variant that the can_throw predicate will always return false.

post error_free(res)
and warnings(res) = 0
and not can_throw(res)
and warning_not_error(res)
and not raise_error(res)
and max_index(res) = len msgs - 1

This routine creates a new reporter object to use the list of messages provided as the first argument - messages to be produced in the given culture.

#### create

This final creation variant uses the default culture specification and makes no throw-back request.

create | (
| format_strings : ARRAY{STR}
| ) : SAME

##### Formal Signature

create3(msgs : seq of STR) res : SAME

##### Pre-condition

pre len msgs > 0
and len msgs(1) > 0

##### Post-condition

Note for this variant that the can_throw predicate will always return false.

post error_free(res)
and warnings(res) = 0
and not can_throw(res)
and warning_not_error(res)
and not raise_error(res)
and max_index(res) = len msgs - 1

This routine creates a new reporter object to use the list of messages provided as the first argument to be produced in the default encoding and repertoire.

### Reader routines

There are three reader predicates for the reporter, permitting state enquiries to be made. They therefore have no pre-conditions and no post-conditions - and all return a Boolean value. They are :-

- throw_back_active - this is true if and only if throw-back is both possible and has been started.
- warning_not_error - this is true by default when creating a reporter. See warn_only and warn_as_errors.
- raise_error - this feature performs a similar function for errors. When it returns true then any error will raise an exception, otherwise merely give rise to an error message.

### Throw-back

Throw-back availability depends on the underlying execution environment providing a suitable messaging system. Each throwback message is accompanied by a file name and text line on which the error or warning is being reported. Throw-back action can only be undertaken if the first version of creation was used - requesting a throw-back message channel.

#### can_throw

If no throw-back request was made at reporter creation then this predicate will return false. If a request was made then this will only return true if the underlying execution environment supports the facility.

can_throw | : BOOL

##### Formal Signature

can_throw(self : SAME) res : BOOL

##### Pre-condition

Since this routine is a predicate, the pre-condition is vacuously true.

##### Post-condition

Since this routine is a predicate, the post-condition also is vacuously true.

This predicate returns true if and only if the execution environment supports throw-back messaging and use of that was requested when creating the reporter.

#### start_throw

Provided that can_throw is true then this routine registers the given file as being the subject of further throw-back messages until a further call to this routine.

start_throw | (
| fyle_ident : FILE_PATH
| ) : BOOL

##### Formal Signature

start_throw(self : SAME, path : FILE_PATH) res : BOOL

##### Pre-condition

Note that it is not necessary for the file named with the given path to either exist or be open at the time of issuing this request!

pre can_throw(self)

##### Post-condition

post throw_back_active(self)

This routine sets up the current source file corresponding to which errors and warnings are to be thrown; sets throw-back active if possible and returns true if and only if throw back is both possible and active.

#### done_throwing

This feature is provided to close the throw-back channel when throwing is complete for this reporter. It is expected to be used when reporting action has been completed.

done_throwing |

##### Formal Signature

done_throwing(self : SAME)

##### Pre-condition

Since the state of throwing will always be false after this routine, whether it is false or true is not relevant when invoking it. The pre-condition is therefore true.

pre true

##### Post-condition

post not throw_back_active(self)

This routine closes throwing for this reporter, after which no further throwing will (or can) be done.

### Warning Messages

The control and issue features for warning message is contained in this sub-section. The issue of a warning message may be done with or without an associated line number in the file being analaysed. Individual features are provided for both kinds of warning with 0, 1, 2 or 3 additional arguments.

#### warn_only

warn_only |

##### Formal Signature

warn_only(self : SAME)

##### Pre-condition

pre true

##### Post-condition

post warning_not_error(self)

This routine sets the warning regime for the reporter to treat warnings as being non-fatal.

#### warn_as_errors

This routine sets the warning regime to be the same as the error reporting regime.

warn_as_errors |

##### Formal Signature

warn_as_errors(self : SAME)

##### Pre-condition

pre true

##### Post-condition

post not warning_not_error(self)

This routine sets the warning regime for the reporter to treat warnings as errors are being treated - which depends on the current error reporting regime.

#### clear_warnings

This routine clears the warning count to zero.

clear_warnings |

##### Formal Signature

clear_warnings(self : SAME)

##### Pre-condition

pre true

##### Post-condition

post warnings(self) = 0

This routine resets the count of warnings so far encountered back to zero.

#### warnings

This routine returns the current count of warnings issued.

warnings | : CARD

##### Formal Signature

warnings(self : SAME) res : CARD

##### Pre-condition

pre true

##### Post-condition

post true

This routine returns the count of warnings issued since either creation or the most recent use of clear_warnings whichever is later.

#### warn

This is the name of a small group of four routines which, after the message index argument take 0, 1, 2 or 3 further arguments - to be used in composing a warning message according to the format string indexed. These arguments are represented in the signature as optional in the style of concrete syntax definitions - for brevity.

warn | (
| index : CARD [, arg1 : $FMT [, arg2 : $FMT [, arg3 : $FMT]]]
| )

##### Formal Signature

warn(self : SAME, index : CARD, args : seq of $FMT)

##### Pre-condition

pre len args <= 3 and index <= max_index(self)

##### Post-condition

post let msg : seq of CHAR be st len msg > 0 in ERR = ERR~ ^ msg

##### Exception

errs WARNING_FATAL : not warning_not_error(self)
and raise_error(self) -> exit

This routine composes a message from the formatting string indexed by the first argument with the values given converted to their string representation and inserted in this string indexed by the formatting mechanism by the order in which they occur as arguments to this routine.

#### line_warn

This is the name of a small group of four routines which, after the message index argument and line number argument take 0, 1, 2 or 3 further arguments - to be used in composing a warning message according to the format string indexed. These arguments are represented in the signature as optional in the style of concrete syntax definitions - for brevity.

line_warn | (
| index : CARD,
| line_number : CARD [, arg1 : $FMT [, arg2 : $FMT [, arg3 : $FMT]]]
| )

##### Formal Signature

line_warn(self : SAME, index : CARD, line_number : CARD, args : seq of $FMT)

##### Pre-condition

pre len args <= 3 and index <= max_index(self)

##### Post-condition

post let msg : seq of CHAR be st len msg > 0 in ERR = ERR~ ^ msg

##### Exception

errs WARNING_FATAL : not warning_not_error(self)
and raise_error(self) -> exit

This routine composes a message from the formatting string indexed by the first argument with the values given converted to their string representation and inserted in this string indexed by the formatting mechanism by the order in which they occur as arguments to this routine with the line number having the highest index.

### Error Messages

Error message features are similar to those for warnings above with five control features and then the two distinct variants of message feature (with and without line number).

#### fatal

This feature ensures that until any call of non_fatal any error message being produced will result in an exception being raised.

fatal |

##### Formal Signature

fatal(self : SAME)

##### Pre-condition

pre true

##### Post-condition

post raise_error(self)

This routine sets the reporter error regime to raise an exception when an error message is being created.

#### non_fatal

This feature resets the reporter error regime to its default.

non_fatal |

##### Formal Signature

fatal(self : SAME)

##### Pre-condition

pre true

##### Post-condition

post raise_error(self)

This routine sets the reporter error regime to raise an exception when an error message is being created.

#### clear_errors

This routine clears the error count to zero.

clear_errors |

##### Formal Signature

clear_errors(self : SAME)

##### Pre-condition

pre true

##### Post-condition

post errors(self) = 0

This routine resets the count of errors so far encountered back to zero.

#### errors

This routine returns the current count of errors issued.

errors | : CARD

##### Formal Signature

errors(self : SAME) res : CARD

##### Pre-condition

pre true

##### Post-condition

post true

This routine returns the count of errors issued since either creation or the most recent use of clear_warnings whichever is later.

#### error_free

error_free | : BOOL

##### Formal Signature

error_free(self : SAME)

##### Pre-condition

Since this is a predicate, the pre-condition is vacuously true.

##### Post-condition

post errors(self) = 0

This predicate returns true if and only if there have been no errors reported since the later of reporter creation and use of clear_errors.

#### error

This is the name of a small group of four routines which, after the message index argument take 0, 1, 2 or 3 further arguments - to be used in composing an error message according to the format string indexed. These arguments are represented in the signature as optional in the style of concrete syntax definitions - for brevity.

error | (
| index : CARD [, arg1 : $FMT [, arg2 : $FMT [, arg3 : $FMT]]]
| )

##### Formal Signature

error(self : SAME, index : CARD, args : seq of $FMT)

##### Pre-condition

pre len args <= 3 and index <= max_index(self)

##### Post-condition

post let msg : seq of CHAR be st len msg > 0 in ERR = ERR~ ^ msg

##### Exception

errs ERROR_FATAL : raise_error(self) -> exit

This routine composes an error message from the formatting string indexed by the first argument with the values given converted to their string representation and inserted in this string indexed by the formatting mechanism by the order in which they occur as arguments to this routine.

#### line_error

This is the name of a small group of four routines which, after the message index argument and line number argument take 0, 1, 2 or 3 further arguments - to be used in composing an error message according to the format string indexed. These arguments are represented in the signature as optional in the style of concrete syntax definitions - for brevity.

line_error | (
| index : CARD,
| line_number : CARD [, arg1 : $FMT [, arg2 : $FMT [, arg3 : $FMT]]]
| )

##### Formal Signature

line_error(self : SAME, index : CARD, line_number : CARD, args : seq of $FMT)

##### Pre-condition

pre len args <= 3 and index <= max_index(self)

##### Post-condition

post let msg : seq of CHAR be st len msg > 0 in ERR = ERR~ ^ msg

##### Exception

errs ERROR_FATAL : raise_error(self) -> exit

This routine composes an error message from the formatting string indexed by the first argument with the values given converted to their string representation and inserted in this string indexed by the formatting mechanism by the order in which they occur as arguments to this routine with the line number having the highest index.

| Language Index |  | Library Index |  | Input/Output Index

Comments or enquiries should be made to Keith Hopper. Page last modified: Tuesday, 21 November 2000. |