NAME

XML::Essex::Base - class for Essex SAX components

SYNOPSIS

## Not for external use.

DESCRIPTION

All Essex generators, filters and handlers must inherit from this class among others. This class provides methods common to all three and specialized export semantics so that exports may be inherited from base classes.

METHODS

new

Creates and initializes an instance.

import

Uses @EXPORT and @EXPORT_OK arrays like Exporter.pm, but implements inheritence on it. Understands the meaning of the tags ":all" and ":default", which are hardcoded (%EXPORT_TAGS is ignored thus far), but does not emulate Exporter's other, rarely used syntaxes.

main

The main routine. Overload this or pass in a code ref to new( Main = \&foo )> or set_main( \&foo ) to set this.

set_main

Sets the main routines to a code reference.

reset

Called before the main routine is called.

finish

Called after the main routine is called.

execute

Prepares the runtime environment, calls <$self-main( @_ )>>, cleans up afterwards and runs sanity checks.

This is called automatically in filters and handlers, must be called manually in generators.

Calls reset() before and finish() after main().

namespace_map

aka: ns_map

$self->ns_map(
    $ns1 => $prefix1,
    $ns2 => $prefix2,
    ...
);

Creates a new set of mappings in addition to any that are already in effect. If a namespace is mapped to multiple prefixes, the last one created is used. The mappings stay in effect until the map objected referred to by $map is destroyed.

NOTE: the namespace prefixes from the source document override the namespace prefixes set here when events are transmitted downstream. This is so that namespace prefixes are not altered arbitrarily; the philosophy is to make as few changes to the source document as possible and remapping prefixes to match what happens to be declared in the filter would not be proper.

For names in namespaces that are introduced by the filter and are not in the source document, the prefixes from the filter are used. This is a bit dangerous: some other namespace in the source document may use the same prefix and the result could be catastrophic. Some future version will try to detect these collisions, and there may even be a nice way to avoid them.

Source document prefixes are generally invisible in the Essex environment (aside from the start_prefix_mapping and end_prefix_mapping events) because they could be anything. If you root around inside essex objects enough, though, you can ferret them out. Trying to do that is a pretty good indication that something's wrong.

LIMITATIONS

Does not support other Exporter features like exporting past several calling modules.

COPYRIGHT

Copyright 2002, R. Barrie Slaymaker, Jr., All Rights Reserved

LICENSE

You may use this module under the terms of the BSD, Artistic, oir GPL licenses, any version.

AUTHOR

Barrie Slaymaker <barries@slaysys.com>