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:
result()with it, or
returnthat result normally after the end_document is received.
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:
result()to undef and clear the
put()sends is captured by calling
result(), overwriting any previous values and setting the
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.
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.