NAME
XML::Essex::Filter::OutputMonitor - Enforce and cajol Essex output
SYNOPSIS
## Internal use onlyDESCRIPTION
Used by XML::Generator::Essex and XML::Filter::Essex instances to watch what's emitted downstream so as to capture result codes and notice incomplete documents.
Fills in partially filled end_element events and dies on mismatched end_element events. Fills in missing start_document and end_document events (unless auto_document_events is cleared).
NOTE: This could actually fill in missing end_element events, but I think that would lead to subtle bugs and would not help in many cases. It's safer to leave it out and we can always add this feature in the future, whereas taking it out would be difficult.
Returns a 1 from the end_document if no downstream handler is found.
Methods
- reset
-
Undefines all state variables.
- finish
-
Emits an end_doc if need be.
- start_document_seen
-
Sets/gets whether the start_document event was seen.
- end_document_seen
-
Sets/gets whether the end_document event was seen. Will be set if the downstream filter's
end_document()throws an exception. - end_document_result
-
Sets/gets the result returned by the downstream filter's
end_document()event handler. Set to undef if nothing else, for instance if the downstreamend_document()throws an exception. - end_document_result_has_been_set
-
Set if the end_document_result() has been called.
- auto_document_events
-
When set (the default), a start_document will be emitted before the first event unless it is start_document event and an end_document will be emitted after the last event unless an end_document was emitted. When cleared, this automation does not occur. The automatic end_document will not be emitted if an exception is thrown so as not to cause a stateful downstream handler to throw an additional exception.
This does allow well-balanced chunks of XML to be emitted, but there will be start_ and end_document events around them. Clear this member is you don't want to emit them, or if you want to emit them yourself.
This is not affected by reset().
LIMITATIONS
COPYRIGHT
Copyright 2002, R. Barrie Slaymaker, Jr., All Rights ReservedLICENSE
You may use this module under the terms of the BSD, Artistic, oir GPL licenses, any version.
AUTHOR
Barrie Slaymaker <barries@slaysys.com>