NAME

XML::Essex::ResultValues - How Essex manages result values

DESCRIPTION

    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 return that 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.

Details

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:

1. Before entering the main routine, sets result() to undef and clear the result_has_been_set flag.
2. The result of each end_document put() sends is captured by calling result(), overwriting any previous values and setting the result_has_been_set_flag.
3. 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.
4. 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.