view release on metacpan or  search on metacpan

lib/Builder.pm  view on Meta::CPAN

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>



=head2 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.


=head1 EXPORT

Nothing (at this moment!)


=head1 METHODS

=head2 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 I<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.


=head2 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.


=head2 render

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

    my $output = $builder->render;

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


=head1 AUTHOR

Barry Walsh C<< <draegtun at cpan.org> >>


=head1 MOTIVATION

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


=head1 BUGS

Please report any bugs or feature requests to C<bug-builder at rt.cpan.org>, or through
the web interface at L<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.




=head1 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

=over 4

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Builder>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Builder>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Builder>