NAME

XML::SAX::Context

ABSTRACT

XML::SAX::Context - A sub-class of XML::SAX::Base that stores context information during parsing

SYNOPSIS

  use XML::SAX::Context;
  use XML::Parser::PerlSAX;
  my $handler= MyHandler->new;
  my $parser= my $parser = XML::Parser::PerlSAX->new(Handler => $handler);
  $parser->parse( $doc);

  package TestHandler;

  use base qw(XML::SAX::Context);
  
  sub start_element
    { my( $self, $elt)= @_;
      my $current_name= $self->current_name;
      my @ancestor_names= $self->ancestor_names;
      my $current_depth= $self->depth;
          print "in foo" if( $self->in_element( "foo"));
    }
  
  sub characters
    { my( $self, $chars)= @_;
      my $current_tag= $self->current_name;
          my $context= $self->context;
      print "I'm here\n" 
        if( ($self->depth > 3) 
             and ($self->parent( 'ul')->{Attribute}->{'{}foo'} eq 'bar')
          );
    }

DESCRIPTION

XML::SAX::Context allows handlers that subclass it to use convenience methods to access the current parsing context (open elements...)

XML::SAX::Context keeps a stack with the open elements and gives methods to access this stack conveniently

Note: all method names are case insensitive and underscores are discarded, so current_localname can also be called currentLocalName or current_local_name or even CuRrEnTlOcAlNaMe (not recommended!)

Methods

context: returns a reference to the stack of open elements
current_element: returns a reference to the current element as received in the start_element handler
current_name: returns the Name of the currently open element
current_localname: returns the LocalName of the currently open element
current_prefix: returns the Prefix of the currently open element
current_namespaceuri: returns the NamespaceURI of the currently open element
parent_name: returns the Name of the parent of currently open element
parent_localname: returns the LocalName of the parent of currently open element
parent_prefix: returns the Prefix of the parent of currently open element
parent_namespaceuri: returns the NamespaceURI of the parent of currently open element
depth: returns the level in the parse tree. This is purely the level in terms of open elements, starting with 1. In short it is the size of the context stack.
ancestors: same as context
ancestor_names: returns a list of ancestor Names, with the root first
ancestor_localnames: returns a list of ancestor LocalNames, with the root first
ancestor_prefixs: returns a list of ancestor Prefixs, with the root first
ancestor_namespaceuris: returns a list of ancestor NamespaceURIs, with the root first
in_element ( $tagname): returns true if the parent element tag name is $tagname. <$tagname> can be either the Name, including the prefix, or the clarkian notation for the name: {NamespaceURI}LocalName.
within_element ( $tagname): returns the number of elements in the ancestor list which name is $tagname
parent ( $optional_tagname): returns a reference to the parent of the current element. If an $optional_tagname is given then it will give a reference to the deepest element in the ancestor list which Name is $optional_tagname
inherited_attribute ( $attribute_name): walks the context stack (from the top) and returns the value of the first attribute $attribute_name found.

Convenient Functions

The module also provides (but does not export at the moment, so you have to use the full name of the function XML::SAX::Context::clarkian for example) the following functions:

clarkian ($element): returns the clarkian notation for $element ($element is an eleement as received by the start_element handler, and as stored in the context stack): {<NamespaceURI>}<LocalName>

TODO

Allow keeping the siblings of the top of the pile, that's often useful

Check Namespace declarations, they're probably a huge PITA ;--(

AUTHOR

Michel Rodriguez, <mirod@cpan.org>

COPYRIGHT AND LICENSE

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