/ 
Text-TOC-0.10
River stage one • 1 direct dependent • 2 total dependents
/ Text::TOC::HTML

NAME

Text::TOC::HTML - Build a table contents for one or more HTML documents

VERSION

version 0.10

SYNOPSIS

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');

DESCRIPTION

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.

METHODS

This class provides the following methods:

Text::TOC::HTML->new()

The constructor accepts several named parameters:

  • multi

    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.

  • link_generator

    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.

  • style

    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".

  • filter

    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.

$toc->add_file( file => $file, ... )

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).

$toc->html_for_toc()

Returns a blob of HTML that represents the table of contents for all the documents which have been processed.

$toc->html_for_document($path)

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.

$toc->html_for_document_body($path)

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> and </body> tags. The HTML will include the anchors added to support the table of contents.

AUTHOR

Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE

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.