xml_escape($string)

tidy_xml($raw_xml)

Optional flags: "file", "complete", "indentstring", "save", "bytes"

xml_to_object($raw_xml)

Optional flags: "file", "bytes"

object_to_xml($object)

Optional flags: "complete", "tidy", "indentstring", "save", "bytes"

simple_to_xml($simple_array_ref)

    { thing => { name => 'John', location => { city => 'New York', country => 'U.S.A.' } } }
    # <thing><name>John</name><location><country>U.S.A.</country><city>New York</city></location></thing>

    [ thing => [ name => 'John', location => [ city => 'New York', country => 'U.S.A.' ] ] ]
    # <thing><name>John</name><location><country>U.S.A.</country><city>New York</city></location></thing>

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

Here's a mini-tutorial on how to use this function, in which you'll also see how to set attributes.

The simplest invocations are these:

    simple_to_xml({target => undef})
    # <target/>

    simple_to_xml({target => 123})
    # <target>123</target>

Every set of sibling elements (such as the document itself, which is a single top-level element, or a pack of 5 elements all children to the same parent element) is represented in the $simple_array_ref parameter as key-value pairs inside either a hashref or an arrayref (you can choose which).

Keys represent tags+attributes of the sibling elements, whereas values represent the contents of those elements.

Eg:

    [
        first => 'John',
        last => 'Doe,'
    ]

...and...

    {
        first => 'John',
        last => 'Doe',
    }

both translate to:

    <first>John</first><last>Doe</last>

A value can either be undef (to denote an empty element), or a string (to denote a string), or another hashref/arrayref to denote a set of children elements, like this:

    {
        person => {
            name => {
                first => 'John',
                last => 'Doe'
            }
        }
    }

...becomes:

    <person>
        <name>
            <first>John</first>
            <last>Doe</last>
        </name>
    </person>

The only difference between using an arrayref or using a hashref, is that arrayrefs preserve the order of the elements, and allow repetition of identical tags. So a person with many addresses, should choose to represent its list of addresses under an arrayref, like this:

    {
        person => [
            name => {
                first => 'John',
                last => 'Doe',
            },
            address => {
                country => 'Malta',
            },
            address => {
                country => 'Indonesia',
            },
            address => {
                country => 'China',
            }
        ]
    }

...which becomes:

    <person>
        <name>
            <last>Doe</last>
            <first>John</first>
        </name>
        <address>
            <country>Malta</country>
        </address>
        <address>
            <country>Indonesia</country>
        </address>
        <address>
            <country>China</country>
        </address>
    </person>

Finally, to set attributes to your elements (eg id="12") you need to replace the key with either a string containing attributes as well (eg: 'address id="12"'), or replace it with a reference, as the many items in the examples below:

    {thing => [
        'item id="1"' => 'chair',
        [item => {id => 2}] => 'table',
        [item => [id => 3]] => 'door',
        [item => id => 4] => 'sofa',
        {item => {id => 5}} => 'bed',
        {item => [id => 6]} => 'shirt',
        [item => {id => 7, other => 8}, [more => 9, also => 10, but_not => undef]] => 'towel'
    ]}

...which becomes:

    <thing>
        <item id="1">chair</item>
        <item id="2">table</item>
        <item id="3">door</item>
        <item id="4">sofa</item>
        <item id="5">bed</item>
        <item id="6">shirt</item>
        <item id="7" other="8" more="9" also="10">towel</item>
    </thing>

As you see, attributes may be represented in a great variety of ways, so you don't need to remember the "correct" one.

Of course if the "simple structure" is a hashref, the key cannot be a reference (because hash keys are always strings), so if you want attributes on your elements, you either need the enclosing structure to be an arrayref as in the example above, to allow keys to be refs which contain the attributes, or you need to represent the key (=tag+attrs) as a string, like this (also in the previous example): 'item id="1"'

This concludes the mini-tutorial of the simple_to_xml function.

All the strings in $simple_array_ref need to contain characters, rather than bytes/octets. The "bytes" optional flag only affects the produced XML string.

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

xml_to_simple($raw_xml)

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). Also attributes in tags are ignored.

Since the object created is a hashref (unless used with the "arrayref" optional flag), duplicate keys will be discarded.

All strings contained in the output simple structure will always contain characters rather than octets/bytes, regardless of the "bytes" optional flag.

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

check_xml($raw_xml)

Optional flags: "file", "bytes"

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

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";
    }

...or like this...

    my @last = $obj->path('student/name/last');
    foreach my $last (@last) {
        print $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";
    }

Since XML::MyXML version 1.08, the path method supports namespaces.

You can replace the namespace prefix of an attribute or an element name in the path string with the namespace name inside curly brackets, and place the curly-bracketed expression after the local part.

Example #1: Suppose the XML you want to go through is:

    <stream:stream xmlns:stream="http://foo/bar">
        <a>b</a>
    </stream:stream>

Then this will return the string "b":

    $obj->path('/stream{http://foo/bar}/a')->value;

Example #2: Suppose the XML you want to go through is:

    <stream xmlns="http://foo/bar">
        <a>b</a>
    </stream>

Then both of these expressions will return "b":

    $obj->path('/stream/a{http://foo/bar}')->value;
    $obj->path('/stream{http://foo/bar}/a{http://foo/bar}')->value;

Since XML::MyXML version 1.08, quotes in attribute match strings have no special meaning.

If you want to use the "]" character in attribute values, you need to escape it with a backslash character. As you need if you want to use the "}" character in a namespace value in the path string.

Example #1: Suppose the XML you want to go through is:

    <stream xmlns:o="http://foo}bar">
        <a o:name="c]d">b</a>
    </stream>

Then this expression will return "b":

    $obj->path('/stream/a[name{http://foo\}bar}=c\]d]')->value;

Example #2: You can match attribute values containing quote characters with just """ in the path string.

If the XML is:

    <stream id="&quot;1&quot;">a</stream>

...then this will return the string "a":

    $obj->path('/stream[id="1"]')->value;

Optional flags: none

$obj->text([set_value]), also known as $obj->value([set_value])

Optional flags: "strip"

$obj->inner_xml([xml_string])

Optional flags: "bytes"

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

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

Optional flags: none

$obj->tag

Optional flags: "strip_ns"

$obj->name

$obj->parent

Optional flags: none

$obj->simplify

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

$obj->to_xml

Optional flags: "complete", "tidy", "indentstring", "save", "bytes"

$obj->to_tidy_xml

Optional flags: "complete", "indentstring", "save", "bytes"