view release on metacpan or  search on metacpan

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

=head2 XML Node and Attribute Identification

The identification of XML document nodes for modification is handled by the
C<XML::TreePP::XMLPath> module.

The idenfication of attributes in XML nodes is via the C<attr_prefix> property
in the C<XML::TreePP> module.

The idenfication of XML text (or CDATA) nodes is via the C<text_node_key>
property in the C<XML::TreePP> module.

Please review the XMLPath PHILOSOPHY section in it's POD for further
information.

=head2 C<XML::TreePP::XMLPath> dependency on C<XML::TreePP>

The C<XML::TreePP::XMLPath> module has a dependence on C<XML::TreePP>
When C<XML::TreePP::Editor::tpp()> and C<XML::TreePP::Editor::tppx()> methods
are called without parameters, this module checks to see if either of these
objects have been previously created, and links them together.

If you provide your own C<XML::TreePP> or C<XML::TreePP::XMLPath> objects, this
module does not attempt to link them together. Instead you would want to do
it yourself in the following fashion.

    my $tpp = new XML::TreePP;
    my $tppx = new XML::TreePP::XMLPath;
    $tppx->tpp($tpp);
    my $tppe = new XML::TreePP::Editor( tpp => $tpp, tppx => $tppx );

This is essentially similar to how the C<XML::TreePP::Editor::tpp()> and
C<XML::TreePP::Editor::tppx()> methods associate the objects.

=head1 METHODS

=cut

package XML::TreePP::Editor;

use 5.005;
use warnings;
use strict;
use Carp;
use XML::TreePP;
use XML::TreePP::XMLPath 0.61;
use Data::Dumper;

BEGIN {
    use vars      qw(@ISA @EXPORT @EXPORT_OK);
    @ISA        = qw(Exporter);
    @EXPORT     = qw();
    @EXPORT_OK  = qw();

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

    use vars      qw( $VERSION $DEBUG $TPPKEYS );
    $VERSION    = '0.13';
    $DEBUG      = 0;
    $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";
}


=pod

=head2 tpp

This module is an extension of the C<XML::TreePP module>. As such, it uses the
module in many different methods to parse XML Docuements, and when the user
calls the C<set()> and C<get()> methods to set and get properties specific to
the module.

The C<XML::TreePP module>, is loaded upon requesting a new object.

The caller can override the loaded instance of C<XML::TreePP> in favor of
another instance the caller posses, by providing it to this method.

Additionally, this module's loaded instance of C<XML::TreePP> can be directly
accessed or retrieved through this method.

=over 4

=item * C<XML::TreePP>

An instance of C<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.

=item * I<returns>

Returns the result of setting an instance of C<XML::TreePP> in this object.
Or returns the internally loaded instance of C<XML::TreePP>.
Or loads a new instance of C<XML::TreePP> and returns it.

=back

    $tppe->tpp( new XML::TreePP );  # Sets the XML::TreePP instance to be used by this object
    my $tppobj = $tppe->tpp();  # Retrieve the currently loaded XML::TreePP instance

=cut

sub tpp(@) {
    my $self    = shift if ref($_[0]) eq $REF_NAME || undef;
    if (!defined $self) {
        return new XML::TreePP;
    } else {
        # If being given the object, set it and return result
        return $self->{'tpp'} = shift if @_ >= 1 && ref($_[0]) eq "XML::TreePP";
        # If wanting object, and XMLPath object exists, retrieve it, set it, and return it
        if ((defined $self->{'tppx'}) && (ref($self->{'tppx'}) eq "XML::TreePP::XMLPath")) {
            $self->{'tpp'} = $self->{'tppx'}->tpp();
            return $self->{'tpp'};
        }
        # If wanting object and XMLPath object does not exist, create it and return it
        $self->{'tpp'} = new XML::TreePP;
        return $self->{'tpp'};
    }
}