![]() |
Section 8.10.3.11: |
![]() |
The reporter is an 'opaque' type - indicated as a 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.
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.
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.
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.
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.
Apart from not requesting throw-back, this creation variant is identical to the one above.
Note for this variant that the can_throw predicate will always return false.
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.
This final creation variant uses the default culture specification and makes no throw-back request.
Note for this variant that the can_throw predicate will always return false.
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.
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 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.
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.
Since this routine is a predicate, the pre-condition is vacuously true.
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.
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 |
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!
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.
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.
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.
This routine closes throwing for this reporter, after which no further throwing will (or can) be done.
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.
This routine sets the warning regime for the reporter to treat warnings as being non-fatal.
This routine sets the warning regime to be the same as the error reporting regime.
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.
This routine clears the warning count to zero.
This routine resets the count of warnings so far encountered back to zero.
This routine returns the current count of warnings issued.
This routine returns the count of warnings issued since either creation or the most recent use of clear_warnings whichever is later.
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.
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.
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.
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 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).
This feature ensures that until any call of non_fatal any error message being produced will result in an exception being raised.
This routine sets the reporter error regime to raise an exception when an error message is being created.
This feature resets the reporter error regime to its default.
This routine sets the reporter error regime to raise an exception when an error message is being created.
This routine clears the error count to zero.
This routine resets the count of errors so far encountered back to zero.
This routine returns the current count of errors issued.
This routine returns the count of errors issued since either creation or the most recent use of clear_warnings whichever is later.
Since this is a predicate, the pre-condition is vacuously true.
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.
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.
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.
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.
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. |
![]() |