GNU.WIKI: The GNU/Linux Knowledge Base

  [HOME] [PHP Manual] [HowTo] [ABS] [MAN1] [MAN2] [MAN3] [MAN4] [MAN5] [MAN6] [MAN7] [MAN8] [MAN9]

  [0-9] [Aa] [Bb] [Cc] [Dd] [Ee] [Ff] [Gg] [Hh] [Ii] [Jj] [Kk] [Ll] [Mm] [Nn] [Oo] [Pp] [Qq] [Rr] [Ss] [Tt] [Uu] [Vv] [Ww] [Xx] [Yy] [Zz]


NAME

       XML::Mini::Element - Perl implementation of the XML::Mini Element API.

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();

       The code above would output:

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

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.

       A Element has:

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

   new NAME
       Creates a new instance of XML::Mini::Element, with name NAME

   name [NEWNAME]
       If a NEWNAME string is passed, the Element's name is set to NEWNAME.

       Returns the element's name.

   attribute NAME [SETTO [SETTOALT]]
       The attribute() method is used to get and set the Element's attributes
       (ie the name/value pairs contained within the tag, <tagname
       attrib1="value1" attrib2="value2">)

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

       If the optional SETTOALT is passed and SETTO is false, the attribute's
       value is set to SETTOALT.  This is useful in cases when you wish to set
       the attribute to a default value if no SETTO is present, eg
       $myelement->attribute('href', $theHref, 'http://psychogenic.com') will
       default to 'http://psychogenic.com'.

       Returns the value associated with attribute NAME.

   text [SETTO [SETTOALT]]
       The text() 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).

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

   numeric [SETTO [SETTOALT]]
       The numeric() method is used to get or append numeric data to this
       element (it is 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.  See the attribute() method for an example
       use.

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

       Note: ONLY numerical contents are included from the list of child
       XML::MiniNodes.

   header NAME
       The header() method allows you to 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.
       Attributes may be set using 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.

   comment CONTENTS
       The comment() method allows you to 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 will 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 it's child
       Elements, recursively).

   getElement NAME [POSITION]
       Searches the element and it's children for an element with name NAME.

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

       NOTE: The search is performed 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 it's 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).  Thus, on 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'.

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

       BUT be careful:      $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.

       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 would 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,
       these are not part of the returned list.

   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

   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

        $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 (will apply to all children
       added with createChild())

   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,
       thus it will appear first in the XML output.

       Returns a reference to the prepended child element.

       See the note about creating loops in the above appendChild()
       description.

   insertChild CHILDELEMENT INDEX
       Inserts the child element at a specific location in this elements 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.

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

       Returns the child element that was removed, else undef.

   removeAllChildren
       Clears the element's list of child elements.  Returns an array ref of
       child elements that were removed.

   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 parent() method or automatically if
       $XML::Mini::AutoSetParent is true (set to false by default).

   parent NEWPARENT
       The parent() method is used to get/set the element's parent.

       If the NEWPARENT parameter is passed, sets the parent to NEWPARENT
       (NEWPARENT must be an instance of Element)

       Returns a reference to the parent Element if set, NULL otherwise.

       Note: This method is mainly used internally and you wouldn't normally
       need to use it.  It get's called on element appends when
       $XML::Mini::AutoSetParent or $XML::Mini::AvoidLoops or avoidLoops() > 0

   avoidLoops SETTO
       The avoidLoops() method is used to get or set the avoidLoops flag for
       this element.

       When avoidLoops is true, children with parents already set can NOT be
       appended to any other elements.  This is overkill but it is a quick and
       easy way to avoid infinite loops in the heirarchy.

       The avoidLoops default behavior is configured with the
       $XML::Mini::AvoidLoops variable but can be set on individual elements
       (and automagically 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 based on the element's attributes, and
       content (recursively doing the same for all children)

       The optional SPACEOFFSET parameter sets the number of spaces to use
       after newlines for elements at this level (adding 1 space per level in
       depth).  SPACEOFFSET defaults to 0.

       If SPACEOFFSET is passed as $XML::Mini::NoWhiteSpaces no 
 or
       whitespaces will be inserted in the xml string (ie it will all be on a
       single line with no spaces between the tags.

       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 is used
       internally when appending text() and such data.

   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 is used
       internally when appending text() and such data.

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.

       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

       XML::Mini, XML::Mini::Document

       http://minixml.psychogenic.com



  All copyrights belong to their respective owners. Other content (c) 2014-2018, GNU.WIKI. Please report site errors to webmaster@gnu.wiki.
Page load time: 0.084 seconds. Last modified: November 04 2018 12:49:43.