SAXMachines(3)

NAME

       Apache::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.6 2002-Apache::AxKit::Language::SAXMachines(3)