Barrie Slaymaker > XML-Filter-Essex-0.01 > XML::Essex::ResultValues

Download:
XML-Filter-Essex-0.01.tar.gz

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Source  

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:

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.
syntax highlighting: