Builder - Build XML, HTML, CSS and other outputs in blocks


Version 0.06


Simple example....

    use Builder;

    my $builder = Builder->new;
    my $xm = $builder->block( 'Builder::XML' );

    $xm->parent( $xm->child( 'Hi Mum!' ) );
    say $builder->render;

    # => <parent><child>Hi Mum!</child></parent>

Another example using same block object....

            $xm->span( { id => 1 }, 'one' ), 
            $xm->span( { id => 2 }, 'two' ),

    say $builder->render;

    # => <body><div><span id="1">one</span><span id="2">two</span>/div></body>

And finally something a bit more whizzy....

    my $rainbow = $builder->block( 'Builder::XML', { indent => 4, newline => 1 } );

    $rainbow->colours( sub {
        for my $colour qw/red green blue/ {
            $rainbow->$colour( uc $colour );

    say $builder->render;

    # <colours>
    #     <red>RED</red>
    #     <green>GREEN</green>
    #     <blue>BLUE</blue>
    # </colours>


Marketing Spiel

If you need to build structured output then Builder will be exactly what you you've always been waiting for!

Just select and/or tailor the blocks you need then simply click them all together to construct the output of your dreams!

Technical Reality

First we need to create the stack / buffer / scaffold / bucket / zimmerframe (pick your favourite term) object....

    use Builder;
    my $builder = Builder->new;

Then you create the blocks associated with this build object....

    my $xm = $builder->block( 'Builder::XML' );
    my $ns = $builder->block( 'Builder::XML', { namespace => 'baz' } );

Then build your output using these blocks....

        $xm->before( 'foo' ),
        $ns->during( 'I3az' ),
        $xm->after( 'bar' ),

Continue to add more blocks to hearts content until happy then render it.....

    my $output = $builder->render;

    # <fubar><before>foo</before><baz:during>I3az</baz:during><after>bar</after><fubar>

So how does it work?

Remove the smoke and mirrors and all you are left with is parameter context.

Each block component will have its own parameter context. For example when Builder::XML receives no parameters then it will return a closed tag....

    # => <br />

For more information see relevant Builder::* block docs.


Nothing (at this moment!)



By default the constructor will maintain an internal stack (buffer) of the blocks being built.

    my $builder = Builder->new;

This is then later returned (processed) using render method on this object.

Using the output named parameter changes default behaviour to immediately output the blocks to the filehandle provided.

    my $builder = Builder->new( output => \*STDOUT );

There are no other parameters used by constructor.


Creates a block in this stack.

First arg is the block to use, for eg. 'Builder::XML'. Second arg must be a hashref of options (named parameters).

    my $builder = Builder->new();

    my $xm = $builder->block( 'Builder::XML', { cdata => 1 } );

For options that can be passed as args please see relevant Builder::* documentation.


Renders all the blocks for the requested builder stack returning the information.

    my $output = $builder->render;


The render method will automatically flush the builder stack (by calling this method). Unlikely this will be of any use in the outside world!

    $builder->flush;     # there goes all the blocks I just built ;-(


Barry Walsh <draegtun at>


Yep there was some... more on that later!


Please report any bugs or feature requests to bug-builder at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this module with the perldoc command.

    perldoc Builder

You can also look for information at:



Other Builder::* modules:


Similar CPAN modules:

Class::XML, XML::Generator

Builder Source Code

GitHub at


This is (near) beta software. I'll strive to make it better each and every day!

However I accept no liability whatsoever should this software do what you expected ;-)


Copyright 2008-2013 Barry Walsh (Draegtun Systems Ltd |, all rights reserved.

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