XML::M...lement(3pm)

📦
version 1.38 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

✨ XML::Mini::Element ✨

okay bestie, buckle up 💖 this is the XML::Mini::Element page from the User Contributed Perl Documentation (perl manpage, section 3pm), and it's literally the whole element API. it's long so we're doing it in parts — this is part 1, more coming, don't go anywhere 🫶

💅 NAME 💅

XML::Mini::Element — the Perl implementation of the XML::Mini Element API. that's the whole name. iconic.

🌸 SYNOPSIS 🌸

        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 <?xml?> tag
        my $xmlHeader = $xmlElement->header('xml');

        # add the version to get <?xml version="1.0"?>
        $xmlHeader->attribute('version', '1.0');

        # Create a sub element
        my $newChild = $xmlElement->createChild('mychild');

        $newChild->text('hello mommy');

        # Create an orphan element

        my $orphan = $xmlDoc->createElement('annie');

        $orphan->attribute('hair', '#ff0000');
        $orphan->text('tomorrow, tomorrow');

        # Adopt the orphan
        $newChild->appendChild($orphan);

        # ...
        # add a child element to the front of the list
        $xmlElement->prependChild($otherElement);

        print $xmlDoc->toString();

and bestie, that code right there outputs EXACTLY this:

<?xml version="1.0" ?>
 <mychild>
  hello mommy
  <annie hair="#ff0000">
   tomorrow, tomorrow
  </annie>
 </mychild>

no cap, that's the glow-up 🌈

🦋 DESCRIPTION 🦋

so, the main character handle to your xml document is the XML::Mini::Document object — but here's the tea: a ton of the actual functionality and manipulation is you interacting with Element objects. the Document is the director, the Elements are the cast 💅

an Element has:

  • a name
  • a list of 0 or more attributes (and each attribute has 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)

🎀 new NAME 🎀

Creates a brand new instance of XML::Mini::Element, with name NAME. baby's first element ✨

🎀 name [NEWNAME] 🎀

If a NEWNAME string gets passed in, the Element's name is set to NEWNAME.

Returns the element's name.

🎀 attribute NAME [SETTO [SETTOALT]] 🎀

The attribute() method is your getter and your setter for the Element's attributes — iykyk, those are the name/value pairs chillin' inside the tag, like <tagname attrib1="value1" attrib2="value2">.

If SETTO is passed, the attribute's value gets set to SETTO.

If the optional SETTOALT is passed and SETTO is false, the attribute's value is set to SETTOALT. this is lowkey perfect for when you want a default value if no SETTO is around, eg $myelement->attribute('href', $theHref, 'http://psychogenic.com') will default to 'http://psychogenic.com'. slay 💅

Returns the value associated with attribute NAME.

🎀 text [SETTO [SETTOALT]] 🎀

The text() method gets or appends text data to this element — and note that it gets appended to the child list as a new XML::MiniNode object.

If SETTO is passed, a new node is created, filled with SETTO, and appended to the list of this element's children.

If the optional SETTOALT is passed and SETTO is false, the new node's value is set to SETTOALT. (peep the attribute() method for an example use 👀)

Returns a string composed of all child XML::MiniNodes' contents.

Note: all the children XML::MiniNodes' contents — including numeric nodes — are included in the return string. everything, no gatekeeping.

🎀 numeric [SETTO [SETTOALT]] 🎀

The numeric() method gets or appends numeric data to this element — it gets appended to the child list as a XML::MiniNode object.

If SETTO is passed, a new node is created, filled with SETTO, and appended to the list of this element's children.

If the optional SETTOALT is passed and SETTO is false, the new node's value is set to SETTOALT. (again, see attribute() for an example use 💜)

Returns a space separated string composed of all child XML::MiniNodes' numeric contents.

Note: ONLY numerical contents are included from the list of child XML::MiniNodes. the text ones are NOT invited to this party. periodt.

🎀 header NAME 🎀

The header() method lets you add a new XML::Mini::Element::Header to this element's list of children.

Headers return a <? NAME ?> string for the element's toString() method. you can set attributes with attribute(), to create headers like <?xml-stylesheet href="doc.xsl" type="text/xsl"?>.

Valid XML documents must have at least an 'xml' header, like: <?xml version="1.0" ?>

here's how you could begin creating an XML document:

        my $miniXMLDoc =  XML::Mini::Document->new();
        my $xmlRootNode = $miniXMLDoc->getRoot();
        my $xmlHeader = $xmlRootNode->header('xml');
        $xmlHeader->attribute('version', '1.0');

