Text::TOC::HTML - Build a table contents for one or more HTML documents
my $toc = Text::TOC::HTML->new(); $toc->add_file( file => 'path/to/file' ); print $toc->html_for_toc(); print $toc->html_for_document('path/to/file'); print $toc->html_for_document_body('path/to/file');
This class provides a high-level API for generating a table of contents for one or more HTML documents.
As each file is processed, it will be altered in order to add anchors for the table of contents. The end result is a single blob of HTML for the table of contents itself, and new HTML for each document.
This class provides the following methods:
The constructor accepts several named parameters:
This is a boolean indicating whether or not you want to build a multi-document table of contents. This is based on the output, not the input. In other words, if you want the table of contents to link to multiple documents, set this to true.
By default, this class assumes that you are just going to output a single document.
The single vs multi choice affects the default filter for "interesting" nodes in a document, as well as link generation.
The single-document filter looks for second- through fourth-level headings. The multi-document filter looks for first- through fourth-level headings.
The single-document link generator simply generates a fragment link like "#foo". The multi-document link generator defaults to using the source file's file name as part of a "file://" URI. However, for multi-document output you'll almost certainly want to provide your own link generation.
This is an optional subroutine reference that will be used to generate links in the table of contents. See above for a description of the defaults.
This subroutine will be passed a single Text::TOC::Node::HTML object, and is expected to return a string containing a URI.
This can be either "ordered" or "unordered". It determines the list tag used when creating HTML for the table of contents. The default is "unordered".
You can provide a custom subroutine reference for filtering nodes. It will be called with one argument, an HTML::DOM::Node object. It should return true if the node should be included in the table of contents, false otherwise.
This method adds a file to the table of contents. The file can be given as a string or as a Path::Class::File object.
This file will be read and processed for the table of contents.
You can also provide an optional
content parameter, which contains the file's content. If this is provided, the file won't be read. This is useful if there is some pre-processing done to the file (for example, if it is a template of some sort).
Returns a blob of HTML that represents the table of contents for all the documents which have been processed.
Given a path to a file which has been processed, this method returns the HTML for that document. The HTML will include the anchors added to support the table of contents.
Given a path to a file which has been processed, this method returns the HTML body for that document. This is all the HTML between the
</body> tags. The HTML will include the anchors added to support the table of contents.
Dave Rolsky <email@example.com>
This software is copyright (c) 2012 by Dave Rolsky.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.