Sather Home Page

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

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.
Produced with Amaya