NAME

XML::Tiny::DOM::Element - an object representing an XML element

DESCRIPTION

This represents a single <element /> in an XML document that was parsed using XML::Tiny::DOM.

SYNOPSIS

    use XML::Tiny::DOM;
    my $document = XML::Tiny::DOM->new(...);
    # $document is now an XML::Tiny::DOM::Element

now, given a document like this:

    <rsnapshot>
      <externalprograms>
        <rsync binary='/usr/bin/rsync'>
          <args>
            <arg>-a</arg>
            <arg>-q</arg>
          </args>
        </rsync>
      </externalprograms>
      <intervals>
        <interval name='alpha' retain='6' />
        <interval name='beta'  retain='7' />
        <interval name='gamma' retain='4' />
        <interval name='delta' retain='3' />
      </intervals>
    </rsnapshot>

you can do this:

    my $rsync        = $document->externalprograms->rsync();
    my $rsyncbinary  = $rsync->binary();
    my $allrsyncargs = [ $rsync->args->arg('*') ];
    my $secondarg    = $rsync->args->arg(1);
    my $gamma        = $document->intervals->interval('gamma');

METHODS

created by AUTOLOAD

Most methods are created using AUTOLOAD. There's also a few utility and private methods whose names start with an underscore. Consequently your documents shouldn't contain any elements or attributes whose names start with an underscore, or that are called DESTROY or AUTOLOAD, because those are special to perl.

When you call the ...->foo() method on an object, it first looks for an XML attribute with that name. If there is one, its value is returned.

If there's no such attribute, then it looks for a child element with that name. If no parameter is given, it returns the first such element. If a numeric parameter is given, it returns the Nth element (counting from 0). If the parameter is '*' then all such elements are returned. Otherwise, child elements of the appropriate type are searched and a list of those whose ...->name() method returns something that matches the parameter is returned.

_parent

Returns the parent element of this element. It is an error to call this on the root element.

_root

Return the root element.

BUGS and FEEDBACK

I welcome feedback about my code, including constructive criticism. Bug reports should be made using http://rt.cpan.org/ or by email, and should include the smallest possible chunk of code, along with any necessary XML data, which demonstrates the bug. Ideally, this will be in the form of a file which I can drop in to the module's test suite.

SEE ALSO

XML::Tiny::DOM

XML::Tiny

AUTHOR, COPYRIGHT and LICENCE

David Cantrell <david@cantrell.org.uk>

Copyright 2009 David Cantrell <david@cantrell.org.uk>

This software is free-as-in-speech software, and may be used, distributed, and modified under the terms of either the GNU General Public Licence version 2 or the Artistic Licence. It's up to you which one you use. The full text of the licences can be found in the files GPL2.txt and ARTISTIC.txt, respectively.

CONSPIRACY

This module is also free-as-in-mason software.