XML::Essex::ResultValues - How Essex manages result values
The first part of this material is also in L<XML::Essex>.
Essex is designed to Do The Right Thing for the vast majority of uses, so it manages result values automatically unless you take control. Below is a set of detailed rules for how it manages the result value for a filter's processing run, but the overview is:
Generators and Filters normally do not need to manage a result. The result from the next filter downstream's end_document handler will be returned automatically or an exception will be thrown if an incomplete document is sent downstream.
Handlers should either set a result value by calling
result()with it, or
returnthat result normally after the end_document is received.
Generators, filters and handlers should all die() on unexpected conditions and most error conditions (a FALSE or undefined result is not necessarily an error condition for a handler).
Generators and filters generally should not return a value of their own because this will surprise calling code which is expecting a return value of the type that the final SAX handler returns.
In order to free the coder from having to manage these end_document result values, Essex maintains a result value as an attribute of the filter and returns it if the filter has transmitted any events. If the filter has not transmitted any events, it must set this manually, or an exception is thrown.
In addition to the result value itself, Essex also tracks whether the value has been set or not. It is an error to exit normally from the filter without having set a result value. Setting the value to
undef is legal and legitimate, and is thus counted as having set it.
The result value is set or retrieved by the
result() function / method. The rules that Essex uses to manage this value are:
Before entering the main routine, sets
result()to undef and clear the
The result of each end_document
put()sends is captured by calling
result(), overwriting any previous values and setting the
On normal exit (via return), the last
result()set is returned and any
returned value is ignored. If no result has been set and no events were
put()downstream, then the
returned value is returned. If events were
put()downstream and no result was set, than an exception is thrown.
If the filter
die()s with an "end of XML input\n" exception, then the last
result()set is returned. If no result was set, then the exception is propogated.