File Coverage

blib/lib/XML/Writer/Simpler.pm

Criterion	Covered	Total	%
statement	44	44	100.0
branch	11	12	91.6
condition	1	2	50.0
subroutine	8	8	100.0
pod	2	2	100.0
total	66	68	97.0

package XML::Writer::Simpler;

use 5.006;
use strict;
use warnings FATAL => 'all';

=head1 NAME

XML::Writer::Simpler - Perl extension for writing XML data

=head1 SYNOPSIS


=head1 DESCRIPTION

This is a convenience module for writing XML. It's a subclass of
C, with a single convenience method so you usually won't have
to deal with remembering to call C, C, and
C.

This module is lies somewhere in between L and
L. It nests calls like XML::Generator, but allows for
arbitrary subroutine calls as well. It requires fewer braces in general than
XML::Writer::Nest.

This module is a subclass of XML::Writer, so if you can't do what you want to
with the C method, you can fall back to the methods native to XML::Writer.

=cut

use base qw/Exporter XML::Writer/;
use vars qw/@EXPORT_OK $VERSION/;

use Carp;


$VERSION = '0.11';
# package vars for ref to output file
my $out;

=head1 METHODS

=over 4

=item * C

    XML::Writer::Simpler->new(%params);

Creates the object. Acceptable hash keys for %params are the same as those
for L. This module assumes everything is UTF-8, so you can
omit that if you like; it will be provided for you.

=cut

sub new {
    my ($class, %params) = @_;
    $params{ENCODING} ||= 'utf-8';

    my $self = $class->SUPER::new(%params);
    $out = &{$self->{GETOUTPUT}};
    $self->xmlDecl('UTF-8') if $params{ENCODING} eq 'utf-8';
    bless $self, $class;
    return $self;
}

=item * tag

    $xml->tag($tagName, [ \@attributes ], $content);

If C<$content> is a plain scalar value, will output the tag with that content.
If no content is provided, will output an empty tag:

    $xml->tag('example', 'foo');    # foo
    $xml->tag('example');           #

You may also pass an array ref of key/value pairs that wind up as attributes:

    # foo
    $xml->tag('example', [bar => 'baz'], 'foo');

    #
    $xml->tag('example', [bar => 'baz']);

If C<$content> is a code ref, this will start the tag, execute the code ref,
then close the tag. This allows arbitrarily deep/complex tag structures.

    # Text 1Text 2
    $xml->tag('example1', sub {
        $xml->tag('exA', 'Text 1');
        $xml->tag('exB', 'Text 2');
    });

    # 100101102
    $xml->('example2', sub {
        for (my $tag = 'a', my $num = 100; $num < 103; $tag++, $num++) {
            $xml->($tag, $num);
        }
    });

These different styles of calling can be combined in a number of ways to
output basically whatever you like.


    # text z
    $xml->tag('example3', [id => 'ex3'], 'text z');

    # more text
    $xml->tag('example4', [id => 'ex4'], sub {
        $xml->tag('exZ', 'more text');
    });


=cut

sub tag {
    my $self = shift;
    my $tagName = shift;    # name of tag, required
    my $content = pop;      # might be text or a coderef
    my $aref = shift;       # attribute arrayref

    croak unless $tagName;

    my @attrs;
    # if we just have a tag name and an array ref, then the thing we popped
    # off of @_ might actually be the attribute array ref
    if (ref $content eq 'ARRAY') {
        $aref = $content;
        undef($content);
    }
    @attrs = @$aref if ref $aref eq 'ARRAY';

    if (ref $content eq 'CODE') {
        $self->startTag($tagName, @attrs);
        $content->();
        $self->endTag($tagName);
    } else {
        if ($content) {
            $self->dataElement($tagName, $content, @attrs);
        } else {
            $self->emptyTag($tagName, @attrs);
        }
    }
    return;
}


1;

__END__