/ 
XML-ExtOn-0.17
River stage one • 2 direct dependents • 2 total dependents
/ XML::ExtOn

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.