byterock

Its collection day here at the Dist-Pen.

In my last post I looked at the rather plain but useful [Generic] section plug-in, that lets the Pod writer control where any section of POD that begins with =head1 can be moved to anywhere on the page. Today I am going to look at another of the often used plug-in the [Collect] section or plug-in.

This section is used to gather, group collect or otherwise gather together items under a named '=head1' tag what have the same POD tag. Looking at the [@Default] template again you will see there are three of them;

[Collect / ATTRIBUTES]

command = attr

[Collect / METHODS]

command = method

[Collect / FUNCTIONS]

command = func

So in this case it is collecting together what you would expect in your typical POD for a CPAN module. To make the above work for Attributes you have to add the '=attr' in front of all all the attributes you wan to list.

In my case I am playing with a table of contents so I am going to try it here. So to implement it I changed my POD a little like this;

-- =head1 Table Of Contents


++=toc Database::Accessor::Tutorial::GettingStarted

++A quick look at how to get started with Accessor

++=toc Database::Accessor::Tutorial::Basics

++Creating your first Data::Accessor

In this case I create a new POD tag '=toc' and in my 'weaver.ini' file I added this in

[Region  / manual_header]

++[Collect / Table Of Contents]

++

++command = toc

++

[Version]

and after a quick dzil clean and build I get

=head1 Table Of Contents


=head2 Database::Accessor::Tutorial::GettingStarted

A quick look at how to get started with Accessor

=head2 Database::Accessor::Tutorial::Basics

Creating your first Data::Accessor

=head1 Version

So my 'Table Of Contents' stays as a '=head1' while under each of the items that where '=toc' tags are now =head2 with the text underneath.

So very useful when you need to create a list of like sections. It will also collect from anywhere in the document. So the second '=toc' of mine could be at the bottom of the POD and still appear in 'TOC' section. There order however is alway sequential from the top of the source POD as the plug-in finds the 'command' tags.

Like similar plugins you can have as many collections as you like as long as the 'header' and 'command' combinations are unique.

There are a few 'attributes' that work with this section plug-in there is ''the 'command' attribute. It is a required attribute and is the secondary POD tag to look for, '=toc' in the example I used.

The 'header_command' is a way to alter the style of the plug-in's output. If you want your header to look for '=head2' rather than the default '=header1' just use this attribute.

The 'new_command' is another way to alter the style of the out-put. This time it effects the command. So if you wanted '=head3' rather than the default '=head2' you would use this attribute.

For example if I altered my 'weaver' file like this;

[Collect / Table Of Contents]

command = toc

header_command = 'head2'

new_command = 'head3'

[Version]

I get

='head2' Table Of Contents


='head3' Database::Accessor::Tutorial::GettingStarted

A quick look at how to get started with Accessor

='head3' Database::Accessor::Tutorial::Basics

Creating your first Data::Accessor

on a clean and buils, quite useful.

There is finally the 'header' attribute and like most other plug-ins it is just the long hand way to enter the header attribute. Like all other plug-ins the order in which you enter the attribute does not matter.

So there is [Collect] in a nutshell. More uses than a barrel of monkeys or a collecting Godzilla.