/ 
Builder-0.03
River stage zero No dependents
/ Builder

NAME

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

VERSION

Version 0.03

SYNOPSIS

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->body(
    $xm->div( 
        $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>

DESCRIPTION

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->fubar(
    $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....

$xm->br;

# => <br />

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

EXPORT

Nothing (at this moment!)

METHODS

new

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.

block

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.

render

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

my $output = $builder->render;

flush

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 ;-(

AUTHOR

Barry Walsh <draegtun at cpan.org>

MOTIVATION

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

BUGS

Please report any bugs or feature requests to bug-builder at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Builder. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

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

perldoc Builder

You can also look for information at: http://github.com/draegtun/builder

ACKNOWLEDGEMENTS

SEE ALSO

Other Builder::* modules:

Builder::XML

Similar CPAN modules:

Class::XML, XML::Generator

Builder Source Code

GitHub at http://github.com/draegtun/builder/tree/master

DISCLAIMER

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 & LICENSE

Copyright 2008,2009 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.