/ 
XML-Easy-ProceduralWriter-1.00
River stage zero No dependents
/ XML::Easy::ProceduralWriter

NAME

XML::Easy::ProceduralWriter - even easier writing of XML

SYNOPSIS

use XML::Easy::ProceduralWriter;

my $octlets = xml_bytes {
  element "flintstones", contains {
    element "family", surname => "flintstone", contains {
      element "person", hair => "black", contains {
        text "Fred";
      };
      element "person", hair => "blonde", contains {
        text "Wilma";
      };
      element "person", hair => "red", contains {
        text "Pebbles";
      };
    };
    element "family", surname => "rubble", contains {
      my %h = ("Barney" => "blonde", "Betty" => "black", "BamBam" => "white");
      foreach (qw( Barney Betty BamBam )) {
        element "person" hair => $h{$_}, contains { text $_ };
      }
    }
  };
};

# outputs
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<flintstones><family surname="flintstone"><person hair="black">Fred</person><person hair="blonde">Wilma</person><person hair="red">Pebbles</person></family><family surname="rubble"><person hair="blonde">Barney</person><person hair="black">Betty</person><person hair="white">BamBam</person></family></flintstones>

DESCRIPTION

A procedural wrapper around XML::Easy to provide an alternative way of writing XML

Tutorial

You can use this module to write standard XML. You start by saying you want some xml_bytes:

my $octlets = xml_bytes {
  ...
};

The element command adds a 'tag' to the output. The simpliest form is:

xml_bytes {
  element "a";
};

Which outputs

<a/>

Note that xml_bytes taks a block - not a data structure - so you can put anything code you want inside block.

xml_bytes {
  if ($foo) { element "a"; }
  else      { element "b"; }
}

(This is what we mean by "Procedural Writer")

You can also use attributes:

xml_bytes {
  element "a", href => "nojs.html", onclick => "openpopup()";
}

Which outputs

<a href="nojs.html" onclick="openpopup()" />

You can use the contains keyword to add content to the XML node.

element "a", href => "nojs.html", onclick => "openpopup()", contains {
  # ... content here ...
};

The content can be other tags, text, and any other valid Perl:

element "a" href => "nojs.html", onclick => "openpopup()", contains {
  text "Click ";
  element "strong", contains { 
    text "Here ";
    element "em", contains { text "NOW" };
  };
  text " please" if $polite;
  text " $name" if $name;
}

Which outputs

<a href="nojs.html" onclick="openpopup">Click <strong>Here <em>NOW</em></strong> please Mark</a>

Functions

This module exports several functions into your namespace by default. You can use standard Exporter parameters to control which of these are imported into your namespace

xml_element { ... }

Takes a codeblock. The code inside the codeblock should call "element" at least once. The XML::Easy::Element created by that element command is returned.

You don't normally want to call this function directly, using either xml_bytes to create something you can print out or element to create individual xml "tags". The one occasion that it might make sense to use this function is where you want to use an encoding other than UTF-8:

use XML::Easy qq(xml10_write_document);
print xml10_write_document(xml_element {
  element "song", title => "Green Bottles", contains {
    foreach my $bottles (reverse (1..10)) {
      element "verse", contains {
        element "line", contains {
          text "$bottles green bottle";
          text "s" unless $bottles == 1;
          text " hanging on the wall";
        } for (1..2);
        element "line", contains {
          text "if 1 green bottle should accidentally fall";
        };
        element "line", contains {
          text "then they'd be ".($bottles > 1 ? $bottles-1 : "no")." green bottle";
          text "s" unless $bottles-1 == 1;
          text " hanging on the wall";
        };
      };
    }
  }, "UTF-16BE");
xml_bytes { ... }

The same as xml_element, but returns a scalar containing octlets that have a UTF-8 encoded representation of the character representation of the string (i.e. this is what you want to use to create something you can pass to print)

element $element_name, $key => $value, $key => $value, $block

Create an XML::Easy::Element element and add it to the enclosing element.

text $text

Create text and add it to the enclosing element.

contains { ... }

Syntatic sugar for "sub { ... }"

AUTHOR

Mark Fowler <mark@twoshortplanks.com>. Developed by Photoways whist working on the Photobox website.

Copyright (C) Photoways Ltd 2008, all rights reserved.

If you send me an email about this module, there's a good chance my overly agressive spam filter will never let me see it. Please use http://rt.cpan.org/ to report bugs and request new features instead.

LICENSE

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

BUGS

Chucks a lot of stuff into your namespace.

Some people might consider it a bug that this module does not produce a <?xml ... declaration when we convert to bytes. I consider this a feature.

SEE ALSO

XML::Easy