View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Nils Diewald > XML-Loy-0.13 > XML::Loy



Annotate this POD


Open  0
View/Report Bugs
Module Version: 0.13   Source   Latest Release: XML-Loy-0.44_2


XML::Loy - Extensible XML Reader and Writer


  use XML::Loy;

  # Create new document with root node
  my $xml = XML::Loy->new('env');

  # Add elements to the document
  my $header = $xml->add('header');

  # Nest elements
  $header->add('greetings')->add(title => 'Hello!');

  # Append elements with attributes and textual data
  $xml->add(body => { date => 'today' })->add(p => "That's all!");

  # Use CSS3 selectors for element traversal
  $xml->at('title')->attrs(style => 'color: red');

  # Attach comments
  $xml->at('greetings')->comment('My Greeting');

  # Print with pretty indentation
  print $xml->to_pretty_xml;

  # <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  # <env>
  #   <header>
  #       <!-- My Greeting -->
  #       <greetings>
  #         <title style="color: red">Hello!</title>
  #       </greetings>
  #     </header>
  #     <body date="today">
  #       <p>That&#39;s all!</p>
  #     </body>
  #   </env>


XML::Loy allows for the simple creation of small serialized XML documents with various namespaces. It focuses on simplicity and extensibility, while giving you the full power of Mojo::DOM.

This module is an early release! There may be significant changes in the future.


XML::Loy inherits all explicit methods from Mojo::DOM and implements the following new ones.


  my $xml = XML::Loy->new(<<'EOF');
  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>

  $xml = XML::Loy->new('Document');
  $xml = XML::Loy->new(Document => { foo => 'bar' });
  my $xml_new = $xml->new(Document => {id => 'new'} => 'My Content');

Constructs a new XML::Loy document. Accepts either all parameters supported by Mojo::DOM or all parameters supported by add.


  my $xml = XML::Loy->new('Document');

  # Add an empty element

  # Add elements with attributes
  my $elem = $xml->add(Element => { type => 'text/plain' });

  # Add nested elements with textual content
  $elem->add(Child => "I'm a child element");

  # Add elements with attributes, textual content, and a comment
  $xml->add(p => { id => 'id_4' }, 'Hello!', 'My Comment!');

  # Add elements with rules for pretty printing
  $xml->add(Data => { -type => 'armour' }, 'PdGzjvj..');

  # Add XML::Loy objects
  $elem = $xml->new(Element => 'Hello World!');

Adds a new element to a XML::Loy document, either as another XML::Loy object or newly defined. Returns the root node of the added XML::Loy document.

Parameters to define elements are a tag name, followed by an optional hash reference including all attributes of the XML element, an optional textual content, and an optional comment on the element (if the comment should be introduced to an empty element, text content has to be undef).

For giving directives for rendering element content with pretty printing, a special -type attribute can be defined:


  my $xml = XML::Loy->new('Document');
  $xml->set(Element => { id => 5 });

  # Overwrite
  $xml->set(Element => { id => 6 });

Adds a new element as a child to the node only once. Accepts all parameters as defined in add.

If one or more elements with the same tag name are already children of the requesting node, the old elements will be deleted and comments will be merged if possible.


  $node = $node->comment('Resource Descriptor');

Prepends a comment to the current node. If a node already has a comment, comments will be merged.


  my $nr = $xml->extension('Fun', 'XML::Loy::Atom');
  my @extensions = $xml->extension;

Adds or returns an array of extensions. When adding, returns the number of successfully added extensions. When getting, returns the array of associated extensions.

With this package the following extensions are bundled: Atom, Atom-Threading, ActivityStreams, XRD, and HostMeta. See Extensions for further information.


  print $xml->mime;

The mime type associated with the object class. See Extensions for further information.


  my $xml = XML::Loy->new('doc');
  $xml->namespace(fun => '');
  $xml->add('fun:test' => { foo => 'bar' }, 'Works!');
  print $xml->namespace;

  print $xml->to_pretty_xml;

  # <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  # <doc xmlns=""
  #      xmlns:fun="">
  #   <fun:test foo="bar">Works!</fun:test>
  # </doc>

Returns the namespace of the node or adds namespace information to the node's root. When adding, the first parameter gives the prefix, the second one the namespace. The prefix parameter is optional. Namespaces are always added to the document's root, that means, they have to be unique in the scope of the whole document.


  print $xml->to_pretty_xml;
  print $xml->to_pretty_xml(2);

Returns a stringified, pretty printed XML document. Optionally accepts a numerical parameter, defining the start of indentation (defaults to 0).


  package Fun;
  use XML::Loy with => (
    prefix    => 'fun',
    namespace => '',
    mime      => 'application/fun+xml'

  # Add new methods to the object
  sub add_happy {
    my $self = shift;
    my $word = shift;

    my $cool = $self->add('-Cool');
    my $cry  = uc($word) . '!!! \o/ ';
    $cool->add(Happy => {foo => 'bar'}, $cry);

XML::Loy allows for inheritance and thus provides two ways of extending the functionality: By using a derived class as a base class or by extending a base class with the extension method.

With this package the following extensions are bundled: Atom, Atom-Threading, ActivityStreams, XRD, and HostMeta.

For the purpose of extension, three attributes can be set when XML::Loy is used (introduced with the keyword with).

You can use derived objects in your application as you would do with any other object class.

  package main;
  use Fun;
  my $obj = Fun->new('Fun');
  print $obj->to_pretty_xml;

  # <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  # <Fun xmlns="">
  #   <Cool>
  #     <Happy foo="bar">YEAH!!!! \o/ </Happy>
  #   </Cool>
  # </Fun>

The defined namespace is introduced as the document's namespace. The prefix is not in use for derived classes.

Without any changes to the class, you can use this module as an extension to another XML::Loy based document as well.

  use XML::Loy;

  my $obj = XML::Loy->new('object');

  # Use XML::Loy based class 'Fun'

  # Use methods provided by the base class or any extension

  # Print with pretty indentation
  print $obj->to_pretty_xml;

  # <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  # <object xmlns:fun="">
  #   <Cool>
  #     <fun:Happy foo="bar">YEAH!!!! \o/ </fun:Happy>
  #   </Cool>
  # </object>

The defined namespace of Fun is introduced with the prefix fun. The prefix is prepended to all elements added by the add and set methods in the extension class. To prevent this prefixing, prepend the element name with a - (like with <-Cool /> in the example above).

Derived classes are always strict and utf8, use warnings and import all features of Perl 5.10.


Mojolicious, Test::Warn (for testing).


XML::Loy focuses on the comfortable handling of small documents of serialized data and the ease of extensibility. It is - as well as the underlying parser - written in pure perl and not intended to be the fastest thing out there (although I believe there's plenty of space for optimization). That said - it may not suit all your needs, but there are loads of excellent XML libraries out there, you can give a try then. Just to name a few: For fast parsing of huge documents, see XML::Twig. For validation and the availability of lots of tools from the XML world, see XML::LibXML.



Copyright (C) 2011-2013, Nils Diewald.

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

syntax highlighting: