view release on metacpan or  search on metacpan

lib/XML/TreePP/XMLPath.pm  view on Meta::CPAN

be undesirable if you want to evaluate C<animal> for results.

To perform the same evaluation, but return the matching C<animal> node, the
following XMLPath can be used:

    jungle/animal[cat='tiger']

To evaluate C<animal> and C<cat>, but return the matching C<cat> node, the
following XMLPaths can be used:

    jungle/animal[cat='tiger']/cat
    jungle/animal/cat[.='tiger']

The first path analyzes C<animal>, and the second path analyzes C<cat>. But
both matches the same node "<cat color='black>tiger</cat>".

=head2 Matching Attributes

Prior to version 0.52, attributes could only be used in XMLPath to evaluate
an element for a result set.
As of version 0.52, attributes can now be matched in XMLPath to return their
values.

This next example illustrates:

    <jungle>
        <animal>
            <cat color="black">tiger</cat>
        </animal>
    </jungle>
    
    /jungle/animal/cat[.='tiger']/@color

The result set of this XMLPath would be "C<black>".

=head1 METHODS

=cut

package XML::TreePP::XMLPath;

use 5.005;
use strict;
use warnings;
use Exporter;
use Carp;
use XML::TreePP;
use Data::Dumper;

BEGIN {
    use vars          qw(@ISA @EXPORT @EXPORT_OK);
    @ISA            = qw(Exporter);
    @EXPORT         = qw();
    @EXPORT_OK      = qw(&charlexsplit &getAttributes &getElements &getSubtree &parseXMLPath &assembleXMLPath &filterXMLDoc &getValues);

    use vars          qw($REF_NAME);
    $REF_NAME       = "XML::TreePP::XMLPath";  # package name

    use vars          qw( $VERSION $TPPKEYS );
    $VERSION        = '0.72';
    $TPPKEYS        = "force_array force_hash cdata_scalar_ref user_agent http_lite lwp_useragent base_class elem_class xml_deref first_out last_out indent xml_decl output_encoding utf8_flag attr_prefix text_node_key ignore_error use_ixhash";

    use vars          qw($DEBUG $DEBUGMETHOD $DEBUGNODE $DEBUGPATH $DEBUGFILTER $DEBUGDUMP);
    $DEBUG          = 0;
    $DEBUGMETHOD    = 1;
    $DEBUGNODE      = 2;
    $DEBUGPATH      = 3;
    $DEBUGFILTER    = 4;
    $DEBUGDUMP      = 7;
}


=pod

=head2 tpp

=over

This module is an extension of the XML::TreePP module. As such, it uses the
module in many different methods to parse XML Documents, and to get the value
of C<XML::TreePP> properties like C<attr_prefix> and C<text_node_key>.

The C<XML::TreePP> module, however, is only loaded into C<XML::TreePP::XMLPath>
when it becomes necessary to perform the previously described requests. For the
aformentioned properties C<attr_prefix> and C<text_node_key>, default values
are used if a C<XML::TreePP> object has not been loaded.

To avoid having this module load the XML::TreePP module,
do not pass in unparsed XML documents. The caller would instead want to
parse the XML document with C<XML::TreePP::parse()> before passing it in.
Passing in an unparsed XML document causes this module to load C<XML::TreePP>
in order to parse it for processing.

Alternately, If the caller has loaded a copy of C<XML::TreePP>, that object
instance can be assigned to be used by the instance of this module using this
method. In doing so, when XML::TreePP is needed, the instance provided is used
instead of loading another copy.

If this module has loaded an instance of <XML::TreePP>, this instance can be
directly accessed or retrieved through this method. For example, the
aformentioned properties can be set.

    $tppx->tpp->set('attr_prefix','@');  # default is (-) dash
    $tppx->tpp->set('text_node_key','#');  # default is (#) pound

If you want to only get the internally loaded instance of C<XML::TreePP>, but
do not want to load a new instance and instead have undef returned if an
instance is not already loaded, then use the C<get()> method.

    my $tppobj = $tppx->get( 'tpp' );
    warn "XML::TreePP is not loaded in XML::TreePP::XMLPath.\n" if !defined $tppobj;

This method was added in version 0.52

=over 4

=item * B<XML::TreePP>

An instance of XML::TreePP that this object should use instead of, when needed,
loading its own copy. If not provided, the currently loaded instance is
returned. If an instance is not loaded, an instance is loaded and then returned.