NAME

XML::ExtOn - The handler for expansion of Perl SAX by objects.

SYNOPSYS

    use XML::ExtOn;

For write XML:

    use XML::ExtOn;
    my $buf;
    my $wrt = XML::ExtOn::Writer->new( Output => \$buf );
    my $ex_parser = new XML::ExtOn:: Handler => $wrt;
    $ex_parser->start_document;
    my $root = $ex_parser->mk_element("Root");
    $root->add_namespace(
        "myns" => 'http://example.com/myns',
        "myns_test", 'http://example.com/myns_test'
    );
    $ex_parser->start_element( $root );
    my $el = $root->mk_element('vars');
    %{ $el->attrs_by_prefix("myns") }      = ( v1 => 1, v2 => 3 );
    %{ $el->attrs_by_prefix("myns_test") } = 
    ( var1 => "test ns", var2 => "2333" );
    $root->add_content($el);
    $ex_parser->end_element;
    $ex_parser->end_document;
    print $buf;

Result:

    <?xml version="1.0"?>
    <Root xmlns:myns="http://example.com/myns" 
            xmlns:myns_test="http://example.com/myns_test">
    <vars myns_test:var2="2333" 
        myns_test:var1="test ns" 
        myns:v1="1" myns:v2="3"/>
    </Root>

For handle events

    use base 'XML::ExtOn';

Begin method for handle SAX event start_element:

    sub on_start_element {
        my ( $self, $elem ) = @_;

        ...

Check localname for element and add tag image:

        if ( $elem->local_name eq 'gallery' ) {
            $elem->add_content( 
                      $self->mk_element('image')->add_content(
                        $self->mk_characters( "Image number: $_" )
                        )
                  ) for 1..2 ;
        }

XML Before:

    <?xml version="1.0"?>
    <Document>
      <gallery/>
    </Document>

After:

    <?xml version="1.0"?>
    <Document>
      <gallery>
        <image>Image number: 1</image>
        <image>Image number: 2</image>
      </gallery>
    </Document>

Register namespace and set variables

        $elem->add_namespace('demons','http://example.org/demo_namespace');
        $elem->add_namespace('ns2','http://example.org/ns2');
        #set attributes for name space
        my $demo_attrs = $elem->attrs_by_prefix('demons');
        %{$demo_attrs} = ( variable1=>1, 'variable2'=>2);
        #set attributes for namespace URI
        my $ns2_attrs = $elem->attrs_by_ns_uri('http://example.org/ns2');
        %{$ns2_attrs} = ( var=> 'ns1', 'raw'=>2);

Result:

        <sub xmlns:demons="http://example.org/demo_namespace" 
        xmlns:ns2="http://example.org/ns2" 
            demons:variable2="2" ns2:var="ns1" 
            demons:variable1="1" ns2:raw="2"/>

Delete content of element

    if ( $elem->local_name eq 'demo_delete') {
            $elem->skip_content
    }

XML before:

    <?xml version="1.0"?>
    <Document>
        <demo_delete>
          <p>text</p>
        </demo_delete>
    </Document>

After:

    <?xml version="1.0"?>
     <Document>
        <demo_delete/>
     </Document>

Add XML:

        $elem->add_content ( 
             $self->mk_from_xml('<custom><p>text</p></custom>')
        )
Can add element after current

        ...
        return [ $elem, $self->mk_element("after") ];
    }

DESCRIPTION

XML::ExtOn - SAX Handler designed for funny work with XML. It provides an easy-to-use interface for XML applications by adding objects.

