lib/sax/error_handler.nit

   1 # This file is part of NIT ( http://www.nitlanguage.org ).
   2 #
   3 # This file is free software, which comes along with NIT. This software is
   4 # distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
   5 # without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
   6 # PARTICULAR PURPOSE. You can modify it is you want, provided this header
   7 # is kept unaltered, and a notification of the changes is added.
   8 # You are allowed to redistribute it and sell it, alone or is a part of
   9 # another product.
  10
  11 # Basic interface for SAX error handlers.
  12 module sax::error_handler
  13
  14 import sax_parse_exception
  15
  16 # Basic interface for SAX error handlers.
  17 #
  18 # If a SAX application needs to implement customized error
  19 # handling, it must implement this interface and then register an
  20 # instance with the XML reader using the `sax::XMLReader.error_handler
  21 # property. The parser will then report all errors and warnings
  22 # through this interface.
  23 #
  24 # **WARNING:** If an application does *not* register an `ErrorHandler`,
  25 # XML parsing errors will go unreported and bizarre behaviour may result.
  26 #
  27 # For XML processing errors, a SAX driver must use this interface
  28 # instead of throwing an exception: it is up to the application
  29 # to decide whether to throw an exception for different types of
  30 # errors and warnings. Note, however, that there is no requirement that
  31 # the parser continue to provide useful information after a call to
  32 # `fatal_error` (in other words, a SAX driver class
  33 # could catch an exception and report a `fatal_error`).
  34 #
  35 # Note: The original documentation comes from [SAX 2.0](http://www.saxproject.org).
  36 #
  37 # SEE: `sax::XMLReader.error_handler`
  38 abstract class ErrorHandler
  39
  40         # Receive notification of a warning.
  41         #
  42         # SAX parsers will use this method to report conditions that
  43         # are not errors or fatal errors as defined by the XML 1.0
  44         # recommendation. The default behaviour is to take no action.
  45         #
  46         # The SAX parser must continue to provide normal parsing events
  47         # after invoking this method: it should still be possible for the
  48         # application to process the document through to the end.
  49         #
  50         # Filters may use this method to report other, non-XML warnings
  51         # as well.
  52         #
  53         # Parameter:
  54         #
  55         # * `exception`: warning information encapsulated in a SAX parse
  56         # exception.
  57         fun warning(exception: SAXParseException) do end
  58
  59         # Receive notification of a recoverable error.
  60         #
  61         # This corresponds to the definition of "error" in section 1.2
  62         # of the W3C XML 1.0 Recommendation. For example, a validating
  63         # parser would use this callback to report the violation of a
  64         # validity constraint. The default behaviour is to take no
  65         # action.
  66         #
  67         # The SAX parser must continue to provide normal parsing events
  68         # after invoking this method: it should still be possible for the
  69         # application to process the document through to the end. If the
  70         # application cannot do so, then the parser should report a fatal
  71         # error even if the XML 1.0 recommendation does not require it to
  72         # do so.
  73         #
  74         # Filters may use this method to report other, non-XML errors
  75         # as well.
  76         #
  77         # Parameter:
  78         #
  79         # * `exception`: error information encapsulated in a SAX parse
  80         # exception.
  81         fun error(exception: SAXParseException) do end
  82
  83         # Receive notification of a non-recoverable error.
  84         #
  85         # This corresponds to the definition of "fatal error" in
  86         # section 1.2 of the W3C XML 1.0 Recommendation. For example, a
  87         # parser would use this callback to report the violation of a
  88         # well-formedness constraint.
  89         #
  90         # The application must assume that the document is unusable
  91         # after the parser has invoked this method, and should continue
  92         # (if at all) only for the sake of collecting additional error
  93         # messages: in fact, SAX parsers are free to stop reporting any
  94         # other events once this method has been invoked.
  95         #
  96         # Parameter:
  97         #
  98         # * `exception`: error information encapsulated in a SAX parse
  99         # exception.
 100         fun fatal_error(exception: SAXParseException) do
 101                 exception.throw
 102         end
 103 end