.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "EasyOBJ 3pm"
.TH EasyOBJ 3pm "2009-08-19" "perl v5.10.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
XML::EasyOBJ \- Easy XML object navigation
.SH "VERSION"
.IX Header "VERSION"
Version 1.12
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& # open exisiting file
\& my $doc = new XML::EasyOBJ(\*(Aqmy_xml_document.xml\*(Aq);
\& my $doc = new XML::EasyOBJ(\-type => \*(Aqfile\*(Aq, \-param => \*(Aqmy_xml_document.xml\*(Aq);
\&
\& # create object from XML string
\& my $doc = new XML::EasyOBJ(\-type => \*(Aqstring\*(Aq, \-param => $xml_source);
\&
\& # create new file
\& my $doc = new XML::EasyOBJ(\-type => \*(Aqnew\*(Aq, \-param => \*(Aqroot_tag\*(Aq);
\& 
\& # read from document
\& my $text = $doc\->some_element($index)\->getString;
\& my $attr = $doc\->some_element($index)\->getAttr(\*(Aqfoo\*(Aq);
\& my $element = $doc\->some_element($index);
\& my @elements = $doc\->some_element;
\&
\& # first "some_element" element
\& my $elements = $doc\->some_element;
\& # list of "some_element" elements
\& my @elements = $doc\->some_element;
\&
\& # write to document
\& $doc\->an_element\->setString(\*(Aqsome string\*(Aq)
\& $doc\->an_element\->addString(\*(Aqsome string\*(Aq)
\& $doc\->an_element\->setAttr(\*(Aqattrname\*(Aq, \*(Aqval\*(Aq)
\& $doc\->an_element\->setAttr(\*(Aqattr1\*(Aq => \*(Aqval\*(Aq, \*(Aqattr2\*(Aq => \*(Aqval2\*(Aq)
\&
\& # access elements with non\-name chars and the underlying DOM
\& my $element = $doc\->getElement(\*(Aqfoo\-bar\*(Aq)\->getElement(\*(Aqbar\-none\*(Aq);
\& my $dom = $doc\->foobar\->getDomObj;
\&
\& # get elements without specifying the element name
\& my @elements = $doc\->getElement();
\& my $sixth_element = $doc\->getElement(\*(Aq\*(Aq, 5);
\&
\& # remove elements/attrs
\& $doc\->remElement(\*(Aqtagname\*(Aq, $index);
\& $doc\->tag_name\->remAttr($attr);
\&
\& # remap builtin methods
\& $doc\->remapMethod(\*(AqgetString\*(Aq, \*(Aqs\*(Aq);
\& my $text = $doc\->some_element\->s;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
I wrote XML::EasyOBJ a couple of years ago because it seemed to me
that the \s-1DOM\s0 wasn't very \*(L"perlish\*(R" and the \s-1DOM\s0 is difficult for us
mere mortals that don't use it on a regular basis.  As I only need
to process \s-1XML\s0 on an occasionally I wanted an easy way to do what
I needed to do without having to refer back to \s-1DOM\s0 documentation
each time.
.PP
A quick fact list about XML::EasyOBJ:
.PP
.Vb 3
\& * Runs on top of XML::DOM
\& * Allows access to the DOM as needed
\& * Simple routines to reading and writing elements/attributes
.Ve
.SH "REQUIREMENTS"
.IX Header "REQUIREMENTS"
XML::EasyOBJ uses \s-1XML::DOM\s0.  \s-1XML::DOM\s0 is available from \s-1CPAN\s0 (www.cpan.org).
.SH "METHODS"
.IX Header "METHODS"
Below is a description of the methods avialable.
.SS "new"
.IX Subsection "new"
You can create a new object from an \s-1XML\s0 file, a string of \s-1XML\s0, or
a new document.  The constructor takes a set of key value pairs as
follows:
.IP "\-type" 4
.IX Item "-type"
The type is either \*(L"file\*(R", \*(L"string\*(R" or \*(L"new\*(R".  \*(L"file\*(R" will create
the object from a file source, \*(L"string\*(R" will create the object from
a string of \s-1XML\s0 code, and \*(L"new\*(R" will create a new document object.
.IP "\-param" 4
.IX Item "-param"
This value depends on the \-type that is passed to the constructor.
If the \-type is \*(L"file\*(R" this will be the filename to open and parse.
If \-type is \*(L"string\*(R", this is a string of \s-1XML\s0 code.  If \-type is
\&\*(L"new\*(R", this is the name of the root element.
.Sp
Creating an object from an \s-1XML\s0 file:
.Sp
.Vb 1
\& my $doc = new XML::EasyOBJ(\-type => \*(Aqfile\*(Aq, \-param => \*(Aqmy_xml_document.xml\*(Aq);
.Ve
.Sp
Creating an object from a string containing the \s-1XML\s0 source:
.Sp
.Vb 1
\& my $doc = new XML::EasyOBJ(\-type => \*(Aqstring\*(Aq, \-param => $xml_source);
.Ve
.Sp
Creating a new \s-1XML\s0 document by passing the root tag name:
.Sp
.Vb 1
\& my $doc = new XML::EasyOBJ(\-type => \*(Aqnew\*(Aq, \-param => \*(Aqroot_tag\*(Aq);
.Ve
.IP "\-expref" 4
.IX Item "-expref"
Passing a value of 1 will force the expansion of references when
grabbing string data from the \s-1XML\s0 file.  The default value is 0,
not to expand references.
.PP
Obtionally you may also pass the filename to open as the first
argument instead of passing the \-type and \-param parameters.
This is backwards compatable with early version of XML::EasyOBJ
which did not handle \-type and \-param parameters.
.PP
.Vb 1
\& my $doc = new XML::EasyOBJ(\*(Aqmy_xml_document.xml\*(Aq);
.Ve
.SS "makeNewNode( \s-1NEW_TAG\s0 )"
.IX Subsection "makeNewNode( NEW_TAG )"
Append a new element node to the current node. Takes the tag name
as the parameter and returns the created node as a convienence.
.PP
.Vb 1
\& my $p_element = $doc\->body\->makeNewNode(\*(Aqp\*(Aq);
.Ve
.SS "remapMethod( \s-1CUR_METHOD\s0, \s-1NEW_METHOD\s0 )"
.IX Subsection "remapMethod( CUR_METHOD, NEW_METHOD )"
Allows you to change the name of any of the object methods. You
might want to do this for convienience or to avoid a naming
collision with an element in the document.
.PP
Two parameters need to be passed; the current name of the method
and the new name. Returns 1 on a successful mapping and undef
on failure. A failure can result if you don't pass two parameters
if if the \*(L"copy from\*(R" method name does not exist.
.PP
.Vb 2
\& $doc\->remapMethod(\*(AqgetString\*(Aq, \*(Aqs\*(Aq);
\& $doc\->s();
.Ve
.PP
After remapping you must use the new name if you with to remap
the method again.  You can call the remapMethod method from
any place in the \s-1XML\s0 tree and it will always change the method
globally.
.PP
In the following example \f(CW$val1\fR and \f(CW$val2\fR are equal:
.PP
.Vb 4
\& $doc\->some_element\->another_element\->(\*(AqgetString\*(Aq, \*(Aqs\*(Aq);
\& my $val1 = $doc\->s();
\& $doc\->remapMethod(\*(Aqs\*(Aq, \*(AqgetString\*(Aq);
\& my $val2 = $doc\->getString();
.Ve
.SS "getString( )"
.IX Subsection "getString( )"
Recursively extracts text from the current node and all children
element nodes. Returns the extracted text as a single scalar value.
Expands entities based on if the \-expref flag was supplied during
object creation.
.SS "extractText( )"
.IX Subsection "extractText( )"
Same as \fIgetString()\fR but does not check the \-expref flag.  Included for
compatability with inital version of interface.
.SS "setString( \s-1STRING\s0 )"
.IX Subsection "setString( STRING )"
Sets the text value of the specified element. This is done by
first removing all text node children of the current element
and then appending the supplied text as a new child element.
.PP
Take this \s-1XML\s0 fragment and code for example:
.PP
<p>This elment has <b>text</b> and <i>child</i> elements</p>
.PP
.Vb 1
\& $doc\->p\->setString(\*(AqThis is the new text\*(Aq);
.Ve
.PP
This will change the fragment to this:
.PP
<p><b>text</b><i>child</i>This is the new text</p>
.PP
Because the <b> and <i> tags are not text nodes they are left
unchanged, and the new text is added at the end of the specified
element.
.PP
If you need more specific control on the change you should
either use the \fIgetDomObj()\fR method and use the \s-1DOM\s0 methods
directly or remove all of the child nodes and rebuild the
<p> element from scratch.  Also see the \fIaddString()\fR method.
.SS "addString( \s-1STRING\s0 )"
.IX Subsection "addString( STRING )"
Adds to the the text value of the specified element. This
is done by appending the supplied text as a new child element.
.PP
Take this \s-1XML\s0 fragment and code for example:
.PP
<p>This elment has <b>text</b></p>
.PP
.Vb 1
\& $doc\->p\->addString(\*(Aq and elements\*(Aq);
.Ve
.PP
This will change the fragment to this:
.PP
<p>This elment has <b>text</b> and elements</p>
.SS "getAttr( \s-1ATTR_NAME\s0 )"
.IX Subsection "getAttr( ATTR_NAME )"
Returns the value of the named attribute.
.PP
.Vb 1
\& my $val = $doc\->body\->img\->getAttr(\*(Aqsrc\*(Aq);
.Ve
.SS "getTagName( )"
.IX Subsection "getTagName( )"
Returns the tag name of the specified element. This method is
useful when you are enumerating child elements and do not
know their element names.
.PP
.Vb 3
\& foreach my $element ( $doc\->getElement() ) {
\&    print $element\->getTagName();
\& }
.Ve
.SS "setAttr( \s-1ATTR_NAME\s0, \s-1ATTR_VALUE\s0, [\s-1ATTR_NAME\s0, \s-1ATTR_VALUE\s0]... )"
.IX Subsection "setAttr( ATTR_NAME, ATTR_VALUE, [ATTR_NAME, ATTR_VALUE]... )"
For each name/value pair passed the attribute name and value will
be set for the specified element.
.SS "remAttr( \s-1ATTR_NAME\s0 )"
.IX Subsection "remAttr( ATTR_NAME )"
Removes the specified attribute from the current element.
.SS "remElement( \s-1TAG_NAME\s0, \s-1INDEX\s0 )"
.IX Subsection "remElement( TAG_NAME, INDEX )"
Removes a child element of the current element. The name of the
child element and the index must be supplied.  An index of 0
will remove the first occurance of the named element, 1 the second,
2 the third, etc.
.SS "getElement( \s-1TAG_NAME\s0, \s-1INDEX\s0 )"
.IX Subsection "getElement( TAG_NAME, INDEX )"
Returns the node from the tag name and index. If no index is
given the first child with that name is returned. Use this
method when you have element names that include characters that
are not legal as a perl method name.  For example:
.PP
.Vb 5
\& <foo> <!\-\- root element \-\->
\&  <bar>
\&   <foo\-bar>test</foo\-bar>
\&  </bar>
\& </foo>
\&
\& # "foo\-bar" is not a legal method name
\& print $doc\->bar\->getElement(\*(Aqfoo\-bar\*(Aq)\->getString();
.Ve
.SH "getDomObj( )"
.IX Header "getDomObj( )"
Returns the \s-1DOM\s0 object associated with the current node. This
is useful when you need fine access via the \s-1DOM\s0 to perform
a specific function.
.SH "BEGINNER QUICK START GUIDE"
.IX Header "BEGINNER QUICK START GUIDE"
.SS "Introduction"
.IX Subsection "Introduction"
You too can write \s-1XML\s0 applications, just as long as you understand
the basics of \s-1XML\s0 (elements and attributes). You can learn to write
your first program that can read data from an \s-1XML\s0 file in a mere
10 minutes.
.SS "Assumptions"
.IX Subsection "Assumptions"
It is assumed that you are familiar with the structure of the document that
you are reading.  Next, you must know the basics of perl lists, loops, and
how to call a function.  You must also have an \s-1XML\s0 document to read.
.PP
Simple eh?
.SS "Loading the \s-1XML\s0 document"
.IX Subsection "Loading the XML document"
.Vb 2
\& use XML::EasyOBJ;
\& my $doc = new XML::EasyOBJ(\*(Aqmy_xml_document.xml\*(Aq) || die "Can\*(Aqt make object";
.Ve
.PP
Replace the string \*(L"my_xml_document.xml\*(R" with the name of your \s-1XML\s0 document.
If the document is in another directory you will need to specify the path
to it as well.
.PP
The variable \f(CW$doc\fR is an object, and represents our root \s-1XML\s0 element in the document.
.SS "Reading text with getString"
.IX Subsection "Reading text with getString"
Each element becomes an object. So lets assume that the \s-1XML\s0 page looks like
this:
.PP
.Vb 10
\& <table>
\&  <record>
\&   <rec2 foo="bar">
\&    <field1>field1a</field1>
\&    <field2>field2b</field2>
\&    <field3>field3c</field3>
\&   </rec2>
\&   <rec2 foo="baz">
\&    <field1>field1d</field1>
\&    <field2>field2e</field2>
\&    <field3>field3f</field3>
\&   </rec2>
\&  </record>
\& </table>
.Ve
.PP
As mentioned in he last step, the \f(CW$doc\fR object is the root
element of the \s-1XML\s0 page. In this case the root element is the \*(L"table\*(R"
element.
.PP
To read the text of any field is as easy as navigating the \s-1XML\s0 elements.
For example, lets say that we want to retrieve the text \*(L"field2e\*(R". This
text is in the \*(L"field2\*(R" element of the \s-1SECOND\s0 \*(L"rec2\*(R" element, which is
in the \s-1FIRST\s0 \*(L"record\*(R" element.
.PP
So the code to print that value it looks like this:
.PP
.Vb 1
\& print $doc\->record(0)\->rec2(1)\->field2\->getString;
.Ve
.PP
The \*(L"getString\*(R" method returns the text within an element.
.PP
We can also break it down like this:
.PP
.Vb 2
\& # grab the FIRST "record" element (index starts at 0)
\& my $record = $doc\->record(0);
\& 
\& # grab the SECOND "rec2" element within $record
\& my $rec2 = $record\->rec2(1);
\& 
\& # grab the "field2" element from $rec2
\& # NOTE: If you don\*(Aqt specify an index, the first item 
\& #       is returned and in this case there is only 1.
\& my $field2 = $rec2\->field2;
\&
\& # print the text
\& print $field2\->getString;
.Ve
.SS "Reading \s-1XML\s0 attributes with getAttr"
.IX Subsection "Reading XML attributes with getAttr"
Looking at the example in the previous step, can you guess what
this code will print?
.PP
.Vb 2
\& print $doc\->record(0)\->rec2(0)\->getAttr(\*(Aqfoo\*(Aq);
\& print $doc\->record(0)\->rec2(1)\->getAttr(\*(Aqfoo\*(Aq);
.Ve
.PP
If you couldn't guess, they will print out the value of the \*(L"foo\*(R"
attribute of the first and second rec2 elements.
.SS "Looping through elements"
.IX Subsection "Looping through elements"
Lets take our example in the previous step where we printed the
attribute values and rewrite it to use a loop. This will allow
it to print all of the \*(L"foo\*(R" attributes no matter how many \*(L"rec2\*(R"
elements we have.
.PP
.Vb 3
\& foreach my $rec2 ( $doc\->record(0)\->rec2 ) {
\&   print $rec2\->getAttr(\*(Aqfoo\*(Aq);
\& }
.Ve
.PP
When we call \f(CW$doc\fR\->\fIrecord\fR\|(0)\->rec2 this way (i.e. in list context), 
the module will return a list of \*(L"rec2\*(R" elements.
.SS "That's it!"
.IX Subsection "That's it!"
You are now an \s-1XML\s0 programmer! *start rejoicing now*
.SH "PROGRAMMING NOTES"
.IX Header "PROGRAMMING NOTES"
When creating a new instance of XML::EasyOBJ it will return an
object reference on success, or undef on failure. Besides that,
\&\s-1ALL\s0 methods will always return a value. This means that if you
specify an element that does not exist, it will still return an
object reference (and create that element automagically). This 
is just another way to lower the bar, and make this module easier 
to use.
.PP
You will run into problems if you have \s-1XML\s0 tags which are named
after perl's special subroutine names (i.e. \*(L"\s-1DESTROY\s0\*(R", \*(L"\s-1AUTOLOAD\s0\*(R"), 
or if they are named after subroutines used in the module 
( \*(L"getString\*(R", \*(L"getAttr\*(R", etc ). You can get around this by using
the \fIgetElement()\fR method of using the \fIremapMethod()\fR method which can
be used on every object method (except \s-1AUTOLOAD\s0 and \s-1DESTROY\s0).
.SH "AUTHOR/COPYRIGHT"
.IX Header "AUTHOR/COPYRIGHT"
Copyright (C) 2000\-2002 Robert Hanson <rhanson@blast.net>
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1XML::DOM\s0