GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  XML::MYXML (3)

.ds Aq ’

NAME

XML::MyXML - A simple-to-use XML module, for parsing and creating XML documents

CONTENTS

VERSION

version 0.9008

SYNOPSIS



    use XML::MyXML qw(tidy_xml xml_to_object);
    use XML::MyXML qw(:all);

    my $xml = "<item><name>Table</name><price><usd>10.00</usd><eur>8.50</eur></price></item>";
    print tidy_xml($xml);

    my $obj = xml_to_object($xml);
    print "Price in Euros = " . $obj->path(price/eur)->value;

    $obj->simplify is hashref { item => { name => Table, price => { usd => 10.00, eur => 8.50 } } }
    $obj->simplify({ internal => 1 }) is hashref { name => Table, price => { usd => 10.00, eur => 8.50 } }



EXPORTABLE

xml_escape, tidy_xml, xml_to_object, object_to_xml, simple_to_xml, xml_to_simple, check_xml

FEATURES & LIMITATIONS

This module can parse XML comments, CDATA sections, XML entities (the standard five and numeric ones) and simple non-recursive <!ENTITY>s

It will ignore (won’t parse) <!DOCTYPE...>, <?...?> and other <!...> special markup

XML documents passed as parameters to this module’s functions must be strings containing bytes/octets, rather than contain characters. They also must be UTF-8 encoded unless an encoding is declared in the initial XML declaration <?xml ... ?> of the document. All XML documents produced by this module will be UTF-8 encoded (bytes/octets). However all other strings which are output by this module’s functions and methods (and which are not XML documents) will contain characters rather than bytes/octets.

XML documents to be parsed may not contain the > character unencoded in attribute values

OPTIONAL FUNCTION FLAGS

Some functions and methods in this module accept optional flags, listed under each function in the documentation. They are optional, default to zero unless stated otherwise, and can be used as follows: function_name( $param1, { flag1 => 1, flag2 => 1 } ). This is what each flag does:

strip : the function will strip initial and ending whitespace from all text values returned

file : the function will expect the path to a file containing an XML document to parse, instead of an XML string

complete : the function’s XML output will include an XML declaration (<?xml ... ?>) in the beginning

internal : the function will only return the contents of an element in a hashref instead of the element itself (see SYNOPSIS for example)

tidy : the function will return tidy XML

indentstring : when producing tidy XML, this denotes the string with which child elements will be indented (Default is the ’tab’ character)

save : the function (apart from doing what it’s supposed to do) will also save its XML output in a file whose path is denoted by this flag

strip_ns : strip the namespaces (characters up to and including ’:’) from the tags

xslt : will add a <?xml-stylesheet?> link in the XML that’s being output, of type ’text/xsl’, pointing to the filename or URL denoted by this flag

arrayref : the function will create a simple arrayref instead of a simple hashref (which will preserve order and elements with duplicate tags)

FUNCTIONS

    xml_escape($string)

Returns the same string, but with the <, >, &, " and characters replaced by their XML entities (e.g. &).

    tidy_xml($raw_xml)

Returns the XML string in a tidy format (with tabs & newlines)

Optional flags: file, complete, indentstring, save

    xml_to_object($raw_xml)

Creates an ’XML::MyXML::Object’ object from the raw XML provided

Optional flags: file

    object_to_xml($object)

Creates an XML string from the ’XML::MyXML::Object’ object provided

Optional flags: complete, tidy, indentstring, save

    simple_to_xml($simple_array_ref)

Produces a raw XML string from either an array reference, a hash reference or a mixed structure such as these examples:



    { thing => { name => John, location => { city => New York, country => U.S.A. } } }
    [ thing => [ name => John, location => [ city => New York, country => U.S.A. ] ] ]
    { thing => { name => John, location => [ city => New York, city => Boston, country => U.S.A. ] } }



All the strings in $simple_array_ref need to contain characters, rather than bytes/octets. The XML output of this function however will be a UTF-8 encoded string (i.e. will contain bytes/octets).

