.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" 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" '' . ds C` . ds C' '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 >0, 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. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "XML::Mini::Element 3pm" .TH XML::Mini::Element 3pm "2022-10-15" "perl v5.34.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::Mini::Element \- Perl implementation of the XML::Mini Element API. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use XML::Mini::Document; \& \& my $xmlDoc = XML::Mini::Document\->new(); \& \& # Fetch the ROOT element for the document \& # (an instance of XML::Mini::Element) \& my $xmlElement = $xmlDoc\->getRoot(); \& \& # Create an tag \& my $xmlHeader = $xmlElement\->header(\*(Aqxml\*(Aq); \& \& # add the version to get \& $xmlHeader\->attribute(\*(Aqversion\*(Aq, \*(Aq1.0\*(Aq); \& \& # Create a sub element \& my $newChild = $xmlElement\->createChild(\*(Aqmychild\*(Aq); \& \& $newChild\->text(\*(Aqhello mommy\*(Aq); \& \& \& # Create an orphan element \& \& my $orphan = $xmlDoc\->createElement(\*(Aqannie\*(Aq); \& \& $orphan\->attribute(\*(Aqhair\*(Aq, \*(Aq#ff0000\*(Aq); \& $orphan\->text(\*(Aqtomorrow, tomorrow\*(Aq); \& \& # Adopt the orphan \& $newChild\->appendChild($orphan); \& \& \& # ... \& # add a child element to the front of the list \& $xmlElement\->prependChild($otherElement); \& \& print $xmlDoc\->toString(); .Ve .PP The code above would output: .PP hello mommy tomorrow, tomorrow .SH "DESCRIPTION" .IX Header "DESCRIPTION" Although the main handle to the xml document is the XML::Mini::Document object, much of the functionality and manipulation involves interaction with Element objects. .PP A Element has: .PP .Vb 4 \& \- a name \& \- a list of 0 or more attributes (which have a name and a value) \& \- a list of 0 or more children (Element or XML::MiniNode objects) \& \- a parent (optional, only if MINIXML_AUTOSETPARENT > 0) .Ve .SS "new \s-1NAME\s0" .IX Subsection "new NAME" Creates a new instance of XML::Mini::Element, with name \s-1NAME\s0 .SS "name [\s-1NEWNAME\s0]" .IX Subsection "name [NEWNAME]" If a \s-1NEWNAME\s0 string is passed, the Element's name is set to \s-1NEWNAME.\s0 .PP Returns the element's name. .SS "attribute \s-1NAME\s0 [\s-1SETTO\s0 [\s-1SETTOALT\s0]]" .IX Subsection "attribute NAME [SETTO [SETTOALT]]" The \fBattribute()\fR method is used to get and set the Element's attributes (ie the name/value pairs contained within the tag, ) .PP If \s-1SETTO\s0 is passed, the attribute's value is set to \s-1SETTO.\s0 .PP If the optional \s-1SETTOALT\s0 is passed and \s-1SETTO\s0 is false, the attribute's value is set to \s-1SETTOALT.\s0 This is useful in cases when you wish to set the attribute to a default value if no \s-1SETTO\s0 is present, eg \f(CW$myelement\fR\->attribute('href', \f(CW$theHref\fR, 'http://psychogenic.com') will default to 'http://psychogenic.com'. .PP Returns the value associated with attribute \s-1NAME.\s0 .SS "text [\s-1SETTO\s0 [\s-1SETTOALT\s0]]" .IX Subsection "text [SETTO [SETTOALT]]" The \fBtext()\fR method is used to get or append text data to this element (it is appended to the child list as a new XML::MiniNode object). .PP If \s-1SETTO\s0 is passed, a new node is created, filled with \s-1SETTO\s0 and appended to the list of this element's children. .PP If the optional \s-1SETTOALT\s0 is passed and \s-1SETTO\s0 is false, the new node's value is set to \s-1SETTOALT.\s0 See the \fBattribute()\fR method for an example use. .PP Returns a string composed of all child XML::MiniNodes' contents. .PP Note: all the children XML::MiniNodes' contents \- including numeric nodes are included in the return string. .SS "numeric [\s-1SETTO\s0 [\s-1SETTOALT\s0]]" .IX Subsection "numeric [SETTO [SETTOALT]]" The \fBnumeric()\fR method is used to get or append numeric data to this element (it is appended to the child list as a XML::MiniNode object). .PP If \s-1SETTO\s0 is passed, a new node is created, filled with \s-1SETTO\s0 and appended to the list of this element's children. .PP If the optional \s-1SETTOALT\s0 is passed and \s-1SETTO\s0 is false, the new node's value is set to \s-1SETTOALT.\s0 See the \fBattribute()\fR method for an example use. .PP Returns a space separated string composed all child XML::MiniNodes' numeric contents. .PP Note: \s-1ONLY\s0 numerical contents are included from the list of child XML::MiniNodes. .SS "header \s-1NAME\s0" .IX Subsection "header NAME" The \fBheader()\fR method allows you to add a new XML::Mini::Element::Header to this element's list of children. .PP Headers return a string for the element's \fBtoString()\fR method. Attributes may be set using \fBattribute()\fR, to create headers like .PP Valid \s-1XML\s0 documents must have at least an 'xml' header, like: .PP Here's how you could begin creating an \s-1XML\s0 document: .PP .Vb 4 \& my $miniXMLDoc = XML::Mini::Document\->new(); \& my $xmlRootNode = $miniXMLDoc\->getRoot(); \& my $xmlHeader = $xmlRootNode\->header(\*(Aqxml\*(Aq); \& $xmlHeader\->attribute(\*(Aqversion\*(Aq, \*(Aq1.0\*(Aq); .Ve .PP This method was added in version 1.25. .SS "comment \s-1CONTENTS\s0" .IX Subsection "comment CONTENTS" The \fBcomment()\fR method allows you to add a new XML::Mini::Element::Comment to this element's list of children. .PP Comments will return a string when the element's \fBtoString()\fR method is called. .PP Returns a reference to the newly appended XML::Mini::Element::Comment .SS "docType \s-1DEFINITION\s0" .IX Subsection "docType DEFINITION" Append a new element as a child of this element. .PP Returns the appended \s-1DOCTYPE\s0 element. You will normally use the returned element to add \s-1ENTITY\s0 elements, like .PP .Vb 2 \& my $newDocType = $xmlRoot\->docType(\*(Aqspec SYSTEM "spec.dtd"\*(Aq); \& $newDocType\->entity(\*(Aqdoc.audience\*(Aq, \*(Aqpublic review and discussion\*(Aq); .Ve .SS "entity \s-1NAME VALUE\s0" .IX Subsection "entity NAME VALUE" Append a new element as a child of this element. .PP Returns the appended \s-1ENTITY\s0 element. .SS "cdata \s-1CONTENTS\s0" .IX Subsection "cdata CONTENTS" Append a new element as a child of this element. Returns the appended \s-1CDATA\s0 element. .SS "getValue" .IX Subsection "getValue" Returns a string containing the value of all the element's child XML::MiniNodes (and all the XML::MiniNodes contained within it's child Elements, recursively). .SS "getElement \s-1NAME\s0 [\s-1POSITION\s0]" .IX Subsection "getElement NAME [POSITION]" Searches the element and it's children for an element with name \s-1NAME.\s0 .PP Returns a reference to the first Element with name \s-1NAME,\s0 if found, \s-1NULL\s0 otherwise. .PP \&\s-1NOTE:\s0 The search is performed like this, returning the first element that matches: .PP .Vb 4 \& \- Check this element\*(Aqs immediate children (in order) for a match. \& \- Ask each immediate child (in order) to Element::getElement() \& (each child will then proceed similarly, checking all it\*(Aqs immediate \& children in order and then asking them to getElement()) .Ve .PP If a numeric \s-1POSITION\s0 parameter is passed, \fBgetElement()\fR will return the POSITIONth element of name \s-1NAME\s0 (starting at 1). Thus, on document .PP .Vb 12 \& \& \& \& bob \& \& \& jane \& \& \& ralph \& \& .Ve .PP \&\f(CW$people\fR\->getElement('person') will return the element containing the text node \&'bob', while \f(CW$people\fR\->getElement('person', 3) will return the element containing the text 'ralph'. .SS "getElementByPath \s-1PATH\s0 [\s-1POSITIONSARRAY\s0]" .IX Subsection "getElementByPath PATH [POSITIONSARRAY]" Attempts to return a reference to the (first) element at \s-1PATH\s0 where \s-1PATH\s0 is the path in the structure (relative to this element) to the requested element. .PP For example, in the document represented by: .PP .Vb 10 \& \& \& \& \& \& \& DA42 \& \& \& D99983FFF \& \& \& ss\-839uent \& \& \& \& \& $partRate = $xmlDocument\->getElement(\*(AqpartRateRequest\*(Aq); \& \& $accessid = $partRate\->getElementByPath(\*(Aqvendor/accessid\*(Aq); .Ve .PP Will return what you expect (the accessid element with attributes user = \*(L"myusername\*(R" and password = \*(L"mypassword\*(R"). .PP \&\s-1BUT\s0 be careful: \f(CW$accessid\fR = \f(CW$partRate\fR\->getElementByPath('partList/partNum'); .PP will return the partNum element with the value \*(L"\s-1DA42\*(R".\s0 To access other partNum elements you must either use the \s-1POSITIONSARRAY\s0 or the \fBgetAllChildren()\fR method on the partRateRequest element. .PP \&\s-1POSITIONSARRAY\s0 functions like the \s-1POSITION\s0 parameter to \fBgetElement()\fR, but instead of specifying the position of a single element, you must indicate the position of all elements in the path. Therefore, to get the third part number element, you would use .PP .Vb 1 \& my $thirdPart = $xmlDocument\->getElementByPath(\*(AqpartRateRequest/partList/partNum\*(Aq, 1, 1, 3); .Ve .PP The additional 1,1,3 parameters indicate that you wish to retrieve the 1st partRateRequest element in the document, the 1st partList child of partRateRequest and the 3rd partNum child of the partList element (in this instance, the partNum element that contains 'ss\-839uent'). .PP Returns the Element reference if found, \s-1NULL\s0 otherwise. .SS "getAllChildren [\s-1NAME\s0]" .IX Subsection "getAllChildren [NAME]" Returns a reference to an array of all this element's Element children .PP Note: although the Element may contain XML::MiniNodes as children, these are not part of the returned list. .SS "createChild \s-1ELEMENTNAME\s0 [\s-1VALUE\s0]" .IX Subsection "createChild ELEMENTNAME [VALUE]" Creates a new Element instance and appends it to the list of this element's children. The new child element's name is set to \s-1ELEMENTNAME.\s0 .PP If the optional \s-1VALUE\s0 (string or numeric) parameter is passed, the new element's text/numeric content will be set using \s-1VALUE.\s0 .PP Returns a reference to the new child element .SS "appendChild \s-1CHILDELEMENT\s0" .IX Subsection "appendChild CHILDELEMENT" appendChild is used to append an existing Element object to this element's list. .PP Returns a reference to the appended child element. .PP \&\s-1NOTE:\s0 Be careful not to create loops in the hierarchy, eg .PP .Vb 3 \& $parent\->appendChild($child); \& $child\->appendChild($subChild); \& $subChild\->appendChild($parent); .Ve .PP If you want to be sure to avoid loops, set the \s-1MINIXML_AVOIDLOOPS\s0 define to 1 or use the \fBavoidLoops()\fR method (will apply to all children added with \fBcreateChild()\fR) .SS "prependChild \s-1CHILDELEMENT\s0" .IX Subsection "prependChild CHILDELEMENT" prependChild is used to add an existing Element object to this element's list. The added \s-1CHILDELEMENT\s0 will be prepended to the list, thus it will appear first in the \s-1XML\s0 output. .PP Returns a reference to the prepended child element. .PP See the note about creating loops in the above \fBappendChild()\fR description. .SS "insertChild \s-1CHILDELEMENT INDEX\s0" .IX Subsection "insertChild CHILDELEMENT INDEX" Inserts the child element at a specific location in this elements list of children. .PP If \s-1INDEX\s0 is larger than \fBnumChildren()\fR, the \s-1CHILDELEMENT\s0 will be added to the end of the list (same as \fBappendChild()\fR ). .PP Returns the inserted child element. .SS "removeChild \s-1CHILDELEMENT\s0" .IX Subsection "removeChild CHILDELEMENT" Removes the element \s-1CHILDELEMENT\s0 from the list of this element's children, if it is found within this list. .PP Returns the child element that was removed, else undef. .SS "removeAllChildren" .IX Subsection "removeAllChildren" Clears the element's list of child elements. Returns an array ref of child elements that were removed. .SS "remove" .IX Subsection "remove" Removes this element from it's parent's list of children. The parent must be set for the element for this method to work \- this can be done manually using the \fBparent()\fR method or automatically if \f(CW$XML::Mini::AutoSetParent\fR is true (set to false by default). .SS "parent \s-1NEWPARENT\s0" .IX Subsection "parent NEWPARENT" The \fBparent()\fR method is used to get/set the element's parent. .PP If the \s-1NEWPARENT\s0 parameter is passed, sets the parent to \s-1NEWPARENT\s0 (\s-1NEWPARENT\s0 must be an instance of Element) .PP Returns a reference to the parent Element if set, \s-1NULL\s0 otherwise. .PP Note: This method is mainly used internally and you wouldn't normally need to use it. It get's called on element appends when \f(CW$XML::Mini::AutoSetParent\fR or \&\f(CW$XML::Mini::AvoidLoops\fR or \fBavoidLoops()\fR > 0 .SS "avoidLoops \s-1SETTO\s0" .IX Subsection "avoidLoops SETTO" The \fBavoidLoops()\fR method is used to get or set the avoidLoops flag for this element. .PP When avoidLoops is true, children with parents already set can \s-1NOT\s0 be appended to any other elements. This is overkill but it is a quick and easy way to avoid infinite loops in the heirarchy. .PP The avoidLoops default behavior is configured with the \f(CW$XML::Mini::AvoidLoops\fR variable but can be set on individual elements (and automagically all the element's children) with the \&\fBavoidLoops()\fR method. .PP Returns the current value of the avoidLoops flag for the element. .SS "toString [\s-1SPACEOFFSET\s0]" .IX Subsection "toString [SPACEOFFSET]" toString returns an \s-1XML\s0 string based on the element's attributes, and content (recursively doing the same for all children) .PP The optional \s-1SPACEOFFSET\s0 parameter sets the number of spaces to use after newlines for elements at this level (adding 1 space per level in depth). \s-1SPACEOFFSET\s0 defaults to 0. .PP If \s-1SPACEOFFSET\s0 is passed as \f(CW$XML::Mini::NoWhiteSpaces\fR no \en or whitespaces will be inserted in the xml string (ie it will all be on a single line with no spaces between the tags. .PP Returns the \s-1XML\s0 string. .SS "createNode \s-1NODEVALUE\s0" .IX Subsection "createNode NODEVALUE" Private (?) .PP Creates a new XML::MiniNode instance and appends it to the list of this element's children. The new child node's value is set to \s-1NODEVALUE.\s0 .PP Returns a reference to the new child node. .PP Note: You don't need to use this method normally \- it is used internally when appending \fBtext()\fR and such data. .SS "appendNode \s-1CHILDNODE\s0" .IX Subsection "appendNode CHILDNODE" appendNode is used to append an existing XML::MiniNode object to this element's list. .PP Returns a reference to the appended child node. .PP Note: You don't need to use this method normally \- it is used internally when appending \fBtext()\fR and such data. .SH "AUTHOR" .IX Header "AUTHOR" Copyright (C) 2002\-2008 Patrick Deegan, Psychogenic Inc. .PP Programs that use this code are bound to the terms and conditions of the \s-1GNU GPL\s0 (see the \s-1LICENSE\s0 file). If you wish to include these modules in non-GPL code, you need prior written authorisation from the authors. .PP This library is released under the terms of the \s-1GNU GPL\s0 version 3, making it available only for free programs (\*(L"free\*(R" here being used in the sense of the \s-1GPL,\s0 see http://www.gnu.org for more details). Anyone wishing to use this library within a proprietary or otherwise non-GPLed program \s-1MUST\s0 contact psychogenic.com to acquire a distinct license for their application. This approach encourages the use of free software while allowing for proprietary solutions that support further development. .SS "\s-1LICENSE\s0" .IX Subsection "LICENSE" .Vb 3 \& XML::Mini::Element module, part of the XML::Mini XML parser/generator package. \& Copyright (C) 2002\-2008 Patrick Deegan \& All rights reserved \& \& XML::Mini is free software: you can redistribute it and/or modify \& it under the terms of the GNU General Public License as published by \& the Free Software Foundation, either version 3 of the License, or \& (at your option) any later version. \& \& XML::Mini is distributed in the hope that it will be useful, \& but WITHOUT ANY WARRANTY; without even the implied warranty of \& MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the \& GNU General Public License for more details. \& \& You should have received a copy of the GNU General Public License \& along with XML::Mini. If not, see . .Ve .PP Official XML::Mini site: http://minixml.psychogenic.com .PP Contact page for author available on http://www.psychogenic.com/ .SH "SEE ALSO" .IX Header "SEE ALSO" XML::Mini, XML::Mini::Document .PP http://minixml.psychogenic.com