This method was added in version 1.25. a legend 🫶

🎀 comment CONTENTS 🎀

The comment() method lets you add a new XML::Mini::Element::Comment to this element's list of children.

Comments will return a <!-- CONTENTS --> string when the element's toString() method is called.

Returns a reference to the newly appended XML::Mini::Element::Comment.

🎀 docType DEFINITION 🎀

Append a new <!DOCTYPE DEFINITION [ ...]> element as a child of this element.

Returns the appended DOCTYPE element. you'll normally use the returned element to add ENTITY elements, like

 my $newDocType = $xmlRoot->docType('spec SYSTEM "spec.dtd"');
 $newDocType->entity('doc.audience', 'public review and discussion');

🎀 entity NAME VALUE 🎀

Append a new <!ENTITY NAME "VALUE"> element as a child of this element.

Returns the appended ENTITY element.

🎀 cdata CONTENTS 🎀

Append a new <![CDATA[ CONTENTS ]]> element as a child of this element. Returns the appended CDATA element.

🎀 getValue 🎀

Returns a string containing the value of all the element's child XML::MiniNodes (and all the XML::MiniNodes contained within its child Elements, recursively). it goes deep. main character energy, honestly 🔥

🎀 getElement NAME [POSITION] 🎀

Searches the element and its children for an element with name NAME.

Returns a reference to the first Element with name NAME if found, NULL otherwise.

NOTE: the search happens like this, returning the first element that matches: - Check this element's immediate children (in order) for a match. - Ask each immediate child (in order) to Element::getElement() (each child will then proceed similarly, checking all its immediate children in order and then asking them to getElement())

If a numeric POSITION parameter is passed, getElement() will return the POSITIONth element of name NAME (starting at 1). so, on this document:

  <?xml version="1.0"?>
  <people>
   <person>
    bob
   </person>
   <person>
    jane
   </person>
   <person>
    ralph
   </person>
  </people>

$people->getElement('person') will return the element containing the text node 'bob', while $people->getElement('person', 3) will return the element containing the text 'ralph'. found your fave by number 💖

🎀 getElementByPath PATH [POSITIONSARRAY] 🎀

Attempts to return a reference to the (first) element at PATH, where PATH is the path in the structure (relative to this element) to the requested element.

for example, in the document represented by:

         <partRateRequest>
          <vendor>
           <accessid user="myusername" password="mypassword" />
          </vendor>
          <partList>
           <partNum>
            DA42
           </partNum>
           <partNum>
            D99983FFF
           </partNum>
           <partNum>
            ss-839uent
           </partNum>
          </partList>
         </partRateRequest>
        $partRate = $xmlDocument->getElement('partRateRequest');

        $accessid = $partRate->getElementByPath('vendor/accessid');

Will return what you expect — the accessid element with attributes user = "myusername" and password = "mypassword". ate. 💅

BUT be careful, bestie:

        $accessid = $partRate->getElementByPath('partList/partNum');

will return the partNum element with the value "DA42". to access other partNum elements you must either use the POSITIONSARRAY or the getAllChildren() method on the partRateRequest element. don't get caught lackin' 🫣

POSITIONSARRAY functions like the POSITION parameter to getElement(), 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'd use:

        my $thirdPart = $xmlDocument->getElementByPath('partRateRequest/partList/partNum', 1, 1, 3);

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').

Returns the Element reference if found, NULL otherwise.

🎀 getAllChildren [NAME] 🎀

Returns a reference to an array of all this element's Element children.

Note: although the Element may contain XML::MiniNodes as children, those are not part of the returned list. sorry nodes, not today 🌸

🎀 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 ELEMENTNAME.

If the optional VALUE (string or numeric) parameter is passed, the new element's text/numeric content will be set using VALUE.

Returns a reference to the new child element. new baby, who dis 🎀

🎀 appendChild CHILDELEMENT 🎀

appendChild is used to append an existing Element object to this element's list.

Returns a reference to the appended child element.

NOTE: be careful not to create loops in the hierarchy, eg perl $parent->appendChild($child); $child->appendChild($subChild); $subChild->appendChild($parent);

If you want to be sure to avoid loops, set the MINIXML_AVOIDLOOPS define to 1 or use the avoidLoops() method (it will apply to all children added with createChild()). protect your peace and your graph 💀