XML::ExtOn override some SAX events. Each time an SAX event starts, a method by that name prefixed with `on_' is called with the "blessed" Element object to be processed.

XML::ExtOn implement the following methods:

• on_start_document

• on_start_prefix_mapping

• on_start_element

• on_end_element

• on_characters

• on_cdata

XML::ExtOn put all cdata characters into a single event on_cdata.

It compliant XML namespaces (http://www.w3.org/TR/REC-xml-names/), by support default namespace and namespace scoping.

XML::ExtOn provide methods for create XML, such as mk_element, mk_cdata ...

FUNCTIONS

create_pipe "flt_n1",$some_handler, $out_handler

use last arg as handler for out.

return parser ref.

    my $h1     = new MyHandler1::;
    my $filter = create_pipe( 'MyHandler1', $h1 );
    $filter->parse('<root><p>TEST</p></root>');
    #also create pipe of pipes
    my $filter1 = create_pipe( 'MyHandler1', 'MyHandler2' );
    my $h1     = new MyHandler3::;
    my $filter2 = create_pipe(  $filter1, $h1);

split_pipe $filter

return ref to array of filters in pipe

    use XML::ExtOn qw(split_pipe create_pipe);
    my $filter = create_pipe( 'MyHandler1', 'MyHandler2','MyHandler3');
    my $ref = @{ split_pipe( $filter) } [-1];
    isa_ok $ref,  'MyHandler3', 'check last element';

METHODS

on_start_document $document

Method handle start_document event. Usually override for initialaize default variables.

    sub on_start_document {
        my $self = shift;
        $self->{_LINKS_ARRAY} = [];
        $self->SUPER::on_start_document(@_);
    }

on_start_prefix_mapping prefix1=>ns_uri1[, prefix2=>ns_uri2]

Called on start_prefix_mapping event.

    sub on_start_prefix_mapping {
        my $self = shift;
        my %map  = @_;
        $self->SUPER::start_prefix_mapping(@_)
    }

on_start_element $elem

Method handle on_start_element event whith XML::ExtOn::Element object.

Method must return $elem or ref to array of objects.

For example:

    sub on_start_element {
        my $self = shift;
        my $elem = shift;
        $elem->add_content( $self->mk_cdata("test"));
        return $elem
    }
    ...
    
    return [ $elem, ,$self->mk_element("after_start_elem") ]
    
    return [ $self->mk_element("before_start_elem"), $elem ]
    ...

on_end_element $elem

Method handle on_end_element event whith XML::ExtOn::Element object. It call before end if element.

Method must return $elem or ref to array of objects.

For example:

    sub on_end_element {
        my $self = shift;
        my $elem = shift;
        if ( $elem->is_delete_element ) {
            warn $elem->local_name . " deleted";
            return [ $elem, $self->mk_element("after_deleted_elem") ]
        };
        return $elem
    }
    ...
    
    return [ $elem, ,$self->mk_element("after_close_tag_of_elem") ]
    
    return [ $self->mk_element("before_close_tag_of_elem"), $elem ]
    ...

on_characters( $self->current_element, $data->{Data} )

Must return string for write to stream.

    sub on_characters {
        my ( $self, $elem, $str ) = @_;
        #lowercase all characters
        return lc $str;
    }

on_cdata ( $current_element, $data )

Must return string for write to stream

    sub on_cdata {
        my ( $self, $elem, $str ) = @_;
        return lc $str;
    }

mk_element <tag name>

Return object of element item for include to stream.

mk_from_xml <xml string>

Return command for include to stream.

mk_cdata $string | \$string

return command for insert cdata to stream

mk_characters $string | \$string

return command for insert characters to stream

mk_start_element <element object>

return command for start element event

mk_event_element <element object>

return command for expand stack for element

_mk_event_start_element <element object>

return start tag command. (internal)

_mk_event_end_element <element object>

return end tag command. (internal)

mk_end_element <element object>

return command for end element event

current_element

Return link to current processing element.

current_root_element

Return link to current root element in incoming stack. Used in start_element and end_element methods

add_namespace <Prefix> => <Namespace_URI>, [ <Prefix1> => <Namespace_URI1>, ... ]

Add Namespace mapping. return $self

If Prefix eq '', this namespace will then apply to all elements that have no prefix.

    $elem->add_namespace(
        "myns" => 'http://example.com/myns',
        "myns_test", 'http://example.com/myns_test',
        ''=>'http://example.com/new_default_namespace'
    );

parse <file_handler>| <\*GLOB> | <xml string> | <ref to xml string>

SEE ALSO

XML::ExtOn::Element, XML::SAX::Base

AUTHOR

Zahatski Aliaksandr, <zag@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2007-2009 by Zahatski Aliaksandr

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

cpanm XML::ExtOn

perl -MCPAN -e shell
install XML::ExtOn