Optional flags: complete, tidy, indentstring, save, xslt

    xml_to_simple($raw_xml)

Produces a very simple hash object from the raw XML string provided. An example hash object created thusly is this: { thing => { name => John, location => { city => New York, country => U.S.A. } } }

Since the object created is a hashref, duplicate keys will be discarded. WARNING: This function only works on very simple XML strings, i.e. children of an element may not consist of both text and elements (child elements will be discarded in that case)

All strings contained in the output simple structure, will contain characters rather than octets/bytes.

Optional flags: internal, strip, file, strip_ns, arrayref

    check_xml($raw_xml)

Returns true if the $raw_xml string is valid XML (valid enough to be used by this module), and false otherwise.

Optional flags: file

OBJECT METHODS

CW$obj->path(‘‘subtag1/subsubtag2[attr1=val1][attr2]/.../subsubsubtagX’’)

Returns the element specified by the path as an XML::MyXML::Object object. When there are more than one tags with the specified name in the last step of the path, it will return all of them as an array. In scalar context will only return the first one. Simple CSS3-style attribute selectors are allowed in the path next to the tagnames, for example: p[class=big] will only return <p> elements that contain an attribute called class with a value of big. p[class] on the other hand will return p elements having a class attribute, but that attribute can have any value.

An example... To print the last names of all the students from the following XML, do:



    my $xml = <<EOB;
    <people>
        <student>
            <name>
                <first>Alex</first>
                <last>Karelas</last>
            </name>
        </student>
        <student>
            <name>
                <first>John</first>
                <last>Doe</last>
            </name>
        </student>
        <teacher>
            <name>
                <first>Mary</first>
                <last>Poppins</last>
            </name>
        </teacher>
        <teacher>
            <name>
                <first>Peter</first>
                <last>Gabriel</last>
            </name>
        </teacher>
    </people>
    EOB
   
    my $obj = xml_to_object($xml);
    my @students = $obj->path(student);
    foreach my $student (@students) {
        print $student->path(name/last)->value, "\n";
    }



If you wish to describe the root element in the path as well, prepend it in the path with a slash like so:



    if( $student->path(/student/name/last)->value eq $student->path(name/last)->value ) {
        print "The two are identical", "\n";
    }



CW$obj->value

When the element represented by the $obj object has only text contents, returns those contents as a string. If the $obj element has no contents, value will return an empty string.

Optional flags: strip

CW$obj->attr(’attrname’ [, ’attrvalue’])

Gets/Sets the value of the ’attrname’ attribute of the top element. Returns undef if attribute does not exist. If called without the ’attrname’ paramter, returns a hash with all attribute => value pairs. If setting with an attrvalue of undef, then removes that attribute entirely.

Input parameters and output are all in character strings, rather than octets/bytes.

Optional flags: none

CW$obj->tag

Returns the tag of the $obj element. E.g. if $obj represents an <rss:item> element, $obj->tag will return the string ’rss:item’. Returns undef if $obj doesn’t represent a tag.

Optional flags: strip_ns

CW$obj->simplify

Returns a very simple hashref, like the one returned with &XML::MyXML::xml_to_simple. Same restrictions and warnings apply.

Optional flags: internal, strip, strip_ns, arrayref

CW$obj->to_xml

Returns the XML string of the object, just like calling object_to_xml( $obj )

Optional flags: complete, tidy, indentstring, save

CW$obj->to_tidy_xml

Returns the XML string of the object in tidy form, just like calling tidy_xml( object_to_xml( $obj ) )

Optional flags: complete, indentstring, save

BUGS

If you have a Github account, report your issues at <https://github.com/akarelas/xml-myxml/issues>. I will be notified, and then you’ll automatically be notified of progress on your bug as I make changes.

AUTHOR

Alexander Karelas <karjala@karjala.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Alexander Karelas.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 XML::MYXML (3) 2016-03-31

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.