🎀 prependChild CHILDELEMENT 🎀

prependChild is used to add an existing Element object to this element's list. The added CHILDELEMENT will be prepended to the list, so it will appear first in the XML output. front of the line, main character behavior ✨

Returns a reference to the prepended child element.

See the note about creating loops in the above appendChild() description. same warning, same vibes.

🎀 insertChild CHILDELEMENT INDEX 🎀

Inserts the child element at a specific location in this element's list of children.

If INDEX is larger than numChildren(), the CHILDELEMENT will be added to the end of the list (same as appendChild()).

Returns the inserted child element. squeezing into the lineup 🧚

🎀 removeChild CHILDELEMENT 🎀

Removes the element CHILDELEMENT from the list of this element's children, if it's found within this list.

Returns the child element that was removed, else undef. it's giving "you can't sit with us" 😭

🎀 removeAllChildren 🎀

Clears the element's list of child elements. Returns an array ref of child elements that were removed. full clear-out, no survivors, but you get a lil receipt of everyone who got evicted 🌈

okay that's part 1 bestie, more parts on the way, stay tuned 💖

remove 💅

ok so remove does exactly what it says on the tin — it yeets this element out of its parent's list of children. 🫶 but bestie listen: the parent has to be set for this method to work. you can do that manually with the parent() method, or let it happen automatically if $XML::Mini::AutoSetParent is true (it's set to false by default, so don't come for me if it doesn't work).

parent NEWPARENT 🎀

parent() is your go-to for getting or setting an element's parent. it's giving "who's your mom" energy.

  • if you pass the NEWPARENT parameter, it sets the parent to NEWPARENT — and NEWPARENT must be an instance of Element, no exceptions.
  • returns a reference to the parent Element if set, NULL otherwise.
note: this method is mostly used internally and you wouldn't normally need to use it. it gets called on element appends when $XML::Mini::AutoSetParent or $XML::Mini::AvoidLoops or avoidLoops() > 0.

avoidLoops SETTO 🌀

avoidLoops() gets or sets the avoidLoops flag for this element.

when avoidLoops is true, children that already have parents set can NOT be appended to any other elements. is it overkill? yes. is it a quick and easy way to avoid infinite loops in the hierarchy? also yes. 💀

the default behavior is configured with the $XML::Mini::AvoidLoops variable, but you can set it on individual elements (and automagically on all the element's children) with the avoidLoops() method.

returns the current value of the avoidLoops flag for the element.

toString [SPACEOFFSET] ✨

toString returns an XML string built from the element's attributes and content (and it does the same recursively for all the children, slay).

the optional SPACEOFFSET parameter sets the number of spaces to use after newlines for elements at this level — and it adds 1 space per level in depth. SPACEOFFSET defaults to 0.

if SPACEOFFSET is passed as $XML::Mini::NoWhiteSpaces, no \n or whitespaces will be inserted in the xml string — so it'll all be on a single line with no spaces between the tags, periodt.

returns the XML string.

createNode NODEVALUE 🔧

Private (?) 👀

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 NODEVALUE.

returns a reference to the new child node.

note: you don't need to use this method normally — it's used internally when appending text() and such data. iykyk.

appendNode CHILDNODE 📎

appendNode is used to append an existing XML::MiniNode object to this element's list.

returns a reference to the appended child node.

note: you don't need to use this method normally — it's used internally when appending text() and such data. fr fr.

👑 AUTHOR 👑

Copyright (C) 2002-2008 Patrick Deegan, Psychogenic Inc.

programs that use this code are bound to the terms and conditions of the GNU GPL (see the LICENSE file). if you wish to include these modules in non-GPL code, you need prior written authorisation from the authors. bestie, they're serious.

this library is released under the terms of the GNU GPL version 3, making it available only for free programs ("free" here being used in the sense of the GPL, see http://www.gnu.org for more details). anyone wishing to use this library within a proprietary or otherwise non-GPLed program MUST 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. 💖

🌈 LICENSE 🌈

        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 <http://www.gnu.org/licenses/>.

official XML::Mini site: http://minixml.psychogenic.com

contact page for author available on http://www.psychogenic.com/

👀 SEE ALSO 👀

and that's the whole vibe check, bestie. this was the XML::M...lement(3pm) manpage, generated by perl v5.36.0 on 2022-10-15 — go forth and parse some XML, you iconic main character. 💅✨🦋

📦 where this page comes from