Apache::AxKit::LanguagUserAContributed)Apache::AxKit::Language::SAXMachines(3)NAMEApache::AxKit::Language::SAXMachines - Transform Content With SAX Fil-
ters
SYNOPSIS
# add the style processor mapping
AxAddStyleMap application/x-saxmachines Apache::AxKit::Language::SAXMachines
# add the processor
AxAddProcessor application/x-saxmachines .
# create a simple filter chain
PerlSetVar AxSAXMachineFilters "XML::Filter1 XML::Filter2"
# filter set-up via a controller class
PerlSetVar AxSAXMachineClass "Custom::MachineBuilderClass"
DESCRIPTION
Language::SAXMachines provides an easy way ( via Barrie Slaymaker's
XML::SAX::Machines ) to use SAX filter chains to transform XML content.
It is not technically a "language" in the same sense that XSP, XPath-
Script, or XSLT are since there is no stylesheet to write or process.
Instead, the SAX filters are added via config directives in your .htac-
cess or *.conf file.
( Note, future versions may add an associated XML application grammar
that may be used to define/configure the filter chain, but rushing for-
ward to that is Truly Bad Idea(tm) for a number of reasons ).
The configuration directives that are required or recognized by Lan-
guage::SAXMachines are detailed below.
Style Processor Mapping (AxAddStyleMap)
To use Language::SAXMachines you must set set up the mapping between
the style processor's MIME type and the Language::SAXMachines module.
This is achieved via the typical AxAddStyleMap directive:
AxAddStyleMap application/x-saxmachines Apache::AxKit::Language::SAXMachines
Invoking The Processor (AxAddProcessor, etc.)
To apply Language::SAXMachines processor to a given document request,
you must use the AxAddProcessor directive (or one of its relations):
<Files *.xml>
AxAddProcessor application/x-saxmachines .
</Files>
Note the dot ('.') there. Like XSP, there is no external stylesheet to
process so the URI must be set to point back to the document itself.
See the section labeled "ASSOCIATING STYLESHEETS WITH XML FILES" in the
main AxKit POD ( perldoc AxKit ) for additional options.
Setting Up a Simple SAX Filter Chain (AxSAXMachineFilters)
For simple cases where you want to process the document through a
static list of SAX filters, use the AxSAXMachineFilters option. It
accepts a white-space-seperated list of valid SAX Filter module names
and builds a linear processing pipeline from those modules. Filters are
applied in the same order that they appear in the AxSAXMachineFilters
directive.
The following would create a simple pipleline that applies the SAX fil-
ters XML::Filter1 and XML::Filter2 (in that order) to the document.
PerlSetVar AxSAXMachineFilters "XML::Filter1 XML::Filter2"
Using a SAX::Machines-aware Controller Class (AxSAXMachineClass)
A static list of SAX Filters is fine for many tasks. However, for more
advanced applications, it is often desireable for sets of filters (or
other SAX::Machines) to be dynamically chosen and set up at request
time.
The AxSAXMachinesClass directive accpets the module name of a class
that is capable of building a SAX::Machines processing chain. The
object returned from that module's get_machine() method is expected to
a blessed and valid reference to to a SAX::Machine object (including
Pipelines, ByRecords, etc.).
The following would use the SAX::Machines object returned by the
get_machine() method of the the Custom::MachineBuilderClass module to
create the SAX processing chain.
PerlSetVar AxSAXMachineClass "Custom::MachineBuilderClass"
In addition, the get_machines() method in the class defined by the
AxSAXMachineClass directive is passed a reference to the current
Apache::Request instance (as well as few other possibly useful bits of
information) allowing the module to create a processing chain that is
more directly responsive to the context of the current request. A typi-
cal get_machine() implementation might start off like:
sub get_machine {
my ($self, $r, $last_in_chain) = @_;
# make some choices about what filters to add, or machines to build
# based on the info the Apache::Request object in $r
# assumes 'use XML::SAX::Machines qw( Pipeline );'
my $machine = Pipeline( @list_of_filters_we_picked );
return $machine;
}
Note that machines can be nested sets of other machines just as in the
regular usage of XML::SAX::Machines, get_machine() need only return the
top-level 'wrapper machine'.
When Worlds Collide ( Using Both AxSAXMAchineFilters and AxSAXMa-
chineClass )
In cases where both AxSAXMachineFilters and AxSAXMAchineClass are used
to set up the processing for a given request, the machine returned by
AxSAXMAchineClass is given processing precedence. That is, the docu-
ment's event stream will be run through the machine returned by the
AxSAXMAchineClass first, and then passed through the filters defined by
the AxSAXMAchineFilters directive. So,
PerlSetVar AxSAXMachineFilters "XML::Filter1 XML::Filter2"
PerlSetVar AxSAXMachineClass "Custom::MachineBuilderClass"
appearing in the same config block would send the document's events
through a linear pipeline consisting of the machine returned by Cus-
tom::MachineBuilderClass's get_machine() method followed by the filters
XML::Filter1 and XML::Filter2.
SEE ALSO
AxKit, XML::SAX::Machines
perl v5.8.82005-Apache::AxKit::Language::SAXMachines(3)
