/ 
XML-Chain-0.07
⭐ Starred 0 / XML::Chain

NAME

XML::Chain - a chained way of manipulating and inspecting XML documents

SYNOPSIS

use XML::Chain qw(xc);

# basics
my $div = xc('div', class => 'pretty')
            ->c('h1')->t('hello')
            ->up
            ->c('p', class => 'intro')->t('world')
            ->root
            ->a( xc('p')->t('of chained XML.') );
say $div->as_string;
# <div class="pretty"><h1>hello</h1><p class="intro">world</p><p>of chained XML.</p></div>

my $sitemap =
    xc('urlset', xmlns => 'http://www.sitemaps.org/schemas/sitemap/0.9')
    ->t("\n")
    ->c('url')
        ->a('loc',        '-' => 'https://metacpan.org/pod/XML::Chain::Selector')
        ->a('lastmod',    '-' => DateTime->from_epoch(epoch => 1507451828)->strftime('%Y-%m-%d'))
        ->a('changefreq', '-' => 'monthly')
        ->a('priority',   '-' => '0.6')
    ->up->t("\n")
    ->c('url')
        ->a('loc',        '-' => 'https://metacpan.org/pod/XML::Chain::Element')
        ->a('lastmod',    '-' => DateTime->from_epoch(epoch => 1507279028)->strftime('%Y-%m-%d'))
        ->a('changefreq', '-' => 'monthly')
        ->a('priority',   '-' => '0.5')
    ->up->t("\n");
say $sitemap->as_string;
# <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
# <url><loc>https://metacpan.org/pod/XML::Chain::Selector</loc><lastmod>2017-10-08</lastmod><changefreq>monthly</changefreq><priority>0.6</priority></url>
# <url><loc>https://metacpan.org/pod/XML::Chain::Element</loc><lastmod>2017-10-06</lastmod><changefreq>monthly</changefreq><priority>0.5</priority></url>
# </urlset>

DESCRIPTION

This module provides a fast and easy way to create and manipulate XML elements via a set of chained method calls.

EXPORTS

xc

Exported factory method that creates a new XML::Chain::Element object with the document element provided in the parameters. For example:

my $icon = xc('i', class => 'icon-download icon-white');
# <i class="icon-download icon-white"/>

See also XML::Chain::Selector, from which XML::Chain::Element inherits all methods, for the element parameter description, and "CHAINED METHODS" in XML::Chain::Selector for methods on the returned object.

In practice, xc() accepts four input categories: a scalar element name, an XML::LibXML document or node, an existing selector/element, or some other reference that IO::Any can read and XML::LibXML can parse.

xc($el_name, @attrs) scalar with 1+ arguments

An element with $el_name will be created as the document element, and @attrs will be added to it in the same order.

If a hash reference is passed as an argument, its keys and values will be set as attributes in alphabetical key order.

The attribute name "-" is a special case, and the value will be used for text content inside the element.

xc($xml_libxml_ref)

Accepted XML::LibXML object types are:

  • XML::LibXML::Document

    The document is used directly.

  • XML::LibXML::Node

    The node is used as the document element.

    If you need custom parser behavior, parse the XML yourself with your own XML::LibXML instance and pass the resulting document or node to xc().

xc($what_ref)

Any other reference will be passed to "slurp($what)" in IO::Any, then parsed by XML::Chain's private safe default parser, and the result will be set as the document element.

The default parser disables network access, external DTD loading, automatic entity expansion, and recovery from malformed XML. If you need different parser behavior, parse the XML yourself and pass the resulting XML::LibXML::Document or XML::LibXML::Node to xc().

say xc([$tmp_dir, 't01.xml'])->as_string
say xc(\'<body><h1>and</h1><h1>head</h1></body>')
        ->find('//h1')->count

xc($scalar)

An element with $scalar will be created as the document element.

say xc('body');

CHAINED METHODS, METHODS and ELEMENT METHODS

See XML::Chain::Selector and XML::Chain::Element.

METHODS

new

Creates a new XML::Chain object. Optional named arguments is dom (an existing XML::LibXML::Document).

dom

Gets or sets the current XML::LibXML::Document instance used by the object.

CHAINED DOCUMENT METHODS

xc('body')->t('save me')->set_io_any([$tmp_dir, 't01.xml'])->store;
# $tmp_dir/t01.xml file now consists of:
    <body>save me</body>
xc([$tmp_dir, 't01.xml'])->empty->c('div')->t('updated')->store;
# $tmp_dir/t01.xml file now consists of:
    <body><div>updated</div></body>

set_io_any

Stores $what, $options for IO::Any for future use with ->store().

store

Calls IO::Any->spew($io_any, $self->as_string, {atomic => 1}) to save XML back to the target configured via set_io_any.

document_element

Returns the document root element as an XML::Chain::Element object. This is a convenience method equivalent to ->root on a selector.

my $root = $xc->document_element;

CONTRIBUTORS & CREDITS

Initially inspired by Strophe.Builder, then also by jQuery.

The following people have contributed to XML::Chain by committing their code, sending patches, reporting bugs, asking questions, suggesting useful advice, nitpicking, chatting on IRC or commenting on my blog (in no particular order):

Slaven Rezic
Vienna.pm (for listening to my talk and providing valuable feedback)
Mohammad S Anwar
AI
you?

Also thanks to https://geizhals.at/, https://www.riedellskates.eu/ and https://apa.at/.

BUGS

Please report any bugs or feature requests via https://github.com/meon/XML-Chain/issues.

AUTHOR

Jozef Kutej

COPYRIGHT & LICENSE

Copyright 2017 Jozef Kutej, all rights reserved.

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