NAME

XML::Template::Parser - SAX handler for parsing XML::Template documents.

SYNOPSIS

  use XML::SAX::ParserFactory;
  use XML::Template::Parser

  my $handler = XML::Template::Parser->new ();
  my $parser = XML::SAX::ParserFactory->parser (Handler => $handler);
  my $code = eval { $parser->parse_string ($xml) };

DESCRIPTION

This module is the XML::Template document parser. It is implemented as an XML::SAX handler. Whenever an element in a namespace that has been configured is encountered, a subroutine is called in the Perl module associated with the namespace. The subroutine should return Perl code that generates the content of the element. Much of the default element and attribute processing behavior can be modified in the XML::Template configuration file. See XML::Template::Config for more details.

CONSTRUCTOR

A constructor method new is provided by XML::Template::Base. A list of named configuration parameters may be passed to the constructor. The constructor returns a reference to a new parser object or under if an error occurred. If undef is returned, you can use the method error to retrieve the error. For instance:

  my $parser = XML::Template::Parser->new (%config)
    || die XML::Template::Parser->error;

The following named configuration parameters may be passed to the constructor:

String

A blessed reference to an object that parses strings and returns an XML::Template Perl code representation. This value will override the default value $STRING in XML::Template::Config. The default string parser object is of the class XML::Template::Parser::String. This module is generated from the grammar file XML/Template/Parser/string.grammar by Parse::RecDescent. To generate a new string parser, see XML/Template/Parser/README.

PRIVATE METHODS

_init

This method is the internal initialization function called from XML::Template::Base when a new parser object is created.

PUBLIC METHODS

element_string

  my $text = $self->element_string ($type, $element);

This method constructs the XML for an XML::SAX element data structure. If type is 1, attributes are generated.

XML::SAX SUBROUTINES

start_element

This method is invoked at the beginning of every element. The following algorithm is used to parse start elements:

  - Increment depth level.
  - If not skipping
    - Add new namespaces to list, push onto stack.
    - If namespace configured
      - Check proper nesting.
      - If content type is not 'xml', begin skipping at current depth 
        level.
      - Check for missing required attributes.
      - Generate code for attributes (with configured string parsers), 
        add to attribs hash.
      - Create and cache element object, if not nested.  Call constructor 
        with hash of defined namespaces and current namespace.
      - Push attribs hash and code onto stacks.
    - Else
      - Generate code to print XML, append to code private data.
  - Else
    - Generate XML, append to text private data.
  - Push element onto stack.

end_element

This method is invoked at the end of every element. The following algorithm is used to parse end elements:

  - Pop element from stack.
  - If skipping should stop, retrieve collected text from private data, 
    stop skipping.
  - If not skipping
    - Pop namespace list from stack.
    - If namespace configured
      - If not nested, pop element object from stack, otherwise just get 
        it.
      - Pop attribs and code from stacks.
      - If content type is 'empty', call element subroutine with undef and 
        attribs, else if content type is 'text' call element subroutine 
        with skipped text and attribs, else call element subroutine with 
        code and attribs.
    - Else
      - Generate code to print XML, append to code private data.
  - Else
    - Generate XML, append to text private data.
  - Decrement depth level.

characters

This method is invoked for each chunk of character data. The following algorithm is used to parse character data:

  - If not skipping
    - Generate code to print text, append to code private data.
  - Else
    - Append character data to text private data.

end_document

This method is invoked at the end of the document. It returns a string containing the Perl code representation of the parsed XML document.

AUTHOR

Jonathan Waxman <jowaxman@bbl.med.upenn.edu>

COPYRIGHT

Copyright (c) 2002-2003 Jonathan A. Waxman All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm XML::Template

perl -MCPAN -e shell
install XML::Template