>..C<> from a file C:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$tocGenerator->generateFromFile($toc, 'index.htm');
print $toc->format();
For example, with C containing:
Chapter
the output will be:
=head2 Inserting
This code will generate a ToC of HTML headings C<>..C<> of file C, and insert the ToC after the C<> tag at the same time:
use HTML::Toc;
use HTML::TocInsertor;
my $toc = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$tocInsertor->insertIntoFile($toc, 'index.htm');
For example, with C containing:
Chapter
the output will be:
Chapter
If you're planning to update the inserted ToC, you'd better use C to insert the ToC. C marks the inserted ToC elements with update tokens. These update tokens allow C to identify and remove the ToC elements during a future update session. This code uses C instead of C:
use HTML::Toc;
use HTML::TocUpdator;
my $toc = HTML::Toc->new();
my $tocUpdator = HTML::TocUpdator->new();
$tocUpdator->insertIntoFile($toc, 'index.htm');
When applying the code above on 'index.htm':
Chapter
the output will contain additional update tokens:
around the inserted ToC elements:
Chapter
Instead of C you can also use C. C will also insert the ToC, whether there is a ToC already inserted or not.
=head2 Updating
This code will generate a ToC of HTML headings C<>..C<> of file C, and insert or update the ToC after the C<> tag at the same time:
use HTML::Toc;
use HTML::TocUpdator;
my $toc = HTML::Toc->new();
my $tocUpdator = HTML::TocUpdator->new();
$tocUpdator->updateFile($toc, 'indexToc.htm');
For example, with C containing:
foo
bar
Chapter
foo
h
the output will be:
Chapter
All text between the update tokens will be replaced. So be warned: all manual changes made to text between update tokens will be removed unrecoverable after calling C or C.
=head2 Formatting
The ToC isn't generated all at once. There are two stages involved: generating and formatting. Generating the ToC actually means storing a preliminary ToC in C{_toc}>. This preliminary, tokenized ToC has to be turned into something useful by calling Cformat()>. For an example, see paragraph 'L'.
=head1 Advanced
The ToC generation can be modified in a variety of ways. The following paragraphs each explain a single modification. An example of most of the modifications can be found in the C test file. Within this test, a manual containing:
preface
introduction
table of contents
table of figures
table of tables
parts
chapters
appendixes
bibliography
is formatted.
=head2 Using attribute value as ToC text
Normally, the ToC will be made of text between specified ToC tokens. It's also possible to use the attribute value of a token as a ToC text. This can be done by specifying the attribute marked with an L within the L token. For example, suppose you want to generate a ToC of the C attributes of the following image tokens:
This would be the code:
use HTML::Toc;
use HTML::TocInsertor;
my $toc = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$toc->setOptions({
'tokenToToc' => [{
'groupId' => 'image',
'tokenBegin' => '![@]()
'
}],
});
$tocInsertor->insertIntoFile($toc, $filename);
and the output will be:
=head2 Generate single ToC of multiple files
Besides generating a ToC of a single file, it's also possible to generate a single ToC of multiple files. This can be done by specifying either an array of files as the file argument and/or by extending an existing ToC.
=head3 Specify an array of files
For example, suppose you want to generate a ToC of both C:
Chapter of document 1
and C:
Chapter of document 2
Here's the code to do so by specifying an array of files:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({'doLinkToFile' => 1});
$tocGenerator->generateFromFile($toc, ['doc1.htm', 'doc2.htm']);
print $toc->format();
And the output will be:
=head3 Extend an existing ToC
It's also possible to extend an existing ToC. For example, suppose we want the generate a ToC of file C:
Chapter of document 1
and extend this ToC with text from C:
Chapter of document 2
Here's the code to do so:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({'doLinkToFile' => 1});
$tocGenerator->generateFromFile($toc, 'doc1.htm');
$tocGenerator->extendFromFile($toc, 'doc2.htm');
print $toc->format();
And the output will be:
=head2 Generate multiple ToCs
It's possible to generate multiple ToCs at once by specifying a C object array as the ToC argument. For example, suppose you want to generate a default ToC of HTML headings .. as well as a ToC of the C image attributes of the following text:
Header One
Paragraph One
Here's how you would do so:
use HTML::Toc;
use HTML::TocInsertor;
my $toc1 = HTML::Toc->new();
my $toc2 = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$toc2->setOptions({
'tokenToToc' => [{
'groupId' => 'image',
'tokenBegin' => '![@]()
'
}],
});
$tocInsertor->insertIntoFile([$toc1, $toc2], $filename);
And the output will be:
Header One
Paragraph One
=head2 Generate multiple groups in one ToC
You may want to generate a ToC consisting of multiple ToC groups.
=head3 Specify an additional 'Appendix' group
Suppose you want to generate a ToC with one group for the normal headings, and one group for the appendix headings, using this source file:
Chapter
Paragraph
Subparagraph
Chapter
Appendix Chapter
Appendix Paragraph
With the code underneath:
use HTML::Toc;
use HTML::TocInsertor;
my $toc = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$toc->setOptions({
'tokenToToc' => [{
'tokenBegin' => ''
}, {
'tokenBegin' => '',
'level' => 2
}, {
'groupId' => 'appendix',
'tokenBegin' => '',
}, {
'groupId' => 'appendix',
'tokenBegin' => '',
'level' => 2
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
the output will be:
Chapter
Paragraph
Subparagraph
Chapter
Appendix Chapter
Appendix Paragraph
=head3 Specify an additional 'Part' group
Suppose you want to generate a ToC of a document which is divided in multiple parts like this file underneath:
First Part
Chapter
Paragraph
Second Part
Chapter
Paragraph
With the code underneath:
use HTML::Toc;
use HTML::TocInsertor;
my $toc = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$toc->setOptions({
'doNumberToken' => 1,
'tokenToToc' => [{
'tokenBegin' => ''
}, {
'tokenBegin' => '',
'level' => 2,
}, {
'groupId' => 'part',
'tokenBegin' => '',
'level' => 1,
'numberingStyle' => 'upper-alpha'
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
the output will be:
A First Part
1 Chapter
1.1 Paragraph
B Second Part
2 Chapter
2.1 Paragraph
=head2 Number ToC entries
By default, the generated ToC will list its entries unnumbered. If you want to number the ToC entries, two options are available. Either you can specify a numbered list by modifying L and L. Or when the ToC isn't a simple numbered list, you can use the numbers generated by HTML::TocGenerator.
=head3 Specify numbered list
By modifying L and L you can specify a numbered ToC:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({
'templateLevelBegin' => '"\n"',
'templateLevelEnd' => '"
\n"',
});
$tocGenerator->generateFromFile($toc, 'index.htm');
print $toc->format();
For instance with the original file containing:
Chapter
Paragraph
The formatted ToC now will contain C instead of C tags:
See also: L.
=head3 Use generated numbers
Instead of using the HTML ordered list (OL), it's also possible to use the generated numbers to number to ToC nodes. This can be done by modifying L:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({
'templateLevel' => '"- $node $text\n"',
});
$tocGenerator->generateFromFile($toc, 'index.htm');
print $toc->format();
For instance with the original file containing:
Chapter
Paragraph
The formatted ToC now will have the node numbers hard-coded:
See also: L.
=head2 Using CSS for ToC formatting
Suppose you want to display a ToC with upper-alpha numbered appendix headings. To accomplish this, you can specify a CSS style within the source document:
Appendix
Appendix Paragraph
Appendix
Appendix Paragraph
Here's the code:
my $toc = new HTML::Toc;
my $tocInsertor = new HTML::TocInsertor;
$toc->setOptions({
'templateLevelBegin' => '"\n"',
'templateLevelEnd' => '"
\n"',
'doNumberToken' => 1,
'tokenToToc' => [{
'groupId' => 'appendix',
'tokenBegin' => '',
'numberingStyle' => 'upper-alpha'
}, {
'groupId' => 'appendix',
'tokenBegin' => '',
'level' => 2,
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
Which whill result in the following output:
A Appendix
A.1 Appendix Paragraph
B Appendix
B.1 Appendix Paragraph
=head2 Creating site map
Suppose you want to generate a table of contents of the EtitleE tags of the files in the following directory structure:
path file
. index.htm, Main
|- SubDir1 index.htm, Sub1
| |- SubSubDir1 index.htm, SubSub1
|
|- SubDir2 index.htm, Sub2
| |- SubSubDir1 index.htm, SubSub1
| |- SubSubDir2 index.htm, SubSub2
|
|- SubDir3 index.htm, Sub3
By specifying 'fileSpec' which determine how many slashes (/) each file may contain for a specific level:
use HTML::Toc;
use HTML::TocGenerator;
use File::Find;
my $toc = HTML::Toc->new;
my $tocGenerator = HTML::TocGenerator->new;
my @fileList;
sub wanted {
# Add file to 'fileList' if extension matches '.htm'
push (@fileList, $File::Find::name) if (m/\.htm$/);
}
$toc->setOptions({
'doLinkToFile' => 1,
'templateAnchorName' => '""',
'templateAnchorHref' => '""',
'doLinkTocToToken' => 1,
'tokenToToc' => [{
'groupId' => 'dir',
'level' => 1,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+$'
}, {
'groupId' => 'dir',
'level' => 2,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+?/[^/]+$'
}, {
'groupId' => 'dir',
'level' => 3,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+?/[^/]+?/[^/]+$'
}]
});
# Traverse directory structure
find({wanted => \&wanted, no_chdir => 1}, '.');
# Generate ToC of case-insensitively sorted file list
$tocGenerator->extendFromFile(
$toc, [sort {uc($a) cmp uc($b)} @fileList]
);
print $toc->format();
the following ToC will be generated:
=head1 Methods
=head2 HTML::Toc::clear()
syntax: $toc->clear()
returns: --
Clear the ToC.
=head2 HTML::Toc::format()
syntax: $scalar = $toc->format()
returns: Formatted ToC.
Format tokenized ToC.
=head2 HTML::TocGenerator::extend()
syntax: $tocGenerator->extend($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to extend
- $string: string to retrieve ToC from
- $options: hash reference containing generator options.
Extend ToC from specified string. For generator options, see L
=head2 HTML::TocGenerator::extendFromFile()
syntax: $tocGenerator->extendFromFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to extend
- $filename: (reference to array of) file(s) to extend ToC from
- $options: hash reference containing generator options.
Extend ToC from specified file. For generator options, see L. For an example, see L.
=head2 HTML::TocGenerator::generate()
syntax: $tocGenerator->generate($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to generate
- $string: string to retrieve ToC from
- $options: hash reference containing generator options.
Generate ToC from specified string. Before generating, the ToC will be cleared. For extending an existing ToC, use the L method. For generator options, see L.
=head2 HTML::TocGenerator::generateFromFile()
syntax: $tocGenerator->generateFromFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to
generate
- $filename: (reference to array of) file(s) to generate ToC from
- $options: hash reference containing generator options.
Generate ToC from specified file. Before generating, the ToC will be cleared. For extending an extisting ToC, use the L method. For generator options, see L.
=head2 HTML::TocInsertor::insert()
syntax: $tocInsertor->insert($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to insert ToC in
- $options: hash reference containing insertor options.
Insert ToC into specified string. For insertor options, see L.
=head2 HTML::TocInsertor::insertIntoFile()
syntax: $tocInsertor->insertIntoFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to insert ToC in
- $options: hash reference containing insertor options.
Insert ToC into specified file. For insertor options, see L.
=head2 HTML::TocUpdator::insert()
syntax: $tocUpdator->insert($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to insert ToC in
- $options: hash reference containing updator options.
Insert ToC into specified string. Differs from L in that inserted text will be surrounded with update tokens in order for C to be able to update this text the next time an update is issued. For updator options, see L.
=head2 HTML::TocUpdator::insertIntoFile()
syntax: $tocUpdator->insertIntoFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to insert ToC in
- $options: hash reference containing updator options.
Insert ToC into specified file. Differs from L in that inserted text will be surrounded with update tokens in order for C to be able to update this text the next time an update is issued. For updator options, see L.
=head2 HTML::TocUpdator::update()
syntax: $tocUpdator->update($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to update ToC in
- $options: hash reference containing updator options.
Update ToC within specified string. For updator options, see L.
=head2 HTML::TocUpdator::updateFile()
syntax: $tocUpdator->updateFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to update ToC in
- $options: hash reference containing updator options.
Update ToC of specified file. For updator options, see L.
=head1 Parser Options
When generating a ToC, additional options may be specified which influence the way the ToCs are generated using either C, C or C. The options must be specified as a hash reference. For example:
$tocGenerator->generateFromFile($toc, $filename, {doUseGroupsGlobal => 1});
Available options are:
=over 4
=item L
=item L
=item L
=item L
=back
=head2 doGenerateToc
syntax: [0|1]
default: 1
applicable to: TocInsertor, TocUpdator
True (1) if ToC must be generated. False (0) if ToC must be inserted only.
=head2 doUseGroupsGlobal
syntax: [0|1]
default: 0
applicable to: TocGenerator, TocInsertor, TocUpdator
True (1) if group levels must be used globally accross ToCs. False (0) if not. This option only makes sense when an array of ToCs is specified. For example, suppose you want to generate two ToCs, one ToC for '' tokens and one ToC for '' tokens, of the file 'index.htm':
Chapter
Paragraph
Using the default setting of 'doUseGroupsGlobal' => 0:
use HTML::Toc;
use HTML::TocGenerator;
my $toc1 = HTML::Toc->new();
my $toc2 = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc1->setOptions({
'header' => '',
'footer' => '',
'tokenToToc' => [{'tokenBegin' => ''}]
});
$toc2->setOptions({
'header' => '',
'footer' => '',
'tokenToToc' => [{'tokenBegin' => ''}]
});
$tocGenerator->generateFromFile([$toc1, $toc2], 'index.htm');
print $toc1->format() . "\n\n" . $toc2->format();
the output will be:
Each ToC will use its own numbering scheme. Now if 'C' is specified:
$tocGenerator->generateFromFile(
[$toc1, $toc2], 'index.htm', {'doUseGroupsGlobal' => 1}
);
the output will be:
using a global numbering scheme for all ToCs.
=head2 output
syntax: reference to scalar
default: none
applicable to: TocInsertor, TocUpdator
Reference to scalar where the output must be stored in.
=head2 outputFile
syntax: scalar
default: none
applicable to: TocInsertor, TocUpdator
Filename to write output to. If no filename is specified, output will be written to standard output.
=head1 HTML::Toc Options
The C options can be grouped in the following categories:
=over 4
=item L
=item L
=item L
=item L
=back
The ToC options must be specified using the 'setOptions' method. For example:
my $toc = new HTML::Toc;
$toc->setOptions({
'doNumberToken' => 1,
'footer' => ''
'tokenToToc' => [{
'level' => 1,
'tokenBegin' => '',
'numberingStyle' => 'lower-alpha'
}]
});
=head2 Generate options
=over 4
=item Token groups
=over 4
=item L
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=item L
=item L
=back
=item Numbering tokens
=over 4
=item L
=item L
=item L
=back
=item Miscellaneous
=over 4
=item L
=item L
=item L
=item L
=back
=item Linking ToC to tokens
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=back
=head2 Insert options
=over 4
=item L
=back
=head2 Update options
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=back
=head2 Format options
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=head1 HTML::Toc Options Reference
=head2 attributeToExcludeToken
syntax: $scalar
default: '-'
Token which marks an attribute value in a L or L token as an attribute value a token should not have to be marked as a ToC token. See also: L.
=head2 attributeToTocToken
syntax: $scalar
default: '@'
Token which marks an attribute in a L token as an attribute which must be used as ToC text. See also: L.
=head2 doLinkToToken
syntax: [0|1]
default: 1
True (1) if ToC must be linked to tokens, False (0) if not. Note that 'HTML::TocInsertor' must be used to do the actual insertion of the anchor name within the source data.
=head2 doLinkToFile
syntax: [0|1]
default: 0
True (1) if ToC must be linked to file, False (0) if not. In effect only when L equals True (1) and L isn't specified.
=head2 doLinkToId
syntax: [0|1]
default: 0
True (1) if ToC must be linked to tokens by using token ids. False (0) if ToC must be linked to tokens by using anchor names.
=head2 doNestGroup
syntax: [0|1]
default: 0
True (1) if groups must be nested in the formatted ToC, False (0) if not. In effect only when multiple groups are specified within the L setting. For an example, see L.
=head2 doNumberToken
syntax: [0|1]
default: 0
True (1) if tokens which are used for the ToC generation must be numbered. This option may be specified both as a global ToC option or within a L group. When specified within a C option, the C applies to that group only. For an example, see L.
=head2 doSingleStepLevel
syntax: [0|1]
default: 1
True (1) if levels of a formatted ToC must advance one level at a time. For example, when generating a ToC of a file with a missing '':
Chapter
Paragraph
By default, an empty indentation level will be inserted in the ToC:
After specifying:
$toc->setOptions({'doSingleStepLevel' => 0});
the ToC will not have an indentation level inserted for level 2:
=head2 fileSpec
syntax:
default: undef
Specifies which files should match the current level. Valid only if L equals 1. For an example, see L.
=head2 footer
syntax: $scalar
default: "\n\n"
String to output at end of ToC.
=head2 groupId
syntax: $scalar
default: 'h'
Sets the group id attribute of a tokenGroup. With this attribute it's possible to divide the ToC into multiple groups. Each group has its own numbering scheme. For example, to generate a ToC of both normal headings and 'appendix' headings, specify the following ToC settings:
$toc->setOptions({
'tokenToToc' => [{
'tokenBegin' => ''
}, {
'groupId' => 'appendix',
'tokenBegin' => ''
}]
});
=head2 groupToToc
syntax:
default: '.*'
Determines which groups to use for generating the ToC. For example, to create a ToC for groups [a-b] only, specify:
'groupToToc => '[a-b]'
This option is evaluated during both ToC generation and ToC formatting. This enables you to generate a ToC of all groups, but - after generating - format only specified groups:
$toc->setOptions({'groupToToc' => '.*'});
$tocGenerator->generateToc($toc, ...);
# Get ToC of all groups
$fullToc = $toc->format();
# Get ToC of 'appendix' group only
$toc->setOptions({'groupToToc' => 'appendix'});
$appendixToc = $toc->format();
=head2 header
syntax: $scalar
default: "\n\n"
String to output at begin of ToC.
=head2 insertionPoint
syntax: []
default: 'after '
token: <[/]tag{ attribute=[-|@]}> |
|
|
Determines the point within the source, where the ToC should be inserted. When specifying a start tag as the insertion point token, attributes to be included may be specified as well. Note that the attribute value must be specified as a regular expression. For example, to specify the C<> tag as insertion point:
''
Examples of valid 'insertionPoint' tokens are:
''
'
'
''
''
'ToC will be placed here'
It is also possible to specify attributes to exclude, by prefixing the value with an L, default a minus sign (-). For example, to specify the C<> tag as insertion point, excluding all C<> tags:
''
See also L.
=head2 level
syntax: number
default: 1
Number which identifies at which level the tokengroup should be incorporated into the ToC. See also: L.
=head2 levelIndent
syntax: number
default: 3
Sets the number of spaces each level will be indented, when formatting the ToC.
=head2 levelToToc
syntax:
default: '.*'
Determines which group levels to use for generating the ToC. For example, to create a ToC for levels 1-2 only, specify:
'levelToToc => '[1-2]'
This option is evaluated during both ToC generation and ToC formatting. This enables you to generate a ToC of all levels, but - after generating - retrieve only specified levels:
$toc->setOptions({'levelToToc' => '.*'});
$tocGenerator->generateToc($toc, ...);
# Get ToC of all levels
$fullToc = $toc->getToc();
# Get ToC of level 1 only
$toc->setOptions({'levelToToc' => '1'});
$level1Toc = $toc->getToc();
=head2 numberingStyle
syntax: [decimal|lower-alpha|upper-alpha|lower-roman|upper-roman]}
default: decimal
Determines which numbering style to use for a token group when L is set to True (1). When specified as a main ToC option, the setting will be the default for all groups. When specified within a tokengroup, this setting will override any default for that particular tokengroup, e.g.:
$toc->setOptions({
'doNumberToken' => 1,
'tokenToToc' => [{
'level' => 1,
'tokenBegin' => '',
'numberingStyle' => 'lower-alpha'
}]
});
If C style is specified, be sure to have the Roman module installed, available from L.
=head2 templateAnchorName
syntax:
default: '$groupId."-".$node'
Anchor name to use when L is set to True (1). The anchor name is passed to both L and L. The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
If C is a function reference to a function returning the anchor, like in:
$toc->setOptions({'templateAnchorName' => \&assembleAnchorName});
the function will be called with the following arguments:
$anchorName = assembleAnchorName($file, $groupId, $level, $node);
=head2 templateAnchorHrefBegin
syntax:
default: '""' or
'""',
depending on 'doLinkToFile' being 0 or 1 respectively.
Anchor reference begin token to use when L is set to True (1). The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
$anchorName
If C is a function reference to a function returning the anchor, like in:
$toc->setOptions({'templateAnchorHrefBegin' => \&assembleAnchorHrefBegin});
the function will be called with the following arguments:
$anchorHrefBegin = &assembleAnchorHrefBegin(
$file, $groupId, $level, $node, $anchorName
);
See also: L, L.
=head2 templateAnchorHrefEnd
syntax:
default: '" "'
Anchor reference end token to use when L is set to True (1). The template may be specified as either an expression or a function reference. If L is a function reference to a function returning the anchor end, like in:
$toc->setOptions({'templateAnchorHrefEnd' => \&assembleAnchorHrefEnd});
the function will be called without arguments:
$anchorHrefEnd = &assembleAnchorHrefEnd;
See also: L.
=head2 templateAnchorNameBegin
syntax:
default: '""'
Anchor name begin token to use when L is set to True (1). The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
$anchorName
If C is a function reference to a function returning the anchor name, like in:
$toc->setOptions({'templateAnchorNameBegin' => \&assembleAnchorNameBegin});
the function will be called with the following arguments:
$anchorNameBegin = assembleAnchorNameBegin(
$file, $groupId, $level, $node, $anchorName
);
See also: L, L.
=head2 templateAnchorNameEnd
syntax:
default: '" "'
Anchor name end token to use when L is set to True (1). The template may be specified as either an expression or a function reference. If L is a function reference to a function returning the anchor end, like in:
$toc->setOptions({'templateAnchorNameEnd' => \&assembleAnchorNameEnd});
the function will be called without arguments:
$anchorNameEnd = &assembleAnchorNameEnd;
See also: L.
=head2 templateLevel
syntax:
default: '"- $text\n"'
Expression to use when formatting a ToC node. The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$level
$groupId
$node
$sequenceNr
$text
If C
is a function reference to a function returning the ToC node, like in:
$toc->setOptions({'templateLevel' => \&AssembleTocNode});
the function will be called with the following arguments:
$tocNode = &AssembleTocNode(
$level, $groupId, $node, $sequenceNr, $text
);
=head2 templateLevelBegin
syntax:
default: '"\n"'
Expression to use when formatting begin of ToC level. See L for list of available variables to use within the expression. For example, to give each ToC level a class name to use with Cascading Style Sheets (CSS), use the expression:
'"\n"'
which will result in each ToC group being given a class name:
- Header
For an example, see L.
=head2 templateLevelEnd
syntax:
default: '"\n"'
Expression to use when formatting end of ToC level. See L for a list of available variables to use within the expression. The default expression is:
'"
\n"'
For an example, see L.
=head2 templateTokenNumber
syntax:
default: '"$node "'
Token number to use when L equals True (1). The template may be specified as either an expression or a function reference. The expression has access to the following variables:
$file
$groupId
$groupLevel
$level
$node
$toc
If C is a function reference to a function returning the token number, like in:
$toc->setOptions({'templateTokenNumber' => \&assembleTokenNumber});
the function will be called with the following arguments:
$number = &assembleTokenNumber(
$node, $groupId, $file, $groupLevel, $level, $toc
);
=head2 tokenBegin
syntax:
default: ''
token: <[/]tag{ attribute=[-|@]}> |
|
|
This scalar defines the token that will trigger text to be put into the ToC. Any start tag, end tag, comment, declaration or text string can be specified. Examples of valid 'tokenBegin' tokens are:
''
''
''
''
'ToC entry'
When specifying a start tag, attributes to be included may be specified as well. Note that the attribute value is used as a regular expression. For example, to specify the C<> tag as tokenBegin:
''
It is also possible to specify attributes to exclude, by prefixing the value with an L, default a minus sign (-). For example, to specify the C<> tag as tokenBegin, excluding all C<> tags:
''
Also, you can specify here an attribute value which has to be used as ToC text, by prefixing the value with an L, default an at sign (@). For example, to use the class value as ToC text:
''
See L for an elaborated example using the C to generate a ToC of image C attribute values.
See also: L, L.
=head2 tokenEnd
syntax: $scalar
default: empty string ('') or end tag counterpart of 'tokenBegin' if
'tokenBegin' is a start tag
The 'tokenEnd' definition applies to the same rules as L.
See also: L, L.
=head2 tokenToToc
syntax: [{array of hashrefs}]
default: [{
'level' => 1,
'tokenBegin' => ''
}, {
'level' => 2,
'tokenBegin' => ''
}, {
'level' => 3,
'tokenBegin' => ''
}, {
'level' => 4,
'tokenBegin' => ''
}, {
'level' => 5,
'tokenBegin' => ''
}, {
'level' => 6,
'tokenBegin' => ''
}]
This hash define the tokens that must act as ToC entries. Each tokengroup may contain a L, L, L, L and L identifier.
=head2 tokenUpdateBeginAnchorName
syntax:
default: '';
This token marks the begin of an anchor name, inserted by C. This option is used by C.
=head2 tokenUpdateEndAnchorName
syntax:
default: '';
This option is used by C, to mark the end of an inserted anchor name.
=head2 tokenUpdateBeginNumber
syntax:
default: '';
This option is used by C, to mark the begin of an inserted number.
=head2 tokenUpdateEndNumber
syntax:
default: '';
This option is used by C, to mark the end of an inserted number.
=head2 tokenUpdateBeginToc
syntax:
default: '';
This option is used by C, to mark the begin of an inserted ToC.
=head2 tokenUpdateEndToc
syntax:
default: '';
This option is used by C, to mark the end of an inserted ToC.
=head1 Known issues
=head2 Cygwin
In order for the test files to run on Cygwin without errors, the 'UNIX' default text file type has to be selected during the Cygwin setup.
When extracting the tar.gz file with WinZip the 'TAR file smart CR/LF conversion' has to be turned off via {Options|Configuration...|Miscellaneous} in order for the files 'toc.pod' and './manualTest/manualTest1.htm' to be left in UNIX format.
=head2 Nested anchors
HTML::Toc can only link to existing anchors if these anchors are placed outside of the ToC tokens. Otherwise a warning will be given. For example, generating a L ToC of Ch1E> tokens of the following text:
Chapter
the output will be: =head2 Inserting This code will generate a ToC of HTML headings C<>..C<> of file C, and insert the ToC after the C<> tag at the same time:
use HTML::Toc;
use HTML::TocInsertor;
my $toc = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$tocInsertor->insertIntoFile($toc, 'index.htm');
For example, with C containing:
Chapter
the output will be:
Chapter
If you're planning to update the inserted ToC, you'd better use C to insert the ToC. C marks the inserted ToC elements with update tokens. These update tokens allow C to identify and remove the ToC elements during a future update session. This code uses C instead of C:
use HTML::Toc;
use HTML::TocUpdator;
my $toc = HTML::Toc->new();
my $tocUpdator = HTML::TocUpdator->new();
$tocUpdator->insertIntoFile($toc, 'index.htm');
When applying the code above on 'index.htm':
Chapter
the output will contain additional update tokens:
around the inserted ToC elements:
Chapter
Instead of C you can also use C. C will also insert the ToC, whether there is a ToC already inserted or not.
=head2 Updating
This code will generate a ToC of HTML headings C<>..C<> of file C, and insert or update the ToC after the C<> tag at the same time:
use HTML::Toc;
use HTML::TocUpdator;
my $toc = HTML::Toc->new();
my $tocUpdator = HTML::TocUpdator->new();
$tocUpdator->updateFile($toc, 'indexToc.htm');
For example, with C containing:
foo
bar
Chapter
foo
h
the output will be:
Chapter
All text between the update tokens will be replaced. So be warned: all manual changes made to text between update tokens will be removed unrecoverable after calling C or C.
=head2 Formatting
The ToC isn't generated all at once. There are two stages involved: generating and formatting. Generating the ToC actually means storing a preliminary ToC in C{_toc}>. This preliminary, tokenized ToC has to be turned into something useful by calling Cformat()>. For an example, see paragraph 'L'.
=head1 Advanced
The ToC generation can be modified in a variety of ways. The following paragraphs each explain a single modification. An example of most of the modifications can be found in the C test file. Within this test, a manual containing:
preface
introduction
table of contents
table of figures
table of tables
parts
chapters
appendixes
bibliography
is formatted.
=head2 Using attribute value as ToC text
Normally, the ToC will be made of text between specified ToC tokens. It's also possible to use the attribute value of a token as a ToC text. This can be done by specifying the attribute marked with an L within the L token. For example, suppose you want to generate a ToC of the C attributes of the following image tokens:
This would be the code:
use HTML::Toc;
use HTML::TocInsertor;
my $toc = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$toc->setOptions({
'tokenToToc' => [{
'groupId' => 'image',
'tokenBegin' => '![@]()
'
}],
});
$tocInsertor->insertIntoFile($toc, $filename);
and the output will be:
=head2 Generate single ToC of multiple files
Besides generating a ToC of a single file, it's also possible to generate a single ToC of multiple files. This can be done by specifying either an array of files as the file argument and/or by extending an existing ToC.
=head3 Specify an array of files
For example, suppose you want to generate a ToC of both C:
Chapter of document 1
and C:
Chapter of document 2
Here's the code to do so by specifying an array of files:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({'doLinkToFile' => 1});
$tocGenerator->generateFromFile($toc, ['doc1.htm', 'doc2.htm']);
print $toc->format();
And the output will be:
=head3 Extend an existing ToC
It's also possible to extend an existing ToC. For example, suppose we want the generate a ToC of file C:
Chapter of document 1
and extend this ToC with text from C:
Chapter of document 2
Here's the code to do so:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({'doLinkToFile' => 1});
$tocGenerator->generateFromFile($toc, 'doc1.htm');
$tocGenerator->extendFromFile($toc, 'doc2.htm');
print $toc->format();
And the output will be:
=head2 Generate multiple ToCs
It's possible to generate multiple ToCs at once by specifying a C object array as the ToC argument. For example, suppose you want to generate a default ToC of HTML headings .. as well as a ToC of the C image attributes of the following text:
Header One
Paragraph One
Here's how you would do so:
use HTML::Toc;
use HTML::TocInsertor;
my $toc1 = HTML::Toc->new();
my $toc2 = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$toc2->setOptions({
'tokenToToc' => [{
'groupId' => 'image',
'tokenBegin' => '![@]()
'
}],
});
$tocInsertor->insertIntoFile([$toc1, $toc2], $filename);
And the output will be:
Header One
Paragraph One
=head2 Generate multiple groups in one ToC
You may want to generate a ToC consisting of multiple ToC groups.
=head3 Specify an additional 'Appendix' group
Suppose you want to generate a ToC with one group for the normal headings, and one group for the appendix headings, using this source file:
Chapter
Paragraph
Subparagraph
Chapter
Appendix Chapter
Appendix Paragraph
With the code underneath:
use HTML::Toc;
use HTML::TocInsertor;
my $toc = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$toc->setOptions({
'tokenToToc' => [{
'tokenBegin' => ''
}, {
'tokenBegin' => '',
'level' => 2
}, {
'groupId' => 'appendix',
'tokenBegin' => '',
}, {
'groupId' => 'appendix',
'tokenBegin' => '',
'level' => 2
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
the output will be:
Chapter
Paragraph
Subparagraph
Chapter
Appendix Chapter
Appendix Paragraph
=head3 Specify an additional 'Part' group
Suppose you want to generate a ToC of a document which is divided in multiple parts like this file underneath:
First Part
Chapter
Paragraph
Second Part
Chapter
Paragraph
With the code underneath:
use HTML::Toc;
use HTML::TocInsertor;
my $toc = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$toc->setOptions({
'doNumberToken' => 1,
'tokenToToc' => [{
'tokenBegin' => ''
}, {
'tokenBegin' => '',
'level' => 2,
}, {
'groupId' => 'part',
'tokenBegin' => '',
'level' => 1,
'numberingStyle' => 'upper-alpha'
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
the output will be:
A First Part
1 Chapter
1.1 Paragraph
B Second Part
2 Chapter
2.1 Paragraph
=head2 Number ToC entries
By default, the generated ToC will list its entries unnumbered. If you want to number the ToC entries, two options are available. Either you can specify a numbered list by modifying L and L. Or when the ToC isn't a simple numbered list, you can use the numbers generated by HTML::TocGenerator.
=head3 Specify numbered list
By modifying L and L you can specify a numbered ToC:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({
'templateLevelBegin' => '"\n"',
'templateLevelEnd' => '"
\n"',
});
$tocGenerator->generateFromFile($toc, 'index.htm');
print $toc->format();
For instance with the original file containing:
Chapter
Paragraph
The formatted ToC now will contain C instead of C tags:
See also: L.
=head3 Use generated numbers
Instead of using the HTML ordered list (OL), it's also possible to use the generated numbers to number to ToC nodes. This can be done by modifying L:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({
'templateLevel' => '"- $node $text\n"',
});
$tocGenerator->generateFromFile($toc, 'index.htm');
print $toc->format();
For instance with the original file containing:
Chapter
Paragraph
The formatted ToC now will have the node numbers hard-coded:
See also: L.
=head2 Using CSS for ToC formatting
Suppose you want to display a ToC with upper-alpha numbered appendix headings. To accomplish this, you can specify a CSS style within the source document:
Appendix
Appendix Paragraph
Appendix
Appendix Paragraph
Here's the code:
my $toc = new HTML::Toc;
my $tocInsertor = new HTML::TocInsertor;
$toc->setOptions({
'templateLevelBegin' => '"\n"',
'templateLevelEnd' => '"
\n"',
'doNumberToken' => 1,
'tokenToToc' => [{
'groupId' => 'appendix',
'tokenBegin' => '',
'numberingStyle' => 'upper-alpha'
}, {
'groupId' => 'appendix',
'tokenBegin' => '',
'level' => 2,
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
Which whill result in the following output:
A Appendix
A.1 Appendix Paragraph
B Appendix
B.1 Appendix Paragraph
=head2 Creating site map
Suppose you want to generate a table of contents of the EtitleE tags of the files in the following directory structure:
path file
. index.htm, Main
|- SubDir1 index.htm, Sub1
| |- SubSubDir1 index.htm, SubSub1
|
|- SubDir2 index.htm, Sub2
| |- SubSubDir1 index.htm, SubSub1
| |- SubSubDir2 index.htm, SubSub2
|
|- SubDir3 index.htm, Sub3
By specifying 'fileSpec' which determine how many slashes (/) each file may contain for a specific level:
use HTML::Toc;
use HTML::TocGenerator;
use File::Find;
my $toc = HTML::Toc->new;
my $tocGenerator = HTML::TocGenerator->new;
my @fileList;
sub wanted {
# Add file to 'fileList' if extension matches '.htm'
push (@fileList, $File::Find::name) if (m/\.htm$/);
}
$toc->setOptions({
'doLinkToFile' => 1,
'templateAnchorName' => '""',
'templateAnchorHref' => '""',
'doLinkTocToToken' => 1,
'tokenToToc' => [{
'groupId' => 'dir',
'level' => 1,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+$'
}, {
'groupId' => 'dir',
'level' => 2,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+?/[^/]+$'
}, {
'groupId' => 'dir',
'level' => 3,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+?/[^/]+?/[^/]+$'
}]
});
# Traverse directory structure
find({wanted => \&wanted, no_chdir => 1}, '.');
# Generate ToC of case-insensitively sorted file list
$tocGenerator->extendFromFile(
$toc, [sort {uc($a) cmp uc($b)} @fileList]
);
print $toc->format();
the following ToC will be generated:
=head1 Methods
=head2 HTML::Toc::clear()
syntax: $toc->clear()
returns: --
Clear the ToC.
=head2 HTML::Toc::format()
syntax: $scalar = $toc->format()
returns: Formatted ToC.
Format tokenized ToC.
=head2 HTML::TocGenerator::extend()
syntax: $tocGenerator->extend($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to extend
- $string: string to retrieve ToC from
- $options: hash reference containing generator options.
Extend ToC from specified string. For generator options, see L
=head2 HTML::TocGenerator::extendFromFile()
syntax: $tocGenerator->extendFromFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to extend
- $filename: (reference to array of) file(s) to extend ToC from
- $options: hash reference containing generator options.
Extend ToC from specified file. For generator options, see L. For an example, see L.
=head2 HTML::TocGenerator::generate()
syntax: $tocGenerator->generate($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to generate
- $string: string to retrieve ToC from
- $options: hash reference containing generator options.
Generate ToC from specified string. Before generating, the ToC will be cleared. For extending an existing ToC, use the L method. For generator options, see L.
=head2 HTML::TocGenerator::generateFromFile()
syntax: $tocGenerator->generateFromFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to
generate
- $filename: (reference to array of) file(s) to generate ToC from
- $options: hash reference containing generator options.
Generate ToC from specified file. Before generating, the ToC will be cleared. For extending an extisting ToC, use the L method. For generator options, see L.
=head2 HTML::TocInsertor::insert()
syntax: $tocInsertor->insert($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to insert ToC in
- $options: hash reference containing insertor options.
Insert ToC into specified string. For insertor options, see L.
=head2 HTML::TocInsertor::insertIntoFile()
syntax: $tocInsertor->insertIntoFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to insert ToC in
- $options: hash reference containing insertor options.
Insert ToC into specified file. For insertor options, see L.
=head2 HTML::TocUpdator::insert()
syntax: $tocUpdator->insert($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to insert ToC in
- $options: hash reference containing updator options.
Insert ToC into specified string. Differs from L in that inserted text will be surrounded with update tokens in order for C to be able to update this text the next time an update is issued. For updator options, see L.
=head2 HTML::TocUpdator::insertIntoFile()
syntax: $tocUpdator->insertIntoFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to insert ToC in
- $options: hash reference containing updator options.
Insert ToC into specified file. Differs from L in that inserted text will be surrounded with update tokens in order for C to be able to update this text the next time an update is issued. For updator options, see L.
=head2 HTML::TocUpdator::update()
syntax: $tocUpdator->update($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to update ToC in
- $options: hash reference containing updator options.
Update ToC within specified string. For updator options, see L.
=head2 HTML::TocUpdator::updateFile()
syntax: $tocUpdator->updateFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to update ToC in
- $options: hash reference containing updator options.
Update ToC of specified file. For updator options, see L.
=head1 Parser Options
When generating a ToC, additional options may be specified which influence the way the ToCs are generated using either C, C or C. The options must be specified as a hash reference. For example:
$tocGenerator->generateFromFile($toc, $filename, {doUseGroupsGlobal => 1});
Available options are:
=over 4
=item L
=item L
=item L
=item L
=back
=head2 doGenerateToc
syntax: [0|1]
default: 1
applicable to: TocInsertor, TocUpdator
True (1) if ToC must be generated. False (0) if ToC must be inserted only.
=head2 doUseGroupsGlobal
syntax: [0|1]
default: 0
applicable to: TocGenerator, TocInsertor, TocUpdator
True (1) if group levels must be used globally accross ToCs. False (0) if not. This option only makes sense when an array of ToCs is specified. For example, suppose you want to generate two ToCs, one ToC for '' tokens and one ToC for '' tokens, of the file 'index.htm':
Chapter
Paragraph
Using the default setting of 'doUseGroupsGlobal' => 0:
use HTML::Toc;
use HTML::TocGenerator;
my $toc1 = HTML::Toc->new();
my $toc2 = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc1->setOptions({
'header' => '',
'footer' => '',
'tokenToToc' => [{'tokenBegin' => ''}]
});
$toc2->setOptions({
'header' => '',
'footer' => '',
'tokenToToc' => [{'tokenBegin' => ''}]
});
$tocGenerator->generateFromFile([$toc1, $toc2], 'index.htm');
print $toc1->format() . "\n\n" . $toc2->format();
the output will be:
Each ToC will use its own numbering scheme. Now if 'C' is specified:
$tocGenerator->generateFromFile(
[$toc1, $toc2], 'index.htm', {'doUseGroupsGlobal' => 1}
);
the output will be:
using a global numbering scheme for all ToCs.
=head2 output
syntax: reference to scalar
default: none
applicable to: TocInsertor, TocUpdator
Reference to scalar where the output must be stored in.
=head2 outputFile
syntax: scalar
default: none
applicable to: TocInsertor, TocUpdator
Filename to write output to. If no filename is specified, output will be written to standard output.
=head1 HTML::Toc Options
The C options can be grouped in the following categories:
=over 4
=item L
=item L
=item L
=item L
=back
The ToC options must be specified using the 'setOptions' method. For example:
my $toc = new HTML::Toc;
$toc->setOptions({
'doNumberToken' => 1,
'footer' => ''
'tokenToToc' => [{
'level' => 1,
'tokenBegin' => '',
'numberingStyle' => 'lower-alpha'
}]
});
=head2 Generate options
=over 4
=item Token groups
=over 4
=item L
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=item L
=item L
=back
=item Numbering tokens
=over 4
=item L
=item L
=item L
=back
=item Miscellaneous
=over 4
=item L
=item L
=item L
=item L
=back
=item Linking ToC to tokens
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=back
=head2 Insert options
=over 4
=item L
=back
=head2 Update options
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=back
=head2 Format options
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=head1 HTML::Toc Options Reference
=head2 attributeToExcludeToken
syntax: $scalar
default: '-'
Token which marks an attribute value in a L or L token as an attribute value a token should not have to be marked as a ToC token. See also: L.
=head2 attributeToTocToken
syntax: $scalar
default: '@'
Token which marks an attribute in a L token as an attribute which must be used as ToC text. See also: L.
=head2 doLinkToToken
syntax: [0|1]
default: 1
True (1) if ToC must be linked to tokens, False (0) if not. Note that 'HTML::TocInsertor' must be used to do the actual insertion of the anchor name within the source data.
=head2 doLinkToFile
syntax: [0|1]
default: 0
True (1) if ToC must be linked to file, False (0) if not. In effect only when L equals True (1) and L isn't specified.
=head2 doLinkToId
syntax: [0|1]
default: 0
True (1) if ToC must be linked to tokens by using token ids. False (0) if ToC must be linked to tokens by using anchor names.
=head2 doNestGroup
syntax: [0|1]
default: 0
True (1) if groups must be nested in the formatted ToC, False (0) if not. In effect only when multiple groups are specified within the L setting. For an example, see L.
=head2 doNumberToken
syntax: [0|1]
default: 0
True (1) if tokens which are used for the ToC generation must be numbered. This option may be specified both as a global ToC option or within a L group. When specified within a C option, the C applies to that group only. For an example, see L.
=head2 doSingleStepLevel
syntax: [0|1]
default: 1
True (1) if levels of a formatted ToC must advance one level at a time. For example, when generating a ToC of a file with a missing '':
Chapter
Paragraph
By default, an empty indentation level will be inserted in the ToC:
After specifying:
$toc->setOptions({'doSingleStepLevel' => 0});
the ToC will not have an indentation level inserted for level 2:
=head2 fileSpec
syntax:
default: undef
Specifies which files should match the current level. Valid only if L equals 1. For an example, see L.
=head2 footer
syntax: $scalar
default: "\n\n"
String to output at end of ToC.
=head2 groupId
syntax: $scalar
default: 'h'
Sets the group id attribute of a tokenGroup. With this attribute it's possible to divide the ToC into multiple groups. Each group has its own numbering scheme. For example, to generate a ToC of both normal headings and 'appendix' headings, specify the following ToC settings:
$toc->setOptions({
'tokenToToc' => [{
'tokenBegin' => ''
}, {
'groupId' => 'appendix',
'tokenBegin' => ''
}]
});
=head2 groupToToc
syntax:
default: '.*'
Determines which groups to use for generating the ToC. For example, to create a ToC for groups [a-b] only, specify:
'groupToToc => '[a-b]'
This option is evaluated during both ToC generation and ToC formatting. This enables you to generate a ToC of all groups, but - after generating - format only specified groups:
$toc->setOptions({'groupToToc' => '.*'});
$tocGenerator->generateToc($toc, ...);
# Get ToC of all groups
$fullToc = $toc->format();
# Get ToC of 'appendix' group only
$toc->setOptions({'groupToToc' => 'appendix'});
$appendixToc = $toc->format();
=head2 header
syntax: $scalar
default: "\n\n"
String to output at begin of ToC.
=head2 insertionPoint
syntax: []
default: 'after '
token: <[/]tag{ attribute=[-|@]}> |
|
|
Determines the point within the source, where the ToC should be inserted. When specifying a start tag as the insertion point token, attributes to be included may be specified as well. Note that the attribute value must be specified as a regular expression. For example, to specify the C<> tag as insertion point:
''
Examples of valid 'insertionPoint' tokens are:
''
'
'
''
''
'ToC will be placed here'
It is also possible to specify attributes to exclude, by prefixing the value with an L, default a minus sign (-). For example, to specify the C<> tag as insertion point, excluding all C<> tags:
''
See also L.
=head2 level
syntax: number
default: 1
Number which identifies at which level the tokengroup should be incorporated into the ToC. See also: L.
=head2 levelIndent
syntax: number
default: 3
Sets the number of spaces each level will be indented, when formatting the ToC.
=head2 levelToToc
syntax:
default: '.*'
Determines which group levels to use for generating the ToC. For example, to create a ToC for levels 1-2 only, specify:
'levelToToc => '[1-2]'
This option is evaluated during both ToC generation and ToC formatting. This enables you to generate a ToC of all levels, but - after generating - retrieve only specified levels:
$toc->setOptions({'levelToToc' => '.*'});
$tocGenerator->generateToc($toc, ...);
# Get ToC of all levels
$fullToc = $toc->getToc();
# Get ToC of level 1 only
$toc->setOptions({'levelToToc' => '1'});
$level1Toc = $toc->getToc();
=head2 numberingStyle
syntax: [decimal|lower-alpha|upper-alpha|lower-roman|upper-roman]}
default: decimal
Determines which numbering style to use for a token group when L is set to True (1). When specified as a main ToC option, the setting will be the default for all groups. When specified within a tokengroup, this setting will override any default for that particular tokengroup, e.g.:
$toc->setOptions({
'doNumberToken' => 1,
'tokenToToc' => [{
'level' => 1,
'tokenBegin' => '',
'numberingStyle' => 'lower-alpha'
}]
});
If C style is specified, be sure to have the Roman module installed, available from L.
=head2 templateAnchorName
syntax:
default: '$groupId."-".$node'
Anchor name to use when L is set to True (1). The anchor name is passed to both L and L. The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
If C is a function reference to a function returning the anchor, like in:
$toc->setOptions({'templateAnchorName' => \&assembleAnchorName});
the function will be called with the following arguments:
$anchorName = assembleAnchorName($file, $groupId, $level, $node);
=head2 templateAnchorHrefBegin
syntax:
default: '""' or
'""',
depending on 'doLinkToFile' being 0 or 1 respectively.
Anchor reference begin token to use when L is set to True (1). The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
$anchorName
If C is a function reference to a function returning the anchor, like in:
$toc->setOptions({'templateAnchorHrefBegin' => \&assembleAnchorHrefBegin});
the function will be called with the following arguments:
$anchorHrefBegin = &assembleAnchorHrefBegin(
$file, $groupId, $level, $node, $anchorName
);
See also: L, L.
=head2 templateAnchorHrefEnd
syntax:
default: '" "'
Anchor reference end token to use when L is set to True (1). The template may be specified as either an expression or a function reference. If L is a function reference to a function returning the anchor end, like in:
$toc->setOptions({'templateAnchorHrefEnd' => \&assembleAnchorHrefEnd});
the function will be called without arguments:
$anchorHrefEnd = &assembleAnchorHrefEnd;
See also: L.
=head2 templateAnchorNameBegin
syntax:
default: '""'
Anchor name begin token to use when L is set to True (1). The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
$anchorName
If C is a function reference to a function returning the anchor name, like in:
$toc->setOptions({'templateAnchorNameBegin' => \&assembleAnchorNameBegin});
the function will be called with the following arguments:
$anchorNameBegin = assembleAnchorNameBegin(
$file, $groupId, $level, $node, $anchorName
);
See also: L, L.
=head2 templateAnchorNameEnd
syntax:
default: '" "'
Anchor name end token to use when L is set to True (1). The template may be specified as either an expression or a function reference. If L is a function reference to a function returning the anchor end, like in:
$toc->setOptions({'templateAnchorNameEnd' => \&assembleAnchorNameEnd});
the function will be called without arguments:
$anchorNameEnd = &assembleAnchorNameEnd;
See also: L.
=head2 templateLevel
syntax:
default: '"- $text\n"'
Expression to use when formatting a ToC node. The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$level
$groupId
$node
$sequenceNr
$text
If C
is a function reference to a function returning the ToC node, like in:
$toc->setOptions({'templateLevel' => \&AssembleTocNode});
the function will be called with the following arguments:
$tocNode = &AssembleTocNode(
$level, $groupId, $node, $sequenceNr, $text
);
=head2 templateLevelBegin
syntax:
default: '"\n"'
Expression to use when formatting begin of ToC level. See L for list of available variables to use within the expression. For example, to give each ToC level a class name to use with Cascading Style Sheets (CSS), use the expression:
'"\n"'
which will result in each ToC group being given a class name:
- Header
For an example, see L.
=head2 templateLevelEnd
syntax:
default: '"\n"'
Expression to use when formatting end of ToC level. See L for a list of available variables to use within the expression. The default expression is:
'"
\n"'
For an example, see L.
=head2 templateTokenNumber
syntax:
default: '"$node "'
Token number to use when L equals True (1). The template may be specified as either an expression or a function reference. The expression has access to the following variables:
$file
$groupId
$groupLevel
$level
$node
$toc
If C is a function reference to a function returning the token number, like in:
$toc->setOptions({'templateTokenNumber' => \&assembleTokenNumber});
the function will be called with the following arguments:
$number = &assembleTokenNumber(
$node, $groupId, $file, $groupLevel, $level, $toc
);
=head2 tokenBegin
syntax:
default: ''
token: <[/]tag{ attribute=[-|@]}> |
|
|
This scalar defines the token that will trigger text to be put into the ToC. Any start tag, end tag, comment, declaration or text string can be specified. Examples of valid 'tokenBegin' tokens are:
''
''
''
''
'ToC entry'
When specifying a start tag, attributes to be included may be specified as well. Note that the attribute value is used as a regular expression. For example, to specify the C<> tag as tokenBegin:
''
It is also possible to specify attributes to exclude, by prefixing the value with an L, default a minus sign (-). For example, to specify the C<> tag as tokenBegin, excluding all C<> tags:
''
Also, you can specify here an attribute value which has to be used as ToC text, by prefixing the value with an L, default an at sign (@). For example, to use the class value as ToC text:
''
See L for an elaborated example using the C to generate a ToC of image C attribute values.
See also: L, L.
=head2 tokenEnd
syntax: $scalar
default: empty string ('') or end tag counterpart of 'tokenBegin' if
'tokenBegin' is a start tag
The 'tokenEnd' definition applies to the same rules as L.
See also: L, L.
=head2 tokenToToc
syntax: [{array of hashrefs}]
default: [{
'level' => 1,
'tokenBegin' => ''
}, {
'level' => 2,
'tokenBegin' => ''
}, {
'level' => 3,
'tokenBegin' => ''
}, {
'level' => 4,
'tokenBegin' => ''
}, {
'level' => 5,
'tokenBegin' => ''
}, {
'level' => 6,
'tokenBegin' => ''
}]
This hash define the tokens that must act as ToC entries. Each tokengroup may contain a L, L, L, L and L identifier.
=head2 tokenUpdateBeginAnchorName
syntax:
default: '';
This token marks the begin of an anchor name, inserted by C. This option is used by C.
=head2 tokenUpdateEndAnchorName
syntax:
default: '';
This option is used by C, to mark the end of an inserted anchor name.
=head2 tokenUpdateBeginNumber
syntax:
default: '';
This option is used by C, to mark the begin of an inserted number.
=head2 tokenUpdateEndNumber
syntax:
default: '';
This option is used by C, to mark the end of an inserted number.
=head2 tokenUpdateBeginToc
syntax:
default: '';
This option is used by C, to mark the begin of an inserted ToC.
=head2 tokenUpdateEndToc
syntax:
default: '';
This option is used by C, to mark the end of an inserted ToC.
=head1 Known issues
=head2 Cygwin
In order for the test files to run on Cygwin without errors, the 'UNIX' default text file type has to be selected during the Cygwin setup.
When extracting the tar.gz file with WinZip the 'TAR file smart CR/LF conversion' has to be turned off via {Options|Configuration...|Miscellaneous} in order for the files 'toc.pod' and './manualTest/manualTest1.htm' to be left in UNIX format.
=head2 Nested anchors
HTML::Toc can only link to existing anchors if these anchors are placed outside of the ToC tokens. Otherwise a warning will be given. For example, generating a L ToC of Ch1E> tokens of the following text:
Chapter
the output will be:Chapter
If you're planning to update the inserted ToC, you'd better use CChapter
the output will contain additional update tokens: around the inserted ToC elements:Chapter
Instead of C>..C<> of file C, and insert or update the ToC after the C<> tag at the same time:
use HTML::Toc;
use HTML::TocUpdator;
my $toc = HTML::Toc->new();
my $tocUpdator = HTML::TocUpdator->new();
$tocUpdator->updateFile($toc, 'indexToc.htm');
For example, with C containing:
foo
bar
Chapter
foo
h
the output will be:
Chapter
All text between the update tokens will be replaced. So be warned: all manual changes made to text between update tokens will be removed unrecoverable after calling C or C.
=head2 Formatting
The ToC isn't generated all at once. There are two stages involved: generating and formatting. Generating the ToC actually means storing a preliminary ToC in C{_toc}>. This preliminary, tokenized ToC has to be turned into something useful by calling Cformat()>. For an example, see paragraph 'L'.
=head1 Advanced
The ToC generation can be modified in a variety of ways. The following paragraphs each explain a single modification. An example of most of the modifications can be found in the C test file. Within this test, a manual containing:
preface
introduction
table of contents
table of figures
table of tables
parts
chapters
appendixes
bibliography
is formatted.
=head2 Using attribute value as ToC text
Normally, the ToC will be made of text between specified ToC tokens. It's also possible to use the attribute value of a token as a ToC text. This can be done by specifying the attribute marked with an L within the L token. For example, suppose you want to generate a ToC of the C attributes of the following image tokens:
This would be the code:
use HTML::Toc;
use HTML::TocInsertor;
my $toc = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$toc->setOptions({
'tokenToToc' => [{
'groupId' => 'image',
'tokenBegin' => '![@]()
'
}],
});
$tocInsertor->insertIntoFile($toc, $filename);
and the output will be:
=head2 Generate single ToC of multiple files
Besides generating a ToC of a single file, it's also possible to generate a single ToC of multiple files. This can be done by specifying either an array of files as the file argument and/or by extending an existing ToC.
=head3 Specify an array of files
For example, suppose you want to generate a ToC of both C:
Chapter of document 1
and C:
Chapter of document 2
Here's the code to do so by specifying an array of files:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({'doLinkToFile' => 1});
$tocGenerator->generateFromFile($toc, ['doc1.htm', 'doc2.htm']);
print $toc->format();
And the output will be:
=head3 Extend an existing ToC
It's also possible to extend an existing ToC. For example, suppose we want the generate a ToC of file C:
Chapter of document 1
and extend this ToC with text from C:
Chapter of document 2
Here's the code to do so:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({'doLinkToFile' => 1});
$tocGenerator->generateFromFile($toc, 'doc1.htm');
$tocGenerator->extendFromFile($toc, 'doc2.htm');
print $toc->format();
And the output will be:
=head2 Generate multiple ToCs
It's possible to generate multiple ToCs at once by specifying a C object array as the ToC argument. For example, suppose you want to generate a default ToC of HTML headings .. as well as a ToC of the C image attributes of the following text:
Header One
Paragraph One
Here's how you would do so:
use HTML::Toc;
use HTML::TocInsertor;
my $toc1 = HTML::Toc->new();
my $toc2 = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$toc2->setOptions({
'tokenToToc' => [{
'groupId' => 'image',
'tokenBegin' => '![@]()
'
}],
});
$tocInsertor->insertIntoFile([$toc1, $toc2], $filename);
And the output will be:
Header One
Paragraph One
=head2 Generate multiple groups in one ToC
You may want to generate a ToC consisting of multiple ToC groups.
=head3 Specify an additional 'Appendix' group
Suppose you want to generate a ToC with one group for the normal headings, and one group for the appendix headings, using this source file:
Chapter
Paragraph
Subparagraph
Chapter
Appendix Chapter
Appendix Paragraph
With the code underneath:
use HTML::Toc;
use HTML::TocInsertor;
my $toc = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$toc->setOptions({
'tokenToToc' => [{
'tokenBegin' => ''
}, {
'tokenBegin' => '',
'level' => 2
}, {
'groupId' => 'appendix',
'tokenBegin' => '',
}, {
'groupId' => 'appendix',
'tokenBegin' => '',
'level' => 2
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
the output will be:
Chapter
Paragraph
Subparagraph
Chapter
Appendix Chapter
Appendix Paragraph
=head3 Specify an additional 'Part' group
Suppose you want to generate a ToC of a document which is divided in multiple parts like this file underneath:
First Part
Chapter
Paragraph
Second Part
Chapter
Paragraph
With the code underneath:
use HTML::Toc;
use HTML::TocInsertor;
my $toc = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$toc->setOptions({
'doNumberToken' => 1,
'tokenToToc' => [{
'tokenBegin' => ''
}, {
'tokenBegin' => '',
'level' => 2,
}, {
'groupId' => 'part',
'tokenBegin' => '',
'level' => 1,
'numberingStyle' => 'upper-alpha'
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
the output will be:
A First Part
1 Chapter
1.1 Paragraph
B Second Part
2 Chapter
2.1 Paragraph
=head2 Number ToC entries
By default, the generated ToC will list its entries unnumbered. If you want to number the ToC entries, two options are available. Either you can specify a numbered list by modifying L and L. Or when the ToC isn't a simple numbered list, you can use the numbers generated by HTML::TocGenerator.
=head3 Specify numbered list
By modifying L and L you can specify a numbered ToC:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({
'templateLevelBegin' => '"\n"',
'templateLevelEnd' => '"
\n"',
});
$tocGenerator->generateFromFile($toc, 'index.htm');
print $toc->format();
For instance with the original file containing:
Chapter
Paragraph
The formatted ToC now will contain C instead of C tags:
See also: L.
=head3 Use generated numbers
Instead of using the HTML ordered list (OL), it's also possible to use the generated numbers to number to ToC nodes. This can be done by modifying L:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({
'templateLevel' => '"- $node $text\n"',
});
$tocGenerator->generateFromFile($toc, 'index.htm');
print $toc->format();
For instance with the original file containing:
Chapter
Paragraph
The formatted ToC now will have the node numbers hard-coded:
See also: L.
=head2 Using CSS for ToC formatting
Suppose you want to display a ToC with upper-alpha numbered appendix headings. To accomplish this, you can specify a CSS style within the source document:
Appendix
Appendix Paragraph
Appendix
Appendix Paragraph
Here's the code:
my $toc = new HTML::Toc;
my $tocInsertor = new HTML::TocInsertor;
$toc->setOptions({
'templateLevelBegin' => '"\n"',
'templateLevelEnd' => '"
\n"',
'doNumberToken' => 1,
'tokenToToc' => [{
'groupId' => 'appendix',
'tokenBegin' => '',
'numberingStyle' => 'upper-alpha'
}, {
'groupId' => 'appendix',
'tokenBegin' => '',
'level' => 2,
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
Which whill result in the following output:
A Appendix
A.1 Appendix Paragraph
B Appendix
B.1 Appendix Paragraph
=head2 Creating site map
Suppose you want to generate a table of contents of the EtitleE tags of the files in the following directory structure:
path file
. index.htm, Main
|- SubDir1 index.htm, Sub1
| |- SubSubDir1 index.htm, SubSub1
|
|- SubDir2 index.htm, Sub2
| |- SubSubDir1 index.htm, SubSub1
| |- SubSubDir2 index.htm, SubSub2
|
|- SubDir3 index.htm, Sub3
By specifying 'fileSpec' which determine how many slashes (/) each file may contain for a specific level:
use HTML::Toc;
use HTML::TocGenerator;
use File::Find;
my $toc = HTML::Toc->new;
my $tocGenerator = HTML::TocGenerator->new;
my @fileList;
sub wanted {
# Add file to 'fileList' if extension matches '.htm'
push (@fileList, $File::Find::name) if (m/\.htm$/);
}
$toc->setOptions({
'doLinkToFile' => 1,
'templateAnchorName' => '""',
'templateAnchorHref' => '""',
'doLinkTocToToken' => 1,
'tokenToToc' => [{
'groupId' => 'dir',
'level' => 1,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+$'
}, {
'groupId' => 'dir',
'level' => 2,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+?/[^/]+$'
}, {
'groupId' => 'dir',
'level' => 3,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+?/[^/]+?/[^/]+$'
}]
});
# Traverse directory structure
find({wanted => \&wanted, no_chdir => 1}, '.');
# Generate ToC of case-insensitively sorted file list
$tocGenerator->extendFromFile(
$toc, [sort {uc($a) cmp uc($b)} @fileList]
);
print $toc->format();
the following ToC will be generated:
=head1 Methods
=head2 HTML::Toc::clear()
syntax: $toc->clear()
returns: --
Clear the ToC.
=head2 HTML::Toc::format()
syntax: $scalar = $toc->format()
returns: Formatted ToC.
Format tokenized ToC.
=head2 HTML::TocGenerator::extend()
syntax: $tocGenerator->extend($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to extend
- $string: string to retrieve ToC from
- $options: hash reference containing generator options.
Extend ToC from specified string. For generator options, see L
=head2 HTML::TocGenerator::extendFromFile()
syntax: $tocGenerator->extendFromFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to extend
- $filename: (reference to array of) file(s) to extend ToC from
- $options: hash reference containing generator options.
Extend ToC from specified file. For generator options, see L. For an example, see L.
=head2 HTML::TocGenerator::generate()
syntax: $tocGenerator->generate($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to generate
- $string: string to retrieve ToC from
- $options: hash reference containing generator options.
Generate ToC from specified string. Before generating, the ToC will be cleared. For extending an existing ToC, use the L method. For generator options, see L.
=head2 HTML::TocGenerator::generateFromFile()
syntax: $tocGenerator->generateFromFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to
generate
- $filename: (reference to array of) file(s) to generate ToC from
- $options: hash reference containing generator options.
Generate ToC from specified file. Before generating, the ToC will be cleared. For extending an extisting ToC, use the L method. For generator options, see L.
=head2 HTML::TocInsertor::insert()
syntax: $tocInsertor->insert($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to insert ToC in
- $options: hash reference containing insertor options.
Insert ToC into specified string. For insertor options, see L.
=head2 HTML::TocInsertor::insertIntoFile()
syntax: $tocInsertor->insertIntoFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to insert ToC in
- $options: hash reference containing insertor options.
Insert ToC into specified file. For insertor options, see L.
=head2 HTML::TocUpdator::insert()
syntax: $tocUpdator->insert($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to insert ToC in
- $options: hash reference containing updator options.
Insert ToC into specified string. Differs from L in that inserted text will be surrounded with update tokens in order for C to be able to update this text the next time an update is issued. For updator options, see L.
=head2 HTML::TocUpdator::insertIntoFile()
syntax: $tocUpdator->insertIntoFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to insert ToC in
- $options: hash reference containing updator options.
Insert ToC into specified file. Differs from L in that inserted text will be surrounded with update tokens in order for C to be able to update this text the next time an update is issued. For updator options, see L.
=head2 HTML::TocUpdator::update()
syntax: $tocUpdator->update($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to update ToC in
- $options: hash reference containing updator options.
Update ToC within specified string. For updator options, see L.
=head2 HTML::TocUpdator::updateFile()
syntax: $tocUpdator->updateFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to update ToC in
- $options: hash reference containing updator options.
Update ToC of specified file. For updator options, see L.
=head1 Parser Options
When generating a ToC, additional options may be specified which influence the way the ToCs are generated using either C, C or C. The options must be specified as a hash reference. For example:
$tocGenerator->generateFromFile($toc, $filename, {doUseGroupsGlobal => 1});
Available options are:
=over 4
=item L
=item L
=item L
=item L
=back
=head2 doGenerateToc
syntax: [0|1]
default: 1
applicable to: TocInsertor, TocUpdator
True (1) if ToC must be generated. False (0) if ToC must be inserted only.
=head2 doUseGroupsGlobal
syntax: [0|1]
default: 0
applicable to: TocGenerator, TocInsertor, TocUpdator
True (1) if group levels must be used globally accross ToCs. False (0) if not. This option only makes sense when an array of ToCs is specified. For example, suppose you want to generate two ToCs, one ToC for '' tokens and one ToC for '' tokens, of the file 'index.htm':
Chapter
Paragraph
Using the default setting of 'doUseGroupsGlobal' => 0:
use HTML::Toc;
use HTML::TocGenerator;
my $toc1 = HTML::Toc->new();
my $toc2 = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc1->setOptions({
'header' => '',
'footer' => '',
'tokenToToc' => [{'tokenBegin' => ''}]
});
$toc2->setOptions({
'header' => '',
'footer' => '',
'tokenToToc' => [{'tokenBegin' => ''}]
});
$tocGenerator->generateFromFile([$toc1, $toc2], 'index.htm');
print $toc1->format() . "\n\n" . $toc2->format();
the output will be:
Each ToC will use its own numbering scheme. Now if 'C' is specified:
$tocGenerator->generateFromFile(
[$toc1, $toc2], 'index.htm', {'doUseGroupsGlobal' => 1}
);
the output will be:
using a global numbering scheme for all ToCs.
=head2 output
syntax: reference to scalar
default: none
applicable to: TocInsertor, TocUpdator
Reference to scalar where the output must be stored in.
=head2 outputFile
syntax: scalar
default: none
applicable to: TocInsertor, TocUpdator
Filename to write output to. If no filename is specified, output will be written to standard output.
=head1 HTML::Toc Options
The C options can be grouped in the following categories:
=over 4
=item L
=item L
=item L
=item L
=back
The ToC options must be specified using the 'setOptions' method. For example:
my $toc = new HTML::Toc;
$toc->setOptions({
'doNumberToken' => 1,
'footer' => ''
'tokenToToc' => [{
'level' => 1,
'tokenBegin' => '',
'numberingStyle' => 'lower-alpha'
}]
});
=head2 Generate options
=over 4
=item Token groups
=over 4
=item L
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=item L
=item L
=back
=item Numbering tokens
=over 4
=item L
=item L
=item L
=back
=item Miscellaneous
=over 4
=item L
=item L
=item L
=item L
=back
=item Linking ToC to tokens
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=back
=head2 Insert options
=over 4
=item L
=back
=head2 Update options
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=back
=head2 Format options
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=head1 HTML::Toc Options Reference
=head2 attributeToExcludeToken
syntax: $scalar
default: '-'
Token which marks an attribute value in a L or L token as an attribute value a token should not have to be marked as a ToC token. See also: L.
=head2 attributeToTocToken
syntax: $scalar
default: '@'
Token which marks an attribute in a L token as an attribute which must be used as ToC text. See also: L.
=head2 doLinkToToken
syntax: [0|1]
default: 1
True (1) if ToC must be linked to tokens, False (0) if not. Note that 'HTML::TocInsertor' must be used to do the actual insertion of the anchor name within the source data.
=head2 doLinkToFile
syntax: [0|1]
default: 0
True (1) if ToC must be linked to file, False (0) if not. In effect only when L equals True (1) and L isn't specified.
=head2 doLinkToId
syntax: [0|1]
default: 0
True (1) if ToC must be linked to tokens by using token ids. False (0) if ToC must be linked to tokens by using anchor names.
=head2 doNestGroup
syntax: [0|1]
default: 0
True (1) if groups must be nested in the formatted ToC, False (0) if not. In effect only when multiple groups are specified within the L setting. For an example, see L.
=head2 doNumberToken
syntax: [0|1]
default: 0
True (1) if tokens which are used for the ToC generation must be numbered. This option may be specified both as a global ToC option or within a L group. When specified within a C option, the C applies to that group only. For an example, see L.
=head2 doSingleStepLevel
syntax: [0|1]
default: 1
True (1) if levels of a formatted ToC must advance one level at a time. For example, when generating a ToC of a file with a missing '':
Chapter
Paragraph
By default, an empty indentation level will be inserted in the ToC:
After specifying:
$toc->setOptions({'doSingleStepLevel' => 0});
the ToC will not have an indentation level inserted for level 2:
=head2 fileSpec
syntax:
default: undef
Specifies which files should match the current level. Valid only if L equals 1. For an example, see L.
=head2 footer
syntax: $scalar
default: "\n\n"
String to output at end of ToC.
=head2 groupId
syntax: $scalar
default: 'h'
Sets the group id attribute of a tokenGroup. With this attribute it's possible to divide the ToC into multiple groups. Each group has its own numbering scheme. For example, to generate a ToC of both normal headings and 'appendix' headings, specify the following ToC settings:
$toc->setOptions({
'tokenToToc' => [{
'tokenBegin' => ''
}, {
'groupId' => 'appendix',
'tokenBegin' => ''
}]
});
=head2 groupToToc
syntax:
default: '.*'
Determines which groups to use for generating the ToC. For example, to create a ToC for groups [a-b] only, specify:
'groupToToc => '[a-b]'
This option is evaluated during both ToC generation and ToC formatting. This enables you to generate a ToC of all groups, but - after generating - format only specified groups:
$toc->setOptions({'groupToToc' => '.*'});
$tocGenerator->generateToc($toc, ...);
# Get ToC of all groups
$fullToc = $toc->format();
# Get ToC of 'appendix' group only
$toc->setOptions({'groupToToc' => 'appendix'});
$appendixToc = $toc->format();
=head2 header
syntax: $scalar
default: "\n\n"
String to output at begin of ToC.
=head2 insertionPoint
syntax: []
default: 'after '
token: <[/]tag{ attribute=[-|@]}> |
|
|
Determines the point within the source, where the ToC should be inserted. When specifying a start tag as the insertion point token, attributes to be included may be specified as well. Note that the attribute value must be specified as a regular expression. For example, to specify the C<> tag as insertion point:
''
Examples of valid 'insertionPoint' tokens are:
''
'
'
''
''
'ToC will be placed here'
It is also possible to specify attributes to exclude, by prefixing the value with an L, default a minus sign (-). For example, to specify the C<> tag as insertion point, excluding all C<> tags:
''
See also L.
=head2 level
syntax: number
default: 1
Number which identifies at which level the tokengroup should be incorporated into the ToC. See also: L.
=head2 levelIndent
syntax: number
default: 3
Sets the number of spaces each level will be indented, when formatting the ToC.
=head2 levelToToc
syntax:
default: '.*'
Determines which group levels to use for generating the ToC. For example, to create a ToC for levels 1-2 only, specify:
'levelToToc => '[1-2]'
This option is evaluated during both ToC generation and ToC formatting. This enables you to generate a ToC of all levels, but - after generating - retrieve only specified levels:
$toc->setOptions({'levelToToc' => '.*'});
$tocGenerator->generateToc($toc, ...);
# Get ToC of all levels
$fullToc = $toc->getToc();
# Get ToC of level 1 only
$toc->setOptions({'levelToToc' => '1'});
$level1Toc = $toc->getToc();
=head2 numberingStyle
syntax: [decimal|lower-alpha|upper-alpha|lower-roman|upper-roman]}
default: decimal
Determines which numbering style to use for a token group when L is set to True (1). When specified as a main ToC option, the setting will be the default for all groups. When specified within a tokengroup, this setting will override any default for that particular tokengroup, e.g.:
$toc->setOptions({
'doNumberToken' => 1,
'tokenToToc' => [{
'level' => 1,
'tokenBegin' => '',
'numberingStyle' => 'lower-alpha'
}]
});
If C style is specified, be sure to have the Roman module installed, available from L.
=head2 templateAnchorName
syntax:
default: '$groupId."-".$node'
Anchor name to use when L is set to True (1). The anchor name is passed to both L and L. The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
If C is a function reference to a function returning the anchor, like in:
$toc->setOptions({'templateAnchorName' => \&assembleAnchorName});
the function will be called with the following arguments:
$anchorName = assembleAnchorName($file, $groupId, $level, $node);
=head2 templateAnchorHrefBegin
syntax:
default: '""' or
'""',
depending on 'doLinkToFile' being 0 or 1 respectively.
Anchor reference begin token to use when L is set to True (1). The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
$anchorName
If C is a function reference to a function returning the anchor, like in:
$toc->setOptions({'templateAnchorHrefBegin' => \&assembleAnchorHrefBegin});
the function will be called with the following arguments:
$anchorHrefBegin = &assembleAnchorHrefBegin(
$file, $groupId, $level, $node, $anchorName
);
See also: L, L.
=head2 templateAnchorHrefEnd
syntax:
default: '" "'
Anchor reference end token to use when L is set to True (1). The template may be specified as either an expression or a function reference. If L is a function reference to a function returning the anchor end, like in:
$toc->setOptions({'templateAnchorHrefEnd' => \&assembleAnchorHrefEnd});
the function will be called without arguments:
$anchorHrefEnd = &assembleAnchorHrefEnd;
See also: L.
=head2 templateAnchorNameBegin
syntax:
default: '""'
Anchor name begin token to use when L is set to True (1). The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
$anchorName
If C is a function reference to a function returning the anchor name, like in:
$toc->setOptions({'templateAnchorNameBegin' => \&assembleAnchorNameBegin});
the function will be called with the following arguments:
$anchorNameBegin = assembleAnchorNameBegin(
$file, $groupId, $level, $node, $anchorName
);
See also: L, L.
=head2 templateAnchorNameEnd
syntax:
default: '" "'
Anchor name end token to use when L is set to True (1). The template may be specified as either an expression or a function reference. If L is a function reference to a function returning the anchor end, like in:
$toc->setOptions({'templateAnchorNameEnd' => \&assembleAnchorNameEnd});
the function will be called without arguments:
$anchorNameEnd = &assembleAnchorNameEnd;
See also: L.
=head2 templateLevel
syntax:
default: '"- $text\n"'
Expression to use when formatting a ToC node. The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$level
$groupId
$node
$sequenceNr
$text
If C
is a function reference to a function returning the ToC node, like in:
$toc->setOptions({'templateLevel' => \&AssembleTocNode});
the function will be called with the following arguments:
$tocNode = &AssembleTocNode(
$level, $groupId, $node, $sequenceNr, $text
);
=head2 templateLevelBegin
syntax:
default: '"\n"'
Expression to use when formatting begin of ToC level. See L for list of available variables to use within the expression. For example, to give each ToC level a class name to use with Cascading Style Sheets (CSS), use the expression:
'"\n"'
which will result in each ToC group being given a class name:
- Header
For an example, see L.
=head2 templateLevelEnd
syntax:
default: '"\n"'
Expression to use when formatting end of ToC level. See L for a list of available variables to use within the expression. The default expression is:
'"
\n"'
For an example, see L.
=head2 templateTokenNumber
syntax:
default: '"$node "'
Token number to use when L equals True (1). The template may be specified as either an expression or a function reference. The expression has access to the following variables:
$file
$groupId
$groupLevel
$level
$node
$toc
If C is a function reference to a function returning the token number, like in:
$toc->setOptions({'templateTokenNumber' => \&assembleTokenNumber});
the function will be called with the following arguments:
$number = &assembleTokenNumber(
$node, $groupId, $file, $groupLevel, $level, $toc
);
=head2 tokenBegin
syntax:
default: ''
token: <[/]tag{ attribute=[-|@]}> |
|
|
This scalar defines the token that will trigger text to be put into the ToC. Any start tag, end tag, comment, declaration or text string can be specified. Examples of valid 'tokenBegin' tokens are:
''
''
''
''
'ToC entry'
When specifying a start tag, attributes to be included may be specified as well. Note that the attribute value is used as a regular expression. For example, to specify the C<> tag as tokenBegin:
''
It is also possible to specify attributes to exclude, by prefixing the value with an L, default a minus sign (-). For example, to specify the C<> tag as tokenBegin, excluding all C<> tags:
''
Also, you can specify here an attribute value which has to be used as ToC text, by prefixing the value with an L, default an at sign (@). For example, to use the class value as ToC text:
''
See L for an elaborated example using the C to generate a ToC of image C attribute values.
See also: L, L.
=head2 tokenEnd
syntax: $scalar
default: empty string ('') or end tag counterpart of 'tokenBegin' if
'tokenBegin' is a start tag
The 'tokenEnd' definition applies to the same rules as L.
See also: L, L.
=head2 tokenToToc
syntax: [{array of hashrefs}]
default: [{
'level' => 1,
'tokenBegin' => ''
}, {
'level' => 2,
'tokenBegin' => ''
}, {
'level' => 3,
'tokenBegin' => ''
}, {
'level' => 4,
'tokenBegin' => ''
}, {
'level' => 5,
'tokenBegin' => ''
}, {
'level' => 6,
'tokenBegin' => ''
}]
This hash define the tokens that must act as ToC entries. Each tokengroup may contain a L, L, L, L and L identifier.
=head2 tokenUpdateBeginAnchorName
syntax:
default: '';
This token marks the begin of an anchor name, inserted by C. This option is used by C.
=head2 tokenUpdateEndAnchorName
syntax:
default: '';
This option is used by C, to mark the end of an inserted anchor name.
=head2 tokenUpdateBeginNumber
syntax:
default: '';
This option is used by C, to mark the begin of an inserted number.
=head2 tokenUpdateEndNumber
syntax:
default: '';
This option is used by C, to mark the end of an inserted number.
=head2 tokenUpdateBeginToc
syntax:
default: '';
This option is used by C, to mark the begin of an inserted ToC.
=head2 tokenUpdateEndToc
syntax:
default: '';
This option is used by C, to mark the end of an inserted ToC.
=head1 Known issues
=head2 Cygwin
In order for the test files to run on Cygwin without errors, the 'UNIX' default text file type has to be selected during the Cygwin setup.
When extracting the tar.gz file with WinZip the 'TAR file smart CR/LF conversion' has to be turned off via {Options|Configuration...|Miscellaneous} in order for the files 'toc.pod' and './manualTest/manualTest1.htm' to be left in UNIX format.
=head2 Nested anchors
HTML::Toc can only link to existing anchors if these anchors are placed outside of the ToC tokens. Otherwise a warning will be given. For example, generating a L ToC of Ch1E> tokens of the following text:
Chapter
foo h the output will be:Chapter
All text between the update tokens will be replaced. So be warned: all manual changes made to text between update tokens will be removed unrecoverable after calling C
This would be the code:
use HTML::Toc;
use HTML::TocInsertor;
my $toc = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$toc->setOptions({
'tokenToToc' => [{
'groupId' => 'image',
'tokenBegin' => '
=head2 Generate single ToC of multiple files
Besides generating a ToC of a single file, it's also possible to generate a single ToC of multiple files. This can be done by specifying either an array of files as the file argument and/or by extending an existing ToC.
=head3 Specify an array of files
For example, suppose you want to generate a ToC of both CChapter of document 1
and CChapter of document 2
Here's the code to do so by specifying an array of files: use HTML::Toc; use HTML::TocGenerator; my $toc = HTML::Toc->new(); my $tocGenerator = HTML::TocGenerator->new(); $toc->setOptions({'doLinkToFile' => 1}); $tocGenerator->generateFromFile($toc, ['doc1.htm', 'doc2.htm']); print $toc->format(); And the output will be: =head3 Extend an existing ToC It's also possible to extend an existing ToC. For example, suppose we want the generate a ToC of file CChapter of document 1
and extend this ToC with text from CChapter of document 2
Here's the code to do so: use HTML::Toc; use HTML::TocGenerator; my $toc = HTML::Toc->new(); my $tocGenerator = HTML::TocGenerator->new(); $toc->setOptions({'doLinkToFile' => 1}); $tocGenerator->generateFromFile($toc, 'doc1.htm'); $tocGenerator->extendFromFile($toc, 'doc2.htm'); print $toc->format(); And the output will be: =head2 Generate multiple ToCs It's possible to generate multiple ToCs at once by specifying a C.. as well as a ToC of the C image attributes of the following text:
Header One
Paragraph One
Here's how you would do so:
use HTML::Toc;
use HTML::TocInsertor;
my $toc1 = HTML::Toc->new();
my $toc2 = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$toc2->setOptions({
'tokenToToc' => [{
'groupId' => 'image',
'tokenBegin' => '![@]()
'
}],
});
$tocInsertor->insertIntoFile([$toc1, $toc2], $filename);
And the output will be:
Header One
Paragraph One
=head2 Generate multiple groups in one ToC
You may want to generate a ToC consisting of multiple ToC groups.
=head3 Specify an additional 'Appendix' group
Suppose you want to generate a ToC with one group for the normal headings, and one group for the appendix headings, using this source file:
Chapter
Paragraph
Subparagraph
Chapter
Appendix Chapter
Appendix Paragraph
With the code underneath:
use HTML::Toc;
use HTML::TocInsertor;
my $toc = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$toc->setOptions({
'tokenToToc' => [{
'tokenBegin' => ''
}, {
'tokenBegin' => '',
'level' => 2
}, {
'groupId' => 'appendix',
'tokenBegin' => '',
}, {
'groupId' => 'appendix',
'tokenBegin' => '',
'level' => 2
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
the output will be:
Chapter
Paragraph
Subparagraph
Chapter
Appendix Chapter
Appendix Paragraph
=head3 Specify an additional 'Part' group
Suppose you want to generate a ToC of a document which is divided in multiple parts like this file underneath:
First Part
Chapter
Paragraph
Second Part
Chapter
Paragraph
With the code underneath:
use HTML::Toc;
use HTML::TocInsertor;
my $toc = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$toc->setOptions({
'doNumberToken' => 1,
'tokenToToc' => [{
'tokenBegin' => ''
}, {
'tokenBegin' => '',
'level' => 2,
}, {
'groupId' => 'part',
'tokenBegin' => '',
'level' => 1,
'numberingStyle' => 'upper-alpha'
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
the output will be:
A First Part
1 Chapter
1.1 Paragraph
B Second Part
2 Chapter
2.1 Paragraph
=head2 Number ToC entries
By default, the generated ToC will list its entries unnumbered. If you want to number the ToC entries, two options are available. Either you can specify a numbered list by modifying L and L. Or when the ToC isn't a simple numbered list, you can use the numbers generated by HTML::TocGenerator.
=head3 Specify numbered list
By modifying L and L you can specify a numbered ToC:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({
'templateLevelBegin' => '"\n"',
'templateLevelEnd' => '"
\n"',
});
$tocGenerator->generateFromFile($toc, 'index.htm');
print $toc->format();
For instance with the original file containing:
Chapter
Paragraph
The formatted ToC now will contain C instead of C tags:
See also: L.
=head3 Use generated numbers
Instead of using the HTML ordered list (OL), it's also possible to use the generated numbers to number to ToC nodes. This can be done by modifying L:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({
'templateLevel' => '"- $node $text\n"',
});
$tocGenerator->generateFromFile($toc, 'index.htm');
print $toc->format();
For instance with the original file containing:
Chapter
Paragraph
The formatted ToC now will have the node numbers hard-coded:
See also: L.
=head2 Using CSS for ToC formatting
Suppose you want to display a ToC with upper-alpha numbered appendix headings. To accomplish this, you can specify a CSS style within the source document:
Appendix
Appendix Paragraph
Appendix
Appendix Paragraph
Here's the code:
my $toc = new HTML::Toc;
my $tocInsertor = new HTML::TocInsertor;
$toc->setOptions({
'templateLevelBegin' => '"\n"',
'templateLevelEnd' => '"
\n"',
'doNumberToken' => 1,
'tokenToToc' => [{
'groupId' => 'appendix',
'tokenBegin' => '',
'numberingStyle' => 'upper-alpha'
}, {
'groupId' => 'appendix',
'tokenBegin' => '',
'level' => 2,
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
Which whill result in the following output:
A Appendix
A.1 Appendix Paragraph
B Appendix
B.1 Appendix Paragraph
=head2 Creating site map
Suppose you want to generate a table of contents of the EtitleE tags of the files in the following directory structure:
path file
. index.htm, Main
|- SubDir1 index.htm, Sub1
| |- SubSubDir1 index.htm, SubSub1
|
|- SubDir2 index.htm, Sub2
| |- SubSubDir1 index.htm, SubSub1
| |- SubSubDir2 index.htm, SubSub2
|
|- SubDir3 index.htm, Sub3
By specifying 'fileSpec' which determine how many slashes (/) each file may contain for a specific level:
use HTML::Toc;
use HTML::TocGenerator;
use File::Find;
my $toc = HTML::Toc->new;
my $tocGenerator = HTML::TocGenerator->new;
my @fileList;
sub wanted {
# Add file to 'fileList' if extension matches '.htm'
push (@fileList, $File::Find::name) if (m/\.htm$/);
}
$toc->setOptions({
'doLinkToFile' => 1,
'templateAnchorName' => '""',
'templateAnchorHref' => '""',
'doLinkTocToToken' => 1,
'tokenToToc' => [{
'groupId' => 'dir',
'level' => 1,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+$'
}, {
'groupId' => 'dir',
'level' => 2,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+?/[^/]+$'
}, {
'groupId' => 'dir',
'level' => 3,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+?/[^/]+?/[^/]+$'
}]
});
# Traverse directory structure
find({wanted => \&wanted, no_chdir => 1}, '.');
# Generate ToC of case-insensitively sorted file list
$tocGenerator->extendFromFile(
$toc, [sort {uc($a) cmp uc($b)} @fileList]
);
print $toc->format();
the following ToC will be generated:
=head1 Methods
=head2 HTML::Toc::clear()
syntax: $toc->clear()
returns: --
Clear the ToC.
=head2 HTML::Toc::format()
syntax: $scalar = $toc->format()
returns: Formatted ToC.
Format tokenized ToC.
=head2 HTML::TocGenerator::extend()
syntax: $tocGenerator->extend($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to extend
- $string: string to retrieve ToC from
- $options: hash reference containing generator options.
Extend ToC from specified string. For generator options, see L
=head2 HTML::TocGenerator::extendFromFile()
syntax: $tocGenerator->extendFromFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to extend
- $filename: (reference to array of) file(s) to extend ToC from
- $options: hash reference containing generator options.
Extend ToC from specified file. For generator options, see L. For an example, see L.
=head2 HTML::TocGenerator::generate()
syntax: $tocGenerator->generate($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to generate
- $string: string to retrieve ToC from
- $options: hash reference containing generator options.
Generate ToC from specified string. Before generating, the ToC will be cleared. For extending an existing ToC, use the L method. For generator options, see L.
=head2 HTML::TocGenerator::generateFromFile()
syntax: $tocGenerator->generateFromFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to
generate
- $filename: (reference to array of) file(s) to generate ToC from
- $options: hash reference containing generator options.
Generate ToC from specified file. Before generating, the ToC will be cleared. For extending an extisting ToC, use the L method. For generator options, see L.
=head2 HTML::TocInsertor::insert()
syntax: $tocInsertor->insert($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to insert ToC in
- $options: hash reference containing insertor options.
Insert ToC into specified string. For insertor options, see L.
=head2 HTML::TocInsertor::insertIntoFile()
syntax: $tocInsertor->insertIntoFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to insert ToC in
- $options: hash reference containing insertor options.
Insert ToC into specified file. For insertor options, see L.
=head2 HTML::TocUpdator::insert()
syntax: $tocUpdator->insert($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to insert ToC in
- $options: hash reference containing updator options.
Insert ToC into specified string. Differs from L in that inserted text will be surrounded with update tokens in order for C to be able to update this text the next time an update is issued. For updator options, see L.
=head2 HTML::TocUpdator::insertIntoFile()
syntax: $tocUpdator->insertIntoFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to insert ToC in
- $options: hash reference containing updator options.
Insert ToC into specified file. Differs from L in that inserted text will be surrounded with update tokens in order for C to be able to update this text the next time an update is issued. For updator options, see L.
=head2 HTML::TocUpdator::update()
syntax: $tocUpdator->update($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to update ToC in
- $options: hash reference containing updator options.
Update ToC within specified string. For updator options, see L.
=head2 HTML::TocUpdator::updateFile()
syntax: $tocUpdator->updateFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to update ToC in
- $options: hash reference containing updator options.
Update ToC of specified file. For updator options, see L.
=head1 Parser Options
When generating a ToC, additional options may be specified which influence the way the ToCs are generated using either C, C or C. The options must be specified as a hash reference. For example:
$tocGenerator->generateFromFile($toc, $filename, {doUseGroupsGlobal => 1});
Available options are:
=over 4
=item L
=item L
=item L
=item L
=back
=head2 doGenerateToc
syntax: [0|1]
default: 1
applicable to: TocInsertor, TocUpdator
True (1) if ToC must be generated. False (0) if ToC must be inserted only.
=head2 doUseGroupsGlobal
syntax: [0|1]
default: 0
applicable to: TocGenerator, TocInsertor, TocUpdator
True (1) if group levels must be used globally accross ToCs. False (0) if not. This option only makes sense when an array of ToCs is specified. For example, suppose you want to generate two ToCs, one ToC for '' tokens and one ToC for '' tokens, of the file 'index.htm':
Chapter
Paragraph
Using the default setting of 'doUseGroupsGlobal' => 0:
use HTML::Toc;
use HTML::TocGenerator;
my $toc1 = HTML::Toc->new();
my $toc2 = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc1->setOptions({
'header' => '',
'footer' => '',
'tokenToToc' => [{'tokenBegin' => ''}]
});
$toc2->setOptions({
'header' => '',
'footer' => '',
'tokenToToc' => [{'tokenBegin' => ''}]
});
$tocGenerator->generateFromFile([$toc1, $toc2], 'index.htm');
print $toc1->format() . "\n\n" . $toc2->format();
the output will be:
Each ToC will use its own numbering scheme. Now if 'C' is specified:
$tocGenerator->generateFromFile(
[$toc1, $toc2], 'index.htm', {'doUseGroupsGlobal' => 1}
);
the output will be:
using a global numbering scheme for all ToCs.
=head2 output
syntax: reference to scalar
default: none
applicable to: TocInsertor, TocUpdator
Reference to scalar where the output must be stored in.
=head2 outputFile
syntax: scalar
default: none
applicable to: TocInsertor, TocUpdator
Filename to write output to. If no filename is specified, output will be written to standard output.
=head1 HTML::Toc Options
The C options can be grouped in the following categories:
=over 4
=item L
=item L
=item L
=item L
=back
The ToC options must be specified using the 'setOptions' method. For example:
my $toc = new HTML::Toc;
$toc->setOptions({
'doNumberToken' => 1,
'footer' => ''
'tokenToToc' => [{
'level' => 1,
'tokenBegin' => '',
'numberingStyle' => 'lower-alpha'
}]
});
=head2 Generate options
=over 4
=item Token groups
=over 4
=item L
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=item L
=item L
=back
=item Numbering tokens
=over 4
=item L
=item L
=item L
=back
=item Miscellaneous
=over 4
=item L
=item L
=item L
=item L
=back
=item Linking ToC to tokens
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=back
=head2 Insert options
=over 4
=item L
=back
=head2 Update options
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=back
=head2 Format options
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=head1 HTML::Toc Options Reference
=head2 attributeToExcludeToken
syntax: $scalar
default: '-'
Token which marks an attribute value in a L or L token as an attribute value a token should not have to be marked as a ToC token. See also: L.
=head2 attributeToTocToken
syntax: $scalar
default: '@'
Token which marks an attribute in a L token as an attribute which must be used as ToC text. See also: L.
=head2 doLinkToToken
syntax: [0|1]
default: 1
True (1) if ToC must be linked to tokens, False (0) if not. Note that 'HTML::TocInsertor' must be used to do the actual insertion of the anchor name within the source data.
=head2 doLinkToFile
syntax: [0|1]
default: 0
True (1) if ToC must be linked to file, False (0) if not. In effect only when L equals True (1) and L isn't specified.
=head2 doLinkToId
syntax: [0|1]
default: 0
True (1) if ToC must be linked to tokens by using token ids. False (0) if ToC must be linked to tokens by using anchor names.
=head2 doNestGroup
syntax: [0|1]
default: 0
True (1) if groups must be nested in the formatted ToC, False (0) if not. In effect only when multiple groups are specified within the L setting. For an example, see L.
=head2 doNumberToken
syntax: [0|1]
default: 0
True (1) if tokens which are used for the ToC generation must be numbered. This option may be specified both as a global ToC option or within a L group. When specified within a C option, the C applies to that group only. For an example, see L.
=head2 doSingleStepLevel
syntax: [0|1]
default: 1
True (1) if levels of a formatted ToC must advance one level at a time. For example, when generating a ToC of a file with a missing '':
Chapter
Paragraph
By default, an empty indentation level will be inserted in the ToC:
After specifying:
$toc->setOptions({'doSingleStepLevel' => 0});
the ToC will not have an indentation level inserted for level 2:
=head2 fileSpec
syntax:
default: undef
Specifies which files should match the current level. Valid only if L equals 1. For an example, see L.
=head2 footer
syntax: $scalar
default: "\n\n"
String to output at end of ToC.
=head2 groupId
syntax: $scalar
default: 'h'
Sets the group id attribute of a tokenGroup. With this attribute it's possible to divide the ToC into multiple groups. Each group has its own numbering scheme. For example, to generate a ToC of both normal headings and 'appendix' headings, specify the following ToC settings:
$toc->setOptions({
'tokenToToc' => [{
'tokenBegin' => ''
}, {
'groupId' => 'appendix',
'tokenBegin' => ''
}]
});
=head2 groupToToc
syntax:
default: '.*'
Determines which groups to use for generating the ToC. For example, to create a ToC for groups [a-b] only, specify:
'groupToToc => '[a-b]'
This option is evaluated during both ToC generation and ToC formatting. This enables you to generate a ToC of all groups, but - after generating - format only specified groups:
$toc->setOptions({'groupToToc' => '.*'});
$tocGenerator->generateToc($toc, ...);
# Get ToC of all groups
$fullToc = $toc->format();
# Get ToC of 'appendix' group only
$toc->setOptions({'groupToToc' => 'appendix'});
$appendixToc = $toc->format();
=head2 header
syntax: $scalar
default: "\n\n"
String to output at begin of ToC.
=head2 insertionPoint
syntax: []
default: 'after '
token: <[/]tag{ attribute=[-|@]}> |
|
|
Determines the point within the source, where the ToC should be inserted. When specifying a start tag as the insertion point token, attributes to be included may be specified as well. Note that the attribute value must be specified as a regular expression. For example, to specify the C<> tag as insertion point:
''
Examples of valid 'insertionPoint' tokens are:
''
'
'
''
''
'ToC will be placed here'
It is also possible to specify attributes to exclude, by prefixing the value with an L, default a minus sign (-). For example, to specify the C<> tag as insertion point, excluding all C<> tags:
''
See also L.
=head2 level
syntax: number
default: 1
Number which identifies at which level the tokengroup should be incorporated into the ToC. See also: L.
=head2 levelIndent
syntax: number
default: 3
Sets the number of spaces each level will be indented, when formatting the ToC.
=head2 levelToToc
syntax:
default: '.*'
Determines which group levels to use for generating the ToC. For example, to create a ToC for levels 1-2 only, specify:
'levelToToc => '[1-2]'
This option is evaluated during both ToC generation and ToC formatting. This enables you to generate a ToC of all levels, but - after generating - retrieve only specified levels:
$toc->setOptions({'levelToToc' => '.*'});
$tocGenerator->generateToc($toc, ...);
# Get ToC of all levels
$fullToc = $toc->getToc();
# Get ToC of level 1 only
$toc->setOptions({'levelToToc' => '1'});
$level1Toc = $toc->getToc();
=head2 numberingStyle
syntax: [decimal|lower-alpha|upper-alpha|lower-roman|upper-roman]}
default: decimal
Determines which numbering style to use for a token group when L is set to True (1). When specified as a main ToC option, the setting will be the default for all groups. When specified within a tokengroup, this setting will override any default for that particular tokengroup, e.g.:
$toc->setOptions({
'doNumberToken' => 1,
'tokenToToc' => [{
'level' => 1,
'tokenBegin' => '',
'numberingStyle' => 'lower-alpha'
}]
});
If C style is specified, be sure to have the Roman module installed, available from L.
=head2 templateAnchorName
syntax:
default: '$groupId."-".$node'
Anchor name to use when L is set to True (1). The anchor name is passed to both L and L. The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
If C is a function reference to a function returning the anchor, like in:
$toc->setOptions({'templateAnchorName' => \&assembleAnchorName});
the function will be called with the following arguments:
$anchorName = assembleAnchorName($file, $groupId, $level, $node);
=head2 templateAnchorHrefBegin
syntax:
default: '""' or
'""',
depending on 'doLinkToFile' being 0 or 1 respectively.
Anchor reference begin token to use when L is set to True (1). The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
$anchorName
If C is a function reference to a function returning the anchor, like in:
$toc->setOptions({'templateAnchorHrefBegin' => \&assembleAnchorHrefBegin});
the function will be called with the following arguments:
$anchorHrefBegin = &assembleAnchorHrefBegin(
$file, $groupId, $level, $node, $anchorName
);
See also: L, L.
=head2 templateAnchorHrefEnd
syntax:
default: '" "'
Anchor reference end token to use when L is set to True (1). The template may be specified as either an expression or a function reference. If L is a function reference to a function returning the anchor end, like in:
$toc->setOptions({'templateAnchorHrefEnd' => \&assembleAnchorHrefEnd});
the function will be called without arguments:
$anchorHrefEnd = &assembleAnchorHrefEnd;
See also: L.
=head2 templateAnchorNameBegin
syntax:
default: '""'
Anchor name begin token to use when L is set to True (1). The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
$anchorName
If C is a function reference to a function returning the anchor name, like in:
$toc->setOptions({'templateAnchorNameBegin' => \&assembleAnchorNameBegin});
the function will be called with the following arguments:
$anchorNameBegin = assembleAnchorNameBegin(
$file, $groupId, $level, $node, $anchorName
);
See also: L, L.
=head2 templateAnchorNameEnd
syntax:
default: '" "'
Anchor name end token to use when L is set to True (1). The template may be specified as either an expression or a function reference. If L is a function reference to a function returning the anchor end, like in:
$toc->setOptions({'templateAnchorNameEnd' => \&assembleAnchorNameEnd});
the function will be called without arguments:
$anchorNameEnd = &assembleAnchorNameEnd;
See also: L.
=head2 templateLevel
syntax:
default: '"- $text\n"'
Expression to use when formatting a ToC node. The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$level
$groupId
$node
$sequenceNr
$text
If C
is a function reference to a function returning the ToC node, like in:
$toc->setOptions({'templateLevel' => \&AssembleTocNode});
the function will be called with the following arguments:
$tocNode = &AssembleTocNode(
$level, $groupId, $node, $sequenceNr, $text
);
=head2 templateLevelBegin
syntax:
default: '"\n"'
Expression to use when formatting begin of ToC level. See L for list of available variables to use within the expression. For example, to give each ToC level a class name to use with Cascading Style Sheets (CSS), use the expression:
'"\n"'
which will result in each ToC group being given a class name:
- Header
For an example, see L.
=head2 templateLevelEnd
syntax:
default: '"\n"'
Expression to use when formatting end of ToC level. See L for a list of available variables to use within the expression. The default expression is:
'"
\n"'
For an example, see L.
=head2 templateTokenNumber
syntax:
default: '"$node "'
Token number to use when L equals True (1). The template may be specified as either an expression or a function reference. The expression has access to the following variables:
$file
$groupId
$groupLevel
$level
$node
$toc
If C is a function reference to a function returning the token number, like in:
$toc->setOptions({'templateTokenNumber' => \&assembleTokenNumber});
the function will be called with the following arguments:
$number = &assembleTokenNumber(
$node, $groupId, $file, $groupLevel, $level, $toc
);
=head2 tokenBegin
syntax:
default: ''
token: <[/]tag{ attribute=[-|@]}> |
|
|
This scalar defines the token that will trigger text to be put into the ToC. Any start tag, end tag, comment, declaration or text string can be specified. Examples of valid 'tokenBegin' tokens are:
''
''
''
''
'ToC entry'
When specifying a start tag, attributes to be included may be specified as well. Note that the attribute value is used as a regular expression. For example, to specify the C<> tag as tokenBegin:
''
It is also possible to specify attributes to exclude, by prefixing the value with an L, default a minus sign (-). For example, to specify the C<> tag as tokenBegin, excluding all C<> tags:
''
Also, you can specify here an attribute value which has to be used as ToC text, by prefixing the value with an L, default an at sign (@). For example, to use the class value as ToC text:
''
See L for an elaborated example using the C to generate a ToC of image C attribute values.
See also: L, L.
=head2 tokenEnd
syntax: $scalar
default: empty string ('') or end tag counterpart of 'tokenBegin' if
'tokenBegin' is a start tag
The 'tokenEnd' definition applies to the same rules as L.
See also: L, L.
=head2 tokenToToc
syntax: [{array of hashrefs}]
default: [{
'level' => 1,
'tokenBegin' => ''
}, {
'level' => 2,
'tokenBegin' => ''
}, {
'level' => 3,
'tokenBegin' => ''
}, {
'level' => 4,
'tokenBegin' => ''
}, {
'level' => 5,
'tokenBegin' => ''
}, {
'level' => 6,
'tokenBegin' => ''
}]
This hash define the tokens that must act as ToC entries. Each tokengroup may contain a L, L, L, L and L identifier.
=head2 tokenUpdateBeginAnchorName
syntax:
default: '';
This token marks the begin of an anchor name, inserted by C. This option is used by C.
=head2 tokenUpdateEndAnchorName
syntax:
default: '';
This option is used by C, to mark the end of an inserted anchor name.
=head2 tokenUpdateBeginNumber
syntax:
default: '';
This option is used by C, to mark the begin of an inserted number.
=head2 tokenUpdateEndNumber
syntax:
default: '';
This option is used by C, to mark the end of an inserted number.
=head2 tokenUpdateBeginToc
syntax:
default: '';
This option is used by C, to mark the begin of an inserted ToC.
=head2 tokenUpdateEndToc
syntax:
default: '';
This option is used by C, to mark the end of an inserted ToC.
=head1 Known issues
=head2 Cygwin
In order for the test files to run on Cygwin without errors, the 'UNIX' default text file type has to be selected during the Cygwin setup.
When extracting the tar.gz file with WinZip the 'TAR file smart CR/LF conversion' has to be turned off via {Options|Configuration...|Miscellaneous} in order for the files 'toc.pod' and './manualTest/manualTest1.htm' to be left in UNIX format.
=head2 Nested anchors
HTML::Toc can only link to existing anchors if these anchors are placed outside of the ToC tokens. Otherwise a warning will be given. For example, generating a L ToC of Ch1E> tokens of the following text:
Header One
Paragraph One
Here's how you would do so:
use HTML::Toc;
use HTML::TocInsertor;
my $toc1 = HTML::Toc->new();
my $toc2 = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$toc2->setOptions({
'tokenToToc' => [{
'groupId' => 'image',
'tokenBegin' => 'Header One
Paragraph One
=head2 Generate multiple groups in one ToC
You may want to generate a ToC consisting of multiple ToC groups.
=head3 Specify an additional 'Appendix' group
Suppose you want to generate a ToC with one group for the normal headings, and one group for the appendix headings, using this source file:
Chapter
Paragraph
Subparagraph
Chapter
Appendix Chapter
Appendix Paragraph
With the code underneath: use HTML::Toc; use HTML::TocInsertor; my $toc = HTML::Toc->new(); my $tocInsertor = HTML::TocInsertor->new(); $toc->setOptions({ 'tokenToToc' => [{ 'tokenBegin' => ''
}, {
'tokenBegin' => '',
'level' => 2
}, {
'groupId' => 'appendix',
'tokenBegin' => '',
}, {
'groupId' => 'appendix',
'tokenBegin' => '',
'level' => 2
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
the output will be:
Chapter
Paragraph
Subparagraph
Chapter
Appendix Chapter
Appendix Paragraph
=head3 Specify an additional 'Part' group
Suppose you want to generate a ToC of a document which is divided in multiple parts like this file underneath:
First Part
Chapter
Paragraph
Second Part
Chapter
Paragraph
With the code underneath:
use HTML::Toc;
use HTML::TocInsertor;
my $toc = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$toc->setOptions({
'doNumberToken' => 1,
'tokenToToc' => [{
'tokenBegin' => ''
}, {
'tokenBegin' => '',
'level' => 2,
}, {
'groupId' => 'part',
'tokenBegin' => '',
'level' => 1,
'numberingStyle' => 'upper-alpha'
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
the output will be:
A First Part
1 Chapter
1.1 Paragraph
B Second Part
2 Chapter
2.1 Paragraph
=head2 Number ToC entries
By default, the generated ToC will list its entries unnumbered. If you want to number the ToC entries, two options are available. Either you can specify a numbered list by modifying L and L. Or when the ToC isn't a simple numbered list, you can use the numbers generated by HTML::TocGenerator.
=head3 Specify numbered list
By modifying L and L you can specify a numbered ToC:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({
'templateLevelBegin' => '"\n"',
'templateLevelEnd' => '"
\n"',
});
$tocGenerator->generateFromFile($toc, 'index.htm');
print $toc->format();
For instance with the original file containing:
Chapter
Paragraph
The formatted ToC now will contain C instead of C tags:
See also: L.
=head3 Use generated numbers
Instead of using the HTML ordered list (OL), it's also possible to use the generated numbers to number to ToC nodes. This can be done by modifying L:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({
'templateLevel' => '"- $node $text\n"',
});
$tocGenerator->generateFromFile($toc, 'index.htm');
print $toc->format();
For instance with the original file containing:
Chapter
Paragraph
The formatted ToC now will have the node numbers hard-coded:
See also: L.
=head2 Using CSS for ToC formatting
Suppose you want to display a ToC with upper-alpha numbered appendix headings. To accomplish this, you can specify a CSS style within the source document:
Appendix
Appendix Paragraph
Appendix
Appendix Paragraph
Here's the code:
my $toc = new HTML::Toc;
my $tocInsertor = new HTML::TocInsertor;
$toc->setOptions({
'templateLevelBegin' => '"\n"',
'templateLevelEnd' => '"
\n"',
'doNumberToken' => 1,
'tokenToToc' => [{
'groupId' => 'appendix',
'tokenBegin' => '',
'numberingStyle' => 'upper-alpha'
}, {
'groupId' => 'appendix',
'tokenBegin' => '',
'level' => 2,
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
Which whill result in the following output:
A Appendix
A.1 Appendix Paragraph
B Appendix
B.1 Appendix Paragraph
=head2 Creating site map
Suppose you want to generate a table of contents of the EtitleE tags of the files in the following directory structure:
path file
. index.htm, Main
|- SubDir1 index.htm, Sub1
| |- SubSubDir1 index.htm, SubSub1
|
|- SubDir2 index.htm, Sub2
| |- SubSubDir1 index.htm, SubSub1
| |- SubSubDir2 index.htm, SubSub2
|
|- SubDir3 index.htm, Sub3
By specifying 'fileSpec' which determine how many slashes (/) each file may contain for a specific level:
use HTML::Toc;
use HTML::TocGenerator;
use File::Find;
my $toc = HTML::Toc->new;
my $tocGenerator = HTML::TocGenerator->new;
my @fileList;
sub wanted {
# Add file to 'fileList' if extension matches '.htm'
push (@fileList, $File::Find::name) if (m/\.htm$/);
}
$toc->setOptions({
'doLinkToFile' => 1,
'templateAnchorName' => '""',
'templateAnchorHref' => '""',
'doLinkTocToToken' => 1,
'tokenToToc' => [{
'groupId' => 'dir',
'level' => 1,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+$'
}, {
'groupId' => 'dir',
'level' => 2,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+?/[^/]+$'
}, {
'groupId' => 'dir',
'level' => 3,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+?/[^/]+?/[^/]+$'
}]
});
# Traverse directory structure
find({wanted => \&wanted, no_chdir => 1}, '.');
# Generate ToC of case-insensitively sorted file list
$tocGenerator->extendFromFile(
$toc, [sort {uc($a) cmp uc($b)} @fileList]
);
print $toc->format();
the following ToC will be generated:
=head1 Methods
=head2 HTML::Toc::clear()
syntax: $toc->clear()
returns: --
Clear the ToC.
=head2 HTML::Toc::format()
syntax: $scalar = $toc->format()
returns: Formatted ToC.
Format tokenized ToC.
=head2 HTML::TocGenerator::extend()
syntax: $tocGenerator->extend($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to extend
- $string: string to retrieve ToC from
- $options: hash reference containing generator options.
Extend ToC from specified string. For generator options, see L
=head2 HTML::TocGenerator::extendFromFile()
syntax: $tocGenerator->extendFromFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to extend
- $filename: (reference to array of) file(s) to extend ToC from
- $options: hash reference containing generator options.
Extend ToC from specified file. For generator options, see L. For an example, see L.
=head2 HTML::TocGenerator::generate()
syntax: $tocGenerator->generate($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to generate
- $string: string to retrieve ToC from
- $options: hash reference containing generator options.
Generate ToC from specified string. Before generating, the ToC will be cleared. For extending an existing ToC, use the L method. For generator options, see L.
=head2 HTML::TocGenerator::generateFromFile()
syntax: $tocGenerator->generateFromFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to
generate
- $filename: (reference to array of) file(s) to generate ToC from
- $options: hash reference containing generator options.
Generate ToC from specified file. Before generating, the ToC will be cleared. For extending an extisting ToC, use the L method. For generator options, see L.
=head2 HTML::TocInsertor::insert()
syntax: $tocInsertor->insert($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to insert ToC in
- $options: hash reference containing insertor options.
Insert ToC into specified string. For insertor options, see L.
=head2 HTML::TocInsertor::insertIntoFile()
syntax: $tocInsertor->insertIntoFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to insert ToC in
- $options: hash reference containing insertor options.
Insert ToC into specified file. For insertor options, see L.
=head2 HTML::TocUpdator::insert()
syntax: $tocUpdator->insert($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to insert ToC in
- $options: hash reference containing updator options.
Insert ToC into specified string. Differs from L in that inserted text will be surrounded with update tokens in order for C to be able to update this text the next time an update is issued. For updator options, see L.
=head2 HTML::TocUpdator::insertIntoFile()
syntax: $tocUpdator->insertIntoFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to insert ToC in
- $options: hash reference containing updator options.
Insert ToC into specified file. Differs from L in that inserted text will be surrounded with update tokens in order for C to be able to update this text the next time an update is issued. For updator options, see L.
=head2 HTML::TocUpdator::update()
syntax: $tocUpdator->update($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to update ToC in
- $options: hash reference containing updator options.
Update ToC within specified string. For updator options, see L.
=head2 HTML::TocUpdator::updateFile()
syntax: $tocUpdator->updateFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to update ToC in
- $options: hash reference containing updator options.
Update ToC of specified file. For updator options, see L.
=head1 Parser Options
When generating a ToC, additional options may be specified which influence the way the ToCs are generated using either C, C or C. The options must be specified as a hash reference. For example:
$tocGenerator->generateFromFile($toc, $filename, {doUseGroupsGlobal => 1});
Available options are:
=over 4
=item L
=item L
=item L
=item L
=back
=head2 doGenerateToc
syntax: [0|1]
default: 1
applicable to: TocInsertor, TocUpdator
True (1) if ToC must be generated. False (0) if ToC must be inserted only.
=head2 doUseGroupsGlobal
syntax: [0|1]
default: 0
applicable to: TocGenerator, TocInsertor, TocUpdator
True (1) if group levels must be used globally accross ToCs. False (0) if not. This option only makes sense when an array of ToCs is specified. For example, suppose you want to generate two ToCs, one ToC for '' tokens and one ToC for '' tokens, of the file 'index.htm':
Chapter
Paragraph
Using the default setting of 'doUseGroupsGlobal' => 0:
use HTML::Toc;
use HTML::TocGenerator;
my $toc1 = HTML::Toc->new();
my $toc2 = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc1->setOptions({
'header' => '',
'footer' => '',
'tokenToToc' => [{'tokenBegin' => ''}]
});
$toc2->setOptions({
'header' => '',
'footer' => '',
'tokenToToc' => [{'tokenBegin' => ''}]
});
$tocGenerator->generateFromFile([$toc1, $toc2], 'index.htm');
print $toc1->format() . "\n\n" . $toc2->format();
the output will be:
Each ToC will use its own numbering scheme. Now if 'C' is specified:
$tocGenerator->generateFromFile(
[$toc1, $toc2], 'index.htm', {'doUseGroupsGlobal' => 1}
);
the output will be:
using a global numbering scheme for all ToCs.
=head2 output
syntax: reference to scalar
default: none
applicable to: TocInsertor, TocUpdator
Reference to scalar where the output must be stored in.
=head2 outputFile
syntax: scalar
default: none
applicable to: TocInsertor, TocUpdator
Filename to write output to. If no filename is specified, output will be written to standard output.
=head1 HTML::Toc Options
The C options can be grouped in the following categories:
=over 4
=item L
=item L
=item L
=item L
=back
The ToC options must be specified using the 'setOptions' method. For example:
my $toc = new HTML::Toc;
$toc->setOptions({
'doNumberToken' => 1,
'footer' => ''
'tokenToToc' => [{
'level' => 1,
'tokenBegin' => '',
'numberingStyle' => 'lower-alpha'
}]
});
=head2 Generate options
=over 4
=item Token groups
=over 4
=item L
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=item L
=item L
=back
=item Numbering tokens
=over 4
=item L
=item L
=item L
=back
=item Miscellaneous
=over 4
=item L
=item L
=item L
=item L
=back
=item Linking ToC to tokens
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=back
=head2 Insert options
=over 4
=item L
=back
=head2 Update options
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=back
=head2 Format options
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=head1 HTML::Toc Options Reference
=head2 attributeToExcludeToken
syntax: $scalar
default: '-'
Token which marks an attribute value in a L or L token as an attribute value a token should not have to be marked as a ToC token. See also: L.
=head2 attributeToTocToken
syntax: $scalar
default: '@'
Token which marks an attribute in a L token as an attribute which must be used as ToC text. See also: L.
=head2 doLinkToToken
syntax: [0|1]
default: 1
True (1) if ToC must be linked to tokens, False (0) if not. Note that 'HTML::TocInsertor' must be used to do the actual insertion of the anchor name within the source data.
=head2 doLinkToFile
syntax: [0|1]
default: 0
True (1) if ToC must be linked to file, False (0) if not. In effect only when L equals True (1) and L isn't specified.
=head2 doLinkToId
syntax: [0|1]
default: 0
True (1) if ToC must be linked to tokens by using token ids. False (0) if ToC must be linked to tokens by using anchor names.
=head2 doNestGroup
syntax: [0|1]
default: 0
True (1) if groups must be nested in the formatted ToC, False (0) if not. In effect only when multiple groups are specified within the L setting. For an example, see L.
=head2 doNumberToken
syntax: [0|1]
default: 0
True (1) if tokens which are used for the ToC generation must be numbered. This option may be specified both as a global ToC option or within a L group. When specified within a C option, the C applies to that group only. For an example, see L.
=head2 doSingleStepLevel
syntax: [0|1]
default: 1
True (1) if levels of a formatted ToC must advance one level at a time. For example, when generating a ToC of a file with a missing '':
Chapter
Paragraph
By default, an empty indentation level will be inserted in the ToC:
After specifying:
$toc->setOptions({'doSingleStepLevel' => 0});
the ToC will not have an indentation level inserted for level 2:
=head2 fileSpec
syntax:
default: undef
Specifies which files should match the current level. Valid only if L equals 1. For an example, see L.
=head2 footer
syntax: $scalar
default: "\n\n"
String to output at end of ToC.
=head2 groupId
syntax: $scalar
default: 'h'
Sets the group id attribute of a tokenGroup. With this attribute it's possible to divide the ToC into multiple groups. Each group has its own numbering scheme. For example, to generate a ToC of both normal headings and 'appendix' headings, specify the following ToC settings:
$toc->setOptions({
'tokenToToc' => [{
'tokenBegin' => ''
}, {
'groupId' => 'appendix',
'tokenBegin' => ''
}]
});
=head2 groupToToc
syntax:
default: '.*'
Determines which groups to use for generating the ToC. For example, to create a ToC for groups [a-b] only, specify:
'groupToToc => '[a-b]'
This option is evaluated during both ToC generation and ToC formatting. This enables you to generate a ToC of all groups, but - after generating - format only specified groups:
$toc->setOptions({'groupToToc' => '.*'});
$tocGenerator->generateToc($toc, ...);
# Get ToC of all groups
$fullToc = $toc->format();
# Get ToC of 'appendix' group only
$toc->setOptions({'groupToToc' => 'appendix'});
$appendixToc = $toc->format();
=head2 header
syntax: $scalar
default: "\n\n"
String to output at begin of ToC.
=head2 insertionPoint
syntax: []
default: 'after '
token: <[/]tag{ attribute=[-|@]}> |
|
|
Determines the point within the source, where the ToC should be inserted. When specifying a start tag as the insertion point token, attributes to be included may be specified as well. Note that the attribute value must be specified as a regular expression. For example, to specify the C<> tag as insertion point:
''
Examples of valid 'insertionPoint' tokens are:
''
'
'
''
''
'ToC will be placed here'
It is also possible to specify attributes to exclude, by prefixing the value with an L, default a minus sign (-). For example, to specify the C<> tag as insertion point, excluding all C<> tags:
''
See also L.
=head2 level
syntax: number
default: 1
Number which identifies at which level the tokengroup should be incorporated into the ToC. See also: L.
=head2 levelIndent
syntax: number
default: 3
Sets the number of spaces each level will be indented, when formatting the ToC.
=head2 levelToToc
syntax:
default: '.*'
Determines which group levels to use for generating the ToC. For example, to create a ToC for levels 1-2 only, specify:
'levelToToc => '[1-2]'
This option is evaluated during both ToC generation and ToC formatting. This enables you to generate a ToC of all levels, but - after generating - retrieve only specified levels:
$toc->setOptions({'levelToToc' => '.*'});
$tocGenerator->generateToc($toc, ...);
# Get ToC of all levels
$fullToc = $toc->getToc();
# Get ToC of level 1 only
$toc->setOptions({'levelToToc' => '1'});
$level1Toc = $toc->getToc();
=head2 numberingStyle
syntax: [decimal|lower-alpha|upper-alpha|lower-roman|upper-roman]}
default: decimal
Determines which numbering style to use for a token group when L is set to True (1). When specified as a main ToC option, the setting will be the default for all groups. When specified within a tokengroup, this setting will override any default for that particular tokengroup, e.g.:
$toc->setOptions({
'doNumberToken' => 1,
'tokenToToc' => [{
'level' => 1,
'tokenBegin' => '',
'numberingStyle' => 'lower-alpha'
}]
});
If C style is specified, be sure to have the Roman module installed, available from L.
=head2 templateAnchorName
syntax:
default: '$groupId."-".$node'
Anchor name to use when L is set to True (1). The anchor name is passed to both L and L. The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
If C is a function reference to a function returning the anchor, like in:
$toc->setOptions({'templateAnchorName' => \&assembleAnchorName});
the function will be called with the following arguments:
$anchorName = assembleAnchorName($file, $groupId, $level, $node);
=head2 templateAnchorHrefBegin
syntax:
default: '""' or
'""',
depending on 'doLinkToFile' being 0 or 1 respectively.
Anchor reference begin token to use when L is set to True (1). The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
$anchorName
If C is a function reference to a function returning the anchor, like in:
$toc->setOptions({'templateAnchorHrefBegin' => \&assembleAnchorHrefBegin});
the function will be called with the following arguments:
$anchorHrefBegin = &assembleAnchorHrefBegin(
$file, $groupId, $level, $node, $anchorName
);
See also: L, L.
=head2 templateAnchorHrefEnd
syntax:
default: '" "'
Anchor reference end token to use when L is set to True (1). The template may be specified as either an expression or a function reference. If L is a function reference to a function returning the anchor end, like in:
$toc->setOptions({'templateAnchorHrefEnd' => \&assembleAnchorHrefEnd});
the function will be called without arguments:
$anchorHrefEnd = &assembleAnchorHrefEnd;
See also: L.
=head2 templateAnchorNameBegin
syntax:
default: '""'
Anchor name begin token to use when L is set to True (1). The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
$anchorName
If C is a function reference to a function returning the anchor name, like in:
$toc->setOptions({'templateAnchorNameBegin' => \&assembleAnchorNameBegin});
the function will be called with the following arguments:
$anchorNameBegin = assembleAnchorNameBegin(
$file, $groupId, $level, $node, $anchorName
);
See also: L, L.
=head2 templateAnchorNameEnd
syntax:
default: '" "'
Anchor name end token to use when L is set to True (1). The template may be specified as either an expression or a function reference. If L is a function reference to a function returning the anchor end, like in:
$toc->setOptions({'templateAnchorNameEnd' => \&assembleAnchorNameEnd});
the function will be called without arguments:
$anchorNameEnd = &assembleAnchorNameEnd;
See also: L.
=head2 templateLevel
syntax:
default: '"- $text\n"'
Expression to use when formatting a ToC node. The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$level
$groupId
$node
$sequenceNr
$text
If C
is a function reference to a function returning the ToC node, like in:
$toc->setOptions({'templateLevel' => \&AssembleTocNode});
the function will be called with the following arguments:
$tocNode = &AssembleTocNode(
$level, $groupId, $node, $sequenceNr, $text
);
=head2 templateLevelBegin
syntax:
default: '"\n"'
Expression to use when formatting begin of ToC level. See L for list of available variables to use within the expression. For example, to give each ToC level a class name to use with Cascading Style Sheets (CSS), use the expression:
'"\n"'
which will result in each ToC group being given a class name:
- Header
For an example, see L.
=head2 templateLevelEnd
syntax:
default: '"\n"'
Expression to use when formatting end of ToC level. See L for a list of available variables to use within the expression. The default expression is:
'"
\n"'
For an example, see L.
=head2 templateTokenNumber
syntax:
default: '"$node "'
Token number to use when L equals True (1). The template may be specified as either an expression or a function reference. The expression has access to the following variables:
$file
$groupId
$groupLevel
$level
$node
$toc
If C is a function reference to a function returning the token number, like in:
$toc->setOptions({'templateTokenNumber' => \&assembleTokenNumber});
the function will be called with the following arguments:
$number = &assembleTokenNumber(
$node, $groupId, $file, $groupLevel, $level, $toc
);
=head2 tokenBegin
syntax:
default: ''
token: <[/]tag{ attribute=[-|@]}> |
|
|
This scalar defines the token that will trigger text to be put into the ToC. Any start tag, end tag, comment, declaration or text string can be specified. Examples of valid 'tokenBegin' tokens are:
''
''
''
''
'ToC entry'
When specifying a start tag, attributes to be included may be specified as well. Note that the attribute value is used as a regular expression. For example, to specify the C<> tag as tokenBegin:
''
It is also possible to specify attributes to exclude, by prefixing the value with an L, default a minus sign (-). For example, to specify the C<> tag as tokenBegin, excluding all C<> tags:
''
Also, you can specify here an attribute value which has to be used as ToC text, by prefixing the value with an L, default an at sign (@). For example, to use the class value as ToC text:
''
See L for an elaborated example using the C to generate a ToC of image C attribute values.
See also: L, L.
=head2 tokenEnd
syntax: $scalar
default: empty string ('') or end tag counterpart of 'tokenBegin' if
'tokenBegin' is a start tag
The 'tokenEnd' definition applies to the same rules as L.
See also: L, L.
=head2 tokenToToc
syntax: [{array of hashrefs}]
default: [{
'level' => 1,
'tokenBegin' => ''
}, {
'level' => 2,
'tokenBegin' => ''
}, {
'level' => 3,
'tokenBegin' => ''
}, {
'level' => 4,
'tokenBegin' => ''
}, {
'level' => 5,
'tokenBegin' => ''
}, {
'level' => 6,
'tokenBegin' => ''
}]
This hash define the tokens that must act as ToC entries. Each tokengroup may contain a L, L, L, L and L identifier.
=head2 tokenUpdateBeginAnchorName
syntax:
default: '';
This token marks the begin of an anchor name, inserted by C. This option is used by C.
=head2 tokenUpdateEndAnchorName
syntax:
default: '';
This option is used by C, to mark the end of an inserted anchor name.
=head2 tokenUpdateBeginNumber
syntax:
default: '';
This option is used by C, to mark the begin of an inserted number.
=head2 tokenUpdateEndNumber
syntax:
default: '';
This option is used by C, to mark the end of an inserted number.
=head2 tokenUpdateBeginToc
syntax:
default: '';
This option is used by C, to mark the begin of an inserted ToC.
=head2 tokenUpdateEndToc
syntax:
default: '';
This option is used by C, to mark the end of an inserted ToC.
=head1 Known issues
=head2 Cygwin
In order for the test files to run on Cygwin without errors, the 'UNIX' default text file type has to be selected during the Cygwin setup.
When extracting the tar.gz file with WinZip the 'TAR file smart CR/LF conversion' has to be turned off via {Options|Configuration...|Miscellaneous} in order for the files 'toc.pod' and './manualTest/manualTest1.htm' to be left in UNIX format.
=head2 Nested anchors
HTML::Toc can only link to existing anchors if these anchors are placed outside of the ToC tokens. Otherwise a warning will be given. For example, generating a L ToC of Ch1E> tokens of the following text:
',
}, {
'groupId' => 'appendix',
'tokenBegin' => '',
'level' => 2
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
the output will be:
Chapter
Paragraph
Subparagraph
Chapter
Appendix Chapter
Appendix Paragraph
=head3 Specify an additional 'Part' group
Suppose you want to generate a ToC of a document which is divided in multiple parts like this file underneath:
First Part
Chapter
Paragraph
Second Part
Chapter
Paragraph
With the code underneath:
use HTML::Toc;
use HTML::TocInsertor;
my $toc = HTML::Toc->new();
my $tocInsertor = HTML::TocInsertor->new();
$toc->setOptions({
'doNumberToken' => 1,
'tokenToToc' => [{
'tokenBegin' => ''
}, {
'tokenBegin' => '',
'level' => 2,
}, {
'groupId' => 'part',
'tokenBegin' => '',
'level' => 1,
'numberingStyle' => 'upper-alpha'
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
the output will be:
A First Part
1 Chapter
1.1 Paragraph
B Second Part
2 Chapter
2.1 Paragraph
=head2 Number ToC entries
By default, the generated ToC will list its entries unnumbered. If you want to number the ToC entries, two options are available. Either you can specify a numbered list by modifying L and L. Or when the ToC isn't a simple numbered list, you can use the numbers generated by HTML::TocGenerator.
=head3 Specify numbered list
By modifying L and L you can specify a numbered ToC:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({
'templateLevelBegin' => '"\n"',
'templateLevelEnd' => '"
\n"',
});
$tocGenerator->generateFromFile($toc, 'index.htm');
print $toc->format();
For instance with the original file containing:
Chapter
Paragraph
The formatted ToC now will contain C instead of C tags:
See also: L.
=head3 Use generated numbers
Instead of using the HTML ordered list (OL), it's also possible to use the generated numbers to number to ToC nodes. This can be done by modifying L:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({
'templateLevel' => '"- $node $text\n"',
});
$tocGenerator->generateFromFile($toc, 'index.htm');
print $toc->format();
For instance with the original file containing:
Chapter
Paragraph
The formatted ToC now will have the node numbers hard-coded:
See also: L.
=head2 Using CSS for ToC formatting
Suppose you want to display a ToC with upper-alpha numbered appendix headings. To accomplish this, you can specify a CSS style within the source document:
Appendix
Appendix Paragraph
Appendix
Appendix Paragraph
Here's the code:
my $toc = new HTML::Toc;
my $tocInsertor = new HTML::TocInsertor;
$toc->setOptions({
'templateLevelBegin' => '"\n"',
'templateLevelEnd' => '"
\n"',
'doNumberToken' => 1,
'tokenToToc' => [{
'groupId' => 'appendix',
'tokenBegin' => '',
'numberingStyle' => 'upper-alpha'
}, {
'groupId' => 'appendix',
'tokenBegin' => '',
'level' => 2,
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
Which whill result in the following output:
A Appendix
A.1 Appendix Paragraph
B Appendix
B.1 Appendix Paragraph
=head2 Creating site map
Suppose you want to generate a table of contents of the EtitleE tags of the files in the following directory structure:
path file
. index.htm, Main
|- SubDir1 index.htm, Sub1
| |- SubSubDir1 index.htm, SubSub1
|
|- SubDir2 index.htm, Sub2
| |- SubSubDir1 index.htm, SubSub1
| |- SubSubDir2 index.htm, SubSub2
|
|- SubDir3 index.htm, Sub3
By specifying 'fileSpec' which determine how many slashes (/) each file may contain for a specific level:
use HTML::Toc;
use HTML::TocGenerator;
use File::Find;
my $toc = HTML::Toc->new;
my $tocGenerator = HTML::TocGenerator->new;
my @fileList;
sub wanted {
# Add file to 'fileList' if extension matches '.htm'
push (@fileList, $File::Find::name) if (m/\.htm$/);
}
$toc->setOptions({
'doLinkToFile' => 1,
'templateAnchorName' => '""',
'templateAnchorHref' => '""',
'doLinkTocToToken' => 1,
'tokenToToc' => [{
'groupId' => 'dir',
'level' => 1,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+$'
}, {
'groupId' => 'dir',
'level' => 2,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+?/[^/]+$'
}, {
'groupId' => 'dir',
'level' => 3,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+?/[^/]+?/[^/]+$'
}]
});
# Traverse directory structure
find({wanted => \&wanted, no_chdir => 1}, '.');
# Generate ToC of case-insensitively sorted file list
$tocGenerator->extendFromFile(
$toc, [sort {uc($a) cmp uc($b)} @fileList]
);
print $toc->format();
the following ToC will be generated:
=head1 Methods
=head2 HTML::Toc::clear()
syntax: $toc->clear()
returns: --
Clear the ToC.
=head2 HTML::Toc::format()
syntax: $scalar = $toc->format()
returns: Formatted ToC.
Format tokenized ToC.
=head2 HTML::TocGenerator::extend()
syntax: $tocGenerator->extend($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to extend
- $string: string to retrieve ToC from
- $options: hash reference containing generator options.
Extend ToC from specified string. For generator options, see L
=head2 HTML::TocGenerator::extendFromFile()
syntax: $tocGenerator->extendFromFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to extend
- $filename: (reference to array of) file(s) to extend ToC from
- $options: hash reference containing generator options.
Extend ToC from specified file. For generator options, see L. For an example, see L.
=head2 HTML::TocGenerator::generate()
syntax: $tocGenerator->generate($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to generate
- $string: string to retrieve ToC from
- $options: hash reference containing generator options.
Generate ToC from specified string. Before generating, the ToC will be cleared. For extending an existing ToC, use the L method. For generator options, see L.
=head2 HTML::TocGenerator::generateFromFile()
syntax: $tocGenerator->generateFromFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to
generate
- $filename: (reference to array of) file(s) to generate ToC from
- $options: hash reference containing generator options.
Generate ToC from specified file. Before generating, the ToC will be cleared. For extending an extisting ToC, use the L method. For generator options, see L.
=head2 HTML::TocInsertor::insert()
syntax: $tocInsertor->insert($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to insert ToC in
- $options: hash reference containing insertor options.
Insert ToC into specified string. For insertor options, see L.
=head2 HTML::TocInsertor::insertIntoFile()
syntax: $tocInsertor->insertIntoFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to insert ToC in
- $options: hash reference containing insertor options.
Insert ToC into specified file. For insertor options, see L.
=head2 HTML::TocUpdator::insert()
syntax: $tocUpdator->insert($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to insert ToC in
- $options: hash reference containing updator options.
Insert ToC into specified string. Differs from L in that inserted text will be surrounded with update tokens in order for C to be able to update this text the next time an update is issued. For updator options, see L.
=head2 HTML::TocUpdator::insertIntoFile()
syntax: $tocUpdator->insertIntoFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to insert ToC in
- $options: hash reference containing updator options.
Insert ToC into specified file. Differs from L in that inserted text will be surrounded with update tokens in order for C to be able to update this text the next time an update is issued. For updator options, see L.
=head2 HTML::TocUpdator::update()
syntax: $tocUpdator->update($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to update ToC in
- $options: hash reference containing updator options.
Update ToC within specified string. For updator options, see L.
=head2 HTML::TocUpdator::updateFile()
syntax: $tocUpdator->updateFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to update ToC in
- $options: hash reference containing updator options.
Update ToC of specified file. For updator options, see L.
=head1 Parser Options
When generating a ToC, additional options may be specified which influence the way the ToCs are generated using either C, C or C. The options must be specified as a hash reference. For example:
$tocGenerator->generateFromFile($toc, $filename, {doUseGroupsGlobal => 1});
Available options are:
=over 4
=item L
=item L
=item L
=item L
=back
=head2 doGenerateToc
syntax: [0|1]
default: 1
applicable to: TocInsertor, TocUpdator
True (1) if ToC must be generated. False (0) if ToC must be inserted only.
=head2 doUseGroupsGlobal
syntax: [0|1]
default: 0
applicable to: TocGenerator, TocInsertor, TocUpdator
True (1) if group levels must be used globally accross ToCs. False (0) if not. This option only makes sense when an array of ToCs is specified. For example, suppose you want to generate two ToCs, one ToC for '' tokens and one ToC for '' tokens, of the file 'index.htm':
Chapter
Paragraph
Using the default setting of 'doUseGroupsGlobal' => 0:
use HTML::Toc;
use HTML::TocGenerator;
my $toc1 = HTML::Toc->new();
my $toc2 = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc1->setOptions({
'header' => '',
'footer' => '',
'tokenToToc' => [{'tokenBegin' => ''}]
});
$toc2->setOptions({
'header' => '',
'footer' => '',
'tokenToToc' => [{'tokenBegin' => ''}]
});
$tocGenerator->generateFromFile([$toc1, $toc2], 'index.htm');
print $toc1->format() . "\n\n" . $toc2->format();
the output will be:
Each ToC will use its own numbering scheme. Now if 'C' is specified:
$tocGenerator->generateFromFile(
[$toc1, $toc2], 'index.htm', {'doUseGroupsGlobal' => 1}
);
the output will be:
using a global numbering scheme for all ToCs.
=head2 output
syntax: reference to scalar
default: none
applicable to: TocInsertor, TocUpdator
Reference to scalar where the output must be stored in.
=head2 outputFile
syntax: scalar
default: none
applicable to: TocInsertor, TocUpdator
Filename to write output to. If no filename is specified, output will be written to standard output.
=head1 HTML::Toc Options
The C options can be grouped in the following categories:
=over 4
=item L
=item L
=item L
=item L
=back
The ToC options must be specified using the 'setOptions' method. For example:
my $toc = new HTML::Toc;
$toc->setOptions({
'doNumberToken' => 1,
'footer' => ''
'tokenToToc' => [{
'level' => 1,
'tokenBegin' => '',
'numberingStyle' => 'lower-alpha'
}]
});
=head2 Generate options
=over 4
=item Token groups
=over 4
=item L
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=item L
=item L
=back
=item Numbering tokens
=over 4
=item L
=item L
=item L
=back
=item Miscellaneous
=over 4
=item L
=item L
=item L
=item L
=back
=item Linking ToC to tokens
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=back
=head2 Insert options
=over 4
=item L
=back
=head2 Update options
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=back
=head2 Format options
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=head1 HTML::Toc Options Reference
=head2 attributeToExcludeToken
syntax: $scalar
default: '-'
Token which marks an attribute value in a L or L token as an attribute value a token should not have to be marked as a ToC token. See also: L.
=head2 attributeToTocToken
syntax: $scalar
default: '@'
Token which marks an attribute in a L token as an attribute which must be used as ToC text. See also: L.
=head2 doLinkToToken
syntax: [0|1]
default: 1
True (1) if ToC must be linked to tokens, False (0) if not. Note that 'HTML::TocInsertor' must be used to do the actual insertion of the anchor name within the source data.
=head2 doLinkToFile
syntax: [0|1]
default: 0
True (1) if ToC must be linked to file, False (0) if not. In effect only when L equals True (1) and L isn't specified.
=head2 doLinkToId
syntax: [0|1]
default: 0
True (1) if ToC must be linked to tokens by using token ids. False (0) if ToC must be linked to tokens by using anchor names.
=head2 doNestGroup
syntax: [0|1]
default: 0
True (1) if groups must be nested in the formatted ToC, False (0) if not. In effect only when multiple groups are specified within the L setting. For an example, see L.
=head2 doNumberToken
syntax: [0|1]
default: 0
True (1) if tokens which are used for the ToC generation must be numbered. This option may be specified both as a global ToC option or within a L group. When specified within a C option, the C applies to that group only. For an example, see L.
=head2 doSingleStepLevel
syntax: [0|1]
default: 1
True (1) if levels of a formatted ToC must advance one level at a time. For example, when generating a ToC of a file with a missing '':
Chapter
Paragraph
By default, an empty indentation level will be inserted in the ToC:
After specifying:
$toc->setOptions({'doSingleStepLevel' => 0});
the ToC will not have an indentation level inserted for level 2:
=head2 fileSpec
syntax:
default: undef
Specifies which files should match the current level. Valid only if L equals 1. For an example, see L.
=head2 footer
syntax: $scalar
default: "\n\n"
String to output at end of ToC.
=head2 groupId
syntax: $scalar
default: 'h'
Sets the group id attribute of a tokenGroup. With this attribute it's possible to divide the ToC into multiple groups. Each group has its own numbering scheme. For example, to generate a ToC of both normal headings and 'appendix' headings, specify the following ToC settings:
$toc->setOptions({
'tokenToToc' => [{
'tokenBegin' => ''
}, {
'groupId' => 'appendix',
'tokenBegin' => ''
}]
});
=head2 groupToToc
syntax:
default: '.*'
Determines which groups to use for generating the ToC. For example, to create a ToC for groups [a-b] only, specify:
'groupToToc => '[a-b]'
This option is evaluated during both ToC generation and ToC formatting. This enables you to generate a ToC of all groups, but - after generating - format only specified groups:
$toc->setOptions({'groupToToc' => '.*'});
$tocGenerator->generateToc($toc, ...);
# Get ToC of all groups
$fullToc = $toc->format();
# Get ToC of 'appendix' group only
$toc->setOptions({'groupToToc' => 'appendix'});
$appendixToc = $toc->format();
=head2 header
syntax: $scalar
default: "\n\n"
String to output at begin of ToC.
=head2 insertionPoint
syntax: []
default: 'after '
token: <[/]tag{ attribute=[-|@]}> |
|
|
Determines the point within the source, where the ToC should be inserted. When specifying a start tag as the insertion point token, attributes to be included may be specified as well. Note that the attribute value must be specified as a regular expression. For example, to specify the C<> tag as insertion point:
''
Examples of valid 'insertionPoint' tokens are:
''
'
'
''
''
'ToC will be placed here'
It is also possible to specify attributes to exclude, by prefixing the value with an L, default a minus sign (-). For example, to specify the C<> tag as insertion point, excluding all C<> tags:
''
See also L.
=head2 level
syntax: number
default: 1
Number which identifies at which level the tokengroup should be incorporated into the ToC. See also: L.
=head2 levelIndent
syntax: number
default: 3
Sets the number of spaces each level will be indented, when formatting the ToC.
=head2 levelToToc
syntax:
default: '.*'
Determines which group levels to use for generating the ToC. For example, to create a ToC for levels 1-2 only, specify:
'levelToToc => '[1-2]'
This option is evaluated during both ToC generation and ToC formatting. This enables you to generate a ToC of all levels, but - after generating - retrieve only specified levels:
$toc->setOptions({'levelToToc' => '.*'});
$tocGenerator->generateToc($toc, ...);
# Get ToC of all levels
$fullToc = $toc->getToc();
# Get ToC of level 1 only
$toc->setOptions({'levelToToc' => '1'});
$level1Toc = $toc->getToc();
=head2 numberingStyle
syntax: [decimal|lower-alpha|upper-alpha|lower-roman|upper-roman]}
default: decimal
Determines which numbering style to use for a token group when L is set to True (1). When specified as a main ToC option, the setting will be the default for all groups. When specified within a tokengroup, this setting will override any default for that particular tokengroup, e.g.:
$toc->setOptions({
'doNumberToken' => 1,
'tokenToToc' => [{
'level' => 1,
'tokenBegin' => '',
'numberingStyle' => 'lower-alpha'
}]
});
If C style is specified, be sure to have the Roman module installed, available from L.
=head2 templateAnchorName
syntax:
default: '$groupId."-".$node'
Anchor name to use when L is set to True (1). The anchor name is passed to both L and L. The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
If C is a function reference to a function returning the anchor, like in:
$toc->setOptions({'templateAnchorName' => \&assembleAnchorName});
the function will be called with the following arguments:
$anchorName = assembleAnchorName($file, $groupId, $level, $node);
=head2 templateAnchorHrefBegin
syntax:
default: '""' or
'""',
depending on 'doLinkToFile' being 0 or 1 respectively.
Anchor reference begin token to use when L is set to True (1). The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
$anchorName
If C is a function reference to a function returning the anchor, like in:
$toc->setOptions({'templateAnchorHrefBegin' => \&assembleAnchorHrefBegin});
the function will be called with the following arguments:
$anchorHrefBegin = &assembleAnchorHrefBegin(
$file, $groupId, $level, $node, $anchorName
);
See also: L, L.
=head2 templateAnchorHrefEnd
syntax:
default: '" "'
Anchor reference end token to use when L is set to True (1). The template may be specified as either an expression or a function reference. If L is a function reference to a function returning the anchor end, like in:
$toc->setOptions({'templateAnchorHrefEnd' => \&assembleAnchorHrefEnd});
the function will be called without arguments:
$anchorHrefEnd = &assembleAnchorHrefEnd;
See also: L.
=head2 templateAnchorNameBegin
syntax:
default: '""'
Anchor name begin token to use when L is set to True (1). The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
$anchorName
If C is a function reference to a function returning the anchor name, like in:
$toc->setOptions({'templateAnchorNameBegin' => \&assembleAnchorNameBegin});
the function will be called with the following arguments:
$anchorNameBegin = assembleAnchorNameBegin(
$file, $groupId, $level, $node, $anchorName
);
See also: L, L.
=head2 templateAnchorNameEnd
syntax:
default: '" "'
Anchor name end token to use when L is set to True (1). The template may be specified as either an expression or a function reference. If L is a function reference to a function returning the anchor end, like in:
$toc->setOptions({'templateAnchorNameEnd' => \&assembleAnchorNameEnd});
the function will be called without arguments:
$anchorNameEnd = &assembleAnchorNameEnd;
See also: L.
=head2 templateLevel
syntax:
default: '"- $text\n"'
Expression to use when formatting a ToC node. The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$level
$groupId
$node
$sequenceNr
$text
If C
is a function reference to a function returning the ToC node, like in:
$toc->setOptions({'templateLevel' => \&AssembleTocNode});
the function will be called with the following arguments:
$tocNode = &AssembleTocNode(
$level, $groupId, $node, $sequenceNr, $text
);
=head2 templateLevelBegin
syntax:
default: '"\n"'
Expression to use when formatting begin of ToC level. See L for list of available variables to use within the expression. For example, to give each ToC level a class name to use with Cascading Style Sheets (CSS), use the expression:
'"\n"'
which will result in each ToC group being given a class name:
- Header
For an example, see L.
=head2 templateLevelEnd
syntax:
default: '"\n"'
Expression to use when formatting end of ToC level. See L for a list of available variables to use within the expression. The default expression is:
'"
\n"'
For an example, see L.
=head2 templateTokenNumber
syntax:
default: '"$node "'
Token number to use when L equals True (1). The template may be specified as either an expression or a function reference. The expression has access to the following variables:
$file
$groupId
$groupLevel
$level
$node
$toc
If C is a function reference to a function returning the token number, like in:
$toc->setOptions({'templateTokenNumber' => \&assembleTokenNumber});
the function will be called with the following arguments:
$number = &assembleTokenNumber(
$node, $groupId, $file, $groupLevel, $level, $toc
);
=head2 tokenBegin
syntax:
default: ''
token: <[/]tag{ attribute=[-|@]}> |
|
|
This scalar defines the token that will trigger text to be put into the ToC. Any start tag, end tag, comment, declaration or text string can be specified. Examples of valid 'tokenBegin' tokens are:
''
''
''
''
'ToC entry'
When specifying a start tag, attributes to be included may be specified as well. Note that the attribute value is used as a regular expression. For example, to specify the C<> tag as tokenBegin:
''
It is also possible to specify attributes to exclude, by prefixing the value with an L, default a minus sign (-). For example, to specify the C<> tag as tokenBegin, excluding all C<> tags:
''
Also, you can specify here an attribute value which has to be used as ToC text, by prefixing the value with an L, default an at sign (@). For example, to use the class value as ToC text:
''
See L for an elaborated example using the C to generate a ToC of image C attribute values.
See also: L, L.
=head2 tokenEnd
syntax: $scalar
default: empty string ('') or end tag counterpart of 'tokenBegin' if
'tokenBegin' is a start tag
The 'tokenEnd' definition applies to the same rules as L.
See also: L, L.
=head2 tokenToToc
syntax: [{array of hashrefs}]
default: [{
'level' => 1,
'tokenBegin' => ''
}, {
'level' => 2,
'tokenBegin' => ''
}, {
'level' => 3,
'tokenBegin' => ''
}, {
'level' => 4,
'tokenBegin' => ''
}, {
'level' => 5,
'tokenBegin' => ''
}, {
'level' => 6,
'tokenBegin' => ''
}]
This hash define the tokens that must act as ToC entries. Each tokengroup may contain a L, L, L, L and L identifier.
=head2 tokenUpdateBeginAnchorName
syntax:
default: '';
This token marks the begin of an anchor name, inserted by C. This option is used by C.
=head2 tokenUpdateEndAnchorName
syntax:
default: '';
This option is used by C, to mark the end of an inserted anchor name.
=head2 tokenUpdateBeginNumber
syntax:
default: '';
This option is used by C, to mark the begin of an inserted number.
=head2 tokenUpdateEndNumber
syntax:
default: '';
This option is used by C, to mark the end of an inserted number.
=head2 tokenUpdateBeginToc
syntax:
default: '';
This option is used by C, to mark the begin of an inserted ToC.
=head2 tokenUpdateEndToc
syntax:
default: '';
This option is used by C, to mark the end of an inserted ToC.
=head1 Known issues
=head2 Cygwin
In order for the test files to run on Cygwin without errors, the 'UNIX' default text file type has to be selected during the Cygwin setup.
When extracting the tar.gz file with WinZip the 'TAR file smart CR/LF conversion' has to be turned off via {Options|Configuration...|Miscellaneous} in order for the files 'toc.pod' and './manualTest/manualTest1.htm' to be left in UNIX format.
=head2 Nested anchors
HTML::Toc can only link to existing anchors if these anchors are placed outside of the ToC tokens. Otherwise a warning will be given. For example, generating a L ToC of Ch1E> tokens of the following text:
Chapter
Paragraph
Subparagraph
Chapter
Appendix Chapter
Appendix Paragraph
=head3 Specify an additional 'Part' group Suppose you want to generate a ToC of a document which is divided in multiple parts like this file underneath:First Part
Chapter
Paragraph
Second Part
Chapter
Paragraph
With the code underneath: use HTML::Toc; use HTML::TocInsertor; my $toc = HTML::Toc->new(); my $tocInsertor = HTML::TocInsertor->new(); $toc->setOptions({ 'doNumberToken' => 1, 'tokenToToc' => [{ 'tokenBegin' => ''
}, {
'tokenBegin' => '',
'level' => 2,
}, {
'groupId' => 'part',
'tokenBegin' => '',
'level' => 1,
'numberingStyle' => 'upper-alpha'
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
the output will be:
A First Part
1 Chapter
1.1 Paragraph
B Second Part
2 Chapter
2.1 Paragraph
=head2 Number ToC entries
By default, the generated ToC will list its entries unnumbered. If you want to number the ToC entries, two options are available. Either you can specify a numbered list by modifying L and L. Or when the ToC isn't a simple numbered list, you can use the numbers generated by HTML::TocGenerator.
=head3 Specify numbered list
By modifying L and L you can specify a numbered ToC:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({
'templateLevelBegin' => '"\n"',
'templateLevelEnd' => '"
\n"',
});
$tocGenerator->generateFromFile($toc, 'index.htm');
print $toc->format();
For instance with the original file containing:
Chapter
Paragraph
The formatted ToC now will contain C instead of C tags:
See also: L.
=head3 Use generated numbers
Instead of using the HTML ordered list (OL), it's also possible to use the generated numbers to number to ToC nodes. This can be done by modifying L:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({
'templateLevel' => '"- $node $text\n"',
});
$tocGenerator->generateFromFile($toc, 'index.htm');
print $toc->format();
For instance with the original file containing:
Chapter
Paragraph
The formatted ToC now will have the node numbers hard-coded:
See also: L.
=head2 Using CSS for ToC formatting
Suppose you want to display a ToC with upper-alpha numbered appendix headings. To accomplish this, you can specify a CSS style within the source document:
Appendix
Appendix Paragraph
Appendix
Appendix Paragraph
Here's the code:
my $toc = new HTML::Toc;
my $tocInsertor = new HTML::TocInsertor;
$toc->setOptions({
'templateLevelBegin' => '"\n"',
'templateLevelEnd' => '"
\n"',
'doNumberToken' => 1,
'tokenToToc' => [{
'groupId' => 'appendix',
'tokenBegin' => '',
'numberingStyle' => 'upper-alpha'
}, {
'groupId' => 'appendix',
'tokenBegin' => '',
'level' => 2,
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
Which whill result in the following output:
A Appendix
A.1 Appendix Paragraph
B Appendix
B.1 Appendix Paragraph
=head2 Creating site map
Suppose you want to generate a table of contents of the EtitleE tags of the files in the following directory structure:
path file
. index.htm, Main
|- SubDir1 index.htm, Sub1
| |- SubSubDir1 index.htm, SubSub1
|
|- SubDir2 index.htm, Sub2
| |- SubSubDir1 index.htm, SubSub1
| |- SubSubDir2 index.htm, SubSub2
|
|- SubDir3 index.htm, Sub3
By specifying 'fileSpec' which determine how many slashes (/) each file may contain for a specific level:
use HTML::Toc;
use HTML::TocGenerator;
use File::Find;
my $toc = HTML::Toc->new;
my $tocGenerator = HTML::TocGenerator->new;
my @fileList;
sub wanted {
# Add file to 'fileList' if extension matches '.htm'
push (@fileList, $File::Find::name) if (m/\.htm$/);
}
$toc->setOptions({
'doLinkToFile' => 1,
'templateAnchorName' => '""',
'templateAnchorHref' => '""',
'doLinkTocToToken' => 1,
'tokenToToc' => [{
'groupId' => 'dir',
'level' => 1,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+$'
}, {
'groupId' => 'dir',
'level' => 2,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+?/[^/]+$'
}, {
'groupId' => 'dir',
'level' => 3,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+?/[^/]+?/[^/]+$'
}]
});
# Traverse directory structure
find({wanted => \&wanted, no_chdir => 1}, '.');
# Generate ToC of case-insensitively sorted file list
$tocGenerator->extendFromFile(
$toc, [sort {uc($a) cmp uc($b)} @fileList]
);
print $toc->format();
the following ToC will be generated:
=head1 Methods
=head2 HTML::Toc::clear()
syntax: $toc->clear()
returns: --
Clear the ToC.
=head2 HTML::Toc::format()
syntax: $scalar = $toc->format()
returns: Formatted ToC.
Format tokenized ToC.
=head2 HTML::TocGenerator::extend()
syntax: $tocGenerator->extend($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to extend
- $string: string to retrieve ToC from
- $options: hash reference containing generator options.
Extend ToC from specified string. For generator options, see L
=head2 HTML::TocGenerator::extendFromFile()
syntax: $tocGenerator->extendFromFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to extend
- $filename: (reference to array of) file(s) to extend ToC from
- $options: hash reference containing generator options.
Extend ToC from specified file. For generator options, see L. For an example, see L.
=head2 HTML::TocGenerator::generate()
syntax: $tocGenerator->generate($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to generate
- $string: string to retrieve ToC from
- $options: hash reference containing generator options.
Generate ToC from specified string. Before generating, the ToC will be cleared. For extending an existing ToC, use the L method. For generator options, see L.
=head2 HTML::TocGenerator::generateFromFile()
syntax: $tocGenerator->generateFromFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to
generate
- $filename: (reference to array of) file(s) to generate ToC from
- $options: hash reference containing generator options.
Generate ToC from specified file. Before generating, the ToC will be cleared. For extending an extisting ToC, use the L method. For generator options, see L.
=head2 HTML::TocInsertor::insert()
syntax: $tocInsertor->insert($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to insert ToC in
- $options: hash reference containing insertor options.
Insert ToC into specified string. For insertor options, see L.
=head2 HTML::TocInsertor::insertIntoFile()
syntax: $tocInsertor->insertIntoFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to insert ToC in
- $options: hash reference containing insertor options.
Insert ToC into specified file. For insertor options, see L.
=head2 HTML::TocUpdator::insert()
syntax: $tocUpdator->insert($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to insert ToC in
- $options: hash reference containing updator options.
Insert ToC into specified string. Differs from L in that inserted text will be surrounded with update tokens in order for C to be able to update this text the next time an update is issued. For updator options, see L.
=head2 HTML::TocUpdator::insertIntoFile()
syntax: $tocUpdator->insertIntoFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to insert ToC in
- $options: hash reference containing updator options.
Insert ToC into specified file. Differs from L in that inserted text will be surrounded with update tokens in order for C to be able to update this text the next time an update is issued. For updator options, see L.
=head2 HTML::TocUpdator::update()
syntax: $tocUpdator->update($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to update ToC in
- $options: hash reference containing updator options.
Update ToC within specified string. For updator options, see L.
=head2 HTML::TocUpdator::updateFile()
syntax: $tocUpdator->updateFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to update ToC in
- $options: hash reference containing updator options.
Update ToC of specified file. For updator options, see L.
=head1 Parser Options
When generating a ToC, additional options may be specified which influence the way the ToCs are generated using either C, C or C. The options must be specified as a hash reference. For example:
$tocGenerator->generateFromFile($toc, $filename, {doUseGroupsGlobal => 1});
Available options are:
=over 4
=item L
=item L
=item L
=item L
=back
=head2 doGenerateToc
syntax: [0|1]
default: 1
applicable to: TocInsertor, TocUpdator
True (1) if ToC must be generated. False (0) if ToC must be inserted only.
=head2 doUseGroupsGlobal
syntax: [0|1]
default: 0
applicable to: TocGenerator, TocInsertor, TocUpdator
True (1) if group levels must be used globally accross ToCs. False (0) if not. This option only makes sense when an array of ToCs is specified. For example, suppose you want to generate two ToCs, one ToC for '' tokens and one ToC for '' tokens, of the file 'index.htm':
Chapter
Paragraph
Using the default setting of 'doUseGroupsGlobal' => 0:
use HTML::Toc;
use HTML::TocGenerator;
my $toc1 = HTML::Toc->new();
my $toc2 = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc1->setOptions({
'header' => '',
'footer' => '',
'tokenToToc' => [{'tokenBegin' => ''}]
});
$toc2->setOptions({
'header' => '',
'footer' => '',
'tokenToToc' => [{'tokenBegin' => ''}]
});
$tocGenerator->generateFromFile([$toc1, $toc2], 'index.htm');
print $toc1->format() . "\n\n" . $toc2->format();
the output will be:
Each ToC will use its own numbering scheme. Now if 'C' is specified:
$tocGenerator->generateFromFile(
[$toc1, $toc2], 'index.htm', {'doUseGroupsGlobal' => 1}
);
the output will be:
using a global numbering scheme for all ToCs.
=head2 output
syntax: reference to scalar
default: none
applicable to: TocInsertor, TocUpdator
Reference to scalar where the output must be stored in.
=head2 outputFile
syntax: scalar
default: none
applicable to: TocInsertor, TocUpdator
Filename to write output to. If no filename is specified, output will be written to standard output.
=head1 HTML::Toc Options
The C options can be grouped in the following categories:
=over 4
=item L
=item L
=item L
=item L
=back
The ToC options must be specified using the 'setOptions' method. For example:
my $toc = new HTML::Toc;
$toc->setOptions({
'doNumberToken' => 1,
'footer' => ''
'tokenToToc' => [{
'level' => 1,
'tokenBegin' => '',
'numberingStyle' => 'lower-alpha'
}]
});
=head2 Generate options
=over 4
=item Token groups
=over 4
=item L
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=item L
=item L
=back
=item Numbering tokens
=over 4
=item L
=item L
=item L
=back
=item Miscellaneous
=over 4
=item L
=item L
=item L
=item L
=back
=item Linking ToC to tokens
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=back
=head2 Insert options
=over 4
=item L
=back
=head2 Update options
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=back
=head2 Format options
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=head1 HTML::Toc Options Reference
=head2 attributeToExcludeToken
syntax: $scalar
default: '-'
Token which marks an attribute value in a L or L token as an attribute value a token should not have to be marked as a ToC token. See also: L.
=head2 attributeToTocToken
syntax: $scalar
default: '@'
Token which marks an attribute in a L token as an attribute which must be used as ToC text. See also: L.
=head2 doLinkToToken
syntax: [0|1]
default: 1
True (1) if ToC must be linked to tokens, False (0) if not. Note that 'HTML::TocInsertor' must be used to do the actual insertion of the anchor name within the source data.
=head2 doLinkToFile
syntax: [0|1]
default: 0
True (1) if ToC must be linked to file, False (0) if not. In effect only when L equals True (1) and L isn't specified.
=head2 doLinkToId
syntax: [0|1]
default: 0
True (1) if ToC must be linked to tokens by using token ids. False (0) if ToC must be linked to tokens by using anchor names.
=head2 doNestGroup
syntax: [0|1]
default: 0
True (1) if groups must be nested in the formatted ToC, False (0) if not. In effect only when multiple groups are specified within the L setting. For an example, see L.
=head2 doNumberToken
syntax: [0|1]
default: 0
True (1) if tokens which are used for the ToC generation must be numbered. This option may be specified both as a global ToC option or within a L group. When specified within a C option, the C applies to that group only. For an example, see L.
=head2 doSingleStepLevel
syntax: [0|1]
default: 1
True (1) if levels of a formatted ToC must advance one level at a time. For example, when generating a ToC of a file with a missing '':
Chapter
Paragraph
By default, an empty indentation level will be inserted in the ToC:
After specifying:
$toc->setOptions({'doSingleStepLevel' => 0});
the ToC will not have an indentation level inserted for level 2:
=head2 fileSpec
syntax:
default: undef
Specifies which files should match the current level. Valid only if L equals 1. For an example, see L.
=head2 footer
syntax: $scalar
default: "\n\n"
String to output at end of ToC.
=head2 groupId
syntax: $scalar
default: 'h'
Sets the group id attribute of a tokenGroup. With this attribute it's possible to divide the ToC into multiple groups. Each group has its own numbering scheme. For example, to generate a ToC of both normal headings and 'appendix' headings, specify the following ToC settings:
$toc->setOptions({
'tokenToToc' => [{
'tokenBegin' => ''
}, {
'groupId' => 'appendix',
'tokenBegin' => ''
}]
});
=head2 groupToToc
syntax:
default: '.*'
Determines which groups to use for generating the ToC. For example, to create a ToC for groups [a-b] only, specify:
'groupToToc => '[a-b]'
This option is evaluated during both ToC generation and ToC formatting. This enables you to generate a ToC of all groups, but - after generating - format only specified groups:
$toc->setOptions({'groupToToc' => '.*'});
$tocGenerator->generateToc($toc, ...);
# Get ToC of all groups
$fullToc = $toc->format();
# Get ToC of 'appendix' group only
$toc->setOptions({'groupToToc' => 'appendix'});
$appendixToc = $toc->format();
=head2 header
syntax: $scalar
default: "\n\n"
String to output at begin of ToC.
=head2 insertionPoint
syntax: []
default: 'after '
token: <[/]tag{ attribute=[-|@]}> |
|
|
Determines the point within the source, where the ToC should be inserted. When specifying a start tag as the insertion point token, attributes to be included may be specified as well. Note that the attribute value must be specified as a regular expression. For example, to specify the C<> tag as insertion point:
''
Examples of valid 'insertionPoint' tokens are:
''
'
'
''
''
'ToC will be placed here'
It is also possible to specify attributes to exclude, by prefixing the value with an L, default a minus sign (-). For example, to specify the C<> tag as insertion point, excluding all C<> tags:
''
See also L.
=head2 level
syntax: number
default: 1
Number which identifies at which level the tokengroup should be incorporated into the ToC. See also: L.
=head2 levelIndent
syntax: number
default: 3
Sets the number of spaces each level will be indented, when formatting the ToC.
=head2 levelToToc
syntax:
default: '.*'
Determines which group levels to use for generating the ToC. For example, to create a ToC for levels 1-2 only, specify:
'levelToToc => '[1-2]'
This option is evaluated during both ToC generation and ToC formatting. This enables you to generate a ToC of all levels, but - after generating - retrieve only specified levels:
$toc->setOptions({'levelToToc' => '.*'});
$tocGenerator->generateToc($toc, ...);
# Get ToC of all levels
$fullToc = $toc->getToc();
# Get ToC of level 1 only
$toc->setOptions({'levelToToc' => '1'});
$level1Toc = $toc->getToc();
=head2 numberingStyle
syntax: [decimal|lower-alpha|upper-alpha|lower-roman|upper-roman]}
default: decimal
Determines which numbering style to use for a token group when L is set to True (1). When specified as a main ToC option, the setting will be the default for all groups. When specified within a tokengroup, this setting will override any default for that particular tokengroup, e.g.:
$toc->setOptions({
'doNumberToken' => 1,
'tokenToToc' => [{
'level' => 1,
'tokenBegin' => '',
'numberingStyle' => 'lower-alpha'
}]
});
If C style is specified, be sure to have the Roman module installed, available from L.
=head2 templateAnchorName
syntax:
default: '$groupId."-".$node'
Anchor name to use when L is set to True (1). The anchor name is passed to both L and L. The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
If C is a function reference to a function returning the anchor, like in:
$toc->setOptions({'templateAnchorName' => \&assembleAnchorName});
the function will be called with the following arguments:
$anchorName = assembleAnchorName($file, $groupId, $level, $node);
=head2 templateAnchorHrefBegin
syntax:
default: '""' or
'""',
depending on 'doLinkToFile' being 0 or 1 respectively.
Anchor reference begin token to use when L is set to True (1). The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
$anchorName
If C is a function reference to a function returning the anchor, like in:
$toc->setOptions({'templateAnchorHrefBegin' => \&assembleAnchorHrefBegin});
the function will be called with the following arguments:
$anchorHrefBegin = &assembleAnchorHrefBegin(
$file, $groupId, $level, $node, $anchorName
);
See also: L, L.
=head2 templateAnchorHrefEnd
syntax:
default: '" "'
Anchor reference end token to use when L is set to True (1). The template may be specified as either an expression or a function reference. If L is a function reference to a function returning the anchor end, like in:
$toc->setOptions({'templateAnchorHrefEnd' => \&assembleAnchorHrefEnd});
the function will be called without arguments:
$anchorHrefEnd = &assembleAnchorHrefEnd;
See also: L.
=head2 templateAnchorNameBegin
syntax:
default: '""'
Anchor name begin token to use when L is set to True (1). The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
$anchorName
If C is a function reference to a function returning the anchor name, like in:
$toc->setOptions({'templateAnchorNameBegin' => \&assembleAnchorNameBegin});
the function will be called with the following arguments:
$anchorNameBegin = assembleAnchorNameBegin(
$file, $groupId, $level, $node, $anchorName
);
See also: L, L.
=head2 templateAnchorNameEnd
syntax:
default: '" "'
Anchor name end token to use when L is set to True (1). The template may be specified as either an expression or a function reference. If L is a function reference to a function returning the anchor end, like in:
$toc->setOptions({'templateAnchorNameEnd' => \&assembleAnchorNameEnd});
the function will be called without arguments:
$anchorNameEnd = &assembleAnchorNameEnd;
See also: L.
=head2 templateLevel
syntax:
default: '"- $text\n"'
Expression to use when formatting a ToC node. The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$level
$groupId
$node
$sequenceNr
$text
If C
is a function reference to a function returning the ToC node, like in:
$toc->setOptions({'templateLevel' => \&AssembleTocNode});
the function will be called with the following arguments:
$tocNode = &AssembleTocNode(
$level, $groupId, $node, $sequenceNr, $text
);
=head2 templateLevelBegin
syntax:
default: '"\n"'
Expression to use when formatting begin of ToC level. See L for list of available variables to use within the expression. For example, to give each ToC level a class name to use with Cascading Style Sheets (CSS), use the expression:
'"\n"'
which will result in each ToC group being given a class name:
- Header
For an example, see L.
=head2 templateLevelEnd
syntax:
default: '"\n"'
Expression to use when formatting end of ToC level. See L for a list of available variables to use within the expression. The default expression is:
'"
\n"'
For an example, see L.
=head2 templateTokenNumber
syntax:
default: '"$node "'
Token number to use when L equals True (1). The template may be specified as either an expression or a function reference. The expression has access to the following variables:
$file
$groupId
$groupLevel
$level
$node
$toc
If C is a function reference to a function returning the token number, like in:
$toc->setOptions({'templateTokenNumber' => \&assembleTokenNumber});
the function will be called with the following arguments:
$number = &assembleTokenNumber(
$node, $groupId, $file, $groupLevel, $level, $toc
);
=head2 tokenBegin
syntax:
default: ''
token: <[/]tag{ attribute=[-|@]}> |
|
|
This scalar defines the token that will trigger text to be put into the ToC. Any start tag, end tag, comment, declaration or text string can be specified. Examples of valid 'tokenBegin' tokens are:
''
''
''
''
'ToC entry'
When specifying a start tag, attributes to be included may be specified as well. Note that the attribute value is used as a regular expression. For example, to specify the C<> tag as tokenBegin:
''
It is also possible to specify attributes to exclude, by prefixing the value with an L, default a minus sign (-). For example, to specify the C<> tag as tokenBegin, excluding all C<> tags:
''
Also, you can specify here an attribute value which has to be used as ToC text, by prefixing the value with an L, default an at sign (@). For example, to use the class value as ToC text:
''
See L for an elaborated example using the C to generate a ToC of image C attribute values.
See also: L, L.
=head2 tokenEnd
syntax: $scalar
default: empty string ('') or end tag counterpart of 'tokenBegin' if
'tokenBegin' is a start tag
The 'tokenEnd' definition applies to the same rules as L.
See also: L, L.
=head2 tokenToToc
syntax: [{array of hashrefs}]
default: [{
'level' => 1,
'tokenBegin' => ''
}, {
'level' => 2,
'tokenBegin' => ''
}, {
'level' => 3,
'tokenBegin' => ''
}, {
'level' => 4,
'tokenBegin' => ''
}, {
'level' => 5,
'tokenBegin' => ''
}, {
'level' => 6,
'tokenBegin' => ''
}]
This hash define the tokens that must act as ToC entries. Each tokengroup may contain a L, L, L, L and L identifier.
=head2 tokenUpdateBeginAnchorName
syntax:
default: '';
This token marks the begin of an anchor name, inserted by C. This option is used by C.
=head2 tokenUpdateEndAnchorName
syntax:
default: '';
This option is used by C, to mark the end of an inserted anchor name.
=head2 tokenUpdateBeginNumber
syntax:
default: '';
This option is used by C, to mark the begin of an inserted number.
=head2 tokenUpdateEndNumber
syntax:
default: '';
This option is used by C, to mark the end of an inserted number.
=head2 tokenUpdateBeginToc
syntax:
default: '';
This option is used by C, to mark the begin of an inserted ToC.
=head2 tokenUpdateEndToc
syntax:
default: '';
This option is used by C, to mark the end of an inserted ToC.
=head1 Known issues
=head2 Cygwin
In order for the test files to run on Cygwin without errors, the 'UNIX' default text file type has to be selected during the Cygwin setup.
When extracting the tar.gz file with WinZip the 'TAR file smart CR/LF conversion' has to be turned off via {Options|Configuration...|Miscellaneous} in order for the files 'toc.pod' and './manualTest/manualTest1.htm' to be left in UNIX format.
=head2 Nested anchors
HTML::Toc can only link to existing anchors if these anchors are placed outside of the ToC tokens. Otherwise a warning will be given. For example, generating a L ToC of Ch1E> tokens of the following text:
',
'level' => 1,
'numberingStyle' => 'upper-alpha'
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
the output will be:
A First Part
1 Chapter
1.1 Paragraph
B Second Part
2 Chapter
2.1 Paragraph
=head2 Number ToC entries
By default, the generated ToC will list its entries unnumbered. If you want to number the ToC entries, two options are available. Either you can specify a numbered list by modifying L and L. Or when the ToC isn't a simple numbered list, you can use the numbers generated by HTML::TocGenerator.
=head3 Specify numbered list
By modifying L and L you can specify a numbered ToC:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({
'templateLevelBegin' => '"\n"',
'templateLevelEnd' => '"
\n"',
});
$tocGenerator->generateFromFile($toc, 'index.htm');
print $toc->format();
For instance with the original file containing:
Chapter
Paragraph
The formatted ToC now will contain C instead of C tags:
See also: L.
=head3 Use generated numbers
Instead of using the HTML ordered list (OL), it's also possible to use the generated numbers to number to ToC nodes. This can be done by modifying L:
use HTML::Toc;
use HTML::TocGenerator;
my $toc = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc->setOptions({
'templateLevel' => '"- $node $text\n"',
});
$tocGenerator->generateFromFile($toc, 'index.htm');
print $toc->format();
For instance with the original file containing:
Chapter
Paragraph
The formatted ToC now will have the node numbers hard-coded:
See also: L.
=head2 Using CSS for ToC formatting
Suppose you want to display a ToC with upper-alpha numbered appendix headings. To accomplish this, you can specify a CSS style within the source document:
Appendix
Appendix Paragraph
Appendix
Appendix Paragraph
Here's the code:
my $toc = new HTML::Toc;
my $tocInsertor = new HTML::TocInsertor;
$toc->setOptions({
'templateLevelBegin' => '"\n"',
'templateLevelEnd' => '"
\n"',
'doNumberToken' => 1,
'tokenToToc' => [{
'groupId' => 'appendix',
'tokenBegin' => '',
'numberingStyle' => 'upper-alpha'
}, {
'groupId' => 'appendix',
'tokenBegin' => '',
'level' => 2,
}]
});
$tocInsertor->insertIntoFile($toc, $filename);
Which whill result in the following output:
A Appendix
A.1 Appendix Paragraph
B Appendix
B.1 Appendix Paragraph
=head2 Creating site map
Suppose you want to generate a table of contents of the EtitleE tags of the files in the following directory structure:
path file
. index.htm, Main
|- SubDir1 index.htm, Sub1
| |- SubSubDir1 index.htm, SubSub1
|
|- SubDir2 index.htm, Sub2
| |- SubSubDir1 index.htm, SubSub1
| |- SubSubDir2 index.htm, SubSub2
|
|- SubDir3 index.htm, Sub3
By specifying 'fileSpec' which determine how many slashes (/) each file may contain for a specific level:
use HTML::Toc;
use HTML::TocGenerator;
use File::Find;
my $toc = HTML::Toc->new;
my $tocGenerator = HTML::TocGenerator->new;
my @fileList;
sub wanted {
# Add file to 'fileList' if extension matches '.htm'
push (@fileList, $File::Find::name) if (m/\.htm$/);
}
$toc->setOptions({
'doLinkToFile' => 1,
'templateAnchorName' => '""',
'templateAnchorHref' => '""',
'doLinkTocToToken' => 1,
'tokenToToc' => [{
'groupId' => 'dir',
'level' => 1,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+$'
}, {
'groupId' => 'dir',
'level' => 2,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+?/[^/]+$'
}, {
'groupId' => 'dir',
'level' => 3,
'tokenBegin' => '',
'tokenEnd' => ' ',
'fileSpec' => '\./[^/]+?/[^/]+?/[^/]+$'
}]
});
# Traverse directory structure
find({wanted => \&wanted, no_chdir => 1}, '.');
# Generate ToC of case-insensitively sorted file list
$tocGenerator->extendFromFile(
$toc, [sort {uc($a) cmp uc($b)} @fileList]
);
print $toc->format();
the following ToC will be generated:
=head1 Methods
=head2 HTML::Toc::clear()
syntax: $toc->clear()
returns: --
Clear the ToC.
=head2 HTML::Toc::format()
syntax: $scalar = $toc->format()
returns: Formatted ToC.
Format tokenized ToC.
=head2 HTML::TocGenerator::extend()
syntax: $tocGenerator->extend($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to extend
- $string: string to retrieve ToC from
- $options: hash reference containing generator options.
Extend ToC from specified string. For generator options, see L
=head2 HTML::TocGenerator::extendFromFile()
syntax: $tocGenerator->extendFromFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to extend
- $filename: (reference to array of) file(s) to extend ToC from
- $options: hash reference containing generator options.
Extend ToC from specified file. For generator options, see L. For an example, see L.
=head2 HTML::TocGenerator::generate()
syntax: $tocGenerator->generate($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to generate
- $string: string to retrieve ToC from
- $options: hash reference containing generator options.
Generate ToC from specified string. Before generating, the ToC will be cleared. For extending an existing ToC, use the L method. For generator options, see L.
=head2 HTML::TocGenerator::generateFromFile()
syntax: $tocGenerator->generateFromFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to
generate
- $filename: (reference to array of) file(s) to generate ToC from
- $options: hash reference containing generator options.
Generate ToC from specified file. Before generating, the ToC will be cleared. For extending an extisting ToC, use the L method. For generator options, see L.
=head2 HTML::TocInsertor::insert()
syntax: $tocInsertor->insert($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to insert ToC in
- $options: hash reference containing insertor options.
Insert ToC into specified string. For insertor options, see L.
=head2 HTML::TocInsertor::insertIntoFile()
syntax: $tocInsertor->insertIntoFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to insert ToC in
- $options: hash reference containing insertor options.
Insert ToC into specified file. For insertor options, see L.
=head2 HTML::TocUpdator::insert()
syntax: $tocUpdator->insert($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to insert ToC in
- $options: hash reference containing updator options.
Insert ToC into specified string. Differs from L in that inserted text will be surrounded with update tokens in order for C to be able to update this text the next time an update is issued. For updator options, see L.
=head2 HTML::TocUpdator::insertIntoFile()
syntax: $tocUpdator->insertIntoFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to insert ToC in
- $options: hash reference containing updator options.
Insert ToC into specified file. Differs from L in that inserted text will be surrounded with update tokens in order for C to be able to update this text the next time an update is issued. For updator options, see L.
=head2 HTML::TocUpdator::update()
syntax: $tocUpdator->update($toc, $string [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $string: string to update ToC in
- $options: hash reference containing updator options.
Update ToC within specified string. For updator options, see L.
=head2 HTML::TocUpdator::updateFile()
syntax: $tocUpdator->updateFile($toc, $filename [, $options])
args: - $toc: (reference to array of) HTML::Toc object(s) to insert
- $filename: (reference to array of) file(s) to update ToC in
- $options: hash reference containing updator options.
Update ToC of specified file. For updator options, see L.
=head1 Parser Options
When generating a ToC, additional options may be specified which influence the way the ToCs are generated using either C, C or C. The options must be specified as a hash reference. For example:
$tocGenerator->generateFromFile($toc, $filename, {doUseGroupsGlobal => 1});
Available options are:
=over 4
=item L
=item L
=item L
=item L
=back
=head2 doGenerateToc
syntax: [0|1]
default: 1
applicable to: TocInsertor, TocUpdator
True (1) if ToC must be generated. False (0) if ToC must be inserted only.
=head2 doUseGroupsGlobal
syntax: [0|1]
default: 0
applicable to: TocGenerator, TocInsertor, TocUpdator
True (1) if group levels must be used globally accross ToCs. False (0) if not. This option only makes sense when an array of ToCs is specified. For example, suppose you want to generate two ToCs, one ToC for '' tokens and one ToC for '' tokens, of the file 'index.htm':
Chapter
Paragraph
Using the default setting of 'doUseGroupsGlobal' => 0:
use HTML::Toc;
use HTML::TocGenerator;
my $toc1 = HTML::Toc->new();
my $toc2 = HTML::Toc->new();
my $tocGenerator = HTML::TocGenerator->new();
$toc1->setOptions({
'header' => '',
'footer' => '',
'tokenToToc' => [{'tokenBegin' => ''}]
});
$toc2->setOptions({
'header' => '',
'footer' => '',
'tokenToToc' => [{'tokenBegin' => ''}]
});
$tocGenerator->generateFromFile([$toc1, $toc2], 'index.htm');
print $toc1->format() . "\n\n" . $toc2->format();
the output will be:
Each ToC will use its own numbering scheme. Now if 'C' is specified:
$tocGenerator->generateFromFile(
[$toc1, $toc2], 'index.htm', {'doUseGroupsGlobal' => 1}
);
the output will be:
using a global numbering scheme for all ToCs.
=head2 output
syntax: reference to scalar
default: none
applicable to: TocInsertor, TocUpdator
Reference to scalar where the output must be stored in.
=head2 outputFile
syntax: scalar
default: none
applicable to: TocInsertor, TocUpdator
Filename to write output to. If no filename is specified, output will be written to standard output.
=head1 HTML::Toc Options
The C options can be grouped in the following categories:
=over 4
=item L
=item L
=item L
=item L
=back
The ToC options must be specified using the 'setOptions' method. For example:
my $toc = new HTML::Toc;
$toc->setOptions({
'doNumberToken' => 1,
'footer' => ''
'tokenToToc' => [{
'level' => 1,
'tokenBegin' => '',
'numberingStyle' => 'lower-alpha'
}]
});
=head2 Generate options
=over 4
=item Token groups
=over 4
=item L
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=item L
=item L
=back
=item Numbering tokens
=over 4
=item L
=item L
=item L
=back
=item Miscellaneous
=over 4
=item L
=item L
=item L
=item L
=back
=item Linking ToC to tokens
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=back
=head2 Insert options
=over 4
=item L
=back
=head2 Update options
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=back
=head2 Format options
=over 4
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=item L
=back
=head1 HTML::Toc Options Reference
=head2 attributeToExcludeToken
syntax: $scalar
default: '-'
Token which marks an attribute value in a L or L token as an attribute value a token should not have to be marked as a ToC token. See also: L.
=head2 attributeToTocToken
syntax: $scalar
default: '@'
Token which marks an attribute in a L token as an attribute which must be used as ToC text. See also: L.
=head2 doLinkToToken
syntax: [0|1]
default: 1
True (1) if ToC must be linked to tokens, False (0) if not. Note that 'HTML::TocInsertor' must be used to do the actual insertion of the anchor name within the source data.
=head2 doLinkToFile
syntax: [0|1]
default: 0
True (1) if ToC must be linked to file, False (0) if not. In effect only when L equals True (1) and L isn't specified.
=head2 doLinkToId
syntax: [0|1]
default: 0
True (1) if ToC must be linked to tokens by using token ids. False (0) if ToC must be linked to tokens by using anchor names.
=head2 doNestGroup
syntax: [0|1]
default: 0
True (1) if groups must be nested in the formatted ToC, False (0) if not. In effect only when multiple groups are specified within the L setting. For an example, see L.
=head2 doNumberToken
syntax: [0|1]
default: 0
True (1) if tokens which are used for the ToC generation must be numbered. This option may be specified both as a global ToC option or within a L group. When specified within a C option, the C applies to that group only. For an example, see L.
=head2 doSingleStepLevel
syntax: [0|1]
default: 1
True (1) if levels of a formatted ToC must advance one level at a time. For example, when generating a ToC of a file with a missing '':
Chapter
Paragraph
By default, an empty indentation level will be inserted in the ToC:
After specifying:
$toc->setOptions({'doSingleStepLevel' => 0});
the ToC will not have an indentation level inserted for level 2:
=head2 fileSpec
syntax:
default: undef
Specifies which files should match the current level. Valid only if L equals 1. For an example, see L.
=head2 footer
syntax: $scalar
default: "\n\n"
String to output at end of ToC.
=head2 groupId
syntax: $scalar
default: 'h'
Sets the group id attribute of a tokenGroup. With this attribute it's possible to divide the ToC into multiple groups. Each group has its own numbering scheme. For example, to generate a ToC of both normal headings and 'appendix' headings, specify the following ToC settings:
$toc->setOptions({
'tokenToToc' => [{
'tokenBegin' => ''
}, {
'groupId' => 'appendix',
'tokenBegin' => ''
}]
});
=head2 groupToToc
syntax:
default: '.*'
Determines which groups to use for generating the ToC. For example, to create a ToC for groups [a-b] only, specify:
'groupToToc => '[a-b]'
This option is evaluated during both ToC generation and ToC formatting. This enables you to generate a ToC of all groups, but - after generating - format only specified groups:
$toc->setOptions({'groupToToc' => '.*'});
$tocGenerator->generateToc($toc, ...);
# Get ToC of all groups
$fullToc = $toc->format();
# Get ToC of 'appendix' group only
$toc->setOptions({'groupToToc' => 'appendix'});
$appendixToc = $toc->format();
=head2 header
syntax: $scalar
default: "\n\n"
String to output at begin of ToC.
=head2 insertionPoint
syntax: []
default: 'after '
token: <[/]tag{ attribute=[-|@]}> |
|
|
Determines the point within the source, where the ToC should be inserted. When specifying a start tag as the insertion point token, attributes to be included may be specified as well. Note that the attribute value must be specified as a regular expression. For example, to specify the C<> tag as insertion point:
''
Examples of valid 'insertionPoint' tokens are:
''
'
'
''
''
'ToC will be placed here'
It is also possible to specify attributes to exclude, by prefixing the value with an L, default a minus sign (-). For example, to specify the C<> tag as insertion point, excluding all C<> tags:
''
See also L.
=head2 level
syntax: number
default: 1
Number which identifies at which level the tokengroup should be incorporated into the ToC. See also: L.
=head2 levelIndent
syntax: number
default: 3
Sets the number of spaces each level will be indented, when formatting the ToC.
=head2 levelToToc
syntax:
default: '.*'
Determines which group levels to use for generating the ToC. For example, to create a ToC for levels 1-2 only, specify:
'levelToToc => '[1-2]'
This option is evaluated during both ToC generation and ToC formatting. This enables you to generate a ToC of all levels, but - after generating - retrieve only specified levels:
$toc->setOptions({'levelToToc' => '.*'});
$tocGenerator->generateToc($toc, ...);
# Get ToC of all levels
$fullToc = $toc->getToc();
# Get ToC of level 1 only
$toc->setOptions({'levelToToc' => '1'});
$level1Toc = $toc->getToc();
=head2 numberingStyle
syntax: [decimal|lower-alpha|upper-alpha|lower-roman|upper-roman]}
default: decimal
Determines which numbering style to use for a token group when L is set to True (1). When specified as a main ToC option, the setting will be the default for all groups. When specified within a tokengroup, this setting will override any default for that particular tokengroup, e.g.:
$toc->setOptions({
'doNumberToken' => 1,
'tokenToToc' => [{
'level' => 1,
'tokenBegin' => '',
'numberingStyle' => 'lower-alpha'
}]
});
If C style is specified, be sure to have the Roman module installed, available from L.
=head2 templateAnchorName
syntax:
default: '$groupId."-".$node'
Anchor name to use when L is set to True (1). The anchor name is passed to both L and L. The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
If C is a function reference to a function returning the anchor, like in:
$toc->setOptions({'templateAnchorName' => \&assembleAnchorName});
the function will be called with the following arguments:
$anchorName = assembleAnchorName($file, $groupId, $level, $node);
=head2 templateAnchorHrefBegin
syntax:
default: '""' or
'""',
depending on 'doLinkToFile' being 0 or 1 respectively.
Anchor reference begin token to use when L is set to True (1). The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
$anchorName
If C is a function reference to a function returning the anchor, like in:
$toc->setOptions({'templateAnchorHrefBegin' => \&assembleAnchorHrefBegin});
the function will be called with the following arguments:
$anchorHrefBegin = &assembleAnchorHrefBegin(
$file, $groupId, $level, $node, $anchorName
);
See also: L, L.
=head2 templateAnchorHrefEnd
syntax:
default: '" "'
Anchor reference end token to use when L is set to True (1). The template may be specified as either an expression or a function reference. If L is a function reference to a function returning the anchor end, like in:
$toc->setOptions({'templateAnchorHrefEnd' => \&assembleAnchorHrefEnd});
the function will be called without arguments:
$anchorHrefEnd = &assembleAnchorHrefEnd;
See also: L.
=head2 templateAnchorNameBegin
syntax:
default: '""'
Anchor name begin token to use when L is set to True (1). The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$file
$groupId
$level
$node
$anchorName
If C is a function reference to a function returning the anchor name, like in:
$toc->setOptions({'templateAnchorNameBegin' => \&assembleAnchorNameBegin});
the function will be called with the following arguments:
$anchorNameBegin = assembleAnchorNameBegin(
$file, $groupId, $level, $node, $anchorName
);
See also: L, L.
=head2 templateAnchorNameEnd
syntax:
default: '" "'
Anchor name end token to use when L is set to True (1). The template may be specified as either an expression or a function reference. If L is a function reference to a function returning the anchor end, like in:
$toc->setOptions({'templateAnchorNameEnd' => \&assembleAnchorNameEnd});
the function will be called without arguments:
$anchorNameEnd = &assembleAnchorNameEnd;
See also: L.
=head2 templateLevel
syntax:
default: '"- $text\n"'
Expression to use when formatting a ToC node. The template may be specified as either an expression or a function reference. The expression may contain the following variables:
$level
$groupId
$node
$sequenceNr
$text
If C
is a function reference to a function returning the ToC node, like in:
$toc->setOptions({'templateLevel' => \&AssembleTocNode});
the function will be called with the following arguments:
$tocNode = &AssembleTocNode(
$level, $groupId, $node, $sequenceNr, $text
);
=head2 templateLevelBegin
syntax:
default: '"\n"'
Expression to use when formatting begin of ToC level. See L for list of available variables to use within the expression. For example, to give each ToC level a class name to use with Cascading Style Sheets (CSS), use the expression:
'"\n"'
which will result in each ToC group being given a class name:
- Header
For an example, see L.
=head2 templateLevelEnd
syntax:
default: '"\n"'
Expression to use when formatting end of ToC level. See L for a list of available variables to use within the expression. The default expression is:
'"
\n"'
For an example, see L.
=head2 templateTokenNumber
syntax:
default: '"$node "'
Token number to use when L equals True (1). The template may be specified as either an expression or a function reference. The expression has access to the following variables:
$file
$groupId
$groupLevel
$level
$node
$toc
If C is a function reference to a function returning the token number, like in:
$toc->setOptions({'templateTokenNumber' => \&assembleTokenNumber});
the function will be called with the following arguments:
$number = &assembleTokenNumber(
$node, $groupId, $file, $groupLevel, $level, $toc
);
=head2 tokenBegin
syntax:
default: ''
token: <[/]tag{ attribute=[-|@]}> |
|
|
This scalar defines the token that will trigger text to be put into the ToC. Any start tag, end tag, comment, declaration or text string can be specified. Examples of valid 'tokenBegin' tokens are:
''
''
''
''
'ToC entry'
When specifying a start tag, attributes to be included may be specified as well. Note that the attribute value is used as a regular expression. For example, to specify the C<> tag as tokenBegin:
''
It is also possible to specify attributes to exclude, by prefixing the value with an L, default a minus sign (-). For example, to specify the C<> tag as tokenBegin, excluding all C<> tags:
''
Also, you can specify here an attribute value which has to be used as ToC text, by prefixing the value with an L, default an at sign (@). For example, to use the class value as ToC text:
''
See L for an elaborated example using the C to generate a ToC of image C attribute values.
See also: L, L.
=head2 tokenEnd
syntax: $scalar
default: empty string ('') or end tag counterpart of 'tokenBegin' if
'tokenBegin' is a start tag
The 'tokenEnd' definition applies to the same rules as L.
See also: L, L.
=head2 tokenToToc
syntax: [{array of hashrefs}]
default: [{
'level' => 1,
'tokenBegin' => ''
}, {
'level' => 2,
'tokenBegin' => ''
}, {
'level' => 3,
'tokenBegin' => ''
}, {
'level' => 4,
'tokenBegin' => ''
}, {
'level' => 5,
'tokenBegin' => ''
}, {
'level' => 6,
'tokenBegin' => ''
}]
This hash define the tokens that must act as ToC entries. Each tokengroup may contain a L, L, L, L and L identifier.
=head2 tokenUpdateBeginAnchorName
syntax:
default: '';
This token marks the begin of an anchor name, inserted by C. This option is used by C.
=head2 tokenUpdateEndAnchorName
syntax:
default: '';
This option is used by C, to mark the end of an inserted anchor name.
=head2 tokenUpdateBeginNumber
syntax:
default: '';
This option is used by C, to mark the begin of an inserted number.
=head2 tokenUpdateEndNumber
syntax:
default: '';
This option is used by C, to mark the end of an inserted number.
=head2 tokenUpdateBeginToc
syntax:
default: '';
This option is used by C, to mark the begin of an inserted ToC.
=head2 tokenUpdateEndToc
syntax:
default: '';
This option is used by C, to mark the end of an inserted ToC.
=head1 Known issues
=head2 Cygwin
In order for the test files to run on Cygwin without errors, the 'UNIX' default text file type has to be selected during the Cygwin setup.
When extracting the tar.gz file with WinZip the 'TAR file smart CR/LF conversion' has to be turned off via {Options|Configuration...|Miscellaneous} in order for the files 'toc.pod' and './manualTest/manualTest1.htm' to be left in UNIX format.
=head2 Nested anchors
HTML::Toc can only link to existing anchors if these anchors are placed outside of the ToC tokens. Otherwise a warning will be given. For example, generating a L ToC of Ch1E> tokens of the following text:
- \n"',
'templateLevelEnd' => '"
Chapter
Paragraph
The formatted ToC now will contain C- instead of C
- $node $text\n"',
});
$tocGenerator->generateFromFile($toc, 'index.htm');
print $toc->format();
For instance with the original file containing:
Chapter
Paragraph
The formatted ToC now will have the node numbers hard-coded: See also: L. =head2 Using CSS for ToC formatting Suppose you want to display a ToC with upper-alpha numbered appendix headings. To accomplish this, you can specify a CSS style within the source document: Appendix
Appendix Paragraph
Appendix
Appendix Paragraph
Here's the code: my $toc = new HTML::Toc; my $tocInsertor = new HTML::TocInsertor; $toc->setOptions({ 'templateLevelBegin' => '"- \n"',
'templateLevelEnd' => '"
', 'numberingStyle' => 'upper-alpha' }, { 'groupId' => 'appendix', 'tokenBegin' => '
', 'level' => 2, }] }); $tocInsertor->insertIntoFile($toc, $filename); Which whill result in the following output:
A Appendix
A.1 Appendix Paragraph
B Appendix
B.1 Appendix Paragraph
=head2 Creating site map Suppose you want to generate a table of contents of the EtitleE tags of the files in the following directory structure: path file . index.htm, Main |- SubDir1 index.htm,Sub1 | |- SubSubDir1 index.htm,SubSub1 | |- SubDir2 index.htm,Sub2 | |- SubSubDir1 index.htm,SubSub1 | |- SubSubDir2 index.htm,SubSub2 | |- SubDir3 index.htm,Sub3 By specifying 'fileSpec' which determine how many slashes (/) each file may contain for a specific level: use HTML::Toc; use HTML::TocGenerator; use File::Find; my $toc = HTML::Toc->new; my $tocGenerator = HTML::TocGenerator->new; my @fileList; sub wanted { # Add file to 'fileList' if extension matches '.htm' push (@fileList, $File::Find::name) if (m/\.htm$/); } $toc->setOptions({ 'doLinkToFile' => 1, 'templateAnchorName' => '""', 'templateAnchorHref' => '""', 'doLinkTocToToken' => 1, 'tokenToToc' => [{ 'groupId' => 'dir', 'level' => 1, 'tokenBegin' => '', 'tokenEnd' => ' ', 'fileSpec' => '\./[^/]+$' }, { 'groupId' => 'dir', 'level' => 2, 'tokenBegin' => '', 'tokenEnd' => ' ', 'fileSpec' => '\./[^/]+?/[^/]+$' }, { 'groupId' => 'dir', 'level' => 3, 'tokenBegin' => '', 'tokenEnd' => ' ', 'fileSpec' => '\./[^/]+?/[^/]+?/[^/]+$' }] }); # Traverse directory structure find({wanted => \&wanted, no_chdir => 1}, '.'); # Generate ToC of case-insensitively sorted file list $tocGenerator->extendFromFile( $toc, [sort {uc($a) cmp uc($b)} @fileList] ); print $toc->format(); the following ToC will be generated: =head1 Methods =head2 HTML::Toc::clear() syntax: $toc->clear() returns: -- Clear the ToC. =head2 HTML::Toc::format() syntax: $scalar = $toc->format() returns: Formatted ToC. Format tokenized ToC. =head2 HTML::TocGenerator::extend() syntax: $tocGenerator->extend($toc, $string [, $options]) args: - $toc: (reference to array of) HTML::Toc object(s) to extend - $string: string to retrieve ToC from - $options: hash reference containing generator options. Extend ToC from specified string. For generator options, see L. =head2 HTML::TocGenerator::generate() syntax: $tocGenerator->generate($toc, $string [, $options]) args: - $toc: (reference to array of) HTML::Toc object(s) to generate - $string: string to retrieve ToC from - $options: hash reference containing generator options. Generate ToC from specified string. Before generating, the ToC will be cleared. For extending an existing ToC, use the L , C or C . The options must be specified as a hash reference. For example: $tocGenerator->generateFromFile($toc, $filename, {doUseGroupsGlobal => 1}); Available options are: =over 4 =item L ' tokens and one ToC for '
' tokens, of the file 'index.htm':
Chapter
Paragraph
Using the default setting of 'doUseGroupsGlobal' => 0: use HTML::Toc; use HTML::TocGenerator; my $toc1 = HTML::Toc->new(); my $toc2 = HTML::Toc->new(); my $tocGenerator = HTML::TocGenerator->new(); $toc1->setOptions({ 'header' => '', 'footer' => '', 'tokenToToc' => [{'tokenBegin' => ''}] }); $toc2->setOptions({ 'header' => '', 'footer' => '', 'tokenToToc' => [{'tokenBegin' => '
'}] }); $tocGenerator->generateFromFile([$toc1, $toc2], 'index.htm'); print $toc1->format() . "\n\n" . $toc2->format(); the output will be: Each ToC will use its own numbering scheme. Now if 'C
' is specified: $tocGenerator->generateFromFile( [$toc1, $toc2], 'index.htm', {'doUseGroupsGlobal' => 1} ); the output will be: using a global numbering scheme for all ToCs. =head2 output syntax: reference to scalar default: none applicable to: TocInsertor, TocUpdator Reference to scalar where the output must be stored in. =head2 outputFile syntax: scalar default: none applicable to: TocInsertor, TocUpdator Filename to write output to. If no filename is specified, output will be written to standard output. =head1 HTML::Toc Options The C =item L =item L =item L =back The ToC options must be specified using the 'setOptions' method. For example: my $toc = new HTML::Toc; $toc->setOptions({ 'doNumberToken' => 1, 'footer' => '' 'tokenToToc' => [{ 'level' => 1, 'tokenBegin' => ' ', 'numberingStyle' => 'lower-alpha' }] }); =head2 Generate options =over 4 =item Token groups =over 4 =item L
. =head2 attributeToTocToken syntax: $scalar default: '@' Token which marks an attribute in a L . =head2 doLinkToToken syntax: [0|1] default: 1 True (1) if ToC must be linked to tokens, False (0) if not. Note that 'HTML::TocInsertor' must be used to do the actual insertion of the anchor name within the source data. =head2 doLinkToFile syntax: [0|1] default: 0 True (1) if ToC must be linked to file, False (0) if not. In effect only when L . =head2 doNumberToken syntax: [0|1] default: 0 True (1) if tokens which are used for the ToC generation must be numbered. This option may be specified both as a global ToC option or within a L option, the C applies to that group only. For an example, see L . =head2 doSingleStepLevel syntax: [0|1] default: 1 True (1) if levels of a formatted ToC must advance one level at a time. For example, when generating a ToC of a file with a missing ' ':
Chapter
Paragraph
By default, an empty indentation level will be inserted in the ToC: After specifying: $toc->setOptions({'doSingleStepLevel' => 0}); the ToC will not have an indentation level inserted for level 2: =head2 fileSpec syntax:default: undef Specifies which files should match the current level. Valid only if L . =head2 footer syntax: $scalar default: "\n\n" String to output at end of ToC. =head2 groupId syntax: $scalar default: 'h' Sets the group id attribute of a tokenGroup. With this attribute it's possible to divide the ToC into multiple groups. Each group has its own numbering scheme. For example, to generate a ToC of both normal headings and 'appendix' headings, specify the following ToC settings: $toc->setOptions({ 'tokenToToc' => [{ 'tokenBegin' => ' ' }, { 'groupId' => 'appendix', 'tokenBegin' => '
' }] }); =head2 groupToToc syntax:
default: '.*' Determines which groups to use for generating the ToC. For example, to create a ToC for groups [a-b] only, specify: 'groupToToc => '[a-b]' This option is evaluated during both ToC generation and ToC formatting. This enables you to generate a ToC of all groups, but - after generating - format only specified groups: $toc->setOptions({'groupToToc' => '.*'}); $tocGenerator->generateToc($toc, ...); # Get ToC of all groups $fullToc = $toc->format(); # Get ToC of 'appendix' group only $toc->setOptions({'groupToToc' => 'appendix'}); $appendixToc = $toc->format(); =head2 header syntax: $scalar default: "\n\n" String to output at begin of ToC. =head2 insertionPoint syntax: [ default: 'after ' token: <[/]tag{ attribute=[-|@] }> | | | Determines the point within the source, where the ToC should be inserted. When specifying a start tag as the insertion point token, attributes to be included may be specified as well. Note that the attribute value must be specified as a regular expression. For example, to specify the C< > tag as insertion point: '
' Examples of valid 'insertionPoint' tokens are: '
' '
' '' '' 'ToC will be placed here' It is also possible to specify attributes to exclude, by prefixing the value with an L> tag as insertion point, excluding all C<
> tags: '
' See also L
default: '.*' Determines which group levels to use for generating the ToC. For example, to create a ToC for levels 1-2 only, specify: 'levelToToc => '[1-2]' This option is evaluated during both ToC generation and ToC formatting. This enables you to generate a ToC of all levels, but - after generating - retrieve only specified levels: $toc->setOptions({'levelToToc' => '.*'}); $tocGenerator->generateToc($toc, ...); # Get ToC of all levels $fullToc = $toc->getToc(); # Get ToC of level 1 only $toc->setOptions({'levelToToc' => '1'}); $level1Toc = $toc->getToc(); =head2 numberingStyle syntax: [decimal|lower-alpha|upper-alpha|lower-roman|upper-roman]} default: decimal Determines which numbering style to use for a token group when L ', 'numberingStyle' => 'lower-alpha' }] }); If C
style is specified, be sure to have the Roman module installed, available from L is a function reference to a function returning the anchor, like in: $toc->setOptions({'templateAnchorName' => \&assembleAnchorName}); the function will be called with the following arguments: $anchorName = assembleAnchorName($file, $groupId, $level, $node); =head2 templateAnchorHrefBegin syntax: is a function reference to a function returning the anchor, like in: $toc->setOptions({'templateAnchorHrefBegin' => \&assembleAnchorHrefBegin}); the function will be called with the following arguments: $anchorHrefBegin = &assembleAnchorHrefBegin( $file, $groupId, $level, $node, $anchorName ); See also: L is a function reference to a function returning the anchor name, like in: $toc->setOptions({'templateAnchorNameBegin' => \&assembleAnchorNameBegin}); the function will be called with the following arguments: $anchorNameBegin = assembleAnchorNameBegin( $file, $groupId, $level, $node, $anchorName ); See also: L - $text\n"' Expression to use when formatting a ToC node. The template may be specified as either an expression or a function reference. The expression may contain the following variables: $level $groupId $node $sequenceNr $text If C
is a function reference to a function returning the ToC node, like in: $toc->setOptions({'templateLevel' => \&AssembleTocNode}); the function will be called with the following arguments: $tocNode = &AssembleTocNode( $level, $groupId, $node, $sequenceNr, $text ); =head2 templateLevelBegin syntax: default: '" - \n"'
Expression to use when formatting begin of ToC level. See L
- Header
- \n"'
which will result in each ToC group being given a class name:
. =head2 templateLevelEnd syntax: default: '" - \n"'
Expression to use when formatting end of ToC level. See L
. =head2 templateTokenNumber syntax: is a function reference to a function returning the token number, like in: $toc->setOptions({'templateTokenNumber' => \&assembleTokenNumber}); the function will be called with the following arguments: $number = &assembleTokenNumber( $node, $groupId, $file, $groupLevel, $level, $toc ); =head2 tokenBegin syntax: default: ' ' token: <[/]tag{ attribute=[-|@]
}> | | | This scalar defines the token that will trigger text to be put into the ToC. Any start tag, end tag, comment, declaration or text string can be specified. Examples of valid 'tokenBegin' tokens are: ' ' '' '' '' 'ToC entry' When specifying a start tag, attributes to be included may be specified as well. Note that the attribute value is used as a regular expression. For example, to specify the C<
> tag as tokenBegin: '
' It is also possible to specify attributes to exclude, by prefixing the value with an L
> tag as tokenBegin, excluding all C<
> tags: '
' Also, you can specify here an attribute value which has to be used as ToC text, by prefixing the value with an L
' See L
for an elaborated example using the C to generate a ToC of image C attribute values. See also: L ' }, { 'level' => 2, 'tokenBegin' => '
' }, { 'level' => 3, 'tokenBegin' => '
' }, { 'level' => 4, 'tokenBegin' => '
' }, { 'level' => 5, 'tokenBegin' => '
' }, { 'level' => 6, 'tokenBegin' => '
' }] This hash define the tokens that must act as ToC entries. Each tokengroup may contain a L
default: ''; This token marks the begin of an anchor name, inserted by C default: ''; This option is used by C default: ''; This option is used by C default: ''; This option is used by C default: ''; This option is used by C default: ''; This option is used by C > tokens of the following text: - $text\n"' Expression to use when formatting a ToC node. The template may be specified as either an expression or a function reference. The expression may contain the following variables: $level $groupId $node $sequenceNr $text If C
- tags:
See also: L